mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:00:07 +00:00
* fix(cli): a preview's session follows HYPERFRAMES_CACHE_DIR when it is set * docs(cli): background previews follow HYPERFRAMES_CACHE_DIR * test(cli): unstub the preview test's env in a block body * test(cli): clear HYPERFRAMES_CACHE_DIR in the CLI's test home * fix(cli): registry cache, search model, catalog and catch-up follow HYPERFRAMES_CACHE_DIR * style(cli): format the media search cache test * test(cli): compare the model path against an absolute cache folder on Windows too * fix(cli): both catalog readers treat an empty HYPERFRAMES_CATALOG_ARTIFACT_DIR as unset
467 lines
18 KiB
TypeScript
467 lines
18 KiB
TypeScript
import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
import type { MockInstance } from "vitest";
|
|
import { mkdtempSync, rmSync, readdirSync, writeFileSync } from "node:fs";
|
|
import { tmpdir } from "node:os";
|
|
import { join } from "node:path";
|
|
|
|
// The cache lives under homedir(), so the whole suite runs against a scratch
|
|
// home rather than the developer's own ~/.hyperframes.
|
|
const scratchHome = mkdtempSync(join(tmpdir(), "hf-remote-"));
|
|
vi.mock("node:os", async (importOriginal) => ({
|
|
...(await importOriginal<typeof import("node:os")>()),
|
|
homedir: () => scratchHome,
|
|
}));
|
|
|
|
const {
|
|
assetSourceUrl,
|
|
fetchItemFile,
|
|
fetchItemManifest,
|
|
fetchRegistryManifest,
|
|
readRegistryManifest,
|
|
DEFAULT_REGISTRY_URL,
|
|
} = await import("./remote.js");
|
|
|
|
const MANIFEST = {
|
|
name: "hyperframes",
|
|
homepage: "https://hyperframes.heygen.com",
|
|
items: [{ name: "count-up", type: "hyperframes:component" }],
|
|
};
|
|
const ITEM = {
|
|
name: "count-up",
|
|
type: "hyperframes:component",
|
|
title: "Count up",
|
|
description: "Counter",
|
|
files: [{ path: "count.html", target: "count.html", type: "hyperframes:snippet" }],
|
|
};
|
|
|
|
const ONE_DAY_MS = 24 * 60 * 60 * 1000;
|
|
|
|
function ok(body: unknown): Response {
|
|
return new Response(JSON.stringify(body));
|
|
}
|
|
|
|
/**
|
|
* Prime the cache with one good fetch, then jump past the 24h TTL with every
|
|
* later fetch failing: the exact shape of "the registry host stopped answering
|
|
* and the copy on disk is a day old". Returns the failing spy so a caller can
|
|
* assert the network was actually attempted — without that the fallback
|
|
* assertions pass even if the clock never moved.
|
|
*/
|
|
async function staleAfterPriming(
|
|
body: unknown,
|
|
prime: () => Promise<unknown>,
|
|
): Promise<MockInstance<typeof fetch>> {
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(body));
|
|
await prime();
|
|
|
|
vi.useFakeTimers({ shouldAdvanceTime: true });
|
|
vi.setSystemTime(new Date(Date.now() + ONE_DAY_MS + 60_000));
|
|
return vi
|
|
.spyOn(globalThis, "fetch")
|
|
.mockClear()
|
|
.mockRejectedValue(new Error("The operation was aborted"));
|
|
}
|
|
|
|
beforeEach(() => {
|
|
rmSync(join(scratchHome, ".hyperframes"), { recursive: true, force: true });
|
|
vi.restoreAllMocks();
|
|
vi.useRealTimers();
|
|
});
|
|
|
|
afterEach(() => {
|
|
vi.useRealTimers();
|
|
});
|
|
|
|
afterAll(() => {
|
|
rmSync(scratchHome, { recursive: true, force: true });
|
|
});
|
|
|
|
describe("readRegistryManifest", () => {
|
|
it("throws why when the registry host cannot be reached and nothing is cached", async () => {
|
|
vi.spyOn(globalThis, "fetch").mockRejectedValue(
|
|
Object.assign(new TypeError("fetch failed"), {
|
|
cause: Object.assign(new Error("getaddrinfo ENOTFOUND raw.githubusercontent.com"), {
|
|
code: "ENOTFOUND",
|
|
}),
|
|
}),
|
|
);
|
|
await expect(readRegistryManifest(DEFAULT_REGISTRY_URL)).rejects.toThrow(
|
|
"The registry could not be read: fetch failed (getaddrinfo ENOTFOUND raw.githubusercontent.com)",
|
|
);
|
|
});
|
|
});
|
|
|
|
describe("fetchRegistryManifest", () => {
|
|
it("caches manifests under HYPERFRAMES_CACHE_DIR when it is set", async () => {
|
|
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
|
|
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
|
|
try {
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(MANIFEST));
|
|
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
|
|
expect(readdirSync(join(cache, "registry"))).toHaveLength(1);
|
|
} finally {
|
|
vi.unstubAllEnvs();
|
|
rmSync(cache, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
it("rejects poisoned stale cache data instead of returning it on network failure", async () => {
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(MANIFEST));
|
|
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
|
|
const cache = join(scratchHome, ".hyperframes/cache");
|
|
const file = readdirSync(cache)[0]!;
|
|
writeFileSync(
|
|
join(cache, file),
|
|
JSON.stringify({
|
|
fetchedAt: 0,
|
|
data: { ...MANIFEST, items: [{ name: "../../outside", type: "hyperframes:component" }] },
|
|
}),
|
|
);
|
|
vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("offline"));
|
|
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL)).resolves.toBeUndefined();
|
|
});
|
|
it("serves a fresh cache without touching the network", async () => {
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(ok(MANIFEST));
|
|
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
|
|
expect(fetchSpy).toHaveBeenCalledTimes(1);
|
|
|
|
const second = await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
|
|
|
|
expect(second).toEqual(MANIFEST);
|
|
expect(fetchSpy).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it("serves the expired cache when the registry host times out", async () => {
|
|
// The failure this exists for: raw.githubusercontent.com stops answering,
|
|
// the entry is a day and a bit old, and before this fix the caller was
|
|
// told the whole catalog was unreachable while a usable copy sat on disk.
|
|
const fetchSpy = await staleAfterPriming(MANIFEST, () =>
|
|
fetchRegistryManifest(DEFAULT_REGISTRY_URL),
|
|
);
|
|
|
|
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL)).resolves.toEqual(MANIFEST);
|
|
expect(fetchSpy).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it("treats an empty cached payload as a miss rather than an answer", async () => {
|
|
// The callers test the entry, not the payload, so a file carrying a valid
|
|
// fetchedAt and a null body would otherwise short-circuit the fetch and be
|
|
// handed back as a manifest.
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(null));
|
|
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
|
|
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockClear().mockResolvedValue(ok(MANIFEST));
|
|
|
|
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL)).resolves.toEqual(MANIFEST);
|
|
expect(fetchSpy).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it("still reports unreachable when the network fails and nothing was cached", async () => {
|
|
vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("getaddrinfo ENOTFOUND"));
|
|
|
|
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL)).resolves.toBeUndefined();
|
|
});
|
|
|
|
it("falls back to the stale copy under skipCache too", async () => {
|
|
// skipCache asks for something newer. It has never meant "rather have
|
|
// nothing than this", so a failed revalidation must not empty the result.
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(MANIFEST));
|
|
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
|
|
|
|
vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("HTTP 503"));
|
|
|
|
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL, { skipCache: true })).resolves.toEqual(
|
|
MANIFEST,
|
|
);
|
|
});
|
|
|
|
it("prefers a successful refetch over the cached copy", async () => {
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(MANIFEST));
|
|
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
|
|
|
|
const fresher = {
|
|
...MANIFEST,
|
|
items: [
|
|
{ name: "count-up", type: "hyperframes:component" },
|
|
{ name: "push-in", type: "hyperframes:component" },
|
|
],
|
|
};
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValue(ok(fresher));
|
|
|
|
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL, { skipCache: true })).resolves.toEqual(
|
|
fresher,
|
|
);
|
|
});
|
|
});
|
|
|
|
describe("fetchItemManifest", () => {
|
|
it("refreshes a fresh item cache when skipCache is requested", async () => {
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
|
|
await fetchItemManifest("count-up", "hyperframes:component");
|
|
const updated = {
|
|
...ITEM,
|
|
title: "Updated counter",
|
|
files: [{ path: "updated.html", target: "updated.html", type: "hyperframes:snippet" }],
|
|
};
|
|
fetchSpy.mockResolvedValue(ok(updated)).mockClear();
|
|
|
|
await expect(
|
|
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
|
|
skipCache: true,
|
|
}),
|
|
).resolves.toEqual(updated);
|
|
expect(fetchSpy).toHaveBeenCalledOnce();
|
|
await expect(fetchItemManifest("count-up", "hyperframes:component")).resolves.toEqual(updated);
|
|
expect(fetchSpy).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("keeps using a fresh item cache without skipCache", async () => {
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
|
|
await fetchItemManifest("count-up", "hyperframes:component");
|
|
fetchSpy.mockResolvedValue(ok({ ...ITEM, title: "Updated counter" })).mockClear();
|
|
|
|
await expect(fetchItemManifest("count-up", "hyperframes:component")).resolves.toEqual(ITEM);
|
|
expect(fetchSpy).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it.each([0, ONE_DAY_MS + 60_000])(
|
|
"keeps refresh requests offline in cache-only mode with cache age %d",
|
|
async (age) => {
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
|
|
await fetchItemManifest("count-up", "hyperframes:component");
|
|
vi.useFakeTimers();
|
|
vi.setSystemTime(new Date(Date.now() + age));
|
|
fetchSpy.mockRejectedValue(new Error("offline")).mockClear();
|
|
|
|
await expect(
|
|
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
|
|
skipCache: true,
|
|
cacheOnly: true,
|
|
}),
|
|
).resolves.toEqual(ITEM);
|
|
expect(fetchSpy).not.toHaveBeenCalled();
|
|
},
|
|
);
|
|
|
|
it("does not refresh an uncached item in cache-only mode", async () => {
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(ok(ITEM));
|
|
|
|
await expect(
|
|
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
|
|
skipCache: true,
|
|
cacheOnly: true,
|
|
}),
|
|
).rejects.toThrow("not fetched after an earlier registry timeout");
|
|
expect(fetchSpy).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("serves the cached item when a forced refresh fails", async () => {
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
|
|
await fetchItemManifest("count-up", "hyperframes:component");
|
|
fetchSpy.mockRejectedValue(new Error("HTTP 503")).mockClear();
|
|
|
|
await expect(
|
|
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
|
|
skipCache: true,
|
|
}),
|
|
).resolves.toEqual(ITEM);
|
|
expect(fetchSpy).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("keeps a valid cached item when a forced refresh returns invalid data", async () => {
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
|
|
await fetchItemManifest("count-up", "hyperframes:component");
|
|
fetchSpy.mockResolvedValue(ok({ ...ITEM, name: "different-item" })).mockClear();
|
|
|
|
await expect(
|
|
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
|
|
skipCache: true,
|
|
}),
|
|
).resolves.toEqual(ITEM);
|
|
expect(fetchSpy).toHaveBeenCalledOnce();
|
|
await expect(fetchItemManifest("count-up", "hyperframes:component")).resolves.toEqual(ITEM);
|
|
expect(fetchSpy).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("rejects a cache escape name before fetching", async () => {
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch");
|
|
await expect(
|
|
fetchItemManifest("x/../../../.config/tool", "hyperframes:component"),
|
|
).rejects.toThrow(/Invalid registry item/);
|
|
expect(fetchSpy).not.toHaveBeenCalled();
|
|
});
|
|
it("rejects a response for a different requested item", async () => {
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValue(ok(ITEM));
|
|
await expect(fetchItemManifest("other", "hyperframes:component")).rejects.toThrow(
|
|
/Invalid registry manifest/,
|
|
);
|
|
});
|
|
it("cancels oversized manifest responses without materializing their bodies", async () => {
|
|
const cancel = vi.fn();
|
|
const response = new Response(new ReadableStream({ cancel }), {
|
|
headers: { "content-length": "20000000" },
|
|
});
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValue(response);
|
|
await expect(fetchItemManifest("count-up", "hyperframes:component")).rejects.toThrow(
|
|
/download limit/,
|
|
);
|
|
expect(cancel).toHaveBeenCalledOnce();
|
|
});
|
|
it("serves the expired cache when the item fetch fails", async () => {
|
|
const fetchSpy = await staleAfterPriming(ITEM, () =>
|
|
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL),
|
|
);
|
|
|
|
await expect(
|
|
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL),
|
|
).resolves.toEqual(ITEM);
|
|
expect(fetchSpy).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it("still throws when the item fetch fails and nothing was cached", async () => {
|
|
// The documented contract for a genuinely unknown item, unchanged: callers
|
|
// that install by name have to be able to tell "offline" from "no such item".
|
|
vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("The operation was aborted"));
|
|
|
|
await expect(
|
|
fetchItemManifest("never-fetched", "hyperframes:component", DEFAULT_REGISTRY_URL),
|
|
).rejects.toThrow("The operation was aborted");
|
|
});
|
|
|
|
it("surfaces an HTTP error for an item that does not exist", async () => {
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValue({
|
|
ok: false,
|
|
status: 404,
|
|
json: async () => ({}),
|
|
} as unknown as Response);
|
|
|
|
await expect(
|
|
fetchItemManifest("no-such-move", "hyperframes:component", DEFAULT_REGISTRY_URL),
|
|
).rejects.toThrow("HTTP 404");
|
|
});
|
|
});
|
|
|
|
describe("assetSourceUrl", () => {
|
|
const item = { name: "carousel-orbit-1", type: "hyperframes:block" } as never;
|
|
|
|
it("resolves a plain file against the registry base", () => {
|
|
const file = { path: "carousel-orbit-1.html" } as never;
|
|
|
|
expect(assetSourceUrl(item, file, "https://registry.example")).toBe(
|
|
"https://registry.example/blocks/carousel-orbit-1/carousel-orbit-1.html",
|
|
);
|
|
});
|
|
|
|
it("fetches a hosted asset from its own URL, not from the registry base", () => {
|
|
// The bug this guards: joining the base to an absolute URL yields
|
|
// "https://registry.example/blocks/…/https://cdn.example/…", which 404s
|
|
// with a message no reader can act on.
|
|
const file = {
|
|
path: "assets/carousel-images/one.jpg",
|
|
url: "https://cdn.example/registry-assets/deadbeefdeadbeef.jpg",
|
|
} as never;
|
|
|
|
expect(assetSourceUrl(item, file, "https://registry.example")).toBe(
|
|
"https://cdn.example/registry-assets/deadbeefdeadbeef.jpg",
|
|
);
|
|
});
|
|
|
|
it("refuses a url that is not absolute https, rather than silently mis-joining it", () => {
|
|
const file = { path: "assets/one.jpg", url: "http://cdn.example/one.jpg" } as never;
|
|
|
|
expect(() => assetSourceUrl(item, file, "https://registry.example")).toThrow(
|
|
/must be an absolute https:\/\/ URL/,
|
|
);
|
|
});
|
|
});
|
|
|
|
describe("bounded registry file downloads", () => {
|
|
it.each([undefined, "1"])(
|
|
"cancels bodies exceeding the shared budget despite length %s",
|
|
async (length) => {
|
|
const cancel = vi.fn();
|
|
vi.spyOn(globalThis, "fetch").mockResolvedValue(
|
|
new Response(
|
|
new ReadableStream({
|
|
pull(controller) {
|
|
controller.enqueue(new Uint8Array(4));
|
|
},
|
|
cancel,
|
|
}),
|
|
{ headers: length ? { "content-length": length } : {} },
|
|
),
|
|
);
|
|
const budget = { remainingBytes: 5 };
|
|
await expect(
|
|
fetchItemFile(ITEM as never, ITEM.files[0] as never, DEFAULT_REGISTRY_URL, budget),
|
|
).rejects.toThrow(/budget/);
|
|
expect(budget.remainingBytes).toBe(0);
|
|
expect(cancel).toHaveBeenCalledOnce();
|
|
},
|
|
);
|
|
it("shares the byte budget across concurrent files", async () => {
|
|
vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("12345678"));
|
|
const budget = { remainingBytes: 10 };
|
|
const outcomes = await Promise.allSettled(
|
|
[1, 2].map(() =>
|
|
fetchItemFile(ITEM as never, ITEM.files[0] as never, DEFAULT_REGISTRY_URL, budget),
|
|
),
|
|
);
|
|
expect(outcomes.filter((result) => result.status === "fulfilled")).toHaveLength(1);
|
|
expect(budget.remainingBytes).toBe(0);
|
|
});
|
|
});
|
|
|
|
describe("fetchItemFile retries", () => {
|
|
const item = { name: "blur-in", type: "hyperframes:component" } as never;
|
|
const file = { path: "blur-in.html", target: "compositions/components/blur-in.html" } as never;
|
|
|
|
it("recovers from a transient blip instead of failing the whole install", async () => {
|
|
// Item files are the one uncached path, so a single blip used to kill the
|
|
// command outright. Two cheap retries is a better trade than that.
|
|
const fetchSpy = vi
|
|
.spyOn(globalThis, "fetch")
|
|
.mockRejectedValueOnce(new Error("fetch failed", { cause: new Error("ECONNRESET") }))
|
|
.mockResolvedValueOnce(new Response("<div>ok</div>"));
|
|
|
|
await expect(fetchItemFile(item, file, DEFAULT_REGISTRY_URL)).resolves.toEqual(
|
|
Buffer.from("<div>ok</div>"),
|
|
);
|
|
expect(fetchSpy).toHaveBeenCalledTimes(2);
|
|
});
|
|
|
|
it("does not retry a certificate failure, which fails identically every time", async () => {
|
|
// The reported case: a private registry with a self-signed certificate.
|
|
// Retrying only makes the user wait three times as long for one answer.
|
|
const fetchSpy = vi.spyOn(globalThis, "fetch").mockRejectedValue(
|
|
new Error("fetch failed", {
|
|
cause: new Error("self-signed certificate in certificate chain"),
|
|
}),
|
|
);
|
|
|
|
await expect(fetchItemFile(item, file, DEFAULT_REGISTRY_URL)).rejects.toThrow(
|
|
/self-signed certificate/,
|
|
);
|
|
expect(fetchSpy).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it("names the URL it could not reach", async () => {
|
|
vi.spyOn(globalThis, "fetch").mockRejectedValue(
|
|
new Error("fetch failed", { cause: new Error("self-signed certificate in chain") }),
|
|
);
|
|
|
|
await expect(fetchItemFile(item, file, "https://private.example/registry")).rejects.toThrow(
|
|
/https:\/\/private\.example\/registry\/components\/blur-in\/blur-in\.html/,
|
|
);
|
|
});
|
|
|
|
it("gives up after a bounded number of attempts", async () => {
|
|
const fetchSpy = vi
|
|
.spyOn(globalThis, "fetch")
|
|
.mockRejectedValue(new Error("fetch failed", { cause: new Error("ECONNRESET") }));
|
|
|
|
await expect(fetchItemFile(item, file, DEFAULT_REGISTRY_URL)).rejects.toThrow();
|
|
expect(fetchSpy).toHaveBeenCalledTimes(3);
|
|
});
|
|
});
|