itsi-server 0.1.1 → 0.2.2

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

@@ -0,0 +1,50 @@
+module Itsi
+  class Server
+    module CidrToRegex
+      require 'ipaddr'
+
+      def range_to_regex(range)
+        # Convert an IP range to regex by component
+        start_ip, end_ip = range.begin, range.end
+
+        start_parts = start_ip.to_s.split('.').map(&:to_i)
+        end_parts   = end_ip.to_s.split('.').map(&:to_i)
+
+        build_regex_from_parts(start_parts, end_parts)
+      end
+
+      def part_to_range_regex(start_val, end_val)
+        return start_val.to_s if start_val == end_val
+
+        ranges = []
+        (start_val..end_val).each do |val|
+          ranges << val.to_s
+        end
+
+        # Group similar patterns for compact regex
+        ranges.map! { |v| Regexp.escape(v) }
+        "(#{ranges.join('|')})"
+      end
+
+      def build_regex_from_parts(start_parts, end_parts)
+        # Build regex for each octet
+        parts = []
+        (0..3).each do |i|
+          if start_parts[i] == end_parts[i]
+            parts << Regexp.escape(start_parts[i].to_s)
+          else
+            parts << part_to_range_regex(start_parts[i], end_parts[i])
+          end
+        end
+
+        /^#{parts.join('\.')}$/
+      end
+
+      def cidr_to_regex(cidr)
+        ip_range = IPAddr.new(cidr).to_range
+        range_to_regex(ip_range)
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+---
+title: Compression
+url: /middleware/compression
+---
+
+The compression middleware allows you to configure compression settings for your application.
+You can enable several different compression algorithms, and choose to selectively apply these based on the request path, content type, mime-type, and size. You can also choose whether or not to compress streams, and adjust the compression level.
+
+
+## Top level compression
+```ruby {filename=Itsi.rb}
+  compress \
+    min_size: 1024 # 1KiB,
+    algorithms: %w[zstd gzip deflate br],
+    compress_streams: true,
+    mime_types: %[all],
+    level: "fastest"
+```
+
+## Compression within a location block
+```ruby {filename=Itsi.rb}
+
+  location "/images" do
+    compress \
+      min_size: 1024 # 1KiB,
+      algorithms: %w[zstd gzip deflate br],
+      mime_types: %[image],
+      level: "fastest"
+
+    static_assets: \
+      ...
+  end
+```
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `min_size` | The minimum size of the response body in bytes before compression is applied. Default is `1024` (1KiB). |
+| `algorithms` | An array of compression algorithms to use. Supports any combination  of `zstd`, `gzip`, `deflate`, `br`. |
+| `compress_streams` | Whether or not to compress streams. Default is `true`. |
+| `mime_types` | An array of mime-type groups/classes as string to compress. Default is `["all"]`.<br/>Available options are `all`, `text`, `image`, `audio`, `video`, `application`, `font`. <br/>You can also match arbitrary mime-types, by using an `other` object instead `{ "other" => "other/type" }` |
+| `level` | The compression level to use. Default is `fastest`. Can be any of `fastest`, `best`, `balanced` and  `precise` |
+
+<br/>
+
+# Pre-compressed `static_assets`
+Itsi also supports serving pre-compressed static assets directly from the file-system.
+This is configured inside the `static_assets` middleware.
+Go to the [static_assets](/middleware/static_assets.md) middleware for more information.

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

