@antelopejs/dms-frontend 0.3.0 → 0.3.1

package/templates/vue/frontend-module.ts

@@ -17,6 +17,8 @@ import {
   type ComputedRef,
   computed,
   defineComponent,
+  type EffectScope,
+  effectScope,
   getCurrentInstance,
   getCurrentScope,
   h,
@@ -249,6 +251,12 @@ export interface DmsFrontendSdk {
     handler: DmsMiddleware,
     options?: DmsMiddlewareRegistrationOptions,
   ): void;
+  /**
+   * Sends a page visit the backend refuses with a typed 403 (its body is
+   * `code`) to `path` instead of the error page. The server answers with the
+   * redirect before anything renders, so a reload lands on `path` directly.
+   */
+  registerAccessRedirect(code: string, path: string): void;
   provide<T>(key: string | InjectionKey<T>, value: T): void;
   use(plugin: Plugin): void;
 }
@@ -309,6 +317,11 @@ export interface DmsFrontendRuntime {
   pageVersion: number;
   /** The `Cookie` header of the request a server runtime renders. */
   requestCookies?: string;
+  /**
+   * Owns the effects plugins create while they set up. A server render stops
+   * it once done: nothing else would, since a server app is never unmounted.
+   */
+  scope: EffectScope;
 }
 
 const components = new Map<string, DmsComponentRegistration>();
@@ -320,6 +333,7 @@ const plugins: Plugin[] = [];
 const pluginSetups: DmsPluginRegistration[] = [];
 const middleware: DmsMiddleware[] = [];
 const namedMiddleware = new Map<string, DmsMiddleware>();
+const accessRedirects = new Map<string, string>();
 const injections = new Map<string | symbol, unknown>();
 const runtimeConfig = ref<DmsRuntimeConfig>({
   public: {},
@@ -358,6 +372,7 @@ export function createDmsFrontendRuntime(
     }),
     hasNavigationListener: false,
     pageVersion: 0,
+    scope: effectScope(true),
   };
 }
 
@@ -539,10 +554,14 @@ export function useDmsRoute(pattern?: string): DmsRoute {
   runtime.currentRoutePattern = pattern;
   const page = usePage();
   updateRoute(runtime, page.url);
-  watch(
-    () => page.url,
-    (url) => updateRoute(runtime, url),
-  );
+  // A server render never changes its URL, and Inertia's page is shared by
+  // every render the process runs: a watcher there would only tie this
+  // request's runtime to all the requests after it.
+  if (!runtime.isServer)
+    watch(
+      () => page.url,
+      (url) => updateRoute(runtime, url),
+    );
   return runtime.route;
 }
 
@@ -1172,6 +1191,29 @@ export function trackDmsAsyncComponents(app: App): Set<string> {
   return rendered;
 }
 
