itsi-server 0.2.22-aarch64-linux

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

@@ -0,0 +1,72 @@
+---
+title: Rackup File
+url: /middleware/rackup_file
+---
+
+You can use the `rackup_file` middleware to mount a rack application defined in a Rackup file (typically `config.ru`)
+
+The alternative way to mount a rack application is to use the [`run`](/middleware/run) middleware to define a Rack app inline.
+
+You can mount several rack applications to run simultaneously within a single Itsi application, using different location blocks.
+Depending on *where* you mount the app, the application will receive different values for `PATH_INFO`, `SCRIPT_NAME`.
+
+
+{{< callout  >}}
+If no `Itsi.rb` file is defined, Itsi will attempt to run the app defined at `./config.ru` by default, just like other Rack servers. You can also use `-r` or `--rackup_file` flags to specify a different file.
+{{< /callout >}}
+
+
+## Configuration
+
+### Simple inline Rackup file.
+```ruby {filename=Itsi.rb}
+rackup_file "config.ru"
+```
+
+
+### Rack app mounted at a subpath
+```ruby {filename=Itsi.rb}
+require 'rack'
+location "/subpath/*" do
+  rackup_file "config.ru"
+end
+
+rackup_file "config.ru"
+
+```
+
+```bash
+# SCRIPT_NAME is "/subpath", path_info is "/child_path"
+$ curl http://0.0.0.0:3000/subpath/child_path
+
+# SCRIPT_NAME is "", path_info is "/root/child_path"
+$ curl http://0.0.0.0:3000/root/child_path
+:/root/child_path
+```
+
+### `SCRIPT_NAME` and `PATH_INFO` Rack ENV variables.
+Rack applications mounted at a subpath will, by default, receive a `SCRIPT_NAME` value that includes the subpath at which the app is mounted, and a `PATH_INFO` value that is relative to the subpath at which the rack app is mounted.
+If you wish to use location blocks only to control the middleware that applies to a rack app, but still have it behave as if it were mounted elsewhere (e.g. at the root), you can explicitly set the `script_name` option.
+E.g.
+
+```ruby
+location "/subpath/*" do
+  rackup_file "config.ru", script_name: '/'
+end
+```
+
+```bash
+# Our script-name override kicks in here, even though the app is mounted under `/subpath`
+$ curl http://0.0.0.0:3000/subpath/child_path
+/:/subpath/child_path
+```
+
+
+### Options
+* `nonblocking` (default false). Determines whether requests sent to this Rack application should be run on non-blocking threads. Only applies if running in hybrid (non-blocking and blocking thread pool) mode. Otherwise this is a no-op and will run in whatever mode is set globally.
+* `sendfile` (default true). Determines whether Itsi should respect the `X-Sendfile` header set by the Rack application and use the `sendfile` function to efficiently send files. (Despite the name, this does not use the OS-level `sendfile` system call). Note. Itsi enforces the restriction that the referenced file must be within a child directory of the application root.
+
+e.g.
+```ruby {filename=Itsi.rb}
+rackup_file "config.ru", nonblocking: true, sendfile: false
+```

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

