@rip-lang/server 0.5.6 → 0.6.0

package/README.md

@@ -6,9 +6,9 @@
 
 ## Overview
 
-`@rip-lang/server` is a production-grade application server written entirely in Rip. It provides multi-worker process management, hot module reloading, automatic HTTPS, and mDNS service discovery — all in a single ~1,100 line file.
+`@rip-lang/server` is a production-grade application server written entirely in Rip. It provides multi-worker process management, hot reloading, automatic HTTPS, and mDNS service discovery — all in a single ~1,100 line file.
 
-- **`server.rip`** (~1,082 lines) — Complete server: CLI, workers, load balancing, TLS, mDNS
+- **`server.rip`** (~1,100 lines) — Complete server: CLI, workers, load balancing, TLS, mDNS
 
 **Core Philosophy**: Application servers should be simple, fast, and reliable. No complex configuration files. No dependency on external process managers. Just run your app.
 
@@ -54,7 +54,7 @@ rip-server ./app.rip@myapp
 Create `app.rip`:
 
 ```coffee
-import { get, post, read, startHandler } from '@rip-lang/api'
+import { get, read, start } from '@rip-lang/api'
 
 get '/', ->
   'Hello from Rip Server!'
@@ -66,8 +66,7 @@ get '/users/:id', ->
   id = read 'id', 'id!'
   { user: { id, name: "User #{id}" } }
 
-# Export the handler for rip-server
-export default startHandler()
+start()
 ```
 
 Run it:
@@ -104,24 +103,28 @@ rip-server [flags] <app-path>[@alias1,alias2,...]
 
 | Flag | Description | Default |
 |------|-------------|---------|
+| `-v`, `--version` | Show version and exit | — |
 | `http` | HTTP-only mode (no HTTPS) | HTTPS enabled |
 | `https` | HTTPS mode (explicit) | Auto |
 | `http:<port>` | Set HTTP port | 80 or 5700 |
 | `https:<port>` | Set HTTPS port | 443 or 5700 |
 | `w:<n>` | Worker count (`auto`, `half`, `2x`, `3x`, or number) | `half` of cores |
-| `r:<policy>` | Restart policy (e.g., `1000,3600s,10r`) | `10000,3600s,10r` |
+| `r:<policy>` | Restart policy (e.g., `5000,3600s`) | `10000,3600s` |
 | `--cert=<path>` | TLS certificate path | Auto-generated |
 | `--key=<path>` | TLS private key path | Auto-generated |
 | `--auto-tls` | Use mkcert for TLS | Fallback to self-signed |
 | `--hsts` | Enable HSTS headers | Disabled |
 | `--no-redirect-http` | Don't redirect HTTP to HTTPS | Redirects enabled |
-| `--reload=<mode>` | Reload mode: `none`, `process`, `module` | `process` |
+| `--static` | Disable hot reload (production) | Hot reload enabled |
 | `--json-logging` | Output JSON access logs | Human-readable |
 | `--no-access-log` | Disable access logging | Enabled |
 
 ### Subcommands
 
 ```bash
+# Show version
+rip-server --version
+
 # Stop running server
 rip-server stop
 
@@ -147,7 +150,7 @@ rip-server http:3000 app.rip
 # With mDNS aliases (accessible as myapp.local and api.local)
 rip-server app.rip@myapp,api
 
-# Restart after 5000 requests or 1 hour
+# Restart workers after 5000 requests or 1 hour
 rip-server r:5000,3600s app.rip
 ```
 
@@ -193,18 +196,14 @@ When `RIP_WORKER_MODE=1` is set, the same `server.rip` file runs as a worker ins
 
 ### Hot Reloading
 
-Two modes available:
-
-- **`process` mode** (default): File changes trigger rolling restart of all workers
-- **`module` mode**: Each worker reloads the app module on file change (faster, but uses more memory)
+By default, file changes trigger a rolling restart of all workers. Use `--static` in production to disable.
 
 ### Worker Lifecycle
 
-Workers are recycled based on configurable limits:
+Workers are automatically recycled to prevent memory leaks and ensure reliability:
 
-- **maxRequests**: Restart after N requests (default: 10,000)
-- **maxSeconds**: Restart after N seconds (default: 3,600)
-- **maxReloads**: Maximum hot reloads before restart (default: 10)
+- **maxRequests**: Restart worker after N requests (default: 10,000)
+- **maxSeconds**: Restart worker after N seconds (default: 3,600)
 
 ## Built-in Endpoints
 
@@ -248,18 +247,20 @@ Requires `dns-sd` (available on macOS by default).
 
 ## App Requirements
 
-Your app must export a fetch handler. Two patterns are supported:
+Your app must provide a fetch handler. Three patterns are supported:
 
