express-file-cluster 0.3.15 → 0.7.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.
Files changed (116) hide show
  1. package/README.md +71 -33
  2. package/dist/auth/index.cjs +12 -2
  3. package/dist/auth/index.cjs.map +1 -1
  4. package/dist/auth/index.d.cts +13 -2
  5. package/dist/auth/index.d.ts +13 -2
  6. package/dist/auth/index.js +12 -2
  7. package/dist/chunk-277BSYVH.js +127 -0
  8. package/dist/chunk-277BSYVH.js.map +1 -0
  9. package/dist/chunk-6OGOVV57.js +3847 -0
  10. package/dist/chunk-6OGOVV57.js.map +1 -0
  11. package/dist/chunk-7YEX4MQV.cjs +38 -0
  12. package/dist/chunk-7YEX4MQV.cjs.map +1 -0
  13. package/dist/chunk-AZYXQU3Z.cjs +3847 -0
  14. package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
  15. package/dist/chunk-BUBXO7WU.js +170 -0
  16. package/dist/chunk-BUBXO7WU.js.map +1 -0
  17. package/dist/chunk-LJNSJFOL.js +38 -0
  18. package/dist/chunk-LJNSJFOL.js.map +1 -0
  19. package/dist/chunk-MGH4VDV3.cjs +170 -0
  20. package/dist/chunk-MGH4VDV3.cjs.map +1 -0
  21. package/dist/chunk-R34R7QPD.cjs +116 -0
  22. package/dist/chunk-R34R7QPD.cjs.map +1 -0
  23. package/dist/chunk-RS4MXCPW.js +116 -0
  24. package/dist/chunk-RS4MXCPW.js.map +1 -0
  25. package/dist/chunk-T4OHFU5T.cjs +154 -0
  26. package/dist/chunk-T4OHFU5T.cjs.map +1 -0
  27. package/dist/chunk-TI24L4XE.cjs.map +1 -1
  28. package/dist/chunk-TRC4DUZB.js +438 -0
  29. package/dist/chunk-TRC4DUZB.js.map +1 -0
  30. package/dist/chunk-TYR2GZZE.cjs +196 -0
  31. package/dist/chunk-TYR2GZZE.cjs.map +1 -0
  32. package/dist/chunk-UBQYQPBU.js +154 -0
  33. package/dist/chunk-UBQYQPBU.js.map +1 -0
  34. package/dist/chunk-UTM4PEVG.js +196 -0
  35. package/dist/chunk-UTM4PEVG.js.map +1 -0
  36. package/dist/chunk-YL37D6KM.cjs +127 -0
  37. package/dist/chunk-YL37D6KM.cjs.map +1 -0
  38. package/dist/chunk-ZDM5JHVK.cjs +438 -0
  39. package/dist/chunk-ZDM5JHVK.cjs.map +1 -0
  40. package/dist/cli/db-runner.cjs +497 -0
  41. package/dist/cli/db-runner.cjs.map +1 -0
  42. package/dist/cli/db-runner.d.cts +2 -0
  43. package/dist/cli/db-runner.d.ts +2 -0
  44. package/dist/cli/db-runner.js +497 -0
  45. package/dist/cli/db-runner.js.map +1 -0
  46. package/dist/cli/index.cjs +447 -69
  47. package/dist/cli/index.cjs.map +1 -1
  48. package/dist/cli/index.js +473 -95
  49. package/dist/cli/index.js.map +1 -1
  50. package/dist/docs/api-reference/auth.md +232 -0
  51. package/dist/docs/api-reference/compose.md +78 -0
  52. package/dist/docs/api-reference/db.md +351 -0
  53. package/dist/docs/api-reference/http-error.md +109 -0
  54. package/dist/docs/api-reference/ignite.md +326 -0
  55. package/dist/docs/api-reference/table.md +458 -0
  56. package/dist/docs/api-reference/tasks.md +140 -0
  57. package/dist/docs/cli/db.md +38 -0
  58. package/dist/docs/cli/diagnostics.md +145 -0
  59. package/dist/docs/cli/generate.md +120 -0
  60. package/dist/docs/cli/index.md +48 -0
  61. package/dist/docs/cli/start.md +112 -0
  62. package/dist/docs/contributing/index.md +139 -0
  63. package/dist/docs/core-concepts/background-tasks.md +228 -0
  64. package/dist/docs/core-concepts/clustering.md +114 -0
  65. package/dist/docs/core-concepts/file-based-routing.md +235 -0
  66. package/dist/docs/core-concepts/index.md +79 -0
  67. package/dist/docs/core-concepts/middleware.md +144 -0
  68. package/dist/docs/getting-started/index.md +91 -0
  69. package/dist/docs/getting-started/project-structure.md +154 -0
  70. package/dist/docs/guides/ai-agents.md +48 -0
  71. package/dist/docs/guides/authentication.md +196 -0
  72. package/dist/docs/guides/caching.md +124 -0
  73. package/dist/docs/guides/database.md +217 -0
  74. package/dist/docs/guides/deployment.md +171 -0
  75. package/dist/docs/guides/environment-variables.md +106 -0
  76. package/dist/docs/guides/error-handling.md +172 -0
  77. package/dist/docs/guides/generated-portals.md +115 -0
  78. package/dist/docs/guides/logging.md +108 -0
  79. package/dist/docs/guides/mailer.md +166 -0
  80. package/dist/docs/guides/migrations.md +106 -0
  81. package/dist/docs/guides/rbac.md +89 -0
  82. package/dist/docs/guides/validation.md +95 -0
  83. package/dist/docs/index.md +93 -0
  84. package/dist/docs/skills/SKILL.md +44 -0
  85. package/dist/docs/skills/api-surface.md +309 -0
  86. package/dist/docs/skills/auth-internals.md +141 -0
  87. package/dist/docs/skills/pre-flight.md +142 -0
  88. package/dist/docs/skills/routing-rules.md +114 -0
  89. package/dist/docs/skills/tasks-internals.md +172 -0
  90. package/dist/docs/skills/what-not-to-invent.md +251 -0
  91. package/dist/index.cjs +264 -391
  92. package/dist/index.cjs.map +1 -1
  93. package/dist/index.d.cts +699 -7
  94. package/dist/index.d.ts +699 -7
  95. package/dist/index.js +258 -385
  96. package/dist/index.js.map +1 -1
  97. package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
  98. package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
  99. package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
  100. package/dist/pgboss-backend-TCHI7CHM.cjs.map +1 -0
  101. package/dist/tasks/index.cjs.map +1 -1
  102. package/dist/tasks/index.d.cts +1 -1
  103. package/dist/tasks/index.d.ts +1 -1
  104. package/dist/types-B6lVw4bj.d.cts +588 -0
  105. package/dist/types-B6lVw4bj.d.ts +588 -0
  106. package/package.json +28 -5
  107. package/dist/chunk-6522HS2J.cjs +0 -99
  108. package/dist/chunk-6522HS2J.cjs.map +0 -1
  109. package/dist/chunk-DGVOJNR6.cjs +0 -55
  110. package/dist/chunk-DGVOJNR6.cjs.map +0 -1
  111. package/dist/chunk-KOHLLUN7.js +0 -55
  112. package/dist/chunk-KOHLLUN7.js.map +0 -1
  113. package/dist/chunk-VIP3PFWZ.js +0 -99
  114. package/dist/chunk-VIP3PFWZ.js.map +0 -1
  115. package/dist/types-BusbSenn.d.cts +0 -162
  116. package/dist/types-BusbSenn.d.ts +0 -162
