@rip-lang/server 1.3.115 → 1.3.116

package/docs/edge/CONFIG_LIFECYCLE.md

@@ -1,73 +1,111 @@
-# Edge Config Lifecycle (M0b)
+# Edge Config Lifecycle
 
-This document freezes config apply behavior for v1.
+This document describes the implemented v1 lifecycle for `Edgefile.rip` changes.
 
 ## Goal
 
-Config updates must be atomic, reversible, and observable.
+Config updates must be:
+
+- atomic
+- reversible
+- observable
+- safe for in-flight HTTP and websocket proxy traffic
 
 ## Apply pipeline
 
 1. **Parse**
    - Load `Edgefile.rip`.
-   - Compile/evaluate in restricted config context.
-   - Reject if syntax/runtime errors occur.
+   - Evaluate it synchronously in config context.
+   - Reject on syntax or runtime errors.
 
 2. **Validate**
-   - Validate schema version (`version: 1` required).
-   - Validate required keys (`edge`, `app`, `site` domains).
-   - Validate host/path conflicts and ambiguous route precedence.
-   - Validate policy constraints (timeouts, queue caps, worker counts).
+   - Require `version: 1`.
+   - Validate only supported top-level keys:
+     - `version`
+     - `edge`
+     - `upstreams`
+     - `apps`
+     - `routes`
+     - `sites`
+   - Validate route references, wildcard hosts, websocket route requirements,
+     timeout shapes, and verification policy.
 
 3. **Normalize**
    - Expand defaults from `CONTRACTS.md`.
-   - Compile route rules into deterministic route table.
-   - Resolve app entry paths and socket namespaces.
+   - Normalize upstreams, managed apps, route rules, site groups, timeouts, and
+     verification policy.
+   - Compile the deterministic route table.
 
 4. **Stage**
-   - Build a staged config object with new version ID.
-   - Dry-run app pool preparation (spawn readiness checks if needed).
+   - Build a new edge runtime generation:
+     - upstream pool
+     - route table
+     - config metadata
+     - verification policy
+   - Prepare managed app registry changes for the new config.
    - Do not affect active traffic yet.
 
 5. **Activate**
-   - Swap active route/config pointer atomically.
-   - Begin routing new traffic using new route table.
-   - Keep previous config pointer for rollback.
+   - Swap the active edge runtime pointer atomically.
+   - Begin routing new requests through the new generation immediately.
+   - Keep the previous generation as a retired runtime for rollback or drain.
 
 6. **Post-activate verify**
-   - Ensure app pools healthy under new config.
-   - Emit structured "config-activated" event.
+   - Run route-aware verification according to `edge.verify`.
+   - Check referenced upstreams, healthy target counts, and managed app worker readiness.
+   - Emit structured activation events.
 
 7. **Rollback (if needed)**
-   - Revert active pointer to previous known-good config.
-   - Emit structured "config-rollback" event with reason.
+   - Restore the previous app registry snapshot.
+   - Restore the previous active edge runtime.
+   - Mark the failed generation retired and let it drain if needed.
+   - Record structured rollback metadata including reason code and details.
 
 ## Trigger modes
 
 - file watch (`Edgefile.rip`)
 - `SIGHUP`
-- control API (`POST /control/reload`)
+- control API: `POST /reload` on the control Unix socket
 
-All triggers use the same pipeline and safeguards.
+All triggers use the same runtime reload path and the same safeguards.
 
 ## Determinism rules
 
-- No async and no network I/O while evaluating config.
-- Any disallowed operation fails validation.
-- Config evaluation must be repeatable with same input.
+- No async work while evaluating config.
+- No network I/O while evaluating config.
+- Validation must be repeatable for identical input.
 
 ## Failure behavior
 
-- Parse/validate failure: keep serving with existing config.
-- Stage failure: keep serving with existing config.
-- Post-activate health failure: rollback to previous config.
+- Parse/validate failure: keep serving with the existing config.
+- Stage failure: keep serving with the existing config.
+- Post-activate verification failure: rollback to the previous runtime 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 are stopped only after a retired runtime finishes draining.
 
 ## Observability
 
