@rip-lang/server 1.3.125 → 1.4.1

package/{docs/READ_VALIDATORS.md → API.md}

@@ -1,6 +1,16 @@
-# Validation Reference — `read()`
+# Server API Reference
 
-> Extracted from the main [@rip-lang/server README](../README.md).
+> Extracted from the main [@rip-lang/server README](./README.md).
+
+This document covers the framework-facing API for `@rip-lang/server`, including
+validation, routing, middleware, request/response helpers, and app entrypoints.
+
+The framework API is one way to create served content inside Rip Server. It is
+not the whole product identity: the same runtime also serves static content,
+proxied HTTP services, and TCP/TLS services. This reference covers the app and
+API surface within that broader serving model.
+
+## Validation with `read()`
 
 The `read()` function is a validation and parsing powerhouse that eliminates
 90% of API boilerplate.
@@ -265,8 +275,6 @@ get '/logout' ->
 
 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
 
 ```coffee
@@ -297,105 +305,61 @@ use (c, next) ->
 
 ### Request Lifecycle Filters
 
-Three filters run at different stages: `raw` → `before` → handler → `after`
+Three filters run at different stages: `raw` -> `before` -> handler -> `after`
 
 ```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"
 ```
 
-**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:
+Use `@` to access the context directly — no parameter needed.
 
 ### Response Helpers
 
 ```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
-
-  # Raw body
   @body data, 200, { 'Content-Type': 'application/octet-stream' }
-
-  # File serving (auto-detected MIME type via Bun.file)
-  @send 'public/style.css'                    # text/css
-  @send 'data/export.json', 'application/json' # explicit type
+  @send 'public/style.css'
 ```
 
 ### Request Helpers
 
 ```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
+  @req.raw
+  @req.method
+  @req.url
+  @req.path
 ```
 
 ### Request-Scoped State
 
 ```coffee
-# Store data for later middleware/handlers
 use (c, next) ->
   @user = { id: 1, name: 'Alice' }
   @startTime = Date.now()
@@ -410,30 +374,22 @@ get '/profile' ->
 ### `@send(path, type?)`
 
 Serve a file with auto-detected MIME type. Uses `Bun.file()` internally for
-efficient streaming — the file is never buffered in memory.
+efficient streaming.
 
 ```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'
 ```
 
 ### `mimeType(path)`
 
-Exported utility that returns the MIME type for a file path:
-
 ```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'
+mimeType 'style.css'
+mimeType 'app.js'
+mimeType 'photo.png'
 ```
 
 ## Error Handling
@@ -468,7 +424,7 @@ start port: 3000
 start port: 3000, host: '0.0.0.0'
 ```
 
-### Handler Only (for custom servers)
+### Handler Only
 
 ```coffee
 import { startHandler } from '@rip-lang/server'
@@ -488,9 +444,9 @@ export default App ->
 
 ## Context Utilities
 
-### ctx()
+### `ctx()`
 
-Get the current request context from anywhere (via AsyncLocalStorage):
+Get the current request context from anywhere:
 
 ```coffee
 import { ctx } from '@rip-lang/server'
@@ -498,74 +454,52 @@ import { ctx } from '@rip-lang/server'
 logRequest = ->
   c = ctx()
   console.log "#{c.req.method} #{c.req.path}" if c
-
-get '/demo' ->
-  logRequest()
-  { ok: true }
 ```
 
-### resetGlobals()
+### `resetGlobals()`
 
-Reset all global state (routes, middleware, filters). Useful for testing:
+Reset all global state (routes, middleware, filters). Useful for testing.
 
 ```coffee
-import { resetGlobals, get, start } from '@rip-lang/server'
+import { resetGlobals, get } from '@rip-lang/server'
 
 beforeEach ->
   resetGlobals()
-
-get '/test' -> { test: true }
 ```
 
 ## Utility Functions
 
-### isBlank
+### `isBlank`
 
 ```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
+isBlank null
+isBlank ''
+isBlank {}
 ```
 
