@rip-lang/server 1.3.115 → 1.3.117

package/README.md

@@ -2,42 +2,116 @@
 
 # Rip Server - @rip-lang/server
 
-> **A full-stack web framework and production edge server — routing, middleware, multi-worker processes, hot reload, ACME auto-TLS, realtime WebSocket, observability, and mDNS — written entirely in Rip with zero dependencies**
+> **One runtime for your app and your edge — web framework, reverse proxy, TLS passthrough, and managed workers in a single zero-dependency Bun-native server**
 
-Rip Server is a unified web framework and application server. It provides
-Sinatra-style routing, built-in validators, file serving, and middleware
-composition for defining your API, plus multi-worker process management,
-rolling restarts, automatic TLS via Let's Encrypt, Bam-style realtime
-WebSocket support, runtime diagnostics, mDNS service discovery, and
-request load balancing for running it in production — all with zero external
-dependencies.
+Rip Server replaces the combination of a web framework (Express, Hono), a
+process manager (PM2), and a reverse proxy (Nginx, Caddy, Traefik) with one
+unified runtime. Define your API with Sinatra-style routes, serve it with
+managed multi-worker processes, proxy external services, and pass through raw
+TLS for things like the Incus Web UI — all from a single `rip server` command
+with zero external dependencies.
+
+Written entirely in Rip. Runs on Bun.
 
 ## Features
 
+### App Framework
+- **Sinatra-style routing** — `get`, `post`, `put`, `del` with path parameters and wildcards
+- **Request validation** — 40+ built-in validators via [`read()`](docs/READ_VALIDATORS.md) eliminate API boilerplate
+- **Middleware** — cors, sessions, compression, security headers, rate limiting, body limits
+- **File serving** — Auto-detected MIME types via `@send`, SPA fallback support
+- **Realtime WebSocket** — Pub/sub hub where your backend stays HTTP-only
+
+### Server Runtime
 - **Multi-worker architecture** — Automatic worker spawning based on CPU cores
 - **Hot module reloading** — Watches `*.rip` files by default, rolling restarts on change
-- **Rolling restarts** — Zero-downtime deployments
+- **Rolling restarts** — Zero-downtime deployments with per-app worker pools
 - **Automatic HTTPS** — Shipped `*.ripdev.io` wildcard cert, or auto-TLS via Let's Encrypt ACME
-- **Realtime WebSocket** — Bam-style pub/sub hub where your backend stays HTTP-only
-- **Observability** — `/diagnostics` endpoint with request rates, latency percentiles, queue pressure
-- **Appliance-grade reliability** — Graceful shutdown, restart resilience, forced-exit safety net
+- **Observability** — `/diagnostics` with request rates, latency percentiles, queue pressure
 - **mDNS discovery** — `.local` hostname advertisement
-- **Per-app worker pools** — Multi-app registry with host-to-app routing
-- **Request queue** — Built-in request buffering and load balancing
-- **Built-in dashboard** — Server status UI at `rip.local`
-- **Unified package** — Web framework + production server in one
+
+### Edge Proxy
+- **HTTP/WS reverse proxy** — Route to external upstreams with health checks, circuit breakers, and retry
+- **Layer 4 TLS passthrough** — SNI-based raw TCP routing for services that keep their own TLS
+- **Unified port multiplexer** — Stream passthrough and normal HTTPS on the same `:443`
+- **Atomic config reload** — Staged activation with post-verify and automatic rollback
+- **Declarative routing** — Host/path/method matching with wildcard hosts and per-site overrides
+
+## What Can You Build?
+
+- **A single API or web app** — `rip server` with zero config, one command
+- **A multi-app platform** — Per-app worker pools, host routing, and rolling restarts via `config.rip`
+- **A reverse proxy** — Route traffic to external HTTP/WS upstreams with health checks
+- **A TLS passthrough edge** — Expose services like the Incus Web UI without terminating their TLS
+- **A full edge runtime** — Replace Nginx, Caddy, or Traefik for single-host deployments via `Edgefile.rip`
 
 | Directory | Role |
 |-----------|------|
 | `api.rip` | Core framework: routing, validation, `read()`, `session`, `@send` |
 | `middleware.rip` | Built-in middleware: cors, logger, sessions, compression, security, serve |
 | `server.rip` | Edge orchestrator: CLI, workers, load balancing, TLS, mDNS |
-| `edge/` | Request path: forwarding, scheduling, metrics, registry, helpers, TLS, realtime |
+| `edge/` | Request path and edge runtime: config, forwarding, metrics, registry, router, runtime, TLS, upstreams, verification |
 | `control/` | Management: CLI, lifecycle, workers, watchers, mDNS, events |
+| `streams/` | Layer 4 stream routing: ClientHello parsing, SNI routing, stream runtimes, raw TCP upstreams |
 | `acme/` | Auto-TLS: ACME client, crypto, cert store, challenge handler |
 
 > **See Also**: For the DuckDB server, see [@rip-lang/db](../db/README.md).
 
