itsi-server 0.2.22-aarch64-linux

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

@@ -0,0 +1,38 @@
+---
+title: Log Target
+url: /options/log_target
+---
+
+Configures the target for logging. The default value is `:stdout`.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+log_target :stdout
+```
+
+```ruby {filename=Itsi.rb}
+# Log to a file instead
+log_target "my_app.log"
+```
+
+```ruby {filename=Itsi.rb}
+# Log to both a file and the standard output (filename determined by ITSI_LOG_FILE)
+log_target :both
+```
+
+## Options
+| Option   | Description                                                                 |
+|----------|-----------------------------------------------------------------------------|
+| stdout     | Logs are sent to the standard output (console). This is the default option. |
+| [filename] | Logs are written to a specified file.                                       |
+| both       | Logs are sent to both the standard output the default log file.            |
+
+
+## Environment Variables
+You can also control the log target using environment variables.
+If both are set, the value in the configuration file takes precedence.
+
+| Variable   | Description                                                                 |
+|------------|-----------------------------------------------------------------------------|
+| ITSI_LOG_TARGET | Specifies the log target. Possible values are stdout, filename, or both.    |
+| ITSI_LOG_FILE | The name of the log file used by itsi. Default is `itsi-app.log`.    |

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class LogTarget < Option
+
+        insert_text <<~SNIPPET
+        log_target ${1|:stdout,:both,"./filename.log"|}
+        SNIPPET
+
+        detail "Specifies the target for logging. The default value is stdout."
+
+        schema do
+          (Type(String) & Or(Enum(%w[stdout file]), Type(String))).default('stdout')
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+---
+title: Log Target Filters
+url: /options/log_target_filters
+---
+Log target filters allow you fine-grained control over which log messages are enabled based on their level and source. This is configured using the `EnvFilter` syntax, which supports filtering by log level, module path, or a combination of both. Examples of valid filters include:
+
+- `"middleware=debug"`: Enables `debug` level logs for the `middleware` module and its submodules.
+- `"middleware::auth_jwt=trace"`: Enables `trace` level logs for a specific submodule.
+- `"debug,middleware::auth_jwt=warn,middleware::rate_limit=info"`: Combines multiple filters, setting different log levels for different modules.
+
+These filters provide fine-grained control over logging behavior, making it easier to focus on relevant information during debugging or monitoring.
+Configures the size of the listen backlog for the socket. Larger backlog sizes can improve performance for high-throughput applications by allowing more pending connections to queue, but may increase memory usage. The default value is 1024.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+log_target_filters ["middleware=debug", "middleware::rate_limit=trace"]
+```

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class LogTargetFilters < Option
+
+        insert_text <<~SNIPPET
+        log_target_filters ${1|[],%w[middleware=debug middleware::rate_limit=trace]|}
+        SNIPPET
+
+        detail "Specifies the fine-grained target filters for logging. E.g.log_target_filters [\"middleware=debug\", \"middleware::rate_limit=trace\"]."
+
+        schema do
+          (Type(Array) & Required()).default([])
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+---
+title: Multithreaded Reactor
+url: /options/multithreaded_reactor
+---
+
+Configures whether the Tokio reactor should run in multithreaded mode.
+
+Itsi will attempt to intelligently determine this config value by default, by enabling it in single mode, and disabling it in cluster-mode (where attempting to utilize multiple cores via both multi-threaded reactor and multi-worker is generally less efficient, not recommended).
+however you can use this option to override it.
+
+## Options
+|Option | Description |
+|-------|-------------|
+| `true` | Enable multithreaded reactor |
+| `false` | Disable multithreaded reactor |
+| `:auto` | Automatically determine based on mode |
+
+### Default
+
+```ruby {filename=Itsi.rb}
+multithreaded_reactor :auto # Default. Will result in true if running in single mode, false if running in multi mode.
+```
+### Example
+
+```ruby {filename=Itsi.rb}
+multithreaded_reactor true
+```

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