-### toName
-
-Advanced name formatting with intelligent capitalization:
+### `toName`
 
 ```coffee
 import { toName } from '@rip-lang/server'
 
-toName 'john doe'                    # 'John Doe'
-toName 'JANE SMITH'                  # 'Jane Smith'
-toName "o'brien"                     # "O'Brien"
-toName 'mcdonald'                    # 'McDonald'
-toName 'P. o. bOX #44', 'address'    # 'PO Box #44'
-toName '123 main st ne', 'address'   # '123 Main St NE'
+toName 'john doe'
+toName "o'brien"
 ```
 
-### toPhone
-
-US phone number formatting:
+### `toPhone`
 
 ```coffee
 import { toPhone } from '@rip-lang/server'
 
-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'
+toPhone '5551234567'
+toPhone '555.123.4567 x99'
 ```
 
 ## Migration from Hono
 
-### Before (Hono)
+### Before
 
 ```coffee
 import { Hono } from 'hono'
@@ -578,7 +512,7 @@ app.get '/users/:id', (c) ->
 export default app
 ```
 
-### After (@rip-lang/server)
+### After
 
 ```coffee
 import { get, read, startHandler } from '@rip-lang/server'
@@ -590,18 +524,6 @@ get '/users/:id' ->
 export default startHandler()
 ```
 
-### 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

package/CONFIG.md