+## Runtime Tiers
+
+`rip server` is a graduated runtime. Start simple and add capabilities as you need them:
+
+1. **Single-app mode** — one app, zero config, one command
+2. **Managed multi-app mode** — many Rip apps with per-app worker pools via `config.rip`
+3. **Edge mode** — upstream proxying, host/path routing, TLS passthrough, staged reload, verification, and rollback via `Edgefile.rip`
+
+```mermaid
+flowchart TD
+  SingleApp["rip server"] --> ManagedApps["config.rip"]
+  ManagedApps --> EdgeMode["Edgefile.rip"]
+  EdgeMode --> Upstreams["HTTP and WS upstream routes"]
+  EdgeMode --> Streams["Layer 4 TLS passthrough"]
+  EdgeMode --> ManagedRoutes["Managed app routes"]
+```
+
+## Architecture
+
+```mermaid
+flowchart LR
+  Client[Client] --> Port[":443"]
+  Port -->|"HTTP/WS"| TLS["TLS termination"]
+  TLS --> Router["Route matching"]
+  Router -->|upstream| Proxy["Reverse proxy"]
+  Router -->|app| Workers["Worker pool"]
+  Port -->|"TLS passthrough"| SNI["SNI routing"]
+  SNI --> Upstream["Raw TCP upstream"]
+```
+
+When a stream route shares the HTTPS port, Rip uses a multiplexer: matching SNI
+traffic passes through at Layer 4, and everything else falls through to the
+normal HTTP/WebSocket edge runtime. When no stream routes share the HTTPS port,
+there is no multiplexer and no extra hop.
+
+## How Does Rip Server Compare?
+
+| Capability | Rip Server | Caddy | Nginx | Traefik |
+|---|---|---|---|---|
+| HTTP reverse proxy | Yes | Yes | Yes | Yes |
+| WebSocket proxy | Yes | Yes | Yes | Yes |
+| Auto-TLS (ACME) | Yes | Yes | Plugin | Yes |
+| Layer 4 TLS passthrough | Yes | Yes | Stream module | Yes |
+| Managed app workers | Yes | No | No | No |
+| Built-in app framework | Yes | No | No | No |
+| Hot reload | Yes | Yes | Reload | Yes |
+| Atomic rollback | Yes | No | No | No |
+| Per-SNI multi-cert TLS | Yes | Yes | Yes | Yes |
+| Config validation with hints | Yes | Partial | No | Partial |
+| Zero dependencies | Yes | Go binary | C binary | Go binary |
+
+Use Rip Server when you want one Bun-native runtime for both the app and the
+edge. Use Caddy, Nginx, or Traefik when you specifically need mature HTTP
+caching, multi-node service discovery, or their broader ecosystem integrations.
+
 ## Quick Start
 
 ### Installation
@@ -73,13 +147,13 @@ Create `index.rip`:
 ```coffee
 import { get, read, start } from '@rip-lang/server'
 
-get '/', ->
+get '/' ->
   'Hello from Rip Server!'
 
-get '/json', ->
+get '/json' ->
   { message: 'It works!', timestamp: Date.now() }
 
-get '/users/:id', ->
+get '/users/:id' ->
   id = read 'id', 'id!'
   { user: { id, name: "User #{id}" } }
 
@@ -108,660 +182,371 @@ curl http://localhost/status
 # {"status":"healthy","app":"myapp","workers":5,"ports":{"https":443}}
 ```
 
-## The `read()` Function
-
-A validation and parsing powerhouse that eliminates 90% of API boilerplate.
-
-### Basic Patterns
-
-```coffee
-# Required field (throws if missing)
-email = read 'email', 'email!'
-
-# Optional field (returns null if missing)
-phone = read 'phone', 'phone'
-
-# With default value
-role = read 'role', ['admin', 'user'], 'user'
-
-# Get entire payload
-data = read()
-```
-
-### Range Validation
-
-The `[min, max]` syntax works for both numbers and string lengths:
-
-```coffee
-# Numbers: value range
-age = read 'age', 'int', [18, 120]        # Between 18 and 120
-priority = read 'priority', 'int', [1, 10]  # 1-10 range
-
-# Strings: length range
-username = read 'username', 'string', [3, 20]  # 3-20 characters
-bio = read 'bio', 'string', [0, 500]           # Up to 500 chars
-
-# Named parameters
-views = read 'views', 'int', min: 0             # Non-negative integer
-discount = read 'discount', 'float', max: 100   # Up to 100
-```
-
-### Enumeration Validation
-
-```coffee
-# Must be one of these values
-role = read 'role', ['admin', 'user', 'guest']
-status = read 'status', ['pending', 'active', 'closed']
-```
-
-### Regex Validation
-
-```coffee
-# Custom pattern matching
-code = read 'code', /^[A-Z]{3,6}$/
-```
-
-## Built-in Validators
-
-`@rip-lang/server` includes 37 validators for every common API need:
-
-### Numbers & Money
-```coffee
-id = read 'user_id', 'id!'       # Positive integer (1+)
-count = read 'count', 'whole'    # Non-negative integer (0+)
-price = read 'price', 'float'   # Decimal number
-cost = read 'cost', 'money'     # Banker's rounding to cents
-```
-
-### Text Processing
-```coffee
-title = read 'title', 'string'   # Collapses whitespace
-bio = read 'bio', 'text'         # Light cleanup
-name = read 'name', 'name'       # Trims and normalizes
-```
-
-### Contact Information
-```coffee
-email = read 'email', 'email'        # Valid email format
-phone = read 'phone', 'phone'        # US phone → (555) 123-4567
-address = read 'address', 'address'  # Trimmed address
-```
-
-### Geographic Data
-```coffee
-state = read 'state', 'state'      # Two-letter → uppercase
-zip = read 'zip', 'zip'            # 5-digit zip
-zipplus4 = read 'zip', 'zipplus4'  # 12345-6789 format
-```
-
-### Identity & Security
-```coffee
-ssn = read 'ssn', 'ssn'                # SSN → digits only
-sex = read 'gender', 'sex'             # m/f/o
-username = read 'username', 'username' # 3-20 chars, lowercase
-```
-
-### Web & Technical
-```coffee
-url = read 'website', 'url'      # Valid URL
-ip = read 'ip_address', 'ip'     # IPv4 address
-mac = read 'mac', 'mac'          # MAC address
-color = read 'color', 'color'    # Hex color → #abc123
-uuid = read 'user_id', 'uuid'    # UUID format
-semver = read 'version', 'semver' # Semantic version
-```
-
-### Time & Date
-```coffee
-date = read 'date', 'date'        # YYYY-MM-DD
-time = read 'time', 'time'        # HH:MM or HH:MM:SS (24-hour)
-time12 = read 'time', 'time12'    # 12-hour with am/pm
-```
-
-### Boolean & Collections
-```coffee
-active = read 'active', 'truthy'    # true/t/1/yes/y/on → true
-inactive = read 'off', 'falsy'      # false/f/0/no/n/off → true
-flag = read 'flag', 'bool'          # Either → boolean
-tags = read 'tags', 'array'         # Must be array
-config = read 'config', 'hash'      # Must be object
-settings = read 'data', 'json'      # Parse JSON string
-ids = read 'ids', 'ids'             # "1,2,3" → [1, 2, 3]
-slug = read 'slug', 'slug'          # URL-safe slug
-```
-
-### Custom Validators
-
-```coffee
-import { registerValidator, read } from '@rip-lang/server'
-
-registerValidator 'postalCode', (v) ->
-  if v =~ /^[A-Z]\d[A-Z] \d[A-Z]\d$/i
-    _[0].toUpperCase()
-  else
-    null
-
-# Now use it
-code = read 'postal', 'postalCode!'
-```
+## Edgefile Quick Start
 
