@antelopejs/dms 0.5.1 → 0.5.3

package/frontend-vue/layers/dms-ui/app/utils/metadataRetry.ts

@@ -0,0 +1,47 @@
+// Retry policy for reading a stored file's metadata. A refused or missing file
+// will not come back by asking again, so only failures that can heal on their
+// own (network, 5xx, rate limiting) are retried, and with a capped backoff.
+
+interface FetchFailure {
+  statusCode?: number;
+  status?: number;
+}
+
+const RETRY_BASE_DELAY_MS = 1000;
+const RETRY_MAX_DELAY_MS = 30000;
+const CLIENT_ERROR_STATUS_MIN = 400;
+const CLIENT_ERROR_STATUS_MAX = 499;
+const TRANSIENT_CLIENT_STATUSES = new Set([408, 425, 429]);
+
+function failureStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const { statusCode, status } = error as FetchFailure;
+  return statusCode ?? status;
+}
+
+/**
+ * A 4xx (404 gone, 403 denied, 410…) is the server's final answer about this
+ * file; request timeouts and rate limiting are the exceptions that can heal.
+ */
+export function isDefinitiveMetadataFailure(error: unknown): boolean {
+  const status = failureStatus(error);
+  return (
+    status !== undefined &&
+    status >= CLIENT_ERROR_STATUS_MIN &&
+    status <= CLIENT_ERROR_STATUS_MAX &&
+    !TRANSIENT_CLIENT_STATUSES.has(status)
+  );
+}
+
+/**
+ * Delay before retrying after `failedAttempts` consecutive failures, or `null`
+ * when the failure is definitive and the read must not be retried.
+ */
+export function resolveMetadataRetryDelay(
+  error: unknown,
+  failedAttempts: number,
+): number | null {
+  if (isDefinitiveMetadataFailure(error)) return null;
+  const exponent = Math.max(failedAttempts - 1, 0);
+  return Math.min(RETRY_BASE_DELAY_MS * 2 ** exponent, RETRY_MAX_DELAY_MS);
+}

package/frontend-vue/layers/dms-ui/i18n/locales/ui-en-GB.json

@@ -223,7 +223,8 @@
         "uploaded_files": "Uploaded files",
         "rejected_title": "File not added",
         "rejected_size": "{name} exceeds the maximum size ({size})",
