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

package/dist/build/artifact.js

@@ -29,9 +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);
-        // `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` stays the served file list every branch below already reads; `addressed` rides
+        // alongside it into the Worker, where it decides which of those files a browser may retain.
+        const { files: frontend, addressed } = await frontendFiles({
             frontend: context.build.frontend,
             projectDir: context.projectDir,
             output: join(directory, 'frontend'),
@@ -47,7 +47,7 @@ async function prepare(params, context, direct) {
             configuredIssuer,
             router,
             ...(frontend.length === 0 ? {} : { frontendRevision: frontendRevision(frontend) }),
-            ...(immutable.length === 0 ? {} : { frontendImmutable: immutable }),
+            ...(addressed.length === 0 ? {} : { frontendAddressed: addressed }),
         });
         const releaseConfig = generateWranglerConfig({
             workerName: name,

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

@@ -8,7 +8,7 @@ export interface FrontendOutput {
      * 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[];
+    readonly addressed: readonly string[];
 }
 export declare function frontendFiles(input: {
     readonly frontend: Build['frontend'];

package/dist/build/frontend/files.js

@@ -5,9 +5,9 @@ import { buildViteFrontend } from './vite.js';
 export async function frontendFiles(input) {
     const frontend = input.frontend;
     if (frontend === undefined)
-        return { files: [], immutable: [] };
+        return { files: [], addressed: [] };
     if (frontend.source.kind === 'external') {
-        return { files: frontendBuild.files(frontend, []), immutable: [] };
+        return { files: frontendBuild.files(frontend, []), addressed: [] };
     }
     await rm(input.output, { recursive: true, force: true });
     const built = await buildViteFrontend({
@@ -21,7 +21,7 @@ export async function frontendFiles(input) {
     // 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)) };
+    return { files, addressed: built.addressed.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

@@ -10,5 +10,5 @@ export declare function buildViteFrontend(input: {
     readonly recordSource?: (path: string) => void;
     readonly signal: AbortSignal;
 }): Promise<{
-    readonly immutable: readonly string[];
+    readonly addressed: readonly string[];
 }>;

package/dist/build/frontend/vite.js

@@ -26,11 +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')) {
+        const named = JSON.parse(await readFile(addressed, 'utf8'));
+        if (!Array.isArray(named) || named.some((path) => typeof path !== 'string')) {
             throw new TypeError('Vite preparation output evidence is invalid.');
         }
-        return { immutable: Object.freeze([...immutable]) };
+        return { addressed: Object.freeze([...named]) };
     }
     finally {
         await rm(scratch, { recursive: true, force: true });

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

@@ -19,7 +19,7 @@ async function main() {
     const projectDir = process.cwd();
     const vite = await projectVite(projectDir);
     const sources = new Set();
-    const immutable = new Set();
+    const named = new Set();
     let publicDir = false;
     let environment = {
         directory: false,
@@ -47,13 +47,13 @@ async function main() {
                         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.
+                // is safe to retain 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);
+                            named.add(fileName);
                     }
                 },
             },
@@ -67,16 +67,23 @@ async function main() {
         await collectTree(publicDir, sources);
     await writeFile(evidence, JSON.stringify([...sources]));
     if (addressed !== undefined)
-        await writeFile(addressed, JSON.stringify([...immutable].sort()));
+        await writeFile(addressed, JSON.stringify([...named].sort()));
 }
 /**
- * Whether this output's name carries a content hash, read from the template the bundler resolved.
+ * Whether this output's name carries a content hash.
  *
- * 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.
+ * Two facts are required, and each is necessary. The output must carry a `name`, which the bundler
+ * sets only for the outputs it named itself: a plugin emitting an explicit `fileName` bypasses the
+ * template entirely, and such a file can sit anywhere, including beside the bundle's own output. And
+ * the template that was applied must embed `[hash]`, since a project is free to strip it.
+ *
+ * Anything else leaves the answer unknown, and unknown must read as "not content-addressed": losing
+ * the optimization costs a revalidation, while claiming it wrongly serves a stale file for as long
+ * as the header says, with no way to recall it.
  */
 function addressedName(options, entry) {
+    if (typeof entry.name !== 'string')
+        return false;
     const template = entry.type === 'asset'
         ? options.assetFileNames
         : entry.isEntry === true

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

@@ -6,7 +6,7 @@ export interface ExecutionCodegenOptions {
     readonly workerSpecifier?: string;
     readonly build: Build;
     readonly frontendRevision?: string;
-    readonly frontendImmutable?: readonly string[];
+    readonly frontendAddressed?: 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`}${options.frontendImmutable === undefined ? '' : `  frontendImmutable: ${JSON.stringify(options.frontendImmutable)},\n`}  load: async () => ({
+${frontend}${options.frontendRevision === undefined ? '' : `  frontendRevision: ${JSON.stringify(options.frontendRevision)},\n`}${options.frontendAddressed === undefined ? '' : `  frontendAddressed: ${JSON.stringify(options.frontendAddressed)},\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,7 +10,7 @@ export declare function prepareExecution(input: {
     readonly name: string;
     readonly direct: boolean;
     readonly frontendRevision?: string;
-    readonly frontendImmutable?: readonly string[];
+    readonly frontendAddressed?: readonly string[];
     readonly configuredIssuer?: string;
     readonly router: ReturnType<typeof resolveRouter>;
 }): Promise<{

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

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

package/dist/worker/entry.d.ts

@@ -20,8 +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[];
+    /** Served frontend paths the bundler content-addressed; absent means none may be retained. */
+    readonly frontendAddressed?: 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, config.frontendImmutable);
+                    const frontend = await frontendAsset(config.frontend, bindings.ASSETS, url, request, config.frontendRevision, config.frontendAddressed);
                     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, config.frontendImmutable);
+                    const frontend = await frontendAsset(build.frontend, bindings.ASSETS, url, request, config.frontendRevision, config.frontendAddressed);
                     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, immutable?: readonly string[]): Promise<Response | undefined>;
+export declare function frontendAsset(frontend: BuildMaterial['frontend'], assets: Fetcher | undefined, url: URL, request: Request, revision?: string, addressed?: 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, immutable) {
+export async function frontendAsset(frontend, assets, url, request, revision, addressed) {
     if (frontend === undefined || frontend.source.kind === 'external')
         return undefined;
     if (reserved(url.pathname) || (request.method !== 'GET' && request.method !== 'HEAD')) {
@@ -19,13 +19,13 @@ export async function frontendAsset(frontend, assets, url, request, revision, im
     if (route === undefined) {
         const response = await assets.fetch(request);
         return assetPath || response.status !== 404
-            ? publicAsset(response, revision, cacheForever(url, immutable))
+            ? publicAsset(response, revision, retainable(url, addressed))
             : undefined;
     }
     if (route.path !== url.pathname) {
         const response = await assets.fetch(request);
         if (response.status !== 404)
-            return publicAsset(response, revision, cacheForever(url, immutable));
+            return publicAsset(response, revision, retainable(url, addressed));
     }
     // 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.
@@ -38,12 +38,12 @@ export async function frontendAsset(frontend, assets, url, request, revision, im
  * 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)
+function retainable(url, addressed) {
+    if (addressed === undefined || addressed.length === 0)
         return false;
-    return immutable.includes(decodeURIComponent(url.pathname).replace(/^\//u, ''));
+    return addressed.includes(decodeURIComponent(url.pathname).replace(/^\//u, ''));
 }
-function publicAsset(response, revision, immutable) {
+function publicAsset(response, revision, addressed) {
     // 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);
@@ -51,15 +51,22 @@ function publicAsset(response, revision, immutable) {
         readable.headers.set('Access-Control-Allow-Origin', '*');
     if (revision !== undefined)
         readable.headers.set('X-Astrale-Frontend', revision);
+    // A 304 states that the copy the browser already holds is current. Answering it with `no-store`
+    // would tell that browser to discard what it was just told to keep, so the next visit downloads
+    // the file again and every revalidation costs a full transfer: worse than never caching at all.
+    const validated = response.status === 304;
     // Documents select hashed assets. Do not retain stale documents or transient asset misses.
-    if (!response.ok || response.headers.get('Content-Type')?.split(';')[0] === 'text/html') {
+    if ((!response.ok && !validated) ||
+        response.headers.get('Content-Type')?.split(';')[0] === 'text/html') {
         readable.headers.set('Cache-Control', 'no-store');
     }
-    else if (immutable) {
+    else if (addressed) {
         // 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');
+        // the name already states. `immutable` is deliberately absent: it would also suppress the
+        // revalidation a reload performs, which is the one remedy a reader has if this were ever
+        // claimed wrongly. 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');
     }
     return readable;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/adapter-cloudflare",
-  "version": "0.5.0-beta.149",
+  "version": "0.5.0-beta.150",
   "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.146",
+    "@astrale-os/sdk": "0.5.0-beta.147",
     "@noble/hashes": "2.3.0",
     "hono": "^4.6.20",
     "jose": "^6.1.3",