@mistriwork/cloudflare 0.0.0 → 1.0.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baljinder Randhawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
+<img src="mark.svg" alt="mistri" width="48" height="48" />
+
 # @mistriwork/cloudflare
 
-Reserved for [mistri](https://github.com/rbaljinder/mistri). The first release is coming soon.
+A [mistri](https://mistriwork.dev) App on Cloudflare Containers: the container class and the Worker handlers that
+`mistri deploy init cloudflare` writes a Worker against, so a fix to the glue is a package upgrade rather than a diff
+in every project.
+
+```ts
+import { MistriContainer, mistriWorker } from '@mistriwork/cloudflare';
+
+export class App extends MistriContainer {
+  static override options = { vars: ['MISTRI_PUBLIC_URL'], secrets: ['BETTER_AUTH_SECRET'] };
+}
+export default mistriWorker({ binding: 'APP', instance: 'app-1', location: 'enam' });
+```
+
+`MistriContainer` is always on, waits out mistri's startup checks before it answers 500, hands the Worker's named
+vars and secrets to the container, and logs its start and exit. It also upgrades itself: `wrangler deploy` rolls
+nothing out under the `durable_object` scheduling policy and a running container keeps its startup image and env, so
+the Durable Object records what it started the container with (image, `MISTRI_DEPLOY_ID`, instance type) and, on a
+request or the Worker's tick, replaces a healthy container that differs from what its own Worker version wants (never
+one still starting, at most once a minute). The platform moves a running Durable Object onto a new Worker version
+only after about five minutes, so `mistriWorker` stamps its version on the status probe and the tick, and an object
+behind a newer Worker resets itself (at most once per 30 seconds) and starts again on it. `GET /__mistri/status` with `MISTRI_RESTART_TOKEN` in `x-mistri-restart`
+reports the Worker version (`version_metadata` binding `CF_VERSION_METADATA`), what is desired and what the container
+started with, which `mistri deploy` polls; a `POST` with the token stops the container, the manual fallback. Its `options` are `port`, `instanceType` and `image` (pinned at each start, for an account
+whose container applications are created by the Durable Object), `startupTimeoutMs`, `vars`, `secrets`,
+`restartTokenEnv`, `sleepAfter` and `alwaysOn`.
+
+`mistriWorker` returns `fetch` (every request to the one named instance, as it is, so WebSockets and streams pass)
+and `scheduled` (a once-a-minute `/readyz` that starts the instance if a host restart or a rollout stopped it).
+
+`forwardEmail(message, env, { binding, instance, secretEnv, parse })` signs an inbound message (HMAC-SHA-256 over
+`<timestamp>.<body>`) and posts it to the App's `/api/mail/inbound` through the Durable Object. Hand it the parser:
+`parse: (raw) => PostalMime.parse(raw, { attachmentEncoding: 'base64' })`; this package carries none. A 2xx or a replayed delivery (409) is done; a 404, 413, 400 or 422 rejects the message with
+a reason; anything else (401, 403, 429, 5xx) throws, so a signing or configuration fault is retried and logged rather
+than finishing as if the mail were forwarded.
+
+`@cloudflare/containers` is a peer dependency. mistri itself depends on nothing here.
+[Source](https://github.com/rbaljinder/mistri/tree/main/packages/cloudflare).

package/dist/container.d.ts

@@ -0,0 +1,87 @@
+/** The Container class a mistri App runs in on Cloudflare (MistriContainer). */
+import { Container } from '@cloudflare/containers';
+import { type MistriContainerOptions } from './options.js';
+/** The runtime's handle on the container, as far as the pin reads it. */
+interface Runtime {
+    images?: Record<string, unknown>;
+    running?: boolean;
+    inspect?(): Promise<{
+        image?: string;
+    }>;
+    start(options: Record<string, unknown>): unknown;
+}
+interface Storage {
+    get(key: string): Promise<unknown>;
+    put(key: string, value: unknown): Promise<void>;
+}
+interface State {
+    container?: Runtime;
+    storage?: Storage;
+    abort?(reason?: string): void;
+}
+/**
+ * The Container class a mistri App runs in, with what a field deployment learned the hard way:
+ *
+ * - always on: the instance never sleeps on inactivity (jobs, effects, mail and live sync run between requests);
+ * - patient startup: mistri listens only after its startup checks, and the class waits 20 s for the port by default,
+ *   which turned every request during a start into a 500;
+ * - an optional pin of the image and instance type at each start, for an account whose container applications are
+ *   created by the Durable Object;
+ * - a self-upgrade: under the `durable_object` scheduling policy `wrangler deploy` rolls nothing out and a running
+ *   container keeps its startup image and env, so the Durable Object records what it started the container with and, on
+ *   a request or the Worker's tick, replaces a healthy container whose image, deploy id or instance type is not what
+ *   this Worker version wants (at most one replacement per minute; a container still starting is left alone);
+ * - a self-reset: the platform moves a running Durable Object onto a new Worker version eventually (about five minutes
+ *   here), so when the Worker's probe or tick names a newer version than this object's own, the object aborts (at most
+ *   once per 30 seconds) and the platform starts it again on the version that is live;
+ * - a token-gated status probe (isProbe) and restart (isRestart), the manual fallback;
+ * - the Worker's named vars and secrets handed to the container, and its start, stop and error logged.
+ *
+ * Configure by overriding the static `options`:
+ *
+ *   export class App extends MistriContainer {
+ *     static override options = { vars: ['MISTRI_PUBLIC_URL'], secrets: ['BETTER_AUTH_SECRET'] };
+ *   }
+ */
+export declare class MistriContainer extends Container<Record<string, unknown>> {
+    static options: MistriContainerOptions;
+    defaultPort: number;
+    sleepAfter: string;
+    enableInternet: boolean;
+    pingEndpoint: string;
+    private readonly settings;
+    private readonly workerEnv;
+    private readonly runtime;
+    private readonly storage;
+    private readonly object;
+    private recorded;
+    private replacing;
+    private lastReplace;
+    constructor(ctx: State, env: Record<string, unknown>);
+    onActivityExpired(): Promise<void>;
+    /** What this Worker version wants the container to be started with. */
+    private desired;
+    private startedWith;
+    /**
+     * Replace a healthy container that was started with something else than this Worker version wants. The container is
+     * not restarted here: after the stop, the request in hand (or the next one) starts it with this version's image and
+     * env. A container with no record was started before the Durable Object kept one, so it is replaced once.
+     */
+    private upgrade;
+    private report;
+    /**
+     * Abort this Durable Object when the Worker in front of it runs a newer version: the next request finds it started
+     * again on the live version, whose upgrade() then replaces the container. The time of the reset is stored first, so
+     * an object the platform starts again on its old version is reset at most once per RESET_GAP_MS.
+     */
+    private resetIfBehind;
+    fetch(request: Request): Promise<Response>;
+    startAndWaitForPorts(...args: Parameters<Container['startAndWaitForPorts']>): Promise<void>;
+    onStart(): Promise<void>;
+    onStop(params: {
+        exitCode?: number;
+        reason?: string;
+    }): void;
+    onError(error: unknown): unknown;
+}
+export {};

package/dist/container.js

@@ -0,0 +1,200 @@
+/** The Container class a mistri App runs in on Cloudflare (MistriContainer). */
+import { Container } from '@cloudflare/containers';
+import { containerEnv } from './env.js';
+import { DEFAULT_RESTART_TOKEN_ENV, DEFAULT_STARTUP_MS, DEFAULT_PORT, WORKER_VERSION_HEADER, } from './options.js';
+import { isProbe, isRestart } from './restart.js';
+const STARTED_KEY = 'mistri:started';
+const RESET_KEY = 'mistri:reset-at';
+/** The least between two self-resets: an object the platform starts again on its old version is not reset in a loop. */
+const RESET_GAP_MS = 30_000;
+/** The least between two replacements: a start that does not take is retried by the next tick, not in a loop. */
+const REPLACE_GAP_MS = 60_000;
+/**
+ * The Container class a mistri App runs in, with what a field deployment learned the hard way:
+ *
+ * - always on: the instance never sleeps on inactivity (jobs, effects, mail and live sync run between requests);
+ * - patient startup: mistri listens only after its startup checks, and the class waits 20 s for the port by default,
+ *   which turned every request during a start into a 500;
+ * - an optional pin of the image and instance type at each start, for an account whose container applications are
+ *   created by the Durable Object;
+ * - a self-upgrade: under the `durable_object` scheduling policy `wrangler deploy` rolls nothing out and a running
+ *   container keeps its startup image and env, so the Durable Object records what it started the container with and, on
+ *   a request or the Worker's tick, replaces a healthy container whose image, deploy id or instance type is not what
+ *   this Worker version wants (at most one replacement per minute; a container still starting is left alone);
+ * - a self-reset: the platform moves a running Durable Object onto a new Worker version eventually (about five minutes
+ *   here), so when the Worker's probe or tick names a newer version than this object's own, the object aborts (at most
+ *   once per 30 seconds) and the platform starts it again on the version that is live;
+ * - a token-gated status probe (isProbe) and restart (isRestart), the manual fallback;
+ * - the Worker's named vars and secrets handed to the container, and its start, stop and error logged.
+ *
+ * Configure by overriding the static `options`:
+ *
+ *   export class App extends MistriContainer {
+ *     static override options = { vars: ['MISTRI_PUBLIC_URL'], secrets: ['BETTER_AUTH_SECRET'] };
+ *   }
+ */
+export class MistriContainer extends Container {
+    static options = {};
+    defaultPort = DEFAULT_PORT;
+    sleepAfter = '5m';
+    /* PostgreSQL, SMTP and a model API are outbound. */
+    enableInternet = true;
+    /* Startup only waits for the port to answer; /healthz opens no database. */
+    pingEndpoint = 'localhost/healthz';
+    settings;
+    workerEnv;
+    runtime;
+    storage;
+    object;
+    recorded;
+    replacing = false;
+    lastReplace = Number.NEGATIVE_INFINITY;
+    constructor(ctx, env) {
+        super(ctx, env);
+        const settings = new.target.options;
+        this.settings = settings;
+        this.workerEnv = env;
+        this.runtime = ctx.container;
+        this.storage = ctx.storage;
+        this.object = ctx;
+        this.defaultPort = settings.port ?? DEFAULT_PORT;
+        if (settings.sleepAfter)
+            this.sleepAfter = settings.sleepAfter;
+        const runtime = ctx.container;
+        if (runtime && settings.image && settings.instanceType) {
+            const { image, instanceType } = settings;
+            /* `container` is the class's own handle on ctx.container; every use but start passes through unchanged. */
+            this.container = new Proxy(runtime, {
+                get(target, key) {
+                    if (key === 'start')
+                        return (options) => target.start({ ...options, image: target.images?.[image], instance: instanceType });
+                    const value = Reflect.get(target, key);
+                    return typeof value === 'function' ? value.bind(target) : value;
+                },
+            });
+        }
+        this.envVars = containerEnv(settings, env);
+    }
+    async onActivityExpired() {
+        if (this.settings.alwaysOn === false)
+            await super.onActivityExpired();
+    }
+    /** What this Worker version wants the container to be started with. */
+    desired() {
+        const image = this.settings.image ? this.runtime?.images?.[this.settings.image] : undefined;
+        const deployId = this.workerEnv.MISTRI_DEPLOY_ID;
+        return {
+            image: image == null ? null : String(image),
+            deployId: typeof deployId === 'string' && deployId !== '' ? deployId : null,
+            instanceType: this.settings.instanceType ?? null,
+        };
+    }
+    async startedWith() {
+        if (this.recorded === undefined)
+            this.recorded = (await this.storage?.get(STARTED_KEY)) ?? null;
+        return this.recorded;
+    }
+    /**
+     * Replace a healthy container that was started with something else than this Worker version wants. The container is
+     * not restarted here: after the stop, the request in hand (or the next one) starts it with this version's image and
+     * env. A container with no record was started before the Durable Object kept one, so it is replaced once.
+     */
+    async upgrade() {
+        if (this.replacing || !this.runtime?.running || Date.now() - this.lastReplace < REPLACE_GAP_MS)
+            return;
+        const want = this.desired();
+        if (want.image === null && want.deployId === null)
+            return;
+        const had = await this.startedWith();
+        const differs = had === null ||
+            (want.deployId !== null && had.deployId !== want.deployId) ||
+            (want.image !== null && had.image !== want.image) ||
+            (want.instanceType !== null && had.instanceType !== want.instanceType);
+        if (!differs || (await this.getState()).status !== 'healthy')
+            return;
+        this.replacing = true;
+        this.lastReplace = Date.now();
+        try {
+            console.log(`mistri container replaced: started with ${had?.deployId ?? 'unrecorded'}, wanted ${want.deployId ?? want.image}`);
+            await this.destroy();
+        }
+        finally {
+            this.replacing = false;
+        }
+    }
+    async report() {
+        const running = this.runtime?.running === true;
+        let image = null;
+        try {
+            image = (await this.runtime?.inspect?.())?.image || null;
+        }
+        catch {
+            /* A runtime without inspect, or one that refuses while the container starts, reports no image. */
+        }
+        const had = await this.startedWith();
+        const { image: wantImage, deployId } = this.desired();
+        const version = this.workerEnv.CF_VERSION_METADATA?.id;
+        return Response.json({
+            workerVersion: version ?? null,
+            desired: { image: wantImage, deployId },
+            startedWith: had ? { image: had.image, deployId: had.deployId, at: had.at } : null,
+            container: { running, image },
+        });
+    }
+    /**
+     * Abort this Durable Object when the Worker in front of it runs a newer version: the next request finds it started
+     * again on the live version, whose upgrade() then replaces the container. The time of the reset is stored first, so
+     * an object the platform starts again on its old version is reset at most once per RESET_GAP_MS.
+     */
+    async resetIfBehind(request) {
+        const [live, liveAt] = (request.headers.get(WORKER_VERSION_HEADER) ?? '').split(' ');
+        const own = this.workerEnv.CF_VERSION_METADATA;
+        if (!live || !liveAt || !own?.id || !own.timestamp || live === own.id || typeof this.object.abort !== 'function')
+            return;
+        /* Only a newer Worker: during a split rollout an older one also stamps, and must not reset the newer object. */
+        if (!(Date.parse(liveAt) > Date.parse(own.timestamp)))
+            return;
+        const last = Number((await this.storage?.get(RESET_KEY)) ?? 0);
+        if (Date.now() - last < RESET_GAP_MS)
+            return;
+        await this.storage?.put(RESET_KEY, Date.now());
+        console.log(`mistri durable object reset: running Worker version ${own.id}, the Worker in front runs ${live}`);
+        this.object.abort(`Worker version ${live} is live`);
+    }
+    async fetch(request) {
+        await this.resetIfBehind(request);
+        const tokenEnv = this.settings.restartTokenEnv ?? DEFAULT_RESTART_TOKEN_ENV;
+        if (isRestart(request, this.workerEnv, tokenEnv)) {
+            await this.destroy();
+            return new Response('stopped; the next request starts it again\n');
+        }
+        const probe = isProbe(request, this.workerEnv, tokenEnv);
+        try {
+            await this.upgrade();
+        }
+        catch (error) {
+            console.error('mistri container upgrade failed', error);
+        }
+        return probe ? this.report() : super.fetch(request);
+    }
+    startAndWaitForPorts(...args) {
+        const [portsOrArgs, cancellation, start] = args;
+        const patient = { instanceGetTimeoutMS: 60_000, portReadyTimeoutMS: this.settings.startupTimeoutMs ?? DEFAULT_STARTUP_MS };
+        if (portsOrArgs !== undefined && typeof portsOrArgs === 'object' && !Array.isArray(portsOrArgs))
+            return super.startAndWaitForPorts({ ...portsOrArgs, cancellationOptions: { ...patient, ...portsOrArgs.cancellationOptions } });
+        return super.startAndWaitForPorts(portsOrArgs, { ...patient, ...cancellation }, start);
+    }
+    async onStart() {
+        console.log('mistri container started');
+        const want = this.desired();
+        this.recorded = { ...want, at: new Date().toISOString() };
+        await this.storage?.put(STARTED_KEY, this.recorded);
+    }
+    onStop(params) {
+        console.warn(`mistri container stopped: exit ${params.exitCode ?? '?'} (${params.reason ?? 'no reason'})`);
+    }
+    onError(error) {
+        console.error('mistri container error', error);
+        throw error;
+    }
+}

package/dist/env.d.ts

@@ -0,0 +1,8 @@
+/** The environment a mistri container starts with, from the Worker's own. */
+import { type MistriContainerOptions } from './options.js';
+/**
+ * The environment the container starts with: the image's own ENV said again (a start's environment is not guaranteed
+ * to be merged into the image's), what a Cloudflare front end needs, then every named var and secret the Worker holds.
+ * A name that is unset or empty is left out, so the container's default applies.
+ */
+export declare function containerEnv(options: MistriContainerOptions, env: Record<string, unknown>): Record<string, string>;

package/dist/env.js

@@ -0,0 +1,20 @@
+/** The environment a mistri container starts with, from the Worker's own. */
+import { DEFAULT_PORT } from './options.js';
+/**
+ * The environment the container starts with: the image's own ENV said again (a start's environment is not guaranteed
+ * to be merged into the image's), what a Cloudflare front end needs, then every named var and secret the Worker holds.
+ * A name that is unset or empty is left out, so the container's default applies.
+ */
+export function containerEnv(options, env) {
+    const names = [...new Set(['MISTRI_DEPLOY_ID', ...(options.vars ?? []), ...(options.secrets ?? [])])];
+    return {
+        PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
+        PORT: String(options.port ?? DEFAULT_PORT),
+        NODE_OPTIONS: '--enable-source-maps',
+        NODE_COMPILE_CACHE: '/tmp/v8',
+        NODE_ENV: 'production',
+        /* The client address is Cloudflare's CF-Connecting-IP; without this every visitor shares one rate limit. */
+        MISTRI_TRUST_PROXY_CLOUDFLARE: '1',
+        ...Object.fromEntries(names.flatMap((name) => (typeof env[name] === 'string' && env[name] !== '' ? [[name, env[name]]] : []))),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @mistriwork/cloudflare: a mistri App on Cloudflare Containers. `mistri deploy init cloudflare` writes a Worker
+ * against this; a fix to the glue is a package upgrade, not a diff in every project.
+ */
+export { MistriContainer } from './container.js';
+export { mistriWorker, type MistriWorkerOptions } from './worker.js';
+export { forwardEmail, signMail, type ForwardEmailOptions, type InboundMessage, type ParsedMail } from './mail.js';
+export { isProbe, isRestart } from './restart.js';
+export { containerEnv } from './env.js';
+export { PROBE_PATH, RESTART_HEADER, type MistriContainerOptions } from './options.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @mistriwork/cloudflare: a mistri App on Cloudflare Containers. `mistri deploy init cloudflare` writes a Worker
+ * against this; a fix to the glue is a package upgrade, not a diff in every project.
+ */
+export { MistriContainer } from './container.js';
+export { mistriWorker } from './worker.js';
+export { forwardEmail, signMail } from './mail.js';
+export { isProbe, isRestart } from './restart.js';
+export { containerEnv } from './env.js';
+export { PROBE_PATH, RESTART_HEADER } from './options.js';

package/dist/instance.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The one named instance. Its Durable Object, and so its container, is placed where the name is first used, near the
+ * database rather than the visitor: a page is several round trips to it.
+ */
+export declare function instanceOf(env: Record<string, unknown>, binding: string, name: string, location?: string): {
+    fetch(request: Request): Promise<Response>;
+};

package/dist/instance.js

@@ -0,0 +1,10 @@
+/**
+ * The one named instance. Its Durable Object, and so its container, is placed where the name is first used, near the
+ * database rather than the visitor: a page is several round trips to it.
+ */
+export function instanceOf(env, binding, name, location) {
+    const namespace = env[binding];
+    if (!namespace || typeof namespace.idFromName !== 'function')
+        throw new Error(`the Worker has no Durable Object binding "${binding}"`);
+    return namespace.get(namespace.idFromName(name), location ? { locationHint: location } : undefined);
+}

package/dist/mail.d.ts

@@ -0,0 +1,52 @@
+export interface ParsedMail {
+    from?: unknown;
+    to?: unknown[];
+    cc?: unknown[];
+    subject?: string;
+    messageId?: string;
+    inReplyTo?: string;
+    references?: string;
+    text?: string;
+    html?: string;
+    headers: Array<{
+        key: string;
+        value: string;
+    }>;
+    attachments: Array<{
+        filename?: string | null;
+        mimeType: string;
+        content: unknown;
+    }>;
+}
+/** The part of an email message the forwarder reads (Cloudflare's ForwardableEmailMessage). */
+export interface InboundMessage {
+    to: string;
+    raw: ReadableStream<Uint8Array>;
+    setReject(reason: string): void;
+}
+export interface ForwardEmailOptions {
+    /** The Durable Object binding, and the instance and location hint the Worker's `fetch` uses (mistriWorker). */
+    binding: string;
+    instance: string;
+    location?: string;
+    /** The Worker secret holding the signing key (the App's mail secret). */
+    secretEnv: string;
+    /** Parses the raw message. */
+    parse(raw: ReadableStream<Uint8Array>): Promise<ParsedMail>;
+    /** The App's inbound endpoint. Default `/api/mail/inbound`. */
+    path?: string;
+    /** The public address, so the Host header passes MISTRI_ALLOWED_HOSTS. Default the Worker's MISTRI_PUBLIC_URL. */
+    publicUrl?: string;
+    /** The signature headers are `x-<header>-timestamp` and `x-<header>-signature`. Default `mistri`. */
+    header?: string;
+}
+/** `v1=<hex>`: HMAC-SHA-256 over `<timestamp>.<body>`. */
+export declare function signMail(secret: string, timestamp: string, body: string): Promise<string>;
+/**
+ * Forward one message, and let nothing finish quietly that the App did not take. A 2xx (204 taken, 202 dropped and
+ * logged) and the replay 409 are done. A 404 rejects it ("No such mailbox"), a 413 as too large, and a 400 or 422 as
+ * unreadable: those are the message's own fault and a retry cannot change them. Everything else — 401 or 403 (the
+ * signature or the Worker's clock or secret), 429, a 5xx, a redirect — is the deployment's problem, not the sender's, so
+ * it throws, for Email Routing to retry and for the Worker's logs to show. The error names the status, never the message.
+ */
+export declare function forwardEmail(message: InboundMessage, env: Record<string, unknown>, options: ForwardEmailOptions): Promise<void>;

package/dist/mail.js

@@ -0,0 +1,66 @@
+/**
+ * Inbound mail for a tenant App: Cloudflare Email Routing hands a message to the Worker's `email()`; this signs it
+ * and posts it to the App's inbound endpoint through the Durable Object, never over the public Internet.
+ * The message is parsed by a function the project supplies (postal-mime's `PostalMime.parse` is the usual one), so
+ * this package carries no parser.
+ */
+import { instanceOf } from './instance.js';
+const hex = (bytes) => [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, '0')).join('');
+/** `v1=<hex>`: HMAC-SHA-256 over `<timestamp>.<body>`. */
+export async function signMail(secret, timestamp, body) {
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return `v1=${hex(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${timestamp}.${body}`)))}`;
+}
+function mailBody(message, mail) {
+    return JSON.stringify({
+        recipient: message.to,
+        from: mail.from,
+        to: mail.to ?? [],
+        cc: mail.cc ?? [],
+        subject: mail.subject ?? '',
+        messageId: mail.messageId,
+        inReplyTo: mail.inReplyTo,
+        references: mail.references,
+        text: mail.text,
+        html: mail.html,
+        headers: Object.fromEntries(mail.headers.map((h) => [h.key, h.value])),
+        attachments: mail.attachments.map((a) => ({ name: a.filename ?? 'attachment', type: a.mimeType, content: a.content })),
+    });
+}
+/**
+ * Forward one message, and let nothing finish quietly that the App did not take. A 2xx (204 taken, 202 dropped and
+ * logged) and the replay 409 are done. A 404 rejects it ("No such mailbox"), a 413 as too large, and a 400 or 422 as
+ * unreadable: those are the message's own fault and a retry cannot change them. Everything else — 401 or 403 (the
+ * signature or the Worker's clock or secret), 429, a 5xx, a redirect — is the deployment's problem, not the sender's, so
+ * it throws, for Email Routing to retry and for the Worker's logs to show. The error names the status, never the message.
+ */
+export async function forwardEmail(message, env, options) {
+    const secret = env[options.secretEnv];
+    if (typeof secret !== 'string' || !secret)
+        throw new Error(`${options.secretEnv} is not set on the Worker`);
+    const base = options.publicUrl ?? env.MISTRI_PUBLIC_URL;
+    if (!base)
+        throw new Error('forwardEmail needs publicUrl or MISTRI_PUBLIC_URL');
+    const body = mailBody(message, await options.parse(message.raw));
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const name = options.header ?? 'mistri';
+    const answer = await instanceOf(env, options.binding, options.instance, options.location).fetch(new Request(new URL(options.path ?? '/api/mail/inbound', base), {
+        method: 'POST',
+        body,
+        headers: {
+            'content-type': 'application/json',
+            [`x-${name}-timestamp`]: timestamp,
+            [`x-${name}-signature`]: await signMail(secret, timestamp, body),
+        },
+    }));
+    if (answer.ok || answer.status === 409)
+        return;
+    if (answer.status === 404)
+        message.setReject('No such mailbox');
+    else if (answer.status === 413)
+        message.setReject('Message too large');
+    else if (answer.status === 400 || answer.status === 422)
+        message.setReject('Message could not be processed');
+    else
+        throw new Error(`the App answered ${answer.status}${answer.status === 401 ? ' (check the signing secret and the Worker clock)' : ''}`);
+}

package/dist/options.d.ts

@@ -0,0 +1,28 @@
+/** What a project says about its container: every field has the default a mistri App wants. */
+export interface MistriContainerOptions {
+    /** The port the App listens on in the image (PORT). Default 4111. */
+    port?: number;
+    /** Pin the instance type at each start (`standard-1`), for an account whose applications are created by the Durable Object. */
+    instanceType?: string;
+    /** The image's key in wrangler.jsonc, pinned at each start with `instanceType`. Unset leaves both to wrangler.jsonc. */
+    image?: string;
+    /** How long a request waits for a starting container to listen. mistri listens only after its startup checks, so minutes. Default 240000. */
+    startupTimeoutMs?: number;
+    /** Worker vars handed to the container by name (not secret). MISTRI_DEPLOY_ID is always among them. */
+    vars?: readonly string[];
+    /** Worker secrets handed to the container by name. */
+    secrets?: readonly string[];
+    /** The secret holding the restart token; a POST with its value in `x-mistri-restart` stops the container, and a GET of `/__mistri/status` with it reports the roll. Default MISTRI_RESTART_TOKEN. */
+    restartTokenEnv?: string;
+    /** The Durable Object's sleep timer. Default '5m'; it never stops an always-on container. */
+    sleepAfter?: string;
+    /** Keep the container running when idle: jobs, effects and mail run between requests. Default true. */
+    alwaysOn?: boolean;
+}
+export declare const RESTART_HEADER = "x-mistri-restart";
+export declare const PROBE_PATH = "/__mistri/status";
+/** `<version id> <upload time>` of the Worker, stamped by mistriWorker on the probe and the tick; a client's copy is dropped. */
+export declare const WORKER_VERSION_HEADER = "x-mistri-worker-version";
+export declare const DEFAULT_RESTART_TOKEN_ENV = "MISTRI_RESTART_TOKEN";
+export declare const DEFAULT_STARTUP_MS = 240000;
+export declare const DEFAULT_PORT = 4111;

package/dist/options.js

@@ -0,0 +1,7 @@
+export const RESTART_HEADER = 'x-mistri-restart';
+export const PROBE_PATH = '/__mistri/status';
+/** `<version id> <upload time>` of the Worker, stamped by mistriWorker on the probe and the tick; a client's copy is dropped. */
+export const WORKER_VERSION_HEADER = 'x-mistri-worker-version';
+export const DEFAULT_RESTART_TOKEN_ENV = 'MISTRI_RESTART_TOKEN';
+export const DEFAULT_STARTUP_MS = 240_000;
+export const DEFAULT_PORT = 4111;

package/dist/restart.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether this request is an operator's restart: a POST carrying the restart secret (32 characters or more, so a
+ * short guessable one never opens it) in `x-mistri-restart`. The container normally replaces itself after a deploy;
+ * this is the manual fallback, and what `mistri deploy` sends when it does not.
+ */
+export declare function isRestart(request: Request, env: Record<string, unknown>, tokenEnv?: string): boolean;
+/**
+ * Whether this request is the status probe: a GET of PROBE_PATH with the same token header. A path of its own (not `/`)
+ * so a stray header never turns a page view into the probe; an older Worker proxies it to the App, which is not JSON.
+ */
+export declare function isProbe(request: Request, env: Record<string, unknown>, tokenEnv?: string): boolean;

package/dist/restart.js

@@ -0,0 +1,33 @@
+/** The token-gated restart and status probe a deploy sends to a container that a code update left running. */
+import { DEFAULT_RESTART_TOKEN_ENV, PROBE_PATH, RESTART_HEADER } from './options.js';
+/** Equal in time for equal lengths, so the token is not read off response timing. */
+function same(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+function carriesToken(request, env, tokenEnv) {
+    const token = env[tokenEnv];
+    if (typeof token !== 'string' || token.length < 32)
+        return false;
+    const given = request.headers.get(RESTART_HEADER);
+    return given !== null && same(given, token);
+}
+/**
+ * Whether this request is an operator's restart: a POST carrying the restart secret (32 characters or more, so a
+ * short guessable one never opens it) in `x-mistri-restart`. The container normally replaces itself after a deploy;
+ * this is the manual fallback, and what `mistri deploy` sends when it does not.
+ */
+export function isRestart(request, env, tokenEnv = DEFAULT_RESTART_TOKEN_ENV) {
+    return request.method === 'POST' && carriesToken(request, env, tokenEnv);
+}
+/**
+ * Whether this request is the status probe: a GET of PROBE_PATH with the same token header. A path of its own (not `/`)
+ * so a stray header never turns a page view into the probe; an older Worker proxies it to the App, which is not JSON.
+ */
+export function isProbe(request, env, tokenEnv = DEFAULT_RESTART_TOKEN_ENV) {
+    return request.method === 'GET' && new URL(request.url).pathname === PROBE_PATH && carriesToken(request, env, tokenEnv);
+}

package/dist/worker.d.ts

@@ -0,0 +1,27 @@
+export interface MistriWorkerOptions {
+    /** The Durable Object binding in wrangler.jsonc (`durable_objects.bindings[].name`). */
+    binding: string;
+    /** The instance's name. One instance: a second needs a shared cache and health-aware routing first. */
+    instance: string;
+    /** Where the instance runs, fixed the first time the name is used: `enam`, `wnam`, `weur`... Near the database. */
+    location?: string;
+    /** The secret holding the restart token, as the container's `restartTokenEnv`. Default MISTRI_RESTART_TOKEN. */
+    restartTokenEnv?: string;
+}
+/**
+ * `fetch` and `scheduled` for a Worker in front of one always-on mistri container.
+ *
+ *   fetch      every request goes to the instance as it is; a WebSocket or a streamed response passes through
+ *   scheduled  once a minute: starts the instance if a host restart or a rollout stopped it, asking for nothing but
+ *              the process (/readyz answers before any App code)
+ *
+ * The status probe and the tick carry this Worker's version id (the `version_metadata` binding), so a Durable Object
+ * still on the previous version learns a newer one is live and resets itself (MistriContainer) instead of waiting out
+ * the platform's rollout, which took about five minutes. The probe is stamped only when it carries the restart token,
+ * so no visitor can make the object reset; the tick is the Worker's own. Every other request has a client's copy of
+ * the header removed, so a stamp the object reads was always put there here.
+ */
+export declare function mistriWorker(options: MistriWorkerOptions): {
+    fetch(request: Request, env: Record<string, unknown>): Promise<Response>;
+    scheduled(_controller: unknown, env: Record<string, unknown>): Promise<void>;
+};

package/dist/worker.js

@@ -0,0 +1,42 @@
+/** The Worker's `fetch` and `scheduled`: every request to one named, always-on instance. */
+import { instanceOf } from './instance.js';
+import { DEFAULT_RESTART_TOKEN_ENV, WORKER_VERSION_HEADER } from './options.js';
+import { isProbe } from './restart.js';
+/**
+ * `fetch` and `scheduled` for a Worker in front of one always-on mistri container.
+ *
+ *   fetch      every request goes to the instance as it is; a WebSocket or a streamed response passes through
+ *   scheduled  once a minute: starts the instance if a host restart or a rollout stopped it, asking for nothing but
+ *              the process (/readyz answers before any App code)
+ *
+ * The status probe and the tick carry this Worker's version id (the `version_metadata` binding), so a Durable Object
+ * still on the previous version learns a newer one is live and resets itself (MistriContainer) instead of waiting out
+ * the platform's rollout, which took about five minutes. The probe is stamped only when it carries the restart token,
+ * so no visitor can make the object reset; the tick is the Worker's own. Every other request has a client's copy of
+ * the header removed, so a stamp the object reads was always put there here.
+ */
+export function mistriWorker(options) {
+    const instance = (env) => instanceOf(env, options.binding, options.instance, options.location);
+    return {
+        fetch(request, env) {
+            const stamp = isProbe(request, env, options.restartTokenEnv ?? DEFAULT_RESTART_TOKEN_ENV);
+            return instance(env).fetch(stamp || request.headers.has(WORKER_VERSION_HEADER) ? stamped(request, env, stamp) : request);
+        },
+        async scheduled(_controller, env) {
+            const base = env.MISTRI_PUBLIC_URL ?? 'http://container';
+            const answer = await instance(env).fetch(stamped(new Request(new URL('/readyz', base)), env, true));
+            if (!answer.ok)
+                console.warn(`/readyz answered ${answer.status}`);
+        },
+    };
+}
+/** The request with this Worker's version id and upload time in WORKER_VERSION_HEADER when `stamp`, and with no such header otherwise. */
+function stamped(request, env, stamp) {
+    const headers = new Headers(request.headers);
+    const version = env.CF_VERSION_METADATA;
+    if (stamp && version?.id && version.timestamp)
+        headers.set(WORKER_VERSION_HEADER, `${version.id} ${version.timestamp}`);
+    else
+        headers.delete(WORKER_VERSION_HEADER);
+    return new Request(request, { headers });
+}

package/mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><style>.i{fill:#1c1a17}.a{fill:#6b3fd4}@media (prefers-color-scheme:dark){.i{fill:#f2f0ec}.a{fill:#a88bff}}</style><path class="i" d="M2 4H26V18H22V10H18V28H12V10H8V28H2Z"/><rect class="a" x="20" y="20" width="10" height="8"/></svg>

package/package.json

@@ -1,4 +1,45 @@
-{ "name": "@mistriwork/cloudflare", "version": "0.0.0",
-  "description": "Reserved for mistri. The first release is coming soon.",
+{
+  "name": "@mistriwork/cloudflare",
+  "version": "1.0.0-rc.10",
+  "description": "A mistri App on Cloudflare Containers: the Container class and Worker handlers `mistri deploy init cloudflare` writes against, so a fix to the glue is a package upgrade.",
+  "keywords": [
+    "cloudflare",
+    "containers",
+    "deploy",
+    "mistri",
+    "workers"
+  ],
+  "homepage": "https://mistriwork.dev",
+  "bugs": {
+    "url": "https://github.com/rbaljinder/mistri/issues"
+  },
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/rbaljinder/mistri.git" } }
+  "author": "Baljinder Randhawa",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rbaljinder/mistri.git",
+    "directory": "packages/cloudflare"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "mark.svg",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/containers": "^0.3.7"
+  },
+  "peerDependencies": {
+    "@cloudflare/containers": "^0.3.7"
+  },
+  "engines": {
+    "node": ">=24.22.1"
+  }
+}