iodine 0.7.60 → 0.8.0

data/ext/iodine/iodine_caller.h

@@ -1,27 +1,236 @@
-#ifndef H_IODINE_CALLER_H
-#define H_IODINE_CALLER_H
-
-#include "ruby.h"
-
-#include <stdint.h>
-
-extern struct IodineCaller_s {
-  /** Calls a C function within the GVL (unprotected). */
-  void *(*enterGVL)(void *(*func)(void *), void *arg);
-  /** Calls a C function outside the GVL (no Ruby API calls allowed). */
-  void *(*leaveGVL)(void *(*func)(void *), void *arg);
-  /** Calls a Ruby method on a given object, protecting against exceptions. */
-  VALUE (*call)(VALUE obj, ID method);
-  /** Calls a Ruby method on a given object, protecting against exceptions. */
-  VALUE (*call2)(VALUE obj, ID method, int argc, VALUE *argv);
-  /** Calls a Ruby method on a given object, protecting against exceptions. */
-  VALUE(*call_with_block)
-  (VALUE obj, ID method, int argc, VALUE *argv, VALUE udata,
-   VALUE (*block_func)(VALUE block_argv1, VALUE udata, int argc, VALUE *argv));
-  /** Returns the GVL state flag. */
-  uint8_t (*in_GVL)(void);
-  /** Forces the GVL state flag. */
-  void (*set_GVL)(uint8_t state);
-} IodineCaller;
+#ifndef H___IODINE_CALLER___H
+#define H___IODINE_CALLER___H
+#include "iodine.h"
+
+/* *****************************************************************************
+Ruby Caller and Thread (GVL) Helper
+
+From within the GVL call Ruby functions so:
+
+    iodine_caller_result_s r = iodine_ruby_call_inside(recv, mid,
+                                                       argc, argv, proc);
+
+From outside the GVL call Ruby functions so:
+
+    iodine_caller_result_s r = iodine_ruby_call_outside(recv, mid, argc, argv);
+
+When GVL state is ambiguous (may or may not hold it) call Ruby functions so:
+
+    iodine_caller_result_s r = iodine_ruby_call_anywhere(recv, mid, argc, argv);
+
+***************************************************************************** */
+
+/* printout backtrace in case of exceptions */
+static void *iodine_handle_exception(void *ignr) {
+  (void)ignr;
+  FIO_LOG_ERROR("(%d) iodine catching an exposed exception", fio_io_pid());
+  VALUE exc = rb_errinfo();
+  if (exc != Qnil && rb_respond_to(exc, rb_intern("message")) &&
+      rb_respond_to(exc, rb_intern("backtrace"))) {
+    VALUE msg = rb_funcallv(exc, rb_intern("message"), 0, NULL);
+    VALUE exc_class = rb_class_name(CLASS_OF(exc));
+    VALUE bt = rb_funcallv(exc, rb_intern("backtrace"), 0, NULL);
+    if (msg == Qnil)
+      msg = rb_str_new("Error message unavailable", 25);
+    if (exc_class == Qnil)
+      exc_class = rb_str_new("unknown exception class", 23);
+    if (TYPE(bt) == RUBY_T_ARRAY) {
+      bt = rb_ary_join(bt, rb_str_new_literal("\n"));
+      FIO_LOG_ERROR("exposed exception message: %.*s: %.*s\n %s ",
+                    (int)RSTRING_LEN(exc_class),
+                    RSTRING_PTR(exc_class),
+                    (int)RSTRING_LEN(msg),
+                    RSTRING_PTR(msg),
+                    StringValueCStr(bt));
+    } else if (TYPE(bt) == RUBY_T_STRING) {
+      FIO_LOG_ERROR("exposed exception message: %.*s: %.*s\n"
+                    "No backtrace available.\n",
+                    (int)RSTRING_LEN(exc_class),
+                    RSTRING_PTR(exc_class),
+                    (int)RSTRING_LEN(msg),
+                    RSTRING_PTR(msg));
+    } else {
+      FIO_LOG_ERROR("exposed exception message: %.*s: %.*s\n %s\n"
+                    "BACKTRACE UNAVAILABLE!\n",
+                    (int)RSTRING_LEN(exc_class),
+                    RSTRING_PTR(exc_class),
+                    (int)RSTRING_LEN(msg),
+                    RSTRING_PTR(msg));
+      FIO_LOG_ERROR("Backtrace missing.");
+    }
+    rb_backtrace();
+    FIO_LOG_ERROR("\n");
+    rb_set_errinfo(Qnil);
+  } else if (exc != Qnil) {
+    FIO_LOG_ERROR("exposed exception message: NO MESSAGE / DATA AVAILABLE");
+  }
+  return (void *)Qnil;
+}
+
+typedef struct {
+  VALUE recv;
+  ID mid;
+  int argc;
+  VALUE *argv;
+  VALUE proc;
+  int ignore_exceptions;
+} iodine_caller_args_s;
+
+typedef struct {
+  VALUE result;
+  int exception;
+} iodine_caller_result_s;
+
+typedef struct {
+  iodine_caller_args_s in;
+  iodine_caller_result_s out;
+} iodine___caller_s;
+
+static VALUE iodine___func_caller_task(VALUE args_) {
+  iodine_caller_args_s *args = (iodine_caller_args_s *)args_;
+  return rb_funcallv(args->recv, args->mid, args->argc, args->argv);
+}
+
+static VALUE iodine___func_caller_task_proc(VALUE args_) {
+  iodine_caller_args_s *args = (iodine_caller_args_s *)args_;
+  return rb_funcall_with_block(args->recv,
+                               args->mid,
+                               args->argc,
+                               args->argv,
+                               args->proc);
+}
+
+static void *iodine_ruby____outside_task_proc(void *c_) {
+  iodine___caller_s *c = (iodine___caller_s *)c_;
+  c->out.result = rb_protect(iodine___func_caller_task_proc,
+                             (VALUE)&c->in,
+                             &c->out.exception);
+  if (c->out.exception && !c->in.ignore_exceptions)
+    iodine_handle_exception(NULL);
+  return NULL;
+}
+
+static void *iodine_ruby____outside_task(void *c_) {
+  iodine___caller_s *c = (iodine___caller_s *)c_;
+  c->out.result =
+      rb_protect(iodine___func_caller_task, (VALUE)&c->in, &c->out.exception);
+  if (c->out.exception && !c->in.ignore_exceptions)
+    iodine_handle_exception(NULL);
+  return NULL;
+}
+
+/* *****************************************************************************
+Ruby Caller and Thread (GVL) - Helper Implementation
+***************************************************************************** */
+
+/*
+Calls a function from inside the GVL.
+
+Accepts the following, possibly named, arguments:
+
+  (VALUE recv,   ID mid,     int argc,
+   VALUE *argv,  VALUE proc, int ignore_exceptions)
+
+*/
+inline static iodine_caller_result_s iodine_ruby_call_inside(
+    iodine_caller_args_s args) {
+  iodine_caller_result_s r = {0};
+  FIO_ASSERT_DEBUG(args.recv && args.mid,
+                   "iodine_ruby_call requires an object and method name");
+  VALUE stub[1] = {Qnil};
+  if (!args.argv)
+    args.argv = stub;
+  r.result = rb_protect(
+      (args.proc ? iodine___func_caller_task_proc : iodine___func_caller_task),
+      (VALUE)&args,
+      &r.exception);
+  if (r.exception)
+    iodine_handle_exception(NULL);
+  return r;
+}
+
+/*
+Calls a function from outside the GVL, acquiring the lock and then releasing it.
+
+All call sites are from IO/worker threads that do NOT hold the GVL.
+For ambiguous GVL state, use iodine_ruby_call_anywhere instead.
+
+Accepts the following, possibly named, arguments:
+
+  (VALUE recv,   ID mid,     int argc,
+   VALUE *argv,  VALUE proc, int ignore_exceptions)
+
+*/
+inline static iodine_caller_result_s iodine_ruby_call_outside(
+    iodine_caller_args_s args) {
+  VALUE stub[1] = {Qnil};
+  if (!args.argv)
+    args.argv = stub;
+  iodine___caller_s r = {args, {0}};
+  FIO_ASSERT_DEBUG(args.recv && args.mid,
+                   "iodine_ruby_call requires an object and method name");
+  void *(*fn)(void *) = args.proc ? iodine_ruby____outside_task_proc
+                                  : iodine_ruby____outside_task;
+  rb_thread_call_with_gvl(fn, &r);
+  return r.out;
+}
+
+/**
+Calls a function from inside the GVL.
+
+Accepts the following, possibly named, arguments:
+
+  (VALUE recv,   ID mid,     int argc,
+   VALUE *argv,  VALUE proc, int ignore_exceptions)
+
+*/
+#define iodine_ruby_call_inside(...)                                           \
+  iodine_ruby_call_inside((iodine_caller_args_s){__VA_ARGS__})
+
+/**
+Calls a function from outside the GVL, aquiring the lock and then releasing it.
+
+Accepts the following, possibly named, arguments:
+
+  (VALUE recv,   ID mid,     int argc,
+   VALUE *argv,  VALUE proc, int ignore_exceptions)
+
+*/
+#define iodine_ruby_call_outside(...)                                          \
+  iodine_ruby_call_outside((iodine_caller_args_s){__VA_ARGS__})
+
+/**
+For code paths where the calling thread may or may not hold the GVL.
+
+On Ruby 3.x and 4.x (current path): checks ruby_thread_has_gvl_p() at runtime.
+
+NOTE: Ruby Feature #20750 (merged Dec 2025) made rb_thread_call_with_gvl()
+GVL-lenient on Ruby 4.x — safe to call whether or not GVL is held.
+The `&& 0` gate below preserves the safe runtime-check path on all versions
+until the lenient behaviour is confirmed present in every supported Ruby 4.x
+release used in CI. To activate the simplified Ruby 4 fast path, remove
+`&& 0` once Ruby 4.0.1+ GVL-lenience is verified in CI.
+*/
+#if RUBY_API_VERSION_MAJOR >= 4 && 0
+#define iodine_ruby_call_anywhere(...)                                         \
+  iodine_ruby_call_outside((iodine_caller_args_s){__VA_ARGS__})
+#define iodine_c_call_with(fn, args) rb_thread_call_with_gvl(fn, args)
+#define iodine_c_call_without(fn, args)                                        \
+  rb_thread_call_without_gvl(fn, args, NULL, NULL)
+
+#else
+#define iodine_ruby_call_anywhere(...)                                         \
+  (ruby_thread_has_gvl_p()                                                     \
+       ? iodine_ruby_call_inside                                               \
+       : iodine_ruby_call_outside)((iodine_caller_args_s){__VA_ARGS__})
+
+#define iodine_c_call_with(fn, args)                                           \
+  (ruby_thread_has_gvl_p() ? (fn)(args) : rb_thread_call_with_gvl(fn, args))
+
+#define iodine_c_call_without(fn, args)                                        \
+  (ruby_thread_has_gvl_p() ? rb_thread_call_without_gvl(fn, args, NULL, NULL)  \
+                           : (fn)(args))
 
 #endif
