itsi 0.1.20 → 0.2.2

data/gems/server/lib/itsi/server/config/options/recv_buffer_size.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class RecvBufferSize < Option
+
+        insert_text <<~SNIPPET
+        recv_buffer_size ${1|262_144,1_048_576|}
+        SNIPPET
+
+        detail "Specifies the size of the receive buffer for the socket. Larger buffer sizes can improve performance for high-throughput applications but may increase memory usage. The default value is 262,144 bytes."
+
+        schema do
+          (Type(Integer) & Range(1..Float::INFINITY) & Required()).default(262_144)
+        end
+
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/redirect_http_to_https.md

@@ -0,0 +1,21 @@
+---
+title: Redirect HTTP to HTTPS
+url: /options/redirect_http_to_https
+---
+This simple option installs a location block to redirect all HTTP traffic to HTTPS.
+
+```ruby {filename=Itsi.rb}
+redirect_http_to_https!
+```
+
+It is an alias for:
+```ruby
+location protocols: [:http] do
+  redirect \
+    to: "https://{host}{path_and_query}", \
+    type: "moved_permanently"
+end
+```
+
+It is subject to ordinary [location](/middleware/location) resolution rules.
+To make sure this rule takes precedence, place it *above* other locations in the `Itsi.rb` file

data/gems/server/lib/itsi/server/config/options/redirect_http_to_https.rb

@@ -0,0 +1,30 @@
+module Itsi
+  class Server
+    module Config
+      class RedirectHttpToHttps < Option
+
+        insert_text <<~SNIPPET
+        redirect_http_to_https! # Install a location block to redirect HTTP to HTTPS
+                                # (Only works if listening on ports 443 and 80).
+                                # For non-conventional or development ports use a manual redirect
+        SNIPPET
+
+        detail "Install a location block to redirect HTTP to HTTPS."
+
+        def self.option_name
+          :redirect_http_to_https!
+        end
+
+        def build!
+          location.instance_eval do
+            location protocols: [:http] do
+              redirect \
+                to: "https://{host}{path_and_query}", \
+                type: "moved_permanently"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/request_timeout.md

@@ -0,0 +1,23 @@
+---
+title: Request Timeout
+url: /options/request_timeout
+---
+
+Sets the maximum duration (in seconds) allowed for the entire request to complete. If exceeded, the request will be terminated.
+
+
+### Default
+
+```ruby {filename=Itsi.rb}
+request_timeout 300  # 5 minutes
+```
+### Example
+
+```ruby {filename=Itsi.rb}
+request_timeout 60  # 1 minute
+```
+
+
+{{< callout type="warn" >}}
+If the request is held-up inside a Ruby worker, the worker will be gracefully restarted (as killing in-progress threads is not safe).
+{{< /callout >}}

data/gems/server/lib/itsi/server/config/options/request_timeout.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class RequestTimeout < Option
+
+        insert_text <<~SNIPPET
+        request_timeout 300.0 # Request Timeout in Seconds
+        SNIPPET
+
+        detail "Set Request Timeout"
+
+        schema do
+          (Type(Float) & Required()).default(300.0) # Default 5 minutes
+        end
+
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/reuse_address.md

@@ -0,0 +1,16 @@
+---
+title: Reuse Address
+url: /options/reuse_address
+---
+
+Configures whether the server should bind to the underlying socket using the `SO_REUSEADDR` option.
+This optiondetermines whether the server allows the reuse of local addresses during binding. This can be useful in scenarios where a socket needs to be quickly rebound without waiting for the operating system to release the address.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+reuse_address true
+```
+
+```ruby {filename=Itsi.rb}
+reuse_address false
+```

data/gems/server/lib/itsi/server/config/options/reuse_address.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class ReuseAddress < Option
+
+        insert_text <<~SNIPPET
+        reuse_address ${1|true,false|}
+        SNIPPET
+
+        detail "Configures whether the server should set the reuse_address option on the underlying socket."
+
+        schema do
+          (Bool() & Required()).default(true)
+        end
+
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/reuse_port.md

@@ -0,0 +1,16 @@
+---
+title: Reuse Port
+url: /options/reuse_port
+---
+
+Configures whether the server should bind to the underlying socket using the `SO_REUSEPORT` option.
+This option determines whether multiple sockets can listen on the same IP and port combination, which can improve load balancing and fault tolerance in multi-threaded or multi-process server applications.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+reuse_port true
+```
+
+```ruby {filename=Itsi.rb}
+reuse_port false
+```

