express-file-cluster 0.10.2 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/auth/index.cjs +8 -7
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +3 -1
- package/dist/auth/index.d.ts +3 -1
- package/dist/auth/index.js +7 -5
- package/dist/{chunk-BG4A7Z32.js → chunk-3JQWQF2M.js} +3 -3
- package/dist/{chunk-4GHK27JA.cjs → chunk-4FQP6QX3.cjs} +3 -3
- package/dist/{chunk-4GHK27JA.cjs.map → chunk-4FQP6QX3.cjs.map} +1 -1
- package/dist/chunk-546TNO2V.js +226 -0
- package/dist/chunk-546TNO2V.js.map +1 -0
- package/dist/{chunk-MUVO7MGS.js → chunk-74R37C4I.js} +48 -21
- package/dist/chunk-74R37C4I.js.map +1 -0
- package/dist/{chunk-H2PVWCWC.cjs → chunk-A2QGDWCG.cjs} +15 -8
- package/dist/chunk-A2QGDWCG.cjs.map +1 -0
- package/dist/{chunk-5LPRKZPB.js → chunk-BCSJOPYH.js} +2 -2
- package/dist/chunk-BJR42CN3.cjs +872 -0
- package/dist/chunk-BJR42CN3.cjs.map +1 -0
- package/dist/{chunk-C2FOZ7ME.js → chunk-EBJELA7T.js} +30 -25
- package/dist/chunk-EBJELA7T.js.map +1 -0
- package/dist/{chunk-Y4NKIXUL.cjs → chunk-H6MHRHUP.cjs} +104 -50
- package/dist/chunk-H6MHRHUP.cjs.map +1 -0
- package/dist/{chunk-7BC3AN7R.cjs → chunk-IG3V2IOK.cjs} +57 -30
- package/dist/chunk-IG3V2IOK.cjs.map +1 -0
- package/dist/chunk-JAPZYQVJ.cjs +143 -0
- package/dist/chunk-JAPZYQVJ.cjs.map +1 -0
- package/dist/{chunk-JP36TLL4.cjs → chunk-JHCXIYJH.cjs} +25 -47
- package/dist/chunk-JHCXIYJH.cjs.map +1 -0
- package/dist/{chunk-IUZ6A7PB.cjs → chunk-JVB5NLEM.cjs} +15 -13
- package/dist/chunk-JVB5NLEM.cjs.map +1 -0
- package/dist/chunk-LIAGVWFQ.js +872 -0
- package/dist/chunk-LIAGVWFQ.js.map +1 -0
- package/dist/chunk-PUM5ZDAH.js +140 -0
- package/dist/chunk-PUM5ZDAH.js.map +1 -0
- package/dist/{chunk-CGY7JU4Y.cjs → chunk-PUYBKDYD.cjs} +11 -2
- package/dist/chunk-PUYBKDYD.cjs.map +1 -0
- package/dist/{chunk-RETV3GKE.js → chunk-QLM3JEER.js} +5 -3
- package/dist/{chunk-RETV3GKE.js.map → chunk-QLM3JEER.js.map} +1 -1
- package/dist/{chunk-R2K7AFIB.cjs → chunk-SV4C4HWP.cjs} +89 -89
- package/dist/{chunk-R2K7AFIB.cjs.map → chunk-SV4C4HWP.cjs.map} +1 -1
- package/dist/{chunk-V73R76I4.js → chunk-UJ2ISRLP.js} +11 -33
- package/dist/chunk-UJ2ISRLP.js.map +1 -0
- package/dist/chunk-URKE3OXN.cjs +226 -0
- package/dist/chunk-URKE3OXN.cjs.map +1 -0
- package/dist/{chunk-TBIVIR6L.cjs → chunk-VLGN3XUM.cjs} +40 -35
- package/dist/chunk-VLGN3XUM.cjs.map +1 -0
- package/dist/{chunk-Y75V5FCU.js → chunk-X2B7WBKH.js} +88 -34
- package/dist/chunk-X2B7WBKH.js.map +1 -0
- package/dist/chunk-Y7I2633P.js +12 -0
- package/dist/chunk-Y7I2633P.js.map +1 -0
- package/dist/{chunk-B6MB6HEG.js → chunk-ZBQUYFI3.js} +14 -7
- package/dist/chunk-ZBQUYFI3.js.map +1 -0
- package/dist/cli/db-runner.cjs +26 -25
- package/dist/cli/db-runner.cjs.map +1 -1
- package/dist/cli/db-runner.js +5 -3
- package/dist/cli/db-runner.js.map +1 -1
- package/dist/cli/index.cjs +16 -15
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +9 -7
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +2 -0
- package/dist/docs/api-reference/ignite.md +6 -0
- package/dist/docs/api-reference/openapi.md +36 -0
- package/dist/docs/api-reference/tasks.md +5 -1
- package/dist/docs/api-reference/testing.md +4 -0
- package/dist/docs/api-reference/tracing.md +18 -0
- package/dist/docs/api-reference/websockets.md +23 -0
- package/dist/docs/cli/add.md +1 -1
- package/dist/docs/core-concepts/background-tasks.md +5 -1
- package/dist/docs/core-concepts/clustering.md +2 -0
- package/dist/docs/core-concepts/file-based-routing.md +4 -0
- package/dist/docs/core-concepts/middleware.md +2 -0
- package/dist/docs/guides/caching.md +12 -0
- package/dist/docs/guides/error-handling.md +2 -0
- package/dist/docs/guides/feature-matrix.md +16 -0
- package/dist/docs/guides/logging.md +2 -0
- package/dist/docs/guides/openapi.md +57 -0
- package/dist/docs/guides/tracing.md +64 -0
- package/dist/docs/guides/validation.md +2 -0
- package/dist/docs/guides/websockets.md +60 -0
- package/dist/docs/index.md +4 -1
- package/dist/docs/skills/SKILL.md +7 -3
- package/dist/docs/skills/api-surface.md +18 -0
- package/dist/docs/skills/auth-internals.md +4 -2
- package/dist/docs/skills/pre-flight.md +6 -0
- package/dist/docs/skills/routing-rules.md +6 -0
- package/dist/docs/skills/tasks-internals.md +10 -2
- package/dist/docs/skills/what-not-to-invent.md +4 -0
- package/dist/index.cjs +185 -70
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +6 -14
- package/dist/index.d.ts +6 -14
- package/dist/index.js +143 -28
- package/dist/index.js.map +1 -1
- package/dist/openapi-cjs.cjs +5 -0
- package/dist/pgboss-backend-5DXF4G22.js +16 -0
- package/dist/pgboss-backend-KRTFHRNZ.cjs +16 -0
- package/dist/pgboss-backend-KRTFHRNZ.cjs.map +1 -0
- package/dist/registry/index.json +1 -1
- package/dist/tasks/index.cjs +3 -3
- package/dist/tasks/index.d.cts +4 -2
- package/dist/tasks/index.d.ts +4 -2
- package/dist/tasks/index.js +2 -1
- package/dist/testing.cjs +21 -13
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +5 -1
- package/dist/testing.d.ts +5 -1
- package/dist/testing.js +17 -8
- package/dist/testing.js.map +1 -1
- package/dist/thread-runner.cjs +5 -4
- package/dist/thread-runner.cjs.map +1 -1
- package/dist/thread-runner.d.cts +1 -1
- package/dist/thread-runner.d.ts +1 -1
- package/dist/thread-runner.js +4 -2
- package/dist/{types-CPMFTVXm.d.ts → types-Bgeqpm-n.d.cts} +91 -2
- package/dist/{types-CPMFTVXm.d.cts → types-Bgeqpm-n.d.ts} +91 -2
- package/package.json +11 -5
- package/dist/chunk-3SWI46YK.js +0 -74
- package/dist/chunk-3SWI46YK.js.map +0 -1
- package/dist/chunk-74BSJXWD.cjs +0 -220
- package/dist/chunk-74BSJXWD.cjs.map +0 -1
- package/dist/chunk-7BC3AN7R.cjs.map +0 -1
- package/dist/chunk-B6MB6HEG.js.map +0 -1
- package/dist/chunk-C2FOZ7ME.js.map +0 -1
- package/dist/chunk-CGY7JU4Y.cjs.map +0 -1
- package/dist/chunk-H2PVWCWC.cjs.map +0 -1
- package/dist/chunk-IUZ6A7PB.cjs.map +0 -1
- package/dist/chunk-JP36TLL4.cjs.map +0 -1
- package/dist/chunk-KLWL7XSC.js +0 -220
- package/dist/chunk-KLWL7XSC.js.map +0 -1
- package/dist/chunk-MUVO7MGS.js.map +0 -1
- package/dist/chunk-RPL2IFWK.cjs +0 -77
- package/dist/chunk-RPL2IFWK.cjs.map +0 -1
- package/dist/chunk-TBIVIR6L.cjs.map +0 -1
- package/dist/chunk-V73R76I4.js.map +0 -1
- package/dist/chunk-Y4NKIXUL.cjs.map +0 -1
- package/dist/chunk-Y75V5FCU.js.map +0 -1
- package/dist/pgboss-backend-4X2YT4RB.js +0 -14
- package/dist/pgboss-backend-UXQ3O2WT.cjs +0 -15
- package/dist/pgboss-backend-UXQ3O2WT.cjs.map +0 -1
- /package/dist/{chunk-BG4A7Z32.js.map → chunk-3JQWQF2M.js.map} +0 -0
- /package/dist/{chunk-5LPRKZPB.js.map → chunk-BCSJOPYH.js.map} +0 -0
- /package/dist/{pgboss-backend-4X2YT4RB.js.map → pgboss-backend-5DXF4G22.js.map} +0 -0
|
@@ -290,3 +290,5 @@ Device-session `/auth/sessions` (GET) and `/auth/sessions/:id` (DELETE) remain a
|
|
|
290
290
|
Generated User/Admin logout requires authentication, compare-and-sets the account's stored refresh token to empty (including bearer logout with no refresh cookie/body), then revokes the current access token and clears cookies. Login persists refresh credentials only while the password hash still matches its verified snapshot. Generated login/refresh tokens carry `efc_auth_at`, captured before credential reads; revocation rejects a token whose authentication started at or before the cutoff, even if it was signed afterwards. Custom token issuers may include this numeric epoch-millisecond claim for the same protection; it can only restrict access, never override a later server-issued time. Existing generated apps must update their owned auth routes as well as the framework to receive these fixes.
|
|
291
291
|
|
|
292
292
|
Password reset atomically consumes the matching, still-unexpired reset token while replacing the password and clearing stored refresh credentials and pending 2FA challenges. Concurrent use has one winner; expiry is rechecked in the database after hashing. Active 2FA enrollment remains enabled. Password changes also invalidate outstanding reset links. Custom auth-entity logout propagates revocation-store failures instead of returning a false success. Existing apps must update their owned reset-password, change-password, two-factor helper and custom logout files.
|
|
293
|
+
|
|
294
|
+
Since 0.12.0 hardening: cookie-clearing helpers use the configured cookie domain. Authentication stops if a timeout/disconnect already ended the response. Per-user revocation cutoffs persist without a TTL so shorter future token settings cannot revive older sessions. Memory cache protects revocation entries from LRU eviction and rejects new revocation writes if all slots are protected; use durable, no-eviction Redis for production persistence. Explicit session-key clearing or a volatile store restart removes revocation state.
|
|
@@ -365,3 +365,9 @@ ignite({ port: 3000 })
|
|
|
365
365
|
On a worker, the signal closes the HTTP server (in-flight requests finish), drains running task jobs, then exits. On the cluster primary it relays `SIGTERM` to every worker — so `docker stop` / Kubernetes, which signal only PID 1, still shut down gracefully — and force-exits after `timeoutMs + 2s` if a worker hangs. Repeated signals are ignored rather than killing a worker mid-drain.
|
|
366
366
|
|
|
367
367
|
`logging.queries.metrics: true | { maxEntries?: number }` enables bounded per-process query counters and latency summaries (default off; enabled default limit 1000). Read/reset through `getQueryMetrics` / `resetQueryMetrics` from the main package; see [query metrics](../guides/logging.md#query-metrics).
|
|
368
|
+
|
|
369
|
+
## Since 0.11.0: OpenAPI and WebSockets
|
|
370
|
+
|
|
371
|
+
`openapi?: boolean | OpenAPIOptions` opts into `/openapi.json` (or `path`) with route-derived OpenAPI 3.1 JSON. `websocket?: false | WebSocketOptions` configures file `WS` upgrades; they attach automatically when exported, unless disabled. Both features share global middleware. See [OpenAPI](./openapi.md) and [WebSockets](./websockets.md) for exact options and lifecycle.
|
|
372
|
+
|
|
373
|
+
Since 0.12.0: opt-in OpenTelemetry instrumentation uses `tracing: true | TracingOptions`; the app owns its SDK and exporter. See [tracing](../guides/tracing.md) for HTTP/task propagation, trace log fields, thread behavior and shutdown ownership.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# OpenAPI API (since 0.11.0)
|
|
2
|
+
|
|
3
|
+
Exported from `express-file-cluster`:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
generateOpenAPI(
|
|
7
|
+
routes: MountedRoute[] | string, // explicit API directory or already loaded metadata
|
|
8
|
+
options?: OpenAPIOptions & { basePath?: string },
|
|
9
|
+
): Promise<OpenAPIDocument>
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`OpenAPIDocument` contains `openapi: '3.1.0'`, `info`, `paths`, `components.schemas`, and optional `servers`. A directory argument scans/imports route files. A loaded-route argument uses existing metadata. Generation uses HTTP methods, metadata and request schemas. It does not change validation or execute handlers.
|
|
13
|
+
|
|
14
|
+
`ignite({ openapi: true | OpenAPIOptions })` and `createTestApp({ openapi: true | OpenAPIOptions })` generate once and serve the document. Default: disabled.
|
|
15
|
+
|
|
16
|
+
| Option | Default | Purpose |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| `path?: string` | `/openapi.json` | Absolute static document URL; reserved before API routes. |
|
|
19
|
+
| `info?: { title; version; description? }` | project package metadata in ignite; EFC API/1.0.0 in standalone/testing | Required OpenAPI info. |
|
|
20
|
+
| `servers?: { url; description? }[]` | omitted | Deployment URLs. |
|
|
21
|
+
| `components?: Record<string, unknown>` | generated schemas | Explicit components such as security schemes; generated component names avoid collisions. |
|
|
22
|
+
| `schemaToJSONSchema?: (validator: Validator) => JSONSchema \| Promise<JSONSchema>` | Standard JSON Schema input conversion | Adapter for validators without the standard JSON Schema protocol. |
|
|
23
|
+
|
|
24
|
+
`JSONSchema = boolean | Record<string, unknown>`. `RouteMethodMeta` adds `summary`, `tags`, `operationId`, and `openapi: Record<string, unknown> & { hidden?: boolean }`. The explicit operation fields override generated defaults; author-supplied OpenAPI objects must be valid. Only `hidden` is stripped. IDs are normalized for optional path expansions and duplicates are rejected.
|
|
25
|
+
|
|
26
|
+
See [the guide](../guides/openapi.md) for conversion, security and catch-all semantics.
|
|
27
|
+
|
|
28
|
+
The CommonJS generator delegates asynchronously to the ESM implementation, preserving native ESM route imports (including top-level await). It has the same Promise return type in both formats.
|
|
29
|
+
|
|
30
|
+
Document URL collisions are checked against actual GET/HEAD route matchers before hidden operations are filtered. Equivalent optional path variants are collapsed using the first parameter binding; ambiguous templates across routes throw.
|
|
31
|
+
|
|
32
|
+
Query/params object combinators are expanded into parameter fields. Unions retain branch-specific fields as optional and require only fields required by every branch; intersections combine requirements. `x-efc-query-schema` points to the full query schema for cross-field constraints. Object query fields use `deepObject` with `explode: true`. Non-object parameter shapes require explicit `meta.METHOD.openapi.parameters`; generation otherwise reports the route and location instead of omitting inputs.
|
|
33
|
+
|
|
34
|
+
Array query parameters expose the bracketed wire name (`tags[]`), `style: form`, and `explode: true`; the request property remains `tags`. External field references are retained without fetching, and explicit local type hints enable object/array style inference. Uninspectable root parameter objects still require explicit operation parameters.
|
|
35
|
+
|
|
36
|
+
`requestBody.required` is inferred from whether the converted schema accepts `{}`, the missing-body value supplied by Express. Local refs and logical constraints are evaluated without running validators; unresolved external/dynamic references conservatively remain required. Explicit `meta.METHOD.openapi.requestBody` overrides this inference. Example-only bodies are optional.
|
|
@@ -99,7 +99,7 @@ await enqueue('SendEmail', {
|
|
|
99
99
|
|
|
100
100
|
- **Task backend not initialised** — `tasks` was not configured in `ignite()`.
|
|
101
101
|
- **Unknown task name** — no file with that basename exists in `src/tasks/`.
|
|
102
|
-
- **The queue backend is unreachable** — Redis (BullMQ) or PostgreSQL (pg-boss) didn't accept the job within `tasks.enqueueTimeout` (default 5000 ms).
|
|
102
|
+
- **The queue backend is unreachable** — Redis (BullMQ) or PostgreSQL (pg-boss) didn't accept the job within `tasks.enqueueTimeout` (default 5000 ms). A readiness timeout prevents a later Redis submission. Commands already in flight may have committed despite a lost acknowledgment; do not automatically retry non-idempotent work. A pg-boss null acknowledgment rejects rather than reporting success.
|
|
103
103
|
|
|
104
104
|
```ts
|
|
105
105
|
try {
|
|
@@ -138,3 +138,7 @@ src/tasks/ResizeImage.ts → "ResizeImage"
|
|
|
138
138
|
```
|
|
139
139
|
|
|
140
140
|
The name is case-sensitive. `enqueue('sendEmail', ...)` will not match `SendEmail.ts`.
|
|
141
|
+
|
|
142
|
+
Since 0.12.0: opt-in OpenTelemetry instrumentation uses `tracing: true | TracingOptions`; the app owns its SDK and exporter. See [tracing](../guides/tracing.md) for HTTP/task propagation, trace log fields, thread behavior and shutdown ownership.
|
|
143
|
+
|
|
144
|
+
Since 0.12.0: pg-boss boxes reserved-key objects without changing the handler payload; old primitive wrappers remain readable. Thread execution rejects premature exits and disposes timers/open handles after completion, while awaiting pending bridge acknowledgments. Shutdown preserves shared cache until tasks settle and aggregates cleanup failures before exiting nonzero.
|
|
@@ -24,3 +24,7 @@ This helper's `apiDir` is **not** a new `ignite()` option. `createTestApp` is ex
|
|
|
24
24
|
The CommonJS `/testing` entry delegates to the ESM helper using native `import()`, so dynamically imported ESM routes share its authentication and request context. The Node/runner must support the route files' module format.
|
|
25
25
|
|
|
26
26
|
The ESM and CommonJS builds share process-wide auth configuration, request AsyncLocalStorage and cache state. CommonJS `requireAuth` global middleware therefore sees helper auth options, preserves `getCurrentUser()` across awaits into ESM routes, and observes the same revocations. Model/queue fixtures are still configured separately.
|
|
27
|
+
|
|
28
|
+
Since 0.11.0: `openapi?: boolean | OpenAPIOptions` enables the same document endpoint for tests. For WS tests, use `http.createServer(app)` and `attachWebSockets(server, app)`, then close the server in cleanup. The helper itself still never starts a listener.
|
|
29
|
+
|
|
30
|
+
Since 0.12.0: opt-in OpenTelemetry instrumentation uses `tracing: true | TracingOptions`; the app owns its SDK and exporter. See [tracing](../guides/tracing.md) for HTTP/task propagation, trace log fields, thread behavior and shutdown ownership.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Tracing API (since 0.12.0)
|
|
2
|
+
|
|
3
|
+
```ts
|
|
4
|
+
import type { TracingOptions, EFCConfig } from 'express-file-cluster';
|
|
5
|
+
|
|
6
|
+
interface TracingOptions {
|
|
7
|
+
http?: boolean;
|
|
8
|
+
tasks?: boolean;
|
|
9
|
+
shutdown?: () => Promise<void>;
|
|
10
|
+
}
|
|
11
|
+
// EFCConfig.tracing?: boolean | TracingOptions
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Disabled by default. `true` enables HTTP and task instrumentation. An options object enables both unless its `http` or `tasks` field is false. `shutdown` is an optional app SDK shutdown/flush callback, awaited once after serving-process HTTP/WebSocket/task drain by `gracefulShutdown`, within its timeout. Callback rejection logs an error and exits with status 1. A helper/custom server does not invoke it automatically.
|
|
15
|
+
|
|
16
|
+
The app must register its OpenTelemetry provider and async context manager before boot. EFC owns no SDK/exporter and does not change global providers. No new subpath, span helper or OTLP config is exported. The application uses `@opentelemetry/api` for its own spans.
|
|
17
|
+
|
|
18
|
+
`TestAppOptions.tracing` accepts the same option for HTTP instrumentation; task backends are not booted by the helper. See the [guide](../guides/tracing.md) for setup, privacy, backend minimums, worker-thread behavior and SDK lifecycle.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# WebSocket API (since 0.11.0)
|
|
2
|
+
|
|
3
|
+
```ts
|
|
4
|
+
import { attachWebSockets, closeWebSockets } from 'express-file-cluster';
|
|
5
|
+
import type { WebSocketHandler, WebSocketOptions } from 'express-file-cluster';
|
|
6
|
+
```
|
|
7
|
+
|
|
8
|
+
`WebSocketHandler = (socket: ws.WebSocket, request: express.Request) => void | Promise<void>`. Export it as `WS` from a route file. An invalid non-function `WS` export fails boot. File middleware runs before connection; `schema.WS` validates the HTTP handshake.
|
|
9
|
+
|
|
10
|
+
`attachWebSockets(server: http.Server, app: express.Express, options?: WebSocketOptions): ws.WebSocketServer` attaches upgrade handling once. Used automatically by ignite when WS routes exist, or explicitly with an EFC test app/custom server. It also integrates socket draining with `server.close()`.
|
|
11
|
+
|
|
12
|
+
`closeWebSockets(server: http.Server, timeoutMs = 1000): Promise<void>` sends 1001 and waits for clients to disconnect, terminating remaining peers at the deadline. Pending handshake sockets are destroyed immediately, including connections waiting in middleware. It is idempotent, and stops heartbeats. Calling it prevents further upgrades on that attachment.
|
|
13
|
+
|
|
14
|
+
| Option | Default | Behavior |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| `maxPayload?: number` | 1048576 | Integer inbound message byte limit from 1 through 2147483647. Compression is disabled. |
|
|
17
|
+
| `origins?: string[]` | same-origin | Exact HTTP(S) browser origins. Missing Origin is allowed; malformed/opaque origins are refused. |
|
|
18
|
+
| `heartbeatIntervalMs?: number` | 30000 | Integer ping/pong interval from 0 through 2147483647 ms; 0 disables. |
|
|
19
|
+
| `handshakeTimeoutMs?: number` | 10000 | Integer deadline from 1 through 2147483647 ms for upgrade middleware. |
|
|
20
|
+
|
|
21
|
+
`ignite({ websocket: false })` disables automatic attachment. No new import subpath is added. See [the guide](../guides/websockets.md) for middleware, authentication, async context, error handling, cluster boundaries and test cleanup.
|
|
22
|
+
|
|
23
|
+
Upgrades pipelined behind an unfinished HTTP response close the connection without throwing an uncaught socket-assignment error.
|
package/dist/docs/cli/add.md
CHANGED
|
@@ -120,7 +120,7 @@ export const POST = async (req: Request, res: Response) => {
|
|
|
120
120
|
`enqueue(name, payload)` rejects if:
|
|
121
121
|
- The task backend has not been initialised (missing `tasks` config in `ignite()`).
|
|
122
122
|
- The task name was not found in the registry (file not in `src/tasks/`, or bad default export).
|
|
123
|
-
- Redis did not accept the job within `tasks.enqueueTimeout` (default 5000 ms). The request fails fast instead of hanging
|
|
123
|
+
- Redis did not accept the job within `tasks.enqueueTimeout` (default 5000 ms). The request fails fast instead of hanging. A readiness wait cannot submit a Redis job after its deadline. If a backend command was already sent, a timeout or connection failure means its acknowledgment is unknown: the job may have committed. Make handlers idempotent before retrying an enqueue.
|
|
124
124
|
|
|
125
125
|
---
|
|
126
126
|
|
|
@@ -229,3 +229,7 @@ import { enqueue } from 'express-file-cluster/tasks';
|
|
|
229
229
|
```
|
|
230
230
|
|
|
231
231
|
Both are exported from the `tasks` sub-path export of `express-file-cluster`.
|
|
232
|
+
|
|
233
|
+
Since 0.12.0 hardening: thread jobs reject if the worker exits before reporting completion, ignore unrelated progress messages, and dispose the owned worker after the handler and pending enqueue acknowledgments finish. Await all task work; timers/open handles in a completed task are disposed. pg-boss preserves application objects containing its reserved wrapper keys and still reads legacy scalar jobs. A null pg-boss job acknowledgment is an enqueue failure. Shutdown drains jobs before closing cache and telemetry, waits for every backend even if another fails, and exits nonzero on cleanup failure.
|
|
234
|
+
|
|
235
|
+
Thread task progress messages are isolated from the internal completion/enqueue protocol by a per-worker token. Ordinary `parentPort.postMessage()` payloads cannot accidentally acknowledge a task or enqueue another one. This is protocol isolation, not a security sandbox for untrusted task code.
|
|
@@ -112,3 +112,5 @@ Pass a custom timeout (milliseconds) as the second argument:
|
|
|
112
112
|
```ts
|
|
113
113
|
gracefulShutdown(server, 30_000); // 30-second drain window
|
|
114
114
|
```
|
|
115
|
+
|
|
116
|
+
WebSockets (since 0.11.0): each worker owns its accepted connections. Broadcasts are worker-local unless the application uses pub/sub. Graceful worker shutdown closes sockets with 1001, waits for acknowledgments, and terminates unresponsive peers within its drain budget.
|
|
@@ -235,3 +235,7 @@ export const GET = async (req, res) => {
|
|
|
235
235
|
5. Registers an `app.all()` catch for unimplemented methods that returns 405.
|
|
236
236
|
|
|
237
237
|
`asyncWrap` wraps every handler in `Promise.resolve(...).catch(next)` so that thrown errors and rejected promises are forwarded to the Express error handler automatically.
|
|
238
|
+
|
|
239
|
+
Since 0.11.0: route files can also export a `WS` connection handler, sharing the file's middleware and params with HTTP methods. See [WebSockets](../guides/websockets.md). Opt-in [OpenAPI](../guides/openapi.md) documents loaded HTTP method/meta/schema exports.
|
|
240
|
+
|
|
241
|
+
Since 0.12.0 fix: explicit HEAD exports register before GET, so Express’s implicit HEAD fallback cannot shadow them. Other exported-method ordering and 405 metadata stay unchanged.
|
|
@@ -142,3 +142,5 @@ efc generate middleware authorize
|
|
|
142
142
|
```
|
|
143
143
|
|
|
144
144
|
> Route-level role protection doesn't need a custom middleware like `authorize` above — `requireAuth` itself accepts role names: `requireAuth('admin')`. The routes `efc add` generates use this shorthand, and `efc add admin-admins` adds a `Role` model. See [RBAC](../guides/rbac.md).
|
|
145
|
+
|
|
146
|
+
Since 0.12.0 hardening: file/global middleware may return promises; rejections and synchronous throws reach error handling without unhandled worker rejections. Express `next()`, `next("route")` and `next("router")` semantics are retained. Middleware entries must be functions and invalid entries fail at boot. Custom error middleware is also promise-aware and has a sanitized JSON fallback.
|
|
@@ -155,3 +155,15 @@ Either way the failure is logged (at most every 30 seconds), and calling `revoke
|
|
|
155
155
|
`revokeToken(res)` still exists and only clears the cookie — prefer `revokeSession` when a cache is configured.
|
|
156
156
|
|
|
157
157
|
ESM and CommonJS imports share the configured backend, key prefix, pending cache fills and revocation failure policy within one process. A backend configured by one build is used by the other; closing it closes the shared backend. Use one application/cache configuration per process.
|
|
158
|
+
|
|
159
|
+
## Since 0.12.0 production hardening
|
|
160
|
+
|
|
161
|
+
`cache.wrap` recovers after synchronous throws and prevents old in-flight computations from populating a replacement cache namespace. Memory capacity must be a positive safe integer; bad configuration fails before replacing an existing store.
|
|
162
|
+
|
|
163
|
+
Response keys separate HTTP methods and encode string/numeric user identifiers without delimiter collisions. GET and HEAD cannot poison one another. URL-prefix invalidation remains supported. The cache stores completed, serialized JSON and safe representation headers. It honors `Vary` by checking hashed request-header fingerprints; differing variants are misses (a custom key can keep variants separately). Wildcard `Vary`, `no-store`/`no-cache`, `Set-Cookie` (including late cookies), and private responses without `perUser` are not stored. Per-request headers such as CORS, request IDs and cookies are not replayed from cached handler headers; set custom dynamic headers in middleware.
|
|
164
|
+
|
|
165
|
+
Memory cache eviction cannot discard protected auth revocations. If protected entries fill its capacity, new revocation writes reject visibly; ordinary cache writes degrade to misses. Per-user revocation cutoffs have no automatic expiry, protecting older tokens if `jwtExpiresIn` is shortened. Use a persistent Redis deployment with a no-eviction policy for production revocation durability; memory state is still lost on restart, and explicitly clearing session keys removes revocations.
|
|
166
|
+
|
|
167
|
+
IPC cache calls reject on shutdown/disconnection rather than hanging. Rate-limit windows must be finite, at least one millisecond, and safely representable; counter keys isolate route/key tuples even when their components contain colons.
|
|
168
|
+
|
|
169
|
+
Response-cache hits replay the exact serialized JSON bytes, preserving JSON replacer/escaping output without running the replacer a second time.
|
|
@@ -170,3 +170,5 @@ Inspect, retry or purge dead-lettered jobs with `efc tasks failed | retry | purg
|
|
|
170
170
|
| Unique constraint violated | `409` | `{ "error": "<Model> with this <field> already exists", "statusCode": 409 }` |
|
|
171
171
|
| `requestTimeout` exceeded | `408` | `{ "error": "Request Timeout", "statusCode": 408 }` |
|
|
172
172
|
| Missing/invalid auth token | `401` | `{ "error": "Unauthorized" }` |
|
|
173
|
+
|
|
174
|
+
Since 0.12.0 hardening: async file/global middleware and custom error handlers are observed on Express 4. Rejected custom error handlers fall back to EFC’s sanitized JSON handler. Errors after partial response headers destroy the unfinished connection instead of hanging it; no second response is sent after a timeout.
|
|
@@ -56,3 +56,19 @@ What each model API does on which engine — and the test that proves it. Every
|
|
|
56
56
|
| Query logging + N+1 warnings | ✓ | ✓ | ✓ | ✓ | `db/query-log.integration.test.ts: warns once per request about an N+1 pattern` |
|
|
57
57
|
| `efc db studio --write` (through the model) | ✓ | ✓ | ✓ | ✓ | `db/studio.integration.test.ts: inserts, edits and deletes through the model` · `db/studio.integration.test.ts: writes through defineCollection` |
|
|
58
58
|
| Same table from `defineModel` and `defineTable` | — | ✓ | ✓ | — | `db/table.integration.test.ts: defineModel and defineTable over the same table` |
|
|
59
|
+
|
|
60
|
+
## HTTP contracts and WebSockets (since 0.11.0)
|
|
61
|
+
|
|
62
|
+
| Feature | Status | Evidence |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| OpenAPI 3.1 endpoint/offline generation, adapters, query/body contracts and optional paths | Implemented; opt-in | `openapi.test.ts: generates versioned paths, metadata, examples, JSON-schema parameters and request bodies from Zod` |
|
|
65
|
+
| File WS exports, middleware/auth/context, origin and payload limits, heartbeat and drain | Implemented; worker-local | `websocket.test.ts: shares real middleware, auth, decoded params and async request context, while HTTP coexists` |
|
|
66
|
+
|
|
67
|
+
No automatic auth-policy inference, message-schema validation, cross-worker broadcast bus or Swagger UI is included.
|
|
68
|
+
|
|
69
|
+
## Tracing (since 0.12.0)
|
|
70
|
+
|
|
71
|
+
| Feature | Status | Evidence |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| HTTP W3C parentage, concurrent context isolation, template attributes and correlated logs | Opt-in; app-owned SDK | `tracing.test.ts: continues remote traces, isolates concurrent requests and records templates without URL/query/credential values` |
|
|
74
|
+
| Trace-only carrier handling and clean task auth scopes | Native queue hooks; unchanged payloads | `tracing.test.ts: uses native queue metadata, keeps trace-only carriers, and clears auth/request state for task handlers` |
|
|
@@ -123,3 +123,5 @@ resetQueryMetrics(); // optional: start a fresh window without disabling collect
|
|
|
123
123
|
Snapshots are detached from internal state and contain no SQL, parameter values, error details or request IDs. Each entry aggregates completed calls, failures, inclusive statement counts and durations in milliseconds. Nested model calls retain their own entries; their statements also count toward the outer operation, so summing entries is not a global database statement total. `slow` counts calls at or above `slowMs`.
|
|
124
124
|
|
|
125
125
|
When the entry limit is reached, existing pairs keep updating; observations for new pairs increment `dropped`. Reset/reconfiguration clears entries, dropped counts and the `since` timestamp. Metrics are off by default. These are per-process counters, not a cluster-wide service or an OpenTelemetry exporter; collect from each worker/instance separately and secure any diagnostic endpoint you add.
|
|
126
|
+
|
|
127
|
+
Since 0.12.0: opt-in OpenTelemetry instrumentation uses `tracing: true | TracingOptions`; the app owns its SDK and exporter. See [tracing](../guides/tracing.md) for HTTP/task propagation, trace log fields, thread behavior and shutdown ownership.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# OpenAPI generation (since 0.11.0)
|
|
2
|
+
|
|
3
|
+
Enable an OpenAPI 3.1 JSON document for your real HTTP routes:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
ignite({
|
|
7
|
+
...config,
|
|
8
|
+
openapi: {
|
|
9
|
+
path: '/openapi.json',
|
|
10
|
+
info: { title: 'My API', version: '1.0.0' },
|
|
11
|
+
},
|
|
12
|
+
});
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`openapi: true` uses `/openapi.json` and the project's package name/version. It is off by default. Global middleware applies to the document endpoint too. Its URL is reserved before API routing; a conflicting GET or HEAD route fails startup, including hidden routes, dynamic matches, case variants and trailing slashes. Import the JSON into an OpenAPI viewer or client generator.
|
|
16
|
+
|
|
17
|
+
The generator reads HTTP method exports, `meta`, and each method's request `schema`. Existing validation behavior stays the same. Validators that implement [Standard JSON Schema](https://standardschema.dev/json-schema) convert automatically using their input representation (including recent Zod 4 versions). A Standard Schema validator without JSON Schema support needs the `schemaToJSONSchema(validator)` adapter; enabling OpenAPI without one reports which route/location could not be converted. The adapter may be async. Runtime validation does not require JSON Schema support when OpenAPI is off.
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
// src/api/users/[id].ts
|
|
21
|
+
import { z } from 'zod';
|
|
22
|
+
|
|
23
|
+
export const schema = {
|
|
24
|
+
GET: { params: z.object({ id: z.string().uuid() }) },
|
|
25
|
+
};
|
|
26
|
+
export const meta = {
|
|
27
|
+
GET: {
|
|
28
|
+
summary: 'Get a user',
|
|
29
|
+
tags: ['users'],
|
|
30
|
+
response: { status: 200, body: { id: 'example-id', name: 'Jane' } },
|
|
31
|
+
},
|
|
32
|
+
};
|
|
33
|
+
export const GET = async (req, res) => {
|
|
34
|
+
res.json({ id: req.params.id, name: 'Jane' });
|
|
35
|
+
};
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Body schemas become JSON request bodies; object properties in query/params schemas become parameters. Named object schemas behind local `$ref` are resolved for parameter fields. Object unions/intersections (`anyOf`, `oneOf`, `allOf`) retain their fields; a union field is required only when every branch requires it. The operation’s `x-efc-query-schema` references the complete query schema, preserving constraints between fields that individual OpenAPI parameters cannot express. Non-object parameter schemas fail generation with the route/location; supply explicit `meta.METHOD.openapi.parameters` to document a custom representation. Object query fields use `style: deepObject` and `explode: true`, matching Express bracket syntax such as `?filter[name]=Alice`. Nested `$defs` and local JSON Schema pointers are rebased into components; explicit `$id` resource scopes keep their local-reference semantics. Example request headers/query/body and response status/body come from `meta`. A request-validation 400 response is documented. Response schemas, alternative content types and authorization requirements can be supplied explicitly with `meta.METHOD.openapi` (an OpenAPI Operation Object). Auth middleware is not inspected to infer security policy.
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
// In ignite options:
|
|
42
|
+
openapi: {
|
|
43
|
+
components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer' } } },
|
|
44
|
+
}
|
|
45
|
+
// In a route:
|
|
46
|
+
export const meta = {
|
|
47
|
+
GET: { openapi: { security: [{ bearerAuth: [] }] } },
|
|
48
|
+
};
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`meta.GET.openapi.hidden: true` omits an operation. `summary`, `tags`, `description` and `operationId` are also supported directly in `meta.GET`. Explicit IDs must be unique; optional URL expansions get an index suffix. The document includes `basePath`. Optional URL segments expand into separate paths so every documented path parameter is required, as [OpenAPI requires](https://spec.openapis.org/oas/v3.1.0). Equivalent optional expansions use Express’s greedy binding (`[[first]]/[[second]]` with one segment binds `first`); other routes with equivalent templates but different parameter names fail generation rather than emitting an invalid document. Catch-all paths carry `x-efc-catch-all: true`: their slash-separated URL semantics need client-specific handling. WebSocket-only routes do not appear as HTTP operations.
|
|
52
|
+
|
|
53
|
+
For offline use, call `await generateOpenAPI('/absolute/path/to/src/api', { basePath, ...options })`, then write the returned object as JSON. This scans and imports route modules but does not listen, execute handlers or boot services; use the same TS loader/build output as the app, and keep service startup out of route module top-level code. Advanced callers can pass loaded `MountedRoute[]` directly instead. Plain `scanDir()` entries do not contain loaded HTTP exports/schemas. The `/testing` helper accepts the same `openapi` option for document tests.
|
|
54
|
+
|
|
55
|
+
Array query fields use bracketed wire names (`tags[]`) with `style: form` and `explode: true`, so one item and repeated items both reach Express as arrays. For example, `?tags[]=one&tags[]=two` becomes `req.query.tags`. An empty array has no entries to serialize; use an optional query field when omission is allowed. External field `$ref` values are preserved without network requests; provide a local `type` hint or explicit operation parameters if their object/array serialization cannot be inferred. Root parameter objects still need an inspectable local shape or explicit parameters.
|
|
56
|
+
|
|
57
|
+
Request-body requiredness follows whether the converted JSON Schema accepts the empty object Express supplies for a missing body. Required properties keep the body mandatory; optional object bodies allow omission. Local references and logical schema combinations are considered without executing application validators. Unknown external/dynamic body references remain required conservatively. Use `meta.METHOD.openapi.requestBody` to override inference, especially when middleware changes the body or validation uses custom rules. A body example alone does not make a body required.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# OpenTelemetry tracing (since 0.12.0)
|
|
2
|
+
|
|
3
|
+
EFC can trace incoming HTTP requests and background work across BullMQ, pg-boss and worker-thread handoffs. Enable `ignite({ tracing: true })`, or select components with `tracing: { http: true, tasks: true }`. Instrumentation is off by default and is available since 0.12.0.
|
|
4
|
+
|
|
5
|
+
Your application owns the OpenTelemetry SDK, sampling, resources and exporter. EFC uses the standard API and W3C trace-context propagator; it does not create a global provider, read OTLP environment variables, install auto-instrumentation, or choose a collector. Without a registered SDK, tracing safely remains no-op.
|
|
6
|
+
|
|
7
|
+
## Configure the application SDK
|
|
8
|
+
|
|
9
|
+
This example uses the current unified tracing SDK and its compatible API line:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @opentelemetry/api@~1.9.0 @opentelemetry/sdk-trace@^2.12.0 @opentelemetry/context-async-hooks@^2.12.0
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
// src/index.ts — initialize before ignite(), in each serving process
|
|
17
|
+
import { context, trace } from '@opentelemetry/api';
|
|
18
|
+
import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
|
|
19
|
+
import { TracerProvider, BatchSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace';
|
|
20
|
+
import { ignite, gracefulShutdown } from 'express-file-cluster';
|
|
21
|
+
import config from '../efc.config.js';
|
|
22
|
+
|
|
23
|
+
const manager = new AsyncLocalStorageContextManager().enable();
|
|
24
|
+
const provider = new TracerProvider({
|
|
25
|
+
spanProcessors: [new BatchSpanProcessor({ exporter: new ConsoleSpanExporter() })],
|
|
26
|
+
});
|
|
27
|
+
context.setGlobalContextManager(manager);
|
|
28
|
+
trace.setGlobalTracerProvider(provider);
|
|
29
|
+
|
|
30
|
+
const server = await ignite({
|
|
31
|
+
...config,
|
|
32
|
+
tracing: {
|
|
33
|
+
shutdown: async () => {
|
|
34
|
+
await provider.shutdown();
|
|
35
|
+
manager.disable();
|
|
36
|
+
},
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
gracefulShutdown(server);
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Use your preferred exporter in place of `ConsoleSpanExporter`; EFC does not send data to a collector on its own. Initialize an SDK/context manager in every cluster worker; SDKs and exporters are process-local. Use the API version supported by your chosen SDK. If you already use HTTP/Express auto-instrumentation, set `tracing: { http: false }` to avoid an extra EFC HTTP server span while retaining task tracing.
|
|
43
|
+
|
|
44
|
+
## HTTP and logs
|
|
45
|
+
|
|
46
|
+
Each request gets a server span. W3C `traceparent`/`tracestate` headers establish remote parentage; malformed parents start a fresh trace. Concurrent requests retain separate context across awaits. Names use the method and route template (for example `GET /v1/api/users/:id`), with method, template and response status attributes. Unmatched routes use the method alone. Spans end once on response completion or disconnect, including validation failures, request timeouts and WebSocket upgrade handshakes. Upgrades finish at 101; message frames do not create spans automatically.
|
|
47
|
+
|
|
48
|
+
Server errors and aborted connections mark the span as an error; ordinary 4xx responses do not. The error observer runs before custom error middleware. `req.log`, `getLogger()` and the logger proxy include `trace_id`/`span_id` when a valid span context is active. Task handlers start a fresh EFC request/auth scope, so `$currentUser` and request IDs do not leak from the request that queued them.
|
|
49
|
+
|
|
50
|
+
EFC HTTP attributes omit raw URLs, query strings, bodies, cookies and credentials. Native queue instrumentation includes job IDs, queue/task names, attempts and failure diagnostics, not application payloads. Exception messages/stacks can contain application data; configure exporter-side redaction for your application's errors. Baggage is not accepted or persisted by EFC's W3C propagation path.
|
|
51
|
+
|
|
52
|
+
## Queues, retries and threads
|
|
53
|
+
|
|
54
|
+
The new minimum optional backend versions are **BullMQ 5.79.1** and **pg-boss 12.38.0**; upgrade these peers before using 0.12.0. Native backend metadata persists W3C context separately from application payloads. Existing jobs without trace metadata and scheduled jobs start independent traces. Each retry has its own consumer span under the producer context. Queue/admin payloads and dead-letter retry behavior remain unchanged.
|
|
55
|
+
|
|
56
|
+
A `thread: true` job's consumer span covers the entire thread execution. W3C context crosses the worker boundary and returns with nested `enqueue()` calls, including mixed ESM/CommonJS route and task modules. The task registry and enqueue implementation are shared between package formats within each isolate. The application SDK is not copied into a worker isolate: instrumenting additional operations inside the thread requires initializing an SDK there. Task-level spans still export from the queue worker's SDK.
|
|
57
|
+
|
|
58
|
+
## Shutdown and tests
|
|
59
|
+
|
|
60
|
+
`tracing.shutdown` is optional and app-owned. With `gracefulShutdown(server)`, EFC drains HTTP/WebSockets and task backends before awaiting it, under the existing shutdown deadline. It runs once per serving process; rejection is logged and exits with status 1. Custom spans created in the cluster primary need application-managed SDK shutdown. With a custom lifecycle, close the HTTP server and task backends, then shut down your SDK yourself.
|
|
61
|
+
|
|
62
|
+
`createTestApp({ apiDir, tracing: true })` uses the same HTTP instrumentation without creating an SDK or listener. It does not own SDK shutdown. Tests can register an in-memory exporter and inspect actual finished spans. Global OpenTelemetry SDK/context-manager state is process-wide; isolate tests or reset that state between configurations.
|
|
63
|
+
|
|
64
|
+
See [the API reference](../api-reference/tracing.md), [OpenTelemetry instrumentation](https://opentelemetry.io/docs/languages/js/instrumentation/), [BullMQ telemetry](https://docs.bullmq.io/guide/telemetry/) and [pg-boss tracing](https://pgboss.io/opentelemetry).
|
|
@@ -93,3 +93,5 @@ So authentication in `middlewares` still responds 401/403 before any 400 — una
|
|
|
93
93
|
## Model-level validation is separate
|
|
94
94
|
|
|
95
95
|
`schema` validates the HTTP request. `defineModel` validates what you write to the database (types, `required`, `enum`, `min`/`max`, `match`, custom `validate`) and throws a `ModelValidationError` — also a 400 with `issues`. Use both: request schemas for the API contract, model rules for data integrity. See [Database](./database.md).
|
|
96
|
+
|
|
97
|
+
Since 0.11.0: `schema.WS` validates WebSocket handshake params/query through the same pipeline, before upgrade; message validation belongs in the handler. Opt-in OpenAPI conversion uses a separate Standard JSON Schema input protocol or an explicit adapter; Standard Schema validation alone does not guarantee JSON Schema conversion. See [OpenAPI](./openapi.md).
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# File-based WebSockets (since 0.11.0)
|
|
2
|
+
|
|
3
|
+
Export `WS` from a route file. `ignite()` serves its upgrade on the same HTTP server and `basePath` as HTTP routes.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
// src/api/chat/[room].ts
|
|
7
|
+
import type { WebSocketHandler } from 'express-file-cluster';
|
|
8
|
+
import { requireAuth, getCurrentUser } from 'express-file-cluster/auth';
|
|
9
|
+
|
|
10
|
+
export const middlewares = [requireAuth];
|
|
11
|
+
export const WS: WebSocketHandler = (socket, req) => {
|
|
12
|
+
socket.on('message', (data, isBinary) => {
|
|
13
|
+
const user = getCurrentUser();
|
|
14
|
+
socket.send(JSON.stringify({ room: req.params.room, userId: user?.id, text: data.toString(), isBinary }));
|
|
15
|
+
});
|
|
16
|
+
};
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Connect to `ws://localhost:3000/v1/api/chat/general` (use `wss://` behind TLS). `WS` receives a [ws WebSocket](https://github.com/websockets/ws/blob/master/doc/ws.md) and the Express request. An HTTP `GET`/`POST` export can coexist in the same file. HTTP clients do not invoke `WS`, and upgrading an HTTP-only or unknown route returns 404.
|
|
20
|
+
|
|
21
|
+
Middleware response headers (including cookies and request IDs) are included in successful upgrades; protocol framing/negotiation headers remain owned by the WebSocket server. Global and file middleware, cookie parsing, request context and named/optional/catch-all params apply before upgrade. `requireAuth` checks cookies/bearer tokens and revocation during the handshake; auth failure is an HTTP 401/403/503 rather than a WebSocket connection. Use method-keyed `schema.WS` for query/params handshake validation. It does not validate message frames. `getCurrentUser()` and the request logger remain available in message/close/error callbacks and across awaits. Handle errors inside application event listeners; EFC catches errors thrown/rejected by the exported connection handler and closes with 1011.
|
|
22
|
+
|
|
23
|
+
Browser clients use cookies; the browser WebSocket API cannot set arbitrary Authorization headers. Authorization and session changes during an already established connection are application policy: recheck sensitive message operations or close affected sockets when sessions end. Handshake authentication is not repeated for every frame.
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
ignite({
|
|
27
|
+
...config,
|
|
28
|
+
websocket: {
|
|
29
|
+
origins: ['https://app.example.com'],
|
|
30
|
+
maxPayload: 1024 * 1024,
|
|
31
|
+
heartbeatIntervalMs: 30_000,
|
|
32
|
+
handshakeTimeoutMs: 10_000,
|
|
33
|
+
},
|
|
34
|
+
});
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Upgrades are enabled when a `WS` export exists. `websocket: false` disables them. Browser origins default to same-origin using Express's protocol/host; configure `trustProxy` correctly behind a proxy. An explicit origin list replaces this default. Opaque/malformed/cross-origin handshakes are rejected with 403. Clients without an Origin header (such as trusted Node clients) are allowed and still pass auth middleware.
|
|
38
|
+
|
|
39
|
+
`maxPayload` accepts integers from 1 through 2147483647 bytes; larger values fail configuration instead of overflowing the receiver’s limit. Both timer options also have a 2147483647 ms ceiling. Inbound messages default to a 1 MiB limit, compression is disabled, and heartbeat pings terminate unresponsive peers. Set `heartbeatIntervalMs: 0` to disable heartbeat. Pending middleware has a 10-second upgrade deadline; the HTTP `requestTimeout` may reject it earlier. Once upgraded, HTTP request timers are cleared.
|
|
40
|
+
|
|
41
|
+
Pipelined upgrades received while an earlier HTTP response still owns the connection close that connection safely.
|
|
42
|
+
|
|
43
|
+
`server.close()` immediately destroys pending handshake sockets, closes established sockets with code 1001 and terminates unresponsive peers after a drain interval. `gracefulShutdown(server)` drains WebSockets with HTTP/task shutdown, including signals forwarded to workers. Every cluster worker owns its connections; broadcasts through a server's `clients` set stay within that worker. Use application pub/sub for cross-worker/instance messages.
|
|
44
|
+
|
|
45
|
+
## Testing and custom HTTP servers
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import http from 'node:http';
|
|
49
|
+
import { attachWebSockets } from 'express-file-cluster';
|
|
50
|
+
import { createTestApp } from 'express-file-cluster/testing';
|
|
51
|
+
|
|
52
|
+
const app = await createTestApp({ apiDir: '/absolute/path/to/api' });
|
|
53
|
+
const server = http.createServer(app);
|
|
54
|
+
const sockets = attachWebSockets(server, app);
|
|
55
|
+
server.listen(0);
|
|
56
|
+
// Connect a ws client; sockets.clients contains this server's connections.
|
|
57
|
+
// Close server in cleanup; upgraded sockets are drained too.
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The test helper itself still does not start a listener. `attachWebSockets` rejects duplicate attachment. Each server has its own limits, connections and heartbeat; app auth/cache state follows the process-wide isolation rules in the testing guide.
|
package/dist/docs/index.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**express-file-cluster (EFC)** is an opinionated backend framework built on Express. It removes routing ceremony, saturates every CPU core automatically, and ships a production-grade background-task subsystem — all from a single `ignite()` call.
|
|
4
4
|
|
|
5
|
-
> **Status: v0.
|
|
5
|
+
> **Status: v0.12.0 — Beta.** File-based routing (incl. catch-all and optional segments), request validation, clustering, auth, structured logging, MongoDB and PostgreSQL models with types inferred from the schema, PostgreSQL-native `defineTable` (Prisma-style queries and relations: foreign keys, many-to-many, `include`, relation filters, nested writes), query logging, BullMQ and pg-boss tasks with cron and dead-letter tooling, migrations (written for you from model changes: `efc db generate`, plus `efc db pull` and `efc import-prisma`), and the `efc add` feature registry (auth, admin, billing… copied into your app as source you own) are all implemented.
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -48,7 +48,10 @@
|
|
|
48
48
|
| [Coming from Prisma](./guides/coming-from-prisma.md) | `efc import-prisma`, schema and query mapping |
|
|
49
49
|
| [Coming from mongoose](./guides/coming-from-mongoose.md) | `defineCollection` for mongoose users: schema and query mapping |
|
|
50
50
|
| [Testing](./guides/testing.md) | `createTestApp` for real file-based routes without service boot |
|
|
51
|
+
| [OpenAPI (since 0.11.0)](./guides/openapi.md) | Opt-in OpenAPI JSON from route metadata and request schemas |
|
|
52
|
+
| [WebSockets (since 0.11.0)](./guides/websockets.md) | WS file exports, middleware/auth, limits and shutdown |
|
|
51
53
|
| [Validation](./guides/validation.md) | Route `schema` exports with zod, valibot, arktype |
|
|
54
|
+
| [Tracing (since 0.12.0)](./guides/tracing.md) | OpenTelemetry HTTP/task propagation and app-owned SDK setup |
|
|
52
55
|
| [Logging](./guides/logging.md) | pino, request IDs, `getLogger()` |
|
|
53
56
|
| [Caching & Sessions](./guides/caching.md) | `cache`, `cacheResponse`, revoking JWT sessions |
|
|
54
57
|
| [Generated Portals](./guides/generated-portals.md) | Every model and route `create-efc-app` scaffolds for the User/Admin portals |
|
|
@@ -37,12 +37,16 @@ Load **only** the module the work points to. Each is self-contained.
|
|
|
37
37
|
docs/ ← full documentation
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
## Status (v0.
|
|
40
|
+
## Status (v0.12.0 — Beta, Phase 2 complete + defineTable with relations + generated migrations + `efc add` registry)
|
|
41
41
|
|
|
42
42
|
Implemented: file-based router (incl. `[[id]]`, `[...slug]`, `[[...slug]]`), request validation (`export const schema`, Standard Schema), multi-core clustering with graceful shutdown, http-only cookie + Bearer token auth (scrypt password hashing built in), structured logging (pino, request IDs), `defineModel` on MongoDB (mongoose) **and** PostgreSQL (Drizzle) with validation, query options, bulk ops, transactions, `sync()`/`drop()`, PostgreSQL-native `defineTable` (Prisma-style queries, foreign keys, many-to-many, `include`, relation filters, nested writes), MongoDB-native `defineCollection` (mongoose vocabulary, BSON types, geo/text, `bulkWrite`, change streams), query logging (`logging.queries`), BullMQ **and** pg-boss task backends with cron schedules and dead-letter CLI, worker_threads for CPU-bound tasks, migrations/seeds/studio (`efc db`) incl. migrations generated from model diffs (`efc db generate`), `efc db pull` and `efc import-prisma`, full CLI.
|
|
43
43
|
|
|
44
|
-
**Not yet implemented (Phase 3+):**
|
|
44
|
+
**Not yet implemented (Phase 3+):** plugins, `efc lint`, `efc deploy`.
|
|
45
45
|
|
|
46
46
|
Phase 3 testing utilities: `createTestApp` from `express-file-cluster/testing` mounts a real route tree without service boot or a listener. Read `docs/guides/testing.md` and `docs/api-reference/testing.md`; see process-wide auth/logging isolation limits.
|
|
47
47
|
|
|
48
|
-
M6 completed 2026-10-30: query logging + bounded opt-in query metrics, editable studio, pool settings + bounded prepared statements, and a strict 10% nightly benchmark gate. See `bench/results/m6-validation.md` for measured evidence. OpenTelemetry is
|
|
48
|
+
M6 completed 2026-10-30: query logging + bounded opt-in query metrics, editable studio, pool settings + bounded prepared statements, and a strict 10% nightly benchmark gate. See `bench/results/m6-validation.md` for measured evidence. OpenTelemetry instrumentation is implemented in the 0.12.0 release.
|
|
49
|
+
|
|
50
|
+
Since 0.11.0: OpenAPI 3.1 generation (`generateOpenAPI`, `ignite({ openapi })`) and file `WS` exports with HTTP middleware/auth, origin/payload limits, heartbeat and drain. Read `docs/guides/openapi.md`, `docs/api-reference/openapi.md`, `docs/guides/websockets.md`, `docs/api-reference/websockets.md`. These APIs are available since 0.11.0.
|
|
51
|
+
|
|
52
|
+
Since 0.12.0: opt-in HTTP/task OpenTelemetry instrumentation (`tracing: true | TracingOptions`). Read `docs/guides/tracing.md` and `docs/api-reference/tracing.md`; the app owns SDK/context manager/exporter and shutdown. Native task propagation requires BullMQ ≥5.79.1 or pg-boss ≥12.38.0.
|
|
@@ -346,3 +346,21 @@ Generated app 2FA (not core exports): TOTP/email OTP enrollment, password+code l
|
|
|
346
346
|
Auth payloads may include `efc_auth_at` (epoch milliseconds from before credentials are read): revocation checks it conservatively against the account cutoff, capped at the server's issue time. Generated login/refresh routes set it. `/testing` supports CommonJS callers through an async bridge to its ESM implementation.
|
|
347
347
|
|
|
348
348
|
ESM/CJS auth configuration, request context and cache state are shared within the process, including mixed-module middleware in `/testing`. Generated reset-password uses atomic unexpired-token consumption and clears refresh credentials; custom auth logout propagates revocation failure.
|
|
349
|
+
|
|
350
|
+
## 0.11.0 — OpenAPI and WebSockets
|
|
351
|
+
|
|
352
|
+
Main exports: `generateOpenAPI(routes: MountedRoute[] | string, options?: OpenAPIOptions & { basePath?: string }): Promise<OpenAPIDocument>`, `attachWebSockets(server: http.Server, app: express.Express, options?: WebSocketOptions): ws.WebSocketServer`, `closeWebSockets(server: http.Server, timeoutMs = 1000): Promise<void>`. Types: `JSONSchema`, `OpenAPIOptions`, `OpenAPIDocument`, `WebSocketHandler`, `WebSocketOptions`. No new import paths.
|
|
353
|
+
|
|
354
|
+
`EFCConfig.openapi?: boolean | OpenAPIOptions` (off; default path `/openapi.json`); `EFCConfig.websocket?: false | WebSocketOptions` (auto-attach for WS exports). `TestAppOptions.openapi` matches. `MountedRoute` includes optional `schema` and `websocket`. `RouteMethodMeta` adds `summary`, `tags`, `operationId`, `openapi` operation overrides (`hidden` omits). OpenAPI uses Standard JSON Schema input or explicit `schemaToJSONSchema`, not validator source inspection. WS signature `(socket, request) => void | Promise<void>`; file/global middleware and `schema.WS` apply before upgrade. See the API references for defaults and lifecycle.
|
|
355
|
+
|
|
356
|
+
0.11.0 review fixes: WS payload/timer options are bounded to signed int32 (payload/handshake ≥1, heartbeat ≥0). Drain destroys pending upgrades immediately; pipelined upgrades behind active HTTP responses close safely. OpenAPI URL collision checks include hidden GET/HEAD and actual Express matches. Object query fields use deepObject; object unions/intersections retain fields/requirements and `x-efc-query-schema` preserves the whole query contract. Non-object parameter shapes need explicit operation parameters. Equivalent optional paths keep the first parameter binding; conflicting templates across routes throw.
|
|
357
|
+
|
|
358
|
+
OpenAPI follow-up: array query wire names use brackets (`tags[]`, form/explode) to preserve single items; Express still exposes `req.query.tags`. External field refs are kept without fetching; local type hints or explicit parameters control their serialization. Body requiredness checks converted-schema acceptance of Express’s missing-body `{}` without calling validators; unknown refs remain required and explicit requestBody metadata overrides it.
|
|
359
|
+
|
|
360
|
+
## Since 0.12.0 — OpenTelemetry
|
|
361
|
+
|
|
362
|
+
`EFCConfig.tracing?: boolean | TracingOptions` (default off); `TracingOptions` is a root type export with `http?: boolean`, `tasks?: boolean` (enabled unless false when tracing is on), `shutdown?: () => Promise<void>` (app-owned SDK, awaited after serving-process HTTP/task drain). `TestAppOptions.tracing` matches for HTTP only. No new import path or SDK/exporter APIs are provided. Register the application SDK/context manager before boot. W3C trace-only propagation; native queue metadata keeps payloads unchanged; thread enqueue preserves parentage. HTTP route templates/status, error/abort handling and trace log fields are automatic. See `docs/guides/tracing.md`.
|
|
363
|
+
|
|
364
|
+
Since 0.12.0 hardening: promise-aware global/file/error middleware, explicit HEAD priority, terminal thread lifecycle, sanitized custom-error fallback and partial-response closure. Response caches use collision-free user/method scopes, serialized snapshots, Vary fingerprints and cookie/cache-control bypasses; prefix invalidation remains. cache.wrap recovers from synchronous failures and cannot write old results into a reconfigured namespace. Revocation cookies honor cookieDomain; protected memory entries cannot be evicted; user cutoffs persist, and late auth does not write after response timeout. Queue readiness deadlines prevent late starts, while in-flight outcomes still require application idempotency.
|
|
365
|
+
|
|
366
|
+
Response-cache hits replay the exact serialized JSON bytes, preserving JSON replacer/escaping output without running the replacer a second time.
|
|
@@ -47,10 +47,10 @@ Cookie name: exactly `'efc_token'` (hardcoded).
|
|
|
47
47
|
## `revokeToken(res)`
|
|
48
48
|
|
|
49
49
|
```ts
|
|
50
|
-
res.clearCookie('efc_token')
|
|
50
|
+
res.clearCookie('efc_token', { ...(cookieDomain !== undefined && { domain: cookieDomain }) })
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
Uses the configured domain when clearing the cookie. The JWT itself is not invalidated — use `revokeSession` for that.
|
|
54
54
|
|
|
55
55
|
---
|
|
56
56
|
|
|
@@ -152,3 +152,5 @@ Format accepted by `jose`: `'15m'`, `'1h'`, `'7d'`, `'30d'`, integer seconds, et
|
|
|
152
152
|
Generated User/Admin logout requires authentication, compare-and-sets the account's stored refresh token to empty (including bearer logout with no refresh cookie/body), then revokes the current access token and clears cookies. Login persists refresh credentials only while the password hash still matches its verified snapshot. Generated login/refresh tokens carry `efc_auth_at`, captured before credential reads; revocation rejects a token whose authentication started at or before the cutoff, even if it was signed afterwards. Custom token issuers may include this numeric epoch-millisecond claim for the same protection; it can only restrict access, never override a later server-issued time. Existing generated apps must update their owned auth routes as well as the framework to receive these fixes.
|
|
153
153
|
|
|
154
154
|
Password reset atomically consumes the matching, still-unexpired reset token while replacing the password and clearing stored refresh credentials and pending 2FA challenges. Concurrent use has one winner; expiry is rechecked in the database after hashing. Active 2FA enrollment remains enabled. Password changes also invalidate outstanding reset links. Custom auth-entity logout propagates revocation-store failures instead of returning a false success. Existing apps must update their owned reset-password, change-password, two-factor helper and custom logout files.
|
|
155
|
+
|
|
156
|
+
Since 0.12.0 hardening: authentication no longer writes/continues after a request timeout or disconnect. User cutoffs do not expire automatically; changing jwtExpiresIn cannot shorten protection for old tokens. In-memory revocation entries are eviction-protected; capacity exhaustion rejects revocation writes rather than reviving a session. Durable/no-eviction Redis is required for persistence across restarts; clearing session entries intentionally removes their protection.
|
|
@@ -146,3 +146,9 @@ const clusterEnabled = config.cluster ?? (process.env['NODE_ENV'] === 'productio
|
|
|
146
146
|
`databasePool.preparedStatements?: boolean | { max?: number }` defaults true/100 names per physical connection; false or max 0 disables (Mongo ignores). A private Pool/client proxy is passed to Drizzle, preserving Pool identity and transaction-client release; exported native `db` is unchanged. Object query configs for single SELECT/INSERT/UPDATE/DELETE/WITH statements get a SQL-shape hash name; parameters/types/rowMode are untouched, explicit names/control/DDL/multi-statements unchanged. Lifetime budget bounds server names, with unnamed fallback (no eviction/DEALLOCATE). Schema sync/drop bumps generation; connection budgets never reset. External DDL requires reconnecting, and incompatible poolers require opting out. `prepared-statements.integration.test.ts` proves reuse, transactions, budget/disable and schema invalidation.
|
|
147
147
|
|
|
148
148
|
`logging.queries.metrics: true | { maxEntries }` enables bounded per-process model/op aggregates (default off; enabled default 1000, zero disables). Main exports `getQueryMetrics`, `resetQueryMetrics`, `QueryMetric`, `QueryMetricsSnapshot`. Snapshots contain counters/latency summaries, since and dropped observations; no SQL/params/error details. Nested statement counts inclusive; reset/reconfigure starts a new window. Not distributed tracing.
|
|
149
|
+
|
|
150
|
+
Since 0.11.0: after route mounting metadata is loaded, optional OpenAPI is generated/served before attaching the API router. The HTTP server is explicitly created, WS upgrades attach when a WS export exists, then it listens. Graceful shutdown drains WS sockets before completing backend shutdown. Origin policy is separate from CORS; middleware/auth runs during upgrade.
|
|
151
|
+
|
|
152
|
+
Since 0.12.0 tracing: SDK initialization belongs to the app, before ignite, per serving process. HTTP instrumentation precedes request logging; native queue hooks receive `tracing.tasks` at backend init. After HTTP/WS/task drain, gracefulShutdown awaits the app `tracing.shutdown` once under the existing deadline; callback rejection exits 1. Cluster-primary SDK lifecycle for custom primary spans is app-owned.
|
|
153
|
+
|
|
154
|
+
Hardening: shutdown waits for every transport/task close result, then closes cache, then app telemetry; all cleanup is attempted and any failure exits 1. Invalid memory capacity fails before replacing a live store.
|
|
@@ -112,3 +112,9 @@ Files that do NOT match this pattern are silently ignored by `scanDir`.
|
|
|
112
112
|
Header: `Allow: GET, POST` (only the implemented methods).
|
|
113
113
|
|
|
114
114
|
**Only sent when at least one method IS implemented.** A file that exports no HTTP methods gets no 405 handler — Express would return 404.
|
|
115
|
+
|
|
116
|
+
Since 0.11.0, `WS` exports mount upgrade-only handlers on the same paths; HTTP methods skip upgrade requests. File/global middleware and named params apply, then `schema.WS` validation, then the connection handler. OpenAPI documents HTTP exports only; optional path segments expand into separate required-path variants.
|
|
117
|
+
|
|
118
|
+
OpenAPI optional variants deduplicate equivalent template shapes using greedy earlier-parameter bindings; conflicting names across separate routes fail generation. Document URL collision checks use actual Express GET/HEAD matchers, including hidden routes. Query object combinators retain fields and requirements; object query fields serialize as deepObject. WS drain destroys pending handshakes; pipelined upgrades behind an active HTTP response close safely.
|
|
119
|
+
|
|
120
|
+
Since 0.12.0 hardening: register explicit HEAD before GET (Express otherwise invokes GET for HEAD). Async file/global middleware and custom error handlers catch promise failures; malformed middleware entries fail boot. Partially written error responses close, and failed custom handlers use sanitized JSON fallback.
|