-## Routing
+`Edgefile.rip` is the declarative edge config for the Bun-native edge runtime.
+It gives you:
 
-### HTTP Methods
+- **HTTP/WS reverse proxy** — route traffic to external upstreams with health checks, retries, and circuit breakers
+- **Layer 4 TLS passthrough** — route raw TLS connections by SNI to services that keep their own certificates and client-cert auth
+- **Shared-port multiplexer** — stream passthrough and normal HTTPS on the same `:443`, automatically
+- **Managed app routes** — host Rip apps with per-app worker pools alongside proxy routes
+- **Atomic reload** — staged activation with post-verify and automatic rollback via `SIGHUP` or control API
+- **Strict validation** — field-path errors and remediation hints, with `--check-config` for dry-run validation
+- **Diagnostics** — config metadata, counts, reload history, and route descriptions in `/diagnostics`
 
-```coffee
-import { get, post, put, patch, del, all } from '@rip-lang/server'
-
-get    '/users'     -> listUsers!
-post   '/users'     -> createUser!
-get    '/users/:id' -> getUser!
-put    '/users/:id' -> updateUser!
-patch  '/users/:id' -> patchUser!
-del    '/users/:id' -> deleteUser!
-all    '/health'    -> 'ok'  # All methods
-```
-
-### Path Parameters
+### Canonical Shape
 
 ```coffee
-# Basic parameters
-get '/users/:id' ->
-  id = read 'id', 'id!'
-  { id }
-
-# Multiple parameters
-get '/users/:userId/posts/:postId' ->
-  userId = read 'userId', 'id!'
-  postId = read 'postId', 'id!'
-  { userId, postId }
-
-# Custom patterns
-get '/files/:name{[a-z]+\\.txt}' ->
-  name = read 'name'
-  { file: name }
-
-# Wildcards
-get '/static/*', (env) ->
-  { path: env.req.path }
+export default
+  version: 1
+  edge:
+    hsts: true
+    timeouts:
+      connectMs: 2000
+      readMs: 30000
+  upstreams: {}
+  streamUpstreams: {}
+  apps: {}
+  routes: []
+  streams: []
+  sites: {}
 ```
 
-### Route Grouping
+### Edgefile Field Reference
 
-```coffee
-import { prefix } from '@rip-lang/server'
-
-prefix '/api/v1' ->
-  get '/users' -> listUsers!
-  get '/posts' -> listPosts!
+| Field | Purpose |
+|------|---------|
+| `version` | Schema version (optional, defaults to `1`). |
+| `edge` | Global edge settings: TLS, trusted proxies, timeouts, verification policy. |
+| `upstreams` | Named external HTTP services and their targets. |
+| `streamUpstreams` | Named raw TCP upstreams using `host:port` targets and optional `connectTimeoutMs`. |
+| `apps` | Managed Rip apps with entry paths, hosts, worker counts, and env. |
+| `routes` | Declarative route objects that choose exactly one action. |
+| `streams` | Layer 4 stream routes that match by listen port and SNI. |
+| `sites` | Per-host route groups and policy overrides. |
 
-prefix '/api/v2' ->
-  get '/users' -> listUsersV2!
-```
+### Route Shape
 
-## Middleware
+Common route fields:
 
-### Built-in Middleware
+- `host?: string` — exact host, wildcard host like `*.example.com`, or `*`
+- `path: string` — must start with `/`
+- `methods?: string[] | "*"`
+- `priority?: number`
+- `timeouts?: { connectMs, readMs }`
 
-Import from `@rip-lang/server/middleware`:
+Each route must define exactly one action:
 
-```coffee
-import { use } from '@rip-lang/server'
-import { cors, logger, compress, sessions, secureHeaders, timeout, bodyLimit } from '@rip-lang/server/middleware'
-
-# Logging
-use logger()
-use logger format: 'tiny'                # Minimal output
-use logger format: 'dev'                 # Colorized (default)
-use logger skip: (c) -> c.req.path is '/health'
-
-# CORS
-use cors()                               # Allow all origins
-use cors origin: 'https://myapp.com'     # Specific origin
-use cors origin: ['https://a.com', 'https://b.com']
-use cors credentials: true, maxAge: 86400
-
-# Compression (gzip/deflate)
-use compress()
-use compress threshold: 1024             # Min bytes to compress
-
-# Security headers
-use secureHeaders()
-use secureHeaders hsts: true, contentSecurityPolicy: "default-src 'self'"
-
-# Request limits
-use timeout ms: 30000                    # 30 second timeout
-use bodyLimit maxSize: 1024 * 1024       # 1MB max body
-```
+- `upstream: 'name'`
+- `app: 'name'`
+- `static: '/dir'`
+- `redirect: { to: '...', status: 301 }`
+- `headers: { set, remove }`
 
-### Middleware Options
+WebSocket proxy routes use:
 
