@timber-js/app 0.2.0-alpha.227 → 0.2.0-alpha.229

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 (164) hide show
  1. package/agent-skill.md +9 -0
  2. package/dist/_chunks/{actions-B1xSIv32.js → actions-DHum77eH.js} +3 -3
  3. package/dist/_chunks/{actions-B1xSIv32.js.map → actions-DHum77eH.js.map} +1 -1
  4. package/dist/_chunks/{cache-api-DsSXA4Sp.js → cache-api-BZJNt01a.js} +4 -4
  5. package/dist/_chunks/{cache-api-DsSXA4Sp.js.map → cache-api-BZJNt01a.js.map} +1 -1
  6. package/dist/_chunks/{chains-Dgm3PrMe.js → chains-D-RRc7CM.js} +2 -2
  7. package/dist/_chunks/{chains-Dgm3PrMe.js.map → chains-D-RRc7CM.js.map} +1 -1
  8. package/dist/_chunks/chains-KblEfYzm.js +1 -0
  9. package/dist/_chunks/{classify--_kINHQV.js → classify-_W0RWa5w.js} +2 -2
  10. package/dist/_chunks/{classify--_kINHQV.js.map → classify-_W0RWa5w.js.map} +1 -1
  11. package/dist/_chunks/{cli-check-B33yhAPa.js → cli-check-B-JZkpBD.js} +3 -3
  12. package/dist/_chunks/{cli-check-B33yhAPa.js.map → cli-check-B-JZkpBD.js.map} +1 -1
  13. package/dist/_chunks/{cli-schema-sync-DIPurq7X.js → cli-schema-sync-CAllbqRB.js} +2 -2
  14. package/dist/_chunks/{cli-schema-sync-DIPurq7X.js.map → cli-schema-sync-CAllbqRB.js.map} +1 -1
  15. package/dist/_chunks/{cli-schema-sync-uq72EZmD.js → cli-schema-sync-y_8ijmzO.js} +1 -1
  16. package/dist/_chunks/{client-dep-entries-CP7AkMCM.js → client-dep-entries-C9hv-3k9.js} +2 -2
  17. package/dist/_chunks/{client-dep-entries-CP7AkMCM.js.map → client-dep-entries-C9hv-3k9.js.map} +1 -1
  18. package/dist/_chunks/{convention-lint-hZwz5wd4.js → convention-lint-CrDKERHg.js} +4 -13
  19. package/dist/_chunks/convention-lint-CrDKERHg.js.map +1 -0
  20. package/dist/_chunks/dev-server-L8biS7Az.js +1 -0
  21. package/dist/_chunks/{dev-server-B7o4As0l.js → dev-server-Rq659RR1.js} +8 -2
  22. package/dist/_chunks/dev-server-Rq659RR1.js.map +1 -0
  23. package/dist/_chunks/{build-manifest-Y4jl7nwU.js → dev-span-_NzMX-au.js} +25 -2
  24. package/dist/_chunks/dev-span-_NzMX-au.js.map +1 -0
  25. package/dist/_chunks/{error-boundary-D3YyVVuP.js → error-boundary-OHK1mI99.js} +3 -3
  26. package/dist/_chunks/{error-boundary-D3YyVVuP.js.map → error-boundary-OHK1mI99.js.map} +1 -1
  27. package/dist/_chunks/{flight-source-node-0Tp6evlz.js → flight-source-node-BGanuoSS.js} +2 -2
  28. package/dist/_chunks/{flight-source-node-0Tp6evlz.js.map → flight-source-node-BGanuoSS.js.map} +1 -1
  29. package/dist/_chunks/{global-context-DbxNWeBP.js → global-context-CFSSysdJ.js} +32 -2
  30. package/dist/_chunks/global-context-CFSSysdJ.js.map +1 -0
  31. package/dist/_chunks/{json-lossy-check-DVkLUlfC.js → json-lossy-check-BXM45k8p.js} +2 -2
  32. package/dist/_chunks/{json-lossy-check-DVkLUlfC.js.map → json-lossy-check-BXM45k8p.js.map} +1 -1
  33. package/dist/_chunks/{live-graph-BcVjQ1Te.js → live-graph-C7-yA8W9.js} +4 -4
  34. package/dist/_chunks/{live-graph-BcVjQ1Te.js.map → live-graph-C7-yA8W9.js.map} +1 -1
  35. package/dist/_chunks/{logger-CWk44DLp.js → logger-YtMSKfft.js} +103 -60
  36. package/dist/_chunks/logger-YtMSKfft.js.map +1 -0
  37. package/dist/_chunks/navigation-root-CoGHIMiE.js +239 -0
  38. package/dist/_chunks/navigation-root-CoGHIMiE.js.map +1 -0
  39. package/dist/_chunks/{node-response-B9aviPDa.js → node-response-D3hXWb8y.js} +2 -2
  40. package/dist/_chunks/{node-response-B9aviPDa.js.map → node-response-D3hXWb8y.js.map} +1 -1
  41. package/dist/_chunks/{poison-scan-DJYxZc_7.js → poison-scan-CRSP06Es.js} +2 -2
  42. package/dist/_chunks/{poison-scan-DJYxZc_7.js.map → poison-scan-CRSP06Es.js.map} +1 -1
  43. package/dist/_chunks/route-methods-Dk2kZc0n.js +36 -0
  44. package/dist/_chunks/route-methods-Dk2kZc0n.js.map +1 -0
  45. package/dist/_chunks/{scanner-CJC-ScJU.js → scanner-BNQ4qnLX.js} +2 -2
  46. package/dist/_chunks/{scanner-CJC-ScJU.js.map → scanner-BNQ4qnLX.js.map} +1 -1
  47. package/dist/_chunks/segment-context-GAyTjjtS.js +33 -0
  48. package/dist/_chunks/segment-context-GAyTjjtS.js.map +1 -0
  49. package/dist/_chunks/{sizeof-DG4W40lv.js → sizeof-Cmx6Fs-Y.js} +2 -2
  50. package/dist/_chunks/{sizeof-DG4W40lv.js.map → sizeof-Cmx6Fs-Y.js.map} +1 -1
  51. package/dist/_chunks/{status-page-marker-C8POawuF.js → status-page-marker-U6B1aFMb.js} +3 -32
  52. package/dist/_chunks/status-page-marker-U6B1aFMb.js.map +1 -0
  53. package/dist/_chunks/{walkers-DIE203ir.js → walkers-D_QHR_nf.js} +3 -3
  54. package/dist/_chunks/{walkers-DIE203ir.js.map → walkers-D_QHR_nf.js.map} +1 -1
  55. package/dist/adapters/cloudflare-kv-cache.js +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/client/browser-entry/hmr.d.ts +7 -1
  62. package/dist/client/browser-entry/hmr.d.ts.map +1 -1
  63. package/dist/client/dev-pill/index.d.ts +32 -0
  64. package/dist/client/dev-pill/index.d.ts.map +1 -0
  65. package/dist/client/dev-pill/store.d.ts +96 -0
  66. package/dist/client/dev-pill/store.d.ts.map +1 -0
  67. package/dist/client/dev-pill/view.d.ts +9 -0
  68. package/dist/client/dev-pill/view.d.ts.map +1 -0
  69. package/dist/client/error-boundary.js +1 -1
  70. package/dist/client/index.d.ts +1 -0
  71. package/dist/client/index.d.ts.map +1 -1
  72. package/dist/client/index.js +3 -3
  73. package/dist/client/internal.js +16 -7
  74. package/dist/client/internal.js.map +1 -1
  75. package/dist/client/navigation-context.d.ts +20 -0
  76. package/dist/client/navigation-context.d.ts.map +1 -1
  77. package/dist/client/router-lifecycle.d.ts +4 -1
  78. package/dist/client/router-lifecycle.d.ts.map +1 -1
  79. package/dist/client/use-pending-navigation.d.ts +33 -9
  80. package/dist/client/use-pending-navigation.d.ts.map +1 -1
  81. package/dist/config-types.d.ts +10 -0
  82. package/dist/config-types.d.ts.map +1 -1
  83. package/dist/config-validation.d.ts.map +1 -1
  84. package/dist/dev-tools/await-span.d.ts +17 -0
  85. package/dist/dev-tools/await-span.d.ts.map +1 -0
  86. package/dist/dev-tools/instrumentation.d.ts.map +1 -1
  87. package/dist/dev-tools/logger.d.ts.map +1 -1
  88. package/dist/dev-tools/logs.d.ts.map +1 -1
  89. package/dist/dev-tools/span-sink.d.ts +42 -0
  90. package/dist/dev-tools/span-sink.d.ts.map +1 -0
  91. package/dist/index.d.ts.map +1 -1
  92. package/dist/index.js +282 -9
  93. package/dist/index.js.map +1 -1
  94. package/dist/plugins/dev-await.d.ts +40 -0
  95. package/dist/plugins/dev-await.d.ts.map +1 -0
  96. package/dist/plugins/entries.d.ts.map +1 -1
  97. package/dist/routing/convention-lint.d.ts.map +1 -1
  98. package/dist/routing/index.js +2 -2
  99. package/dist/server/action-handler.d.ts.map +1 -1
  100. package/dist/server/csrf.d.ts +1 -1
  101. package/dist/server/csrf.d.ts.map +1 -1
  102. package/dist/server/index.js +2 -2
  103. package/dist/server/internal.d.ts +2 -1
  104. package/dist/server/internal.d.ts.map +1 -1
  105. package/dist/server/internal.js +26 -27
  106. package/dist/server/internal.js.map +1 -1
  107. package/dist/server/pipeline.d.ts +8 -0
  108. package/dist/server/pipeline.d.ts.map +1 -1
  109. package/dist/server/route-handler.d.ts +1 -2
  110. package/dist/server/route-handler.d.ts.map +1 -1
  111. package/dist/server/route-methods.d.ts +23 -0
  112. package/dist/server/route-methods.d.ts.map +1 -0
  113. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  114. package/dist/server/slot-resolver.d.ts.map +1 -1
  115. package/dist/server/tracing.d.ts +18 -8
  116. package/dist/server/tracing.d.ts.map +1 -1
  117. package/dist/shared/dev-span.d.ts +97 -0
  118. package/dist/shared/dev-span.d.ts.map +1 -0
  119. package/docs/api/31-api-client.mdx +27 -1
  120. package/docs/api/34-api-config.mdx +21 -1
  121. package/docs/learn/09-streaming.mdx +7 -1
  122. package/package.json +3 -3
  123. package/src/client/browser-entry/hmr.ts +13 -1
  124. package/src/client/browser-entry/index.ts +4 -1
  125. package/src/client/dev-pill/index.ts +128 -0
  126. package/src/client/dev-pill/store.ts +231 -0
  127. package/src/client/dev-pill/view.ts +278 -0
  128. package/src/client/index.ts +1 -0
  129. package/src/client/navigation-context.ts +5 -2
  130. package/src/client/router-lifecycle.ts +23 -3
  131. package/src/client/use-pending-navigation.ts +93 -14
  132. package/src/config-types.ts +10 -0
  133. package/src/config-validation.ts +10 -0
  134. package/src/dev-tools/await-span.ts +40 -0
  135. package/src/dev-tools/instrumentation.ts +20 -0
  136. package/src/dev-tools/logger.ts +3 -37
  137. package/src/dev-tools/logs.ts +10 -1
  138. package/src/dev-tools/span-sink.ts +132 -0
  139. package/src/index.ts +2 -0
  140. package/src/plugins/dev-await.ts +268 -0
  141. package/src/plugins/entries.ts +2 -0
  142. package/src/routing/convention-lint.ts +1 -3
  143. package/src/server/action-handler.ts +5 -0
  144. package/src/server/csrf.ts +11 -3
  145. package/src/server/internal.ts +2 -1
  146. package/src/server/pipeline.ts +14 -0
  147. package/src/server/route-handler.ts +8 -19
  148. package/src/server/route-methods.ts +37 -0
  149. package/src/server/rsc-entry/index.ts +7 -1
  150. package/src/server/slot-resolver.ts +45 -5
  151. package/src/server/tracing.ts +124 -90
  152. package/src/shared/dev-span.ts +182 -0
  153. package/dist/_chunks/build-manifest-Y4jl7nwU.js.map +0 -1
  154. package/dist/_chunks/chains-CwOr3Myj.js +0 -1
  155. package/dist/_chunks/convention-lint-hZwz5wd4.js.map +0 -1
  156. package/dist/_chunks/dev-server-B7o4As0l.js.map +0 -1
  157. package/dist/_chunks/dev-server-hZzmbMvK.js +0 -1
  158. package/dist/_chunks/global-context-DbxNWeBP.js.map +0 -1
  159. package/dist/_chunks/logger-CWk44DLp.js.map +0 -1
  160. package/dist/_chunks/navigation-root-M3B2ZrdO.js +0 -122
  161. package/dist/_chunks/navigation-root-M3B2ZrdO.js.map +0 -1
  162. package/dist/_chunks/segment-context-CYiGTi3K.js +0 -131
  163. package/dist/_chunks/segment-context-CYiGTi3K.js.map +0 -1
  164. package/dist/_chunks/status-page-marker-C8POawuF.js.map +0 -1
