@stacksjs/rpx 0.11.13 → 0.11.14

package/src/daemon.ts

@@ -16,8 +16,8 @@
  * paths are reachable without touching `~/.stacks/rpx` or :443.
  */
 /* eslint-disable no-console */
-import type { ProxyOptions, SSLConfig, TlsOption } from './types'
-import type { ProxyRoute } from './proxy-handler'
+import type { ProductionTlsConfig, ProxyOptions, SSLConfig, TlsOption } from './types'
+import type { ProxyRoute, ProxyServer as ProxyServerLike } from './proxy-handler'
 import { spawn as nodeSpawn } from 'node:child_process'
 import * as fsp from 'node:fs/promises'
 import { homedir } from 'node:os'
@@ -25,7 +25,10 @@ import * as path from 'node:path'
 import * as process from 'node:process'
 import { log } from './logger'
 import { checkExistingCertificates, generateCertificate } from './https'
-import { createProxyFetchHandler } from './proxy-handler'
+import { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
+import { matchHost } from './host-match'
+import { buildSniTlsConfig } from './sni'
+import { resolveStaticRoute } from './static-files'
 import { gcStaleEntries, getRegistryDir, isPidAlive, readAll, watchRegistry } from './registry'
 import type { RegistryEntry } from './registry'
 import {
@@ -49,6 +52,12 @@ export interface DaemonOptions {
   hostname?: string
   /** TLS bootstrap options forwarded to httpsConfig. */
   https?: TlsOption
+  /**
+   * Production per-domain SNI certs (real PEMs on disk). When usable certs are
+   * found, the listener serves them per SNI server name instead of the dev
+   * self-signed shared cert.
+   */
+  productionCerts?: ProductionTlsConfig
   /** PID-GC interval in ms. Defaults to 5000. */
   gcIntervalMs?: number
 }
@@ -148,10 +157,18 @@ export async function releaseDaemonLock(rpxDir: string = getDaemonRpxDir()): Pro
  * fetch handler. The entry's `from` is normalized to `host:port`.
  */
 function entryToRoute(entry: RegistryEntry): ProxyRoute {
-  const fromUrl = new URL(entry.from.startsWith('http') ? entry.from : `http://${entry.from}`)
+  const cleanUrls = entry.cleanUrls ?? false
+  if (entry.static) {
+    return {
+      static: resolveStaticRoute(entry.static, cleanUrls),
+      cleanUrls,
+    }
+  }
+  const from = entry.from ?? 'localhost:1'
+  const fromUrl = new URL(from.startsWith('http') ? from : `http://${from}`)
   return {
     sourceHost: fromUrl.host,
-    cleanUrls: entry.cleanUrls ?? false,
+    cleanUrls,
     changeOrigin: entry.changeOrigin ?? false,
     pathRewrites: entry.pathRewrites,
   }
@@ -315,8 +332,10 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
   const pidPath = await acquireDaemonLock(rpxDir)
 
   // Module-scoped state so the watcher and fetch handler share one routing view.
+  // Routing table keyed by host pattern. Lookup prefers an exact match, then
+  // the most-specific `*.suffix` wildcard (see `matchHost`).
   let routingTable = new Map<string, ProxyRoute>()
-  const getRoute = (host: string): ProxyRoute | undefined => routingTable.get(host)
+  const getRoute = (host: string): ProxyRoute | undefined => matchHost(routingTable, host)
 
   function rebuild(entries: RegistryEntry[]): void {
     const next = new Map<string, ProxyRoute>()
@@ -340,19 +359,42 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
     debugLog('daemon', `DNS setup on start failed: ${err}`, verbose)
   })
 
-  const sslConfig = await bootstrapTls(opts, registryDir)
+  // Production per-domain SNI: serve real PEM certs (e.g. Let's Encrypt) keyed
+  // by server name on the one listener. Falls back to the dev shared cert when
+  // no usable production certs are configured.
+  let sniTls: Array<{ serverName: string, cert: string, key: string }> = []
+  if (opts.productionCerts) {
+    sniTls = await buildSniTlsConfig(opts.productionCerts, verbose)
+    if (verbose && sniTls.length > 0)
+      log.info(`SNI: serving ${sniTls.length} real cert(s): ${sniTls.map(e => e.serverName).join(', ')}`)
+  }
 
-  const httpsServer = Bun.serve({
-    port: httpsPort,
-    hostname,
-    tls: {
+  const fetchHandler = createProxyFetchHandler(getRoute, verbose)
+  const wsHandler = createProxyWebSocketHandler(verbose)
+
+  let tlsConfig: unknown
+  if (sniTls.length > 0) {
+    tlsConfig = sniTls.map(e => ({ serverName: e.serverName, cert: e.cert, key: e.key }))
+  }
+  else {
+    const sslConfig = await bootstrapTls(opts, registryDir)
+    tlsConfig = {
       key: sslConfig.key,
       cert: sslConfig.cert,
       ca: sslConfig.ca,
       requestCert: false,
       rejectUnauthorized: false,
+    }
+  }
+
+  const httpsServer = Bun.serve({
+    port: httpsPort,
+    hostname,
+    tls: tlsConfig as any,
+    fetch(req: Request, server: unknown) {
+      return fetchHandler(req, server as ProxyServerLike)
     },
-    fetch: createProxyFetchHandler(getRoute, verbose),
+    websocket: wsHandler,
     error(err: Error) {
       debugLog('daemon', `https server error: ${err}`, verbose)
       return new Response(`Server Error: ${err.message}`, { status: 500 })

package/src/host-match.ts

@@ -0,0 +1,52 @@
+/**
+ * Host-based route matching with wildcard support.
+ *
+ * The routing table is keyed by host pattern. A pattern is either an exact
+ * hostname (`api.example.com`) or a wildcard (`*.example.com`). Lookup prefers
+ * an exact match, then the most-specific (deepest-suffix) wildcard.
+ *
+ * Kept dependency-free and pure so it's reusable from both the daemon and the
+ * in-process multi-proxy path, and trivially unit-testable.
+ */
+
+export function isWildcardPattern(pattern: string): boolean {
+  return pattern.startsWith('*.')
+}
+
+/**
+ * True if `hostname` matches the wildcard `pattern` (`*.suffix`). A wildcard
+ * matches exactly one or more leading labels — `*.example.com` matches
+ * `a.example.com` and `a.b.example.com`, but NOT the bare apex `example.com`.
+ */
+export function matchesWildcard(hostname: string, pattern: string): boolean {
+  if (!isWildcardPattern(pattern))
+    return false
+  const suffix = pattern.slice(1) // '*.example.com' → '.example.com'
+  return hostname.length > suffix.length && hostname.endsWith(suffix)
+}
+
+/**
+ * Find the route value for `hostname` in a host-keyed map. Exact match wins;
+ * otherwise the matching wildcard with the longest (most-specific) suffix wins.
+ * Returns `undefined` when nothing matches.
+ */
+export function matchHost<T>(table: Map<string, T>, hostname: string): T | undefined {
+  const exact = table.get(hostname)
+  if (exact !== undefined)
+    return exact
+
+  let best: T | undefined
+  let bestLen = -1
+  for (const [pattern, value] of table) {
+    if (!isWildcardPattern(pattern))
+      continue
+    if (matchesWildcard(hostname, pattern)) {
+      const len = pattern.length - 1 // length of the matched suffix
+      if (len > bestLen) {
+        bestLen = len
+        best = value
+      }
+    }
+  }
+  return best
+}

package/src/index.ts

@@ -112,8 +112,22 @@ export type {
   StopDaemonResult,
 } from './daemon'
 
-export { createProxyFetchHandler } from './proxy-handler'
-export type { GetRoute, ProxyFetchHandler, ProxyRoute } from './proxy-handler'
+export { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
+export type { GetRoute, ProxyFetchHandler, ProxyRoute, ProxyServer } from './proxy-handler'
+
+export { isWildcardPattern, matchesWildcard, matchHost } from './host-match'
+
+export {
+  contentTypeFor,
+  resolveStaticFile,
+  resolveStaticRoute,
+  safeRelativePath,
+  serveStaticFile,
+} from './static-files'
+export type { ResolvedStaticRoute, StaticResolution } from './static-files'
+
+export { buildSniTlsConfig, serverNameFromCertFilename } from './sni'
+export type { SniTlsEntry } from './sni'
 
 export { deriveIdFromTarget, runViaDaemon } from './daemon-runner'
 export type { DaemonRunnerOptions, DaemonRunnerProxy } from './daemon-runner'

package/src/proxy-handler.ts

@@ -1,5 +1,5 @@
 /**
- * The fetch handler used by the shared :443 server. Both the in-process
+ * The request handlers used by the shared :443 server. Both the in-process
  * multi-proxy mode in `start.ts` and the long-running daemon delegate to this
  * module so routing semantics stay in one place.
  *
@@ -7,37 +7,108 @@
  * The callback indirection lets each caller use whatever data structure makes
  * sense (a fixed Map at startup, or a hot-swappable registry view) without
  * coupling this module to either.
+ *
+ * Three transports are supported per route:
+ *   - HTTP(S) proxying via `fetch()` to an upstream `host:port`.
+ *   - WebSocket proxying via `server.upgrade()` + an upstream `WebSocket`.
+ *   - Static file serving from a local directory (`route.static`).
  */
+import type { ServerWebSocket } from 'bun'
+import type { ResolvedStaticRoute } from './static-files'
 import type { PathRewrite } from './types'
-import { debugLog } from './utils'
-import { resolvePathRewrite } from './utils'
+import { serveStaticFile } from './static-files'
+import { debugLog, resolvePathRewrite } from './utils'
 
 export interface ProxyRoute {
-  /** Upstream `host:port` to forward requests to (e.g. `localhost:5173`). */
-  sourceHost: string
+  /**
+   * Upstream `host:port` to forward requests to (e.g. `localhost:5173`).
+   * Optional when `static` is set.
+   */
+  sourceHost?: string
   /** Strip `.html` suffix and 301 to clean URLs. */
   cleanUrls?: boolean
   /** Set the `origin` header to the target. */
   changeOrigin?: boolean
   /** Per-route path rewrites (vite/nginx-style prefix routing). */
   pathRewrites?: PathRewrite[]
+  /** When set, serve files from a local directory instead of proxying. */
+  static?: ResolvedStaticRoute
 }
 
 export type GetRoute = (hostname: string) => ProxyRoute | undefined
 
-export type ProxyFetchHandler = (req: Request) => Promise<Response>
+export type ProxyFetchHandler = (req: Request, server?: ProxyServer) => Promise<Response | undefined>
+
+/** Minimal shape of the Bun server needed for WebSocket upgrades. */
+export interface ProxyServer {
+  // Loose `any` so it structurally accepts Bun's `Server<WebSocketData>` for
+  // any data generic (the daemon/start callers parameterize differently).
+  upgrade: (req: Request, options?: { data?: any, headers?: any }) => boolean
+}
+
+/** Data attached to an upgraded client socket so the ws handler can dial upstream. */
+interface WsData {
+  targetUrl: string
+  forwardHeaders: Record<string, string>
+}
+
+/** Per-socket state: the upstream client + a buffer for early client frames. */
+interface WsState {
+  upstream: WebSocket
+  upstreamOpen: boolean
+  pending: Array<string | ArrayBufferLike | Uint8Array>
+}
+
+const HOP_BY_HOP = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+  'sec-websocket-key',
+  'sec-websocket-version',
+  'sec-websocket-extensions',
+])
+
+function extractHostname(req: Request): string {
+  const hostHeader = req.headers.get('host') || ''
+  // Strip port (`stacks.localhost:443` → `stacks.localhost`).
+  return hostHeader.split(':')[0]
+}
+
+/**
+ * Resolve the upstream target (`host` + `path`) for a request against a route,
+ * applying any matching path rewrite.
+ */
+function resolveTarget(req: Request, route: ProxyRoute, verbose?: boolean): { targetHost: string, targetPath: string, search: string } {
+  const url = new URL(req.url)
+  let targetHost = route.sourceHost ?? ''
+  let targetPath = url.pathname
+
+  const rewriteMatch = resolvePathRewrite(url.pathname, route.pathRewrites)
+  if (rewriteMatch) {
+    targetHost = rewriteMatch.targetHost
+    targetPath = rewriteMatch.targetPath
+    debugLog('request', `Path rewrite: ${url.pathname} → ${targetHost}${targetPath}`, verbose)
+  }
+
+  return { targetHost, targetPath, search: url.search }
+}
 
 /**
  * Build a Bun.serve-compatible `fetch` handler that routes requests based on
  * the `Host` header. Returns 404 when no route matches and 502 on upstream
- * failures.
+ * failures. When a request is a WebSocket upgrade and `server` is supplied, it
+ * is upgraded (returns `undefined` so Bun completes the handshake) and the
+ * traffic is handled by the `websocket` handler from {@link createProxyWebSocketHandler}.
  */
 export function createProxyFetchHandler(getRoute: GetRoute, verbose?: boolean): ProxyFetchHandler {
-  return async (req: Request): Promise<Response> => {
+  return async (req: Request, server?: ProxyServer): Promise<Response | undefined> => {
     const url = new URL(req.url)
-    const hostHeader = req.headers.get('host') || ''
-    // Strip port (`stacks.localhost:443` → `stacks.localhost`).
-    const hostname = hostHeader.split(':')[0]
+    const hostname = extractHostname(req)
 
     const route = getRoute(hostname)
     if (!route) {
@@ -45,19 +116,42 @@ export function createProxyFetchHandler(getRoute: GetRoute, verbose?: boolean):
       return new Response(`No proxy configured for ${hostname}`, { status: 404 })
     }
 
-    let targetHost = route.sourceHost
-    let targetPath = url.pathname
+    // Static file serving short-circuits everything else.
+    if (route.static)
+      return serveStaticFile(url.pathname, route.static)
+
+    // WebSocket upgrade: hand the socket to Bun and dial the upstream on open.
+    if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+      if (!server || !route.sourceHost)
+        return new Response('WebSocket upgrade not supported here', { status: 400 })
+
+      const { targetHost, targetPath, search } = resolveTarget(req, route, verbose)
+      const targetUrl = `ws://${targetHost}${targetPath}${search}`
 
-    // Per-route path rewrites: prefix preserved by default, matching Vite /
-    // nginx / http-proxy-middleware semantics. See `resolvePathRewrite`.
-    const rewriteMatch = resolvePathRewrite(url.pathname, route.pathRewrites)
-    if (rewriteMatch) {
-      targetHost = rewriteMatch.targetHost
-      targetPath = rewriteMatch.targetPath
-      debugLog('request', `Path rewrite: ${url.pathname} → ${targetHost}${targetPath}`, verbose)
+      const forwardHeaders: Record<string, string> = {}
+      for (const [k, v] of req.headers) {
+        if (!HOP_BY_HOP.has(k.toLowerCase()) && k.toLowerCase() !== 'host')
+          forwardHeaders[k] = v
+      }
+      forwardHeaders.host = targetHost
+      forwardHeaders['x-forwarded-for'] = '127.0.0.1'
+      forwardHeaders['x-forwarded-proto'] = 'https'
+      forwardHeaders['x-forwarded-host'] = hostname
+
+      const data: WsData = { targetUrl, forwardHeaders }
+      const ok = server.upgrade(req, { data })
+      if (ok) {
+        debugLog('ws', `upgraded ${hostname}${targetPath} → ${targetUrl}`, verbose)
+        return undefined
+      }
+      return new Response('WebSocket upgrade failed', { status: 400 })
     }
 
-    const targetUrl = `http://${targetHost}${targetPath}${url.search}`
+    if (!route.sourceHost)
+      return new Response(`No upstream configured for ${hostname}`, { status: 502 })
+
+    const { targetHost, targetPath, search } = resolveTarget(req, route, verbose)
+    const targetUrl = `http://${targetHost}${targetPath}${search}`
 
     try {
       const headers = new Headers(req.headers)
@@ -97,3 +191,72 @@ export function createProxyFetchHandler(getRoute: GetRoute, verbose?: boolean):
     }
   }
 }
+
+/**
+ * Build the `websocket` handler block for Bun.serve. It opens an upstream
+ * `WebSocket` per client socket, buffers client→upstream frames until the
+ * upstream connection is open, and pipes messages, closes and errors in both
+ * directions with a clean teardown.
+ */
+export function createProxyWebSocketHandler(verbose?: boolean) {
+  const state = new WeakMap<ServerWebSocket<WsData>, WsState>()
+
+  return {
+    open(ws: ServerWebSocket<WsData>): void {
+      const { targetUrl, forwardHeaders } = ws.data
+      let upstream: WebSocket
+      try {
+        // Bun's WebSocket accepts a `headers` option (control-channel auth etc.).
+        upstream = new WebSocket(targetUrl, { headers: forwardHeaders } as any)
+      }
+      catch (err) {
+        debugLog('ws', `failed to open upstream ${targetUrl}: ${err}`, verbose)
+        ws.close(1011, 'upstream connect failed')
+        return
+      }
+      upstream.binaryType = 'arraybuffer'
+      const st: WsState = { upstream, upstreamOpen: false, pending: [] }
+      state.set(ws, st)
+
+      upstream.addEventListener('open', () => {
+        st.upstreamOpen = true
+        for (const frame of st.pending)
+          upstream.send(frame as any)
+        st.pending = []
+      })
+      upstream.addEventListener('message', (ev: MessageEvent) => {
+        // Forward both binary (ArrayBuffer) and text frames to the client.
+        ws.send(ev.data as any)
+      })
+      upstream.addEventListener('close', (ev: CloseEvent) => {
+        try { ws.close(ev.code || 1000, ev.reason || '') }
+        catch { /* already closing */ }
+      })
+      upstream.addEventListener('error', () => {
+        debugLog('ws', `upstream error for ${targetUrl}`, verbose)
+        try { ws.close(1011, 'upstream error') }
+        catch { /* already closing */ }
+      })
+    },
+
+    message(ws: ServerWebSocket<WsData>, message: string | Buffer): void {
+      const st = state.get(ws)
+      if (!st)
+        return
+      const frame = typeof message === 'string' ? message : new Uint8Array(message)
+      if (st.upstreamOpen)
+        st.upstream.send(frame as any)
+      else
+        st.pending.push(frame)
+    },
+
+    close(ws: ServerWebSocket<WsData>, code: number, reason: string): void {
+      const st = state.get(ws)
+      if (!st)
+        return
+      state.delete(ws)
+      try { st.upstream.close(code || 1000, reason || '') }
+      catch { /* already closed */ }
+    },
+  }
+}

package/src/registry.ts

@@ -14,7 +14,7 @@
  *   - `id` is validated against a strict charset to keep it from escaping
  *     the registry directory.
  */
-import type { PathRewrite } from './types'
+import type { PathRewrite, StaticRouteConfig } from './types'
 import * as fs from 'node:fs'
 import * as fsp from 'node:fs/promises'
 import { homedir } from 'node:os'
@@ -24,7 +24,8 @@ import { debugLog } from './utils'
 
 export interface RegistryEntry {
   id: string
-  from: string
+  /** Upstream `host:port`. Optional when `static` is set. */
+  from?: string
   to: string
   /**
    * Optional. PID of the long-running process that owns this entry. When set,
@@ -38,6 +39,8 @@ export interface RegistryEntry {
   pathRewrites?: PathRewrite[]
   cleanUrls?: boolean
   changeOrigin?: boolean
+  /** Serve a local directory for this route instead of proxying. */
+  static?: string | StaticRouteConfig
 }
 
 const ID_PATTERN = /^[a-zA-Z0-9._-]+$/
@@ -89,9 +92,13 @@ function isValidEntry(value: unknown): value is RegistryEntry {
   // (manual entries from `rpx register`) the daemon's PID-GC skips it.
   const pidOk = e.pid === undefined
     || (typeof e.pid === 'number' && Number.isInteger(e.pid) && e.pid > 0)
+  // A route forwards to an upstream (`from`) OR serves files (`static`).
+  const hasFrom = typeof e.from === 'string' && e.from.length > 0
+  const hasStatic = typeof e.static === 'string'
+    || (!!e.static && typeof e.static === 'object' && typeof (e.static as StaticRouteConfig).dir === 'string')
   return (
     typeof e.id === 'string' && isValidId(e.id)
-    && typeof e.from === 'string' && e.from.length > 0
+    && (hasFrom || hasStatic)
     && typeof e.to === 'string' && e.to.length > 0
     && pidOk
     && typeof e.createdAt === 'string'
@@ -272,6 +279,7 @@ export function watchRegistry(
           pathRewrites: entry.pathRewrites,
           cleanUrls: entry.cleanUrls,
           changeOrigin: entry.changeOrigin,
+          static: entry.static,
         }))
         .sort((a, b) => a.id.localeCompare(b.id)),
     )

package/src/sni.ts

@@ -0,0 +1,93 @@
+/**
+ * Build a Bun.serve TLS array for per-domain SNI from real PEM files on disk.
+ *
+ * Production deployments (Let's Encrypt) have one cert+key per domain. Bun's
+ * `Bun.serve({ tls: [{ serverName, cert, key }, ...] })` selects the right cert
+ * by SNI server name at handshake time, so a single listener can front many
+ * domains with their own real certs.
+ */
+import type { DomainCert, ProductionTlsConfig } from './types'
+import * as fsp from 'node:fs/promises'
+import * as path from 'node:path'
+import { debugLog } from './utils'
+
+/** One entry of the Bun.serve `tls` array. */
+export interface SniTlsEntry {
+  serverName: string
+  cert: string
+  key: string
+}
+
+/**
+ * Map a PEM filename under a `certsDir` to its SNI server name. Returns `null`
+ * for files that aren't `<name>.crt`. The wildcard convention
+ * `_wildcard.<apex>.crt` maps to server name `*.<apex>`.
+ */
+export function serverNameFromCertFilename(filename: string): string | null {
+  if (!filename.endsWith('.crt'))
+    return null
+  const base = filename.slice(0, -'.crt'.length)
+  if (base.length === 0)
+    return null
+  if (base.startsWith('_wildcard.'))
+    return `*.${base.slice('_wildcard.'.length)}`
+  return base
+}
+
+async function readPair(serverName: string, certPath: string, keyPath: string, verbose?: boolean): Promise<SniTlsEntry | null> {
+  try {
+    const [cert, key] = await Promise.all([
+      fsp.readFile(certPath, 'utf8'),
+      fsp.readFile(keyPath, 'utf8'),
+    ])
+    return { serverName, cert, key }
+  }
+  catch (err) {
+    debugLog('sni', `skipping ${serverName}: ${(err as Error).message}`, verbose)
+    return null
+  }
+}
+
+/**
+ * Build the SNI TLS array from a {@link ProductionTlsConfig}. Reads PEM files
+ * from an explicit `domains` map and/or a `certsDir` convention. Files that
+ * can't be read are skipped (logged in verbose mode). Returns `[]` when nothing
+ * usable is found so the caller can fall back to the dev cert flow.
+ */
+export async function buildSniTlsConfig(cfg: ProductionTlsConfig, verbose?: boolean): Promise<SniTlsEntry[]> {
+  const bySrvName = new Map<string, DomainCert>()
+
+  if (cfg.certsDir) {
+    let names: string[] = []
+    try {
+      names = await fsp.readdir(cfg.certsDir)
+    }
+    catch (err) {
+      debugLog('sni', `certsDir read failed (${cfg.certsDir}): ${(err as Error).message}`, verbose)
+    }
+    for (const name of names) {
+      const serverName = serverNameFromCertFilename(name)
+      if (!serverName)
+        continue
+      const base = name.slice(0, -'.crt'.length)
+      bySrvName.set(serverName, {
+        certPath: path.join(cfg.certsDir, name),
+        keyPath: path.join(cfg.certsDir, `${base}.key`),
+      })
+    }
+  }
+
+  // Explicit `domains` entries take precedence over `certsDir` discoveries.
+  if (cfg.domains) {
+    for (const [serverName, pair] of Object.entries(cfg.domains))
+      bySrvName.set(serverName, pair)
+  }
+
+  const entries: SniTlsEntry[] = []
+  for (const [serverName, pair] of bySrvName) {
+    const entry = await readPair(serverName, pair.certPath, pair.keyPath, verbose)
+    if (entry)
+      entries.push(entry)
+  }
+  return entries
+}