@molecule/api-server-default-express 1.0.3 → 1.0.4

package/README.md

@@ -3,15 +3,11 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-06T05:03:58.023Z
+Generated: 2026-10-16T23:31:50.537Z
 -->
 
 # @molecule/api-server-default-express
 
-> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
-> It is written to be read by coding agents as much as by people, and is generated from this
-> package's source — edit `src/index.ts` JSDoc, not this file.
-
 `@molecule/api-server-default-express` — drop-in Express server
 factory used by the molecule fleet's `api/src/server.ts`.
 
@@ -20,6 +16,10 @@ returns a `(port?) => Promise<server>` function that runs
 migrations, wires bonds, mounts router + middleware, and starts
 an HTTP (or self-signed HTTPS for local dev) listener.
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 ```ts
@@ -58,6 +58,21 @@ npm install -D @types/express
 
 ### Interfaces
 
+#### `TaggedError`
+
+A deliberately-tagged molecule error mapped to a real HTTP status by the API.
+
+```typescript
+interface TaggedError {
+  /** HTTP status to return (e.g. 503 for a missing provider config). */
+  statusCode: number
+  /** Machine-readable key the app/IDE maps to a friendly message. */
+  errorKey: string
+  /** Human-readable message. */
+  message: string
+}
+```
+
 #### `CreateServerOptions`
 
 Options for `createServerFactory`.
@@ -96,21 +111,6 @@ interface CreateServerOptions {
 }
 ```
 
-#### `TaggedError`
-
-A deliberately-tagged molecule error mapped to a real HTTP status by the API.
-
-```typescript
-interface TaggedError {
-  /** HTTP status to return (e.g. 503 for a missing provider config). */
-  statusCode: number
-  /** Machine-readable key the app/IDE maps to a friendly message. */
-  errorKey: string
-  /** Human-readable message. */
-  message: string
-}
-```
-
 ### Functions
 
 #### `classifyTaggedError(error)`
@@ -135,30 +135,6 @@ function classifyTaggedError(error: unknown): TaggedError | null
 
 **Returns:** The classified tagged error, or `null` if it isn't a molecule-tagged error.
 
-#### `createServerFactory(opts)`
-
-Returns an Express server-creation function bound to the given
-setupBonds / runMigrations / router loaders. The returned `create`
-builds the canonical molecule fleet server:
-
-- Migrations run first, then bonds, then router import.
-- Global browser-security headers ({@link securityHeadersMiddleware})
-  applied before any router (anti-clickjacking + nosniff + referrer baseline).
-- `bodyParser` / `cookieParser` / `cors` middleware applied.
-- Router mounted at `/api`.
-- `/health` endpoint with `{ status: 'ok', timestamp }`.
-- Bare-string `Unauthorized` / `Unauthorized.` errors normalized to 401.
-- HTTPS in dev if `process.env.HTTPS` is set, using self-signed
-  certs from optional dependency `pem`.
-- `process.on('uncaughtException')` + `unhandledRejection` registered
-  on first call (idempotent across multiple `create()` invocations).
-
-```typescript
-function createServerFactory(
-  opts: CreateServerOptions,
-): (port?: number) => Promise<express.Express | https.Server>
-```
-
 #### `errorMiddleware(error, req, res, _next)`
 
 Terminal Express error middleware for the canonical molecule fleet server.
@@ -185,8 +161,8 @@ depend on `NODE_ENV`. Calling `next(error)` here would fall through to Express's
 `finalhandler`, which embeds `err.stack` in the HTTP response body whenever
 `app.get('env') !== 'production'` (the default when `NODE_ENV` is unset or
 `development`), disclosing absolute server paths, module layout, dependency
-versions, and query/data fragments. Returning the opaque 500 unconditionally
-removes that leak for every flagship app regardless of how it is deployed.
+
+_(description truncated — read the full text in `node_modules/@molecule/api-server-default-express/dist/server.d.ts`.)_
 
 ```typescript
 function errorMiddleware(
@@ -248,6 +224,30 @@ function securityHeadersMiddleware(
 - `res` — The response to set headers on.
 - `next` — Express next.
 
+#### `createServerFactory(opts)`
+
+Returns an Express server-creation function bound to the given
+setupBonds / runMigrations / router loaders. The returned `create`
+builds the canonical molecule fleet server:
+
+- Migrations run first, then bonds, then router import.
+- Global browser-security headers ({@link securityHeadersMiddleware})
+  applied before any router (anti-clickjacking + nosniff + referrer baseline).
+- `bodyParser` / `cookieParser` / `cors` middleware applied.
+- Router mounted at `/api`.
+- `/health` endpoint with `{ status: 'ok', timestamp }`.
+- Bare-string `Unauthorized` / `Unauthorized.` errors normalized to 401.
+- HTTPS in dev if `process.env.HTTPS` is set, using self-signed
+  certs from optional dependency `pem`.
+- `process.on('uncaughtException')` + `unhandledRejection` registered
+  on first call (idempotent across multiple `create()` invocations).
+
+```typescript
+function createServerFactory(
+  opts: CreateServerOptions,
+): (port?: number) => Promise<express.Express | https.Server>
+```
+
 ## Injection Notes
 
 ### Requirements

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,MAAM,YAAY,CAAA;AAI9B,OAAO,OAAO,MAAM,SAAS,CAAA;AAS7B,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAetE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,mBA6CrC,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC9D;AAYD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACjE,IAAI,CAEN;AAYD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,CAAC,cAU/C,CAAA;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,mBAAmB,GACxB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAuG5D"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,MAAM,YAAY,CAAA;AAI9B,OAAO,OAAO,MAAM,SAAS,CAAA;AAS7B,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAetE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,mBA6CrC,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC9D;AAYD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACjE,IAAI,CAEN;AAYD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,CAAC,cAU/C,CAAA;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,mBAAmB,GACxB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAqH5D"}

package/dist/server.js

@@ -288,6 +288,19 @@ export function createServerFactory(opts) {
         const httpServer = process.env.HTTPS
             ? server
             : http.createServer(app);
+        // Outlive every connection pool that sits in front of this server. Node's
+        // default keepAliveTimeout is 5000 ms — exactly what Node's global http
+        // agent (what a proxy's `http.request` uses with no agent given) keeps an
+        // idle socket for. With both sides on the same 5 s timer, an idle
+        // connection is closed by the server at the very moment a proxy reuses it,
+        // and that one request is lost (measured against the platform front: a
+        // dropped reuse answers it a fast ECONNRESET, which costs a retry). A
+        // server-side timeout well above the client's makes the CLIENT always let
+        // go first, so a reuse can never land on a socket the server is closing.
+        // `headersTimeout` must stay greater than `keepAliveTimeout` (Node throws
+        // on boot otherwise).
+        httpServer.keepAliveTimeout = 65_000;
+        httpServer.headersTimeout = 66_000;
         await runServerCreatedHooks(httpServer);
         httpServer.listen(port, () => {
             logger.info(`Started ${process.env.NODE_ENV} ${process.env.HTTPS ? 'HTTPS' : 'HTTP'} server on port ${port}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-server-default-express",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Default Express server factory: bonds setup, DB migrations, body/cookie/cors middleware, /api router mount, /health endpoint, 401 normalization, optional HTTPS via self-signed pem certs. Extracts 80-line server.ts shipped by 79 fleet apps.",
   "homepage": "https://www.molecule.dev/packages/api-server-default-express",
   "type": "module",