express-file-cluster 0.11.0 → 0.12.1

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.
Files changed (139) hide show
  1. package/dist/auth/index.cjs +8 -7
  2. package/dist/auth/index.cjs.map +1 -1
  3. package/dist/auth/index.d.cts +1 -1
  4. package/dist/auth/index.d.ts +1 -1
  5. package/dist/auth/index.js +7 -5
  6. package/dist/{chunk-JBOMTZT5.js → chunk-3JQWQF2M.js} +3 -3
  7. package/dist/chunk-3ROVNEDR.js +20 -0
  8. package/dist/chunk-3ROVNEDR.js.map +1 -0
  9. package/dist/{chunk-WHBSVYUY.cjs → chunk-4FQP6QX3.cjs} +3 -3
  10. package/dist/{chunk-WHBSVYUY.cjs.map → chunk-4FQP6QX3.cjs.map} +1 -1
  11. package/dist/chunk-546TNO2V.js +226 -0
  12. package/dist/chunk-546TNO2V.js.map +1 -0
  13. package/dist/{chunk-EJDZZ4KX.js → chunk-74R37C4I.js} +48 -21
  14. package/dist/chunk-74R37C4I.js.map +1 -0
  15. package/dist/{chunk-H2PVWCWC.cjs → chunk-A2QGDWCG.cjs} +15 -8
  16. package/dist/chunk-A2QGDWCG.cjs.map +1 -0
  17. package/dist/{chunk-DGYPIIJE.cjs → chunk-AG7PVYPE.cjs} +90 -64
  18. package/dist/chunk-AG7PVYPE.cjs.map +1 -0
  19. package/dist/{chunk-O2E7H2XA.js → chunk-BCSJOPYH.js} +2 -2
  20. package/dist/{chunk-OM2XJJWX.js → chunk-EBJELA7T.js} +30 -25
  21. package/dist/chunk-EBJELA7T.js.map +1 -0
  22. package/dist/{chunk-IEF6AEK3.cjs → chunk-H6MHRHUP.cjs} +104 -50
  23. package/dist/chunk-H6MHRHUP.cjs.map +1 -0
  24. package/dist/chunk-I2IVJURJ.cjs +20 -0
  25. package/dist/chunk-I2IVJURJ.cjs.map +1 -0
  26. package/dist/{chunk-6WTMRZS7.cjs → chunk-IG3V2IOK.cjs} +57 -30
  27. package/dist/chunk-IG3V2IOK.cjs.map +1 -0
  28. package/dist/chunk-JAPZYQVJ.cjs +143 -0
  29. package/dist/chunk-JAPZYQVJ.cjs.map +1 -0
  30. package/dist/{chunk-QSIP7YLW.cjs → chunk-JHCXIYJH.cjs} +25 -48
  31. package/dist/chunk-JHCXIYJH.cjs.map +1 -0
  32. package/dist/{chunk-GWMW6XY7.cjs → chunk-JVB5NLEM.cjs} +15 -13
  33. package/dist/chunk-JVB5NLEM.cjs.map +1 -0
  34. package/dist/chunk-PUM5ZDAH.js +140 -0
  35. package/dist/chunk-PUM5ZDAH.js.map +1 -0
  36. package/dist/{chunk-CGY7JU4Y.cjs → chunk-PUYBKDYD.cjs} +11 -2
  37. package/dist/chunk-PUYBKDYD.cjs.map +1 -0
  38. package/dist/{chunk-336IU55W.js → chunk-QLM3JEER.js} +5 -3
  39. package/dist/{chunk-336IU55W.js.map → chunk-QLM3JEER.js.map} +1 -1
  40. package/dist/{chunk-SOU3PBJC.cjs → chunk-SV4C4HWP.cjs} +89 -89
  41. package/dist/{chunk-SOU3PBJC.cjs.map → chunk-SV4C4HWP.cjs.map} +1 -1
  42. package/dist/{chunk-2IDRC7RK.js → chunk-UJ2ISRLP.js} +11 -34
  43. package/dist/chunk-UJ2ISRLP.js.map +1 -0
  44. package/dist/chunk-URKE3OXN.cjs +226 -0
  45. package/dist/chunk-URKE3OXN.cjs.map +1 -0
  46. package/dist/{chunk-DTMDJGRW.cjs → chunk-VLGN3XUM.cjs} +40 -35
  47. package/dist/chunk-VLGN3XUM.cjs.map +1 -0
  48. package/dist/{chunk-R6GPQZLI.js → chunk-X2B7WBKH.js} +88 -34
  49. package/dist/chunk-X2B7WBKH.js.map +1 -0
  50. package/dist/chunk-Y7I2633P.js +12 -0
  51. package/dist/chunk-Y7I2633P.js.map +1 -0
  52. package/dist/{chunk-B6MB6HEG.js → chunk-ZBQUYFI3.js} +14 -7
  53. package/dist/chunk-ZBQUYFI3.js.map +1 -0
  54. package/dist/{chunk-LECHRAU3.js → chunk-ZU2GK5WY.js} +84 -58
  55. package/dist/chunk-ZU2GK5WY.js.map +1 -0
  56. package/dist/cli/db-runner.cjs +26 -25
  57. package/dist/cli/db-runner.cjs.map +1 -1
  58. package/dist/cli/db-runner.js +5 -3
  59. package/dist/cli/db-runner.js.map +1 -1
  60. package/dist/cli/index.cjs +20 -16
  61. package/dist/cli/index.cjs.map +1 -1
  62. package/dist/cli/index.js +13 -8
  63. package/dist/cli/index.js.map +1 -1
  64. package/dist/docs/api-reference/auth.md +2 -0
  65. package/dist/docs/api-reference/ignite.md +4 -0
  66. package/dist/docs/api-reference/tasks.md +6 -2
  67. package/dist/docs/api-reference/testing.md +2 -0
  68. package/dist/docs/api-reference/tracing.md +18 -0
  69. package/dist/docs/cli/add.md +1 -1
  70. package/dist/docs/cli/diagnostics.md +1 -1
  71. package/dist/docs/cli/index.md +1 -1
  72. package/dist/docs/core-concepts/background-tasks.md +7 -1
  73. package/dist/docs/core-concepts/file-based-routing.md +4 -0
  74. package/dist/docs/core-concepts/middleware.md +2 -0
  75. package/dist/docs/guides/caching.md +12 -0
  76. package/dist/docs/guides/error-handling.md +2 -0
  77. package/dist/docs/guides/feature-matrix.md +7 -0
  78. package/dist/docs/guides/logging.md +2 -0
  79. package/dist/docs/guides/tracing.md +64 -0
  80. package/dist/docs/index.md +2 -1
  81. package/dist/docs/skills/SKILL.md +5 -3
  82. package/dist/docs/skills/api-surface.md +8 -0
  83. package/dist/docs/skills/auth-internals.md +4 -2
  84. package/dist/docs/skills/pre-flight.md +4 -0
  85. package/dist/docs/skills/routing-rules.md +3 -1
  86. package/dist/docs/skills/tasks-internals.md +12 -4
  87. package/dist/docs/skills/what-not-to-invent.md +2 -0
  88. package/dist/index.cjs +167 -71
  89. package/dist/index.cjs.map +1 -1
  90. package/dist/index.d.cts +5 -14
  91. package/dist/index.d.ts +5 -14
  92. package/dist/index.js +124 -27
  93. package/dist/index.js.map +1 -1
  94. package/dist/pgboss-backend-5DXF4G22.js +16 -0
  95. package/dist/pgboss-backend-KRTFHRNZ.cjs +16 -0
  96. package/dist/pgboss-backend-KRTFHRNZ.cjs.map +1 -0
  97. package/dist/registry/index.json +1 -1
  98. package/dist/tasks/index.cjs +3 -3
  99. package/dist/tasks/index.d.cts +2 -2
  100. package/dist/tasks/index.d.ts +2 -2
  101. package/dist/tasks/index.js +2 -1
  102. package/dist/testing.cjs +16 -14
  103. package/dist/testing.cjs.map +1 -1
  104. package/dist/testing.d.cts +2 -1
  105. package/dist/testing.d.ts +2 -1
  106. package/dist/testing.js +10 -7
  107. package/dist/testing.js.map +1 -1
  108. package/dist/thread-runner.cjs +5 -4
  109. package/dist/thread-runner.cjs.map +1 -1
  110. package/dist/thread-runner.d.cts +1 -1
  111. package/dist/thread-runner.d.ts +1 -1
  112. package/dist/thread-runner.js +4 -2
  113. package/dist/{types-D3QmZgeX.d.ts → types-Bgeqpm-n.d.cts} +12 -1
  114. package/dist/{types-D3QmZgeX.d.cts → types-Bgeqpm-n.d.ts} +12 -1
  115. package/package.json +7 -3
  116. package/dist/chunk-2IDRC7RK.js.map +0 -1
  117. package/dist/chunk-3SWI46YK.js +0 -74
  118. package/dist/chunk-3SWI46YK.js.map +0 -1
  119. package/dist/chunk-6WTMRZS7.cjs.map +0 -1
  120. package/dist/chunk-B6MB6HEG.js.map +0 -1
  121. package/dist/chunk-CGY7JU4Y.cjs.map +0 -1
  122. package/dist/chunk-DGYPIIJE.cjs.map +0 -1
  123. package/dist/chunk-DTMDJGRW.cjs.map +0 -1
  124. package/dist/chunk-EJDZZ4KX.js.map +0 -1
  125. package/dist/chunk-GWMW6XY7.cjs.map +0 -1
  126. package/dist/chunk-H2PVWCWC.cjs.map +0 -1
  127. package/dist/chunk-IEF6AEK3.cjs.map +0 -1
  128. package/dist/chunk-LECHRAU3.js.map +0 -1
  129. package/dist/chunk-OM2XJJWX.js.map +0 -1
  130. package/dist/chunk-QSIP7YLW.cjs.map +0 -1
  131. package/dist/chunk-R6GPQZLI.js.map +0 -1
  132. package/dist/chunk-RPL2IFWK.cjs +0 -77
  133. package/dist/chunk-RPL2IFWK.cjs.map +0 -1
  134. package/dist/pgboss-backend-PQW6I3VF.js +0 -14
  135. package/dist/pgboss-backend-QVXISTLP.cjs +0 -15
  136. package/dist/pgboss-backend-QVXISTLP.cjs.map +0 -1
  137. /package/dist/{chunk-JBOMTZT5.js.map → chunk-3JQWQF2M.js.map} +0 -0
  138. /package/dist/{chunk-O2E7H2XA.js.map → chunk-BCSJOPYH.js.map} +0 -0
  139. /package/dist/{pgboss-backend-PQW6I3VF.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.
@@ -369,3 +369,7 @@ On a worker, the signal closes the HTTP server (in-flight requests finish), drai
369
369
  ## Since 0.11.0: OpenAPI and WebSockets
370
370
 
371
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.
374
+
375
+ Routes with HTTP handlers return 405 and an `Allow` header for unsupported methods, including `TRACE` and `PROPFIND` when all seven export names are implemented. Unknown paths remain 404; WebSocket upgrades use their own pipeline. See [file-based routing](../core-concepts/file-based-routing.md).
@@ -10,7 +10,7 @@ import { defineTask, enqueue } from 'express-file-cluster/tasks';
10
10
 
11
11
  ## `defineTask(handler)` / `defineTask(options, handler)`
12
12
 
13
- Creates a `TaskDefinition`. The file's default export must be a `TaskDefinition` for EFC to register the task.
13
+ Creates a `TaskDefinition`. EFC scans top-level `.ts`, `.js`, `.mts`, and `.mjs` task files and registers those whose default export is a `TaskDefinition`. `efc tasks` lists matching filenames without importing them.
14
14
 
15
15
  ```ts
16
16
  // Overloads
@@ -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). It never waits indefinitely, and a rejected job is not queued later behind your back, so it is safe to retry or return a 503.
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.
@@ -26,3 +26,5 @@ The CommonJS `/testing` entry delegates to the ESM helper using native `import()
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
27
 
28
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.
@@ -140,7 +140,7 @@ Wrong answers are asked again. A question is only asked for a variable the app d
140
140
 
141
141
  ```json
142
142
  {
143
- "registry": "0.11.0",
143
+ "registry": "0.12.0",
144
144
  "language": "typescript",
145
145
  "database": "postgresql",
146
146
  "modelApi": "defineTable",
@@ -36,7 +36,7 @@ Static routes appear before dynamic routes (routes with `:param` segments), matc
36
36
 
37
37
  ## `efc tasks`
38
38
 
39
- Lists the background tasks found in `src/tasks/`.
39
+ Lists the top-level `.ts`, `.js`, `.mts`, and `.mjs` task files without loading their modules.
40
40
 
41
41
  ```bash
42
42
  efc tasks
@@ -41,7 +41,7 @@ npm install --save-dev express-file-cluster
41
41
  | `efc db seed [name]` | Run seed scripts |
42
42
  | `efc db studio` | Read-only database browser on 127.0.0.1 |
43
43
  | `efc routes` | Print the resolved route table |
44
- | `efc tasks` | List registered background tasks |
44
+ | `efc tasks` | List task names from supported files without importing them |
45
45
  | `efc tasks failed \| retry \| purge` | Inspect and act on dead-lettered jobs |
46
46
  | `efc doctor` | Validate config, env vars, and project setup |
47
47
  | `efc --version` | Print the installed version |
@@ -19,6 +19,8 @@ EFC does not hand-roll the queue. Persistence, retries, backoff, dead-lettering,
19
19
 
20
20
  ## Defining a task
21
21
 
22
+ Task discovery recognizes top-level `.ts`, `.js`, `.mts`, and `.mjs` files. Use `efc tasks` to list their names without running the modules.
23
+
22
24
  ### I/O-bound task
23
25
 
24
26
  ```ts
@@ -120,7 +122,7 @@ export const POST = async (req: Request, res: Response) => {
120
122
  `enqueue(name, payload)` rejects if:
121
123
  - The task backend has not been initialised (missing `tasks` config in `ignite()`).
122
124
  - 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, and the rejected job is not silently queued later.
125
+ - 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
126
 
125
127
  ---
126
128
 
@@ -229,3 +231,7 @@ import { enqueue } from 'express-file-cluster/tasks';
229
231
  ```
230
232
 
231
233
  Both are exported from the `tasks` sub-path export of `express-file-cluster`.
234
+
235
+ 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.
236
+
237
+ 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.
@@ -80,6 +80,8 @@ Content-Type: application/json
80
80
 
81
81
  ---
82
82
 
83
+ This includes methods outside the seven supported export names, such as `TRACE` and `PROPFIND`, even when all seven handlers are exported. Unknown paths still return 404; WebSocket upgrades continue through their own pipeline.
84
+
83
85
  ## Dynamic parameters
84
86
 
85
87
  ```ts
@@ -237,3 +239,5 @@ export const GET = async (req, res) => {
237
239
  `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
240
 
239
241
  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.
242
+
243
+ 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.
@@ -65,3 +65,10 @@ What each model API does on which engine — and the test that proves it. Every
65
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
66
 
67
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,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).
@@ -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.11.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.
5
+ > **Status: v0.12.1 — 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
 
