iodine 0.4.19 → 0.5.0

data/ext/iodine/http.h

@@ -1,45 +1,24 @@
+#ifndef H_HTTP_H
 /*
-copyright: Boaz segev, 2016-2017
-license: MIT
+Copyright: Boaz Segev, 2016-2018
+License: MIT
 
 Feel free to copy, use and enjoy according to the license provided.
 */
-#ifndef HTTP_H
-#define HTTP_H
+#define H_HTTP_H
 
 #include "facil.h"
 
-/** an HTTP/1.1 vs. HTTP/2 identifier. */
-enum HTTP_VERSION { HTTP_V1 = 0, HTTP_V2 = 1 };
+#include <time.h>
 
-/** HTTP header information */
-typedef struct {
-  const char *name;
-  union {
-    const char *data;
-    const char *value;
-  };
-  uint32_t name_len;
-  union {
-    uint32_t data_len;
-    uint32_t value_len;
-  };
-} http_header_s;
-
-/** Settings typedef */
-typedef struct http_settings_s http_settings_s;
+/* support C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 /* *****************************************************************************
-Core include files
-*/
-// clang-format off
-#include <time.h>
-#include "http_request.h"
-#include "http_response.h"
-// clang-format on
-/* *****************************************************************************
-Hard Coded Settings
-*/
+Compile Time Settings
+***************************************************************************** */
 
 /** When a new connection is accepted, it will be immediately declined with a
  * 503 service unavailable (server busy) response unless the following number of
@@ -52,94 +31,857 @@ Hard Coded Settings
 #define HTTP_DEFAULT_BODY_LIMIT (1024 * 1024 * 50)
 #endif
 
-/* support C++ */
-#ifdef __cplusplus
-extern "C" {
+#ifndef HTTP_MAX_HEADER_COUNT
+#define HTTP_MAX_HEADER_COUNT 128
+#endif
+
+#ifndef HTTP_MAX_HEADER_LENGTH
+/** the default maximum length for a single header line */
+#define HTTP_MAX_HEADER_LENGTH 8192
 #endif
 
+/** the `http_listen settings, see detils in the struct definition. */
+typedef struct http_settings_s http_settings_s;
+
 /* *****************************************************************************
-HTTP Core API & data structure
-*/
+The Request / Response type and functions
+***************************************************************************** */
 
-/** Manages protocol settings for the HTTP protocol */
-struct http_settings_s {
+/**
+ * A generic HTTP handle used for HTTP request/response data.
+ *
+ * The `http_s` data can only be accessed safely from within the `on_request`
+ * HTTP callback OR an `http_defer` callback.
+ */
+typedef struct {
+  /** the HTTP request's "head" starts with a private data used by facil.io */
+  struct {
+    /** the function touting table - used by facil.io, don't use directly! */
+    void *vtbl;
+    /** the connection's owner / uuid - used by facil.io, don't use directly! */
+    uintptr_t flag;
+    /** The response headers, if they weren't sent. Don't access directly. */
+    FIOBJ out_headers;
+  } private_data;
+  /** a time merker indicating when the request was received. */
+  struct timespec received_at;
+  /** a String containing the method data (supports non-standard methods. */
+  FIOBJ method;
+  /** The status string, for response objects (client mode response). */
+  FIOBJ status_str;
+  /** The HTTP version string, if any. */
+  FIOBJ version;
+  /** The status used for the response (or if the object is a response).
+   *
+   * When sending a request, the status should be set to 0.
+   */
+  uintptr_t status;
+  /** The request path, if any. */
+  FIOBJ path;
+  /** The request query, if any. */
+  FIOBJ query;
+  /** a hash of general header data. When a header is set multiple times (such
+   * as cookie headers), an Array will be used instead of a String. */
+  FIOBJ headers;
+  /**
+   * a placeholder for a hash of cookie data.
+   * the hash will be initialized when parsing the request.
+   */
+  FIOBJ cookies;
+  /**
+   * a placeholder for a hash of request data.
+   * the hash will be initialized when parsing the request.
+   */
+  FIOBJ params;
   /**
-  The maximum size of an HTTP request's body (when posting data).
+   * a reader for body data (might be a temporary file or a string or NULL).
+   * see fiobj_data.h for details.
+   */
+  FIOBJ body;
+  /** an opaque user data pointer, to be used BEFORE calling `http_defer`. */
+  void *udata;
+} http_s;
 
-  Defaults to ~ 50Mb.
-  */
-  size_t max_body_size;
-  /** REQUIRED: the callback to be performed when requests come in. */
-  void (*on_request)(http_request_s *request);
+/**
+* This is a helper for setting cookie data.
+
+This struct is used together with the `http_response_set_cookie`. i.e.:
+
+      http_response_set_cookie(response,
+        .name = "my_cookie",
+        .value = "data" );
+
+*/
+typedef struct {
+  /** The cookie's name (Symbol). */
+  char *name;
+  /** The cookie's value (leave blank to delete cookie). */
+  char *value;
+  /** The cookie's domain (optional). */
+  char *domain;
+  /** The cookie's path (optional). */
+  char *path;
+  /** The cookie name's size in bytes or a terminating NULL will be assumed.*/
+  size_t name_len;
+  /** The cookie value's size in bytes or a terminating NULL will be assumed.*/
+  size_t value_len;
+  /** The cookie domain's size in bytes or a terminating NULL will be assumed.*/
+  size_t domain_len;
+  /** The cookie path's size in bytes or a terminating NULL will be assumed.*/
+  size_t path_len;
+  /** Max Age (how long should the cookie persist), in seconds (0 == session).*/
+  int max_age;
+  /** Limit cookie to secure connections.*/
+  unsigned secure : 1;
+  /** Limit cookie to HTTP (intended to prevent javascript access/hijacking).*/
+  unsigned http_only : 1;
+} http_cookie_args_s;
+
+/**
+ * Sets a response header, taking ownership of the value object, but NOT the
+ * name object (so name objects could be reused in future responses).
+ *
+ * Returns -1 on error and 0 on success.
+ */
+int http_set_header(http_s *h, FIOBJ name, FIOBJ value);
+
+/**
+ * Sets a response header, taking ownership of the value object, but NOT the
+ * name object (so name objects could be reused in future responses).
+ *
+ * Returns -1 on error and 0 on success.
+ */
+int http_set_header2(http_s *h, fio_cstr_s name, fio_cstr_s value);
+
+/**
+ * Sets a response cookie, taking ownership of the value object, but NOT the
+ * name object (so name objects could be reused in future responses).
+ *
+ * Returns -1 on error and 0 on success.
+ *
+ * Note: Long cookie names and long cookie values will be considered a security
+ * vaiolation and an error will be returned. It should be noted that most
+ * proxies and servers will refuse long cookie names or values and many impose
+ * total header lengths (including cookies) of ~8Kib.
+ */
+int http_set_cookie(http_s *h, http_cookie_args_s);
+#define http_set_cookie(http___handle, ...)                                    \
+  http_set_cookie((http___handle), (http_cookie_args_s){__VA_ARGS__})
+
+/**
+ * Sends the response headers and body.
+ *
+ * **Note**: The body is *copied* to the HTTP stream and it's memory should be
+ * freed by the calling function.
+ *
+ * Returns -1 on error and 0 on success.
+ *
+ * AFTER THIS FUNCTION IS CALLED, THE `http_s` OBJECT IS NO LONGER VALID.
+ */
+int http_send_body(http_s *h, void *data, uintptr_t length);
+
+/**
+ * Sends the response headers and the specified file (the response's body).
+ *
+ * The file is closed automatically.
+ *
+ * Returns -1 on error and 0 on success.
+ *
+ * AFTER THIS FUNCTION IS CALLED, THE `http_s` OBJECT IS NO LONGER VALID.
+ */
+int http_sendfile(http_s *h, int fd, uintptr_t length, uintptr_t offset);
+
+/**
+ * Sends the response headers and the specified file (the response's body).
+ *
+ * The `local` and `encoded` strings will be joined into a single string that
+ * represent the file name. Either or both of these strings can be empty.
+ *
+ * The `encoded` string will be URL decoded while the `local` string will used
+ * as is.
+ *
+ * Returns 0 on success. A success value WILL CONSUME the `http_s` handle (it
+ * will become invalid).
+ *
+ * Returns -1 on error (The `http_s` handle should still be used).
+ */
+int http_sendfile2(http_s *h, const char *prefix, size_t prefix_len,
+                   const char *encoded, size_t encoded_len);
+
+/**
+ * Sends an HTTP error response.
+ *
+ * Returns -1 on error and 0 on success.
+ *
+ * AFTER THIS FUNCTION IS CALLED, THE `http_s` OBJECT IS NO LONGER VALID.
+ *
+ * The `uuid` and `settings` arguments are only required if the `http_s` handle
+ * is NULL.
+ */
+int http_send_error(http_s *h, size_t error_code);
+
+/**
+ * Sends the response headers for a header only response.
+ *
+ * AFTER THIS FUNCTION IS CALLED, THE `http_s` OBJECT IS NO LONGER VALID.
+ */
+void http_finish(http_s *h);
+
+/**
+ * Pushes a data response when supported (HTTP/2 only).
+ *
+ * Returns -1 on error and 0 on success.
+ */
+int http_push_data(http_s *h, void *data, uintptr_t length, FIOBJ mime_type);
+
+/**
+ * Pushes a file response when supported (HTTP/2 only).
+ *
+ * If `mime_type` is NULL, an attempt at automatic detection using `filename`
+ * will be made.
+ *
+ * Returns -1 on error and 0 on success.
+ */
+int http_push_file(http_s *h, FIOBJ filename, FIOBJ mime_type);
+
+/* *****************************************************************************
+HTTP evented API (pause / resume HTTp handling)
+***************************************************************************** */
+
+/**
+ * Pauses the request / response handling and INVALIDATES the current `http_s`
+ * handle (no `http` functions can be called).
+ *
+ * The `http_resume` function MUST be called (at some point) using the opaque
+ * `http` pointer given to the callback `task`.
+ *
+ * The opaque `http` pointer is only valid for a single call to `http_resume`
+ * and can't be used by any other `http` function (it's a different data type).
+ *
+ * Note: the currecnt `http_s` handle will become invalid once this function is
+ *    called and it's data might be deallocated, invalid or used by a different
+ *    thread.
+ */
+void http_pause(http_s *h, void (*task)(void *http));
+
+/**
+ * Resumes a request / response handling within a task and INVALIDATES the
+ * current `http_s` handle.
+ *
+ * The `task` MUST call one of the `http_send_*`, `http_finish`, or
+ * `http_pause`functions.
+ *
+ * The (optional) `fallback` will receive the opaque `udata` that was stored in
+ * the HTTP handle and can be used for cleanup.
+ *
+ * Note: `http_resume` can only be called after calling `http_pause` and
+ * entering it's task.
+ *
+ * Note: the current `http_s` handle will become invalid once this function is
+ *    called and it's data might be deallocated, invalidated or used by a
+ *    different thread.
+ */
+void http_resume(void *http, void (*task)(http_s *h),
+                 void (*fallback)(void *udata));
+
+/** Returns the `udata` associated with the paused opaque handle */
+void *http_paused_udata_get(void *http);
+
+/**
+ * Sets the `udata` associated with the paused opaque handle, returning the
+ * old value.
+ */
+void *http_paused_udata_set(void *http, void *udata);
+
+/* *****************************************************************************
+HTTP Connections - Listening / Connecting / Hijacking
+***************************************************************************** */
+
+/** The HTTP settings. */
+typedef struct http_settings_s {
+  /** Callback for normal HTTP requests. */
+  void (*on_request)(http_s *request);
+  /**
+   * Callback for Upgrade and EventSource (SSE) requests.
+   *
+   * SSE/EventSource requests set the `requested_protocol` string to `"sse"`.
+   */
+  void (*on_upgrade)(http_s *request, char *requested_protocol, size_t len);
+  /** CLIENT REQUIRED: a callback for the HTTP response. */
+  void (*on_response)(http_s *response);
+  /** (optional) the callback to be performed when the HTTP service closes. */
+  void (*on_finish)(struct http_settings_s *settings);
+  /** Opaque user data. Facil.io will ignore this field, but you can use it. */
+  void *udata;
   /**
-  A public folder for file transfers - allows to circumvent any application
-  layer server and simply serve files.
-  */
+   * A public folder for file transfers - allows to circumvent any application
+   * layer logic and simply serve static files.
+   *
+   * Supports automatic `gz` pre-compressed alternatives.
+   */
   const char *public_folder;
   /**
-  The length of the public_folder string.
-  */
+   * The length of the public_folder string.
+   */
   size_t public_folder_length;
-  /** Opaque user data. */
-  void *udata;
-  /** Opaque user data for the optional `set_rw_hooks`. */
-  void *rw_udata;
-  /** (optional) the callback to be performed when the HTTP service closes. */
-  void (*on_finish)(intptr_t uuid, void *udata);
   /**
-   * Allows a an implementation for the transport layer (i.e. TLS) without
-   * effecting the HTTP protocol.
+   * The maximum number of bytes allowed for the request string (method, path,
+   * query), header names and fields.
+   *
+   * Defaults to 32Kib (which is about 4 times more than I would recommend).
+   *
+   * This reflects the total overall size. On HTTP/1.1, each header line (name +
+   * value pair) is also limitied to a hardcoded HTTP_MAX_HEADER_LENGTH bytes.
    */
-  sock_rw_hook_s *(*set_rw_hooks)(intptr_t fduuid, void *rw_udata);
+  size_t max_header_size;
   /**
-   * A cleanup callback for the `rw_udata`.
+   * The maximum size of an HTTP request's body (posting / downloading).
+   *
+   * Defaults to ~ 50Mb.
    */
-  void (*on_finish_rw)(intptr_t uuid, void *rw_udata);
+  size_t max_body_size;
   /**
-  Logging flag - set to TRUE to log static file requests.
-
-  Dynamic request logging is always the dynamic application's responsibility.
-  */
-  uint8_t log_static;
-  /** An HTTP/1.x connection timeout. Defaults to ~5 seconds.*/
+   * The maximum number of clients that are allowed to connect concurrently.
+   *
+   * This value's default setting is usually for the best.
+   *
+   * The default value is computed according to the server's capacity, leaving
+   * some breathing room for other network and disk operations.
+   *
+   * Note: clients, by the nature of socket programming, are counted according
+   *       to their internal file descriptor (`fd`) value. Open files and other
+   *       sockets count towards a server's limit.
+   */
+  intptr_t max_clients;
+  /** reserved for future use. */
+  intptr_t reserved1;
+  /** reserved for future use. */
+  intptr_t reserved2;
+  /** reserved for future use. */
+  intptr_t reserved3;
+  /** reserved for future use. */
+  intptr_t reserved4;
+  /**
+   * The maximum websocket message size/buffer (in bytes) for Websocket
+   * connections. Defaults to ~250KB.
+   */
+  size_t ws_max_msg_size;
+  /**
+   * An HTTP/1.x connection timeout.
+   *
+   * `http_listen` defaults to ~40s and `http_connect` defaults to ~30s.
+   *
+   * Note: the connection might be closed (by other side) before timeout occurs.
+   */
   uint8_t timeout;
   /**
-  The default HTTP version which a new connection will use. At the moment, only
-  version HTTP/1.1 is supported.
-  */
-  enum HTTP_VERSION version;
+   * Timeout for the websocket connections, a ping will be sent whenever the
+   * timeout is reached. Defaults to 40 seconds.
+   *
+   * Connections are only closed when a ping cannot be sent (the network layer
+   * fails). Pongs are ignored.
+   */
+  uint8_t ws_timeout;
+  /** Logging flag - set to TRUE to log HTTP requests. */
+  uint8_t log;
+  /** a read only flag set automatically to indicate the protocol's mode. */
+  uint8_t is_client;
+} http_settings_s;
+
+/**
+ * Listens to HTTP connections at the specified `port`.
+ *
+ * Leave as NULL to ignore IP binding.
+ *
+ * Returns -1 on error and 0 on success. the `on_finish` callback is always
+ * called.
+ */
+int http_listen(const char *port, const char *binding, struct http_settings_s);
+/** Listens to HTTP connections at the specified `port` and `binding`. */
+#define http_listen(port, binding, ...)                                        \
+  http_listen((port), (binding), (struct http_settings_s){__VA_ARGS__})
+
+/**
+ * Connects to an HTTP server as a client.
+ *
+ * Upon a successful connection, the `on_response` callback is called with an
+ * empty `http_s*` handler (status == 0). Use the same API to set it's content
+ * and send the request to the server. The next`on_response` will contain the
+ * response.
+ *
+ * `address` should contain a full URL style address for the server. i.e.:
+ *
+ *           "http:/www.example.com:8080/"
+ *
+ * If an `address` includes a path or query data, they will be automatically
+ * attached (both of them) to the HTTP handl'es `path` property. i.e.
+ *
+ *           "http:/www.example.com:8080/my_path?foo=bar"
+ *           // will result in:
+ *           fiobj_obj2cstr(h->path).data; //=> "/my_path?foo=bar"
+ *
+ * To open a Websocket connection, it's possible to use the `ws` protocol
+ * signature. However, it would be better to use the `websocket_connect`
+ * function instead.
+ *
+ * Returns -1 on error and 0 on success. the `on_finish` callback is always
+ * called.
+ */
+int http_connect(const char *address, struct http_settings_s);
+#define http_connect(address, ...)                                             \
+  http_connect((address), (struct http_settings_s){__VA_ARGS__})
+
+/**
+ * Returns the settings used to setup the connection.
+ *
+ * Returns -1 on error and 0 on success.
+ */
+struct http_settings_s *http_settings(http_s *h);
+
+/**
+ * Returns the direct address of the connected peer (likely an intermediary).
+ */
+sock_peer_addr_s http_peer_addr(http_s *h);
+
+/**
+ * Hijacks the socket away from the HTTP protocol and away from facil.io.
+ *
+ * It's possible to hijack the socket and than reconnect it to a new protocol
+ * object.
+ *
+ * If any HTTP functions are called after the hijacking, the protocol object
+ * might attempt to continue reading data from the buffer.
+ *
+ * Returns the underlining socket connection's uuid. If `leftover` isn't NULL,
+ * it will be populated with any remaining data in the HTTP buffer (the data
+ * will be automatically deallocated, so copy the data if it's required).
+ *
+ * WARNING: this isn't a good was to handle HTTP connections, especially as
+ * HTTP/2 enters the picture.
+ */
+intptr_t http_hijack(http_s *h, fio_cstr_s *leftover);
+
+/* *****************************************************************************
+Websocket Upgrade (Server and Client connection establishment)
+***************************************************************************** */
+
+/**
+ * The type for a Websocket handle, used to identify a Websocket connection.
+ *
+ * Similar to an `http_s` handle, it is only valid within the scope of the
+ * specific connection (the callbacks / tasks) and shouldn't be stored or
+ * accessed otherwise.
+ */
+typedef struct ws_s ws_s;
+
+/**
+ * This struct is used for the named agruments in the `http_upgrade2ws`
+ * function and macro.
+ */
+typedef struct {
+  /** REQUIRED: The `http_s` to be initiating the websocket connection.*/
+  http_s *http;
+  /**
+   * The (optional) on_message callback will be called whenever a websocket
+   * message is received for this connection.
+   *
+   * The data received points to the websocket's message buffer and it will be
+   * overwritten once the function exits (it cannot be saved for later, but it
+   * can be copied).
+   */
+  void (*on_message)(ws_s *ws, char *data, size_t size, uint8_t is_text);
   /**
-  internal flag for library use.
-  */
-  uint8_t private_metaflags;
+   * The (optional) on_open callback will be called once the websocket
+   * connection is established and before is is registered with `facil`, so no
+   * `on_message` events are raised before `on_open` returns.
+   */
+  void (*on_open)(ws_s *ws);
+  /**
+   * The (optional) on_ready callback will be after a the underlying socket's
+   * buffer changes it's state from full to empty.
+   *
+   * If the socket's buffer is never used, the callback is never called.
+   */
+  void (*on_ready)(ws_s *ws);
+  /**
+   * The (optional) on_shutdown callback will be called if a websocket
+   * connection is still open while the server is shutting down (called before
+   * `on_close`).
+   */
+  void (*on_shutdown)(ws_s *ws);
+  /**
+   * The (optional) on_close callback will be called once a websocket connection
+   * is terminated or failed to be established.
+   *
+   * The `uuid` is the connection's unique ID that can identify the Websocket. A
+   * value of `uuid == 0` indicates the Websocket connection wasn't established
+   * (an error occured).
+   *
+   * The `udata` is the user data as set during the upgrade or using the
+   * `websocket_udata_set` function.
+   */
+  void (*on_close)(intptr_t uuid, void *udata);
+  /** Opaque user data. */
+  void *udata;
+} websocket_settings_s;
+
+/**
+ * Upgrades an HTTP/1.1 connection to a Websocket connection.
+ *
+ * This function will end the HTTP stage of the connection and attempt to
+ * "upgrade" to a Websockets connection.
+ *
+ * Thie `http_s` handle will be invalid after this call and the `udata` will be
+ * set to the new Websocket `udata`.
+ *
+ * A client connection's `on_finish` callback will be called (since the HTTP
+ * stage has finished).
+ */
+int http_upgrade2ws(websocket_settings_s);
+
+/** This macro allows easy access to the `http_upgrade2ws` function. The macro
+ * allows the use of named arguments, using the `websocket_settings_s` struct
+ * members. i.e.:
+ *
+ *     on_message(ws_s * ws, char * data, size_t size, int is_text) {
+ *        ; // ... this is the websocket on_message callback
+ *        websocket_write(ws, data, size, is_text); // a simple echo example
+ *     }
+ *
+ *     on_upgrade(http_s* h) {
+ *        http_upgrade2ws( .http = h, .on_message = on_message);
+ *     }
+ */
+#define http_upgrade2ws(...)                                                   \
+  http_upgrade2ws((websocket_settings_s){__VA_ARGS__})
+
+/**
+ * Connects to a Websocket service according to the provided address.
+ *
+ * This is a somewhat naive connector object, it doesn't perform any
+ * authentication or other logical handling. However, it's quire easy to author
+ * a complext authentication logic using a combination of `http_connect` and
+ * `http_upgrade2ws`.
+ *
+ * Returns the uuid for the future websocket on success.
+ *
+ * Returns -1 on error;
+ */
+int websocket_connect(const char *address, websocket_settings_s settings);
+#define websocket_connect(address, ...)                                        \
+  websocket_connect((address), (websocket_settings_s){__VA_ARGS__})
+
+#include "websockets.h"
+
+/* *****************************************************************************
+EventSource Support (SSE)
+***************************************************************************** */
+
+/**
+ * The type for the EventSource (SSE) handle, used to identify an SSE
+ * connection.
+ */
+typedef struct http_sse_s http_sse_s;
+
+/**
+ * This struct is used for the named agruments in the `http_upgrade2sse`
+ * function and macro.
+ */
+struct http_sse_s {
+  /**
+   * The (optional) on_open callback will be called once the EventSource
+   * connection is established.
+   */
+  void (*on_open)(http_sse_s *sse);
+  /**
+   * The (optional) on_ready callback will be after a the underlying socket's
+   * buffer changes it's state to empty.
+   *
+   * If the socket's buffer is never used, the callback is never called.
+   */
+  void (*on_ready)(http_sse_s *sse);
+  /**
+   * The (optional) on_shutdown callback will be called if a connection is still
+   * open while the server is shutting down (called before `on_close`).
+   */
+  void (*on_shutdown)(http_sse_s *sse);
+  /**
+   * The (optional) on_close callback will be called once a connection is
+   * terminated or failed to be established.
+   *
+   * The `uuid` is the connection's unique ID that can identify the Websocket. A
+   * value of `uuid == 0` indicates the Websocket connection wasn't established
+   * (an error occured).
+   *
+   * The `udata` is the user data as set during the upgrade or using the
+   * `websocket_udata_set` function.
+   */
+  void (*on_close)(http_sse_s *sse);
+  /** Opaque user data. */
+  void *udata;
 };
 
-typedef protocol_s *(*http_on_open_func)(intptr_t, void *);
-typedef void (*http_on_finish_func)(void *);
 /**
-Return the callback used for creating the HTTP protocol in the `settings`.
-*/
-http_on_open_func http_get_on_open_func(http_settings_s *settings);
+ * Upgrades an HTTP connection to an EventSource (SSE) connection.
+ *
+ * Thie `http_s` handle will be invalid after this call.
+ *
+ * On HTTP/1.1 connections, this will preclude future requests using the same
+ * connection.
+ */
+int http_upgrade2sse(http_s *h, http_sse_s);
+
+/** This macro allows easy access to the `http_upgrade2sse` function. The macro
+ * allows the use of named arguments, using the `websocket_settings_s` struct
+ * members. i.e.:
+ *
+ *     on_open_sse(sse_s * sse) {
+ *        ; // ... this is the websocket on_message callback
+ *        FIOBJ ch = (FIOBJ)sse->udata;
+ *        http_sse_subscribe(ch, NULL, NULL); // a simple echo example
+ *     }
+ *
+ *     on_upgrade(http_s* h) {
+ *        http_upgrade2sse(h, .on_open = on_open_sse);
+ *     }
+ */
+#define http_upgrade2sse(h, ...)                                               \
+  http_upgrade2sse((h), (http_sse_s){__VA_ARGS__})
+
 /**
-Return the callback used for freeing the HTTP protocol in the `settings`.
-*/
-http_on_finish_func http_get_on_finish_func(http_settings_s *settings);
+ * Sets the ping interval for SSE connections.
+ */
+void http_sse_set_timout(http_sse_s *sse, uint8_t timeout);
+
+struct http_sse_subscribe_args {
+  /** The channel namr used for the subscription. */
+  FIOBJ channel;
+  /** The optional on message callback. If missing, Data is directly writen. */
+  void (*on_message)(http_sse_s *sse, FIOBJ channel, FIOBJ msg, void *udata);
+  /** An optional callback for when a subscription is fully canceled. */
+  void (*on_unsubscribe)(void *udata);
+  /** Opaque user */
+  void *udata;
+  /** Use pattern matching for channel subscription. */
+  unsigned use_pattern : 1;
+};
 
 /**
-Listens for incoming HTTP connections on the specified posrt and address,
-implementing the requested settings.
+ * Subscribes to a channel. See {struct http_sse_subscribe_args} for possible
+ * arguments.
+ *
+ * Returns a subscription ID on success and 0 on failure.
+ *
+ * All subscriptions are automatically revoked once the connection is closed.
+ *
+ * If the connections subscribes to the same channel more than once, messages
+ * will be merged. However, another subscription ID will be assigned, and two
+ * calls to {http_sse_unsubscribe} will be required in order to unregister from
+ * the channel.
+ */
+uintptr_t http_sse_subscribe(http_sse_s *sse,
+                             struct http_sse_subscribe_args args);
 
-Since facil.io doesn't support native TLS/SLL
-*/
-int http_listen(const char *port, const char *address,
-                http_settings_s settings);
+/** This macro allows easy access to the `http_sse_subscribe` function. */
+#define http_sse_subscribe(sse, ...)                                           \
+  http_sse_subscribe((sse), (struct http_sse_subscribe_args){__VA_ARGS__})
 
-#define http_listen(port, address, ...)                                        \
-  http_listen((port), (address), (http_settings_s){__VA_ARGS__})
+/**
+ * Cancels a subscription and invalidates the subscription object.
+ */
+void http_sse_unsubscribe(http_sse_s *sse, uintptr_t subscription);
+
+/**
+ * Named arguments for the {http_sse_write} function.
+ *
+ * These arguments list the possible fields for the SSE event.
+ *
+ * Event fields listed here:
+ * https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events
+ */
+struct http_sse_write_args {
+  fio_cstr_s id;    /* (optionl) sets the `id` event property. */
+  fio_cstr_s event; /* (optionl) sets the `event` event property. */
+  fio_cstr_s data;  /* (optionl) sets the `data` event property. */
+  intptr_t retry;   /* (optionl) sets the `retry` event property. */
+};
+
+/**
+ * Writes data to an EventSource (SSE) connection.
+ *
+ * See the {struct http_sse_write_args} for possible named arguments.
+ */
+int http_sse_write(http_sse_s *sse, struct http_sse_write_args);
+#define http_sse_write(sse, ...)                                               \
+  http_sse_write((sse), (struct http_sse_write_args){__VA_ARGS__})
+
+/**
+ * Get the connection's UUID (for facil_defer and similar use cases).
+ */
+intptr_t http_sse2uuid(http_sse_s *sse);
+
+/**
+ * Closes an EventSource (SSE) connection.
+ */
+int http_sse_close(http_sse_s *sse);
+
+/**
+ * Duplicates an SSE handle by reference, remember to http_sse_free.
+ *
+ * Returns the same object (increases a reference count, no allocation is made).
+ */
+http_sse_s *http_sse_dup(http_sse_s *sse);
+
+/**
+ * Frees an SSE handle by reference (decreases the reference count).
+ */
+void http_sse_free(http_sse_s *sse);
 
 /* *****************************************************************************
-HTTP Helper functions that might be used globally
-*/
+HTTP GET and POST parsing helpers
+***************************************************************************** */
+
+/**
+ * Attempts to decode the request's body.
+ *
+ * Supported Types include:
+ * * application/x-www-form-urlencoded
+ * * application/json
+ * * multipart/form-data
+ *
+ * This should be called before `http_parse_query`, in order to support JSON
+ * data.
+ *
+ * If the JSON data isn't an object, it will be saved under the key "JSON" in
+ * the `params` hash.
+ *
+ * If the `multipart/form-data` type contains JSON files, they will NOT be
+ * parsed (they will behave like any other file, with `data`, `type` and
+ * `filename` keys assigned). This allows non-object JSON data (such as array)
+ * to be handled by the app.
+ */
+int http_parse_body(http_s *h);
+
+/**
+ * Parses the query part of an HTTP request/response. Uses `http_add2hash`.
+ *
+ * This should be called after the `http_parse_body` function, just in case the
+ * body is JSON that doesn't have an object at it's root.
+ */
+void http_parse_query(http_s *h);
+
+/** Parses any Cookie / Set-Cookie headers, using the `http_add2hash` scheme. */
+void http_parse_cookies(http_s *h, uint8_t is_url_encoded);
+
+/**
+ * Adds a named parameter to the hash, converting a string to an object and
+ * resolving nesting references and URL decoding if required.
+ *
+ * i.e.:
+ *
+ * * "name[]" references a nested Array (nested in the Hash).
+ * * "name[key]" references a nested Hash.
+ * * "name[][key]" references a nested Hash within an array. Hash keys will be
+ *   unique (repeating a key advances the hash).
+ * * These rules can be nested (i.e. "name[][key1][][key2]...")
+ * * "name[][]" is an error (there's no way for the parser to analyse
+ *    dimentions)
+ *
+ * Note: names can't begine with "[" or end with "]" as these are reserved
+ *       characters.
+ */
+int http_add2hash(FIOBJ dest, char *name, size_t name_len, char *value,
+                  size_t value_len, uint8_t encoded);
+
+/**
+ * Adds a named parameter to the hash, using an existing object and resolving
+ * nesting references.
+ *
+ * i.e.:
+ *
+ * * "name[]" references a nested Array (nested in the Hash).
+ * * "name[key]" references a nested Hash.
+ * * "name[][key]" references a nested Hash within an array. Hash keys will be
+ *   unique (repeating a key advances the hash).
+ * * These rules can be nested (i.e. "name[][key1][][key2]...")
+ * * "name[][]" is an error (there's no way for the parser to analyse
+ *    dimentions)
+ *
+ * Note: names can't begine with "[" or end with "]" as these are reserved
+ *       characters.
+ */
+int http_add2hash2(FIOBJ dest, char *name, size_t name_len, FIOBJ value,
+                   uint8_t encoded);
+
+/* *****************************************************************************
+HTTP Status Strings and Mime-Type helpers
+***************************************************************************** */
+
+/** Returns a human readable string related to the HTTP status number. */
+fio_cstr_s http_status2str(uintptr_t status);
+
+/** Registers a Mime-Type to be associated with the file extension. */
+void http_mimetype_register(char *file_ext, size_t file_ext_len,
+                            FIOBJ mime_type_str);
+
+/**
+ * Finds the mime-type associated with the file extension, returning a String on
+ * success and FIOBJ_INVALID on failure.
+ *
+ * Remember to call `fiobj_free`.
+ */
+FIOBJ http_mimetype_find(char *file_ext, size_t file_ext_len);
+
+/**
+ * Returns the mime-type associated with the URL or the default mime-type for
+ * HTTP.
+ *
+ * Remember to call `fiobj_free`.
+ */
+FIOBJ http_mimetype_find2(FIOBJ url);
+
+/** Clears the Mime-Type registry (it will be emoty afterthis call). */
+void http_mimetype_clear(void);
+
+/* *****************************************************************************
+Commonly used headers (fiobj Symbol objects)
+***************************************************************************** */
+
+extern FIOBJ HTTP_HEADER_ACCEPT;
+extern FIOBJ HTTP_HEADER_CACHE_CONTROL;
+extern FIOBJ HTTP_HEADER_CONNECTION;
+extern FIOBJ HTTP_HEADER_CONTENT_ENCODING;
+extern FIOBJ HTTP_HEADER_CONTENT_LENGTH;
+extern FIOBJ HTTP_HEADER_CONTENT_RANGE;
+extern FIOBJ HTTP_HEADER_CONTENT_TYPE;
+extern FIOBJ HTTP_HEADER_COOKIE;
+extern FIOBJ HTTP_HEADER_DATE;
+extern FIOBJ HTTP_HEADER_ETAG;
+extern FIOBJ HTTP_HEADER_HOST;
+extern FIOBJ HTTP_HEADER_LAST_MODIFIED;
+extern FIOBJ HTTP_HEADER_ORIGIN;
+extern FIOBJ HTTP_HEADER_SET_COOKIE;
+extern FIOBJ HTTP_HEADER_UPGRADE;
+
+/* *****************************************************************************
+HTTP General Helper functions that could be used globally
+***************************************************************************** */
+
+/**
+ * Returns a String object representing the unparsed HTTP request (HTTP version
+ * is capped at HTTP/1.1). Mostly usable for proxy usage and debugging.
+ */
+FIOBJ http_req2str(http_s *h);
+
+/**
+ * Writes a log line to `stderr` about the request / response object.
+ *
+ * This function is called automatically if the `.log` setting is enabled.
+ */
+void http_write_log(http_s *h);
+/* *****************************************************************************
+HTTP Time related helper functions that could be used globally
+***************************************************************************** */
 
 /**
 A faster (yet less localized) alternative to `gmtime_r`.
@@ -148,7 +890,7 @@ See the libc `gmtime_r` documentation for details.
 
 Falls back to `gmtime_r` for dates before epoch.
 */
-struct tm *http_gmtime(const time_t *timer, struct tm *tmbuf);
+struct tm *http_gmtime(time_t timer, struct tm *tmbuf);
 
 /**
 Writes an HTTP date string to the `target` buffer.
@@ -172,36 +914,14 @@ size_t http_date2rfc2822(char *target, struct tm *tmbuf);
  */
 size_t http_time2str(char *target, const time_t t);
 
-/**
-A fast, inline alternative to `sprintf(dest, "%lu", num)`.
-
-Writes an **unsigned** number to a buffer, as a string. This is an unsafe
-functions that assumes the buffer will have at least 21 bytes and isn't NULL.
-
-A NULL terminating byte is written.
-
-Returns the number of bytes actually written (excluding the NULL byte).
-*/
-static inline size_t http_ul2a(char *dest, size_t num) {
-  uint8_t digits = 1;
-  size_t tmp = num;
-  while ((tmp /= 10))
-    ++digits;
-
-  dest += digits;
-  *(dest--) = 0;
-  for (size_t i = 0; i < digits; i++) {
-    num = num - (10 * (tmp = (num / 10)));
-    *(dest--) = '0' + num;
-    num = tmp;
-  }
-  return digits;
-}
+/* *****************************************************************************
+HTTP URL decoding helper functions that might be used globally
+***************************************************************************** */
 
 /** Decodes a URL encoded string, no buffer overflow protection. */
 ssize_t http_decode_url_unsafe(char *dest, const char *url_data);
 
-/** Decodes a URL encoded string (i.e., the "query" part of a request). */
+/** Decodes a URL encoded string (query / form data). */
 ssize_t http_decode_url(char *dest, const char *url_data, size_t length);
 
 /** Decodes the "path" part of a request, no buffer overflow protection. */
@@ -211,8 +931,9 @@ ssize_t http_decode_path_unsafe(char *dest, const char *url_data);
  */
 ssize_t http_decode_path(char *dest, const char *url_data, size_t length);
 
+/* support C++ */
 #ifdef __cplusplus
-} /* extern "C" */
+}
 #endif
 
-#endif
+#endif /* H_HTTP_H */