itsi-server 0.1.1 → 0.2.2

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

@@ -0,0 +1,61 @@
+module Itsi
+  class Server
+    module Config
+      class IntrusionProtection < Middleware
+
+        require_relative "rate_limit_store"
+        require_relative "token_source"
+
+        insert_text <<~SNIPPET
+        intrusion_protection \\
+          banned_url_patterns: ${1|KnownPaths.php_php|},
+          banned_header_patterns: { "User-Agent" => ${2|%w[sqlmap curl]|} },
+          banned_time_seconds: ${3|300,600|},
+          store_config: ${4|"in_memory",{redis:{connection_url:"redis://localhost:6379"}}|},
+          error_response: ${5|"forbidden",{ code:403\\, plaintext:{inline:"Access Denied"} }|}
+        SNIPPET
+
+
+        detail "Detects and automatically bans clients that attempt to access suspicious URLs"
+
+        schema do
+          {
+            banned_url_patterns: Array(Type(String)).default([]),
+            banned_header_patterns: Hash(Type(String), Array(Type(String))).default({}),
+            banned_time_seconds: Type(Float).default(300),
+            store_config: (Required() & Or(Enum(["in_memory"]), Type(RateLimitStore))).default("in_memory"),
+            error_response: Type(ErrorResponseDef).default("forbidden"),
+            combine: Bool().default(true),
+            trusted_proxies: (Hash(Type(String), Type(TokenSource)) & Required()).default({})
+          }
+        end
+
+        def build!
+          @params[:banned_url_patterns] = Array(@params[:banned_url_patterns]).flatten.map do |pattern|
+            if pattern.is_a?(Regexp)
+              pattern.source
+            else
+              "#{pattern}$"
+            end
+          end
+
+          @params[:banned_header_patterns].transform_values! do |patterns|
+            Array(patterns).flatten.map do |pattern|
+              if pattern.is_a?(Regexp)
+                pattern.source
+              else
+                pattern
+              end
+            end
+          end
+
+          if location.middleware[:intrusion_protection]
+            location.middleware[:intrusion_protection] = Array(location.middleware[:intrusion_protection]) + [@params]
+          else
+            location.middleware[:intrusion_protection] = @params
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+---
+title: Location
+url: /middleware/location
+---
+
+The `location` block is the essential building block of Itsi-powered apps.
+It allows you to selectively apply middleware based on request structure.
+This is similar to a `location` block in NGINX, but with added capabilities—most notably, support for nested location blocks.
+{{< callout type="warn" >}}
+Location blocks are matched in definition order, and only a single location block applies per request.
+This rule is applied recursively: the first top-level match is chosen, then the first matching child, and so on.
+{{</ callout >}}
+
+## Examples
+
+```ruby {filename="Itsi.rb"}
+# Wildcard routes: matches any path beginning with /admin/
+location "/admin/*" do
+  auth_basic ...
+end
+```
+
+```ruby {filename="Itsi.rb"}
+# Nested routes and named captures
+location "/organizations/:organisation_id" do
+  location "/users" do
+    location "/:user_id([0-9]+)" do
+      rate_limiter requests: 10, seconds: 5, ...
+      auth_jwt ...
+      ...
+    end
+  end
+
+  # Shared middleware for multiple exact sub-routes.
+  location "/settings", "/options" do
+    auth_basic ...
+  end
+end
+```
+
+```ruby {filename="Itsi.rb"}
+# Regex route: matches either 'users' or 'organizations'
+location /(?:users)|(?:organizations)/ do
+  intrusion_protection banned_url_patterns: [/wp-admin/]
+  ...
+end
+```
+```ruby {filename="Itsi.rb"}
+# Match on non-route options.
+# Redirect http requests to https requests
+location protocols: ["http"]
+  redirect type: :permanent, to: "https://{host}{path_and_query}"
+end
+```
+
+## Route Matches
+Routes have several options for matching:
+
+{{% details title="Exact Match (e.g. `\"/api/users\"`)" closed="true" %}}
+Matches the complete request path exactly. No prefix matching is performed.
+{{% /details %}}
+
+
+{{% details title="Wildcard Match (e.g. `\"/api/users/*\"`)" closed="true" %}}
+Fuzzily matches any path that with support for wild-card dynamic segments.
+{{% /details %}}
+
+{{% details title="Named Captures (e.g. `\"/api/users/:id\"`)" closed="true" %}}
+Similar to Wildcard match, but captures dynamic segments by name, using `:name` syntax. Matches are delimited by `/`, and captured values are accessible in logs and handlers.
+
+You can restrict captures to specific character sets, using embedded regular expressions:
+
+```ruby
+# Matches numeric user IDs
+location "/users/:id([0-9]+)" do
+  ...
+end
+```
+{{% /details %}}
+{{% details title="Regex Match (e.g. `/api\/(users|organizations)/`)" closed="true" %}}
+Full regular expression support for matching complex or variable patterns.
+{{% /details %}}
+
+{{% details title="Nested Matches" closed="true" %}}
+Nested blocks allow deeper route matching. Matching proceeds recursively:
+a top-level match is found first, followed by the first matching child block, and so on.
+{{% /details %}}
+
+
+## Options
+Location blocks match can also match on several other request attributes:
+* `methods`: An array of HTTP methods to match on. E.g. `%w[GET POST PUT DELETE]`
+* `protocols`: An array of protocols to match on. %w[http https]
+* `hosts`: An array of hosts to match on. E.g. `%w[example.com www.example.com]`
+* `ports`: An array of ports to match on. E.g. `%w[80 443]`
+* `extensions`: An array of file extensions to match on. E.g. `%w[html css js]`
+* `content_types`: An array of content types to match on. E.g. `%w[text/html application/json]`
+* `accepts`: An array of accept headers to match on. E.g. `%w[text/html application/json]`
+
+Pass these to the location block using keyword arguments, e.g.
+
+```ruby
+# Redirect all http JSON requests to use https exclusively.
+location protocols: ["http"], content_types: ["application/json"]
+  redirect type: :permanent, to: "https://{host}{path_and_query}"
+end
+```

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