-| Middleware | Options |
-|------------|---------|
-| `logger()` | `format`, `skip`, `stream` |
-| `cors()` | `origin`, `methods`, `headers`, `credentials`, `maxAge`, `exposeHeaders`, `preflight` |
-| `compress()` | `threshold`, `encodings` |
-| `sessions()` | `secret`, `name`, `maxAge`, `secure`, `httpOnly`, `sameSite` |
-| `secureHeaders()` | `hsts`, `hstsMaxAge`, `contentSecurityPolicy`, `frameOptions`, `referrerPolicy` |
-| `timeout()` | `ms`, `message`, `status` |
-| `bodyLimit()` | `maxSize`, `message` |
+- `websocket: true`
+- `upstream: 'name'`
 
-### Session Usage
+### Stream Shape
 
-```coffee
-import { get, use, before, session } from '@rip-lang/server'
-import { sessions } from '@rip-lang/server/middleware'
+Common stream fields:
 
-# Sessions parses cookies directly from request headers
-use sessions secret: process.env.SESSION_SECRET
+- `listen: number` — TCP port to bind
+- `sni: string[]` — exact or wildcard SNI patterns
+- `upstream: 'name'`
+- `timeouts?: { handshakeMs, idleMs, connectMs }`
 
-before ->
-  session.views ?= 0
-  session.views += 1
+When `listen` matches the active HTTPS port, Rip uses a shared-port
+multiplexer. Matching SNI traffic is passed through to the stream upstream, and
+everything else falls through to Rip's internal HTTPS server.
 
-get '/profile' ->
-  { userId: session.userId, views: session.views }
-
-get '/login' ->
-  session.userId = 123
-  { loggedIn: true }
-
-get '/logout' ->
-  delete session.userId
-  { loggedOut: true }
-```
-
-The `session` import works anywhere via AsyncLocalStorage — no `@` needed, works in helpers and nested callbacks.
-
-**Security note:** Without `secret`, sessions use plain base64 (dev only). With `secret`, sessions are HMAC-SHA256 signed (tamper-proof). Always set `secret` in production.
-
-### CORS with Preflight
+### Example: Pure Proxy Shape
 
 ```coffee
-import { use } from '@rip-lang/server'
-import { cors } from '@rip-lang/server/middleware'
-
-# Handle OPTIONS early (before routes are matched)
-use cors origin: 'https://myapp.com', preflight: true
-```
-
-### Custom Middleware
+export default
+  version: 1
+  edge:
+    hsts: true
+    trustedProxies: ['10.0.0.0/8']
+    verify:
+      requireHealthyUpstreams: true
+      requireReadyApps: true
+      includeUnroutedManagedApps: true
+      minHealthyTargetsPerUpstream: 1
+  upstreams:
+    app:
+      targets: ['http://app.incusbr0:3000']
+      healthCheck:
+        path: '/health'
+  routes: [
+    { path: '/ws', websocket: true, upstream: 'app' }
+    { path: '/*', upstream: 'app' }
+  ]
+```
+
+### Example: TLS Passthrough For Incus
 
 ```coffee
-# Authentication middleware
-use (c, next) ->
-  token = @req.header 'Authorization'
-  unless token
-    return @json { error: 'Unauthorized' }, 401
-  @user = validateToken!(token)
-  await next()
-
-# Timing middleware
-use (c, next) ->
-  start = Date.now()
-  await next()
-  @header 'X-Response-Time', "#{Date.now() - start}ms"
-```
+export default
+  version: 1
 
-### Request Lifecycle Filters
+  edge: {}
 
-Three filters run at different stages: `raw` → `before` → handler → `after`
+  streamUpstreams:
+    incus:
+      targets: ['127.0.0.1:8443']
 
-```coffee
-import { raw, before, after, get } from '@rip-lang/server'
-
-# Runs first — modify raw request before body parsing
-raw (req) ->
-  if req.headers.get('X-Raw-SQL') is 'true'
-    req.headers.set 'content-type', 'text/plain'
-
-skipPaths = ['/favicon.ico', '/ping', '/health']
-
-# Runs before handler (after body parsing)
-before ->
-  @start = Date.now()
-  @silent = @req.path in skipPaths
-  unless @req.header 'Authorization'
-    return @json { error: 'Unauthorized' }, 401
-
-# Runs after handler
-after ->
-  return if @silent
-  console.log "#{@req.method} #{@req.path} - #{Date.now() - @start}ms"
+  streams: [
+    { listen: 8443, sni: ['incus.example.com'], upstream: 'incus' }
+  ]
 ```
 
-**Note:** `raw` receives the native `Request` object (before parsing). `before` and `after` use `@` to access the context.
-
-**How `@` works:** Handlers are called with `this` bound to the context, so `@foo` is `this.foo`. This gives you Sinatra-like magic access to:
-- `@req` — Request object
-- `@json()`, `@text()`, `@html()`, `@redirect()`, `@send()` — Response helpers
-- `@header()` — Response header modifier
-- `@anything` — Custom per-request state
-
-**Imports that work anywhere** (via AsyncLocalStorage or Proxy):
-- `read` — Validated request parameters
-- `session` — Session data (if middleware enabled)
-- `env` — `process.env` shortcut (e.g., `env.DATABASE_URL`)
-
-## Context Object
-
-Use `@` to access the context directly — no parameter needed:
+### Example: Unified Port For Apps + Incus
 
-### Response Helpers
+If a stream route listens on the active HTTPS port, Rip automatically switches
+that port into multiplexer mode. Matching SNI traffic is passed through at
+Layer 4, and everything else falls through to Rip's internal HTTPS server.
 
 ```coffee
-get '/demo' ->
-  # JSON response
-  @json { data: 'value' }
-  @json { data: 'value' }, 201  # With status
-  @json { data: 'value' }, 200, { 'X-Custom': 'header' }
-
-  # Text response
-  @text 'Hello'
-  @text 'Created', 201
-
-  # HTML response
-  @html '<h1>Hello</h1>'
-
-  # Redirect
-  @redirect '/new-location'
-  @redirect '/new-location', 301  # Permanent
+export default
+  version: 1
+  edge: {}
 
-  # Raw body
-  @body data, 200, { 'Content-Type': 'application/octet-stream' }
+  streamUpstreams:
+    incus:
+      targets: ['127.0.0.1:8443']
 
