webspresso 0.0.106 → 0.0.108

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 (118) hide show
  1. package/.agents/AGENTS.md +4 -1
  2. package/.agents/CACHE.md +1 -0
  3. package/.agents/CONTEXT.md +152 -0
  4. package/.agents/ORM.md +74 -0
  5. package/.agents/SHUTDOWN.md +8 -1
  6. package/.agents/skills/webspresso-framework/SKILL.md +2 -1
  7. package/.agents/skills/webspresso-orm-and-database/SKILL.md +9 -0
  8. package/.agents/skills/webspresso-routing-and-api/SKILL.md +18 -2
  9. package/.agents/skills/webspresso-services/SKILL.md +36 -3
  10. package/AGENTS.md +6 -3
  11. package/bin/webspresso.js +17 -7
  12. package/core/app.js +45 -11
  13. package/core/applySchema.js +3 -72
  14. package/core/auth/index.js +4 -1
  15. package/core/auth/jwt.js +85 -13
  16. package/core/auth/magic-link.js +23 -5
  17. package/core/auth/manager.js +7 -1
  18. package/core/auth/redis-session.js +62 -25
  19. package/core/auth/session-manager.js +28 -2
  20. package/core/auth/sessions.js +182 -52
  21. package/core/cache/lru.js +10 -0
  22. package/core/cache/tagged-lru.js +4 -0
  23. package/core/compileSchema.js +3 -68
  24. package/core/compression/compressible.js +53 -6
  25. package/core/compression/negotiate.js +31 -12
  26. package/core/console/eval.js +4 -1
  27. package/core/content/service.js +1 -0
  28. package/core/context/app-context.js +201 -0
  29. package/core/context/index.js +55 -0
  30. package/core/context/request.js +241 -0
  31. package/core/errors/domain.js +20 -2
  32. package/core/errors/http.js +1 -0
  33. package/core/events/dispatcher.js +144 -15
  34. package/core/events/signal.js +9 -0
  35. package/core/health/probes.js +12 -2
  36. package/core/http/hono-adapter.js +1 -1
  37. package/core/http/index.js +10 -1
  38. package/core/http/pipeline.js +519 -334
  39. package/core/index.js +36 -2
  40. package/core/mail/mailer.js +1 -1
  41. package/core/orm/eager-loader.js +170 -55
  42. package/core/orm/index.js +25 -47
  43. package/core/orm/json-fields.js +44 -13
  44. package/core/orm/model.js +18 -1
  45. package/core/orm/query-builder.js +33 -15
  46. package/core/orm/repository.js +59 -12
  47. package/core/orm/schema-helpers.js +59 -0
  48. package/core/orm/scopes.js +54 -4
  49. package/core/orm/transaction.js +109 -14
  50. package/core/plugins/index.js +8 -0
  51. package/core/plugins/plugin-manager.js +1098 -0
  52. package/core/queue/manager.js +55 -27
  53. package/core/rate-limit/stores/memory.js +23 -10
  54. package/core/resilience/circuit-breaker.js +34 -14
  55. package/core/schema-cache.js +2 -64
  56. package/core/services/builtins/auth.js +273 -0
  57. package/core/services/builtins/exchange.js +229 -0
  58. package/core/services/builtins/file-manager.js +178 -0
  59. package/core/services/builtins/mail.js +134 -0
  60. package/core/services/builtins/media.js +196 -0
  61. package/core/services/builtins/system.js +219 -0
  62. package/core/services/discovery.js +133 -0
  63. package/core/services/executor.js +629 -0
  64. package/core/services/index.js +114 -0
  65. package/core/services/loader.js +161 -0
  66. package/core/services/memoize.js +408 -0
  67. package/core/services/registry.js +731 -0
  68. package/core/services/validator.js +424 -0
  69. package/core/shutdown/shutdown-manager.js +194 -114
  70. package/core/ssr/stream.js +109 -16
  71. package/core/stream/text-stream.js +45 -4
  72. package/core/studio/inspector.js +9 -1
  73. package/core/studio/server.js +24 -8
  74. package/core/utils/index.js +110 -0
  75. package/core/utils/string.js +77 -16
  76. package/core/utils/timeout.js +4 -0
  77. package/core/validation/apply.js +74 -0
  78. package/core/validation/cache.js +66 -0
  79. package/core/validation/compiler.js +77 -0
  80. package/core/validation/index.js +40 -1
  81. package/index.d.ts +249 -12
  82. package/index.js +68 -20
  83. package/package.json +18 -8
  84. package/plugins/admin-panel/client/parts/07-model-list.js +5 -2
  85. package/plugins/admin-panel/index.js +24 -11
  86. package/plugins/admin-panel/modules/user-management.js +3 -2
  87. package/plugins/csrf/index.js +2 -1
  88. package/plugins/dashboard/index.js +27 -7
  89. package/src/app-context.js +4 -188
  90. package/src/dev/typegen.js +1 -1
  91. package/src/file-router.js +12 -3
  92. package/src/plugin-manager.js +5 -861
  93. package/src/server.js +30 -34
  94. package/src/services/builtins/auth.js +2 -273
  95. package/src/services/builtins/exchange.js +2 -229
  96. package/src/services/builtins/file-manager.js +2 -178
  97. package/src/services/builtins/mail.js +2 -134
  98. package/src/services/builtins/media.js +2 -196
  99. package/src/services/builtins/system.js +2 -219
  100. package/src/services/discovery.js +2 -125
  101. package/src/services/executor.js +2 -362
  102. package/src/services/index.js +4 -60
  103. package/src/services/loader.js +2 -0
  104. package/src/services/memoize.js +2 -234
  105. package/src/services/registry.js +2 -314
  106. package/src/services/validator.js +2 -273
  107. package/core/utils/array.js +0 -12
  108. package/core/utils/base64url.js +0 -8
  109. package/core/utils/ensure-leading-slash.js +0 -6
  110. package/core/utils/escape-html.js +0 -7
  111. package/core/utils/escape-regexp.js +0 -7
  112. package/core/utils/get-client-ip.js +0 -6
  113. package/core/utils/hmac.js +0 -6
  114. package/core/utils/random.js +0 -9
  115. package/core/utils/safe-compare.js +0 -3
  116. package/core/utils/sha256.js +0 -6
  117. package/core/utils/strip-trailing-slash.js +0 -6
  118. package/core/utils/walk.js +0 -7