data/gems/server/lib/itsi/server/config/options/reuse_port.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class ReusePort < Option
+
+        insert_text <<~SNIPPET
+        reuse_port ${1|true,false|}
+        SNIPPET
+
+        detail "Configures whether the server should set the reuse_port option on the underlying socket."
+
+        schema do
+          (Bool() & Required()).default(true)
+        end
+
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/scheduler_threads.md

@@ -0,0 +1,34 @@
+---
+title: Scheduler Threads
+url: /options/scheduler_threads
+---
+
+You can explicitly spawn a pool of non-blocking scheduler threads and divide work across traditional blocking and non-blocking threads, using [location](/middleware/location) blocks.
+
+This allows you to safely dip your toes into using non-blocking threads for specific I/O heavy operations without having to port an entire application to non-blocking I/O.
+
+To use blocking and non-blocking threads in conjunction you need to perform several steps.
+1. Configure a thread pool using [threads](/middleware/threads)
+2. Configure a **separate** non-blocking thread pool using [scheduler_threads](/middleware/scheduler_threads) (By opting into this option you automatically make the ordinary thread pool blocking)
+3. Enable a [fiber_scheduler](/options/fiber_scheduler)
+4. Mount your app as non-blocking for selected routes. (Using either [run](/middleware/run), [rackup_file](/middleware/rackup_file) or [endpoint](/middleware/endpoint))
+
+## Configuration
+Here is an example configuration of the all of the above E.g.
+
+```ruby {filename=Itsi.rb}
+
+threads 3 # 3 threads (opting into scheduler threads make these blocking)
+scheduler_threads 1 # 1 non-blocking scheduler thread
+fiber_scheduler true
+
+# We mount the same app *twice*.
+# For a specific route prefix, all requests will be sent to non blocking threads.
+# All others fall through to the default mount
+location "/heavy_io/*" do
+  rackup_file "./config.ru", nonblocking: true
+end
+
+rackup_file "./config.ru"
+
+```

data/gems/server/lib/itsi/server/config/options/scheduler_threads.rb

@@ -0,0 +1,17 @@
+module Itsi
+  class Server
+    module Config
+      class SchedulerThreads < Option
+
+        insert_text "scheduler_threads ${1|1,2,Etc.nprocessors|} # Number of non-blocking scheduler threads to run per worker"
+
+        detail "Number of non-blocking scheduler threads to run per worker"
+
+        schema do
+          Range(1..255)
+        end
+
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/shutdown_timeout.md

@@ -0,0 +1,17 @@
+---
+title: Shutdown Timeout
+url: /options/shutdown_timeout
+---
+
+Sets the timeout for graceful shutdown of the server. Itsi will stop accepting new connections immediately after receiving a shutdown signal. Existing connections will be allowed to complete their requests within the specified timeout. Any connections that do not complete within the timeout will be forcefully closed.
+
+### Default
+
+```ruby {filename=Itsi.rb}
+shutdown_timeout 5.0  # 5 seconds
+```
+### Example
+
+```ruby {filename=Itsi.rb}
+shutdown_timeout 20.0  # 20 seconds
+```

data/gems/server/lib/itsi/server/config/options/shutdown_timeout.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class PinWorkerCores < Option
+
+        insert_text <<~SNIPPET
+        pin_worker_cores ${1|true,false|} # Configure whether worker processes should attempt to pin to a single CPU core.
+        SNIPPET
+
+        detail "Configure whether worker processes should attempt to pin to a single CPU core"
+
+        schema do
+          (Bool() & Required()).default(true) # Default 5 seconds
+        end
+
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/stream_body.md

@@ -0,0 +1,32 @@
+---
+title: Stream Body
+url: /options/stream_body
+---
+
+The **stream_body** option controls whether Itsi buffers the request body in memory before passing it to your application code. Several Rack applications rely on this behaviour (so that the request can be rewound and/or parsed in its entirety before being processed), for this reason the default behaviour is `true`.
+However for light-weight requests that benefit from not holding the entire request body in memory, you can set this option to `false`.
+
+
+{{< callout >}}
+To prevent excessive memory usage, Itsi will store any large buffered request bodies in temporary storage on the file-system when request body streaming is disabled.
+{{< /callout >}}
+
+
+
+Streaming bodies cooperate particularly well with [Fiber scheduler](/options/fiber_scheduler) mode, to allow you to process many large and long-running incoming data streams simultaneously. For this use case, be sure to adjust both [max_body](/options/max_body) and [request_timeout](/options/request_timeout) to ensure large incoming requests are not terminated prematurely.
+
+
+
+## Configuration File
+
+```ruby
+# Disable streaming the request body
+stream_body false
+
+# Enable streaming the request body
+stream_body true
+post("/test_stream") do |req|
+  # req.body is an IO
+  first_five_bytes = req.body.read(5)
+end
+```

