@timber-js/app 0.2.0-alpha.226 → 0.2.0-alpha.228

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 (101) hide show
  1. package/dist/_chunks/{actions-B1xSIv32.js → actions-DprvPi7O.js} +3 -3
  2. package/dist/_chunks/{actions-B1xSIv32.js.map → actions-DprvPi7O.js.map} +1 -1
  3. package/dist/_chunks/{build-output-helper-B7wWGTfR.js → build-output-helper-5UsltK-S.js} +29 -2
  4. package/dist/_chunks/build-output-helper-5UsltK-S.js.map +1 -0
  5. package/dist/_chunks/{cache-api-DsSXA4Sp.js → cache-api-BjE-nNC0.js} +4 -4
  6. package/dist/_chunks/{cache-api-DsSXA4Sp.js.map → cache-api-BjE-nNC0.js.map} +1 -1
  7. package/dist/_chunks/chains-BS8fQYao.js +1 -0
  8. package/dist/_chunks/{chains-Dgm3PrMe.js → chains-DaDEXv0c.js} +2 -2
  9. package/dist/_chunks/{chains-Dgm3PrMe.js.map → chains-DaDEXv0c.js.map} +1 -1
  10. package/dist/_chunks/{classify--_kINHQV.js → classify-BuIifN5v.js} +2 -2
  11. package/dist/_chunks/{classify--_kINHQV.js.map → classify-BuIifN5v.js.map} +1 -1
  12. package/dist/_chunks/{cli-check-B33yhAPa.js → cli-check-B_fDvxhs.js} +3 -3
  13. package/dist/_chunks/{cli-check-B33yhAPa.js.map → cli-check-B_fDvxhs.js.map} +1 -1
  14. package/dist/_chunks/{cli-schema-sync-uq72EZmD.js → cli-schema-sync-CUIk0G2X.js} +1 -1
  15. package/dist/_chunks/{cli-schema-sync-DIPurq7X.js → cli-schema-sync-D9OLUUFv.js} +2 -2
  16. package/dist/_chunks/{cli-schema-sync-DIPurq7X.js.map → cli-schema-sync-D9OLUUFv.js.map} +1 -1
  17. package/dist/_chunks/{client-dep-entries-CP7AkMCM.js → client-dep-entries-COuyF8-c.js} +2 -2
  18. package/dist/_chunks/{client-dep-entries-CP7AkMCM.js.map → client-dep-entries-COuyF8-c.js.map} +1 -1
  19. package/dist/_chunks/{cloudflare-B75X6u4O.js → cloudflare-_2fhxQE8.js} +4 -20
  20. package/dist/_chunks/{cloudflare-B75X6u4O.js.map → cloudflare-_2fhxQE8.js.map} +1 -1
  21. package/dist/_chunks/{convention-lint-hZwz5wd4.js → convention-lint-BHY0d5AQ.js} +4 -13
  22. package/dist/_chunks/convention-lint-BHY0d5AQ.js.map +1 -0
  23. package/dist/_chunks/{dev-server-B7o4As0l.js → dev-server-BaM7q3pr.js} +2 -2
  24. package/dist/_chunks/{dev-server-B7o4As0l.js.map → dev-server-BaM7q3pr.js.map} +1 -1
  25. package/dist/_chunks/dev-server-NnGosJ06.js +1 -0
  26. package/dist/_chunks/{flight-source-node-0Tp6evlz.js → flight-source-node-CZJ9Drb7.js} +2 -2
  27. package/dist/_chunks/{flight-source-node-0Tp6evlz.js.map → flight-source-node-CZJ9Drb7.js.map} +1 -1
  28. package/dist/_chunks/{json-lossy-check-DVkLUlfC.js → json-lossy-check-BNwKrm2R.js} +2 -2
  29. package/dist/_chunks/{json-lossy-check-DVkLUlfC.js.map → json-lossy-check-BNwKrm2R.js.map} +1 -1
  30. package/dist/_chunks/{live-graph-BcVjQ1Te.js → live-graph-DiRVmRrC.js} +4 -4
  31. package/dist/_chunks/{live-graph-BcVjQ1Te.js.map → live-graph-DiRVmRrC.js.map} +1 -1
  32. package/dist/_chunks/{logger-CWk44DLp.js → logger-DRMij51J.js} +4 -4
  33. package/dist/_chunks/logger-DRMij51J.js.map +1 -0
  34. package/dist/_chunks/{node-response-B9aviPDa.js → node-response-C-dQn-0N.js} +2 -2
  35. package/dist/_chunks/{node-response-B9aviPDa.js.map → node-response-C-dQn-0N.js.map} +1 -1
  36. package/dist/_chunks/{poison-scan-DJYxZc_7.js → poison-scan-CqPGN0ru.js} +2 -2
  37. package/dist/_chunks/{poison-scan-DJYxZc_7.js.map → poison-scan-CqPGN0ru.js.map} +1 -1
  38. package/dist/_chunks/route-methods-Dk2kZc0n.js +36 -0
  39. package/dist/_chunks/route-methods-Dk2kZc0n.js.map +1 -0
  40. package/dist/_chunks/{scanner-CJC-ScJU.js → scanner-C__vsQ8d.js} +2 -2
  41. package/dist/_chunks/{scanner-CJC-ScJU.js.map → scanner-C__vsQ8d.js.map} +1 -1
  42. package/dist/_chunks/{sizeof-DG4W40lv.js → sizeof-DcEcQaSL.js} +2 -2
  43. package/dist/_chunks/{sizeof-DG4W40lv.js.map → sizeof-DcEcQaSL.js.map} +1 -1
  44. package/dist/_chunks/{walkers-DIE203ir.js → walkers-D6KY4jyS.js} +3 -3
  45. package/dist/_chunks/{walkers-DIE203ir.js.map → walkers-D6KY4jyS.js.map} +1 -1
  46. package/dist/adapters/cloudflare-dev.js +1 -1
  47. package/dist/adapters/cloudflare-kv-cache.js +2 -2
  48. package/dist/adapters/cloudflare.d.ts +0 -7
  49. package/dist/adapters/cloudflare.d.ts.map +1 -1
  50. package/dist/adapters/cloudflare.js +1 -1
  51. package/dist/adapters/nitro.d.ts.map +1 -1
  52. package/dist/adapters/nitro.js +6 -5
  53. package/dist/adapters/nitro.js.map +1 -1
  54. package/dist/adapters/shared.d.ts +18 -0
  55. package/dist/adapters/shared.d.ts.map +1 -1
  56. package/dist/analyze/crawl-entry.js +3 -3
  57. package/dist/analyze/graph-command.js +2 -2
  58. package/dist/cache/index.js +2 -2
  59. package/dist/cache/stores/memory.js +1 -1
  60. package/dist/cli.js +3 -3
  61. package/dist/index.js +7 -7
  62. package/dist/routing/convention-lint.d.ts.map +1 -1
  63. package/dist/routing/index.js +2 -2
  64. package/dist/rsc-runtime/rsc.d.ts +2 -2
  65. package/dist/rsc-runtime/rsc.d.ts.map +1 -1
  66. package/dist/rsc-runtime/server-reference-load-error.d.ts +14 -0
  67. package/dist/rsc-runtime/server-reference-load-error.d.ts.map +1 -0
  68. package/dist/rsc-runtime/server-references.d.ts +11 -0
  69. package/dist/rsc-runtime/server-references.d.ts.map +1 -1
  70. package/dist/server/action-handler.d.ts +7 -5
  71. package/dist/server/action-handler.d.ts.map +1 -1
  72. package/dist/server/csrf.d.ts +1 -1
  73. package/dist/server/csrf.d.ts.map +1 -1
  74. package/dist/server/index.js +2 -2
  75. package/dist/server/internal.d.ts +2 -1
  76. package/dist/server/internal.d.ts.map +1 -1
  77. package/dist/server/internal.js +22 -24
  78. package/dist/server/internal.js.map +1 -1
  79. package/dist/server/route-handler.d.ts +1 -2
  80. package/dist/server/route-handler.d.ts.map +1 -1
  81. package/dist/server/route-methods.d.ts +23 -0
  82. package/dist/server/route-methods.d.ts.map +1 -0
  83. package/package.json +2 -2
  84. package/src/adapters/cloudflare.ts +7 -19
  85. package/src/adapters/nitro.ts +12 -5
  86. package/src/adapters/shared.ts +31 -0
  87. package/src/routing/convention-lint.ts +1 -3
  88. package/src/rsc-runtime/rsc.ts +8 -7
  89. package/src/rsc-runtime/server-reference-load-error.ts +16 -0
  90. package/src/rsc-runtime/server-references.ts +63 -1
  91. package/src/server/action-handler.ts +36 -17
  92. package/src/server/csrf.ts +11 -3
  93. package/src/server/internal.ts +2 -1
  94. package/src/server/route-handler.ts +8 -19
  95. package/src/server/route-methods.ts +37 -0
  96. package/src/server/tracing.ts +3 -3
  97. package/dist/_chunks/build-output-helper-B7wWGTfR.js.map +0 -1
  98. package/dist/_chunks/chains-CwOr3Myj.js +0 -1
  99. package/dist/_chunks/convention-lint-hZwz5wd4.js.map +0 -1
  100. package/dist/_chunks/dev-server-hZzmbMvK.js +0 -1
  101. package/dist/_chunks/logger-CWk44DLp.js.map +0 -1
