iodine 0.3.6 → 0.4.0

data/ext/iodine/websockets.h

@@ -9,6 +9,10 @@ Feel free to copy, use and enjoy according to the license provided.
 
 #include "http.h"
 
+/* *****************************************************************************
+Upgrading from HTTP to Websockets
+***************************************************************************** */
+
 /**
 The Websocket type is an opaque type used by the websocket API to provide
 identify a specific Websocket connection and manage it's internal state.
@@ -109,8 +113,20 @@ ssize_t websocket_upgrade(websocket_settings_s settings);
 #define websocket_upgrade(...)                                                 \
   websocket_upgrade((websocket_settings_s){__VA_ARGS__})
 
+/* *****************************************************************************
+Websocket information
+***************************************************************************** */
+
 /** Returns the opaque user data associated with the websocket. */
 void *websocket_udata(ws_s *ws);
+
+/**
+Sets the opaque user data associated with the websocket.
+
+Returns the old value, if any.
+*/
+void *websocket_udata_set(ws_s *ws, void *udata);
+
 /**
 Returns the underlying socket UUID.
 
@@ -118,20 +134,157 @@ This is only relevant for collecting the protocol object from outside of
 websocket events, as the socket shouldn't be written to.
 */
 intptr_t websocket_uuid(ws_s *ws);
-/**
-Sets the opaque user data associated with the websocket.
 
-Returns the old value, if any.
+/**
+Counts the number of websocket connections.
 */
-void *websocket_udata_set(ws_s *ws, void *udata);
+size_t websocket_count(void);
+
+/* *****************************************************************************
+Websocket Connection Management (write / close)
+***************************************************************************** */
+
 /** Writes data to the websocket. Returns -1 on failure (0 on success). */
 int websocket_write(ws_s *ws, void *data, size_t size, uint8_t is_text);
 /** Closes a websocket connection. */
 void websocket_close(ws_s *ws);
