iodine 0.7.60 → 0.8.0

data/ext/iodine/iodine_listener.h

@@ -0,0 +1,263 @@
+#ifndef H___IODINE_LISTENER___H
+#define H___IODINE_LISTENER___H
+#include "iodine.h"
+
+/* *****************************************************************************
+Iodine Listener - Server Socket Listener Management
+
+This module provides the Iodine::Listener Ruby class which represents an
+active server socket listener. Listeners are created via Iodine.listen()
+and can be used to:
+
+- Map URL routes to different handlers (for HTTP listeners)
+- Get/set the handler for raw TCP/WebSocket connections
+- Manage listener lifecycle
+
+The Listener class wraps either:
+- fio_http_listener_s for HTTP/WebSocket listeners
+- fio_io_listener_s for raw TCP listeners
+
+Ruby API (Iodine::Listener):
+- listener.map(url: "/path", handler: obj) - Map URL to handler (HTTP only)
+- listener.map                             - Get current handler
+
+Note: Listeners can only be created via Iodine.listen(), not directly
+instantiated.
+***************************************************************************** */
+
+/* *****************************************************************************
+Ruby Object
+***************************************************************************** */
+
+/** The Iodine::Listener Ruby class */
+static VALUE iodine_rb_IODINE_LISTENER;
+
+/**
+ * Internal structure representing an Iodine listener.
+ *
+ * Wraps either an HTTP listener (fio_http_listener_s) or a raw IO listener
+ * (fio_io_listener_s) along with its Ruby handler object.
+ */
+typedef struct {
+  void *listener;   /**< Pointer to fio_http_listener_s or fio_io_listener_s */
+  VALUE handler;    /**< Ruby handler object for callbacks */
+  bool is_http;     /**< true if HTTP listener, false if raw TCP */
+} iodine_listener_s;
+
+static void iodine_listener_free(void *p) {
+  iodine_listener_s *m = (iodine_listener_s *)p;
+  ruby_xfree(m);
+}
+
+static size_t iodine_listener_size(const void *p) {
+  iodine_listener_s *m = (iodine_listener_s *)p;
+  return sizeof(*m);
+}
+
+FIO_IFUNC void iodine_listener_gc_mark(void *p) {
+  iodine_listener_s *m = (iodine_listener_s *)p;
+  if (!IODINE_STORE_IS_SKIP(m->handler))
+    rb_gc_mark(m->handler);
+}
+
+static const rb_data_type_t IODINE_LISTNER_DATA_TYPE = {
+    .wrap_struct_name = "IodineListner",
+    .function =
+        {
+            .dmark = iodine_listener_gc_mark,
+            .dfree = iodine_listener_free,
+            .dsize = iodine_listener_size,
+        },
+    .data = NULL,
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static iodine_listener_s *iodine_listener_ptr(VALUE self) {
+  iodine_listener_s *m;
+  TypedData_Get_Struct(self, iodine_listener_s, &IODINE_LISTNER_DATA_TYPE, m);
+  return m;
+}
+
+static VALUE iodine_listener_alloc(VALUE klass) {
+  iodine_listener_s *m;
+  VALUE self = TypedData_Make_Struct(klass,
+                                     iodine_listener_s,
+                                     &IODINE_LISTNER_DATA_TYPE,
+                                     m);
+  *m = (iodine_listener_s){0};
+  return self;
+}
+
+/* *****************************************************************************
+Helpers - Internal Handler Management
+***************************************************************************** */
+
+/**
+ * Macro called when a listener's handler is set.
+ * Releases the old handler from the store and holds the new one.
+ * Also injects handler methods into the listener class.
+ */
+#define IODINE_LISTNER_ONSET(o)                                                \
+  do {                                                                         \
+    STORE.release(old_value);                                                  \
+    STORE.hold(o->handler);                                                    \
+    iodine_handler_method_injection__inner(iodine_rb_IODINE_LISTENER,          \
+                                           o->handler,                         \
+                                           0);                                 \
+  } while (0)
+
+FIO_DEF_GETSET_FUNC(static,
+                    iodine___listener,
+                    iodine_listener_s,
+                    VALUE,
+                    handler,
+                    IODINE_LISTNER_ONSET)
+
+#undef IODINE_LISTNER_ONSET
+
+/**
+ * Creates a new Iodine::Listener Ruby object wrapping a native listener.
+ *
+ * This is called internally by Iodine.listen() to create the Ruby wrapper.
+ *
+ * @param listener Pointer to the native listener (HTTP or raw)
+ * @param handler Ruby handler object for callbacks
+ * @param is_http true for HTTP listeners, false for raw TCP
+ * @return New Iodine::Listener VALUE
+ *
+ * @note Raises NoMemError if allocation fails.
+ */
+static VALUE iodine_listener_new(void *listener, VALUE handler, bool is_http) {
+  VALUE r = iodine_listener_alloc(iodine_rb_IODINE_LISTENER);
+  if (IODINE_STORE_IS_SKIP(r))
+    rb_raise(rb_eNoMemError, "Listener loocation error!");
+  iodine_listener_s *l = iodine_listener_ptr(r);
+  *l = (iodine_listener_s){.listener = listener,
+                           .handler = handler,
+                           .is_http = is_http};
+  return r;
+}
+
+/* *****************************************************************************
+API - Ruby Methods
+***************************************************************************** */
+
+/**
+ * Maps a URL path to a handler or retrieves the current handler.
+ *
+ * For HTTP listeners:
+ * - With url and handler: Maps the URL path to the handler
+ * - With url only: Returns the handler for that URL path
+ * - With neither: Returns the default handler
+ *
+ * For raw TCP listeners:
+ * - URL parameter is not allowed (raises RuntimeError)
+ * - With handler: Sets the connection handler
+ * - Without handler: Returns the current handler
+ *
+ * @param argc Number of arguments
+ * @param argv Array of arguments (url:, handler:)
+ * @param o The Iodine::Listener instance
+ * @return The handler for the specified URL/listener
+ *
+ * @note Raises RuntimeError if called on an inactive listener.
+ * @note Raises RuntimeError if URL is provided for non-HTTP listener.
+ *
+ * Ruby: listener.map(url: "/api", handler: MyHandler)
+ *       listener.map(url: "/api")  # => returns handler
+ *       listener.map               # => returns default handler
+ */
+static VALUE iodine_listener_map(int argc, VALUE *argv, VALUE o) {
+  iodine_listener_s *l = iodine_listener_ptr(o);
+  fio_http_settings_s settings;
+  VALUE url = Qnil;
+  VALUE handler = Qnil;
+
+  iodine_rb2c_arg(argc,
+                  argv,
+                  IODINE_ARG_RB(url, 0, "url", 0),
+                  IODINE_ARG_RB(handler, 0, "handler", 0));
+  if (!l->listener)
+    rb_raise(rb_eRuntimeError,
+             "call to `map` can only be called on active listeners");
+  if (l->is_http) {
+    if (RB_TYPE_P(url, RUBY_T_SYMBOL))
+      url = rb_sym2str(rb_sym2id(url));
+    if (!IODINE_STORE_IS_SKIP(url))
+      rb_check_type(url, RUBY_T_STRING);
+    if (handler == Qnil) { /* read value */
+      handler = (VALUE)(fio_http_route_settings(
+                            (fio_http_listener_s *)(l->listener),
+                            IODINE_STORE_IS_SKIP(url) ? "/" : RSTRING_PTR(url))
+                            ->udata);
+    } else { /* set value for HTTP router */
+      if (!IODINE_STORE_IS_SKIP(handler)) {
+        STORE.hold(handler);
+        iodine_handler_method_injection__inner(iodine_rb_IODINE_LISTENER,
+                                               handler,
+                                               0);
+      }
+      settings =
+          *fio_http_listener_settings((fio_http_listener_s *)l->listener);
+      if (IODINE_STORE_IS_SKIP(handler))
+        handler = (VALUE)settings.udata;
+      settings.udata = (void *)handler;
+      settings.public_folder = FIO_STR_INFO0;
+      // TODO: test for a handler's public folder property?
+      fio_http_route FIO_NOOP((fio_http_listener_s *)l->listener,
+                              RSTRING_PTR(url),
+                              settings);
+    }
+  } else { /* not HTTP, URLs are invalid. */
+    if (!IODINE_STORE_IS_SKIP(url))
+      rb_raise(rb_eRuntimeError,
+               "URL values are only valid for HTTP listener objects.");
+    if (handler == Qnil) { /* read value */
+      handler = iodine___listener_handler(l);
+    } else { /* set value for raw router */
+      fio_io_listener_udata_set((fio_io_listener_s *)(l->listener),
+                                (void *)handler);
+      iodine___listener_handler_set(l, handler);
+    }
+  }
+  return handler;
+}
+
+/**
+ * Raises an error - Listeners cannot be directly instantiated.
+ *
+ * Listeners must be created via Iodine.listen() which returns a
+ * properly configured Listener object.
+ *
+ * @param o The Listener instance (unused)
+ * @return Never returns (always raises)
+ *
+ * @note Always raises RuntimeError.
+ */
+static VALUE iodine_listener_initialize(VALUE o) {
+  rb_raise(rb_eRuntimeError,
+           "Iodine Listeners can only be created using Iodine.listen");
+  return Qnil;
+}
+
+/* *****************************************************************************
+Initialize - Ruby Class Registration
+***************************************************************************** */
+
+/**
+ * Initializes the Iodine::Listener Ruby class.
+ *
+ * Defines the class under the Iodine module and registers:
+ * - Allocator function
+ * - initialize method (raises error - use Iodine.listen instead)
+ * - map method for URL routing (HTTP) or handler access (raw)
+ */
+static void Init_Iodine_Listener(void) {
+  VALUE m = iodine_rb_IODINE_LISTENER =
+      rb_define_class_under(iodine_rb_IODINE, "Listener", rb_cObject);
+  STORE.hold(iodine_rb_IODINE_LISTENER);
+  rb_define_alloc_func(m, iodine_listener_alloc);
+  rb_define_method(m, "initialize", iodine_listener_initialize, 0);
+  rb_define_method(m, "map", iodine_listener_map, -1);
+}
+#endif /* H___IODINE_LISTENER___H */

data/ext/iodine/iodine_log.h

@@ -0,0 +1,297 @@
+#ifndef H___IODINE_LOG___H
+#define H___IODINE_LOG___H
+#include "iodine.h"
+
+/* *****************************************************************************
+Iodine::Logger - Ruby-facing leveled logging
+
+Routes Ruby log messages through the facil.io C STL logging system
+(FIO_LOG_*), so Ruby output shares the same stderr sink, level prefixes,
+truncation limits, and the global log level (Iodine::Logger.level /
+FIO_LOG_LEVEL) as the C core.
+
+Log levels (from facil.io):
+- 0: FIO_LOG_LEVEL_NONE    - No logging
+- 1: FIO_LOG_LEVEL_FATAL   - Fatal errors only
+- 2: FIO_LOG_LEVEL_ERROR   - Errors and above
+- 3: FIO_LOG_LEVEL_WARNING - Warnings and above
+- 4: FIO_LOG_LEVEL_INFO    - Info and above (default)
+- 5: FIO_LOG_LEVEL_DEBUG   - Debug and above
+
+Ruby API:
+- Iodine::Logger.fatal(*msg, &blk) / .error / .warn / .info / .debug
+  (each argument logged separately; callable arguments invoked; a block's
+  return value logged; nothing evaluated while the level is silenced)
+- Iodine::Logger << msg (alias for info)
+- Iodine::Logger.level / .level= (Integer 0-5 or Symbol)
+- Iodine::Logger::NONE / FATAL / ERROR / WARN / INFO / DEBUG constants
+***************************************************************************** */
+
+static VALUE iodine_rb_IODINE_LOGGER;
+
+/* *****************************************************************************
+Leveled logging methods
+***************************************************************************** */
+
+/** Emits a single message at the given level through the C STL logging. */
+static void iodine_log_emit_value(int level, VALUE msg) {
+  VALUE str = rb_obj_as_string(msg);
+  const char *cstr = StringValueCStr(str);
+  switch (level) {
+  case FIO_LOG_LEVEL_FATAL: FIO_LOG_FATAL("%s", cstr); break;
+  case FIO_LOG_LEVEL_ERROR: FIO_LOG_ERROR("%s", cstr); break;
+  case FIO_LOG_LEVEL_WARNING: FIO_LOG_WARNING("%s", cstr); break;
+  case FIO_LOG_LEVEL_INFO: FIO_LOG_INFO("%s", cstr); break;
+  default: FIO_LOG_DEBUG2("%s", cstr); break;
+  }
+}
+
+/**
+ * Shared implementation for all leveled methods.
+ *
+ * Each argument is logged as its own message. Arguments that answer `call`
+ * (e.g. Proc / lambda) are invoked and their return value is logged. If a
+ * block is given, it is called last and its return value is logged (Rack
+ * SPEC compatible logger behavior).
+ *
+ * Lazy evaluation: when the level exceeds the current verbosity, nothing is
+ * evaluated - arguments are not converted, callables are not invoked and the
+ * block is not called.
+ */
+static VALUE iodine_log_write(int level, int argc, VALUE *argv) {
+  if (level > FIO_LOG_LEVEL_GET())
+    return Qnil;
+  for (int i = 0; i < argc; ++i) {
+    VALUE msg = argv[i];
+    if (rb_respond_to(msg, IODINE_CALL_ID))
+      msg = rb_funcall2(msg, IODINE_CALL_ID, 0, NULL);
+    iodine_log_emit_value(level, msg);
+  }
+  if (rb_block_given_p())
+    iodine_log_emit_value(
+        level,
+        rb_funcall2(rb_block_proc(), IODINE_CALL_ID, 0, NULL));
+  return Qnil;
+}
+
+/**
+ * @!method fatal(*messages, &block)
+ * Logs each message at fatal level (level 1).
+ *
+ * Callable arguments are invoked and a block's return value is logged
+ * (evaluated only when the level is active).
+ *
+ * @param messages [Array<Object>] the messages (converted with #to_s)
+ * @return [nil]
+ */
+static VALUE iodine_log_fatal(int argc, VALUE *argv, VALUE self) {
+  return iodine_log_write(FIO_LOG_LEVEL_FATAL, argc, argv);
+  (void)self;
+}
+
+/**
+ * @!method error(*messages, &block)
+ * Logs each message at error level (level 2).
+ *
+ * Callable arguments are invoked and a block's return value is logged
+ * (evaluated only when the level is active).
+ *
+ * @param messages [Array<Object>] the messages (converted with #to_s)
+ * @return [nil]
+ */
+static VALUE iodine_log_error(int argc, VALUE *argv, VALUE self) {
+  return iodine_log_write(FIO_LOG_LEVEL_ERROR, argc, argv);
+  (void)self;
+}
+
+/**
+ * @!method warn(*messages, &block)
+ * Logs each message at warning level (level 3).
+ *
+ * Callable arguments are invoked and a block's return value is logged
+ * (evaluated only when the level is active).
+ *
+ * @param messages [Array<Object>] the messages (converted with #to_s)
+ * @return [nil]
+ */
+static VALUE iodine_log_warn(int argc, VALUE *argv, VALUE self) {
+  return iodine_log_write(FIO_LOG_LEVEL_WARNING, argc, argv);
+  (void)self;
+}
+
+/**
+ * @!method info(*messages, &block)
+ * Logs each message at info level (level 4).
+ *
+ * Callable arguments are invoked and a block's return value is logged
+ * (evaluated only when the level is active).
+ *
+ * @param messages [Array<Object>] the messages (converted with #to_s)
+ * @return [nil]
+ */
+static VALUE iodine_log_info(int argc, VALUE *argv, VALUE self) {
+  return iodine_log_write(FIO_LOG_LEVEL_INFO, argc, argv);
+  (void)self;
+}
+
+/**
+ * @!method <<(message)
+ * Alias for {#info} - logs the message at info level (level 4).
+ *
+ * @param message [Object] the message (converted with #to_s)
+ * @return [nil]
+ */
+static VALUE iodine_log_lshift(int argc, VALUE *argv, VALUE self) {
+  return iodine_log_write(FIO_LOG_LEVEL_INFO, argc, argv);
+  (void)self;
+}
+
+/**
+ * @!method debug(*messages, &block)
+ * Logs each message at debug level (level 5), routed through FIO_LOG_DEBUG2
+ * (the C file:line prefix is omitted, since it would point at the binding
+ * rather than the Ruby caller).
+ *
+ * Callable arguments are invoked and a block's return value is logged
+ * (evaluated only when the level is active).
+ *
+ * @param messages [Array<Object>] the messages (converted with #to_s)
+ * @return [nil]
+ */
+static VALUE iodine_log_debug(int argc, VALUE *argv, VALUE self) {
+  return iodine_log_write(FIO_LOG_LEVEL_DEBUG, argc, argv);
+  (void)self;
+}
+
+/* *****************************************************************************
+Level helpers
+***************************************************************************** */
+
+/**
+ * @!method level
+ * Returns the current logging level (the process-wide C STL log level).
+ *
+ * @return [Integer] the current log level (0-5)
+ */
+static VALUE iodine_log_level(VALUE self) {
+  return RB_INT2FIX(((long)FIO_LOG_LEVEL_GET()));
+  (void)self;
+}
+
+/**
+ * @!method level=(level)
+ * Sets the current logging level (the process-wide C STL log level).
+ *
+ * @param level [Integer, Symbol] the log level: 0-5, or one of
+ *              :none, :fatal, :error, :warn, :info, :debug
+ * @return [Integer, Symbol] the given level
+ * @raise [TypeError] if level is not an Integer or Symbol
+ * @raise [ArgumentError] if the level value is unknown or out of range
+ */
+static VALUE iodine_log_level_set(VALUE self, VALUE level) {
+  int n;
+  if (RB_TYPE_P(level, RUBY_T_SYMBOL)) {
+    ID id = rb_sym2id(level);
+    if (id == rb_intern("none")) {
+      n = FIO_LOG_LEVEL_NONE;
+    } else if (id == rb_intern("fatal")) {
+      n = FIO_LOG_LEVEL_FATAL;
+    } else if (id == rb_intern("error")) {
+      n = FIO_LOG_LEVEL_ERROR;
+    } else if (id == rb_intern("warn") || id == rb_intern("warning")) {
+      n = FIO_LOG_LEVEL_WARNING;
+    } else if (id == rb_intern("info")) {
+      n = FIO_LOG_LEVEL_INFO;
+    } else if (id == rb_intern("debug")) {
+      n = FIO_LOG_LEVEL_DEBUG;
+    } else {
+      rb_raise(rb_eArgError,
+               "unknown log level: :%s (expected :none, :fatal, :error, "
+               ":warn, :info or :debug)",
+               rb_id2name(id));
+      return Qnil;
+    }
+  } else {
+    rb_check_type(level, RUBY_T_FIXNUM);
+    long lng = RB_FIX2INT(level);
+    if (lng < FIO_LOG_LEVEL_NONE || lng > FIO_LOG_LEVEL_DEBUG) {
+      rb_raise(rb_eArgError, "log level must be between 0 and 5");
+      return Qnil;
+    }
+    n = (int)lng;
+  }
+  FIO_LOG_LEVEL_SET(n);
+  return level;
+  (void)self;
+}
+
+/* *****************************************************************************
+Initialization
+***************************************************************************** */
+
+/**
+ * Initializes the Iodine::Logger module.
+ */
+static void Init_Iodine_Logger(void) {
+  iodine_rb_IODINE_LOGGER = rb_define_module_under(iodine_rb_IODINE, "Logger");
+  STORE.hold(iodine_rb_IODINE_LOGGER);
+
+  /* Log level constants (mirroring the facil.io FIO_LOG_LEVEL_* values) */
+  rb_define_const(iodine_rb_IODINE_LOGGER,
+                  "NONE",
+                  RB_INT2FIX(FIO_LOG_LEVEL_NONE));
+  rb_define_const(iodine_rb_IODINE_LOGGER,
+                  "FATAL",
+                  RB_INT2FIX(FIO_LOG_LEVEL_FATAL));
+  rb_define_const(iodine_rb_IODINE_LOGGER,
+                  "ERROR",
+                  RB_INT2FIX(FIO_LOG_LEVEL_ERROR));
+  rb_define_const(iodine_rb_IODINE_LOGGER,
+                  "WARN",
+                  RB_INT2FIX(FIO_LOG_LEVEL_WARNING));
+  rb_define_const(iodine_rb_IODINE_LOGGER,
+                  "INFO",
+                  RB_INT2FIX(FIO_LOG_LEVEL_INFO));
+  rb_define_const(iodine_rb_IODINE_LOGGER,
+                  "DEBUG",
+                  RB_INT2FIX(FIO_LOG_LEVEL_DEBUG));
+
+  /* Leveled logging methods (module functions: callable on the module and
+   * available as private instance methods when included) */
+  rb_define_module_function(iodine_rb_IODINE_LOGGER,
+                            "fatal",
+                            iodine_log_fatal,
+                            -1);
+  rb_define_module_function(iodine_rb_IODINE_LOGGER,
+                            "error",
+                            iodine_log_error,
+                            -1);
+  rb_define_module_function(iodine_rb_IODINE_LOGGER,
+                            "warn",
+                            iodine_log_warn,
+                            -1);
+  rb_define_module_function(iodine_rb_IODINE_LOGGER,
+                            "info",
+                            iodine_log_info,
+                            -1);
+  rb_define_module_function(iodine_rb_IODINE_LOGGER,
+                            "debug",
+                            iodine_log_debug,
+                            -1);
+  rb_define_module_function(iodine_rb_IODINE_LOGGER,
+                            "<<",
+                            iodine_log_lshift,
+                            -1);
+
+  /* Level helpers */
+  rb_define_module_function(iodine_rb_IODINE_LOGGER,
+                            "level",
+                            iodine_log_level,
+                            0);
+  rb_define_module_function(iodine_rb_IODINE_LOGGER,
+                            "level=",
+                            iodine_log_level_set,
+                            1);
+}
+
+#endif /* H___IODINE_LOG___H */