itsi-server 0.1.1 → 0.2.2

data/lib/itsi/server/config/middleware/static_response.md

@@ -0,0 +1,44 @@
+---
+title: Static Response
+url: /middleware/static_response
+---
+
+The **Static Response** middleware returns a fixed HTTP response immediately, without invoking any downstream handlers. You configure the status code, headers, and body content once, and every request is answered identically.
+
+## Key Features
+- **Fixed Status Code**: Return any valid HTTP status (200–599).
+- **Custom Headers**: Pre‑set arbitrary headers (e.g. Content‑Type, Cache‑Control).
+- **Arbitrary Body**: Supply text or binary data as the response payload.
+- **Zero Routing**: Always handles the request; bypasses your application logic entirely.
+
+## Example Usage
+```ruby {filename=Itsi.rb}
+static_response \
+  code:    200,
+  headers: [
+    ["Content-Type", "application/json"],
+    ["Cache-Control", "max-age=60"]
+  ],
+  body:    "{\"message\":\"OK\"}"
+```
+
+Every request now returns HTTP 200 with JSON body `{"message":"OK"}` and the prescribed headers.
+
+## Configuration Options
+
+| Option    | Type                        | Description                                                                                     |
+|-----------|-----------------------------|-------------------------------------------------------------------------------------------------|
+| **code**  | Integer                     | HTTP status code to return (e.g. 200, 404, 500).                                                |
+| **headers**| Array of [String,String]   | List of header name/value pairs to include.                                                     |
+| **body**  | Array<UInt8>                | Raw response body bytes. For text, use `string.bytes`.                                          |
+
+```ruby
+# Example in Itsi.rb
+static_response \
+  code:    404,
+  headers: [
+    ["Content-Type", "text/plain"],
+    ["X-Error",        "NotFound"]
+  ],
+  body:    "Page not found"
+```

data/lib/itsi/server/config/middleware/static_response.rb

@@ -0,0 +1,29 @@
+module Itsi
+  class Server
+    module Config
+      class StaticResponse < Middleware
+        insert_text <<~SNIPPET
+        static_response \\
+          code: ${1|200,404,500|}, \\
+          headers: [${2|["Content-Type","text/plain"],["Cache-Control","max-age=60"]|}], \\
+          body: ${3|"OK".bytes, "Not Found".bytes|}
+        SNIPPET
+
+        detail "Immediately return a fixed HTTP response with code, headers, and body."
+
+        schema do
+          {
+            code:    (Type(Integer) & Required()),
+            headers: Array(Array(Type(String), Type(String))).default([]),
+            body:    Type(String).default("")
+          }
+        end
+
+        def initialize(location, params)
+          super
+          @params[:body] = @params[:body].bytes
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/middleware/string_rewrite.md

@@ -0,0 +1,67 @@
+---
+title: String Rewrites
+url: /middleware/string_rewrites
+next: faqs/
+---
+
+The String Rewrite mechanism is used when configuring Itsi for
+* [Reverse Proxying](/middleware/proxy)
+* [Redirects](/middleware/redirect)
+* [Logging](/middleware/log_requests)
+* [Request Headers](/middleware/request_headers)
+* [Response Headers](/middleware/response_headers)
+
+It allows you to create dynamic strings from a template by combining literal text with placeholders. Placeholders (denoted using curly braces: `{}`) are replaced at runtime with data derived from the HTTP request, response, or context.
+
+### Rewriting a Request
+
+The following placeholders are supported:
+
+- **`request_id`**: A short unique identifier for the request.
+- **`request_id_full`**: The full request identifier.
+- **`method`**: The HTTP request method (e.g., GET, POST).
+- **`path`**: The URL path of the request.
+- **`addr`**: The client IP address.
+- **`host`**: The host portion of the URL (defaults to `localhost` if unspecified).
+- **`path_and_query`**: The combination of the URL path and query string.
+- **`query`**: The query string (prepended with a `?` if non-empty).
+- **`port`**: The port number (defaulting to `80` if not available).
+- **`start_time`**: The formatted start time of the request.
+- **`<Header-Name>`**: Any existing response header. For example `{Content-Type}` or `{Set-Cookie}` will be replaced with its current value.
+
+The mechanism also allows any available matching regex capture from routes defined in the [location](/middleware/location) block.
+If no match is found, otherwise, the placeholder remains unchanged (i.e. it is rendered as `{placeholder_name}`).
+
+## Rewriting a Response
+
+When you use String Rewrite in `response_headers`, you can refer to built‑in response fields **and** any header in the outgoing response:
+
+- **`status`**: The HTTP status code (e.g., `200`, `404`).
+- **`response_time`**: The computed response time, formatted (e.g., `12.345ms`).
+- **`<Header-Name>`**: Any existing response header. For example `{Content-Type}` or `{Set-Cookie}` will be replaced with its current value.
+
+If a header placeholder does not exist on the response, it will render as `{Header-Name}`.
+
+## Example Templates
+
+### Reverse Proxying
+
+When acting as a reverse proxy, you might want to forward the request to a backend service. For example, if your backend service expects the complete path and query string appended to its URL, you could use:
+
+```ruby
+"https://backend.example.com/api{path}{query}"
+```
+
+For an incoming request to `/v1/resource?x=1`, this template rewrites the target URL to:
+`https://backend.example.com/api/v1/resource?x=1`
+
+### Redirects
+
+For redirect middleware, a common use case is to guide clients from an old URL to a new one. For instance:
+
+```ruby
+"https://new.example.com{path}?source=redirect"
+```
+
+If a request comes in to `/old-section?foo=bar`, the rewrite produces:
+`https://new.example.com/old-section?source=redirect`

