itsi-server 0.2.22-aarch64-linux

data/lib/itsi/server/config/options/send_buffer_size.md

@@ -0,0 +1,15 @@
+---
+title: Send Buffer Size
+url: /options/send_buffer_size
+---
+
+Configures the size of the send 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.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+send_buffer_size 262_144
+```
+
+```ruby {filename=Itsi.rb}
+send_buffer_size 1_048_576
+```

data/lib/itsi/server/config/options/send_buffer_size.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class SendBufferSize < Option
+
+        insert_text <<~SNIPPET
+        send_buffer_size ${1|262_144,1_048_576|}
+        SNIPPET
+
+        detail "Specifies the size of the send 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/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/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/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/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/lib/itsi/server/config/options/threads.md

@@ -0,0 +1,44 @@
+---
+title: Threads
+url: /options/threads
+---
+Itsi supports running in threaded mode. Spawning more than one thread per worker is helpful for applications that require high concurrency and low latency.
+
+Note, that while threading allows for concurrent execution of tasks, it also introduces additional overhead due to context switching between threads.
+This overhead can be significant, especially when dealing with a large number of concurrent tasks.
+To minimize this overhead, it's recommended to keep the number of threads low, and tune this parameter based on your specific use case.
+
+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.
+
+## Examples
+```ruby {filename="Itsi.rb"}
+# Starts each worker with a single thread
+threads 1
+```
+
+```ruby {filename="Itsi.rb"}
+# Each worker will start 4 threads
+threads 4
+```
+
+Threads increase concurrency at the expense of memory usage and CPU overhead.
+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
+You can also override the number of threads using either the `-t` or `--threads` command line option.
+E.g.
+
+```bash
+itsi -t 3
+```

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

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

data/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/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/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/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/lib/itsi/server/config/options/workers.md

@@ -0,0 +1,42 @@
+---
+title: Workers
+url: /options/workers
+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.
+
+## Configuration File
+The number of workers to use can be specified inside the configuration file (usually `./Itsi.rb` at the project root)
+using the `workers` function.
+
+## Examples
+
+```ruby {filename="Itsi.rb"}
+# Starts a single worker, putting Itsi in single-process mode
+workers 1
+```
+
+```ruby {filename="Itsi.rb"}
+# Starts 4 workers, putting Itsi in cluster-process mode
+workers 4
+```
+
+```ruby {filename="Itsi.rb"}
+# Sets the number of workers to the number of CPU cores available on the system
+workers Etc.nprocessors
+```
+
+To maximize performance, it's typical to increase number of workers
+to be at or near the number of CPU cores available on your system.
+
+However, note hyperthreads and efficiency cores may impact this and using every available core is not
+always the most effective choice.
+
+## Command Line
+You can also override the number of workers using either the `-w` or workers `--workers` command line option.
+E.g.
+
+```bash
+itsi -w 4
+```

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

@@ -0,0 +1,17 @@
+module Itsi
+  class Server
+    module Config
+      class Workers < Option
+
+        insert_text "workers ${1|1,2,Etc.nprocessors|} # Number of worker processes to run"
+
+        detail "Number of worker processes to run"
+
+        schema do
+          Range(1..255)
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/writev.md

@@ -0,0 +1,25 @@
+---
+title: Write Vectored
+url: /options/writev
+---
+
+Set whether HTTP/1 connections should try to use vectored writes,
+or always flatten into a single buffer.
+
+Note that setting this to false may mean more copies of body data,
+but may also improve performance when an IO transport doesn't
+support vectored writes well, such as most TLS implementations.
+
+Setting this to true will force hyper to use queued strategy
+which may eliminate unnecessary cloning on some TLS backends
+
+Default is `nil` in which case hyper will try to guess which mode to use
+
+## Configuration
+```ruby {filename=Itsi.rb}
+writev true
+```
+
+```ruby {filename=Itsi.rb}
+writev false
+```

data/lib/itsi/server/config/options/writev.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class Writev < Option
+
+        insert_text <<~SNIPPET
+        writev ${1|true,false|}
+        SNIPPET
+
+        detail "Set whether HTTP/1 connections should try to use vectored writes"
+
+        schema do
+          (Bool() & Required()).default(false)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Itsi
+  class Server
+    module Config
+      module TypedStruct
+        VALUE = 0
+        VALIDATE = 1
+
+        def self.new(defaults = nil, &defaults_blk)
+          defaults = TypedStruct.module_eval(&defaults_blk) if defaults_blk
+          return defaults unless defaults.is_a?(Hash)
+
+          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|
+              raise "─ Invalid input to #{self}: #{input.last}" if input.last && !input.last.is_a?(Hash)
+
+              raw_input.transform_keys! { |k| k.to_s.downcase.to_sym }
+              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?
+
+              initial_values = defaults.each_with_object({}) do |(k, default_config), inputs|
+                value = raw_input.key?(k) ? raw_input[k] : default_config[VALUE].dup
+                next inputs[k] = value unless validate
+
+                begin
+                  inputs[k] = default_config[VALIDATE].validate!(value)
+                rescue StandardError => e
+                  raise ArgumentError, "─ #{k}: #{e.message}"
+                end
+              end
+
+              super(initial_values)
+              validator = self.class.instance_eval { @validators }
+              instance_eval(&validator) if validator
+            end
+
+            define_singleton_method(:validate) do |&blk|
+              @validators = blk
+            end
+
+            defaults.each do |key, (_, validation)|
+              define_method(:"#{key}?") do
+                !!self[key]
+              end
+              define_method(:"#{key}=") do |value|
+                self[key] = validation.validate!(value)
+              end
+            end
+
+            define_method(:[]=) do |key, value|
+              super(key, defaults[key][VALIDATE].validate!(value))
+            end
+
+            def is_typed_struct?
+              true
+            end
+
+            def merge_config(other)
+              self.class.new(members.map do |key|
+                value = self[key]
+                has_merged_val = (other.is_a?(Hash) ? other.key?(key) : other.member?(key))
+                next [key, value] unless has_merged_val
+
+                [
+                  key,
+                  TypedStruct.typed_struct?(value) ? value.merge_config(other[key]) : other[key]
+                ]
+              end.to_h)
+            end
+
+            def to_h
+              super.transform_values { |v| v.respond_to?(:merge_config) ? v.to_h : v }
+            end
+          end
+        end
+
+        def self.typed_struct?(inst)
+          inst.respond_to?(:is_typed_struct?) && inst.is_typed_struct?
+        end
+
+        class Validation
+          attr_reader :name, :validations
+          attr_accessor :next
+
+          def initialize(name, validations)
+            @name = name.to_s
+            @validations = Array(validations)
+            @next = nil
+          end
+
+          def inspect
+            "#{@name}"
+          end
+
+          def &(other)
+            tail = self
+            tail = tail.next while tail.next
+            tail.next = other
+            self
+          end
+
+          def default(value)
+            [value, self]
+          end
+
+          def validate!(value)
+            value = value.to_s if value.is_a?(Symbol)
+            @validations.each do |validation|
+              case validation
+              when Proc
+                validation.call(value)
+              when Array
+                unless !value || validation.include?(value)
+                  raise ArgumentError,
+                        "─ `#{@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}"
+                end
+              when Regexp
+                unless !value || validation.match?(value)
+                  raise ArgumentError,
+                        "─ `#{@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?(Integer) then Integer(value)
+                      elsif validation.eql?(Proc)
+                        raise ArgumentError, "Invalid #{validation} value: #{value.inspect}" unless value.is_a?(Proc)
+                      elsif validation.eql?(String) || validation.eql?(Symbol)
+                        unless value.is_a?(String) || value.is_a?(Symbol)
+                          raise ArgumentError,
+                                "Invalid #{validation} value: #{value.inspect}"
+                        end
+
+                        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}"
+                  end
+                end
+              end
+            end
+            if self.next
+              self.next.validate!(value)
+            else
+              value
+            end
+          end
+        end
+
+        {
+          Bool: Validation.new(:Bool, [[true, false]]),
+          Required: Validation.new(:Required, ->(value) { !value.nil? }),
+          Or: lambda { |*validations|
+            Validation.new(:Or, lambda { |v|
+              return true if v.nil?
+
+              errs = []
+              validations.each do |validation|
+                v = validation.validate!(v)
+                return v
+              rescue StandardError => e
+                errs << e.message
+              end
+              raise StandardError.new("─ Validation failed (None match:) \n  └#{errs.join("\n  └")}")
+            })
+          },
+          Range: lambda { |input_range|
+            Validation.new(:Range, [input_range])
+          },
+          Length: lambda { |input_length|
+            Validation.new(:Length, ->(value) { input_length === value.length })
+          },
+          Hash: lambda { |key_type, value_type|
+            Validation.new(:Hash, lambda { |hash|
+              return true if hash.nil?
+              raise StandardError.new("Expected hash got #{hash.class}") unless hash.is_a?(Hash)
+
+              hash.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.is_a?(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
+              end
+            }])
+          }
+        }.each do |name, factory|
+          if factory.is_a?(Proc)
+            define_singleton_method(name, &factory)
+            define_singleton_method(name.to_s.downcase, &factory)
+          else
+            const_set(name, factory)
+            define_singleton_method(name, -> { factory.dup })
+            define_singleton_method(name.to_s.downcase, -> { factory.dup })
+          end
+        end
+      end
+    end
+  end
+end