(saved);
const [fileDrop, setFileDrop] = useState(false);
const dragDepth = useRef(0);
const importRevision = useRef(0);
@@ -356,31 +425,86 @@ function App() {
message("cancelExperiment");
setExperiment({ running: false, progress: 0, error: "" });
};
- const localDocument = useMemo(() => {
- try {
- return {
- text: serializeWorkspace({
- board: { version: 1, nodes, edges, config, title, interview: brief },
- active: game.active,
- draft: game.draft,
- view: game.view,
- }),
- error: "",
- };
- } catch (error) {
- return {
- text: "",
- error:
- error instanceof Error
- ? error.message
- : "Check the board settings before saving.",
- };
- }
- }, [nodes, edges, config, title, brief, game.active, game.draft, game.view]);
+ const workspaceDraft = (): LocalWorkspace => ({
+ board: { version: 1, nodes, edges, config, title, interview: brief },
+ active: game.active,
+ draft: game.draft,
+ view: game.view,
+ revision: baseRevision.current,
+ });
+ const localDocument = useMemo(
+ () => ({
+ nodes,
+ edges,
+ config,
+ title,
+ brief,
+ active: game.active,
+ draft: game.draft,
+ view: game.view,
+ }),
+ [nodes, edges, config, title, brief, game.active, game.draft, game.view],
+ );
const writeLocal = useCallback(() => {
try {
- if (!localDocument.text) throw new Error(localDocument.error);
- localStorage.setItem("liveboard-v1", localDocument.text);
+ if (blockWrites.current) {
+ setSaveStatus("Not saved");
+ setSaveError(
+ "Download the unreadable workspace before replacing it.",
+ );
+ return false;
+ }
+ const nextText = serializeWorkspace(
+ workspaceDraft(),
+ previousWorkspace.current,
+ );
+ const stored = localStorage.getItem(WORKSPACE_KEY);
+ if (stored && workspaceBody(stored) === workspaceBody(nextText)) {
+ const revision = planWorkspaceWrite({
+ baseRevision: baseRevision.current,
+ storedText: stored,
+ nextText,
+ });
+ if (revision.action === "adopt") {
+ baseRevision.current = revision.revision;
+ lastBody.current = workspaceBody(stored);
+ setSaveStatus("Saved");
+ setSaveError("");
+ return true;
+ }
+ }
+ const decision = planWorkspaceWrite({
+ baseRevision: baseRevision.current,
+ storedText: stored,
+ nextText,
+ blockWrites: blockWrites.current,
+ });
+ if (decision.action === "adopt") {
+ baseRevision.current = decision.revision;
+ lastBody.current = workspaceBody(stored ?? nextText);
+ setSaveStatus("Saved");
+ setSaveError("");
+ return true;
+ }
+ if (decision.action === "conflict") {
+ setConflictText(decision.storedText);
+ setSaveStatus("Not saved");
+ setSaveError("A newer workspace is open in another tab.");
+ return false;
+ }
+ if (decision.action === "refuse") {
+ setSaveStatus("Not saved");
+ setSaveError(
+ decision.reason === "quarantine"
+ ? "Download the unreadable workspace before replacing it."
+ : "The saved workspace could not be read. Download it before replacing it.",
+ );
+ return false;
+ }
+ localStorage.setItem(WORKSPACE_KEY, decision.text);
+ baseRevision.current = decision.revision;
+ lastBody.current = workspaceBody(decision.text);
+ previousWorkspace.current = parseWorkspace(decision.text);
setSaveStatus("Saved");
setSaveError("");
return true;
@@ -395,13 +519,37 @@ function App() {
);
return false;
}
+ // workspaceDraft reads the latest render state captured by localDocument.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
}, [localDocument]);
useEffect(() => {
- if (localDocument.error) {
+ let text = "";
+ try {
+ text = serializeWorkspace(workspaceDraft(), previousWorkspace.current);
+ } catch (error) {
setSaveStatus("Not saved");
- setSaveError(localDocument.error);
+ setSaveError(
+ error instanceof Error
+ ? error.message
+ : "Check the board settings before saving.",
+ );
+ return;
+ }
+ const body = workspaceBody(text);
+ if (boot.status === "unreadable") {
+ if (bootBody.current === null) {
+ bootBody.current = body;
+ return;
+ }
+ if (body === bootBody.current) return;
+ }
+ if (echoing.current && workspaceContent(text) === echoContent.current) {
+ lastBody.current = body;
+ setSaveStatus("Saved");
+ setSaveError("");
return;
}
+ echoing.current = false;
setSaveStatus("Saving…");
const timer = setTimeout(writeLocal, 500);
const flush = () => {
@@ -418,6 +566,52 @@ function App() {
document.removeEventListener("visibilitychange", hidden);
};
}, [localDocument, writeLocal]);
+ useEffect(() => {
+ const onStorage = (event: StorageEvent) => {
+ if (event.key !== WORKSPACE_KEY || !event.newValue) return;
+ let remote: LocalWorkspace;
+ try {
+ remote = parseWorkspace(event.newValue);
+ } catch {
+ return;
+ }
+ const remoteBody = workspaceBody(event.newValue);
+ if (remote.revision !== undefined && remote.revision < baseRevision.current)
+ return;
+ if (remoteBody === lastBody.current) {
+ baseRevision.current = remote.revision ?? baseRevision.current;
+ return;
+ }
+ let localText = "";
+ try {
+ localText = serializeWorkspace(
+ sessionRef.current.draft(),
+ previousWorkspace.current,
+ );
+ } catch {
+ setConflictText(event.newValue);
+ return;
+ }
+ if (workspaceBody(localText) === lastBody.current) {
+ previousWorkspace.current = remote;
+ baseRevision.current = remote.revision ?? 0;
+ lastBody.current = remoteBody;
+ echoing.current = true;
+ echoContent.current = workspaceContent(event.newValue);
+ sessionRef.current.loadBoard(remote.board);
+ sessionRef.current.restore({
+ active: remote.active,
+ draft: remote.draft,
+ view: remote.view,
+ });
+ setConflictText("");
+ return;
+ }
+ setConflictText(event.newValue);
+ };
+ window.addEventListener("storage", onStorage);
+ return () => window.removeEventListener("storage", onStorage);
+ }, []);
const save = () => {
if (writeLocal()) setToast("Workspace saved in this browser");
};
@@ -457,7 +651,7 @@ function App() {
cache: { ...current.cache, technology: "redis" },
}));
};
- const loadBoard = (board: Board) => {
+ const loadBoard = (board: Board, briefOverride?: InterviewBrief) => {
setNodes(
board.nodes.map((node) => ({
...node,
@@ -472,7 +666,7 @@ function App() {
if (!board.nodes.length) {
setPanel("components");
}
- if (board.interview) setBrief(board.interview);
+ setBrief(briefForLoad(board, briefOverride));
setTitle(board.title);
setSelection(
board.nodes.find((n) => n.data.role === "balancer")?.id ??
@@ -487,6 +681,11 @@ function App() {
}),
);
};
+ sessionRef.current = {
+ loadBoard,
+ restore: game.restore,
+ draft: workspaceDraft,
+ };
const resetBoard = (kind: Scenario) => {
game.leave();
loadBoard(scenario(kind));
@@ -540,8 +739,14 @@ function App() {
}
};
const exportBoard = () => {
+ const current = workspaceDraft();
+ let text: string;
try {
- parseBoard(serializeBoard(boardDocument()));
+ text = serializeBoard(
+ parseWorkspace(
+ serializeWorkspace(current, previousWorkspace.current),
+ ).board,
+ );
} catch (error) {
setToast(
error instanceof Error
@@ -550,8 +755,12 @@ function App() {
);
return;
}
+ if (boardWasRepaired(current, previousWorkspace.current))
+ setToast(
+ "Downloaded the board. Unfinished fields kept their last valid values.",
+ );
const url = URL.createObjectURL(
- new Blob([serializeBoard(boardDocument())], { type: "application/json" }),
+ new Blob([text], { type: "application/json" }),
);
const a = document.createElement("a");
a.href = url;
@@ -600,6 +809,65 @@ function App() {
},
};
});
+ const canReplaceUnreadable = !blockWrites.current || recoveryDownloaded;
+ const downloadRecovery = () => {
+ if (!recoveryText) return;
+ downloadText("liveboard-unreadable.json", recoveryText);
+ setRecoveryDownloaded(true);
+ blockWrites.current = false;
+ };
+ const startFresh = () => {
+ if (!canReplaceUnreadable) return;
+ blockWrites.current = false;
+ lastBody.current = "";
+ if (writeLocal()) setSaveError("");
+ };
+ const discardSavedCopy = () => {
+ if (!recoveryDownloaded) return;
+ try {
+ discardRecovery(localStorage);
+ } catch {
+ /* Closing the notice is still useful if storage is blocked. */
+ }
+ setRecoveryText("");
+ };
+ const loadConflict = () => {
+ if (!conflictText) return;
+ try {
+ const remote = parseWorkspace(conflictText);
+ previousWorkspace.current = remote;
+ baseRevision.current = remote.revision ?? 0;
+ lastBody.current = workspaceBody(conflictText);
+ echoing.current = true;
+ echoContent.current = workspaceContent(conflictText);
+ loadBoard(remote.board);
+ game.restore({
+ active: remote.active,
+ draft: remote.draft,
+ view: remote.view,
+ });
+ setConflictText("");
+ setSaveStatus("Saved");
+ setSaveError("");
+ } catch (error) {
+ setSaveError(
+ error instanceof Error
+ ? error.message
+ : "The other tab's workspace could not be read.",
+ );
+ }
+ };
+ const keepConflict = () => {
+ if (!conflictText) return;
+ try {
+ baseRevision.current = parseWorkspace(conflictText).revision ?? 0;
+ } catch {
+ setSaveError("The other tab's workspace could not be read.");
+ return;
+ }
+ setConflictText("");
+ writeLocal();
+ };
return (
{
@@ -1223,12 +1491,16 @@ function App() {
onLoadBrief={(id) => {
const item = briefs.find((b) => b.id === id);
if (!item) return;
- loadBoard(scenario(item.scenario));
- setBrief({
- ...structuredClone(defaultBrief),
- prompt: item.prompt,
- requirements: item.requirements,
- });
+ const preset = scenario(item.scenario);
+ game.leave();
+ loadBoard(
+ preset,
+ briefForLoad(preset, {
+ ...structuredClone(defaultBrief),
+ prompt: item.prompt,
+ requirements: item.requirements,
+ }),
+ );
clock.reset(defaultBrief.minutes);
selectExecutionTab("Interview");
}}
@@ -1583,6 +1855,50 @@ function App() {
Board, exercise, or submission · JSON
)}
+ {recoveryText && (
+
+
+ {canReplaceUnreadable
+ ? "A copy is stored on this device. You can download it, start a new board, or keep editing. Discard the copy only after downloading it."
+ : "This tab will not replace the saved file until you download a copy."}
+
+
+
+ Download copy
+
+
+ Start fresh
+
+
+ Discard copy
+
+
+
+ )}
+ {conflictText && (
+
+
+ Saving now would replace that newer copy. Load it, or keep the
+ board open in this tab.
+
+
+
+ Load other tab
+
+
+ Keep this tab
+
+
+
+ )}
{toast && (
diff --git a/src/app/persistence.test.ts b/src/app/persistence.test.ts
new file mode 100644
index 0000000..9ccf2a1
--- /dev/null
+++ b/src/app/persistence.test.ts
@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import { scenario } from "../board/board";
+import {
+ parseWorkspace,
+ serializeWorkspace,
+ type LocalWorkspace,
+} from "./workspace";
+import {
+ RECOVERY_KEY,
+ RECOVERY_PREVIOUS_KEY,
+ WORKSPACE_KEY,
+ discardRecovery,
+ loadStoredWorkspace,
+ planWorkspaceWrite,
+ recoveryText,
+ workspaceContent,
+ type StorageLike,
+} from "./persistence";
+
+function memory(): StorageLike & { map: Map } {
+ const map = new Map();
+ return {
+ map,
+ getItem: (key) => map.get(key) ?? null,
+ setItem: (key, value) => map.set(key, value),
+ removeItem: (key) => map.delete(key),
+ };
+}
+function workspace(patch: Partial = {}): LocalWorkspace {
+ return {
+ board: scenario("cache"),
+ view: "gallery",
+ revision: 0,
+ ...patch,
+ };
+}
+
+describe("workspace persistence", () => {
+ it("does not rewrite an unchanged document or replace a newer tab", () => {
+ const stored = serializeWorkspace(workspace({ revision: 4 }));
+ expect(
+ planWorkspaceWrite({
+ baseRevision: 4,
+ storedText: stored,
+ nextText: serializeWorkspace(workspace({ revision: 4 })),
+ }),
+ ).toEqual({ action: "adopt", revision: 4 });
+ const newer = serializeWorkspace(
+ workspace({
+ revision: 5,
+ board: { ...scenario("cache"), title: "Other tab" },
+ }),
+ );
+ const conflict = planWorkspaceWrite({
+ baseRevision: 4,
+ storedText: newer,
+ nextText: serializeWorkspace(
+ workspace({
+ revision: 4,
+ board: { ...scenario("cache"), title: "This tab" },
+ }),
+ ),
+ });
+ expect(conflict).toMatchObject({ action: "conflict", storedRevision: 5 });
+ const kept = planWorkspaceWrite({
+ baseRevision: 5,
+ storedText: newer,
+ nextText: serializeWorkspace(
+ workspace({
+ revision: 5,
+ board: { ...scenario("cache"), title: "This tab" },
+ }),
+ ),
+ });
+ expect(kept.action).toBe("write");
+ if (kept.action === "write") {
+ expect(kept.revision).toBe(6);
+ expect(parseWorkspace(kept.text).board.title).toBe("This tab");
+ }
+ });
+ it("treats node movement as the same workspace content", () => {
+ const board = scenario("cache");
+ const moved = structuredClone(board);
+ moved.nodes[0].position = { x: 40, y: 80 };
+ expect(workspaceContent(serializeWorkspace(workspace({ board })))).toBe(
+ workspaceContent(serializeWorkspace(workspace({ board: moved }))),
+ );
+ });
+ it("adopts the same board saved by another tab without writing over it", () => {
+ const board = scenario("cache");
+ const stored = serializeWorkspace(workspace({ board, revision: 7 }));
+ expect(
+ planWorkspaceWrite({
+ baseRevision: 6,
+ storedText: stored,
+ nextText: serializeWorkspace(workspace({ board, revision: 6 })),
+ }),
+ ).toEqual({ action: "adopt", revision: 7 });
+ });
+ it("refuses to replace unreadable storage and keeps a recoverable copy", () => {
+ const store = memory();
+ store.setItem(WORKSPACE_KEY, "{");
+ const loaded = loadStoredWorkspace(store, 1000);
+ expect(loaded).toMatchObject({ status: "unreadable", preserved: true });
+ expect(store.getItem(WORKSPACE_KEY)).toBe("{");
+ expect(recoveryText(store.getItem(RECOVERY_KEY))).toBe("{");
+ const replaced = planWorkspaceWrite({
+ baseRevision: 0,
+ storedText: "{",
+ nextText: serializeWorkspace(workspace()),
+ });
+ expect(replaced.action).toBe("write");
+ if (replaced.action === "write") {
+ expect(replaced.revision).toBe(1);
+ expect(parseWorkspace(replaced.text).board.title).toBe("User profile API");
+ }
+ const blocked = memory();
+ blocked.setItem = () => {
+ throw new Error("quota");
+ };
+ blocked.map.set(WORKSPACE_KEY, "{not json");
+ const blockedLoad = loadStoredWorkspace(blocked);
+ expect(blockedLoad.status).toBe("unreadable");
+ if (blockedLoad.status === "unreadable")
+ expect(blockedLoad.preserved).toBe(false);
+ expect(
+ planWorkspaceWrite({
+ baseRevision: 0,
+ storedText: null,
+ nextText: serializeWorkspace(workspace()),
+ blockWrites: true,
+ }).action,
+ ).toBe("refuse");
+ });
+ it("keeps the previous recovery when a second unreadable document appears", () => {
+ const store = memory();
+ store.setItem(WORKSPACE_KEY, "{first");
+ expect(loadStoredWorkspace(store, 1).status).toBe("unreadable");
+ store.setItem(WORKSPACE_KEY, "{second");
+ expect(loadStoredWorkspace(store, 2).status).toBe("unreadable");
+ expect(recoveryText(store.getItem(RECOVERY_KEY))).toBe("{second");
+ expect(recoveryText(store.getItem(RECOVERY_PREVIOUS_KEY))).toBe("{first");
+ discardRecovery(store);
+ expect(store.getItem(RECOVERY_KEY)).toBeNull();
+ expect(store.getItem(RECOVERY_PREVIOUS_KEY)).toBeNull();
+ });
+ it("still loads a legacy board file stored before workspace revisions", () => {
+ const store = memory();
+ const board = scenario("balanced");
+ store.setItem(
+ WORKSPACE_KEY,
+ JSON.stringify(JSON.parse(serializeWorkspace(workspace({ board }))).board),
+ );
+ const loaded = loadStoredWorkspace(store);
+ expect(loaded.status).toBe("ok");
+ if (loaded.status === "ok")
+ expect(loaded.workspace.board.title).toBe(board.title);
+ });
+});
diff --git a/src/app/persistence.ts b/src/app/persistence.ts
new file mode 100644
index 0000000..ddf2385
--- /dev/null
+++ b/src/app/persistence.ts
@@ -0,0 +1,182 @@
+import { parseWorkspace, type LocalWorkspace } from "./workspace";
+
+export const WORKSPACE_KEY = "liveboard-v1";
+export const RECOVERY_KEY = "liveboard-v1-recovery";
+export const RECOVERY_PREVIOUS_KEY = "liveboard-v1-recovery-previous";
+
+export type StorageLike = {
+ getItem(key: string): string | null;
+ setItem(key: string, value: string): void;
+ removeItem(key: string): void;
+};
+
+export type LoadResult =
+ | { status: "empty" }
+ | { status: "ok"; workspace: LocalWorkspace; text: string }
+ | { status: "unreadable"; text: string; preserved: boolean };
+
+export type WritePlan =
+ | { action: "write"; text: string; revision: number }
+ | { action: "adopt"; revision: number }
+ | { action: "conflict"; storedText: string; storedRevision: number }
+ | { action: "refuse"; reason: "unreadable" | "quarantine" };
+
+function canonical(value: unknown): unknown {
+ if (Array.isArray(value)) return value.map(canonical);
+ if (value && typeof value === "object")
+ return Object.fromEntries(
+ Object.entries(value as Record)
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([key, item]) => [key, canonical(item)]),
+ );
+ return value;
+}
+export function workspaceBody(text: string): string {
+ try {
+ const raw = JSON.parse(text) as Record | null;
+ if (raw && typeof raw === "object" && !Array.isArray(raw))
+ delete raw.revision;
+ return JSON.stringify(canonical(raw));
+ } catch {
+ return text;
+ }
+}
+export function workspaceContent(text: string): string {
+ try {
+ const raw = JSON.parse(text) as {
+ revision?: number;
+ board?: { nodes?: { position?: unknown }[] };
+ };
+ delete raw.revision;
+ for (const node of raw.board?.nodes ?? []) delete node.position;
+ return JSON.stringify(canonical(raw));
+ } catch {
+ return text;
+ }
+}
+
+export function storedRevision(text: string | null): number | "unreadable" {
+ if (!text) return 0;
+ try {
+ const raw = JSON.parse(text) as Record | null;
+ if (!raw || typeof raw !== "object" || Array.isArray(raw))
+ return "unreadable";
+ if (raw.format !== "liveboard-workspace-v1") return 0;
+ if (raw.revision === undefined) return 0;
+ if (
+ typeof raw.revision === "number" &&
+ Number.isInteger(raw.revision) &&
+ raw.revision >= 0 &&
+ raw.revision <= Number.MAX_SAFE_INTEGER
+ )
+ return raw.revision;
+ return "unreadable";
+ } catch {
+ return "unreadable";
+ }
+}
+
+export function planWorkspaceWrite(input: {
+ baseRevision: number;
+ storedText: string | null;
+ nextText: string;
+ blockWrites?: boolean;
+}): WritePlan {
+ if (input.blockWrites) return { action: "refuse", reason: "quarantine" };
+ const revision = storedRevision(input.storedText);
+ if (revision === "unreadable") {
+ const raw = JSON.parse(input.nextText) as Record;
+ raw.revision = 1;
+ return { action: "write", text: JSON.stringify(raw), revision: 1 };
+ }
+ const nextBody = workspaceBody(input.nextText);
+ const storedBody = input.storedText ? workspaceBody(input.storedText) : "";
+ if (input.storedText && revision > input.baseRevision) {
+ if (storedBody === nextBody) return { action: "adopt", revision };
+ return {
+ action: "conflict",
+ storedText: input.storedText,
+ storedRevision: revision,
+ };
+ }
+ if (input.storedText && storedBody === nextBody)
+ return { action: "adopt", revision };
+ const nextRevision = revision + 1;
+ const raw = JSON.parse(input.nextText) as Record;
+ raw.revision = nextRevision;
+ return {
+ action: "write",
+ text: JSON.stringify(raw),
+ revision: nextRevision,
+ };
+}
+
+export function recoveryText(record: string | null): string | undefined {
+ if (!record) return undefined;
+ try {
+ const raw = JSON.parse(record) as Record | null;
+ if (
+ raw?.format === "liveboard-recovery-v1" &&
+ typeof raw.text === "string" &&
+ raw.text.length > 0
+ )
+ return raw.text;
+ } catch {
+ return undefined;
+ }
+ return undefined;
+}
+
+function preserveUnreadable(
+ storage: StorageLike,
+ text: string,
+ now: number,
+): boolean {
+ const record = JSON.stringify({
+ format: "liveboard-recovery-v1",
+ savedAt: now,
+ text,
+ });
+ try {
+ const existing = storage.getItem(RECOVERY_KEY);
+ if (existing && recoveryText(existing) !== text) {
+ if (!storage.getItem(RECOVERY_PREVIOUS_KEY))
+ storage.setItem(RECOVERY_PREVIOUS_KEY, existing);
+ }
+ storage.setItem(RECOVERY_KEY, record);
+ return recoveryText(storage.getItem(RECOVERY_KEY)) === text;
+ } catch {
+ return false;
+ }
+}
+
+export function loadStoredWorkspace(
+ storage: StorageLike,
+ now = Date.now(),
+): LoadResult {
+ let text: string | null;
+ try {
+ text = storage.getItem(WORKSPACE_KEY);
+ } catch {
+ return { status: "empty" };
+ }
+ if (!text) return { status: "empty" };
+ try {
+ return { status: "ok", workspace: parseWorkspace(text), text };
+ } catch {
+ return {
+ status: "unreadable",
+ text,
+ preserved: preserveUnreadable(storage, text, now),
+ };
+ }
+}
+
+export function discardRecovery(storage: StorageLike) {
+ try {
+ storage.removeItem(RECOVERY_KEY);
+ storage.removeItem(RECOVERY_PREVIOUS_KEY);
+ } catch {
+ /* The banner can close even when storage is blocked. */
+ }
+}
diff --git a/src/app/workspace.test.ts b/src/app/workspace.test.ts
index 7ebd64f..11b9ecf 100644
--- a/src/app/workspace.test.ts
+++ b/src/app/workspace.test.ts
@@ -1,7 +1,14 @@
import { describe, expect, it } from "vitest";
import { scenario, serializeBoard } from "../board/board";
import { createChallenge } from "../challenges/challenges";
-import { boardFilename, parseWorkspace, serializeWorkspace } from "./workspace";
+import { briefForLoad, defaultBrief } from "../interview/interview";
+import { checkoutScenario } from "../scenarios/checkout";
+import {
+ boardFilename,
+ boardWasRepaired,
+ parseWorkspace,
+ serializeWorkspace,
+} from "./workspace";
describe("local workspace documents", () => {
it("restores boards saved before assessment autosave", () => {
@@ -27,13 +34,71 @@ describe("local workspace documents", () => {
expect(restored.draft?.problem).toBe(active.problem);
expect(restored.view).toBe("play");
});
- it("does not persist an invalid exercise draft", () => {
+ it("saves the board when a draft title or component field is unfinished", () => {
const board = scenario("cache");
- const draft = createChallenge(board);
+ const previous = parseWorkspace(
+ serializeWorkspace({ board, view: "author", revision: 2 }),
+ );
+ board.nodes[0].data.name = " ";
+ board.config.route = "/users";
+ board.config.ttl = 12;
+ board.config.kafka.topic = " ";
+ const draft = createChallenge(scenario("cache"));
draft.title = "";
- expect(() =>
+ draft.problem = "The cache expires before the next read.";
+ const text = serializeWorkspace(
+ { board, draft, view: "author", revision: 2 },
+ previous,
+ );
+ const restored = parseWorkspace(text);
+ expect(restored.revision).toBe(2);
+ expect(restored.board.config.ttl).toBe(12);
+ expect(restored.board.config.route).toBe("/users/:id");
+ expect(restored.board.config.kafka.topic).toBe("orders");
+ expect(restored.board.nodes[0].data.name).toBe("Client");
+ expect(restored.draft?.title).toBe("Untitled exercise");
+ expect(restored.draft?.problem).toBe(
+ "The cache expires before the next read.",
+ );
+ expect(
+ boardWasRepaired({ board, draft, view: "author" }, previous),
+ ).toBe(true);
+ });
+ it("restores the last valid route and draft title while keeping newer edits", () => {
+ const board = scenario("cache");
+ board.config.route = "/profiles/:id";
+ const draft = createChallenge(board);
+ draft.title = "Cache incident";
+ const previous = parseWorkspace(
serializeWorkspace({ board, draft, view: "author" }),
- ).toThrow();
+ );
+ board.config.route = "/profiles/";
+ board.config.concurrency = 6;
+ draft.title = "";
+ draft.problem = "Updated incident.";
+ const restored = parseWorkspace(
+ serializeWorkspace({ board, draft, view: "author" }, previous),
+ );
+ expect(restored.board.config.route).toBe("/profiles/:id");
+ expect(restored.board.config.concurrency).toBe(6);
+ expect(restored.draft?.title).toBe("Cache incident");
+ expect(restored.draft?.problem).toBe("Updated incident.");
+ });
+ it("reads workspaces saved before revisions", () => {
+ const board = scenario("cache");
+ const raw = JSON.parse(serializeWorkspace({ board, view: "gallery" }));
+ delete raw.revision;
+ expect(parseWorkspace(JSON.stringify(raw)).revision).toBe(0);
+ });
+ it("uses the board brief when a template has one and the default otherwise", () => {
+ expect(briefForLoad(scenario("cache")).prompt).toBe(defaultBrief.prompt);
+ expect(briefForLoad(checkoutScenario()).prompt).toContain("checkout");
+ expect(
+ briefForLoad(scenario("cache"), {
+ ...defaultBrief,
+ prompt: "Preset prompt",
+ }).prompt,
+ ).toBe("Preset prompt");
});
it("rejects malformed or oversized stored documents", () => {
expect(() => parseWorkspace("{")).toThrow();
diff --git a/src/app/workspace.ts b/src/app/workspace.ts
index f8bec21..bdd5cdf 100644
--- a/src/app/workspace.ts
+++ b/src/app/workspace.ts
@@ -1,22 +1,143 @@
-import { parseBoard, serializeBoard, type Board } from "../board/board";
+import {
+ catalog,
+ parseBoard,
+ serializeBoard,
+ type Board,
+} from "../board/board";
import {
parseChallenge,
type ChallengeDefinition,
} from "../challenges/challenges";
+import { defaults } from "../simulation/engine";
+import { consumerDefaults, kafkaDefaults } from "../simulation/kafka";
+export type WorkspaceView = "gallery" | "play" | "author";
export type LocalWorkspace = {
board: Board;
active?: ChallengeDefinition;
draft?: ChallengeDefinition;
- view: "gallery" | "play" | "author";
+ view: WorkspaceView;
+ /** Missing on workspaces saved before multi-tab revisions. */
+ revision?: number;
};
+const routePattern = /^\/[\w/-]*:id$/;
+
+function validName(name: unknown): name is string {
+ return typeof name === "string" && !!name.trim() && name.length <= 80;
+}
+function validRoute(route: unknown): route is string {
+ return typeof route === "string" && routePattern.test(route);
+}
+function validLabel(value: unknown): value is string {
+ return (
+ typeof value === "string" &&
+ !!value.trim() &&
+ value.length <= 4096 &&
+ !/[\u0000-\u001f]/.test(value)
+ );
+}
+function repairBoard(board: Board, previous?: Board): Board {
+ const previousNames = new Map(
+ previous?.nodes.map((node) => [node.id, String(node.data.name ?? "")]) ??
+ [],
+ );
+ const nodes = board.nodes.map((node) => {
+ const current = String(node.data.name ?? "");
+ const fallback = previousNames.get(node.id);
+ const name = validName(current)
+ ? current
+ : validName(fallback)
+ ? fallback
+ : (catalog.find((item) => item.role === node.data.role)?.name ??
+ "Component");
+ return { ...node, data: { ...node.data, name } };
+ });
+ const config = {
+ ...board.config,
+ kafka: { ...board.config.kafka },
+ consumerOverrides: Object.fromEntries(
+ Object.entries(board.config.consumerOverrides ?? {}).map(
+ ([id, settings]) => [id, { ...settings }],
+ ),
+ ),
+ backendOverrides: board.config.backendOverrides
+ ? Object.fromEntries(
+ Object.entries(board.config.backendOverrides).map(([id, settings]) => [
+ id,
+ { ...settings },
+ ]),
+ )
+ : undefined,
+ };
+ const priorRoute = previous?.config.route;
+ config.route = validRoute(config.route)
+ ? config.route
+ : validRoute(priorRoute)
+ ? priorRoute
+ : defaults.route;
+ for (const [id, settings] of Object.entries(config.backendOverrides ?? {})) {
+ if (settings.route !== undefined && !validRoute(settings.route)) {
+ const prior = previous?.config.backendOverrides?.[id]?.route;
+ if (validRoute(prior)) settings.route = prior;
+ else delete settings.route;
+ }
+ }
+ if (!validLabel(config.kafka.topic)) {
+ const prior = previous?.config.kafka.topic;
+ config.kafka.topic = validLabel(prior) ? prior : kafkaDefaults.topic;
+ }
+ for (const [id, settings] of Object.entries(config.consumerOverrides)) {
+ if (settings.groupId !== undefined && !validLabel(settings.groupId)) {
+ const prior = previous?.config.consumerOverrides?.[id]?.groupId;
+ if (validLabel(prior)) settings.groupId = prior;
+ else settings.groupId = consumerDefaults.groupId;
+ }
+ }
+ return { ...board, nodes, config };
+}
+function repairChallenge(
+ value: ChallengeDefinition | undefined,
+ previous?: ChallengeDefinition,
+): ChallengeDefinition | undefined {
+ if (!value) return undefined;
+ const next = {
+ ...value,
+ title: value.title.trim()
+ ? value.title
+ : previous?.title.trim() || "Untitled exercise",
+ problem: value.problem.trim()
+ ? value.problem
+ : previous?.problem.trim() || "Describe the incident.",
+ };
+ try {
+ return parseChallenge(next);
+ } catch {
+ if (!previous) return undefined;
+ try {
+ return parseChallenge(previous);
+ } catch {
+ return undefined;
+ }
+ }
+}
+function revisionOf(raw: Record): number {
+ if (raw.revision === undefined) return 0;
+ if (
+ typeof raw.revision === "number" &&
+ Number.isInteger(raw.revision) &&
+ raw.revision >= 0 &&
+ raw.revision <= Number.MAX_SAFE_INTEGER
+ )
+ return raw.revision;
+ throw new Error("Invalid workspace revision.");
+}
export function parseWorkspace(text: string): LocalWorkspace {
if (text.length > 6_000_000)
throw new Error("The saved workspace is too large.");
const raw = JSON.parse(text);
if (raw?.format !== "liveboard-workspace-v1")
- return { board: parseBoard(text), view: "gallery" };
+ return { board: parseBoard(text), view: "gallery", revision: 0 };
if (!["gallery", "play", "author"].includes(raw.view))
throw new Error("Invalid saved assessment view.");
return {
@@ -24,19 +145,45 @@ export function parseWorkspace(text: string): LocalWorkspace {
active: raw.active ? parseChallenge(raw.active) : undefined,
draft: raw.draft ? parseChallenge(raw.draft) : undefined,
view: raw.view,
+ revision: revisionOf(raw),
};
}
-
-export function serializeWorkspace(workspace: LocalWorkspace): string {
+export function serializeWorkspace(
+ workspace: LocalWorkspace,
+ previous?: LocalWorkspace,
+): string {
+ const view: WorkspaceView =
+ workspace.view === "play" || workspace.view === "author"
+ ? workspace.view
+ : "gallery";
return JSON.stringify({
format: "liveboard-workspace-v1",
- board: parseBoard(serializeBoard(workspace.board)),
- active: workspace.active ? parseChallenge(workspace.active) : undefined,
- draft: workspace.draft ? parseChallenge(workspace.draft) : undefined,
- view: workspace.view,
+ revision: workspace.revision ?? 0,
+ board: parseBoard(
+ serializeBoard(repairBoard(workspace.board, previous?.board)),
+ ),
+ active: repairChallenge(workspace.active, previous?.active),
+ draft: repairChallenge(workspace.draft, previous?.draft),
+ view,
});
}
-
+export function boardWasRepaired(
+ workspace: LocalWorkspace,
+ previous?: LocalWorkspace,
+): boolean {
+ const saved = parseWorkspace(serializeWorkspace(workspace, previous));
+ const names = new Map(
+ saved.board.nodes.map((node) => [node.id, String(node.data.name)]),
+ );
+ return (
+ workspace.board.nodes.some(
+ (node) => names.get(node.id) !== String(node.data.name ?? ""),
+ ) ||
+ saved.board.config.route !== workspace.board.config.route ||
+ saved.draft?.title !== workspace.draft?.title ||
+ saved.draft?.problem !== workspace.draft?.problem
+ );
+}
export function boardFilename(title: string): string {
const name = title
.trim()
diff --git a/src/board/layout.css b/src/board/layout.css
index d2967d6..6b6215c 100644
--- a/src/board/layout.css
+++ b/src/board/layout.css
@@ -1029,6 +1029,46 @@
.local-save-status.save-failed {
color: #a14c36;
}
+.workspace-notice {
+ position: fixed;
+ top: 68px;
+ left: 50%;
+ z-index: 40;
+ width: min(520px, calc(100% - 24px));
+ transform: translateX(-50%);
+ padding: 14px 16px;
+ border: 1px solid #e4c7a8;
+ border-radius: 8px;
+ background: #fffdf8;
+ color: #5c4632;
+ box-shadow: 0 8px 24px #293f2618;
+}
+.workspace-notice strong {
+ display: block;
+ margin-bottom: 6px;
+ font-size: 13px;
+}
+.workspace-notice p {
+ margin: 0 0 10px;
+ font-size: 12px;
+ line-height: 1.45;
+}
+.workspace-notice-actions {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 8px;
+}
+.workspace-notice-actions button {
+ border: 1px solid #d7c3ae;
+ border-radius: 6px;
+ background: white;
+ color: #5c4632;
+ padding: 6px 10px;
+ font-size: 12px;
+}
+.workspace-notice-actions button:disabled {
+ opacity: 0.45;
+}
.file-drop-overlay {
position: absolute;
inset: 8px;
diff --git a/src/challenges/useChallengeSession.ts b/src/challenges/useChallengeSession.ts
index 39d69dd..a912096 100644
--- a/src/challenges/useChallengeSession.ts
+++ b/src/challenges/useChallengeSession.ts
@@ -246,6 +246,22 @@ export default function useChallengeSession({
setBaseline(undefined);
setView("gallery");
};
+ const restore = (session: {
+ active?: ChallengeDefinition;
+ draft?: ChallengeDefinition;
+ view: "gallery" | "play" | "author";
+ }) => {
+ cancel();
+ if (session.active) trusted.set(session.active.id, session.active);
+ setActive(session.active);
+ setDraft(session.draft);
+ setView(session.view);
+ setReport(undefined);
+ setBaseline(undefined);
+ setHints(0);
+ setAttempts(0);
+ setStatus({ running: false, progress: 0, error: "", baseline: false });
+ };
return {
active,
draft,
@@ -265,6 +281,7 @@ export default function useChallengeSession({
cancel,
receive,
leave,
+ restore,
pending,
};
}
diff --git a/src/interview/interview.ts b/src/interview/interview.ts
index 3716133..0449b41 100644
--- a/src/interview/interview.ts
+++ b/src/interview/interview.ts
@@ -108,6 +108,12 @@ export const briefs = [
"Preserve order for each customer key. Let independent groups consume the same events. Demonstrate commit and replay behavior. Explain producer acknowledgments during a replica failure.",
},
];
+export function briefForLoad(
+ board: { interview?: InterviewBrief },
+ override?: InterviewBrief,
+): InterviewBrief {
+ return structuredClone(override ?? board.interview ?? defaultBrief);
+}
export function parseBrief(value: unknown): InterviewBrief {
if (value === undefined) return structuredClone(defaultBrief);
if (!value || typeof value !== "object" || Array.isArray(value))
diff --git a/src/simulation/engine.ts b/src/simulation/engine.ts
index c297dec..62f1eb2 100644
--- a/src/simulation/engine.ts
+++ b/src/simulation/engine.ts
@@ -493,7 +493,13 @@ export class Engine {
? "No healthy backend targets"
: "Connect the client or load balancer to a backend",
};
- if (!viaBalancer) return { id: healthy[0], viaBalancer };
+ // A drawn client edge is a real route. Without a balancer, share traffic
+ // round-robin. Least-connections stays a load-balancer policy.
+ if (!viaBalancer)
+ return {
+ id: healthy[this.roundRobin++ % healthy.length],
+ viaBalancer,
+ };
let candidates = healthy;
if (this.config.balancer.policy === "least-connections") {
const least = Math.min(
@@ -1299,14 +1305,28 @@ export class Engine {
this.dependencyFailure(j, 503, "Database unavailable during read");
return;
}
- j.attemptDeadline = undefined;
- this.circuits.success(j.backendId!, j.generation ?? 0);
const read = this.database.read(j.path.split("/").pop()!, this.state.now);
this.emit(j, "database", this.database.state.reply);
if (read.error) {
- this.finish(429, { error: read.error }, "database");
+ // Throttling is a failed dependency attempt and can open the breaker.
+ // It is not retried: a missing row is a successful lookup, and a quota
+ // window does not refill during backoff.
+ j.attemptDeadline = undefined;
+ this.circuits.failure(
+ j.backendId!,
+ resilienceSettings(this.config, j.backendId!),
+ this.state.now,
+ j.generation ?? 0,
+ );
+ this.finish(
+ 429,
+ { error: read.error, attempts: j.attempt },
+ "database",
+ );
return;
}
+ j.attemptDeadline = undefined;
+ this.circuits.success(j.backendId!, j.generation ?? 0);
const value = read.value;
if (!value) {
this.finish(404, { error: "User not found" }, "database");
diff --git a/src/simulation/resilience.test.ts b/src/simulation/resilience.test.ts
index 9b46f34..f80bbab 100644
--- a/src/simulation/resilience.test.ts
+++ b/src/simulation/resilience.test.ts
@@ -115,6 +115,42 @@ describe("Dependency retries and connection failures", () => {
e.advance(900);
expect(e.state.results[0].status).toBe(429);
expect(e.state.circuits.backend.retries).toBe(0);
+ expect(e.state.circuits.backend.successes).toBe(0);
+ expect(e.state.circuits.backend.failures).toBe(1);
+ });
+ it("opens the breaker when a throttled read is the failure threshold", () => {
+ const e = new Engine();
+ e.configure({
+ ...defaults,
+ delay: 1,
+ concurrency: 2,
+ timeout: 5000,
+ database: {
+ ...defaults.database,
+ technology: "dynamodb",
+ readFrom: "primary",
+ readCapacity: 1,
+ },
+ resilienceOverrides: {
+ backend: {
+ breaker: true,
+ failureThreshold: 1,
+ maxRetries: 3,
+ attemptTimeout: 5000,
+ },
+ },
+ });
+ e.send("/users/1", 2);
+ e.advance(900);
+ expect(e.state.results.map((result) => result.status).sort()).toEqual([
+ 200, 429,
+ ]);
+ expect(e.state.circuits.backend).toMatchObject({
+ state: "open",
+ successes: 1,
+ failures: 1,
+ retries: 0,
+ });
});
it("uses bounded fixed and exponential retry delays", () => {
expect(retryDelay({ ...resilienceDefaults, backoffMs: 100 }, 1)).toBe(100);
diff --git a/src/simulation/scaling.test.ts b/src/simulation/scaling.test.ts
index 4fd8bfe..3f54c1f 100644
--- a/src/simulation/scaling.test.ts
+++ b/src/simulation/scaling.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
-import { Engine, type Config, type Role } from "./engine";
-import { scenario } from "../board/board";
+import { Engine, defaults, type Config, type Role } from "./engine";
+import { createEdge, createNode, executionConfig, scenario } from "../board/board";
function scaled(): Config {
const board = scenario("balanced");
return {
@@ -138,6 +138,35 @@ describe("load balancing", () => {
new Set(e.state.results.slice(0, 2).map((r) => r.backendId)),
).toEqual(new Set(["backend", "backend-2"]));
});
+ it("shares direct client connections across healthy backends", () => {
+ const board = scenario("empty");
+ board.nodes = [
+ createNode("client"),
+ createNode("backend", "backend", { x: 300, y: 40 }),
+ createNode("backend", "backend-2", { x: 300, y: 280 }),
+ createNode("database"),
+ ];
+ board.edges = [
+ createEdge("client", "backend"),
+ createEdge("client", "backend-2"),
+ createEdge("backend", "database"),
+ createEdge("backend-2", "database"),
+ ];
+ const engine = new Engine();
+ engine.configure({ ...defaults, ...executionConfig(board) });
+ engine.send("/users/1", 6);
+ expect(engine.state.backends.backend.reachable).toBe(true);
+ expect(engine.state.backends["backend-2"].reachable).toBe(true);
+ expect(engine.state.backends.backend.assigned).toBe(3);
+ expect(engine.state.backends["backend-2"].assigned).toBe(3);
+ engine.configure({
+ ...engine.config,
+ backendOverrides: { "backend-2": { online: false } },
+ });
+ engine.send("/users/1", 4);
+ expect(engine.state.backends.backend.assigned).toBe(7);
+ expect(engine.state.backends["backend-2"].assigned).toBe(3);
+ });
it("returns 503 when all targets or the balancer are offline", () => {
const base = scaled();
const e = configured({
diff --git a/src/simulation/simulation.worker.ts b/src/simulation/simulation.worker.ts
index 83cc862..3599afe 100644
--- a/src/simulation/simulation.worker.ts
+++ b/src/simulation/simulation.worker.ts
@@ -1,208 +1,6 @@
-import {
- ChallengeRunner,
- type ChallengeDefinition,
-} from "../challenges/challenges";
-import type { Board } from "../board/board";
-import { ExperimentRunner, type ExperimentSpec } from "./experiments";
-import { Engine, type Config } from "./engine";
-let engine = new Engine();
-let playing = true;
-let speed = 1;
-let experiment: { id: string; runner: ExperimentRunner } | undefined;
-function pumpExperiment() {
- const current = experiment;
- if (!current) return;
- try {
- for (let i = 0; i < 30 && !current.runner.finished; i++)
- current.runner.tick();
- if (experiment !== current) return;
- if (current.runner.finished) {
- postMessage({
- type: "experimentComplete",
- id: current.id,
- report: current.runner.report,
- });
- experiment = undefined;
- } else {
- postMessage({
- type: "experimentProgress",
- id: current.id,
- progress: current.runner.progress(),
- });
- setTimeout(pumpExperiment, 0);
- }
- } catch (error) {
- postMessage({
- type: "experimentError",
- id: current.id,
- error: error instanceof Error ? error.message : "Experiment failed",
- });
- experiment = undefined;
- }
-}
-let challenge: { id: string; runner: ChallengeRunner } | undefined;
-function pumpChallenge() {
- const current = challenge;
- if (!current) return;
- try {
- for (let i = 0; i < 30 && !current.runner.finished; i++)
- current.runner.tick();
- if (challenge !== current) return;
- if (current.runner.finished) {
- postMessage({
- type: "challengeComplete",
- id: current.id,
- report: current.runner.report,
- });
- challenge = undefined;
- } else {
- postMessage({
- type: "challengeProgress",
- id: current.id,
- progress: current.runner.progress(),
- });
- setTimeout(pumpChallenge, 0);
- }
- } catch (error) {
- postMessage({
- type: "challengeError",
- id: current.id,
- error:
- error instanceof Error
- ? error.message
- : "Challenge verification failed",
- });
- challenge = undefined;
- }
-}
-function publish() {
- postMessage({ type: "snapshot", state: engine.state });
-}
-onmessage = (
- event: MessageEvent<{
- type: string;
- spec?: ExperimentSpec;
- definition?: ChallengeDefinition;
- board?: Board;
- id?: string;
- config?: Config;
- path?: string;
- count?: number;
- value?: number;
- running?: boolean;
- command?: string;
- groupId?: string;
- record?: { id: string; name: string; email: string };
- }>,
-) => {
- const message = event.data;
- switch (message.type) {
- case "challenge":
- try {
- challenge = {
- id: message.id!,
- runner: new ChallengeRunner(message.definition!, message.board!),
- };
- setTimeout(pumpChallenge, 0);
- } catch (error) {
- postMessage({
- type: "challengeError",
- id: message.id,
- error: error instanceof Error ? error.message : "Invalid challenge",
- });
- }
- return;
- case "cancelChallenge":
- challenge = undefined;
- return;
- case "experiment":
- try {
- experiment = {
- id: message.id!,
- runner: new ExperimentRunner(message.config!, message.spec!),
- };
- setTimeout(pumpExperiment, 0);
- } catch (error) {
- postMessage({
- type: "experimentError",
- id: message.id,
- error: error instanceof Error ? error.message : "Experiment failed",
- });
- }
- return;
- case "cancelExperiment":
- experiment = undefined;
- return;
- case "produce":
- engine.produce(message.count);
- break;
- case "cacheCommand":
- engine.cacheCommand(message.command ?? "");
- break;
- case "commit":
- engine.kafka.now = engine.state.now;
- engine.kafka.commit(message.groupId ?? "");
- break;
- case "replay":
- engine.kafka.replay(message.groupId ?? "", engine.state.now);
- break;
- case "ack":
- engine.queueLab.ackAll(engine.state.now);
- break;
- case "redrive":
- engine.queueLab.redrive(engine.state.now);
- break;
- case "dbWrite":
- if (message.record)
- engine.database.write(
- message.record,
- engine.state.now,
- engine.config.online,
- );
- break;
- case "dbRead":
- if (engine.config.online)
- engine.database.read(message.path ?? "1", engine.state.now);
- else engine.database.state.reply = "Read failed · database offline";
- break;
- case "configure":
- engine.configure(message.config!);
- break;
- case "traffic":
- engine.setTraffic(message.value!, message.path!, !!message.running);
- break;
- case "send":
- engine.send(message.path!, message.count);
- break;
- case "play":
- playing = !!message.value;
- break;
- case "speed":
- speed = message.value!;
- break;
- case "step":
- engine.step();
- break;
- case "advance":
- engine.advance(message.value!);
- break;
- case "expire":
- engine.state.entries = [];
- break;
- case "reset": {
- const config = engine.config;
- engine = new Engine();
- engine.configure(config);
- break;
- }
- }
- engine.syncLabs();
- publish();
-};
-setInterval(() => {
- if (playing) {
- engine.advance(50 * speed);
- publish();
- }
-}, 50);
-publish();
+import { createSimulationHost } from "./simulationHost";
+
+const host = createSimulationHost((message) => postMessage(message));
+onmessage = (event: MessageEvent) => host.handle(event.data);
+setInterval(() => host.tick(), 50);
+host.publish();
diff --git a/src/simulation/simulationHost.test.ts b/src/simulation/simulationHost.test.ts
new file mode 100644
index 0000000..52fe320
--- /dev/null
+++ b/src/simulation/simulationHost.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { createEdge, createNode, executionConfig, scenario } from "../board/board";
+import { defaults } from "./engine";
+import { createSimulationHost, snapshotFrom } from "./simulationHost";
+
+describe("simulation worker host", () => {
+ it("routes a direct multi-backend configure and send through the worker protocol", () => {
+ const messages: unknown[] = [];
+ const host = createSimulationHost((message) => messages.push(message));
+ const board = scenario("empty");
+ board.nodes = [
+ createNode("client"),
+ createNode("backend", "backend", { x: 280, y: 40 }),
+ createNode("backend", "backend-2", { x: 280, y: 280 }),
+ createNode("database"),
+ ];
+ board.edges = [
+ createEdge("client", "backend"),
+ createEdge("client", "backend-2"),
+ createEdge("backend", "database"),
+ createEdge("backend-2", "database"),
+ ];
+ host.handle({
+ type: "configure",
+ config: { ...defaults, ...executionConfig(board) },
+ });
+ host.handle({ type: "send", path: "/users/1", count: 4 });
+ const state = snapshotFrom(messages);
+ expect(state?.backends.backend.assigned).toBe(2);
+ expect(state?.backends["backend-2"].assigned).toBe(2);
+ });
+});
diff --git a/src/simulation/simulationHost.ts b/src/simulation/simulationHost.ts
new file mode 100644
index 0000000..84d5a1f
--- /dev/null
+++ b/src/simulation/simulationHost.ts
@@ -0,0 +1,226 @@
+import {
+ ChallengeRunner,
+ type ChallengeDefinition,
+} from "../challenges/challenges";
+import type { Board } from "../board/board";
+import { ExperimentRunner, type ExperimentSpec } from "./experiments";
+import { Engine, type Config, type Snapshot } from "./engine";
+
+export type SimulationCommand = {
+ type: string;
+ spec?: ExperimentSpec;
+ definition?: ChallengeDefinition;
+ board?: Board;
+ id?: string;
+ config?: Config;
+ path?: string;
+ count?: number;
+ value?: number;
+ running?: boolean;
+ command?: string;
+ groupId?: string;
+ record?: { id: string; name: string; email: string };
+};
+
+export function createSimulationHost(post: (message: unknown) => void) {
+ let engine = new Engine();
+ let playing = true;
+ let speed = 1;
+ let experiment: { id: string; runner: ExperimentRunner } | undefined;
+ let challenge: { id: string; runner: ChallengeRunner } | undefined;
+ const publish = () => post({ type: "snapshot", state: engine.state });
+ function pumpExperiment() {
+ const current = experiment;
+ if (!current) return;
+ try {
+ for (let i = 0; i < 30 && !current.runner.finished; i++)
+ current.runner.tick();
+ if (experiment !== current) return;
+ if (current.runner.finished) {
+ post({
+ type: "experimentComplete",
+ id: current.id,
+ report: current.runner.report,
+ });
+ experiment = undefined;
+ } else {
+ post({
+ type: "experimentProgress",
+ id: current.id,
+ progress: current.runner.progress(),
+ });
+ setTimeout(pumpExperiment, 0);
+ }
+ } catch (error) {
+ post({
+ type: "experimentError",
+ id: current.id,
+ error: error instanceof Error ? error.message : "Experiment failed",
+ });
+ experiment = undefined;
+ }
+ }
+ function pumpChallenge() {
+ const current = challenge;
+ if (!current) return;
+ try {
+ for (let i = 0; i < 30 && !current.runner.finished; i++)
+ current.runner.tick();
+ if (challenge !== current) return;
+ if (current.runner.finished) {
+ post({
+ type: "challengeComplete",
+ id: current.id,
+ report: current.runner.report,
+ });
+ challenge = undefined;
+ } else {
+ post({
+ type: "challengeProgress",
+ id: current.id,
+ progress: current.runner.progress(),
+ });
+ setTimeout(pumpChallenge, 0);
+ }
+ } catch (error) {
+ post({
+ type: "challengeError",
+ id: current.id,
+ error:
+ error instanceof Error
+ ? error.message
+ : "Challenge verification failed",
+ });
+ challenge = undefined;
+ }
+ }
+ return {
+ publish,
+ tick() {
+ if (playing) {
+ engine.advance(50 * speed);
+ publish();
+ }
+ },
+ handle(message: SimulationCommand) {
+ switch (message.type) {
+ case "challenge":
+ try {
+ challenge = {
+ id: message.id!,
+ runner: new ChallengeRunner(message.definition!, message.board!),
+ };
+ setTimeout(pumpChallenge, 0);
+ } catch (error) {
+ post({
+ type: "challengeError",
+ id: message.id,
+ error:
+ error instanceof Error ? error.message : "Invalid challenge",
+ });
+ }
+ return;
+ case "cancelChallenge":
+ challenge = undefined;
+ return;
+ case "experiment":
+ try {
+ experiment = {
+ id: message.id!,
+ runner: new ExperimentRunner(message.config!, message.spec!),
+ };
+ setTimeout(pumpExperiment, 0);
+ } catch (error) {
+ post({
+ type: "experimentError",
+ id: message.id,
+ error:
+ error instanceof Error ? error.message : "Experiment failed",
+ });
+ }
+ return;
+ case "cancelExperiment":
+ experiment = undefined;
+ return;
+ case "produce":
+ engine.produce(message.count);
+ break;
+ case "cacheCommand":
+ engine.cacheCommand(message.command ?? "");
+ break;
+ case "commit":
+ engine.kafka.now = engine.state.now;
+ engine.kafka.commit(message.groupId ?? "");
+ break;
+ case "replay":
+ engine.kafka.replay(message.groupId ?? "", engine.state.now);
+ break;
+ case "ack":
+ engine.queueLab.ackAll(engine.state.now);
+ break;
+ case "redrive":
+ engine.queueLab.redrive(engine.state.now);
+ break;
+ case "dbWrite":
+ if (message.record)
+ engine.database.write(
+ message.record,
+ engine.state.now,
+ engine.config.online,
+ );
+ break;
+ case "dbRead":
+ if (engine.config.online)
+ engine.database.read(message.path ?? "1", engine.state.now);
+ else engine.database.state.reply = "Read failed · database offline";
+ break;
+ case "configure":
+ engine.configure(message.config!);
+ break;
+ case "traffic":
+ engine.setTraffic(message.value!, message.path!, !!message.running);
+ break;
+ case "send":
+ engine.send(message.path!, message.count);
+ break;
+ case "play":
+ playing = !!message.value;
+ break;
+ case "speed":
+ speed = message.value!;
+ break;
+ case "step":
+ engine.step();
+ break;
+ case "advance":
+ engine.advance(message.value!);
+ break;
+ case "expire":
+ engine.state.entries = [];
+ break;
+ case "reset": {
+ const config = engine.config;
+ engine = new Engine();
+ engine.configure(config);
+ break;
+ }
+ }
+ engine.syncLabs();
+ publish();
+ },
+ };
+}
+
+export function snapshotFrom(messages: unknown[]): Snapshot | undefined {
+ const snapshot = [...messages]
+ .reverse()
+ .find(
+ (message): message is { type: string; state: Snapshot } =>
+ !!message &&
+ typeof message === "object" &&
+ "type" in message &&
+ message.type === "snapshot" &&
+ "state" in message,
+ );
+ return snapshot?.state;
+}