data/lib/itsi/server/config/middleware/token_source.rb

@@ -0,0 +1,32 @@
+module Itsi
+  class Server
+    module Config
+
+      HeaderSource = TypedStruct.new do
+        {
+          name: Type(String) & Required(),
+          prefix: Type(String)
+        }
+      end
+
+      HeaderSourceOuter = TypedStruct.new do
+        {
+          header: Type(HeaderSource)
+        }
+      end
+
+      QuerySource = TypedStruct.new do
+        {
+          query: Type(String) & Required()
+        }
+      end
+
+      TokenSource = TypedStruct.new do
+        Or(
+          Type(HeaderSourceOuter),
+          Type(QuerySource)
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Itsi
+  class Server
+    module Config
+      class Middleware
+        include ConfigHelpers
+
+        def build!
+          location.middleware[self.class.middleware_name] = @params
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Itsi
+  class Server
+    module Config
+      class Option
+        include ConfigHelpers
+
+
+        def build!
+          location.options[self.class.option_name] = @params
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+---
+title: Options
+type: docs
+next: auto_reload_config/
+url: /options
+prev: configuration/
+cascade:
+  type: docs
+weight: 1
+---
+
+Most of Itsi's capabilities are unlocked via the Itsi.rb config file.
+The config file uses a simple DSL, where you can write plain Ruby to define your application's configuration.
+For the best development experience, be sure to use [RubyLSP](https://shopify.github.io/ruby-lsp/) for snippets, autocomplete and documentation, right in your editor.
+
+{{< details title="An example Itsi.rb file:" >}}
+
+
+```ruby {filename="Itsi.rb"}
+workers 2
+threads 2
+scheduler_threads 3
+
+fiber_scheduler true
+
+rate_limiter requests: 100, seconds: 10
+
+auth_basic realm: "Restricted Area", credentials_file: "credentials.txt"
+
+location "/app" do
+  get "/" do |req|
+    req.ok "Hello, World!"
+  end
+end
+
+```
+{{< /details >}}

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

@@ -0,0 +1,13 @@
+---
+title: Auto Reload Config
+url: /options/auto_reload_config
+prev: options/
+---
+
+Auto reload config is a feature that allows the server to automatically reload the configuration file when it is modified. This feature is useful when you want to make changes to the configuration file without having to restart the server.
+
+To opt in to config auto reloading, add the following line to your configuration file:
+
+```ruby {filename=Itsi.rb}
+auto_reload_config!
+```

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

@@ -0,0 +1,41 @@
+module Itsi
+  class Server
+    module Config
+      class AutoReloadConfig < Option
+
+        insert_text <<~SNIPPET
+        auto_reload_config! # Auto-reload the server configuration each time it changes.
+        SNIPPET
+
+        detail "Auto-reload the server configuration each time it changes."
+
+        def self.option_name
+          :auto_reload_config!
+        end
+
+        def build!
+          location.instance_eval do
+            return if @auto_reloading
+
+            if @included
+              @included.each do |file|
+                if ENV["BUNDLE_BIN_PATH"]
+                  watch "#{file}.rb", [%w[bundle exec itsi restart]]
+                else
+                  watch "#{file}.rb", [%w[itsi restart]]
+                end
+              end
+            end
+            @auto_reloading = true
+
+            if ENV["BUNDLE_BIN_PATH"]
+              watch "Itsi.rb", [%w[bundle exec itsi restart]]
+            else
+              watch "Itsi.rb", [%w[itsi restart]]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+---
+title: Bind
+url: /options/bind
+---
+
+The **Bind** option instructs Itsi on which network interfaces to listen on.
+It supports various protocols and formats to allow flexible binding to TCP/IP addresses or Unix sockets, with optional TLS configuration.
+You can bind to multiple interfaces at once.
+
+## Bind Formats
+
+You can specify the bind address as a URI. Common formats include:
+
+- **TCP/HTTP:**
+  ```ruby
+  bind "http://0.0.0.0:3000"
+  ```
+  Listens on all interfaces on port 3000 using plain HTTP.
+
+- **TCP/HTTPS:**
+  ```ruby
+  bind "https://0.0.0.0:3000?cert=/path/to/cert.pem&key=/path/to/key.pem"
+  ```
+  Listens on all interfaces on port 3000 using HTTPS.
+  TLS options (e.g. certificates) can be provided via query parameters. You can also use `cert=acme` with additional ACME parameters to enable automatic certificate retrieval.
+  E.g.
+
+  ```ruby
+  bind "https://0.0.0.0:3000?cert=acme&acme_email=example@example.com&domains=domain1.com,domain2.com"
+  ```
+
+- **Unix Socket:**
+  ```ruby
+  bind "unix:///tmp/itsi.sock"
+  ```
+  Listens using a Unix domain socket.
+
+- **TLS over Unix Socket:**
+  ```ruby
+  bind "tls:///tmp/itsi.sock"
+  ```
+  Listens using a Unix socket while enabling TLS.
+
+## Configuration File
+
+In your configuration file (typically `Itsi.rb`), specify the bind option using the `bind` function.
+
+## Examples
+
+```ruby {filename="Itsi.rb"}
+# Bind to all interfaces on port 3000 with HTTP:
+bind "http://0.0.0.0:3000"
+```
+
+```ruby {filename="Itsi.rb"}
+# Bind to all interfaces on port 3000 with HTTPS using certificate files:
+bind "https://0.0.0.0:3000?cert=/path/to/cert.pem&key=/path/to/key.pem"
+```
+
+```ruby {filename="Itsi.rb"}
+# Bind to a Unix socket:
+bind "unix:///tmp/itsi.sock"
+```
+
+## Command Line
+
+Bind addresses can also be specified from the command line via the `-b` or  `--bind` option:
+
+```bash
+itsi -b "http://0.0.0.0:3000" -b "https://0.0.0.0:3001"
+```

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

@@ -0,0 +1,26 @@
+module Itsi
+  class Server
+    module Config
+      class Bind < Option
+
+        insert_text <<~SNIPPET
+        bind "${1|http://0.0.0.0:3000,https://0.0.0.0:3000,http://0.0.0.0,https://0.0.0.0,unix:///tmp/itsi.sock,tls:///tmp/itsi.sock,https://0.0.0.0?cert=/path/to/cert.pem&key=/path/to/key.pem,https://0.0.0.0?cert=acme&domains=domain.com&acme_email=user@example.com,https://0.0.0.0:3001?domains=devdomain.com,http://0.0.0.0:9292,http://0.0.0.0:8080,https://0.0.0.0:8443|}"
+        SNIPPET
+
+        detail "Bind the server to a specific address and port."
+
+        schema do
+          Type(String) & Required()
+        end
+
+        def initialize(location, params={})
+          super
+        end
+
+        def build!
+          (@location.options[:binds] ||= []) << @params
+        end
+      end
+    end
+  end
+end

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://localhost"
+
+or
+
+bind "https://localhost: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
+```