-  # File serving (auto-detected MIME type via Bun.file)
-  @send 'public/style.css'                    # text/css
-  @send 'data/export.json', 'application/json' # explicit type
+  streams: [
+    { listen: 443, sni: ['incus.example.com'], upstream: 'incus' }
+  ]
 ```
 
-### Request Helpers
+This means:
 
-```coffee
-get '/info' ->
-  # Path and query parameters — use read() for validation!
-  id = read 'id', 'id!'
-  q  = read 'q'
-
-  # Headers
-  auth = @req.header 'Authorization'
-  allHeaders = @req.header()
-
-  # Body (async)
-  json = @req.json!
-  text = @req.text!
-  form = @req.formData!
-  parsed = @req.parseBody!
-
-  # Raw request
-  @req.raw     # Native Request object
-  @req.method  # 'GET', 'POST', etc.
-  @req.url     # Full URL
-  @req.path    # Path only
-```
+- `https://incus.example.com` keeps Incus's own TLS and client-certificate flow
+- every other HTTPS host on `:443` still terminates TLS in Rip and uses the
+  normal HTTP/WebSocket edge runtime
+- if no stream route shares the HTTPS port, Rip stays on the normal direct
+  `Bun.serve()` path with no extra hop
 
-### Request-Scoped State
+### Example: Mixed Apps + Upstreams
 
 ```coffee
-# Store data for later middleware/handlers
-use (c, next) ->
-  @user = { id: 1, name: 'Alice' }
-  @startTime = Date.now()
-  await next()
-
-get '/profile' ->
-  @json @user
+export default
+  version: 1
+  edge: {}
+  upstreams:
+    api:
+      targets: ['http://api.incusbr0:4000']
+  apps:
+    admin:
+      entry: './admin/index.rip'
+      hosts: ['admin.example.com']
+  routes: [
+    { path: '/api/*', upstream: 'api' }
+    { path: '/admin/*', app: 'admin' }
+  ]
+  sites:
+    'admin.example.com':
+      routes: [
+        { path: '/*', app: 'admin' }
+      ]
 ```
 
-## File Serving
-
-### `@send(path, type?)`
+### Example: Manual Wildcard TLS
 
-Serve a file with auto-detected MIME type. Uses `Bun.file()` internally for
-efficient streaming — the file is never buffered in memory.
+Use manual cert/key paths for wildcard TLS. ACME HTTP-01 cannot issue
+`*.domain` certificates.
 
 ```coffee
-# Auto-detected content type (30+ extensions supported)
-get '/css/*', -> @send "css/#{@req.path.slice(5)}"
-
-# Explicit content type
-get '/files/*', -> @send "uploads/#{@req.path.slice(7)}", 'application/octet-stream'
-
-# SPA fallback — serve index.html for all unmatched routes
-notFound -> @send 'index.html', 'text/html; charset=UTF-8'
+export default
+  version: 1
+  edge:
+    cert: './certs/wildcard.example.com.crt'
+    key: './certs/wildcard.example.com.key'
+    hsts: true
+  upstreams:
+    web:
+      targets: ['http://web.incusbr0:3000']
+  routes: [
+    { path: '/*', upstream: 'web', host: '*.example.com' }
+  ]
 ```
 
-### `mimeType(path)`
+## Host Blocks
 
-Exported utility that returns the MIME type for a file path:
+Use `hosts` to group TLS certificates, routes, and static file serving
+under each hostname. This is the cleanest way to configure multi-domain hosting.
 
-```coffee
-import { mimeType } from '@rip-lang/server'
-
-mimeType 'style.css'    # 'text/css; charset=UTF-8'
-mimeType 'app.js'       # 'application/javascript'
-mimeType 'photo.png'    # 'image/png'
-mimeType 'data.xyz'     # 'application/octet-stream'
-```
+`hosts` defines per-domain configuration. `version` and `edge` are optional --
+they default to `1` and `{}` respectively.
 
-## Error Handling
-
-### Custom Error Handler
+### Host Blocks Shape
 
 ```coffee
-import { onError } from '@rip-lang/server'
-
-onError (err, c) ->
-  console.error 'Error:', err
-  c.json { error: err.message }, err.status or 500
-```
-
-### Custom 404 Handler
+export default
+  hosts:
+    '*.trusthealth.com':
+      cert: '/ssl/trusthealth.com.crt'
+      key:  '/ssl/trusthealth.com.key'
+      root: '/mnt/trusthealth/website'
+      routes: [
+        { path: '/*', static: '.', spa: true }
+      ]
+
+    '*.zionlabshare.com':
+      cert: '/ssl/zionlabshare.com.crt'
+      key:  '/ssl/zionlabshare.com.key'
+      routes: [
+        { path: '/api/*', upstream: 'api' }
+        { path: '/*', static: '/mnt/zion/dist', spa: true }
+      ]
+
+  upstreams:
+    api: { targets: ['http://127.0.0.1:3807'] }
+
+  streamUpstreams:
+    incus: { targets: ['127.0.0.1:8443'] }
+
+  streams: [
+    { listen: 443, sni: ['incus.trusthealth.com'], upstream: 'incus' }
+  ]
+```
+
+### How Host Blocks Work
+
+- Each server block is keyed by hostname (exact or wildcard)
+- Per-server `cert`/`key` enable SNI-based certificate selection (multiple domains on one port)
+- `edge.cert` and `edge.key` are the optional fallback TLS identity
+- A server with just `root` and no `routes` serves static files automatically
+- A server with `passthrough` routes raw TLS to another address (no termination)
+- `streams`, `streamUpstreams`, `upstreams`, and `apps` stay top-level and are shared
+- Routes inside a server block inherit the server hostname automatically
+- Hosts not matching any server block or stream route fall through to the default app
+
+### Host Block Fields
+
+| Field | Purpose |
+|-------|---------|
+| `passthrough` | Raw TLS passthrough to `host:port` (no cert, no routes needed) |
+| `cert` | TLS certificate path for this hostname (must pair with `key`) |
+| `key` | TLS private key path for this hostname (must pair with `cert`) |
+| `root` | Default filesystem base; if present with no `routes`, serves static files |
+| `spa` | Server-level SPA fallback (boolean, used with `root`-only blocks) |
+| `routes` | Array of route objects (optional if `root` or `passthrough` is set) |
+| `timeouts` | Per-server timeout defaults |
+
+### Static Routes
+
+Static routes serve files from disk with auto-detected MIME types:
 
 ```coffee