@@ -0,0 +1,408 @@
+# Serve Reference
+
+This document is the reference for `serve.rip` and the runtime behavior behind
+it.
+
+Rip Server serves content. Here, `content` means anything you want to make
+reachable over the network: a static site, a Rip app, a proxied HTTP service,
+or a TCP/TLS service.
+
+`serve.rip` is the operator model for publishing and routing that content. It
+combines:
+
+- config shape
+- config lifecycle
+- runtime contracts
+- scheduler policy
+- implementation constraints that matter to operators
+
+Those lifecycle and runtime constraints are part of serving, not side systems.
+TLS, proxy health, verification, rollback, drain, reload, and diagnostics are
+the guarantees that make serving safe and coherent.
+
+## Canonical shape
+
+`serve.rip` is the only config file and `hosts` is the canonical authoring
+surface.
+
+```coffee
+export default
+  version: 1
+  server: {}
+  certs: {}
+  proxies: {}
+  apps: {}
+  rules: {}
+  groups: {}
+  hosts: {}
+  streams: []
+```
+
+There are no alternate top-level route/site models.
+
+## Top-level sections
+
+### `server`
+
+`edge` is accepted as an alias for backward compatibility.
+
+Global settings:
+
+- `acme` (boolean or array of domains)
+- `cert`
+- `key`
+- `hsts`
+- `trustedProxies`
+- `timeouts`
+- `verify`
+
+Verification settings:
+
+- `requireHealthyProxies`
+- `requireReadyApps`
+- `includeUnroutedManagedApps`
+- `minHealthyTargetsPerProxy`
+
+### `certs`
+
+Reusable TLS identities.
+
+Preferred shorthand:
+
+```coffee
+certs:
+  trusthealth: '/ssl/trusthealth.com'
+```
+
+This expands to:
+
+- `cert: '/ssl/trusthealth.com.crt'`
+- `key: '/ssl/trusthealth.com.key'`
+
+Explicit object form is also valid:
+
+```coffee
+certs:
+  trusthealth:
+    cert: '/ssl/trusthealth.com.crt'
+    key: '/ssl/trusthealth.com.key'
+```
+
+### `proxies`
+
+Named backend proxy targets.
+
+Transport kind is inferred from URL scheme:
+
+- `http://...` => HTTP proxy
+- `https://...` => HTTPS proxy
+- `tcp://...` => raw TCP proxy
+
+```coffee
+proxies:
+  api:
+    hosts: ['http://127.0.0.1:4000']
+    check:
+      path: '/health'
+      intervalMs: 5000
+      timeoutMs: 2000
+    retry:
+      attempts: 2
+      retryOn: [502, 503, 504]
+    timeouts:
+      connectMs: 2000
+      readMs: 30000
+
+  incus:
+    hosts: ['tcp://127.0.0.1:8443']
+    connectTimeoutMs: 5000
+```
+
+Rules:
+
+- HTTP proxies may use `check`, `retry`, and `timeouts`
+- TCP proxies may use `connectTimeoutMs`
+- mixed scheme families in one proxy are invalid
+
+### `apps`
+
+Named managed Rip applications with worker and queue settings.
+
+```coffee
+apps:
+  web:
+    entry: './apps/web/index.rip'
+    workers: 4
+    maxQueue: 512
+    queueTimeoutMs: 30000
+    readTimeoutMs: 30000
+```
+
+### `rules`
+
+Named reusable HTTP rule bundles.
+
+```coffee
+rules:
+  web: [
+    { path: '/api/*', proxy: 'api' }
+    { path: '/*', app: 'web' }
+  ]
+```
+
+You do not have to use `rules`. Hosts may also define inline rules or mixed
+arrays of named and inline rules.
+
+### `groups`
+
+Named reusable host lists.
+
+```coffee
+groups:
+  publicWeb: ['example.com', 'www.example.com']
+```
+
+### `hosts`
+
+The canonical config surface. Each binding resolves to one or more concrete
+hosts and owns the HTTP or passthrough behavior for those hosts.
+
+Examples:
+
+```coffee
+hosts:
+  'example.com':
+    cert: 'main'
+    rules: [
+      { path: '/api/*', proxy: 'api' }
+      { path: '/*', app: 'web' }
+    ]
+
+  publicWeb:
+    hosts: 'publicWeb'
+    cert: 'main'
+    rules: 'web'
+
+hosts: *{
+  ['example.com', 'foo.bar.com']:
+    cert: 'main'
+    rules: 'web'
+}
+```
+
+Host block fields:
+
+- `hosts`
+- `cert`
+- `key`
+- `rules`
+- `proxy`
+- `app`
+- `root`
+- `spa`
+- `browse`
+- `timeouts`
+
+Rules:
+
+- `cert` references a named entry in `certs`, unless paired with inline `key`
+- `rules` can reference named rules, inline rules, or both
+- rules inside a host block must not specify `host`
+- `proxy` is a shorthand catch-all proxy binding
+- `app` is a shorthand catch-all app binding
+- `root` is a shorthand catch-all static binding
+- if `proxy` targets a TCP proxy, Rip generates the default `:443` SNI stream route automatically
+
+### `streams`
+
+Explicit Layer 4 stream routes matched by `listen` port and SNI.
+
+```coffee
+streams: [
+  { listen: 443, sni: ['db.example.com'], proxy: 'db' }
+]
+```
+
+If a stream route shares the HTTPS port, Rip switches that port into shared
+multiplexer mode: matching SNI is passed through at Layer 4, and everything
+else falls through to Rip's internal HTTPS server.
+
+## Config lifecycle
+
+### Goal
+
+Config updates must be:
+
+- atomic
+- reversible
+- observable
+- safe for in-flight HTTP and websocket proxy traffic
+
+### Apply pipeline
+
+1. Parse
+   - Load `serve.rip`
+   - Evaluate synchronously in config context
+   - Reject on syntax or runtime errors
+2. Validate
+   - Require `version: 1`
+   - Validate supported top-level keys
+   - Validate reusable config references, wildcard hosts, websocket route requirements, timeout shapes, and verification policy
+3. Normalize
+   - Expand defaults
+   - Normalize certs, proxies, apps, rules, groups, concrete host bindings, timeouts, and verification policy
+   - Compile the deterministic route table
+4. Stage
+   - Build a new edge runtime generation
+   - Prepare managed app registry changes
+   - Do not affect active traffic yet
+5. Activate
+   - Swap the active runtime atomically
+   - Route new traffic through the new generation
+   - Keep the old generation retired for rollback or drain
+6. Post-activate verify
+   - Check referenced HTTP proxies, healthy target counts, and managed app worker readiness
+7. Rollback
+   - Restore the previous registry snapshot and active runtime if verification fails
+
+### Trigger modes
+
+- file watch on `serve.rip`
+- `SIGHUP`
+- control API: `POST /reload`
+
+All triggers use the same reload path and safeguards.
+
+### Failure behavior
+
+- Parse or validate failure: keep serving the existing config
+- Stage failure: keep serving the existing config
+- Post-activate verification failure: rollback automatically
+
+### Draining behavior
+
+- Retired runtimes remain alive while:
+  - HTTP requests that started on them are still in flight
+  - websocket proxy connections that started on them are still open
+- Health checks stop only after a retired runtime finishes draining
+
+## Contracts
+
+### `AppDescriptor`
+
+```ts
+type AppDescriptor = {
+  id: string
+  entry: string | null
+  appBaseDir: string | null
+  hosts: string[]
+  workers: number | null
+  maxQueue: number
+  queueTimeoutMs: number
+  readTimeoutMs: number
+  env: Record<string, string>
+}
+```
+
+### `RouteRule`
+
+```ts
+type RouteRule = {
+  id: string
+  host: string | "*" | "*.example.com"
+  path: string
+  methods: string[] | "*"
+  priority: number
+  proxy?: string | null
+  app?: string | null
+  static?: string | null
+  redirect?: { to: string, status: number } | null
+  headers?: { set?: Record<string, string>, remove?: string[] } | null
+  websocket?: boolean
+  timeouts?: Partial<TimeoutPolicy>
+}
+```
+
+Route rules are normalized from `serve.rip` host bindings. Authoring
+composition through `rules`, `groups`, `certs`, and `proxies` must be fully
+resolved before route compilation.
+
+### `VerifyPolicy`
+
+```ts
+type VerifyPolicy = {
+  requireHealthyProxies: boolean
+  requireReadyApps: boolean
+  includeUnroutedManagedApps: boolean
+  minHealthyTargetsPerProxy: number
+}
+```
+
+Defaults:
+
+- `requireHealthyProxies: true`
+- `requireReadyApps: true`
+- `includeUnroutedManagedApps: true`
+- `minHealthyTargetsPerProxy: 1`
+
+### `EdgeRuntime`
+
+```ts
+type EdgeRuntime = {
+  id: string
+  upstreamPool: UpstreamPool
+  routeTable: RouteTable
+  configInfo: ConfigInfo
+  verifyPolicy: VerifyPolicy | null
+  inflight: number
+  wsConnections: number
+  retiredAt: string | null
+}
+```
+
+## Scheduler policy
+
+v1 uses **least-inflight** per app pool.
+
+Selection order:
+
+1. filter to workers in `ready` state
+2. choose the worker with lowest `inflight`
+3. tie-break by lowest `workerId`
+
+Fallback behavior:
+
+- if all workers are saturated and queue depth `< maxQueue`: enqueue
+- if queue depth `>= maxQueue`: return `503` with `Retry-After`
+
+Retry interaction:
+
+- retry only idempotent requests by default
+- never retry after partial upstream response
+- retry decisions occur after scheduler selection and only on retry-eligible failures
+
+## Operational constraints
+
+- Config evaluation must be deterministic
+- No async work while evaluating config
+- No network I/O while evaluating config
+- Validation errors must include field path, message, and remediation hint
+
+TLS posture in v1:
+
+- dynamic SNI selection was not observed
+- in-process cert hot reload was not observed
+- graceful restart cert activation works
+- ACME HTTP-01 is the reliable baseline
+
+## Historical notes worth keeping
+
+Accepted design choices that still matter:
+
+- single project architecture with two runtime roles:
+  - EdgeControlPlane
+  - AppDataPlane
+- direct request path remains `client -> ingress -> worker`
+- config apply lifecycle is atomic
+- `server.rip` should stay orchestration/wiring, not business logic
+- prefer themed files over generic utility dumping grounds