-### Pattern 1: Export `startHandler()` (Recommended)
+### Pattern 1: Use `@rip-lang/api` with `start()` (Recommended)
 
 ```coffee
-import { get, startHandler } from '@rip-lang/api'
+import { get, start } from '@rip-lang/api'
 
 get '/', -> 'Hello!'
 
-export default startHandler()
+start()
 ```
 
+The `start()` function automatically detects when running under `rip-server` and registers the handler.
+
 ### Pattern 2: Export fetch function directly
 
 ```coffee
@@ -282,10 +283,9 @@ export default
 | `RIP_DEBUG` | Enable debug logging |
 | `RIP_MAX_REQUESTS` | Default max requests per worker |
 | `RIP_MAX_SECONDS` | Default max seconds per worker |
-| `RIP_MAX_RELOADS` | Default max reloads per worker |
 | `RIP_MAX_QUEUE` | Maximum request queue size |
 | `RIP_QUEUE_TIMEOUT_MS` | Queue timeout in milliseconds |
-| `RIP_RELOAD` | Reload mode override |
+| `RIP_STATIC` | Set to `1` to disable hot reload |
 
 ## Dashboard
 
@@ -304,7 +304,7 @@ The server includes a built-in dashboard accessible at `http://rip.local/` (when
 | Feature | rip-server | PM2 | Nginx |
 |---------|------------|-----|-------|
 | Pure Rip | ✅ | ❌ | ❌ |
-| Single File | ✅ (~1,076 lines) | ❌ | ❌ |
+| Single File | ✅ (~1,100 lines) | ❌ | ❌ |
 | Hot Reload | ✅ | ✅ | ❌ |
 | Multi-Worker | ✅ | ✅ | ✅ |
 | Auto HTTPS | ✅ | ❌ | ❌ |