@@ -0,0 +1,43 @@
+module Itsi
+  class Server
+    module Config
+      class RackupFile < Middleware
+        insert_text <<~SNIPPET
+          rackup_file \\
+            "config.ru",
+            nonblocking: ${2|true,false|},
+            sendfile: ${3|true,false|}
+
+        SNIPPET
+
+        detail "Define an inline Rack Application"
+
+        schema do
+          {
+            nonblocking: Bool().default(false),
+            script_name: Type(String).default(nil),
+            sendfile: Bool().default(true)
+          }
+        end
+
+        def initialize(location, app, **params)
+          super(location, params)
+          raise "Rackup file must be a string" unless app.is_a?(String)
+
+          @app = app
+        end
+
+        def build!
+          app_args = {
+            preloader: -> { Itsi::Server::RackInterface.for(@app) },
+            sendfile: @params[:sendfile],
+            nonblocking: @params[:nonblocking],
+            script_name: @params[:script_name],
+            base_path: "^(?<base_path>#{location.paths_from_parent.gsub(/\.\*\)$/, ")")}).*$"
+          }
+          location.middleware[:app] = app_args
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+---
+title: Rate Limiter
+url: /middleware/rate_limit
+---
+
+The **Rate Limiter** middleware enforces a fixed‑window rate limit on incoming requests. You configure a maximum number of requests allowed in a given time span, along with how to identify the client and where to store counters (in‑memory or Redis).
+
+By default it limits per IP address using an in‑memory store, but you can:
+
+- Change the window size (`requests` per `seconds`)
+- Limit based on other attributes (header or query parameter)
+- Swap to a Redis backend for cross‑process rate limiting
+- Customize the error response when the limit is exceeded
+
+## Configuration
+
+```ruby
+rate_limit \
+  requests: 100,                   # max 100 requests
+  seconds: 60,                     # per 60‑second window
+  key: "address",                  # limit by client IP
+  store_config: "in_memory",       # use local in‑memory store
+  error_response: "too_many_requests"
+```
+
+### `requests` / `seconds`
+
+- **`requests`**: Number of allowed requests in each window (positive integer).
+- **`seconds`**: Length of each fixed window in seconds (positive integer).
+
+### `key`
+
+How to identify the client:
+
+- **`"address"`** (default): use the client’s socket IP.
+- **Header or query parameter**:
+  ```ruby
+  key: { parameter: { header: { name: "X-Api-Key-Id" } } }
+  ```
+  or
+  ```ruby
+  key: { parameter: { query: "user_id" } }
+  ```
+
+### `store_config`
+
+Where to keep counters:
+
+- **`"in_memory"`** (default): per‑process, reset when server restarts.
+- **Redis** (shared across workers):
+  ```ruby
+  store_config: { redis: { connection_url: "redis://localhost:6379/1" } }
+  ```
+
+### `error_response`
+
+Customizes the response when the limit is reached (default is built‑in `too_many_requests`):
+
+```ruby
+error_response: {
+  code: 429,
+  plaintext: { inline: "Rate limit exceeded" },
+  default:   "plaintext"
+}
+```
+
+## Rate Limit Response Headers
+
+When a request **exceeds** the allowed rate, the middleware returns your configured error response **plus** these headers:
+
+| Header                    | Meaning                                                                                  |
+|---------------------------|------------------------------------------------------------------------------------------|
+| **X-RateLimit-Limit**       | The maximum number of requests allowed per window (`requests` value).                    |
+| **X-RateLimit-Remaining**   | How many requests remain in the current window (will be `0` once the limit is hit).      |
+| **X-RateLimit-Reset**       | Seconds until the current window resets (time until your counter zeroes out).            |
+| **Retry-After**             | Same value as `X-RateLimit-Reset` — suggests when clients should retry their request.    |
+
+> **Example**
+> With `requests: 5, seconds: 60`, after 5 calls the 6th returns:
+> ```
+> 429 Too Many Requests
+> X-RateLimit-Limit:     5
+> X-RateLimit-Remaining: 0
+> X-RateLimit-Reset:     42
+> Retry-After:           42
+> ```
+
+## How It Works
+
+1. **On each request**
+   - Compute the client key (IP, header, or query).
+   - Increment a counter for the current time window.
+
+2. **Fixed‑window logic**
+   - If the counter ≤ `requests`, allow through.
+   - Otherwise, immediately return the configured `error_response` plus the **X-RateLimit** headers.
+
+3. **Store options**
+   - **In‑memory**: simple hash, fast but not shared across processes.
+   - **Redis**: atomic `INCR` + `EXPIRE` commands, shared across all workers.
+
+Place `rate_limit` anywhere in your routing DSL to apply it to all downstream handlers in that scope.
+
+
+## Trusted Proxies
+
+By default, a rate limiter middleware uses the IP address from the underlying socket (remote_addr). However, if your server is behind a reverse proxy, all requests will appear to come from the proxy’s IP address. This can break IP-based rules or cause rate-limiting to group all users together.
+
+To address this, you can declare trusted proxies and instruct the server to extract the original client IP from forwarded headers only if the request came from one of these proxies.
+
+
+### Configuring trusted_proxies
+
+To trust one or more upstream proxies, provide a trusted_proxies map in the middleware configuration.
+E.g.
+```ruby {filename=Itsi.rb}
+rate_limit \
+  requests: 100,                   # max 100 requests
+  seconds: 60,                     # per 60‑second window
+  key: "address",                  # limit by client IP
+  store_config: "in_memory",       # use local in‑memory store
+  error_response: "too_many_requests",
+  trusted_proxies: {
+    "192.168.1.1" => { header: { name: "X-Forwarded-For" } }
+  }
+```

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

