@rip-lang/server 1.3.98 → 1.3.99

package/docs/edge/M0B_REVIEW_NOTES.md

@@ -0,0 +1,102 @@
+# M0b Review Notes
+
+Status: Active
+
+## Accepted decisions
+
+- Single project architecture with two runtime roles:
+  - EdgeControlPlane
+  - AppDataPlane
+- Direct request path remains `client -> ingress -> worker` (no relay hop).
+- v1 scheduler: least-inflight with deterministic tie-break.
+- Config apply lifecycle is atomic (`parse -> validate -> normalize -> stage -> activate/rollback`).
+- Deterministic config evaluation (no async/network I/O).
+- v1 TLS posture reflects M0a findings:
+  - HTTP-01 prioritized for reliable v1 ACME
+  - TLS-ALPN-01 treated as beta/deferred
+  - graceful restart cert activation path
+
+## Deferred / future decisions
+
+- Dynamic SNI cert selection when Bun API supports it reliably
+- In-process cert hot reload without restart
+- DNS-01 provider integrations
+- HTTP/2 and gRPC production posture
+
+## 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
+
+## Refactor Guardrails
+
+Group by theme, not by function. A file should cover a coherent area — not
+necessarily one function or one class. Pragmatism over purity.
+
+- Group related functions into one file by theme (e.g. all CLI logic in `cli.rip`).
+- No generic `utils.rip` dumping ground — but themed helpers files are fine.
+- If a module is under ~20 lines with only one importer, fold it into its neighbor.
+- If a module grows past ~300 lines, consider splitting by sub-theme.
+- Keep import fan-out low; if a module imports too many siblings, the boundary is wrong.
+- `server.rip` should stay as orchestration/wiring, not business logic.
+- Every extraction or consolidation must pass tests.
+- Prefer vertical domains:
+  - `edge/*` for request-path behavior (forwarding, scheduling, status, registry)
+  - `control/*` for management (CLI, lifecycle, workers, watchers, mDNS)
+  - `acme/*` only when ACME implementation begins
+
+## Coding Conventions
+
+### Bare `try` over `try ... catch then null`
+
+In Rip, a bare `try` compiles to `try {} catch {}` in JavaScript — functionally
+identical to `try ... catch then null`, which compiles to `try {} catch { null; }`.
+The extra `null;` is a no-op statement with no behavioral difference.
+
+**Preferred style:** use bare `try` for fire-and-forget error suppression.
+
+```coffee
+# Good — clean, concise
+try unlinkSync(path)
+try server.stop()
+
+# Good — multiline bare try
+try
+  proc.kill()
+  console.log "stopped #{host}"
+
+# Avoid — unnecessary catch block
+try unlinkSync(path) catch then null
+
+# Avoid — verbose no-op catch
+try
+  proc.kill()
+catch
+  null
+```
+
+**When to use an explicit catch:**
+- When the catch body does actual work (logging, fallback value, cleanup)
+- When catching a specific error variable: `catch e`
+- When fall-through after try needs a specific return value that differs from `undefined`
+
+```coffee
+# Good — catch does real work
+try
+  pkg = JSON.parse(readFileSync(path, 'utf8'))
+catch
+  console.log 'version unknown'
+
+# Good — catch with error variable
+catch e
+  console.error "failed: #{e.message}"
+```
+
+## Evidence links
+
+- TLS spikes and outputs:
+  - `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`

package/docs/edge/SCHEDULER.md

@@ -0,0 +1,46 @@
+# Scheduler Policy (M0b)
+
+This document freezes v1 scheduler behavior.
+
+## Algorithm
+
+v1 uses **least-inflight** per app pool.
+
+Selection order:
+1. filter to workers in `ready` state
+2. choose 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`
+
+## Fairness expectations
+
+- No worker starvation under steady load
+- No worker starvation under burst load
+- Workload spread should converge over time for equal worker capacity
+
+## Retry policy 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
+
+## Metrics emitted
+
+- per-app scheduler decisions
+- per-worker inflight counts
+- queue depth and queue wait duration
+- shed count (`503` due to capacity)
+
+## Change criteria (v2)
+
+Consider upgrading algorithm if:
+- tail latency variance between workers > 3x for sustained periods
+- workload variance causes persistent imbalance despite least-inflight
+
+Candidate future algorithms:
+- EWMA latency-weighted
+- power-of-two choices

package/middleware.rip

@@ -36,7 +36,7 @@
 import { get, enableCorsPreflight } from '@rip-lang/server'
 import { fileURLToPath } from 'node:url'
 import { dirname, resolve } from 'node:path'
-import { existsSync } from 'node:fs'
+import { existsSync, realpathSync } from 'node:fs'
 
 export cors = (opts = {}) ->
   origin = opts.origin or '*'
@@ -525,12 +525,14 @@ export serve = (opts = {}) ->
     serve._registered = true
 
   # Route: {prefix}/*.rip — serve .rip files from the app directory tree
-  appDirResolved = resolve(appDir)
+  appDirResolved = realpathSync(resolve(appDir))
   get "#{prefix}/*.rip" ->
     name = @req.path.slice("#{prefix}/".length)
     path = resolve(appDir, name)
-    return unless path.startsWith(appDirResolved)
-    @send path, 'text/x-rip; charset=UTF-8' if existsSync(path)
+    return unless existsSync(path)
+    realPath = realpathSync(path)
+    return unless realPath.startsWith(appDirResolved)
+    @send realPath, 'text/x-rip; charset=UTF-8'
 
   # Routes: {prefix}/{name} — per-bundle JSON endpoints (cached + Brotli)
   # Built once per worker on first request, then served from memory with ETag/304.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rip-lang/server",
-  "version": "1.3.98",
+  "version": "1.3.99",
   "description": "Pure Rip web framework and application server",
   "type": "module",
   "main": "api.rip",
@@ -45,7 +45,7 @@
   "author": "Steve Shreeve <steve.shreeve@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "rip-lang": ">=3.13.108"
+    "rip-lang": ">=3.13.109"
   },
   "files": [
     "api.rip",