http: client code improvement

Client app can sends request target, custom header and body to
HTTP layer. In response it receives all bytes as received from
transport, aditionally we provide offset and length of headers
and body.
In addtion client app is now able to receive response with all
status codes and Host header field is set in request at protocol
layer.

Type: improvement

Change-Id: I8c8e2c8f99cdf500126b7c2c722aebc254aa0d9f
Signed-off-by: Matus Fabian <matfabia@cisco.com>

1 files changed, 199 insertions, 3 deletions

diff --git a/src/plugins/http/http_plugin.rst b/src/plugins/http/http_plugin.rst
index 2f7a58ef9bf..273812735f7 100644
--- a/src/plugins/http/http_plugin.rst
+++ b/src/plugins/http/http_plugin.rst
@@ -191,10 +191,10 @@ Following example shows how to create headers section:
   http_add_header (resp_headers,
 		   http_header_name_token (HTTP_HEADER_CACHE_CONTROL),
 		   http_token_lit ("max-age=600"));
-  http_add_header (&hs->resp_headers,
+  http_add_header (resp_headers,
 		   http_header_name_token (HTTP_HEADER_LOCATION),
 		   (const char *) redirect, vec_len (redirect));
-  headers_buf = http_serialize_headers (hs->resp_headers);
+  headers_buf = http_serialize_headers (resp_headers);
 
 The example below show how to create and send response HTTP message metadata:
 
@@ -236,7 +236,7 @@ Finally application sends response body:
       vec_free (tx_buf);
     }
   if (svm_fifo_set_event (ts->tx_fifo))
-    session_send_io_evt_to_thread (ts->tx_fifo, SESSION_IO_EVT_TX);
+    session_program_tx_io_evt (ts->handle, SESSION_IO_EVT_TX);
 
 Example above shows how to send body data by copy, alternatively you could pass it as pointer:
 
@@ -249,3 +249,199 @@ Example above shows how to send body data by copy, alternatively you could pass
   ASSERT (rv == sizeof (data));
 
 In this case you need to free data when you receive next request or when session is closed.