@@ -312,18 +312,16 @@ The server includes a built-in dashboard accessible at `http://rip.local/` (when
 | Zero Config | ✅ | ❌ | ❌ |
 | Built-in LB | ✅ | ❌ | ✅ |
 
-## TODO
+## Roadmap
 
 > *Planned improvements for future releases:*
 
-- [ ] "Try it Now" section with clone-and-run example
-- [ ] Dashboard screenshots and feature description
-- [ ] Performance benchmarks (req/s, latency)
-- [ ] Scaling guidelines
-- [ ] More troubleshooting scenarios
+- [ ] Request ID tracing for debugging
+- [ ] Metrics endpoint (Prometheus format)
+- [ ] Multi-file hot reload (watch entire directory)
 - [ ] Static file serving
 - [ ] Rate limiting
-- [ ] Graceful shutdown improvements
+- [ ] Performance benchmarks
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rip-lang/server",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "Pure Rip application server — multi-worker, hot reload, HTTPS, mDNS",
   "type": "module",
   "main": "server.rip",

package/server.rip

@@ -12,14 +12,22 @@
 #   bun server.rip list                    # List registered hosts
 # ==============================================================================
 
-import { existsSync, statSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs'
+import { existsSync, statSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
-import { homedir, cpus } from 'node:os'
+import { homedir, cpus, networkInterfaces } from 'node:os'
 import { X509Certificate } from 'node:crypto'
 
 # Match capture holder for Rip's =~
 _ = null
 
+# ==============================================================================
+# Constants
+# ==============================================================================
+
+MAX_BACKOFF_MS = 30000        # Max delay between worker restart attempts
+MAX_RESTART_COUNT = 10        # Max consecutive worker crashes before giving up
+SHUTDOWN_TIMEOUT_MS = 30000   # Max time to wait for in-flight requests on shutdown
+
 # ==============================================================================
 # Utilities
 # ==============================================================================
@@ -28,6 +36,7 @@ nowMs = -> Date.now()
 
 getWorkerSocketPath = (prefix, id) -> "/tmp/#{prefix}.#{id}.sock"
 getControlSocketPath = (prefix) -> "/tmp/#{prefix}.ctl.sock"
+getPidFilePath = (prefix) -> "/tmp/#{prefix}.pid"
 
 coerceInt = (value, fallback) ->
   return fallback unless value? and value isnt ''
@@ -129,24 +138,20 @@ parseWorkersToken = (token, fallback) ->
   n = parseInt(token)
   if Number.isFinite(n) and n > 0 then n else fallback
 
-parseRestartPolicy = (token, defReqs, defSecs, defReloads) ->
-  return { maxRequests: defReqs, maxSeconds: defSecs, maxReloads: defReloads } unless token
+parseRestartPolicy = (token, defReqs, defSecs) ->
+  return { maxRequests: defReqs, maxSeconds: defSecs } unless token
   maxRequests = defReqs
   maxSeconds = defSecs
-  maxReloads = defReloads
 
   for part in token.split(',').map((s) -> s.trim()).filter(Boolean)
     if part.endsWith('s')
       secs = parseInt(part.slice(0, -1))
       maxSeconds = secs if Number.isFinite(secs) and secs >= 0
-    else if part.endsWith('r')
-      rls = parseInt(part.slice(0, -1))
-      maxReloads = rls if Number.isFinite(rls) and rls >= 0
     else
       n = parseInt(part)
       maxRequests = n if Number.isFinite(n) and n > 0
 
-  { maxRequests, maxSeconds, maxReloads }
+  { maxRequests, maxSeconds }
 
 resolveAppEntry = (appPathInput) ->
   abs = if isAbsolute(appPathInput) then appPathInput else resolve(process.cwd(), appPathInput)
@@ -253,12 +258,10 @@ parseFlags = (argv) ->
   policy = parseRestartPolicy(
     getKV('r:'),
     coerceInt(process.env.RIP_MAX_REQUESTS, 10000),
-    coerceInt(process.env.RIP_MAX_SECONDS, 3600),
-    coerceInt(process.env.RIP_MAX_RELOADS, 10)
+    coerceInt(process.env.RIP_MAX_SECONDS, 3600)
   )
 
-  reloadFlag = getKV('--reload=') or process.env.RIP_RELOAD
-  reload = if reloadFlag in ['none', 'process', 'module'] then reloadFlag else 'process'
+  reload = not (has('--static') or process.env.RIP_STATIC is '1')
 
   httpsPort = do ->
     kv = getKV('--https-port=')
@@ -274,7 +277,6 @@ parseFlags = (argv) ->
     workers
     maxRequestsPerWorker: policy.maxRequests
     maxSecondsPerWorker: policy.maxSeconds
-    maxReloadsPerWorker: policy.maxReloads
     httpPort
     httpsPort
     certPath: getKV('--cert=')
@@ -284,7 +286,7 @@ parseFlags = (argv) ->
     redirectHttp: not has('--no-redirect-http')
     reload
     socketPrefix
-    maxQueue: coerceInt(getKV('--max-queue='), coerceInt(process.env.RIP_MAX_QUEUE, 8192))
+    maxQueue: coerceInt(getKV('--max-queue='), coerceInt(process.env.RIP_MAX_QUEUE, 512))
     queueTimeoutMs: coerceInt(getKV('--queue-timeout-ms='), coerceInt(process.env.RIP_QUEUE_TIMEOUT_MS, 2000))
     connectTimeoutMs: coerceInt(getKV('--connect-timeout-ms='), coerceInt(process.env.RIP_CONNECT_TIMEOUT_MS, 200))
     readTimeoutMs: coerceInt(getKV('--read-timeout-ms='), coerceInt(process.env.RIP_READ_TIMEOUT_MS, 5000))
@@ -299,68 +301,29 @@ parseFlags = (argv) ->
 runWorker = ->
   workerId = parseInt(process.env.WORKER_ID or '0')
   maxRequests = parseInt(process.env.MAX_REQUESTS or '10000')
-  maxReloads = parseInt(process.env.MAX_RELOADS or '10')
   maxSeconds = parseInt(process.env.MAX_SECONDS or '0')
   appEntry = process.env.APP_ENTRY
   socketPath = process.env.SOCKET_PATH
-  hotReloadMode = process.env.RIP_RELOAD or 'none'
   socketPrefix = process.env.SOCKET_PREFIX
   version = parseInt(process.env.RIP_VERSION or '1')
 
-  appReady = false
-  inflight = false
-  handled = 0
   startedAtMs = Date.now()
-  lastMtime = 0
-  cachedHandler = null
-  hotReloadCount = 0
-  lastCheckTime = 0
-  CHECK_INTERVAL_MS = 100
-
-  checkForChanges = ->
-    return false unless hotReloadMode is 'module'
-    now = Date.now()
-    return false if now - lastCheckTime < CHECK_INTERVAL_MS
-    lastCheckTime = now
-    try
-      stats = statSync(appEntry)
-      currentMtime = stats.mtime.getTime()
-      if lastMtime is 0
-        lastMtime = currentMtime
-        return false
-      if currentMtime > lastMtime
-        lastMtime = currentMtime
-        return true
-      false
-    catch
-      false
+  # Use object to avoid Rip closure scoping issues with mutable variables
+  workerState =
+    appReady: false
+    inflight: false
+    handled: 0
+    handler: null
 
   getHandler = ->
-    hasChanged = checkForChanges()
-    if hasChanged
-      hotReloadCount++
-      console.log "[worker #{workerId}] File changed, reloading... (#{hotReloadCount}/#{maxReloads})"
-      cachedHandler = null
-
-      if hotReloadCount >= maxReloads
-        console.log "[worker #{workerId}] Reached maxReloads (#{maxReloads}), graceful exit"
-        setTimeout (-> process.exit(0)), 100
-        return -> new Response('Worker cycling', { status: 503 })
-
-    return cachedHandler if cachedHandler and not hasChanged
+    return workerState.handler if workerState.handler
 
     try
-      # Try to import the API for resetGlobals
-      api = null
-      try
-        api = await import('@rip-lang/api')
-      catch
-        null
+      mod = await import(appEntry)
 
-      api?.resetGlobals?()
+      # Ensure module has fully executed by yielding to microtask queue
+      await Promise.resolve()
 
-      bustQuery = if hotReloadMode is 'module' then "?bust=#{Date.now()}" else ''
-      mod = await import(appEntry + bustQuery)
       fresh = mod.default or mod
 
       if typeof fresh is 'function'
@@ -370,12 +333,18 @@ runWorker = ->
       else
         h = globalThis.__ripHandler  # Handler set by start() in rip-server mode
 
-      h = api?.startHandler?() unless h
-      cachedHandler = h or cachedHandler
-      cachedHandler or (-> new Response('not ready', { status: 503 }))
+      unless h
+        try
+          api = await import('@rip-lang/api')
+          h = api?.startHandler?()
+        catch
+          null
+
+      workerState.handler = h if h
+      workerState.handler or (-> new Response('not ready', { status: 503 }))
     catch e
-      console.error "[worker #{workerId}] import failed:", e if process.env.RIP_DEBUG
-      cachedHandler or (-> new Response('not ready', { status: 503 }))
+      console.error "[worker #{workerId}] import failed:", e
+      workerState.handler or (-> new Response('not ready', { status: 503 }))
 
   selfJoin = ->
     try
@@ -398,7 +367,7 @@ runWorker = ->
   # Preload handler
   try
     initial = getHandler!
-    appReady = typeof initial is 'function'
+    workerState.appReady = typeof initial is 'function'
   catch
     null
 
@@ -407,35 +376,38 @@ runWorker = ->
     maxRequestBodySize: 100 * 1024 * 1024
     fetch: (req) ->
       url = new URL(req.url)
-      return new Response(if appReady then 'ok' else 'not-ready') if url.pathname is '/ready'
+      return new Response(if workerState.appReady then 'ok' else 'not-ready') if url.pathname is '/ready'
 
-      if inflight
+      if workerState.inflight
         return new Response 'busy',
           status: 503
           headers: { 'Rip-Worker-Busy': '1', 'Retry-After': '0', 'Rip-Worker-Id': String(workerId) }
 
       handlerFn = getHandler!
-      appReady = typeof handlerFn is 'function'
-      inflight = true
+      workerState.appReady = typeof handlerFn is 'function'
+      workerState.inflight = true
 
       try
         return new Response('not ready', { status: 503 }) unless typeof handlerFn is 'function'
         res = handlerFn!(req)
         res = res!(req) if typeof res is 'function'
         if res instanceof Response then res else new Response(String(res))
-      catch
+      catch err
+        console.error "[worker #{workerId}] ERROR:", err
         new Response('error', { status: 500 })
       finally
-        inflight = false
-        handled++
-        exceededReqs = handled >= maxRequests
+        workerState.inflight = false
+        workerState.handled++
+        exceededReqs = workerState.handled >= maxRequests
         exceededTime = maxSeconds > 0 and (Date.now() - startedAtMs) / 1000 >= maxSeconds
         setTimeout (-> process.exit(0)), 10 if exceededReqs or exceededTime
 
   selfJoin!
 
   shutdown = ->
-    while inflight
+    # Wait for in-flight request to complete (with timeout)
+    start = Date.now()
+    while workerState.inflight and Date.now() - start < SHUTDOWN_TIMEOUT_MS
       await new Promise (r) -> setTimeout(r, 10)
     try server.stop() catch then null
     selfQuit!
@@ -470,7 +442,7 @@ class Manager
       w = @spawnWorker!(@currentVersion)
       @workers.push(w)
 
-    if @flags.reload is 'process'
+    if @flags.reload
       @currentMtime = @getEntryMtime()
       interval = setInterval =>
         return clearInterval(interval) if @shuttingDown
@@ -489,14 +461,13 @@ class Manager
   stop: ->
     for w in @workers
       try w.process.kill() catch then null
-      try w.process.exited catch then null
-      try Bun.spawn(['rm', '-f', w.socketPath]).exited catch then null
+      try unlinkSync(w.socketPath) catch then null
     @workers = []
 
   spawnWorker: (version) ->
     workerId = ++@nextWorkerId
     socketPath = getWorkerSocketPath(@flags.socketPrefix, workerId)
-    try Bun.spawn(['rm', '-f', socketPath]).exited catch then null
+    try unlinkSync(socketPath) catch then null
 
     workerEnv = Object.assign {}, process.env,
       RIP_WORKER_MODE: '1'
@@ -505,10 +476,8 @@ class Manager
       SOCKET_PREFIX: @flags.socketPrefix
       APP_ENTRY: @flags.appEntry
       MAX_REQUESTS: String(@flags.maxRequestsPerWorker)
-      MAX_RELOADS: String(@flags.maxReloadsPerWorker)
       MAX_SECONDS: String(@flags.maxSecondsPerWorker)
       RIP_LOG_JSON: if @flags.jsonLogging then '1' else '0'
-      RIP_RELOAD: @flags.reload
       RIP_VERSION: String(version or @currentVersion)
 
     proc = Bun.spawn ['rip', __filename],
@@ -523,24 +492,26 @@ class Manager
     tracked
 
   monitor: (w) ->
-    await w.process.exited  # Wait for process to exit
+    # Watch for process exit in background (don't block)
+    w.process.exited.then =>
+      return if @shuttingDown
+      return if @retiringIds.has(w.id)
 
-    # Notify server to remove dead worker's socket entry
-    try
-      ctl = getControlSocketPath(@flags.socketPrefix)
-      body = JSON.stringify({ op: 'quit', workerId: w.id })
-      await fetch('http://localhost/worker', { method: 'POST', body, headers: { 'content-type': 'application/json' }, unix: ctl })
-    catch
-      null
+      # Notify server to remove dead worker's socket entry (fire-and-forget)
+      try
+        ctl = getControlSocketPath(@flags.socketPrefix)
+        body = JSON.stringify({ op: 'quit', workerId: w.id })
+        fetch!('http://localhost/worker', { method: 'POST', body, headers: { 'content-type': 'application/json' }, unix: ctl }).catch(-> null)
+      catch
+        null
 
-    return if @shuttingDown
-    return if @retiringIds.has(w.id)
-    w.restartCount++
-    w.backoffMs = Math.min(w.backoffMs * 2, 30000)
-    return if w.restartCount > 10
-    await new Promise (r) -> setTimeout(r, w.backoffMs)
-    idx = @workers.findIndex((x) -> x.id is w.id)
-    @workers[idx] = @spawnWorker!() if idx >= 0
+      w.restartCount++
+      w.backoffMs = Math.min(w.backoffMs * 2, MAX_BACKOFF_MS)
+      return if w.restartCount > MAX_RESTART_COUNT
+      setTimeout =>
+        idx = @workers.findIndex((x) -> x.id is w.id)
+        @workers[idx] = @spawnWorker(@currentVersion) if idx >= 0
+      , w.backoffMs
 
   waitWorkerReady: (socketPath, timeoutMs = 5000) ->
     start = Date.now()
@@ -565,8 +536,21 @@ class Manager
       @workers.push(replacement)
       pairs.push({ old: oldWorker, replacement })
 
-    Promise.all!(pairs.map((p) => @waitWorkerReady(p.replacement.socketPath, 3000)))
+    # Wait for all replacements and check readiness
+    readyResults = Promise.all!(pairs.map((p) => @waitWorkerReady(p.replacement.socketPath, 3000)))
+
+    # Check if all replacements are ready
+    allReady = readyResults.every((ready) -> ready)
+    unless allReady
+      console.error "[manager] Rolling restart aborted: not all new workers ready"
+      # Kill failed replacements and keep old workers
+      for pair, i in pairs
+        unless readyResults[i]
+          try pair.replacement.process.kill() catch then null
+          @workers = @workers.filter((w) -> w.id isnt pair.replacement.id)
+      return
 
+    # All ready - retire old workers
     for { old } in pairs
       @retiringIds.add(old.id)
       try old.process.kill() catch then null
@@ -611,54 +595,39 @@ class Server
 
   start: ->
     httpOnly = @flags.httpsPort is null
+    fetchFn = @fetch.bind(@)
 
-    startOnPort = (p, fetchFn) =>
+    # Helper to start server, incrementing port if needed
+    startOnPort = (p, opts = {}) =>
       port = p
       while true
         try
-          return Bun.serve({ port, idleTimeout: 8, fetch: fetchFn })
+          return Bun.serve(Object.assign({ port, idleTimeout: 8, fetch: fetchFn }, opts))
         catch e
-          if e?.code is 'EADDRINUSE'
-            port++
-            continue
-          throw e
+          throw e unless e?.code is 'EADDRINUSE'
+          port++
 
     if httpOnly
       if @flags.httpPort is 0
         try
-          @server = Bun.serve({ port: 80, idleTimeout: 8, fetch: @fetch.bind(@) })
+          @server = Bun.serve({ port: 80, idleTimeout: 8, fetch: fetchFn })
         catch e
-          if e?.code in ['EADDRINUSE', 'EACCES']
-            @server = startOnPort(5700, @fetch.bind(@))
-          else
-            throw e
+          throw e unless e?.code in ['EADDRINUSE', 'EACCES']
+          @server = startOnPort(5700)
       else
-        @server = startOnPort(@flags.httpPort, @fetch.bind(@))
+        @server = startOnPort(@flags.httpPort)
       @flags.httpPort = @server.port
     else
       tls = @loadTlsMaterial!
 
-      startOnTlsPort = (p) =>
-        port = p
-        while true
-          try
-            return Bun.serve({ port, idleTimeout: 8, tls, fetch: @fetch.bind(@) })
-          catch e
-            if e?.code is 'EADDRINUSE'
-              port++
-              continue
-            throw e
-
       if not @flags.httpsPort or @flags.httpsPort is 0
         try
-          @httpsServer = Bun.serve({ port: 443, idleTimeout: 8, tls, fetch: @fetch.bind(@) })
+          @httpsServer = Bun.serve({ port: 443, idleTimeout: 8, tls, fetch: fetchFn })
         catch e
-          if e?.code in ['EADDRINUSE', 'EACCES']
-            @httpsServer = startOnTlsPort(5700)
-          else
-            throw e
+          throw e unless e?.code in ['EADDRINUSE', 'EACCES']
+          @httpsServer = startOnPort(5700, { tls })
       else
-        @httpsServer = startOnTlsPort(@flags.httpsPort)
+        @httpsServer = startOnPort(@flags.httpsPort, { tls })
 
       httpsPort = @httpsServer.port
       @flags.httpsPort = httpsPort
@@ -755,8 +724,26 @@ class Server
     @newestVersion is null or worker.version is null or worker.version >= @newestVersion
 
   releaseWorker: (worker) ->
+    return unless worker
+    return unless @sockets.some((s) -> s.socket is worker.socket)  # Validate still in pool
     worker.inflight = 0
-    @availableWorkers.push(worker) if @isCurrentVersion(worker)
+    if @isCurrentVersion(worker)
+      @availableWorkers.push(worker)
+      # Force array mutation to be visible (workaround for timing issue)
+      @availableWorkers.length
+
+  logAccess: (req, res, totalSeconds, workerSeconds) ->
+    if @flags.jsonLogging
+      logAccessJson(@flags.appName, req, res, totalSeconds, workerSeconds)
+    else if @flags.accessLog
+      logAccessHuman(@flags.appName, req, res, totalSeconds, workerSeconds)
+
+  buildResponse: (res, req, start, workerSeconds) ->
+    headers = stripInternalHeaders(res.headers)
+    headers.delete('date')
+    @maybeAddSecurityHeaders(headers)
+    @logAccess(req, res, (performance.now() - start) / 1000, workerSeconds)
+    new Response(res.body, { status: res.status, statusText: res.statusText, headers })
 
   forwardToWorker: (req, socket) ->
     start = performance.now()
@@ -770,7 +757,9 @@ class Server
       res = @forwardOnce!(req, socket.socket)
       workerSeconds = (performance.now() - t0) / 1000
 
-      if res.status is 503 and res.headers.get('Rip-Worker-Busy') is '1'
+      # Only retry bodyless requests (body stream can't be reused)
+      canRetry = req.method in ['GET', 'HEAD', 'OPTIONS', 'DELETE']
+      if canRetry and res.status is 503 and res.headers.get('Rip-Worker-Busy') is '1'
         retry = @getNextAvailableSocket()
         if retry and retry isnt socket
           @releaseWorker(socket)
@@ -779,15 +768,10 @@ class Server
           t1 = performance.now()
           res = @forwardOnce!(req, retry.socket)
           workerSeconds = (performance.now() - t1) / 1000
-          headers = stripInternalHeaders(res.headers)
-          headers.delete('date')
-          if @flags.jsonLogging
-            logAccessJson(@flags.appName, req, res, (performance.now() - start) / 1000, workerSeconds)
-          else if @flags.accessLog
-            logAccessHuman(@flags.appName, req, res, (performance.now() - start) / 1000, workerSeconds)
           @releaseWorker(retry)
-          return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
-    catch
+          return @buildResponse(res, req, start, workerSeconds)
+    catch err
+      console.error "[server] forwardToWorker error:", err.message or err if process.env.RIP_DEBUG
       @sockets = @sockets.filter((x) -> x.socket isnt socket.socket)
       @availableWorkers = @availableWorkers.filter((x) -> x.socket isnt socket.socket)
       released = true
@@ -796,32 +780,28 @@ class Server
       @releaseWorker(socket) unless released
 
     return new Response('Service unavailable', { status: 503, headers: { 'Retry-After': '1' } }) unless res
-
-    headers = stripInternalHeaders(res.headers)
-    headers.delete('date')
-    @maybeAddSecurityHeaders(headers)
-
-    if @flags.jsonLogging
-      logAccessJson(@flags.appName, req, res, (performance.now() - start) / 1000, workerSeconds)
-    else if @flags.accessLog
-      logAccessHuman(@flags.appName, req, res, (performance.now() - start) / 1000, workerSeconds)
-
-    new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+    @buildResponse(res, req, start, workerSeconds)
 
   forwardOnce: (req, socketPath) ->
     inUrl = new URL(req.url)
     forwardUrl = "http://localhost#{inUrl.pathname}#{inUrl.search}"
     controller = new AbortController()
-    timer = setTimeout (-> controller.abort()), @flags.connectTimeoutMs
+    connectTimer = setTimeout (-> controller.abort()), @flags.connectTimeoutMs
+    readTimeoutMs = @flags.readTimeoutMs
 
     try
-      upstream = fetch!(forwardUrl, { method: req.method, headers: req.headers, body: req.body, unix: socketPath, signal: controller.signal })
-      clearTimeout(timer)
+      # Don't await fetch - we need to race the promise against timeout
+      fetchPromise = fetch(forwardUrl, { method: req.method, headers: req.headers, body: req.body, unix: socketPath, signal: controller.signal })
       readGuard = new Promise (_, rej) ->
-        setTimeout (-> rej(new Response('Upstream timeout', { status: 504 }))), @flags.readTimeoutMs
-      Promise.race!([Promise.resolve(upstream), readGuard])
-    finally
-      clearTimeout(timer)
+        setTimeout (-> rej(new Error('Upstream timeout'))), readTimeoutMs
+      res = Promise.race!([fetchPromise, readGuard])
+      clearTimeout(connectTimer)
+      res
+    catch err
+      clearTimeout(connectTimer)
+      if err.message is 'Upstream timeout'
+        return new Response('Gateway timeout', { status: 504 })
+      throw err
 
   drainQueue: ->
     while @inflightTotal < Math.max(1, @sockets.length) and @availableWorkers.length > 0
@@ -897,18 +877,18 @@ class Server
         console.error 'Failed to read TLS cert/key from provided paths. Use http or fix paths.'
         process.exit(2)
 
-    # mkcert path under ~/.rip/certs
+    # Ensure certs directory exists
+    certsDir = join(homedir(), '.rip', 'certs')
+    try mkdirSync(certsDir, { recursive: true }) catch then null
+
+    # Try mkcert first (trusted local CA)
     if @flags.autoTls
-      dir = join(homedir(), '.rip', 'certs')
-      try mkdirSync(dir, { recursive: true }) catch then null
-      certPath = join(dir, 'localhost.pem')
-      keyPath = join(dir, 'localhost-key.pem')
+      certPath = join(certsDir, 'localhost.pem')
+      keyPath = join(certsDir, 'localhost-key.pem')
       unless existsSync(certPath) and existsSync(keyPath)
         try
-          gen = Bun.spawn(['mkcert', '-install'])
-          try gen.exited catch then null
-          p = Bun.spawn(['mkcert', '-key-file', keyPath, '-cert-file', certPath, 'localhost', '127.0.0.1', '::1'])
-          p.exited
+          Bun.spawnSync(['mkcert', '-install'])
+          Bun.spawnSync(['mkcert', '-key-file', keyPath, '-cert-file', certPath, 'localhost', '127.0.0.1', '::1'])
         catch
           null  # fall through to self-signed
       if existsSync(certPath) and existsSync(keyPath)
@@ -918,14 +898,11 @@ class Server
         return { cert, key }
 
     # Self-signed via openssl
-    dir = join(homedir(), '.rip', 'certs')
-    try mkdirSync(dir, { recursive: true }) catch then null
-    certPath = join(dir, 'selfsigned-localhost.pem')
-    keyPath = join(dir, 'selfsigned-localhost-key.pem')
+    certPath = join(certsDir, 'selfsigned-localhost.pem')
+    keyPath = join(certsDir, 'selfsigned-localhost-key.pem')
     unless existsSync(certPath) and existsSync(keyPath)
       try
-        p = Bun.spawn(['openssl', 'req', '-x509', '-nodes', '-newkey', 'rsa:2048', '-keyout', keyPath, '-out', certPath, '-subj', '/CN=localhost', '-days', '1'])
-        p.exited
+        Bun.spawnSync(['openssl', 'req', '-x509', '-nodes', '-newkey', 'rsa:2048', '-keyout', keyPath, '-out', certPath, '-subj', '/CN=localhost', '-days', '3650'])
       catch
         console.error 'TLS required but could not provision a certificate (mkcert/openssl missing). Use http or provide --cert/--key.'
         process.exit(2)
@@ -950,12 +927,12 @@ class Server
 
   getLanIP: ->
     try
-      output = Bun.spawnSync(['ifconfig'], { stdout: 'pipe' }).stdout.toString()
-      matches = output.match(/inet\s+(\d+\.\d+\.\d+\.\d+)/g)
-      if matches
-        for match in matches
-          ip = match.split(/\s+/)[1]
-          return ip if ip and ip isnt '127.0.0.1' and not ip.startsWith('169.254.')
+      nets = networkInterfaces()
+      for name, addrs of nets
+        for addr in addrs
+          continue if addr.internal or addr.family isnt 'IPv4'
+          continue if addr.address.startsWith('169.254.')  # Link-local
+          return addr.address
     catch
       null
     null
@@ -971,13 +948,14 @@ class Server
 
     port = @flags.httpsPort or @flags.httpPort or 80
     protocol = if @flags.httpsPort then 'https' else 'http'
+    serviceType = if @flags.httpsPort then '_https._tcp' else '_http._tcp'
     serviceName = host.replace('.local', '')
 
     try
       proc = Bun.spawn [
         'dns-sd', '-P'
         serviceName
-        '_http._tcp'
+        serviceType
         'local'
         String(port)
         host
@@ -1002,46 +980,62 @@ class Server
 # ==============================================================================
 
 main = ->
-  # Subcommand: stop
-  if 'stop' in process.argv
+  # Version flag
+  if '--version' in process.argv or '-v' in process.argv
     try
-      Bun.spawn(['pkill', '-f', __filename]).exited
-      Bun.spawn(['pkill', '-f', 'dns-sd -P.*_http._tcp']).exited
+      pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'))
+      console.log "rip-server v#{pkg.version}"
     catch
-      null
-    console.log 'rip-server: stop requested'
+      console.log 'rip-server (version unknown)'
     return
 
-  # Subcommand: list
-  if 'list' in process.argv
-    getKV = (prefix) ->
-      for tok in process.argv
-        return tok.slice(prefix.length) if tok.startsWith(prefix)
-      undefined
+  # Helper functions for subcommands
+  getKV = (prefix) ->
+    for tok in process.argv
+      return tok.slice(prefix.length) if tok.startsWith(prefix)
+    undefined
 
-    findAppPathToken = ->
-      for i in [2...process.argv.length]
-        tok = process.argv[i]
-        pathPart = if tok.includes('@') then tok.split('@')[0] else tok
-        looksLikePath = pathPart.includes('/') or pathPart.startsWith('.') or pathPart.endsWith('.rip') or pathPart.endsWith('.ts')
-        try
-          return pathPart if looksLikePath and existsSync(if isAbsolute(pathPart) then pathPart else resolve(process.cwd(), pathPart))
-        catch
-          null
-      undefined
+  findAppPathToken = ->
+    for i in [2...process.argv.length]
+      tok = process.argv[i]
+      pathPart = if tok.includes('@') then tok.split('@')[0] else tok
+      looksLikePath = pathPart.includes('/') or pathPart.startsWith('.') or pathPart.endsWith('.rip') or pathPart.endsWith('.ts')
+      try
+        return pathPart if looksLikePath and existsSync(if isAbsolute(pathPart) then pathPart else resolve(process.cwd(), pathPart))
+      catch
+        null
+    undefined
 
-    computeSocketPrefix = ->
-      override = getKV('--socket-prefix=')
-      return override if override
-      appTok = findAppPathToken()
-      if appTok
-        try
-          { appName } = resolveAppEntry(appTok)
-          return "rip_#{appName}"
-        catch
-          null
-      'rip_server'
+  computeSocketPrefix = ->
+    override = getKV('--socket-prefix=')
+    return override if override
+    appTok = findAppPathToken()
+    if appTok
+      try
+        { appName } = resolveAppEntry(appTok)
+        return "rip_#{appName}"
+      catch
+        null
+    'rip_server'
 
+  # Subcommand: stop
+  if 'stop' in process.argv
+    prefix = computeSocketPrefix()
+    pidFile = getPidFilePath(prefix)
+    try
+      if existsSync(pidFile)
+        pid = parseInt(readFileSync(pidFile, 'utf8').trim())
+        process.kill(pid, 'SIGTERM')
+        console.log "rip-server: sent SIGTERM to process #{pid}"
+      else
+        console.log "rip-server: no PID file found at #{pidFile}, trying pkill..."
+        Bun.spawnSync(['pkill', '-f', __filename])
+    catch e
+      console.error "rip-server: stop failed: #{e.message}"
+    return
+
+  # Subcommand: list
+  if 'list' in process.argv
     controlUnix = getControlSocketPath(computeSocketPrefix())
     try
       res = fetch!('http://localhost/registry', { unix: controlUnix, method: 'GET' })
@@ -1056,11 +1050,15 @@ main = ->
 
   # Normal startup
   flags = parseFlags(process.argv)
+  pidFile = getPidFilePath(flags.socketPrefix)
+  writeFileSync(pidFile, String(process.pid))
+
   svr = new Server(flags)
   mgr = new Manager(flags)
 
   cleanup = ->
     console.log 'rip-server: shutting down...'
+    try unlinkSync(pidFile) catch then null
     svr.stop()
     mgr.stop!
     process.exit(0)