-Every config attempt emits:
+Every reload attempt records:
+
 - attempt ID
-- source trigger (watch/signal/api)
+- source trigger (`startup`, `sighup`, `control_api`)
 - old version
-- new version (if any)
-- result: applied / rejected / rolled_back
+- new version
+- result (`loaded`, `applied`, `rejected`, `rolled_back`)
+- reason
 - reason code
+- reason details
+- timestamp
+
+`/diagnostics` exposes:
+
+- active config metadata
+- active runtime inflight and websocket counts
+- retired runtimes still draining
+- last reload attempt
+- bounded reload history

package/docs/edge/CONTRACTS.md

@@ -1,12 +1,14 @@
-# Edge Contracts (M0b)
+# Edge Contracts
 
-This document freezes the core data contracts for the unified edge/app runtime in `@rip-lang/server`.
-
-Status: Draft frozen for M0b review.
+This document describes the implemented core contracts for the unified
+edge/app runtime in `@rip-lang/server`.
 
 ## Source of truth inputs
 
-- Plan: `.cursor/plans/rip_unified_master_plan_v2_2892e891.plan.md`
+- Runtime implementation: `packages/server/server.rip`
+- Edge config normalization: `packages/server/edge/config.rip`
+- Edge runtime lifecycle: `packages/server/edge/runtime.rip`
+- Verification policy: `packages/server/edge/verify.rip`
 - TLS findings: `packages/server/spikes/tls/FINDINGS.md`
 
 ## AppDescriptor
@@ -14,35 +16,17 @@ Status: Draft frozen for M0b review.
 ```ts
 type AppDescriptor = {
   id: string
-  entry: string
+  entry: string | null
+  appBaseDir: string | null
   hosts: string[]
-  prefixes: string[]
-  workers: number
+  workers: number | null
   maxQueue: number
-  maxInflight: number
+  queueTimeoutMs: number
+  readTimeoutMs: number
   env: Record<string, string>
-  restartPolicy: {
-    maxRestarts: number
-    backoffMs: number
-    windowMs: number
-  }
-  healthCheck: {
-    path: string
-    intervalMs: number
-    timeoutMs: number
-    unhealthyThreshold: number
-  }
 }
 ```
 
-Defaults:
-- `workers`: `cpus().length`, min `2`
-- `maxQueue`: `1000`
-- `maxInflight`: `workers * 32`
-- `env`: `{}`
-- `restartPolicy`: `{ maxRestarts: 10, backoffMs: 1000, windowMs: 60000 }`
-- `healthCheck`: `{ path: "/ready", intervalMs: 5000, timeoutMs: 2000, unhealthyThreshold: 3 }`
-
 ## WorkerEndpoint
 
 ```ts
@@ -51,48 +35,62 @@ type WorkerEndpoint = {
   workerId: number
   socketPath: string
   inflight: number
-  version: number
-  state: "starting" | "ready" | "draining" | "stopped"
+  version: number | null
   startedAt: number
-  requestCount: number
 }
 ```
 
-Defaults:
-- `inflight`: `0`
-- `state`: `"starting"`
-- `requestCount`: `0`
-
-## RouteAction
-
-```ts
-type RouteAction =
-  | { kind: "toApp"; appId: string }
-  | { kind: "proxy"; upstream: string; host?: string }
-  | { kind: "static"; dir: string; spaFallback?: string }
-  | { kind: "redirect"; to: string; status: number }
-  | { kind: "headers"; set?: Record<string, string>; remove?: string[] }
-```
-
 ## RouteRule
 
 ```ts
 type RouteRule = {
   id: string
-  host: string | "*"
-  pathPattern: string
+  host: string | "*" | "*.example.com"
+  path: string
   methods: string[] | "*"
-  action: RouteAction
   priority: number
+  upstream?: 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>
 }
 ```
 
+## VerifyPolicy
+
+```ts
+type VerifyPolicy = {
+  requireHealthyUpstreams: boolean
+  requireReadyApps: boolean
+  includeUnroutedManagedApps: boolean
+  minHealthyTargetsPerUpstream: number
+}
+```
+
 Defaults:
