iodine 0.7.59 → 0.8.0

data/ext/iodine/iodine_pubsub_msg.h

@@ -0,0 +1,228 @@
+#ifndef H___IODINE_PUBSUB_MSG___H
+#define H___IODINE_PUBSUB_MSG___H
+#include "iodine.h"
+
+/* *****************************************************************************
+Iodine PubSub Message - Published Message Wrapper
+
+This module provides the Iodine::PubSub::Message Ruby class which represents
+a message received through the pub/sub system. Message objects are passed
+to subscription callbacks and custom engine publish handlers.
+
+Message Properties (readable and writable):
+- id        - Unique message identifier (Integer)
+- channel   - Channel name the message was published to (String)
+- event     - Alias for channel
+- filter    - Filter value (Integer, reserved)
+- message   - The message payload (String)
+- msg       - Alias for message
+- data      - Alias for message
+- published - Timestamp when message was published (Integer)
+- to_s      - Returns the message payload (String)
+
+Ruby API (Iodine::PubSub::Message):
+- message.id          - Get message ID
+- message.channel     - Get channel name
+- message.message     - Get message payload
+- message.published   - Get publish timestamp
+- message.id = val    - Set message ID (for custom engines)
+- etc.
+***************************************************************************** */
+
+/* *****************************************************************************
+Ruby PubSub Message Object - Internal Types
+***************************************************************************** */
+
+/**
+ * Enum for indexing into the message's VALUE store array.
+ * Each property is stored at a specific index for fast access.
+ */
+typedef enum {
+  IODINE_PUBSUB_MSG_STORE_id,        /**< Message unique ID */
+  IODINE_PUBSUB_MSG_STORE_channel,   /**< Channel name */
+  IODINE_PUBSUB_MSG_STORE_filter,    /**< Filter value */
+  IODINE_PUBSUB_MSG_STORE_message,   /**< Message payload */
+  IODINE_PUBSUB_MSG_STORE_published, /**< Publish timestamp */
+  IODINE_PUBSUB_MSG_STORE_FINISH,    /**< Sentinel - array size */
+} iodine_pubsub_msg_store_e;
+
+/**
+ * Internal structure representing a PubSub message.
+ *
+ * Stores Ruby VALUE objects for each message property in an array
+ * indexed by iodine_pubsub_msg_store_e values.
+ */
+typedef struct iodine_pubsub_msg_wrapper_s {
+  const fio_pubsub_msg_s *msg; /**< Original C message (may be NULL) */
+  VALUE
+  store[IODINE_PUBSUB_MSG_STORE_FINISH]; /**< Ruby values for properties */
+} iodine_pubsub_msg_wrapper_s;
+
+static size_t iodine_pubsub_msg_data_size(const void *ptr_) {
+  iodine_pubsub_msg_wrapper_s *m = (iodine_pubsub_msg_wrapper_s *)ptr_;
+  return sizeof(*m) + (m->msg ? (sizeof(m->msg[0]) + m->msg->message.len +
+                                 m->msg->channel.len)
+                              : 0);
+}
+
+static void iodine_pubsub_msg_mark(void *m_) {
+  iodine_pubsub_msg_wrapper_s *m = (iodine_pubsub_msg_wrapper_s *)m_;
+  for (size_t i = 0; i < IODINE_PUBSUB_MSG_STORE_FINISH; ++i)
+    if (!IODINE_STORE_IS_SKIP(m->store[i]))
+      rb_gc_mark(m->store[i]);
+}
+
+static void iodine_pubsub_msg_free(void *ptr_) {
+  iodine_pubsub_msg_wrapper_s *c = (iodine_pubsub_msg_wrapper_s *)ptr_;
+  ruby_xfree(c);
+  FIO_LEAK_COUNTER_ON_FREE(iodine_pubsub_msg);
+}
+
+static const rb_data_type_t IODINE_PUBSUB_MSG_DATA_TYPE = {
+    .wrap_struct_name = "IodinePSMessage",
+    .function =
+        {
+            .dmark = iodine_pubsub_msg_mark,
+            .dfree = iodine_pubsub_msg_free,
+            .dsize = iodine_pubsub_msg_data_size,
+        },
+    .data = NULL,
+    // .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE iodine_pubsub_msg_alloc(VALUE klass) {
+  iodine_pubsub_msg_wrapper_s *m =
+      (iodine_pubsub_msg_wrapper_s *)ruby_xmalloc(sizeof(*m));
+  if (!m)
+    goto no_memory;
+  *m = (iodine_pubsub_msg_wrapper_s){0};
+  for (size_t i = 0; i < IODINE_PUBSUB_MSG_STORE_FINISH; ++i)
+    m->store[i] = Qnil;
+  FIO_LEAK_COUNTER_ON_ALLOC(iodine_pubsub_msg);
+  return TypedData_Wrap_Struct(klass, &IODINE_PUBSUB_MSG_DATA_TYPE, m);
+no_memory:
+  FIO_LOG_FATAL("Memory allocation failed");
+  fio_io_stop();
+  return Qnil;
+}
+
+static iodine_pubsub_msg_wrapper_s *iodine_pubsub_msg_get(VALUE self) {
+  iodine_pubsub_msg_wrapper_s *m;
+  TypedData_Get_Struct(self,
+                       iodine_pubsub_msg_wrapper_s,
+                       &IODINE_PUBSUB_MSG_DATA_TYPE,
+                       m);
+  return m;
+}
+
+/**
+ * Creates a new Iodine::PubSub::Message Ruby object from a C message.
+ *
+ * Copies all message properties from the C struct into Ruby VALUE objects.
+ * The returned message is held in the STORE to prevent GC.
+ *
+ * @param msg The C message struct to wrap
+ * @return New Iodine::PubSub::Message VALUE
+ */
+static VALUE iodine_pubsub_msg_new(const fio_pubsub_msg_s *msg) {
+  VALUE m = rb_obj_alloc(iodine_rb_IODINE_PUBSUB_MSG);
+  STORE.hold(m);
+  iodine_pubsub_msg_wrapper_s *c = iodine_pubsub_msg_get(m);
+  c->store[IODINE_PUBSUB_MSG_STORE_id] = ULL2NUM(msg->id);
+  c->store[IODINE_PUBSUB_MSG_STORE_channel] =
+      (msg->channel.len ? rb_enc_str_new(msg->channel.buf,
+                                         msg->channel.len,
+                                         IodineBinaryEncoding)
+                        : Qnil);
+  ;
+  c->store[IODINE_PUBSUB_MSG_STORE_filter] =
+      (msg->filter ? INT2NUM(((int16_t)(msg->filter))) : Qnil);
+  c->store[IODINE_PUBSUB_MSG_STORE_message] =
+      (msg->message.len ? rb_enc_str_new(msg->message.buf,
+                                         msg->message.len,
+                                         IodineBinaryEncoding)
+                        : Qnil);
+  c->store[IODINE_PUBSUB_MSG_STORE_published] =
+      (msg->timestamp ? ULL2NUM(msg->timestamp) : Qnil);
+  return m;
+}
+
+/**
+ * Macro to define getter and setter functions for message properties.
+ *
+ * Generates:
+ * - iodine_pubsub_msg_<name>_get(self) - Returns the property value
+ * - iodine_pubsub_msg_<name>_set(self, val) - Sets the property value
+ *
+ * @param val_name The property name (id, channel, filter, message, published)
+ */
+#define IODINE_DEF_GET_SET_FUNC(val_name, ...)                                 \
+  /** Returns the message's val_name */                                        \
+  static VALUE iodine_pubsub_msg_##val_name##_get(VALUE self) {                \
+    iodine_pubsub_msg_wrapper_s *c = iodine_pubsub_msg_get(self);              \
+    if (!c)                                                                    \
+      return Qnil;                                                             \
+    return c->store[IODINE_PUBSUB_MSG_STORE_##val_name];                       \
+  }                                                                            \
+  /** Sets the message's val_name */                                           \
+  static VALUE iodine_pubsub_msg_##val_name##_set(VALUE self, VALUE val) {     \
+    iodine_pubsub_msg_wrapper_s *c = iodine_pubsub_msg_get(self);              \
+    if (!c)                                                                    \
+      return Qnil;                                                             \
+    return (c->store[IODINE_PUBSUB_MSG_STORE_##val_name] = val);               \
+  }
+
+/* Generate getter/setter functions for all message properties */
+IODINE_DEF_GET_SET_FUNC(id);        /* message.id / message.id= */
+IODINE_DEF_GET_SET_FUNC(channel);   /* message.channel / message.channel= */
+IODINE_DEF_GET_SET_FUNC(filter);    /* message.filter / message.filter= */
+IODINE_DEF_GET_SET_FUNC(message);   /* message.message / message.message= */
+IODINE_DEF_GET_SET_FUNC(published); /* message.published / message.published= */
+
+#undef IODINE_DEF_GET_SET_FUNC
+
+/* *****************************************************************************
+Initialize - Ruby Class Registration
+***************************************************************************** */
+
+/**
+ * Initializes the Iodine::PubSub::Message Ruby class.
+ *
+ * Defines the Message class under Iodine::PubSub with:
+ * - Getter methods: id, channel, event, filter, message, msg, data, published,
+ * to_s
+ * - Setter methods: id=, channel=, event=, filter=, message=, msg=, data=,
+ * published=
+ *
+ * Note: event/msg/data are aliases for channel/message respectively.
+ */
+static void Init_Iodine_PubSub_Message(void) {
+  // clang-format off
+  iodine_rb_IODINE_PUBSUB_MSG = rb_define_class_under(iodine_rb_IODINE_PUBSUB, "Message", rb_cObject);
+  STORE.hold(iodine_rb_IODINE_PUBSUB_MSG);
+  rb_define_alloc_func(iodine_rb_IODINE_PUBSUB_MSG, iodine_pubsub_msg_alloc);
+  
+  /* Getter methods */
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "id", iodine_pubsub_msg_id_get, 0);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "channel", iodine_pubsub_msg_channel_get, 0);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "event", iodine_pubsub_msg_channel_get, 0);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "filter", iodine_pubsub_msg_filter_get, 0);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "message", iodine_pubsub_msg_message_get, 0);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "msg", iodine_pubsub_msg_message_get, 0);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "data", iodine_pubsub_msg_message_get, 0);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "published", iodine_pubsub_msg_published_get, 0);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "to_s", iodine_pubsub_msg_message_get, 0);
+
+  /* Setter methods */
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "id=", iodine_pubsub_msg_id_set, 1);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "channel=", iodine_pubsub_msg_channel_set, 1);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "event=", iodine_pubsub_msg_channel_set, 1);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "filter=", iodine_pubsub_msg_filter_set, 1);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "message=", iodine_pubsub_msg_message_set, 1);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "msg=", iodine_pubsub_msg_message_set, 1);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "data=", iodine_pubsub_msg_message_set, 1);
+  rb_define_method(iodine_rb_IODINE_PUBSUB_MSG, "published=", iodine_pubsub_msg_published_set, 1);
+  // clang-format on
+}
+
+#endif /* H___IODINE_PUBSUB_MSG___H */

