docs: add docs for boundary rules engine (#21471)

Closes: https://github.com/coder/boundary/issues/146 - added docs for rules engine - move all boundary-related docs under new `boundary` directory
2026-09-24 15:04:27 +08:00 · 2026-01-09 15:04:51 -05:00
parent a09d85cc26
commit 1bfd776cb4
7 changed files with 112 additions and 7 deletions
@@ -0,0 +1,98 @@
+# Rules Engine Documentation
+
+## Overview
+
+The `rulesengine` package provides a flexible rule-based filtering system for HTTP/HTTPS requests. Rules use a simple key-value syntax with support for wildcards and multiple values.
+
+### Basic Syntax
+
+Rules follow the format: `key=value [key=value ...]` with three supported keys:
+
+- **`method`**: HTTP method(s) - Any HTTP method (e.g., `GET`, `POST`, `PUT`, `DELETE`), `*` (all methods), or comma-separated list
+- **`domain`**: Domain/hostname pattern - `github.com`, `*.example.com`, `*` (all domains)
+- **`path`**: URL path pattern - `/api/users`, `/api/*/users`, `*` (all paths), or comma-separated list
+
+**Key behavior**:
+
+- If a key is omitted, it matches all values
+- Multiple key-value pairs in one rule are separated by whitespace
+- Multiple rules in the allowlist are OR'd together (OR logic)
+- Default deny: if no rule matches, the request is denied
+
+**Examples**:
+
+```yaml
+allowlist:
+  - domain=github.com                                  # All methods, all paths for github.com
+  - method=GET,POST domain=api.example.com             # GET/POST to api.example.com
+  - domain=api.example.com path=/users,/posts          # Multiple paths
+  - method=GET domain=github.com path=/api/*           # All three keys
+```
+
+---
+
+## Wildcard Symbol for Domains
+
+The `*` wildcard matches domain labels (parts separated by dots).
+
+| Pattern        | Matches                                                          | Does NOT Match                                                           |
+|----------------|------------------------------------------------------------------|--------------------------------------------------------------------------|
+| `*`            | All domains                                                      | -                                                                        |
+| `github.com`   | `github.com`, `api.github.com`, `v1.api.github.com` (subdomains) | `github.io` (diff domain)                                                |
+| `*.github.com` | `api.github.com`, `v1.api.github.com` (1+ subdomain levels)      | `github.com` (base domain)                                               |
+| `api.*.com`    | `api.github.com`, `api.google.com`                               | `api.v1.github.com` (`*` in the middle matches exactly one domain label) |
+| `*.*.com`      | `api.example.com`, `api.v1.github.com`                           | -                                                                        |
+| `api.*`        | ❌ **ERROR** - Cannot end with `*`                                | -                                                                        |
+
+**Important**:
+
+- Patterns without `*` at the start automatically match subdomains
+- `*.example.com` matches one or more subdomain levels
+- Domain patterns **cannot end with asterisk**
+
+---
+
+## Wildcard Symbol for Paths
+
+The `*` wildcard matches path segments (parts separated by slashes).
+
+| Pattern        | Matches                                                    | Does NOT Match                          |
+|----------------|------------------------------------------------------------|-----------------------------------------|
+| `*`            | All paths                                                  | -                                       |
+| `/api/users`   | `/api/users`                                               | `/api/users/123` (subpaths don't match) |
+| `/api/*`       | `/api/users`, `/api/posts`                                 | `/api`                                  |
+| `/api/*/users` | `/api/v1/users`, `/api/v2/users`                           | `/api/users`, `/api/v1/v2/users`        |
+| `/*/users`     | `/api/users`, `/v1/users`                                  | `/api/v1/users`                         |
+| `/api/v1/*`    | `/api/v1/users`, `/api/v1/users/123/details` (1+ segments) | `/api/v1`                               |
+
+**Important**:
+
+- `*` matches **exactly one segment** (except at the end)
+- `*` at the **end** matches **one or more segments** (special behavior)
+- `*` must match an entire segment (cannot be part of a segment like `/api/user*`)
+
+---
+
+## Special Meaning of Wildcard at Beginning and End
+
+| Position   | Domain              | Path                  |
+|------------|---------------------|-----------------------|
+| Beginning  | 1+ subdomain levels | Exactly 1 segment     |
+| Middle     | Exactly 1 label     | Exactly 1 segment     |
+| End        | ❌ Not allowed       | 1+ segments (special) |
+| Standalone | All domains         | All paths             |
+
+---
+
+## Multipath
+
+Specify multiple paths in a single rule by separating them with commas:
+
+```yaml
+allowlist:
+  - domain=api.example.com path=/users,/posts,/comments
+  - domain=api.example.com path=/api,/api/*
+```
+
+`NOTE`: The pattern `/api/*` does not include the base path `/api`.
+To match both, use `path=/api,/api/*`.