-import { notFound } from '@rip-lang/server'
-
-notFound (c) ->
-  c.json { error: 'Not found', path: c.req.path }, 404
+{ path: '/*', static: '.', spa: true }
+{ path: '/assets/*', static: '/mnt/assets' }
 ```
 
-## Server Options
+- `static` is the directory to serve from (absolute path or relative to `root`)
+- `root` on a route overrides the server-level `root`
+- `spa: true` enables SPA fallback: when a file is not found and the request
+  accepts `text/html`, serves `index.html` instead
+- Directory requests serve `index.html` if present
+- Path traversal is rejected
 
-### Basic Server
+### Redirect Routes
 
 ```coffee
-import { start } from '@rip-lang/server'
-
-start port: 3000
-start port: 3000, host: '0.0.0.0'
+{ path: '/old/*', redirect: { to: 'https://new.example.com', status: 301 } }
 ```
 
-### Handler Only (for custom servers)
+## Operator Runbook
 
-```coffee
-import { startHandler } from '@rip-lang/server'
+### Start With An Explicit Edgefile
 
-export default startHandler()
-```
-
-### App Pattern
-
-```coffee
-import { App, get, post } from '@rip-lang/server'
-
-export default App ->
-  get '/', -> 'Hello'
-  post '/echo', -> read()
+```bash
+rip server --edgefile=./Edgefile.rip
 ```
 
-## Context Utilities
-
-### ctx()
+### Validate Config Without Serving
 
-Get the current request context from anywhere (via AsyncLocalStorage):
-
-```coffee
-import { ctx } from '@rip-lang/server'
-
-logRequest = ->
-  c = ctx()
-  console.log "#{c.req.method} #{c.req.path}" if c
-
-get '/demo' ->
-  logRequest()
-  { ok: true }
+```bash
+rip server --check-config
+rip server --check-config --edgefile=./Edgefile.rip
 ```
 
-### resetGlobals()
-
-Reset all global state (routes, middleware, filters). Useful for testing:
-
-```coffee
-import { resetGlobals, get, start } from '@rip-lang/server'
+### Reload Config Safely
 
-beforeEach ->
-  resetGlobals()
+Send `SIGHUP` to the long-lived server process:
 
-get '/test', -> { test: true }
+```bash
+kill -HUP "$(cat /tmp/rip_myapp.pid)"
 ```
 
-## Utility Functions
+The default PID file is `/tmp/rip_<app-name>.pid`. If you use a custom socket
+prefix, the PID file follows `/tmp/<socket-prefix>.pid`.
+Reload success or rejection is printed to stderr and reflected in `/diagnostics`.
 
-### isBlank
+You can also trigger reload through the control socket:
 
-```coffee
-import { isBlank } from '@rip-lang/server'
-
-isBlank null        # true
-isBlank undefined   # true
-isBlank ''          # true
-isBlank '   '       # true
-isBlank []          # true
-isBlank {}          # true
-isBlank false       # true
-isBlank 'hello'     # false
-isBlank [1, 2]      # false
+```bash
+curl --unix-socket /tmp/rip_myapp.ctl.sock -X POST http://localhost/reload
 ```
 
-### toName
-
-Advanced name formatting with intelligent capitalization:
+When file watching is enabled, application code changes use the same staged
+reload path automatically. You can always reload Edgefile changes explicitly via
+`SIGHUP` or the control socket API.
 
-```coffee
-import { toName } from '@rip-lang/server'
+### Inspect Active Config And Diagnostics
 
-toName 'john doe'           # 'John Doe'
-toName 'JANE SMITH'         # 'Jane Smith'
-toName "o'brien"            # "O'Brien"
-toName 'mcdonald'           # 'McDonald'
-toName 'los angeles', 'address'  # 'Los Angeles'
+```bash
+curl http://localhost/diagnostics
 ```
 
-### toPhone
+The `config` block reports:
 
-US phone number formatting:
+- config kind (`edge`, `legacy`, or `none`)
+- active path
+- schema version
+- counts for apps, upstreams, routes, and sites
+- active compiled route descriptions
+- last result (`loaded`, `rejected`, etc.)
+- reload timestamp
+- last error, if any
+- active edge runtime inflight/WS counts
+- retired edge runtimes still draining after a config swap
+- last reload attempt record
+- bounded reload history with source, versions, result, and reason
+- structured rollback/rejection code and details for failed reloads
 
-```coffee
-import { toPhone } from '@rip-lang/server'
+The top-level diagnostics payload also includes:
 
-toPhone '5551234567'        # '(555) 123-4567'
-toPhone '555-123-4567'      # '(555) 123-4567'
-toPhone '555.123.4567 x99'  # '(555) 123-4567, ext. 99'
-toPhone '+1 555 123 4567'   # '(555) 123-4567'
-```
-
-## Migration from Hono
+- `upstreams`: per-upstream target counts and healthy/unhealthy target totals
 
-### Before (Hono)
+### Verification Policy
 
-```coffee
-import { Hono } from 'hono'
+Use `edge.verify` to tune post-activate verification:
 
-app = new Hono()
-app.get '/users/:id', (c) ->
-  id = c.req.param 'id'
-  c.json { id }
+- `requireHealthyUpstreams`: require referenced upstreams to prove healthy targets
+- `requireReadyApps`: require referenced managed apps to have ready workers
+- `includeUnroutedManagedApps`: also verify managed apps not directly referenced by a route
+- `minHealthyTargetsPerUpstream`: minimum healthy targets required per referenced upstream
 
-export default app
-```
+## Validation
 