data/ext/iodine/iodine_redis.h

@@ -0,0 +1,322 @@
+#ifndef H___IODINE_REDIS___H
+#define H___IODINE_REDIS___H
+
+/* *****************************************************************************
+RESP3 PubSub Engine Wrapper for Ruby
+
+Exposes the facil.io Redis engine as Iodine::PubSub::Engine::RESP3.
+
+Usage:
+    resp3 = Iodine::PubSub::Engine::RESP3.new("redis://localhost:6379/", ping: 50)
+    Iodine::PubSub.default = resp3
+    resp3.cmd("SET", "key", "value") { |result| puts result }
+
+***************************************************************************** */
+
+static VALUE iodine_rb_IODINE_REDIS;
+
+/* *****************************************************************************
+Redis Command Callback Context
+***************************************************************************** */
+
+typedef struct iodine_redis_cmd_ctx_s {
+  VALUE block;
+  fio_pubsub_engine_s *engine;
+} iodine_redis_cmd_ctx_s;
+
+/* *****************************************************************************
+Redis Command Callback - Called from IO thread
+***************************************************************************** */
+
+typedef struct iodine_redis_callback_args_s {
+  VALUE block;
+  FIOBJ reply;
+} iodine_redis_callback_args_s;
+
+static void *iodine_redis_callback_in_gvl(void *arg_) {
+  iodine_redis_callback_args_s *args = (iodine_redis_callback_args_s *)arg_;
+  VALUE result = iodine_fiobj2ruby(args->reply);
+  STORE.hold(result);
+  iodine_ruby_call_inside(args->block, IODINE_CALL_ID, 1, &result);
+  STORE.release(result);
+  return NULL;
+}
+
+static void iodine_redis_cmd_callback(fio_pubsub_engine_s *e,
+                                      FIOBJ reply,
+                                      void *udata) {
+  iodine_redis_cmd_ctx_s *ctx = (iodine_redis_cmd_ctx_s *)udata;
+  if (ctx->block != Qnil) {
+    iodine_redis_callback_args_s args = {
+        .block = ctx->block,
+        .reply = reply,
+    };
+    rb_thread_call_with_gvl(iodine_redis_callback_in_gvl, &args);
+    STORE.release(ctx->block);
+  }
+  FIO_MEM_FREE(ctx, sizeof(*ctx));
+  (void)e;
+}
+
+/* *****************************************************************************
+Ruby Methods
+***************************************************************************** */
+
+/**
+ * @!method initialize(url, ping: 0)
+ * Creates a new RESP3 Pub/Sub engine.
+ *
+ * @param url [String] Redis-compatible server URL (e.g., "redis://localhost:6379/")
+ * @param ping [Integer] Ping interval in seconds (0-255, default: 300)
+ * @return [Iodine::PubSub::Engine::RESP3]
+ *
+ * URL formats supported:
+ * - "redis://host:port"
+ * - "redis://user:password@host:port/db"
+ * - "host:port"
+ * - "host" (default port 6379)
+ *
+ * @example
+ *   resp3 = Iodine::PubSub::Engine::RESP3.new("redis://localhost:6379/")
+ *   resp3 = Iodine::PubSub::Engine::RESP3.new("redis://secret@host:6379/", ping: 60)
+ */
+static VALUE iodine_redis_initialize(int argc, VALUE *argv, VALUE self) {
+  /* Get the engine struct from parent class */
+  iodine_pubsub_eng_s *e = iodine_pubsub_eng_get(self);
+
+  VALUE url_val;
+  VALUE opts = Qnil;
+
+  /* Parse arguments: url, optional keyword args */
+  rb_scan_args(argc, argv, "1:", &url_val, &opts);
+
+  /* Validate URL */
+  if (url_val == Qnil || url_val == Qfalse) {
+    rb_raise(rb_eArgError, "Redis URL is required");
+    return Qnil;
+  }
+  Check_Type(url_val, T_STRING);
+  const char *url = StringValueCStr(url_val);
+
+  /* Parse ping interval from keyword args */
+  uint8_t ping_interval = 0;
+  if (opts != Qnil) {
+    VALUE ping_val = rb_hash_aref(opts, ID2SYM(rb_intern("ping")));
+    if (ping_val != Qnil) {
+      long ping = NUM2LONG(ping_val);
+      if (ping < 0 || ping > 255) {
+        rb_raise(rb_eArgError, "ping must be between 0 and 255");
+        return Qnil;
+      }
+      ping_interval = (uint8_t)ping;
+    }
+  }
+
+  /* Create the Redis engine */
+  e->ptr = fio_redis_new(.url = url, .ping_interval = ping_interval);
+  if (!e->ptr) {
+    rb_raise(rb_eRuntimeError, "Failed to create RESP3 engine");
+    return Qnil;
+  }
+
+  /* Attach to pub/sub system */
+  fio_pubsub_engine_attach(e->ptr);
+
+  return self;
+}
+
+/**
+ * @!method connection_state
+ * Returns the RESP3 connection state.
+ *
+ * @return [Symbol] `:connecting`, `:connected`, or `:error`
+ */
+static VALUE iodine_redis_connection_state(VALUE self) {
+  iodine_pubsub_eng_s *e = iodine_pubsub_eng_get(self);
+  switch (fio_redis_state(e->ptr)) {
+  case FIO_REDIS_STATE_CONNECTING:
+    return ID2SYM(rb_intern("connecting"));
+  case FIO_REDIS_STATE_CONNECTED:
+    return ID2SYM(rb_intern("connected"));
+  default: return ID2SYM(rb_intern("error"));
+  }
+}
+
+/**
+ * @!method cmd(*args, &block)
+ * Sends a Redis command and optionally receives the response via callback.
+ *
+ * @param args [Array<String, Integer, Float, Symbol, Boolean, nil>] Command and arguments
+ * @yield [result] Called with the Redis response
+ * @yieldparam result [Object] The parsed Redis response
+ * @return [Boolean] true on success, false on error
+ *
+ * @example
+ *   redis.cmd("SET", "key", "value") { |r| puts "SET result: #{r}" }
+ *   redis.cmd("GET", "key") { |value| puts "Value: #{value}" }
+ *   redis.cmd("KEYS", "*") { |keys| p keys }
+ *   redis.cmd("INCR", "counter") { |new_val| puts new_val }
+ *
+ * @note Do NOT use SUBSCRIBE/PSUBSCRIBE/UNSUBSCRIBE/PUNSUBSCRIBE commands.
+ *       These are handled internally by the pub/sub system.
+ */
+static VALUE iodine_redis_cmd(int argc, VALUE *argv, VALUE self) {
+  iodine_pubsub_eng_s *e = iodine_pubsub_eng_get(self);
+
+  if (!e->ptr) {
+    rb_raise(rb_eRuntimeError, "RESP3 engine not initialized");
+    return Qfalse;
+  }
+
+  if (argc < 1) {
+    rb_raise(rb_eArgError, "At least one argument (command) is required");
+    return Qfalse;
+  }
+
+  /* Build FIOBJ array from Ruby arguments */
+  FIOBJ cmd = fiobj_array_new();
+  fiobj_array_reserve(cmd, argc);
+
+  for (int i = 0; i < argc; ++i) {
+    VALUE arg = argv[i];
+    FIOBJ item = FIOBJ_INVALID;
+
+    switch (rb_type(arg)) {
+    case RUBY_T_STRING:
+      item = fiobj_str_new_cstr(RSTRING_PTR(arg), RSTRING_LEN(arg));
+      break;
+    case RUBY_T_SYMBOL:
+      arg = rb_sym2str(arg);
+      item = fiobj_str_new_cstr(RSTRING_PTR(arg), RSTRING_LEN(arg));
+      break;
+    case RUBY_T_FIXNUM:
+      item = fiobj_num_new((intptr_t)NUM2LL(arg));
+      break;
+    case RUBY_T_FLOAT: item = fiobj_float_new(RFLOAT_VALUE(arg)); break;
+    case RUBY_T_TRUE: item = fiobj_str_new_cstr("1", 1); break;
+    case RUBY_T_FALSE: item = fiobj_str_new_cstr("0", 1); break;
+    case RUBY_T_NIL: item = fiobj_null(); break;
+    default:
+      /* Try to convert to string */
+      arg = rb_funcallv(arg, IODINE_TO_S_ID, 0, NULL);
+      if (RB_TYPE_P(arg, RUBY_T_STRING)) {
+        item = fiobj_str_new_cstr(RSTRING_PTR(arg), RSTRING_LEN(arg));
+      } else {
+        fiobj_free(cmd);
+        rb_raise(rb_eTypeError,
+                 "Cannot convert argument %d to Redis command element",
+                 i);
+        return Qfalse;
+      }
+    }
+    fiobj_array_push(cmd, item);
+  }
+
+  /* Get the block if provided */
+  VALUE block = Qnil;
+  if (rb_block_given_p()) {
+    block = rb_block_proc();
+  }
+
+  /* Prepare callback context */
+  iodine_redis_cmd_ctx_s *ctx = NULL;
+  void (*callback)(fio_pubsub_engine_s *, FIOBJ, void *) = NULL;
+
+  if (block != Qnil) {
+    ctx =
+        (iodine_redis_cmd_ctx_s *)FIO_MEM_REALLOC(NULL, 0, sizeof(*ctx), 0);
+    if (!ctx) {
+      fiobj_free(cmd);
+      rb_raise(rb_eNoMemError, "Failed to allocate callback context");
+      return Qfalse;
+    }
+    ctx->block = block;
+    ctx->engine = e->ptr;
+    STORE.hold(block);
+    callback = iodine_redis_cmd_callback;
+  }
+
+  /* Send the command */
+  int result = fio_redis_send(e->ptr, cmd, callback, ctx);
+  fiobj_free(cmd);
+
+  if (result != 0) {
+    if (ctx) {
+      STORE.release(block);
+      FIO_MEM_FREE(ctx, sizeof(*ctx));
+    }
+    return Qfalse;
+  }
+
+  return Qtrue;
+}
+
+/* *****************************************************************************
+Custom dealloc for Redis - need to call fio_redis_free instead of default
+***************************************************************************** */
+
+static void iodine_redis_free(void *ptr_) {
+  iodine_pubsub_eng_s *e = (iodine_pubsub_eng_s *)ptr_;
+  if (e->ptr) {
+    fio_pubsub_engine_detach(e->ptr);
+    fio_redis_free(e->ptr);
+    e->ptr = NULL;
+  }
+  ruby_xfree(e);
+}
+
+static const rb_data_type_t IODINE_REDIS_DATA_TYPE = {
+    .wrap_struct_name = "IodineRedis",
+    .function =
+        {
+            .dfree = iodine_redis_free,
+            .dsize = iodine_pubsub_eng_data_size,
+        },
+    .parent = &IODINE_PUBSUB_ENG_DATA_TYPE,
+    .data = NULL,
+};
+
+static VALUE iodine_redis_alloc(VALUE klass) {
+  iodine_pubsub_eng_s *e =
+      (iodine_pubsub_eng_s *)ruby_xmalloc(sizeof(iodine_pubsub_eng_s));
+  if (!e)
+    goto no_memory;
+  *e = (iodine_pubsub_eng_s){0};
+  return TypedData_Wrap_Struct(klass, &IODINE_REDIS_DATA_TYPE, e);
+
+no_memory:
+  FIO_LOG_FATAL("Memory allocation failed for Redis engine");
+  fio_io_stop();
+  return Qnil;
+}
+
+/* *****************************************************************************
+Initialization
+***************************************************************************** */
+
+/**
+ * Initializes the Iodine::PubSub::Engine::RESP3 class.
+ */
+static void Init_Iodine_RESP3(void) {
+  /* Define Iodine::PubSub::Engine::RESP3 as a subclass of Engine. */
+  iodine_rb_IODINE_REDIS = rb_define_class_under(iodine_rb_IODINE_PUBSUB_ENG,
+                                                  "RESP3",
+                                                  iodine_rb_IODINE_PUBSUB_ENG);
+  STORE.hold(iodine_rb_IODINE_REDIS);
+
+  /* Set up allocation function */
+  rb_define_alloc_func(iodine_rb_IODINE_REDIS, iodine_redis_alloc);
+
+  /* Define instance methods */
+  rb_define_method(iodine_rb_IODINE_REDIS,
+                   "initialize",
+                   iodine_redis_initialize,
+                   -1);
+  rb_define_method(iodine_rb_IODINE_REDIS,
+                   "connection_state",
+                   iodine_redis_connection_state,
+                   0);
+  rb_define_method(iodine_rb_IODINE_REDIS, "cmd", iodine_redis_cmd, -1);
+}
+
+#endif /* H___IODINE_REDIS___H */