@@ -51,6 +51,7 @@
51
51
  | [OpenAPI (since 0.11.0)](./guides/openapi.md) | Opt-in OpenAPI JSON from route metadata and request schemas |
52
52
  | [WebSockets (since 0.11.0)](./guides/websockets.md) | WS file exports, middleware/auth, limits and shutdown |
53
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 |
54
55
  | [Logging](./guides/logging.md) | pino, request IDs, `getLogger()` |
55
56
  | [Caching & Sessions](./guides/caching.md) | `cache`, `cacheResponse`, revoking JWT sessions |
56
57
  | [Generated Portals](./guides/generated-portals.md) | Every model and route `create-efc-app` scaffolds for the User/Admin portals |
@@ -37,14 +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.11.0 — Beta, Phase 2 complete + defineTable with relations + generated migrations + `efc add` registry)
40
+ ## Status (v0.12.1 — 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+):** plugins, OpenTelemetry, `efc lint`, `efc deploy`.
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 a separate Phase 3 task.
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
49
 
50
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.
@@ -356,3 +356,11 @@ Main exports: `generateOpenAPI(routes: MountedRoute[] | string, options?: OpenAP
356
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
357
 
358
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
- That's the entire implementation. Clears the cookie. The JWT itself is not invalidated — use `revokeSession` for that.
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.
@@ -148,3 +148,7 @@ const clusterEnabled = config.cluster ?? (process.env['NODE_ENV'] === 'productio
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
149
 
150
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.
@@ -65,7 +65,7 @@ For each route module:
65
65
  4. Register: `app[method](pattern ?? urlPath, ...paramMapper?, ...middlewares, validate?, asyncWrap(handler))`.
66
66
  `validate` exists when `schema` has an entry for that method (method key wins over file-wide
67
67
  `{ params, query, body }`). It runs AFTER middlewares; failure → 400 with `issues`.
68
- 5. If **any** methods are implemented and **any** are unimplemented: register `app.all(urlPath, ...)` that returns 405 with `Allow: <implemented>` for the missing methods.
68
+ 5. If **any** HTTP methods are implemented, register `app.all(pattern ?? urlPath, ...)` that returns 405 with `Allow: <implemented>` for unsupported methods, including `TRACE` and `PROPFIND`, even when all seven export names are implemented. WebSocket upgrades pass through.
69
69
 
70
70
  **asyncWrap**: `Promise.resolve(handler(req, res, next)).catch(next)` — all route errors auto-forwarded.
71
71
 
@@ -116,3 +116,5 @@ Header: `Allow: GET, POST` (only the implemented methods).
116
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
117
 
118
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.
@@ -14,7 +14,7 @@ tasksDir/ResizeImage.ts → name: "ResizeImage"
14
14
  tasksDir/jobs/DoWork.ts → ERROR — scanTasks only reads top-level files
15
15
  ```
