itsi-server 0.2.22-aarch64-linux

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

@@ -0,0 +1,65 @@
+---
+title: TLS Certificates
+url: /options/certificates
+---
+
+Itsi can automatically generate TLS certificates for you, both in development and production environments.
+
+## Development / Self-signed
+To automatically generate a TLS certificate in development, just bind using the `https` scheme.
+E.g.
+```ruby {filename=Itsi.rb}
+bind "https://0.0.0.0"
+
+or
+
+bind "https://0.0.0.0:8443"
+```
+Itsi will generate a local development CA for you if it does not yet exist, then use this to
+sign a just-in-time certificate for your server.
+The local CA will by default live inside a `.itsi` directory inside your home directory.
+This directory can be overwritten using the `ITSI_LOCAL_CA_DIR` environment variable.
+
+You can add this CA to your system's trusted certificate store to avoid browser warnings in development.
+
+If you want the generated certificate to be valid for specific domains, you can add these to your bind string, and they will be added as subject alternative names (SANs). For example:
+
+```ruby {filename=Itsi.rb}
+bind "https://example.com?domains=development.example.com,development.example.org"
+```
+## Existing Certificates
+If you already have a certificate and key, you can use them by passing the path to the certificate and key files to the `bind` method.
+E.g.
+```ruby {filename=Itsi.rb}
+bind "https://example.com?cert=/path/to/cert.pem&key=/path/to/key.pem"
+```
+
+## Production Certificates (Let's Encrypt)
+If you want to use Let's Encrypt to automatically generate a production TLS certificate, you can add `cert=acme` to the bind string.
+
+E.g.
+```ruby {filename=Itsi.rb}
+bind "https://0.0.0.0?cert=acme&domains=example.com,example.org&acme_email=you@example.com"
+```
+
+You can provide several ENV variables to configure further configure the Let's Encrypt integration:
+- `ITSI_ACME_CACHE_DIR`: The directory to use to cache Let's encrypt certificates (so that these are not regenerated each time the server is restarted).
+- `ITSI_ACME_CONTACT_EMAIL`: The email address to use for Let's Encrypt account registration (overridden by the `acme_email` parameter).
+- `ITSI_ACME_CA_PEM_PATH`: Optional CA Pem path, used for testing with non-trusted CAs for certifcate generation (e.g. pebble)
+- `ITSI_ACME_DIRECTORY_URL`: Override the ACME directory URL (e.g. https://acme-staging-v02.api.letsencrypt.org/directory).
+
+{{< callout type="info" >}}
+Let's Encrypt enforces strict rate limits on production certificate generation. To verify that your configuration is correct, it's recommended to test it first using the staging directory URL. E.g.
+`ITSI_ACME_DIRECTORY_URL=https://acme-staging-v02.api.letsencrypt.org/directory`
+{{< /callout >}}
+
+
+{{< callout type="warn" >}}
+Currently only the TLS-ALPN-01 challenge type is supported for automated certificates.
+The HTTP-01 challenge is not *yet* supported. This means that, for e.g. if your server is sitting behind a CDN or reverse proxy that performs HTTPS termination, you will not be able to rely on the *automated* certificate generation for fully automated, verified e2e encryption.
+
+Instead you may wish to use:
+* [Self-signed](#development--self-signed) certificates
+* [Manually](#existing-certificates) install certificates
+* Use HTTP between the CDN and the server
+{{< /callout >}}

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

@@ -0,0 +1,14 @@
+---
+title: Daemonize
+url: /options/daemonize
+---
+
+If you set `daemonize` to true, the server will run in the background.
+(Setting `daemonize` back to false, while auto-reloading config will not return the service to the foreground).
+
+## Configuration
+```ruby {filename=Itsi.rb}
+daemonize true
+```
+
+Use `status`, `start` and `stop` to inspect server state.

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class Daemonize < Option
+
+        insert_text <<~SNIPPET
+        daemonize ${1|true,false|}
+        SNIPPET
+
+        detail "Configures whether the server should run in the background."
+
+        schema do
+          (Bool() & Required())
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+---
+title: Fiber Scheduler
+url: /options/fiber_scheduler
+---
+Itsi supports processing requests in threads that are managed by a fiber scheduler.
+This allows Itsi to process a very large number of IO heavy requests concurrently without the memory and context switching overhead of managing multiple threads.
+
+Enabling Fiber Scheduler mode can drastically improve application performance if you perform large amounts of blocking IO operations.
+
+
+## Configuration File
+```ruby {filename="Itsi.rb"}
+# Enable Itsi's fiber scheduler mode
+# (This will use an instance of `Itsi::Scheduler`
+# This is Itsi's built in Fiber scheduler.)
+fiber_scheduler true
+```
+
+```ruby {filename="Itsi.rb"}
+# In the spirit of the Fiber::Scheduler interface,
+# you can bring your own scheduler!.
+# E.g. using the scheduler from the popular Async library.
+fiber_scheduler "Async::Scheduler"
+```
+
+{{< callout type="warning" >}}
+Running in Fiber scheduler mode can be a huge performance boon, but it's not without tradeoffs. Because it enables drastically more in-flight requests,
+it can have a substantial impact on memory usage. Similarly, it can increase the amount of simultaneous demand on pooled resources (like database connections or network sockets)
+and can cause increased contention on shared locks.
+
+While well-tuned Fiber based servers can drastically outperform their blocking counterparts in some scenarios, the above compromises can make it an unsafe blanket choice, particularly for some large applications with dependencies not specifically designed for a cooperative multitasking environment.
+
+To see Itsi's recommended approach to enjoying the benefits of a Fiber scheduler while managing these risks, consider using Itsi's [hybrid mode](/options/scheduler_threads).
+{{< /callout >}}

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

@@ -0,0 +1,21 @@
+module Itsi
+  class Server
+    module Config
+      class FiberScheduler < Option
+
+        insert_text "fiber_scheduler ${1|true,'Itsi::Scheduler'|} # Enable Fiber Scheduler mode"
+
+        detail "Enable Fiber Scheduler mode"
+
+        schema do
+          Or(Bool(), (Type(String) & Required()))
+        end
+
+        def build!
+          @params = "Itsi::Scheduler" if @params == true
+          location.options[:scheduler_class] = @params if @params
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+---
+title: Header Read Timeout
+url: /options/header_read_timeout
+---
+
+Sets the maximum time (in seconds) allowed to receive the request headers. This protects against slowloris-style attacks.
+
+### Default
+
+```ruby  {filename=Itsi.rb}
+header_read_timeout 2.0
+```
+### Example
+
+```ruby  {filename=Itsi.rb}
+header_read_timeout 5.0
+```

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

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class HeaderReadTimeout < Option
+
+        insert_text <<~SNIPPET
+        header_read_timeout 2.0 # Request Timeout in Seconds
+        SNIPPET
+
+        detail "Header read timeout."
+
+        schema do
+          (Type(Float) & Required()).default(2.0) # Default 1 second
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+---
+title: Hooks
+url: /options/hooks
+---
+
+* [after_fork](/options/after_fork)
+* [after_memory_limit_reached](/options/after_memory_limit_reached)
+* [after_start](/options/after_start)
+* [before_fork](/options/before_fork)
+* [before_restart](/options/before_restart)
+* [before_shutdown](/options/before_shutdown)

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

@@ -0,0 +1,13 @@
+---
+title: After Fork
+url: /options/after_fork
+parent: /options/after_fork
+---
+
+The **after_fork** hook runs once **in each worker process** immediately after it is forked. Use it to reinitialize connections (DB, cache) that shouldn't be shared across forks.
+
+```ruby {filename=Itsi.rb}
+after_fork do
+  DB.reconnect!
+end
+```

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

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

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

@@ -0,0 +1,14 @@
+---
+title: After Memory Limit Reached
+url: /options/after_memory_limit_reached
+---
+
+The **after_memory_limit_reached** hook fires whenever a worker’s RSS memory usage exceeds a configured limit. It passes the PID of the process so you can log, alert, or take corrective action.
+
+This option works in conjunction with the [worker_memory_limit](/options/worker_memory_limit).
+
+```ruby {filename=Itsi.rb}
+after_memory_limit_reached do |pid|
+  AlertService.notify("Worker #{pid} memory exceeded limit")
+end
+```

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,21 @@
+---
+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.
+The path of the included file is evaluated relative to the current configuration file.
+
+## 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,41 @@
+module Itsi
+  class Server
+    module Config
+      class Include < Option
+        insert_text "include \"${1|other_file|}\" # 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) & Required()
+        end
+
+        def build!
+          caller_location = caller_locations(2, 1).first.path
+          included_file = \
+            if caller_location =~ %r{lib/itsi/server}
+              File.expand_path("#{@params}.rb")
+            else
+              File.expand_path("#{@params}.rb", File.dirname(caller_location))
+            end
+
+          location.instance_eval do
+            @included ||= []
+            @included << included_file
+
+            if @auto_reloading
+              if ENV["BUNDLE_BIN_PATH"]
+                watch "#{included_file}", [%w[bundle exec itsi restart]]
+              else
+                watch "#{included_file}", [%w[itsi restart]]
+              end
+            end
+          end
+
+          code = IO.read(included_file)
+          location.instance_eval(code, included_file, 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|1024,2048,4096|}
+        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