@@ -0,0 +1,37 @@
+module Itsi
+  class Server
+    module Config
+      class Compress < Middleware
+
+        insert_text <<~SNIPPET
+        compress \\
+          min_size: ${1|1024 * 1024|},
+          algorithms: ${2|%w[zstd gzip deflate br]|},
+          compress_streams: ${3|true,false|},
+          mime_types: ${4|%w[all],%w[image],%w[text image audio video font]|},
+          level: ${5|"fastest","precise","balanced","best"|}
+        SNIPPET
+
+        detail "Enable response compression"
+
+        OtherMimeType = TypedStruct.new do
+          {
+            other: Type(String)
+          }
+        end
+
+        schema do
+          {
+            min_size: (Range(0..1024 ** 4) & Required()).default(1024),
+            algorithms: (Array(Enum(%w[zstd gzip deflate br])).default(%w[zstd gzip deflate br])),
+            compress_streams: (Bool().default(true)),
+            mime_types: Array(Or(Enum(%w[text image application audio video font all]), Type(OtherMimeType))).default(%w[all]),
+            level: Enum(%w[fastest precise balanced best]).default("fastest")
+          }
+        end
+
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+---
+title: CORS
+url: /middleware/cors
+---
+
+The CORS middleware allows you to configure CORS settings for your application.
+You can enable CORS for specific origins, methods, headers, and credentials.
+
+
+## CORS configuration
+```ruby {filename=Itsi.rb}
+cors \
+  allow_origins: ["*"],
+  allow_methods: ["GET", "POST", "PUT", "DELETE"],
+  allow_headers: ["Content-Type", "Authorization"],
+  allow_credentials: true,
+  expose_headers: ["X-Total-Count"],
+  max_age: 3600
+```
+
+
+
+## CORS Applied to a sub-location
+```ruby {filename=Itsi.rb}
+location "/api" do
+  cors \
+    allow_origins: ["*"],
+    allow_methods: ["GET", "POST", "PUT", "DELETE"],
+    allow_headers: ["Content-Type", "Authorization"],
+    allow_credentials: true,
+    expose_headers: ["X-Total-Count"],
+    max_age: 3600
+end
+```
+
+## Configuration Options
+
+You can customize the CORS behavior using the following options:
+
+- **allow_origins**:
+  A list of allowed origins (e.g., `"*"` or specific domain names).
+  When credentials are allowed (see `allow_credentials`), the middleware echoes back the exact origin from the request.
+
+- **allow_methods**:
+  A list of allowed HTTP methods. Supported methods include:
+  - `GET`
+  - `POST`
+  - `PUT`
+  - `DELETE`
+  - `OPTIONS`
+  - `HEAD`
+  - `PATCH`
+  The internal implementation uses an enum (`HttpMethod`) with helper methods to match and convert these values.
+
+- **allow_headers**:
+  A list of headers that the client is allowed to include in its requests.
+
+- **allow_credentials**:
+  A boolean flag indicating whether credentials (like cookies or authorization headers) are allowed.
+
+- **expose_headers**:
+  A list of headers that browsers are allowed to access from the response.
+
+- **max_age**:
+  An optional field that sets the maximum time (in seconds) the result of a preflight request can be cached.
+
+## How It Works
+
+### Preflight Requests
+
+For HTTP OPTIONS requests (used to determine if the actual request is safe to send):
+#### 1.	Extraction of Request Headers
+The middleware extracts the following from the incoming request:
+*	`Origin`
+*	`Access-Control-Request-Method`
+*	`Access-Control-Request-Headers`
+
+#### 2.	Validation via preflight_headers
+These values are validated:
+*	The Origin must be provided and permitted according to allow_origins.
+*	The Access-Control-Request-Method must match one of the configured allow_methods.
+*	Any headers listed in Access-Control-Request-Headers must appear in the allow_headers configuration.
+
+#### 3.	Response Generation
+If the validation succeeds, the middleware constructs a set of CORS headers including:
+*	`Access-Control-Allow-Origin`
+*	`Access-Control-Allow-Methods`
+*	`Access-Control-Allow-Headers`
+*	`Access-Control-Allow-Credentials` (if enabled)
+*	`Access-Control-Max-Age` (if set)
+*	`Access-Control-Expose-Headers` (if configured)
+
+A response with status code 204 No Content is sent immediately, ending further processing.

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

