iodine 0.4.19 → 0.5.0

data/ext/iodine/iodine_pubsub.c

@@ -8,20 +8,31 @@ Feel free to copy, use and enjoy according to the license provided.
 #include "rb-call.h"
 
 #include "pubsub.h"
+#include "rb-fiobj2rb.h"
 #include "redis_engine.h"
+#include "websockets.h"
 
 VALUE IodineEngine;
+ID iodine_engine_pubid;
 
 static VALUE IodinePubSub;
+static VALUE IodinePubSubSubscription;
 static ID engine_varid;
 static ID engine_subid;
-static ID engine_pubid;
 static ID engine_unsubid;
 static ID default_pubsubid;
 
-static VALUE channel_var_id;
-static VALUE pattern_var_id;
-static VALUE message_var_id;
+static ID to_str_shadow_id;
+
+static VALUE as_sym_id;
+static VALUE binary_sym_id;
+static VALUE handler_sym_id;
+static VALUE match_sym_id;
+static VALUE message_sym_id;
+static VALUE redis_sym_id;
+static VALUE text_sym_id;
+static VALUE to_sym_id;
+static VALUE channel_sym_id;
 
 /* *****************************************************************************
 Mock Functions
@@ -52,66 +63,188 @@ call this function from your own code / application.
 
 The function should return `true` on success and `nil` or `false` on failure.
 */