+
+/* *****************************************************************************
+Websocket Pub/Sub
+=================
+
+API for websocket pub/sub that can be used to publish messages across process
+boundries.
+
+Supports pub/sub engines (see {pubsub.h}) that can connect to a backend service
+such as Redis.
+
+The default pub/sub engine (if `NULL` or unspecified) will publish the messages
+to the process cluster (all the processes in `facil_run`).
+
+To publish to a channel, use the API provided in {pubsub.h}.
+***************************************************************************** */
+
+/** Pub/sub engine type. Engine documentation is in `pubsub.h` */
+typedef struct pubsub_engine_s pubsub_engine_s;
+
+/** Incoming pub/sub messages will be passed along using this data structure. */
+typedef struct {
+  /** the websocket receiving the message. */
+  ws_s *ws;
+  /** the pub/sub engine from which where the message originated. */
+  struct pubsub_engine_s *engine;
+  /** the Websocket pub/sub subscription ID. */
+  uintptr_t subscription_id;
+  /** the channel where the message was published. */
+  struct {
+    const char *name;
+    size_t len;
+  } channel;
+  /** the published message. */
+  struct {
+    const char *data;
+    size_t len;
+  } msg;
+  /** Pattern matching was used for channel subscription. */
+  unsigned use_pattern : 1;
+  /** user opaque data. */
+  void *udata;
+} websocket_pubsub_notification_s;
+
+/** Possible arguments for the {websocket_subscribe} function. */
+struct websocket_subscribe_s {
+  /** the websocket receiving the message. REQUIRED. */
+  ws_s *ws;
+  /**
+   * The pub/sub engine to use.
+   *
+   * Default: engine will publish messages throughout the facil process cluster.
+   */
+  struct pubsub_engine_s *engine;
+  /** the channel where the message was published. */
+  struct {
+    const char *name;
+    size_t len;
+  } channel;
+  /**
+   * The callback that handles pub/sub notifications.
+   *
+   * Default: send directly to websocket client.
+   */
+  void (*on_message)(websocket_pubsub_notification_s notification);
+  /**
+   * An optional cleanup callback for the `udata`.
+   */
+  void (*on_unsubscribe)(void *udata);
+  /** User opaque data, passed along to the notification. */
+  void *udata;
+  /** Use pattern matching for channel subscription. */
+  unsigned use_pattern : 1;
+  /**
+   * When using client forwarding (no `on_message` callback), this indicates if
+   * messages should be sent to the client as binary blobs, which is the safest
+   * approach.
+   *
+   * Default: tests for UTF-8 data encoding and sends as text if valid UTF-8.
+   * Messages above ~32Kb are always assumed to be binary.
+   */
+  unsigned force_binary : 1;
+  /**
+   * When using client forwarding (no `on_message` callback), this indicates if
+   * messages should be sent to the client as text.
+   *
+   * `force_binary` has precedence.
+   *
+   * Default: see above.
+   *
+   */
+  unsigned force_text : 1;
+};
+
 /**
-Counts the number of websocket connections.
+ * Subscribes to a channel. See {struct websocket_subscribe_s} for possible
+ * arguments.
+ *
+ * Returns a subscription ID on success and 0 on failure.
+ *
+ * All subscriptions are automatically revoked once the websocket is closed.
+ *
+ * If the connections subscribes to the same channel more than once, messages
+ * will be merged. However, another subscription ID will be assigned, since two
+ * calls to {websocket_unsubscribe} will be required in order to unregister from
+ * the channel.
+ */
+uintptr_t websocket_subscribe(struct websocket_subscribe_s args);
+
+#define websocket_subscribe(wbsckt, ...)                                       \
+  websocket_subscribe((struct websocket_subscribe_s){.ws = wbsckt, __VA_ARGS__})
+
+/**
+ * Finds an existing subscription (in case the subscription ID wasn't saved).
+ * See {struct websocket_subscribe_s} for possible arguments.
+ *
+ * Returns the existing subscription's ID (if exists) or 0 (no subscription).
+ */
+uintptr_t websocket_find_sub(struct websocket_subscribe_s args);
+
+#define websocket_find_sub(wbsckt, ...)                                        \
+  websocket_find_sub((struct websocket_subscribe_s){.ws = wbsckt, __VA_ARGS__})
+
+/**
+ * Unsubscribes from a channel.
+ *
+ * Failures are silent.
+ *
+ * All subscriptions are automatically revoked once the websocket is closed. So
+ * only use this function to unsubscribe while the websocket is open.
+ */
+void websocket_unsubscribe(ws_s *ws, uintptr_t subscription_id);
+
+/* *****************************************************************************
+Websocket Tasks - within a single process scope, NOT and entire cluster
+*****************************************************************************
 */