@@ -0,0 +1,32 @@
+module Itsi
+  class Server
+    module Config
+      class Cors < Middleware
+
+        insert_text <<~SNIPPET
+        cors \\
+          allow_origins: ${1|["*"]|},
+          allow_methods: ${2|%w[GET POST PUT DELETE]|},
+          allow_headers: ${3|%w[Content-Type Authorization]|},
+          allow_credentials: ${4|true,false|},
+          expose_headers: ${5|[]|},
+          max_age: ${6|3600|}
+        SNIPPET
+
+        detail "Enables Cross-Origin Resource Sharing (CORS) for the server."
+
+        schema do
+          {
+            allow_origins: Array(Type(String)).default(["*"]),
+            allow_methods: Array(Type(String)).default(["GET", "POST", "PUT", "DELETE"]),
+            allow_headers: Array(Type(String)).default(["Content-Type", "Authorization"]),
+            allow_credentials: Bool().default(false),
+            expose_headers: Array(Type(String)).default([]),
+            max_age: Type(Integer).default(3600)
+          }
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+---
+title: Content Security Policy
+url: /middleware/csp
+---
+
+The `csp` middleware sets a [Content-Security-Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) header on outgoing responses and optionally collects violation reports from clients.
+
+### Options
+
+| Key                 | Type        | Default         | Description |
+|----------------------|-------------|------------------|-------------|
+| `policy`      | `CspConfig` | `nil`            | Optional policy components for `default-src`, `script-src`, etc. |
+| `reporting_enabled` | `Bool`      | `false`          | Enable collection of CSP violation reports |
+| `report_file`       | `PathBuf`   | `nil`            | Where to persist reports if reporting is enabled |
+| `report_endpoint`   | `String`    | `"/csp-report"`  | Endpoint to receive reports from the browser |
+| `flush_interval`    | `Integer`   | `10`             | How frequently (in seconds) to flush pending reports to file |
+
+### Example
+
+```ruby
+csp \
+  policy: {
+    default_src: ["'self'"],
+    script_src: ["'self'", "cdn.example.com"],
+    style_src: ["'self'"],
+    report_uri: ["/csp-report"]
+  },
+  reporting_enabled: true,
+  report_endpoint: "/csp-report",
+  report_file: "csp_reports.json",
+  flush_interval: 5
+```
+
+### Reporting
+Configure `reporting_enabled`, `report_endpoint`, `report_file` and `flush_interval` to have Itsi perform CSP violation report collection.
+
+If reporting is enabled, the middleware will collect violation reports from clients and persist them to the specified file at the given interval. (Make sure that `report_endpoint` and `report_uri` inside `policy_input` are correctly matched.)

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