@@ -0,0 +1,99 @@
+module Itsi
+  class Server
+    module Config
+      class Location < Middleware
+
+        insert_text <<~SNIPPET
+        location "${1:/}" do
+          $2
+        end
+        SNIPPET
+
+        detail "Group middleware by route and/or route options"
+
+        schema do
+          {
+            routes: Array(Or(Type(String), Type(Regexp))),
+            methods: Array(Type(String)),
+            protocols: Array(Type(String)),
+            schemes: Array(Type(String)),
+            hosts: Array(Type(String)),
+            ports: Array(Type(String)),
+            extensions: Array(Type(String)),
+            content_types: Array(Type(String)),
+            accepts: Array(Type(String)),
+            block: Type(Proc)
+          }
+        end
+
+        attr_accessor :location, :routes, :block, :protocols, :hosts, :ports,
+          :extensions, :content_types, :accepts, :block
+
+        def initialize(location,
+          *routes,
+          methods: [],
+          protocols: [],
+          schemes: [],
+          hosts: [],
+          ports: [],
+          extensions: [],
+          content_types: [],
+          accepts: [],
+          &block
+        )
+
+          @location = location
+          params = self.schema.new({
+            routes: routes,
+            methods: methods,
+            protocols: protocols,
+            schemes: schemes,
+            hosts: hosts,
+            ports: ports,
+            extensions: extensions,
+            content_types: content_types,
+            accepts: accepts,
+            block: block
+          }).to_h
+          @routes = params[:routes].empty? ? ["*"] : params[:routes]
+          @methods = params[:methods]
+          @protocols = params[:protocols] | params[:schemes]
+          @hosts = params[:hosts]
+          @ports = params[:ports]
+          @extensions = params[:extensions]
+          @content_types = params[:content_types]
+          @accepts = params[:accepts]
+          @block = block
+        end
+
+        def http_methods
+          @methods
+        end
+
+        def build!
+          build_child = lambda {
+            location.children << DSL.new(
+              location,
+              routes: routes,
+              methods: Array(http_methods) | location.http_methods,
+              protocols: Array(protocols) | location.protocols,
+              hosts: Array(hosts) | location.hosts,
+              ports: Array(ports) | location.ports,
+              extensions: Array(extensions) | location.extensions,
+              content_types: Array(content_types) | location.content_types,
+              accepts: Array(accepts) | location.accepts,
+              controller: location.controller,
+              &block
+            )
+          }
+          if location.parent.nil?
+            location.options[:middleware_loaders] << build_child
+          else
+            build_child[]
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+---
+title: Request Logs
+url: /middleware/log_requests
+---
+
+The request logging middleware allows you to define customized log statements to occur before and/or after each request is processed.
+
+You can provide a log level and format string to be written before and after each request.
+
+
+```ruby {filename=Itsi.rb}
+log_requests \
+  before: {
+    level: "INFO",
+    format: "[{request_id}] {method} {path_and_query} - {addr} "
+  },
+  after: {
+    level: "INFO",
+    format: "[{request_id}] └─ {status} in {response_time}"
+  }
+```
+
+
+The log statement can populated with several different placeholders.
+Available values are:
+
+### `before` Format String
+* `request_id` -  (A short, unique hexadecimal request identifier)
+* `request_id_full` - (A full 128-bit unique request identifier)
+* `method` - The HTTP method
+* `path` - The HTTP Path
+* `addr` - The client's IP address
+* `host` - The request host
+* `path_and_query` - The path and query combined
+* `query` - The request query string
+* `port` - The bound port
+* `start_time` - The request start time
+* `<Header-Name>`: Any existing request header. For example `{Accept}` or `{Cookie}` will be replaced with its current value.
+
+
+### `after` Format String
+* `request_id` - (A short, unique hexadecimal request identifier)
+* `request_id_full` - (A full 128-bit unique request identifier)
+* `status` - The HTTP status code
+* `addr` - The client's IP address
+* `response_time` - The response time in milliseconds
+* `<Header-Name>`: Any existing response header. For example `{Content-Type}` or `{Set-Cookie}` will be replaced with its current value.
+
+
+### Path Attributes
+In addition to this, any capture groups referenced by container location blocks
+are also made available, to be interpolated into the log statement. E.g.:
+
+```ruby {filename=Itsi.rb}
+
+location "/users/:user_id" do # 1. If we capture user_id here.
+
+  log_requests before: {
+    level: "INFO",
+    format: "[{request_id}] User: {user_id}" # 2. Then we can log the user_id here.
+  }
+
+end
+
+```

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

