zitejs 0.10.2 → 0.10.3

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.
@@ -571,4 +571,5 @@ export declare const describeOutputSchema: z.ZodObject<{
571
571
  verifySession: "verifySession";
572
572
  }>>;
573
573
  problems: z.ZodArray<z.ZodString>;
574
+ runtimeVersion: z.ZodString;
574
575
  }, z.core.$strip>;
@@ -175,4 +175,6 @@ exports.describeOutputSchema = zod_1.z.object({
175
175
  workflows: zod_1.z.array(exports.describedWorkflowSchema),
176
176
  authHooks: zod_1.z.array(exports.authHookNameSchema),
177
177
  problems: zod_1.z.array(zod_1.z.string()),
178
+ /** The zitejs the build's server code was bundled from. */
179
+ runtimeVersion: zod_1.z.string(),
178
180
  });
@@ -0,0 +1,63 @@
1
+ import type { RunReport } from './types.js';
2
+ export declare const FRAME: {
3
+ readonly head: 1;
4
+ readonly chunk: 2;
5
+ readonly end: 3;
6
+ readonly report: 4;
7
+ readonly fail: 5;
8
+ };
9
+ /**
10
+ * What the host decides an answer by, in place of reading its headers. The status travels here because a 204 or a 304
11
+ * can't carry the frames as its body.
12
+ */
13
+ export type AnswerHead = {
14
+ status: number;
15
+ contentType: string | null;
16
+ /** The body's length as the app declared it, for the host to declare again; the frames are longer. */
17
+ contentLength: number | null;
18
+ /** What the edge's page cache decides by: the host writes these over the app's own, so no one reads those. */
19
+ cacheControl: string | null;
20
+ vary: string | null;
21
+ setCookies: string[];
22
+ };
23
+ /**
24
+ * The app's answer as the host reads it: its headers as they are, and its body in frames. `report` is asked once the
25
+ * body has ended cleanly; a body that fails or is cancelled stops the frames short of `end`.
26
+ */
27
+ export declare const framedAnswer: (response: Response,
28
+ /** Given what failed the body, when it failed. */
29
+ report: (failure?: unknown) => Promise<RunReport | null>) => Response;
30
+ /** An answer that breaks the protocol, which only a broken or hostile build sends. */
31
+ export declare class MalformedAnswer extends Error {
32
+ }
33
+ /** The app's own body failed partway, with the app's message for why. */
34
+ export declare class AnswerFailed extends Error {
35
+ }
36
+ /** How a decoded body stopped: at `end`, cancelled by its reader, or with what stopped it. */
37
+ export type BodyEnd = {
38
+ outcome: 'ok' | 'canceled';
39
+ } | {
40
+ outcome: 'error';
41
+ error: unknown;
42
+ };
43
+ export type DecodedAnswer = {
44
+ head: AnswerHead;
45
+ /** The body's chunks as they arrive. It closes at `end` and errors on anything else. */
46
+ body: ReadableStream<Uint8Array>;
47
+ ended: Promise<BodyEnd>;
48
+ /**
49
+ * The report's JSON once the body has ended, cleanly or with the app's `AnswerFailed`: null without one, past its
50
+ * cap, or when the answer broke off. A frame that breaks the protocol rejects it.
51
+ */
52
+ report: Promise<string | null>;
53
+ };
54
+ /** The most of a `head` and a `report` payload `decodeAnswer` holds, in bytes. */
55
+ export type AnswerCaps = {
56
+ head: number;
57
+ report: number;
58
+ };
59
+ /**
60
+ * Reads an answer's head, then hands on its body's chunks as they arrive, never holding one, and reads its report once
61
+ * the body has ended. A missing, oversized or malformed head rejects.
62
+ */
63
+ export declare const decodeAnswer: (stream: ReadableStream<Uint8Array> | null, caps: AnswerCaps) => Promise<DecodedAnswer>;
@@ -0,0 +1,297 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.decodeAnswer = exports.AnswerFailed = exports.MalformedAnswer = exports.framedAnswer = exports.FRAME = void 0;
4
+ exports.FRAME = { head: 1, chunk: 2, end: 3, report: 4, fail: 5 };
5
+ // A failure's message, cut to this on the app's side and refused past four bytes a character on the host's.
6
+ const FAILURE_CHARS = 1_024;
7
+ const FAILURE_BYTES = FAILURE_CHARS * 4;
8
+ const declaredLength = (header) => {
9
+ const length = header === null ? NaN : Number(header);
10
+ return Number.isSafeInteger(length) && length >= 0 ? length : null;
11
+ };
12
+ const HEADER_BYTES = 5;
13
+ const NOTHING = new Uint8Array(0);
14
+ const encoder = new TextEncoder();
15
+ const decoder = new TextDecoder();
16
+ const frameHeader = (type, length) => {
17
+ const header = new Uint8Array(HEADER_BYTES);
18
+ header[0] = type;
19
+ new DataView(header.buffer).setUint32(1, length);
20
+ return header;
21
+ };
22
+ const frame = (type, payload = NOTHING) => {
23
+ const whole = new Uint8Array(HEADER_BYTES + payload.byteLength);
24
+ whole.set(frameHeader(type, payload.byteLength));
25
+ whole.set(payload, HEADER_BYTES);
26
+ return whole;
27
+ };
28
+ const jsonFrame = (type, value) => frame(type, encoder.encode(JSON.stringify(value)));
29
+ /**
30
+ * The app's answer as the host reads it: its headers as they are, and its body in frames. `report` is asked once the
31
+ * body has ended cleanly; a body that fails or is cancelled stops the frames short of `end`.
32
+ */
33
+ const framedAnswer = (response,
34
+ /** Given what failed the body, when it failed. */
35
+ report) => {
36
+ const head = {
37
+ status: response.status,
38
+ contentType: response.headers.get('content-type'),
39
+ contentLength: declaredLength(response.headers.get('content-length')),
40
+ cacheControl: response.headers.get('cache-control'),
41
+ vary: response.headers.get('vary'),
42
+ setCookies: response.headers.getSetCookie(),
43
+ };
44
+ const reader = response.body?.getReader();
45
+ const body = new ReadableStream({
46
+ start: controller => controller.enqueue(jsonFrame(exports.FRAME.head, head)),
47
+ async pull(controller) {
48
+ let read;
49
+ try {
50
+ read = reader ? await reader.read() : { done: true, value: undefined };
51
+ }
52
+ catch (error) {
53
+ // The run log keeps a failed answer's input, console and stack, as it does a clean one's.
54
+ const message = error instanceof Error ? error.message : String(error);
55
+ controller.enqueue(frame(exports.FRAME.fail, encoder.encode(message.slice(0, FAILURE_CHARS))));
56
+ controller.enqueue(jsonFrame(exports.FRAME.report, await report(error)));
57
+ controller.close();
58
+ return;
59
+ }
60
+ if (!read.done) {
61
+ controller.enqueue(frameHeader(exports.FRAME.chunk, read.value.byteLength));
62
+ controller.enqueue(read.value);
63
+ return;
64
+ }
65
+ controller.enqueue(frame(exports.FRAME.end));
66
+ controller.enqueue(jsonFrame(exports.FRAME.report, await report()));
67
+ controller.close();
68
+ },
69
+ cancel: reason => reader?.cancel(reason),
70
+ });
71
+ const headers = new Headers(response.headers);
72
+ // The frames are longer than the body the app measured.
73
+ headers.delete('content-length');
74
+ return new Response(body, { headers });
75
+ };
76
+ exports.framedAnswer = framedAnswer;
77
+ /** An answer that breaks the protocol, which only a broken or hostile build sends. */
78
+ class MalformedAnswer extends Error {
79
+ }
80
+ exports.MalformedAnswer = MalformedAnswer;
81
+ /** The app's own body failed partway, with the app's message for why. */
82
+ class AnswerFailed extends Error {
83
+ }
84
+ exports.AnswerFailed = AnswerFailed;
85
+ // The runtime's own errors are short; one an app raises can carry tens of megabytes, which kept would fill the host.
86
+ const KEPT_MESSAGE_CHARS = 256;
87
+ /** An error from the app's side of the transport, as the host may keep it: short, or only that the answer broke off. */
88
+ const kept = (error) => {
89
+ if (error instanceof MalformedAnswer || error instanceof AnswerFailed)
90
+ return error;
91
+ const message = error?.message;
92
+ return new Error(typeof message === 'string' && message.length <= KEPT_MESSAGE_CHARS
93
+ ? message
94
+ : "The app's answer broke off");
95
+ };
96
+ const framesOf = (stream) => {
97
+ const reader = stream.getReader();
98
+ let held = NOTHING;
99
+ /** Up to `max` of the next bytes, as they arrived; none at the stream's end. */
100
+ const some = async (max) => {
101
+ while (!held.byteLength) {
102
+ const read = await reader.read();
103
+ if (read.done)
104
+ return NOTHING;
105
+ held = read.value;
106
+ }
107
+ if (held.byteLength <= max) {
108
+ const all = held;
109
+ held = NOTHING;
110
+ return all;
111
+ }
112
+ // A copy: what stays held shares the read's buffer, which whoever takes this may detach.
113
+ const taken = held.slice(0, max);
114
+ held = held.subarray(max);
115
+ return taken;
116
+ };
117
+ const exactly = async (length, what) => {
118
+ const whole = new Uint8Array(length);
119
+ for (let filled = 0; filled < length;) {
120
+ const piece = await some(length - filled);
121
+ if (!piece.byteLength)
122
+ throw new MalformedAnswer(`The answer ended inside ${what}`);
123
+ whole.set(piece, filled);
124
+ filled += piece.byteLength;
125
+ }
126
+ return whole;
127
+ };
128
+ /** The next frame's type and length; undefined at the stream's end between frames. */
129
+ const next = async () => {
130
+ const start = await some(HEADER_BYTES);
131
+ if (!start.byteLength)
132
+ return undefined;
133
+ const header = new Uint8Array(HEADER_BYTES);
134
+ header.set(start);
135
+ if (start.byteLength < HEADER_BYTES)
136
+ header.set(await exactly(HEADER_BYTES - start.byteLength, 'a frame header'), start.byteLength);
137
+ return {
138
+ type: header[0],
139
+ length: new DataView(header.buffer).getUint32(1),
140
+ };
141
+ };
142
+ // A stream that already failed has nothing left to stop.
143
+ const cancel = (reason) => reader.cancel(reason).catch(() => { });
144
+ return { some, exactly, next, cancel };
145
+ };
146
+ const isHead = (value) => {
147
+ const head = value;
148
+ return (typeof head?.status === 'number' &&
149
+ Number.isInteger(head.status) &&
150
+ head.status >= 200 &&
151
+ head.status <= 599 &&
152
+ (head.contentType === null || typeof head.contentType === 'string') &&
153
+ (head.contentLength === null ||
154
+ (Number.isSafeInteger(head.contentLength) &&
155
+ head.contentLength >= 0)) &&
156
+ (head.cacheControl === null || typeof head.cacheControl === 'string') &&
157
+ (head.vary === null || typeof head.vary === 'string') &&
158
+ Array.isArray(head.setCookies) &&
159
+ head.setCookies.every(cookie => typeof cookie === 'string'));
160
+ };
161
+ const readHead = async (frames, cap) => {
162
+ const first = await frames.next();
163
+ if (first?.type !== exports.FRAME.head)
164
+ throw new MalformedAnswer("The answer doesn't start with its head");
165
+ if (first.length > cap)
166
+ throw new MalformedAnswer("The answer's head is larger than the host reads");
167
+ const text = decoder.decode(await frames.exactly(first.length, 'its head'));
168
+ let head;
169
+ try {
170
+ head = JSON.parse(text);
171
+ }
172
+ catch {
173
+ throw new MalformedAnswer("The answer's head isn't JSON");
174
+ }
175
+ if (!isHead(head))
176
+ throw new MalformedAnswer("The answer's head isn't one");
177
+ // Only these: anything else an app padded the head with is let go now, not held as long as its body streams.
178
+ return {
179
+ status: head.status,
180
+ contentType: head.contentType,
181
+ contentLength: head.contentLength,
182
+ cacheControl: head.cacheControl,
183
+ vary: head.vary,
184
+ setCookies: head.setCookies,
185
+ };
186
+ };
187
+ const readReport = async (frames, cap) => {
188
+ try {
189
+ // Cut off inside its frame's header is missing too, as inside its payload.
190
+ const report = await frames.next().catch(() => undefined);
191
+ if (!report)
192
+ return null;
193
+ if (report.type !== exports.FRAME.report)
194
+ throw new MalformedAnswer(`The answer sent a frame of type ${report.type} after its end`);
195
+ if (report.length > cap) {
196
+ await frames.cancel();
197
+ return null;
198
+ }
199
+ // Cut off inside it, as a build stopped mid-report is, the report is missing, not malformed.
200
+ const bytes = await frames
201
+ .exactly(report.length, 'its report')
202
+ .catch(() => null);
203
+ if (!bytes)
204
+ return null;
205
+ const text = decoder.decode(bytes);
206
+ if (await frames.next())
207
+ throw new MalformedAnswer('The answer sent more after its report');
208
+ return text;
209
+ }
210
+ catch (error) {
211
+ // A build stopped after `end` sends no report, which leaves the host's word.
212
+ if (error instanceof MalformedAnswer)
213
+ throw error;
214
+ return null;
215
+ }
216
+ };
217
+ /**
218
+ * Reads an answer's head, then hands on its body's chunks as they arrive, never holding one, and reads its report once
219
+ * the body has ended. A missing, oversized or malformed head rejects.
220
+ */
221
+ const decodeAnswer = async (stream, caps) => {
222
+ if (!stream)
223
+ throw new MalformedAnswer("The answer doesn't start with its head");
224
+ const frames = framesOf(stream);
225
+ let head;
226
+ try {
227
+ head = await readHead(frames, caps.head);
228
+ }
229
+ catch (raw) {
230
+ const error = kept(raw);
231
+ await frames.cancel(error);
232
+ throw error;
233
+ }
234
+ let settleEnded;
235
+ const ended = new Promise(resolve => (settleEnded = resolve));
236
+ let settleReport;
237
+ const report = new Promise(resolve => (settleReport = resolve));
238
+ // Read for a run's row only; a page's goes unread.
239
+ report.catch(() => { });
240
+ const stopped = (end) => {
241
+ settleEnded(end);
242
+ settleReport(Promise.resolve(null));
243
+ };
244
+ // Of the chunk now passing through.
245
+ let left = 0;
246
+ const body = new ReadableStream({
247
+ async pull(controller) {
248
+ try {
249
+ for (;;) {
250
+ if (left > 0) {
251
+ const piece = await frames.some(left);
252
+ if (!piece.byteLength)
253
+ throw new MalformedAnswer('The answer ended inside a chunk');
254
+ left -= piece.byteLength;
255
+ controller.enqueue(piece);
256
+ return;
257
+ }
258
+ const next = await frames.next();
259
+ if (next?.type === exports.FRAME.chunk) {
260
+ left = next.length;
261
+ continue;
262
+ }
263
+ if (next?.type === exports.FRAME.end && next.length === 0) {
264
+ controller.close();
265
+ settleEnded({ outcome: 'ok' });
266
+ settleReport(readReport(frames, caps.report));
267
+ return;
268
+ }
269
+ if (next?.type === exports.FRAME.fail) {
270
+ if (next.length > FAILURE_BYTES)
271
+ throw new MalformedAnswer("The answer's failure is longer than the host reads");
272
+ const error = new AnswerFailed(decoder.decode(await frames.exactly(next.length, 'its failure')));
273
+ controller.error(error);
274
+ settleEnded({ outcome: 'error', error });
275
+ settleReport(readReport(frames, caps.report));
276
+ return;
277
+ }
278
+ throw new MalformedAnswer(next
279
+ ? `The answer sent a frame of type ${next.type} in its body`
280
+ : 'The answer ended without its end');
281
+ }
282
+ }
283
+ catch (raw) {
284
+ const error = kept(raw);
285
+ controller.error(error);
286
+ stopped({ outcome: 'error', error });
287
+ await frames.cancel(error);
288
+ }
289
+ },
290
+ cancel(reason) {
291
+ stopped({ outcome: 'canceled' });
292
+ return frames.cancel(reason);
293
+ },
294
+ });
295
+ return { head, body, ended, report };
296
+ };
297
+ exports.decodeAnswer = decodeAnswer;
@@ -1,6 +1,8 @@
1
1
  export { isReservedIntegrationId, RESERVED_INTEGRATION_IDS, } from '../internal/reservedIds.js';