@@ -0,0 +1,141 @@
1
+ # EFC — Auth Internals (Exact)
2
+
3
+ Source: `packages/core/src/auth/index.ts`
4
+
5
+ ---
6
+
7
+ ## Configuration (happens in Pre-Flight)
8
+
9
+ ```ts
10
+ // Called by ignite() at Pre-Flight step 2
11
+ configureAuth({
12
+ secret: jwtSecret,
13
+ strategy: authStrategy, // 'http-only' | 'localStorage'
14
+ expiresIn: JWT_EXPIRES_IN ?? '7d',
15
+ cookieDomain: COOKIE_DOMAIN, // optional
16
+ })
17
+ ```
18
+
19
+ `_config` is a module-level singleton. All auth functions throw `'[EFC] Auth not configured — pass jwtSecret to ignite()'` if called before `configureAuth`.
20
+
21
+ ---
22
+
23
+ ## `issueToken(res, payload)`
24
+
25
+ ```ts
26
+ // Signs JWT (HS256), sets HttpOnly cookie
27
+ const token = await new SignJWT(payload)
28
+ .setProtectedHeader({ alg: 'HS256' })
29
+ .setExpirationTime(expiresIn)
30
+ .sign(new TextEncoder().encode(secret))
31
+
32
+ res.cookie('efc_token', token, {
33
+ httpOnly: true,
34
+ secure: process.env['NODE_ENV'] === 'production',
35
+ sameSite: 'strict',
36
+ ...(cookieDomain && { domain: cookieDomain }),
37
+ })
38
+ ```
39
+
40
+ Cookie name: exactly `'efc_token'` (hardcoded).
41
+ `secure` is only set in production. In dev, the cookie is sent over HTTP.
42
+ **Does NOT set `path` explicitly** — defaults to `/`.
43
+ **Does NOT set `maxAge` or `expires`** — cookie is session-scoped (expires when browser closes), but the JWT itself has an expiry enforced server-side by `jwtVerify`.
44
+
45
+ ---
46
+
47
+ ## `revokeToken(res)`
48
+
49
+ ```ts
50
+ res.clearCookie('efc_token')
51
+ ```
52
+
53
+ That's the entire implementation. Clears the cookie. The JWT itself is not invalidated — use `revokeSession` for that.
54
+
55
+ ---
56
+
57
+ ## Session revocation (`revokeSession`, `revokeAllSessions`) — needs `cache`
58
+
59
+ Every signed token now carries `jti` (randomUUID), `iat`, and `efc_iat` (ms) — via the shared `sign()` used by
60
+ both `issueToken` and `signToken`.
61
+
62
+ - `revokeSession(req, res?)`: verifies the request's token, sets cache key `sess:jti:<jti>` with TTL = `exp - now`;
63
+ clears the cookie when `res` is given and strategy is http-only. Throws if no cache / cache unreachable.
64
+ - `revokeAllSessions(userId)`: sets `sess:user:<id>` = `Date.now()` with TTL = `jwtExpiresIn` in seconds.
65
+ - `requireAuth` (only when a cache is configured): after `jwtVerify`, rejects with 401 if `sess:jti:<jti>` exists,
66
+ or if `efc_iat` (fallback `iat*1000`) < the user's cutoff. User id = `payload.sub ?? payload.id`.
67
+ If the cache read throws → `cache.onRevocationCheckError`: `'reject'` (default) → **503**
68
+ `{ error: 'Service Unavailable', statusCode: 503 }`; `'allow'` → request passes. Logged at most every 30 s.
69
+
70
+ ---
71
+
72
+ ## `signToken(payload)`
73
+
74
+ ```ts
75
+ // Signs JWT, returns string (no cookie)
76
+ return await new SignJWT(payload)
77
+ .setProtectedHeader({ alg: 'HS256' })
78
+ .setExpirationTime(expiresIn)
79
+ .sign(new TextEncoder().encode(secret))
80
+ ```
81
+
82
+ No `res` argument. Token must be sent in the response body by the route handler.
83
+
84
+ ---
85
+
86
+ ## `requireAuth` — middleware internals
87
+
88
+ `requireAuth` is dual-purpose, dispatched at runtime on the first argument:
89
+
90
+ ```ts
91
+ // Bare — Express calls it as (req, res, next). First arg is an object → auth-only path.
92
+ export const middlewares = [requireAuth];
93
+
94
+ // Role-checked — called by user code with string args first, returns a new
95
+ // RequestHandler that Express later invokes as (req, res, next).
96
+ export const middlewares = [requireAuth('admin')]; // any of these roles
97
+ export const middlewares = [requireAuth('user', 'admin')]; // multiple allowed
98
+ ```
99
+
100
+ ```ts
101
+ // Strategy 'http-only': reads req.cookies.efc_token
102
+ // Strategy 'localStorage': reads Authorization header → strips 'Bearer '
103
+
104
+ if (!token) → res.status(401).json({ error: 'Unauthorized' }); return
105
+
106
+ const { payload } = await jwtVerify(token, new TextEncoder().encode(secret))
107
+
108
+ // only when called with role names:
109
+ if (roles.length > 0 && !roles.includes(payload.role)) →
110
+ res.status(403).json({ error: 'Forbidden' }); return
111
+
112
+ (req as any).user = payload // ← attaches to req.user
113
+ next()
114
+ ```
115
+
116
+ On any auth error (expired, invalid signature, malformed, missing token): catches and returns `{ error: 'Unauthorized' }` with status 401. A role mismatch returns `{ error: 'Forbidden' }` with status 403 instead. **Does NOT call next(err)** in either case — it handles the response itself and returns.
117
+
118
+ `req.user` is typed as `unknown` in the source. Cast to your payload type or use `(req as any).user`.
119
+
120
+ ---
121
+
122
+ ## JWT library
123
+
124
+ Uses `jose` (not `jsonwebtoken`). Key is UTF-8 encoded via `new TextEncoder().encode(secret)` before every call — no pre-computed key object is cached between requests.
125
+
126
+ ---
127
+
128
+ ## Token expiry
129
+
130
+ `expiresIn` is passed into `configureAuth` as a plain string by `ignite()` (`config.jwtExpiresIn ?? '7d'`) — `configureAuth` itself never touches `process.env`. All tokens issued in the same process lifetime use the same expiry value.
131
+
132
+ Format accepted by `jose`: `'15m'`, `'1h'`, `'7d'`, `'30d'`, integer seconds, etc.
133
+
134
+ ---
135
+
136
+ ## What auth does NOT do
137
+
138
+ - No refresh tokens in the framework itself (the scaffolder can generate an app-level `/auth/refresh` route backed by a DB-stored token — that's app code, not a core export).
139
+ - No revocation without a `cache` configured (then `revokeToken` just clears the cookie and a copied token stays valid until it expires). With a cache: `revokeSession` / `revokeAllSessions`.
140
+ - No CSRF token — relies on `SameSite: Strict` for http-only strategy.
141
+ - No multi-strategy per-route override — `authStrategy` is global, set once in `ignite()`.
@@ -0,0 +1,142 @@
1
+ # EFC — Pre-Flight Lifecycle (Exact)
2
+
3
+ Source: `packages/core/src/index.ts` — `ignite()` function, worker branch.
4
+
5
+ This is the exact order of operations inside every worker process (or the single process when `cluster: false`).
6
+
7
+ ---
8
+
9
+ ## Step-by-step sequence
10
+
11
+ ```
12
+ ignite() called
13
+ │
14
+ ├─ cluster.isPrimary && cluster enabled?
15
+ │ YES → runMaster() → fork workers → return undefined (master exits here)
16
+ │ NO → continue as worker
17
+ │
18
+ ▼
19
+ 0. configureLogger(config.logging) (runs before the primary/worker split)
20
+
21
+ 1. Create Express app
22
+ - Wrap every request in an AsyncLocalStorage context
23
+ - requestLogger(): X-Request-Id → req.id / req.log / getLogger(); one log line per response
24
+ - requestTimeout → 408 middleware (if set)
25
+ - Apply CORS middleware (from config.cors — ignite() never reads CORS_ORIGINS itself)
26
+ - Apply express.json()
27
+ - Apply express.urlencoded({ extended: true })
28
+ - Apply cookieParser()
29
+ - Apply globalMiddlewares[] (from config)
30
+
31
+ 2. Connect Database [database = config.database ?? scheme of databaseUrl]
32
+ - setDbEngine(database) → decides what defineModel compiles to (mongoose / Drizzle)
33
+ - mongodb: connectMongo(url) → setDbClient(mongoose.connection)
34
+ - postgresql: connectPostgres(url) → pg Pool (+ Drizzle) → setDbClient(pool)
35
+ - db proxy is now live. Models compile lazily on first use.
36
+
37
+ 3. Configure Auth [if jwtSecret is set]
38
+ - configureAuth({ secret, strategy, expiresIn, cookieDomain? })
39
+ - issueToken / requireAuth / signToken are now usable
40
+
41
+ 4. Scan + Register Tasks [src/tasks by convention — there is no tasksDir option]
42
+ - scanTasks(tasksDir)
43
+ - Walks tasksDir, imports each file, reads default export
44
+ - Calls registerTask(basename, definition) for each valid TaskDefinition
45
+
46
+ 5. Start Task Queue Backend [if config.tasks is set]
47
+ - backend === 'bullmq' → initBullMQ({ redisUrl, concurrency, enqueueTimeout, queue })
48
+ - Queue(queue) with enableOfflineQueue: false; Worker(queue, processor)
49
+ - cron schedulers reconciled in the BACKGROUND (Redis outage can't block boot)
50
+ - backend === 'pg-boss' → initPgBoss({ connectionString ?? databaseUrl, ... })
51
+ - one pg-boss queue per task: `<queue>.<Task>`; work() + schedule() per task
52
+ - setEnqueueImpl(...) → enqueue() is now usable
53
+
54
+ 6. Scan Routes
55
+ - scanDir(apiDir) → RouteEntry[]
56
+ - File → URL transformation (see routing-rules.md)
57
+ - Per-segment specificity sort
58
+
59
+ 7. Mount Routes
60
+ - mountRoutes(app, routes)
61
+ - Dynamic import of each route module
62
+ - Register handlers on Express
63
+
64
+ 8. Register error handler [onError if provided, else built-in]
65
+
66
+ 9. app.listen(port)
67
+ - Resolves Promise<http.Server> on 'listening' event
68
+ - Logs: Worker <id> listening on :<port>
69
+ ```
70
+
71
+ ---
72
+
73
+ ## Key invariants
74
+
75
+ - **Steps 2–5 run BEFORE routes are mounted.** By the time a handler executes, `db` is live and `enqueue()` works.
76
+ - **Each worker runs all 8 steps independently.** Workers never share DB connections or task registry state.
77
+ - **`cluster: false` is identical** — the same 8 steps run in the single process, skipping the fork branch.
78
+ - **`cluster: true` + `cluster.isPrimary`** — the master process does NOTHING after `runMaster()`. It forks workers and watches `exit` events. It does not run Pre-Flight.
79
+
80
+ ---
81
+
82
+ ## `runMaster()` (cluster/index.ts)
83
+
84
+ ```ts
85
+ runMaster({ workers, onWorkerReady, onWorkerCrash })
86
+ → cluster.fork() × workers
87
+ → cluster.on('online', worker => onWorkerReady?.(worker.id))
88
+ → cluster.on('exit', (worker, code, signal) => {
89
+ if (!isShuttingDown) {
90
+ onWorkerCrash?.(worker.id, code ?? -1)
91
+ cluster.fork() // immediate respawn, no delay
92
+ }
93
+ })
94
+ ```
95
+
96
+ The master never calls `app.listen()`. If `ignite()` is called in the primary process, it returns `undefined` — not a server.
97
+
98
+ ---
99
+
100
+ ## `gracefulShutdown()` — shutdown path
101
+
102
+ ```
103
+ SIGTERM or SIGINT received
104
+ │
105
+ ├─ already shutting down? → ignore (repeat signals must not kill a draining worker)
106
+ │
107
+ ├─ server is defined (worker or single-process)
108
+ │ → server.closeIdleConnections()
109
+ │ → server.close(() => closeBullMQ() + closePgBoss() → process.exit(0))
110
+ │ → setTimeout(force process.exit(1), timeoutMs) // default 10s
111
+ │
112
+ └─ server is undefined (primary)
113
+ → shutdownMaster(): isShuttingDown = true, SIGTERM relayed to every worker
114
+ (docker stop / k8s only signal PID 1)
115
+ → primary exits when all workers have; force-exit after timeoutMs + 2s
116
+ ```
117
+
118
+ ---
119
+
120
+ ## Port resolution (exact precedence)
121
+
122
+ ```
123
+ 1. config.port (if provided and not NaN)
124
+ 2. 3000 (hardcoded default)
125
+ ```
126
+
127
+ `ignite()` never reads `process.env.PORT` itself — pass it explicitly (typically via `efc.config.ts`: `port: process.env.PORT ? Number(process.env.PORT) : undefined`).
128
+
129
+ ---
130
+
131
+ ## Cluster enable/disable logic (exact)
132
+
133
+ ```ts
134
+ const clusterEnabled = config.cluster ?? (process.env['NODE_ENV'] === 'production');
135
+ ```
136
+
137
+ - `config.cluster` is `undefined` AND `NODE_ENV !== 'production'` → **clustering OFF** (dev default)
138
+ - `config.cluster` is `undefined` AND `NODE_ENV === 'production'` → **clustering ON**
139
+ - `config.cluster: true` → **ON** regardless of NODE_ENV
140
+ - `config.cluster: false` → **OFF** regardless of NODE_ENV
141
+
142
+ `efc start dev` sets `NODE_ENV=development` → clustering is automatically off in dev.
@@ -0,0 +1,114 @@
1
+ # EFC — Routing Rules (Exact)
2
+
3
+ Source: `packages/core/src/router/scan.ts` + `packages/core/src/router/mount.ts`
4
+
5
+ ---
6
+
7
+ ## File → URL transformation (exact algorithm)
8
+
9
+ ```
10
+ scan.ts: filePathToUrlPath(relativePath)
11
+
12
+ 1. Strip extension (.ts | .js | .mts | .mjs | .cts | .cjs)
13
+ 2. Strip /index (trailing /index becomes '')
14
+ 3. Per segment:
15
+ [[...name]] → :name*? optional catch-all (≥0 segments)
16
+ [...name] → :name* catch-all (≥1 segment)
17
+ [[name]] → :name? optional
18
+ [name] → :name dynamic (also inside a segment: post-[id] → post-:id)
19
+ 4. If result is '' → '/'
20
+ 5. Prepend '/'
21
+ ```
22
+
23
+ A catch-all must be the LAST segment — `[...slug]/edit.ts` throws at startup. Catch-all
24
+ routes mount on a compiled RegExp (`RouteEntry.pattern`); a mapper restores named params,
25
+ and catch-all values arrive as `string[]` (URI-decoded; `[]` when an optional one is empty).
26
+
27
+ ### Examples derived from the exact regex
28
+
29
+ | File (relative to apiDir) | URL |
30
+ |---|---|
31
+ | `/health.ts` | `/health` |
32
+ | `/users/index.ts` | `/users` |
33
+ | `/users/[id].ts` | `/users/:id` |
34
+ | `/posts/[slug]/comments.ts` | `/posts/:slug/comments` |
35
+ | `/index.ts` | `/` |
36
+ | `/auth/login.ts` | `/auth/login` |
37
+ | `/a/[b]/[c].ts` | `/a/:b/:c` |
38
+ | `/users/[[id]].ts` | `/users/:id?` (matches `/users` and `/users/7`) |
39
+ | `/docs/[...slug].ts` | `/docs/:slug*` (`/docs/a/b` → `slug: ['a','b']`; not `/docs`) |
40
+ | `/docs/[[...slug]].ts` | `/docs/:slug*?` (also `/docs` → `slug: []`) |
41
+
42
+ **Edge case:** `/users/index.ts` → strips extension → `/users/index` → strips `/index` → `/users`. NOT `/users/`. There is no trailing slash.
43
+
44
+ ---
45
+
46
+ ## Sorting: per-segment specificity
47
+
48
+ Each segment gets a rank — static 0, `[id]` 1, `[[id]]` 2, `[...slug]` 3, `[[...slug]]` 4 — and
49
+ routes are compared rank-by-rank from the first segment; ties sort alphabetically by URL.
50
+ So `/users/me` beats `/users/:id`, which beats `/users/:id?`, then `/users/:rest*`.
51
+
52
+ ---
53
+
54
+ ## Method dispatching (mount.ts)
55
+
56
+ Recognised method names (exact — case-sensitive uppercase):
57
+ ```
58
+ GET POST PUT PATCH DELETE HEAD OPTIONS
59
+ ```
60
+
61
+ For each route module:
62
+ 1. Import the module dynamically.
63
+ 2. Read `mod.middlewares` (must be an array, else ignored), `mod.schema`, `mod.meta`.
64
+ 3. For each of the 7 method names, check `typeof mod[METHOD] === 'function'`.
65
+ 4. Register: `app[method](pattern ?? urlPath, ...paramMapper?, ...middlewares, validate?, asyncWrap(handler))`.
66
+ `validate` exists when `schema` has an entry for that method (method key wins over file-wide
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.
69
+
70
+ **asyncWrap**: `Promise.resolve(handler(req, res, next)).catch(next)` — all route errors auto-forwarded.
71
+
72
+ ---
73
+
74
+ ## `middlewares` export rules
75
+
76
+ ```ts
77
+ export const middlewares = [mw1, mw2]; // ✅ valid — applied to all methods
78
+ export const middlewares = mw1; // ❌ ignored — must be an array
79
+ ```
80
+
81
+ The check in mount.ts: `Array.isArray(mod['middlewares'])`.
82
+
83
+ ---
84
+
85
+ ## Route file extensions accepted
86
+
87
+ ```
88
+ .ts .js .mts .mjs .cts .cjs
89
+ ```
90
+
91
+ Regex: `/\.(ts|js|mts|mjs|cts|cjs)$/`
92
+
93
+ Files that do NOT match this pattern are silently ignored by `scanDir`.
94
+
95
+ ---
96
+
97
+ ## What scanDir does NOT do
98
+
99
+ - Does NOT follow symlinks (uses `fs.readdirSync` with `withFileTypes`).
100
+ - Does NOT skip files named `index.ts` specially during scan — they are treated as routes whose URL resolves to the parent directory path.
101
+ - Does NOT support nested `index` files as catch-alls — only the exact directory name maps to the URL.
102
+ - Does NOT allow a catch-all anywhere but the last segment.
103
+
104
+ ---
105
+
106
+ ## 405 response format
107
+
108
+ ```json
109
+ { "error": "Method Not Allowed" }
110
+ ```
111
+
112
+ Header: `Allow: GET, POST` (only the implemented methods).
113
+
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.
@@ -0,0 +1,172 @@
1
+ # EFC — Task System Internals (Exact)
2
+
3
+ Source: `packages/core/src/tasks/`
4
+
5
+ ---
6
+
7
+ ## Task naming rule
8
+
9
+ **The task name is the file's basename without extension.** This is the only rule. No path, no directory, no subdirectory.
10
+
11
+ ```
12
+ tasksDir/SendEmail.ts → name: "SendEmail"
13
+ tasksDir/ResizeImage.ts → name: "ResizeImage"
14
+ tasksDir/jobs/DoWork.ts → ERROR — scanTasks only reads top-level files
15
+ ```
16
+
17
+ `scanTasks` uses `fs.readdirSync(tasksDir)` (non-recursive). **Sub-directories in `tasksDir` are not scanned.**
18
+
19
+ ---
20
+
21
+ ## `defineTask` — exact overloads
22
+
23
+ ```ts
24
+ // Overload 1: handler only
25
+ defineTask<T>(handler: (payload: T) => Promise<void>): TaskDefinition<T>
26
+
27
+ // Overload 2: options + handler
28
+ defineTask<T>(options: TaskOptions, handler: (payload: T) => Promise<void>): TaskDefinition<T>
29
+ ```
30
+
31
+ The returned `TaskDefinition` has `name: ''` — the name is set later by `registerTask()` when `scanTasks` processes the file.
32
+
33
+ **The `default` export must be a `TaskDefinition`**, not a plain function. `export default async (payload) => {}` will be rejected by `scanTasks` — it requires `def.handler` to be a function.
34
+
35
+ ```ts
36
+ // ✅ correct
37
+ export default defineTask<Payload>(async (payload) => { ... });
38
+
39
+ // ❌ wrong — scanTasks will warn and skip this file
40
+ export default async function(payload: Payload) { ... }
41
+ ```
42
+
43
+ ---
44
+
45
+ ## Task registration flow
46
+
47
+ ```
48
+ scanTasks(tasksDir)
49
+ → fs.readdirSync(tasksDir).filter(f => /\.(ts|js|mts|mjs)$/.test(f))
50
+ → for each file:
51
+ mod = await import(filePath)
52
+ def = mod.default as TaskDefinition
53
+ if (!def || typeof def.handler !== 'function') → warn + skip
54
+ registerTask(basename_without_ext, { ...def, filePath })
55
+ ```
56
+
57
+ `registerTask` stores to `taskRegistry: Map<string, TaskDefinition>`.
58
+
59
+ ---
60
+
61
+ ## `enqueue(name, payload)` — what it checks
62
+
63
+ ```ts
64
+ async function enqueue<T>(name: string, payload: T): Promise<void> {
65
+ if (!_impl) throw Error('[EFC] Task queue not initialised...')
66
+ return _impl(name, payload)
67
+ }
68
+ ```
69
+
70
+ `_impl` is set by `setEnqueueImpl()` called inside `initBullMQ()` or `initPgBoss()`. If `tasks` is not configured in `ignite()`, `_impl` is null and `enqueue()` always throws.
71
+
72
+ The BullMQ `_impl` also validates the name:
73
+ ```ts
74
+ const def = taskRegistry.get(name)
75
+ if (!def) throw Error(`[EFC] Cannot enqueue unknown task: "${name}"...`)
76
+ ```
77
+
78
+ So `enqueue` throws for both "no backend" and "unknown task name".
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.
81
+
82
+ ---
83
+
84
+ ## BullMQ queue name
85
+
86
+ The queue is named `'efc'` (hardcoded). All tasks share a single queue. The job `name` field is the task name (file basename).
87
+
88
+ ---
89
+
90
+ ## `thread: true` execution path
91
+
92
+ ```
93
+ enqueue('ResizeImage', payload)
94
+ → BullMQ picks up the job
95
+ → processor: def = taskRegistry.get(job.name)
96
+ → def.options.thread && def.filePath
97
+ YES → runInThread(def.filePath, job.data)
98
+ NO → def.handler(job.data)
99
+ ```
100
+
101
+ `runInThread` in `thread-runner.ts`:
102
+ - Spawns `new Worker(thread-runner.js, { workerData: { handlerPath, payload } })`
103
+ - Worker-side: imports `handlerPath`, reads `mod.default`, calls `def.handler(payload)`
104
+ - Resolves on `{ ok: true }`, rejects on `{ ok: false, error }`
105
+
106
+ `thread: true` requires `def.filePath` to be set. This is only guaranteed when the task was registered via `scanTasks` (which stores the file path). If you call `registerTask` manually without `filePath`, `thread: true` will silently fall through to the event loop (the `&&` short-circuits).
107
+
108
+ ---
109
+
110
+ ## Retry/backoff wiring (BullMQ)
111
+
112
+ ```ts
113
+ queue.add(name, payload, {
114
+ attempts: (def.options.retries ?? 3) + 1, // retries = re-runs; attempts counts the first run
115
+ backoff: {
116
+ type: def.options.backoff ?? 'exponential',
117
+ delay: 1000,
118
+ },
119
+ })
120
+ ```
121
+
122
+ `backoff.delay: 1000` is hardcoded (1 second base delay). Exponential: 1s, 2s, 4s, ...
123
+
124
+ ---
125
+
126
+ ## Redis URL parsing
127
+
128
+ Built-in `parseRedisUrl` in `bullmq-backend.ts`:
129
+ ```ts
130
+ // Parses: redis[s]://[user:password@]host[:port][/db]
131
+ { host, port, username?, password?, db?, tls? } // tls: {} for rediss://
132
+ ```
133
+
134
+ Defaults: `host: 'localhost'`, `port: 6379`. User/password are URI-decoded.
135
+
136
+ ---
137
+
138
+ ## What `tasks` in `ignite()` does NOT do
139
+
140
+ - Does NOT start a dedicated task-runner process — tasks run inside each worker process.
141
+ - Does NOT auto-retry on `enqueue` failure — `enqueue` itself doesn't retry; the backend handles job-level retries.
142
+ - On `gracefulShutdown()`, the HTTP server closes first, then `closeBullMQ()` / `closePgBoss()` drain in-flight jobs before exit.
143
+ - Does NOT provide a dead-letter web UI — use `efc tasks failed | retry | purge` (or Bull Board).
144
+ - Does NOT support sub-directories in `tasksDir`.
145
+
146
+ ---
147
+
148
+ ## Cron schedules
149
+
150
+ `defineTask({ schedule: '<cron>', timezone?: '<IANA>' }, handler)`. Reconciled on every boot:
151
+
152
+ - **BullMQ**: `queue.upsertJobScheduler('efc-cron:<Task>', { pattern, tz }, { name, data: {}, opts })` — idempotent,
153
+ so every cluster worker can run it. Schedulers with the `efc-cron:` prefix whose task lost its schedule are
154
+ removed. Sync is not awaited (`whenSchedulesSynced()` exposes it for tests). 6-field patterns (seconds) work.
155
+ - **pg-boss**: `boss.schedule('<queue>.<Task>', cron, {}, { tz, retry… })`; stale `<queue>.*` schedules are
156
+ `unschedule`d. One-minute resolution.
157
+ - Scheduled runs always receive `{}` as payload.
158
+
159
+ ## pg-boss backend (`tasks/pgboss-backend.ts`)
160
+
161
+ - `new PgBoss({ connectionString: tasks.connectionString ?? databaseUrl, schema? })`, `start()`.
162
+ - One pg-boss queue per task, named `<tasks.queue>.<TaskName>` (default prefix `efc`); `createQueue` is idempotent.
163
+ - `retryLimit = retries` (pg-boss counts re-runs, like EFC), `retryDelay: 1`, `retryBackoff` for exponential.
164
+ - Non-object payloads are boxed as `{ __efcValue: payload }` and unboxed for the handler.
165
+ - `enqueue` = `boss.send(...)` raced against `enqueueTimeout`.
166
+
167
+ ## Dead letters (`tasks/admin.ts`, CLI `efc tasks failed|retry|purge`)
168
+
169
+ `TaskAdmin` = `counts()`, `listFailed({ limit, name })`, `retry(ids)`, `purge(ids)` (empty ids = all).
170
+ BullMQ: `queue.getFailed`, `job.retry('failed')`, `job.remove()`. pg-boss: reads `pgboss.job WHERE state='failed'`,
171
+ then `boss.retry` / `boss.deleteJob`. A retried job gets exactly one more attempt on both backends.
172
+ CLI picks BullMQ when `REDIS_URL` is set, else pg-boss for a `postgres` `DATABASE_URL`; `--backend/--queue` override.