@@ -0,0 +1,31 @@
+module Itsi
+  class Server
+    module Config
+      class LogRequests < Middleware
+
+        insert_text <<~SNIPPET
+        log_requests \\
+          before: { level: ${1|"INFO","WARN","ERROR","DEBUG"|} format: ${2|"[{request_id}] {method} {path_and_query} - {addr} "|} },
+          after: { level: ${3|"INFO","WARN","ERROR","DEBUG"|}, format: ${4|"[{request_id}] └─ {status} in {response_time}"|} }
+        SNIPPET
+
+        detail "Enable logging before or after requests"
+
+        LogRequestConfig = TypedStruct.new do
+          {
+            level: (Required() & Enum(%w[INFO WARN ERROR DEBUG])).default("INFO"),
+            format: Type(String)
+          }
+        end
+
+        schema do
+          {
+            before: Type(LogRequestConfig),
+            after: Type(LogRequestConfig)
+          }
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+---
+title: Max Body
+url: /options/max_body
+---
+
+Limits the maximum request body size in bytes. This helps prevent excessively large payloads, which can cause resource exhaustion or denial-of-service issues.
+
+### Default
+
+```ruby {filename=Itsi.rb}
+max_body 10 * 1024 ** 2  # 10 MiB
+```
+
+### Example
+
+```ruby {filename=Itsi.rb}
+max_body 5 * 1024 ** 2  # 5 MiB
+```

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

