@stacksjs/rpx 0.11.14 → 0.11.16

package/src/daemon.ts

@@ -16,7 +16,7 @@
  * paths are reachable without touching `~/.stacks/rpx` or :443.
  */
 /* eslint-disable no-console */
-import type { ProductionTlsConfig, ProxyOptions, SSLConfig, TlsOption } from './types'
+import type { OnDemandTlsConfig, 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'
@@ -26,8 +26,10 @@ import * as process from 'node:process'
 import { log } from './logger'
 import { checkExistingCertificates, generateCertificate } from './https'
 import { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
-import { matchHost } from './host-match'
+import { buildHostRoutes, matchHostRoute, normalizePathPrefix } from './host-routes'
+import type { HostRoutes } from './host-routes'
 import { buildSniTlsConfig } from './sni'
+import { OnDemandCertManager } from './on-demand'
 import { resolveStaticRoute } from './static-files'
 import { gcStaleEntries, getRegistryDir, isPidAlive, readAll, watchRegistry } from './registry'
 import type { RegistryEntry } from './registry'
@@ -58,6 +60,12 @@ export interface DaemonOptions {
    * self-signed shared cert.
    */
   productionCerts?: ProductionTlsConfig
+  /**
+   * On-demand TLS: lazily issue real certs for approved unknown hosts via ACME
+   * http-01 (served from this daemon's `:80` listener). Opt-in via `enabled`.
+   * Seeded with the `productionCerts`/`certsDir` certs already on disk.
+   */
+  onDemandTls?: OnDemandTlsConfig
   /** PID-GC interval in ms. Defaults to 5000. */
   gcIntervalMs?: number
 }
@@ -70,6 +78,13 @@ export interface DaemonHandle {
   httpsPort: number
   httpPort: number
   pidPath: string
+  /**
+   * Pre-warm an on-demand cert for `host` (issue it now if approved & missing,
+   * rebuilding the `:443` listener). Resolves `true` if a cert is available
+   * afterwards. No-op resolving `false` when on-demand TLS isn't enabled. Lets a
+   * tunnel server warm a subdomain's cert at registration time.
+   */
+  ensureCert: (host: string) => Promise<boolean>
 }
 
 const DEFAULT_GC_INTERVAL_MS = 5000
@@ -158,10 +173,12 @@ export async function releaseDaemonLock(rpxDir: string = getDaemonRpxDir()): Pro
  */
 function entryToRoute(entry: RegistryEntry): ProxyRoute {
   const cleanUrls = entry.cleanUrls ?? false
+  const basePath = normalizePathPrefix(entry.path)
   if (entry.static) {
     return {
       static: resolveStaticRoute(entry.static, cleanUrls),
       cleanUrls,
+      basePath,
     }
   }
   const from = entry.from ?? 'localhost:1'
@@ -171,6 +188,7 @@ function entryToRoute(entry: RegistryEntry): ProxyRoute {
     cleanUrls,
     changeOrigin: entry.changeOrigin ?? false,
     pathRewrites: entry.pathRewrites,
+    basePath,
   }
 }
 
@@ -290,6 +308,9 @@ async function elevateDaemonToRoot(
           try { process.kill(pid, 'SIGTERM') }
           catch { /* EPERM — root-owned shared daemon */ }
         },
+        // On-demand issuance runs inside the elevated child's own runDaemon
+        // handle; this caller-side stub can't reach it directly.
+        ensureCert: () => Promise.resolve(false),
       }
     }
     // sudo exits fast when auth fails; while the daemon runs it stays alive.