16
16
 
17
- `scanTasks` uses `fs.readdirSync(tasksDir)` (non-recursive). **Sub-directories in `tasksDir` are not scanned.**
17
+ `scanTasks` and `efc tasks` share top-level discovery for `.ts`, `.js`, `.mts`, and `.mjs` files. Only the runtime scanner imports the modules.
18
18
 
19
19
  ---
20
20
 
@@ -46,7 +46,7 @@ export default async function(payload: Payload) { ... }
46
46
 
47
47
  ```
48
48
  scanTasks(tasksDir)
49
- → fs.readdirSync(tasksDir).filter(f => /\.(ts|js|mts|mjs)$/.test(f))
49
+ → listTaskFiles(tasksDir)
50
50
  → for each file:
51
51
  mod = await import(filePath)
52
52
  def = mod.default as TaskDefinition
@@ -77,7 +77,7 @@ if (!def) throw Error(`[EFC] Cannot enqueue unknown task: "${name}"...`)
77
77
 
78
78
  So `enqueue` throws for both "no backend" and "unknown task name".
79
79
 
80
- It also rejects when Redis is unreachable: the Queue's ioredis connection has `enableOfflineQueue: false`, and `waitUntilReady()` + `queue.add()` is raced against `tasks.enqueueTimeout` (default 5000 ms). Message: `[EFC] Cannot enqueue task "X": Redis at host:port did not respond within Nms`. A rejected job is never queued later.
80
+ It also rejects when Redis is unreachable: the Queue's ioredis connection has `enableOfflineQueue: false`, and `waitUntilReady()` + `queue.add()` is raced against `tasks.enqueueTimeout` (default 5000 ms). Message: `[EFC] Cannot enqueue task "X": Redis at host:port did not respond within Nms`. An expired readiness wait cannot submit later. An already-sent backend command has an uncertain outcome on timeout/disconnect; handlers must be idempotent before retrying.
81
81
 
82
82
  ---
83
83
 
@@ -162,7 +162,7 @@ Defaults: `host: 'localhost'`, `port: 6379`. User/password are URI-decoded.
162
162
  - `new PgBoss({ connectionString: tasks.connectionString ?? databaseUrl, schema? })`, `start()`.
163
163
  - One pg-boss queue per task, named `<tasks.queue>.<TaskName>` (default prefix `efc`); `createQueue` is idempotent.
164
164
  - `retryLimit = retries` (pg-boss counts re-runs, like EFC), `retryDelay: 1`, `retryBackoff` for exponential.
165
- - Non-object payloads are boxed as `{ __efcValue: payload }` and unboxed for the handler.
165
+ - Non-object/reserved-key payloads use a versioned internal wrapper; application objects with `__efcValue` survive unchanged. Old one-key primitive boxes remain readable.
166
166
  - `enqueue` = `boss.send(...)` raced against `enqueueTimeout`.
167
167
 
168
168
  ## Dead letters (`tasks/admin.ts`, CLI `efc tasks failed|retry|purge`)
@@ -171,3 +171,11 @@ Defaults: `host: 'localhost'`, `port: 6379`. User/password are URI-decoded.
171
171
  BullMQ: `queue.getFailed`, `job.retry('failed')`, `job.remove()`. pg-boss: reads `pgboss.job WHERE state='failed'`,
172
172
  then `boss.retry` / `boss.deleteJob`. A retried job gets exactly one more attempt on both backends.
173
173
  CLI picks BullMQ when `REDIS_URL` is set, else pg-boss for a `postgres` `DATABASE_URL`; `--backend/--queue` override.
174
+
175
+ Since 0.12.0 tracing: `tracing: true`/`{tasks:true}` enables native BullMQ telemetry (minimum 5.79.1) or pg-boss openTelemetry + propagateContext (minimum 12.38.0), using W3C trace-only metadata without changing payloads. Retries have separate consumer spans; cron runs have no boot-time parent. Task handlers get a fresh EFC auth/request scope. Thread consumer spans export on the queue worker; W3C context crosses thread/nested-enqueue messages without copying the SDK.
176
+
177
+ The task registry and enqueue implementation share process state across the package’s ESM/CJS exports; the worker-thread enqueue bridge stays isolate-local.
178
+
179
+ Hardening: thread completion waits for pending bridge acknowledgments and terminates the owned isolate; any exit before completion rejects, including exit code 0. Ignore unrelated progress messages. pg-boss null send acknowledgments reject. Async file/global middleware and custom error handlers are promise-aware. Shutdown waits for all task drains before cache, then telemetry; failures aggregate and exit nonzero.
180
+
181
+ 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.
@@ -277,3 +277,5 @@ const conn = db.model('User') // throws: db not ready
277
277
  ```
278
278
 
279
279
  Since 0.11.0, WebSockets and OpenAPI are implemented. Read the new guides/API references before using them. Use `WS` file exports and `ignite({openapi})`/`generateOpenAPI`, with the four existing import paths only. No Socket.IO protocol, cross-worker broadcast bus, message-schema validator, Swagger UI, or automatic auth-policy inference is provided.
280
+
281
+ Since 0.12.0 tracing exception: HTTP/task instrumentation exists behind `tracing`, with app-owned SDK/exporter/context manager. No EFC OTLP endpoint/env config, auto-instrumentation installer, message tracing, SQL tracing or baggage propagation is supplied.