itsi-server 0.2.22-aarch64-linux

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

@@ -0,0 +1,113 @@
+---
+title: Static Assets
+url: /middleware/static_assets
+---
+
+The Static Assets middleware serves files from a specified root directory. It is capable of optimized delivery of static content such as HTML, CSS, JavaScript, images, as well as large assets, such as video files using streaming bodies and range requests.
+It can auto-index directories for simple directory listings.
+
+## Key Features
+- **Auto Indexing**: Optionally generate directory listings when an index file is missing.
+- **HTML Fallback**: When enabled, the middleware attempts to serve a file with a `.html` extension if the requested file is not found.
+- **In-Memory Caching**: Files under a certain size (and up to a configurable count) are cached in memory for performance.
+- **Custom Headers**: User-supplied headers (e.g., for caching) can be added to responses.
+- **Relative Path Processing**: When enabled, the middleware rewrites request paths relative to a configured base path.
+- **Partial Content**: Supports Range requests for serving partial file content.
+
+## Example
+
+```ruby {filename=Itsi.rb}
+static_assets root_dir: "./"
+```
+
+### Directory Index
+#### HTML
+
+  {{< card link="/" title="Static File Server" image="/directory_listing.jpg" subtitle="Static File Listing, Powered by Itsi." method="Resize" options="500x q80 webp" >}}
+
+#### JSON
+Directory indexes also support responding in JSON format. E.g.
+
+`curl -H "Accept: application/json" http://0.0.0.0`
+
+```json
+{
+  "directory": ".",
+  "items": [
+    {
+      "is_dir": false,
+      "modified": "2025-04-22 04:21:43",
+      "name": "Gemfile",
+      "path": "Gemfile",
+      "size": "42 B"
+    },
+    {
+      "is_dir": false,
+      "modified": "2025-04-22 04:21:48",
+      "name": "Gemfile.lock",
+      "path": "Gemfile%2Elock",
+      "size": "463 B"
+    },
+    {
+      "is_dir": false,
+      "modified": "2025-04-22 02:46:45",
+      "name": "Itsi.rb",
+      "path": "Itsi%2Erb",
+      "size": "80 B"
+    }
+  ],
+  "title": "Directory listing for ."
+}
+```
+
+## Configuration Options
+
+
+| Option                         | Description                                                                                                                                                                                                                           |
+|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`root_dir`** (Default ".")                | The relative or absolute disk path where static files reside.                                                                                                                                                                                   |
+| **`not_found_behavior`** (Default `{error: "not_found"}`)       | Determines what to do when a file isn’t found. See [Not Found Behavior](#not-found-behavior) below. |
+| **`auto_index`** (Default `false`)            | If <code>true</code>, directory listings are automatically generated when no index file is found. Defaults to <code>false</code>.                                                                                                    |
+| **`try_html_extension`** (Default `true`)      | If <code>true</code>, when the requested file isn’t found, the middleware attempts to serve the same path with a <code>.html</code> extension. Defaults to <code>true</code>.                                                 |
+| **`max_file_size_in_memory`** (Default `1048576`)  | Maximum file size (in bytes) for caching files in memory. Files larger than this will be served from disk. Defaults to <code>1048576</code> (1 MB).                                                                                |
+| **`max_files_in_memory`** (Default `100`)      | Maximum number of files to cache in memory. Defaults to <code>100</code>.                                                                                                                                                             |
+| **`file_check_interval`** (Default `1`)      | Max time (in seconds) a file stays in cache before the file-system is checked for modifications. Defaults to <code>1</code>.                                                                                                                                                |
+| **`headers`** (Default `nil`)                 | A hash of additional headers to include in responses (e.g. <code>{"Cache-Control" => "max-age=3600"}</code>).                                                                                                                         |
+| **`allowed_extensions`** (Default `[]`)       | An array of permitted file extensions (e.g. <code>["html", "css", "js", "png", "jpg"]</code>). If a requested file’s extension isn’t in this list, it won’t be served. An empty list (default) means all extensions are allowed.                                                           |
+| **`relative_path`** (Default `true`)           | If <code>true</code>, the effective file lookup path is computed relative to the base path at which the middleware is mounted (See [location](/middleware/location) to understand mounting options). Defaults to <code>true</code>.                                                                                               |
+| **`serve_hidden_files`** (Default `false`)       | If <code>false</code>, files whose names start with a dot (".") are not served. Defaults to <code>false</code>.                                                                                                                        |
+
+
+## Not Found Behavior
+The static assets middleware supports many configuration options when a file is not found.
+* **`fallthrough`**: The request is *not* handled by this middleware and is instead served by the next middleware in the chain. The option is given as a string. E.g.
+```ruby
+error_response: "fallthrough"
+```
+* **`index`**: Unsatisfiable requests instead result in serving an index file. (Useful for SPAs with client-side routing).
+```ruby
+error_response: {index: "./path/to/index.html" }
+```
+* **`redirect`**: Unsatisfiable requests are redirected. Options for type are the same as defined for the [redirect](/middleware/redirect) middleware.
+```ruby
+error_response: {redirect: { to: "http://example.com/redirect_path", type: "permanent" }}
+```
+* **`error`**: Provide an overridden error response. See [`error_response`](/middleware/error_response) for details.
+e.g.
+```ruby
+error_response: {error: "not_found"}
+```
+
+```ruby
+error_response: \
+  {
+    error:
+    {
+      code: 404,
+      plaintext: {inline: "File not found"},
+      json: {inline: "{\"message\": \"File not found\"}"},
+      html: {file: "./path/to/not_found.html"},
+      default: "plaintext"
+    }
+  }
+```

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

@@ -0,0 +1,99 @@
+module Itsi
+  class Server
+    module Config
+      class StaticAssets < Middleware
+
+        insert_text <<~SNIPPET
+          static_assets \\
+            root_dir: "${1|./,/var/www,|}",
+            not_found_behavior: ${2|"fallthrough",{index: "index.html"},{error: "not_found"}|},
+            auto_index: ${3|true,false|},
+            try_html_extension: ${4|true,false|},
+            max_file_size_in_memory: ${5|1048576,2097152|},
+            max_files_in_memory: ${6|100,500,1000|},
+            file_check_interval: ${7|1,60,120|},
+            headers: { ${8|,"Cache-Control" => "max-age=3600",|} },
+            allowed_extensions: ${9|%w[html css js png jpg],[]|},
+            relative_path: ${10|true,false|},
+            serve_hidden_files: ${11|true,false|}
+        SNIPPET
+
+        detail "Serves static files from a designated directory with options for auto indexing, in-memory caching, "\
+          "and custom header support. Supports relative path rewriting and file range requests."
+
+        ErrorResponse = TypedStruct.new do
+          {
+            error: Type(ErrorResponseDef) & Required()
+          }
+        end
+
+        IndexResponse = TypedStruct.new do
+          {
+            index: Type(String) & Required()
+          }
+        end
+
+        RedirectTarget = TypedStruct.new do
+          {
+            to: (Required() & Type(String)),
+            type: Enum(["permanent", "temporary", "found", "moved_permanently"]).default("moved_permanently")
+          }
+        end
+
+        RedirectResponse = TypedStruct.new do
+          {
+            redirect: Type(RedirectTarget) & Required()
+          }
+        end
+
+        schema do
+          {
+            root_dir: (Type(String) & Required()).default("./"),
+            not_found_behavior: Or(
+              Enum(%w[fallthrough index redirect internal_server_error]),
+              Type(IndexResponse),
+              Type(RedirectResponse),
+              Type(ErrorResponse)
+            ).default({error: "not_found"}),
+            allowed_extensions: (Array(Type(String)) & Required()).default([]),
+            auto_index: Bool().default(false),
+            try_html_extension: Bool().default(true),
+            max_file_size_in_memory: Type(Integer).default(1048576),
+            max_files_in_memory: Type(Integer).default(100),
+            file_check_interval: Type(Integer).default(1),
+            headers: Hash(Type(String), Type(String)).default({}),
+            relative_path: Bool().default(true),
+            serve_hidden_files: Bool().default(false)
+          }
+        end
+
+        def build!
+          root_dir = @params[:root_dir] || "."
+
+          if !File.exist?(root_dir)
+            raise "Warning: static_assets root_dir '#{root_dir}' does not exist!"
+          elsif !File.directory?(root_dir)
+            raise "Warning: static_assets root_dir '#{root_dir}' is not a directory!"
+          end
+
+          @params[:relative_path] = true unless @params.key?(:relative_path)
+          @params[:allowed_extensions] ||= []
+
+          if @params[:try_html_extension] && @params[:allowed_extensions].include?("html")
+            @params[:allowed_extensions] << ""
+          end
+
+          if @params[:allowed_extensions].any? && @params[:auto_index]
+            @params[:allowed_extensions] |= ["html"]
+            @params[:allowed_extensions] |= [""]
+          end
+
+          @params[:base_path] = "^(?<base_path>#{location.paths_from_parent.gsub(/\.\*\)$/,")")}).*$"
+          params = @params
+
+          location.middleware[:static_assets] = params
+        end
+      end
+    end
+  end
+end

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,30 @@
+module Itsi
+  class Server
+    module Config
+      class StaticResponse < Middleware
+
+        insert_text <<~SNIPPET
+          static_response \\
+            code: ${1|200,404,500|},
+            headers: [${2|%w[content-type text/plain],%w[cache-control max-age=60]|}],
+            body: ${3|"OK", "Not Found"|}
+        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,81 @@
+---
+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.
+
+Modifiers can be appended after a pipe | to transform the substituted value.
+
+## Modifiers
+
+After a placeholder name, add |<modifier>:<arg> (or for replace, |replace:<from>,<to>). Available modifiers:
+
+`strip_prefix:<text>` If the substituted value starts with <text>, remove that prefix.
+
+`strip_suffix:<text>` If the substituted value ends with <text>, remove that suffix.
+
+`replace:<from>,<to>` Replace all occurrences of <from> in the substituted value with <to>.
+
+Modifiers are applied in the order they appear. You can chain multiple modifiers by repeating the |<modifier>:<arg> syntax (e.g. `{path|strip_prefix:/rails|replace:old,new}`).
+
+### 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,13 @@
+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,41 @@
+---
+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
+
+fiber_scheduler true
+
+auth_basic realm: "Restricted Area", credentials_file: "./credentials.txt"
+
+auto_reload_config! # Auto-reload the server configuration each time it changes.
+
+location "/app*" do
+  rate_limit requests: 3, seconds: 5
+  rackup_file "config.ru"
+end
+
+location "/inline*" 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,46 @@
+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!
+          return if @auto_reloading
+
+          src = caller.find { |l| !(l =~ %r{lib/itsi/server/config}) }.split(":").first
+
+          location.instance_eval do
+            return if @auto_reloading
+
+            if @included
+              @included.each do |file|
+                next if "#{file}" == src
+
+                if ENV["BUNDLE_BIN_PATH"]
+                  watch "#{file}", [%w[bundle exec itsi restart]]
+                else
+                  watch "#{file}", [%w[itsi restart]]
+                end
+              end
+            end
+            @auto_reloading = true
+
+            if ENV["BUNDLE_BIN_PATH"]
+              watch src, [%w[bundle exec itsi restart]]
+            else
+              watch src, [%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