@antelopejs/dms-frontend 0.6.3 → 0.7.0

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/module-server.mjs

@@ -49,15 +49,33 @@ function readJsonFile(url, fallback) {
   }
 }
 
-/** Sets `value` at `path` when the object holding it exists but lacks it. */
-function fillPath(target, path, value) {
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** The object holding `path`'s last key, when every key up to it is own. */
+function holderOf(target, path) {
   let node = target;
   for (const key of path.slice(0, -1)) {
-    if (typeof node[key] !== "object" || node[key] === null) return;
+    if (UNSAFE_KEYS.has(key) || !Object.hasOwn(node, key)) return undefined;
     node = node[key];
+    if (typeof node !== "object" || node === null) return undefined;
   }
+  return UNSAFE_KEYS.has(path.at(-1)) ? undefined : node;
+}
+
+/** Sets `value` at `path` when the object holding it exists but lacks it. */
+function fillPath(target, path, value) {
+  const holder = holderOf(target, path);
+  const key = path.at(-1);
+  if (holder && (holder[key] === undefined || holder[key] === ""))
+    holder[key] = value;
+}
+
+/** Sets `value` at `path` only where the build left an empty string. */
+function fillEmptied(target, path, value) {
+  const holder = holderOf(target, path);
   const key = path.at(-1);
-  if (typeof node[key] !== "string" || node[key] === "") node[key] = value;
+  if (holder && Object.hasOwn(holder, key) && holder[key] === "")
+    holder[key] = value;
 }
 
 /**
@@ -77,12 +95,56 @@ export function privateOptionsWithFallbacks(modules, environment, env) {
   return modules;
 }
 
+/** Each string leaf of `value`, array items included, with its path. */
+function* stringLeaves(value, path = []) {
+  if (typeof value === "string") yield [path, value];
+  else if (typeof value === "object" && value !== null)
+    for (const [key, child] of Object.entries(value))
+      yield* stringLeaves(child, [...path, key]);
+}
+
+/**
+ * Fills the private values a build left empty from `DMS_PRIVATE_OPTIONS`, a
+ * JSON object of private options by module id
+ * (`{"acme__shop-frontend-vue":{"apiKey":"…"}}`): any module's secrets, where
+ * `DMS_HTML_RENDER_SECRET` and `DMS_OAUTH_RELAY_SECRET` name two of them. Only
+ * a value the build emptied is filled, array items included: a value the
+ * manifest carries wins, and no option or section is added or replaced.
+ *
+ * @param modules The private options by module id
+ * @param json The variable's value; nothing is filled when unset
+ * @param warn Reports a value that is not a JSON object, never its content
+ */
+export function privateOptionsFromJson(modules, json, warn) {
+  if (!json) return modules;
+  let given;
+  try {
+    given = JSON.parse(json);
+  } catch {
+    given = undefined;
+  }
+  if (typeof given !== "object" || given === null || Array.isArray(given)) {
+    warn("DMS_PRIVATE_OPTIONS is not a JSON object of options by module id");
+    return modules;
+  }
+  for (const [id, options] of Object.entries(given)) {
+    if (UNSAFE_KEYS.has(id) || !Object.hasOwn(modules, id)) continue;
+    for (const [path, value] of stringLeaves(options))
+      if (path.length > 0) fillEmptied(modules[id], path, value);
+  }
+  return modules;
+}
+
 function readPrivateOptions(env = process.env) {
   const { modules = {}, environment = {} } = readJsonFile(
     SERVER_OPTIONS_FILE,
     {},
   );
-  return privateOptionsWithFallbacks(modules, environment, env);
+  return privateOptionsFromJson(
+    privateOptionsWithFallbacks(modules, environment, env),
+    env.DMS_PRIVATE_OPTIONS,
+    (message) => console.warn(message),
+  );
 }
 
 function readPublicOptions() {

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);