2
2
  export { authHookNameSchema, describedAccessSchema, describedFunctionSchema, describedPageSchema, describedRouteSchema, describedScheduleSchema, describedTriggerSchema, describedWorkflowSchema, describeOutputSchema, } from './describe/schema.js';
3
- export type { AppContext, ExpiringToken, HostConnection, HostMode, HostPage, HostProps, PlatformBinding, SiteHead, WebManifest, } from './types.js';
3
+ export { AnswerFailed, decodeAnswer, FRAME, framedAnswer, MalformedAnswer, } from './frames.js';
4
+ export type { AnswerCaps, AnswerHead, BodyEnd, DecodedAnswer, } from './frames.js';
5
+ export type { AppContext, ConsoleRecord, ExpiringToken, HostConnection, HostMode, HostPage, HostProps, PlatformBinding, RunReport, SiteHead, WebManifest, } from './types.js';
4
6
  /** What the host dispatches a request to do beside serving it; without props, only `warm` and `describe`. */
5
7
  export declare const INVOKE_KINDS: readonly ["webhook", "describe", "workflow", "register", "warm", "authHook", "function"];
6
8
  export type InvokeKind = (typeof INVOKE_KINDS)[number];
@@ -9,8 +11,6 @@ export declare const isInvokeKind: (kind: unknown) => kind is InvokeKind;
9
11
  export declare const INVOKE_HEADER = "x-zite-invoke";
