@luckystack/server 0.10.1 → 0.11.0

package/dist/index.d.ts

@@ -1,352 +1,21 @@
-import { IncomingMessage, ServerResponse, Server } from 'node:http';
-import { Server as Server$1 } from 'socket.io';
-import { RuntimeMapsProvider } from '@luckystack/core';
-export { ErrorFormatter, ErrorFormatterContext, getErrorFormatter, registerErrorFormatter } from '@luckystack/core';
-
-/**
- * Module augmentation: extends `@luckystack/core`'s `HookPayloads` interface
- * with socket lifecycle hooks owned by this package. Side-effect imported
- * by `index.ts` so consumers get the augmentation automatically.
- *
- * Hook semantics:
- *   - `on*` hooks are notifications. Handlers may side-effect; return values
- *     are ignored.
- *   - `pre*` hooks may return a `HookStopSignal` to abort the main flow. The
- *     stop signal carries an `errorCode` that's emitted back to the client.
- *   - `post*` hooks fire after the side-effect succeeds.
- */
-interface OnSocketConnectPayload {
-    socketId: string;
-    token: string | null;
-    ip: string;
-}
-interface OnSocketDisconnectPayload {
-    socketId: string;
-    token: string | null;
-    reason: string;
-}
-interface PreRoomJoinPayload {
-    token: string;
-    room: string;
-}
-interface PostRoomJoinPayload {
-    token: string;
-    room: string;
-    allRooms: string[];
-}
-interface PreRoomLeavePayload {
-    token: string;
-    room: string;
-}
-interface PostRoomLeavePayload {
-    token: string;
-    room: string;
-    allRooms: string[];
-}
-interface OnLocationUpdatePayload {
-    token: string;
-    oldLocation: {
-        pathName: string;
-        searchParams?: Record<string, string>;
-    } | undefined;
-    newLocation: {
-        pathName: string;
-        searchParams?: Record<string, string>;
-    };
-}
-declare module '@luckystack/core' {
-    interface HookPayloads {
-        onSocketConnect: OnSocketConnectPayload;
-        onSocketDisconnect: OnSocketDisconnectPayload;
-        preRoomJoin: PreRoomJoinPayload;
-        postRoomJoin: PostRoomJoinPayload;
-        preRoomLeave: PreRoomLeavePayload;
-        postRoomLeave: PostRoomLeavePayload;
-        onLocationUpdate: OnLocationUpdatePayload;
-    }
-}
-
-interface RouteContext {
-    routePath: string;
-    method: string;
-    queryString: string | undefined;
-    token: string | null;
-}
-type StaticFileHandler = (req: IncomingMessage, res: ServerResponse) => unknown;
-type FaviconHandler = (res: ServerResponse) => unknown;
-type CustomRouteHandler = (req: IncomingMessage, res: ServerResponse, ctx: RouteContext) => Promise<boolean> | boolean;
-type CustomRoutePhase = 'pre-params' | 'post-params';
-interface CreateLuckyStackServerOptions {
-    /**
-     * Port the HTTP server listens on. Resolution order:
-     *   1. This option (`options.port`)
-     *   2. Second positional argv (`npm run server -- <bundles> <port>`), parsed
-     *      by `@luckystack/server/parseArgv`
-     *   3. `options.defaultPort` (the project's single-instance default, e.g. the
-     *      `backend` port from `config.ports.ts`)
-     *   4. `80` for generic consumers that supplied no port source
-     */
-    port?: number | string;
-    /**
-     * Project's single-instance default backend port. Sits BELOW positional argv
-     * so a multi-instance boot (`npm run server -- <preset> <port>`) still wins.
-     * The scaffold passes the `backend` value from `config.ports.ts` here, so the
-     * listen port has one static source of truth.
-     */
-    defaultPort?: number;
-    /** Bind address. Defaults to process.env.SERVER_IP or '127.0.0.1'. */
-    ip?: string;
-    /** Project-side static file handler (Vite output, etc.). Used as the catch-all. */
-    serveFile?: StaticFileHandler;
-    /** Project-side favicon handler. */
-    serveFavicon?: FaviconHandler;
-    /**
-     * Optional pre-fallback hook for project-specific HTTP routes. Return `true`
-     * if the route was handled (response ended). Return `false` (or omit return)
-     * to fall through to the framework's static file serving.
-     */
-    customRoutes?: CustomRouteHandler;
-    /**
-     * Enable dev-mode tooling (devkit hot reload, REPL, console init).
-     * Defaults to `resolveRuntimeMode() !== 'production'` (NODE_ENV-based).
-     */
-    enableDevTools?: boolean;
-    /**
-     * Maximum HTTP buffer size for socket.io. Defaults to 5 MB. Adjust if you
-     * stream large payloads through sockets.
-     */
-    maxHttpBufferSize?: number;
-    /** Fail boot if no DeployConfig has been registered. Default: false. */
-    requireDeployConfig?: boolean;
-    /** Fail boot if no ServicesConfig has been registered. Default: false. */
-    requireServicesConfig?: boolean;
-    /** Fail boot if no OAuth providers have been registered. Default: false. */
-    requireOAuthProviders?: boolean;
-    /**
-     * Dynamic-import callback for production runtime maps. When provided, the
-     * framework registers its built-in `RuntimeMapsProvider` and the consumer
-     * no longer needs a hand-rolled `server/prod/runtimeMaps.ts`. Pass a
-     * function that calls `import()` with a path relative to the consumer's
-     * server module — the framework cannot resolve that path on the
-     * consumer's behalf because dynamic-import resolution is module-scoped.
-     *
-     * @example
-     * loadGeneratedMaps: (preset) => import(`./prod/generatedApis.${preset}`)
-     */
-    loadGeneratedMaps?: (preset: string) => Promise<unknown>;
-    /**
-     * Override the preset(s) to load (skips argv lookup). Pass a single preset
-     * name or an array for multi-preset boots. Default: the first positional
-     * argv arg parsed by `@luckystack/server/parseArgv`, falling back to
-     * `'default'`.
-     */
-    runtimeMapsPreset?: string | string[];
-}
-interface StopLuckyStackServerOptions {
-    /**
-     * Why the server is stopping — threaded into the `preServerStop` hook payload.
-     * Defaults to `'manual'` for a programmatic `stop()`; the signal handlers pass
-     * the received signal name.
-     */
-    reason?: 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'manual';
-    /**
-     * Soft budget (ms) for the whole shutdown sequence — the `preServerStop` hook
-     * fan-out, the bounded `flushErrorTrackers()` race, and closing the
-     * http/io/redis-adapter handles. Each step is wrapped so a single hanging step
-     * cannot stall the others past this deadline. Defaults to `10000`.
-     */
-    timeoutMs?: number;
-}
-interface AfterListenOptions {
-    /**
-     * Re-throw instead of swallowing. Use only when the process is genuinely
-     * useless without this task. Default `false` — a listening server survives a
-     * failing post-listen task.
-     */
-    fatal?: boolean;
-    /** Label used in the failure log. Defaults to `post-listen task`. */
-    label?: string;
-}
-interface RunningLuckyStackServer {
-    httpServer: Server;
-    ioServer: Server$1;
-    /**
-     * Start listening. Resolves when the HTTP server is ready. Logs the bound
-     * URL on success.
-     */
-    listen: (callback?: () => void) => Promise<Server>;
-    /**
-     * Run work that belongs AFTER the server is accepting traffic — durable queue
-     * workers, warm-up passes, reconciliation jobs.
-     *
-     * A rejection here is logged loudly and swallowed by default, because the
-     * server is already up: killing a healthy process over one broken dependency
-     * turns an outage into a crash-loop (supervisor restarts, dependency is still
-     * down, repeat). Pass `{ fatal: true }` when the process genuinely has no
-     * purpose without the task — the rejection then propagates to the caller.
-     *
-     * Never resolves to the task's value; it is fire-and-report, not a pipeline
-     * stage. Read what you need inside the callback.
-     */
-    afterListen: (task: () => void | Promise<void>, options?: AfterListenOptions) => Promise<void>;
-    /**
-     * Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the
-     * core `preServerStop` hook, flushes error-trackers (bounded by a timeout
-     * race), and closes the Socket.io server, the HTTP server, and the
-     * Redis-adapter pub/sub clients. Every step is isolated + time-bounded so one
-     * failing/hanging step cannot hang the whole shutdown. Idempotent — a second
-     * call returns the in-flight shutdown promise. Resolves once shutdown
-     * completes (or the timeout forces it to finish).
-     */
-    stop: (options?: StopLuckyStackServerOptions) => Promise<void>;
-    /** Alias of {@link stop} matching the `net.Server`-style `close({ timeoutMs })` API. */
-    close: (options?: StopLuckyStackServerOptions) => Promise<void>;
-}
-
-declare const createLuckyStackServer: (options?: CreateLuckyStackServerOptions) => Promise<RunningLuckyStackServer>;
-
-interface BootstrapLuckyStackOptions extends CreateLuckyStackServerOptions {
-    /**
-     * Folder name (relative to project root) that contains the overlay files.
-     * Default: `luckystack`. Each subfolder mirrors a framework package and
-     * holds the project's overrides for that package.
-     */
-    overlayRoot?: string;
-    /**
-     * Skip auto-loading the overlay folder. Useful for tests that build the
-     * registries by hand.
-     */
-    skipOverlayLoad?: boolean;
-}
-declare const OVERLAY_ORDER: string[];
-type OverlayLoader = () => Promise<void>;
-declare const registerOverlayLoader: (loader: OverlayLoader) => void;
-interface OverlayEntries {
-    /** Files to import, in load order: `index.*` first, then the rest alphabetically. */
-    fileNames: string[];
-    /**
-     * Subdirectories the flat walk skipped, minus conventional test folders.
-     * The caller warns about these — silently dropping them meant overlay code
-     * one level down simply never ran, with nothing to point at.
-     */
-    ignoredDirectoryNames: string[];
-}
-/**
- * Decide what a single overlay package folder contributes. Exported because
- * both the runtime walk here and `scripts/bundleServer.mjs` must agree exactly:
- * a file the bundler includes but the loader skips (or the reverse) is a
- * dev/prod divergence, which is the defect class ADR 0046 exists for.
- */
-declare const collectOverlayEntries: (packageDir: string) => OverlayEntries;
-declare const bootstrapLuckyStack: (options?: BootstrapLuckyStackOptions) => Promise<RunningLuckyStackServer>;
-
-interface BootstrapRequirements {
-    /**
-     * If true, require a deploy config to have been registered. Defaults to
-     * false because single-instance deployments don't need one.
-     */
-    requireDeployConfig?: boolean;
-    /**
-     * If true, require a services config to have been registered. Defaults to
-     * false; only needed when running the router.
-     */
-    requireServicesConfig?: boolean;
-    /**
-     * If true, require an OAuth provider list to have been registered.
-     * Defaults to false (an app may use credentials only).
-     */
-    requireOAuthProviders?: boolean;
-}
-declare const verifyBootstrap: (requirements?: BootstrapRequirements) => Promise<void>;
-
-type RuntimeMapRecord = Record<string, unknown>;
-/**
- * The shape that the generated maps module must export. `scripts/generateServerRequests.ts`
- * emits exactly this shape: `{ apis, syncs, functions }` where each value is a
- * `Record<string, Handler>`. Consumers can import this type to validate their
- * generated file in CI or type-check the `loadGenerated` callback return.
- */
-interface GeneratedRuntimeMapsModule {
-    apis: RuntimeMapRecord;
-    syncs: RuntimeMapRecord;
-    functions: RuntimeMapRecord;
-}
-interface ProdRuntimeMapsLoaderOptions {
-    /**
-     * Dynamic-import callback for the generated maps module of a given preset.
-     * Called once per preset per process lifetime; the result is cached.
-     *
-     * The resolved module must have shape `{ apis, syncs, functions }` (the
-     * shape `scripts/generateServerRequests.ts` emits — see
-     * {@link GeneratedRuntimeMapsModule}). A mis-shaped module logs a warning
-     * and results in every route for that preset returning `notFound`.
-     *
-     * Pass a function that calls `import()` with a path relative to YOUR
-     * server-side module — the framework cannot resolve a relative path on
-     * your behalf because dynamic-import resolution is module-scoped.
-     *
-     * @example
-     * loadGenerated: (preset) => import(`./prod/generatedApis.${preset}`)
-     */
-    loadGenerated: (preset: string) => Promise<unknown>;
-    /**
-     * Override the preset(s) to load. Skips the argv lookup. Accepts a single
-     * preset name or an array. Useful in tests or when the preset list comes
-     * from a non-argv source.
-     */
-    preset?: string | string[];
-}
-declare const createProdRuntimeMapsProvider: (options: ProdRuntimeMapsLoaderOptions) => RuntimeMapsProvider;
-/**
- * Convenience wrapper around `createProdRuntimeMapsProvider` +
- * `registerRuntimeMapsProvider`. Most consumers want this — pass the
- * loader callback once and the runtime is wired.
- */
-declare const registerProdRuntimeMapsProvider: (options: ProdRuntimeMapsLoaderOptions) => RuntimeMapsProvider;
-
-interface ParsedServerArgv {
-    bundles: string[];
-    port: number | null;
-}
-declare const parseServerArgv: (argv: string[]) => ParsedServerArgv;
-declare const applyServerArgv: () => void;
-declare const getParsedBundles: () => string[];
-declare const getParsedPort: () => number | null;
-
-interface RegisterCustomRouteOptions {
-    /** Pipeline phase the handler runs in. Defaults to `'post-params'`. */
-    phase?: CustomRoutePhase;
-}
-declare const registerCustomRoute: (handler: CustomRouteHandler, options?: RegisterCustomRouteOptions) => void;
-declare const getCustomRoutes: () => readonly CustomRouteHandler[];
-declare const getPreParamsCustomRoutes: () => readonly CustomRouteHandler[];
-declare const clearCustomRoutes: () => void;
-
-interface OriginExemptMatcher {
-    /**
-     * A route is exempt when its path equals this prefix OR continues past it on a
-     * path-SEGMENT boundary (i.e. `<prefix>/...`). Matching is boundary-aware so a
-     * prefix can't bleed into a sibling route — `/webhooks` exempts `/webhooks` and
-     * `/webhooks/stripe` but NOT `/webhooksadmin`.
-     */
-    pathPrefix: string;
-}
-declare const registerOriginExemptPath: (matcher: OriginExemptMatcher) => void;
-declare const getOriginExemptPaths: () => readonly OriginExemptMatcher[];
-declare const clearOriginExemptPaths: () => void;
-declare const isOriginExemptPath: (routePath: string) => boolean;
-
-type SecurityHeadersBuilder = (req: IncomingMessage) => Record<string, string> | null | undefined;
-/**
- * Register a custom security-headers builder. Called for every HTTP
- * request; return a plain object that gets merged on top of the framework
- * defaults. Use for Content-Security-Policy, HSTS, Permissions-Policy.
- *
- * Last-write-wins: subsequent calls replace the previous builder. Pass
- * `null` to unregister.
- */
-declare const registerSecurityHeaders: (builder: SecurityHeadersBuilder | null) => void;
-/** Read the active builder (or null). */
-declare const getSecurityHeadersBuilder: () => SecurityHeadersBuilder | null;
-
-export { type AfterListenOptions, type BootstrapLuckyStackOptions, type BootstrapRequirements, type CreateLuckyStackServerOptions, type CustomRouteHandler, type CustomRoutePhase, type FaviconHandler, type GeneratedRuntimeMapsModule, OVERLAY_ORDER, type OnLocationUpdatePayload, type OnSocketConnectPayload, type OnSocketDisconnectPayload, type OriginExemptMatcher, type OverlayEntries, type ParsedServerArgv, type PostRoomJoinPayload, type PostRoomLeavePayload, type PreRoomJoinPayload, type PreRoomLeavePayload, type ProdRuntimeMapsLoaderOptions, type RegisterCustomRouteOptions, type RouteContext, type RunningLuckyStackServer, type SecurityHeadersBuilder, type StaticFileHandler, type StopLuckyStackServerOptions, applyServerArgv, bootstrapLuckyStack, clearCustomRoutes, clearOriginExemptPaths, collectOverlayEntries, createLuckyStackServer, createProdRuntimeMapsProvider, getCustomRoutes, getOriginExemptPaths, getParsedBundles, getParsedPort, getPreParamsCustomRoutes, getSecurityHeadersBuilder, isOriginExemptPath, parseServerArgv, registerCustomRoute, registerOriginExemptPath, registerOverlayLoader, registerProdRuntimeMapsProvider, registerSecurityHeaders, verifyBootstrap };
+import './hookPayloads.js';
+export { createLuckyStackServer } from './createServer.js';
+export type { OnSocketConnectPayload, OnSocketDisconnectPayload, PreRoomJoinPayload, PostRoomJoinPayload, PreRoomLeavePayload, PostRoomLeavePayload, OnLocationUpdatePayload, } from './hookPayloads.js';
+export { bootstrapLuckyStack, registerOverlayLoader, OVERLAY_ORDER, collectOverlayEntries } from './bootstrap.js';
+export type { OverlayEntries } from './bootstrap.js';
+export type { BootstrapLuckyStackOptions } from './bootstrap.js';
+export { verifyBootstrap } from './verifyBootstrap.js';
+export type { BootstrapRequirements } from './verifyBootstrap.js';
+export { createProdRuntimeMapsProvider, registerProdRuntimeMapsProvider, } from './runtimeMapsLoader.js';
+export type { ProdRuntimeMapsLoaderOptions, GeneratedRuntimeMapsModule } from './runtimeMapsLoader.js';
+export { applyServerArgv, parseServerArgv, getParsedBundles, getParsedPort, } from './argv.js';
+export type { ParsedServerArgv } from './argv.js';
+export { registerCustomRoute, getCustomRoutes, getPreParamsCustomRoutes, clearCustomRoutes, } from './customRoutesRegistry.js';
+export type { RegisterCustomRouteOptions } from './customRoutesRegistry.js';
+export { registerOriginExemptPath, getOriginExemptPaths, clearOriginExemptPaths, isOriginExemptPath, } from './originExemptRegistry.js';
+export type { OriginExemptMatcher } from './originExemptRegistry.js';
+export { registerSecurityHeaders, getSecurityHeadersBuilder, } from './securityHeadersRegistry.js';
+export type { SecurityHeadersBuilder } from './securityHeadersRegistry.js';
+export { registerErrorFormatter, getErrorFormatter, } from './errorFormatterRegistry.js';
+export type { ErrorFormatter, ErrorFormatterContext } from './errorFormatterRegistry.js';
+export type { AfterListenOptions, CreateLuckyStackServerOptions, RunningLuckyStackServer, StopLuckyStackServerOptions, RouteContext, StaticFileHandler, FaviconHandler, CustomRouteHandler, CustomRoutePhase, } from './types.js';

