@stacksjs/rpx 0.11.20 → 0.11.22

package/dist/site-supervisor.d.ts

@@ -0,0 +1,56 @@
+import type { RegistryEntry } from './registry';
+import type { SiteResolver } from './site-resolver';
+/** A launched site process, abstracted so tests can inject a fake. */
+export declare interface SiteProcessHandle {
+  pid: number
+  exited: Promise<number | null>
+  stop: (signal?: NodeJS.Signals) => void
+}
+/** A point-in-time view of one supervised site, for `rpx sites` / status. */
+export declare interface SiteSnapshot {
+  host: string
+  dir: string
+  status: 'starting' | 'ready' | 'failed'
+  pid: number | null
+  ports: Record<string, number>
+  uptimeMs: number
+  idleMs: number
+  error?: string
+}
+export declare interface SiteSupervisorOptions {
+  resolver: SiteResolver
+  registryDir?: string
+  rpxDir?: string
+  verbose?: boolean
+  startupTimeoutMs?: number
+  pollIntervalMs?: number
+  reapIntervalMs?: number
+  restartDelayMs?: number
+  killGraceMs?: number
+  launcher?: SiteLauncher
+  probePort?: (port: number) => Promise<boolean>
+  pickPort?: (preferred: number) => Promise<number>
+  isHostRoutable?: (host: string) => boolean
+  onSiteActivating?: (host: string) => void
+  now?: () => number
+  writeEntry?: (entry: RegistryEntry, dir?: string, verbose?: boolean) => Promise<void>
+  removeEntry?: (id: string, dir?: string, verbose?: boolean) => Promise<void>
+}
+/** Spawn a site's dev command. Injected for tests; default spawns a shell. */
+export type SiteLauncher = (spec: {
+  command: string
+  cwd: string
+  env: Record<string, string>
+  logPath: string
+}) => SiteProcessHandle;
+export type SiteRequestStatus = | { kind: 'unknown' }
+  | { kind: 'starting', host: string, sinceMs: number, source: 'config' | 'discovered', logTail: string }
+  | { kind: 'ready', host: string }
+  | { kind: 'failed', host: string, error: string, logTail: string }
+export declare class SiteSupervisor {
+  constructor(opts: SiteSupervisorOptions);
+  onRequest(host: string): Promise<SiteRequestStatus>;
+  stop(host: string): Promise<void>;
+  list(): SiteSnapshot[];
+  stopAll(): Promise<void>;
+}

package/dist/start.d.ts

@@ -6,7 +6,7 @@ import type { SniTlsEntry } from './sni';
 export declare function cleanup(options?: CleanupOptions): Promise<void>;
 export declare function startServer(options: SingleProxyConfig): Promise<void>;
 export declare function setupProxy(options: ProxySetupOptions): Promise<void>;
-export declare function startHttpRedirectServer(verbose?: boolean, httpPort?: number, httpsPort?: number): void;
+export declare function startHttpRedirectServer(verbose?: boolean, httpPort?: number, httpsPort?: number, acmeChallengeWebroot?: string): void;
 export declare function startProxy(options: ProxyOption): void;
 export declare function startProxies(options?: ProxyOptions): Promise<void>;
 /**

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { OriginGuardOptions } from './origin-guard';
+import type { RedirectRouteConfig } from './redirect';
 import type { TlsConfig, TlsOption } from '@stacksjs/tlsx';
 export type { TlsConfig, TlsOption };
 export declare interface StartOptions {
@@ -17,13 +18,28 @@ export declare interface StaticRouteConfig {
   pathRewriteStyle?: PathRewriteStyle
   maxAge?: number
 }
+/**
+ * HTTP Basic auth for a single route. When set, rpx challenges every request to
+ * the route with `401`/`WWW-Authenticate` until valid credentials are supplied
+ * (proxy, static, and WebSocket transports are all gated). Credentials may be
+ * given inline, as a `users[]` list, and/or via an Apache `htpasswd` file.
+ */
+export declare interface BasicAuthConfig {
+  realm?: string
+  username?: string
+  password?: string
+  users?: Array<{ username: string, password: string }>
+  htpasswdFile?: string
+}
 export declare interface BaseProxyConfig {
   from?: string
   to: string
+  auth?: BasicAuthConfig
   path?: string
   start?: StartOptions
   pathRewrites?: PathRewrite[]
   static?: string | StaticRouteConfig
+  redirect?: string | RedirectRouteConfig
   id?: string
 }
 export declare interface CleanupConfig {
@@ -79,6 +95,49 @@ export declare interface OnDemandTlsConfig {
   staging?: boolean
   certsDir?: string
 }
+/**
+ * One backend a site exposes, mapped to a request path. rpx picks a free port,
+ * exports it to the dev command via {@link portEnv}, and proxies {@link path}
+ * (under the site host) to `localhost:<port>`.
+ *
+ * A Stacks app, for example, has three: the frontend at `/` (env `PORT`), the
+ * API at `/api` (env `PORT_API`), and the docs at `/docs` (env `PORT_DOCS`).
+ */
+export declare interface SiteRouteTemplate {
+  path?: string
+  portEnv: string
+  defaultPort?: number
+  stripPrefix?: boolean
+  readyGate?: boolean
+}
+/**
+ * A lazily-booted project. The first request to {@link to} starts {@link command}
+ * in {@link dir}; rpx holds the request behind a "starting…" splash until the
+ * site's ready gate passes, then proxies it. After {@link idleTimeoutMs} with no
+ * traffic the process is stopped again — so a machine can "have" dozens of sites
+ * but only run the ones in active use.
+ */
+export declare interface SiteConfig {
+  to: string
+  dir: string
+  command: string
+  env?: Record<string, string>
+  routes?: SiteRouteTemplate[]
+  selfRegisters?: boolean
+  idleTimeoutMs?: number
+}
+/**
+ * On-demand sites: lazily boot a project's dev server the first time its host is
+ * visited, then proxy to it (Valet/puma-dev style). Opt-in via {@link enabled}.
+ */
+export declare interface OnDemandSitesConfig {
+  enabled?: boolean
+  sites?: SiteConfig[]
+  roots?: string[]
+  tlds?: string[]
+  idleTimeoutMs?: number
+  startupTimeoutMs?: number
+}
 export declare interface SharedProxyConfig {
   https: boolean | TlsOption
   cleanup: boolean | CleanupOptions
@@ -92,10 +151,12 @@ export declare interface SharedProxyConfig {
   singlePortMode?: boolean
   httpPort?: number
   httpsPort?: number
+  acmeChallengeWebroot?: string
   viaDaemon?: boolean
   hostsManagement?: boolean
   productionCerts?: ProductionTlsConfig
   onDemandTls?: OnDemandTlsConfig
+  onDemand?: OnDemandSitesConfig
   originGuard?: OriginGuardOptions
 }
 export declare interface SingleProxyConfig extends BaseProxyConfig, SharedProxyConfig {}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/rpx",
   "type": "module",
-  "version": "0.11.20",
+  "version": "0.11.22",
   "description": "A modern and smart reverse proxy.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",