iodine 0.3.6 → 0.4.0

data/ext/iodine/resp.h

@@ -0,0 +1,253 @@
+/*
+Copyright: Boaz segev, 2017
+License: MIT except for any non-public-domain algorithms (none that I'm aware
+of), which might be subject to their own licenses.
+
+Feel free to copy, use and enjoy in accordance with to the license(s).
+*/
+#ifndef H_RESP_PARSER_H
+/**
+This is a neive implementation of the RESP protocol for Redis.
+*/
+#define H_RESP_PARSER_H
+
+#include <stdint.h>
+#include <stdlib.h>
+
+/** The RESP Parser Type */
+typedef struct resp_parser_s *resp_parser_pt;
+
+/* *****************************************************************************
+RESP types and objects (Arrays, Strings & Integers)
+***************************************************************************** */
+
+enum resp_type_enum {
+  /** A simple flag object object (`resp_object_s`) for NULL. */
+  RESP_NULL = 0,
+  /** A simple flag object object (`resp_object_s`) for OK. */
+  RESP_OK = 1,
+  /** A String object (`resp_string_s`) that indicates an error. */
+  RESP_ERR = (2 + 8),
+  /** A Number object object (`resp_number_s`). */
+  RESP_NUMBER = 4,
+  /** A String object (`resp_string_s`). */
+  RESP_STRING = 8,
+  /** An Array object object (`resp_array_s`). */
+  RESP_ARRAY = 16,
+  /**
+   * A specific Array object object (`resp_array_s`) for Pub/Sub semantics.
+   *
+   * This is more of a hint than a decree, sometimes pubsub semantics are
+   * misleading.
+   */
+  RESP_PUBSUB = (32 + 16),
+};
+
+/** a simple emtpy object type, used for RESP_NULL and RESP_OK */
+typedef struct { enum resp_type_enum type; } resp_object_s;
+
+/** The RESP_ARRAY and RESP_PUBSUB types */
+typedef struct {
+  enum resp_type_enum type;
+  size_t len;
+  size_t pos; /** allows simple iteration. */
+  resp_object_s *array[];
+} resp_array_s;
+
+/** The RESP_STRING and RESP_ERR types */
+typedef struct {
+  enum resp_type_enum type;
+  size_t len;
+  uint8_t string[];
+} resp_string_s;
+
+/** The RESP_NUMBER type */
+typedef struct {
+  enum resp_type_enum type;
+  int64_t number;
+} resp_number_s;
+
+#define resp_obj2arr(obj)                                                      \
+  ((resp_array_s *)((obj)->type == RESP_ARRAY || (obj)->type == RESP_PUBSUB    \
+                        ? (obj)                                                \
+                        : NULL))
+#define resp_obj2str(obj)                                                      \
+  ((resp_string_s *)((obj)->type == RESP_STRING || (obj)->type == RESP_ERR     \
+                         ? (obj)                                               \
+                         : NULL))
+#define resp_obj2num(obj)                                                      \
+  ((resp_number_s *)((obj)->type == RESP_NUMBER ? (obj) : NULL))
+
+/** Allocates an RESP NULL objcet. Remeber to free when done. */
+resp_object_s *resp_nil2obj(void);
+
+/** Allocates an RESP OK objcet. Remeber to free when done. */
+resp_object_s *resp_OK2obj(void);
+
+/** Allocates an RESP Error objcet. Remeber to free when done. */
+resp_object_s *resp_err2obj(const void *msg, size_t len);
+
+/** Allocates an RESP Number objcet. Remeber to free when done. */
+resp_object_s *resp_num2obj(uint64_t num);
+
+/** Allocates an RESP String objcet. Remeber to free when done. */
+resp_object_s *resp_str2obj(const void *str, size_t len);
+
+/**
+ *Allocates an RESP Array objcet. Remeber to free when done (freeing an array
+ *frees it's children automatically).
+ *
+ * It's possible to pass NULL as the `argv`, in which case the array created
+ * will have the capacity `argc` and could me manually populated.
+ *
+ * The objects are MOVED into the array's possesion. If you wish to retain a
+ * copy of the objects, use the `resp_dup_object` to increase their reference
+ * count.
+ */
+resp_object_s *resp_arr2obj(int argc, resp_object_s *argv[]);
+
+/** Duplicates an object by increasing it's reference count. */
+resp_object_s *resp_dup_object(resp_object_s *obj);
+
+/** frees an object by decreasing it's reference count and testing. */
+void resp_free_object(resp_object_s *obj);
+
+/**
+ * Formats a RESP object back into a string.
+ *
+ * Returns 0 on success and -1 on failur.
+ *
+ * Accepts a memory buffer `dest` to which the data will be written and a poiner
+ * to the size of the buffer.
+ *
+ * Once the function returns, `size` will be updated to include the number of
+ * bytes required for the string. If the function returned a failuer, this value
+ * can be used to allocate enough memory to contain the string.
+ *
+ * The string is Binary safe and it ISN'T always NUL terminated.
+ *
+ * The optional `parser` argument allows experimental extensions to be used when
+ * formatting the object. It can be ignored when formatting without extensions.
+ *
+ * **If implementing a server**: DON'T use this to format outgoing pub/sub
+ * notifications.
+ *
+ * When implementing a server, Pub/Sub should avoid multiple copies by using a
+ * dedicated buffer with a reference count. By decreasing the reference count
+ * every time the message was sent (see the `sock_write2` support for the
+ * dealloc callback), it's possible to avoid multiple copies of the message.
+ */
+int resp_format(resp_parser_pt p, uint8_t *dest, size_t *size,
+                resp_object_s *obj);
+
+/**
+ * Performs a task on each object. Protects from loop-backs.
+ *
+ * To break loop in the middle, `task` can return -1.
+ *
+ * Returns count.
+ */
+size_t resp_obj_each(resp_parser_pt p, resp_object_s *obj,
+                     int (*task)(resp_parser_pt p, resp_object_s *obj,
+                                 void *arg),
+                     void *arg);
+
+/* *****************************************************************************
+The RESP Parser
+***************************************************************************** */
+
+/** create the parser */
+resp_parser_pt resp_parser_new(void);
+
+/** free the parser and it's resources. */
+void resp_parser_destroy(resp_parser_pt);
+
+/** Clears the parser state, as if starting a new session / connection. */
+void resp_parser_clear(resp_parser_pt);
+
+/**
+ * Feed the parser with data.
+ *
+ * Returns any fully parsed object / reply (often an array, but not always) or
+ * NULL (needs more data / error).
+ *
+ * If a RESP object was parsed, it is returned and `len` is updated to reflect
+ * the number of bytes actually read.
+ *
+ * If more data is needed, NULL is returned and `len` is left unchanged.
+ *
+ * An error is reported by by returning NULL and setting `len` to 0 at the same
+ * time.
+ *
+ * Partial consumption is possible when multiple replys were available in the
+ * buffer. Otherwise the parser will consume the whole of the buffer.
+ *
+ */
+resp_object_s *resp_parser_feed(resp_parser_pt, uint8_t *buffer, size_t *len);
+
+/* *****************************************************************************
+State - The Pub / Sub Multiplexer (Experimental)
+***************************************************************************** */
+
+/**
+It seems to me that the main reason that pub/sub messages and normal RESP
+connetcions cannot share the same socket is the risk of identity collisions.
+
+For example, the command LRANGE might return the following array response
+`["message", "users", "hello"]`... this looks exactly like a Pub/Sub
+notification.
+
+However, this situation is very uncomfortable. For example:
+
+* The sender already knows the content of the message. There is no reason to
+  waste bandwidth to send the same message back to the sender using a different
+  socket.
+
+* The cost isn't just Bandwidth, but also memory, since the sender will have two
+  copies of the same message (if not more), the one being sent and the other
+  being received (sometimes more then once, for different channel patterns).
+
+
+* Instead of handling the message localy, the sender is forced to wait until the
+  message is received by the pub/sub Redis conection - otherwise tere will be
+  duplicate messages being published.
+
+* This design doubles the client load (number of connections) for each Redis
+  server (and client).
+
+But we can solve this.
+
+For example, what if we use a "magic byte" to distinguish between the array
+`["message", "users", "hello"]` and the pub/sub notification `["message",
+"users", "hello"]`?
+
+What if every time the first word in an array response satrts with an `"m"` or a
+`"+"`, we will add the `"+"` byte infront of it?
+
+Now the notification will look like this: `["message", "users", "hello"]`, and
+the array response (i.e. to `LRANGE`) will be: `["+message", "users", "hello"]`
+- a distinct difference allowing for pub/sub and regular conections to use the
+same pipelining socket.
+
+The big issue (and I may be wrong), is backwards compatibility - we can't change
+the semantics of the protocol without breaking existing clients... or can we?
+
+I believe this hurdle can be easily circumvented by adding a single command to
+the existing pallet. Somthing along the lines of: `ENABLE <feature>`.
+
+Such a flexible command allows clients to negotiate changes to the semantics
+for the connection. It's meant to be a single non-reversible change for the
+specific connection (similar to the `Upgrade` HTTP/Websocket concept).
+
+Now, the little `"+"` "magic byte" can be easily handled.
+
+The following function activates the "magic byte" assuming the `ENABLE` command
+was negotiated for the connection.
+*/
+void resp_enable_duplex_pubsub(resp_parser_pt parser);
+
+#ifdef DEBUG
+void resp_test(void);
+#endif
+
+#endif