10
12
  /** Where the host POSTs a workflow, registration, auth hook or test run, with `{ input }`. */
11
13
  export declare const INVOKE_PATH = "/_zite/invoke";
12
- /** On describe's answer: the zitejs the build's server code was bundled from. */
13
- export declare const RUNTIME_VERSION_HEADER = "x-zitejs-version";
14
14
  /** An editor preview's access, on every same-origin fetch its pages make. */
15
15
  export declare const PREVIEW_CLAIM_HEADER = "x-zite-preview";
16
16
  /** At the gateway, the connection a call on Zite's AI key bills to. */
@@ -1,9 +1,9 @@
1
1
  "use strict";
2
- // What a Start build and the platform's host say to each other on the wire. Import-free but for the reserved ids and
3
- // describe's output schema, which imports only zod and the auth hook names, so the host takes these without loading
4
- // anything of zitejs.
2
+ // What a Start build and the platform's host say to each other on the wire. Import-free but for the reserved ids, the
3
+ // answer's frames and describe's output schema, which imports only zod and the auth hook names, so the host takes these
4
+ // without loading anything of zitejs.
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.START_APP_DEPENDENCIES = exports.DEMO_READ_ONLY_CODE = exports.ERROR_CODE_HEADER = exports.GATEWAY_CONNECTION_HEADER = exports.PREVIEW_CLAIM_HEADER = exports.RUNTIME_VERSION_HEADER = exports.INVOKE_PATH = exports.INVOKE_HEADER = exports.isInvokeKind = exports.INVOKE_KINDS = exports.describeOutputSchema = exports.describedWorkflowSchema = exports.describedTriggerSchema = exports.describedScheduleSchema = exports.describedRouteSchema = exports.describedPageSchema = exports.describedFunctionSchema = exports.describedAccessSchema = exports.authHookNameSchema = exports.RESERVED_INTEGRATION_IDS = exports.isReservedIntegrationId = void 0;
6
+ exports.START_APP_DEPENDENCIES = exports.DEMO_READ_ONLY_CODE = exports.ERROR_CODE_HEADER = exports.GATEWAY_CONNECTION_HEADER = exports.PREVIEW_CLAIM_HEADER = exports.INVOKE_PATH = exports.INVOKE_HEADER = exports.isInvokeKind = exports.INVOKE_KINDS = exports.MalformedAnswer = exports.framedAnswer = exports.FRAME = exports.decodeAnswer = exports.AnswerFailed = exports.describeOutputSchema = exports.describedWorkflowSchema = exports.describedTriggerSchema = exports.describedScheduleSchema = exports.describedRouteSchema = exports.describedPageSchema = exports.describedFunctionSchema = exports.describedAccessSchema = exports.authHookNameSchema = exports.RESERVED_INTEGRATION_IDS = exports.isReservedIntegrationId = void 0;
7
7
  var reservedIds_js_1 = require("../internal/reservedIds.js");
