Save a session to start your day.
Copy, don't synchronize
Select favorites above to copy to the other database. Existing choices are kept; removals are not propagated.
@@ -269,7 +281,11 @@
Confirm selected favorites
},
});
const data = await response.json();
- if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
+ if (!response.ok) {
+ const error = new Error(`${data.error.code}: ${data.error.message}`);
+ error.code = data.error.code;
+ throw error;
+ }
return data;
}
@@ -279,6 +295,36 @@
Confirm selected favorites
if (id === "message") $(id).className = `notice ${error ? "error" : "success"}`;
}
+ function showFailure(error) {
+ const step = config?.mode === "starter"
+ ? (error.code === "TODO_LIST_SESSIONS" ? 1 : error.code === "TODO_SAVE_FAVORITE" ? 2 : undefined)
+ : undefined;
+ if (step) {
+ $("exercise").hidden = false;
+ $("exercise-title").textContent = step === 1
+ ? "Exercise 1 — Read the catalog" : "Exercise 2 — Save your first favorite";
+ $("exercise-help").textContent = step === 1
+ ? "Your database is reachable. Implement listSessions to make its catalog appear; this is an expected exercise checkpoint, not a system failure."
+ : "The catalog is working. Implement saveFavorite, then try Save favorite again. Your existing favorites have not been reset.";
+ $("exercise-guide").href = `https://github.com/documentdb/ato-2026-workshop/blob/main/docs/lab.md#${step === 1 ? "2-read-the-catalog" : "3-save-favorites-and-prove-persistence"}`;
+ } else {
+ $("exercise").hidden = true;
+ notice("error", error.message);
+ }
+ if (!state) {
+ $("catalog-empty").hidden = false;
+ $("catalog-empty").textContent = step === 1
+ ? "Next: complete Exercise 1 in exercises/starter/repository.js, save, and refresh."
+ : "The catalog could not be loaded. Resolve the error above, then refresh.";
+ $("catalog-source").textContent = step === 1
+ ? "Catalog source and snapshot details will appear after Exercise 1. The attendee guide explains the included schedule."
+ : "Catalog source details are unavailable until this database can be read.";
+ $("status").textContent = step === 1
+ ? "Database reachable. Ready for Exercise 1."
+ : "This request did not complete. Check the error above; no fallback target was used.";
+ }
+ }
+
async function perform(action) {
if (busy) return;
busy = true;
@@ -287,7 +333,7 @@
Confirm selected favorites
try {
await action();
} catch (error) {
- notice("error", error.message);
+ showFailure(error);
} finally {
busy = false;
controls();
@@ -306,7 +352,7 @@
Confirm selected favorites
function renderConfiguration() {
$("target-name").textContent = label(config.target);
- $("mode").textContent = `${config.mode === "starter" ? "TODO starter" : "Complete reference"} / Same application data layer`;
+ $("mode").textContent = `${config.mode === "starter" ? "Exercise implementation (your editable code)" : "Complete reference"} / Same application data layer`;
$("target-select").replaceChildren();
for (const { id: target } of config.targets) {
const option = node("option", label(target));
@@ -362,6 +408,7 @@
Confirm selected favorites
body: JSON.stringify({ target: config.target, sessionId: session.id }),
});
await loadState();
+ $("exercise").hidden = true;
notice("message", saved ? "Removed from the active database only." : "Favorite saved in the active database.");
});
});
@@ -422,6 +469,9 @@
Confirm selected favorites
async function refresh() {
state = undefined;
selected.clear();
+ $("exercise").hidden = true;
+ $("catalog-source").textContent = "Checking this catalog's source and snapshot date...";
+ $("favorites-empty").hidden = false;
$("sessions").replaceChildren();
$("favorites").replaceChildren();
$("copy-results").replaceChildren();
@@ -466,7 +516,7 @@
Confirm selected favorites
link.download = `${state.catalog.kind === "practice" ? "practice-" : ""}conference-favorites.ics`;
link.click();
setTimeout(() => URL.revokeObjectURL(url), 1000);
- notice("message", "Calendar export requested. Save the .ics file if your browser prompts, then import it manually; this is not a live subscription.");
+ notice("message", "Calendar export requested. Save the .ics file if prompted, then follow the Google Calendar / Apple Calendar import steps below the download button. This is a snapshot, not a live subscription.");
}));
$("copy").addEventListener("click", () => {
$("copy-route").textContent = `${label(config.target)} -> ${label(destination())}`;
diff --git a/src/server.js b/src/server.js
index 83610f3..99f9d14 100644
--- a/src/server.js
+++ b/src/server.js
@@ -88,18 +88,18 @@ export async function createApp({ config, connections, repository, logger = cons
}
const target = activeTarget;
if (request.method === "GET" && url.pathname === "/api/health") {
- await connections.db(target).command({ ping: 1 });
+ await (await connections.db(target)).command({ ping: 1 });
json(200, { ready: true, target, mode: config.mode, location: config.location });
return;
}
if (request.method === "GET" && url.pathname === "/api/state") {
- const state = await readPlanner(connections.db(target), repository);
+ const state = await readPlanner(await connections.db(target), repository);
json(200, { target, ...state });
return;
}
if (request.method === "GET" && url.pathname === "/api/calendar") {
assertTarget(url.searchParams.get("target"));
- const state = await readPlanner(connections.db(target), repository);
+ const state = await readPlanner(await connections.db(target), repository);
if (state.orphanedFavorites.length) {
throw new WorkshopError(409, "CATALOG_DRIFT", "Some favorites have no matching session. Resolve the catalog drift before exporting.");
}
@@ -120,14 +120,14 @@ export async function createApp({ config, connections, repository, logger = cons
if (!["local", "site-b", "cloud"].includes(data.nextTarget)) {
throw new WorkshopError(400, "INVALID_TARGET", "Choose one of the configured database targets.");
}
- await connections.db(data.nextTarget).command({ ping: 1 });
+ await (await connections.db(data.nextTarget)).command({ ping: 1 });
assertTarget(data.target);
activeTarget = data.nextTarget;
json(200, details());
return;
}
if (url.pathname === "/api/favorites") {
- const db = connections.db(target);
+ const db = await connections.db(target);
await requireSession(db, data.sessionId);
if (request.method === "POST") {
const result = await repository.saveFavorite(db, data.sessionId);
@@ -142,7 +142,7 @@ export async function createApp({ config, connections, repository, logger = cons
if (data.source !== target || !["local", "site-b", "cloud"].includes(data.destination) || data.source === data.destination) {
throw new WorkshopError(400, "INVALID_TRANSFER", "Copy from the active target to the other configured target.");
}
- const result = await copyFavorites(connections.db(data.source), connections.db(data.destination), data.sessionIds);
+ const result = await copyFavorites(await connections.db(data.source), await connections.db(data.destination), data.sessionIds);
if (!result.complete) {
logger.error(JSON.stringify({ event: "copy_incomplete", statuses: result.results.map((item) => item.status) }));
}
diff --git a/test/connections.test.js b/test/connections.test.js
new file mode 100644
index 0000000..b9f420f
--- /dev/null
+++ b/test/connections.test.js
@@ -0,0 +1,122 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createConnections } from "../src/connections.js";
+import { waitForDatabase } from "../scripts/database.mjs";
+
+const config = { targets: {
+ local: { uri: "mongodb://site-a.invalid", database: "test_a", developmentCertificate: true },
+ "site-b": { uri: "mongodb://site-b.invalid", database: "test_b", developmentCertificate: true },
+ cloud: { uri: "mongodb://managed.invalid", database: "test_cloud", developmentCertificate: false },
+} };
+function mockDriver() {
+ const clients = [];
+ const failure = () => Object.assign(new Error("synthetic failure"), { name: "MongoServerSelectionError" });
+ class Client {
+ constructor(uri, options) {
+ Object.assign(this, { uri, options, connects: 0, closes: 0, topology: null });
+ clients.push(this);
+ }
+ async connect() {
+ this.connects++;
+ if (Client.gate) await Client.gate;
+ // Model the pinned driver's failed-lazy-connect state. Only explicit
+ // connect may repair it; db()/commands never repair a closed topology.
+ this.topology = Client.available ? "connected" : "closed";
+ if (!Client.available) throw failure();
+ return this;
+ }
+ db(name) {
+ return { name, command: async () => {
+ if (this.topology !== "connected" || !Client.available) throw failure();
+ return { ok: 1 };
+ } };
+ }
+ async close() { this.closes++; this.topology = "closed"; }
+ }
+ Client.available = false;
+ return { Client, clients };
+}
+
+test("first failed acquisition retries explicitly on the same cached client, without replaying commands", async () => {
+ const { Client, clients } = mockDriver();
+ const connections = createConnections(config, { Client });
+ await assert.rejects(connections.db("site-b"), { name: "MongoServerSelectionError" });
+ assert.equal(clients[0].topology, "closed");
+ Client.available = true;
+ assert.deepEqual(await (await connections.db("site-b")).command({ ping: 1 }), { ok: 1 });
+ assert.equal(clients.length, 1);
+ assert.equal(clients[0].connects, 2);
+ Client.available = false;
+ await assert.rejects(clients[0].db("test_b").command({ ping: 1 }));
+ assert.equal(clients[0].connects, 2, "a failed operation isn't automatically retried");
+ Client.available = true;
+ await (await connections.db("site-b")).command({ ping: 1 });
+ assert.equal(clients[0].connects, 3);
+ await connections.close();
+});
+
+test("concurrent failed and healthy acquisitions settle, reuse one client, and keep TLS/timeouts", async () => {
+ const { Client, clients } = mockDriver();
+ const connections = createConnections(config, { Client });
+ const failed = await Promise.allSettled(Array.from({ length: 3 }, () => connections.db("site-b")));
+ assert.ok(failed.every(({ status }) => status === "rejected"));
+ Client.available = true;
+ assert.equal((await Promise.all(Array.from({ length: 3 }, () => connections.db("site-b")))).length, 3);
+ assert.equal(clients.length, 1);
+ assert.equal(clients[0].connects, 6);
+ const { options } = clients[0];
+ assert.equal(options.tls, true);
+ assert.equal(options.tlsAllowInvalidCertificates, true);
+ assert.equal(options.tlsAllowInvalidHostnames, false);
+ assert.equal(options.retryWrites, false);
+ assert.equal(options.serverSelectionTimeoutMS, 5000);
+ assert.equal(options.connectTimeoutMS, 5000);
+ assert.equal(options.timeoutMS, 10000);
+ await connections.db("cloud");
+ assert.equal(clients[1].options.tlsAllowInvalidCertificates, false);
+ await assert.rejects(connections.db("unknown"), { code: "TARGET_NOT_CONFIGURED" });
+ await connections.close();
+ assert.ok(clients.every(({ closes }) => closes === 1));
+});
+
+test("close is terminal and idempotent and waits for acquisitions without handing out a closing Db", async () => {
+ const { Client, clients } = mockDriver();
+ Client.available = true;
+ let release;
+ Client.gate = new Promise((resolve) => { release = resolve; });
+ const connections = createConnections(config, { Client });
+ const acquisition = assert.rejects(connections.db("local"), { code: "CONNECTIONS_CLOSED" });
+ const closing = connections.close();
+ assert.equal(connections.close(), closing);
+ assert.equal(clients[0].closes, 0);
+ await assert.rejects(connections.db("site-b"), { code: "CONNECTIONS_CLOSED" });
+ release();
+ await Promise.all([acquisition, closing]);
+ assert.equal(clients.length, 1);
+ assert.equal(clients[0].closes, 1);
+ await assert.rejects(connections.db("local"), { code: "CONNECTIONS_CLOSED" });
+});
+
+test("wait retries acquisition INSIDE its loop, then the original invocation succeeds", async () => {
+ let attempts = 0;
+ let clock = 0;
+ const connections = { async db(target) {
+ assert.equal(target, "site-b");
+ if (++attempts < 3) throw new Error("not ready yet");
+ return { async command(command) { assert.deepEqual(command, { ping: 1 }); } };
+ } };
+ await waitForDatabase(connections, "site-b", { timeoutMS: 6000, now: () => clock, sleep: async (ms) => { clock += ms; } });
+ assert.equal(attempts, 3);
+ assert.equal(clock, 4000);
+});
+
+test("wait deadline is bounded even when every acquisition rejects", async () => {
+ let attempts = 0;
+ let clock = 0;
+ const failure = new Error("unavailable");
+ await assert.rejects(waitForDatabase({ async db() { attempts++; throw failure; } }, "site-b", {
+ timeoutMS: 4500, now: () => clock, sleep: async (ms) => { clock += ms; },
+ }), (error) => error === failure);
+ assert.equal(attempts, 3);
+ assert.equal(clock, 4500);
+});
diff --git a/test/database.integration.js b/test/database.integration.js
index d8700a4..697c754 100644
--- a/test/database.integration.js
+++ b/test/database.integration.js
@@ -1,3 +1,6 @@
+import { inspectDatabase } from "../src/inspection.js";
+import { programCounts } from "../scripts/program-counts.mjs";
+import { programCountsPipeline } from "../examples/complete/program-counts.js";
import test from "node:test";
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
@@ -24,21 +27,11 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
const config = readConfig({ ...localEnv, LOCAL_DATABASE_NAME: `verify_source_${runId}` });
const sourceConnections = createConnections(config);
const destinationConnections = createConnections(readConfig({ ...localEnv, SITE_B_DATABASE_NAME: `verify_destination_${runId}` }));
- const source = sourceConnections.db("local");
- const destination = destinationConnections.db("site-b");
- assert.notEqual(config.targets.local.uri.split("@")[1], config.targets["site-b"].uri.split("@")[1], "integration requires two distinct server endpoints");
- // Site A's credentials must not authenticate to Site B (or vice versa).
- for (const [from, to] of [["local", "site-b"], ["site-b", "local"]]) {
- const foreign = createConnections({ targets: { local: {
- ...config.targets[from],
- uri: `${config.targets[from].uri.split("@")[0]}@${config.targets[to].uri.split("@")[1]}`,
- } } });
- try {
- await assert.rejects(foreign.db("local").command({ ping: 1 }), { code: 18 });
- } finally { await foreign.close(); }
- }
+ let source;
+ let destination;
let sourceOwned = false;
let destinationOwned = false;
+ // Register ownership-aware cleanup before the first asynchronous acquisition.
t.after(async () => {
try {
if (sourceOwned) await source.dropDatabase();
@@ -50,6 +43,19 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
}
}
});
+ source = await sourceConnections.db("local");
+ destination = await destinationConnections.db("site-b");
+ assert.notEqual(config.targets.local.uri.split("@")[1], config.targets["site-b"].uri.split("@")[1], "integration requires two distinct server endpoints");
+ // Site A's credentials must not authenticate to Site B (or vice versa).
+ for (const [from, to] of [["local", "site-b"], ["site-b", "local"]]) {
+ const foreign = createConnections({ targets: { local: {
+ ...config.targets[from],
+ uri: `${config.targets[from].uri.split("@")[0]}@${config.targets[to].uri.split("@")[1]}`,
+ } } });
+ try {
+ await assert.rejects(async () => (await foreign.db("local")).command({ ping: 1 }), { code: 18 });
+ } finally { await foreign.close(); }
+ }
await source.createCollection("verification_ownership");
sourceOwned = true;
await destination.createCollection("verification_ownership");
@@ -105,6 +111,10 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
assert.match(drift.results[0].message, /details differ/);
await destination.collection("sessions").updateOne({ _id: ids[0] }, { $set: { room: originalSession.room } });
+ const beforeMigration = await inspectDatabase(source);
+ assert.equal(beforeMigration.session.schemaVersion, 1);
+ assert.equal(Object.hasOwn(beforeMigration.session, "attendanceMode"), false);
+ assert.ok(beforeMigration.favorite.savedAt);
await source.collection("sessions").createIndex({ startsAt: 1, _id: 1 }, { name: "schedule_order" });
const migrate = () => source.collection("sessions").updateMany(
{ catalogVersion: catalog.fingerprint, schemaVersion: 1, attendanceMode: { $exists: false } },
@@ -112,6 +122,12 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
);
assert.equal((await migrate()).modifiedCount, catalog.sessions.length);
assert.equal((await migrate()).modifiedCount, 0);
+ const afterMigration = await inspectDatabase(source);
+ assert.equal(afterMigration.session._id, beforeMigration.session._id);
+ assert.equal(afterMigration.session.schemaVersion, 2);
+ assert.equal(afterMigration.session.attendanceMode, "in-person");
+ assert.equal(afterMigration.favorite.savedAt, beforeMigration.favorite.savedAt);
+ assert.ok(afterMigration.indexes.some(({ name }) => name === "schedule_order"));
await seedCatalog(source, catalog);
assert.equal(await source.collection("sessions").countDocuments({ schemaVersion: 2 }), catalog.sessions.length);
const state = await readPlanner(source, repository);
@@ -120,7 +136,7 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
const app = await createApp({
config: { ...config, mode: "complete" },
- connections: { db: (target) => {
+ connections: { db: async (target) => {
if (target === "local") return source;
if (target === "site-b") return destination;
throw new WorkshopError(409, "TARGET_NOT_CONFIGURED", "No cloud access in this test.");
@@ -167,3 +183,34 @@ test("two real independent DocumentDB servers: independent data, retry-safe roun
await app.close();
}
});
+
+test("optional aggregation queries the actual official snapshot on an owned local test database", async (t) => {
+ const connections = createConnections(readConfig({
+ ...process.env, ACTIVE_TARGET: "local", WORKSHOP_SCENARIO: "attendee",
+ LOCAL_DATABASE_NAME: `verify_query_${randomUUID().replaceAll("-", "")}`,
+ }));
+ let db;
+ let owned = false;
+ t.after(async () => {
+ try { if (owned) await db.dropDatabase(); }
+ finally { await connections.close(); }
+ });
+ db = await connections.db("local");
+ await db.createCollection("verification_ownership");
+ owned = true;
+ const catalog = await readCatalog();
+ await seedCatalog(db, catalog);
+ const result = await programCounts(db, programCountsPipeline);
+ // Independent calculation: conference timezone rather than pipeline bounds.
+ const expected = new Map();
+ for (const session of catalog.sessions) {
+ const day = new Intl.DateTimeFormat("en-CA", { timeZone: catalog.timeZone }).format(new Date(session.startsAt));
+ if (day === "2026-10-19") expected.set(session.track, (expected.get(session.track) || 0) + 1);
+ }
+ assert.deepEqual(result.rows, [...expected].map(([_id, entries]) => ({ _id, entries }))
+ .sort((a, b) => b.entries - a.entries || a._id.localeCompare(b._id)));
+ assert.equal(result.rows.length, 17);
+ assert.equal(result.rows.reduce((sum, row) => sum + row.entries, 0), 74);
+ assert.equal(await db.collection("sessions").countDocuments(), 216);
+ assert.equal(await db.collection("favorites").countDocuments(), 0);
+});
diff --git a/test/experience.test.js b/test/experience.test.js
new file mode 100644
index 0000000..3bd63ea
--- /dev/null
+++ b/test/experience.test.js
@@ -0,0 +1,117 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import vm from "node:vm";
+import { readCatalog } from "../src/catalog.js";
+import { inspectDatabase } from "../src/inspection.js";
+import { programCounts, validatePipeline } from "../scripts/program-counts.mjs";
+import { programCountsPipeline } from "../examples/complete/program-counts.js";
+
+async function browser() {
+ const html = await readFile(new URL("../src/public/index.html", import.meta.url), "utf8");
+ const script = [...html.matchAll(/
]*>([\s\S]*?)<\/script>/g)].at(-1)[1];
+ const elements = new Map();
+ const element = () => ({ hidden: true, textContent: "", value: "", children: [],
+ addEventListener() {}, setAttribute() {}, append(...nodes) { this.children.push(...nodes); },
+ replaceChildren(...nodes) { this.children = nodes; },
+ });
+ const context = vm.createContext({ URLSearchParams, Intl, Date, Set, Map, Error, console,
+ document: {
+ getElementById(id) { if (!elements.has(id)) elements.set(id, element()); return elements.get(id); },
+ createElement: element, querySelectorAll: () => [],
+ },
+ });
+ // Exercise the actual page functions without auto-boot/network. Separate HTTP
+ // tests verify the endpoint contracts. This is not a rendered-browser proof.
+ vm.runInContext(script.replace(/ perform\(refresh\);\s*$/, ""), context);
+ vm.runInContext('config = {mode:"starter", target:"local", targets:[{id:"local",label:"Site A"}], scenario:"attendee", location:"codespaces"}', context);
+ return { elements, context, run: (source) => vm.runInContext(source, context) };
+}
+
+test("expected TODOs show a guided checkpoint, not red error or indefinite loading", async () => {
+ const { elements, run } = await browser();
+ run('showFailure({code:"TODO_LIST_SESSIONS",message:"TODO"})');
+ assert.equal(elements.get("exercise").hidden, false);
+ assert.match(elements.get("exercise-title").textContent, /Exercise 1/);
+ assert.match(elements.get("exercise-help").textContent, /listSessions/);
+ assert.match(elements.get("exercise-guide").href, /#2-read-the-catalog$/);
+ assert.doesNotMatch(elements.get("catalog-empty").textContent, /Loading/);
+ assert.doesNotMatch(elements.get("catalog-source").textContent, /Loading/);
+ assert.equal(elements.get("error")?.hidden ?? true, true);
+ run('showFailure({code:"TODO_SAVE_FAVORITE",message:"TODO"})');
+ assert.match(elements.get("exercise-title").textContent, /Exercise 2/);
+ assert.match(elements.get("exercise-help").textContent, /saveFavorite/);
+ assert.match(elements.get("exercise-guide").href, /#3-save-favorites-and-prove-persistence$/);
+ run('renderConfiguration()');
+ assert.match(elements.get("mode").textContent, /Exercise implementation/);
+ assert.doesNotMatch(elements.get("mode").textContent, /TODO|unfinished/);
+});
+
+test("real errors remain errors; completed exercise state is not inferred from mode", async () => {
+ const { elements, run } = await browser();
+ run('showFailure({code:"DATABASE_UNAVAILABLE",message:"Database unavailable"})');
+ assert.equal(elements.get("exercise").hidden, true);
+ assert.equal(elements.get("error").hidden, false);
+ assert.match(elements.get("catalog-empty").textContent, /could not be loaded/);
+ run('config.mode="complete"; showFailure({code:"TODO_LIST_SESSIONS",message:"Unexpected TODO"})');
+ assert.equal(elements.get("exercise").hidden, true);
+ assert.equal(elements.get("error").textContent, "Unexpected TODO");
+});
+
+test("inspect returns actual bounded projected sessions/favorites and index definitions", async () => {
+ const calls = [];
+ const session = { _id: "sample", title: "Published entry", startsAt: "2026-10-19T13:00:00.000Z", schemaVersion: 1 };
+ const favorite = { _id: "sample", savedAt: "2026-10-17T13:00:00.000Z" };
+ const db = { collection(name) { return {
+ async findOne() { return { _id: "catalog", version: "test", fingerprint: "fp" }; },
+ find(filter, options) {
+ calls.push({ name, filter, options });
+ return { sort(order) { calls.at(-1).sort = order; return this; }, limit(count) { calls.at(-1).limit = count; return this; },
+ async toArray() { return [structuredClone(name === "sessions" ? session : favorite)]; } };
+ },
+ listIndexes() { return { async toArray() { return [{ name: "schedule_order", key: { startsAt: 1, _id: 1 }, ignored: "not emitted" }]; } }; },
+ }; } };
+ const before = await inspectDatabase(db);
+ assert.deepEqual(before.session, session);
+ assert.equal(Object.hasOwn(before.session, "attendanceMode"), false);
+ assert.deepEqual(before.favorite, favorite);
+ assert.ok(calls.every(({ limit }) => limit === 1));
+ assert.deepEqual(calls[0].filter, { catalogVersion: "fp" });
+ assert.deepEqual(calls[1].options.projection, { _id: 1, savedAt: 1 });
+ assert.deepEqual(before.indexes, [{ name: "schedule_order", key: { startsAt: 1, _id: 1 } }]);
+ Object.assign(session, { schemaVersion: 2, attendanceMode: "in-person" });
+ const after = await inspectDatabase(db);
+ assert.equal(after.session.schemaVersion, 2);
+ assert.equal(after.session.attendanceMode, "in-person");
+ assert.equal(after.favorite.savedAt, before.favorite.savedAt);
+});
+
+test("optional reference counts match the real fixed snapshot, not attendees or the current day", async () => {
+ const catalog = await readCatalog();
+ const pipeline = programCountsPipeline(catalog.fingerprint);
+ assert.deepEqual(validatePipeline(pipeline), pipeline);
+ assert.equal(pipeline[0].$match.catalogVersion, catalog.fingerprint);
+ const range = pipeline[0].$match.startsAt;
+ const selected = catalog.sessions.filter(({ startsAt }) => startsAt >= range.$gte && startsAt < range.$lt);
+ assert.ok(selected.every(({ startsAt }) => new Intl.DateTimeFormat("en-CA", { timeZone: catalog.timeZone }).format(new Date(startsAt)) === "2026-10-19"));
+ const counts = new Map();
+ for (const row of selected) counts.set(row.track, (counts.get(row.track) || 0) + 1);
+ const expected = [...counts].map(([_id, entries]) => ({ _id, entries })).sort((a, b) => b.entries - a.entries || a._id.localeCompare(b._id));
+ assert.deepEqual(pipeline[1], { $group: { _id: "$track", entries: { $sum: 1 } } });
+ assert.deepEqual(pipeline[2], { $sort: { entries: -1, _id: 1 } });
+ // These values are independently computed from data/catalog.json; changing
+ // the snapshot requires reviewing both the challenge's expected result and test.
+ assert.equal(selected.length, 74);
+ assert.equal(expected.length, 17);
+ assert.deepEqual(expected[0], { _id: "Inclusion & Diversity in Open Source", entries: 10 });
+ let actualPipeline;
+ const db = { collection(name) { return {
+ async findOne() { assert.equal(name, "workshop_meta"); return { _id: "catalog", fingerprint: catalog.fingerprint, version: catalog.version }; },
+ aggregate(stages, options) { actualPipeline = stages; assert.equal(options.maxTimeMS, 5000); return { async toArray() { return expected; } }; },
+ }; } };
+ assert.deepEqual((await programCounts(db, programCountsPipeline)).rows, expected);
+ assert.deepEqual(actualPipeline.at(-1), { $limit: 30 });
+ for (const stage of ["$out", "$merge", "$lookup", "$unionWith"]) {
+ assert.throws(() => validatePipeline([{ [stage]: "forbidden" }]), { code: "READ_ONLY_PIPELINE" });
+ }
+});
diff --git a/test/http.test.js b/test/http.test.js
index 2395839..b99b573 100644
--- a/test/http.test.js
+++ b/test/http.test.js
@@ -8,7 +8,7 @@ test("HTTP target changes are explicit; errors are sanitized and writes require
const calls = [];
const config = { activeTarget: "local", mode: "complete", location: "laptop", targets: { local: {} } };
const connections = {
- db(target) {
+ async db(target) {
calls.push(target);
if (target !== "local") throw new WorkshopError(409, "TARGET_NOT_CONFIGURED", "No cloud target.");
return { command: async () => ({ ok: 1 }) };
@@ -55,7 +55,7 @@ test("unavailable Site B does not switch the active target or fall back after a
const app = await createApp({
config, repository: {}, logger: { error() {} },
connections: {
- db(target) {
+ async db(target) {
calls.push(target);
return { async command() {
if (target === "site-b" && unavailable) {
diff --git a/test/reconnect-interruption.integration.js b/test/reconnect-interruption.integration.js
new file mode 100644
index 0000000..14a8070
--- /dev/null
+++ b/test/reconnect-interruption.integration.js
@@ -0,0 +1,75 @@
+// Opt-in Docker-host test; NOT part of offline npm test or the app container's
+// database suite. Every subprocess creates its own random project and .env.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn, execFile } from "node:child_process";
+import { access } from "node:fs/promises";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const execute = promisify(execFile);
+for (const signal of ["SIGTERM", "SIGINT"]) {
+ test(`${signal} routes through owned cleanup; a repeated signal cannot interrupt cleanup`, { timeout: 780000 }, async () => {
+ const child = spawn(process.execPath, ["scripts/test-reconnect.mjs"], {
+ cwd: root, stdio: ["ignore", "pipe", "pipe"],
+ });
+ const events = [];
+ let ownership;
+ let repeated = false;
+ let timedOut = false;
+ let force;
+ const timer = setTimeout(() => {
+ timedOut = true;
+ child.kill("SIGTERM");
+ force = setTimeout(() => child.kill("SIGKILL"), 180000);
+ }, 600000);
+ const closed = new Promise((resolve, reject) => {
+ child.once("error", reject);
+ child.once("close", (code, exitSignal) => resolve({ code, exitSignal }));
+ });
+ // Only parsed harness receipts, never raw child/driver/Compose output.
+ const read = async (stream) => {
+ for await (const line of createInterface({ input: stream })) {
+ let event;
+ try { event = JSON.parse(line); } catch { continue; }
+ events.push(event);
+ if (event.check === "owned-ephemeral-project-ready") {
+ ownership = event;
+ child.kill(signal);
+ }
+ if (event.event === "owned-cleanup-started" && ownership) {
+ repeated = child.kill(signal);
+ }
+ }
+ };
+ try {
+ const readers = Promise.all([read(child.stdout), read(child.stderr)]);
+ const result = await closed;
+ await readers;
+ assert.equal(timedOut, false, "Harness did not reach its owned-project checkpoint within the startup budget");
+ assert.ok(ownership, "No owned-project receipt");
+ assert.match(ownership.project, /^ato-reconnect-[a-f0-9]{32}$/);
+ assert.equal(repeated, true, "Did not send a second signal during cleanup");
+ assert.equal(result.exitSignal, null, "Harness exited via default signal termination instead of cleanup");
+ assert.equal(result.code, signal === "SIGINT" ? 130 : 143);
+ assert.ok(!events.some(({ error }) => error === "OWN_PROJECT_CLEANUP_FAILED"), "Harness reported cleanup failure");
+ const cleaned = events.find(({ check }) => check === "only-owned-ephemeral-project-cleaned");
+ assert.equal(cleaned?.project, ownership.project);
+ assert.equal(cleaned?.privateDirectoryRemoved, true);
+ for (const list of [["ps", "-aq"], ["volume", "ls", "-q"], ["network", "ls", "-q"]]) {
+ // Independently verify every resource family, narrowly by the generated
+ // project label. This test does not adopt/delete any pre-existing stack.
+ const { stdout } = await execute("docker", [...list, "--filter", `label=com.docker.compose.project=${ownership.project}`], { timeout: 15000 });
+ assert.equal(stdout.trim(), "", "Owned resources remain after interruption");
+ }
+ await assert.rejects(access(ownership.privateDirectory), { code: "ENOENT" });
+ console.log(JSON.stringify({ check: "signal-cleanup-independently-verified", signal, project: ownership.project,
+ containers: 0, volumes: 0, networks: 0, privateDirectoryRemoved: true, exitCode: result.code }));
+ } finally {
+ clearTimeout(timer); clearTimeout(force);
+ if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+ }
+ });
+}
diff --git a/test/reconnect.probe.mjs b/test/reconnect.probe.mjs
new file mode 100644
index 0000000..98b7f5b
--- /dev/null
+++ b/test/reconnect.probe.mjs
@@ -0,0 +1,43 @@
+// Internal live harness helper, run inside its OWN disposable Compose project.
+// JSON lines keep one connection manager alive across host-controlled outages.
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { createInterface } from "node:readline";
+import { readConfig } from "../src/config.js";
+import { createConnections } from "../src/connections.js";
+
+const config = readConfig();
+assert.equal(config.scenario, "attendee");
+const connections = createConnections(config);
+try {
+ if (process.argv[2] === "snapshot") {
+ const result = {};
+ for (const target of ["local", "site-b"]) {
+ const db = await connections.db(target);
+ const favorites = await db.collection("favorites").find({}).sort({ _id: 1 }).toArray();
+ result[target] = {
+ sessions: await db.collection("sessions").countDocuments(),
+ favorites: favorites.length,
+ favoriteDigest: createHash("sha256").update(JSON.stringify(favorites)).digest("hex"),
+ };
+ }
+ console.log(JSON.stringify(result));
+ } else {
+ console.log(JSON.stringify({ ready: true, pid: process.pid }));
+ for await (const line of createInterface({ input: process.stdin })) {
+ const { expected } = JSON.parse(line);
+ assert.ok(["ready", "unavailable"].includes(expected));
+ const outcomes = await Promise.allSettled(Array.from({ length: 3 }, async () => {
+ const db = await connections.db("site-b");
+ await db.command({ ping: 1 });
+ }));
+ assert.ok(outcomes.every(({ status }) => status === (expected === "ready" ? "fulfilled" : "rejected")));
+ if (expected === "unavailable") assert.ok(outcomes.every(({ reason }) => reason.name?.startsWith("Mongo")));
+ console.log(JSON.stringify({ expected, concurrent: 3, passed: true, pid: process.pid }));
+ }
+ }
+} catch {
+ // Never print a driver's raw message, URI, stack, or supplied input.
+ console.error(JSON.stringify({ error: "RECONNECT_PROBE_FAILED" }));
+ process.exitCode = 1;
+} finally { await connections.close(); }
diff --git a/test/regression-safety.test.js b/test/regression-safety.test.js
new file mode 100644
index 0000000..3d9bdd3
--- /dev/null
+++ b/test/regression-safety.test.js
@@ -0,0 +1,61 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+
+// These are packaging/scope guards, not substitutes for the live outage test.
+test("live reconnect harness owns a fresh project and never targets an attendee stack", async () => {
+ const source = await readFile(new URL("../scripts/test-reconnect.mjs", import.meta.url), "utf8");
+ assert.match(source, /const project = `ato-reconnect-\$\{randomUUID\(\)/);
+ assert.match(source, /"--project-name", project/);
+ assert.match(source, /"--env-file", join\(directory, "\.env"\)/);
+ assert.match(source, /await setup\(directory, \{\},/);
+ assert.match(source, /delete env\[key\]/);
+ assert.match(source, /127\.0\.0\.1::3000/);
+ assert.match(source, /if \(owned\)/);
+ assert.match(source, /\[\.\.\.base, "down", "--volumes"/);
+ assert.doesNotMatch(source, /system.*prune|volume.*prune|docker.*kill.*\$\(/);
+ assert.match(source, /await appIdentity\(\), identity/);
+ assert.match(source, /waiter\.result/);
+ assert.match(source, /assert\.deepEqual\(await snapshot\(\), before\)/);
+});
+
+test("interruptions share cancellable work and verified, signal-resistant owned cleanup", async () => {
+ const source = await readFile(new URL("../scripts/test-reconnect.mjs", import.meta.url), "utf8");
+ assert.match(source, /process\.on\("SIGINT", onSignal\)/);
+ assert.match(source, /process\.on\("SIGTERM", onSignal\)/);
+ assert.match(source, /AbortSignal\.any\(\[interrupted\.signal, AbortSignal\.timeout\(20000\)\]\)/);
+ assert.match(source, /return cleanupPromise \|\|=/);
+ assert.match(source, /if \(!running\.cleanup\) running\.cancel\(\)/);
+ assert.match(source, /child\.kill\("SIGKILL"\), 5000/);
+ assert.match(source, /await Promise\.all\(pending\.map/);
+ assert.match(source, /assert\.ok\(cleanup\.ok && empty/);
+ const cleanup = source.slice(source.indexOf("function cleanupOwned()"));
+ for (const command of ['["ps", "-aq"]', '["volume", "ls", "-q"]', '["network", "ls", "-q"]']) {
+ assert.ok(cleanup.includes(command));
+ }
+ assert.ok(cleanup.indexOf("cleanup.ok && empty") < cleanup.indexOf("await rm(directory"));
+ assert.match(cleanup, /OWN_PROJECT_CLEANUP_FAILED/);
+});
+
+test("runtime image includes all live harness fixtures and optional exercises", async () => {
+ const dockerfile = await readFile(new URL("../Dockerfile", import.meta.url), "utf8");
+ for (const directory of ["src", "scripts", "test", "examples", "exercises", "data"]) {
+ assert.ok(dockerfile.includes(`COPY --chown=node:node ${directory} ./${directory}`));
+ }
+ // Root-only docs checks must stay separate: Docker intentionally omits docs.
+ const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+ assert.equal(pkg.scripts.test, "node --test test/*.test.js");
+ assert.equal(pkg.scripts["test:docs"], "node scripts/check-doc-links.mjs");
+});
+
+test("persistent guide and calendar links keep accessible labels and safe new-tab navigation", async () => {
+ const html = await readFile(new URL("../src/public/index.html", import.meta.url), "utf8");
+ assert.match(html, /Attendee guide \(opens new tab\)/);
+ assert.match(html, /Google Calendar \/ Apple Calendar import steps/);
+ assert.match(html, /id="exercise" role="status" aria-labelledby="exercise-title"/);
+ assert.match(html, /id="error" role="alert"/);
+ assert.match(html, /id="status" role="status"/);
+ for (const [, anchor] of html.matchAll(/(]+)>/g)) {
+ if (anchor.includes('target="_blank"')) assert.ok(anchor.includes('rel="noopener noreferrer"'));
+ }
+});