itsi-server 0.1.1 → 0.2.2

data/lib/itsi/server/config/options/hooks/after_memory_limit_reached.rb

@@ -0,0 +1,28 @@
+module Itsi
+  class Server
+    module Config
+      class AfterMemoryLimitReached < Option
+        insert_text <<~SNIPPET
+        after_memory_limit_reached do |pid|
+          ${1:# code to run when memory threshold is exceeded}
+        end
+        SNIPPET
+
+        detail "Run code in a worker after its memory usage exceeds the configured threshold."
+
+        schema do
+          (Type(Proc) & Required())
+        end
+
+        def initialize(location, &params)
+          super(location, params)
+        end
+
+        def build!
+          location.options[:hooks] ||= {}
+          location.options[:hooks][:after_memory_threshold_reached] = @params
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/hooks/after_start.md

@@ -0,0 +1,12 @@
+---
+title: After Start
+url: /options/after_start
+---
+
+The **after_start** hook runs once after the server start-up process has completed.
+
+```ruby {filename=Itsi.rb}
+after_start do
+  DB.reconnect!
+end
+```

data/lib/itsi/server/config/options/hooks/after_start.rb

@@ -0,0 +1,28 @@
+module Itsi
+  class Server
+    module Config
+      class AfterStart < Option
+        insert_text <<~SNIPPET
+        after_start do
+          ${1:# code to run after worker starts}
+        end
+        SNIPPET
+
+        detail "Run code after worker starts"
+
+        schema do
+          (Type(Proc) & Required())
+        end
+
+        def initialize(location, &params)
+          super(location, params)
+        end
+
+        def build!
+          location.options[:hooks] ||= {}
+          location.options[:hooks][:after_start] = @params
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/hooks/before_fork.md

@@ -0,0 +1,13 @@
+---
+title: Before Fork
+url: /options/before_fork
+---
+
+The **before_fork** hook runs once in the master process **before** any worker processes are spawned. Use it to preload resources, open shared connections, or otherwise prepare global state.
+
+```ruby {filename=Itsi.rb}
+before_fork do
+  # this runs in the master, once before forking
+  MyCache.connect!(url: ENV["CACHE_URL"])
+end
+```

data/lib/itsi/server/config/options/hooks/before_fork.rb

@@ -0,0 +1,28 @@
+module Itsi
+  class Server
+    module Config
+      class BeforeFork < Option
+        insert_text <<~SNIPPET
+        before_fork do
+          ${1:# code to run before worker forks}
+        end
+        SNIPPET
+
+        detail "Run code before worker forks"
+
+        schema do
+          (Type(Proc) & Required())
+        end
+
+        def initialize(location, &params)
+          super(location, params)
+        end
+
+        def build!
+          location.options[:hooks] ||= {}
+          location.options[:hooks][:before_fork] = @params
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/hooks/before_restart.md

@@ -0,0 +1,12 @@
+---
+title: Before Restart
+url: /options/before_restart
+---
+
+The **before_restart** hook runs once right before the server restarts after receiving a restart signal.
+
+```ruby {filename=Itsi.rb}
+before_restart do
+  # this runs once before restarting
+end
+```

data/lib/itsi/server/config/options/hooks/before_restart.rb

@@ -0,0 +1,28 @@
+module Itsi
+  class Server
+    module Config
+      class BeforeRestart < Option
+        insert_text <<~SNIPPET
+        before_restart do
+          ${1:# code to run before worker restarts}
+        end
+        SNIPPET
+
+        detail "Run code before worker restarts"
+
+        schema do
+          (Type(Proc) & Required())
+        end
+
+        def initialize(location, &params)
+          super(location, params)
+        end
+
+        def build!
+          location.options[:hooks] ||= {}
+          location.options[:hooks][:before_restart] = @params
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/hooks/before_shutdown.md

@@ -0,0 +1,12 @@
+---
+title: Before Shutdown
+url: /options/before_shutdown
+---
+
+The **before_shutdown** hook runs once in the master process **before** the process shuts down.
+
+```ruby {filename=Itsi.rb}
+before_shutdown do
+  # this runs in the master, once before shutdown
+end
+```

data/lib/itsi/server/config/options/hooks/before_shutdown.rb

@@ -0,0 +1,28 @@
+module Itsi
+  class Server
+    module Config
+      class BeforeShutdown < Option
+        insert_text <<~SNIPPET
+        before_shutdown do
+          ${1:# code to run before worker shuts down}
+        end
+        SNIPPET
+
+        detail "Run code before worker shuts down"
+
+        schema do
+          (Type(Proc) & Required())
+        end
+
+        def initialize(location, &params)
+          super(location, params)
+        end
+
+        def build!
+          location.options[:hooks] ||= {}
+          location.options[:hooks][:before_shutdown] = @params
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+---
+title: Include
+url: /options/include
+---
+
+Use the `include` option to load additional files to be evaluated within the current configuration context.
+You can use this option to split a large configuration file into multiple smaller files.
+
+Files required using `include` are also subject to auto-reloading, when using the [auto_reload_config](/options/auto_reload_config) option.
+
+## Examples
+```ruby {filename="Itsi.rb"}
+include "middleware"
+include "logging"
+```
+
+```ruby {filename="Itsi.rb"}
+include "concurrency"
+include "security"
+```

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

@@ -0,0 +1,36 @@
+module Itsi
+  class Server
+    module Config
+      class Include < Option
+
+        insert_text "include \"${1|other_file.rb|}\" # Include another file to be loaded within the current configuration"
+
+        detail "Include another file to be loaded within the current configuration"
+
+        schema do
+          Type(String)
+        end
+
+        def build!
+          included_file = @params
+          location.instance_eval do
+            @included ||= []
+            @included << included_file
+
+            if @auto_reloading
+              if ENV["BUNDLE_BIN_PATH"]
+                watch "#{included_file}.rb", [%w[bundle exec itsi restart]]
+              else
+                watch "#{included_file}.rb", [%w[itsi restart]]
+              end
+            end
+          end
+
+          code = IO.read("#{included_file}.rb")
+          location.instance_eval(code, "#{included_file}.rb", 1)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+---
+title: Listen Backlog
+url: /options/listen_backlog
+---
+
+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}
+listen_backlog 1024
+```

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class ListenBacklog < Option
+
+        insert_text <<~SNIPPET
+        listen_backlog ${1|262_144,1_048_576|}
+        SNIPPET
+
+        detail "Specifies 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."
+
+        schema do
+          (Type(Integer) & Range(1..Float::INFINITY) & Required()).default(1024)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+---
+title: Log Format
+url: /options/log_format
+---
+
+The `log_format` option toggles between JSON and plain text logging formats. By default, it is set to plain-text. For logging structured data into an external system, it is usually recommended to use the `JSON` format.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+log_format :plain
+```
+
+## Environment Variables
+You can also set the `ITSI_LOG_FORMAT` environment variable to `json` or `plain` to control
+this. If both are set, the configuration takes precedence.
+
+## ANSI Escape codes.
+By default Itsi tries to determine whether or not to use ANSI escape codes based on the output [target](/options/log_target). If you need to override this behavior, you can set the `ITSI_LOG_ANSI` environment variable to `true` or `false`.

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class LogFormat < Option
+
+        insert_text <<~SNIPPET
+        log_format :${1|json,plain|}
+        SNIPPET
+
+        detail "This option configures the log format for the server (json/plain)."
+
+        schema do
+          (Enum([:json, :plain]) & Required()).default(:json)
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+---
+title: Log Level
+url: /options/log_level
+---
+
+The `log_level` option allows you to control the verbosity of the logs. By default, it is set to `info`.
+Valid values are `trace`, `debug`, `info`, `warn`, `error`, and `off`.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+log_level :debug
+```
+
+## Environment Variables
+You can also set the `ITSI_LOG` environment variable to to control this.
+If both are set, the configuration takes precedence.
+
+### Syntax
+
+**ITSI_LOG** uses [EnvFilter directive syntax](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax).
+
+E.g.
+```bash
+ITSI_LOG=warn # Set global log level
+```
+
+
+```bash
+ITSI_LOG=info,middleware=debug # Set global log level, and override for all targets starting with middleware::*.
+```
+
+```bash
+ITSI_LOG=warn,middleware::auth_jwt=debug,middleware=info #
+```

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

@@ -0,0 +1,20 @@
+module Itsi
+  class Server
+    module Config
+      class LogLevel < Option
+
+        insert_text <<~SNIPPET
+        log_level :${1|trace,debug,info,warn,error|}
+
+        SNIPPET
+
+        detail "This option configures the log level for the server."
+
+        schema do
+          (Enum([:trace, :debug, :info, :warn, :error]) & Required()).default(:info)
+        end
+
+      end
+    end
+  end
+end

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}
+reuse_address true
+```
+
+```ruby {filename=Itsi.rb}
+reuse_address 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/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
+```