@@ -0,0 +1,21 @@
+module Itsi
+  class Server
+    module Config
+      class MaxBody < Middleware
+
+        insert_text <<~SNIPPET
+        max_body limit_bytes: ${1: 10 * 1024 ** 2} # Maximum body size in bytes
+        SNIPPET
+
+        detail "Limit request body size."
+
+        schema do
+          {
+            limit_bytes: (Type(Integer) & Required()).default(10 * 1024 ** 2) # Default 10 MiB
+          }
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+---
+title: Reverse Proxy
+url: /middleware/proxy
+---
+
+The Reverse Proxy middleware enables reverse proxying by forwarding incoming HTTP requests to one of several backend servers. It supports streaming requests and responses, uses a dynamic URL rewriting mechanism to compute the target URL, supports multiple backend selection strategies, and can override or add headers before forwarding requests.
+
+## Proxy Configuration
+
+```ruby
+proxy \
+  to: "http://backend.example.com/api{path}{query}", \
+  backends: ["127.0.0.1:3001", "127.0.0.1:3002"], \
+  backend_priority: "round_robin", \
+  headers: { "X-Forwarded-For" => { rewrite: "{addr}" } }, \
+  verify_ssl: false, \
+  timeout: 30, \
+  tls_sni: true, \
+  error_response: "bad_gateway"
+```
+## Options
+| **Option**            | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `to`              | The target URL. It supports dynamic URL rewriting using placeholders like `{path}` and `{query}`. If no backends are given, it will perform DNS resolution to determine the appropriate backend to route to. This parameter also determines the SNI hostname and Host header (unless overridden).                                                                                                                              |
+| `backends` (Optional) | An array of Socket addresses. E.g. `["127.0.0.1:3001", "127.0.0.1:3002"]`. If provided, all requests will be routed to one of these backends based on the selected `backend_priority` algorithm. **Note:** The proxy uses persistent connections, so repeated testing from the same client will typically be satisfied by the same backend.                                                           |
+| `backend_priority` (Optional) | The strategy for selecting a backend server. Options include `round_robin`, `ordered`, and `random`. Defaults to `round_robin`.                                                                                                                                                                                                                                                                                                                        |
+| `headers` (Optional)  | A hash of headers to be overridden or added before forwarding requests. To clear a header, set the value to `nil`.                                                                                                                                                                                                                                                                                                                                                 |
+| `verify_ssl` (Optional) | A boolean indicating whether to verify SSL certificates. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                                                                   |
+| `timeout` (Optional)   | The timeout in seconds for the proxy request. Failures to respond in time will result in a 504 timeout error. Defaults to `30` seconds.                                                                                                                                                                                                                                                                                                                         |
+| `tls_sni` (Optional)   | A boolean indicating whether to use TLS SNI. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `error_response` (Optional) | The error response to be returned when the proxy fails. Users can either use a built-in error response or provide a custom one. See [Error Responses](/middleware/error_response) for more details on how to structure this. Defaults to the built-in `502 Bad Gateway` response.                                                                                                                |
+
+## How It Works
+
+1. **URL Rewriting**
+   The `to` parameter is a dynamic template that applies the [String Rewrite](/middleware/string_rewrite) mechanism. For instance, placeholders such as `{path}` and `{query}` are replaced with parts from the incoming request.
+   *Example*:
+   - For a request to `/resource?id=5`, a template of
+     ```ruby
+     "http://backend.example.com/api{path}{query}"
+     ```
+     produces:
+     ```
+     http://backend.example.com/api/resource?id=5
+     ```
+
+2. **Backend Selection**
+   The `backends` array lists available backend server addresses (formatted as `"IP:port"`). The `backend_priority` setting controls how a backend is chosen:
+   - **round_robin**: Cycles sequentially through the list.
+   - **ordered**: Always selects the first backend.
+   - **random**: Chooses a backend at random.
+   Note - The proxy uses persistent connections, so repeated testing from the same client will typically be satisfied by the same backend.
+
+3. **Header Overrides**
+   The `headers` option lets you specify extra or overriding headers. Each header value may be a literal or a string rewrite. For example, overriding `"X-Forwarded-For"` to carry the client’s IP is done by:
+   ```ruby
+   { "X-Forwarded-For" => { rewrite: "{addr}" } }
+   ```
+
+4. **Request Forwarding and Error Handling**
+   Depending on whether the request method is idempotent, the middleware buffers the request body to allow retries, or streams it directly. If the target URL is invalid or a backend error occurs (e.g. timeout or connection error), a configurable error response is returned.
+  See [Error Responses](/middleware/error_response) for more details on how to customize errors.

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

@@ -0,0 +1,41 @@
+module Itsi
+  class Server
+    module Config
+      class Proxy < Middleware
+
+        insert_text <<~SNIPPET
+        proxy \\
+          to: "${1:http://backend.example.com/api{path}{query}}", \\
+          backends: [${2:"127.0.0.1:3001", "127.0.0.1:3002"}], \\
+          backend_priority: ${3|"round_robin","ordered","random"|}, \\
+          headers: { ${4| "X-Forwarded-For" => { rewrite: "{addr}" },|} }, \\
+          verify_ssl: ${5|true,false|}, \\
+          timeout: ${6|30,60|}, \\
+          tls_sni: ${7|true,false|}, \\
+          error_response: ${8|"bad_gateway", "service_unavailable", { code: 503\\, default_format: "html"\\, html: { inline: "<h1>Service Unavailable</h1>" } }|}
+        SNIPPET
+
+        detail "Forwards incoming requests to a backend server using dynamic URL rewriting. Supports various backend selection strategies and header overriding."
+
+        schema do
+          {
+            to: Type(String) & Required(),
+            backends: Array(Type(String)),
+            backend_priority: Enum(["round_robin", "ordered", "random"]).default("round_robin"),
+            headers: Hash(Type(String), Type(String)).default({}),
+            verify_ssl: Bool().default(true),
+            tls_sni: Bool().default(true),
+            timeout: Type(Integer).default(30),
+            error_response: Type(ErrorResponseDef).default("bad_gateway"),
+          }
+        end
+
+        def build!
+          require 'uri'
+          @params[:backends]||=  URI.extract(@params[:to]).map(&URI.method(:parse)).map{|u| "#{u.scheme}://#{u.host}:#{u.port}" }
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+---
+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
+```
+
+### 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,44 @@
+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),
+            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 = Itsi::Server::RackInterface.for(app)
+        end
+
+        def build!
+          app_args = {
+            preloader: -> { @app},
+            sendfile: @params[:sendfile],
+            nonblocking: @params[:nonblocking],
+            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