-static VALUE engine_pub_placeholder(VALUE self, VALUE channel, VALUE msg,
-                                    VALUE use_pattern) {
+static VALUE engine_pub_placeholder(VALUE self, VALUE channel, VALUE msg) {
+  { /* test for built-in C engines */
+    iodine_engine_s *engine;
+    Data_Get_Struct(self, iodine_engine_s, engine);
+    if (engine->p != &engine->engine) {
+      FIOBJ ch = fiobj_str_new(RSTRING_PTR(channel), RSTRING_LEN(channel));
+      FIOBJ m = fiobj_str_new(RSTRING_PTR(msg), RSTRING_LEN(msg));
+      pubsub_publish(.engine = engine->p, .channel = ch, .message = m);
+      fiobj_free(ch);
+      fiobj_free(msg);
+      return Qtrue;
+    }
+  }
   return Qnil;
   (void)self;
   (void)msg;
   (void)channel;
-  (void)use_pattern;
 }
 
 /* *****************************************************************************
-Ruby API
+Engine registration and resetting
 ***************************************************************************** */
 
-/** @!visibility public
-Called by the engine to distribute a `message` to a `channel`. Supports
-`pattern` channel matching as well.
-
-i.e.
-
-      # Regular message distribution
-      self.distribute "My Channel", "Hello!"
-      # Pattern message distribution
-      self.distribute "My Ch*", "Hello!", true
+/**
+This method adds the engine to the pub/sub system, allowing it to recieve system
+wide notifications.
+*/
+static VALUE iodine_engine_register2(VALUE self, VALUE engine) {
+  iodine_engine_s *e;
+  Registry.add(engine);
+  Data_Get_Struct(engine, iodine_engine_s, e);
+  if (e->p) {
+    e->handler = engine;
+    pubsub_engine_register(e->p);
+    return Qtrue;
+  }
+  return Qfalse;
+  (void)self;
+  (void)engine;
+}
 
-Returns `self`, always.
+/**
+This method adds the engine to the pub/sub system, allowing it to recieve system
+wide notifications.
+*/
+static VALUE iodine_engine_register(VALUE self) {
+  return iodine_engine_register2(self, self);
+}
 
-This is the ONLY method inherited from {Iodine::PubSub::Engine} that
-should be called from within your code (by the engine itself).
+/**
+This method removes the engine from the pub/sub system.
+*/
+static VALUE iodine_engine_deregister2(VALUE self, VALUE engine) {
+  iodine_engine_s *e;
+  Data_Get_Struct(engine, iodine_engine_s, e);
+  if (e->p) {
+    pubsub_engine_deregister(e->p);
+    Registry.remove(engine);
+    return Qtrue;
+  }
+  Registry.remove(engine);
+  return Qfalse;
+  (void)self;
+  (void)engine;
+}
 
-**Notice:**
+/**
+This method removes the engine from the pub/sub system.
+*/
+static VALUE iodine_engine_deregister(VALUE self) {
+  return iodine_engine_deregister2(self, self);
+}
 
-Message distribution requires both the {Iodine::PubSub::Engine} instance and the
-channel to be the same.
+/**
+This method resets the engine, (re)sending all the current subscription data as
+if the {register} method was just called.
+*/
+static VALUE iodine_engine_reset2(VALUE self, VALUE engine) {
+  iodine_engine_s *e;
+  Data_Get_Struct(engine, iodine_engine_s, e);
+  if (e->p) {
+    e->handler = engine;
+    pubsub_engine_resubscribe(e->p);
+    return Qtrue;
+  }
+  return Qfalse;
+  (void)self;
+  (void)engine;
+}
 
-If a client subscribed to "channel 1" on engine A, they will NOT receive
-messages from "channel 1" on engine B.
+/**
+This method resets the engine, (re)sending all the current subscription data as
+if the {register} method was just called.
 */
-static VALUE engine_distribute(int argc, VALUE *argv, VALUE self) {
-  if (argc < 2 || argc > 3)
-    rb_raise(rb_eArgError,
-             "wrong number of arguments (given %d, expected 2..3).", argc);
-  VALUE channel = argv[0];
-  VALUE msg = argv[1];
-  VALUE pattern = argc >= 3 ? argv[2] : Qnil;
-  Check_Type(channel, T_STRING);
-  Check_Type(msg, T_STRING);
+static VALUE iodine_engine_reset(VALUE self) {
+  return iodine_engine_reset2(self, self);
+}
 
-  iodine_engine_s *engine;
-  Data_Get_Struct(self, iodine_engine_s, engine);
+/* *****************************************************************************
+Ruby Subscription Object
+***************************************************************************** */
+typedef struct {
+  uintptr_t subscription;
+  intptr_t uuid;
+  void *owner;
+  iodine_pubsub_type_e type;
+} iodine_subscription_s;
+
+static inline iodine_subscription_s subscription_data(VALUE self) {
+  iodine_subscription_s data = {.uuid = iodine_get_fd(self)};
+  if (data.uuid && !sock_isvalid(data.uuid)) {
+    iodine_set_fd(self, -1);
+    data.uuid = -1;
+    return data;
+  }
+
+  data.subscription =
+      ((uintptr_t)NUM2LL(rb_ivar_get(self, iodine_timeout_var_id)));
+  data.owner = iodine_get_cdata(self);
+  if (!data.owner) {
+    data.type = IODINE_PUBSUB_GLOBAL;
+  } else if ((uintptr_t)data.owner & 1) {
+    data.owner = (void *)((uintptr_t)data.owner & (~(uintptr_t)1));
+    data.type = IODINE_PUBSUB_SSE;
+  } else {
+    data.type = IODINE_PUBSUB_WEBSOCKET;
+  }
+  return data;
+}
 
-  pubsub_engine_distribute(.engine = engine->p,
-                           .channel.name = RSTRING_PTR(channel),
-                           .channel.len = RSTRING_LEN(channel),
-                           .msg.data = RSTRING_PTR(msg),
-                           .msg.len = RSTRING_LEN(msg),
-                           .use_pattern =
-                               (pattern != Qnil && pattern != Qfalse));
+static inline VALUE subscription_initialize(uintptr_t sub, intptr_t uuid,
+                                            void *owner,
+                                            iodine_pubsub_type_e type,
+                                            VALUE channel) {
+  VALUE self = RubyCaller.call(IodinePubSubSubscription, iodine_new_func_id);
+  if (type == IODINE_PUBSUB_SSE)
+    owner = (void *)((uintptr_t)owner | (uintptr_t)1);
+  iodine_set_cdata(self, owner);
+  iodine_set_fd(self, uuid);
+  rb_ivar_set(self, to_str_shadow_id, channel);
+  rb_ivar_set(self, iodine_timeout_var_id, ULL2NUM(sub));
   return self;
 }
 
+// static void set_subscription(VALUE self, pubsub_sub_pt sub) {
+//   iodine_set_cdata(self, sub);
+// }
+
+/** Closes (cancels) a subscription. */
+static VALUE close_subscription(VALUE self) {
+  iodine_subscription_s data = subscription_data(self);
+  if (!data.subscription)
+    return Qnil;
+  switch (data.type) {
+  case IODINE_PUBSUB_GLOBAL:
+    pubsub_unsubscribe((pubsub_sub_pt)data.subscription);
+    break;
+  case IODINE_PUBSUB_WEBSOCKET:
+    websocket_unsubscribe(data.owner, data.subscription);
+    break;
+  case IODINE_PUBSUB_SSE:
+    http_sse_unsubscribe(data.owner, data.subscription);
+    break;
+  }
+  rb_ivar_set(self, iodine_timeout_var_id, ULL2NUM(0));
+  return Qnil;
+}
+
+/** Test if the subscription's target is equal to String. */
+static VALUE subscription_eq_s(VALUE self, VALUE str) {
+  return rb_str_equal(rb_attr_get(self, to_str_shadow_id), str);
+}
+
+/** Returns the target stream / channel / pattern as a String object. */
+static VALUE subscription_to_s(VALUE self) {
+  return rb_attr_get(self, to_str_shadow_id);
+}
+
+/* *****************************************************************************
+Ruby API
+***************************************************************************** */
+
 pubsub_engine_s *iodine_engine_ruby2facil(VALUE ruby_engine) {
   if (ruby_engine == Qnil || ruby_engine == Qfalse)
     return NULL;
@@ -128,73 +261,77 @@ C => Ruby Bridge
 
 struct engine_gvl_args_s {
   const pubsub_engine_s *eng;
-  const char *ch;
-  size_t ch_len;
-  const char *msg;
-  size_t msg_len;
+  FIOBJ ch;
+  FIOBJ msg;
   uint8_t use_pattern;
 };
 
 static void *engine_subscribe_inGVL(void *a_) {
   struct engine_gvl_args_s *args = a_;
+  VALUE eng = ((iodine_engine_s *)args->eng)->handler;
+  if (!eng || eng == Qnil || eng == Qfalse)
+    return NULL;
   VALUE data[2];
-  data[0] = rb_str_new(args->ch, args->ch_len);
+  fio_cstr_s tmp = fiobj_obj2cstr(args->ch);
   data[1] = args->use_pattern ? Qtrue : Qnil;
-  VALUE eng = ((iodine_engine_s *)args->eng)->handler;
+  data[0] = rb_str_new(tmp.data, tmp.len);
   eng = RubyCaller.call2(eng, engine_subid, 2, data);
-  return ((eng == Qfalse || eng == Qnil) ? (void *)-1 : (void *)0);
+  return NULL;
 }
 
 /* Should return 0 on success and -1 on failure. */
-static int engine_subscribe(const pubsub_engine_s *eng, const char *ch,
-                            size_t ch_len, uint8_t use_pattern) {
+static void engine_subscribe(const pubsub_engine_s *eng, FIOBJ ch,
+                             uint8_t use_pattern) {
   struct engine_gvl_args_s args = {
-      .eng = eng, .ch = ch, .ch_len = ch_len, .use_pattern = use_pattern,
+      .eng = eng, .ch = ch, .use_pattern = use_pattern,
   };
-  return RubyCaller.call_c(engine_subscribe_inGVL, &args) ? 0 : -1;
+  RubyCaller.call_c(engine_subscribe_inGVL, &args);
 }
 
 static void *engine_unsubscribe_inGVL(void *a_) {
   struct engine_gvl_args_s *args = a_;
+  VALUE eng = ((iodine_engine_s *)args->eng)->handler;
+  if (!eng || eng == Qnil || eng == Qfalse)
+    return NULL;
   VALUE data[2];
-  data[0] = rb_str_new(args->ch, args->ch_len);
+  fio_cstr_s tmp = fiobj_obj2cstr(args->ch);
   data[1] = args->use_pattern ? Qtrue : Qnil;
-  VALUE eng = ((iodine_engine_s *)args->eng)->handler;
+  data[0] = rb_str_new(tmp.data, tmp.len);
   RubyCaller.call2(eng, engine_unsubid, 2, data);
   return NULL;
 }
 
 /* Return value is ignored - nothing should be returned. */
-static void engine_unsubscribe(const pubsub_engine_s *eng, const char *ch,
-                               size_t ch_len, uint8_t use_pattern) {
+static void engine_unsubscribe(const pubsub_engine_s *eng, FIOBJ ch,
+                               uint8_t use_pattern) {
   struct engine_gvl_args_s args = {
-      .eng = eng, .ch = ch, .ch_len = ch_len, .use_pattern = use_pattern,
+      .eng = eng, .ch = ch, .use_pattern = use_pattern,
   };
   RubyCaller.call_c(engine_unsubscribe_inGVL, &args);
 }
 
 static void *engine_publish_inGVL(void *a_) {
   struct engine_gvl_args_s *args = a_;
-  VALUE data[3];
-  data[0] = rb_str_new(args->ch, args->ch_len);
-  data[1] = rb_str_new(args->msg, args->msg_len);
-  data[2] = args->use_pattern ? Qtrue : Qnil;
   VALUE eng = ((iodine_engine_s *)args->eng)->handler;
-  eng = RubyCaller.call2(eng, engine_pubid, 3, data);
+  if (!eng || eng == Qnil || eng == Qfalse)
+    return NULL;
+  VALUE data[2];
+  fio_cstr_s tmp = fiobj_obj2cstr(args->ch);
+  data[0] = rb_str_new(tmp.data, tmp.len);
+  Registry.add(data[0]);
+  tmp = fiobj_obj2cstr(args->msg);
+  data[1] = rb_str_new(tmp.data, tmp.len);
+  Registry.add(data[1]);
+  eng = RubyCaller.call2(eng, iodine_engine_pubid, 2, data);
+  Registry.remove(data[0]);
+  Registry.remove(data[1]);
   return ((eng == Qfalse || eng == Qnil) ? (void *)-1 : 0);
 }
 
 /* Should return 0 on success and -1 on failure. */
-static int engine_publish(const pubsub_engine_s *eng, const char *ch,
-                          size_t ch_len, const char *msg, size_t msg_len,
-                          uint8_t use_pattern) {
+static int engine_publish(const pubsub_engine_s *eng, FIOBJ ch, FIOBJ msg) {
   struct engine_gvl_args_s args = {
-      .eng = eng,
-      .ch = ch,
-      .ch_len = ch_len,
-      .msg = msg,
-      .msg_len = msg_len,
-      .use_pattern = use_pattern,
+      .eng = eng, .ch = ch, .msg = msg,
   };
   return RubyCaller.call_c(engine_publish_inGVL, &args) ? 0 : -1;
 }
@@ -216,12 +353,12 @@ static void engine_free(void *eng_) {
   free(eng);
 }
 
-/* GMP::Integer.allocate */
+/* Iodine::PubSub::Engine.allocate */
 static VALUE engine_alloc_c(VALUE self) {
   iodine_engine_s *eng = malloc(sizeof(*eng));
   if (TYPE(self) == T_CLASS)
     *eng = (iodine_engine_s){
-        .handler = self,
+        .handler = (VALUE)0,
         .engine =
             {
                 .subscribe = engine_subscribe,
@@ -237,6 +374,9 @@ static VALUE engine_alloc_c(VALUE self) {
 static VALUE engine_initialize(VALUE self) {
   iodine_engine_s *engine;
   Data_Get_Struct(self, iodine_engine_s, engine);
+  if (TYPE(self) == T_CLASS) {
+    fprintf(stderr, "This sucks...\n");
+  }
   engine->handler = self;
   return self;
 }
@@ -246,56 +386,29 @@ Redis
 ***************************************************************************** */
 
 struct redis_callback_data {
-  resp_object_s *msg;
+  FIOBJ msg;
   VALUE block;
 };
 
-/*
-populate
-*/
-int populate_redis_callback_reply(resp_parser_pt p, resp_object_s *o,
-                                  void *rep) {
-  switch (o->type) {
-  case RESP_ARRAY:
-  case RESP_PUBSUB:
-    break;
-  case RESP_NULL:
-    rb_ary_push((VALUE)rep, Qnil);
-    break;
-  case RESP_NUMBER:
-    rb_ary_push((VALUE)rep, LONG2FIX(resp_obj2num(o)->number));
-    break;
-  case RESP_ERR:
-  case RESP_STRING:
-    rb_ary_push((VALUE)rep, rb_str_new((char *)resp_obj2str(o)->string,
-                                       resp_obj2str(o)->len));
-    break;
-  case RESP_OK:
-    rb_ary_push((VALUE)rep, rb_str_new("OK", 2));
-    break;
-  }
-  return 0;
-  (void)p;
-}
 /*
 Perform a Redis message callback in the GVL
 */
 static void *perform_redis_callback_inGVL(void *data) {
   struct redis_callback_data *a = data;
-  VALUE reply = rb_ary_new();
-  resp_obj_each(NULL, a->msg, populate_redis_callback_reply, (void *)reply);
+  VALUE reply = fiobj2rb_deep(a->msg, 1);
+  Registry.add(reply);
   rb_funcallv(a->block, iodine_call_proc_id, 1, &reply);
   Registry.remove(a->block);
+  Registry.remove(reply);
   return NULL;
 }
 
 /*
 Redis message callback
 */
-static void redis_callback(pubsub_engine_s *e, resp_object_s *msg,
-                           void *block) {
+static void redis_callback(pubsub_engine_s *e, FIOBJ reply, void *block) {
   struct redis_callback_data d = {
-      .msg = msg, .block = (VALUE)block,
+      .msg = reply, .block = (VALUE)block,
   };
   RubyCaller.call_c(perform_redis_callback_inGVL, &d);
   (void)e;
@@ -318,46 +431,40 @@ static VALUE redis_send(int argc, VALUE *argv, VALUE self) {
     rb_raise(rb_eArgError,
              "wrong number of arguments (given %d, expected at least 1).",
              argc);
-  resp_object_s *cmd = NULL;
   Check_Type(argv[0], T_STRING);
-
-  iodine_engine_s *e;
-  Data_Get_Struct(self, iodine_engine_s, e);
-  cmd = resp_arr2obj(argc, NULL);
-  for (int i = 0; i < argc; i++) {
-    switch (TYPE(argv[i])) {
-    case T_SYMBOL:
-      argv[i] = rb_sym2str(argv[i]);
-    /* Fallthrough */
-    case T_STRING:
-      resp_obj2arr(cmd)->array[i] =
-          resp_str2obj(RSTRING_PTR(argv[i]), RSTRING_LEN(argv[i]));
-      break;
-    case T_FIXNUM:
-      resp_obj2arr(cmd)->array[i] = resp_num2obj(FIX2LONG(argv[i]));
-      break;
-    default:
-      goto error;
-      break;
+  FIOBJ data = FIOBJ_INVALID;
+  FIOBJ cmd = FIOBJ_INVALID;
+  if (argc > 1) {
+    for (int i = 0; i < argc; ++i) {
+      if (TYPE(argv[i]) == T_SYMBOL)
+        argv[i] = rb_sym2str(argv[i]);
+      if (TYPE(argv[i]) != T_FIXNUM)
+        Check_Type(argv[i], T_STRING);
+    }
+    data = fiobj_ary_new();
+    for (int i = 0; i < argc; ++i) {
+      if (TYPE(argv[i]) == T_FIXNUM)
+        fiobj_ary_push(data, fiobj_num_new(FIX2LONG(argv[i])));
+      else
+        fiobj_ary_push(
+            data, fiobj_str_new(RSTRING_PTR(argv[i]), RSTRING_LEN(argv[i])));
     }
   }
+  cmd = fiobj_str_new(RSTRING_PTR(argv[0]), RSTRING_LEN(argv[0]));
+  iodine_engine_s *e;
+  Data_Get_Struct(self, iodine_engine_s, e);
 
   if (rb_block_given_p()) {
     VALUE block = rb_block_proc();
     Registry.add(block);
-    redis_engine_send(e->p, cmd, redis_callback, (void *)block);
+    redis_engine_send(e->p, cmd, data, redis_callback, (void *)block);
     return block;
   } else {
-    redis_engine_send(e->p, cmd, NULL, NULL);
+    redis_engine_send(e->p, cmd, data, NULL, NULL);
   }
+  fiobj_free(cmd);
+  fiobj_free(data);
   return Qtrue;
-error:
-  if (cmd)
-    resp_free_object(cmd);
-  rb_raise(rb_eArgError, "Arguments can only include Strings, Symbols and "
-                         "Integers - no arrays or hashes or other objects can "
-                         "be sent.");
-  return self;
 }
 
 /**
@@ -371,7 +478,7 @@ Accepts:
 
 address:: the Redis server's address. Required.
 port:: the Redis Server port. Default: 6379
-ping:: the PING interval. Default: 0 (~5 minutes).
+ping:: the PING interval up to 255 seconds. Default: 0 (~5 minutes).
 auth:: authentication password. Default: none.
 */
 static VALUE redis_engine_initialize(int argc, VALUE *argv, VALUE self) {
@@ -407,9 +514,9 @@ static VALUE redis_engine_initialize(int argc, VALUE *argv, VALUE self) {
                           .ping_interval = iping,
                           .auth = (auth == Qnil ? NULL : StringValueCStr(auth)),
                           .auth_len = (auth == Qnil ? 0 : RSTRING_LEN(auth)));
+  engine->dealloc = redis_engine_destroy;
   if (!engine->p)
     rb_raise(rb_eRuntimeError, "unknown error, can't initialize RedisEngine.");
-  engine->dealloc = redis_engine_destroy;
   return self;
 }
 
@@ -429,9 +536,17 @@ static VALUE ips_set_default(VALUE self, VALUE en) {
     rb_raise(rb_eArgError, "deafult engine must be an Iodine::PubSub::Engine.");
   if (!e->p)
     rb_raise(rb_eArgError, "This Iodine::PubSub::Engine is broken.");
-  rb_ivar_set(self, default_pubsubid, en);
+  rb_ivar_set(Iodine, default_pubsubid, en);
   PUBSUB_DEFAULT_ENGINE = e->p;
   return en;
+  (void)self;
+}
+
+/** Deprecated. Use {Iodine::PubSub.default_engine=}. */
+static VALUE ips_set_default_dep(VALUE self, VALUE en) {
+  fprintf(stderr, "WARNING: Iodine.default_pubsub is deprecated. Use "
+                  "Iodine::PubSub.default_engine.\n");
+  return ips_set_default(self, en);
 }
 
 /**
@@ -440,7 +555,17 @@ Returns the default Pub/Sub engine (if any).
 See {Iodine::PubSub} and {Iodine::PubSub::Engine} for more details.
 */
 static VALUE ips_get_default(VALUE self) {
-  return rb_ivar_get(self, default_pubsubid);
+  return rb_ivar_get(Iodine, default_pubsubid);
+  (void)self;
+}
+
+/**
+Deprecated. Use {Iodine::PubSub.default_engine}.
+*/
+static VALUE ips_get_default_dep(VALUE self) {
+  fprintf(stderr, "WARNING: Iodine.default_pubsub is deprecated. Use "
+                  "Iodine::PubSub.default_engine.\n");
+  return ips_get_default(self);
 }
 
 /* *****************************************************************************
@@ -455,9 +580,11 @@ static void iodine_on_unsubscribe(void *u1, void *u2) {
 
 static void *on_pubsub_notificationinGVL(pubsub_message_s *n) {
   VALUE rbn[2];
-  rbn[0] = rb_str_new(n->channel.name, n->channel.len);
+  fio_cstr_s tmp = fiobj_obj2cstr(n->channel);
+  rbn[0] = rb_str_new(tmp.data, tmp.len);
   Registry.add(rbn[0]);
-  rbn[1] = rb_str_new(n->msg.data, n->msg.len);
+  tmp = fiobj_obj2cstr(n->message);
+  rbn[1] = rb_str_new(tmp.data, tmp.len);
   Registry.add(rbn[1]);
   RubyCaller.call2((VALUE)n->udata1, iodine_call_proc_id, 2, rbn);
   Registry.remove(rbn[0]);
@@ -469,116 +596,256 @@ static void on_pubsub_notificationin(pubsub_message_s *n) {
   RubyCaller.call_c((void *(*)(void *))on_pubsub_notificationinGVL, n);
 }
 
-/**
-Subscribes the process 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 a required block.
+static void iodine_on_unsubscribe_ws(void *u) {
+  if (u && (VALUE)u != Qnil && u != (VALUE)Qfalse)
+    Registry.remove((VALUE)u);
+}
 
-Accepts a single Hash argument with the following possible options:
+static void *
+on_pubsub_notificationinGVL_ws(websocket_pubsub_notification_s *n) {
+  VALUE rbn[2];
+  fio_cstr_s tmp = fiobj_obj2cstr(n->channel);
+  rbn[0] = rb_str_new(tmp.data, tmp.len);
+  Registry.add(rbn[0]);
+  tmp = fiobj_obj2cstr(n->message);
+  rbn[1] = rb_str_new(tmp.data, tmp.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;
+}
 
-:engine :: If provided, the engine to use for pub/sub. Otherwise the default
-        :: engine is used.
+static void on_pubsub_notificationin_ws(websocket_pubsub_notification_s n) {
+  RubyCaller.call_c((void *(*)(void *))on_pubsub_notificationinGVL_ws, &n);
+}
 
-:channel :: Required (unless :pattern). The channel to subscribe to.
+static void on_pubsub_notificationin_sse(http_sse_s *sse, FIOBJ channel,
+                                         FIOBJ message, void *udata) {
+  websocket_pubsub_notification_s n = {
+      .channel = channel, .message = message, .udata = udata};
+  RubyCaller.call_c((void *(*)(void *))on_pubsub_notificationinGVL, &n);
+  (void)sse;
+}
 
-:pattern :: An alternative to the required :channel, subscribes to a pattern.
+/** Subscribes to a Pub/Sub channel - internal implementation */
+VALUE iodine_subscribe(int argc, VALUE *argv, void *owner,
+                       iodine_pubsub_type_e type) {
 
-*/
-static VALUE iodine_subscribe(VALUE self, VALUE args) {
-  Check_Type(args, T_HASH);
-  rb_need_block();
+  VALUE rb_ch = Qnil;
+  VALUE rb_opt = 0;
+  VALUE block = 0;
+  uint8_t use_pattern = 0, force_text = 1, force_binary = 0;
+  intptr_t uuid = 0;
 
-  uint8_t use_pattern = 0;
+  switch (argc) {
+  case 2:
+    rb_ch = argv[0];
+    rb_opt = argv[1];
+    break;
+  case 1:
+    /* single argument must be a Hash / channel name */
+    if (TYPE(argv[0]) == T_HASH) {
+      rb_opt = argv[0];
+      rb_ch = rb_hash_aref(argv[0], to_sym_id);
+      if (rb_ch == Qnil || rb_ch == Qfalse) {
+        /* temporary backport support */
+        rb_ch = rb_hash_aref(argv[0], channel_sym_id);
+        if (rb_ch) {
+          fprintf(stderr,
+                  "WARNING: use of :channel in subscribe is deprecated.\n");
+        }
+      }
+    } else {
+      rb_ch = argv[0];
+    }
+    break;
+  default:
+    rb_raise(rb_eArgError, "method accepts 1 or 2 arguments.");
+    return Qnil;
+  }
 
-  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, "a channel is required for pub/sub methods.");
+    rb_raise(rb_eArgError,
+             "a target (:to) subject / stream / channel is required.");
   }
+
   if (TYPE(rb_ch) == T_SYMBOL)
     rb_ch = rb_sym2str(rb_ch);
   Check_Type(rb_ch, T_STRING);
 
-  VALUE block = rb_block_proc();
-  Registry.add(block);
+  if (rb_opt) {
+    if (type == IODINE_PUBSUB_WEBSOCKET &&
+        rb_hash_aref(rb_opt, as_sym_id) == binary_sym_id) {
+      force_text = 0;
+      force_binary = 1;
+    }
+    if (rb_hash_aref(rb_opt, match_sym_id) == redis_sym_id) {
+      use_pattern = 1;
+    }
+    block = rb_hash_aref(rb_opt, handler_sym_id);
+    if (block != Qnil)
+      Registry.add(block);
+  }
+
+  if (block == Qnil) {
+    if (rb_block_given_p()) {
+      block = rb_block_proc();
+      Registry.add(block);
+    } else if (type == IODINE_PUBSUB_GLOBAL) {
+      rb_need_block();
+      return Qnil;
+    }
+  }
+  if (block == Qnil)
+    block = 0;
+
+  FIOBJ ch = fiobj_str_new(RSTRING_PTR(rb_ch), RSTRING_LEN(rb_ch));
+
+  uintptr_t sub = 0;
+  switch (type) {
+  case IODINE_PUBSUB_GLOBAL:
+    sub = (uintptr_t)pubsub_subscribe(.channel = ch, .use_pattern = use_pattern,
+                                      .on_message = on_pubsub_notificationin,
+                                      .on_unsubscribe = iodine_on_unsubscribe,
+                                      .udata1 = (void *)block);
+    break;
+  case IODINE_PUBSUB_WEBSOCKET:
+    uuid = websocket_uuid(owner);
+    sub = websocket_subscribe(
+        owner, .channel = ch, .use_pattern = use_pattern,
+        .force_text = force_text, .force_binary = force_binary,
+        .on_message = (block ? on_pubsub_notificationin_ws : NULL),
+        .on_unsubscribe = (block ? iodine_on_unsubscribe_ws : NULL),
+        .udata = (void *)block);
+    break;
+  case IODINE_PUBSUB_SSE:
+    uuid = http_sse2uuid(owner);
+    sub = http_sse_subscribe(
+        owner, .channel = ch, .use_pattern = use_pattern,
+        .on_message = (block ? on_pubsub_notificationin_sse : NULL),
+        .on_unsubscribe = (block ? iodine_on_unsubscribe_ws : NULL),
+        .udata = (void *)block);
 
-  pubsub_engine_s *engine =
-      iodine_engine_ruby2facil(rb_hash_aref(args, engine_varid));
+    break;
+  }
 
-  uintptr_t subid =
-      (uintptr_t)pubsub_subscribe(.channel.name = RSTRING_PTR(rb_ch),
-                                  .channel.len = RSTRING_LEN(rb_ch),
-                                  .engine = engine, .use_pattern = use_pattern,
-                                  .on_message = on_pubsub_notificationin,
-                                  .on_unsubscribe = iodine_on_unsubscribe,
-                                  .udata1 = (void *)block);
-  if (!subid)
+  fiobj_free(ch);
+  if (!sub)
     return Qnil;
-  return ULL2NUM(subid);
-  (void)self;
+  return subscription_initialize(sub, uuid, owner, type, rb_ch);
 }
 
+// clang-format off
 /**
-Cancels the subscription matching `sub_id`.
+Subscribes to a Pub/Sub channel.
+
+The method accepts 1-2 arguments and an optional block. These are all valid ways
+to call the method:
+
+      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
+
+The first argument must be either a String or a Hash.
+
+The second, optional, argument must be a Hash (if given).
+
+The options Hash supports the following possible keys (other keys are ignored, all keys are Symbols):
+
+: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.
+
+:to :: The channel / subject to subscribe to.
+
+Returns an {Iodine::PubSub::Subscription} object that answers to:
+
+close :: closes the connection.
+to_s :: returns the subscription's target (stream / channel / subject).
+==(str) :: returns true if the string is an exact match for the target (even if the target itself is a pattern).
+
 */
-static VALUE iodine_unsubscribe(VALUE self, VALUE sub_id) {
-  if (sub_id == Qnil || sub_id == Qfalse)
-    return Qnil;
-  Check_Type(sub_id, T_FIXNUM);
-  pubsub_unsubscribe((pubsub_sub_pt)NUM2LONG(sub_id));
-  return Qnil;
+static VALUE iodine_subscribe_global(int argc, VALUE *argv, VALUE self) {
+  // clang-format on
+  return iodine_subscribe(argc, argv, NULL, IODINE_PUBSUB_GLOBAL);
   (void)self;
 }
 
 /**
 Publishes a message to a channel.
 
-Accepts a single Hash argument with the following possible options:
+Can be used using two Strings:
+
+      publish(to, message)
+
+The method accepts an optional `engine` argument:
+
+      publish(to, message, my_pubsub_engine)
 
-: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.
+Alternatively, accepts the following named arguments:
 
-: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.
+:to :: The channel to publish to (required).
+
+:message :: The message to be published (required).
+
+:engine :: If provided, the engine to use for pub/sub. Otherwise the default
+engine is used.
 
-:message :: REQUIRED. The message to be published.
-:
 */
-static VALUE iodine_publish(VALUE self, VALUE args) {
-  Check_Type(args, T_HASH);
+VALUE iodine_publish(int argc, VALUE *argv, VALUE self) {
+  VALUE rb_ch, rb_msg, rb_engine = Qnil;
   uint8_t use_pattern = 0;
+  const pubsub_engine_s *engine = NULL;
+  switch (argc) {
+  case 3:
+    /* fallthrough */
+    rb_engine = argv[2];
+  case 2:
+    rb_ch = argv[0];
+    rb_msg = argv[1];
+    break;
+  case 1: {
+    /* single argument must be a Hash */
+    Check_Type(argv[0], T_HASH);
+    rb_ch = rb_hash_aref(argv[0], to_sym_id);
+    if (rb_ch == Qnil || rb_ch == Qfalse) {
+      use_pattern = 1;
+      rb_ch = rb_hash_aref(argv[0], match_sym_id);
+    }
+    rb_msg = rb_hash_aref(argv[0], message_sym_id);
+    rb_engine = rb_hash_aref(argv[0], engine_varid);
+  } break;
+  default:
+    rb_raise(rb_eArgError, "method accepts 1-3 arguments.");
+  }
 
-  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 (rb_msg == Qnil || rb_msg == Qfalse) {
+    rb_raise(rb_eArgError, "message is required.");
   }
+  Check_Type(rb_msg, T_STRING);
+
+  if (rb_ch == Qnil || rb_ch == Qfalse)
+    rb_raise(rb_eArgError, "channel is required .");
   if (TYPE(rb_ch) == T_SYMBOL)
     rb_ch = rb_sym2str(rb_ch);
   Check_Type(rb_ch, T_STRING);
 
-  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.");
+  if (rb_engine == Qfalse) {
+    engine = PUBSUB_PROCESS_ENGINE;
+  } else if (rb_engine == Qnil) {
+    engine = NULL;
+  } else {
+    engine = iodine_engine_ruby2facil(rb_engine);
   }
-  Check_Type(rb_msg, T_STRING);
 
-  pubsub_engine_s *engine =
-      iodine_engine_ruby2facil(rb_hash_aref(args, engine_varid));
+  FIOBJ ch = fiobj_str_new(RSTRING_PTR(rb_ch), RSTRING_LEN(rb_ch));
+  FIOBJ msg = fiobj_str_new(RSTRING_PTR(rb_msg), RSTRING_LEN(rb_msg));
 
   intptr_t ret =
-      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);
+      pubsub_publish(.engine = engine, .channel = ch, .message = msg);
+  fiobj_free(ch);
+  fiobj_free(msg);
   if (!ret)
     return Qfalse;
   return Qtrue;
@@ -589,32 +856,64 @@ static VALUE iodine_publish(VALUE self, VALUE args) {
 Initialization
 ***************************************************************************** */
 void Iodine_init_pubsub(void) {
-  engine_varid = rb_intern("engine");
+  default_pubsubid = rb_intern("default_pubsub");
   engine_subid = rb_intern("subscribe");
   engine_unsubid = rb_intern("unsubscribe");
-  engine_pubid = rb_intern("publish");
-  default_pubsubid = rb_intern("default_pubsub");
-  channel_var_id = ID2SYM(rb_intern("channel"));
-  pattern_var_id = ID2SYM(rb_intern("pattern"));
-  message_var_id = ID2SYM(rb_intern("message"));
+  engine_varid = rb_intern("engine");
+  iodine_engine_pubid = rb_intern("publish");
+  to_str_shadow_id = rb_intern("@to_s");
+
+  as_sym_id = ID2SYM(rb_intern("as"));
+  binary_sym_id = ID2SYM(rb_intern("binary"));
+  handler_sym_id = ID2SYM(rb_intern("handler"));
+  match_sym_id = ID2SYM(rb_intern("match"));
+  message_sym_id = ID2SYM(rb_intern("message"));
+  redis_sym_id = ID2SYM(rb_intern("redis"));
+  text_sym_id = ID2SYM(rb_intern("text"));
+  to_sym_id = ID2SYM(rb_intern("to"));
+
+  channel_sym_id = ID2SYM(rb_intern("channel")); /* bawards compatibility */
 
   IodinePubSub = rb_define_module_under(Iodine, "PubSub");
   IodineEngine = rb_define_class_under(IodinePubSub, "Engine", rb_cObject);
+  IodinePubSubSubscription =
+      rb_define_class_under(IodinePubSub, "Subscription", rb_cObject);
+
+  rb_define_method(IodinePubSubSubscription, "close", close_subscription, 0);
+  rb_define_method(IodinePubSubSubscription, "==", subscription_eq_s, 1);
+  rb_attr(IodinePubSubSubscription, rb_intern("to_s"), 1, 0, 1);
+  rb_define_method(IodinePubSubSubscription, "to_s", subscription_to_s, 1);
 
   rb_define_alloc_func(IodineEngine, engine_alloc_c);
   rb_define_method(IodineEngine, "initialize", engine_initialize, 0);
 
-  rb_define_method(IodineEngine, "distribute", engine_distribute, -1);
   rb_define_method(IodineEngine, "subscribe", engine_sub_placeholder, 2);
   rb_define_method(IodineEngine, "unsubscribe", engine_sub_placeholder, 2);
-  rb_define_method(IodineEngine, "publish", engine_pub_placeholder, 3);
+  rb_define_method(IodineEngine, "publish", engine_pub_placeholder, 2);
+  rb_define_method(IodineEngine, "register", iodine_engine_register, 0);
+  rb_define_method(IodineEngine, "deregister", iodine_engine_deregister, 0);
+  rb_define_method(IodineEngine, "reset", iodine_engine_reset, 0);
 
-  rb_define_module_function(Iodine, "default_pubsub=", ips_set_default, 1);
-  rb_define_module_function(Iodine, "default_pubsub", ips_get_default, 0);
+  rb_define_module_function(Iodine, "subscribe", iodine_subscribe_global, -1);
+  rb_define_module_function(Iodine, "publish", iodine_publish, -1);
+  rb_define_module_function(Iodine, "default_engine=", ips_set_default, 1);
+  rb_define_module_function(Iodine, "default_engine", ips_get_default, 0);
 
-  rb_define_module_function(Iodine, "subscribe", iodine_subscribe, 1);
-  rb_define_module_function(Iodine, "unsubscribe", iodine_unsubscribe, 1);
-  rb_define_module_function(Iodine, "publish", iodine_publish, 1);
+  rb_define_module_function(IodinePubSub, "default_engine=", ips_set_default,
+                            1);
+  rb_define_module_function(IodinePubSub, "default_engine", ips_get_default, 0);
+  rb_define_method(IodinePubSub, "register", iodine_engine_register2, 1);
+  rb_define_method(IodinePubSub, "deregister", iodine_engine_deregister2, 1);
+  rb_define_method(IodinePubSub, "reset", iodine_engine_reset2, 1);
+
+  rb_define_module_function(IodinePubSub, "subscribe", iodine_subscribe_global,
+                            -1);
+  rb_define_module_function(IodinePubSub, "publish", iodine_publish, -1);
+
+  /* deprecated */
+
+  rb_define_module_function(Iodine, "default_pubsub=", ips_set_default_dep, 1);
+  rb_define_module_function(Iodine, "default_pubsub", ips_get_default_dep, 0);
 
   /* *************************
   Initialize C pubsub engines
@@ -629,6 +928,7 @@ void Iodine_init_pubsub(void) {
   /** This is the (currently) default pub/sub engine. It will distribute
    * messages to all subscribers in the process cluster. */
   rb_define_const(IodinePubSub, "CLUSTER", engine_in_c);
+
   // rb_const_set(IodineEngine, rb_intern("CLUSTER"), e);
 
   engine_in_c = rb_funcallv(IodineEngine, iodine_new_func_id, 0, NULL);
@@ -638,6 +938,7 @@ void Iodine_init_pubsub(void) {
   /** This is a single process pub/sub engine. It will distribute messages to
    * all subscribers sharing the same process. */
   rb_define_const(IodinePubSub, "SINGLE_PROCESS", engine_in_c);
+
   // rb_const_set(IodineEngine, rb_intern("SINGLE_PROCESS"), e);
 
   engine_in_c =