@antelopejs/dms-frontend 0.7.0 → 0.7.1

package/dist/help.js

@@ -63,7 +63,7 @@ exports.ENVIRONMENT_VARIABLES = [
     ],
     [
         "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)",
+        "How long a GET or HEAD waits out a waking or starting backend's 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"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

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

@@ -4,7 +4,7 @@
 // allows.
 
 import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
-import { isColdStart } from "./backend-wake.mjs";
+import { isWaitable } 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
@@ -47,7 +47,7 @@ async function refusalCode(response) {
 
 /** The error for a failed backend response, with its typed code if any. */
 export async function backendResponseError(response) {
-  const retryAfter = isColdStart(response)
+  const retryAfter = isWaitable(response)
     ? (response.headers.get("retry-after") ?? undefined)
     : undefined;
   return new BackendResponseError(

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

@@ -1,14 +1,14 @@
-// Waiting out a backend the platform is waking from sleep.
+// Waiting out a backend that is waking from sleep or still starting.
 //
 // 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.
+// Retry-After in whole seconds; a DMS backend that listens before it is ready
+// answers 503 with a Retry-After too, without the header. A 503 with a
+// Retry-After in whole seconds is the signal, with or without the header; a
+// 503 without one goes out as it came. 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
+// The wait starts with the first waitable 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.
@@ -18,7 +18,7 @@
 
 import { setTimeout as sleep } from "node:timers/promises";
 
-/** Header marking a 503 as a cold start to wait out. */
+/** Header a platform marks the 503 of a backend it is waking with. */
 export const COLD_START_HEADER = "x-antelope-cold-start";
 const COLD_START_VALUE = "1";
 const UNAVAILABLE = 503;
@@ -34,12 +34,14 @@ 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) {
+/**
+ * Whether `response` is a 503 asking to come back after a Retry-After in
+ * whole seconds: a platform waking the backend (with the cold-start header)
+ * or a backend still starting.
+ */
+export function isWaitable(response) {
   return (
-    response.status === UNAVAILABLE &&
-    response.headers.get(COLD_START_HEADER) === COLD_START_VALUE &&
-    WHOLE_SECONDS.test(retryAfter(response))
+    response.status === UNAVAILABLE && WHOLE_SECONDS.test(retryAfter(response))
   );
 }
 
@@ -57,7 +59,7 @@ export function wakeBudgetMs(env = process.env) {
   return WHOLE_MILLISECONDS.test(raw) ? Number(raw) : DEFAULT_BUDGET_MS;
 }
 
-/** The pause a cold-start answer's Retry-After asks for, kept between bounds. */
+/** The pause a waitable answer's Retry-After asks for, kept between bounds. */
 function retryDelayMs(response) {
   return Math.min(
     MAX_DELAY_MS,
@@ -66,17 +68,15 @@ function retryDelayMs(response) {
 }
 
 /**
- * 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.
+ * What the client gets once the budget is spent: the last waitable answer's
+ * status, Retry-After and cold-start header if it had one, 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),
-    },
-  });
+  const headers = { "retry-after": retryAfter(cold) };
+  if (cold.headers.get(COLD_START_HEADER) === COLD_START_VALUE)
+    headers[COLD_START_HEADER] = COLD_START_VALUE;
+  return new Response(null, { status: UNAVAILABLE, headers });
 }
 
 /**
@@ -102,9 +102,9 @@ async function repeat(url, init, deadline, now) {
 }
 
 /**
- * `fetch`, waiting out cold-start answers to a GET or a HEAD until `budgetMs`
+ * `fetch`, waiting out waitable 503s 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
+ * caller gets the 503 with its `Retry-After` to relay. The client
  * leaving, through `init.signal`, ends the wait with its AbortError.
  */
 export async function fetchWaking(
@@ -116,7 +116,7 @@ export async function fetchWaking(
   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) {
+  for (let repeats = 0; isWaitable(response); repeats += 1) {
     const cold = response;
     const delay = retryDelayMs(cold);
     if (repeats >= MAX_REPEATS || now() + delay > deadline) return cold;