-        "rejected_type": "{name} is not an allowed file type"
+        "rejected_type": "{name} is not an allowed file type",
+        "file_unavailable": "File unavailable"
       },
       "image": {
         "add": "Add",
@@ -233,6 +234,7 @@
         "single_hint": "Single image",
         "formats_any": "Any image format",
         "upload_failed": "Upload failed",
+        "file_unavailable": "File unavailable",
         "retry": "Retry",
         "replace": "Replace",
         "delete": "Delete",

package/frontend-vue/layers/dms-ui/i18n/locales/ui-fr-FR.json

@@ -224,7 +224,8 @@
         "uploaded_files": "Fichiers téléversés",
         "rejected_title": "Fichier non ajouté",
         "rejected_size": "{name} dépasse la taille maximale ({size})",
-        "rejected_type": "{name} n'est pas un type de fichier autorisé"
+        "rejected_type": "{name} n'est pas un type de fichier autorisé",
+        "file_unavailable": "Fichier indisponible"
       },
       "image": {
         "add": "Ajouter",
@@ -234,6 +235,7 @@
         "single_hint": "Une seule image",
         "formats_any": "Tous formats d'image",
         "upload_failed": "Échec de l'envoi",
+        "file_unavailable": "Fichier indisponible",
         "retry": "Réessayer",
         "replace": "Remplacer",
         "delete": "Supprimer",

package/frontend-vue/tests/file-unavailable.test.ts

@@ -0,0 +1,107 @@
+// @vitest-environment jsdom
+import {
+  computed,
+  createApp,
+  defineComponent,
+  h,
+  inject,
+  onScopeDispose,
+  ref,
+  watch,
+  type App,
+} from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import File from "../layers/dms-ui/app/components/form/components/File.vue";
+
+const STORED_KEY = "files/profile/avatar.pdf";
+const authFetch = vi.fn();
+
+const passthrough = defineComponent({
+  inheritAttrs: false,
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("span", slots.default?.()),
+});
+
+function mountFile(): { app: App; container: HTMLElement } {
+  const app = createApp({
+    render: () => h(File, { modelValue: STORED_KEY }),
+  });
+  app.config.globalProperties.$t = (key: string) => key;
+  app.component("UFileUpload", passthrough);
+  app.component("ULink", passthrough);
+  app.component("UButton", defineComponent({ setup: () => () => h("button") }));
+  app.component(
+    "UIcon",
+    defineComponent({
+      props: ["name"],
+      setup: (props) => () => h("i", { "data-icon": props.name }),
+    }),
+  );
+  const container = document.createElement("div");
+  app.mount(container);
+  return { app, container };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.stubGlobal("ref", ref);
+  vi.stubGlobal("computed", computed);
+  vi.stubGlobal("watch", watch);
+  vi.stubGlobal("inject", inject);
+  vi.stubGlobal("onScopeDispose", onScopeDispose);
+  vi.stubGlobal("FORM_FIELD_LOADING_KEY", Symbol());
+  vi.stubGlobal("FORM_CONTENT_LANGUAGE_KEY", Symbol());
+  vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "x-content-language");
+  vi.stubGlobal("useAuthFetch", () => ({ $authFetch: authFetch }));
+  vi.stubGlobal("useUploadWithProgress", () => ({
+    uploadWithProgress: vi.fn(),
+  }));
+  vi.stubGlobal("useFormField", () => ({ emitFormChange: vi.fn() }));
+  vi.stubGlobal("useI18n", () => ({ t: (key: string) => key }));
+  vi.stubGlobal("useToast", () => ({ add: vi.fn() }));
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  vi.resetAllMocks();
+});
+
+it("marks a stored file whose metadata cannot be read as unavailable", async () => {
+  authFetch.mockRejectedValue(new Error("404"));
+  const { app, container } = mountFile();
+  await vi.advanceTimersByTimeAsync(0);
+
+  expect(container.textContent).toContain("dms.form.file.file_unavailable");
+  expect(
+    container.querySelector('[data-icon="i-lucide-file-check"]'),
+  ).toBeNull();
+  expect(
+    container.querySelector('[data-icon="i-lucide-alert-circle"]'),
+  ).not.toBeNull();
+  app.unmount();
+});
+
+it("clears the unavailable state once a retry reads the file", async () => {
+  authFetch.mockRejectedValueOnce(new Error("503")).mockResolvedValueOnce({
+    resourceKey: STORED_KEY,
+    filename: "avatar.pdf",
+    size: 2048,
+    mimetype: "application/pdf",
+    url: "https://example.test/avatar.pdf",
+  });
+  const { app, container } = mountFile();
+  await vi.advanceTimersByTimeAsync(0);
+  expect(container.textContent).toContain("dms.form.file.file_unavailable");
+
+  await vi.advanceTimersByTimeAsync(1000);
+
+  expect(container.textContent).not.toContain("dms.form.file.file_unavailable");
+  expect(container.textContent).toContain("avatar.pdf");
+  expect(
+    container.querySelector('[data-icon="i-lucide-file-check"]'),
+  ).not.toBeNull();
+  app.unmount();
+});