data/gems/server/lib/itsi/server/config/options/stream_body.rb

@@ -0,0 +1,18 @@
+module Itsi
+  class Server
+    module Config
+      class StreamBody < Option
+
+        insert_text <<~SNIPPET
+        stream_body ${1|true,false|}
+        SNIPPET
+
+        detail "Configures whether request bodies should be completed buffered *before* they are forwarded to the application."
+
+        schema do
+          Or(Bool(), Type(Symbol)).default(false)
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/threads.md

@@ -1,7 +1,6 @@
 ---
 title: Threads
 url: /options/threads
-weight: 2
 ---
 Itsi supports running in threaded mode. Spawning more than one thread per worker is helpful for applications that require high concurrency and low latency.
 
@@ -11,6 +10,12 @@ To minimize this overhead, it's recommended to keep the number of threads low, a
 
 When running Itsi in blocking mode, the total number of concurrent requests will be equal to `workers` x `threads`
 
+
+{{< callout >}}
+If you enable  a [fiber_scheduler](/options/fiber_scheduler), the threads will be non-blocking, unless you are using both [threads](/options/threads) and [scheduler_threads](/options/scheduler_threads) **together**.
+{{< /callout >}}
+
+
 ## Configuration File
 The number of threads to use can be specified inside the configuration file (usually `./Itsi.rb` at the project root)
 using the `threads` function.
