zitejs 0.10.0-start.3 → 0.10.0-start.5

package/dist/cjs/start/entries.d.ts

@@ -1,8 +1,12 @@
 import type { SourceDir } from "../sourceRoots.js";
 export declare const START_SERVER_ENTRY = ".zite/server.ts";
 export declare const START_INSTANCE_ENTRY = ".zite/start.ts";
-/** The server entry every Start app builds with. Platform-owned: regenerated, never edited. */
-export declare const renderStartServerEntry: () => string;
+export type StartTarget = "cloudflare" | "node";
+/**
+ * The server entry every Start app builds with. Platform-owned: regenerated,
+ * never edited. On Workers it's an entrypoint the host can also call over RPC.
+ */
+export declare const renderStartServerEntry: (target?: StartTarget) => string;
 /** The start instance: the platform's middleware, then the app's own `src/start.ts` when it has one. */
 export declare const renderStartInstance: (hasAppStart: boolean) => string;
 export declare const hasAppStart: (appDir: string) => boolean;

package/dist/cjs/start/entries.js

@@ -8,8 +8,19 @@ const node_path_1 = require("node:path");
 exports.START_SERVER_ENTRY = ".zite/server.ts";
 exports.START_INSTANCE_ENTRY = ".zite/start.ts";
 const APP_START_FILES = ["src/start.ts", "src/start.tsx"];
-/** The server entry every Start app builds with. Platform-owned: regenerated, never edited. */
-const renderStartServerEntry = () => `// Generated by zitejs for TanStack Start apps. The platform owns this file.
+/**
+ * The server entry every Start app builds with. Platform-owned: regenerated,
+ * never edited. On Workers it's an entrypoint the host can also call over RPC.
+ */
+const renderStartServerEntry = (target = "cloudflare") => target === "cloudflare"
+    ? `// Generated by zitejs for TanStack Start apps. The platform owns this file.
+import handler from '@tanstack/react-start/server-entry';
+import { createZiteWorker } from 'zitejs/start/worker';
+import { getRouter } from '../src/router';
+
+export default createZiteWorker({ handler, getRouter });
+`
+    : `// Generated by zitejs for TanStack Start apps. The platform owns this file.
 import handler, { createServerEntry } from '@tanstack/react-start/server-entry';
 import { createZiteFetch } from 'zitejs/start/server';
 import { getRouter } from '../src/router';

package/dist/esm/start/describe.d.ts