@@ -6,34 +6,89 @@
6
6
  * @module core/http/pipeline
7
7
  */
8
8
 
9
+ const fs = require('fs');
9
10
  const path = require('path');
10
11
  const { ZodError } = require('zod');
11
12
  const { translateValidationIssues, getTranslatorForRequest } = require('../../src/api/validation-i18n');
13
+ const { runWithContext } = require('../context/request');
14
+ const { detectLocale, loadI18n, createTranslator, resolvePageAssets, applyPageAssetsToTemplateData } = require('../../src/file-router');
15
+ const { createHelpers, getAssetManager } = require('../../src/helpers');
16
+ const { sendEarlyHints } = require('../early-hints');
12
17
 
13
18
  /**
14
- * Runs a sequence of middleware functions
15
- * Supports Express-style (req, res, next)
19
+ * Validates request input against compiled schema
20
+ * @param {Object} req - Request object
21
+ * @param {Object} compiledSchema - Compiled Zod schema object
22
+ */
23
+ function validateRequestInput(req, compiledSchema) {
24
+ req.input = {
25
+ body: undefined,
26
+ params: undefined,
27
+ query: undefined,
28
+ headers: undefined,
29
+ };
30
+
31
+ if (!compiledSchema) return;
32
+
33
+ if (compiledSchema.body && typeof compiledSchema.body.parse === 'function') {
34
+ req.input.body = compiledSchema.body.parse(req.body);
35
+ } else {
36
+ req.input.body = req.body;
37
+ }
38
+
39
+ if (compiledSchema.params && typeof compiledSchema.params.parse === 'function') {
40
+ req.input.params = compiledSchema.params.parse(req.params);
41
+ } else {
42
+ req.input.params = req.params;
43
+ }
44
+
45
+ if (compiledSchema.query && typeof compiledSchema.query.parse === 'function') {
46
+ req.input.query = compiledSchema.query.parse(req.query);
47
+ } else {
48
+ req.input.query = req.query;
49
+ }
50
+
51
+ if (compiledSchema.headers && typeof compiledSchema.headers.parse === 'function') {
52
+ req.input.headers = compiledSchema.headers.parse(req.headers);
53
+ }
54
+ }
55
+
56
+ /**
57
+ * Runs a sequence of middleware functions.
58
+ * Supports Express-style (req, res, next), 2-arg modern async (req, res),
59
+ * error propagation, and response termination detection.
60
+ *
16
61
  * @param {Function[]} middlewares
17
62
  * @param {Object} req
18
63
  * @param {Object} res
64
+ * @returns {Promise<void>}
19
65
  */
