@antelopejs/dms-frontend 0.6.2 → 0.6.4

package/dist/commands/start-action.js

@@ -11,6 +11,19 @@ const server_process_1 = require("../server-process");
 const update_check_1 = require("../update-check");
 const module_set_1 = require("../module-set");
 const BUILD_TIME_MANIFEST = "the build-time manifest";
+const PRODUCTION = "production";
+function serverNodeEnv() {
+    const nodeEnv = process.env.NODE_ENV || PRODUCTION;
+    if (nodeEnv !== PRODUCTION) {
+        const ui = (0, cli_1.getProcessUi)();
+        ui.message("warn", `NODE_ENV is ${nodeEnv}: the server renders with the development builds of Vue and its libraries`, {
+            details: [
+                `${ui.symbols.levels.hint} Unset it for start, or set it to ${PRODUCTION}`,
+            ],
+        });
+    }
+    return nodeEnv;
+}
 async function runStart(options) {
     const startedAt = Date.now();
     const backendUrl = (0, common_1.requireBackendUrl)(options.backendUrl);
@@ -46,6 +59,7 @@ async function runStart(options) {
     const secrets = (0, common_1.resolveManifestSecrets)((0, common_1.collectManifestSecrets)((0, common_1.readCachedManifest)(workspaceDir)?.manifest.modules ?? []));
     (0, common_1.reportManifestSecrets)(secrets, (count) => `Set ${count === 1 ? "it" : "them"}, or rebuild with DMS_BOOTSTRAP_SECRET so the manifest carries ${count === 1 ? "it" : "them"}`);
     const secretSources = (0, common_1.describeSecretSources)(secrets.sources, BUILD_TIME_MANIFEST);
+    const nodeEnv = serverNodeEnv();
     await reserved.release();
     const code = await (0, server_process_1.runServer)({
         name: "production server",
@@ -53,6 +67,7 @@ async function runStart(options) {
         cwd: workspaceDir,
         env: {
             ...process.env,
+            NODE_ENV: nodeEnv,
             PORT: String(port),
             DMS_API_BASE_URL: backendUrl,
             DMS_SESSION_SECRET: sessionSecret,

package/dist/help.js

@@ -24,6 +24,10 @@ exports.ENVIRONMENT_VARIABLES = [
         "DMS_COOKIE_SECURE",
         "Secure cookies unless false (default: false in dev, true in start)",
     ],
+    [
+        "NODE_ENV",
+        "Build of Vue and its libraries the server loads (default: development in dev, production in start)",
+    ],
     [
         "DMS_TRUSTED_PROXY_HOPS",
         "Trusted reverse-proxy hops, counted from the right (default: 0)",
@@ -52,6 +56,10 @@ exports.ENVIRONMENT_VARIABLES = [
         "DMS_BACKEND_PROXIES",
         "More backend prefixes the server proxies, as a JSON array of { path, auth? }",
     ],
+    [
+        "DMS_BACKEND_WAKE_BUDGET_MS",
+        "How long a GET or HEAD waits out a backend's cold-start 503, in ms (default: 30000; 0: never)",
+    ],
     ["DMS_CLIENT_BASE_URL", "Public frontend URL used in links and e-mails"],
     ["NO_COLOR", "Same as --no-color"],
     ["ANTELOPEJS_VERBOSE", "Same as --verbose"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
@@ -80,8 +80,8 @@
     "unzipper": "^0.12.3"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.13.2",
-    "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
+    "@antelopejs/core": "^1.16.0",
+    "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
     "@iconify/utils": "^3.1.0",
     "@iconify/vue": "^5.0.1",
     "@inertiajs/vue3": "^3.7.1",
@@ -109,7 +109,7 @@
     "vue-i18n": "^11.2.7"
   },
   "peerDependencies": {
-    "@antelopejs/core": ">=1.13.2 <2"
+    "@antelopejs/core": ">=1.16.0 <2"
   },
   "optionalDependencies": {
     "@oxc-parser/binding-darwin-arm64": "^0.95.0",

package/templates/vue/frontend-module.ts

@@ -1070,9 +1070,11 @@ const warnedServerReads = new Set<string>();
 
 /**
  * Warns, in a development server render, about a backend read no async data
- * handler makes: an immediate watcher's, a setup's own `await $fetch`. The
- * server waits for it, but the page carries none of it, so the browser reads
- * it again and may hydrate with other data.
+ * handler makes: an immediate watcher's, a setup's own `await $fetch`, a
+ * middleware's. The server waits for it, but the page carries none of it, so
+ * the browser reads it again and may hydrate with other data. Code that hands
+ * the answer over itself (`useDmsState` with `transfer: true`) looks the same
+ * from here, so the message names that exception rather than guess.
  */
 function warnUntransferredRead(
   runtime: DmsFrontendRuntime,
@@ -1089,9 +1091,10 @@ function warnUntransferredRead(
   warnedServerReads.add(request);
   console.warn(
     `DMS: ${request} was read during a server render outside useDmsFetch and useDmsAsyncData ` +
-      "(an immediate watcher, a setup's own await): the page does not carry the answer, " +
-      "so the browser reads it again. Load it with useDmsFetch or useDmsAsyncData, " +
-      "or leave it to the browser (server: false, onMounted).",
+      "(an immediate watcher, a setup's own await, a middleware): unless the code hands the " +
+      "answer over (useDmsState with transfer: true), the page does not carry it and the " +
+      "browser reads it again. Load it with useDmsFetch or useDmsAsyncData, in a middleware " +
+      "or a plugin too, or leave it to the browser (server: false, onMounted).",
   );
 }
 

package/templates/vue/server/backend-response.mjs

@@ -4,6 +4,7 @@
 // allows.
 
 import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
+import { isColdStart } from "./backend-wake.mjs";
 import { isFrontendVisit, redirectFrontendVisit } from "./inertia.mjs";
 
 // What a JSON caller gets when the backend fails: the generic i18n key of the
@@ -19,10 +20,13 @@ const FORBIDDEN = 403;
 const FRONTEND_ORIGIN = "http://frontend.local";
 
 export class BackendResponseError extends Error {
-  constructor(status, code) {
+  constructor(status, code, retryAfter) {
     super(`DMS backend returned ${status}`);
     this.status = status;
     this.code = code;
+    // Set only for a cold-start answer, so the visitor is told when to try
+    // again instead of getting an opaque failure.
+    this.retryAfter = retryAfter;
   }
 }
 
@@ -43,7 +47,14 @@ async function refusalCode(response) {
 
 /** The error for a failed backend response, with its typed code if any. */
 export async function backendResponseError(response) {
-  return new BackendResponseError(response.status, await refusalCode(response));
+  const retryAfter = isColdStart(response)
+    ? (response.headers.get("retry-after") ?? undefined)
+    : undefined;
+  return new BackendResponseError(
+    response.status,
+    await refusalCode(response),
+    retryAfter,
+  );
 }
 
 /**

package/templates/vue/server/backend-wake.mjs

@@ -0,0 +1,129 @@
+// Waiting out a backend the platform is waking from sleep.
+//
+// A platform that scales the backend to zero answers the first requests with
+// a 503 while it starts a replica, marked with the cold-start header and a
+// Retry-After in whole seconds: all three make the signal, and a 503 missing
+// one of them goes out as it came. The header is a reserved resume
+// convention, not a proof of where the answer came from: a backend may set it
+// too, and then gets the same bounded wait. Only a GET or a HEAD is repeated;
+// a POST, PATCH or DELETE is sent once.
+//
+// The wait starts with the first cold-start answer and lasts at most the
+// budget, the repeated requests included: one still waiting for its answer
+// when the budget runs out is aborted, and no request starts after it. It
+// ends at once when the client leaves.
+//
+// Lives apart from server.mjs so the file stays under the size the linter
+// allows.
+
+import { setTimeout as sleep } from "node:timers/promises";
+
+/** Header marking a 503 as a cold start to wait out. */
+export const COLD_START_HEADER = "x-antelope-cold-start";
+const COLD_START_VALUE = "1";
+const UNAVAILABLE = 503;
+const RETRYABLE_METHODS = new Set(["GET", "HEAD"]);
+const DEFAULT_BUDGET_MS = 30_000;
+const MIN_DELAY_MS = 1_000;
+// Repeats after the first request, so a GET is sent 16 times at most. They
+// are capped as well as the time, so a marked answer with `Retry-After: 0`
+// cannot multiply a GET.
+const MAX_REPEATS = 15;
+const MAX_DELAY_MS = 5_000;
+const MS_PER_SECOND = 1_000;
+const WHOLE_SECONDS = /^\d+$/;
+const WHOLE_MILLISECONDS = /^\d+$/;
+
+/** Whether `response` is a 503 marked as a cold start, with its Retry-After. */
+export function isColdStart(response) {
+  return (
+    response.status === UNAVAILABLE &&
+    response.headers.get(COLD_START_HEADER) === COLD_START_VALUE &&
+    WHOLE_SECONDS.test(retryAfter(response))
+  );
+}
+
+function retryAfter(response) {
+  return (response.headers.get("retry-after") ?? "").trim();
+}
+
+/**
+ * How long a request may wait for a waking backend, from
+ * DMS_BACKEND_WAKE_BUDGET_MS. 0 turns the wait off; anything but a whole
+ * number of milliseconds keeps the default.
+ */
+export function wakeBudgetMs(env = process.env) {
+  const raw = (env.DMS_BACKEND_WAKE_BUDGET_MS ?? "").trim();
+  return WHOLE_MILLISECONDS.test(raw) ? Number(raw) : DEFAULT_BUDGET_MS;
+}
+
+/** The pause a cold-start answer's Retry-After asks for, kept between bounds. */
+function retryDelayMs(response) {
+  return Math.min(
+    MAX_DELAY_MS,
+    Math.max(MIN_DELAY_MS, Number(retryAfter(response)) * MS_PER_SECOND),
+  );
+}
+
+/**
+ * What the client gets once the budget is spent: the last cold-start answer's
+ * status and headers, without the body its pause already discarded.
+ */
+function expired(cold) {
+  return new Response(null, {
+    status: UNAVAILABLE,
+    headers: {
+      [COLD_START_HEADER]: COLD_START_VALUE,
+      "retry-after": retryAfter(cold),
+    },
+  });
+}
+
+/**
+ * Sends one repeat, aborted if no answer has come by `deadline`. Once the
+ * answer has come the deadline no longer applies, so a ready backend's body
+ * streams for as long as it needs; only the client leaving ends it.
+ * Resolves to undefined when the deadline aborted the request.
+ */
+async function repeat(url, init, deadline, now) {
+  const late = new AbortController();
+  const timer = setTimeout(() => late.abort(), Math.max(0, deadline - now()));
+  const signal = init.signal
+    ? AbortSignal.any([init.signal, late.signal])
+    : late.signal;
+  try {
+    return await fetch(url, { ...init, signal });
+  } catch (error) {
+    if (late.signal.aborted && !init.signal?.aborted) return undefined;
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * `fetch`, waiting out cold-start answers to a GET or a HEAD until `budgetMs`
+ * from the first of them is spent or MAX_REPEATS repeats are sent. Then the
+ * caller gets a cold-start 503 with its `Retry-After` to relay. The client
+ * leaving, through `init.signal`, ends the wait with its AbortError.
+ */
+export async function fetchWaking(
+  url,
+  init = {},
+  { budgetMs = wakeBudgetMs(), now = Date.now } = {},
+) {
+  const method = (init.method ?? "GET").toUpperCase();
+  let response = await fetch(url, init);
+  if (!RETRYABLE_METHODS.has(method)) return response;
+  const deadline = now() + budgetMs;
+  for (let repeats = 0; isColdStart(response); repeats += 1) {
+    const cold = response;
+    const delay = retryDelayMs(cold);
+    if (repeats >= MAX_REPEATS || now() + delay > deadline) return cold;
+    cold.body?.cancel().catch(() => {});
+    await sleep(delay, undefined, { signal: init.signal });
+    if (now() >= deadline) return expired(cold);
+    response = (await repeat(url, init, deadline, now)) ?? expired(cold);
+  }
+  return response;
+}

package/templates/vue/server.mjs

@@ -17,6 +17,7 @@ import {
   redirectAccessRefusal,
   UNEXPECTED_ERROR_BODY,
 } from "./server/backend-response.mjs";
+import { fetchWaking } from "./server/backend-wake.mjs";
 import { handleClientError } from "./server/client-error.mjs";
 import {
   reportListenError,
@@ -154,9 +155,10 @@ function serverComponentFetch(request) {
 }
 
 async function backendJson(path, request) {
-  const response = await fetch(new URL(path, process.env.DMS_API_BASE_URL), {
-    headers: backendHeaders(request),
-  });
+  const response = await fetchWaking(
+    new URL(path, process.env.DMS_API_BASE_URL),
+    { headers: backendHeaders(request), signal: request.dmsAbandoned },
+  );
   if (!response.ok) {
     throw await backendResponseError(response);
   }
@@ -211,7 +213,7 @@ async function proxy(request, response, backendProxy) {
   // answers: its stream, an SSE feed above all, then stayed open for good.
   const abandoned = new AbortController();
   response.once("close", () => abandoned.abort());
-  const upstream = await fetch(backendUrl(request.url), {
+  const upstream = await fetchWaking(backendUrl(request.url), {
     signal: abandoned.signal,
     method: request.method,
     headers: { ...backendHeaders(request, access), ...PLAIN_ANSWER_HEADERS },
@@ -330,6 +332,9 @@ async function writeBackendError(error, request, response) {
   if (await redirectAccessRefusal(error, request, response, loadRenderer))
     return;
   console.error("DMS backend request failed", error);
+  const retryHeaders = error?.retryAfter
+    ? { "retry-after": error.retryAfter }
+    : {};
   if (isFrontendVisit(request)) {
     const props = {
       path: pathname,
@@ -343,18 +348,24 @@ async function writeBackendError(error, request, response) {
         request,
         response,
         status,
-        inertiaHeaders(page.version),
+        { ...inertiaHeaders(page.version), ...retryHeaders },
         JSON.stringify(page),
       );
     }
     const { html } = await renderRequestHtml(page, request);
-    return writeContent(request, response, status, htmlHeaders(), html);
+    return writeContent(
+      request,
+      response,
+      status,
+      { ...htmlHeaders(), ...retryHeaders },
+      html,
+    );
   }
   const payload =
     error instanceof UpstreamError || error instanceof RequestBodyError
       ? { message: error.message }
       : UNEXPECTED_ERROR_BODY;
-  response.writeHead(status, { "content-type": JSON_TYPE });
+  response.writeHead(status, { "content-type": JSON_TYPE, ...retryHeaders });
   response.end(JSON.stringify(payload));
 }
 
@@ -476,7 +487,19 @@ async function writeRequestFailure(error, request, response) {
   await writeBackendError(error, request, response);
 }
 
+/**
+ * Aborted once the client is gone, ending a wait for a waking backend. An
+ * embedder's response that emits no events never aborts it.
+ */
+function abandonedSignal(response) {
+  const abandoned = new AbortController();
+  if (typeof response.once === "function")
+    response.once("close", () => abandoned.abort());
+  return abandoned.signal;
+}
+
 export async function handleRequestSafely(request, response) {
+  request.dmsAbandoned = abandonedSignal(response);
   try {
     if (refuseForeignTarget(request, response)) return;
     await handleRequest(request, response);