package/dist/index.js

@@ -391,9 +391,12 @@ import {
   clearAllRateLimits,
   getProjectConfig as getProjectConfig4,
   formatKey,
+  isTestResetTarget,
   redis as redis2,
+  TEST_RESET_ONLY_PARAM,
   tryCatch as tryCatch2
 } from "@luckystack/core";
+var splitList = (value) => (value ?? "").split(",").map((s) => s.trim()).filter(Boolean);
 var handleTestResetRoute = async ({ req, res, routePath }) => {
   if (routePath !== getProjectConfig4().http.testResetEndpoint) return false;
   const nodeEnv = process.env.NODE_ENV;
@@ -419,9 +422,33 @@ var handleTestResetRoute = async ({ req, res, routePath }) => {
     res.end(JSON.stringify({ status: "error", errorCode: "auth.forbidden" }));
     return true;
   }
+  const rawUrl = req.url ?? "/";
+  const searchParams = URL.canParse(rawUrl, "http://localhost") ? new URL(rawUrl, "http://localhost").searchParams : new URLSearchParams();
+  const onlyParam = searchParams.get(TEST_RESET_ONLY_PARAM);
+  let targets;
+  if (onlyParam === null) {
+    targets = /* @__PURE__ */ new Set(["rateLimits", "sessions", "activeUsers"]);
+    if (splitList(searchParams.get("include")).includes("hooks")) targets.add("hooks");
+  } else {
+    const requested = splitList(onlyParam);
+    const unknown = requested.filter((target) => !isTestResetTarget(target));
+    if (requested.length === 0 || unknown.length > 0) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({
+        status: "error",
+        errorCode: "test.invalidResetTarget",
+        errorParams: [{ key: "target", value: unknown.join(",") || "(empty)" }]
+      }));
+      return true;
+    }
+    targets = new Set(requested.filter(isTestResetTarget));
+  }
   const cleared = [];
