@stacksjs/rpx 0.11.13 → 0.11.14

package/src/start.ts

@@ -20,8 +20,10 @@ import { addHosts, checkHosts, removeHosts } from './hosts'
 import { checkExistingCertificates, cleanupCertificates, generateCertificate, httpsConfig, loadSSLConfig } from './https'
 import { DefaultPortManager, findAvailablePort, isPortInUse } from './port-manager'
 import { ProcessManager } from './process-manager'
-import { createProxyFetchHandler } from './proxy-handler'
-import type { ProxyRoute } from './proxy-handler'
+import { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
+import type { ProxyRoute, ProxyServer as ProxyServerLike } from './proxy-handler'
+import { isWildcardPattern, matchHost } from './host-match'
+import { resolveStaticRoute } from './static-files'
 import { debugLog, getSudoPassword, safeStringify } from './utils'
 
 const processManager = new ProcessManager()
@@ -307,7 +309,7 @@ export async function startServer(options: SingleProxyConfig): Promise<void> {
 
   // Check and update hosts file for custom domains
   const hostsToCheck = [toUrl.hostname]
-  if (!toUrl.hostname.includes('localhost') && !toUrl.hostname.includes('127.0.0.1')) {
+  if (isHostsManagementEnabled(options) && !toUrl.hostname.includes('localhost') && !toUrl.hostname.includes('127.0.0.1')) {
     debugLog('hosts', `Checking if hosts file entry exists for: ${toUrl.hostname}`, options?.verbose)
 
     try {
@@ -709,9 +711,11 @@ export async function setupProxy(options: ProxySetupOptions): Promise<void> {
   // Use the global port manager if not provided
   const portManager = options.portManager || globalPortManager
 
+  const hostsEnabled = isHostsManagementEnabled(options)
+
   try {
     // Add an extra check to make sure the hostname is in the hosts file
-    if (to && !to.includes('localhost') && !to.includes('127.0.0.1')) {
+    if (hostsEnabled && to && !to.includes('localhost') && !to.includes('127.0.0.1')) {
       const hostsExist = await checkHosts([to], verbose)
       if (!hostsExist[0]) {
         log.warn(`The hostname ${to} isn't in your hosts file. Adding it now...`)
@@ -728,7 +732,7 @@ export async function setupProxy(options: ProxySetupOptions): Promise<void> {
     else {
       // On macOS, *.localhost domains resolve to 127.0.0.1 automatically (RFC 6761)
       // so we don't need to add them to /etc/hosts
-      if (process.platform !== 'darwin' && to && to.includes('localhost') && !to.match(/^(localhost|127\.0\.0\.1)$/)) {
+      if (hostsEnabled && process.platform !== 'darwin' && to && to.includes('localhost') && !to.match(/^(localhost|127\.0\.0\.1)$/)) {
         const hostsExist = await checkHosts([to], verbose)
         if (!hostsExist[0]) {
           debugLog('hosts', `${to} not found in hosts file, adding...`, verbose)
@@ -931,6 +935,23 @@ function getVerbose(options: any): boolean {
   return options?.verbose || false
 }
 
+/**
+ * Whether rpx may read/write `/etc/hosts`. Disabled when `hostsManagement` is
+ * explicitly `false`, or when `cleanup.hosts` is `false` (or `cleanup` is
+ * `false`). Real-server deployments with real DNS should set
+ * `hostsManagement: false` so rpx never touches `/etc/hosts`.
+ */
+function isHostsManagementEnabled(options: any): boolean {
+  if (options?.hostsManagement === false)
+    return false
+  const cleanup = options?.cleanup
+  if (cleanup === false)
+    return false
+  if (cleanup && typeof cleanup === 'object' && cleanup.hosts === false)
+    return false
+  return true
+}
+
 export async function startProxies(options?: ProxyOptions): Promise<void> {
   // Allow re-using a previous SSL config between multiple startProxies calls
   // This is particularly important for the Vite plugin
@@ -957,8 +978,13 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
   }
 
   const verbose = getVerbose(mergedOptions)
+  // Master switch for /etc/hosts management. `hostsManagement: false` (real
+  // server with real DNS) or `cleanup: { hosts: false }` disables all hosts
+  // reads/writes. Defaults to enabled for backward compatibility.
+  const hostsEnabled = isHostsManagementEnabled(mergedOptions)
   debugLog('config', `Starting with config: ${safeStringify(mergedOptions, 2)}`, verbose)
   debugLog('config', `Is multi-proxy? ${'proxies' in mergedOptions}`, verbose)
+  debugLog('config', `Hosts management enabled? ${hostsEnabled}`, verbose)
 
   // viaDaemon mode short-circuits before any port binding / cert work — the
   // daemon owns all of that. We only need to register entries and block.
@@ -1072,7 +1098,7 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
   // Pre-acquire sudo credentials once so that all subsequent sudo operations
   // (cert trust, hosts file, DNS resolver) reuse the cached credential
   // without prompting again. `sudo -v` validates and caches for the timeout period.
-  if (process.platform !== 'win32' && (mergedOptions.https || mergedOptions.cleanup?.hosts !== false)) {
+  if (process.platform !== 'win32' && (mergedOptions.https || hostsEnabled)) {
     const sudoPassword = getSudoPassword()
     if (!sudoPassword) {
       try {
@@ -1151,7 +1177,10 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
     log.info(`  Consider using reserved TLDs: .test, .localhost, or .local`)
   }
 
-  if (process.platform === 'darwin' && customDomains.length > 0) {
+  // Local development DNS (resolver overrides + hosts entries) is a dev-only
+  // convenience. On a real server (`hostsManagement: false`) DNS is real, so
+  // skip it entirely — nothing under /etc should be touched.
+  if (hostsEnabled && process.platform === 'darwin' && customDomains.length > 0) {
     const { setupDevelopmentDns } = await import('./dns')
     const dnsStarted = await setupDevelopmentDns({ domains: customDomains, verbose })
     if (dnsStarted) {
@@ -1217,19 +1246,31 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
 
     for (const option of proxyOptions) {
       const domain = option.to || 'rpx.localhost'
-      const fromUrl = new URL(option.from?.startsWith('http') ? option.from : `http://${option.from}`)
+      const cleanUrls = option.cleanUrls || false
 
-      routingTable.set(domain, {
-        sourceHost: fromUrl.host,
-        cleanUrls: option.cleanUrls || false,
-        changeOrigin: option.changeOrigin || false,
-        pathRewrites: option.pathRewrites,
-      })
-
-      debugLog('proxies', `Route: ${domain} → ${fromUrl.host}`, verbose)
+      // Static-file route: serve a local directory instead of proxying.
+      if (option.static) {
+        routingTable.set(domain, {
+          static: resolveStaticRoute(option.static, cleanUrls),
+          cleanUrls,
+        })
+        debugLog('proxies', `Route: ${domain} → static ${typeof option.static === 'string' ? option.static : option.static.dir}`, verbose)
+      }
+      else {
+        const fromUrl = new URL(option.from?.startsWith('http') ? option.from : `http://${option.from}`)
+        routingTable.set(domain, {
+          sourceHost: fromUrl.host,
+          cleanUrls,
+          changeOrigin: option.changeOrigin || false,
+          pathRewrites: option.pathRewrites,
+        })
+        debugLog('proxies', `Route: ${domain} → ${fromUrl.host}`, verbose)
+      }
 
-      // Ensure hosts file entries exist for non-localhost domains
-      if (!domain.includes('localhost') && !domain.includes('127.0.0.1')) {
+      // Ensure hosts file entries exist for non-localhost domains. A wildcard
+      // domain (`*.example.com`) has no single hosts entry — skip it. Skipped
+      // entirely when hosts management is disabled (real-server mode).
+      if (hostsEnabled && !isWildcardPattern(domain) && !domain.includes('localhost') && !domain.includes('127.0.0.1')) {
         try {
           const hostsExist = await checkHosts([domain], verbose)
           if (!hostsExist[0]) {
@@ -1259,6 +1300,9 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
       return
     }
 
+    const sharedFetchHandler = createProxyFetchHandler(host => matchHost(routingTable, host), verbose)
+    const sharedWsHandler = createProxyWebSocketHandler(verbose)
+
     try {
       const bunServer = Bun.serve({
         port: listenPort,
@@ -1270,7 +1314,10 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
           requestCert: false,
           rejectUnauthorized: false,
         },
-        fetch: createProxyFetchHandler(host => routingTable.get(host), verbose),
+        fetch(req: Request, server: unknown) {
+          return sharedFetchHandler(req, server as ProxyServerLike)
+        },
+        websocket: sharedWsHandler,
         error(err: Error) {
           debugLog('server', `Shared proxy server error: ${err}`, verbose)
           return new Response(`Server Error: ${err.message}`, { status: 500 })

package/src/static-files.ts

@@ -0,0 +1,201 @@
+/**
+ * Static-file serving for proxy routes.
+ *
+ * A route configured with `static` serves files from a local directory instead
+ * of forwarding to an upstream. Path resolution is split into a pure function
+ * (`resolveStaticFile`) so it's trivially unit-testable, and a thin `Bun.file`
+ * wrapper (`serveStaticFile`) that does the actual I/O.
+ */
+import type { PathRewriteStyle, StaticRouteConfig } from './types'
+import * as path from 'node:path'
+
+/** Normalized static-route config (shorthand string already expanded). */
+export interface ResolvedStaticRoute {
+  dir: string
+  spa: boolean
+  pathRewriteStyle: PathRewriteStyle
+  maxAge: number
+  cleanUrls: boolean
+}
+
+export function resolveStaticRoute(
+  cfg: string | StaticRouteConfig,
+  cleanUrls: boolean,
+): ResolvedStaticRoute {
+  if (typeof cfg === 'string')
+    return { dir: cfg, spa: false, pathRewriteStyle: 'directory', maxAge: 0, cleanUrls }
+  return {
+    dir: cfg.dir,
+    spa: cfg.spa ?? false,
+    pathRewriteStyle: cfg.pathRewriteStyle ?? 'directory',
+    maxAge: cfg.maxAge ?? 0,
+    cleanUrls,
+  }
+}
+
+/** A minimal extension → MIME map covering the common web asset types. */
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.txt': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.pdf': 'application/pdf',
+  '.wasm': 'application/wasm',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+}
+
+export function contentTypeFor(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase()
+  return MIME_TYPES[ext] ?? 'application/octet-stream'
+}
+
+/**
+ * Decode + normalize a URL pathname into a safe relative path.
+ *
+ * Traversal safety: normalizing against a leading `/` collapses every `..`
+ * segment and clamps at the root, so the returned relative path never contains
+ * `..` and `path.join(root, rel)` can't escape `root`. Backslash, NUL and
+ * malformed percent-encoding are rejected outright (return `null`); the
+ * residual `..` guard is belt-and-suspenders.
+ */
+export function safeRelativePath(pathname: string): string | null {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(pathname)
+  }
+  catch {
+    return null
+  }
+  // Reject NUL and backslash (Windows-style) escapes outright.
+  if (decoded.includes('\0') || decoded.includes('\\'))
+    return null
+
+  // `path.posix.normalize` collapses `..`/`.`; a leading `/` keeps it rooted so
+  // a normalized result that still contains `..` means traversal above root.
+  const normalized = path.posix.normalize(`/${decoded}`)
+  if (normalized.includes('..'))
+    return null
+  // Strip the leading slash to get a path relative to the static root.
+  return normalized.replace(/^\/+/, '')
+}
+
+export interface StaticResolution {
+  /** Absolute file path to attempt to serve. */
+  filePath: string
+  /** When set, the request should 301-redirect to this clean URL. */
+  redirectTo?: string
+}
+
+/**
+ * Pure resolution of an incoming request pathname to a candidate file path on
+ * disk. Does no I/O; the caller checks existence and may fall back (SPA).
+ *
+ * Rules:
+ *  - A trailing `/` (or root) resolves to `index.html` in that directory.
+ *  - `cleanUrls` + a `.html` request → 301 to the extensionless URL.
+ *  - Extensionless paths resolve per `pathRewriteStyle`:
+ *      - `directory`: `/about` → `about/index.html`
+ *      - `flat`:      `/about` → `about.html`
+ *  - Paths with a real extension (`.css`, `.png`, …) map straight through.
+ *
+ * Returns `null` when the path is unsafe (traversal attempt).
+ */
+export function resolveStaticFile(
+  pathname: string,
+  route: ResolvedStaticRoute,
+): StaticResolution | null {
+  const rel = safeRelativePath(pathname)
+  if (rel === null)
+    return null
+
+  const ext = path.posix.extname(rel)
+
+  // `cleanUrls`: redirect explicit `.html` requests to the clean URL.
+  if (route.cleanUrls && ext === '.html') {
+    const clean = pathname.replace(/\/index\.html$/i, '/').replace(/\.html$/i, '')
+    return { filePath: path.join(route.dir, rel), redirectTo: clean || '/' }
+  }
+
+  // Directory or root request → index.html.
+  if (rel === '' || pathname.endsWith('/'))
+    return { filePath: path.join(route.dir, rel, 'index.html') }
+
+  // Asset with a concrete extension → serve directly.
+  if (ext !== '')
+    return { filePath: path.join(route.dir, rel) }
+
+  // Extensionless route → resolve by SSG style.
+  if (route.pathRewriteStyle === 'flat')
+    return { filePath: path.join(route.dir, `${rel}.html`) }
+  return { filePath: path.join(route.dir, rel, 'index.html') }
+}
+
+/**
+ * Serve a static file for the matched route. Returns a 301 for clean-URL
+ * redirects, the file with the right `Content-Type`/`Cache-Control` when it
+ * exists, the SPA `index.html` fallback when configured, or 404.
+ */
+export async function serveStaticFile(
+  pathname: string,
+  route: ResolvedStaticRoute,
+): Promise<Response> {
+  const resolution = resolveStaticFile(pathname, route)
+  if (!resolution)
+    return new Response('Forbidden', { status: 403 })
+
+  if (resolution.redirectTo)
+    return new Response(null, { status: 301, headers: { Location: resolution.redirectTo } })
+
+  const cacheControl = route.maxAge > 0
+    ? `public, max-age=${route.maxAge}`
+    : 'no-cache'
+
+  const file = Bun.file(resolution.filePath)
+  if (await file.exists()) {
+    return new Response(file, {
+      status: 200,
+      headers: {
+        'Content-Type': contentTypeFor(resolution.filePath),
+        'Cache-Control': cacheControl,
+      },
+    })
+  }
+
+  // SPA fallback: serve the root index.html so client-side routing works.
+  if (route.spa) {
+    const indexPath = path.join(route.dir, 'index.html')
+    const index = Bun.file(indexPath)
+    if (await index.exists()) {
+      return new Response(index, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-cache',
+        },
+      })
+    }
+  }
+
+  return new Response('Not Found', { status: 404 })
+}

package/src/types.ts

@@ -24,11 +24,47 @@ export interface PathRewrite {
   stripPrefix?: boolean
 }
 
+/**
+ * How a static-file route maps request paths to files on disk.
+ *
+ * - `directory` (default): `/about` → `<root>/about/index.html` (SSG dir style).
+ * - `flat`: `/about` → `<root>/about.html` (flat-file style).
+ */
+export type PathRewriteStyle = 'directory' | 'flat'
+
+export interface StaticRouteConfig {
+  /** Absolute path to the directory served for this route. */
+  dir: string
+  /**
+   * Single-page-app fallback: serve `index.html` for any path that doesn't
+   * resolve to a real file (so client-side routing works). Default: `false`.
+   */
+  spa?: boolean
+  /**
+   * Extensionless-URL resolution style for `.html` files. Default: `directory`.
+   */
+  pathRewriteStyle?: PathRewriteStyle
+  /**
+   * `Cache-Control` max-age (seconds) for served files. Default: `0`.
+   */
+  maxAge?: number
+}
+
 export interface BaseProxyConfig {
-  from: string // localhost:5173
+  /**
+   * Upstream `host:port` to forward to (e.g. `localhost:5173`). Optional when
+   * `static` is set (the route serves files from disk instead of proxying).
+   */
+  from?: string // localhost:5173
   to: string // stacks.localhost
   start?: StartOptions
   pathRewrites?: PathRewrite[]
+  /**
+   * Serve a local directory for this route instead of proxying to `from`.
+   * Provide an absolute directory path (shorthand) or a {@link StaticRouteConfig}.
+   * When set, `from` is optional; exactly one of `from`/`static` must be present.
+   */
+  static?: string | StaticRouteConfig
   /**
    * Stable id used when registering this proxy with the rpx daemon. Derived
    * from `to` if omitted. Must match `/^[a-zA-Z0-9._-]+$/` and be ≤128 chars.
@@ -48,6 +84,35 @@ export interface CleanupConfig {
 
 export type CleanupOptions = Partial<CleanupConfig>
 
+/**
+ * A real PEM cert+key pair on disk for one SNI server name.
+ */
+export interface DomainCert {
+  /** Absolute path to the PEM certificate (fullchain). */
+  certPath: string
+  /** Absolute path to the PEM private key. */
+  keyPath: string
+}
+
+/**
+ * Production TLS using real certs (e.g. Let's Encrypt) served per-domain via
+ * SNI on a single listener. Provide either an explicit `domains` map or a
+ * `certsDir` convention.
+ */
+export interface ProductionTlsConfig {
+  /**
+   * Explicit per-domain cert/key files keyed by SNI server name. Use
+   * `*.example.com` for a wildcard server name.
+   */
+  domains?: Record<string, DomainCert>
+  /**
+   * Directory of PEM files following the convention `<domain>.crt` /
+   * `<domain>.key`. A wildcard pair `_wildcard.<apex>.crt` /
+   * `_wildcard.<apex>.key` is registered under server name `*.<apex>`.
+   */
+  certsDir?: string
+}
+
 export interface SharedProxyConfig {
   https: boolean | TlsOption
   cleanup: boolean | CleanupOptions
@@ -64,6 +129,19 @@ export interface SharedProxyConfig {
    * `:443` (Valet-style). Default: `false` for backward compatibility.
    */
   viaDaemon?: boolean
+  /**
+   * Master switch for all `/etc/hosts` reads/writes. Set to `false` on a real
+   * server with real DNS so rpx never touches `/etc/hosts`. When omitted, the
+   * legacy behavior applies (driven by `cleanup.hosts`). `cleanup: { hosts:
+   * false }` also disables hosts management.
+   */
+  hostsManagement?: boolean
+  /**
+   * Production per-domain SNI certs (Let's Encrypt PEMs already on disk). When
+   * provided, the listener serves a different real cert per SNI server name
+   * instead of the dev self-signed shared cert.
+   */
+  productionCerts?: ProductionTlsConfig
 }
 
 export type SharedProxyOptions = Partial<SharedProxyConfig>

package/dist/chunk-kbnzcycw.js

@@ -1 +0,0 @@
-import{$ as j,S as a,T as b,U as c,V as d,W as e,X as f,Y as g,Z as h,_ as i,aa as k,ba as l,ca as m,da as n}from"./chunk-pncxrxde.js";import"./chunk-zs1tyy8z.js";export{l as tearDownDevelopmentDns,k as syncDevelopmentDnsFromRegistry,d as stopDnsServer,c as startDnsServer,h as setupResolver,j as setupDevelopmentDns,f as resolverFilePath,m as removeResolver,i as removeLegacyTldResolvers,n as reconcileStaleDevelopmentDns,e as isDnsServerRunning,g as contentLooksLikeRpxResolver,b as RPX_RESOLVER_MARKER,a as DNS_PORT};