-- `host`: `"*"`
-- `methods`: `"*"`
-- `priority`: declaration order
-- `timeouts`: inherit site/app/global defaults
+
+- `requireHealthyUpstreams: true`
+- `requireReadyApps: true`
+- `includeUnroutedManagedApps: true`
+- `minHealthyTargetsPerUpstream: 1`
+
+## EdgeRuntime
+
+```ts
+type EdgeRuntime = {
+  id: string
+  upstreamPool: UpstreamPool
+  routeTable: RouteTable
+  configInfo: ConfigInfo
+  verifyPolicy: VerifyPolicy | null
+  inflight: number
+  wsConnections: number
+  retiredAt: string | null
+}
+```
 
 ## SchedulerDecision
 
@@ -107,9 +105,10 @@ type SchedulerDecision = {
 ```
 
 Defaults:
-- `algorithm`: `"least-inflight"`
-- `fallback`: `"queue"` while queue `< maxQueue`, else `"shed-503"`
-- `queuePosition`: `null` when immediately assigned
+
+- `algorithm: "least-inflight"`
+- `fallback: "queue"` while queue `< maxQueue`, else `"shed-503"`
+- `queuePosition: null` when immediately assigned
 
 ## TlsCertRecord
 
@@ -128,19 +127,11 @@ type TlsCertRecord = {
 }
 ```
 
-Defaults:
-- `source`: `"acme"` for auto-managed certificates
-- `lastRenewAttempt`: `null`
-- `lastRenewResult`: `null`
-
-## Constraint from M0a
+## TLS constraints
 
 From `packages/server/spikes/tls/FINDINGS.md`:
-- dynamic SNI selection and ALPN-driven cert selection were not observed
-- in-process cert hot reload was not observed
-- graceful restart reload works
 
-Therefore v1 contract assumptions:
-- TLS config is loaded at process start
-- cert activation uses graceful restart path 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 v1 baseline

package/docs/edge/EDGEFILE_CONTRACT.md

@@ -1,53 +1,282 @@
-# Edgefile Contract (M0b)
+# Edgefile Contract
 
-This document freezes v1 config expectations for `Edgefile.rip`.
+This document defines the `Edgefile.rip` contract as implemented in
+`@rip-lang/server`.
 
-## Required top-level shape
+## Host model detection
 
-```text
-version: 1
-edge: ...
-app "...": ...
-site "...": ...
+The Edgefile supports two host models, auto-detected by key presence:
+
+- **Flat model** (`routes`/`sites`) -- routes listed at the top level with optional per-host site groups
+- **Host blocks** (`hosts`) -- per-domain blocks that own cert, root, routes, and passthrough
+`version` and `edge` are optional (default to `1` and `{}` respectively).
+
+## Flat model shape
+
+```coffee
+export default
+  version: 1
+  edge: ...
+  upstreams: ...
+  streamUpstreams: ...
+  apps: ...
+  routes: ...
+  streams: ...
+  sites: ...
+```
+
+## Server blocks shape
+
+```coffee
+export default
+  hosts: ...
+  upstreams: ...
+  apps: ...
+  streamUpstreams: ...
+  streams: ...
+```
+
+### `hosts`
+
+Per-domain server blocks, keyed by hostname (exact or wildcard).
+
+```coffee
+hosts:
+  '*.trusthealth.com':
+    cert: '/ssl/trusthealth.com.crt'
+    key:  '/ssl/trusthealth.com.key'
+    root: '/mnt/trusthealth/website'
+    routes: [
+      { path: '/*', static: '.', spa: true }
+    ]
 ```
 
+Server block fields:
+
+- `passthrough?: string` -- raw TLS passthrough to `host:port` (no cert, no routes needed)
+- `cert?: string` -- TLS certificate path (must pair with `key`)
+- `key?: string` -- TLS private key path (must pair with `cert`)
+- `root?: string` -- default filesystem base; serves static files if no routes are defined
+- `spa?: boolean` -- server-level SPA fallback (used with root-only blocks)
+- `routes?: array` -- route objects (optional if `root` or `passthrough` is set)
+- `timeouts?: object` -- per-server timeout defaults
+
+Per-server `cert`/`key` enable SNI-based certificate selection via Bun's TLS
+array. `edge.cert` and `edge.key` remain the fallback TLS identity for
+unmatched hostnames. The TLS array is sorted by specificity: exact hosts first,
+then wildcards by label count, then the fallback entry.
+
+Routes inside a server block inherit the server hostname and must not specify
+`host`. Routes with `upstream` or `app` must reference known entries from the
+top-level `upstreams` or `apps` sections.
+
+Static routes support `static` (string path), `root` (overrides server root),
+and `spa` (boolean, serves `index.html` on miss for GET/HEAD with Accept
+text/html).
+
+Hosts not matching any server block or stream route fall through to the default
+app.
+
 ## Determinism policy
 
 - Config evaluation is synchronous.
 - Async operations are disallowed.
 - Network I/O is disallowed.
-- Validation errors must include line, field path, and remediation hint.
+- Validation errors must include a field path, message, and remediation hint.
+- With the same file contents, config evaluation must produce the same normalized shape.
+
+## Top-level sections
+
+### `version`
+
+- Optional. Defaults to `1`.
+
+### `edge`
+
+Global edge settings. Optional (defaults to `{}`).
+
+Supported keys:
+
+- `acme: boolean`
+- `acmeDomains: string[]`
+- `cert: string`
+- `key: string`
+- `hsts: boolean`
+- `trustedProxies: string[]`
+- `timeouts: { connectMs, readMs }`
+- `verify: { requireHealthyUpstreams, requireReadyApps, includeUnroutedManagedApps, minHealthyTargetsPerUpstream }`
+
+### `upstreams`
+
+Named reverse-proxy backends.
+
+```coffee
+upstreams:
+  app:
+    targets: ['http://app.incusbr0:3000']
+    healthCheck:
+      path: '/health'
+      intervalMs: 5000
+      timeoutMs: 2000
+    retry:
+      attempts: 2
+      retryOn: [502, 503, 504]
+    timeouts:
+      connectMs: 2000
+      readMs: 30000
+```
+
+### `apps`
+
+Managed Rip applications with worker pools.
+
+```coffee
+apps:
+  admin:
+    entry: './admin/index.rip'
+    hosts: ['admin.example.com']
+    workers: 2
+    maxQueue: 512
+    queueTimeoutMs: 30000
+    readTimeoutMs: 30000
+    env:
+      ADMIN_MODE: '1'
+```
+
+### `streamUpstreams`
 
-## Route actions (v1)
+Named raw TCP upstreams for Layer 4 passthrough.
 
-- `toApp(appId)`
-- `proxy(upstream)`
-- `static(dir)` (optional; app-side static remains valid)
-- `redirect(to, status)`
-- `headers(set/remove)`
+```coffee
+streamUpstreams:
+  incus:
+    targets: ['127.0.0.1:8443']
+    connectTimeoutMs: 5000  # optional, default 5000
+```
+
+### `routes`
+
+Declarative edge route objects.
+
+Each route must define exactly one action:
+
+- `upstream`
+- `app`
+- `static`
+- `redirect`
+- `headers`
+
+Common route fields:
+
+- `id?: string`
+- `host?: string` — exact host, wildcard host like `*.example.com`, or `*`
+- `path: string` — must start with `/`
+- `methods?: string[] | "*"`
+- `priority?: number`
+- `timeouts?: { connectMs, readMs }`
+
+Action-specific fields:
+
+- `upstream: string`
+- `app: string`
+- `static: string`
+- `redirect: { to: string, status: number }`
+- `headers: { set?: object, remove?: string[] }`
+
+WebSocket proxy routes use:
+
+- `websocket: true`
+- `upstream: string`
+
+### `streams`
+
+Declarative Layer 4 stream routes.
+
+```coffee
+streams: [
+  { listen: 8443, sni: ['incus.example.com'], upstream: 'incus' }
+]
+```
+
+Supported fields:
+
+- `id?: string`
+- `listen: number`
+- `sni: string[]`
+- `upstream: string`
+- `timeouts?: { handshakeMs, idleMs, connectMs }`
+
+If a stream route listens on the active HTTPS port, Rip switches that port into
+a shared multiplexer mode:
+
+- the public port is owned by the Layer 4 listener
+- matching SNI traffic is passed through to the configured `streamUpstreams`
+- non-matching SNI, or TLS clients without SNI, fall through to Rip's internal
+  HTTPS server and continue through the normal HTTP/WebSocket edge runtime
+
+### `sites`
+
+Per-host route groups and policy overrides.
+
+```coffee
+sites:
+  'admin.example.com':
+    routes: [
+      { path: '/*', app: 'admin' }
+    ]
+```
 
 ## Host/path precedence
 
-1. exact host > wildcard host
-2. more specific path > less specific path
-3. lower explicit priority number first
-4. declaration order tie-break
+Route precedence is:
+
+1. exact host
+2. wildcard host
+3. catch-all host
+4. more specific path
+5. lower explicit priority number
+6. declaration order tie-break
+
+Wildcard hosts are single-label only:
+
+- `*.example.com` matches `api.example.com`
+- `*.example.com` does **not** match `a.b.example.com`
 
 ## Timeout inheritance
 
-- Global (`edge`) defaults
-- overridden by app/site policy
-- overridden by route-level explicit timeout values
+Timeout resolution is:
+
+1. route-level `timeouts`
+2. site-level `timeouts`
+3. edge-level `timeouts`
+4. server defaults
+
+## Verification policy
+
+`edge.verify` tunes post-activate verification:
+
+- `requireHealthyUpstreams: boolean`
+- `requireReadyApps: boolean`
+- `includeUnroutedManagedApps: boolean`
+- `minHealthyTargetsPerUpstream: number`
+
+These settings affect staged activation, post-activate verification, and rollback.
 
 ## Reload semantics
 
-- Any trigger runs the atomic pipeline from `CONFIG_LIFECYCLE.md`.
-- Invalid config never replaces active config.
+- Every reload trigger runs the same lifecycle.
+- Invalid config never replaces the active config.
+- A new edge runtime is staged, activated atomically, then verified.
+- Failed verification causes automatic rollback to the previous runtime.
+- Retired runtimes drain in-flight HTTP and websocket proxy traffic before cleanup.
 
-## v1 TLS implications from M0a
+## v1 TLS implications
 
 Based on `packages/server/spikes/tls/FINDINGS.md`:
-- v1 should not assume dynamic per-SNI cert switching
-- v1 should not assume in-process cert hot reload
-- v1 should use graceful restart for cert activation
-- v1 ACME baseline should prioritize HTTP-01
+
+- v1 does not assume dynamic per-SNI cert switching.
+- v1 does not assume in-process cert hot reload.
+- v1 uses graceful restart for cert activation.
+- v1 ACME prioritizes HTTP-01.
+- ACME HTTP-01 cannot issue wildcard certificates. Wildcard TLS requires manual
+  `cert` + `key`.

package/docs/edge/M0B_REVIEW_NOTES.md

@@ -1,6 +1,6 @@
 # M0b Review Notes
 
-Status: Active
+Status: Maintained
 
 ## Accepted decisions
 
@@ -25,9 +25,9 @@ Status: Active
 
 ## Open items for next review pass
 
-- Confirm `Edgefile.rip` syntax shape against current Rip parser
-- Validate route precedence edge cases in conformance tests
-- Confirm ops defaults for retention policy in deployment docs
+- Expand end-to-end websocket proxy coverage beyond the current package tests
+- Decide whether staged rollout policy should gain additional operator tuning beyond `edge.verify`
+- Confirm retention policy expectations for reload history and retired runtime visibility in deployment docs
 
 ## Refactor Guardrails
 
@@ -99,4 +99,4 @@ catch e
   - `packages/server/spikes/tls/README.md`
   - `packages/server/spikes/tls/FINDINGS.md`
 - Plan of record:
-  - `.cursor/plans/rip_unified_master_plan_v2_2892e891.plan.md`
+  - `packages/server/docs/edge/PURE_BUN_EDGE_PLAN.md`