iodine 0.4.19 → 0.5.0

data/ext/iodine/iodine_pubsub.h

@@ -9,7 +9,17 @@ Feel free to copy, use and enjoy according to the license provided.
 #include "iodine.h"
 #include "pubsub.h"
 
+typedef enum {
+  IODINE_PUBSUB_GLOBAL,
+  IODINE_PUBSUB_WEBSOCKET,
+  IODINE_PUBSUB_SSE
+} iodine_pubsub_type_e;
+
 extern VALUE IodineEngine;
+extern ID iodine_engine_pubid;
+VALUE iodine_publish(int argc, VALUE *argv, VALUE self);
+VALUE iodine_subscribe(int argc, VALUE *argv, void *owner,
+                       iodine_pubsub_type_e type);
 
 typedef struct {
   pubsub_engine_s engine;

data/ext/iodine/iodine_websockets.c

@@ -20,17 +20,10 @@ Core helpers and data
 static VALUE IodineWebsocket; // The Iodine::Http::Websocket class
 static ID ws_var_id;          // id for websocket pointer
 static ID dup_func_id;        // id for the buffer.dup method
+static ID iodine_on_ready_id; // id for the on_ready method
 
-static VALUE force_var_id;
-static VALUE channel_var_id;
-static VALUE pattern_var_id;
-static VALUE text_var_id;
-static VALUE binary_var_id;
-static VALUE engine_var_id;
-static VALUE message_var_id;
-
-#define set_uuid(object, request)                                              \
-  rb_ivar_set((object), iodine_fd_var_id, ULONG2NUM((request)->fd))
+#define set_uuid(object, uuid)                                                 \
+  rb_ivar_set((object), iodine_fd_var_id, ULONG2NUM((uuid)))
 
 inline static intptr_t get_uuid(VALUE obj) {
   VALUE i = rb_ivar_get(obj, iodine_fd_var_id);
@@ -51,85 +44,35 @@ inline static ws_s *get_ws(VALUE obj) {
 #define get_handler(ws) ((VALUE)websocket_udata((ws_s *)(ws)))
 
 /* *****************************************************************************
-Buffer management - Rubyfy the way the buffer is handled.
-***************************************************************************** */
-
-// struct buffer_s {
-//   void *data;
-//   size_t size;
-// };
-//
-// /** returns a buffer_s struct, with a buffer (at least) `size` long. */
-// struct buffer_s create_ws_buffer(ws_s *owner);
-//
-// /** returns a buffer_s struct, with a buffer (at least) `size` long. */
-// struct buffer_s resize_ws_buffer(ws_s *owner, struct buffer_s);
-//
-// /** releases an existing buffer. */
-// void free_ws_buffer(ws_s *owner, struct buffer_s);
-//
-// /** Sets the initial buffer size. (4Kb)*/
-// #define WS_INITIAL_BUFFER_SIZE 4096
-//
-// // buffer increments by 4,096 Bytes (4Kb)
-// #define round_up_buffer_size(size) ((((size) >> 12) + 1) << 12)
-//
-// struct buffer_args {
-//   struct buffer_s buffer;
-//   ws_s *ws;
-// };
-//
-// void *ruby_land_buffer(void *_buf) {
-// #define args ((struct buffer_args *)(_buf))
-//   if (args->buffer.data == NULL) {
-//     VALUE rbbuff = rb_str_buf_new(WS_INITIAL_BUFFER_SIZE);
-//     rb_ivar_set(get_handler(args->ws), iodine_buff_var_id, rbbuff);
-//     rb_str_set_len(rbbuff, 0);
-//     rb_enc_associate(rbbuff, IodineBinaryEncoding);
-//     args->buffer.data = RSTRING_PTR(rbbuff);
-//     args->buffer.size = WS_INITIAL_BUFFER_SIZE;
-//
-//   } else {
-//     VALUE rbbuff = rb_ivar_get(get_handler(args->ws), iodine_buff_var_id);
-//     rb_str_modify(rbbuff);
-//     rb_str_resize(rbbuff, args->buffer.size);
-//     args->buffer.data = RSTRING_PTR(rbbuff);
-//     args->buffer.size = rb_str_capacity(rbbuff);
-//   }
-//   return NULL;
-// #undef args
-// }
-//
-// struct buffer_s create_ws_buffer(ws_s *owner) {
-//   struct buffer_args args = {.ws = owner};
-//   RubyCaller.call_c(ruby_land_buffer, &args);
-//   return args.buffer;
-// }
-//
-// struct buffer_s resize_ws_buffer(ws_s *owner, struct buffer_s buffer) {
-//   buffer.size = round_up_buffer_size(buffer.size);
-//   struct buffer_args args = {.ws = owner, .buffer = buffer};
-//   RubyCaller.call_c(ruby_land_buffer, &args);
-//   return args.buffer;
-// }
-// void free_ws_buffer(ws_s *owner, struct buffer_s buff) {
-//   (void)(owner);
-//   (void)(buff);
-// }
-//
-// #undef round_up_buffer_size
-
-/* *****************************************************************************
-Websocket Ruby API
+SSE / Websocket Ruby API
 ***************************************************************************** */
 
 /** Closes the websocket connection. The connection is only closed after
  * existing data in the outgoing buffer is sent. */
 static VALUE iodine_ws_close(VALUE self) {
-  ws_s *ws = get_ws(self);
-  if (!ws || ((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
+  void *ws = get_ws(self);
+  if (!ws) {
     return Qfalse;
-  websocket_close(ws);
+  }
+  iodine_pubsub_type_e c_type = (iodine_pubsub_type_e)iodine_get_cdata(self);
+  switch (c_type) {
+  case IODINE_PUBSUB_WEBSOCKET:
+    /* WebSockets*/
+    if (((protocol_s *)ws)->service != WEBSOCKET_ID_STR) {
+      return Qfalse;
+    }
+    websocket_close(ws);
+    break;
+  case IODINE_PUBSUB_SSE:
+    /* SSE */
+    http_sse_close(ws);
+    break;
+  case IODINE_PUBSUB_GLOBAL:
+  /* fallthrough */
+  default:
+    return Qfalse;
+    break;
+  }
   return self;
 }
 
@@ -139,52 +82,71 @@ static VALUE iodine_ws_close(VALUE self) {
  * Returns `true` on success or `false if the websocket was closed or an error
  * occurred.
  *
- * `write` will return immediately UNLESS resources are insufficient. If the
- * global `write` buffer is full, `write` will block until a buffer "packet"
- * becomes available and can be assigned to the socket. */
+ * `write` will return immediately, adding the data to the outgoing queue.
+ *
+ * If the connection is closed, `write` will raise an exception.
+ */
 static VALUE iodine_ws_write(VALUE self, VALUE data) {
   Check_Type(data, T_STRING);
-  ws_s *ws = get_ws(self);
-  // if ((void *)ws == (void *)0x04 || (void *)data == (void *)0x04 ||
-  //     RSTRING_PTR(data) == (void *)0x04)
-  //   fprintf(stderr, "iodine_ws_write: self = %p ; data = %p\n"
-  //                   "\t\tString ptr: %p, String length: %lu\n",
-  //           (void *)ws, (void *)data, RSTRING_PTR(data), RSTRING_LEN(data));
-  if (!ws || ((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
+  void *ws = get_ws(self);
+  iodine_pubsub_type_e c_type = (iodine_pubsub_type_e)iodine_get_cdata(self);
+  if (!ws || !c_type) {
+    rb_raise(rb_eIOError, "Connection is closed");
     return Qfalse;
-  websocket_write(ws, RSTRING_PTR(data), RSTRING_LEN(data),
-                  rb_enc_get(data) == IodineUTF8Encoding);
-  return Qtrue;
-}
-
-/** Returns the number of active websocket connections (including connections
- * that are in the process of closing down). */
-static VALUE iodine_ws_count(VALUE self) {
-  return LONG2FIX(websocket_count());
-  (void)self;
+  }
+  switch (c_type) {
+  case IODINE_PUBSUB_WEBSOCKET:
+    /* WebSockets*/
+    if (((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
+      goto error;
+    websocket_write(ws, RSTRING_PTR(data), RSTRING_LEN(data),
+                    rb_enc_get(data) == IodineUTF8Encoding);
+    return Qtrue;
+    break;
+  case IODINE_PUBSUB_SSE:
+    /* SSE */
+    http_sse_write(
+        ws, .data = {.data = RSTRING_PTR(data), .len = RSTRING_LEN(data)});
+    return Qtrue;
+    break;
+  case IODINE_PUBSUB_GLOBAL:
+  /* fallthrough */
+  default:
+  error:
+    rb_raise(rb_eIOError, "Connection is closed");
+    return Qfalse;
+  }
+  return Qfalse;
 }
 
 /**
-Returns a weak indication as to the state of the socket's buffer. If the server
-has data in the buffer that wasn't written to the socket, `has_pending?` will
-return `true`, otherwise `false` will be returned.
+Returns the number of pending writes or -1 if the connection is closed
 */
 static VALUE iodine_ws_has_pending(VALUE self) {
   intptr_t uuid = get_uuid(self);
-  return sock_has_pending(uuid) ? Qtrue : Qfalse;
+  if (!uuid || sock_isclosed(uuid))
+    return INT2NUM(-1);
+  return SIZET2NUM(sock_pending(uuid));
 }
 
 /**
-Returns a connection's UUID which is valid for *this process* (not a machine
-or internet unique value).
-
-This can be used together with a true process wide UUID to uniquely identify a
-connection across the internet.
+Returns true is the connection is open, false if it isn't.
 */
-static VALUE iodine_ws_uuid(VALUE self) {
+static VALUE iodine_ws_is_open(VALUE self) {
   intptr_t uuid = get_uuid(self);
-  return LONG2FIX(uuid);
-}
+  if (uuid && sock_isvalid(uuid))
+    return Qtrue;
+  return Qfalse;
+}
+
+/** Returns a local (per process) unique identifier for the conection. */
+// static VALUE iodine_ws_uuid(VALUE self) {
+//   intptr_t uuid = get_uuid(self);
+//   return ULL2NUM(uuid);
+//   if (uuid && sock_isvalid(uuid))
+//     return Qtrue;
+//   return Qfalse;
+// }
 
 /* *****************************************************************************
 Websocket defer
@@ -247,419 +209,120 @@ static VALUE iodine_defer(int argc, VALUE *argv, VALUE self) {
   return block;
 }
 
-/* *****************************************************************************
-Websocket Pub/Sub API
-***************************************************************************** */
-
-static void iodine_on_unsubscribe(void *u) {
-  if (u && (VALUE)u != Qnil && u != (VALUE)Qfalse)
-    Registry.remove((VALUE)u);
-}
-
-static void *on_pubsub_notificationinGVL(websocket_pubsub_notification_s *n) {
-  VALUE rbn[2];
-  rbn[0] = rb_str_new(n->channel.name, n->channel.len);
-  Registry.add(rbn[0]);
-  rbn[1] = rb_str_new(n->msg.data, n->msg.len);
-  Registry.add(rbn[1]);
-  RubyCaller.call2((VALUE)n->udata, iodine_call_proc_id, 2, rbn);
-  Registry.remove(rbn[0]);
-  Registry.remove(rbn[1]);
-  return NULL;
-}
-
-static void on_pubsub_notificationin(websocket_pubsub_notification_s n) {
-  RubyCaller.call_c((void *(*)(void *))on_pubsub_notificationinGVL, &n);
-}
-
-/**
-Subscribes the websocket to a channel belonging to a specific pub/sub service
-(using an {Iodine::PubSub::Engine} to connect Iodine to the service).
-
-The function accepts a single argument (a Hash) and an optional block.
-
-If no block is provided, the message is sent directly to the websocket client.
-
-Accepts a single Hash argument with the following possible options:
-
-:engine :: If provided, the engine to use for pub/sub. Otherwise the default
-engine is used.
-
-:channel :: Required (unless :pattern). The channel to subscribe to.
-
-:pattern :: An alternative to the required :channel, subscribes to a pattern.
-
-:force :: This can be set to either nil, :text or :binary and controls the way
-the message will be forwarded to the websocket client. This is only valid if no
-block was provided. Defaults to smart encoding based testing.
-
-
-*/
-static VALUE iodine_ws_subscribe(VALUE self, VALUE args) {
-  Check_Type(args, T_HASH);
-  ws_s *ws = get_ws(self);
-  if (!ws || ((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
-    return Qfalse;
-  uint8_t use_pattern = 0, force_text = 0, force_binary = 0;
-
-  VALUE rb_ch = rb_hash_aref(args, channel_var_id);
-  if (rb_ch == Qnil || rb_ch == Qfalse) {
-    use_pattern = 1;
-    rb_ch = rb_hash_aref(args, pattern_var_id);
-    if (rb_ch == Qnil || rb_ch == Qfalse)
-      rb_raise(rb_eArgError, "channel is required for pub/sub methods.");
-  }
-  if (TYPE(rb_ch) == T_SYMBOL)
-    rb_ch = rb_sym2str(rb_ch);
-  Check_Type(rb_ch, T_STRING);
-
-  VALUE tmp = rb_hash_aref(args, force_var_id);
-  if (tmp == text_var_id)
-    force_text = 1;
-  else if (tmp == binary_var_id)
-    force_binary = 1;
-
-  VALUE block = 0;
-  if (rb_block_given_p()) {
-    block = rb_block_proc();
-    Registry.add(block);
-  }
-
-  pubsub_engine_s *engine =
-      iodine_engine_ruby2facil(rb_hash_aref(args, engine_var_id));
-
-  uintptr_t subid = websocket_subscribe(
-      ws, .channel.name = RSTRING_PTR(rb_ch), .channel.len = RSTRING_LEN(rb_ch),
-      .engine = engine, .use_pattern = use_pattern, .force_text = force_text,
-      .force_binary = force_binary,
-      .on_message = (block ? on_pubsub_notificationin : NULL),
-      .on_unsubscribe = (block ? iodine_on_unsubscribe : NULL),
-      .udata = (void *)block);
-  if (!subid)
-    return Qnil;
-  return ULL2NUM(subid);
-}
 /**
-Searches for the subscription ID for the describes subscription.
-
-Takes the same arguments as {subscribe}, a single Hash argument with the
-following possible options:
-
-:engine :: If provided, the engine to use for pub/sub. Otherwise the default
-engine is used.
+Schedules a block of code to run for the specified websocket at a later time,
+(**if** the connection is open). The block will run within the connection's
+lock, offering a fast concurrency synchronizing tool.
 
-:channel :: The subscription's channel.
+The block of code will receive the websocket's callback object. i.e.
 
-:pattern :: An alternative to the required :channel, subscribes to a pattern.
+    Iodine::Websocket.defer(uuid) {|ws| ws.write "I'm doing this" }
 
-:force :: This can be set to either nil, :text or :binary and controls the way
-the message will be forwarded to the websocket client. This is only valid if no
-block was provided. Defaults to smart encoding based testing.
+On success returns the block, otherwise (connection invalid) returns `false`.
 
+A sucessful event registration doesn't guaranty that the block will be called
+(the connection might close between the event registration and the execution).
 */
-static VALUE iodine_ws_is_subscribed(VALUE self, VALUE args) {
-  Check_Type(args, T_HASH);
-  ws_s *ws = get_ws(self);
-  if (!ws || ((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
+static VALUE iodine_class_defer(VALUE self, VALUE ws_uuid) {
+  (void)(self);
+  intptr_t fd = FIX2LONG(ws_uuid);
+  if (!sock_isvalid(fd))
     return Qfalse;
-  uint8_t use_pattern = 0, force_text = 0, force_binary = 0;
-
-  VALUE rb_ch = rb_hash_aref(args, channel_var_id);
-  if (rb_ch == Qnil || rb_ch == Qfalse) {
-    use_pattern = 1;
-    rb_ch = rb_hash_aref(args, pattern_var_id);
-    if (rb_ch == Qnil || rb_ch == Qfalse)
-      rb_raise(rb_eArgError, "channel is required for pub/sub methods.");
-  }
-  if (TYPE(rb_ch) == T_SYMBOL)
-    rb_ch = rb_sym2str(rb_ch);
-  Check_Type(rb_ch, T_STRING);
-
-  VALUE tmp = rb_hash_aref(args, force_var_id);
-  if (tmp == text_var_id)
-    force_text = 1;
-  else if (tmp == binary_var_id)
-    force_binary = 1;
-
-  VALUE block = 0;
-  if (rb_block_given_p()) {
-    block = rb_block_proc();
-  }
-
-  pubsub_engine_s *engine =
-      iodine_engine_ruby2facil(rb_hash_aref(args, engine_var_id));
-
-  uintptr_t subid = websocket_find_sub(
-      ws, .channel.name = RSTRING_PTR(rb_ch), .channel.len = RSTRING_LEN(rb_ch),
-      .engine = engine, .use_pattern = use_pattern, .force_text = force_text,
-      .force_binary = force_binary,
-      .on_message = (block ? on_pubsub_notificationin : NULL),
-      .udata = (void *)block);
-  if (!subid)
-    return Qnil;
-  return LONG2NUM(subid);
-}
-
-/**
-Cancels the subscription matching `sub_id`.
-*/
-static VALUE iodine_ws_unsubscribe(VALUE self, VALUE sub_id) {
-  if (sub_id == Qnil || sub_id == Qfalse)
-    return Qnil;
-  ws_s *ws = get_ws(self);
-  if (!ws || ((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
+  // requires a block to be passed
+  rb_need_block();
+  VALUE block = rb_block_proc();
+  if (block == Qnil)
     return Qfalse;
-  Check_Type(sub_id, T_FIXNUM);
-  websocket_unsubscribe(ws, NUM2LONG(sub_id));
-  return Qnil;
-}
-
-/**
-Publishes a message to a channel.
-
-Accepts a single Hash argument with the following possible options:
-
-:engine :: If provided, the engine to use for pub/sub. Otherwise the default
-engine is used.
-
-:channel :: Required (unless :pattern). The channel to publish to.
-
-:pattern :: An alternative to the required :channel, publishes to a pattern.
-This is NOT supported by Redis and it's limited to the local process cluster.
-
-:message :: REQUIRED. The message to be published.
-:
-*/
-static VALUE iodine_ws_publish(VALUE self, VALUE args) {
-  Check_Type(args, T_HASH);
-  uint8_t use_pattern = 0;
-
-  VALUE rb_ch = rb_hash_aref(args, channel_var_id);
-  if (rb_ch == Qnil || rb_ch == Qfalse) {
-    use_pattern = 1;
-    rb_ch = rb_hash_aref(args, pattern_var_id);
-    if (rb_ch == Qnil || rb_ch == Qfalse)
-      rb_raise(rb_eArgError, "channel is required for pub/sub methods.");
-  }
-  if (TYPE(rb_ch) == T_SYMBOL)
-    rb_ch = rb_sym2str(rb_ch);
-  Check_Type(rb_ch, T_STRING);
+  Registry.add(block);
 
-  VALUE rb_msg = rb_hash_aref(args, message_var_id);
-  if (rb_msg == Qnil || rb_msg == Qfalse) {
-    rb_raise(rb_eArgError, "message is required for the :publish method.");
-  }
-  Check_Type(rb_msg, T_STRING);
-
-  pubsub_engine_s *engine =
-      iodine_engine_ruby2facil(rb_hash_aref(args, engine_var_id));
-
-  intptr_t subid =
-      pubsub_publish(.engine = engine, .channel.name = (RSTRING_PTR(rb_ch)),
-                     .channel.len = (RSTRING_LEN(rb_ch)),
-                     .msg.data = (RSTRING_PTR(rb_msg)),
-                     .msg.len = (RSTRING_LEN(rb_msg)),
-                     .use_pattern = use_pattern);
-  if (!subid)
-    return Qfalse;
-  return Qtrue;
-  (void)self;
+  facil_defer(.uuid = fd, .task = iodine_perform_defer, .arg = (void *)block,
+              .fallback = iodine_defer_fallback);
+  return block;
 }
 
 /* *****************************************************************************
-Websocket Multi-Write - Deprecated
+Websocket Pub/Sub API
 ***************************************************************************** */
 
-// static uint8_t iodine_ws_if_callback(ws_s *ws, void *block) {
-//   if (!ws)
-//     return 0;
-//   VALUE handler = get_handler(ws);
-//   uint8_t ret = 0;
-//   if (handler)
-//     ret = RubyCaller.call2((VALUE)block, iodine_call_proc_id, 1, &handler);
-//   return ret && ret != Qnil && ret != Qfalse;
-// }
-//
-// static void iodine_ws_write_each_complete(ws_s *ws, void *block) {
-//   (void)ws;
-//   if ((VALUE)block != Qnil)
-//     Registry.remove((VALUE)block);
-// }
-
+// clang-format off
 /**
- * Writes data to all the Websocket connections sharing the same process
- * (worker) except `self`.
- *
- * If a block is given, it will be passed each Websocket connection in turn
- * (much like `each`) and send the data only if the block returns a "truthy"
- * value (i.e. NOT `false` or `nil`).
- *
- * See both {#write} and {#each} for more details.
- */
-// static VALUE iodine_ws_multiwrite(VALUE self, VALUE data) {
-//   Check_Type(data, T_STRING);
-//   ws_s *ws = get_ws(self);
-//   // if ((void *)ws == (void *)0x04 || (void *)data == (void *)0x04 ||
-//   //     RSTRING_PTR(data) == (void *)0x04)
-//   //   fprintf(stderr, "iodine_ws_write: self = %p ; data = %p\n"
-//   //                   "\t\tString ptr: %p, String length: %lu\n",
-//   //           (void *)ws, (void *)data, RSTRING_PTR(data),
-//   RSTRING_LEN(data)); if (!ws || ((protocol_s *)ws)->service !=
-//   WEBSOCKET_ID_STR)
-//     ws = NULL;
-//
-//   VALUE block = Qnil;
-//   if (rb_block_given_p())
-//     block = rb_block_proc();
-//   if (block != Qnil)
-//     Registry.add(block);
-//   websocket_write_each(.origin = ws, .data = RSTRING_PTR(data),
-//                        .length = RSTRING_LEN(data),
-//                        .is_text = (rb_enc_get(data) == IodineUTF8Encoding),
-//                        .on_finished = iodine_ws_write_each_complete,
-//                        .filter =
-//                            ((block == Qnil) ? NULL : iodine_ws_if_callback),
-//                        .arg = (void *)block);
-//   return Qtrue;
-// }
+Subscribes the connection to a Pub/Sub channel.
 
-/* *****************************************************************************
-Websocket task performance
-*/
+The method accepts 1-2 arguments and an optional block. These are all valid ways
+to call the method:
 
-static void iodine_ws_perform_each_task(intptr_t fd, protocol_s *protocol,
-                                        void *data) {
-  (void)(fd);
-  VALUE handler = get_handler(protocol);
-  if (handler)
-    RubyCaller.call2((VALUE)data, iodine_call_proc_id, 1, &handler);
-}
-static void iodine_ws_finish_each_task(intptr_t fd, void *data) {
-  (void)(fd);
-  Registry.remove((VALUE)data);
-}
+      subscribe("my_stream") {|from, msg| p msg }
+      subscribe("my_stream", match: :redis) {|from, msg| p msg }
+      subscribe(to: "my_stream")  {|from, msg| p msg }
+      subscribe to: "my_stream", match: :redis, handler: MyProc
 
-inline static void iodine_ws_run_each(intptr_t origin, VALUE block) {
-  facil_each(.origin = origin, .service = WEBSOCKET_ID_STR,
-             .task = iodine_ws_perform_each_task, .arg = (void *)block,
-             .on_complete = iodine_ws_finish_each_task);
-}
+The first argument must be either a String or a Hash.
 
-/** Performs a block of code for each websocket connection. The function returns
-the block of code.
+The second, optional, argument must be a Hash (if given).
 
-The block of code should accept a single variable which is the websocket
-connection.
+The options Hash supports the following possible keys (other keys are ignored,
+all keys are Symbols):
 
-i.e.:
+:match :: The channel / subject name matching type to be used. Valid value is: `:redis`. Future versions hope to support `:nats` and `:rabbit` patern matching as well.
 
-      def on_message data
-        msg = data.dup; # data will be overwritten once the function exists.
-        each {|ws| ws.write msg}
-      end
+:to :: The channel / subject to subscribe to.
 
+:as :: valid for WebSocket connections only. can be either `:text` or `:binary`. `:text` is the default transport for pub/sub events.
 
-The block of code will be executed asynchronously, to avoid having two blocks
-of code running at the same time and minimizing race conditions when using
-multilple threads.
- */
-static VALUE iodine_ws_each(VALUE self) {
-  // requires a block to be passed
-  rb_need_block();
-  VALUE block = rb_block_proc();
-  if (block == Qnil)
-    return Qnil;
-  Registry.add(block);
-  intptr_t fd = get_uuid(self);
-  iodine_ws_run_each(fd, block);
-  return block;
-}
+Returns an {Iodine::PubSub::Subscription} object that answers to:
 
-/**
-Runs the required block for each websocket.
+#.close :: closes the connection.
 
-Tasks will be performed asynchronously, within each connection's lock, so no
-connection will have more then one task being performed at the same time
-(similar to {#defer}).
+#.to_s :: returns the subscription's target (stream / channel / subject).
 
-Also, unlike {Iodine.run}, the block will **not** be called unless the
-websocket is still open at the time it's execution begins.
+#.==(str) :: returns true if the string is an exact match for the target (even if the target itself is a pattern).
 
-Always returns `self`.
 */
-static VALUE iodine_ws_class_each(VALUE self) {
-  // requires a block to be passed
-  rb_need_block();
-  VALUE block = rb_block_proc();
-  if (block == Qnil)
-    return Qfalse;
-  Registry.add(block);
-  iodine_ws_run_each(-1, block);
-  return self;
+static VALUE iodine_ws_subscribe(int argc, VALUE *argv, VALUE self) {
+  // clang-format on
+  ws_s *owner = get_ws(self);
+  return iodine_subscribe(argc, argv, owner,
+                          (iodine_pubsub_type_e)iodine_get_cdata(self));
 }
 
-/**
-Schedules a block of code to run for the specified websocket at a later time,
-(**if** the connection is open). The block will run within the connection's
-lock, offering a fast concurrency synchronizing tool.
-
-The block of code will receive the websocket's callback object. i.e.
-
-    Iodine::Websocket.defer(uuid) {|ws| ws.write "I'm doing this" }
-
-On success returns the block, otherwise (connection invalid) returns `false`.
-
-A sucessful event registration doesn't guaranty that the block will be called
-(the connection might close between the event registration and the execution).
-*/
-static VALUE iodine_class_defer(VALUE self, VALUE ws_uuid) {
-  (void)(self);
-  intptr_t fd = FIX2LONG(ws_uuid);
-  if (!sock_isvalid(fd))
-    return Qfalse;
-  // requires a block to be passed
-  rb_need_block();
-  VALUE block = rb_block_proc();
-  if (block == Qnil)
-    return Qfalse;
-  Registry.add(block);
-
-  facil_defer(.uuid = fd, .task = iodine_perform_defer, .arg = (void *)block,
-              .fallback = iodine_defer_fallback);
-  return block;
-}
+/* *****************************************************************************
+WebSocket Callbacks
+***************************************************************************** */
 
-//////////////////////////////////////
-// Protocol functions
-void ws_on_open(ws_s *ws) {
+static void ws_on_open(ws_s *ws) {
   VALUE handler = get_handler(ws);
   if (!handler)
     return;
+  set_uuid(handler, websocket_uuid(ws));
   set_ws(handler, ws);
+  iodine_set_cdata(handler, (void *)IODINE_PUBSUB_WEBSOCKET);
   RubyCaller.call(handler, iodine_on_open_func_id);
 }
-void ws_on_close(ws_s *ws) {
-  VALUE handler = get_handler(ws);
+static void ws_on_close(intptr_t uuid, void *handler_) {
+  VALUE handler = (VALUE)handler_;
   if (!handler) {
     fprintf(stderr,
             "ERROR: (iodine websockets) Closing a handlerless websocket?!\n");
     return;
   }
+  set_ws(handler, NULL);
+  set_uuid(handler, 0);
+  iodine_set_cdata(handler, (void *)IODINE_PUBSUB_GLOBAL);
   RubyCaller.call(handler, iodine_on_close_func_id);
-  set_ws(handler, Qnil);
   Registry.remove(handler);
+  (void)uuid;
 }
-void ws_on_shutdown(ws_s *ws) {
+static void ws_on_shutdown(ws_s *ws) {
   VALUE handler = get_handler(ws);
   if (!handler)
     return;
   RubyCaller.call(handler, iodine_on_shutdown_func_id);
 }
-void ws_on_ready(ws_s *ws) {
+static void ws_on_ready(ws_s *ws) {
   VALUE handler = get_handler(ws);
   if (!handler)
     return;
-  RubyCaller.call(handler, iodine_on_ready_func_id);
+  RubyCaller.call(handler, iodine_on_drained_func_id);
 }
 
 struct ws_on_data_args_s {
@@ -668,7 +331,7 @@ struct ws_on_data_args_s {
   size_t length;
   uint8_t is_text;
 };
-void *ws_on_data_inGIL(void *args_) {
+static void *ws_on_data_inGIL(void *args_) {
   struct ws_on_data_args_s *a = args_;
   VALUE handler = get_handler(a->ws);
   if (!handler) {
@@ -683,7 +346,7 @@ void *ws_on_data_inGIL(void *args_) {
   rb_funcallv(handler, iodine_on_message_func_id, 1, &buffer);
   return NULL;
 }
-void ws_on_data(ws_s *ws, char *data, size_t length, uint8_t is_text) {
+static void ws_on_data(ws_s *ws, char *data, size_t length, uint8_t is_text) {
   struct ws_on_data_args_s a = {
       .ws = ws, .data = data, .length = length, .is_text = is_text};
   RubyCaller.call_c(ws_on_data_inGIL, &a);
@@ -699,45 +362,141 @@ static VALUE empty_func(VALUE self) {
   return Qnil;
 }
 
+/**  Please implement your own callback for this event. */
+static VALUE empty_func_drained(VALUE self) {
+  RubyCaller.call(self, iodine_on_ready_id);
+  (void)(self);
+  return Qnil;
+}
+
+/** DEPRECATED! Please override {on_drained} instead. */
+static VALUE empty_func_on_ready(VALUE self) {
+  (void)(self);
+  return Qnil;
+}
+
+/* *****************************************************************************
+SSE Callbacks
+***************************************************************************** */
+
+/**
+ * The (optional) on_open callback will be called once the EventSource
+ * connection is established.
+ */
+static void iodine_sse_on_open(http_sse_s *sse) {
+  VALUE handler = (VALUE)sse->udata;
+  if (!handler)
+    return;
+  set_uuid(handler, http_sse2uuid(sse));
+  set_ws(handler, sse);
+  iodine_set_cdata(handler, (void *)IODINE_PUBSUB_SSE);
+  RubyCaller.call(handler, iodine_on_open_func_id);
+}
+
+/**
+ * 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.
+ */
+static void iodine_sse_on_ready(http_sse_s *sse) {
+  VALUE handler = (VALUE)sse->udata;
+  if (!handler)
+    return;
+  RubyCaller.call(handler, iodine_on_drained_func_id);
+}
+
+/**
+ * The (optional) on_shutdown callback will be called if a connection is still
+ * open while the server is shutting down (called before `on_close`).
+ */
+static void iodine_sse_on_shutdown(http_sse_s *sse) {
+  VALUE handler = (VALUE)sse->udata;
+  if (!handler)
+    return;
+  RubyCaller.call(handler, iodine_on_shutdown_func_id);
+}
+/**
+ * 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.
+ */
+static void iodine_sse_on_close(http_sse_s *sse) {
+  VALUE handler = (VALUE)sse->udata;
+  if (!handler) {
+    fprintf(stderr,
+            "ERROR: (iodine websockets) Closing a handlerless websocket?!\n");
+    return;
+  }
+  set_ws(handler, NULL);
+  set_uuid(handler, 0);
+  iodine_set_cdata(handler, (void *)IODINE_PUBSUB_GLOBAL);
+  RubyCaller.call(handler, iodine_on_close_func_id);
+  Registry.remove(handler);
+}
+
 /* *****************************************************************************
 Upgrading
 ***************************************************************************** */
 
-void iodine_websocket_upgrade(http_request_s *request,
-                              http_response_s *response, VALUE handler,
-                              size_t max_msg, uint8_t ping) {
+static VALUE iodine_prep_ws_handler(VALUE handler) {
   // make sure we have a valid handler, with the Websocket Protocol mixin.
   if (handler == Qnil || handler == Qfalse || TYPE(handler) == T_FIXNUM ||
       TYPE(handler) == T_STRING || TYPE(handler) == T_SYMBOL)
-    goto failed;
+    return Qnil;
   if (TYPE(handler) == T_CLASS || TYPE(handler) == T_MODULE) {
     // include the Protocol module
     rb_include_module(handler, IodineWebsocket);
     rb_extend_object(handler, IodineWebsocket);
     handler = RubyCaller.call(handler, iodine_new_func_id);
     if (handler == Qnil || handler == Qfalse)
-      goto failed;
+      return Qnil;
+    Registry.add(handler);
     // check that we created a handler
   } else {
+    Registry.add(handler);
     // include the Protocol module in the object's class
     VALUE p_class = rb_obj_class(handler);
     rb_include_module(p_class, IodineWebsocket);
     rb_extend_object(p_class, IodineWebsocket);
   }
+  return handler;
+}
+
+void iodine_upgrade_websocket(http_s *h, VALUE handler) {
+  // add the handler to the registry
+  handler = iodine_prep_ws_handler(handler);
+  if (handler == Qnil)
+    goto failed;
+  // send upgrade response and set new protocol
+  http_upgrade2ws(.http = h, .udata = (void *)handler, .on_close = ws_on_close,
+                  .on_open = ws_on_open, .on_shutdown = ws_on_shutdown,
+                  .on_ready = ws_on_ready, .on_message = ws_on_data);
+  return;
+failed:
+  http_send_error(h, 400);
+  return;
+}
+
+void iodine_upgrade_sse(http_s *h, VALUE handler) {
   // add the handler to the registry
-  Registry.add(handler);
-  // set the UUID for the connection
-  set_uuid(handler, request);
+  handler = iodine_prep_ws_handler(handler);
+  if (handler == Qnil)
+    goto failed;
   // send upgrade response and set new protocol
-  websocket_upgrade(.request = request, .response = response,
-                    .udata = (void *)handler, .on_close = ws_on_close,
-                    .on_open = ws_on_open, .on_shutdown = ws_on_shutdown,
-                    .on_ready = ws_on_ready, .on_message = ws_on_data,
-                    .max_msg_size = max_msg, .timeout = ping);
+  http_upgrade2sse(h, .udata = (void *)handler, .on_open = iodine_sse_on_open,
+                   .on_ready = iodine_sse_on_ready,
+                   .on_shutdown = iodine_sse_on_shutdown,
+                   .on_close = iodine_sse_on_close);
   return;
 failed:
-  response->status = 400;
-  http_response_finish(response);
+  http_send_error(h, 400);
   return;
 }
 
@@ -749,14 +508,7 @@ void Iodine_init_websocket(void) {
   // get IDs and data that's used often
   ws_var_id = rb_intern("iodine_ws_ptr"); // when upgrading
   dup_func_id = rb_intern("dup");         // when upgrading
-
-  force_var_id = ID2SYM(rb_intern("fource"));
-  channel_var_id = ID2SYM(rb_intern("channel"));
-  pattern_var_id = ID2SYM(rb_intern("pattern"));
-  message_var_id = ID2SYM(rb_intern("message"));
-  engine_var_id = ID2SYM(rb_intern("engine"));
-  text_var_id = ID2SYM(rb_intern("text"));
-  binary_var_id = ID2SYM(rb_intern("binary"));
+  iodine_on_ready_id = rb_intern2("on_ready", 8);
 
   // the Ruby websockets protocol class.
   IodineWebsocket = rb_define_module_under(Iodine, "Websocket");
@@ -764,26 +516,32 @@ void Iodine_init_websocket(void) {
     fprintf(stderr, "WTF?!\n"), exit(-1);
   // // callbacks and handlers
   rb_define_method(IodineWebsocket, "on_open", empty_func, 0);
+
   // rb_define_method(IodineWebsocket, "on_message", empty_func_message, 1);
+
   rb_define_method(IodineWebsocket, "on_shutdown", empty_func, 0);
   rb_define_method(IodineWebsocket, "on_close", empty_func, 0);
-  rb_define_method(IodineWebsocket, "on_ready", empty_func, 0);
+  rb_define_method(IodineWebsocket, "on_drained", empty_func_drained, 0);
   rb_define_method(IodineWebsocket, "write", iodine_ws_write, 1);
   rb_define_method(IodineWebsocket, "close", iodine_ws_close, 0);
 
-  rb_define_method(IodineWebsocket, "conn_id", iodine_ws_uuid, 0);
-  rb_define_method(IodineWebsocket, "has_pending?", iodine_ws_has_pending, 0);
+  /// Deprectaed!
+  rb_define_method(IodineWebsocket, "on_ready", empty_func_on_ready, 0);
+
+  // rb_define_method(IodineWebsocket, "_cid", iodine_ws_uuid, 0);
+  // rb_define_method(IodineWebsocket, "_sock", iodine_ws_uuid, 0);
+
+  rb_define_method(IodineWebsocket, "pending", iodine_ws_has_pending, 0);
+  rb_define_method(IodineWebsocket, "open?", iodine_ws_is_open, 0);
   rb_define_method(IodineWebsocket, "defer", iodine_defer, -1);
+
   // rb_define_method(IodineWebsocket, "each", iodine_ws_each, 0);
 
-  rb_define_method(IodineWebsocket, "subscribe", iodine_ws_subscribe, 1);
-  rb_define_method(IodineWebsocket, "unsubscribe", iodine_ws_unsubscribe, 1);
-  rb_define_method(IodineWebsocket, "subscribed?", iodine_ws_is_subscribed, 1);
-  rb_define_method(IodineWebsocket, "publish", iodine_ws_publish, 1);
+  rb_define_method(IodineWebsocket, "subscribe", iodine_ws_subscribe, -1);
+  rb_define_method(IodineWebsocket, "publish", iodine_publish, -1);
 
-  rb_define_singleton_method(IodineWebsocket, "each", iodine_ws_class_each, 0);
-  rb_define_singleton_method(IodineWebsocket, "defer", iodine_class_defer, 1);
-  rb_define_singleton_method(IodineWebsocket, "count", iodine_ws_count, 0);
-  // rb_define_singleton_method(IodineWebsocket, "publish", iodine_ws_publish,
+  // rb_define_singleton_method(IodineWebsocket, "defer", iodine_class_defer,
   // 1);
+
+  rb_define_singleton_method(IodineWebsocket, "publish", iodine_publish, -1);
 }