@astrale-os/adapter-cloudflare 0.5.0-beta.148 → 0.5.0-beta.149

package/dist/build/artifact.js

@@ -29,7 +29,9 @@ async function prepare(params, context, direct) {
         const name = workerName(params, context.build.schema.compiled.root.origin, context.environment);
         const revision = context.build.schema.compiled.root.revision;
         const configuredIssuer = deploymentAddressing(params);
-        const frontend = await frontendFiles({
+        // `frontend` stays the served file list every branch below already reads; `immutable` rides
+        // alongside it into the Worker, where it decides which of those files may be cached forever.
+        const { files: frontend, immutable } = await frontendFiles({
             frontend: context.build.frontend,
             projectDir: context.projectDir,
             output: join(directory, 'frontend'),
@@ -45,6 +47,7 @@ async function prepare(params, context, direct) {
             configuredIssuer,
             router,
             ...(frontend.length === 0 ? {} : { frontendRevision: frontendRevision(frontend) }),
+            ...(immutable.length === 0 ? {} : { frontendImmutable: immutable }),
         });
         const releaseConfig = generateWranglerConfig({
             workerName: name,

package/dist/build/frontend/files.d.ts

@@ -1,9 +1,19 @@
 import type { Build } from '@astrale-os/sdk/deployment/build';
 import { frontend as frontendBuild } from '@astrale-os/sdk/deployment/build';
+/** The served frontend, and which of its files a browser may keep without revalidating. */
+export interface FrontendOutput {
+    readonly files: readonly frontendBuild.FrontendFile[];
+    /**
+     * Served paths the bundler content-addressed, so their bytes can never change under a given name.
+     * A frontend Astrale does not build leaves this empty, which is what keeps the absence of evidence
+     * indistinguishable from evidence of mutability.
+     */
+    readonly immutable: readonly string[];
+}
 export declare function frontendFiles(input: {
     readonly frontend: Build['frontend'];
     readonly projectDir: string;
     readonly output: string;
     readonly recordSource?: (path: string) => void;
     readonly signal: AbortSignal;
-}): Promise<readonly frontendBuild.FrontendFile[]>;
+}): Promise<FrontendOutput>;

package/dist/build/frontend/files.js

@@ -5,18 +5,23 @@ import { buildViteFrontend } from './vite.js';
 export async function frontendFiles(input) {
     const frontend = input.frontend;
     if (frontend === undefined)
-        return [];
-    if (frontend.source.kind === 'external')
-        return frontendBuild.files(frontend, []);
+        return { files: [], immutable: [] };
+    if (frontend.source.kind === 'external') {
+        return { files: frontendBuild.files(frontend, []), immutable: [] };
+    }
     await rm(input.output, { recursive: true, force: true });
-    await buildViteFrontend({
+    const built = await buildViteFrontend({
         projectDir: input.projectDir,
         output: input.output,
         ...(frontend.source.config === undefined ? {} : { config: frontend.source.config }),
         recordSource: input.recordSource,
         signal: input.signal,
     });
-    return frontendBuild.files(frontend, await readFiles(input.output));
+    const files = frontendBuild.files(frontend, await readFiles(input.output));
+    // A name the bundler reported but that never reached disk is not a served path; keeping only the
+    // intersection means the evidence describes exactly what this deployment will answer with.
+    const served = new Set(files.map((file) => file.path));
+    return { files, immutable: built.immutable.filter((path) => served.has(path)) };
 }
 async function readFiles(root, current = '') {
     const entries = await readdir(join(root, current), { withFileTypes: true });

package/dist/build/frontend/vite.d.ts

@@ -1,8 +1,14 @@
-/** Build a Vite frontend in an isolated process and report its authored inputs. */
+/**
+ * Build a Vite frontend in an isolated process and report its authored inputs, along with the
+ * outputs the bundler content-addressed. Those are the files a browser may keep forever, and only
+ * the build that named them can say which they are.
+ */
 export declare function buildViteFrontend(input: {
     readonly projectDir: string;
     readonly output: string;
     readonly config?: string;
     readonly recordSource?: (path: string) => void;
     readonly signal: AbortSignal;
-}): Promise<void>;
+}): Promise<{
+    readonly immutable: readonly string[];
+}>;

package/dist/build/frontend/vite.js

@@ -3,16 +3,21 @@ import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runViteProcess } from './vite.process.js';
-/** Build a Vite frontend in an isolated process and report its authored inputs. */
+/**
+ * Build a Vite frontend in an isolated process and report its authored inputs, along with the
+ * outputs the bundler content-addressed. Those are the files a browser may keep forever, and only
+ * the build that named them can say which they are.
+ */
 export async function buildViteFrontend(input) {
     const parent = dirname(input.output);
     await mkdir(parent, { recursive: true });
     const scratch = await mkdtemp(join(parent, 'vite-run-'));
     const evidence = join(scratch, 'sources.json');
+    const addressed = join(scratch, 'addressed.json');
     try {
         await runViteProcess({
             cwd: input.projectDir,
-            arguments: [runnerPath(), input.output, evidence, input.config ?? ''],
+            arguments: [runnerPath(), input.output, evidence, input.config ?? '', addressed],
             signal: input.signal,
         });
         const sources = JSON.parse(await readFile(evidence, 'utf8'));
@@ -21,6 +26,11 @@ export async function buildViteFrontend(input) {
         }
         for (const path of sources)
             input.recordSource?.(path);
+        const immutable = JSON.parse(await readFile(addressed, 'utf8'));
+        if (!Array.isArray(immutable) || immutable.some((path) => typeof path !== 'string')) {
+            throw new TypeError('Vite preparation output evidence is invalid.');
+        }
+        return { immutable: Object.freeze([...immutable]) };
     }
     finally {
         await rm(scratch, { recursive: true, force: true });

package/dist/build/frontend/vite.runner.js

@@ -12,13 +12,14 @@ const CONFIG_FILES = Object.freeze([
 ]);
 await main();
 async function main() {
-    const [output, evidence, configured] = process.argv.slice(2);
+    const [output, evidence, configured, addressed] = process.argv.slice(2);
     if (output === undefined || evidence === undefined) {
         throw new TypeError('Vite preparation runner arguments are invalid.');
     }
     const projectDir = process.cwd();
     const vite = await projectVite(projectDir);
     const sources = new Set();
+    const immutable = new Set();
     let publicDir = false;
     let environment = {
         directory: false,
@@ -45,6 +46,16 @@ async function main() {
                     if (path !== undefined)
                         sources.add(path);
                 },
+                // The bundler is the only party that knows which outputs it content-addressed: a served path
+                // is safe to cache forever exactly when its name changes with its bytes. Reading that here,
+                // from the build that produced them, is what keeps the answer a fact rather than a guess
+                // about directory layout or file naming.
+                generateBundle(options, bundle) {
+                    for (const [fileName, entry] of Object.entries(bundle)) {
+                        if (addressedName(options, entry))
+                            immutable.add(fileName);
+                    }
+                },
             },
         ],
     });
@@ -55,6 +66,23 @@ async function main() {
     if (publicDir !== false)
         await collectTree(publicDir, sources);
     await writeFile(evidence, JSON.stringify([...sources]));
+    if (addressed !== undefined)
+        await writeFile(addressed, JSON.stringify([...immutable].sort()));
+}
+/**
+ * Whether this output's name carries a content hash, read from the template the bundler resolved.
+ *
+ * A template that is not a plain string, or that omits `[hash]`, leaves the answer unknown, and
+ * unknown must read as "not content-addressed": losing the optimization costs a revalidation, while
+ * claiming it wrongly pins a stale file in browsers for as long as the header says.
+ */
+function addressedName(options, entry) {
+    const template = entry.type === 'asset'
+        ? options.assetFileNames
+        : entry.isEntry === true
+            ? options.entryFileNames
+            : options.chunkFileNames;
+    return typeof template === 'string' && template.includes('[hash]');
 }
 function environmentCandidates(input) {
     const directory = input.directory;

package/dist/build/worker/codegen/service.d.ts

@@ -6,6 +6,7 @@ export interface ExecutionCodegenOptions {
     readonly workerSpecifier?: string;
     readonly build: Build;
     readonly frontendRevision?: string;
+    readonly frontendImmutable?: readonly string[];
     readonly maximumRequestBytes?: number;
     readonly invocationTimeoutMs?: number;
     readonly identityIssuer?: string;

package/dist/build/worker/codegen/service.js

@@ -36,7 +36,7 @@ type WorkerEnv = CloudflareEnv & CloudflareAdapterBindings & {
 type RuntimeEnv = Omit<WorkerEnv, 'ASTRALE_SIGNING_IDENTITY'>
 ${routerPredicate}
 export default generatedCloudflareWorkerEntry<WorkerEnv, RuntimeEnv>()({
-${frontend}${options.frontendRevision === undefined ? '' : `  frontendRevision: ${JSON.stringify(options.frontendRevision)},\n`}  load: async () => ({
+${frontend}${options.frontendRevision === undefined ? '' : `  frontendRevision: ${JSON.stringify(options.frontendRevision)},\n`}${options.frontendImmutable === undefined ? '' : `  frontendImmutable: ${JSON.stringify(options.frontendImmutable)},\n`}  load: async () => ({
     runtime: (await import(${JSON.stringify(options.runtimeSpecifier)})).default,
     material: ${JSON.stringify(generated)} as unknown as GeneratedBuildMaterial,
   }),

package/dist/build/worker/execution.prepare.d.ts

@@ -10,6 +10,7 @@ export declare function prepareExecution(input: {
     readonly name: string;
     readonly direct: boolean;
     readonly frontendRevision?: string;
+    readonly frontendImmutable?: readonly string[];
     readonly configuredIssuer?: string;
     readonly router: ReturnType<typeof resolveRouter>;
 }): Promise<{

package/dist/build/worker/execution.prepare.js

@@ -25,6 +25,9 @@ export async function prepareExecution(input) {
         workerSpecifier,
         build: input.context.build,
         ...(input.frontendRevision === undefined ? {} : { frontendRevision: input.frontendRevision }),
+        ...(input.frontendImmutable === undefined
+            ? {}
+            : { frontendImmutable: input.frontendImmutable }),
         ...(maximumRequestBytes === undefined ? {} : { maximumRequestBytes }),
         ...(invocationTimeoutMs === undefined ? {} : { invocationTimeoutMs }),
         ...(input.params.tokenExchange === undefined

package/dist/worker/entry.d.ts

@@ -20,6 +20,8 @@ export interface CloudflareWorkerConfig<RuntimeValue extends Runtime, Bindings e
     readonly frontend?: BuildMaterial['frontend'];
     /** Generated browser-file identity used only for deployment propagation checks. */
     readonly frontendRevision?: string;
+    /** Served frontend paths the bundler content-addressed; absent means none may be cached forever. */
+    readonly frontendImmutable?: readonly string[];
     /** Load the exact Runtime and Build once, after the isolate has accepted a request. */
     readonly load: () => CloudflareWorkerSource<RuntimeValue, Material> | Promise<CloudflareWorkerSource<RuntimeValue, Material>>;
     readonly privateKey: JsonWebKey | ((bindings: Bindings) => JsonWebKey);

package/dist/worker/entry.js

@@ -87,13 +87,13 @@ function createCloudflareWorkerEntry(restore) {
                 }
                 currentPublicUrl = publicUrl;
                 if (config.frontend !== undefined) {
-                    const frontend = await frontendAsset(config.frontend, bindings.ASSETS, url, request, config.frontendRevision);
+                    const frontend = await frontendAsset(config.frontend, bindings.ASSETS, url, request, config.frontendRevision, config.frontendImmutable);
                     if (frontend !== undefined)
                         return withProviderVersion(frontend, bindings);
                 }
                 const { application, build } = await realize();
                 if (config.frontend === undefined) {
-                    const frontend = await frontendAsset(build.frontend, bindings.ASSETS, url, request, config.frontendRevision);
+                    const frontend = await frontendAsset(build.frontend, bindings.ASSETS, url, request, config.frontendRevision, config.frontendImmutable);
                     if (frontend !== undefined)
                         return withProviderVersion(frontend, bindings);
                 }

package/dist/worker/frontend.d.ts

@@ -1,4 +1,4 @@
 import type { BuildMaterial } from '@astrale-os/sdk/deployment/build/material';
 import type { Fetcher } from './entry.js';
 /** Serve public frontend files without realizing the Application's execution Runtime. */
-export declare function frontendAsset(frontend: BuildMaterial['frontend'], assets: Fetcher | undefined, url: URL, request: Request, revision?: string): Promise<Response | undefined>;
+export declare function frontendAsset(frontend: BuildMaterial['frontend'], assets: Fetcher | undefined, url: URL, request: Request, revision?: string, immutable?: readonly string[]): Promise<Response | undefined>;

package/dist/worker/frontend.js

@@ -1,5 +1,5 @@
 /** Serve public frontend files without realizing the Application's execution Runtime. */
-export async function frontendAsset(frontend, assets, url, request, revision) {
+export async function frontendAsset(frontend, assets, url, request, revision, immutable) {
     if (frontend === undefined || frontend.source.kind === 'external')
         return undefined;
     if (reserved(url.pathname) || (request.method !== 'GET' && request.method !== 'HEAD')) {
@@ -18,16 +18,32 @@ export async function frontendAsset(frontend, assets, url, request, revision) {
         return undefined;
     if (route === undefined) {
         const response = await assets.fetch(request);
-        return assetPath || response.status !== 404 ? publicAsset(response, revision) : undefined;
+        return assetPath || response.status !== 404
+            ? publicAsset(response, revision, cacheForever(url, immutable))
+            : undefined;
     }
     if (route.path !== url.pathname) {
         const response = await assets.fetch(request);
         if (response.status !== 404)
-            return publicAsset(response, revision);
+            return publicAsset(response, revision, cacheForever(url, immutable));
     }
-    return publicAsset(await assets.fetch(new Request(new URL(`/${route.document}${url.search}`, url.origin), request)), revision);
+    // A route serves its document, never the requested path, so the document decides: it is named by
+    // the route rather than by its bytes, and `publicAsset` already refuses to retain it.
+    return publicAsset(await assets.fetch(new Request(new URL(`/${route.document}${url.search}`, url.origin), request)), revision, false);
 }
-function publicAsset(response, revision) {
+/**
+ * Whether this exact served path is one the build content-addressed.
+ *
+ * The set is evidence from the bundler that named the file, not an inference from where it sits: a
+ * path under the bundle's own directory may still have been copied there verbatim from `public/`,
+ * and a content-addressed output may sit anywhere the project's configuration puts it.
+ */
+function cacheForever(url, immutable) {
+    if (immutable === undefined || immutable.length === 0)
+        return false;
+    return immutable.includes(decodeURIComponent(url.pathname).replace(/^\//u, ''));
+}
+function publicAsset(response, revision, immutable) {
     // Plain Views have an opaque sandbox origin. Their modules, CSS and fonts still need
     // public reads; this neither enables credentials nor changes execution endpoint CORS.
     const readable = new Response(response.body, response);
@@ -39,6 +55,12 @@ function publicAsset(response, revision) {
     if (!response.ok || response.headers.get('Content-Type')?.split(';')[0] === 'text/html') {
         readable.headers.set('Cache-Control', 'no-store');
     }
+    else if (immutable) {
+        // The bytes behind this name can never change, so a revalidation could only ever confirm what
+        // the name already states. Anything not proved content-addressed keeps the platform default,
+        // which revalidates and is therefore never wrong, only slower.
+        readable.headers.set('Cache-Control', 'public, max-age=31536000, immutable');
+    }
     return readable;
 }
 function reserved(path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/adapter-cloudflare",
-  "version": "0.5.0-beta.148",
+  "version": "0.5.0-beta.149",
   "description": "Deploy an Astrale application through Cloudflare Workers",
   "keywords": [
     "adapter",
@@ -53,7 +53,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@astrale-os/sdk": "0.5.0-beta.145",
+    "@astrale-os/sdk": "0.5.0-beta.146",
     "@noble/hashes": "2.3.0",
     "hono": "^4.6.20",
     "jose": "^6.1.3",