20
66
  async function runMiddlewares(middlewares, req, res) {
21
- if (!Array.isArray(middlewares)) return;
67
+ if (!Array.isArray(middlewares) || middlewares.length === 0) return;
22
68
 
23
69
  for (const mw of middlewares) {
24
70
  if (typeof mw !== 'function') continue;
71
+
72
+ // Fast-path: if response already finished/flushed, stop executing chain
73
+ if (res && (res.headersSent || res.writableEnded || res.finished)) return;
74
+
25
75
  await new Promise((resolve, reject) => {
26
76
  let settled = false;
77
+ const prevEnd = typeof res?.end === 'function' ? res.end : null;
78
+
27
79
  const done = (err) => {
28
80
  if (settled) return;
29
81
  settled = true;
82
+ if (res && prevEnd && res.end !== prevEnd) {
83
+ res.end = prevEnd;
84
+ }
30
85
  if (err) reject(err);
31
86
  else resolve();
32
87
  };
33
88
 
34
- const prevEnd = res?.end;
35
- if (res && typeof res.end === 'function') {
89
+ if (prevEnd) {
36
90
  res.end = function (...args) {
91
+ if (res && prevEnd) res.end = prevEnd;
37
92
  const ret = prevEnd.apply(this, args);
38
93
  done();
39
94
  return ret;
@@ -41,33 +96,63 @@ async function runMiddlewares(middlewares, req, res) {
41
96
  }
42
97
 
43
98
  try {
44
- mw(req, res, (err) => {
99
+ const ret = mw(req, res, (err) => {
45
100
  done(err);
46
101
  });
102
+
103
+ if (ret && typeof ret.then === 'function') {
104
+ ret.then(
105
+ () => {
106
+ // Auto-advance for 2-arg async middlewares or when response was sent
107
+ if (mw.length < 3 || (res && (res.headersSent || res.writableEnded || res.finished))) {
108
+ done();
109
+ }
110
+ },
111
+ (asyncErr) => {
112
+ // Asynchronous exception in async middleware caught and forwarded
113
+ done(asyncErr);
114
+ }
115
+ );
116
+ } else if (mw.length < 3 || (res && (res.headersSent || res.writableEnded || res.finished))) {
117
+ done();
118
+ }
47
119
  } catch (syncErr) {
48
120
  done(syncErr);
49
121
  }
50
122
  });
51
- if (res && res.headersSent) return;
123
+
124
+ if (res && (res.headersSent || res.writableEnded || res.finished)) return;
52
125
  }
53
126
  }
54
127
 
128
+ /**
129
+ * Creates a reusable pipeline runner function for a middleware array
130
+ * @param {Function[]} [middlewares=[]]
131
+ * @returns {(req: any, res: any) => Promise<void>}
132
+ */
133
+ function createPipelineRunner(middlewares = []) {
134
+ const mws = Array.isArray(middlewares) ? middlewares.slice() : [];
135
+ return function pipelineRunner(req, res) {
136
+ return runMiddlewares(mws, req, res);
137
+ };
138
+ }
139
+
55
140
  /**
56
141
  * Decorates an error with route execution metadata
57
142
  * @param {Error} err
58
- * @param {Object} descriptor
59
- * @param {Object} req
143
+ * @param {Object} [descriptor]
144
+ * @param {Object} [req]
60
145
  * @returns {Error}
61
146
  */
62
- function enrichRouteError(err, descriptor, req) {
147
+ function enrichRouteError(err, descriptor = {}, req = {}) {
63
148
  if (err && typeof err === 'object') {
64
- if (!err.route) err.route = descriptor.path;
65
- if (!err.method) err.method = descriptor.method ? descriptor.method.toUpperCase() : (req.method || 'GET');
66
- if (!err.source) err.source = descriptor.source || descriptor.file;
67
- if (!err.file) err.file = descriptor.file;
68
- if (!err.module) err.module = descriptor.module || null;
69
- if (!err.phase) err.phase = descriptor && descriptor.type === 'page' ? 'page' : 'handler';
70
- if (!err.requestId) err.requestId = req && (req.id || (req.headers && req.headers['x-request-id'])) || null;
149
+ if (!err.route && descriptor?.path) err.route = descriptor.path;
150
+ if (!err.method) err.method = descriptor?.method ? descriptor.method.toUpperCase() : (req?.method || 'GET');
151
+ if (!err.source && (descriptor?.source || descriptor?.file)) err.source = descriptor.source || descriptor.file;
152
+ if (!err.file && descriptor?.file) err.file = descriptor.file;
153
+ if (!err.module && descriptor?.module) err.module = descriptor.module;
154
+ if (!err.phase) err.phase = descriptor?.type === 'page' ? 'page' : 'handler';
155
+ if (!err.requestId) err.requestId = (req && (req.id || (req.headers && req.headers['x-request-id']))) || null;
71
156
  }
72
157
  return err;
73
158
  }
@@ -87,7 +172,7 @@ function enrichRouteError(err, descriptor, req) {
87
172
  */
88
173
  async function executeApiPipeline(params) {
89
174
  const {
90
- descriptor,
175
+ descriptor = {},
91
176
  context = {},
92
177
  apiDef,
93
178
  handlerFn,
@@ -97,137 +182,171 @@ async function executeApiPipeline(params) {
97
182
  res,
98
183
  } = params;
99
184
 
100
- const appOptions = context.options || {};
101
- const isDev = context.isDev !== undefined
102
- ? context.isDev
103
- : (appOptions.isDev !== undefined ? appOptions.isDev : process.env.NODE_ENV === 'development');
104
- const db = context.db || req.db;
105
- const serviceRegistry = context.serviceRegistry;
106
-
107
- // 1. Injections
108
- if (db && !req.db) req.db = db;
109
- if (!req.service && serviceRegistry) {
110
- req.service = (name, input, opts) => {
111
- const baseContext = req.context || { req, res, db, user: req.user, session: req.session };
112
- return serviceRegistry.call(name, input, baseContext, opts);
113
- };
114
- }
185
+ try {
186
+ const appOptions = context.options || {};
187
+ const isDev = context.isDev !== undefined
188
+ ? context.isDev
189
+ : (appOptions.isDev !== undefined ? appOptions.isDev : process.env.NODE_ENV === 'development');
190
+ const db = context.db || req.db;
191
+ const serviceRegistry = context.serviceRegistry;
192
+
193
+ // 1. Injections
194
+ if (db && !req.db) req.db = db;
195
+ if (!req.service && serviceRegistry) {
196
+ const getCallContext = (explicitCtx) => {
197
+ if (explicitCtx) return explicitCtx;
198
+ const ctx = req.context ? { ...req.context } : { req, res, db: req.db || db };
199
+ if (!ctx.req) ctx.req = req;
200
+ if (!ctx.res) ctx.res = res;
201
+ if (!ctx.db) ctx.db = req.db || db;
202
+ if (req.user !== undefined) ctx.user = req.user;
203
+ if (req.auth !== undefined) ctx.auth = req.auth;
204
+ if (req.session !== undefined) ctx.session = req.session;
205
+ return ctx;
206
+ };
207
+ req.service = (name, input, opts) => {
208
+ return serviceRegistry.call(name, input, getCallContext(opts?.ctx), opts);
209
+ };
210
+ req.service.call = req.service;
211
+ req.service.execute = req.service;
212
+ req.service.invalidate = (name, input, ctx) =>
213
+ serviceRegistry.invalidate(name, input, getCallContext(ctx));
214
+ req.service.clearCache = (name) =>
215
+ serviceRegistry.clearCache(name);
216
+ req.service.invalidateByTag = (tag, serviceName) =>
217
+ serviceRegistry.invalidateByTag(tag, serviceName);
218
+ req.service.invalidateByTags = (tags, serviceName) =>
219
+ serviceRegistry.invalidateByTags(tags, serviceName);
220
+ req.service.invalidateTag = req.service.invalidateByTag;
221
+ req.service.invalidateTags = req.service.invalidateByTags;
222
+ }
115
223
 
116
- // 2. Schema validation
117
- if (compiledSchema) {
118
- try {
119
- const { validateRequestInput } = require('../../src/api/api-loader');
120
- validateRequestInput(req, compiledSchema);
121
- } catch (err) {
122
- if (err instanceof ZodError || err.name === 'ZodError' || Array.isArray(err?.issues)) {
123
- const pagesDir = context.pagesDir || appOptions.pagesDir || 'pages';
124
- const routeDir = descriptor.file ? path.dirname(descriptor.file) : '';
125
- const translatedIssues = translateValidationIssues(err.issues, {
126
- req,
127
- pagesDir,
128
- routeDir,
129
- isDev,
130
- });
131
- if (res && typeof res.status === 'function' && typeof res.json === 'function') {
132
- return res.status(400).json({
133
- error: 'Validation Error',
134
- issues: translatedIssues,
224
+ // 2. Schema validation
225
+ const pagesDir = context.pagesDir || appOptions.pagesDir || 'pages';
226
+ const routeDir = descriptor._routeDir !== undefined
227
+ ? descriptor._routeDir
228
+ : (descriptor._routeDir = descriptor.file ? path.dirname(descriptor.file) : '');
229
+
230
+ if (compiledSchema) {
231
+ try {
232
+ validateRequestInput(req, compiledSchema);
233
+ } catch (err) {
234
+ if (err instanceof ZodError || err.name === 'ZodError' || Array.isArray(err?.issues)) {
235
+ const translatedIssues = translateValidationIssues(err.issues, {
236
+ req,
237
+ pagesDir,
238
+ routeDir,
239
+ isDev,
135
240
  });
241
+ if (res && typeof res.status === 'function' && typeof res.json === 'function') {
242
+ return res.status(400).json({
243
+ error: 'Validation Error',
244
+ issues: translatedIssues,
245
+ });
246
+ }
247
+ const validationErr = new Error('Validation Error');
248
+ validationErr.status = 400;
249
+ validationErr.issues = translatedIssues;
250
+ throw validationErr;
136
251
  }
137
- const validationErr = new Error('Validation Error');
138
- validationErr.status = 400;
139
- validationErr.issues = translatedIssues;
140
- throw validationErr;
252
+ throw err;
141
253
  }
142
- throw err;
254
+ } else {
255
+ req.input = {
256
+ body: req.body,
257
+ params: req.params,
258
+ query: req.query,
259
+ };
143
260
  }
144
- } else {
145
- req.input = {
146
- body: req.body,
147
- params: req.params,
148
- query: req.query,
149
- };
150
- }
151
261
 
152
- // 2.5 Feature Flag Guard
153
- if (apiDef && apiDef.flag) {
154
- const flagKey = typeof apiDef.flag === 'string' ? apiDef.flag : apiDef.flag.key;
155
- const isEnabled = typeof req.hasFeature === 'function'
156
- ? req.hasFeature(flagKey)
157
- : ((context.app?.flags || context.flags)?.isEnabled(flagKey, req) ?? false);
158
-
159
- if (!isEnabled) {
160
- const statusCode = (typeof apiDef.flag === 'object' && apiDef.flag.statusCode) || 404;
161
- const message = (typeof apiDef.flag === 'object' && apiDef.flag.message) || (statusCode === 403 ? 'Forbidden' : 'Not Found');
162
-
163
- if (res && typeof res.status === 'function') {
164
- return res.status(statusCode).json({
165
- error: statusCode === 403 ? 'Forbidden' : 'Not Found',
166
- message,
167
- feature: flagKey,
168
- });
262
+ // 2.5 Feature Flag Guard
263
+ if (apiDef && apiDef.flag) {
264
+ const flagKey = typeof apiDef.flag === 'string' ? apiDef.flag : apiDef.flag.key;
265
+ const isEnabled = typeof req.hasFeature === 'function'
266
+ ? req.hasFeature(flagKey)
267
+ : ((context.app?.flags || context.flags)?.isEnabled(flagKey, req) ?? false);
268
+
269
+ if (!isEnabled) {
270
+ const statusCode = (typeof apiDef.flag === 'object' && apiDef.flag.statusCode) || 404;
271
+ const message = (typeof apiDef.flag === 'object' && apiDef.flag.message) || (statusCode === 403 ? 'Forbidden' : 'Not Found');
272
+
273
+ if (res && typeof res.status === 'function') {
274
+ return res.status(statusCode).json({
275
+ error: statusCode === 403 ? 'Forbidden' : 'Not Found',
276
+ message,
277
+ feature: flagKey,
278
+ });
279
+ }
280
+ const notFound = new Error(message);
281
+ notFound.status = statusCode;
282
+ notFound.statusCode = statusCode;
283
+ throw notFound;
169
284
  }
170
- const notFound = new Error(message);
171
- notFound.status = statusCode;
172
- notFound.statusCode = statusCode;
173
- throw notFound;
174
285
  }
175
- }
176
286
 
177
- // 3. Middlewares
178
- if (middlewares.length > 0) {
179
- await runMiddlewares(middlewares, req, res);
180
- if (res && res.headersSent) return;
181
- }
287
+ // 3. Build Context
288
+ const tr = getTranslatorForRequest(req, { pagesDir, routeDir, isDev });
289
+
290
+ const apiCtx = {
291
+ req,
292
+ res,
293
+ params: req.params || {},
294
+ query: req.query || {},
295
+ body: req.body || {},
296
+ input: req.input,
297
+ locale: tr.locale,
298
+ t: tr.t,
299
+ service: req.service
300
+ ? req.service
301
+ : (name, input, opts) =>
302
+ serviceRegistry ? serviceRegistry.call(name, input, req.context || { req, res, db, user: req.user, session: req.session }, opts) : null,
303
+ module: descriptor.module || null,
304
+ config: appOptions,
305
+ logger: req.logger || console,
306
+ db,
307
+ user: req.user,
308
+ auth: req.auth,
309
+ session: req.session,
310
+ queue: req.queue || context.queue || null,
311
+ cache: req.cache || context.cache || null,
312
+ flags: req.flags || null,
313
+ hasFeature: typeof req.hasFeature === 'function' ? (k, c) => req.hasFeature(k, c) : () => false,
314
+ getVariant: typeof req.getVariant === 'function' ? (k, c) => req.getVariant(k, c) : () => null,
315
+ sse: (sourceOrOptions, maybeOptions) => (res && typeof res.sse === 'function' ? res.sse(sourceOrOptions, maybeOptions) : null),
316
+ streamText: (sourceOrCallback, maybeOptions) => (res && typeof res.streamText === 'function' ? res.streamText(sourceOrCallback, maybeOptions) : null),
317
+ streamJson: (sourceOrCallback, maybeOptions) => (res && typeof res.streamJson === 'function' ? res.streamJson(sourceOrCallback, maybeOptions) : null),
318
+ };
182
319
 
183
- // 4. Build Context & Execute
184
- const pagesDir = context.pagesDir || appOptions.pagesDir || 'pages';
185
- const routeDir = descriptor.file ? path.dirname(descriptor.file) : '';
186
- const tr = getTranslatorForRequest(req, { pagesDir, routeDir, isDev });
320
+ req.ctx = apiCtx;
321
+ if (res) {
322
+ res.service = apiCtx.service;
323
+ res.input = apiCtx.input;
324
+ res.module = apiCtx.module;
325
+ }
187
326
 
188
- const apiCtx = {
189
- req,
190
- res,
191
- params: req.params || {},
192
- query: req.query || {},
193
- body: req.body || {},
194
- input: req.input,
195
- locale: tr.locale,
196
- t: tr.t,
197
- service: req.service
198
- ? req.service
199
- : (name, input, opts) =>
200
- serviceRegistry ? serviceRegistry.call(name, input, req.context || { req, res, db, user: req.user, session: req.session }, opts) : null,
201
- module: descriptor.module || null,
202
- config: appOptions,
203
- logger: console,
204
- db,
205
- flags: req.flags || null,
206
- hasFeature: typeof req.hasFeature === 'function' ? (k, c) => req.hasFeature(k, c) : () => false,
207
- getVariant: typeof req.getVariant === 'function' ? (k, c) => req.getVariant(k, c) : () => null,
208
- sse: (sourceOrOptions, maybeOptions) => (res && typeof res.sse === 'function' ? res.sse(sourceOrOptions, maybeOptions) : null),
209
- streamText: (sourceOrCallback, maybeOptions) => (res && typeof res.streamText === 'function' ? res.streamText(sourceOrCallback, maybeOptions) : null),
210
- streamJson: (sourceOrCallback, maybeOptions) => (res && typeof res.streamJson === 'function' ? res.streamJson(sourceOrCallback, maybeOptions) : null),
211
- };
327
+ // 4. Execute within Ambient Request Context
328
+ return await runWithContext(apiCtx, async () => {
329
+ if (middlewares.length > 0) {
330
+ await runMiddlewares(middlewares, req, res);
331
+ if (res && (res.headersSent || res.writableEnded || res.finished)) return;
332
+ }
212
333
 
213
- req.ctx = apiCtx;
214
- if (res) {
215
- res.service = apiCtx.service;
216
- res.input = apiCtx.input;
217
- res.module = apiCtx.module;
218
- }
334
+ const result = await handlerFn(req, res, apiCtx);
219
335
 
220
- const result = await handlerFn(req, res, apiCtx);
336
+ // 5. Auto-respond if handler returned a value and response not yet sent
337
+ if (res && !res.headersSent && !res.writableEnded && !res.finished) {
338
+ if (result !== undefined && typeof res.json === 'function') {
339
+ res.json(result);
340
+ return result;
341
+ }
342
+ }
221
343
 
222
- // 5. Auto-respond if handler returned a value and response not yet sent
223
- if (res && !res.headersSent) {
224
- if (result !== undefined && typeof res.json === 'function') {
225
- res.json(result);
226
344
  return result;
227
- }
345
+ });
346
+ } catch (err) {
347
+ enrichRouteError(err, descriptor, req);
348
+ throw err;
228
349
  }
229
-
230
- return result;
231
350
  }
232
351
 
233
352
  /**
@@ -236,7 +355,7 @@ async function executeApiPipeline(params) {
236
355
  */
237
356
  async function executePagePipeline(params) {
238
357
  const {
239
- descriptor,
358
+ descriptor = {},
240
359
  context = {},
241
360
  pageDef,
242
361
  middlewares = [],
@@ -247,239 +366,305 @@ async function executePagePipeline(params) {
247
366
  hasNjkTemplate,
248
367
  } = params;
249
368
 
250
- const appOptions = context.options || {};
251
- const isDev = context.isDev !== undefined
252
- ? context.isDev
253
- : (appOptions.isDev !== undefined ? appOptions.isDev : process.env.NODE_ENV === 'development');
254
- const db = context.db || req.db;
255
- const serviceRegistry = context.serviceRegistry;
256
- const pagesDir = context.pagesDir || appOptions.pagesDir || 'pages';
257
-
258
- // 1. Injections
259
- if (db && !req.db) req.db = db;
260
- if (!req.service && serviceRegistry) {
261
- const baseContext = req.context || { req, res, db, user: req.user, session: req.session };
262
- req.service = (name, input, opts) =>
263
- serviceRegistry.call(name, input, baseContext, opts);
264
- }
265
-
266
- // 2. Middlewares
267
- if (middlewares.length > 0) {
268
- await runMiddlewares(middlewares, req, res);
269
- if (res && res.headersSent) return;
270
- }
369
+ try {
370
+ const appOptions = context.options || {};
371
+ const isDev = context.isDev !== undefined
372
+ ? context.isDev
373
+ : (appOptions.isDev !== undefined ? appOptions.isDev : process.env.NODE_ENV === 'development');
374
+ const db = context.db || req.db;
375
+ const serviceRegistry = context.serviceRegistry;
376
+ const pagesDir = context.pagesDir || appOptions.pagesDir || 'pages';
377
+
378
+ // 1. Injections
379
+ if (db && !req.db) req.db = db;
380
+ if (!req.service && serviceRegistry) {
381
+ const baseContext = req.context || { req, res, db, user: req.user, session: req.session };
382
+ req.service = (name, input, opts) =>
383
+ serviceRegistry.call(name, input, baseContext, opts);
384
+ req.service.call = req.service;
385
+ req.service.execute = req.service;
386
+ req.service.invalidate = (name, input, ctx) =>
387
+ serviceRegistry.invalidate(name, input, ctx || baseContext);
388
+ req.service.clearCache = (name) =>
389
+ serviceRegistry.clearCache(name);
390
+ req.service.invalidateByTag = (tag, serviceName) =>
391
+ serviceRegistry.invalidateByTag(tag, serviceName);
392
+ req.service.invalidateByTags = (tags, serviceName) =>
393
+ serviceRegistry.invalidateByTags(tags, serviceName);
394
+ req.service.invalidateTag = req.service.invalidateByTag;
395
+ req.service.invalidateTags = req.service.invalidateByTags;
396
+ }
271
397
 
272
- // 3. Build Page Context
273
- const baseUrl = process.env.BASE_URL || `http://localhost:${process.env.PORT || 7331}`;
274
- const { detectLocale, loadI18n, createTranslator, resolvePageAssets, applyPageAssetsToTemplateData } = require('../../src/file-router');
275
- const { createHelpers, getAssetManager } = require('../../src/helpers');
276
- const { sendEarlyHints } = require('../early-hints');
277
-
278
- const locale = detectLocale(req);
279
- const fsy = createHelpers({ req, res, baseUrl, locale });
280
-
281
- const defaultLocale = process.env.DEFAULT_LOCALE || 'en';
282
- let t;
283
- const translatorCache = context.translatorCache;
284
- if (!isDev && translatorCache) {
285
- const transKey = `${pagesDir}::::${locale}::${defaultLocale}`;
286
- t = translatorCache.get(transKey);
287
- if (!t) {
288
- const translations = loadI18n(pagesDir, '', locale, false);
289
- const fallbackTranslations = locale !== defaultLocale ? loadI18n(pagesDir, '', defaultLocale, false) : undefined;
398
+ // 2. Build Page Context
399
+ const baseUrl = process.env.BASE_URL || `http://localhost:${process.env.PORT || 7331}`;
400
+ const locale = detectLocale(req);
401
+ const fsy = createHelpers({ req, res, baseUrl, locale });
402
+
403
+ const defaultLocale = process.env.DEFAULT_LOCALE || 'en';
404
+ let t;
405
+ const translatorCache = context.translatorCache;
406
+ if (!isDev && translatorCache) {
407
+ const transKey = `${pagesDir}::::${locale}::${defaultLocale}`;
408
+ t = translatorCache.get(transKey);
409
+ if (!t) {
410
+ const translations = loadI18n(pagesDir, '', locale, false);
411
+ const fallbackTranslations = locale !== defaultLocale ? loadI18n(pagesDir, '', defaultLocale, false) : undefined;
412
+ t = createTranslator(translations, {
413
+ locale,
414
+ fallbackTranslations,
415
+ fallbackLocale: defaultLocale,
416
+ });
417
+ translatorCache.set(transKey, t);
418
+ }
419
+ } else {
420
+ const translations = loadI18n(pagesDir, '', locale, isDev);
421
+ const fallbackTranslations = locale !== defaultLocale ? loadI18n(pagesDir, '', defaultLocale, isDev) : undefined;
290
422
  t = createTranslator(translations, {
291
423
  locale,
292
424
  fallbackTranslations,
293
425
  fallbackLocale: defaultLocale,
294
426
  });
295
- translatorCache.set(transKey, t);
296
427
  }
297
- } else {
298
- const translations = loadI18n(pagesDir, '', locale, isDev);
299
- const fallbackTranslations = locale !== defaultLocale ? loadI18n(pagesDir, '', defaultLocale, isDev) : undefined;
300
- t = createTranslator(translations, {
428
+
429
+ const pageCtx = {
430
+ req,
431
+ res,
432
+ params: req.params || {},
433
+ query: req.query || {},
434
+ service: req.service
435
+ ? req.service
436
+ : (name, input, opts) =>
437
+ serviceRegistry ? serviceRegistry.call(name, input, req.context || { req, res, db, user: req.user, session: req.session }, opts) : null,
438
+ module: descriptor.module || null,
439
+ config: appOptions,
440
+ logger: req.logger || console,
441
+ redirect: (url, status = 302) => {
442
+ if (res && typeof res.redirect === 'function') {
443
+ res.redirect(status, url);
444
+ }
445
+ return { __redirected: true };
446
+ },
447
+ error: (status = 500, message = 'Page Error') => {
448
+ const err = new Error(message);
449
+ err.status = status;
450
+ throw err;
451
+ },
452
+ earlyHints: (links, cb) => sendEarlyHints(res, links, cb),
453
+ renderStream: (tpl, data = {}, opts = {}) => {
454
+ if (res && typeof res.renderStream === 'function') {
455
+ return res.renderStream(tpl, data, opts);
456
+ }
457
+ const { renderStream } = require('../ssr/stream');
458
+ return renderStream(res, tpl, data, { env: nunjucks, ...opts });
459
+ },
460
+ streamText: (sourceOrCallback, maybeOptions) => {
461
+ if (res && typeof res.streamText === 'function') {
462
+ return res.streamText(sourceOrCallback, maybeOptions);
463
+ }
464
+ const { streamText } = require('../stream/text-stream');
465
+ return streamText(req, res, sourceOrCallback, maybeOptions);
466
+ },
467
+ streamJson: (sourceOrCallback, maybeOptions) => {
468
+ if (res && typeof res.streamJson === 'function') {
469
+ return res.streamJson(sourceOrCallback, maybeOptions);
470
+ }
471
+ const { streamJson } = require('../stream/text-stream');
472
+ return streamJson(req, res, sourceOrCallback, maybeOptions);
473
+ },
474
+ fsy,
301
475
  locale,
302
- fallbackTranslations,
303
- fallbackLocale: defaultLocale,
304
- });
305
- }
476
+ t,
477
+ db,
478
+ user: req.user,
479
+ auth: req.auth,
480
+ session: req.session,
481
+ queue: req.queue || context.queue || null,
482
+ cache: req.cache || context.cache || null,
483
+ };
306
484
 
307
- const pageCtx = {
308
- req,
309
- res,
310
- params: req.params || {},
311
- query: req.query || {},
312
- service: req.service
313
- ? req.service
314
- : (name, input, opts) =>
315
- serviceRegistry ? serviceRegistry.call(name, input, req.context || { req, res, db, user: req.user, session: req.session }, opts) : null,
316
- module: descriptor.module || null,
317
- config: appOptions,
318
- logger: console,
319
- redirect: (url, status = 302) => {
320
- if (res && typeof res.redirect === 'function') {
321
- res.redirect(status, url);
485
+ req.ctx = pageCtx;
486
+
487
+ // 3. Execute within Ambient Request Context
488
+ return await runWithContext(pageCtx, async () => {
489
+ // 3.1. Middlewares
490
+ if (middlewares.length > 0) {
491
+ await runMiddlewares(middlewares, req, res);
492
+ if (res && (res.headersSent || res.writableEnded || res.finished)) return;
322
493
  }
323
- return { __redirected: true };
324
- },
325
- error: (status = 500, message = 'Page Error') => {
326
- const err = new Error(message);
327
- err.status = status;
328
- throw err;
329
- },
330
- earlyHints: (links, cb) => sendEarlyHints(res, links, cb),
331
- fsy,
332
- locale,
333
- t,
334
- db,
335
- };
336
494
 
337
- // 4. Early Hints
338
- const earlyHintsOpt = pageDef.earlyHints !== undefined
339
- ? pageDef.earlyHints
340
- : (descriptor.earlyHints !== undefined
341
- ? descriptor.earlyHints
342
- : (appOptions && (appOptions.earlyHints ?? appOptions.server?.earlyHints)));
343
-
344
- if (earlyHintsOpt && earlyHintsOpt !== false && res && !res.headersSent) {
345
- const auto = typeof earlyHintsOpt === 'object' ? (earlyHintsOpt.auto !== false) : Boolean(earlyHintsOpt);
346
- const linksToSend = [];
347
-
348
- if (Array.isArray(earlyHintsOpt)) {
349
- linksToSend.push(...earlyHintsOpt);
350
- } else if (typeof earlyHintsOpt === 'object' && earlyHintsOpt.links) {
351
- const customLinks = typeof earlyHintsOpt.links === 'function' ? earlyHintsOpt.links(req) : earlyHintsOpt.links;
352
- if (Array.isArray(customLinks)) linksToSend.push(...customLinks);
353
- else if (customLinks) linksToSend.push(customLinks);
354
- }
495
+ // 4. Early Hints
496
+ const earlyHintsOpt = pageDef.earlyHints !== undefined
497
+ ? pageDef.earlyHints
498
+ : (descriptor.earlyHints !== undefined
499
+ ? descriptor.earlyHints
500
+ : (appOptions && (appOptions.earlyHints ?? appOptions.server?.earlyHints)));
501
+
502
+ if (earlyHintsOpt && earlyHintsOpt !== false && res && !res.headersSent && !res.writableEnded && !res.finished) {
503
+ const auto = typeof earlyHintsOpt === 'object' ? (earlyHintsOpt.auto !== false) : Boolean(earlyHintsOpt);
504
+ const linksToSend = [];
505
+
506
+ if (Array.isArray(earlyHintsOpt)) {
507
+ linksToSend.push(...earlyHintsOpt);
508
+ } else if (typeof earlyHintsOpt === 'object' && earlyHintsOpt.links) {
509
+ const customLinks = typeof earlyHintsOpt.links === 'function' ? earlyHintsOpt.links(req) : earlyHintsOpt.links;
510
+ if (Array.isArray(customLinks)) linksToSend.push(...customLinks);
511
+ else if (customLinks) linksToSend.push(customLinks);
512
+ }
355
513
 
356
- if (auto) {
357
- const assetManager = fsy?.assetManager || getAssetManager();
358
- if (assetManager && typeof assetManager.getRouteAssetCandidates === 'function') {
359
- const candidates = assetManager.getRouteAssetCandidates(
360
- descriptor.source || descriptor.file,
361
- descriptor.path
362
- );
363
- if (Array.isArray(candidates)) {
364
- for (const cand of candidates) {
365
- if (typeof assetManager.hasPageCss === 'function' && assetManager.hasPageCss(cand)) {
366
- linksToSend.push(assetManager.pageCssUrl(cand));
367
- break;
368
- }
369
- }
370
- for (const cand of candidates) {
371
- if (typeof assetManager.hasPageJs === 'function' && assetManager.hasPageJs(cand)) {
372
- linksToSend.push(assetManager.pageJsUrl(cand));
373
- break;
514
+ if (auto) {
515
+ const assetManager = fsy?.assetManager || getAssetManager();
516
+ if (assetManager && typeof assetManager.getRouteAssetCandidates === 'function') {
517
+ const candidates = assetManager.getRouteAssetCandidates(
518
+ descriptor.source || descriptor.file,
519
+ descriptor.path
520
+ );
521
+ if (Array.isArray(candidates)) {
522
+ for (const cand of candidates) {
523
+ if (typeof assetManager.hasPageCss === 'function' && assetManager.hasPageCss(cand)) {
524
+ linksToSend.push(assetManager.pageCssUrl(cand));
525
+ break;
526
+ }
527
+ }
528
+ for (const cand of candidates) {
529
+ if (typeof assetManager.hasPageJs === 'function' && assetManager.hasPageJs(cand)) {
530
+ linksToSend.push(assetManager.pageJsUrl(cand));
531
+ break;
532
+ }
533
+ }
374
534
  }
375
535
  }
376
536
  }
537
+
538
+ if (linksToSend.length > 0) {
539
+ sendEarlyHints(res, linksToSend);
540
+ }
377
541
  }
378
- }
379
542
 
380
- if (linksToSend.length > 0) {
381
- sendEarlyHints(res, linksToSend);
382
- }
383
- }
543
+ // 5. Run load() lifecycle
544
+ let loadedData = {};
545
+ if (typeof pageDef.load === 'function') {
546
+ loadedData = (await pageDef.load(pageCtx)) || {};
547
+ if (loadedData.__redirected || (res && (res.headersSent || res.writableEnded || res.finished))) {
548
+ return;
549
+ }
550
+ }
384
551
 
385
- // 5. Run load() lifecycle
386
- let loadedData = {};
387
- if (typeof pageDef.load === 'function') {
388
- loadedData = (await pageDef.load(pageCtx)) || {};
389
- if (loadedData.__redirected || (res && res.headersSent)) {
390
- return;
391
- }
392
- }
552
+ // 6. Run head() lifecycle
553
+ let headData = {};
554
+ if (typeof pageDef.head === 'function') {
555
+ headData = (await pageDef.head(loadedData, pageCtx)) || {};
556
+ }
393
557
 
394
- // 6. Run head() lifecycle
395
- let headData = {};
396
- if (typeof pageDef.head === 'function') {
397
- headData = (await pageDef.head(loadedData, pageCtx)) || {};
398
- }
558
+ // 7. Check for companion Nunjucks template
559
+ const templateExists = hasNjkTemplate !== undefined && hasNjkTemplate !== null
560
+ ? hasNjkTemplate
561
+ : (njkCandidate ? fs.existsSync(njkCandidate) : false);
562
+
563
+ if (templateExists && nunjucks) {
564
+ let pageHead = headData;
565
+ let pageAssetsActive = false;
566
+ const pageAssetsOpt = context.pageAssets || (appOptions && appOptions.pageAssets);
567
+ if (pageAssetsOpt) {
568
+ const pageAssetsResolved = resolvePageAssets(pageAssetsOpt);
569
+ if (pageAssetsResolved.enabled) {
570
+ const pageAssetBundle = applyPageAssetsToTemplateData(
571
+ pageAssetsResolved,
572
+ loadedData,
573
+ {
574
+ file: descriptor.source || descriptor.file,
575
+ routePath: descriptor.path,
576
+ },
577
+ fsy?.assetManager || getAssetManager()
578
+ );
579
+ loadedData = pageAssetBundle.data;
580
+ pageHead = {
581
+ ...headData,
582
+ stylesheets: [...(headData.stylesheets || []), ...(pageAssetBundle.pageHead?.stylesheets || [])],
583
+ scripts: [...(headData.scripts || []), ...(pageAssetBundle.pageHead?.scripts || [])],
584
+ };
585
+ pageAssetsActive = true;
586
+ }
587
+ }
399
588
 
400
- // 7. Check for companion Nunjucks template
401
- const fs = require('fs');
402
- const templateExists = hasNjkTemplate !== undefined && hasNjkTemplate !== null
403
- ? hasNjkTemplate
404
- : (njkCandidate ? fs.existsSync(njkCandidate) : false);
405
-
406
- if (templateExists && nunjucks) {
407
- let pageHead = headData;
408
- let pageAssetsActive = false;
409
- const pageAssetsOpt = context.pageAssets || (appOptions && appOptions.pageAssets);
410
- if (pageAssetsOpt) {
411
- const pageAssetsResolved = resolvePageAssets(pageAssetsOpt);
412
- if (pageAssetsResolved.enabled) {
413
- const pageAssetBundle = applyPageAssetsToTemplateData(
414
- pageAssetsResolved,
415
- loadedData,
416
- {
417
- file: descriptor.source || descriptor.file,
418
- routePath: descriptor.path,
419
- },
420
- fsy?.assetManager || getAssetManager()
421
- );
422
- loadedData = pageAssetBundle.data;
423
- pageHead = {
424
- ...headData,
425
- stylesheets: [...(headData.stylesheets || []), ...(pageAssetBundle.pageHead?.stylesheets || [])],
426
- scripts: [...(headData.scripts || []), ...(pageAssetBundle.pageHead?.scripts || [])],
589
+ const templateData = {
590
+ ...loadedData,
591
+ head: pageHead,
592
+ pageHead,
593
+ pageAssets: pageAssetsActive || Boolean(loadedData.pageAssets),
594
+ fsy,
595
+ locale,
596
+ t,
597
+ params: req.params,
598
+ query: req.query,
427
599
  };
428
- pageAssetsActive = true;
429
- }
430
- }
431
600
 
432
- const templateData = {
433
- ...loadedData,
434
- head: pageHead,
435
- pageHead,
436
- pageAssets: pageAssetsActive || Boolean(loadedData.pageAssets),
437
- fsy,
438
- locale,
439
- t,
440
- params: req.params,
441
- query: req.query,
442
- };
601
+ const isStreaming = Boolean(
602
+ pageDef.stream ||
603
+ descriptor.stream ||
604
+ loadedData.__stream ||
605
+ loadedData.stream ||
606
+ loadedData.defer ||
607
+ loadedData.__defer
608
+ );
443
609
 
444
- return new Promise((resolve, reject) => {
445
- nunjucks.render(njkCandidate, templateData, (err, html) => {
446
- if (err) return reject(err);
447
- if (res) {
448
- res.setHeader('Content-Type', 'text/html; charset=utf-8');
449
- res.send(html);
610
+ if (isStreaming && res && !res.headersSent) {
611
+ const { renderStream } = require('../ssr/stream');
612
+ const streamDefer = loadedData.defer || loadedData.__defer || pageDef.defer || {};
613
+ return await renderStream(res, njkCandidate, templateData, {
614
+ env: nunjucks,
615
+ defer: streamDefer,
616
+ status: 200,
617
+ loadingTemplate: pageDef.loadingTemplate || descriptor.loadingTemplate,
618
+ layouts: pageDef.layouts || descriptor.layouts,
619
+ });
450
620
  }
451
- resolve(html);
452
- });
453
- });
454
- }
455
621
 
456
- // 8. Render via definePage render() method
457
- if (typeof pageDef.render === 'function') {
458
- const html = await pageDef.render(loadedData, pageCtx);
459
- if (res) {
460
- res.setHeader('Content-Type', 'text/html; charset=utf-8');
461
- return res.send(html);
462
- }
463
- return html;
464
- }
622
+ return new Promise((resolve, reject) => {
623
+ nunjucks.render(njkCandidate, templateData, (err, html) => {
624
+ if (err) return reject(err);
625
+ if (res && !res.headersSent && !res.writableEnded && !res.finished) {
626
+ res.setHeader('Content-Type', 'text/html; charset=utf-8');
627
+ res.send(html);
628
+ }
629
+ resolve(html);
630
+ });
631
+ });
632
+ }
465
633
 
466
- // 9. Fallback: if json or data
467
- if (typeof loadedData === 'object' && loadedData !== null) {
468
- if (res && typeof res.json === 'function') {
469
- return res.json(loadedData);
470
- }
471
- return loadedData;
472
- }
634
+ // 8. Render via definePage render() method
635
+ if (typeof pageDef.render === 'function') {
636
+ const html = await pageDef.render(loadedData, pageCtx);
637
+ if (res && !res.headersSent && !res.writableEnded && !res.finished) {
638
+ res.setHeader('Content-Type', 'text/html; charset=utf-8');
639
+ return res.send(html);
640
+ }
641
+ return html;
642
+ }
643
+
644
+ // 9. Fallback: if json or data
645
+ if (typeof loadedData === 'object' && loadedData !== null) {
646
+ if (res && !res.headersSent && !res.writableEnded && !res.finished && typeof res.json === 'function') {
647
+ return res.json(loadedData);
648
+ }
649
+ return loadedData;
650
+ }
473
651
 
474
- if (res && typeof res.send === 'function') {
475
- return res.send(String(loadedData));
652
+ if (res && !res.headersSent && !res.writableEnded && !res.finished && typeof res.send === 'function') {
653
+ return res.send(String(loadedData));
654
+ }
655
+ return String(loadedData);
656
+ });
657
+ } catch (err) {
658
+ enrichRouteError(err, descriptor, req);
659
+ throw err;
476
660
  }
477
- return String(loadedData);
478
661
  }
479
662
 
480
663
  module.exports = {
664
+ createPipelineRunner,
481
665
  runMiddlewares,
482
666
  enrichRouteError,
667
+ validateRequestInput,
483
668
  executeApiPipeline,
484
669
  executePagePipeline,
485
670
  };