8
8
  Object.defineProperty(exports, "isReservedIntegrationId", { enumerable: true, get: function () { return reservedIds_js_1.isReservedIntegrationId; } });
9
9
  Object.defineProperty(exports, "RESERVED_INTEGRATION_IDS", { enumerable: true, get: function () { return reservedIds_js_1.RESERVED_INTEGRATION_IDS; } });
@@ -17,6 +17,12 @@ Object.defineProperty(exports, "describedScheduleSchema", { enumerable: true, ge
17
17
  Object.defineProperty(exports, "describedTriggerSchema", { enumerable: true, get: function () { return schema_js_1.describedTriggerSchema; } });
18
18
  Object.defineProperty(exports, "describedWorkflowSchema", { enumerable: true, get: function () { return schema_js_1.describedWorkflowSchema; } });
19
19
  Object.defineProperty(exports, "describeOutputSchema", { enumerable: true, get: function () { return schema_js_1.describeOutputSchema; } });
20
+ var frames_js_1 = require("./frames.js");
21
+ Object.defineProperty(exports, "AnswerFailed", { enumerable: true, get: function () { return frames_js_1.AnswerFailed; } });
22
+ Object.defineProperty(exports, "decodeAnswer", { enumerable: true, get: function () { return frames_js_1.decodeAnswer; } });
23
+ Object.defineProperty(exports, "FRAME", { enumerable: true, get: function () { return frames_js_1.FRAME; } });
24
+ Object.defineProperty(exports, "framedAnswer", { enumerable: true, get: function () { return frames_js_1.framedAnswer; } });
25
+ Object.defineProperty(exports, "MalformedAnswer", { enumerable: true, get: function () { return frames_js_1.MalformedAnswer; } });
20
26
  /** What the host dispatches a request to do beside serving it; without props, only `warm` and `describe`. */
21
27
  exports.INVOKE_KINDS = [
22
28
  'webhook',
@@ -33,8 +39,6 @@ exports.isInvokeKind = isInvokeKind;
33
39
  exports.INVOKE_HEADER = 'x-zite-invoke';
34
40
  /** Where the host POSTs a workflow, registration, auth hook or test run, with `{ input }`. */
35
41
  exports.INVOKE_PATH = '/_zite/invoke';
36
- /** On describe's answer: the zitejs the build's server code was bundled from. */
37
- exports.RUNTIME_VERSION_HEADER = 'x-zitejs-version';
38
42
  /** An editor preview's access, on every same-origin fetch its pages make. */
39
43
  exports.PREVIEW_CLAIM_HEADER = 'x-zite-preview';
40
44
  /** At the gateway, the connection a call on Zite's AI key bills to. */
@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.ziteProvider = exports.trimmed = exports.URL_NAMES = exports.contextOf = exports.renewedToken = exports.isExpiringToken = void 0;
4
4
  // A streamed answer can outlive the request's deadline, which the token's expiry follows.
5
5
  const RENEW_WITHIN_MS = 30_000;
6
+ // The platform binding answers its one question whatever it's asked.
7
+ const APP_TOKEN_URL = 'https://platform/app-token';
6
8
  const expiresWithin = (expiresAt, ms) => expiresAt !== undefined && expiresAt - Date.now() < ms;
7
9
  const isExpiringToken = (value) => {
8
10
  const given = value;
@@ -68,7 +70,7 @@ const ziteProvider = (props) => {
68
70
  held: () => current,
69
71
  keep: fresh => (current = fresh),
70
72
  renew: async () => {
71
- const fresh = await props.platform.appToken();
73
+ const fresh = await (await props.platform.fetch(APP_TOKEN_URL)).json();
72
74
  return (0, exports.isExpiringToken)(fresh) ? fresh : null;
73
75
  },
74
76
  withinMs: RENEW_WITHIN_MS,
@@ -40,6 +40,22 @@ export type RunRecord = {
40
40
  /** A durable call that stopped short of the end, which the run's next call carries on from. */
41
41
  suspended?: StepSuspension;
42
42
  };
43
+ /** One console call made while a request ran, as classic's run log keeps it. */
44
+ export type ConsoleRecord = {
45
+ level: 'log' | 'info' | 'warn' | 'error';
46
+ message: string;
47
+ at: number;
48
+ };
49
+ /**
50
+ * What a request's code reports of itself for its row in the run log: its top-level run, the one that failed if any
51
+ * did, and its console. The host writes the row from what it saw, and adds this.
52
+ */
53
+ export type RunReport = {
54
+ input?: string;
55
+ output?: string;
56
+ error?: RunRecord['error'];
57
+ console?: ConsoleRecord[];
58
+ };
43
59
  /** One step of a workflow call, as zitejs/steps reports it. `failed` marks a replayed final failure. */
44
60
  export type StepRecord = {
45
61
  name: string;
@@ -122,9 +138,9 @@ export type FetchRecord = {
122
138
  };
123
139
  /**
124
140
  * Where the platform's services answer this app: `gateway` takes calls on a key Zite pays for, `runs` a live page's
125
- * analytics and each request's run detail. `email`, `pdf`, `uploads` (the upload session), `steps` (a workflow run's
126
- * saved steps) and `schedules` are each that service's own endpoint, which the platform picks per workspace and the
127
- * host names on every dispatch: a call to one it doesn't name fails.
141
+ * analytics and each request's calls and fetches. `email`, `pdf`, `uploads` (the upload session), `steps` (a workflow
142
+ * run's saved steps) and `schedules` are each that service's own endpoint, which the platform picks per workspace and
143
+ * the host names on every dispatch: a call to one it doesn't name fails.
128
144
  */
129
145
  export type PlatformUrls = {
130
146
  baseRunner: string;
@@ -161,8 +177,11 @@ export type ExpiringToken = {
161
177
  * was dispatched with. Its presence in props is what marks a request the host dispatched.
162
178
  */
163
179
  export type PlatformBinding = {
164
- /** The request's app token, signed again when it's about to expire; null once it can't be. */
165
- appToken(): Promise<ExpiringToken | null>;
180
+ /**
181
+ * Answers the request's app token as an `ExpiringToken`'s JSON, signed again when it's about to expire, or null once
182
+ * it can't be. The host never reads what it's sent.
183
+ */
184
+ fetch(url: string): Promise<Response>;
166
185
  };
167
186
  /** A demo is the published build serving a read-only visitor: as live, but every write is refused. */
168
187
  export type HostMode = 'live' | 'preview' | 'demo' | 'validate';
@@ -337,7 +356,7 @@ export type HostRequestState = {
337
356
  connectionAnswers?: Map<string, unknown>;
338
357
  /** One refresh per connection per request, however many calls got a 401. */
339
358
  refreshing?: Map<string, Promise<string | undefined>>;
340
- /** The outbound fetches, flushed with its runs. */
359
+ /** The outbound fetches, sent with its calls. */
341
360
  fetches?: FetchRecord[];
342
361
  /** The secrets its fetch log redacts, longest first; cleared when a connection is learned. */
343
362
  secretValues?: string[];
@@ -345,9 +364,13 @@ export type HostRequestState = {
345
364
  secretsAt?: number;
346
365
  /** How much of its fetch log is bodies so far. */
347
366
  fetchLogChars?: number;
348
- /** Filled by run capture, flushed to the platform once the response ends. */
367
+ /** Filled by run capture; the top-level one goes in the request's report. */
349
368
  runs: RunRecord[];
350
- /** The data calls this request made, flushed with its runs. */
369
+ /** Its console, for the request's report. */
370
+ console?: ConsoleRecord[];
371
+ /** How much of `console` is messages so far. */
372
+ consoleChars?: number;
373
+ /** The data calls this request made, sent to the runs service once the response ends. */
351
374
  calls?: CallRecord[];
352
375
  /** This request's Airtable reads, so the same one twice goes out once. */
353
376
  airtableReads?: Map<string, Promise<unknown>>;
@@ -59,6 +59,8 @@ export type Description = {
59
59
  authHooks: AuthHookName[];
60
60
  /** What's wrong with the app as a whole, beside any one function, route or workflow. */
61
61
  problems: string[];
62
+ /** The zitejs the build's server code was bundled from. */
63
+ runtimeVersion: string;
62
64
  };
63
65
  /** What the build knows of the app beside its code: its access mode, and whether it's a standalone automation. */
64
66
  export type AppFacts = {
@@ -6,6 +6,7 @@ import { runWithStartContext } from '@tanstack/start-storage-context';
6
6
  import { z } from 'zod';
7
7
  import { ziteMiddlewareKind, } from '../middlewareKind.js';
8
8
  import { isZiteRouter } from '../router.js';
9
+ import { ZITEJS_VERSION } from '../version.js';
9
10
  import { loadAuthHooks } from '../serve/authHooks.js';
10
11
  import { loadProviderTriggers, } from '../automations/workflowRun.js';
11
12
  import { isProviderTrigger, } from '../automations/workflow.js';
@@ -368,5 +369,6 @@ export async function describeApp(opts) {
368
369
  workflows,
369
370
  authHooks: Object.keys(await loadAuthHooks()),
370
371
  problems,
372
+ runtimeVersion: ZITEJS_VERSION,
371
373
  };
372
374
  }
@@ -571,4 +571,5 @@ export declare const describeOutputSchema: z.ZodObject<{
571
571
  verifySession: "verifySession";
572
572
  }>>;
573
573
  problems: z.ZodArray<z.ZodString>;
574
+ runtimeVersion: z.ZodString;
574
575
  }, z.core.$strip>;
@@ -172,4 +172,6 @@ export const describeOutputSchema = z.object({
172
172
  workflows: z.array(describedWorkflowSchema),
173
173
  authHooks: z.array(authHookNameSchema),
174
174
  problems: z.array(z.string()),
175
+ /** The zitejs the build's server code was bundled from. */
176
+ runtimeVersion: z.string(),
175
177
  });
@@ -0,0 +1,63 @@
1
+ import type { RunReport } from './types.js';
2
+ export declare const FRAME: {
3
+ readonly head: 1;
4
+ readonly chunk: 2;
5
+ readonly end: 3;
6
+ readonly report: 4;
7
+ readonly fail: 5;
8
+ };
9
+ /**
10
+ * What the host decides an answer by, in place of reading its headers. The status travels here because a 204 or a 304
11
+ * can't carry the frames as its body.
12
+ */
13
+ export type AnswerHead = {
14
+ status: number;
15
+ contentType: string | null;
16
+ /** The body's length as the app declared it, for the host to declare again; the frames are longer. */
17
+ contentLength: number | null;
18
+ /** What the edge's page cache decides by: the host writes these over the app's own, so no one reads those. */
19
+ cacheControl: string | null;
20
+ vary: string | null;
21
+ setCookies: string[];
22
+ };
23
+ /**
24
+ * The app's answer as the host reads it: its headers as they are, and its body in frames. `report` is asked once the
25
+ * body has ended cleanly; a body that fails or is cancelled stops the frames short of `end`.
26
+ */
27
+ export declare const framedAnswer: (response: Response,
28
+ /** Given what failed the body, when it failed. */
29
+ report: (failure?: unknown) => Promise<RunReport | null>) => Response;
30
+ /** An answer that breaks the protocol, which only a broken or hostile build sends. */
31
+ export declare class MalformedAnswer extends Error {
32
+ }
33
+ /** The app's own body failed partway, with the app's message for why. */
34
+ export declare class AnswerFailed extends Error {
35
+ }
36
+ /** How a decoded body stopped: at `end`, cancelled by its reader, or with what stopped it. */
37
+ export type BodyEnd = {
38
+ outcome: 'ok' | 'canceled';
39
+ } | {
40
+ outcome: 'error';
41
+ error: unknown;
42
+ };
43
+ export type DecodedAnswer = {
44
+ head: AnswerHead;
45
+ /** The body's chunks as they arrive. It closes at `end` and errors on anything else. */
46
+ body: ReadableStream<Uint8Array>;
47
+ ended: Promise<BodyEnd>;
48
+ /**
49
+ * The report's JSON once the body has ended, cleanly or with the app's `AnswerFailed`: null without one, past its
50
+ * cap, or when the answer broke off. A frame that breaks the protocol rejects it.
51
+ */
52
+ report: Promise<string | null>;
53
+ };
54
+ /** The most of a `head` and a `report` payload `decodeAnswer` holds, in bytes. */
55
+ export type AnswerCaps = {
56
+ head: number;
57
+ report: number;
58
+ };
59
+ /**
60
+ * Reads an answer's head, then hands on its body's chunks as they arrive, never holding one, and reads its report once
61
+ * the body has ended. A missing, oversized or malformed head rejects.
62
+ */
63
+ export declare const decodeAnswer: (stream: ReadableStream<Uint8Array> | null, caps: AnswerCaps) => Promise<DecodedAnswer>;