@@ -3,6 +3,7 @@ import type { WorkflowConfig } from "./workflow.js";
 export type Access = {
     kind: "signedIn" | "anyone" | "webhook" | "none";
     roles: string[];
+    paused?: true;
 };
 export type DescribedFunction = {
     id: string;

package/dist/esm/start/describe.js

@@ -16,7 +16,8 @@ const accessOf = (chain, problems) => {
     if (base.length > 1)
         problems.push(`access-conflict: ${base.join(" + ")}`);
     const kind = base.includes("webhook") ? "webhook" : base.includes("signedIn") ? "signedIn" : "anyone";
-    return { kind, roles };
+    const paused = kinds.some((k) => k.kind === "webhook" && k.paused === true);
+    return paused ? { kind, roles, paused } : { kind, roles };
 };
 const jsonSchemaOf = (validator) => {
     if (validator && typeof validator === "object" && "_zod" in validator) {

package/dist/esm/start/entries.d.ts

@@ -1,8 +1,12 @@
 import type { SourceDir } from "../sourceRoots.js";
 export declare const START_SERVER_ENTRY = ".zite/server.ts";
 export declare const START_INSTANCE_ENTRY = ".zite/start.ts";
-/** The server entry every Start app builds with. Platform-owned: regenerated, never edited. */
-export declare const renderStartServerEntry: () => string;
+export type StartTarget = "cloudflare" | "node";
+/**
+ * The server entry every Start app builds with. Platform-owned: regenerated,
+ * never edited. On Workers it's an entrypoint the host can also call over RPC.
+ */
+export declare const renderStartServerEntry: (target?: StartTarget) => string;
 /** The start instance: the platform's middleware, then the app's own `src/start.ts` when it has one. */
 export declare const renderStartInstance: (hasAppStart: boolean) => string;
 export declare const hasAppStart: (appDir: string) => boolean;

package/dist/esm/start/entries.js

@@ -3,8 +3,19 @@ import { dirname, join, relative } from "node:path";
 export const START_SERVER_ENTRY = ".zite/server.ts";
 export const START_INSTANCE_ENTRY = ".zite/start.ts";
 const APP_START_FILES = ["src/start.ts", "src/start.tsx"];
-/** The server entry every Start app builds with. Platform-owned: regenerated, never edited. */
-export const renderStartServerEntry = () => `// Generated by zitejs for TanStack Start apps. The platform owns this file.
+/**
+ * The server entry every Start app builds with. Platform-owned: regenerated,
+ * never edited. On Workers it's an entrypoint the host can also call over RPC.
+ */
+export const renderStartServerEntry = (target = "cloudflare") => target === "cloudflare"
+    ? `// Generated by zitejs for TanStack Start apps. The platform owns this file.
+import handler from '@tanstack/react-start/server-entry';
+import { createZiteWorker } from 'zitejs/start/worker';
+import { getRouter } from '../src/router';
+
+export default createZiteWorker({ handler, getRouter });
+`
+    : `// Generated by zitejs for TanStack Start apps. The platform owns this file.
 import handler, { createServerEntry } from '@tanstack/react-start/server-entry';
 import { createZiteFetch } from 'zitejs/start/server';
 import { getRouter } from '../src/router';

package/dist/esm/start/index.d.ts

@@ -39,7 +39,10 @@ export declare const isSignInRequired: (error: unknown) => boolean;
 export declare function loginHref(redirectTo?: string): string;
 /** What a zitejs middleware means, for describe. Keyed by identity, so composing or re-exporting keeps it. */
 export type ZiteMiddlewareKind = {
-    kind: "signedIn" | "anyone" | "webhook" | "factory";
+    kind: "signedIn" | "anyone" | "factory";
+} | {
+    kind: "webhook";
+    paused?: true;
 } | {
     kind: "role";
     role: string;
@@ -54,8 +57,14 @@ export declare const signedIn: import("@tanstack/react-start").RequestMiddleware
 export declare const anyone: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, {
     user: User | null;
 }>;
-/** Webhooks delivered by the platform, which already checked the URL token. */
-export declare const webhook: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>;
+/**
+ * Webhooks delivered by the platform, which already checked the URL token.
+ * `webhook.paused` keeps the URL but runs nothing: the platform answers the
+ * provider 200 and drops the delivery until it's switched back.
+ */
+export declare const webhook: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined> & {
+    paused: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>;
+};
 /** Signed-in users with this role. */
 export declare const role: (name: string) => import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, readonly [import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, {
     user: User;

package/dist/esm/start/index.js

@@ -120,12 +120,17 @@ export const anyone = tag(createMiddleware().server(({ next, serverFnMeta }) =>
     const { user } = host();
     return runInScope({ kind: "anyone", user }, () => next({ context: { user } }));
 })), { kind: "anyone" });
-/** Webhooks delivered by the platform, which already checked the URL token. */
-export const webhook = tag(createMiddleware().server(({ next }) => {
+const webhookMiddleware = (paused) => tag(createMiddleware().server(({ next }) => {
     if (host().invoke?.kind !== "webhook")
         return new Response("Not found", { status: 404 });
     return runInScope({ kind: "webhook", user: null }, () => next());
-}), { kind: "webhook" });
+}), paused ? { kind: "webhook", paused: true } : { kind: "webhook" });
+/**
+ * Webhooks delivered by the platform, which already checked the URL token.
+ * `webhook.paused` keeps the URL but runs nothing: the platform answers the
+ * provider 200 and drops the delivery until it's switched back.
+ */
+export const webhook = Object.assign(webhookMiddleware(false), { paused: webhookMiddleware(true) });
 /** Signed-in users with this role. */
 export const role = (name) => tag(createMiddleware()
     .middleware([signedIn])

package/dist/esm/start/server.d.ts

@@ -1,7 +1,7 @@
-import type { HostProps, PlatformBinding, ZiteRequestContext } from "./types.js";
+import type { HostProps, PlatformBinding, RenderWatch, ZiteRequestContext } from "./types.js";
 export { runWithHost } from "./scope.js";
 export { describeApp } from "./describe.js";
-export type { HostProps, PlatformBinding, PlatformCallInput, PlatformCallResult, PlatformSession, RunRecord } from "./types.js";
+export type { HostProps, PlatformBinding, PlatformCallInput, PlatformCallResult, PlatformSession, RenderWatch, RunRecord } from "./types.js";
 /**
  * Routes every zitejs data, integration and email call to this request's
  * platform, on one session, and only inside an access scope. The access kind
@@ -22,16 +22,30 @@ export declare const builtFunctionIds: () => string[];
 /** Each server function's `description` option, written in by `zite()` at build. */
 export declare const builtFunctionDescriptions: () => Record<string, string>;
 type Fetch = (request: Request, ...rest: unknown[]) => Promise<Response> | Response;
-/**
- * The fetch handler of a Start app's server entry. A request the host
- * dispatched carries its identity and platform in props; anything else (describe
- * under `vite preview`, tests) reads `x-zite-*` headers and uses `platform`
- * if one is given.
- */
-export declare function createZiteFetch(options: {
+type WorkerContext = {
+    waitUntil(promise: Promise<unknown>): void;
+};
+export type ZiteServerOptions = {
     handler: {
         fetch: Fetch;
     };
     getRouter: () => unknown;
     platform?: PlatformBinding;
-}): Fetch;
+};
+type HostedContext = WorkerContext & {
+    props?: Partial<HostProps>;
+};
+export type ZiteHandlers = {
+    fetch: Fetch;
+    /** A page the host may cache: as `fetch`, with every read and outbound fetch reported to `watch`. */
+    render(request: Request, ctx: HostedContext, watch: RenderWatch): Promise<Response>;
+};
+/**
+ * The handlers of a Start app's server entry. A request the host dispatched
+ * carries its identity and platform in props; anything else (describe under
+ * `vite preview`, tests) reads `x-zite-*` headers and uses `platform` if one
+ * is given.
+ */
+export declare function createZiteHandlers(options: ZiteServerOptions): ZiteHandlers;
+/** The fetch handler alone, for entries that take no RPC. */
+export declare function createZiteFetch(options: ZiteServerOptions): Fetch;

package/dist/esm/start/server.js

@@ -18,7 +18,7 @@ export function installPlatformTransport() {
         // Fails closed: no platform means no platform access, never a fallback.
         if (!host?.platform)
             throw new Error("The Zite platform binding is missing");
-        host.session ??= Promise.resolve(host.platform.session());
+        host.session ??= Promise.resolve(host.watch ? host.platform.session(host.watch) : host.platform.session());
         const result = await (await host.session).call({ integrationId, className, methodName, params, access: scope.kind });
         if ("value" in result)
             return result.value;
@@ -26,7 +26,31 @@ export function installPlatformTransport() {
         throw new ZiteError(code in ZITE_ERROR_STATUS ? code : "INTERNAL_ERROR", message);
     };
     globalThis.__wrapSdkCall = sdkCall;
+    watchOutboundFetches();
 }
+let fetchesWatched = false;
+const fetchedHost = (input) => {
+    try {
+        return new URL(input instanceof Request ? input.url : input).host;
+    }
+    catch {
+        return "?";
+    }
+};
+// A page that fetched depends on more than the reads the host saw, so the host
+// must hear of it before the fetch goes out. Next patches fetch for the same reason.
+const watchOutboundFetches = () => {
+    if (fetchesWatched)
+        return;
+    fetchesWatched = true;
+    const nativeFetch = globalThis.fetch.bind(globalThis);
+    globalThis.fetch = async (input, init) => {
+        const watch = getHost()?.watch;
+        if (watch)
+            await watch.uncacheable(`fetch ${fetchedHost(input)}`);
+        return nativeFetch(input, init);
+    };
+};
 const decodeUser = (value) => JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(value.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0))));
 const INVOKE_KINDS = new Set(["webhook", "describe", "workflow", "warm"]);
 /** What the host dispatched this request with. Headers are ignored: props are the only thing it alone can set. */
@@ -114,21 +138,22 @@ const pageStatus = (host) => {
     return isZiteError(failed) ? ZITE_ERROR_STATUS[failed.code] : undefined;
 };
 /**
- * The fetch handler of a Start app's server entry. A request the host
- * dispatched carries its identity and platform in props; anything else (describe
- * under `vite preview`, tests) reads `x-zite-*` headers and uses `platform`
- * if one is given.
+ * The handlers of a Start app's server entry. A request the host dispatched
+ * carries its identity and platform in props; anything else (describe under
+ * `vite preview`, tests) reads `x-zite-*` headers and uses `platform` if one
+ * is given.
  */
-export function createZiteFetch(options) {
+export function createZiteHandlers(options) {
     installPlatformTransport();
     // Loaded on first use, so a page request never pays for importing workflow modules.
     let workflows;
     const loadedWorkflows = () => (workflows ??= loadWorkflows());
-    return async (request, ...rest) => {
-        const ctx = rest[1];
+    const serve = async (request, ctx, watch) => {
         const host = ctx?.props?.platform
             ? hostContextFromProps(request, ctx.props)
             : hostContextFromRequest(request, options.platform);
+        if (watch)
+            host.watch = watch;
         // Starting this isolate was the point: the platform warms a build before its
         // first visitors, and no app code runs.
         if (host.invoke?.kind === "warm")
@@ -150,10 +175,23 @@ export function createZiteFetch(options) {
             const { platform } = host;
             if (!host.runs.length || !platform)
                 return;
-            const flushed = platform.runs({ runs: host.runs }).catch((error) => {
+            const batch = { runs: host.runs };
+            // On the request's session when it has one: one call, not another binding round trip.
+            const flushed = (async () => {
+                const session = host.session ? await host.session : undefined;
+                await (session?.runs ? session.runs(batch) : platform.runs(batch));
+            })().catch((error) => {
                 console.error("[zite] couldn't record runs", error);
             });
             ctx?.waitUntil(flushed);
         });
     };
+    return {
+        fetch: (request, ...rest) => serve(request, rest[1]),
+        render: (request, ctx, watch) => serve(request, ctx, watch),
+    };
+}
+/** The fetch handler alone, for entries that take no RPC. */
+export function createZiteFetch(options) {
+    return createZiteHandlers(options).fetch;
 }

package/dist/esm/start/types.d.ts

@@ -42,11 +42,22 @@ export type PlatformCallResult = {
 };
 export type PlatformSession = {
     call(call: PlatformCallInput): Promise<PlatformCallResult>;
+    /** As `PlatformBinding.runs`, on a session the request already holds. Hosts before 0.10.0-start.4 lack it. */
+    runs?(batch: {
+        runs: RunRecord[];
+    }): Promise<void>;
+};
+/**
+ * The host's ear on a page render it may cache, from `render()`. Reports can
+ * only make the page less cacheable, so an app gains nothing by sending them.
+ */
+export type RenderWatch = {
+    uncacheable(reason: string): Promise<void>;
 };
 /** What the host hands each request: its platform, already scoped to the app, build, request and user. */
 export type PlatformBinding = {
-    /** Every platform call of one request goes through one session. */
-    session(): PlatformSession | Promise<PlatformSession>;
+    /** Every platform call of one request goes through one session. A render's session reports what it read to `watch`. */
+    session(watch?: RenderWatch): PlatformSession | Promise<PlatformSession>;
     /** One batch per request, after its response has ended. */
     runs(batch: {
         runs: RunRecord[];
@@ -76,6 +87,8 @@ export type ZiteRequestContext = {
     runs: RunRecord[];
     platform?: PlatformBinding;
     session?: Promise<PlatformSession>;
+    /** Set when the host renders a page it may cache. */
+    watch?: RenderWatch;
     /** This request's router, so a page's status can follow the error it rendered. */
     router?: unknown;
 };

package/dist/esm/start/vite.js

@@ -32,8 +32,9 @@ export function zite(options = {}) {
     // Platform-owned, so they're rewritten whenever they differ. Sandboxes run the
     // image's zitejs for `generate`, which may predate Start; the plugin can't.
     const appDir = process.cwd();
-    if (!options.serverEntry)
-        writeIfChanged(appDir, START_SERVER_ENTRY, renderStartServerEntry());
+    if (!options.serverEntry) {
+        writeIfChanged(appDir, START_SERVER_ENTRY, renderStartServerEntry(options.cloudflare === false ? "node" : "cloudflare"));
+    }
     writeIfChanged(appDir, START_INSTANCE_ENTRY, renderStartInstance(hasAppStart(appDir)));
     // Every server function TanStack's compiler found, from its own hook, by id.
     const ids = new Map();
@@ -125,7 +126,7 @@ export function zite(options = {}) {
                 behavior: "error",
                 client: {
                     // Appended to TanStack's own.
-                    specifiers: ["zitejs/start/server", "zitejs/start/describe", "zitejs/runtime"],
+                    specifiers: ["zitejs/start/server", "zitejs/start/worker", "zitejs/start/describe", "zitejs/runtime"],
                     // Replaces TanStack's list, so its `**/*.server.*` is restated. File
                     // patterns also catch `zitejs/db` and `zitejs/integrations`, which the
                     // aliases above rewrite before specifiers are matched.

package/dist/esm/start/worker.d.ts

@@ -0,0 +1,11 @@
+import { type ZiteServerOptions } from "./server.js";
+import type { RenderWatch } from "./types.js";
+export type ZiteWorker = new (ctx: unknown, env: unknown) => {
+    fetch(request: Request): Promise<Response>;
+    render(request: Request, watch: RenderWatch): Promise<Response>;
+};
+/**
+ * A Start app's Worker. The host sends most requests to `fetch`, and a page it
+ * may cache to `render` over RPC, with a watch for what the page depends on.
+ */
+export declare function createZiteWorker(options: ZiteServerOptions): ZiteWorker;

package/dist/esm/start/worker.js

@@ -0,0 +1,20 @@
+// For the generated server entry of a Workers build only. Apps never import this.
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { createZiteHandlers } from "./server.js";
+/**
+ * A Start app's Worker. The host sends most requests to `fetch`, and a page it
+ * may cache to `render` over RPC, with a watch for what the page depends on.
+ */
+export function createZiteWorker(options) {
+    const handlers = createZiteHandlers(options);
+    return class extends WorkerEntrypoint {
+        async fetch(request) {
+            return handlers.fetch(request, this.env, this.ctx);
+        }
+        // An argument's stubs are disposed when the call returns, and a streamed
+        // page can still read after that.
+        async render(request, watch) {
+            return handlers.render(request, this.ctx, watch.dup?.() ?? watch);
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zitejs",
-  "version": "0.10.0-start.3",
+  "version": "0.10.0-start.5",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "sideEffects": false,
@@ -101,6 +101,11 @@
       "import": "./dist/esm/start/server.js",
       "default": "./dist/esm/start/server.js"
     },
+    "./start/worker": {
+      "types": "./dist/esm/start/worker.d.ts",
+      "import": "./dist/esm/start/worker.js",
+      "default": "./dist/esm/start/worker.js"
+    },
     "./start/instance": {
       "types": "./dist/esm/start/instance.d.ts",
       "import": "./dist/esm/start/instance.js",