data/ext/iodine/sock.c

@@ -383,15 +383,23 @@ Writing - from files
 struct sock_packet_file_data_s {
   intptr_t fd;
   off_t offset;
-  void (*close)(void *);
+  union {
+    void (*close)(intptr_t);
+    void (*dealloc)(void *);
+  };
+  int *pfd;
   uint8_t buffer[];
 };
 
 static void sock_perform_close_fd(intptr_t fd) { close(fd); }
+static void sock_perform_close_pfd(void *pfd) { close(*(int *)pfd); }
 
 static void sock_close_from_fd(packet_s *packet) {
   struct sock_packet_file_data_s *ext = (void *)packet->buffer.buf;
-  ext->close((void *)ext->fd);
+  if (ext->pfd)
+    ext->dealloc(ext->pfd);
+  else
+    ext->close(ext->fd);
 }
 
 static int sock_write_from_fd(int fd, struct packet_s *packet) {
@@ -871,10 +879,9 @@ ssize_t sock_read(intptr_t uuid, void *buf, size_t count) {
 */
 ssize_t sock_write2_fn(sock_write_info_s options) {
   int fd = sock_uuid2fd(options.uuid);
-  if (validate_uuid(options.uuid))
-    clear_fd(fd, 0);
+
   // avoid work when an error is expected to occur.
-  if (!fdinfo(fd).open || options.offset < 0) {
+  if (validate_uuid(options.uuid) || !fdinfo(fd).open || options.offset < 0) {
     if (options.move == 0) {
       errno = (options.offset < 0) ? ERANGE : EBADF;
       return -1;
@@ -887,12 +894,11 @@ ssize_t sock_write2_fn(sock_write_info_s options) {
     errno = (options.offset < 0) ? ERANGE : EBADF;
     return -1;
   }
-  // if (options.offset < 0)
-  //   options.offset = 0;
+
   packet_s *packet = sock_packet_grab();
   packet->buffer.len = options.length;
-  if (options.is_fd == 0) {  /* is data */
-    if (options.move == 0) { /* memory is copied. */
+  if (options.is_fd == 0 && options.is_pfd == 0) { /* is data */
+    if (options.move == 0) {                       /* memory is copied. */
       if (options.length <= BUFFER_PACKET_SIZE) {
         /* small enough for internal buffer */
         memcpy(packet->buffer.buf, (uint8_t *)options.buffer + options.offset,
@@ -915,11 +921,18 @@ ssize_t sock_write2_fn(sock_write_info_s options) {
     ext->dealloc = options.dealloc ? options.dealloc : free;
     packet->metadata = (struct packet_metadata_s){
         .write_func = sock_write_buffer_ext, .free_func = sock_free_buffer_ext};
+
   } else { /* is file */
     struct sock_packet_file_data_s *ext = (void *)packet->buffer.buf;
-    ext->fd = options.data_fd;
-    ext->close = options.dealloc ? options.dealloc
-                                 : (void (*)(void *))sock_perform_close_fd;
+    if (options.is_pfd) {
+      ext->pfd = (int *)options.buffer;
+      ext->fd = *ext->pfd;
+      ext->dealloc = options.dealloc ? options.dealloc : sock_perform_close_pfd;
+    } else {
+      ext->fd = options.data_fd;
+      ext->pfd = NULL;
+      ext->close = options.close ? options.close : sock_perform_close_fd;
+    }
     ext->offset = options.offset;
     packet->metadata = (struct packet_metadata_s){
         .write_func =
@@ -929,6 +942,7 @@ ssize_t sock_write2_fn(sock_write_info_s options) {
         .free_func = options.move ? sock_close_from_fd
                                   : (void (*)(packet_s *))SOCK_DEALLOC_NOOP};
   }
+
 /* place packet in queue */
 place_packet_in_queue:
   if (validate_uuid(options.uuid))

data/ext/iodine/sock.h

@@ -268,7 +268,7 @@ typedef struct {
     /** This is an alternative deallocation callback accessor (same memory space
      * as `dealloc`) for conveniently setting the file `close` callback.
      */
-    void (*close)(int fd);
+    void (*close)(intptr_t fd);
   };
   /** The length (size) of the buffer, or the amount of data to be sent from the
    * file descriptor.
@@ -283,10 +283,21 @@ typedef struct {
   unsigned move : 1;
   /** The packet will be sent as soon as possible. */
   unsigned urgent : 1;
-  /** The buffer contains the value of a file descriptor (`int`) - casting, not
-   * pointing, i.e.: `.buffer = (void*)fd;`
+  /**
+   * The buffer contains the value of a file descriptor (`int`). i.e.:
+   *  `.data_fd = fd` or `.buffer = (void*)fd;`
    */
   unsigned is_fd : 1;
+  /**
+   * The buffer **points** to a file descriptor (`int`): `.buffer = (void*)&fd;`
+   *
+   * In the case the `dealloc` function will be called, allowing both closure
+   * and deallocation of the `int` pointer.
+   *
+   * This feature can be used for file reference counting, such as implemented
+   * by the `fio_file_cache` service.
+   */
+  unsigned is_pfd : 1;
   /** for internal use */
   unsigned rsv : 1;
 } sock_write_info_s;

data/ext/iodine/spnlock.inc

@@ -43,15 +43,32 @@ typedef volatile unsigned char spn_lock_i;
 
 /* Select the correct compiler builtin method. */
 #if defined(__has_builtin)
-#if __has_builtin(__sync_swap)
-#define SPN_LOCK_BUILTIN(...) __sync_swap(__VA_ARGS__)
+
+#if __has_builtin(__atomic_exchange_n)
+#define SPN_LOCK_BUILTIN(...) __atomic_exchange_n(__VA_ARGS__, __ATOMIC_ACQ_REL)
+/** An atomic addition operation */
+#define spn_add(...) __atomic_add_fetch(__VA_ARGS__, __ATOMIC_ACQ_REL)
+/** An atomic subtraction operation */
+#define spn_sub(...) __atomic_sub_fetch(__VA_ARGS__, __ATOMIC_ACQ_REL)
+
 #elif __has_builtin(__sync_fetch_and_or)
 #define SPN_LOCK_BUILTIN(...) __sync_fetch_and_or(__VA_ARGS__)
+/** An atomic addition operation */
+#define spn_add(...) __sync_add_and_fetch(__VA_ARGS__)
+/** An atomic subtraction operation */
+#define spn_sub(...) __sync_sub_and_fetch(__VA_ARGS__)
+
 #else
 #error Required builtin "__sync_swap" or "__sync_fetch_and_or" missing from compiler.
 #endif /* defined(__has_builtin) */
+
 #elif __GNUC__ > 3
 #define SPN_LOCK_BUILTIN(...) __sync_fetch_and_or(__VA_ARGS__)
+/** An atomic addition operation */
+#define spn_add(...) __sync_add_and_fetch(__VA_ARGS__)
+/** An atomic subtraction operation */
+#define spn_sub(...) __sync_sub_and_fetch(__VA_ARGS__)
+
 #else
 #error Required builtin "__sync_swap" or "__sync_fetch_and_or" not found.
 #endif

data/ext/iodine/websockets.c

@@ -6,7 +6,10 @@ Feel free to copy, use and enjoy according to the license provided.
 */
 #include "spnlock.inc"
 
+#include "fio_list.h"
+
 #include "bscrypt.h"
+#include "pubsub.h"
 #include "websockets.h"
 #include <arpa/inet.h>
 #include <errno.h>
@@ -106,10 +109,14 @@ struct Websocket {
   void *udata;
   /** The maximum websocket message size */
   size_t max_msg_size;
+  /** active pub/sub subscriptions */
+  fio_list_s subscriptions;
   /** message buffer. */
   struct buffer_s buffer;
   /** message length (how much of the buffer actually used). */
   size_t length;
+  /** for fragmenting the `on_data` parsing and message handling. */
+  size_t resume_from;
   /** parser. */
   struct {
     union {
@@ -156,6 +163,35 @@ static __thread struct {
   char buffer[WEBSOCKET_READ_MAX];
 } read_buffer;
 
+/* *****************************************************************************
+Create/Destroy the websocket subscription objects
+***************************************************************************** */
+
+typedef struct {
+  fio_list_s node;
+  pubsub_sub_pt sub;
+} subscription_s;
+
+static inline subscription_s *create_subscription(ws_s *ws, pubsub_sub_pt sub) {
+  subscription_s *s = malloc(sizeof(*s));
+  s->sub = sub;
+  fio_list_add(&ws->subscriptions, &s->node);
+  return s;
+}
+
+static inline void free_subscription(subscription_s *s) {
+  fio_list_remove(&s->node);
+  free(s);
+}
+
+static inline void clear_subscriptions(ws_s *ws) {
+  subscription_s *s;
+  fio_list_for_each(subscription_s, node, s, ws->subscriptions) {
+    pubsub_unsubscribe(s->sub);
+    free_subscription(s);
+  }
+}
+
 /*******************************************************************************
 The Websocket Protocol implementation
 */
@@ -168,7 +204,10 @@ static void ws_ping(intptr_t fd, protocol_s *ws) {
               .dealloc = SOCK_DEALLOC_NOOP);
 }
 
-static void on_close(protocol_s *_ws) { destroy_ws((ws_s *)_ws); }
+static void on_close(intptr_t uuid, protocol_s *_ws) {
+  destroy_ws((ws_s *)_ws);
+  (void)uuid;
+}
 
 static void on_ready(intptr_t fduuid, protocol_s *ws) {
   (void)(fduuid);
@@ -194,6 +233,12 @@ static void websocket_write_impl(intptr_t fd, void *data, size_t len, char text,
 static size_t websocket_encode(void *buff, void *data, size_t len, char text,
                                char first, char last, char client);
 
+static void on_data(intptr_t sockfd, protocol_s *_ws);
+static void on_data_def(intptr_t sockfd, protocol_s *_ws, void *arg) {
+  on_data(sockfd, _ws);
+  (void)arg;
+}
+
 /* read data from the socket, parse it and invoke the websocket events. */
 static void on_data(intptr_t sockfd, protocol_s *_ws) {
 #define ws ((ws_s *)_ws)
@@ -201,8 +246,15 @@ static void on_data(intptr_t sockfd, protocol_s *_ws) {
     return;
   ssize_t len = 0;
   ssize_t data_len = 0;
+  if (ws->resume_from) {
+    sock_touch(sockfd);
+    len = ws->resume_from;
+    ws->resume_from = 0;
+    goto resume_parsing;
+  }
   while ((len = sock_read(sockfd, read_buffer.buffer, WEBSOCKET_READ_MAX)) >
          0) {
+  resume_parsing:
     data_len = 0;
     read_buffer.pos = 0;
     while (read_buffer.pos < len) {
@@ -424,6 +476,13 @@ static void on_data(intptr_t sockfd, protocol_s *_ws) {
       *((char *)(&(ws->parser.head))) = 0;
       ws->parser.received = ws->parser.length = ws->parser.psize.len2 =
           data_len = 0;
+      if (read_buffer.pos < len) {
+        /* we just finished an on_message callback, let's fragment the event. */
+        ws->resume_from = len;
+        facil_defer(.task = on_data_def, .task_type = FIO_PR_LOCK_TASK,
+                    .uuid = sockfd);
+        return;
+      }
     }
   }
 #undef ws
@@ -436,19 +495,19 @@ Create/Destroy the websocket object
 static ws_s *new_websocket() {
   // allocate the protocol object
   ws_s *ws = malloc(sizeof(*ws));
-  memset(ws, 0, sizeof(*ws));
-
-  // setup the protocol & protocol callbacks
-  ws->protocol.ping = ws_ping;
-  ws->protocol.service = WEBSOCKET_ID_STR;
-  ws->protocol.on_data = on_data;
-  ws->protocol.on_close = on_close;
-  ws->protocol.on_ready = on_ready;
-  ws->protocol.on_shutdown = on_shutdown;
-  // return the object
+  *ws = (ws_s){
+      .protocol.service = WEBSOCKET_ID_STR,
+      .protocol.ping = ws_ping,
+      .protocol.on_data = on_data,
+      .protocol.on_close = on_close,
+      .protocol.on_ready = on_ready,
+      .protocol.on_shutdown = on_shutdown,
+      .subscriptions = FIO_LIST_INIT_STATIC(ws->subscriptions),
+  };
   return ws;
 }
 static void destroy_ws(ws_s *ws) {
+  clear_subscriptions(ws);
   if (ws->on_close)
     ws->on_close(ws);
   free_ws_buffer(ws, ws->buffer);
@@ -610,6 +669,235 @@ static void websocket_write_impl(intptr_t fd, void *data, size_t len,
   return;
 }
 
+/* *****************************************************************************
+UTF-8 testing. This part was practically copied from:
+https://stackoverflow.com/a/22135005/4025095
+and
+http://bjoern.hoehrmann.de/utf-8/decoder/dfa
+***************************************************************************** */
+/* Copyright (c) 2008-2009 Bjoern Hoehrmann <bjoern@hoehrmann.de> */
+/* See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details. */
+
+#define UTF8_ACCEPT 0
+#define UTF8_REJECT 1
+
+static const uint8_t utf8d[] = {
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0, // 00..1f
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0, // 20..3f
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0, // 40..5f
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
+    0,   0,   0,   0,   0,   0,   0,   0,   0,   0, // 60..7f
+    1,   1,   1,   1,   1,   1,   1,   1,   1,   1,   1,
+    1,   1,   1,   1,   1,   9,   9,   9,   9,   9,   9,
+    9,   9,   9,   9,   9,   9,   9,   9,   9,   9, // 80..9f
+    7,   7,   7,   7,   7,   7,   7,   7,   7,   7,   7,
+    7,   7,   7,   7,   7,   7,   7,   7,   7,   7,   7,
+    7,   7,   7,   7,   7,   7,   7,   7,   7,   7, // a0..bf
+    8,   8,   2,   2,   2,   2,   2,   2,   2,   2,   2,
+    2,   2,   2,   2,   2,   2,   2,   2,   2,   2,   2,
+    2,   2,   2,   2,   2,   2,   2,   2,   2,   2, // c0..df
+    0xa, 0x3, 0x3, 0x3, 0x3, 0x3, 0x3, 0x3, 0x3, 0x3, 0x3,
+    0x3, 0x3, 0x4, 0x3, 0x3, // e0..ef
+    0xb, 0x6, 0x6, 0x6, 0x5, 0x8, 0x8, 0x8, 0x8, 0x8, 0x8,
+    0x8, 0x8, 0x8, 0x8, 0x8, // f0..ff
+    0x0, 0x1, 0x2, 0x3, 0x5, 0x8, 0x7, 0x1, 0x1, 0x1, 0x4,
+    0x6, 0x1, 0x1, 0x1, 0x1, // s0..s0
+    1,   1,   1,   1,   1,   1,   1,   1,   1,   1,   1,
+    1,   1,   1,   1,   1,   1,   0,   1,   1,   1,   1,
+    1,   0,   1,   0,   1,   1,   1,   1,   1,   1, // s1..s2
+    1,   2,   1,   1,   1,   1,   1,   2,   1,   2,   1,
+    1,   1,   1,   1,   1,   1,   1,   1,   1,   1,   1,
+    1,   2,   1,   1,   1,   1,   1,   1,   1,   1, // s3..s4
+    1,   2,   1,   1,   1,   1,   1,   1,   1,   2,   1,
+    1,   1,   1,   1,   1,   1,   1,   1,   1,   1,   1,
+    1,   3,   1,   3,   1,   1,   1,   1,   1,   1, // s5..s6
+    1,   3,   1,   1,   1,   1,   1,   3,   1,   3,   1,
+    1,   1,   1,   1,   1,   1,   3,   1,   1,   1,   1,
+    1,   1,   1,   1,   1,   1,   1,   1,   1,   1, // s7..s8
+};
+
+static inline uint32_t validate_utf8(uint8_t *str, size_t len) {
+  uint32_t state = 0;
+  uint32_t type;
+  while (len) {
+    type = utf8d[*str];
+    state = utf8d[256 + state * 16 + type];
+    if (state == UTF8_REJECT)
+      return 0;
+    len--;
+    str++;
+  }
+  return state == 0;
+}
+/* *****************************************************************************
+Subscription handling
+***************************************************************************** */
+
+typedef struct {
+  void (*on_message)(websocket_pubsub_notification_s notification);
+  void (*on_unsubscribe)(void *udata);
+  void *udata;
+} websocket_sub_data_s;
+
+static void websocket_on_unsubscribe(void *u1, void *u2) {
+  websocket_sub_data_s *d = u2;
+  (void)u1;
+  if (d->on_unsubscribe)
+    d->on_unsubscribe(d->udata);
+  free(d);
+}
+
+static void websocket_on_pubsub_message_direct(pubsub_message_s *msg) {
+  protocol_s *pr =
+      facil_protocol_try_lock((intptr_t)msg->udata1, FIO_PR_LOCK_WRITE);
+  if (!pr) {
+    if (errno == EBADF)
+      return;
+    pubsub_defer(msg);
+    return;
+  }
+  websocket_write((ws_s *)pr, msg->msg.data, msg->msg.len,
+                  msg->msg.len >= (2 << 14)
+                      ? 0
+                      : validate_utf8((uint8_t *)msg->msg.data, msg->msg.len));
+  facil_protocol_unlock(pr, FIO_PR_LOCK_WRITE);
+}
+
+static void websocket_on_pubsub_message_direct_txt(pubsub_message_s *msg) {
+  protocol_s *pr =
+      facil_protocol_try_lock((intptr_t)msg->udata1, FIO_PR_LOCK_WRITE);
+  if (!pr) {
+    if (errno == EBADF)
+      return;
+    pubsub_defer(msg);
+    return;
+  }
+  websocket_write((ws_s *)pr, msg->msg.data, msg->msg.len, 1);
+  facil_protocol_unlock(pr, FIO_PR_LOCK_WRITE);
+}
+
+static void websocket_on_pubsub_message_direct_bin(pubsub_message_s *msg) {
+  protocol_s *pr =
+      facil_protocol_try_lock((intptr_t)msg->udata1, FIO_PR_LOCK_WRITE);
+  if (!pr) {
+    if (errno == EBADF)
+      return;
+    pubsub_defer(msg);
+    return;
+  }
+  websocket_write((ws_s *)pr, msg->msg.data, msg->msg.len, 0);
+  facil_protocol_unlock(pr, FIO_PR_LOCK_WRITE);
+}
+
+static void websocket_on_pubsub_message(pubsub_message_s *msg) {
+  protocol_s *pr =
+      facil_protocol_try_lock((intptr_t)msg->udata1, FIO_PR_LOCK_TASK);
+  if (!pr) {
+    if (errno == EBADF)
+      return;
+    pubsub_defer(msg);
+    return;
+  }
+  websocket_sub_data_s *d = msg->udata2;
+
+  if (d->on_message)
+    d->on_message((websocket_pubsub_notification_s){
+        .ws = (ws_s *)pr,
+        .engine = (pubsub_engine_s *)msg->engine,
+        .subscription_id = (intptr_t)msg->subscription,
+        .channel = {.name = msg->channel.name, .len = msg->channel.len},
+        .msg = {.data = msg->msg.data, .len = msg->msg.len},
+        .use_pattern = msg->use_pattern,
+    });
+  facil_protocol_unlock(pr, FIO_PR_LOCK_TASK);
+}
+
+/**
+ * Returns a subscription ID on success and 0 on failure.
+ */
+#undef websocket_subscribe
+uintptr_t websocket_subscribe(struct websocket_subscribe_s args) {
+  websocket_sub_data_s *d = malloc(sizeof(*d));
+  *d = (websocket_sub_data_s){.udata = args.udata,
+                              .on_message = args.on_message,
+                              .on_unsubscribe = args.on_unsubscribe};
+  pubsub_sub_pt sub = pubsub_subscribe(
+          .engine = args.engine,
+          .channel =
+              {
+                  .name = (char *)args.channel.name, .len = args.channel.len,
+              },
+          .use_pattern = args.use_pattern,
+          .on_unsubscribe = websocket_on_unsubscribe,
+          .on_message =
+              (args.on_message
+                   ? websocket_on_pubsub_message
+                   : args.force_binary
+                         ? websocket_on_pubsub_message_direct_bin
+                         : args.force_text
+                               ? websocket_on_pubsub_message_direct_txt
+                               : websocket_on_pubsub_message_direct),
+          .udata1 = (void *)args.ws->fd, .udata2 = d);
+  if (!sub) {
+    free(d);
+    return 0;
+  }
+  subscription_s *s = create_subscription(args.ws, sub);
+  return (uintptr_t)s;
+}
+
+/**
+ * Returns the existing subscription's ID (if exists) or 0 (no subscription).
+ */
+#undef websocket_find_sub
+uintptr_t websocket_find_sub(struct websocket_subscribe_s args) {
+  pubsub_sub_pt sub = pubsub_find_sub(
+          .engine = args.engine,
+          .channel =
+              {
+                  .name = (char *)args.channel.name, .len = args.channel.len,
+              },
+          .use_pattern = args.use_pattern,
+          .on_message =
+              (args.on_message
+                   ? websocket_on_pubsub_message
+                   : args.force_binary
+                         ? websocket_on_pubsub_message_direct_bin
+                         : args.force_text
+                               ? websocket_on_pubsub_message_direct_txt
+                               : websocket_on_pubsub_message_direct),
+          .udata1 = (void *)args.ws->fd, .udata2 = args.udata);
+  if (!sub)
+    return 0;
+  subscription_s *s;
+  fio_list_for_each(subscription_s, node, s, args.ws->subscriptions) {
+    if (s->sub == sub)
+      return (uintptr_t)s;
+  }
+  return 0;
+}
+
+/**
+ * Unsubscribes from a channel.
+ */
+void websocket_unsubscribe(ws_s *ws, uintptr_t subscription_id) {
+  subscription_s *s;
+  fio_list_for_each(subscription_s, node, s, ws->subscriptions) {
+    if (s == (subscription_s *)subscription_id) {
+      pubsub_unsubscribe(s->sub);
+      free_subscription(s);
+      return;
+    }
+  }
+}
+
 /*******************************************************************************
 The API implementation
 */