@@ -0,0 +1,34 @@
+module Itsi
+  class Server
+    module Config
+      class RateLimit < Middleware
+        require_relative "rate_limit_store"
+        require_relative "token_source"
+
+        insert_text <<~SNIPPET
+        rate_limit \\
+          requests: ${1|1,5,100|},
+          seconds: ${2|1,5,100|},
+          key: ${3|"address",{parameter:{header:{name:"X-Forwarded-For"}}}|},
+          store_config: ${4|"in_memory",{redis:{connection_url: "redis://localhost:6379"}}|},
+          error_response: ${5|"too_many_requests", { code: 429\\, default_format: "html"\\, html: { inline: "<h1>Unauthorized</h1>" } }|}
+        SNIPPET
+
+        detail "Automatically limits the number of requests a client can make within a given time period."
+
+
+        schema do
+          {
+            requests: Required() & Type(Integer) & Range(1..2**32),
+            seconds: Required() & Type(Integer) & Range(1..2**32),
+            key: (Required() & Or(Enum(["address"]), Type(RateLimitKey))).default("address"),
+            store_config: (Required() & Or(Enum(["in_memory"]), Type(RateLimitStore))).default("in_memory"),
+            error_response: Type(ErrorResponseDef).default("too_many_requests"),
+            trusted_proxies: (Hash(Type(String), Type(TokenSource)) & Required()).default({})
+          }
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Itsi
+  class Server
+    module Config
+
+      RateLimitKey = TypedStruct.new do
+        {
+          parameter: Or(
+            Hash(Enum(["header"]), Hash(Enum(["name"]), Type(String))) & Required(),
+            Hash(Enum(["query"]), Type(String)) & Required()
+          )
+        }
+      end
+
+      RateLimitStore = TypedStruct.new do
+        {
+          redis: Type(TypedStruct.new do
+            {
+              connection_url: Type(String)& Required()
+            }
+          end) & Required()
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+---
+title: Redirect
+url: /middleware/redirect
+---
+
+The Redirect middleware enables automatic redirection of incoming requests to a different URL. It computes the target URL using a string rewrite rule and responds with an HTTP redirect status code based on the configuration. Once the middleware processes a request, it immediately returns a redirection response without further processing.
+
+## Redirect configuration
+
+```ruby
+redirect \
+  to: "https://example.com/new-path", \
+  type: "permanent"
+```
+
+## Redirect Applied to a sub-location
+
+```ruby
+location "/old-path" do
+  redirect \
+    to: "https://example.com/new-path", \
+    type: "temporary"
+  # No further route processing occurs for /old-path.
+end
+```
+## Redirect HTTP to HTTPS
+
+```ruby
+location protocols: [:http] do
+  redirect \
+    to: "https://{host}{path_and_query}", \
+    type: "moved_permanently"
+end
+```
+> A shorthand for the above exists, call `redirect_http_to_https!`. Note that this is
+an alias for the above, and as such 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.
+
+
+
+## Configuration Options
+
+- **to**:
+  A [string rewrite rule](/middleware/string_rewrites) (or literal string) specifying the target URL for the redirection. This value can incorporate dynamic portions of the incoming request.
+
+- **type**:
+  Specifies the type of redirection. Allowed values include:
+  - `"permanent"`: Responds with a 308 Permanent Redirect.
+  - `"temporary"`: Responds with a 307 Temporary Redirect.
+  - `"moved_permanently"`: Responds with a 301 Moved Permanently.
+  - `"found"`: Responds with a 302 Found.
+
+## How It Works
+
+When a request is received, the Redirect middleware immediately intercepts it and builds a redirect response. The target URL is computed via the provided rewrite rule (`to`), and the response is sent with the appropriate HTTP status code as determined by the `type` option. No further handling is performed on the request.

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

@@ -0,0 +1,25 @@
+module Itsi
+  class Server
+    module Config
+      class Redirect < Middleware
+
+        insert_text <<~SNIPPET
+        redirect \\
+          to: "${1:https://example.com/new-path}",
+          type: ${2|"permanent","temporary","found","moved_permanently"|}
+        SNIPPET
+
+        detail "Automatically redirects incoming requests to a new URL based on a string rewrite rule."
+
+        Redirect = TypedStruct.new do
+          {
+            to: (Required() & Type(String)),
+            type: Enum(["permanent", "temporary", "found", "moved_permanently"]).default("moved_permanently")
+          }
+        end
+
+        schema Redirect
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+---
+title: Request Headers
+url: /middleware/request_headers
+---
+
+The **Request Headers** middleware lets you add, override or remove HTTP headers **before** your application handler sees the request. You can inject static values or use the full power of [String Rewrite](/middleware/string_rewrite) to generate header values based on path, query, method, etc.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+request_headers \
+  additions: {
+    "X-Correlation-ID" => ["{request_id_full}"],
+    "X-Env"            => ["production"]
+  },
+  removals: ["X-Forwarded-For"]
+```
+
+- **additions** (`Hash(String,Array(StringRewrite))`)
+  A map of header names to an array of StringRewrite templates. Each template is rendered **after** removals.
+- **removals** `Array(String)`
+  A list of header names to delete outright. If you want to override an existing header, include it in **both** removals and additions.
+
+## Examples
+```ruby {filename=Itsi.rb}
+# Add a per‑request UUID and drop any X‑Forwarded‑For header
+request_headers \
+  additions: { "X-Correlation-ID" => ["{request_id}"] },
+  removals:  ["X-Forwarded-For"]
+
+# Inject the full request path and query
+request_headers \
+  additions: { "X-Full-URL" => ["{path_and_query}"] },
+  removals:  []
+```

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

@@ -0,0 +1,24 @@
+module Itsi
+  class Server
+    module Config
+      class RequestHeaders < Middleware
+
+        insert_text <<~SNIPPET
+        request_headers \\
+          additions: { ${1:"X-Correlation-ID" => ["{request_id_full\\}"]} },
+          removals:  [${2:"X-Forwarded-For"}]
+        SNIPPET
+
+        detail "Add, override or remove request headers before reaching your handler."
+
+        schema do
+          {
+            additions: Hash(Type(String), Array(Type(String))).default({}),
+            removals: Array(Type(String)).default([]),
+            combine: Bool().default(true)
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+---
+title: Response Headers
+url: /middleware/response_headers
+---
+
+The **Response Headers** middleware lets you add, override or remove HTTP headers **after** your application handler has produced a response. You can attach static values or dynamically compute them via [String Rewrite](/middleware/string_rewrite).
+
+## Configuration
+```ruby {filename=Itsi.rb}
+response_headers \
+  additions: {
+    "X-Processed-By"        => ["Itsi"],
+    "X-Response-Time-Millis" => ["{response_time}"]
+  },
+  removals: ["Server"]
+```
+- **additions** `Hash(String,Array(StringRewrite))`
+  A map of header names to StringRewrite templates. Templates are evaluated against the final response and context in **after**.
+- **removals** `Array(String)`
+  A list of header names to delete before adding new ones.
+
+## Examples
+```ruby {filename=Itsi.rb}
+# Stamp every response with our server name
+response_headers \
+  additions: { "X-Powered-By" => ["Itsi"] },
+  removals:  []
+
+# Remove the Server header and add timing info
+response_headers \
+  additions: { "X-Response-Time" => ["{response_time}"] },
+  removals:  ["Server"]
+```

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

@@ -0,0 +1,25 @@
+module Itsi
+  class Server
+    module Config
+      class ResponseHeaders < Middleware
+
+        insert_text <<~SNIPPET
+          response_headers \\
+            additions: { ${1:"X-Powered-By" => ["Itsi"]} },
+            removals:  [${2:"Server"}]
+          SNIPPET
+
+
+        detail "Add, override or remove response headers before sending to the client."
+
+        schema do
+          {
+            additions: Hash(Type(String), Array(Type(String))).default({}),
+            removals: Array(Type(String)).default([]),
+            combine: Bool().default(true)
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+---
+title: Run
+url: /middleware/run
+---
+
+You can use the `run` middleware to run an inline rack application.
+The alternative way to mount a rack application is to use a [`rackup_file`](/middleware/rackup_file) middleware.
+
+You can mount several rack applications  to run simultaneously within a single Itsi application, using different location blocks.
+Depending on *where* you mount the app, the application will receive different values for `PATH_INFO`, `SCRIPT_NAME`.
+
+## Configuration
+
+### Simple inline Rack app.
+```ruby {filename=Itsi.rb}
+run ->(env){ [200, { 'content-type' => 'text/plain' }, ['OK']] }
+```
+
+### Rack app using Rack::Builder
+```ruby {filename=Itsi.rb}
+run(Rack::Builder.app do
+  use Rack::CommonLogger
+  run ->(env) { [200, { 'content-type' => 'text/plain' }, ['OK']] }
+end)
+```
+
+
+### Rack app mounted at a subpath
+```ruby {filename=Itsi.rb}
+require 'rack'
+location "/subpath/*" do
+  run(Rack::Builder.app do
+    use Rack::CommonLogger
+    run ->(env) { [200, { 'content-type' => 'text/plain' }, [[env['SCRIPT_NAME'], env['PATH_INFO']].join(":") ]  ] }
+  end)
+end
+
+run(Rack::Builder.app do
+  use Rack::CommonLogger
+  run ->(env) { [200, { 'content-type' => 'text/plain' }, [[env['SCRIPT_NAME'], env['PATH_INFO']].join(":") ]  ] }
+end)
+```
+
+```bash
+$ curl http://0.0.0.0:3000/subpath/child_path
+/subpath:/child_path
+
+$ curl http://0.0.0.0:3000/root/child_path
+:/root/child_path
+```
+
+### `SCRIPT_NAME` and `PATH_INFO` Rack ENV variables.
+Rack applications mounted at a subpath will, by default, receive a `SCRIPT_NAME` value that includes the subpath at which the app is mounted, and a `PATH_INFO` value that is relative to the subpath at which the rack app is mounted.
+If you wish to use location blocks only to control the middleware that applies to a rack app, but still have it behave as if it were mounted elsewhere (e.g. at the root), you can explicitly set the `script_name` option.
+E.g.
+
+```ruby
+location "/subpath/*" do
+  run(Rack::Builder.app do
+    use Rack::CommonLogger
+    run ->(env) { [200, { 'content-type' => 'text/plain' }, [[env['SCRIPT_NAME'], env['PATH_INFO']].join(":") ]  ] }
+  end, script_name: '/')
+end
+```
+
+```bash
+# Our script-name override kicks in here, even though the app is mounted under `/subpath`
+$ curl http://0.0.0.0:3000/subpath/child_path
+/:/subpath/child_path
+```
+
+### Options
+* `nonblocking` (default false). Determines whether requests sent to this Rack application should be run on non-blocking threads. Only applies if running in hybrid (non-blocking and blocking thread pool) mode. Otherwise this is a no-op and will run in whatever mode is set globally.
+* `sendfile` (default true). Determines whether Itsi should respect the `X-Sendfile` header set by the Rack application and use the `sendfile` function to efficiently send files. (Despite the name, this does not use the OS-level `sendfile` system call). Note. Itsi enforces the restriction that the referenced file must be within a child directory of the application root.
+
+e.g.
+```ruby {filename=Itsi.rb}
+run ->(env){ [200, { 'content-type' => 'text/plain' }, ['OK']] }, nonblocking: true, sendfile: false
+```

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

@@ -0,0 +1,45 @@
+module Itsi
+  class Server
+    module Config
+      class Run < Middleware
+
+        insert_text <<~SNIPPET
+        run \\
+          ${1:->(env){[200, {"Content-Type" => "text/plain"\\}, ["Hello, World!"]]}},
+          nonblocking: ${2|true,false|},
+          sendfile: ${3|true,false|}
+        SNIPPET
+
+        detail "Define an inline Rack Application"
+
+        schema do
+          {
+            nonblocking: Bool().default(false),
+            script_name: Type(String).default(nil),
+            sendfile: Bool().default(true)
+          }
+        end
+
+        def initialize(location, app, params={})
+          super(location, params)
+          raise "App must be a Rack application" unless app.respond_to?(:call)
+          @app = app
+        end
+
+        def build!
+          app_args = {
+            preloader: -> { Itsi::Server::RackInterface.for(@app) },
+            sendfile: @params[:sendfile],
+            nonblocking: @params[:nonblocking],
+            script_name: @params[:script_name],
+            base_path: "^(?<base_path>#{location.paths_from_parent.gsub(/\.\*\)$/, ')')}).*$"
+          }
+          location.middleware[:app] = app_args
+          location.location("*") do
+            @middleware[:app] = app_args
+          end
+        end
+      end
+    end
+  end
+end