@@ -8,8 +8,7 @@
8
8
  * See design/07-routing.md §"route.ts — API Endpoints"
9
9
  */
10
10
  import type { RouteContext } from './types.ts';
11
- /** HTTP methods that route.ts can export as named handlers. */
12
- export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
11
+ import { type HttpMethod } from './route-methods.ts';
13
12
  /** A single route handler function — one-arg signature. */
14
13
  export type RouteHandler = (ctx: RouteContext) => Response | Promise<Response>;
15
14
  /** A route.ts module — named exports for each supported HTTP method. */
@@ -1 +1 @@
1
- {"version":3,"file":"route-handler.d.ts","sourceRoot":"","sources":["../../src/server/route-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE/E,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG;KACvB,CAAC,IAAI,UAAU,CAAC,CAAC,EAAE,YAAY;CACjC,CAAC;AAOF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,EAAE,CAyBpE;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyC/F;AAgCD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,GAAG,QAAQ,CAqCjF"}
1
+ {"version":3,"file":"route-handler.d.ts","sourceRoot":"","sources":["../../src/server/route-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIjF,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE/E,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG;KACvB,CAAC,IAAI,UAAU,CAAC,CAAC,EAAE,YAAY;CACjC,CAAC;AAIF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,EAAE,CAiBpE;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2C/F;AAgCD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,GAAG,QAAQ,CAqCjF"}
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The HTTP methods a `route.ts` can export as named handlers.
3
+ *
4
+ * A leaf module with no imports, so the build-time convention lint
5
+ * (`routing/convention-lint.ts`) and the runtime dispatcher
6
+ * (`server/route-handler.ts`) read one list without the lint pulling in
7
+ * the request runtime. Adding a method here updates the `RouteModule` type,
8
+ * the `Allow` header on 405 and automatic `OPTIONS` responses, and the
9
+ * `ROUTE_NO_METHODS` lint together.
10
+ *
11
+ * `QUERY` is RFC 10008's safe, idempotent method with a request body.
12
+ * See design/07-routing.md §"Supported Methods".
13
+ */
14
+ export declare const HTTP_METHODS: readonly ['GET', 'QUERY', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
15
+ /** HTTP methods that route.ts can export as named handlers. */
16
+ export type HttpMethod = (typeof HTTP_METHODS)[number];
17
+ /**
18
+ * Whether a request method names a route.ts handler. Exact case: method
19
+ * names are case-sensitive (RFC 9110 §9.1), and the CSRF gate compares them
20
+ * exactly, so `query` is not `QUERY` here either.
21
+ */
22
+ export declare function isHttpMethod(method: string): method is HttpMethod;
23
+ //# sourceMappingURL=route-methods.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"route-methods.d.ts","sourceRoot":"","sources":["../../src/server/route-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,YACvB,KAAK,EACL,OAAO,EACP,MAAM,EACN,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,CACD,CAAC;AAEX,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAIvD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,UAAU,CAEjE"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@timber-js/app",
3
- "version": "0.2.0-alpha.226",
3
+ "version": "0.2.0-alpha.228",
4
4
  "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
5
5
  "keywords": [
6
6
  "cloudflare-workers",
@@ -167,7 +167,7 @@
167
167
  "@content-collections/vite": "^0.2.0 || ^0.3.0",
168
168
  "@typescript/native-preview": "^7.0.0-dev.0",
169
169
  "@vitejs/plugin-react": "^6.1.0",
170
- "@vitejs/plugin-rsc": "^0.5.36",
170
+ "@vitejs/plugin-rsc": "^0.5.39",
171
171
  "nuqs": "^2.0.0",
172
172
  "react": "19.3.1",
173
173
  "react-dom": "19.3.1",
@@ -21,7 +21,12 @@ import {
21
21
  buildStaticDirectoryOutput,
22
22
  writeHeadersFile,
23
23
  } from './build-output-helper.ts';
24
- import { adapterBase, generateHeadersFile } from './shared.ts';
24
+ import {
25
+ adapterBase,
26
+ generateHeadersFile,
27
+ generateRuntimeInitModule,
28
+ RUNTIME_INIT_MODULE,
29
+ } from './shared.ts';
25
30
  // Isomorphic, zero-import module — safe to load from an adapter, which Node's
26
31
  // native ESM loader evaluates before Vite's resolver exists. Same precedent as
27
32
  // `adapters/shared.ts` importing `../shared/base-path.js`.
@@ -321,7 +326,7 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
321
326
  // BEFORE the RSC entry evaluates (ESM import order). Without this,
322
327
  // createRequestHandler's auto-wire for WorkersCachePurge would not
323
328
  // detect the Cloudflare runtime (TIM-1170).
324
- await writeFile(join(outDir, '_timber-runtime-init.js'), generateRuntimeInitModule());
329
+ await writeFile(join(outDir, RUNTIME_INIT_MODULE), generateRuntimeInitModule('cloudflare'));
325
330
 
326
331
  // Generate the Workers entry point
327
332
  const hasManifestInit = !!artifacts.manifestInit;
@@ -647,23 +652,6 @@ globalThis.__TIMBER_PREBUILT_SOURCE__ = {
647
652
  `;
648
653
  }
649
654
 
650
- /**
651
- * Generate the runtime init module that sets TIMBER_RUNTIME before the
652
- * RSC entry evaluates. Imported as a side-effect module in _worker.js.
653
- *
654
- * @internal Exported for testing.
655
- */
656
- export function generateRuntimeInitModule(): string {
657
- return `// Generated by @timber-js/app/adapters/cloudflare
658
- // Sets TIMBER_RUNTIME before the RSC handler evaluates (TIM-1170).
659
- // Must be a separate module imported before rsc/index.js so that ESM
660
- // evaluation order guarantees the env var is set when
661
- // createRequestHandler() runs its auto-wire logic.
662
- globalThis.process ??= { env: {} }
663
- process.env.TIMBER_RUNTIME = 'cloudflare'
664
- `;
665
- }
666
-
667
655
  /** Wrangler binding sections generated from `CloudflareBindings`. */
668
656
  export interface WranglerBindingsConfig {
669
657
  kv_namespaces?: Array<{ binding: string; id: string }>;
@@ -23,7 +23,7 @@ import {
23
23
  generateSendResponseModule,
24
24
  spawnNitroPreview,
25
25
  } from './nitro-preview.ts';
26
- import { adapterBase } from './shared.ts';
26
+ import { adapterBase, generateRuntimeInitModule, RUNTIME_INIT_MODULE } from './shared.ts';
27
27
  import { HEADERS_FILE, REDIRECTS_FILE } from '../shared/static-platform-files.ts';
28
28
  import type {
29
29
  BuildArtifacts,
@@ -215,6 +215,13 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
215
215
  await writeFile(rscEntry, `${artifacts.manifestInit}\n${rscContent}`);
216
216
  }
217
217
 
218
+ // Sets TIMBER_RUNTIME ahead of the RSC entry's top-level await of
219
+ // instrumentation register(); the entry imports it first.
220
+ await writeFile(
221
+ join(outDir, RUNTIME_INIT_MODULE),
222
+ generateRuntimeInitModule(PRESET_CONFIGS[preset].runtimeName)
223
+ );
224
+
218
225
  // Generate the Nitro entry point (imports from ./rsc/ within nitro dir)
219
226
  const entry = generateNitroEntry(preset, compress, artifacts.immutableDirs);
220
227
  await writeFile(join(outDir, 'entry.ts'), entry);
@@ -303,7 +310,6 @@ export function generateNitroEntry(
303
310
  // The manifest init is prepended to rsc/index.js before the nitro build,
304
311
  // so globalThis.__TIMBER_BUILD_MANIFEST__ is set before any code reads it.
305
312
  const serverEntryRelative = './rsc/index.js';
306
- const runtimeName = PRESET_CONFIGS[preset].runtimeName;
307
313
  const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;
308
314
  const supportsWaitUntil = PRESET_CONFIGS[preset].supportsWaitUntil;
309
315
 
@@ -363,11 +369,12 @@ export function generateNitroEntry(
363
369
  return `// Generated by @timber-js/app/adapters/nitro
364
370
  // Do not edit — this file is regenerated on each build.
365
371
 
372
+ // Side-effect import, first: sets TIMBER_RUNTIME before the RSC entry (and
373
+ // its top-level await of instrumentation register()) evaluates.
374
+ // See design/25-production-deployments.md §"TIMBER_RUNTIME".
375
+ import './${RUNTIME_INIT_MODULE}'
366
376
  import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
367
377
  ${compressImport}${immutableAssets.imports}
368
- // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
369
- // See design/25-production-deployments.md §"TIMBER_RUNTIME".
370
- process.env.TIMBER_RUNTIME = '${runtimeName}'
371
378
 
372
379
  // Nitro's index.mjs wraps this import with defineLazyEventHandler, which
373
380
  // already handles the event handler protocol. We export a plain async
@@ -281,3 +281,34 @@ export function generateHeadersFile({
281
281
 
282
282
  return content;
283
283
  }
284
+
285
+ // ─── TIMBER_RUNTIME ──────────────────────────────────────────────────────
286
+
287
+ /** File name of the generated module that sets `TIMBER_RUNTIME`. */
288
+ export const RUNTIME_INIT_MODULE = '_timber-runtime-init.js';
289
+
290
+ /**
291
+ * Generate the module that sets `process.env.TIMBER_RUNTIME`.
292
+ *
293
+ * It must be its own module, imported for side effects ahead of the RSC
294
+ * entry. ESM evaluates every import of a module — including the imported
295
+ * module's top-level await — before that module's own body runs, and the
296
+ * RSC entry awaits `register()` from instrumentation.ts at top level. An
297
+ * assignment in the importing entry's body would therefore run after
298
+ * `register()` has already read the variable. A side-effect import listed
299
+ * first is evaluated first. See design/25-production-deployments.md
300
+ * §"TIMBER_RUNTIME".
301
+ *
302
+ * `globalThis.process ??= { env: {} }` covers runtimes without a Node
303
+ * `process` global (Workers without nodejs_compat, some edge presets).
304
+ */
305
+ export function generateRuntimeInitModule(runtimeName: string): string {
306
+ return `// Generated by @timber-js/app — do not edit.
307
+ // Sets TIMBER_RUNTIME before the RSC entry evaluates. Imported as a
308
+ // side-effect module ahead of the RSC entry so ESM evaluation order
309
+ // guarantees instrumentation.ts register() sees it.
310
+ globalThis.process ??= { env: {} }
311
+ globalThis.process.env ??= {}
312
+ process.env.TIMBER_RUNTIME = ${JSON.stringify(runtimeName)}
313
+ `;
314
+ }
@@ -20,6 +20,7 @@
20
20
  import { existsSync } from 'node:fs';
21
21
  import type { RouteFile, RouteTree, SegmentNode } from './types.ts';
22
22
  import { swallow } from '../server/logger.ts';
23
+ import { HTTP_METHODS } from '../server/route-methods.ts';
23
24
  import {
24
25
  fileDefaultExportIsLocalValue,
25
26
  fileHasAnyExport,
@@ -247,9 +248,6 @@ function hasAnyPage(node: SegmentNode): boolean {
247
248
 
248
249
  // ─── Check: Route Exports ───────────────────────────────────────────────────
249
250
 
250
- /** HTTP methods that route.ts can export. */
251
- const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'] as const;
252
-
253
251
  /**
254
252
  * Warn when a route.ts file doesn't appear to export any recognized HTTP methods.
255
253
  *
@@ -11,8 +11,9 @@
11
11
  *
12
12
  * Keep this as thin pass-through re-exports — the value is the single choke
13
13
  * point, not abstraction. The exceptions are `renderFlight`, the only way to
14
- * render Flight (render-flight.ts), and `loadServerAction`, which tells an
15
- * unknown reference from a broken module (server-references.ts). Bound-args encryption is plugin-rsc's
14
+ * render Flight (render-flight.ts), and `loadServerAction`, `decodeReply` and
15
+ * `decodeAction`, which tell an unknown reference from a broken module
16
+ * (server-references.ts). Bound-args encryption is plugin-rsc's
16
17
  * injected runtime, resolved to encryption-runtime.ts so it renders through
17
18
  * `renderFlight` too.
18
19
  */
@@ -22,13 +23,13 @@ import { scopeReferenceCacheToGeneration } from './dev-reference-cache.ts';
22
23
  // The only way to render Flight; see render-flight.ts.
23
24
  export { renderFlight } from './render-flight.ts';
24
25
 
25
- // Resolves an unknown reference to undefined instead of rejecting, so a
26
- // rejection means a real module failed to load; see server-references.ts.
27
- export { loadServerAction } from './server-references.ts';
26
+ // `loadServerAction` resolves an unknown reference to undefined instead of
27
+ // rejecting, so a rejection means a real module failed to load. The decoders
28
+ // reject with `ServerReferenceLoadError` (server-reference-load-error.ts) for
29
+ // that case alone. See server-references.ts.
30
+ export { loadServerAction, decodeReply, decodeAction } from './server-references.ts';
28
31
 
29
32
  export {
30
- decodeReply,
31
- decodeAction,
32
33
  // No-JS action result → the `useActionState` hook that submitted it
33
34
  // (server/action-handler.ts), as Next.js does in its action handler.
34
35
  decodeFormState,
@@ -0,0 +1,16 @@
1
+ /**
2
+ * A server reference a request body named is a known module that failed to
3
+ * load: the server's fault, where any other decode failure is the client's.
4
+ * `cause` is the module's own error. Thrown by `decodeReply` and
5
+ * `decodeAction` (server-references.ts); kept apart from them so code that
6
+ * only checks for it does not import plugin-rsc's virtual modules.
7
+ */
8
+ export class ServerReferenceLoadError extends Error {
9
+ constructor(
10
+ readonly referenceId: string,
11
+ options: { cause: unknown }
12
+ ) {
13
+ super(`Server reference "${referenceId}" failed to load`, options);
14
+ this.name = 'ServerReferenceLoadError';
15
+ }
16
+ }
@@ -16,10 +16,18 @@
16
16
  * plugin-rsc's loader reads, and an unknown module resolves to `undefined`:
17
17
  * what plugin-rsc already resolves for an unknown export of a known module.
18
18
  * A rejection from the load itself is then a real failure.
19
+ *
20
+ * `decodeReply` and `decodeAction` make the same split for the references a
21
+ * request body names, which React loads while it decodes.
19
22
  */
20
23
 
21
- import { loadServerAction as loadServerReference } from '@vitejs/plugin-rsc/rsc';
24
+ import {
25
+ decodeAction as decodeActionWith,
26
+ decodeReply as decodeReplyWith,
27
+ loadServerAction as loadServerReference,
28
+ } from '@vitejs/plugin-rsc/rsc';
22
29
  import serverReferences from 'virtual:vite-rsc/server-references';
30
+ import { ServerReferenceLoadError } from './server-reference-load-error.ts';
23
31
 
24
32
  /**
25
33
  * Whether plugin-rsc knows `moduleId` as a `'use server'` module.
@@ -71,3 +79,57 @@ export async function loadServerAction(id: string): Promise<unknown> {
71
79
  if (!(await isServerReferenceModule(moduleId))) return undefined;
72
80
  return loadServerReference(id);
73
81
  }
82
+
83
+ type ServerReferenceListener = (reference: { id: string; name: string }) => void;
84
+
85
+ /**
86
+ * Run a plugin-rsc decode, and when it rejects, say whose fault it was.
87
+ *
88
+ * React loads every server reference the body names while it decodes (the
89
+ * no-JS action itself, and server functions passed as arguments or bound to
90
+ * one) and rejects the same way for a reference that does not exist and a
91
+ * module that fails to load. plugin-rsc reports each reference before it
92
+ * loads (`onServerReference`). The callback is synchronous and the dev
93
+ * lookup is not, so the references are only collected here. After a failed
94
+ * decode, each is loaded again through `loadServerAction`, which resolves an
95
+ * unknown one to undefined and rejects only for a known module that does not
96
+ * load. That rejection becomes a `ServerReferenceLoadError`. Anything else
97
+ * (a made-up reference, a body that will not parse) rethrows as the client
98
+ * error it is.
99
+ */
100
+ async function decodeNamingFaults<T>(
101
+ decode: (onServerReference: ServerReferenceListener) => Promise<T>
102
+ ): Promise<T> {
103
+ const references = new Set<string>();
104
+ try {
105
+ return await decode(({ id, name }) => references.add(`${id}#${name}`));
106
+ } catch (error) {
107
+ for (const reference of references) {
108
+ try {
109
+ await loadServerAction(reference);
110
+ } catch (loadError) {
111
+ throw new ServerReferenceLoadError(reference, { cause: loadError });
112
+ }
113
+ }
114
+ throw error;
115
+ }
116
+ }
117
+
118
+ /**
119
+ * plugin-rsc's `decodeReply`, rejecting with `ServerReferenceLoadError` when
120
+ * a server function among the arguments names a module that fails to load.
121
+ */
122
+ export function decodeReply(body: string | FormData): Promise<unknown[]> {
123
+ return decodeNamingFaults((onServerReference) =>
124
+ decodeReplyWith(body, undefined, { onServerReference })
125
+ );
126
+ }
127
+
128
+ /**
129
+ * plugin-rsc's `decodeAction`, rejecting with `ServerReferenceLoadError`
130
+ * when the form's action, or a server function bound to it, names a module
131
+ * that fails to load.
132
+ */
133
+ export function decodeAction(body: FormData): Promise<() => Promise<void>> {
134
+ return decodeNamingFaults((onServerReference) => decodeActionWith(body, { onServerReference }));
135
+ }
@@ -21,6 +21,9 @@ import {
21
21
  decodeFormState,
22
22
  renderFlight,
23
23
  } from '../rsc-runtime/rsc.ts';
24
+ // Not through rsc.ts: the class has no plugin-rsc dependency, so tests that
25
+ // stand in for the runtime do not have to provide it.
26
+ import { ServerReferenceLoadError } from '../rsc-runtime/server-reference-load-error.ts';
24
27
  import { flightChunkBytes, flightResponse, openFlightReader } from './flight-source.ts';
25
28
  import { concatBytes } from './stream-utils.ts';
26
29
 
@@ -96,11 +99,13 @@ export function isActionRequest(req: Request): boolean {
96
99
  * with `formState` — React's `decodeFormState` of the result, present
97
100
  * only when the submitted form used `useActionState` — handed to SSR
98
101
  * and hydration, where React gives it to the hook that submitted.
99
- * - `error`: the action threw. The page is rendered again with the error
100
- * in place of the page component, so the route's nearest error page
101
- * answers, with the
102
- * status the pipeline gives any unhandled error. The JS path rejects
103
- * the action for the same throw, so both reach an error boundary.
102
+ * - `error`: the action threw, or a module it needs (its own, or the one a
103
+ * server function bound to it lives in) failed to load. The page is
104
+ * rendered again with the error in place of the page component, so the
105
+ * route's nearest error page answers, with the status the pipeline gives
106
+ * any unhandled error. The JS path rejects the action for the same
107
+ * throw, and answers the load failure with a 500, so both reach an
108
+ * error boundary.
104
109
  *
105
110
  * Carries two cookie-related snapshots taken before the action's ALS scope
106
111
  * exits, so the rerender pipeline (which establishes its own fresh cookie
@@ -176,6 +181,11 @@ export async function handleActionRequest(
176
181
  // handleActionRequest remains safe to call from any entry point that
177
182
  // bypasses the gate — and it never applies the per-route exemption, which
178
183
  // is for route.ts only. See LOCAL-773, TIM-1543.
184
+ //
185
+ // It protects only unsafe methods. `validateCsrf` passes safe methods,
186
+ // including `QUERY` (TIM-1619), so an entry point that hands this function
187
+ // anything but a POST must check the method itself; today the only caller
188
+ // is behind `isActionRequest`, which is POST-only.
179
189
  const csrfResult = validateCsrf(req, config.csrf);
180
190
  if (!csrfResult.ok) {
181
191
  return csrfRejectionResponse(req, csrfResult);
@@ -277,11 +287,11 @@ async function reportRevalidationErrors(req: Request, errors: readonly unknown[]
277
287
  * Any client can send these, so they are logged at warn with the reason and
278
288
  * no stack, and are not reported to `onRequestError`: an error tracker would
279
289
  * otherwise record whatever a client makes up (TIM-1601). A known action
280
- * module that fails to load is the server's fault, and `decodeRscActionCall`
281
- * answers it with a 500 and reports it. Two loads cannot be split that way
282
- * and land here: a server function passed as an argument, which
283
- * `decodeReply` loads, and the no-JS action, which `decodeAction` loads.
284
- * Their module's error is still the logged reason.
290
+ * module that fails to load is the server's fault, wherever it is loaded:
291
+ * the action by ID, a server function passed as an argument (`decodeReply`),
292
+ * or the no-JS action and what is bound to it (`decodeAction`). It is
293
+ * answered with a 500 (the no-JS path renders the error page) and reported,
294
+ * and never gets here.
285
295
  */
286
296
  function rejectActionRequest(req: Request, reason: unknown): Response {
287
297
  logActionRejected({
@@ -382,6 +392,12 @@ async function decodeRscActionCall(
382
392
  decoded = await decodeReply(await req.text());
383
393
  }
384
394
  } catch (error) {
395
+ if (error instanceof ServerReferenceLoadError) {
396
+ // A server function among the arguments lives in a module that does
397
+ // not load: the same server fault as the action's own module above.
398
+ await reportActionError(req, error.cause);
399
+ return new Response(null, { status: 500 });
400
+ }
385
401
  return rejectActionRequest(req, error);
386
402
  }
387
403
  // The client always encodes an argument list. Anything else would fail
@@ -643,13 +659,16 @@ async function handleFormAction(
643
659
  try {
644
660
  actionFn = (await decodeAction(formData)) as ((...args: unknown[]) => Promise<unknown>) | null;
645
661
  } catch (error) {
646
- // decodeAction both decodes the form's `$ACTION_REF_` metadata and loads
647
- // the module, and React does not say which failed. On a no-JS POST that
648
- // metadata is written by React into the form, so a failure is almost
649
- // always a forged or truncated request: 400, logged at warn with the
650
- // error as the reason. A module that genuinely fails to import also
651
- // breaks the RSC render of a page that imports it, which reports it; an
652
- // action module only a client component imports gets the warning alone.
662
+ if (error instanceof ServerReferenceLoadError) {
663
+ // The action's module, or the module of a server function bound to
664
+ // it, does not load: a server fault, answered with the error page as
665
+ // an action that threw is.
666
+ const errorId = randomUUID();
667
+ await reportActionError(req, error.cause, errorId);
668
+ return { kind: 'error', error: error.cause, errorId };
669
+ }
670
+ // Forged or truncated `$ACTION_REF_` metadata, or a reference to a
671
+ // module or export that does not exist: the client's mistake.
653
672
  return rejectActionRequest(req, error);
654
673
  }
655
674
  if (!actionFn) {
@@ -64,8 +64,16 @@ export type CsrfResult = { ok: true } | CsrfRejection;
64
64
 
65
65
  // ─── Constants ────────────────────────────────────────────────────────────
66
66
 
67
- /** HTTP methods that are considered safe (no mutation). */
68
- const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
67
+ /**
68
+ * HTTP methods that are considered safe (no mutation). `QUERY` (RFC 10008)
69
+ * is safe by definition, is not a CORS-safelisted method, so a cross-origin
70
+ * browser `QUERY` is preflighted, and HTML forms cannot send it: a cross-site
71
+ * page cannot make a browser send one with the user's cookies unless the
72
+ * app's own CORS policy allows it. A handler
73
+ * that mutates on `QUERY` breaks the method's contract, as one that mutates
74
+ * on `GET` does.
75
+ */
76
+ const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'QUERY']);
69
77
 
70
78
  /**
71
79
  * `Sec-Fetch-Site` values that mean the browser itself vouches for the
@@ -112,7 +120,7 @@ function deriveRequestScheme(req: Request): string {
112
120
  * origin derived from the scheme and `Host`.
113
121
  * 4. Neither header → allow: not a browser, so no ambient cookies to abuse.
114
122
  *
115
- * Safe methods (GET, HEAD, OPTIONS) and `csrf: false` always pass.
123
+ * Safe methods (GET, HEAD, OPTIONS, QUERY) and `csrf: false` always pass.
116
124
  */
117
125
  export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
118
126
  if (SAFE_METHODS.has(req.method)) return { ok: true };
@@ -145,7 +145,8 @@ export type {
145
145
 
146
146
  // ── Route Handler ────────────────────────────────────────────────────────
147
147
  export { handleRouteRequest, resolveAllowedMethods } from './route-handler.ts';
148
- export type { RouteModule, RouteHandler, HttpMethod } from './route-handler.ts';
148
+ export type { RouteModule, RouteHandler } from './route-handler.ts';
149
+ export type { HttpMethod } from './route-methods.ts';
149
150
 
150
151
  // ── Render Timeout ───────────────────────────────────────────────────────
151
152
  export { RenderTimeoutError } from './render-timeout.ts';
@@ -13,12 +13,10 @@ import { stripHeadBody } from './head-response.ts';
13
13
  import { setMutableCookieContext } from './request-context.ts';
14
14
  import { getSetCookieHeaders } from './cookie-context.ts';
15
15
  import { syncCookieJar } from './pipeline-helpers.ts';
16
+ import { HTTP_METHODS, isHttpMethod, type HttpMethod } from './route-methods.ts';
16
17
 
17
18
  // ─── Types ───────────────────────────────────────────────────────────────
18
19
 
19
- /** HTTP methods that route.ts can export as named handlers. */
20
- export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
21
-
22
20
  /** A single route handler function — one-arg signature. */
23
21
  export type RouteHandler = (ctx: RouteContext) => Response | Promise<Response>;
24
22
 
@@ -27,9 +25,6 @@ export type RouteModule = {
27
25
  [K in HttpMethod]?: RouteHandler;
28
26
  };
29
27
 
30
- /** All recognized HTTP method export names. */
31
- const HTTP_METHODS: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
32
-
33
28
  // ─── Allowed Methods ─────────────────────────────────────────────────────
34
29
 
35
30
  /**
@@ -51,18 +46,10 @@ export function resolveAllowedMethods(mod: RouteModule): HttpMethod[] {
51
46
  }
52
47
 
53
48
  // HEAD is implicit when GET is exported
54
- if (mod.GET && !mod.HEAD) {
55
- methods.push('HEAD');
56
- } else if (mod.HEAD) {
57
- methods.push('HEAD');
58
- }
49
+ if (mod.GET || mod.HEAD) methods.push('HEAD');
59
50
 
60
51
  // OPTIONS is always implicit
61
- if (!mod.OPTIONS) {
62
- methods.push('OPTIONS');
63
- } else {
64
- methods.push('OPTIONS');
65
- }
52
+ methods.push('OPTIONS');
66
53
 
67
54
  return methods;
68
55
  }
@@ -76,7 +63,7 @@ export function resolveAllowedMethods(mod: RouteModule): HttpMethod[] {
76
63
  * and merges response headers from ctx.headers.
77
64
  */
78
65
  export async function handleRouteRequest(mod: RouteModule, ctx: RouteContext): Promise<Response> {
79
- const method = ctx.req.method.toUpperCase() as HttpMethod;
66
+ const method = ctx.req.method;
80
67
  const allowed = resolveAllowedMethods(mod);
81
68
  const allowHeader = allowed.join(', ');
82
69
 
@@ -106,8 +93,10 @@ export async function handleRouteRequest(mod: RouteModule, ctx: RouteContext): P
106
93
  }
107
94
  }
108
95
 
109
- // Dispatch to the named handler
110
- const handler = mod[method];
96
+ // Dispatch to the named handler. Only a listed method is a handler: an
97
+ // export named for any other token (`PROPFIND`, lowercase `query`) is not
98
+ // dispatched, matching the Allow header and the convention lint.
99
+ const handler = isHttpMethod(method) ? mod[method] : undefined;
111
100
  if (!handler) {
112
101
  return mergeResponseHeaders(
113
102
  new Response(null, { status: 405, headers: { Allow: allowHeader } }),
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The HTTP methods a `route.ts` can export as named handlers.
3
+ *
4
+ * A leaf module with no imports, so the build-time convention lint
5
+ * (`routing/convention-lint.ts`) and the runtime dispatcher
6
+ * (`server/route-handler.ts`) read one list without the lint pulling in
7
+ * the request runtime. Adding a method here updates the `RouteModule` type,
8
+ * the `Allow` header on 405 and automatic `OPTIONS` responses, and the
9
+ * `ROUTE_NO_METHODS` lint together.
10
+ *
11
+ * `QUERY` is RFC 10008's safe, idempotent method with a request body.
12
+ * See design/07-routing.md §"Supported Methods".
13
+ */
14
+ export const HTTP_METHODS = [
15
+ 'GET',
16
+ 'QUERY',
17
+ 'POST',
18
+ 'PUT',
19
+ 'PATCH',
20
+ 'DELETE',
21
+ 'HEAD',
22
+ 'OPTIONS',
23
+ ] as const;
24
+
25
+ /** HTTP methods that route.ts can export as named handlers. */
26
+ export type HttpMethod = (typeof HTTP_METHODS)[number];
27
+
28
+ const METHOD_SET: ReadonlySet<string> = new Set(HTTP_METHODS);
29
+
30
+ /**
31
+ * Whether a request method names a route.ts handler. Exact case: method
32
+ * names are case-sensitive (RFC 9110 §9.1), and the CSRF gate compares them
33
+ * exactly, so `query` is not `QUERY` here either.
34
+ */
35
+ export function isHttpMethod(method: string): method is HttpMethod {
36
+ return METHOD_SET.has(method);
37
+ }
@@ -341,7 +341,7 @@ export async function setSpanAttribute(
341
341
  if (!api) return;
342
342
 
343
343
  const activeSpan = api.trace.getActiveSpan();
344
- if (activeSpan) {
344
+ if (activeSpan?.isRecording()) {
345
345
  activeSpan.setAttribute(key, value);
346
346
  }
347
347
  }
@@ -358,7 +358,7 @@ export async function addSpanEvent(
358
358
  if (!api) return;
359
359
 
360
360
  const activeSpan = api.trace.getActiveSpan();
361
- if (activeSpan) {
361
+ if (activeSpan?.isRecording()) {
362
362
  activeSpan.addEvent(name, attributes);
363
363
  }
364
364
  }
@@ -381,7 +381,7 @@ export function addSpanEventSync(
381
381
  if (!_otelApi) return;
382
382
 
383
383
  const activeSpan = _otelApi.trace.getActiveSpan();
384
- if (activeSpan) {
384
+ if (activeSpan?.isRecording()) {
385
385
  activeSpan.addEvent(name, attributes);
386
386
  }
387
387
  }