-  await clearAllRateLimits();
-  cleared.push("rateLimits");
+  if (targets.has("rateLimits")) {
+    await clearAllRateLimits();
+    cleared.push("rateLimits");
+  }
   const sessionPattern = `${formatKey("-session", "")}:*`;
   const activeUsersPattern = `${formatKey("-activeUsers", "")}:*`;
   const scanAndDelete = async (pattern, label) => {
@@ -442,11 +469,9 @@ var handleTestResetRoute = async ({ req, res, routePath }) => {
     if (deleted > 0) cleared.push(label);
     return deleted;
   };
-  await scanAndDelete(sessionPattern, "sessions");
-  await scanAndDelete(activeUsersPattern, "activeUsers");
-  const rawUrl = req.url ?? "/";
-  const includeFlag = URL.canParse(rawUrl, "http://localhost") ? new URL(rawUrl, "http://localhost").searchParams.get("include") ?? "" : "";
-  if (includeFlag.split(",").map((s) => s.trim()).includes("hooks")) {
+  if (targets.has("sessions")) await scanAndDelete(sessionPattern, "sessions");
+  if (targets.has("activeUsers")) await scanAndDelete(activeUsersPattern, "activeUsers");
+  if (targets.has("hooks")) {
     clearAllHooks();
     cleared.push("hooks");
   }