package/frontend-vue/tests/image-hydration-ids.test.ts

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+import {
+  computed,
+  createSSRApp,
+  defineComponent,
+  h,
+  inject,
+  onBeforeUnmount,
+  ref,
+  useId,
+  watch,
+  type App,
+} from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import Image from "../layers/dms-ui/app/components/form/components/Image.vue";
+
+const STORED_IMAGE = { key: "files/profile/cover.png", alt: "Cover" };
+
+const passthrough = defineComponent({
+  inheritAttrs: false,
+  setup:
+    (_, { slots }) =>
+    () =>
+      slots.default?.(),
+});
+
+function createImageApp(): App {
+  const app = createSSRApp({
+    render: () => h(Image, { modelValue: STORED_IMAGE }),
+  });
+  app.component("UButton", defineComponent({ setup: () => () => h("button") }));
+  app.component("UIcon", defineComponent({ setup: () => () => h("span") }));
+  app.component("UInput", defineComponent({ setup: () => () => h("input") }));
+  app.component("UTooltip", passthrough);
+  app.component("UModal", defineComponent({ setup: () => () => null }));
+  return app;
+}
+
+beforeEach(() => {
+  vi.stubGlobal("ref", ref);
+  vi.stubGlobal("computed", computed);
+  vi.stubGlobal("watch", watch);
+  vi.stubGlobal("inject", inject);
+  vi.stubGlobal("useId", useId);
+  vi.stubGlobal("onBeforeUnmount", onBeforeUnmount);
+  vi.stubGlobal("FORM_FIELD_LOADING_KEY", Symbol());
+  vi.stubGlobal("FORM_CONTENT_LANGUAGE_KEY", Symbol());
+  vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "x-content-language");
+  vi.stubGlobal("useAuthFetch", () => ({
+    $authFetch: () => new Promise(() => undefined),
+  }));
+  vi.stubGlobal("useUploadWithProgress", () => ({
+    uploadWithProgress: vi.fn(),
+  }));
+  vi.stubGlobal("useFormField", () => ({ emitFormChange: vi.fn() }));
+  vi.stubGlobal("useI18n", () => ({ t: (key: string) => key }));
+  vi.stubGlobal("useToast", () => ({ add: vi.fn() }));
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+it("hydrates a stored single image without an attribute mismatch", async () => {
+  const html = await renderToString(createImageApp());
+  const container = document.createElement("div");
+  container.innerHTML = html;
+  const warnings: string[] = [];
+  const app = createImageApp();
+  app.config.warnHandler = (message) => warnings.push(message);
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+
+  app.mount(container);
+
+  expect(warnings.filter((message) => message.includes("Hydration"))).toEqual(
+    [],
+  );
+  expect(consoleError).not.toHaveBeenCalledWith(
+    expect.stringContaining("Hydration"),
+  );
+  const label = container.querySelector("label")!;
+  expect(label.htmlFor).not.toBe("");
+  expect(container.querySelector("input:not([type])")!.id).toBe(label.htmlFor);
+  app.unmount();
+  consoleError.mockRestore();
+});

package/frontend-vue/tests/image-reference-preservation.test.ts

@@ -5,6 +5,7 @@ import {
   createSSRApp,
   defineComponent,
   effectScope,
+  getCurrentInstance,
   h,
   nextTick,
   onScopeDispose,
@@ -12,12 +13,17 @@ import {
   reactive,
   ref,
   watch,
+  useId,
   type EffectScope,
   type Ref,
 } from "vue";
 import { renderToString } from "vue/server-renderer";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
 import Image from "../layers/dms-ui/app/components/form/components/Image.vue";
+import {
+  isDefinitiveMetadataFailure,
+  resolveMetadataRetryDelay,
+} from "../layers/dms-ui/app/utils/metadataRetry";
 
 interface ImageValue {
   key: string;
@@ -90,11 +96,14 @@ beforeEach(() => {
         }),
   );
   vi.stubGlobal("defineProps", () => props);
+  vi.stubGlobal("isDefinitiveMetadataFailure", isDefinitiveMetadataFailure);
+  vi.stubGlobal("resolveMetadataRetryDelay", resolveMetadataRetryDelay);
   vi.stubGlobal("defineEmits", () => emit);
   vi.stubGlobal("ref", ref);
   vi.stubGlobal("computed", computed);
   vi.stubGlobal("watch", watch);
   vi.stubGlobal("inject", () => null);
+  vi.stubGlobal("useId", () => (getCurrentInstance() ? useId() : "image"));
   vi.stubGlobal("FORM_FIELD_LOADING_KEY", Symbol());
   vi.stubGlobal("FORM_CONTENT_LANGUAGE_KEY", Symbol());
   vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "x-content-language");
@@ -117,7 +126,7 @@ afterEach(() => {
 it("preserves a denied image when another image is removed", async () => {
   const image = loadImage();
   await nextTick();
-  expect(image.items.value[0]!.status).toBe("error");
+  expect(image.items.value[0]!.status).toBe("unavailable");
   image.removeItem(image.items.value[1]!.id);
   expect(emit).toHaveBeenLastCalledWith("update:modelValue", [original]);
 });
@@ -191,7 +200,8 @@ it("keeps the denied image and its explicit deletion control in rendered markup"
   );
   app.component("UModal", defineComponent({ setup: () => () => null }));
   const html = await renderToString(app);
-  expect(html).toContain("dms.form.image.upload_failed");
+  expect(html).toContain("dms.form.image.file_unavailable");
+  expect(html).not.toContain("dms.form.image.upload_failed");
   expect(html).toContain("dms.form.image.delete</button>");
   expect(emit).not.toHaveBeenCalled();
 });

package/frontend-vue/tests/metadata-retry.test.ts

@@ -0,0 +1,187 @@
+// @vitest-environment jsdom
+import {
+  type App,
+  type Component,
+  computed,
+  createApp,
+  type FunctionalComponent,
+  h,
+  inject,
+  onBeforeUnmount,
+  onScopeDispose,
+  ref,
+  useId,
+  watch,
+} from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import File from "../layers/dms-ui/app/components/form/components/File.vue";
+import Image from "../layers/dms-ui/app/components/form/components/Image.vue";
+import {
+  isDefinitiveMetadataFailure,
+  resolveMetadataRetryDelay,
+} from "../layers/dms-ui/app/utils/metadataRetry";
+
+const authFetch = vi.fn();
+const LONG_WAIT_MS = 120000;
+
+interface FieldCase {
+  name: string;
+  component: Component;
+  modelValue: unknown;
+  unavailableLabel: string;
+  metadata: Record<string, unknown>;
+}
+
+const FIELD_CASES: FieldCase[] = [
+  {
+    name: "File",
+    component: File,
+    modelValue: "files/profile/avatar.pdf",
+    unavailableLabel: "dms.form.file.file_unavailable",
+    metadata: {
+      resourceKey: "files/profile/avatar.pdf",
+      filename: "avatar.pdf",
+      size: 2048,
+      mimetype: "application/pdf",
+      url: "https://example.test/avatar.pdf",
+    },
+  },
+  {
+    name: "Image",
+    component: Image,
+    modelValue: { key: "files/profile/cover.png", alt: "Cover" },
+    unavailableLabel: "dms.form.image.file_unavailable",
+    metadata: {
+      resourceKey: "files/profile/cover.png",
+      filename: "cover.png",
+      size: 2048,
+      mimetype: "image/png",
+      url: "https://example.test/cover.png",
+    },
+  },
+];
+
+const passthrough: FunctionalComponent = (_, { slots }) =>
+  h("span", slots.default?.());
+
+const renderTag =
+  (tag: string): FunctionalComponent =>
+  () =>
+    h(tag);
+
+function httpError(status: number): Error {
+  return Object.assign(new Error(`HTTP ${status}`), {
+    status,
+    statusCode: status,
+  });
+}
+
+function mountField(field: FieldCase): { app: App; container: HTMLElement } {
+  const app = createApp({
+    render: () => h(field.component, { modelValue: field.modelValue }),
+  });
+  app.config.globalProperties.$t = (key: string) => key;
+  for (const name of ["UFileUpload", "ULink", "UTooltip"])
+    app.component(name, passthrough);
+  app.component("UButton", renderTag("button"));
+  app.component("UIcon", renderTag("i"));
+  app.component("UInput", renderTag("input"));
+  app.component("UModal", () => null);
+  const container = document.createElement("div");
+  app.mount(container);
+  return { app, container };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.stubGlobal("ref", ref);
+  vi.stubGlobal("computed", computed);
+  vi.stubGlobal("watch", watch);
+  vi.stubGlobal("inject", inject);
+  vi.stubGlobal("useId", useId);
+  vi.stubGlobal("onBeforeUnmount", onBeforeUnmount);
+  vi.stubGlobal("onScopeDispose", onScopeDispose);
+  vi.stubGlobal("FORM_FIELD_LOADING_KEY", Symbol());
+  vi.stubGlobal("FORM_CONTENT_LANGUAGE_KEY", Symbol());
+  vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "x-content-language");
+  vi.stubGlobal("useAuthFetch", () => ({ $authFetch: authFetch }));
+  vi.stubGlobal("useUploadWithProgress", () => ({
+    uploadWithProgress: vi.fn(),
+  }));
+  vi.stubGlobal("useFormField", () => ({ emitFormChange: vi.fn() }));
+  vi.stubGlobal("useI18n", () => ({ t: (key: string) => key }));
+  vi.stubGlobal("useToast", () => ({ add: vi.fn() }));
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  vi.resetAllMocks();
+});
+
+describe.each(FIELD_CASES)("$name stored-value metadata", (field) => {
+  it.each([403, 404, 410])(
+    "reads a file answered with %i exactly once and shows it unavailable",
+    async (status) => {
+      authFetch.mockRejectedValue(httpError(status));
+      const { app, container } = mountField(field);
+
+      await vi.advanceTimersByTimeAsync(LONG_WAIT_MS);
+
+      expect(authFetch).toHaveBeenCalledTimes(1);
+      expect(container.textContent).toContain(field.unavailableLabel);
+      app.unmount();
+    },
+  );
+
+  it("retries transient failures with a growing delay until the read succeeds", async () => {
+    authFetch
+      .mockRejectedValueOnce(httpError(503))
+      .mockRejectedValueOnce(new Error("network down"))
+      .mockRejectedValueOnce(httpError(429))
+      .mockResolvedValueOnce(field.metadata);
+    const { app, container } = mountField(field);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(authFetch).toHaveBeenCalledTimes(1);
+    expect(container.textContent).toContain(field.unavailableLabel);
+
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(authFetch).toHaveBeenCalledTimes(2);
+    await vi.advanceTimersByTimeAsync(1999);
+    expect(authFetch).toHaveBeenCalledTimes(2);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(authFetch).toHaveBeenCalledTimes(3);
+    await vi.advanceTimersByTimeAsync(4000);
+    expect(authFetch).toHaveBeenCalledTimes(4);
+
+    expect(container.textContent).not.toContain(field.unavailableLabel);
+    await vi.advanceTimersByTimeAsync(LONG_WAIT_MS);
+    expect(authFetch).toHaveBeenCalledTimes(4);
+    app.unmount();
+  });
+});
+
+describe("metadata retry policy", () => {
+  it("treats refusals and missing files as definitive", () => {
+    for (const status of [400, 401, 403, 404, 410])
+      expect(isDefinitiveMetadataFailure(httpError(status))).toBe(true);
+    for (const error of [
+      httpError(408),
+      httpError(429),
+      httpError(500),
+      httpError(503),
+      new Error("network down"),
+      undefined,
+    ])
+      expect(isDefinitiveMetadataFailure(error)).toBe(false);
+  });
+
+  it("backs off exponentially up to a cap and never retries a definitive failure", () => {
+    const transient = httpError(503);
+    expect(resolveMetadataRetryDelay(transient, 1)).toBe(1000);
+    expect(resolveMetadataRetryDelay(transient, 2)).toBe(2000);
+    expect(resolveMetadataRetryDelay(transient, 3)).toBe(4000);
+    expect(resolveMetadataRetryDelay(transient, 50)).toBe(30000);
+    expect(resolveMetadataRetryDelay(httpError(404), 1)).toBeNull();
+  });
+});