@@ -0,0 +1,44 @@
+module Itsi
+  class Server
+    module Config
+      class Csp < Middleware
+        insert_text <<~SNIPPET
+          csp \\
+            policy: {
+              default_src: ${1:["'self'"]},
+              script_src: ${2:["'self'", "cdn.example.com"]},
+              style_src: ${3:["'self'"]},
+              report_uri: ${4:["/csp-report"]}
+            },
+            reporting_enabled: ${5|true,false|},
+            report_file: "${6:csp_reports.json}",
+            report_endpoint: "${7:/csp-report}",
+            flush_interval: ${8:5.0}
+        SNIPPET
+
+        detail "Adds Content-Security-Policy headers and collects violation reports."
+
+        CspPolicy = TypedStruct.new do
+          {
+            default_src: Array(Type(String)).default([]),
+            script_src: Array(Type(String)).default([]),
+            style_src: Array(Type(String)).default([]),
+            report_uri: Array(Type(String)).default([])
+          }
+        end
+
+        schema do
+          {
+            policy: (Type(CspPolicy) & Required()).default({default_src: [], script_src: [], style_src: [], report_uri: []}),
+            reporting_enabled: Bool().default(false),
+            report_file: Type(String),
+            report_endpoint: Type(String).default("/csp-report"),
+            flush_interval: Type(Float).default(5.0)
+          }
+        end
+
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+---
+title: Deny List
+url: /middleware/deny_list
+next: endpoint/
+---
+The **deny_list** middleware restricts access to only those clients whose IP address matches one a set of approved patterns. All other requests receive a configurable forbidden response.
+
+## Configuration
+
+```ruby {filename=Itsi.rb}
+deny_list \
+  denied_patterns: [
+    /192\.168\.0\.\d+/,     # block all 192.168.0.x
+    /203\.0\.113\.(10|11)/, # block .10 and .11
+    "10.0.0.0/24"           # block all IPs in the 10.0.0.x range
+  ],
+  error_response: { code: 403,
+                    plaintext: { inline: "Access denied" },
+                    default: "plaintext" }
+```
+
+*	`denied_patterns` (required):
+An array of Ruby‑style regexp strings. Each incoming client IP (from req.addr) is tested against this set; if any match, the request is blocked.
+*	`error_response` (optional):
+A built‑in or custom error response (default is forbidden / HTTP 403).
+
+
+## Trusted Proxies
+
+By default, a deny-list 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}
+deny_list \
+  denied_patterns: ["10.0.0.0/8", /198\.51\.100\.\d+/],
+  trusted_proxies: {
+    "192.168.1.1" => { header: { name: "X-Forwarded-For" } }
+  },
+  error_response: { code: 403, plaintext: { inline: "Access denied" } }
+```

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

@@ -0,0 +1,42 @@
+module Itsi
+  class Server
+    module Config
+
+      require_relative "cidr_to_regex"
+      require_relative "token_source"
+
+      include CidrToRegex
+
+      class DenyList < Middleware
+        insert_text <<~SNIPPET
+        deny_list \\
+          denied_patterns: [${1|"127.0.0.1","127.*", /127\.0\.*/|}],
+          error_response: ${2|"forbidden",{ code: 403\\, plaintext: { inline: "Access denied" } }|}
+        SNIPPET
+
+        detail "Block any clients whose IP matches one of the given regex patterns."
+
+        schema do
+          {
+            denied_patterns: Array(Type(String)) & Required(),
+            error_response: Type(ErrorResponseDef).default("forbidden"),
+            trusted_proxies: (Hash(Type(String), Type(TokenSource)) & Required()).default({})
+          }
+        end
+
+        def initialize(location, params={})
+          params[:denied_patterns] = Array(params[:denied_patterns]).map do |pattern|
+            if pattern.is_a?(Regexp)
+              pattern.source
+            elsif pattern =~ /\A\d{1,3}(?:\.\d{1,3}){3}\/\d{1,2}\z/
+              cidr_to_regex(pattern).source
+            else
+              pattern
+            end
+          end
+          super
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/middleware/endpoint/_index.md

@@ -0,0 +1,159 @@
+---
+title: Endpoint
+url: /middleware/endpoint
+prev: deny_list/
+next: controller/
+---
+
+The **endpoint** middleware allows you to define an ultra light-weight, inline, Ruby endpoint.
+
+> If you're after running a rack app using a fully-featured framework, e.g. a Ruby on Rails or Sinatra, take a look at the [Rackup File](/middleware/rackup_file) middleware instead.
+This feature can be useful for quickly prototyping, building small pieces of isolated functionality, or minimal endpoints where high throughput is essential.
+
+`endpoint` has several variants, that further restrict the endpoint to respond to specific HTTP methods:
+- [`get`](/middleware/get) for **GET** requests
+- [`post`](/middleware/post) for **POST** requests
+- [`put`](/middleware/put) for **PUT** requests
+- [`patch`](/middleware/patch) for **PATCH** requests
+- [`delete`](/middleware/delete) for **DELETE** requests
+
+### Functions
+Endpoints also support:
+* Request and response schema validation. See [Schema Validation](/middleware/endpoint/schemas)
+* Controllers. See [Controllers](/middleware/controller)
+
+## Usage
+Endpoints require an optional path (default "*") and a handler proc or function, which must accept a mandatory request object (See [Request](/middleware/http_request)) and an optional params object.
+
+
+```ruby {filename=Itsi.rb}
+# A routeless endpoint is the same as a 'catch-all' endpoint.
+# E.g. this:
+get do |req|
+end
+
+# Is equivalent to this:
+get "*" do |req|
+end
+```
+
+The request object itself holds a reference [`#response`](/middleware/http_response) object, which can be used to manage the response explicitly.
+
+### Request Life-cycle
+Unlike most Rack frameworks where the life-span of an HTTP request/response is tied to the controller action, in Itsi there is no such contract.
+You must explicitly close the response to complete it.
+This also allows you hold on to a connection *indefinitely* (or until top-level timeouts occur, e.g. [request_timeout](/options/request_timeout)), and makes it easy to manage several concurrent requests asynchronously (especially if combined with [fiber_scheduler](/options/fiber_scheduler)).
+
+There are several ways to write and close a response.
+
+**Simple Responses**
+* `request#respond`.
+```ruby
+get do |req|
+  req.respond "ok", 200, {} # All params are optional, and can also use named kwargs instead of positional args
+end
+```
+* respond + status aliases. E.g. `request#ok`, `request#created`, `request#not_found`
+```ruby
+get do |req|
+  req.ok "ok", {} # All params are optional, and can also use named kwargs instead of positional args
+end
+```
+
+**Low-level responses** (for low-level control over long-lived requests)
+* `response#respond`
+* `response#send_and_close`
+* `response#close`
+
+#### Simple Responses
+For most use-cases using simple responses is all you need.
+E.g.
+
+```ruby {filename=Itsi.rb}
+# Catch-all endpoint.
+endpoint "/example/*" do |request|
+  request.ok "Hello, World!"
+end
+```
+
+
+```ruby{filename=Itsi.rb}
+# Single body, status and headers
+
+# 200 assumed
+endpoint("/"){|req| req.respond "Just a body"  }
+
+# With status
+endpoint("/"){|req| req.respond "Body and status", 200  }
+
+# With status and headers
+endpoint("/"){|req| req.respond "Body and status", 200, {"Content-Type" => "text/plain"}  }
+
+# With kwargs
+endpoint("/"){|req| req.respond body: "Just a body"  }
+
+# With status
+endpoint("/"){|req| req.respond body: "Body and status", status: 200  }
+
+# With status and headers
+endpoint("/"){|req| req.respond body: "Body and status", status: 200, headers: {"Content-Type" => "text/plain"}  }
+
+# Response Formats
+# JSON
+endpoint("/"){|req| req.respond json: { "message": "With JSON Body" }  }
+
+# XML
+endpoint("/"){|req| req.respond xml: "<message>With XML Body</message>"}
+
+# HTML
+endpoint("/"){|req| req.respond html: "<html><body><h1>With HTML Body</h1></body></html>"}
+
+# Text
+endpoint("/"){|req| req.respond text: "With Text Body"}
+
+
+# Status helpers (All status codes supported)
+endpoint("/"){|req| req.ok "Ok"  }
+endpoint("/"){|req| req.not_found "Not Found"  }
+endpoint("/"){|req| req.created "Created"  }
+endpoint("/"){|req| req.accepted "Accepted"  }
+```
+
+For more advanced responses (e.g streaming responses), see documentation on [response](/middleware/response.rb)
+
+### Capturing URL parameters
+```ruby {filename=Itsi.rb}
+# Catch-all endpoint.
+location "/foo" do
+  endpoint "/users/:user_id" do |request|
+    if (user = User.find(request.query_params[:user_id]))
+      request.ok json: user.to_json
+    else
+      request.not_found "User not found!"
+    end
+  end
+
+  # Optionally restrict the character sets of capture groups using Regex
+  endpoint "/books/:book_id(\d+)" do |request|
+    request.ok "Got book #{request.query_params[:book_id]}"
+  end
+end
+```
+
+### Basic Request Body / Parameters
+
+If an endpoint accepts a second parameters argument, incoming request bodies will be parsed into a Ruby hash (including uploaded files as `File` objects and fed into the handler as the second parameter ).
+
+The following request formats will be automatically detected and deserialized:
+* **JSON** (`"Content-Type"` header is set to `"application/json"`)
+* **Form-encoded** (`"Content-Type"` header is set to `"application/x-www-form-urlencoded"`)
+* **Multipart** (`"Content-Type"` header is set to `"multipart/form-data"`)
+
+
+```ruby {filename=Itsi.rb}
+location "/echo" do
+  post "/body" do |request, params|
+    request.ok json: params.to_json
+  end
+end
+```