@@ -312,6 +333,9 @@ async function elevateDaemonToRoot(
  * listeners are bound and the initial routing table is populated. Use
  * `handle.done` for the lifetime promise.
  */
+// `opts` IS used throughout; pickier's no-unused-vars mis-fires on this fn after
+// the on-demand serve refactor (its --fix would wrongly rename to `_opts`).
+// eslint-disable-next-line pickier/no-unused-vars
 export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle> {
   const verbose = opts.verbose ?? false
   const rpxDir = opts.rpxDir ?? getDaemonRpxDir()
@@ -332,17 +356,20 @@ 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 => matchHost(routingTable, host)
+  // Routing table keyed by host pattern; each host owns an ordered list of
+  // path-scoped routes. Lookup prefers an exact host match, then the
+  // most-specific `*.suffix` wildcard (see `matchHostList`); within a host the
+  // longest matching path prefix wins (see `matchHostRoute`).
+  let routingTable: HostRoutes<ProxyRoute> = new Map()
+  const getRoute = (host: string, pathname: string): ProxyRoute | undefined =>
+    matchHostRoute(routingTable, host, pathname)
 
   function rebuild(entries: RegistryEntry[]): void {
-    const next = new Map<string, ProxyRoute>()
-    for (const e of entries)
-      next.set(e.to, entryToRoute(e))
-    routingTable = next
-    debugLog('daemon', `routing table now covers ${next.size} host(s): ${Array.from(next.keys()).join(', ') || '<empty>'}`, verbose)
+    routingTable = buildHostRoutes(
+      entries.map(e => ({ host: e.to, path: e.path, route: entryToRoute(e) })),
+    )
+    const hosts = Array.from(routingTable.keys())
+    debugLog('daemon', `routing table now covers ${hosts.length} host(s): ${hosts.join(', ') || '<empty>'}`, verbose)
   }
 
   // Initial GC + load before binding so the very first request finds a route.
@@ -372,34 +399,88 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
   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,
+  // Bootstrap the dev shared cert once when there's no real SNI set, so a single
+  // SNI listener with on-demand can still answer hosts that aren't covered yet.
+  let devSslConfig: SSLConfig | null = null
+  if (sniTls.length === 0)
+    devSslConfig = await bootstrapTls(opts, registryDir)
+
+  // On-demand TLS manager (opt-in). Holds the live SNI set; lazily issues real
+  // certs for approved unknown hosts via ACME http-01 served from our :80
+  // listener (Bun can't issue at handshake time — see on-demand.ts header).
+  const onDemandCfg = opts.onDemandTls
+  const onDemand: OnDemandCertManager | null = onDemandCfg?.enabled
+    ? new OnDemandCertManager({
+        config: onDemandCfg,
+        certsDir: onDemandCfg.certsDir ?? opts.productionCerts?.certsDir ?? path.join(rpxDir, 'on-demand-certs'),
+        initial: sniTls,
+        verbose,
+        // A new cert was issued/adopted — rebuild :443 with the augmented set.
+        onCertAdded: (entries) => { void rebuildTls(entries) },
+      })
+    : null
+
+  /** Build the TLS option for Bun.serve from the current SNI set (or dev cert). */
+  function tlsFor(entries: Array<{ serverName: string, cert: string, key: string }>): unknown {
+    if (entries.length > 0)
+      return entries.map(e => ({ serverName: e.serverName, cert: e.cert, key: e.key }))
+    // No real certs: fall back to the dev self-signed shared cert.
+    return {
+      key: devSslConfig!.key,
+      cert: devSslConfig!.cert,
+      ca: devSslConfig!.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)
-    },
-    websocket: wsHandler,
-    error(err: Error) {
-      debugLog('daemon', `https server error: ${err}`, verbose)
-      return new Response(`Server Error: ${err.message}`, { status: 500 })
-    },
-  })
+  /** (Re)create the :443 listener. Factored so on-demand can rebuild it. */
+  function serveHttps(entries: Array<{ serverName: string, cert: string, key: string }>): ReturnType<typeof Bun.serve> {
+    return Bun.serve({
+      port: httpsPort,
+      hostname,
+      tls: tlsFor(entries) as any,
+      fetch(req: Request, server: unknown) {
+        return fetchHandler(req, server as ProxyServerLike)
+      },
+      websocket: wsHandler,
+      error(err: Error) {
+        debugLog('daemon', `https server error: ${err}`, verbose)
+        return new Response(`Server Error: ${err.message}`, { status: 500 })
+      },
+    })
+  }
+
+  let httpsServer = serveHttps(onDemand ? onDemand.sniEntries() : sniTls)
+
+  /**
+   * Bun has no working SNICallback and `server.reload({ tls })` does not update
+   * certs at runtime (verified Bun 1.3.14/1.4.0). So to serve a freshly-issued
+   * cert we tear the old listener down and re-bind with the augmented SNI set.
+   * The rebind is sub-second; if the OS hasn't freed the port yet we retry on a
+   * short async backoff. In-flight requests on the old listener drain
+   * (`stop(false)`). Only ever invoked from the (async) issuance callback.
+   */
+  async function rebuildTls(entries: Array<{ serverName: string, cert: string, key: string }>): Promise<void> {
+    if (stopped)
+      return
+    debugLog('daemon', `rebuilding :443 with ${entries.length} SNI cert(s)`, verbose)
+    httpsServer.stop(false)
+    let lastErr: unknown
+    for (let attempt = 0; attempt < 20 && !stopped; attempt++) {
+      try {
+        httpsServer = serveHttps(entries)
+        return
+      }
+      catch (err) {
+        // EADDRINUSE while the old socket releases — back off briefly, retry.
+        lastErr = err
+        await new Promise(resolve => setTimeout(resolve, 25))
+      }
+    }
+    // Could not rebind: the old listener is already down. Surface the failure.
+    log.error(`rpx: failed to rebuild :443 after issuing cert: ${(lastErr as Error)?.message}`)
+  }
 
   let httpServer: ReturnType<typeof Bun.serve> | null = null
   if (httpPort > 0) {
@@ -409,6 +490,22 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
       fetch(req: Request) {
         const u = new URL(req.url)
         const host = (req.headers.get('host') ?? u.hostname).split(':')[0]
+
+        // Serve ACME http-01 challenges for in-flight on-demand issuances.
+        if (onDemand && u.pathname.startsWith('/.well-known/acme-challenge/')) {
+          const keyAuth = onDemand.challengeStore.handlePath(u.pathname)
+          if (keyAuth !== undefined)
+            return new Response(keyAuth, { status: 200, headers: { 'content-type': 'text/plain' } })
+          return new Response('challenge not found', { status: 404 })
+        }
+
+        // First plaintext hit for an approved-but-uncovered host: kick off
+        // issuance so the cert exists for the subsequent HTTPS request. We don't
+        // block the redirect on it (the browser retries over HTTPS anyway).
+        if (onDemand && !onDemand.hasCert(host)) {
+          onDemand.ensureCert(host).catch(() => {})
+        }
+
         return new Response(null, {
           status: 301,
           headers: { Location: `https://${host}${u.pathname}${u.search}` },
@@ -483,6 +580,7 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
     httpsPort: typeof httpsServer.port === 'number' ? httpsServer.port : httpsPort,
     httpPort: httpServer && typeof httpServer.port === 'number' ? httpServer.port : httpPort,
     pidPath,
+    ensureCert: (host: string) => (onDemand ? onDemand.ensureCert(host) : Promise.resolve(false)),
   }
 }
 

package/src/host-routes.ts

@@ -0,0 +1,147 @@
+/**
+ * Path-aware routing within a single host.
+ *
+ * `host-match.ts` answers "which host pattern owns this hostname?" (exact wins,
+ * then most-specific wildcard). That is sufficient when every host maps to a
+ * single backend. But a single domain often needs to serve several things at
+ * once — e.g. `stacksjs.com/api/*` proxied to an app on `:3000`,
+ * `stacksjs.com/docs*` served from `/var/www/docs`, and `stacksjs.com/` served
+ * from `/var/www/public`. That requires a second routing dimension: the
+ * request **path**.
+ *
+ * This module layers path routing on top of host routing without disturbing
+ * host-only routing:
+ *   - Each host pattern maps to a list of `(path, route)` entries.
+ *   - Lookup first resolves the host (reusing `matchHost` semantics), then picks
+ *     the entry whose `path` is the longest prefix of the request pathname.
+ *   - A host with a single entry whose `path` is `'/'` (or empty) behaves
+ *     exactly like the old host-only table — full backward compatibility.
+ *
+ * Kept dependency-free and pure so it's reusable from both the daemon and the
+ * in-process multi-proxy path, and trivially unit-testable.
+ */
+import { isWildcardPattern, matchesWildcard } from './host-match'
+
+/** One path-scoped route under a host. */
+export interface PathRoute<T> {
+  /**
+   * Path prefix this route owns, e.g. `'/api'`. `'/'` (or `''`) is the host
+   * default that catches everything not claimed by a more specific prefix.
+   */
+  path: string
+  /** The route value (e.g. a {@link import('./proxy-handler').ProxyRoute}). */
+  route: T
+}
+
+/**
+ * A host-keyed routing table where each host owns an ordered set of
+ * path-scoped routes. Build it with {@link buildHostRoutes}.
+ */
+export type HostRoutes<T> = Map<string, Array<PathRoute<T>>>
+
+/**
+ * Normalize a path prefix to a leading-slash, no-trailing-slash form so prefix
+ * comparisons are predictable. `''`/`undefined`/`'/'` all normalize to `'/'`
+ * (the host default). `'/api/'` → `'/api'`, `'docs'` → `'/docs'`.
+ */
+export function normalizePathPrefix(path: string | undefined): string {
+  if (!path || path === '/')
+    return '/'
+  let p = path.trim()
+  if (!p.startsWith('/'))
+    p = `/${p}`
+  // Strip trailing slashes (but keep the root '/').
+  p = p.replace(/\/+$/, '')
+  return p === '' ? '/' : p
+}
+
+/**
+ * True if `pathname` is matched by the prefix `prefix`. The root prefix `'/'`
+ * matches everything. A non-root prefix matches when the pathname equals it
+ * (`/api`), or continues with a `/` (`/api/x`) — so `/api` does NOT match
+ * `/apifoo`, only a real path-segment boundary.
+ */
+export function pathPrefixMatches(pathname: string, prefix: string): boolean {
+  if (prefix === '/')
+    return true
+  if (pathname === prefix)
+    return true
+  return pathname.startsWith(`${prefix}/`)
+}
+
+/**
+ * Build a {@link HostRoutes} table from a flat list of entries. Entries are
+ * grouped by host; within each host the path-routes are sorted longest-prefix
+ * first so {@link matchHostRoute} can take the first match. If two entries
+ * collide on the same (host, path) the later one wins (matching `Map.set`).
+ */
+export function buildHostRoutes<T>(
+  entries: Array<{ host: string, path?: string, route: T }>,
+): HostRoutes<T> {
+  const byHost = new Map<string, Map<string, T>>()
+  for (const e of entries) {
+    const prefix = normalizePathPrefix(e.path)
+    let paths = byHost.get(e.host)
+    if (!paths) {
+      paths = new Map<string, T>()
+      byHost.set(e.host, paths)
+    }
+    paths.set(prefix, e.route)
+  }
+
+  const table: HostRoutes<T> = new Map()
+  for (const [host, paths] of byHost) {
+    const list: Array<PathRoute<T>> = []
+    for (const [path, route] of paths)
+      list.push({ path, route })
+    // Longest prefix first; '/' (length 1) naturally sorts last as the default.
+    list.sort((a, b) => b.path.length - a.path.length)
+    table.set(host, list)
+  }
+  return table
+}
+
+/**
+ * Find the path-route list for `hostname` in a {@link HostRoutes} table. Exact
+ * host match wins; otherwise the most-specific (deepest-suffix) wildcard wins —
+ * mirroring {@link import('./host-match').matchHost}.
+ */
+export function matchHostList<T>(table: HostRoutes<T>, hostname: string): Array<PathRoute<T>> | undefined {
+  const exact = table.get(hostname)
+  if (exact !== undefined)
+    return exact
+
+  let best: Array<PathRoute<T>> | undefined
+  let bestLen = -1
+  for (const [pattern, value] of table) {
+    if (!isWildcardPattern(pattern))
+      continue
+    if (matchesWildcard(hostname, pattern)) {
+      const len = pattern.length - 1
+      if (len > bestLen) {
+        bestLen = len
+        best = value
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * Resolve a (hostname, pathname) pair to a single route value. First the host
+ * is resolved ({@link matchHostList}); then the longest matching path prefix
+ * within that host wins. Returns `undefined` when no host matches, or a host
+ * matches but no path prefix (including the `'/'` default) covers the request.
+ */
+export function matchHostRoute<T>(table: HostRoutes<T>, hostname: string, pathname: string): T | undefined {
+  const list = matchHostList(table, hostname)
+  if (!list)
+    return undefined
+  // `list` is pre-sorted longest-prefix-first, so the first match is the most
+  // specific one ('/' is last and matches everything as the host default).
+  for (const entry of list) {
+    if (pathPrefixMatches(pathname, entry.path))
+      return entry.route
+  }
+  return undefined
+}

package/src/index.ts

@@ -112,11 +112,20 @@ export type {
   StopDaemonResult,
 } from './daemon'
 
-export { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
+export { createProxyFetchHandler, createProxyWebSocketHandler, stripBasePath } from './proxy-handler'
 export type { GetRoute, ProxyFetchHandler, ProxyRoute, ProxyServer } from './proxy-handler'
 
 export { isWildcardPattern, matchesWildcard, matchHost } from './host-match'
 
+export {
+  buildHostRoutes,
+  matchHostList,
+  matchHostRoute,
+  normalizePathPrefix,
+  pathPrefixMatches,
+} from './host-routes'
+export type { HostRoutes, PathRoute } from './host-routes'
+
 export {
   contentTypeFor,
   resolveStaticFile,
@@ -129,6 +138,9 @@ export type { ResolvedStaticRoute, StaticResolution } from './static-files'
 export { buildSniTlsConfig, serverNameFromCertFilename } from './sni'
 export type { SniTlsEntry } from './sni'
 
+export { isLikelyHostname, matchesAllowedSuffix, OnDemandCertManager } from './on-demand'
+export type { CertIssuer, OnDemandCertManagerOptions } from './on-demand'
+
 export { deriveIdFromTarget, runViaDaemon } from './daemon-runner'
 export type { DaemonRunnerOptions, DaemonRunnerProxy } from './daemon-runner'