+
+#endif /* H___IODINE_CALLER___H */

data/ext/iodine/iodine_cli.h

@@ -0,0 +1,434 @@
+#ifndef H___IODINE_CLI___H
+#define H___IODINE_CLI___H
+#include "iodine.h"
+
+/* *****************************************************************************
+Iodine CLI - Command Line Interface Parsing
+
+This module provides the Iodine::Base::CLI Ruby module for parsing and
+managing command-line arguments. It wraps facil.io's CLI parser with
+Ruby-friendly access.
+
+Features:
+- Parses ARGV with support for named and positional arguments
+- Supports various argument types: strings, integers, booleans
+- Provides default values from environment variables (THREADS, WORKERS, etc.)
+- Configures TLS, RESP3, clustering, and HTTP settings
+
+CLI Options (parsed from command line):
+- Address: -b/--bind, -p/--port
+- Concurrency: -t/--threads, -w/--workers
+- HTTP: --public, --max-line, --max-header, --max-body, --keep-alive, --log
+- WebSocket/SSE: --ws-max-msg, --timeout
+- TLS: --tls-self, --tls-name, --tls-cert, --tls-key, --tls-password
+- Clustering: --broadcast, --secret
+- RESP3: --redis, --redis-ping
+- Hot Restart: --hot-restart, --config, --preload
+- Misc: --verbose, --rack, --pid, --contained
+
+Ruby API (Iodine::Base::CLI):
+- CLI.parse(required)  - Parse ARGV, returns Hash of options
+- CLI[key]             - Get CLI option value
+- CLI[key] = value     - Set CLI option value (before start only)
+
+Environment Variables:
+- THREADS, WORKERS     - Default thread/worker counts
+- ADDRESS, PORT        - Default binding address/port
+- SECRET               - Cluster secret key
+- IODINE_MTLS          - Enable embedded TLS 1.3
+***************************************************************************** */
+
+/** Maximum number of CLI arguments supported */
+#define IODINE_CLI_LIMIT 256
+
+static int iodine_cli_task(fio_buf_info_s name,
+                           fio_buf_info_s val,
+                           fio_cli_arg_e t,
+                           void *h_) {
+  static long at = 0;
+  VALUE h = (VALUE)h_;
+  VALUE tmp = Qnil;
+  VALUE n = Qnil;
+  VALUE v = Qnil;
+  switch (t) {
+  case FIO_CLI_ARG_BOOL: v = Qtrue; break;
+  case FIO_CLI_ARG_INT: v = RB_LL2NUM(fio_atol(&val.buf)); break;
+  default: v = rb_str_new(val.buf, val.len); break;
+  }
+  STORE.cache(v);
+  if (name.buf) {
+    at = 0;
+    while (name.buf[0] == '-') {
+      ++name.buf;
+      --name.len;
+    }
+    n = rb_str_new(name.buf, name.len);
+    STORE.cache(n);
+  } else {
+    n = RB_INT2FIX(at);
+    ++at;
+  }
+  rb_hash_aset(h, n, v);
+  if (RB_TYPE_P(n, RUBY_T_STRING)) {
+    tmp = rb_str_intern(n);
+    STORE.cache((n = tmp));
+    rb_hash_aset(h, n, v);
+  }
+  return 0;
+}
+
+/* *****************************************************************************
+Ruby Public API.
+***************************************************************************** */
+/* used here, defined later */
+static VALUE iodine_tls_default_set(VALUE klass, VALUE backend);
+
+FIO_IFUNC bool iodine___mtls_env(void) {
+  bool ret = 0;
+  char *e = fio_sys_env("IODINE_MTLS");
+  if (!e)
+    return ret;
+  fio_str_info_s s = FIO_STR_INFO1(e);
+  fio_str_info_s untrue = FIO_STR_INFO1((char *)"false");
+  fio_str_info_s untrue2 = FIO_STR_INFO1((char *)"0");
+  ret = (bool)(1UL ^ ((unsigned)(FIO_STR_INFO_IS_EQ(s, untrue)) |
+                      FIO_STR_INFO_IS_EQ(s, untrue2)));
+  return ret;
+}
+
+/** Read CLI as required data. */
+static VALUE iodine_cli_parse(VALUE self, VALUE required) {
+  if (!RB_TYPE_P(rb_argv, RUBY_T_ARRAY))
+    rb_raise(rb_eException, "ARGV should be an Array!");
+  FIO_STR_INFO_TMP_VAR(desc, 2048);
+  FIO_STR_INFO_TMP_VAR(threads, 128);
+  FIO_STR_INFO_TMP_VAR(workers, 128);
+  const char *argv[IODINE_CLI_LIMIT];
+  const char *threads_env = NULL;
+  const char *workers_env = NULL;
+  long len = 0;
+  VALUE iodine_version = rb_const_get(iodine_rb_IODINE, rb_intern("VERSION"));
+
+  /* I don't know if Ruby promises a NUL separator, but fio_bstr does. */
+  if (rb_argv0 && RB_TYPE_P(rb_argv0, RUBY_T_STRING)) {
+    argv[len++] =
+        fio_bstr_write(NULL, RSTRING_PTR(rb_argv0), RSTRING_LEN(rb_argv0));
+  } else
+    argv[len++] = (const char *)"iodine";
+  for (long i = 0; len < IODINE_CLI_LIMIT && i < rb_array_len(rb_argv); ++i) {
+    VALUE o = rb_ary_entry(rb_argv, i);
+    if (!RB_TYPE_P(o, RUBY_T_STRING)) {
+      FIO_LOG_WARNING("ARGV member skipped - not a String!");
+      continue;
+    }
+    argv[len++] = fio_bstr_write(NULL, RSTRING_PTR(o), RSTRING_LEN(o));
+  }
+
+  /* in case of `-h` or error, make sure we clean up */
+  for (long i = 0; i < len; ++i)
+    fio_state_callback_add(FIO_CALL_AT_EXIT,
+                           (void (*)(void *))fio_bstr_free,
+                           (void *)argv[i]);
+
+  threads_env = fio_sys_env("THREADS");
+  workers_env = fio_sys_env("WORKERS");
+
+  fio_string_write2(
+      &threads,
+      NULL,
+      FIO_STRING_WRITE_STR1("--threads -t ("),
+      (threads_env ? FIO_STRING_WRITE_STR1(threads_env)
+                   : FIO_STRING_WRITE_STR1("-4")),
+      FIO_STRING_WRITE_STR1(") number of worker threads to use."));
+  fio_string_write2(
+      &workers,
+      NULL,
+      FIO_STRING_WRITE_STR1("--workers -w ("),
+      (workers_env ? FIO_STRING_WRITE_STR1(workers_env)
+                   : FIO_STRING_WRITE_STR1("-2")),
+      FIO_STRING_WRITE_STR1(") number of worker processes to use."));
+
+  fio_string_write2(
+      &desc,
+      NULL,
+      FIO_STRING_WRITE_STR1("Iodine's (" FIO_POLL_ENGINE_STR
+                            ") HTTP/WebSocket server version "),
+      FIO_STRING_WRITE_STR2(RSTRING_PTR(iodine_version),
+                            (size_t)RSTRING_LEN(iodine_version)),
+      FIO_STRING_WRITE_STR1(
+          "\r\n\r\nUse:\r\n    iodine <options> <filename>\r\n\r\n"
+          "Both <options> and <filename> are optional. i.e.,:\r\n"
+          "    iodine -p 0 -b /tmp/my_unix_sock\r\n"
+          "    iodine -p 8080 path/to/app/config.ru\r\n"
+          "    iodine -p 8080 path/to/app/config.nru\r\n"
+          "    iodine -p 8080 -w 4 -t 16\r\n"
+          "    iodine -w -1 -t 4 -r redis://usr:pass@localhost:6379/\r\n\r\n"
+          "Default <filename> if unspecified: `config.nru` and `config.ru`"));
+
+  fio_cli_end();
+  fio_cli_start(
+      (int)len,
+      (const char **)argv,
+      0,
+      ((required == Qnil || required == Qfalse) ? -1 : 1),
+      desc.buf,
+      FIO_CLI_PRINT_HEADER("Address Binding"),
+      FIO_CLI_PRINT_LINE(
+          "NOTE: also controlled by the ADDRESS or PORT environment vars."),
+      FIO_CLI_STRING(
+          "-bind -b address to listen to in URL format (MAY include PORT)."),
+      FIO_CLI_PRINT(
+          "It's possible to add TLS/SSL data to the binding URL. i.e.:"),
+      FIO_CLI_PRINT("\t iodine -b https://0.0.0.0/?tls=./cert_path/"),
+      FIO_CLI_PRINT(
+          "\t iodine -b https://0.0.0.0/?key=./key.pem&cert=./cert.pem"),
+      FIO_CLI_PRINT("TLS client authentication / trust is available. i.e.:"),
+      FIO_CLI_PRINT("\t iodine -b https://0.0.0.0/?trust=ca.pem"),
+      FIO_CLI_PRINT("\t iodine -b https://0.0.0.0/?trust=system"),
+      FIO_CLI_INT("-port -p default port number to listen to."),
+      FIO_CLI_PRINT(
+          "Note: these are optional and supersede previous instructions."),
+
+      FIO_CLI_PRINT_HEADER("Concurrency"),
+      FIO_CLI_INT(threads.buf),
+      FIO_CLI_INT(workers.buf),
+
+      FIO_CLI_PRINT_HEADER("HTTP"),
+      FIO_CLI_STRING("--public -www public folder for static file service."),
+      FIO_CLI_INT("--max-line -maxln (" FIO_MACRO2STR(
+          FIO_HTTP_DEFAULT_MAX_LINE_LEN) ") per-header line limit, in bytes."),
+      FIO_CLI_INT("--max-header -maxhd (" FIO_MACRO2STR(
+          FIO_HTTP_DEFAULT_MAX_HEADER_SIZE) ") total header limit per request, "
+                                            "in bytes."),
+      FIO_CLI_INT("--max-body -maxbd (" FIO_MACRO2STR(
+          FIO_HTTP_DEFAULT_MAX_BODY_SIZE) ") total message payload limit per "
+                                          "request, in bytes."),
+      FIO_CLI_INT("--keep-alive -k (" FIO_MACRO2STR(
+          FIO_HTTP_DEFAULT_TIMEOUT) ") HTTP keep-alive timeout in seconds "
+                                    "(0..255)"),
+      FIO_CLI_INT("--max-age -maxage (3600) default Max-Age header value for "
+                  "static files."),
+      FIO_CLI_BOOL("--no-dynamic-deflate -no-dynd Disable dynamic deflation of "
+                   "HTTP replies."),
+      FIO_CLI_BOOL("--log -v log HTTP messages."),
+
+      FIO_CLI_PRINT_HEADER("WebSocket / SSE"),
+      FIO_CLI_BOOL("--no-websocket-deflate -no-wsd Disable WebSocket "
+                   "permessage-deflate."),
+      FIO_CLI_INT("--ws-max-msg -maxms (" FIO_MACRO2STR(
+          FIO_HTTP_DEFAULT_WS_MAX_MSG_SIZE) ") incoming WebSocket message "
+                                            "limit, in bytes."),
+      FIO_CLI_INT("--timeout -ping (" FIO_MACRO2STR(
+          FIO_HTTP_DEFAULT_TIMEOUT_LONG) ") WebSocket / SSE timeout, in "
+                                         "seconds."),
+
+      FIO_CLI_PRINT_HEADER("TLS / SSL"),
+      FIO_CLI_PRINT(
+          "NOTE: may crash if no crypto implementation is available."),
+      FIO_CLI_BOOL(
+          "--tls-self -tls uses SSL/TLS with a self signed certificate."),
+      FIO_CLI_STRING("--tls-name -name The host name for the SSL/TLS "
+                     "certificate (if any)."),
+      FIO_CLI_STRING("--tls-cert -cert The SSL/TLS certificate .pem file."),
+      FIO_CLI_STRING("--tls-key -key The SSL/TLS private key .pem file."),
+      FIO_CLI_STRING(
+          "--tls-password -tls-pass The SSL/TLS password for the private key."),
+      FIO_CLI_BOOL("--tls-embedded -mtls uses facil.io's minimal TLS 1.3 "
+                   "implementation."),
+      FIO_CLI_PRINT(
+          "NOTE: facil.io's TLS 1.3 was never audited, but could be useful."),
+
+      FIO_CLI_PRINT_HEADER("Clustering Pub/Sub"),
+      FIO_CLI_INT("--broadcast -bp Cluster Broadcast Port."),
+      FIO_CLI_STRING("--secret -scrt Cluster Secret."),
+      FIO_CLI_PRINT("NOTE: also controlled by the SECRET and SECRET_LENGTH "
+                    "environment vars."),
+
+      FIO_CLI_PRINT_HEADER("Connecting Iodine to a RESP3 Database:"),
+      FIO_CLI_STRING(
+          "--redis -r an optional RESP3 database URL (e.g., Valkey or Redis)."),
+      FIO_CLI_INT("--redis-ping -rp RESP3 ping interval in seconds."),
+
+      FIO_CLI_PRINT_HEADER("Hot Application Swapping / Restarts"),
+      FIO_CLI_PRINT_LINE(
+          "(requires cluster mode, app code runs only in workers)"),
+      FIO_CLI_INT(
+          "--hot-restart -hr restarts all worker processes every n seconds."),
+      FIO_CLI_STRING(
+          "--config -C (config/boot.rb) configuration file to be loaded."),
+      FIO_CLI_PRINT("NOTE: the code in the --config file won't be updated."),
+      FIO_CLI_BOOL("--preload -preload loads the app code before forking "
+                   "(cluster only)."),
+      FIO_CLI_PRINT(
+          "NOTE: otherwise only the --config file will run in root process."),
+
+      FIO_CLI_PRINT_HEADER("Misc"),
+      FIO_CLI_BOOL("--verbose -V -d print out debugging messages."),
+      FIO_CLI_BOOL("--rack -R -rack prefer Rack::Builder over NeoRack."),
+      FIO_CLI_STRING(
+          "--pid -pidfile -pid name for the pid file to be created."),
+      FIO_CLI_BOOL(
+          "--contained attempts to handle possible container restrictions."),
+      FIO_CLI_PRINT(
+          "Containers sometimes impose file-system restrictions, i.e.,"),
+      FIO_CLI_PRINT("the IPC Unix Socket might need to be placed in `/tmp`."));
+
+  /* review CLI for logging */
+  if (fio_cli_get_bool("-V")) {
+    FIO_LOG_LEVEL = FIO_LOG_LEVEL_DEBUG;
+  }
+
+  if (fio_cli_get_bool("-mtls") || iodine___mtls_env()) {
+    fio_io_functions_s io_fn;
+    io_fn = fio_tls13_io_functions();
+    fio_io_tls_default_functions(&io_fn);
+    iodine_tls_default_set(Qnil, ID2SYM(rb_intern("iodine")));
+    fio_cli_set("-tls", "1");
+    FIO_LOG_DEBUG2("TLS 1.3 registered as default TLS implementation");
+  }
+
+  if (fio_cli_get_bool("--contained")) { /* container - IPC url in tmp */
+    char *u = (char *)fio_ipc_url();
+    memcpy((void *)(u + 7), "/tmp/", 5);
+  }
+
+  /* Secret Detection */
+  if (fio_cli_get("-scrt")) {
+    fio_buf_info_s scrt = FIO_BUF_INFO1((char *)fio_cli_get("-scrt"));
+    fio_secret_set(scrt.buf, scrt.len, 0);
+  }
+
+  /* Clustering */
+  if (!fio_cli_get_i("-bp") && fio_sys_env("PUBSUB_PORT")) {
+    char *bp_s = fio_sys_env("PUBSUB_PORT");
+    int64_t bp = fio_atol(&bp_s);
+    if (bp > 0 && bp < 0xFFFFLL)
+      fio_cli_set("-bp", fio_sys_env("PUBSUB_PORT"));
+  }
+  if (fio_cli_get_i("-bp") > 0) {
+    fio_ipc_cluster_listen((uint16_t)fio_cli_get_i("-bp"));
+  }
+
+  /* support -b and -p for when a URL isn't provided */
+  if (fio_cli_get("-p")) {
+    fio_buf_info_s tmp = fio_cli_get_str("-b");
+    if (tmp.buf) {
+      FIO_STR_INFO_TMP_VAR(url, 2048);
+      FIO_ASSERT(tmp.len < 2000, "binding address / url too long.");
+      fio_url_s u = fio_url_parse(tmp.buf, tmp.len);
+      tmp.buf = (char *)fio_cli_get("-p");
+      tmp.len = strlen(tmp.buf);
+      FIO_ASSERT(tmp.len < 6, "port number too long.");
+      fio_string_write2(&url,
+                        NULL,
+                        FIO_STRING_WRITE_STR2(u.scheme.buf, u.scheme.len),
+                        (u.scheme.len ? FIO_STRING_WRITE_STR2("://", 3)
+                                      : FIO_STRING_WRITE_STR2(NULL, 0)),
+                        FIO_STRING_WRITE_STR2(u.host.buf, u.host.len),
+                        FIO_STRING_WRITE_STR2(":", 1),
+                        FIO_STRING_WRITE_STR2(tmp.buf, tmp.len),
+                        (u.query.len ? FIO_STRING_WRITE_STR2("?", 1)
+                                     : FIO_STRING_WRITE_STR2(NULL, 0)),
+                        FIO_STRING_WRITE_STR2(u.query.buf, u.query.len));
+      fio_cli_set("-b", url.buf);
+    } else {
+      fio_sys_env_set("PORT", fio_cli_get("-p"), 1);
+    }
+  }
+
+  /* Save data to Hash and return it... why? I don't know. */
+  VALUE h = rb_hash_new();
+  STORE.hold(h);
+  fio_cli_each(iodine_cli_task, (void *)h);
+  /* cleanup */
+  for (long i = 0; i < len; ++i) {
+    fio_state_callback_remove(FIO_CALL_AT_EXIT,
+                              (void (*)(void *))fio_bstr_free,
+                              (void *)argv[i]);
+    fio_bstr_free((char *)argv[i]);
+  }
+  STORE.release(h);
+  return h;
+}
+
+static VALUE iodine_cli_get(VALUE self, VALUE key) {
+  VALUE r = Qnil;
+  fio_buf_info_s val;
+  int64_t ival = 0;
+  char *tmp;
+  if (RB_INTEGER_TYPE_P(key)) {
+    val = fio_cli_unnamed_str(NUM2UINT(key));
+    if (val.buf)
+      r = rb_str_new(val.buf, val.len);
+    return r;
+  }
+  if (RB_TYPE_P(key, RUBY_T_SYMBOL))
+    key = rb_sym2str(key);
+  if (!RB_TYPE_P(key, RUBY_T_STRING))
+    rb_raise(rb_eArgError,
+             "key should be either an Integer, a String or a Symbol");
+  val = fio_cli_get_str(RSTRING_PTR(key));
+  if (!val.len)
+    return r;
+  tmp = val.buf;
+  ival = fio_atol(&tmp);
+  if (tmp == val.buf + val.len)
+    r = LL2NUM(ival);
+  else
+    r = rb_str_new(val.buf, val.len);
+  return r;
+}
+
+static VALUE iodine_cli_set(VALUE self, VALUE key, VALUE value) {
+  if (fio_io_is_running() || !fio_io_is_master())
+    rb_raise(rb_eException,
+             "Setting CLI arguments can only be performed before Iodine.start "
+             "and in the master process.");
+  if (RB_INTEGER_TYPE_P(key)) {
+    if (!RB_TYPE_P(value, RUBY_T_STRING))
+      rb_raise(rb_eArgError,
+               "value for an indexed CLI argument should be a String");
+    fio_cli_set_unnamed(NUM2UINT(key), RSTRING_PTR(value));
+    return value;
+  }
+  if (RB_TYPE_P(key, RUBY_T_SYMBOL))
+    key = rb_sym2str(key);
+  if (!RB_TYPE_P(key, RUBY_T_STRING))
+    rb_raise(rb_eArgError,
+             "key should be either an Integer, a String or a Symbol");
+  fio_cli_arg_e t = fio_cli_type(RSTRING_PTR(key));
+  if (t == FIO_CLI_ARG_INT) { /* Number */
+    if (!RB_INTEGER_TYPE_P(value))
+      rb_raise(rb_eArgError,
+               "value for %s should be an Integer",
+               RSTRING_PTR(key));
+    fio_cli_set_i(RSTRING_PTR(key), NUM2LL(value));
+  } else if (t == FIO_CLI_ARG_BOOL) { /* Boolean */
+    if (value != Qtrue && value != Qfalse)
+      rb_raise(rb_eArgError,
+               "value for %s should be a Boolean",
+               RSTRING_PTR(key));
+    fio_cli_set_i(RSTRING_PTR(key), NUM2LL((value == Qtrue)));
+
+  } else { /* must be String */
+    if (!RB_TYPE_P(value, RUBY_T_STRING))
+      rb_raise(rb_eArgError,
+               "value for %s should be a String",
+               RSTRING_PTR(key));
+    fio_cli_set(RSTRING_PTR(key), RSTRING_PTR(value));
+  }
+  return value;
+}
+
+/** Initialize Iodine::Base::CLI */
+/**
+ * The Iodine::Base::CLI module is used internally to manage CLI options.
+ */
+static void Init_Iodine_Base_CLI(void) {
+  VALUE cli = rb_define_module_under(iodine_rb_IODINE_BASE, "CLI");
+  rb_define_singleton_method(cli, "parse", iodine_cli_parse, 1);
+  rb_define_singleton_method(cli, "[]", iodine_cli_get, 1);
+  rb_define_singleton_method(cli, "[]=", iodine_cli_set, 2);
+  iodine_cli_parse(cli, Qfalse);
+}
+#endif /* H___IODINE_CLI___H */