@@ -0,0 +1,268 @@
1
+ /**
2
+ * timber-dev-await — dev-only transform that turns every `await` in app
3
+ * server code into a span, so postgres queries, redis calls and SDK
4
+ * requests appear in the terminal tree and the dev request pill without
5
+ * per-library instrumentation.
6
+ *
7
+ * const rows = await db.select().from(users);
8
+ * // becomes
9
+ * const rows = await __timber_await$(async () => (db.select().from(users)),
10
+ * "db.select().from(users)", "app/users/page.tsx:12");
11
+ *
12
+ * `__timber_await$` is declared once per module and looks the wrapper up on
13
+ * `globalThis[DEV_AWAIT_KEY]` at call time (installed with dev tracing,
14
+ * `dev-tools/await-span.ts`); with none installed it calls the thunk. A
15
+ * global rather than an injected import, so the rewrite needs no resolvable
16
+ * specifier from a workspace package outside the app.
17
+ *
18
+ * Scope: the RSC environment, `vite dev` only; every module outside
19
+ * node_modules and outside timber itself, so a monorepo's `packages/db`
20
+ * (where the query actually is) is covered. Skipped: `'use client'`
21
+ * modules, top-level await (no request to nest under), awaits of literals,
22
+ * `await import()` (module loading, and plugin-rsc injects one per layout),
23
+ * awaits whose operand contains `yield` (an async arrow can't hold it).
24
+ * `for await` and `await using` are not AwaitExpressions and are untouched.
25
+ *
26
+ * See design/50-dev-request-pill.md §"Phase 2".
27
+ */
28
+
29
+ import { existsSync } from 'node:fs';
30
+ import { dirname, join, relative } from 'node:path';
31
+ import { fileURLToPath } from 'node:url';
32
+ import MagicString from 'magic-string';
33
+ import { parseAst, type Plugin } from 'vite';
34
+ import type { PluginContext } from '../plugin-context.ts';
35
+
36
+ /** The per-module helper's name; `$` keeps it out of the way of app identifiers. */
37
+ const HELPER = '__timber_await$';
38
+
39
+ /** Longest label kept, in characters. */
40
+ const LABEL_MAX = 80;
41
+
42
+ const SCRIPT_RE = /\.[cm]?[jt]sx?$/;
43
+
44
+ interface Node {
45
+ type: string;
46
+ start: number;
47
+ end: number;
48
+ [key: string]: unknown;
49
+ }
50
+
51
+ function isNode(value: unknown): value is Node {
52
+ return (
53
+ typeof value === 'object' &&
54
+ value !== null &&
55
+ typeof (value as { type?: unknown }).type === 'string' &&
56
+ typeof (value as { start?: unknown }).start === 'number'
57
+ );
58
+ }
59
+
60
+ function children(node: Node): Node[] {
61
+ const out: Node[] = [];
62
+ for (const key of Object.keys(node)) {
63
+ const value = node[key];
64
+ if (Array.isArray(value)) {
65
+ for (const item of value) if (isNode(item)) out.push(item);
66
+ } else if (isNode(value)) {
67
+ out.push(value);
68
+ }
69
+ }
70
+ return out;
71
+ }
72
+
73
+ const FUNCTION_TYPES = new Set([
74
+ 'FunctionDeclaration',
75
+ 'FunctionExpression',
76
+ 'ArrowFunctionExpression',
77
+ ]);
78
+
79
+ function containsYield(node: Node): boolean {
80
+ if (node.type === 'YieldExpression') return true;
81
+ // A nested function's yields belong to it.
82
+ if (FUNCTION_TYPES.has(node.type)) return false;
83
+ return children(node).some(containsYield);
84
+ }
85
+
86
+ /** Leading directive prologue: `'use server'`, `'use client'`, `'use strict'`. */
87
+ function directives(program: Node): { names: string[]; end: number } {
88
+ const body = (program.body as Node[] | undefined) ?? [];
89
+ const names: string[] = [];
90
+ let end = 0;
91
+ for (const stmt of body) {
92
+ if (typeof stmt.directive !== 'string') break;
93
+ names.push(stmt.directive);
94
+ end = stmt.end;
95
+ }
96
+ return { names, end };
97
+ }
98
+
99
+ /** A string or template that starts like a URL: `scheme://`, `/path`, `?query`, or `${base}/path`. */
100
+ const URL_START = /^(?:[a-z][a-z0-9+.-]*:\/\/|\/|\?|\$\{[^}]*\}\/)/i;
101
+
102
+ /** `scheme://user:pass@host` → `scheme://…@host`. */
103
+ function redactUserinfo(text: string): string {
104
+ return text.replace(/:\/\/[^/@\s]*@/g, '://…@');
105
+ }
106
+
107
+ /**
108
+ * The operand's source with URL secrets cut out. Labels are source text,
109
+ * but source can hold literals: `fetch('https://api/x?token=abc')` would
110
+ * put the token in a span attribute that reaches the browser, the replay
111
+ * buffer and any OTEL exporter. In string and template literals that start
112
+ * like a URL, everything from the first `?` or `#` becomes `?…` / `#…`,
113
+ * and userinfo becomes `…@`. Other strings (a SQL `?` placeholder) and
114
+ * code (`a?.b`, ternaries) are left alone. Codex review on #1272.
115
+ */
116
+ function redactedSource(code: string, arg: Node): string {
117
+ const edits: Array<{ start: number; end: number; text: string }> = [];
118
+ const visit = (node: Node) => {
119
+ if (node.type === 'Literal' && typeof node.value === 'string') {
120
+ const inner = code.slice(node.start + 1, node.end - 1);
121
+ if (URL_START.test(inner)) {
122
+ const cut = inner.search(/[?#]/);
123
+ const kept = cut === -1 ? inner : `${inner.slice(0, cut)}${inner[cut]}…`;
124
+ edits.push({ start: node.start + 1, end: node.end - 1, text: redactUserinfo(kept) });
125
+ }
126
+ return;
127
+ }
128
+ if (node.type === 'TemplateLiteral') {
129
+ const inner = code.slice(node.start + 1, node.end - 1);
130
+ const quasis = (node.quasis as Node[] | undefined) ?? [];
131
+ if (URL_START.test(inner)) {
132
+ for (const quasi of quasis) {
133
+ const raw = code.slice(quasi.start, quasi.end);
134
+ const cut = raw.search(/[?#]/);
135
+ if (cut === -1) {
136
+ edits.push({ start: quasi.start, end: quasi.end, text: redactUserinfo(raw) });
137
+ continue;
138
+ }
139
+ // Everything after the cut, later ${…} included, is query.
140
+ edits.push({
141
+ start: quasi.start,
142
+ end: node.end - 1,
143
+ text: `${redactUserinfo(raw.slice(0, cut))}${raw[cut]}…`,
144
+ });
145
+ return;
146
+ }
147
+ return;
148
+ }
149
+ }
150
+ for (const child of children(node)) visit(child);
151
+ };
152
+ visit(arg);
153
+
154
+ let out = '';
155
+ let at = arg.start;
156
+ for (const edit of edits.sort((a, b) => a.start - b.start)) {
157
+ if (edit.start < at) continue;
158
+ out += code.slice(at, edit.start) + edit.text;
159
+ at = edit.end;
160
+ }
161
+ return out + code.slice(at, arg.end);
162
+ }
163
+
164
+ function label(source: string): string {
165
+ const collapsed = source.replace(/\s+/g, ' ').trim();
166
+ return collapsed.length > LABEL_MAX ? `${collapsed.slice(0, LABEL_MAX - 1)}…` : collapsed;
167
+ }
168
+
169
+ /**
170
+ * Rewrite the awaits in one module. Returns null when nothing changed.
171
+ * Exported for tests; `relPath` is the location prefix shown in the pill.
172
+ */
173
+ export function instrumentAwaits(
174
+ code: string,
175
+ relPath: string
176
+ ): { code: string; map: ReturnType<MagicString['generateMap']> } | null {
177
+ if (!code.includes('await')) return null;
178
+
179
+ let parsed: unknown;
180
+ try {
181
+ // Runs after Vite's own TS/JSX transform, but `jsx` also accepts
182
+ // anything that reaches it untransformed.
183
+ parsed = parseAst(code, { lang: 'jsx' });
184
+ } catch {
185
+ return null; // Not ours to report; the module's own parse will.
186
+ }
187
+ if (!isNode(parsed)) return null;
188
+ const program = parsed;
189
+
190
+ const prologue = directives(program);
191
+ if (prologue.names.includes('use client')) return null;
192
+
193
+ const lineStarts = [0];
194
+ for (let i = 0; i < code.length; i++) if (code[i] === '\n') lineStarts.push(i + 1);
195
+ const lineOf = (offset: number) => {
196
+ let lo = 0;
197
+ let hi = lineStarts.length - 1;
198
+ while (lo < hi) {
199
+ const mid = (lo + hi + 1) >> 1;
200
+ if (lineStarts[mid]! <= offset) lo = mid;
201
+ else hi = mid - 1;
202
+ }
203
+ return lo + 1;
204
+ };
205
+
206
+ const s = new MagicString(code);
207
+ let count = 0;
208
+
209
+ const visit = (node: Node, inFunction: boolean) => {
210
+ const nowInFunction = inFunction || FUNCTION_TYPES.has(node.type);
211
+ for (const child of children(node)) visit(child, nowInFunction);
212
+
213
+ // Post-order, so an inner await's suffix lands before an outer one's
214
+ // at a shared end offset.
215
+ if (node.type !== 'AwaitExpression' || !nowInFunction) return;
216
+ const arg = node.argument;
217
+ if (!isNode(arg) || arg.type === 'Literal' || containsYield(arg)) return;
218
+ // Module loading, not data — and plugin-rsc injects `await import()` of
219
+ // its CSS virtual module into layouts, which read as a slow app await.
220
+ if (arg.type === 'ImportExpression') return;
221
+
222
+ const text = JSON.stringify(label(redactedSource(code, arg)));
223
+ const location = JSON.stringify(`${relPath}:${lineOf(node.start)}`);
224
+ // Parenthesized: the operand may be a sequence or an object literal.
225
+ // Async: the operand may itself contain an await.
226
+ s.prependRight(arg.start, `${HELPER}(async () => (`);
227
+ s.appendLeft(arg.end, `), ${text}, ${location})`);
228
+ count++;
229
+ };
230
+ visit(program, false);
231
+ if (count === 0) return null;
232
+
233
+ // After the directive prologue — a statement before `'use server'` would
234
+ // demote it to a plain string.
235
+ const helper =
236
+ `\nconst ${HELPER} = (f, l, c) => ` +
237
+ `(globalThis[Symbol.for("timber.dev.await")] ?? ((g) => g()))(f, l, c);\n`;
238
+ s.appendLeft(prologue.end, helper);
239
+
240
+ return { code: s.toString(), map: s.generateMap({ hires: true }) };
241
+ }
242
+
243
+ /** Directory of the nearest package.json above this file: timber itself. */
244
+ function findTimberRoot(): string {
245
+ let dir = dirname(fileURLToPath(import.meta.url));
246
+ while (!existsSync(join(dir, 'package.json'))) {
247
+ const parent = dirname(dir);
248
+ if (parent === dir) break;
249
+ dir = parent;
250
+ }
251
+ return dir;
252
+ }
253
+
254
+ export function timberDevAwait(ctx: PluginContext): Plugin {
255
+ const timberRoot = findTimberRoot();
256
+ return {
257
+ name: 'timber-dev-await',
258
+ apply: 'serve',
259
+ applyToEnvironment: (env) => env.name === 'rsc',
260
+ transform(code, id) {
261
+ if (id.startsWith('\0')) return;
262
+ const file = id.split('?')[0]!;
263
+ if (!SCRIPT_RE.test(file) || file.includes('/node_modules/')) return;
264
+ if (file.startsWith(`${timberRoot}/`)) return;
265
+ return instrumentAwaits(code, relative(ctx.root, file)) ?? undefined;
266
+ },
267
+ };
268
+ }
@@ -156,6 +156,8 @@ function generateConfigModule(ctx: PluginContext): string {
156
156
  base: ctx.base,
157
157
  dev: ctx.dev ?? false,
158
158
  slowPhaseMs: ctx.config.dev?.slowPhaseMs ?? 200,
159
+ // Read by the dev HMR setup only. design/50-dev-request-pill.md.
160
+ devRequestPill: ctx.config.dev?.requestPill ?? true,
159
161
  slowRequestMs: ctx.config.slowRequestMs ?? 3000,
160
162
  topLoader: ctx.config.topLoader,
161
163
  debug: ctx.config.debug ?? false,
@@ -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
  *
@@ -181,6 +181,11 @@ export async function handleActionRequest(
181
181
  // handleActionRequest remains safe to call from any entry point that
182
182
  // bypasses the gate — and it never applies the per-route exemption, which
183
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.
184
189
  const csrfResult = validateCsrf(req, config.csrf);
185
190
  if (!csrfResult.ok) {
186
191
  return csrfRejectionResponse(req, csrfResult);
@@ -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';
@@ -19,10 +19,12 @@ import type { CoercedParams } from '../shared/param-value.ts';
19
19
  import type { ProxyExport } from './proxy.ts';
20
20
  import type { MiddlewareFn } from './middleware-runner.ts';
21
21
  import { runWithTimingCollector, getServerTimingHeader } from './server-timing.ts';
22
+ import { traceTimingEntry } from '../shared/dev-span.ts';
22
23
  import { wrapResponseWithStreamTiming } from './stream-utils.ts';
23
24
  import { runWithRequestContext } from './request-context.ts';
24
25
  import {
25
26
  generateTraceId,
27
+ getTraceId,
26
28
  runWithTraceId,
27
29
  getOtelTraceId,
28
30
  replaceTraceId,
@@ -199,6 +201,14 @@ export interface PipelineConfig {
199
201
  * Default: `'total'`.
200
202
  */
201
203
  serverTiming?: 'detailed' | 'total' | false;
204
+ /**
205
+ * Add a `timber-trace;desc="<traceId>"` Server-Timing entry to every
206
+ * response, whatever `serverTiming` is, so the dev request pill can match
207
+ * the page and its fetches to their spans. Set by the dev RSC entry only:
208
+ * it must never be on in a production build, `TIMBER_DEBUG` included.
209
+ * See design/50-dev-request-pill.md §"Correlation".
210
+ */
211
+ devTraceTiming?: boolean;
202
212
  /**
203
213
  * Auto-generated sitemap handler. When provided, the pipeline intercepts
204
214
  * `/sitemap.xml` and `/sitemap/N.xml` requests and delegates to this
@@ -572,6 +582,10 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
572
582
  }
573
583
  // serverTiming === false: no header at all
574
584
 
585
+ if (config.devTraceTiming) {
586
+ result.headers.append('Server-Timing', traceTimingEntry(getTraceId()));
587
+ }
588
+
575
589
  // Wrap the response body with stream-lifecycle timing when
576
590
  // detailed mode is on. Logs firstChunk/lastChunk/maxGap/close
577
591
  // on stream close — measures the post-flush stream tail that
@@ -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
+ }
@@ -281,7 +281,10 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
281
281
  // without exposing anything to clients.
282
282
  if (debugEnabled) {
283
283
  const devLogMode = resolveLogMode();
284
- if (devLogMode !== 'quiet') {
284
+ // Quiet silences the terminal tree, not the spans: in dev they also
285
+ // feed the request pill (design/50-dev-request-pill.md), and the
286
+ // processor prints nothing in quiet mode.
287
+ if (devLogMode !== 'quiet' || isDev) {
285
288
  await initDevTracing({ mode: devLogMode, slowPhaseMs });
286
289
  }
287
290
  }
@@ -400,6 +403,9 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
400
403
  // See design/17-logging.md §"slowRequestMs"
401
404
  slowRequestMs: (runtimeConfig as Record<string, unknown>).slowRequestMs as number | undefined,
402
405
  serverTiming: resolveServerTimingMode(runtimeConfig, isDev),
406
+ devTraceTiming:
407
+ isDev &&
408
+ ((runtimeConfig as Record<string, unknown>).devRequestPill as boolean | undefined) !== false,
403
409
  onPipelineError: isDev
404
410
  ? (error: Error, phase: string) => devHooks.onPipelineError?.(error, phase)
405
411
  : undefined,
@@ -25,6 +25,7 @@ import { containSlotSubtree } from './slot-subtree-contain.ts';
25
25
  import { loadModule, type ManifestLoader } from './safe-load.ts';
26
26
  import type { InterceptionContext, RouteMatch } from './pipeline.ts';
27
27
  import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
28
+ import { traceCall, withSpan } from './tracing.ts';
28
29
  import { loadFallbackModule, reportRenderError } from './pipeline-helpers.ts';
29
30
  import type { ManifestSegmentNode } from './route-matcher.ts';
30
31
  import { setSlotParams, runWithSlotSegmentParams } from './request-context.ts';
@@ -152,10 +153,15 @@ export async function resolveSlotElement(
152
153
  if (isClientReference(SlotPage)) {
153
154
  element = h(SlotPage, {});
154
155
  } else {
156
+ // Same `timber.page` span as a main-route page, tagged with the slot
157
+ // so a slow `@slot` page is attributed to itself in a trace rather
158
+ // than hiding inside its parent layout's span.
159
+ const leaf = slotMatch.chain[slotMatch.chain.length - 1];
160
+ const spanAttributes = slotSpanAttributes('timber.route', leaf, slotNode);
155
161
  const SafeSlotPage = async (props: Record<string, unknown>) => {
156
162
  try {
157
- const rendered = await scope(() =>
158
- (SlotPage as (props: Record<string, unknown>) => unknown)(props)
163
+ const rendered = await withSpan('timber.page', spanAttributes, () =>
164
+ scope(() => (SlotPage as (props: Record<string, unknown>) => unknown)(props))
159
165
  );
160
166
  return containSlotSubtree(rendered as React.ReactNode, denyFallback);
161
167
  } catch (error) {
@@ -184,6 +190,7 @@ export async function resolveSlotElement(
184
190
  // handles main segments. The slot root (index 0) is handled below.
185
191
  element = await wrapWithIntermediateSegments(
186
192
  slotMatch.chain,
193
+ slotNode,
187
194
  element,
188
195
  h,
189
196
  req,
@@ -193,7 +200,7 @@ export async function resolveSlotElement(
193
200
 
194
201
  // Wrap with slot root's layout — INSIDE the access gate, so the layout
195
202
  // server component never executes when access.ts denies. See TIM-1074.
196
- element = await wrapWithLayout(slotNode, element, h, scope, denyFallback);
203
+ element = await wrapWithLayout(slotNode, slotNode, element, h, scope, denyFallback);
197
204
 
198
205
  // Wrap in SlotAccessGate if slot root has access.ts. The gate is
199
206
  // OUTSIDE the layout, matching the segment model in
@@ -286,6 +293,7 @@ function computeSlotSegmentPath(
286
293
  */
287
294
  async function wrapWithIntermediateSegments(
288
295
  chain: ManifestSegmentNode[],
296
+ slotNode: ManifestSegmentNode,
289
297
  element: React.ReactElement,
290
298
  h: CreateElementFn,
291
299
  req: Request,
@@ -300,7 +308,7 @@ async function wrapWithIntermediateSegments(
300
308
  errorBoundaryComponent: TimberErrorBoundary,
301
309
  isSlotBoundary: true,
302
310
  });
303
- element = await wrapWithLayout(seg, element, h, scope, denyFallback);
311
+ element = await wrapWithLayout(seg, slotNode, element, h, scope, denyFallback);
304
312
  element = await wrapWithAccessGate(seg, element, h, scope);
305
313
  }
306
314
  return element;
@@ -341,12 +349,42 @@ function ScopedSlotLayout(props: {
341
349
  layout: (props: Record<string, unknown>) => unknown;
342
350
  scope: SlotParamScope;
343
351
  denyFallback: React.ReactNode;
352
+ spanAttributes: Record<string, string>;
344
353
  children: React.ReactElement;
345
354
  }): unknown {
346
- const rendered = props.scope(() => props.layout({ children: props.children }));
355
+ // `traceCall`, not `withSpan`: the layout runs in this frame, under React's
356
+ // render dispatcher, and a synchronous throw leaves synchronously — so a
357
+ // sync layout's `use()` can suspend and be retried by Flight. A promise an
358
+ // async layout returns goes to the walk, which turns a rejected deny into
359
+ // the slot's fallback; a synchronous deny gets the same answer here.
360
+ let rendered: unknown;
361
+ try {
362
+ rendered = traceCall('timber.layout', props.spanAttributes, () =>
363
+ props.scope(() => props.layout({ children: props.children }))
364
+ );
365
+ } catch (error) {
366
+ if (isDenySignal(error)) return props.denyFallback;
367
+ throw error;
368
+ }
347
369
  return containSlotSubtree(rendered as React.ReactNode, props.denyFallback, props.children);
348
370
  }
349
371
 
372
+ /**
373
+ * Span attributes for a component in a slot's matched chain: the segment's
374
+ * URL pattern under `routeKey` (`timber.route` for a page, `timber.segment`
375
+ * for a layout — the keys the main route's spans use) and the slot's
376
+ * directory name under `timber.slot`. A slot is transparent to the URL, so
377
+ * without `timber.slot` a slot page and the main page at the same pattern
378
+ * would be indistinguishable in a trace.
379
+ */
380
+ function slotSpanAttributes(
381
+ routeKey: 'timber.route' | 'timber.segment',
382
+ node: ManifestSegmentNode,
383
+ slotNode: ManifestSegmentNode
384
+ ): Record<string, string> {
385
+ return { [routeKey]: node.urlPath || '/', 'timber.slot': slotNode.segmentName };
386
+ }
387
+
350
388
  /**
351
389
  * Wrap an element with a segment's layout component, if present.
352
390
  *
@@ -359,6 +397,7 @@ function ScopedSlotLayout(props: {
359
397
  */
360
398
  async function wrapWithLayout(
361
399
  node: ManifestSegmentNode,
400
+ slotNode: ManifestSegmentNode,
362
401
  element: React.ReactElement,
363
402
  h: CreateElementFn,
364
403
  scope?: SlotParamScope,
@@ -373,6 +412,7 @@ async function wrapWithLayout(
373
412
  layout: Layout as (props: Record<string, unknown>) => unknown,
374
413
  scope,
375
414
  denyFallback,
415
+ spanAttributes: slotSpanAttributes('timber.segment', node, slotNode),
376
416
  children: element,
377
417
  });
378
418
  }