@@ -0,0 +1,24 @@
+module Itsi
+  class Server
+    module Config
+      class MultithreadedReactor < Option
+
+        insert_text <<~SNIPPET
+        multithreaded_reactor ${1|:auto,true,false|}
+        SNIPPET
+
+        detail "Configures whether the server should use a multithreaded reactor."
+
+        schema do
+          (Or(Bool(), Enum([:auto])) & Required()).default(:auto) # Default 5 seconds
+        end
+
+        def initialize(location, value)
+          value = nil if value == :auto
+          super
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+---
+title: Nodelay
+url: /options/nodelay
+---
+
+Configures whether the server should enable the `TCP_NODELAY` option on the underlying socket.
+This option determines whether the Nagle's algorithm is disabled, allowing small packets of data to be sent immediately without waiting for more data to fill the packet.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+nodelay true
+```
+
+```ruby {filename=Itsi.rb}
+nodelay false
+```

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

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

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

@@ -0,0 +1,19 @@
+---
+title: OOB GC
+url: /options/oob_gc
+---
+
+The **OOB GC Response Threshold** sets the threshold at which the Ruby GC should be triggered during periods where there is a gap in queued requests.
+
+## Configuration File
+
+### Examples
+
+```ruby {filename="Itsi.rb"}
+oob_gc_response_threshold 1000 # Trigger GC every 1000 pauses/gaps
+```
+
+
+{{< callout >}}
+Settings this too aggressively can seriously impact performance. It's recommended to start with a relatively high value and then adjust based on your application's specific needs and performance characteristics.
+{{< /callout >}}

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

@@ -0,0 +1,18 @@
+module Itsi
+  class Server
+    module Config
+      class OobGcResponsesThreshold < Option
+
+        insert_text <<~SNIPPET
+        oob_gc_responses_threshold ${1|128,256,512,1024|} # Trigger GC every N gaps in the request queue.
+        SNIPPET
+
+        detail "Sets the threshold for the number of request queue pauses, before triggering garbage collection."
+
+        schema do
+          Type(Integer) & Required()
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+---
+title: Pin Worker Cores
+url: /options/pin_worker_cores
+---
+
+Sets whether worker processes should attempt to pin to a single CPU core.
+
+### Default
+
+```ruby {filename=Itsi.rb}
+pin_worker_cores true
+```
+### Example
+
+```ruby {filename=Itsi.rb}
+pin_worker_cores false
+```

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class ShutdownTimeout < Option
+
+        insert_text <<~SNIPPET
+        shutdown_timeout 5.0 # Shutdown Timeout in Seconds
+        SNIPPET
+
+        detail "Sets the timeout for graceful shutdown of the server."
+
+        schema do
+          (Type(Float) & Required()).default(5.0) # Default 5 seconds
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+---
+title: Pipeline Flush
+url: /options/pipeline_flush
+---
+
+Aggregates flushes to better support pipelined responses. (HTTP1 only)
+The default value is `false`.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+pipeline_flush true
+```
+
+```ruby {filename=Itsi.rb}
+pipeline_flush false
+```

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class PipelineFlush < Option
+
+        insert_text <<~SNIPPET
+        pipeline_flush ${1|true,false|}
+        SNIPPET
+
+        detail "Aggregates flushes to better support pipelined responses. (HTTP1 only)."
+
+        schema do
+          (Bool() & Required()).default(false)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+---
+title: Preload
+url: /options/preload
+---
+
+The **preload** option controls whether your application code and middleware are loaded into memory **before** forking worker processes. Preloading can improve request‑handling performance (thanks to copy‑on‑write memory sharing and avoiding per‑worker load time), but it also increases the master process’s memory footprint and startup time. In **single‑worker** mode (`workers 1`), `preload` is ignored.
+
+## Configuration File
+
+```ruby
+# Load everything in the master process before forking
+preload true
+
+# Only preload the gems in the named Gemfile group (e.g. :assets)
+preload :assets
+# Only preload the gems in the named Gemfile group (e.g. :preload)
+preload :preload
+
+# Do not preload (load after forking in each worker)
+preload false
+```

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

@@ -0,0 +1,18 @@
+module Itsi
+  class Server
+    module Config
+      class Preload < Option
+
+        insert_text <<~SNIPPET
+        preload ${1|true,false,:preload|} # Preload
+        SNIPPET
+
+        detail "Configures whether all apps and middleware are preloaded before forking, just specific gem groups, or nothing. Has no effect if running in single mode."
+
+        schema do
+          Or(Bool(), Type(Symbol)).default(false)
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,18 @@
+---
+title: Reuse Address
+url: /options/reuse_address
+---
+
+Configures whether the server should bind to the underlying socket using the `SO_REUSEADDR` option.
+This option determines 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.
+
+The default value is `false`.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+reuse_address true
+```
+
+```ruby {filename=Itsi.rb}
+reuse_address false
+```

data/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(false)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+---
+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.
+
+The default value is `false`.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+reuse_port true
+```
+
+```ruby {filename=Itsi.rb}
+reuse_port false
+```

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

@@ -0,0 +1,17 @@
+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/lib/itsi/server/config/options/ruby_thread_request_backlog_size.md

@@ -0,0 +1,18 @@
+---
+title: Ruby Thread Request Backlog Size
+url: /options/ruby_thread_request_backlog_size
+---
+
+Configures the size of the backlog queue for incoming requests in the Ruby thread pool.
+Up to this many requests can be queued at once before the server rejects further requests to Ruby workers (note this does not block other requests to proxied hosts or for static assets).
+
+The default value is `30 x number of threads`.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+ruby_thread_request_backlog_size 20
+```
+
+```ruby {filename=Itsi.rb}
+ruby_thread_request_backlog_size 100
+```

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class RubyThreadRequestBacklogSize < Option
+
+        insert_text <<~SNIPPET
+        ruby_thread_request_backlog_size ${1|10,25,50,100|}
+        SNIPPET
+
+        detail "The maximum number of requests that can be queued for processing by the Ruby thread."
+
+        schema do
+          (Type(Integer)).default(nil)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+---
+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
+  # You can optionally use the `script_name: ""` option here to set the base path for the mounted app (useful if a nested app
+  # should still serve requests as if it was mounted at the root).
+  # Otherwise it will infer the script-name based on the parent location block.
+  rackup_file "./config.ru", nonblocking: true
+end
+
+rackup_file "./config.ru"
+
+```
+## Examples.
+
+See [a code example](https://github.com/wouterken/itsi/tree/main/examples/hybrid_scheduler_mode) in the Git repository.

data/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