+/**
+ * Records the scope of every component a server render creates, and returns
+ * the function that stops them once the render is over.
+ *
+ * A server app is never mounted, so it is never unmounted either: Vue leaves
+ * the scope of each component it rendered running, and nothing handed to
+ * `onScopeDispose` is ever released. Nuxt UI's `useRuntimeHook` registers in
+ * a process-wide hook registry and only unregisters there, so every server
+ * render of the dashboard sidebar stayed reachable, its whole component tree
+ * and page props with it, until the server ran out of heap.
+ */
+export function trackDmsServerScopes(app: App): () => void {
+  const scopes: EffectScope[] = [];
+  app.mixin({
+    beforeCreate(this: ComponentPublicInstance) {
+      scopes.push(this.$.scope);
+    },
+  });
+  return () => {
+    for (const scope of scopes.splice(0)) scope.stop();
+  };
+}
+
 export async function resolveDmsAsyncComponents(
   names: readonly string[],
 ): Promise<void> {
@@ -1252,6 +1294,10 @@ function findDmsPageEntry(props: DmsPageProps): DmsFrontendEntry | undefined {
     : dynamicPages.get(CATCH_ALL_PAGE_KEY);
 }
 
+/** The path a frontend module registered for a typed backend refusal. */
+export function resolveDmsAccessRedirect(code: string): string | undefined {
+  return accessRedirects.get(code);
+}
 export function hasDmsPage(name: string): boolean {
   return pages.has(normalizeDmsPageKey(name));
 }
@@ -1374,6 +1420,9 @@ function createSdk(options: DmsModuleOptions): DmsFrontendSdk {
       if (!namedMiddleware.has(name)) namedMiddleware.set(name, handler);
       if (options.global) middleware.push(handler);
     },
+    registerAccessRedirect: (code, path) => {
+      if (!accessRedirects.has(code)) accessRedirects.set(code, path);
+    },
     provide: (key, value) => {
       if (!injections.has(key)) injections.set(key, value);
     },
@@ -1459,7 +1508,9 @@ export async function installDmsPlugins(
   });
   for (const registration of pluginSetups) {
     if (registration.clientOnly && typeof window === "undefined") continue;
-    await app.runWithContext(() => registration.setup(appContext));
+    await runtime.scope.run(() =>
+      app.runWithContext(() => registration.setup(appContext)),
+    );
   }
   return async () => {
     for (const callback of hooks.get("app:mounted") ?? []) await callback();

package/templates/vue/gitignore

@@ -1,6 +1,15 @@
+# Translation catalogs are data, not markup, and Tailwind's automatic source
+# detection honors this file. A catalog it scans reloads the whole page when it
+# changes, where the dev server would otherwise apply the edited translations
+# in place.
+locales.generated/
+frontend-modules/**/i18n/locales/
 # Rewritten by the auto-import plugins while the dev server discovers new
 # components and composables. Tailwind's automatic source detection honors this
 # file: without it, every rewrite invalidates the stylesheets and triggers a
 # CSS hot update on plain navigation.
 auto-imports.d.ts
 components.d.ts
+# Build output, which the email bundle watcher rewrites during development:
+# read as Tailwind sources, each rebuild would push a burst of CSS updates.
+dist/

package/templates/vue/network-error.ts

@@ -0,0 +1,70 @@
+import { router } from "@inertiajs/vue3";
+
+export interface DmsNetworkErrorToast {
+  id: string;
+  title: string;
+  description: string;
+  color: "error";
+}
+
+export interface DmsNetworkErrorTranslator {
+  locale: { value: string };
+  t: (key: string) => string;
+  te: (key: string) => boolean;
+}
+
+const NETWORK_ERROR_TOAST_ID = "dms-network-error";
+const NETWORK_ERROR_KEY = "error.network";
+const DEFAULT_LOCALE = "en";
+// Shipped with the renderer, since no module is guaranteed to translate the
+// case; a module overrides them with `error.network.title` and
+// `error.network.description` in its own locale files.
+const NETWORK_ERROR_MESSAGES: Record<
+  string,
+  Record<"title" | "description", string>
+> = {
+  en: {
+    title: "Connection lost",
+    description:
+      "The server could not be reached. Check your connection and try again.",
+  },
+  fr: {
+    title: "Connexion perdue",
+    description:
+      "Le serveur est injoignable. Vérifiez votre connexion et réessayez.",
+  },
+};
+
+function networkErrorMessage(
+  i18n: DmsNetworkErrorTranslator,
+  name: "title" | "description",
+): string {
+  const key = `${NETWORK_ERROR_KEY}.${name}`;
+  if (i18n.te(key)) return i18n.t(key);
+  const locale = i18n.locale.value.slice(0, 2);
+  return (NETWORK_ERROR_MESSAGES[locale] ??
+    NETWORK_ERROR_MESSAGES[DEFAULT_LOCALE])[name];
+}
+
+/**
+ * Tell the visitor when an Inertia visit never reached the server, instead of
+ * leaving the click without effect and the failure as an uncaught rejection.
+ * The current page stays as it was, so they can retry once back online.
+ *
+ * @returns A function removing the listener
+ */
+export function showNetworkErrors(
+  notify: (toast: DmsNetworkErrorToast) => void,
+  i18n: DmsNetworkErrorTranslator,
+): () => void {
+  return router.on("networkError", (event) => {
+    event.preventDefault();
+    notify({
+      // One toast however many visits fail while the server is away.
+      id: NETWORK_ERROR_TOAST_ID,
+      title: networkErrorMessage(i18n, "title"),
+      description: networkErrorMessage(i18n, "description"),
+      color: "error",
+    });
+  });
+}

package/templates/vue/server/auth/backend.mjs

@@ -15,6 +15,9 @@ export class UpstreamError extends Error {
 }
 
 const PUBLIC_AUTH_MESSAGE = /^error\.[a-z0-9_.-]{1,100}$/;
+// The API error contract's generic key: the technical cause of a failure the
+// backend did not describe stays in the server log.
+export const GENERIC_ERROR_MESSAGE = "error.500.description";
 
 export function publicBackendMessage(data) {
   const message = typeof data === "string" ? data : data?.message;
@@ -47,8 +50,12 @@ export async function backend(path, request, options = {}) {
     data = response.ok ? {} : text;
   }
   if (!response.ok) {
-    const message = publicBackendMessage(data) ?? "DMS backend request failed";
-    throw new UpstreamError(response.status, message);
+    const message = publicBackendMessage(data);
+    if (!message)
+      console.error(
+        `DMS backend request failed: ${response.status} ${options.method ?? "GET"} ${path}`,
+      );
+    throw new UpstreamError(response.status, message ?? GENERIC_ERROR_MESSAGE);
   }
   return data;
 }

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

@@ -0,0 +1,85 @@
+// Reading a failed DMS backend response for the page a visitor gets instead.
+//
+// Lives apart from server.mjs so the file stays under the size the linter
+// allows.
+
+import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
+import { isFrontendVisit, redirectFrontendVisit } from "./inertia.mjs";
+
+// What a JSON caller gets when the backend fails: the generic i18n key of the
+// API error contract. A page gets the status code alone, which the DMS error
+// page describes in the visitor's language; the technical cause only reaches
+// the server log.
+export const UNEXPECTED_ERROR_BODY = { message: GENERIC_ERROR_MESSAGE };
+// A typed refusal carries a machine-readable i18n key as its body, bare or
+// JSON-encoded, e.g. `saas.errors.workspace.access_blocked`.
+const REFUSAL_CODE = /^[a-z0-9_-]+(?:\.[a-z0-9_-]+)+$/i;
+const REFUSAL_CODE_MAX_LENGTH = 200;
+const FORBIDDEN = 403;
+const FRONTEND_ORIGIN = "http://frontend.local";
+
+export class BackendResponseError extends Error {
+  constructor(status, code) {
+    super(`DMS backend returned ${status}`);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+async function refusalCode(response) {
+  const text = (await response.text().catch(() => "")).trim();
+  if (text.length > REFUSAL_CODE_MAX_LENGTH) return undefined;
+  let value = text;
+  try {
+    const data = JSON.parse(text);
+    value = typeof data === "string" ? data : data?.message;
+  } catch {
+    // A bare code.
+  }
+  return typeof value === "string" && REFUSAL_CODE.test(value)
+    ? value
+    : undefined;
+}
+
+/** 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));
+}
+
+/**
+ * Redirect a page visit the backend refused with a typed 403 (a suspended
+ * workspace, say) to the path a frontend module registered for its code
+ * through the SDK's `registerAccessRedirect`, looked up in the SSR renderer
+ * `loadRenderer` resolves. Only a same-origin path other than the refused one
+ * qualifies: a refused destination sent to itself again would loop.
+ *
+ * @returns Whether the visit was redirected
+ */
+export async function redirectAccessRefusal(
+  error,
+  request,
+  response,
+  loadRenderer,
+) {
+  if (
+    !isFrontendVisit(request) ||
+    !(error instanceof BackendResponseError) ||
+    error.status !== FORBIDDEN ||
+    !error.code
+  )
+    return false;
+  let location;
+  try {
+    location = (await loadRenderer()).accessRedirect?.(error.code);
+  } catch (rendererError) {
+    console.error("DMS access redirect lookup failed", rendererError);
+    return false;
+  }
+  if (!location) return false;
+  const target = new URL(location, FRONTEND_ORIGIN);
+  const refused = new URL(request.url, FRONTEND_ORIGIN);
+  if (target.origin !== FRONTEND_ORIGIN || target.pathname === refused.pathname)
+    return false;
+  redirectFrontendVisit(request, response, location);
+  return true;
+}

package/templates/vue/server/email-bundle-watch.mjs

@@ -0,0 +1,31 @@
+// Development-only email bundle builder, forked by the frontend server.
+//
+// Runs Vite's email build in watch mode so `dist/server` exists as soon as the
+// dev server does and follows every template edit the layer watchers mirror
+// into the workspace. It lives in its own process so its builds never hold the
+// dev server's event loop, and it reports each build over IPC so the server
+// renders from a finished bundle only.
+
+import { fileURLToPath } from "node:url";
+import { build } from "vite";
+
+const PROJECT_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+// The server owns this process: when its IPC channel closes, however the
+// server ended, there is nobody left to build for.
+process.on("disconnect", () => process.exit(0));
+
+const watcher = await build({
+  root: PROJECT_ROOT,
+  configFile: fileURLToPath(
+    new URL("../vite.email.config.ts", import.meta.url),
+  ),
+  logLevel: "warn",
+  build: { watch: {} },
+});
+
+watcher.on("event", (event) => {
+  if (event.code === "START") process.send?.({ state: "building" });
+  else if (event.code === "END") process.send?.({ state: "ready" });
+  else if (event.code === "ERROR") process.send?.({ state: "failed" });
+});

package/templates/vue/server/email.mjs

@@ -1,7 +1,82 @@
+import { fork } from "node:child_process";
+import { constants, setPriority } from "node:os";
+import { fileURLToPath } from "node:url";
 import { body } from "./auth/backend.mjs";
 import { validRenderToken } from "./render-token.mjs";
 
 const JSON_TYPE = "application/json";
+const EMAIL_RENDERER_URL = new URL(
+  "../dist/server/email-renderer.js",
+  import.meta.url,
+);
+const EMAIL_BUNDLE_WATCH_URL = new URL(
+  "./email-bundle-watch.mjs",
+  import.meta.url,
+);
+// A render waits this long for a build in progress, then tries the bundle
+// already on disk rather than holding the backend's request indefinitely.
+const EMAIL_BUILD_WAIT_MS = 60_000;
+
+// Settled whenever no email build is running. The version changes with each
+// finished build: Node caches an imported module by URL, so the renderer is
+// imported under a new one to pick up rebuilt templates.
+let emailBuild = Promise.resolve();
+let settleEmailBuild;
+let emailBundleVersion = 0;
+
+function emailBuildStarted() {
+  if (settleEmailBuild) return;
+  emailBuild = new Promise((settle) => {
+    settleEmailBuild = settle;
+  });
+}
+
+function emailBuildSettled() {
+  emailBundleVersion += 1;
+  settleEmailBuild?.();
+  settleEmailBuild = undefined;
+}
+
+/**
+ * Build the email bundle now and again on every template change, for
+ * development: only the production build otherwise produces it. The builder
+ * runs in a child process at low priority, so the dev server keeps answering
+ * while it works.
+ */
+export function watchEmailBundle() {
+  emailBuildStarted();
+  const builder = fork(fileURLToPath(EMAIL_BUNDLE_WATCH_URL), {
+    cwd: fileURLToPath(new URL("..", import.meta.url)),
+  });
+  try {
+    setPriority(builder.pid, constants.priority.PRIORITY_BELOW_NORMAL);
+  } catch {
+    // Not permitted on this platform; the build only runs at normal priority.
+  }
+  builder.on("message", (message) => {
+    if (message?.state === "building") emailBuildStarted();
+    else emailBuildSettled();
+  });
+  builder.on("exit", (code) => {
+    emailBuildSettled();
+    if (code) console.error(`DMS email bundle watcher exited with ${code}`);
+  });
+  return builder;
+}
+
+async function loadEmailRenderer() {
+  let timer;
+  await Promise.race([
+    emailBuild,
+    new Promise((settle) => {
+      timer = setTimeout(settle, EMAIL_BUILD_WAIT_MS);
+    }),
+  ]);
+  clearTimeout(timer);
+  const url = new URL(EMAIL_RENDERER_URL);
+  if (emailBundleVersion) url.searchParams.set("v", emailBundleVersion);
+  return import(url.href);
+}
 
 /** Renders an email template for an authenticated backend request. */
 export async function handleEmailRender(request, response) {
@@ -19,7 +94,7 @@ export async function handleEmailRender(request, response) {
     return response.end(JSON.stringify({ message: "Invalid request body" }));
   }
   try {
-    const { renderEmail } = await import("../dist/server/email-renderer.js");
+    const { renderEmail } = await loadEmailRenderer();
     const html = await renderEmail(input.templateName, input.props ?? {}, {
       locale: request.headers["x-content-language"],
     });

package/templates/vue/server/inertia.mjs

@@ -76,6 +76,15 @@ export function handleAssetVersionMismatch(request, response) {
   return true;
 }
 
+/** A page visit: a document or Inertia request, as opposed to an API call. */
+export function isFrontendVisit(request) {
+  if (request.method !== "GET") return false;
+  return (
+    Boolean(request.headers["x-inertia"]) ||
+    request.headers.accept?.includes("text/html")
+  );
+}
+
 export function redirectFrontendVisit(request, response, location) {
   const vary = { vary: "X-Inertia" };
   if (!request.headers["x-inertia"]) {

package/templates/vue/server/request-failure.mjs

@@ -0,0 +1,54 @@
+// Answers for requests the server cannot serve at all: an unreadable URL, or a
+// failure while it was already rendering the error page.
+//
+// Lives apart from server.mjs so the file stays under the size the linter
+// allows.
+
+const FRONTEND_ORIGIN = "http://frontend.local";
+const TEXT_TYPE = "text/plain; charset=utf-8";
+
+/**
+ * Whether the path of `url` holds a percent-escape no decoder accepts, such as
+ * `/projects/%E0%A4%A`. Vite and the router decode the path, and throw on it.
+ */
+export function hasMalformedPath(url) {
+  try {
+    decodeURI(new URL(url, FRONTEND_ORIGIN).pathname);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Whether a failed request can no longer be answered: the client went away, or
+ * the response already started.
+ */
+export function isResponseGone(error, response) {
+  return (
+    error?.code === "ERR_STREAM_PREMATURE_CLOSE" ||
+    response.destroyed ||
+    response.writableEnded ||
+    response.headersSent
+  );
+}
+
+export function writeBadRequest(response) {
+  response.writeHead(400, { "content-type": TEXT_TYPE });
+  response.end("Bad Request");
+}
+
+/**
+ * The last resort once even the error page failed: a bare 500, or a dropped
+ * connection when the response already started. The server keeps running
+ * either way.
+ */
+export function abandonResponse(error, response) {
+  console.error("DMS error response failed", error);
+  if (response.headersSent || response.writableEnded) {
+    response.destroy();
+    return;
+  }
+  response.writeHead(500, { "content-type": TEXT_TYPE });
+  response.end("Internal Server Error");
+}