+
+
+Client application
+^^^^^^^^^^^^^^^^^^
+
+Client application opens connection with vnet URI where transport protocol is set to ``http``.
+
+Sending data
+""""""""""""""
+
+HTTP request is sent when connection is successfully established in ``session_connected_callback``.
+
+When client application sends message to HTTP layer it starts with message metadata, followed by request target, optional headers and body (if any) buffers.
+
+Application should set following items:
+
+* HTTP method
+* target form, offset and length
+* header section offset and length
+* body offset and length
+
+Application could pass headers to HTTP layer. Header list is created dynamically as vector of ``http_header_t``,
+where we store only pointers to buffers (zero copy).
+Well known header names are predefined.
+The list is serialized just before you send buffer to HTTP layer.
+
+.. note::
+    Following headers are added at protocol layer and **MUST NOT** be set by application: Host, User-Agent
+
+
+The example below shows how to create headers section:
+
+.. code-block:: C
+
+  #include <http/http.h>
+  #include <http/http_header_names.h>
+  #include <http/http_content_types.h>
+  http_header_t *req_headers = 0;
+  u8 *headers_buf = 0;
+  http_add_header (req_headers,
+		   http_header_name_token (HTTP_HEADER_ACCEPT),
+		   http_content_type_token (HTTP_CONTENT_TEXT_HTML));
+  headers_buf = http_serialize_headers (req_headers);
+  vec_free (hs->req_headers);
+
+Following example shows how to set message metadata:
+
+.. code-block:: C
+
+  http_msg_t msg;
+  msg.type = HTTP_MSG_REQUEST;
+  msg.method_type = HTTP_REQ_GET;
+  msg.data.headers_offset = 0;
+  /* request target */
+  msg.data.target_form = HTTP_TARGET_ORIGIN_FORM;
+  msg.data.target_path_offset = 0;
+  msg.data.target_path_len = vec_len (target);
+  /* custom headers */
+  msg.data.headers_offset = msg.data.target_path_len;
+  msg.data.headers_len = vec_len (headers_buf);
+  /* no request body because we are doing GET request */
+  msg.data.body_len = 0;
+  /* data type and total length */
+  msg.data.type = HTTP_MSG_DATA_INLINE;
+  msg.data.len = msg.data.target_path_len + msg.data.headers_len + msg.data.body_len;
+
+Finally application sends everything to HTTP layer:
+
+.. code-block:: C
+
+  svm_fifo_seg_t segs[3] = { { (u8 *) &msg, sizeof (msg) }, /* message metadata */
+			     { target, vec_len (target) }, /* request target */
+			     { headers_buf, vec_len (headers_buf) } }; /* serialized headers */
+  rv = svm_fifo_enqueue_segments (as->tx_fifo, segs, 3, 0 /* allow partial */);
+  vec_free (headers_buf);
+  if (rv < 0 || rv != sizeof (msg) + msg.data.len)
+    {
+      clib_warning ("failed app enqueue");
+      return -1;
+    }
+  if (svm_fifo_set_event (as->tx_fifo))
+    session_program_tx_io_evt (as->handle, SESSION_IO_EVT_TX);
+
+Receiving data
+""""""""""""""
+
+HTTP plugin sends message header with metadata for parsing, in form of offset and length, followed by all data bytes as received from transport.
+
+Application will get pre-parsed following items:
+
+* status code
+* header section offset and length
+* body offset and length
+
+The example below reads HTTP message header in ``builtin_app_rx_callback``, which is first step application should do:
+
+.. code-block:: C
+
+  #include <http/http.h>
+  http_msg_t msg;
+  rv = svm_fifo_dequeue (ts->rx_fifo, sizeof (msg), (u8 *) &msg);
+  ASSERT (rv == sizeof (msg));
+
+As next step application might validate message type and status code:
+
+.. code-block:: C
+
+  if (msg.type != HTTP_MSG_REPLY)
+    {
+      /* your error handling */
+    }
+  if (msg.code != HTTP_STATUS_OK)
+    {
+      /* your error handling */
+      /* of course you can continue with steps bellow */
+      /* you might be interested in some headers or body content (if any) */
+    }
+
+Headers are parsed using a generic algorithm, independent of the individual header names.
+When header is repeated, its combined value consists of all values separated by comma, concatenated in order as received.
+Following example shows how to parse headers:
+
+.. code-block:: C
+
+  #include <http/http_header_names.h>
+  if (msg.data.headers_len)
+    {
+      u8 *headers = 0;
+      http_header_table_t *ht;
+      vec_validate (headers, msg.data.headers_len - 1);
+      rv = svm_fifo_peek (ts->rx_fifo, msg.data.headers_offset,
+			  msg.data.headers_len, headers);
+      ASSERT (rv == msg.data.headers_len);
+      if (http_parse_headers (headers, &ht))
+        {
+          /* your error handling */
+        }
+      /* get Content-Type header */
+      const char *content_type = http_get_header (ht, http_header_name_str (HTTP_HEADER_CONTENT_TYPE));
+      if (content_type)
+        {
+          /* do something interesting */
+        }
+      http_free_header_table (ht);
+      vec_free (headers);
+    }
+
+Finally application reads body, which might be received in multiple pieces (depends on size), so we might need some state machine in ``builtin_app_rx_callback``.
+We will add following members to our session context structure:
+
+.. code-block:: C
+
+  typedef struct
+  {
+    /* ... */
+    u32 to_recv;
+    u8 *resp_body;
+  } session_ctx_t;
+
+First we prepare vector for response body, do it only once when you are reading metadata:
+
+.. code-block:: C
+
+  /* drop everything up to body */
+  svm_fifo_dequeue_drop (ts->rx_fifo, msg.data.body_offset);
+  ctx->to_recv = msg.data.body_len;
+  /* prepare vector for response body */
+  vec_validate (ctx->resp_body, msg.data.body_len - 1);
+  vec_reset_length (ctx->resp_body);
+
+Now we can start reading body content, following block of code could be executed multiple times:
+
+.. code-block:: C
+
+  /* dequeue */
+  u32 max_deq = svm_fifo_max_dequeue (ts->rx_fifo);
+  u32 n_deq = clib_min (to_recv, max_deq);
+  /* current offset */
+  u32 curr = vec_len (ctx->resp_body);
+  rv = svm_fifo_dequeue (ts->rx_fifo, n_deq, ctx->resp_body + curr);
+  if (rv < 0 || rv != n_deq)
+    {
+      /* your error handling */
+    }
+  /* update length of the vector */
+  vec_set_len (ctx->resp_body, curr + n_deq);
+  /* update number of remaining bytes to receive */
+  ASSERT (to_recv >= rv);
+  ctx->to_recv -= rv;
+  /* check if all data received */
+  if (ctx->to_recv == 0)
+    {
+      /* we are done */
+      /* close the session if you don't want to send another request */
+      /* and update state machine... */
+    }