@@ -27,7 +32,7 @@ threads 4
 ```
 
 Threads increase concurrency at the expense of memory usage and CPU overhead.
-For IO heavy workloads, consider using non-blocking mode instead, which can achieve higher concurrency with fewer threads.
+For IO heavy workloads, consider using [non-blocking mode](/options/fiber_scheduler) instead, which can achieve higher concurrency with fewer threads.
 Non-blocking mode and threads can be used simultaneously in a hybrid configuration.
 
 ## Command Line

data/gems/server/lib/itsi/server/config/options/threads.rb

@@ -3,7 +3,7 @@ module Itsi
     module Config
       class Threads < Option
 
-        insert_text "threads ${1|1,2,Etc.nprocessors|}"
+        insert_text "threads ${1|1,2,Etc.nprocessors|} # Number of threads to run per worker"
 
         detail "Number of threads to run per worker"
 

data/gems/server/lib/itsi/server/config/options/watch.md

@@ -0,0 +1,16 @@
+---
+title: Watch
+url: /options/watch
+---
+
+The `watch` option uses Itsi's built-in file watching mechanism to execute a list of commands each time any file matching the path glob parameter is modified.
+
+You can have several active watches at once.
+
+E.g.
+
+```ruby {filename=Itsi.rb}
+watch 'config/*.yml', [%w[npm run build], %w[bundle exec cache:mark_dirty]]
+
+watch 'app/**/*.rb', [%w[bundle exec itsi restart]]
+```

data/gems/server/lib/itsi/server/config/options/watch.rb

@@ -0,0 +1,28 @@
+module Itsi
+  class Server
+    module Config
+      class Watch < Option
+
+        insert_text <<~SNIPPET
+        watch "${1:./**/*.rb}", [${2:%w[bundle exec itsi restart]}] # Run a command each time a watched set of files changes
+        SNIPPET
+
+        detail "Run a command each time a watched set of files changes"
+
+        def initialize(location, path, commands)
+          @path = path
+          @commands = commands
+          super(location, nil)
+        end
+
+        def build!
+          path, commands = @path, @commands
+          location.instance_eval do
+            @options[:notify_watchers] ||= []
+            @options[:notify_watchers] << [path, commands]
+          end
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/worker_memory_limit.md

@@ -0,0 +1,22 @@
+---
+title: Worker Memory Limit
+url: /options/worker_memory_limit
+---
+
+The **Worker Memory Limit** option sets the maximum amount of memory a worker process can use before it is terminated. If an [`after_memory_threshold_reached`](/options/after_memory_limit_reached) hook is also set, you can define custom behaviour (e.g. an alert or exception notification) that should occur before the worker is rebooted.
+
+
+## Configuration File
+
+### Examples
+
+```ruby {filename="Itsi.rb"}
+worker_memory_limit 256 * 1024 ** 2 # 256 MB
+```
+
+```ruby {filename="Itsi.rb"}
+worker_memory_limit 256 * 1024 ** 2 # 256 MB
+after_memory_limit_reached do |pid|
+  send_slack_alert("Worker #{pid} exceeded memory limit")
+end
+```

data/gems/server/lib/itsi/server/config/options/worker_memory_limit.rb

@@ -0,0 +1,18 @@
+module Itsi
+  class Server
+    module Config
+      class WorkerMemoryLimit < Option
+
+        insert_text <<~SNIPPET
+        worker_memory_limit ${1|256,512,1024,2048|} * 1024 ** 2 # Worker memory limit in bytes
+        SNIPPET
+
+        detail "Set the maximum amount of memory a worker process can use before it is terminated."
+
+        schema do
+          Type(Integer) & Required()
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/options/workers.md

@@ -1,8 +1,7 @@
 ---
 title: Workers
 url: /options/workers
-prev: /options
-weight: 1
+next: middleware/
 ---
 Itsi is a preforking server. It can run as either a single process (`workers 1`) or in clustered mode (`workers > 1`).
 <br/>You can switch between the two without downtime.

data/gems/server/lib/itsi/server/config/options/workers.rb

@@ -3,7 +3,7 @@ module Itsi
     module Config
       class Workers < Option
 
-        insert_text "workers ${1|1,2,Etc.nprocessors|}"
+        insert_text "workers ${1|1,2,Etc.nprocessors|} # Number of worker processes to run"
 
         detail "Number of worker processes to run"
 

data/gems/server/lib/itsi/server/config/typed_struct.rb

@@ -16,12 +16,19 @@ module Itsi
           defaults.transform_values! { _1.is_a?(Validation) ? _1.default(nil) : _1 }
           Struct.new(*defaults.keys, keyword_init: true) do
             define_method(:initialize) do |*input, validate: true, **raw_input|
+
+              if input.last && !input.last.is_a?(Hash)
+                raise "─ Invalid input to #{self}: #{input.last}"
+              end
               raw_input.transform_keys!{|k| k.to_s.downcase.to_sym }
-              raw_input.merge!(input.pop) if input.last.is_a?(Hash)
+              raw_input.merge!(input.pop.transform_keys!{|k| k.to_s.downcase.to_sym}) if input.last.is_a?(Hash)
 
               excess_keys = raw_input.keys - defaults.keys
 
-              raise "Unsupported keys #{excess_keys}" if excess_keys.any?
+              if excess_keys.any?
+                raise "─ Unsupported keys #{excess_keys}"
+
+              end
 
               initial_values = defaults.each_with_object({}) do |(k, default_config), inputs|
                 value = raw_input.key?(k) ? raw_input[k] : default_config[VALUE].dup
@@ -30,7 +37,7 @@ module Itsi
                 begin
                   inputs[k] = default_config[VALIDATE].validate!(value)
                 rescue StandardError => e
-                  raise ArgumentError, e.message
+                  raise ArgumentError, "─ #{k}: #{e.message}"
                 end
               end
 
@@ -97,7 +104,7 @@ module Itsi
             "#{@name}"
           end
 
-          def +(other)
+          def &(other)
             tail = self
             while tail.next
               tail = tail.next
@@ -115,40 +122,47 @@ module Itsi
             @validations.each do |validation|
               case validation
               when Proc
-                unless validation.call(value)
-                  raise ArgumentError,
-                        "─  `#{@name}` validation failed. Invalid value: #{value.inspect}"
-                end
+                validation.call(value)
               when Array
                 unless !value || validation.include?(value)
                   raise ArgumentError,
-                        "─  `#{@name}` validation failed. Invalid #{validation} value: #{value.inspect}"
+                        "─ `#{@name}` validation failed. Invalid #{validation} value: #{value.inspect}"
                 end
               when Range
                 unless !value || validation.include?(value)
                   raise ArgumentError,