-### After (@rip-lang/server)
+The `read()` function is a validation and parsing powerhouse that eliminates
+90% of API boilerplate. It supports 40+ built-in validators including `email`,
+`phone`, `money`, `uuid`, `json`, `regex`, and composable object schemas.
 
 ```coffee
-import { get, read, startHandler } from '@rip-lang/server'
-
-get '/users/:id', ->
-  id = read 'id', 'id!'
-  { id }
-
-export default startHandler()
+email = read 'email', 'email!'           # required, validated
+phone = read 'phone', 'phone'            # optional, formatted
+role  = read 'role', ['admin', 'user']   # enum
+age   = read 'age', 'int', [18, 120]     # range-checked
 ```
 
-### API Compatibility
-
-| Hono | @rip-lang/server |
-|------|------------------|
-| `app.get(path, handler)` | `get path, handler` |
-| `app.post(path, handler)` | `post path, handler` |
-| `app.use(middleware)` | `use middleware` |
-| `app.basePath(path)` | `prefix path, -> ...` |
-| `c.json(data)` | `@json(data)` or return `{ data }` |
-| `c.req.param('id')` | `@req.param('id')` or `read 'id'` |
-| `c.req.query('q')` | `@req.query('q')` or `read 'q'` |
-
-## Real-World Example
-
-```coffee
-import { get, post, put, del, use, read, start, before, after, onError } from '@rip-lang/server'
-import { logger } from '@rip-lang/server/middleware'
-
-use logger()
-
-before ->
-  @start = Date.now()
-
-after ->
-  console.log "#{@req.method} #{@req.path} - #{Date.now() - @start}ms"
-
-onError (err) ->
-  @json { error: err.message }, err.status or 500
-
-get '/', ->
-  { name: 'My API', version: '1.0' }
-
-get '/users', ->
-  page = read 'page', 'int', [1, 100]
-  limit = read 'limit', 'int', [1, 50]
-  users = db.listUsers! page or 1, limit or 10
-  { users, page, limit }
-
-get '/users/:id', ->
-  id = read 'id', 'id!'
-  user = db.getUser!(id)
-  unless user
-    throw { message: 'User not found', status: 404 }
-  { user }
-
-post '/users', ->
-  email = read 'email', 'email!'
-  name = read 'name', 'string', [1, 100]
-  phone = read 'phone', 'phone'
-  user = db.createUser! { email, name, phone }
-  { user, created: true }
-
-put '/users/:id', ->
-  id = read 'id', 'id!'
-  email = read 'email', 'email'
-  name = read 'name', 'string', [1, 100]
-  user = db.updateUser! id, { email, name }
-  { user, updated: true }
-
-del '/users/:id', ->
-  id = read 'id', 'id!'
-  db.deleteUser!(id)
-  { deleted: true }
-
-start port: 3000
-```
+See the full [Validation Reference](docs/READ_VALIDATORS.md) for all 37+
+validators, patterns, custom validators, and real-world examples.
 
 ## App Path & Naming
 
@@ -843,14 +628,18 @@ rip server [flags] [app-path]@<alias1>,<alias2>,...
 |------|-------------|---------|
 | `-h`, `--help` | Show help and exit | — |
 | `-v`, `--version` | Show version and exit | — |
+| `--edgefile=<path>` | Load `Edgefile.rip` from an explicit path | Auto-discover or none |
+| `--check-config` | Validate `Edgefile.rip` or `config.rip` and exit | Disabled |
 | `--watch=<glob>` | Watch glob pattern | `*.rip` |
 | `--static` | Disable hot reload and file watching | — |
 | `--env=<mode>` | Environment mode (`dev`, `prod`) | `development` |
 | `--debug` | Enable debug logging | Disabled |
+| `--quiet` | Suppress startup URL output | Disabled |
 | `http` | HTTP-only mode (no HTTPS) | HTTPS enabled |
 | `https` | HTTPS mode (explicit) | Auto |
 | `http:<port>` | Set HTTP port | 80, fallback 3000 |
 | `https:<port>` | Set HTTPS port | 443, fallback 3443 |
+| `--socket-prefix=<name>` | Override Unix socket / PID file prefix | `rip_<app-name>` |
 | `w:<n>` | Worker count (`auto`, `half`, `2x`, `3x`, or number) | `half` of cores |
 | `r:<reqs>,<secs>s` | Restart policy: requests, seconds (e.g., `5000,3600s`) | `10000,3600s` |
 | `--cert=<path>` | TLS certificate path | Shipped `*.ripdev.io` cert |