-size_t websocket_count(void);
 
 /** The named arguments for `websocket_each` */
 struct websocket_each_args_s {

data/lib/iodine.rb

@@ -26,6 +26,92 @@ require 'iodine/iodine'
 #
 #
 # Please read the {file:README.md} file for an introduction to Iodine and an overview of it's API.
+#
+# == The API
+#
+# The main API methods for the top {Iodine} namesapce are grouped here by subject.
+#
+# === Event Loop / Concurrency
+#
+# Iodine manages an internal event-loop and reactor pattern. The following API
+# manages Iodine's behavior.
+#
+# * {Iodine.threads}, {Iodine.threads=} gets or sets the amount of threads iodine will use in it's working thread pool.
+# * {Iodine.processes}, {Iodine.processes} gets or sets the amount of processes iodine will utilize (`fork`) to handle connections.
+# * {Iodine.start} starts iodine's event loop and reactor pattern. At this point, it's impossible to change the number of threads or processes used.
+#
+# === Event and Task Scheduling
+#
+# * {Iodine.run} schedules a block of code to run asynchronously.
+# * {Iodine.run_after}, {Iodine.run_every} schedules a block of code to run (asynchronously) using a timer.
+# * {Iodine.start} starts iodine's event loop and reactor pattern. At this point, it's impossible to change the number of threads or processes used.
+#
+# In addition to the top level API, there's also the connection class and connection instance API, as specified in the {Iodine::Protocol} and {Iodine::Websocket} documentation, which allows for a connection bound task(s) to be scheduled to run within the connection's lock (for example, {Iodine::Websocket#defer} and {Iodine::Websocket#each}).
+#
+# === Connection Handling
+#
+# Iodine handles connections using {Iodine::Protocol} objects. The following API
+# manages either built-in or custom {Protocol} objects (classes / instances) in relation to their network sockets.
+#
+# * {Iodine.attach_fd}, {Iodine.attach_io} allows Iodine to take controll of an IO object (i.e., a TCP/IP Socket, a Unix Socket or a pipe).
+# * {Iodine.connect} creates a new TCP/IP connection using the specified Protocol.
+# * {Iodine.listen} listens to new TCP/IP connections using the specified Protocol.
+# * {Iodine.listen2http} listens to new TCP/IP connections using the buildin HTTP / Websocket Protocol.
+# * {Iodine.warmup} warms up and HTTP Rack applications.
+# * {Iodine.count} counts the number of connections (including HTTP / Websocket connections).
+# * {Iodine::Protocol.each} runs a code of block for every connection sharing the process (except HTTP / Websocket connections).
+# * {Iodine::Websocket.each} runs a code of block for every existing websocket sharing the process.
+#
+# In addition to the top level API, there's also the connection class and connection instance API, as specified in the {Iodine::Protocol} and {Iodine::Websocket} documentation.
+#
+# === Pub/Sub
+#
+# Iodine offers a native Pub/Sub engine (no database required) that can be easily extended by implementing a Pub/Sub {Iodine::PubSub::Engine}.
+#
+# The following methods offect server side Pub/Sub that allows the server code to react to channel event.
+#
+# * {Iodine.subscribe}, {Iodine.unsubscribe} manages a process's subscription to a channel (which is different than a connection's subscription, such as employed by {Iodine::Websocket}).
+# * {Iodine.publish} publishes a message to a Pub/Sub channel. The message will be sent to all subscribers - connections, other processes in the cluster and even other machines (when using the {Iodine::PubSub::RedisEngine}).
+# * {Iodine.default_pubsub=}, {Iodine.default_pubsub} sets or gets the default Pub/Sub {Iodine::PubSub::Engine}. i.e., when set to a new {Iodine::PubSub::RedisEngine} instance, all Pub/Sub method calls will use the Redis engine (unless explicitly requiring a different engine).
+#
+# {Iodine::Websocket} objects have a seperate Pub/Sub implementation that manages the subscription's lifetime to match the connection's lifetime and allows direct client Pub/Sub (forwards the message to the client directly).
+#
+# == Patching Rack
+#
+# Although Iodine offers Rack::Utils optimizations using monkey patching, Iodine does NOT monkey patch Rack automatically.
+#
+# Choosing to monkey patch Rack::Utils could offer significant performance gains for some applications. i.e. (on my machine):
+#
+#       require 'iodine'
+#       require 'rack'
+#       # a String in need of decoding
+#       s = '%E3%83%AB%E3%83%93%E3%82%A4%E3%82%B9%E3%81%A8'
+#       Benchmark.bm do |bm|
+#         # Pre-Patch
+#         bm.report("   Rack.unescape")    {1_000_000.times { Rack::Utils.unescape s } }
+#         bm.report("    Rack.rfc2822")    {1_000_000.times { Rack::Utils.rfc2822(Time.now) } }
+#         bm.report("    Rack.rfc2109")    {1_000_000.times { Rack::Utils.rfc2109(Time.now) } }
+#         # Perform Patch
+#         Iodine.patch_rack
+#         puts "            --- Monkey Patching Rack ---"
+#         # Post Patch
+#         bm.report("Patched.unescape")    {1_000_000.times { Rack::Utils.unescape s } }
+#         bm.report(" Patched.rfc2822")    {1_000_000.times { Rack::Utils.rfc2822(Time.now) } }
+#         bm.report(" Patched.rfc2109")    {1_000_000.times { Rack::Utils.rfc2109(Time.now) } }
+#       end && nil
+#
+# Results:
+#         user     system      total        real
+#         Rack.unescape  8.660000   0.010000   8.670000 (  8.687807)
+#         Rack.rfc2822  3.730000   0.000000   3.730000 (  3.727732)
+#         Rack.rfc2109  3.020000   0.010000   3.030000 (  3.031940)
+#                      --- Monkey Patching Rack ---
+#         Patched.unescape  0.340000   0.000000   0.340000 (  0.341506)
+#         Patched.rfc2822  0.740000   0.000000   0.740000 (  0.737796)
+#         Patched.rfc2109  0.690000   0.010000   0.700000 (  0.700155)
+#
+# At the moment, the extent of the monkey patching offered is very limited.
+# As new optimizations are added, the policy regarding monkey patching (benifit vs. risks) might be re-evaluated.
 module Iodine
   @threads = (ARGV.index('-t') && ARGV[ARGV.index('-t') + 1]) || ENV['MAX_THREADS']
   @processes = (ARGV.index('-w') && ARGV[ARGV.index('-w') + 1]) || ENV['MAX_WORKERS']
@@ -64,7 +150,7 @@ module Iodine
   # file to load now instead of waiting for "first access". This allows multi-threaded safety and better memory utilization during forking.
   #
   # Use {warmup} when either {processes} or {threads} are set to more then 1.
-  def self.warmup
+  def self.warmup app
     # load anything marked with `autoload`, since autoload isn't thread safe nor fork friendly.
     Module.constants.each do |n|
       begin
@@ -72,7 +158,24 @@ module Iodine
       rescue Exception => _e
       end
     end
+    ::Rack::Builder.new(app) do |r|
+      r.warmup do |a|
+        client = ::Rack::MockRequest.new(a)
+        client.get('/')
+      end
+    end
   end
+
+  def self.patch_rack
+    ::Rack::Utils.class_eval do
+      Iodine::Base::MonkeyPatch::RackUtils.methods(false).each do |m|
+        ::Rack::Utils.define_singleton_method(m,
+              Iodine::Base::MonkeyPatch::RackUtils.instance_method(m) )
+      end
+    end
+  end
+
+  self.default_pubsub = ::Iodine::PubSub::CLUSTER
 end
 
 require 'rack/handler/iodine' unless defined? ::Iodine::Rack::IODINE_RACK_LOADED

data/lib/iodine/cli.rb

@@ -0,0 +1,106 @@
+require 'iodine'
+require 'rack'
+
+module Iodine
+  module Base
+    # Command line interface
+    module CLI
+
+      def print_help
+        puts <<-EOS
+
+Iodine's HTTP/Websocket server version #{Iodine::VERSION}
+
+Use:
+
+    iodine <options> <filename>
+
+Both <options> and <filename> are optional.
+
+Available options:
+ -p          Port number. Default: 3000.
+ -t          Number of threads. Default: CPU core count.
+ -w          Number of worker processes. Default: CPU core count.
+ -www        Public folder for static file serving. Default: nil (none).
+ -v          Log responses. Default: never log responses.
+ -warmup     Warmup invokes autoloading (lazy loading) during server startup.
+ -tout       HTTP inactivity connection timeout. Default: 5 seconds.
+ -maxbd      Maximum Mb per HTTP message (max body size). Default: 50Mib.
+ -maxms      Maximum Bytes per Websocket message. Default: 250Kib.
+ -ping       Websocket ping interval in seconds. Default: 40 seconds.
+ <filename>  Defaults to: config.ru
+
+Example:
+
+    iodine -p 80
+
+    iodine -p 8080 path/to/app/conf.ru
+
+    iodine -p 8080 -w 4 -t 16
+
+EOS
+      end
+
+
+      def try_file filename
+        return nil unless File.exist? filename
+        return ::Rack::Builder.parse_file filename
+      end
+
+
+
+      def call
+        if ARGV[0] =~ /(\-\?)|(help)|(\?)|(h)|(\-h)$/
+          return print_help
+        end
+
+        app, opt = nil, nil
+        filename = ((ARGV[-2].to_s[0] != '-' || ARGV[-2].to_s == '-warmup') && ARGV[-1].to_s[0] != '-' && ARGV[-1])
+        if filename
+          app, opt = try_file filename;
+          unless opt
+            puts "* Couldn't find #{filename}\n  testing for config.ru\n"
+            app, opt = try_file "config.ru"
+          end
+        else
+          app, opt = try_file "config.ru";
+        end
+
+        unless opt
+          puts "WARNING: Ruby application not found#{ filename ? " - missing both #{filename} and config.ru" : " - missing config.ru"}."
+          if ARGV.index('-www') && ARGV[ARGV.index('-www') + 1]
+            puts "         Running only static file service."
+            opt = ::Rack::Server::Options.new.parse!([])
+          else
+            puts "For help run:"
+            puts "       iodine -?"
+            return
+          end
+        end
+
+        if ARGV.index('-maxbd') && ARGV[ARGV.index('-maxbd') + 1]
+          Iodine::Rack.max_body_size = ARGV[ARGV.index('-maxbd') + 1].to_i
+        end
+        if ARGV.index('-maxms') && ARGV[ARGV.index('-maxms') + 1]
+          Iodine::Rack.max_msg_size = ARGV[ARGV.index('-maxms') + 1].to_i
+        end
+        if ARGV.index('-ping') && ARGV[ARGV.index('-ping') + 1]
+          Iodine::Rack.ws_timeout = ARGV[ARGV.index('-ping') + 1].to_i
+        end
+        if ARGV.index('-www') && ARGV[ARGV.index('-www') + 1]
+          Iodine::Rack.public = ARGV[ARGV.index('-www') + 1]
+        end
+        if ARGV.index('-tout') && ARGV[ARGV.index('-tout') + 1]
+          Iodine::Rack.timeout = ARGV[ARGV.index('-tout') + 1].to_i
+          puts "WARNNING: Iodine::Rack.timeout set to 0 (ignored, timeout will be ~5 seconds)."
+        end
+        Iodine::Rack.log = true if ARGV.index('-v')
+        Iodine::Rack.log = false if ARGV.index('-q')
+        Iodine.warmup(app) if ARGV.index('-warmup')
+        Iodine::Rack.run(app, opt)
+      end
+
+      extend self
+    end
+  end
+end

data/lib/iodine/monkeypatch.rb

@@ -0,0 +1,40 @@
+module Iodine
+  module Base
+    # Iodine does NOT monkey patch automatically at this time.
+    #
+    # This may change in future releases, but that's unlikely.
+    module MonkeyPatch
+      # Iodine does NOT monkey patch Rack automatically. However, it's possible to
+      # moneky patch Rack::Utils using this module.
+      #
+      # Choosing to monkey patch Rack::Utils could offer significant performance gains for some applications. i.e. (on my machine):
+      #
+      #       require 'iodine'
+      #       require 'rack'
+      #       s = '%E3%83%AB%E3%83%93%E3%82%A4%E3%82%B9%E3%81%A8'
+      #       Benchmark.bm do |bm|
+      #         # Pre-Patch
+      #         bm.report("Rack")    {1_000_000.times { Rack::Utils.unescape s } }
+      #
+      #         # Perform Patch
+      #         Rack::Utils.class_eval do
+      #           Iodine::Base::MonkeyPatch::RackUtils.methods(false).each do |m|
+      #             define_singleton_method(m,
+      #                   Iodine::Base::MonkeyPatch::RackUtils.instance_method(m) )
+      #           end
+      #         end
+      #
+      #         # Post Patch
+      #         bm.report("Patched") {1_000_000.times { Rack::Utils.unescape s } }
+      #       end && nil
+      #
+      # Results:
+      #         user     system      total        real
+      #       Rack     8.620000   0.020000   8.640000 (  8.636676)
+      #       Patched  0.320000   0.000000   0.320000 (  0.322377)
+      module RackUtils
+      end
+    end
+  end
+end
+\