-                        "─  `#{@name}` validation failed. Invalid #{validation} value: #{value.inspect}"
+                        "─ `#{@name}` validation failed. Invalid #{validation} value: #{value.inspect}"
                 end
               when Regexp
                 unless !value || validation.match?(value)
                   raise ArgumentError,
-                        "─  `#{@name}` validation failed. Invalid #{validation} value: #{value.inspect}"
+                        "─ `#{@name}` validation failed. Invalid #{validation} value: #{value.inspect}"
                 end
+              when Validation
+                validation.validate!(value)
               when Class
-
                 if value && !value.is_a?(validation)
                   begin
                     value = \
                       if validation.eql?(Time) then Time.parse(value.to_s)
                       elsif validation.eql?(::Date) then Date.parse(value.to_s)
                       elsif validation.eql?(Float) then Float(value)
-                      elsif validation.eql?(String) then value.to_s
-                      elsif validation.eql?(Symbol) then value.is_a?(Symbol) ? value : value.to_s.to_sym
-                      else validation.new(value)
+                      elsif validation.eql?(Integer) then Integer(value)
+                      elsif validation.eql?(Proc) then
+                        raise ArgumentError, "Invalid #{validation} value: #{value.inspect}" unless value.is_a?(Proc)
+                      elsif validation.eql?(String) || validation.eql?(Symbol)
+                        raise ArgumentError, "Invalid #{validation} value: #{value.inspect}" unless value.is_a?(String) || value.is_a?(Symbol)
+                        if validation.eql?(String)
+                          value.to_s
+                        elsif validation.eql?(Symbol)
+                          value.to_s.to_sym
+                        end
+                      else
+                        validation.new(value)
                       end
                   rescue StandardError => e
                     raise ArgumentError,
-                          "─ `#{@name}` Validation Failed. Invalid #{validation.to_s.split("::").last} value: #{value.inspect}. Failure reason: \n └#{e.message}"
+                          "─ `#{@name}` Validation Failed. Invalid #{validation.to_s.split("::").last} value: #{value.inspect}. Failure reason: \n  └─ #{e.message}"
                   end
                 end
               end
@@ -164,9 +178,20 @@ module Itsi
         {
           Bool: Validation.new(:Bool, [[true, false]]),
           Required: Validation.new(:Required, ->(value) { !value.nil? }),
-          Or: ->(validation_a, validation_b){
+          Or: ->(*validations){
             Validation.new(:Or, ->(v){
-              validation_a.validate!(v) || validation_b.validate!(v)
+
+              return true if v.nil?
+              errs = []
+              validations.each do |validation|
+                begin
+                  v = validation.validate!(v)
+                  return v
+                rescue StandardError => e
+                  errs << e.message
+                end
+              end
+              raise StandardError.new("─ Validation failed (None match:) \n  └#{errs.join("\n  └")}")
             })
           },
           Range: ->(input_range) {
@@ -175,12 +200,26 @@ module Itsi
           Length: lambda { |input_length|
             Validation.new(:Length, ->(value) { input_length === value.length })
           },
+          Hash: ->(key_type, value_type) {
+            Validation.new(:Hash, ->(v){
+              return true if v.nil?
+              raise StandardError.new("Expected hash got #{v.class}") unless v.is_a?(Hash)
+              v.map do |k, v|
+                [
+                  key_type.validate!(k),
+                  value_type.validate!(v)
+                ]
+              end.to_h
+            })
+          },
           Type: ->(input_type) { Validation.new(:Type, input_type) },
           Enum: ->(allowed_values) { Validation.new(:Enum, [allowed_values.map{|v| v.kind_of?(Symbol) ? v.to_s : v}]) },
           Array: lambda { |*value_validations|
             Validation.new(:Array, [::Array, lambda { |value|
               return true unless value
 
+              raise StandardError.new("Expected Array got #{value.class}") unless value.is_a?(Array)
+
               value&.map! do |v|
                 value_validations.all? { v = _1.validate!(v) }
                 v
@@ -193,8 +232,8 @@ module Itsi
             define_singleton_method(name.to_s.downcase, &factory)
           else
             const_set(name, factory)
-            define_singleton_method(name, -> { factory })
-            define_singleton_method(name.to_s.downcase, -> { factory })
+            define_singleton_method(name, -> { factory.dup })
+            define_singleton_method(name.to_s.downcase, -> { factory.dup })
           end
         end
       end