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.
- package/README.md +71 -33
- package/dist/auth/index.cjs +12 -2
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +13 -2
- package/dist/auth/index.d.ts +13 -2
- package/dist/auth/index.js +12 -2
- package/dist/chunk-277BSYVH.js +127 -0
- package/dist/chunk-277BSYVH.js.map +1 -0
- package/dist/chunk-6OGOVV57.js +3847 -0
- package/dist/chunk-6OGOVV57.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-AZYXQU3Z.cjs +3847 -0
- package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
- package/dist/chunk-BUBXO7WU.js +170 -0
- package/dist/chunk-BUBXO7WU.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-MGH4VDV3.cjs +170 -0
- package/dist/chunk-MGH4VDV3.cjs.map +1 -0
- package/dist/chunk-R34R7QPD.cjs +116 -0
- package/dist/chunk-R34R7QPD.cjs.map +1 -0
- package/dist/chunk-RS4MXCPW.js +116 -0
- package/dist/chunk-RS4MXCPW.js.map +1 -0
- package/dist/chunk-T4OHFU5T.cjs +154 -0
- package/dist/chunk-T4OHFU5T.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-TRC4DUZB.js +438 -0
- package/dist/chunk-TRC4DUZB.js.map +1 -0
- package/dist/chunk-TYR2GZZE.cjs +196 -0
- package/dist/chunk-TYR2GZZE.cjs.map +1 -0
- package/dist/chunk-UBQYQPBU.js +154 -0
- package/dist/chunk-UBQYQPBU.js.map +1 -0
- package/dist/chunk-UTM4PEVG.js +196 -0
- package/dist/chunk-UTM4PEVG.js.map +1 -0
- package/dist/chunk-YL37D6KM.cjs +127 -0
- package/dist/chunk-YL37D6KM.cjs.map +1 -0
- package/dist/chunk-ZDM5JHVK.cjs +438 -0
- package/dist/chunk-ZDM5JHVK.cjs.map +1 -0
- package/dist/cli/db-runner.cjs +497 -0
- package/dist/cli/db-runner.cjs.map +1 -0
- package/dist/cli/db-runner.d.cts +2 -0
- package/dist/cli/db-runner.d.ts +2 -0
- package/dist/cli/db-runner.js +497 -0
- package/dist/cli/db-runner.js.map +1 -0
- package/dist/cli/index.cjs +447 -69
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +473 -95
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +232 -0
- package/dist/docs/api-reference/compose.md +78 -0
- package/dist/docs/api-reference/db.md +351 -0
- package/dist/docs/api-reference/http-error.md +109 -0
- package/dist/docs/api-reference/ignite.md +326 -0
- package/dist/docs/api-reference/table.md +458 -0
- package/dist/docs/api-reference/tasks.md +140 -0
- package/dist/docs/cli/db.md +38 -0
- package/dist/docs/cli/diagnostics.md +145 -0
- package/dist/docs/cli/generate.md +120 -0
- package/dist/docs/cli/index.md +48 -0
- package/dist/docs/cli/start.md +112 -0
- package/dist/docs/contributing/index.md +139 -0
- package/dist/docs/core-concepts/background-tasks.md +228 -0
- package/dist/docs/core-concepts/clustering.md +114 -0
- package/dist/docs/core-concepts/file-based-routing.md +235 -0
- package/dist/docs/core-concepts/index.md +79 -0
- package/dist/docs/core-concepts/middleware.md +144 -0
- package/dist/docs/getting-started/index.md +91 -0
- package/dist/docs/getting-started/project-structure.md +154 -0
- package/dist/docs/guides/ai-agents.md +48 -0
- package/dist/docs/guides/authentication.md +196 -0
- package/dist/docs/guides/caching.md +124 -0
- package/dist/docs/guides/database.md +217 -0
- package/dist/docs/guides/deployment.md +171 -0
- package/dist/docs/guides/environment-variables.md +106 -0
- package/dist/docs/guides/error-handling.md +172 -0
- package/dist/docs/guides/generated-portals.md +115 -0
- package/dist/docs/guides/logging.md +108 -0
- package/dist/docs/guides/mailer.md +166 -0
- package/dist/docs/guides/migrations.md +106 -0
- package/dist/docs/guides/rbac.md +89 -0
- package/dist/docs/guides/validation.md +95 -0
- package/dist/docs/index.md +93 -0
- package/dist/docs/skills/SKILL.md +44 -0
- package/dist/docs/skills/api-surface.md +309 -0
- package/dist/docs/skills/auth-internals.md +141 -0
- package/dist/docs/skills/pre-flight.md +142 -0
- package/dist/docs/skills/routing-rules.md +114 -0
- package/dist/docs/skills/tasks-internals.md +172 -0
- package/dist/docs/skills/what-not-to-invent.md +251 -0
- package/dist/index.cjs +264 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +699 -7
- package/dist/index.d.ts +699 -7
- package/dist/index.js +258 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
- package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
- package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
- package/dist/pgboss-backend-TCHI7CHM.cjs.map +1 -0
- package/dist/tasks/index.cjs.map +1 -1
- package/dist/tasks/index.d.cts +1 -1
- package/dist/tasks/index.d.ts +1 -1
- package/dist/types-B6lVw4bj.d.cts +588 -0
- package/dist/types-B6lVw4bj.d.ts +588 -0
- package/package.json +28 -5
- package/dist/chunk-6522HS2J.cjs +0 -99
- package/dist/chunk-6522HS2J.cjs.map +0 -1
- package/dist/chunk-DGVOJNR6.cjs +0 -55
- package/dist/chunk-DGVOJNR6.cjs.map +0 -1
- package/dist/chunk-KOHLLUN7.js +0 -55
- package/dist/chunk-KOHLLUN7.js.map +0 -1
- package/dist/chunk-VIP3PFWZ.js +0 -99
- package/dist/chunk-VIP3PFWZ.js.map +0 -1
- package/dist/types-BusbSenn.d.cts +0 -162
- 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.
|