@@ -902,18 +691,7 @@ rip server --debug
 rip server r:5000,3600s
 ```
 
-## Architecture
-
-### Edge Planning Docs
-
-Current M0 artifacts for the unified edge/app evolution live in:
-
-- [Edge contracts](docs/edge/CONTRACTS.md)
-- [Config lifecycle](docs/edge/CONFIG_LIFECYCLE.md)
-- [Scheduler policy](docs/edge/SCHEDULER.md)
-- [Edgefile contract](docs/edge/EDGEFILE_CONTRACT.md)
-- [M0b review notes](docs/edge/M0B_REVIEW_NOTES.md)
-- [TLS spike findings](spikes/tls/FINDINGS.md)
+## Internals
 
 ### Self-Spawning Design
 
@@ -952,18 +730,34 @@ When `RIP_SETUP_MODE=1` is set, the same file runs the one-time setup phase. Whe
 
 ### Request Flow
 
-1. **Main Process** receives HTTP/HTTPS request
-2. **Server** selects available worker from pool
-3. **Request** forwarded via Unix socket
-4. **Worker** processes request, returns response
-5. **Server** forwards response to client
+```mermaid
+flowchart TD
+  request[Incoming Request] --> validate[ValidateRequest]
+  validate --> rateLimit[RateLimit]
+  rateLimit --> edgeRoute{Edge Route Match}
+  edgeRoute -->|upstream| upstream[Proxy To Upstream]
+  edgeRoute -->|app| worker[Forward To Managed Worker]
+  edgeRoute -->|no edge match| registry[Host Registry]
+  registry --> worker
+  worker --> response[Response]
+  upstream --> response
+```
+
+At runtime:
+
+1. validate request and rate-limit early
+2. check the active edge route table
+3. proxy to an upstream if an `upstream` route matches
+4. otherwise resolve a managed app and forward to its worker pool
+5. keep retired edge runtimes alive while in-flight HTTP and websocket traffic drains
 
 ### Hot Reloading
 
 Two layers of hot reload work together by default:
 
-- **API changes** — The Manager watches for `.rip` file changes in the app directory and triggers rolling worker restarts (zero downtime, server-side).
+- **API changes** — The Manager watches `.rip` files per app directory and triggers rolling restarts for the affected app pool only.
 - **UI changes** (`watch: true` in `serve` middleware) — Workers register their component directories with the Manager via the control socket. The Manager watches those directories and broadcasts SSE reload events to connected browsers (client-side).
+- **Edge config changes** — `Edgefile.rip` changes use the staged reload path with verification, rollback, and bounded reload history.
 
 SSE connections are held by the long-lived Server process, not by recyclable workers, ensuring stable hot-reload connections. Each app prefix gets its own SSE pool for multi-app isolation.
 
@@ -1129,6 +923,9 @@ Returns:
   "version": { "server": "1.0.0", "rip": "3.13.108" },
   "uptime": 86400,
   "apps": [{ "id": "myapp", "workers": 4, "inflight": 2, "queueDepth": 0 }],
+  "upstreams": [
+    { "id": "app", "targets": 2, "healthyTargets": 2, "unhealthyTargets": 0 }
+  ],
   "metrics": {
     "requests": 150000,
     "responses": { "2xx": 148000, "4xx": 1500, "5xx": 500 },
@@ -1138,9 +935,41 @@ Returns:
     "acme": { "renewals": 1, "failures": 0 },
     "websocket": { "connections": 45, "messages": 12000, "deliveries": 89000 }
   },
-  "gauges": { "workersActive": 4, "inflight": 2, "queueDepth": 0 },
+  "gauges": {
+    "workersActive": 4,
+    "inflight": 2,
+    "queueDepth": 0,
+    "upstreamTargetsHealthy": 2,
+    "upstreamTargetsUnhealthy": 0
+  },
   "realtime": { "clients": 23, "groups": 8, "deliveries": 89000, "messages": 12000 },
-  "hosts": ["localhost", "myapp.ripdev.io"]
+  "hosts": ["localhost", "myapp.ripdev.io"],
+  "config": {
+    "kind": "edge",
+    "path": "/srv/Edgefile.rip",
+    "version": 1,
+    "counts": { "apps": 2, "upstreams": 1, "routes": 4, "sites": 1 },
+    "lastResult": "applied",
+    "lastError": null,
+    "lastErrorCode": null,
+    "lastErrorDetails": null,
+    "activeRouteDescriptions": [
+      "* /api/* proxy:api",
+      "admin.example.com /* app:admin"
+    ],
+    "activeRuntime": { "id": "edge-123", "inflight": 1, "wsConnections": 2 },
+    "retiredRuntimes": [],
+    "lastReload": {
+      "id": "reload-4",
+      "source": "control_api",
+      "oldVersion": 1,
+      "newVersion": 1,
+      "result": "applied",
+      "reason": null,
+      "code": null
+    },
+    "reloadHistory": []
+  }
 }
 ```
 
@@ -1179,7 +1008,7 @@ Your app must provide a fetch handler. Three patterns are supported:
 ```coffee
 import { get, start } from '@rip-lang/server'
 
-get '/', -> 'Hello!'
+get '/' -> 'Hello!'
 
 start()
 ```
@@ -1297,7 +1126,7 @@ dir = import.meta.dir
 
 use serve dir: dir, title: 'My App', watch: true
 
-get '/css/*', -> @send "#{dir}/css/#{@req.path.slice(5)}"
+get '/css/*' -> @send "#{dir}/css/#{@req.path.slice(5)}"
 
 notFound -> @send "#{dir}/index.html", 'text/html; charset=UTF-8'
 
@@ -1322,22 +1151,6 @@ This gives you:
 
 See [Hot Reloading](#hot-reloading) for details on how the two layers (API + UI) work together.
 
-## Comparison with Other Servers
-
-| Feature | rip server | PM2 | Nginx | Caddy |
-|---------|-----------|-----|-------|-------|
-| Pure Rip | ✅ | ❌ | ❌ | ❌ |
-| Zero Dependencies | ✅ | ❌ | ❌ | ❌ |
-| Hot Reload | ✅ (default) | ✅ | ❌ | ❌ |
-| Multi-Worker | ✅ | ✅ | ✅ | ❌ |
-| Auto HTTPS (ACME) | ✅ | ❌ | ❌ | ✅ |
-| Realtime WebSocket | ✅ (Bam-style) | ❌ | ❌ | ❌ |
-| Runtime Diagnostics | ✅ (latency p50/p95/p99) | ❌ | ❌ | ❌ |
-| mDNS | ✅ | ❌ | ❌ | ❌ |
-| Zero Config | ✅ | ❌ | ❌ | ✅ |
-| Built-in LB | ✅ | ❌ | ✅ | ✅ |
-| Graceful Shutdown | ✅ | ✅ | ✅ | ✅ |
-
 ## Multi-App Configuration (`config.rip`)
 
 If a `config.rip` file exists next to your entry file, the server loads it
@@ -1435,9 +1248,9 @@ Frames flow bidirectionally; close and error propagate between both ends.
 
 ## Roadmap
 
-> *Planned improvements for future releases:*
-
 - [ ] Prometheus / OpenTelemetry metrics export
+- [ ] Inline edge handlers (run small handlers without a worker process)
+- [ ] HTTP response caching at the edge
 
 ## License