From eb90e09682c63d2832dc3b904657aa8ebde9dd52 Mon Sep 17 00:00:00 2001 From: Aqib Nawab Date: Wed, 18 Nov 2026 13:20:16 +0500 Subject: [PATCH 1/2] Add the daily games: System Design Runner, Linux Command Explorer, Docker Commands Three browser games in /puzzles, three rounds each (easy, medium, hard), new every day and the same for everyone. Each round a learner solves for the first time that day earns 3 XP, and finishing all three rounds of one game earns 2 more (33 XP a day at most). A visitor can play without an account. Framework: - shared/games: the GameEngine contract, deterministic daily rotation, and one pure engine per game. The browser plays with the engine for instant feedback, and the server replays the submission with the same engine before it records the round or pays XP. - GamePlay table (migration), game_round and game_set XP sources, a /api/v1/games API (daily set, submit a round), unit and API tests. - Shell: round tabs, result with stars, XP chip and confetti, a mute switch, synthesized sound effects, and a terminal component for the command games. Games: - System Design Runner: 12 AWS incident scenarios (cost, right-sizing, latency, outages, hot keys). Pick a limited set of changes and run a 24-hour traffic simulation against latency, availability and cost goals. - Linux Command Explorer: 14 terminal missions on a made-up server with a shell of about 45 commands, pipes, redirects and permissions. - Docker Commands: 16 scenarios in two modes, a fix-the-container terminal with a live dock view and a visual Dockerfile and compose builder. /puzzles now lists the games instead of the coming soon page. --- docs/14-gamification.mdx | 2 + docs/16-learning-areas.mdx | 17 +- docs/17-daily-games.mdx | 40 + docs/README.mdx | 1 + .../(learn)/(catalog)/puzzles/[game]/page.tsx | 27 + .../app/(learn)/(catalog)/puzzles/page.tsx | 86 +- frontend/src/components/games/celebration.tsx | 97 + .../components/games/docker/build-play.tsx | 500 +++++ .../src/components/games/docker/dock-view.tsx | 223 +++ .../components/games/docker/docker-play.tsx | 25 + .../components/games/docker/docker-styles.tsx | 33 + .../src/components/games/docker/fix-play.tsx | 153 ++ .../components/games/docker/mission-panel.tsx | 76 + frontend/src/components/games/game-host.tsx | 220 +++ .../src/components/games/game-terminal.tsx | 128 ++ frontend/src/components/games/games-hub.tsx | 94 + .../src/components/games/linux/linux-play.tsx | 184 ++ .../components/games/linux/mission-panel.tsx | 169 ++ frontend/src/components/games/registry.tsx | 14 + .../components/games/sysdesign/diagram.tsx | 247 +++ .../games/sysdesign/sysdesign-play.tsx | 420 +++++ frontend/src/components/games/types.ts | 19 + frontend/src/lib/games/audio.ts | 155 ++ frontend/src/lib/games/client.ts | 13 + frontend/src/lib/learn-areas.ts | 6 +- frontend/src/shared/api/games.ts | 46 + frontend/src/shared/games/daily.ts | 45 + frontend/src/shared/games/docker/builder.ts | 484 +++++ frontend/src/shared/games/docker/daemon.ts | 1453 +++++++++++++++ frontend/src/shared/games/docker/engine.ts | 145 ++ frontend/src/shared/games/docker/scenarios.ts | 503 +++++ frontend/src/shared/games/index.ts | 19 + frontend/src/shared/games/linux/commands.ts | 1642 +++++++++++++++++ frontend/src/shared/games/linux/engine.ts | 108 ++ frontend/src/shared/games/linux/fs.ts | 362 ++++ frontend/src/shared/games/linux/missions.ts | 589 ++++++ frontend/src/shared/games/linux/model.ts | 92 + frontend/src/shared/games/linux/regex.ts | 496 +++++ frontend/src/shared/games/linux/shell.ts | 942 ++++++++++ frontend/src/shared/games/sysdesign/engine.ts | 74 + .../src/shared/games/sysdesign/scenarios.ts | 394 ++++ frontend/src/shared/games/sysdesign/sim.ts | 277 +++ frontend/src/shared/games/sysdesign/types.ts | 167 ++ frontend/src/shared/games/types.ts | 54 + frontend/src/shared/gamification/xp.ts | 11 + .../20261118120000_game_plays/migration.sql | 24 + server/prisma/schema.prisma | 789 ++++---- server/src/controllers/games.ts | 14 + server/src/routes/v1/games.ts | 21 + server/src/routes/v1/index.ts | 2 + server/src/services/games/daily.ts | 76 + server/src/shared/api/games.ts | 45 + server/src/shared/games/daily.ts | 44 + server/src/shared/games/docker/builder.ts | 483 +++++ server/src/shared/games/docker/daemon.ts | 1452 +++++++++++++++ server/src/shared/games/docker/engine.ts | 144 ++ server/src/shared/games/docker/scenarios.ts | 502 +++++ server/src/shared/games/index.ts | 18 + server/src/shared/games/linux/commands.ts | 1641 ++++++++++++++++ server/src/shared/games/linux/engine.ts | 107 ++ server/src/shared/games/linux/fs.ts | 361 ++++ server/src/shared/games/linux/missions.ts | 588 ++++++ server/src/shared/games/linux/model.ts | 91 + server/src/shared/games/linux/regex.ts | 495 +++++ server/src/shared/games/linux/shell.ts | 941 ++++++++++ server/src/shared/games/sysdesign/engine.ts | 73 + .../src/shared/games/sysdesign/scenarios.ts | 393 ++++ server/src/shared/games/sysdesign/sim.ts | 276 +++ server/src/shared/games/sysdesign/types.ts | 166 ++ server/src/shared/games/types.ts | 53 + server/src/shared/gamification/xp.ts | 11 + server/src/validations/games.ts | 11 + server/tests/api/games.test.ts | 97 + server/tests/unit/shared/games/daily.test.ts | 74 + server/tests/unit/shared/games/docker.test.ts | 344 ++++ server/tests/unit/shared/games/linux.test.ts | 463 +++++ .../tests/unit/shared/games/sysdesign.test.ts | 186 ++ 77 files changed, 20362 insertions(+), 475 deletions(-) create mode 100644 docs/17-daily-games.mdx create mode 100644 frontend/src/app/(learn)/(catalog)/puzzles/[game]/page.tsx create mode 100644 frontend/src/components/games/celebration.tsx create mode 100644 frontend/src/components/games/docker/build-play.tsx create mode 100644 frontend/src/components/games/docker/dock-view.tsx create mode 100644 frontend/src/components/games/docker/docker-play.tsx create mode 100644 frontend/src/components/games/docker/docker-styles.tsx create mode 100644 frontend/src/components/games/docker/fix-play.tsx create mode 100644 frontend/src/components/games/docker/mission-panel.tsx create mode 100644 frontend/src/components/games/game-host.tsx create mode 100644 frontend/src/components/games/game-terminal.tsx create mode 100644 frontend/src/components/games/games-hub.tsx create mode 100644 frontend/src/components/games/linux/linux-play.tsx create mode 100644 frontend/src/components/games/linux/mission-panel.tsx create mode 100644 frontend/src/components/games/registry.tsx create mode 100644 frontend/src/components/games/sysdesign/diagram.tsx create mode 100644 frontend/src/components/games/sysdesign/sysdesign-play.tsx create mode 100644 frontend/src/components/games/types.ts create mode 100644 frontend/src/lib/games/audio.ts create mode 100644 frontend/src/lib/games/client.ts create mode 100644 frontend/src/shared/api/games.ts create mode 100644 frontend/src/shared/games/daily.ts create mode 100644 frontend/src/shared/games/docker/builder.ts create mode 100644 frontend/src/shared/games/docker/daemon.ts create mode 100644 frontend/src/shared/games/docker/engine.ts create mode 100644 frontend/src/shared/games/docker/scenarios.ts create mode 100644 frontend/src/shared/games/index.ts create mode 100644 frontend/src/shared/games/linux/commands.ts create mode 100644 frontend/src/shared/games/linux/engine.ts create mode 100644 frontend/src/shared/games/linux/fs.ts create mode 100644 frontend/src/shared/games/linux/missions.ts create mode 100644 frontend/src/shared/games/linux/model.ts create mode 100644 frontend/src/shared/games/linux/regex.ts create mode 100644 frontend/src/shared/games/linux/shell.ts create mode 100644 frontend/src/shared/games/sysdesign/engine.ts create mode 100644 frontend/src/shared/games/sysdesign/scenarios.ts create mode 100644 frontend/src/shared/games/sysdesign/sim.ts create mode 100644 frontend/src/shared/games/sysdesign/types.ts create mode 100644 frontend/src/shared/games/types.ts create mode 100644 server/prisma/migrations/20261118120000_game_plays/migration.sql create mode 100644 server/src/controllers/games.ts create mode 100644 server/src/routes/v1/games.ts create mode 100644 server/src/services/games/daily.ts create mode 100644 server/src/shared/api/games.ts create mode 100644 server/src/shared/games/daily.ts create mode 100644 server/src/shared/games/docker/builder.ts create mode 100644 server/src/shared/games/docker/daemon.ts create mode 100644 server/src/shared/games/docker/engine.ts create mode 100644 server/src/shared/games/docker/scenarios.ts create mode 100644 server/src/shared/games/index.ts create mode 100644 server/src/shared/games/linux/commands.ts create mode 100644 server/src/shared/games/linux/engine.ts create mode 100644 server/src/shared/games/linux/fs.ts create mode 100644 server/src/shared/games/linux/missions.ts create mode 100644 server/src/shared/games/linux/model.ts create mode 100644 server/src/shared/games/linux/regex.ts create mode 100644 server/src/shared/games/linux/shell.ts create mode 100644 server/src/shared/games/sysdesign/engine.ts create mode 100644 server/src/shared/games/sysdesign/scenarios.ts create mode 100644 server/src/shared/games/sysdesign/sim.ts create mode 100644 server/src/shared/games/sysdesign/types.ts create mode 100644 server/src/shared/games/types.ts create mode 100644 server/src/validations/games.ts create mode 100644 server/tests/api/games.test.ts create mode 100644 server/tests/unit/shared/games/daily.test.ts create mode 100644 server/tests/unit/shared/games/docker.test.ts create mode 100644 server/tests/unit/shared/games/linux.test.ts create mode 100644 server/tests/unit/shared/games/sysdesign.test.ts diff --git a/docs/14-gamification.mdx b/docs/14-gamification.mdx index 14f6ae77..d1b80017 100644 --- a/docs/14-gamification.mdx +++ b/docs/14-gamification.mdx @@ -55,6 +55,8 @@ Amounts are data in `shared/gamification/xp.ts`: | Open answer approved by a mentor | 15 | `answer:` | | Course completed | 100 | `course:` | | Weekly goal met | 25 | `weekly_goal:` | +| Daily game round solved (first time that day) | 3, 9 a day at most | `game_round:::` | +| All three rounds of one daily game in a day | +2 | `game_set::` | Logging in and raw time never earn XP. diff --git a/docs/16-learning-areas.mdx b/docs/16-learning-areas.mdx index 0969e68b..ca25772d 100644 --- a/docs/16-learning-areas.mdx +++ b/docs/16-learning-areas.mdx @@ -21,7 +21,7 @@ area section is written so one work session can pick it up on its own. | Audiobooks | `/audiobooks`, `/audiobooks/[course]` | Open | Every narrated course as an audiobook, with a player that follows you across pages. | | Labs | `/labs` | Partly open | Visual and guided labs open; shell labs planned. | | Bite-sized practice | `/practice` | Coming soon | One topic a few minutes a day, led by questions. | -| Puzzles | `/puzzles` | Coming soon | Several kinds of daily puzzle. | +| Puzzles | `/puzzles` | Live | Three daily games: System Design Runner, Linux Command Explorer, Docker Commands ([`17-daily-games.mdx`](17-daily-games.mdx)). | | On-call tutors | `/voice` | Coming soon | A voice tutor per topic that tracks progress across its modules. | Lab kinds, under `/labs`: @@ -56,7 +56,7 @@ frontend/src/app/(learn)/(catalog)/ guided/ Guided labs (the Dev Weekends tracks, from `lib/guided-labs.ts`) shell/ Shell labs and the desktop app docs (coming soon page) practice/ Bite-sized practice (coming soon page) - puzzles/ Puzzles (coming soon page) + puzzles/ Daily games hub and one page per game voice/ On-call tutors (coming soon page) ``` @@ -203,18 +203,9 @@ spaced review queue (wrong answers come back after a few days, then less often). [`05-review-queue.mdx`](05-review-queue.mdx). - Rewards: XP and streak credit through [`14-gamification.mdx`](14-gamification.mdx). -## Puzzles (planned) +## Puzzles (live) -Several kinds of daily puzzle that use course ideas, one a day, the same for everyone. - -- Kinds to start with: find the bottleneck, trace the request (order the steps), fix the diagram, - odd one out. Each kind is a small client component with a server-checked answer. -- Model: `Puzzle { id, kind, date, data, answer (server only), clues[] }` and - `PuzzleAttempt { userId, puzzleId, tries, solvedAt }`. A wrong try reveals the next clue. -- The diagram kinds can reuse the lab board model in `packages/learning-ui/src/labs/` for drawing - and checking. -- Leaderboard: the mobile app adds a daily leaderboard later. It must be opt-in, like the weekly - leaderboards. +The puzzles area is now the daily games: three browser games with three rounds each, the same for everyone, each solved round earning a little XP. How they are built, how XP works and how to add a game is in [`17-daily-games.mdx`](17-daily-games.mdx). The earlier plan for four puzzle kinds (find the bottleneck, trace the request, fix the diagram, odd one out) can become a fourth game on the same framework. A daily leaderboard stays an opt-in later step, like the weekly ones. ## On-call tutors (planned) diff --git a/docs/17-daily-games.mdx b/docs/17-daily-games.mdx new file mode 100644 index 00000000..a61e9ac4 --- /dev/null +++ b/docs/17-daily-games.mdx @@ -0,0 +1,40 @@ +--- +title: Daily games +status: framework and three games in progress (2026-11-18) +--- + +# Daily games + +Three short browser games every day, inside `/puzzles`: **System Design Runner**, **Linux Command Explorer** and **Docker Commands**. Each game has three rounds a day (easy, medium, hard), the same for everyone. Each round solved for the first time that day gives a little XP, and finishing all three rounds of one game gives a small bonus. + +## XP + +Amounts live in `server/src/shared/gamification/xp.ts` (change a number there and every client agrees): `game_round` 3 XP, `game_set` 2 XP. The most the games give in a day is 33 XP. A replayed round gives nothing. Keys are `game_round:::` and `game_set::`, so XP is paid once. Only learners (role MENTEE) earn XP; a visitor can play without an account and sees a prompt to sign in. + +## How a game is built + +A game is a **pure, deterministic engine** in `server/src/shared/games//engine.ts` that implements `GameEngine` (`shared/games/types.ts`): + +- `roundsFor(dayKey)` returns today's three rounds (use `pickDaily` from `shared/games/daily.ts`, one scenario per difficulty, rotating through the pool). +- `parseSubmission(input)` narrows an unknown value from the network. It must be strict and never throw. +- `verify(round, submission)` replays the submission and returns `{ passed, stars, score, message }`. It must be pure, deterministic and never throw. No clock, no `Math.random` (use `seededRandom`), no DOM, no network. + +The same engine runs in the browser (instant feedback, animation) and on the server (`services/games/daily.ts` replays the submission before it records the round and awards XP). Engines are in `server/src/shared`, which `pnpm sync-shared` copies into `frontend/src/shared`. Never edit the copy. + +The browser part is a play component, `frontend/src/components/games//-play.tsx`, default export, props `GamePlayProps` (`components/games/types.ts`). It draws the board or terminal and calls `onFinish(submission)` when the player is done. The shell (`game-host.tsx`) verifies, plays the result sound, shows stars, XP and confetti, saves the round for a signed-in learner, and offers the next round. A play component must reset itself when `attempt` changes (the shell also remounts it with a new `key`), and must ignore input while `locked`. + +## Look and feel + +These are real games, not forms. Every game must have: + +- **Sound.** Use `sounds` from props (`lib/games/audio.ts`: `key`, `enter`, `ok`, `error`, `snap`, `coin`, `whoosh`, `alarm`, `boot`, `win`, `fanfare`, `lose`). Add new synthesized effects to that file if a game needs one (keep them short and quiet). Sound is off for people who ask for reduced motion, and the shell has a mute switch. +- **Motion with meaning:** packets flowing, bars filling, containers pulsing or shaking, layers stacking, counters ticking, shake on a mistake. Wrap decorative motion in `motion-safe:`; the game must still work with `motion-reduce`. +- **Feedback on every action** (sound plus a visible change), a clear goal, a visible progress or score, a hint that costs a star, and a short, friendly message when something is wrong. +- Use the Tailwind theme tokens (`bg-card`, `border-border`, `text-muted-foreground`, `bg-secondary`, `text-primary`, `brand-yellow`) so light and dark both work, and `GameTerminal` (`components/games/game-terminal.tsx`) for any terminal. Phone first: it must be playable at 375 px wide and with the keyboard alone, with labels on controls. +- No em dashes or en dashes in any text, comment or test. Plain, short English, for a learner who may read English as a second language. + +## Tests + +- Server: `cd server && pnpm exec vitest run tests/unit/shared/games` (pure engine tests: every scenario is solvable by its stated solution, wrong submissions fail, the daily rotation is deterministic and varies by day, `parseSubmission` rejects junk). +- Type checks: `cd server && pnpm exec tsc -p tsconfig.json --noEmit` and `cd frontend && pnpm exec tsc --noEmit -p .`. +- Look at it: `node /gameshot.mjs [width]` logs in as a learner and saves a screenshot of the page (dev stack: web http://localhost:3100, API http://localhost:4100). diff --git a/docs/README.mdx b/docs/README.mdx index 19b7a11c..cb5130c6 100644 --- a/docs/README.mdx +++ b/docs/README.mdx @@ -44,6 +44,7 @@ regardless of which part of the doc set you're working from. | [`13-engagement.mdx`](13-engagement.mdx) | Engagement events (`POST /api/v1/events`), mascot registry, roles, rules and the web player | | [`14-gamification.mdx`](14-gamification.mdx) | XP ledger, levels and module stages, streaks in the learner's timezone, streak freezes, weekly leaderboards, feature flags | | [`15-content-separation.mdx`](15-content-separation.mdx) | Private course source, publishing workflow, and public web/desktop compatibility | +| [`17-daily-games.mdx`](17-daily-games.mdx) | The daily games in `/puzzles`: the engine contract, XP rules, sound and animation rules, and how to add a game | | [`16-learning-areas.mdx`](16-learning-areas.mdx) | The five learner areas (courses, labs, practice, puzzles, voice agents), their routes and nav, and the build plan for each | ## Build phases diff --git a/frontend/src/app/(learn)/(catalog)/puzzles/[game]/page.tsx b/frontend/src/app/(learn)/(catalog)/puzzles/[game]/page.tsx new file mode 100644 index 00000000..84bdde72 --- /dev/null +++ b/frontend/src/app/(learn)/(catalog)/puzzles/[game]/page.tsx @@ -0,0 +1,27 @@ +import type { Metadata } from "next"; +import { notFound } from "next/navigation"; +import { GameHost } from "@/components/games/game-host"; +import { GAME_IDS, isGameId } from "@/shared/games/types"; + +const TITLES = { sysdesign: "System Design Runner", linux: "Linux Command Explorer", docker: "Docker Commands" } as const; + +export function generateStaticParams() { + return GAME_IDS.map((game) => ({ game })); +} + +export async function generateMetadata({ params }: { params: Promise<{ game: string }> }): Promise { + const { game } = await params; + if (!isGameId(game)) return {}; + return { title: `${TITLES[game]} - daily game`, alternates: { canonical: `/puzzles/${game}` } }; +} + +export default async function GamePage({ params }: { params: Promise<{ game: string }> }) { + const { game } = await params; + if (!isGameId(game)) notFound(); + return ( +
+

{TITLES[game]}

+ +
+ ); +} diff --git a/frontend/src/app/(learn)/(catalog)/puzzles/page.tsx b/frontend/src/app/(learn)/(catalog)/puzzles/page.tsx index ce9f4025..933f838a 100644 --- a/frontend/src/app/(learn)/(catalog)/puzzles/page.tsx +++ b/frontend/src/app/(learn)/(catalog)/puzzles/page.tsx @@ -1,94 +1,28 @@ import type { Metadata } from "next"; import { SITE_SHARE_IMAGE } from "@/lib/site"; import { areaById } from "@/lib/learn-areas"; -import { AreaHero, AreaPage, ComingSoonPanel } from "@/components/areas/area-page"; -import { FilterChips, pickFilter } from "@/components/areas/filter-chips"; +import { AreaHero, AreaPage } from "@/components/areas/area-page"; +import { GamesHub } from "@/components/games/games-hub"; export const metadata: Metadata = { - title: "Puzzles", - description: "A new puzzle every day, built on what you learn. The same puzzle for everyone, and a daily leaderboard to climb.", + title: "Daily games", + description: "Three short games every day: fix a broken system, explore a Linux server, repair a Docker container. A little XP for each round you solve.", alternates: { canonical: "/puzzles" }, - openGraph: { title: "Daily puzzles on Edorax", url: "/puzzles", images: [SITE_SHARE_IMAGE] }, + openGraph: { title: "Daily games on Edorax", url: "/puzzles", images: [SITE_SHARE_IMAGE] }, }; -// The kinds take turns through the week. Each has a one-line goal and an example of the day's prompt. -const KINDS = [ - { - id: "bottleneck", - label: "Find the bottleneck", - goal: "A small system is struggling. Tap the one part that gives out first.", - example: "Users → load balancer → two app servers → one database at 95% CPU. Checkout takes 9 seconds.", - }, - { - id: "trace", - label: "Trace the request", - goal: "Put the steps of a request in order, from the tap on a phone to the answer on screen.", - example: "DNS lookup · TLS handshake · cache miss · database read · response rendered", - }, - { - id: "fix", - label: "Fix the diagram", - goal: "One link or one part is wrong. Find it and fix it in as few moves as you can.", - example: "A queue sits between the browser and the load balancer. One move fixes it.", - }, - { - id: "odd", - label: "Odd one out", - goal: "Four ideas, one does not belong. Say which, and the reason appears.", - example: "Read replica · write-ahead log · CDN edge cache · sticky session", - }, -] as const; - -const RULES = [ - ["One a day", "New at midnight in your time zone. Yesterday's stays open to practise."], - ["A few tries", "Each wrong try shows a clue, so you learn something either way."], - ["Daily leaderboard", "Fewer tries and a faster solve rank higher. It resets every day; joining is your choice."], -] as const; - -type SearchParams = Promise>; - -export default async function PuzzlesPage({ searchParams }: { searchParams: SearchParams }) { +export default function PuzzlesPage() { const area = areaById("puzzles"); - const query = await searchParams; - const id = pickFilter(query.kind, KINDS.map((k) => k.id)) ?? KINDS[0].id; - const kind = KINDS.find((k) => k.id === id)!; - return ( - -
- ({ value: k.id, label: k.label }))} /> -
- -
-
- {kind.label} -

{kind.goal}

-

- Example: - {kind.example} -

-
-
- {RULES.map(([title, body]) => ( -
-
{title}
-
{body}
-
- ))} -
-
- - - The visual labs are the closest thing today: a design, a set of checks, and a reason for every result. - +
); } diff --git a/frontend/src/components/games/celebration.tsx b/frontend/src/components/games/celebration.tsx new file mode 100644 index 00000000..8704e92a --- /dev/null +++ b/frontend/src/components/games/celebration.tsx @@ -0,0 +1,97 @@ +"use client"; + +import { useEffect, useRef } from "react"; + +const COLORS = ["#1d4ed8", "#facc15", "#22c55e", "#f97316", "#ec4899", "#38bdf8"]; + +type Particle = { x: number; y: number; vx: number; vy: number; size: number; spin: number; angle: number; color: string; life: number }; + +/** + * A burst of confetti over the whole page for about 2.5 seconds. It draws on one canvas, does not + * catch clicks, and does nothing at all when the system asks for reduced motion. + */ +export function ConfettiBurst({ stars, burstKey }: { stars: number; burstKey: string }) { + const canvas = useRef(null); + + useEffect(() => { + const el = canvas.current; + if (!el || window.matchMedia("(prefers-reduced-motion: reduce)").matches) return; + const ctx = el.getContext("2d"); + if (!ctx) return; + const ratio = Math.min(window.devicePixelRatio || 1, 2); + el.width = window.innerWidth * ratio; + el.height = window.innerHeight * ratio; + ctx.scale(ratio, ratio); + + const count = 70 + Math.max(1, stars) * 45; + const particles: Particle[] = Array.from({ length: count }, (_, i) => { + const side = i % 2 === 0 ? 0.2 : 0.8; + const angle = (-Math.PI / 2) + (Math.random() - 0.5) * 1.5; + const speed = 8 + Math.random() * 10; + return { + x: window.innerWidth * side, y: window.innerHeight * 0.72, + vx: Math.cos(angle) * speed * (side < 0.5 ? 1 : -1) * 0.6, vy: Math.sin(angle) * speed, + size: 5 + Math.random() * 6, spin: (Math.random() - 0.5) * 0.4, angle: Math.random() * Math.PI, + color: COLORS[i % COLORS.length]!, life: 1, + }; + }); + + let frame = 0; + let raf = 0; + const tick = () => { + frame++; + ctx.clearRect(0, 0, window.innerWidth, window.innerHeight); + for (const p of particles) { + p.vy += 0.32; + p.vx *= 0.992; + p.x += p.vx; + p.y += p.vy; + p.angle += p.spin; + p.life = Math.max(0, 1 - frame / 150); + ctx.save(); + ctx.globalAlpha = p.life; + ctx.translate(p.x, p.y); + ctx.rotate(p.angle); + ctx.fillStyle = p.color; + ctx.fillRect(-p.size / 2, -p.size / 4, p.size, p.size / 2); + ctx.restore(); + } + if (frame < 150) raf = requestAnimationFrame(tick); + else ctx.clearRect(0, 0, window.innerWidth, window.innerHeight); + }; + raf = requestAnimationFrame(tick); + return () => cancelAnimationFrame(raf); + }, [stars, burstKey]); + + return ; +} + +/** Three stars that pop in one after another. Earned stars are filled. */ +export function StarRow({ stars, size = "lg" }: { stars: number; size?: "sm" | "lg" }) { + const box = size === "lg" ? "size-10" : "size-4"; + return ( +
+ {[1, 2, 3].map((n) => ( + + + + ))} +
+ ); +} + +/** "+3 XP" chip that floats up and settles. */ +export function XpChip({ amount, label }: { amount: number; label?: string }) { + if (amount <= 0) return null; + return ( + + +{amount} XP{label ? {label} : null} + + ); +} diff --git a/frontend/src/components/games/docker/build-play.tsx b/frontend/src/components/games/docker/build-play.tsx new file mode 100644 index 00000000..c52f36ac --- /dev/null +++ b/frontend/src/components/games/docker/build-play.tsx @@ -0,0 +1,500 @@ +"use client"; + +import { useCallback, useEffect, useMemo, useRef, useState, type DragEvent } from "react"; +import { AlertTriangle, ArrowDown, ArrowUp, CheckCircle2, Clock, Hammer, GripVertical, HardDrive, Layers, Play, X, Zap } from "lucide-react"; +import { Button } from "@/components/ui/button"; +import { cn } from "@/lib/utils"; +import type { GameSounds } from "@/lib/games/audio"; +import { checkBuildGoal, simulateBuild, type BuildGoal, type BuildLayer, type BuildReport } from "@/shared/games/docker/builder"; +import type { BuildRound, BuildSubmission } from "@/shared/games/docker/engine"; +import { MissionPanel } from "./mission-panel"; +import { useReducedMotion } from "./docker-styles"; + +type Props = { + round: BuildRound; + attempt: number; + locked: boolean; + sounds: GameSounds; + onFinish: (submission: BuildSubmission) => void; +}; + +type Phase = "edit" | "cold" | "rebuild" | "built" | "running" | "ran"; + +const RUN_GOALS = new Set(["runs", "reachable"]); + +function layerTone(label: string): string { + const word = label.split(/[\s:]/)[0]?.toUpperCase() ?? ""; + if (word === "FROM") return "border-sky-500/60 bg-sky-500/10"; + if (word === "COPY") return "border-amber-500/60 bg-amber-500/10"; + if (word === "RUN") return "border-violet-500/60 bg-violet-500/10"; + return "border-border bg-secondary/60"; +} + +function seconds(n: number) { + return `${n.toFixed(1)} s`; +} + +function LayerStack({ layers, mode, total }: { layers: BuildLayer[]; mode: "cold" | "rebuild"; total: number }) { + return ( +
    + {layers.map((layer, i) => ( +
  1. + + {layer.label} + {mode === "rebuild" ? ( + {layer.cached ? "CACHED" : "REBUILT"} + ) : null} + + {mode === "rebuild" ? (layer.cached ? "0.1 s" : seconds(layer.seconds)) : `${layer.sizeMb > 0 ? `+${layer.sizeMb} MB, ` : ""}${seconds(layer.seconds)}`} + + {layer.failed ? : null} +
  2. + ))} + {layers.length === 0 ?
  3. Waiting for the first layer ({total} in all)...
  4. : null} +
+ ); +} + +function Tile({ icon, label, value, tone }: { icon: React.ReactNode; label: string; value: string; tone?: "good" | "bad" }) { + return ( +
+

{icon} {label}

+

{value}

+
+ ); +} + +/** Build mode: put a Dockerfile or a compose file together from pieces, build it, then run it. */ +export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { + const compose = round.kind === "compose"; + const reduced = useReducedMotion(); + const [steps, setSteps] = useState([]); + const [picks, setPicks] = useState>({}); + const [activeSlot, setActiveSlot] = useState(round.slots?.[0]?.id ?? ""); + const [hintsUsed, setHintsUsed] = useState(0); + const [phase, setPhase] = useState("edit"); + const [report, setReport] = useState(null); + const [coldShown, setColdShown] = useState(0); + const [rebuildShown, setRebuildShown] = useState(0); + const [runShown, setRunShown] = useState(0); + const [note, setNote] = useState(null); + const [dragOver, setDragOver] = useState(null); + const timers = useRef([]); + const firstAttempt = useRef(attempt); + + const byId = useMemo(() => new Map(round.pieces.map((p) => [p.id, p])), [round.pieces]); + const slots = round.slots ?? []; + const submissionSteps = useMemo( + () => (compose ? slots.filter((s) => picks[s.id]).map((s) => `${s.id}:${picks[s.id]}`) : steps), + [compose, slots, picks, steps], + ); + const placed = compose ? Object.keys(picks).length : steps.length; + + const clearTimers = useCallback(() => { + timers.current.forEach((t) => window.clearTimeout(t)); + timers.current = []; + }, []); + useEffect(() => clearTimers, [clearTimers]); + const later = useCallback((fn: () => void, ms: number) => { + timers.current.push(window.setTimeout(fn, ms)); + }, []); + + /** Any change to the pieces throws away the last build, like editing a file does. */ + const invalidate = useCallback(() => { + clearTimers(); + setPhase("edit"); + setReport(null); + setColdShown(0); + setRebuildShown(0); + setRunShown(0); + setNote(null); + }, [clearTimers]); + + const resetAll = useCallback(() => { + invalidate(); + setSteps([]); + setPicks({}); + setActiveSlot(round.slots?.[0]?.id ?? ""); + }, [invalidate, round.slots]); + + useEffect(() => { + if (attempt !== firstAttempt.current) { + firstAttempt.current = attempt; + resetAll(); + setHintsUsed(0); + } + }, [attempt, resetAll]); + + // ---- Dockerfile editing ------------------------------------------------------------------- + function addPiece(id: string, at?: number) { + if (locked || steps.includes(id)) return; + invalidate(); + setSteps((s) => { + if (s.includes(id)) return s; + const next = [...s]; + next.splice(at === undefined ? next.length : Math.min(at, next.length), 0, id); + return next; + }); + sounds.snap(); + } + function movePiece(from: number, to: number) { + if (locked || to < 0 || to >= steps.length || from === to) return; + invalidate(); + setSteps((s) => { + const next = [...s]; + const [item] = next.splice(from, 1); + next.splice(to, 0, item!); + return next; + }); + sounds.snap(); + } + function removePiece(index: number) { + if (locked) return; + invalidate(); + setSteps((s) => s.filter((_, i) => i !== index)); + sounds.whoosh(); + } + + function onDragStart(event: DragEvent, payload: string) { + event.dataTransfer.setData("text/plain", payload); + event.dataTransfer.effectAllowed = "move"; + } + function onDropAt(event: DragEvent, index: number) { + event.preventDefault(); + event.stopPropagation(); + setDragOver(null); + const payload = event.dataTransfer.getData("text/plain"); + if (payload.startsWith("tray:")) addPiece(payload.slice(5), index); + else if (payload.startsWith("row:")) { + const from = Number(payload.slice(4)); + if (Number.isInteger(from)) movePiece(from, index > from ? index - 1 : index); + } + } + function onDropTray(event: DragEvent) { + event.preventDefault(); + const payload = event.dataTransfer.getData("text/plain"); + if (payload.startsWith("row:")) removePiece(Number(payload.slice(4))); + } + + // ---- Compose editing ---------------------------------------------------------------------- + function pickPiece(slot: string, id: string) { + if (locked) return; + invalidate(); + setPicks((p) => ({ ...p, [slot]: id })); + sounds.snap(); + const next = slots.find((s) => s.id !== slot && !picks[s.id] && slots.indexOf(s) > slots.findIndex((x) => x.id === slot)) ?? slots.find((s) => s.id !== slot && !picks[s.id]); + if (next) setActiveSlot(next.id); + } + function dropOnSlot(event: DragEvent, slot: string) { + event.preventDefault(); + const payload = event.dataTransfer.getData("text/plain"); + if (!payload.startsWith("tray:")) return; + const piece = byId.get(payload.slice(5)); + if (piece?.slot === slot) pickPiece(slot, piece.id); + else { + sounds.error(); + setNote("That piece belongs to a different blank."); + } + } + + // ---- Build and run ------------------------------------------------------------------------ + function build() { + if (locked || submissionSteps.length === 0) return; + clearTimers(); + const result = simulateBuild(round, submissionSteps); + setReport(result); + setNote(null); + setRunShown(0); + setRebuildShown(0); + const layers = result.layers; + if (reduced) { + setColdShown(layers.length); + setRebuildShown(result.ok && !compose ? layers.length : 0); + setPhase("built"); + result.ok ? sounds.ok() : sounds.error(); + return; + } + setColdShown(0); + setPhase("cold"); + sounds.whoosh(); + layers.forEach((_, i) => later(() => { setColdShown(i + 1); sounds.snap(); }, 420 * (i + 1))); + const coldEnd = 420 * (layers.length + 1); + if (!result.ok || compose) { + later(() => { + setPhase("built"); + result.ok ? sounds.ok() : sounds.error(); + }, coldEnd); + return; + } + later(() => { setPhase("rebuild"); setRebuildShown(0); sounds.whoosh(); }, coldEnd + 200); + let at = coldEnd + 200; + layers.forEach((layer, i) => { + at += layer.cached ? 160 : 420; + later(() => { setRebuildShown(i + 1); layer.cached ? sounds.coin() : sounds.snap(); }, at); + }); + later(() => { setPhase("built"); sounds.ok(); }, at + 250); + } + + function run() { + if (locked || !report || !report.ok) return; + clearTimers(); + setRunShown(0); + setPhase("running"); + sounds.boot(); + const total = report.runLog.length; + const finish = () => { + setPhase("ran"); + report.started && report.reachable ? sounds.win(2) : sounds.error(); + }; + if (reduced || total === 0) { + setRunShown(total); + return finish(); + } + report.runLog.forEach((_, i) => later(() => { setRunShown(i + 1); sounds.key(); }, 500 * (i + 1))); + later(finish, 500 * (total + 1)); + } + + function revealHint() { + if (hintsUsed >= round.hints.length) return; + setHintsUsed(hintsUsed + 1); + sounds.ok(); + } + + const ranOrBuilt = phase === "built" || phase === "running" || phase === "ran"; + const goals = round.goals.map((g) => { + if (!report) return { label: g.label, met: null }; + if (RUN_GOALS.has(g.kind) && phase !== "ran") return { label: g.label, met: null }; + if (phase === "cold" || phase === "rebuild") return { label: g.label, met: null }; + return { label: g.label, met: checkBuildGoal(report, g) }; + }); + const allMet = phase === "ran" && goals.every((g) => g.met); + const unplaced = round.pieces.filter((p) => !steps.includes(p.id)); + const slotPieces = round.pieces.filter((p) => p.slot === activeSlot); + const busy = phase === "cold" || phase === "rebuild" || phase === "running"; + + const coldLayers = report ? report.layers.slice(0, coldShown) : []; + const coldDone = report !== null && coldShown >= report.layers.length; + const pct = report && report.layers.length ? Math.round((coldShown / report.layers.length) * 100) : 0; + const rebuildLayers = report ? report.layers.slice(0, rebuildShown) : []; + const rebuildTime = rebuildLayers.reduce((sum, l) => sum + (l.cached ? 0.1 : l.seconds), 0); + const coldTime = coldLayers.reduce((sum, l) => sum + l.seconds, 0); + const rebuildActive = report?.ok && !compose && (phase === "rebuild" || ranOrBuilt); + + const tray = ( +
e.preventDefault()} + onDrop={onDropTray} + > +

+ {compose ? `Choices for: ${slots.find((s) => s.id === activeSlot)?.label ?? "pick a blank"}` : "Pieces"} +

+

+ {compose ? "Tap a choice, or drag it onto its blank. Only one is right." : "Tap a piece to add it, or drag it into the Dockerfile. Drag a line back here to take it out."} +

+
+ {(compose ? slotPieces : unplaced).map((p) => { + const selected = compose && picks[p.slot ?? ""] === p.id; + return ( + + ); + })} + {!compose && unplaced.length === 0 ?

Every piece is placed. Take one out if you want to change it.

: null} +
+
+ ); + + const surface = compose ? ( +
+

docker-compose.yml

+
+ {(round.skeleton ?? []).map((line, i) => { + if ("text" in line) return
{line.text}
; + const slot = slots.find((s) => s.id === line.slot)!; + const chosen = picks[slot.id] ? byId.get(picks[slot.id]!) : undefined; + return ( + + ); + })} +
+
+ ) : ( +
e.preventDefault()} onDrop={(e) => onDropAt(e, steps.length)}> +

Dockerfile

+
    + {steps.map((id, i) => ( +
  1. onDragStart(e, `row:${i}`)} + onDragOver={(e) => { e.preventDefault(); setDragOver(i); }} + onDragLeave={() => setDragOver(null)} + onDrop={(e) => onDropAt(e, i)} + className={cn( + "flex items-center gap-1.5 rounded-sm border border-transparent bg-background/60 py-0.5 pl-1 pr-0.5 motion-safe:animate-[bm-pop_0.25s_ease-out_both]", + dragOver === i && "border-primary", + )} + > + + {i + 1} + {byId.get(id)?.text} + + + +
  2. + ))} +
+ {steps.length === 0 ?

Empty. Add the first line (FROM).

: null} + {steps.length > 0 && dragOver === null ?
: null} +
+ ); + + const buildPanel = ( +
+
+ + + {note ? {note} : null} +
+ + {!report ? ( +

+ {compose ? "Fill every blank, then build. Docker pulls each image and starts the services in order." : "Put the lines in order, then build. Each line becomes a layer, and Docker reuses a layer when nothing above it changed."} +

+ ) : ( +
+
+
+ {compose ? "Pull and create" : "Build"} + {coldShown}/{report.layers.length || 0} {compose ? "images" : "layers"} +
+
+
+
+ + {coldDone && report.error ? ( +

+ {report.error} +

+ ) : null} + {coldDone && !report.error && report.warnings.length > 0 ? ( +
    {report.warnings.map((w) =>
  • Warning: {w}
  • )}
+ ) : null} +
+ + {rebuildActive ? ( +
+
+ Change one line of code, build again + {rebuildShown}/{report.layers.length} +
+ +
+ ) : null} + + {report.ok ? ( +
+ } label={compose ? "Pull time" : "Build time"} value={seconds(phase === "cold" ? coldTime : report.coldSec)} /> + {compose ? ( + } label="Services" value={String(report.layers.length)} /> + ) : ( + } label="Rebuild" value={seconds(phase === "rebuild" ? rebuildTime : report.rebuildSec)} tone={ranOrBuilt ? (report.cacheFriendly ? "good" : "bad") : undefined} /> + )} + } label="Image size" value={`${report.sizeMb} MB`} /> +
+ ) : null} + + {(phase === "running" || phase === "ran") && report.ok ? ( +
+

{compose ? "Services" : "Container"}

+
+ {report.runLog.slice(0, runShown).map((line, i) => ( +
{line}
+ ))} +
+ {phase === "ran" ? ( +

+ {report.started && report.reachable ? : } + {report.started && report.reachable ? (compose ? `Everything is up and localhost:${report.port} answers.` : `The container is running and localhost:${report.port} answers.`) : report.started ? "It runs, but nobody can reach it yet." : "It did not start."} +

+ ) : null} +
+ ) : null} +
+ )} +
+ ); + + return ( +
+ { sounds.whoosh(); resetAll(); }} + onFinish={() => onFinish({ mode: "build", steps: submissionSteps, hints: hintsUsed })} + finishLabel={allMet ? "Finish: all goals met" : "Finish and check"} + canFinish={placed > 0} + ready={allMet} + locked={locked} + /> +
+
+ {tray} + {surface} +
+
{buildPanel}
+
+
+ ); +} diff --git a/frontend/src/components/games/docker/dock-view.tsx b/frontend/src/components/games/docker/dock-view.tsx new file mode 100644 index 00000000..d7779bfe --- /dev/null +++ b/frontend/src/components/games/docker/dock-view.tsx @@ -0,0 +1,223 @@ +"use client"; + +import { Box, Cylinder, Globe, HardDrive, Network, RotateCw, X } from "lucide-react"; +import { CATALOG, diskUsedMb, fmtSize, portsText, statusText, type Container, type DockerWorld } from "@/shared/games/docker/daemon"; +import { cn } from "@/lib/utils"; + +const DISK_MB = 2000; + +const NET_TONES = [ + "border-sky-500/50 bg-sky-500/10 text-sky-700 dark:text-sky-300", + "border-violet-500/50 bg-violet-500/10 text-violet-700 dark:text-violet-300", + "border-pink-500/50 bg-pink-500/10 text-pink-700 dark:text-pink-300", + "border-teal-500/50 bg-teal-500/10 text-teal-700 dark:text-teal-300", +]; + +export type Probe = { port: number; ok: boolean } | null; + +function Whale({ className }: { className?: string }) { + return ( + + + + + + + + + + + + + + + + ); +} + +function stateOf(c: Container): "running" | "exited" | "crashed" | "restarting" | "created" { + if (c.status === "exited" && c.exitCode !== 0) return "crashed"; + return c.status; +} + +const TONE: Record, string> = { + running: "border-emerald-500/70 bg-emerald-500/10", + exited: "border-border bg-muted/50 opacity-80", + crashed: "border-red-500/70 bg-red-500/10", + restarting: "border-amber-500/70 bg-amber-500/10", + created: "border-dashed border-border bg-muted/30", +}; + +function StateDot({ state }: { state: ReturnType }) { + if (state === "restarting") return ; + const color = state === "running" ? "bg-emerald-500" : state === "crashed" ? "bg-red-500" : "bg-muted-foreground/60"; + return ; +} + +/** Colour for a network name, the same every time. */ +function netTone(world: DockerWorld, name: string): string { + const user = world.networks.filter((n) => !["bridge", "host", "none"].includes(n)); + const i = user.indexOf(name); + return i < 0 ? "border-border bg-secondary text-muted-foreground" : NET_TONES[i % NET_TONES.length]!; +} + +/** + * The live picture of the virtual Docker host: container boxes coloured by state, arrows from + * "localhost" to the published ports, and chips for volumes, networks and images. It only reads + * the world; the terminal changes it. + */ +export function DockView({ world, crashed, probe }: { world: DockerWorld; crashed: ReadonlySet; probe: Probe }) { + const running = world.containers.filter((c) => c.status === "running").length; + const published = world.containers.filter((c) => c.status !== "exited").flatMap((c) => c.ports.map((p) => ({ c, p }))); + const used = diskUsedMb(world); + const pct = Math.min(100, Math.round((used / DISK_MB) * 100)); + const userNets = world.networks.filter((n) => !["bridge", "host", "none"].includes(n)); + + return ( +
+
+ +
+

Docker host

+

+ {running} running, {world.containers.length - running} not running +

+
+
+
+ Disk + {pct}% +
+
+
85 ? "bg-red-500" : pct > 60 ? "bg-amber-500" : "bg-emerald-500")} style={{ width: `${pct}%` }} /> +
+
+
+ +
+ {published.length > 0 ? ( +
+ {published.map(({ c, p }) => { + const live = c.status === "running"; + const probed = live && probe && probe.port === p.host ? probe : null; + return ( +
+ + localhost:{p.host} + + + + {live ? : } {c.name}:{p.container} + + {probed ? ( + {probed.ok ? "200 OK" : "no answer"} + ) : null} +
+ ); + })} +
+ ) : null} + + {world.containers.length === 0 ? ( +

No containers yet. Try docker run -d -p 8080:80 nginx

+ ) : ( +
    + {world.containers.map((c) => { + const state = stateOf(c); + return ( +
  • +
    + + {c.name} + {state === "crashed" ? "crashed" : c.status} +
    +

    {c.image}

    +

    {statusText(world, c)}

    + {c.status === "running" || c.status === "restarting" ? ( +

    {portsText(c) || (CATALOG[c.image]?.port ? `${CATALOG[c.image]!.port}/tcp (not published)` : "no ports")}

    + ) : null} + {c.oomKilled ?

    Out of memory ({c.memoryMb} MB limit)

    : null} + {c.mounts.length + c.networks.length > 0 ? ( +
    + {c.mounts.map((m) => ( + + {m.kind === "volume" ? m.source.slice(0, 12) : m.source} + + ))} + {c.networks.map((n) => ( + + {n} + + ))} +
    + ) : null} +
  • + ); + })} +
+ )} + + {(world.volumes.length > 0 || userNets.length > 0) ? ( +
+ {world.volumes.length > 0 ? ( +
+

Volumes

+
+ {world.volumes.map((v) => { + const user = world.containers.filter((c) => c.mounts.some((m) => m.source === v)); + return ( + + {v.slice(0, 14)}{user.length ? ` (${user.map((c) => c.name).join(", ")})` : " (unused)"} + + ); + })} +
+
+ ) : null} + {userNets.length > 0 ? ( +
+

Networks

+
+ {userNets.map((n) => { + const members = world.containers.filter((c) => c.networks.includes(n)); + return ( + + {n}{members.length ? `: ${members.map((c) => c.name).join(", ")}` : " (empty)"} + + ); + })} +
+
+ ) : null} +
+ ) : null} + + {world.images.length > 0 ? ( +
+

Images

+
+ {world.images.map((i) => ( + " ? "border-dashed border-amber-500/60 text-amber-700 dark:text-amber-300" : "border-border bg-secondary")}> + {i.repo === "" ? "" : `${i.repo}:${i.tag}`} {fmtSize(i.sizeMb)} + + ))} +
+
+ ) : null} +
+
+ ); +} diff --git a/frontend/src/components/games/docker/docker-play.tsx b/frontend/src/components/games/docker/docker-play.tsx new file mode 100644 index 00000000..7caaee28 --- /dev/null +++ b/frontend/src/components/games/docker/docker-play.tsx @@ -0,0 +1,25 @@ +"use client"; + +import type { GamePlayProps } from "../types"; +import type { DockerRound, DockerSubmission } from "@/shared/games/docker/engine"; +import { BuildPlay } from "./build-play"; +import { DockerStyles } from "./docker-styles"; +import { FixPlay } from "./fix-play"; + +/** + * Docker Commands. A round is either "fix" (repair a broken virtual Docker host in a terminal, + * watching a live picture of it) or "build" (put a Dockerfile or compose file together from + * pieces, build it, then run it). + */ +export default function DockerPlay({ round, attempt, locked, sounds, onFinish }: GamePlayProps) { + return ( +
+ + {round.mode === "fix" ? ( + + ) : ( + + )} +
+ ); +} diff --git a/frontend/src/components/games/docker/docker-styles.tsx b/frontend/src/components/games/docker/docker-styles.tsx new file mode 100644 index 00000000..d8f5682e --- /dev/null +++ b/frontend/src/components/games/docker/docker-styles.tsx @@ -0,0 +1,33 @@ +"use client"; + +/** + * The few keyframes the Docker game needs. They only run when the system has not asked for reduced + * motion, so the game works the same without them. + */ +export function DockerStyles() { + return ( + + ); +} + +export function useReducedMotion(): boolean { + if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false; + return window.matchMedia("(prefers-reduced-motion: reduce)").matches; +} diff --git a/frontend/src/components/games/docker/fix-play.tsx b/frontend/src/components/games/docker/fix-play.tsx new file mode 100644 index 00000000..f35a787d --- /dev/null +++ b/frontend/src/components/games/docker/fix-play.tsx @@ -0,0 +1,153 @@ +"use client"; + +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; +import { GameTerminal, type TerminalLine } from "../game-terminal"; +import type { GameSounds } from "@/lib/games/audio"; +import { checkGoal, cloneWorld, HELP_LINES, runLine, type DockerEvent, type DockerWorld } from "@/shared/games/docker/daemon"; +import { MAX_COMMANDS, type FixRound, type FixSubmission } from "@/shared/games/docker/engine"; +import { DockView, type Probe } from "./dock-view"; +import { MissionPanel } from "./mission-panel"; + +type Props = { + round: FixRound; + attempt: number; + locked: boolean; + sounds: GameSounds; + onFinish: (submission: FixSubmission) => void; +}; + +const COMPLETIONS = [ + "docker", "ps", "images", "run", "start", "stop", "restart", "rm", "rmi", "logs", "inspect", "exec", "pull", "network", "volume", "stats", "system", "compose", + "curl", "help", "hint", "clear", "reset", "--name", "--network", "--restart", "--memory", "--tail", "prune", "create", "connect", "ls", +]; + +function intro(round: FixRound): TerminalLine[] { + const lines: TerminalLine[] = [{ kind: "sys", text: "Virtual Docker host. Type help to see the commands, hint for a clue." }]; + if (round.world.compose) lines.push({ kind: "sys", text: "This project has a docker-compose.yml. Read it with: cat docker-compose.yml" }); + return lines; +} + +/** Fix mode: a broken virtual Docker host, a terminal to repair it, and a live picture of the host. */ +export function FixPlay({ round, attempt, locked, sounds, onFinish }: Props) { + const [world, setWorld] = useState(() => cloneWorld(round.world)); + const [lines, setLines] = useState(() => intro(round)); + const [commands, setCommands] = useState([]); + const [hintsUsed, setHintsUsed] = useState(0); + const [crashed, setCrashed] = useState>(new Set()); + const [probe, setProbe] = useState(null); + const [announced, setAnnounced] = useState(false); + const firstAttempt = useRef(attempt); + + const goals = useMemo(() => round.goals.map((g) => ({ label: g.label, met: checkGoal(world, g) })), [round.goals, world]); + const allMet = goals.every((g) => g.met); + + const reset = useCallback(() => { + setWorld(cloneWorld(round.world)); + setLines([...intro(round), { kind: "sys", text: "The host is back to how it started. Your hints stay counted." }]); + setCommands([]); + setCrashed(new Set()); + setProbe(null); + setAnnounced(false); + }, [round]); + + // A new attempt starts the round again (the shell also remounts this component). + useEffect(() => { + if (attempt !== firstAttempt.current) { + firstAttempt.current = attempt; + reset(); + setHintsUsed(0); + } + }, [attempt, reset]); + + function sound(events: DockerEvent[], ok: boolean, text: string) { + if (!ok) return sounds.error(); + if (events.some((e) => e.type === "crashed" || e.type === "blocked")) return sounds.error(); + if (events.some((e) => e.type === "started")) return sounds.boot(); + if (events.some((e) => e.type === "pruned")) return sounds.whoosh(); + if (events.some((e) => e.type === "pulled" && e.name === "curl")) return sounds.whoosh(); + if (events.some((e) => ["created", "removed", "network", "volume", "pulled", "stopped"].includes(e.type)) || /^docker (stop|rm|start)/.test(text)) return sounds.ok(); + } + + function revealHint() { + if (hintsUsed >= round.hints.length) return; + const text = round.hints[hintsUsed]!; + setHintsUsed(hintsUsed + 1); + setLines((l) => [...l, { kind: "sys", text: `Hint ${hintsUsed + 1}: ${text}` }]); + sounds.ok(); + } + + function submit(raw: string) { + const line = raw.trim(); + if (!line) return; + const echo: TerminalLine = { kind: "in", text: line }; + if (line === "help") return setLines((l) => [...l, echo, ...HELP_LINES.map((text): TerminalLine => ({ kind: "out", text }))]); + if (line === "hint") { + setLines((l) => [...l, echo]); + return revealHint(); + } + if (line === "clear") return setLines([]); + if (line === "reset") { + sounds.whoosh(); + return reset(); + } + if (commands.length >= MAX_COMMANDS) { + sounds.error(); + return setLines((l) => [...l, echo, { kind: "sys", text: `That is ${MAX_COMMANDS} commands, the limit. Press Reset to start again.` }]); + } + const next = cloneWorld(world); + const result = runLine(next, line); + setWorld(next); + setCommands((c) => [...c, line]); + setCrashed(new Set(result.events.filter((e) => e.type === "crashed").map((e) => e.name))); + const curl = /^curl\s/.test(line); + if (curl) { + const port = Number(/:(\d{1,5})/.exec(line)?.[1] ?? 80); + setProbe({ port, ok: result.ok }); + } + const out: TerminalLine[] = result.lines.map((l) => ({ kind: l.kind, text: l.text })); + const nowMet = round.goals.every((g) => checkGoal(next, g)); + if (nowMet && !announced) { + out.push({ kind: "sys", text: "Every goal is met. Press Finish to check your fix." }); + setAnnounced(true); + } + setLines((l) => [...l, echo, ...out]); + sound(result.events, result.ok, line); + } + + const count = commands.length; + return ( +
+
+ { sounds.whoosh(); reset(); }} + onFinish={() => onFinish({ mode: "fix", commands, hints: hintsUsed })} + finishLabel={allMet ? "Finish: all goals met" : "Finish and check"} + canFinish={count > 0} + ready={allMet} + locked={locked} + /> +
+
+ +
+
+ +
+
+ ); +} diff --git a/frontend/src/components/games/docker/mission-panel.tsx b/frontend/src/components/games/docker/mission-panel.tsx new file mode 100644 index 00000000..1dfbd5c5 --- /dev/null +++ b/frontend/src/components/games/docker/mission-panel.tsx @@ -0,0 +1,76 @@ +"use client"; + +import { CheckCircle2, Circle, Lightbulb, RotateCcw, Send } from "lucide-react"; +import { Button } from "@/components/ui/button"; +import { cn } from "@/lib/utils"; + +export type MissionGoal = { label: string; met: boolean | null }; + +type Props = { + title: string; + goals: MissionGoal[]; + /** The count line, for example "3 commands, par 3". */ + counter: { label: string; value: number; par: number; limit: number; text?: string }; + hints: string[]; + hintsUsed: number; + onHint: () => void; + onReset: () => void; + onFinish: () => void; + finishLabel: string; + canFinish: boolean; + ready: boolean; + locked: boolean; +}; + +/** The objective checklist, the command counter against par, the hints and the reset and finish buttons. */ +export function MissionPanel({ title, goals, counter, hints, hintsUsed, onHint, onReset, onFinish, finishLabel, canFinish, ready, locked }: Props) { + const pace = counter.value <= counter.par + 1 ? "text-emerald-600 dark:text-emerald-400" : counter.value <= counter.par + 4 ? "text-amber-600 dark:text-amber-400" : "text-red-600 dark:text-red-400"; + const fill = Math.min(100, Math.round((counter.value / Math.max(1, counter.par + 4)) * 100)); + const more = hintsUsed < hints.length; + return ( +
+
+

{title}

+

+ {counter.text ?? `${counter.value} ${counter.label}, par ${counter.par}`} +

+
+
+
+
+ +
    + {goals.map((g) => ( +
  • + {g.met ? : } + + {g.label} + {g.met ? " (done)" : " (not done)"} + +
  • + ))} +
+ + {hintsUsed > 0 ? ( +
    + {hints.slice(0, hintsUsed).map((h, i) => ( +
  1. Hint {i + 1}. {h}
  2. + ))} +
+ ) : null} + +
+ + + +
+

Hints cost stars: no hints and few {counter.label} give three stars.

+
+ ); +} diff --git a/frontend/src/components/games/game-host.tsx b/frontend/src/components/games/game-host.tsx new file mode 100644 index 00000000..dd246b27 --- /dev/null +++ b/frontend/src/components/games/game-host.tsx @@ -0,0 +1,220 @@ +"use client"; + +import { Suspense, useCallback, useEffect, useMemo, useState } from "react"; +import Link from "next/link"; +import { ArrowLeft, ArrowRight, RotateCcw, Volume2, VolumeX } from "lucide-react"; +import { Button, buttonVariants } from "@/components/ui/button"; +import { ApiError } from "@/lib/api-client"; +import { fetchDailyGames, submitGameRound } from "@/lib/games/client"; +import { gameSounds, isSoundEnabled, setSoundEnabled } from "@/lib/games/audio"; +import { engineFor, ROUNDS_PER_DAY, type GameId, type VerifyResult } from "@/shared/games"; +import type { DailyGameView, DailyGamesView, SubmitRoundResult } from "@/shared/api/games"; +import { cn } from "@/lib/utils"; +import { ConfettiBurst, StarRow, XpChip } from "./celebration"; +import { GAME_PLAYS } from "./registry"; + +const TIER_LABEL = ["Easy", "Medium", "Hard"] as const; + +type Outcome = { + local: VerifyResult; + server: SubmitRoundResult | null; + /** Set when the server could not be reached or the learner is not signed in. */ + note: string | null; + burst: string; +}; + +/** + * One daily game: loads today's rounds, shows the three round tabs, hosts the game's play + * component, checks a finished round with the shared engine, and shows the result with sound, + * stars and confetti. A signed-in learner's round is also replayed and recorded on the server. + */ +export function GameHost({ game }: { game: GameId }) { + const [daily, setDaily] = useState(null); + const [failed, setFailed] = useState(false); + const [roundIndex, setRoundIndex] = useState(0); + const [attempt, setAttempt] = useState(0); + const [busy, setBusy] = useState(false); + const [outcome, setOutcome] = useState(null); + const [soundOn, setSoundOn] = useState(false); + + // The sound switch lives in localStorage, so it can only be read after the page has mounted. + // eslint-disable-next-line react-hooks/set-state-in-effect + useEffect(() => setSoundOn(isSoundEnabled()), []); + + const load = useCallback(() => { + fetchDailyGames().then(setDaily).catch(() => setFailed(true)); + }, []); + useEffect(load, [load]); + + const view: DailyGameView | undefined = daily?.games.find((g) => g.id === game); + const Play = GAME_PLAYS[game]; + const engine = useMemo(() => engineFor(game), [game]); + + // Open on the first round that is not solved yet. + useEffect(() => { + if (!view) return; + const open = [0, 1, 2].find((i) => !view.progress.some((p) => p.roundIndex === i)); + // Open on the first round that is not solved, once today's progress has loaded. + // eslint-disable-next-line react-hooks/set-state-in-effect + setRoundIndex(open ?? 0); + }, [view?.id, daily?.dayKey]); // eslint-disable-line react-hooks/exhaustive-deps + + const finish = useCallback( + async (submission: unknown) => { + if (!view || busy) return; + const round = view.rounds[roundIndex]!; + const parsed = engine.parseSubmission(submission); + const local: VerifyResult = parsed === null + ? { passed: false, stars: 0, score: 0, message: "That did not look like a finished round." } + : engine.verify(round, parsed); + const burst = `${roundIndex}-${attempt}-${Date.now()}`; + if (!local.passed) { + gameSounds.lose(); + setOutcome({ local, server: null, note: null, burst }); + return; + } + gameSounds.win(local.stars); + setOutcome({ local, server: null, note: null, burst }); + if (!daily?.signedIn) { + setOutcome({ local, server: null, note: "Sign in to save your stars and earn XP.", burst }); + return; + } + setBusy(true); + try { + const server = await submitGameRound(game, roundIndex, submission); + if (server.xpAwarded > 0) gameSounds.coin(); + if (server.setBonus > 0) setTimeout(() => gameSounds.fanfare(), 500); + setOutcome({ local, server, note: null, burst }); + load(); + } catch (error) { + const note = error instanceof ApiError && error.status === 401 ? "Sign in to save your stars and earn XP." : "Solved. We could not save it just now, so no XP this time."; + setOutcome({ local, server: null, note, burst }); + } finally { + setBusy(false); + } + }, + [view, busy, roundIndex, attempt, engine, daily?.signedIn, game, load], + ); + + function toggleSound() { + const next = !soundOn; + setSoundEnabled(next); + setSoundOn(next); + if (next) gameSounds.ok(); + } + + function pick(index: number) { + setOutcome(null); + setAttempt((n) => n + 1); + setRoundIndex(index); + } + + if (failed) { + return ( +
+

Today's games could not be loaded.

+ +
+ ); + } + if (!daily || !view) return
; + + const round = view.rounds[roundIndex]!; + const solved = (i: number) => view.progress.find((p) => p.roundIndex === i); + const passed = outcome?.local.passed ?? false; + const stars = outcome?.local.stars ?? 0; + const last = roundIndex >= ROUNDS_PER_DAY - 1; + const setDone = outcome?.server?.setComplete; + + return ( +
+ {outcome?.local.passed ? : null} + +
+ + All daily games + + +
+ +
+ {[0, 1, 2].map((i) => { + const done = solved(i); + return ( + + ); + })} +
+ +
+

{round.title}

+

{round.brief}

+
+ +
+ }> + + +
+ + {outcome ? ( +
+
+ {passed ? : null} +
+

{passed ? (setDone ? "All three solved today!" : "Solved!") : "Not yet"}

+

{outcome.local.message}

+
+
+ + +
+
+ {outcome.note ?

{outcome.note} {!daily.signedIn ? Sign in : null}

: null} + {outcome.server?.alreadySolved ?

You solved this one earlier today, so it is practice and gives no more XP.

: null} +
+ {!passed || last ? ( + + ) : null} + {passed && !last ? ( + + ) : null} + {passed && last ? Back to today's games : null} +
+
+ ) : null} +
+ ); +} diff --git a/frontend/src/components/games/game-terminal.tsx b/frontend/src/components/games/game-terminal.tsx new file mode 100644 index 00000000..e75b45ae --- /dev/null +++ b/frontend/src/components/games/game-terminal.tsx @@ -0,0 +1,128 @@ +"use client"; + +import { useEffect, useRef, useState, type KeyboardEvent } from "react"; +import { cn } from "@/lib/utils"; +import type { GameSounds } from "@/lib/games/audio"; + +export type TerminalLine = { + /** "in" is what the player typed, "out" is normal output, "err" an error, "sys" a note from the game. */ + kind: "in" | "out" | "err" | "sys"; + text: string; + /** The prompt that was showing when the player typed this line (only for "in"). */ + prompt?: string; +}; + +type Props = { + lines: TerminalLine[]; + prompt: string; + onSubmit: (line: string) => void; + sounds: GameSounds; + locked?: boolean; + /** Words Tab can finish, for example command names. */ + completions?: string[]; + placeholder?: string; + className?: string; + /** Height of the output area. */ + height?: string; +}; + +/** + * A small terminal for the command games: a scrolling log, a prompt, history on the arrow keys and + * Tab to finish a command name. The game owns the lines and the rules; this only draws and types. + */ +export function GameTerminal({ lines, prompt, onSubmit, sounds, locked = false, completions = [], placeholder, className, height = "h-80" }: Props) { + const [value, setValue] = useState(""); + const [cursor, setCursor] = useState(null); + const log = useRef(null); + const input = useRef(null); + const history = useRef([]); + + useEffect(() => { + const el = log.current; + if (el) el.scrollTop = el.scrollHeight; + }, [lines]); + + function send() { + const line = value; + if (!line.trim()) return; + history.current.push(line); + setCursor(null); + setValue(""); + sounds.enter(); + onSubmit(line); + } + + function onKeyDown(event: KeyboardEvent) { + if (event.key === "Enter") { + event.preventDefault(); + send(); + } else if (event.key === "ArrowUp" || event.key === "ArrowDown") { + event.preventDefault(); + const past = history.current; + if (past.length === 0) return; + const next = event.key === "ArrowUp" ? (cursor === null ? past.length - 1 : Math.max(0, cursor - 1)) : cursor === null ? null : cursor + 1; + if (next === null || next >= past.length) { + setCursor(null); + setValue(""); + } else { + setCursor(next); + setValue(past[next]!); + } + } else if (event.key === "Tab") { + event.preventDefault(); + const words = value.split(" "); + const last = words[words.length - 1] ?? ""; + if (!last) return; + const matches = completions.filter((word) => word.startsWith(last)); + if (matches.length === 1) { + words[words.length - 1] = matches[0]!; + setValue(words.join(" ") + " "); + } + } + } + + return ( +
input.current?.focus()} + > +
+ {lines.map((line, i) => ( +
+ {line.kind === "in" ? {line.prompt ?? prompt} : null} + {line.text} +
+ ))} +
+
+ {prompt} + { + setValue(event.target.value); + sounds.key(); + }} + onKeyDown={onKeyDown} + placeholder={placeholder} + spellCheck={false} + autoCapitalize="off" + autoComplete="off" + autoCorrect="off" + aria-label="Type a command and press Enter" + className="min-w-0 flex-1 bg-transparent outline-none placeholder:text-muted-foreground/60" + /> +
+
+ ); +} diff --git a/frontend/src/components/games/games-hub.tsx b/frontend/src/components/games/games-hub.tsx new file mode 100644 index 00000000..56809950 --- /dev/null +++ b/frontend/src/components/games/games-hub.tsx @@ -0,0 +1,94 @@ +"use client"; + +import { useEffect, useState } from "react"; +import Link from "next/link"; +import { Boxes, Network, Terminal, Zap, type LucideIcon } from "lucide-react"; +import { fetchDailyGames } from "@/lib/games/client"; +import type { DailyGamesView } from "@/shared/api/games"; +import type { GameId } from "@/shared/games"; +import { cn } from "@/lib/utils"; +import { StarRow } from "./celebration"; + +const LOOK: Record = { + sysdesign: { icon: Network, accent: "bg-sky-500/15 text-sky-700 dark:text-sky-300", cta: "Fix today's incidents" }, + linux: { icon: Terminal, accent: "bg-emerald-500/15 text-emerald-700 dark:text-emerald-300", cta: "Start today's quests" }, + docker: { icon: Boxes, accent: "bg-orange-500/15 text-orange-700 dark:text-orange-300", cta: "Fix today's containers" }, +}; + +function timeLeft(resetsAt: string, now: number): string { + const ms = Math.max(0, new Date(resetsAt).getTime() - now); + const h = Math.floor(ms / 3_600_000); + const m = Math.floor((ms % 3_600_000) / 60_000); + return `${h}h ${String(m).padStart(2, "0")}m`; +} + +/** Today's three games with how far each is solved, the XP earned and the time until a new set. */ +export function GamesHub() { + const [daily, setDaily] = useState(null); + const [failed, setFailed] = useState(false); + const [now, setNow] = useState(() => Date.now()); + + useEffect(() => { + fetchDailyGames().then(setDaily).catch(() => setFailed(true)); + const timer = setInterval(() => setNow(Date.now()), 30_000); + return () => clearInterval(timer); + }, []); + + if (failed) return

Today's games could not be loaded. Refresh the page to try again.

; + if (!daily) { + return ( +
+ {[0, 1, 2].map((i) =>
)} +
+ ); + } + + return ( +
+
+

+ + {daily.signedIn ? ( + {daily.xpToday} XP earned today, up to {daily.xpToday + daily.xpLeft} from the games. + ) : ( + Play without an account. Sign in to save stars and earn XP. + )} +

+

New games in {timeLeft(daily.resetsAt, now)}

+
+ +
+ {daily.games.map((game) => { + const look = LOOK[game.id]; + const Icon = look.icon; + const solved = game.progress.length; + return ( + + +

{game.title}

+

{game.tagline}

+
    + {[0, 1, 2].map((i) => { + const done = game.progress.find((p) => p.roundIndex === i); + return ( +
  1. + {["Easy", "Medium", "Hard"][i]} + {done ? : Open} +
  2. + ); + })} +
+ + {game.setComplete ? "All solved. Play again for practice" : solved > 0 ? "Keep going" : look.cta} + + + ); + })} +
+
+ ); +} diff --git a/frontend/src/components/games/linux/linux-play.tsx b/frontend/src/components/games/linux/linux-play.tsx new file mode 100644 index 00000000..ace695d8 --- /dev/null +++ b/frontend/src/components/games/linux/linux-play.tsx @@ -0,0 +1,184 @@ +"use client"; + +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; +import { GameTerminal, type TerminalLine } from "../game-terminal"; +import type { GamePlayProps } from "../types"; +import { createLinuxSession, type LinuxRound, type LinuxSubmission, type Shell } from "@/shared/games/linux/engine"; +import { Controls, Counter, MissionPanel, type MissionStats } from "./mission-panel"; + +const MAX_LINES = 600; +/** The pause between reaching the goal and handing the run to the shell, so the win can be seen. */ +const FINISH_DELAY_MS = 1400; + +function prefersReducedMotion(): boolean { + return typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches; +} + +/** + * The Linux Command Explorer: a fake shell on a made-up server, with a mission panel next to it. + * The shared engine runs one command at a time; this component draws the screen, plays the sounds + * and calls `onFinish` with the commands when the goal is reached. + */ +export default function LinuxPlay({ round, attempt, locked, sounds, onFinish }: GamePlayProps) { + const [session, setSession] = useState(() => createLinuxSession(round)); + const [run, setRun] = useState(0); + const [lines, setLines] = useState([]); + const [typed, setTyped] = useState(0); + const [showBoot, setShowBoot] = useState(true); + const [prompt, setPrompt] = useState(() => session?.prompt() ?? "$"); + const [stats, setStats] = useState(() => blankStats(round)); + const [finished, setFinished] = useState(false); + const timers = useRef[]>([]); + const sent = useRef(false); + const box = useRef(null); + + const focusTerminal = useCallback(() => { + box.current?.querySelector("input")?.focus({ preventScroll: true }); + }, []); + + const clearTimers = useCallback(() => { + timers.current.forEach(clearTimeout); + timers.current = []; + }, []); + useEffect(() => clearTimers, [clearTimers]); + + const startOver = useCallback(() => { + clearTimers(); + sent.current = false; + const next = createLinuxSession(round); + setSession(next); + setLines([]); + setTyped(0); + setShowBoot(true); + setFinished(false); + setPrompt(next?.prompt() ?? "$"); + setStats(blankStats(round)); + setRun((n) => n + 1); + }, [round, clearTimers]); + + // The shell resets itself when the shell part of the host asks for a new attempt. + const firstAttempt = useRef(attempt); + useEffect(() => { + if (attempt !== firstAttempt.current) { + firstAttempt.current = attempt; + startOver(); + } + }, [attempt, startOver]); + + // Put the cursor in the terminal, so the keyboard works at once (and again after a reset). + useEffect(() => { + const t = setTimeout(focusTerminal, 50); + return () => clearTimeout(t); + }, [run, focusTerminal]); + + // A typewriter boot line: `typed` counts the characters shown so far. + const bootFull = useMemo(() => session?.bootLines().join("\n") ?? "", [session]); + useEffect(() => { + if (!session) return; + if (prefersReducedMotion()) { + const t = setTimeout(() => setTyped(bootFull.length), 0); + return () => clearTimeout(t); + } + if (run === 0) sounds.boot(); + const timer = setInterval(() => { + setTyped((n) => { + if (n + 2 >= bootFull.length) clearInterval(timer); + return Math.min(bootFull.length, n + 2); + }); + }, 24); + return () => clearInterval(timer); + }, [session, run, bootFull]); // eslint-disable-line react-hooks/exhaustive-deps + + const completions = useMemo(() => session?.completions() ?? [], [session, lines]); // eslint-disable-line react-hooks/exhaustive-deps + + const runLine = useCallback( + (line: string) => { + if (!session || locked || finished) return; + const before = session.prompt(); + const res = session.run(line); + const out: TerminalLine[] = res.lines.map((l) => ({ kind: l.kind, text: l.text })); + if (res.accepted && !res.clear) out.unshift({ kind: "in", text: line, prompt: before }); + if (!res.accepted && out.length === 0) out.push({ kind: "sys", text: "Nothing to run." }); + + if (res.clear) setShowBoot(false); + setLines((prev) => [...(res.clear ? [] : prev), ...out].slice(-MAX_LINES)); + setPrompt(session.prompt()); + + const progress = session.progress(); + setStats({ done: progress.done, commands: progress.commands, hints: progress.hints, hintsTotal: progress.hintsTotal, flash: res.newlyDone }); + + const notFound = res.lines.some((l) => l.kind === "err" && /command not found/.test(l.text)); + if (notFound || !res.accepted) sounds.error(); + else if (res.newlyDone.length > 0) sounds.ok(); + + if (res.newlyDone.length > 0) { + const t = setTimeout(() => setStats((s) => ({ ...s, flash: [] })), 1200); + timers.current.push(t); + } + + if (res.solved && !sent.current) { + sent.current = true; + setFinished(true); + setLines((prev) => [...prev, { kind: "sys", text: "Mission complete! Checking your run ..." }]); + const t = setTimeout(() => onFinish({ commands: session.commands, hints: session.hintCount }), FINISH_DELAY_MS); + timers.current.push(t); + } + }, + [session, locked, finished, sounds, onFinish], + ); + + const hint = useCallback(() => { + if (!session || locked || finished) return; + sounds.snap(); + runLine("hint"); + }, [session, locked, finished, sounds, runLine]); + + if (!session) { + return ( +
+

This mission could not be loaded.

+
+ ); + } + + const booting = typed < bootFull.length; + const shown: TerminalLine[] = showBoot ? [{ kind: "sys", text: bootFull.slice(0, typed) + (booting ? "_" : "") }, ...lines] : lines; + const disabled = locked || finished; + + return ( +
+
+
+
+ + Objectives {stats.done.filter(Boolean).length}/{round.objectives.length} + + +
+ +
+ +

+ Tab finishes a name. Arrow up repeats a command. Type help to see what works. +

+
+
+ +
+
+ ); +} + +function blankStats(round: LinuxRound): MissionStats { + return { done: round.objectives.map(() => false), commands: 0, hints: 0, hintsTotal: round.hintCount, flash: [] }; +} diff --git a/frontend/src/components/games/linux/mission-panel.tsx b/frontend/src/components/games/linux/mission-panel.tsx new file mode 100644 index 00000000..d76f74bb --- /dev/null +++ b/frontend/src/components/games/linux/mission-panel.tsx @@ -0,0 +1,169 @@ +"use client"; + +import { useState } from "react"; +import { BookOpen, Check, ChevronDown, Lightbulb, RotateCcw } from "lucide-react"; +import { Button } from "@/components/ui/button"; +import { cn } from "@/lib/utils"; +import { StarRow } from "../celebration"; +import { linuxCheatSheet, type LinuxRound } from "@/shared/games/linux/engine"; + +export type MissionStats = { + done: boolean[]; + commands: number; + hints: number; + hintsTotal: number; + /** Objectives that just ticked, for a short animation. */ + flash: number[]; +}; + +/** How many stars the player can still reach with this many commands and hints. */ +export function starsNow(round: LinuxRound, commands: number, hints: number): 1 | 2 | 3 { + if (hints === 0 && commands <= round.par) return 3; + if (hints <= 1 && commands <= round.par + 4) return 2; + return 1; +} + +/** The command counter against par: a bar that fills and changes colour as stars are lost. */ +export function Counter({ round, stats, compact = false }: { round: LinuxRound; stats: MissionStats; compact?: boolean }) { + const stars = starsNow(round, stats.commands, stats.hints); + const width = Math.min(100, Math.round((stats.commands / Math.max(1, round.par + 4)) * 100)); + return ( +
+
+ + {stats.commands} + / par {round.par} + + {compact ? null : } +
+
+
+
+
+ ); +} + +/** The mission checklist. A tick pops in when an objective is done. */ +export function Checklist({ round, stats }: { round: LinuxRound; stats: MissionStats }) { + return ( +
    + {round.objectives.map((label, i) => { + const done = stats.done[i] ?? false; + return ( +
  1. + + + + + {label} + {done ? " (done)" : " (not done yet)"} + +
  2. + ); + })} +
+ ); +} + +/** A small "what works" list that opens on demand. */ +export function CheatSheet() { + const [open, setOpen] = useState(false); + return ( +
+ + {open ? ( +
+ {linuxCheatSheet().map((group) => ( +
+

{group.group}

+
    + {group.items.map((item) => ( +
  • + {item.usage} + {item.desc} +
  • + ))} +
+
+ ))} +

Pipes (|), redirects (> and >>), quotes, &&, $HOME and * all work. Tab finishes names. Arrow up repeats a command.

+
+ ) : null} +
+ ); +} + +/** Hint and reset buttons. */ +export function Controls({ stats, disabled, onHint, onReset }: { stats: MissionStats; disabled: boolean; onHint: () => void; onReset: () => void }) { + const left = stats.hintsTotal - stats.hints; + return ( +
+ + +
+ ); +} + +export function MissionPanel({ round, stats, disabled, onHint, onReset }: { round: LinuxRound; stats: MissionStats; disabled: boolean; onHint: () => void; onReset: () => void }) { + const doneCount = stats.done.filter(Boolean).length; + return ( + + ); +} diff --git a/frontend/src/components/games/registry.tsx b/frontend/src/components/games/registry.tsx new file mode 100644 index 00000000..bd2bd29c --- /dev/null +++ b/frontend/src/components/games/registry.tsx @@ -0,0 +1,14 @@ +"use client"; + +import { lazy, type ComponentType } from "react"; +import type { GameId } from "@/shared/games"; +import type { GamePlayProps } from "./types"; + +// Each game's play component is loaded on its own page, so the hub stays light. +// Each game has its own round and submission types, so the registry can only hold them loosely. +/* eslint-disable @typescript-eslint/no-explicit-any */ +export const GAME_PLAYS: Record>> = { + sysdesign: lazy(() => import("./sysdesign/sysdesign-play")), + linux: lazy(() => import("./linux/linux-play")), + docker: lazy(() => import("./docker/docker-play")), +}; diff --git a/frontend/src/components/games/sysdesign/diagram.tsx b/frontend/src/components/games/sysdesign/diagram.tsx new file mode 100644 index 00000000..8811b51c --- /dev/null +++ b/frontend/src/components/games/sysdesign/diagram.tsx @@ -0,0 +1,247 @@ +"use client"; + +// The architecture diagram: inline SVG, drawn top to bottom so it stays readable at 375 px wide. +// Packets are animated with the Web Animations API, and only when the player allows motion. +import { useEffect, useRef } from "react"; +import type { ComponentId, Model, SimResult, StepResult, SysdesignRound } from "@/shared/games/sysdesign/engine"; +import { cn } from "@/lib/utils"; + +type Pt = [number, number]; +type Tone = "ok" | "warn" | "bad" | "dead" | "off"; + +const toneStroke: Record = { + ok: "stroke-emerald-500", + warn: "stroke-amber-500", + bad: "stroke-red-500", + dead: "stroke-red-600", + off: "stroke-border", +}; +const toneFill: Record = { + ok: "fill-emerald-500", + warn: "fill-amber-500", + bad: "fill-red-500", + dead: "fill-red-600", + off: "fill-muted-foreground", +}; + +export function utilTone(util: number): Tone { + return util >= 1 ? "bad" : util >= 0.8 ? "warn" : "ok"; +} + +function Node(props: { + id: ComponentId | string; + x: number; + y: number; + w: number; + h: number; + title: string; + sub?: string; + tone?: Tone; + util?: number; + ring?: boolean; + dim?: boolean; +}) { + const { x, y, w, h, title, sub, tone = "off", util, ring, dim } = props; + return ( + + {ring ? ( + + ) : null} + + + {title} + + {sub ? ( + + {sub} + + ) : null} + {util !== undefined ? ( + + + + + ) : null} + {ring ? ( + + + + ! + + + ) : null} + + ); +} + +function lengthOf(points: Pt[]) { + let total = 0; + for (let i = 1; i < points.length; i++) total += Math.hypot(points[i]![0] - points[i - 1]![0], points[i]![1] - points[i - 1]![1]); + return total; +} + +/** Cut a path short, so a dropped packet dies part of the way along. */ +function truncate(points: Pt[], share: number): Pt[] { + const total = lengthOf(points) * share; + const out: Pt[] = [points[0]!]; + let walked = 0; + for (let i = 1; i < points.length; i++) { + const [x0, y0] = points[i - 1]!; + const [x1, y1] = points[i]!; + const seg = Math.hypot(x1 - x0, y1 - y0); + if (walked + seg >= total) { + const k = seg === 0 ? 0 : (total - walked) / seg; + out.push([x0 + (x1 - x0) * k, y0 + (y1 - y0) * k]); + return out; + } + out.push([x1, y1]); + walked += seg; + } + return out; +} + +function Packet({ points, delay, dur, dropped }: { points: Pt[]; delay: number; dur: number; dropped: boolean }) { + const ref = useRef(null); + useEffect(() => { + const el = ref.current; + if (!el || typeof el.animate !== "function") return; + const path = dropped ? truncate(points, 0.55) : points; + const total = lengthOf(path) || 1; + let walked = 0; + const frames: Keyframe[] = path.map((p, i) => { + if (i > 0) walked += Math.hypot(p[0] - path[i - 1]![0], p[1] - path[i - 1]![1]); + const edge = i === 0 || i === path.length - 1; + return { offset: walked / total, transform: `translate(${p[0]}px, ${p[1]}px)`, opacity: edge ? 0.2 : 1 }; + }); + frames[0]!.offset = 0; + frames[frames.length - 1]!.offset = 1; + if (dropped) frames[frames.length - 1]!.opacity = 0; + const anim = el.animate(frames, { duration: dur, delay, fill: "both", easing: "linear" }); + return () => anim.cancel(); + }, [points, delay, dur, dropped]); + return ; +} + +type Edge = { id: string; pts: Pt[]; layer: number; drop: number; count: number; dashed?: boolean }; + +export type DiagramProps = { + round: SysdesignRound; + model: Model; + preview: SimResult; + /** The step being played, or null when the player is planning. */ + step: StepResult | null; + /** Show the red "problem" marker. */ + problem: boolean; + animate: boolean; + /** Playing right now. */ + running: boolean; +}; + +export function SystemDiagram({ round, model: m, preview, step, problem, animate, running }: DiagramProps) { + const zoneDown = !!step?.zoneDown; + const appUtil = step ? step.appUtil : preview.peakAppUtil; + const dbUtil = step ? step.dbUtil : preview.peakDbUtil; + const repUtil = step ? step.replicaUtil : Math.max(0, ...preview.steps.map((s) => s.replicaUtil)); + const twoZones = m.app.zones === 2; + const hasBatch = !!round.batchJob; + const batchOn = !!step?.batchRunning; + const showNat = round.focus === "nat" || m.net.natGb >= 10000; + const showLogs = round.focus === "storage" || m.logs.gb >= 10000; + const replicas = Math.min(2, Math.round(m.db.replicas)); + const ring = (id: ComponentId) => problem && round.focus === id; + + const appToneA: Tone = zoneDown ? "dead" : step ? utilTone(appUtil) : appUtil >= 1 ? "bad" : appUtil >= 0.8 ? "warn" : "ok"; + const appToneB: Tone = step ? utilTone(appUtil) : utilTone(appUtil); + const dbTone: Tone = zoneDown && !m.db.multiAz ? "dead" : utilTone(dbUtil); + + const instances = m.app.autoscale ? `${m.app.scaleMin}-${m.app.scaleMax}` : String(m.app.count); + const appSub = step && m.app.autoscale ? `${step.appInstances} running` : `${twoZones ? Math.ceil((m.app.autoscale ? m.app.scaleMin : m.app.count) / 2) : instances} x ${m.app.label}`; + const appSubB = step && m.app.autoscale ? `${step.appInstances} running` : `${Math.floor(m.app.count / 2) || 1} x ${m.app.label}`; + + const edges: Edge[] = []; + const add = (e: Edge | null) => e && edges.push(e); + const appDrop = step?.appDrop ?? 0; + const dbDrop = step?.dbDrop ?? 0; + const lbDrop = zoneDown && !twoZones ? 1 : 0; + add({ id: "u-lb", pts: [[180, 42], [180, 66]], layer: 0, drop: lbDrop, count: 2 }); + if (m.cdn.on) add({ id: "u-cdn", pts: [[150, 42], [60, 66]], layer: 0, drop: 0, count: 1 }); + add({ id: "lb-a", pts: [[160, 100], [92, 140]], layer: 1, drop: twoZones && zoneDown ? (m.app.healthChecks ? 0.1 : 1) : appDrop, count: 2 }); + if (twoZones) add({ id: "lb-b", pts: [[200, 100], [268, 140]], layer: 1, drop: appDrop > 0.5 ? appDrop : 0, count: 2 }); + if (m.cache.on) add({ id: "a-cache", pts: [[50, 196], [50, 214]], layer: 2, drop: appDrop, count: 1 }); + if (m.queue.on) add({ id: "a-queue", pts: [[133, 196], [133, 214]], layer: 2, drop: appDrop, count: 1 }); + add({ id: "a-db", pts: [[92, 196], [92, 300]], layer: 2, drop: zoneDown && !m.db.multiAz ? 1 : dbDrop, count: 2 }); + if (m.queue.on) add({ id: "q-db", pts: [[133, 248], [133, 300]], layer: 3, drop: zoneDown && !m.db.multiAz ? 1 : 0, count: 1 }); + if (twoZones) { + const standbyPath: Pt[] = [[268, 196], [268, 300]]; + add({ id: "b-db", pts: zoneDown && m.db.multiAz ? standbyPath : [[300, 196], [300, 276], [50, 276], [50, 300]], layer: 2, drop: dbDrop, count: 2 }); + } + if (m.db.multiAz) add({ id: "sync", pts: [[168, 328], [192, 328]], layer: 3, drop: 0, count: 1, dashed: true }); + if (replicas > 0) { + add({ id: "rep1", pts: [[130, 356], [130, 368], [228, 368], [228, 380]], layer: 3, drop: repUtil > 1 ? 1 - 1 / repUtil : 0, count: 1, dashed: true }); + if (replicas > 1) add({ id: "rep2", pts: [[228, 368], [306, 368], [306, 380]], layer: 3, drop: repUtil > 1 ? 1 - 1 / repUtil : 0, count: 1, dashed: true }); + } + if (hasBatch && batchOn) { + add({ id: "job-db", pts: [[214, 262], [214, 286], [150, 286], [150, 300]], layer: 2, drop: dbDrop, count: 2, dashed: true }); + if (!m.batch.separate) add({ id: "job-app", pts: twoZones ? [[268, 222], [268, 196]] : [[200, 222], [170, 190]], layer: 2, drop: appDrop, count: 2, dashed: true }); + } + + const dur = 480; + const edgeClass = (e: Edge) => { + if (!step) return "stroke-border"; + if (e.drop >= 0.5) return "stroke-red-500"; + if (e.drop >= 0.04) return "stroke-amber-500"; + return "stroke-emerald-500/70"; + }; + + return ( + + {/* Availability Zone panels */} + + + + {zoneDown ? "ZONE A DOWN" : "Availability Zone A"} + + + Availability Zone B + + {!twoZones && !m.db.multiAz && !hasBatch && !replicas ? ( + + nothing here yet + + ) : null} + + {/* Connections */} + {edges.map((e) => ( + p.join(",")).join(" ")} fill="none" strokeWidth={2} strokeDasharray={e.dashed ? "4 3" : undefined} className={cn("transition-colors", edgeClass(e))} /> + ))} + + {/* Nodes */} + + {m.cdn.on ? : null} + = 1 ? "dead" : m.app.healthChecks ? "ok" : "off"} ring={ring("lb")} /> + + {twoZones ? : null} + {m.cache.on ? : null} + {m.queue.on ? 50 ? "warn" : "ok"} ring={ring("queue")} /> : null} + {hasBatch ? ( + + ) : null} + = 2 ? "hot key on one partition" : "DynamoDB table") : "primary database"} tone={dbTone} util={zoneDown && !m.db.multiAz ? 0 : dbUtil} ring={ring("db")} /> + {m.db.multiAz ? : null} + {replicas > 0 ? : null} + {replicas > 1 ? : null} + {showNat ? : null} + {showLogs ? 0 ? "old logs in Glacier" : "all in Standard"} tone={m.logs.coldShare > 0 ? "ok" : "off"} ring={ring("storage")} /> : null} + + {/* Packets, one set per step */} + {animate && running && step + ? edges.flatMap((e) => { + const dropped = Math.round(e.count * Math.min(1, e.drop)); + return Array.from({ length: e.count }, (_, i) => ( + = 0.04 && e.drop < 0.5 && i === 0)} /> + )); + }) + : null} + + ); +} diff --git a/frontend/src/components/games/sysdesign/sysdesign-play.tsx b/frontend/src/components/games/sysdesign/sysdesign-play.tsx new file mode 100644 index 00000000..f385d055 --- /dev/null +++ b/frontend/src/components/games/sysdesign/sysdesign-play.tsx @@ -0,0 +1,420 @@ +"use client"; + +// System Design Runner. A production incident on a small AWS system: pick a few changes, press Run, +// and watch 24 hours of traffic play out. The result comes from the shared engine, so the browser and +// the server always agree. +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; +import { Check, Lightbulb, Play, RotateCcw, SkipForward, TriangleAlert, X } from "lucide-react"; +import { Button } from "@/components/ui/button"; +import { cn } from "@/lib/utils"; +import { costDelta, evaluateGoals, simulate, STEPS, type SimResult, type SysdesignRound, type SysdesignSubmission } from "@/shared/games/sysdesign/engine"; +import type { GamePlayProps } from "../types"; +import { SystemDiagram, utilTone } from "./diagram"; + +const STEP_MS = 520; +const STEP_MS_REDUCED = 160; + +function useReducedMotion() { + const [reduced, setReduced] = useState(false); + // The reduced motion setting can only be read in the browser, after mount. + useEffect(() => { + const query = window.matchMedia("(prefers-reduced-motion: reduce)"); + // eslint-disable-next-line react-hooks/set-state-in-effect + setReduced(query.matches); + const on = () => setReduced(query.matches); + query.addEventListener("change", on); + return () => query.removeEventListener("change", on); + }, []); + return reduced; +} + +const usd = (n: number) => `$${n.toLocaleString("en-US")}`; +const toneText = (ok: boolean) => (ok ? "text-emerald-600 dark:text-emerald-400" : "text-red-600 dark:text-red-400"); + +function Gauge({ label, text, fill, goal, ok, goalText }: { label: string; text: string; fill: number; goal: number; ok: boolean; goalText: string }) { + const pct = (n: number) => `${Math.round(Math.max(0, Math.min(1, n)) * 100)}%`; + return ( +
+

{label}

+

{text}

+
+
+
+
+

{goalText}

+
+ ); +} + +function UtilBar({ label, value, note }: { label: string; value: number; note?: string }) { + const tone = utilTone(value); + const color = tone === "bad" ? "bg-red-500" : tone === "warn" ? "bg-amber-500" : "bg-emerald-500"; + const percent = Math.round(value * 100); + return ( +
+
+ {label} + {note ?? `${percent}%`} +
+
+
+
+
+ ); +} + +/** 24 bars, one per hour: the traffic of the day, coloured by how the system did while it ran. */ +function Timeline({ round, sim, step, ran }: { round: SysdesignRound; sim: SimResult; step: number; ran: boolean }) { + const max = Math.max(1, ...round.traffic); + return ( +
+
+ {round.traffic.map((load, t) => { + const result = sim.steps[t]!; + const seen = ran && t <= step; + const color = !seen ? "bg-muted-foreground/35" : result.status === "down" ? "bg-red-500" : result.status === "slow" ? "bg-amber-500" : "bg-emerald-500"; + const inOutage = round.outage && t >= round.outage.from && t <= round.outage.to; + const inBatch = round.batchJob && t >= round.batchJob.from && t <= round.batchJob.to; + return ( +
+
+ {inOutage || inBatch ? : null} +
+ ); + })} +
+
+ 00:00 + 12:00 + 23:00 +
+

+ One bar is one hour of traffic. + {round.outage ? " Red line: a zone fails." : ""} + {round.batchJob ? " Amber line: the report job runs." : ""} +

+
+ ); +} + +export default function SysdesignPlay({ round, attempt, locked, sounds, onFinish }: GamePlayProps) { + const reduced = useReducedMotion(); + const [picked, setPicked] = useState([]); + const [phase, setPhase] = useState<"plan" | "run" | "done">("plan"); + const [step, setStep] = useState(0); + const [runSim, setRunSim] = useState(null); + const [hints, setHints] = useState(0); + const [notice, setNotice] = useState(null); + const [shaking, setShaking] = useState(false); + const finishRef = useRef(onFinish); + // eslint-disable-next-line react-hooks/refs -- keeps the latest callback for timers that outlive a render + finishRef.current = onFinish; + const lastStatus = useRef("ok"); + const runPicked = useRef([]); + + const baseline = useMemo(() => simulate(round, []), [round]); + const preview = useMemo(() => simulate(round, picked), [round, picked]); + const deltas = useMemo(() => Object.fromEntries(round.changes.map((c) => [c.id, costDelta(round, c.id)])), [round]); + const forecastOk = useMemo(() => evaluateGoals(round.goals, preview).every((g) => g.met), [round, preview]); + + // A new attempt (or a new round) starts from scratch. + useEffect(() => { + // eslint-disable-next-line react-hooks/set-state-in-effect + setPicked([]); + setPhase("plan"); + setStep(0); + setRunSim(null); + setHints(0); + setNotice(null); + lastStatus.current = "ok"; + sounds.alarm(); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [attempt, round.id]); + + // Plays the day, one hour at a time. + useEffect(() => { + if (phase !== "run" || !runSim) return; + const current = runSim.steps[step]; + if (current) { + if (current.status !== "ok" && lastStatus.current === "ok") sounds.alarm(); + lastStatus.current = current.status; + } + const wait = step >= STEPS - 1 ? 700 : reduced ? STEP_MS_REDUCED : STEP_MS; + const timer = window.setTimeout(() => { + if (step >= STEPS - 1) { + setPhase("done"); + finishRef.current({ changes: runPicked.current }); + } else { + setStep(step + 1); + } + }, wait); + return () => window.clearTimeout(timer); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [phase, step, runSim, reduced]); + + const toggle = useCallback( + (id: string) => { + if (locked || phase === "run") return; + if (phase === "done") { + setPhase("plan"); + setRunSim(null); + } + setNotice(null); + if (picked.includes(id)) { + sounds.key(); + setPicked(picked.filter((p) => p !== id)); + return; + } + if (picked.length >= round.maxChanges) { + sounds.error(); + setShaking(true); + window.setTimeout(() => setShaking(false), 450); + setNotice(`You can use only ${round.maxChanges} changes. Remove one first.`); + return; + } + sounds.snap(); + setPicked([...picked, id]); + }, + [locked, phase, picked, round.maxChanges, sounds], + ); + + function run() { + if (locked || phase === "run") return; + const sim = simulate(round, picked); + runPicked.current = picked; + lastStatus.current = "ok"; + setNotice(null); + setRunSim(sim); + setStep(0); + setPhase("run"); + sounds.boot(); + sounds.whoosh(); + } + + function hint() { + if (hints >= round.hints.length) return; + sounds.ok(); + setHints(hints + 1); + } + + function clearAll() { + if (locked || phase === "run") return; + sounds.key(); + setPicked([]); + setNotice(null); + if (phase === "done") { + setPhase("plan"); + setRunSim(null); + } + } + + const running = phase === "run"; + const shown = running && runSim ? runSim : preview; + const current = running && runSim ? runSim.steps[step]! : null; + const showFinal = phase === "done"; + const goals = round.goals; + + let availability = shown.availability; + if (current && runSim) { + let load = 0; + let ok = 0; + for (let t = 0; t <= step; t++) { + load += runSim.steps[t]!.load; + ok += runSim.steps[t]!.load * runSim.steps[t]!.success; + } + availability = load > 0 ? Math.round((ok / load) * 10000) / 100 : 100; + } + const p95 = current ? current.p95Ms : shown.p95Ms; + const cost = current ? current.costToDate : shown.costUsd; + const checks = evaluateGoals(goals, shown); + const allMet = checks.every((c) => c.met); + const peakReplica = Math.max(0, ...shown.steps.map((s) => s.replicaUtil)); + const m = shown.model; + const resolved = showFinal ? allMet : forecastOk; + const lines = [...shown.costLines].sort((a, b) => b.usd - a.usd); + const costMax = Math.max(1, ...lines.map((l) => l.usd)); + + return ( +
+ {/* Incident banner */} +
+ {!resolved ? : null} + +
+

+ {resolved ? (showFinal ? "Incident resolved" : "Forecast looks stable. Press Run to prove it.") : "Incident"} +

+

{round.incident}

+
+
+ +
+ {/* Left: gauges, diagram, timeline, bars */} +
+
+

{running ? `Live, hour ${String(step).padStart(2, "0")}:00` : showFinal ? "Result of the run" : "Forecast"}

+ {running ? ( + + Running + + ) : null} +
+ +
+ + = goals.minAvailability} goalText={`goal ${goals.minAvailability}%`} /> + +
+

Prices are illustrative round numbers for the game. They are not AWS quotes.

+ + + + + +
+

{current ? "How busy, now" : "How busy, at the peak"}

+ + + {m.db.replicas > 0 ? : null} + {m.cache.on ? : null} + {m.queue.on ? : null} +
+ +
+ Where the money goes +
    + {lines.map((l) => ( +
  • +
    + {l.label} + {usd(l.usd)} +
    +
    +
    +
    +
  • + ))} +
+

Today it is {usd(baseline.costUsd)} a month with no changes.

+
+
+ + {/* Right: goals, change cards, controls */} +
+
+

{showFinal ? "Result: your goals" : "Your goals"}

+
    + {checks.map((c) => ( +
  • + + {c.met ? : } + + + {c.label} {c.target} + {showFinal ? "Result" : running ? "This run" : "Forecast"}: {c.actual} + +
  • + ))} +
+
+ +
+
+

Pick your changes

+

+ + {Array.from({ length: round.maxChanges }, (_, i) => ( + + ))} + + {round.maxChanges - picked.length} of {round.maxChanges} left +

+
+ {notice ? ( +

+ {notice} +

+ ) : null} +
    + {round.changes.map((c) => { + const index = picked.indexOf(c.id); + const on = index >= 0; + const delta = deltas[c.id] ?? 0; + return ( +
  • + +
  • + ); + })} +
+
+ + {hints > 0 ? ( +
+

+ Clues +

+
    + {round.hints.slice(0, hints).map((h) => ( +
  1. {h}
  2. + ))} +
+
+ ) : null} + +
+ {running ? ( + <> + + + + ) : ( + + )} + + +
+
+
+
+ ); +} diff --git a/frontend/src/components/games/types.ts b/frontend/src/components/games/types.ts new file mode 100644 index 00000000..c5a7947d --- /dev/null +++ b/frontend/src/components/games/types.ts @@ -0,0 +1,19 @@ +import type { GameSounds } from "@/lib/games/audio"; + +/** + * What the game shell hands to each game's play component. The component draws the board or the + * terminal and lets the player act; it calls `onFinish` when the player says they are done. The + * shell then replays the submission with the shared engine, shows the result and the celebration, + * and (for a signed-in learner) records it on the server. + */ +export type GamePlayProps = { + round: Round; + /** 0 easy, 1 medium, 2 hard. */ + roundIndex: number; + /** Changes when the player retries, so the component starts the round from scratch. */ + attempt: number; + /** True while the shell is checking a submission: ignore input. */ + locked: boolean; + sounds: GameSounds; + onFinish: (submission: Submission) => void; +}; diff --git a/frontend/src/lib/games/audio.ts b/frontend/src/lib/games/audio.ts new file mode 100644 index 00000000..075e45d4 --- /dev/null +++ b/frontend/src/lib/games/audio.ts @@ -0,0 +1,155 @@ +"use client"; + +// Sound effects for the daily games, made with the Web Audio API so there are no files to load. +// They follow the app's one sound switch (isSoundEnabled), which is already off for people who ask +// their system for reduced motion. Nothing plays before the learner has interacted with the page. + +import { isSoundEnabled, setSoundEnabled } from "@/lib/sound-feedback"; + +type Wave = OscillatorType; + +let context: AudioContext | null = null; +const lastPlayed = new Map(); + +function audio(): AudioContext | null { + if (typeof window === "undefined" || !isSoundEnabled()) return null; + const Ctor = window.AudioContext ?? (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext; + if (!Ctor) return null; + context ??= new Ctor(); + if (context.state === "suspended") void context.resume(); + return context; +} + +/** Skip a sound that would repeat inside `gap` milliseconds, so held keys do not machine-gun. */ +function throttled(name: string, gap: number): boolean { + const now = Date.now(); + if (now - (lastPlayed.get(name) ?? 0) < gap) return true; + lastPlayed.set(name, now); + return false; +} + +function tone(ctx: AudioContext, opts: { freq: number; to?: number; start?: number; length: number; wave?: Wave; gain?: number }) { + const start = ctx.currentTime + (opts.start ?? 0); + const osc = ctx.createOscillator(); + const amp = ctx.createGain(); + osc.type = opts.wave ?? "sine"; + osc.frequency.setValueAtTime(opts.freq, start); + if (opts.to) osc.frequency.exponentialRampToValueAtTime(opts.to, start + opts.length); + const peak = opts.gain ?? 0.16; + amp.gain.setValueAtTime(0.0001, start); + amp.gain.exponentialRampToValueAtTime(peak, start + 0.01); + amp.gain.exponentialRampToValueAtTime(0.0001, start + opts.length); + osc.connect(amp).connect(ctx.destination); + osc.start(start); + osc.stop(start + opts.length + 0.05); +} + +function noise(ctx: AudioContext, opts: { start?: number; length: number; from: number; to: number; gain?: number }) { + const start = ctx.currentTime + (opts.start ?? 0); + const frames = Math.max(1, Math.floor(ctx.sampleRate * opts.length)); + const buffer = ctx.createBuffer(1, frames, ctx.sampleRate); + const data = buffer.getChannelData(0); + for (let i = 0; i < frames; i++) data[i] = Math.random() * 2 - 1; + const source = ctx.createBufferSource(); + source.buffer = buffer; + const filter = ctx.createBiquadFilter(); + filter.type = "bandpass"; + filter.frequency.setValueAtTime(opts.from, start); + filter.frequency.exponentialRampToValueAtTime(opts.to, start + opts.length); + const amp = ctx.createGain(); + const peak = opts.gain ?? 0.12; + amp.gain.setValueAtTime(0.0001, start); + amp.gain.exponentialRampToValueAtTime(peak, start + 0.02); + amp.gain.exponentialRampToValueAtTime(0.0001, start + opts.length); + source.connect(filter).connect(amp).connect(ctx.destination); + source.start(start); +} + +const NOTE = { c5: 523.25, d5: 587.33, e5: 659.25, g5: 783.99, a5: 880, b5: 987.77, c6: 1046.5, e6: 1318.5, g6: 1568 }; + +/** Every effect a game may play. Each returns quietly when sound is off. */ +export const gameSounds = { + /** A key press in a terminal. */ + key() { + const ctx = audio(); + if (!ctx || throttled("key", 35)) return; + tone(ctx, { freq: 1500 + Math.random() * 400, length: 0.025, wave: "square", gain: 0.035 }); + }, + /** A command sent. */ + enter() { + const ctx = audio(); + if (!ctx || throttled("enter", 60)) return; + tone(ctx, { freq: 420, to: 300, length: 0.07, wave: "triangle", gain: 0.1 }); + }, + /** A small step forward: a clue found, a piece placed. */ + ok() { + const ctx = audio(); + if (!ctx || throttled("ok", 80)) return; + tone(ctx, { freq: NOTE.e5, length: 0.12, gain: 0.12 }); + tone(ctx, { freq: NOTE.a5, start: 0.08, length: 0.16, gain: 0.12 }); + }, + /** A mistake. */ + error() { + const ctx = audio(); + if (!ctx || throttled("error", 120)) return; + tone(ctx, { freq: 170, to: 110, length: 0.22, wave: "sawtooth", gain: 0.1 }); + }, + /** A piece snaps into place. */ + snap() { + const ctx = audio(); + if (!ctx || throttled("snap", 50)) return; + noise(ctx, { length: 0.05, from: 1800, to: 900, gain: 0.09 }); + tone(ctx, { freq: 640, to: 520, length: 0.06, wave: "triangle", gain: 0.08 }); + }, + /** A pickup, such as a counter ticking up. */ + coin() { + const ctx = audio(); + if (!ctx || throttled("coin", 60)) return; + tone(ctx, { freq: NOTE.b5, length: 0.07, wave: "square", gain: 0.06 }); + tone(ctx, { freq: NOTE.e6, start: 0.07, length: 0.2, wave: "square", gain: 0.06 }); + }, + /** Traffic or a command moving fast. */ + whoosh() { + const ctx = audio(); + if (!ctx) return; + noise(ctx, { length: 0.4, from: 300, to: 3200, gain: 0.1 }); + }, + /** A system is in trouble. */ + alarm() { + const ctx = audio(); + if (!ctx || throttled("alarm", 400)) return; + for (let i = 0; i < 3; i++) tone(ctx, { freq: i % 2 ? 620 : 880, start: i * 0.14, length: 0.12, wave: "square", gain: 0.07 }); + }, + /** A run is starting. */ + boot() { + const ctx = audio(); + if (!ctx) return; + tone(ctx, { freq: 220, to: 880, length: 0.35, wave: "triangle", gain: 0.09 }); + }, + /** A round solved. More stars play a longer, brighter run of notes. */ + win(stars: number) { + const ctx = audio(); + if (!ctx) return; + const run = [NOTE.c5, NOTE.e5, NOTE.g5, NOTE.c6, NOTE.e6, NOTE.g6].slice(0, 3 + Math.max(1, Math.min(3, stars))); + run.forEach((freq, i) => tone(ctx, { freq, start: i * 0.09, length: 0.28, wave: "triangle", gain: 0.13 })); + noise(ctx, { start: 0.05, length: 0.5, from: 4000, to: 9000, gain: 0.04 }); + }, + /** A whole set of three rounds finished. */ + fanfare() { + const ctx = audio(); + if (!ctx) return; + [NOTE.c5, NOTE.c5, NOTE.c5, NOTE.g5, NOTE.e5, NOTE.g5, NOTE.c6].forEach((freq, i) => + tone(ctx, { freq, start: i * 0.11, length: i === 6 ? 0.6 : 0.16, wave: "square", gain: 0.07 }), + ); + }, + /** A round not solved yet. Gentle, so trying again feels fine. */ + lose() { + const ctx = audio(); + if (!ctx) return; + [NOTE.g5, NOTE.e5, NOTE.c5].forEach((freq, i) => tone(ctx, { freq: freq / 2, start: i * 0.14, length: 0.22, wave: "sine", gain: 0.12 })); + }, +}; + +export type GameSounds = typeof gameSounds; + +export { isSoundEnabled, setSoundEnabled }; diff --git a/frontend/src/lib/games/client.ts b/frontend/src/lib/games/client.ts new file mode 100644 index 00000000..e46ba94f --- /dev/null +++ b/frontend/src/lib/games/client.ts @@ -0,0 +1,13 @@ +import { apiFetch } from "@/lib/api-client"; +import type { DailyGamesView, SubmitRoundResult } from "@/shared/api/games"; +import type { GameId } from "@/shared/games/types"; + +/** Today's games. Open to visitors; a signed-in learner also gets their progress. */ +export function fetchDailyGames(): Promise { + return apiFetch("/api/v1/games/daily"); +} + +/** Send a finished round to be replayed on the server. Needs a signed-in learner. */ +export function submitGameRound(game: GameId, roundIndex: number, submission: unknown): Promise { + return apiFetch(`/api/v1/games/${game}/rounds/${roundIndex}/submit`, { method: "POST", json: { submission } }); +} diff --git a/frontend/src/lib/learn-areas.ts b/frontend/src/lib/learn-areas.ts index 8bae7c15..a62323ce 100644 --- a/frontend/src/lib/learn-areas.ts +++ b/frontend/src/lib/learn-areas.ts @@ -73,10 +73,10 @@ export const LEARN_AREAS: readonly LearnArea[] = [ name: "Puzzles", short: "Puzzles", href: "/puzzles", - status: "coming-soon", - tagline: "One new puzzle a day. Solve it, then climb the daily leaderboard.", + status: "live", + tagline: "Three short games a day. Fix a system, explore a server, repair a container.", summary: - "Several kinds of daily puzzles that use what you learn. One a day, the same for everyone, so you can compete with everyone on today's leaderboard.", + "Three playable games, new every day: fix a broken system design, explore a Linux server with real commands, and repair a Docker container. Each round you solve earns a little XP.", matches: ["/puzzles"], }, { diff --git a/frontend/src/shared/api/games.ts b/frontend/src/shared/api/games.ts new file mode 100644 index 00000000..f42f19a0 --- /dev/null +++ b/frontend/src/shared/api/games.ts @@ -0,0 +1,46 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// Wire types for the daily games (docs/17-daily-games.mdx). +import type { GameId, RoundBase, Stars } from "../games/types"; + +/** What one solved round left behind. */ +export type GameRoundProgress = { roundIndex: number; stars: Stars; score: number }; + +export type DailyGameView = { + id: GameId; + title: string; + tagline: string; + /** Today's three rounds. The game component knows its own round shape. */ + rounds: Array>; + /** Solved rounds only, for a signed-in learner. */ + progress: GameRoundProgress[]; + /** All three rounds solved today. */ + setComplete: boolean; +}; + +export type DailyGamesView = { + /** The learner's local day (UTC for a visitor who is not signed in). */ + dayKey: string; + /** When the next set opens, as an ISO time. */ + resetsAt: string; + signedIn: boolean; + /** XP earned from the games today. */ + xpToday: number; + /** XP a learner can still earn from the games today. */ + xpLeft: number; + games: DailyGameView[]; +}; + +export type SubmitRoundBody = { submission: unknown }; + +export type SubmitRoundResult = { + passed: boolean; + stars: Stars; + score: number; + message: string; + /** This round was already solved today; nothing new was recorded for XP. */ + alreadySolved: boolean; + xpAwarded: number; + /** Extra XP for finishing all three rounds of the game today. */ + setBonus: number; + setComplete: boolean; +}; diff --git a/frontend/src/shared/games/daily.ts b/frontend/src/shared/games/daily.ts new file mode 100644 index 00000000..6eafd3bb --- /dev/null +++ b/frontend/src/shared/games/daily.ts @@ -0,0 +1,45 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +import { DIFFICULTIES, type Difficulty } from "./types"; + +/** Whole days since 1970-01-01 for a "YYYY-MM-DD" day key. Pure, no time zone involved. */ +export function dayNumber(dayKey: string): number { + const [y, m, d] = dayKey.split("-").map(Number); + return Math.floor(Date.UTC(y!, (m ?? 1) - 1, d ?? 1) / 86_400_000); +} + +/** A small stable hash, so two games do not rotate in step. */ +export function hashString(text: string): number { + let h = 2166136261; + for (let i = 0; i < text.length; i++) { + h ^= text.charCodeAt(i); + h = Math.imul(h, 16777619); + } + return h >>> 0; +} + +/** + * One scenario per difficulty for the day. The pool for a difficulty is walked in a fixed order, + * so a scenario does not repeat until the whole pool has been shown, and a game with N scenarios + * per difficulty shows each one every N days. The start offset differs per game and difficulty. + */ +export function pickDaily(pool: readonly T[], dayKey: string, gameId: string): T[] { + const day = dayNumber(dayKey); + return DIFFICULTIES.map((difficulty) => { + const tier = pool.filter((round) => round.difficulty === difficulty); + if (tier.length === 0) throw new Error(`${gameId}: no ${difficulty} scenarios`); + const offset = hashString(`${gameId}:${difficulty}`) % tier.length; + return tier[(day + offset) % tier.length]!; + }); +} + +/** Seeded pseudo random numbers (mulberry32), for engines that need repeatable noise. */ +export function seededRandom(seed: number): () => number { + let a = seed >>> 0; + return () => { + a = (a + 0x6d2b79f5) >>> 0; + let t = a; + t = Math.imul(t ^ (t >>> 15), t | 1); + t ^= t + Math.imul(t ^ (t >>> 7), t | 61); + return ((t ^ (t >>> 14)) >>> 0) / 4294967296; + }; +} diff --git a/frontend/src/shared/games/docker/builder.ts b/frontend/src/shared/games/docker/builder.ts new file mode 100644 index 00000000..9cbb2f83 --- /dev/null +++ b/frontend/src/shared/games/docker/builder.ts @@ -0,0 +1,484 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The build simulation for the Docker Commands game. The player puts together a Dockerfile (pieces +// in an order) or a small compose file (one choice per blank). `simulateBuild` reads the result the +// way Docker would and reports whether it builds, how long a build and a rebuild take, how big the +// image is, and whether the app can be reached. Pure and deterministic, and it never throws. + +export type BuildKind = "dockerfile" | "compose"; + +export type ComposeFact = { + service: string; + key: "port" | "env" | "depends" | "volume" | "network" | "decl-volume" | "decl-network"; + value: string; +}; + +export type BuildPiece = { + id: string; + /** What the player reads, for example `RUN npm ci`. */ + text: string; + /** Compose only: the blank this piece can fill. */ + slot?: string; + /** Compose only: what the piece means. */ + facts?: ComposeFact[]; +}; + +/** The app a Dockerfile builds. */ +export type AppSpec = { + runtime: "node" | "python"; + /** The file or pattern that lists the dependencies, as written in COPY. */ + manifest: string; + /** What the app listens on when nothing sets the port. */ + defaultPort: number; + /** An environment variable the app reads for its port. */ + portEnv?: string; + /** Start commands that work, for example `node server.js`. */ + start: string[]; +}; + +export type StackService = { + image: string; + sizeMb: number; + /** The port the app listens on inside its container. */ + port?: number; + requiredEnv?: string[]; + dataPath?: string; + /** An environment variable that must name another service (DB_HOST=db). */ + hostEnv?: { key: string; value: string }; + mustDependOn?: string[]; + /** Services this one talks to, so they must share a network. */ + mustReach?: string[]; +}; + +export type StackSpec = { + services: Record; + publish: { service: string; host: number }; + /** These two services must not share a network. */ + isolate?: [string, string]; +}; + +export type ComposeLine = { text: string } | { slot: string }; + +export type BuildSlot = { id: string; label: string; indent: number }; + +export type BuildGoal = + | { kind: "builds"; label: string } + | { kind: "runs"; label: string } + | { kind: "reachable"; port: number; label: string } + | { kind: "size"; maxMb: number; label: string } + | { kind: "rebuild"; maxSec: number; label: string } + | { kind: "persists"; label: string } + | { kind: "isolated"; label: string }; + +export type BuildData = { + kind: BuildKind; + pieces: BuildPiece[]; + app?: AppSpec; + slots?: BuildSlot[]; + skeleton?: ComposeLine[]; + fixed?: ComposeFact[]; + stack?: StackSpec; +}; + +export type BuildLayer = { + /** The instruction or service, for example `RUN npm ci`. */ + label: string; + sizeMb: number; + seconds: number; + /** True when a rebuild after a code change reuses this layer. */ + cached: boolean; + failed: boolean; +}; + +export type BuildReport = { + kind: BuildKind; + /** The image (or the compose file) was built. */ + ok: boolean; + /** Why the build stopped, or null. */ + error: string | null; + layers: BuildLayer[]; + warnings: string[]; + /** Seconds for a first build. */ + coldSec: number; + /** Seconds to build again after one source file changed. */ + rebuildSec: number; + sizeMb: number; + cacheFriendly: boolean; + /** The container (or every service) started. */ + started: boolean; + /** Something answers on `port`. */ + reachable: boolean; + port: number | null; + persists: boolean | null; + isolated: boolean | null; + runLog: string[]; +}; + +const BASES: Record = { + "node:20": { sizeMb: 1100, runtime: "node" }, + "node:20-slim": { sizeMb: 240, runtime: "node" }, + "node:20-alpine": { sizeMb: 180, runtime: "node" }, + "python:3.12": { sizeMb: 1010, runtime: "python" }, + "python:3.12-slim": { sizeMb: 150, runtime: "python" }, + "ubuntu:22.04": { sizeMb: 77, runtime: "none" }, + "alpine:3.19": { sizeMb: 8, runtime: "none" }, +}; + +const round1 = (n: number) => Math.round(n * 10) / 10; + +function emptyReport(kind: BuildKind): BuildReport { + return { + kind, ok: false, error: null, layers: [], warnings: [], coldSec: 0, rebuildSec: 0, sizeMb: 0, cacheFriendly: false, + started: false, reachable: false, port: null, persists: null, isolated: null, runLog: [], + }; +} + +function normalizeCmd(arg: string): string { + const t = arg.trim(); + if (t.startsWith("[")) { + try { + const parsed: unknown = JSON.parse(t); + if (Array.isArray(parsed)) return parsed.map(String).join(" "); + } catch { + return t; + } + } + return t.replace(/\s+/g, " "); +} + +// --------------------------------------------------------------------------------------------- +// Dockerfile. + +function simulateDockerfile(data: BuildData, steps: string[]): BuildReport { + const report = emptyReport("dockerfile"); + const app = data.app; + if (!app) { + report.error = "This round has no app to build."; + return report; + } + const byId = new Map(data.pieces.map((p) => [p.id, p])); + const texts: string[] = []; + for (const id of steps) { + const piece = byId.get(id); + if (!piece) { + report.error = `Unknown piece "${id}".`; + return report; + } + texts.push(piece.text); + } + if (texts.length === 0) { + report.error = "The Dockerfile is empty. Add FROM first."; + return report; + } + + let base: { sizeMb: number; runtime: "node" | "python" | "none" } | null = null; + let workdir = "/"; + let workdirSet = false; + let manifestDir: string | null = null; + let sourceDir: string | null = null; + let installed = false; + const env: Record = {}; + let exposed: number | null = null; + let cmd: string | null = null; + let installIdx = -1; + let sourceIdx = -1; + let cmdIdx = -1; + let lastBuildIdx = -1; + let size = 0; + let cold = 0; + + const addLayer = (label: string, sizeMb: number, seconds: number, failed = false) => { + report.layers.push({ label, sizeMb: round1(sizeMb), seconds: round1(seconds), cached: false, failed }); + size += sizeMb; + cold += seconds; + }; + + for (let i = 0; i < texts.length; i++) { + const text = texts[i]!; + const space = text.indexOf(" "); + const op = (space < 0 ? text : text.slice(0, space)).toUpperCase(); + const arg = space < 0 ? "" : text.slice(space + 1).trim(); + if (i === 0 && op !== "FROM") { + addLayer(text, 0, 0, true); + report.error = "A Dockerfile must start with FROM. Put FROM first."; + return finishFailed(report, cold, size); + } + if (op === "FROM") { + if (i > 0) { + addLayer(text, 0, 0, true); + report.error = "This round uses one FROM only. Take the other FROM out."; + return finishFailed(report, cold, size); + } + base = BASES[arg] ?? null; + if (!base) { + addLayer(text, 0, 0, true); + report.error = `pull access denied for ${arg}: the image does not exist.`; + return finishFailed(report, cold, size); + } + addLayer(text, base.sizeMb, base.sizeMb / 40); + } else if (op === "WORKDIR") { + workdir = arg; + workdirSet = true; + addLayer(text, 0, 0.1); + } else if (op === "COPY") { + const [src] = arg.split(/\s+/); + if (src !== "." && src !== app.manifest) { + addLayer(text, 0, 0, true); + report.error = `COPY failed: "${src ?? ""}" was not found in the build folder.`; + return finishFailed(report, cold, size); + } + if (src === ".") { + sourceDir = workdir; + manifestDir = workdir; + sourceIdx = i; + addLayer(text, 4, 0.8); + } else { + manifestDir = workdir; + addLayer(text, 0.1, 0.2); + } + lastBuildIdx = i; + } else if (op === "RUN") { + const cmdText = normalizeCmd(arg); + const installs = app.runtime === "node" ? ["npm ci", "npm install"] : ["pip install -r requirements.txt", "pip install --no-cache-dir -r requirements.txt"]; + if (installs.includes(cmdText)) { + if (!base || base.runtime !== app.runtime) { + addLayer(text, 0, 0.3, true); + report.error = `/bin/sh: ${app.runtime === "node" ? "npm" : "pip"}: not found. The base image has no ${app.runtime === "node" ? "Node" : "Python"}.`; + return finishFailed(report, cold, size); + } + if (manifestDir !== workdir) { + addLayer(text, 0, 0.3, true); + report.error = app.runtime === "node" + ? "npm error: could not read package.json. Copy the dependency file before this RUN." + : "ERROR: Could not open requirements file. Copy requirements.txt before this RUN."; + return finishFailed(report, cold, size); + } + installed = true; + installIdx = i; + const heavy = app.runtime === "node" ? (cmdText === "npm ci" ? 34 : 46) : 28; + addLayer(text, app.runtime === "node" ? 95 : 60, heavy); + } else if (/^(npm start|npm run \w+|node |python )/.test(cmdText)) { + addLayer(text, 0, 60, true); + report.error = "The build never finishes: RUN runs while building. Start the app with CMD."; + return finishFailed(report, cold, size); + } else { + addLayer(text, 1, 1); + } + lastBuildIdx = i; + } else if (op === "ENV") { + const [k, v] = arg.split("="); + if (k && v !== undefined) env[k] = v.replace(/^"|"$/g, ""); + addLayer(text, 0, 0.1); + } else if (op === "EXPOSE") { + const port = Number(arg.split("/")[0]); + if (!Number.isInteger(port) || port < 1 || port > 65535) { + addLayer(text, 0, 0, true); + report.error = `EXPOSE needs a port number, not "${arg}".`; + return finishFailed(report, cold, size); + } + exposed = port; + addLayer(text, 0, 0.1); + } else if (op === "CMD") { + cmd = normalizeCmd(arg); + cmdIdx = i; + addLayer(text, 0, 0.1); + } else { + addLayer(text, 0, 0, true); + report.error = `Unknown instruction ${op}.`; + return finishFailed(report, cold, size); + } + } + + report.ok = true; + report.coldSec = round1(cold); + report.sizeMb = Math.round(size); + const boundary = sourceIdx === -1 ? Number.POSITIVE_INFINITY : sourceIdx; + let rebuild = 0; + report.layers.forEach((layer, i) => { + layer.cached = i < boundary; + rebuild += layer.cached ? 0.1 : layer.seconds; + }); + report.rebuildSec = round1(rebuild); + report.cacheFriendly = installIdx !== -1 && sourceIdx !== -1 && installIdx < sourceIdx; + if (cmdIdx !== -1 && cmdIdx < lastBuildIdx) report.warnings.push("CMD comes before COPY or RUN. It works, but keep CMD last so the file reads in order."); + if (!workdirSet) report.warnings.push("There is no WORKDIR, so the files land in the root folder."); + + // Run it. + const log = report.runLog; + const listening = env[app.portEnv ?? ""] !== undefined ? Number(env[app.portEnv ?? ""]) : app.defaultPort; + const entry = app.start[0] ?? ""; + if (cmd === null) { + log.push("The image has no CMD, so the container has nothing to run and stops at once."); + } else if (!app.start.includes(cmd)) { + log.push(`${cmd.split(" ")[0]}: command not found or wrong for this app. Expected something like: ${entry}`); + } else if (sourceDir === null || sourceDir !== workdir) { + log.push(app.runtime === "node" ? `Error: Cannot find module '${workdir === "/" ? "" : workdir}/server.js'` : `python: can't open file '${workdir === "/" ? "" : workdir}/app.py': No such file`); + } else if (!installed) { + log.push(app.runtime === "node" ? "Error: Cannot find module 'express'. The dependencies were not installed." : "ModuleNotFoundError: No module named 'flask'. The dependencies were not installed."); + } else { + report.started = true; + log.push(`app listening on port ${listening}`); + } + if (report.started) { + report.port = listening; + report.reachable = exposed !== null && exposed === listening; + if (exposed === null) log.push("Nothing is published: add EXPOSE with the port the app listens on."); + else if (!report.reachable) log.push(`The app listens on ${listening} but port ${exposed} is the one published. Connection reset.`); + else log.push(`localhost:${listening} answers. 200 OK`); + } + return report; +} + +function finishFailed(report: BuildReport, cold: number, size: number): BuildReport { + report.coldSec = round1(cold); + report.sizeMb = Math.round(size); + return report; +} + +// --------------------------------------------------------------------------------------------- +// Compose. + +function simulateCompose(data: BuildData, steps: string[]): BuildReport { + const report = emptyReport("compose"); + const stack = data.stack; + const slots = data.slots ?? []; + if (!stack) { + report.error = "This round has no stack to start."; + return report; + } + const picks = new Map(); + for (const step of steps) { + const [slot, id] = step.split(":"); + const piece = data.pieces.find((p) => p.id === id && p.slot === slot); + if (!slot || !id || !piece) { + report.error = `Unknown choice "${step}".`; + return report; + } + if (picks.has(slot)) { + report.error = `The blank "${slot}" was filled twice.`; + return report; + } + picks.set(slot, piece); + } + const empty = slots.filter((s) => !picks.has(s.id)); + if (empty.length > 0) { + report.error = `Fill every blank first (${empty.length} left).`; + return report; + } + + const facts: ComposeFact[] = [...(data.fixed ?? [])]; + for (const piece of picks.values()) facts.push(...(piece.facts ?? [])); + const declaredVolumes = new Set(facts.filter((f) => f.key === "decl-volume").map((f) => f.value)); + const declaredNetworks = new Set(facts.filter((f) => f.key === "decl-network").map((f) => f.value)); + const names = Object.keys(stack.services); + const of = (service: string, key: ComposeFact["key"]) => facts.filter((f) => f.service === service && f.key === key).map((f) => f.value); + + for (const name of names) { + for (const v of of(name, "volume")) { + const src = v.split(":")[0]!; + if (!src.startsWith(".") && !src.startsWith("/") && !declaredVolumes.has(src)) { + report.error = `service "${name}" refers to undefined volume ${src}: invalid compose project`; + return report; + } + } + for (const n of of(name, "network")) { + if (!declaredNetworks.has(n)) { + report.error = `service "${name}" refers to undefined network ${n}: invalid compose project`; + return report; + } + } + for (const d of of(name, "depends")) { + if (!names.includes(d)) { + report.error = `service "${name}" depends on undefined service "${d}": invalid compose project`; + return report; + } + } + } + report.ok = true; + + // Start order: dependencies first. + const order: string[] = []; + const visit = (name: string, depth: number) => { + if (order.includes(name) || depth > 8) return; + for (const d of of(name, "depends")) visit(d, depth + 1); + order.push(name); + }; + names.forEach((n) => visit(n, 0)); + + const networksOf = (name: string) => { + const list = of(name, "network"); + return list.length ? list : ["default"]; + }; + const shares = (a: string, b: string) => networksOf(a).some((n) => networksOf(b).includes(n)); + const status = new Map(); + let size = 0; + let cold = 0; + for (const name of order) { + const svc = stack.services[name]!; + const seconds = round1(svc.sizeMb / 40); + report.layers.push({ label: `${name}: pull ${svc.image}`, sizeMb: svc.sizeMb, seconds, cached: false, failed: false }); + size += svc.sizeMb; + cold += seconds; + const env = new Map(of(name, "env").map((e) => [e.split("=")[0]!, e.slice(e.indexOf("=") + 1)])); + let crash: string | null = null; + for (const key of svc.requiredEnv ?? []) if (!env.get(key)) crash ??= `${key} is not set. The container exited with code 1.`; + for (const d of svc.mustDependOn ?? []) if (!of(name, "depends").includes(d)) crash ??= `started before ${d} was ready: connect ECONNREFUSED. Add depends_on: [${d}].`; + if (svc.hostEnv && env.get(svc.hostEnv.key) !== svc.hostEnv.value) { + const got = env.get(svc.hostEnv.key); + crash ??= got === "localhost" || got === undefined ? `connect ECONNREFUSED 127.0.0.1: "${got ?? "(unset)"}" is the container itself. Use the service name ${svc.hostEnv.value}.` : `getaddrinfo ENOTFOUND ${got}`; + } + for (const target of svc.mustReach ?? []) { + if (!shares(name, target)) crash ??= `getaddrinfo ENOTFOUND ${target}: ${name} and ${target} share no network.`; + else if (status.get(target) === false) crash ??= `connect ECONNREFUSED ${target}: ${target} is not running.`; + } + status.set(name, crash === null); + report.runLog.push(crash === null ? `${name} | started` : `${name} | ${crash}`); + if (crash) report.layers[report.layers.length - 1]!.failed = true; + } + report.coldSec = round1(cold); + report.rebuildSec = round1(cold); + report.sizeMb = Math.round(size); + report.cacheFriendly = true; + report.started = order.every((n) => status.get(n) === true); + + const pub = stack.publish; + const pubSvc = stack.services[pub.service]; + const mapped = of(pub.service, "port").some((p) => { + const [h, c] = p.split(":"); + return Number(h) === pub.host && Number(c) === pubSvc?.port; + }); + report.port = pub.host; + report.reachable = status.get(pub.service) === true && mapped; + if (status.get(pub.service) === true && !mapped) report.runLog.push(`localhost:${pub.host} does not answer: the published port does not lead to port ${pubSvc?.port ?? "?"} inside ${pub.service}.`); + else if (report.reachable) report.runLog.push(`localhost:${pub.host} answers. 200 OK`); + + const dataServices = names.filter((n) => stack.services[n]!.dataPath); + if (dataServices.length > 0) { + report.persists = dataServices.every((n) => of(n, "volume").some((v) => v.split(":")[1] === stack.services[n]!.dataPath)); + if (!report.persists) report.warnings.push("The database data is not on a volume, so it is lost when the container is removed."); + } + if (stack.isolate) report.isolated = !shares(stack.isolate[0], stack.isolate[1]); + if (report.isolated === false) report.warnings.push(`${stack.isolate![0]} can reach ${stack.isolate![1]} directly. Keep them on different networks.`); + return report; +} + +export function simulateBuild(data: BuildData, steps: string[]): BuildReport { + try { + return data.kind === "compose" ? simulateCompose(data, steps) : simulateDockerfile(data, steps); + } catch { + const report = emptyReport(data.kind); + report.error = "The build could not be read."; + return report; + } +} + +export function checkBuildGoal(report: BuildReport, goal: BuildGoal): boolean { + switch (goal.kind) { + case "builds": return report.ok; + case "runs": return report.ok && report.started; + case "reachable": return report.started && report.reachable && report.port === goal.port; + case "size": return report.ok && report.sizeMb <= goal.maxMb; + case "rebuild": return report.ok && report.rebuildSec <= goal.maxSec; + case "persists": return report.persists === true; + case "isolated": return report.isolated === true; + } +} diff --git a/frontend/src/shared/games/docker/daemon.ts b/frontend/src/shared/games/docker/daemon.ts new file mode 100644 index 00000000..d5f30289 --- /dev/null +++ b/frontend/src/shared/games/docker/daemon.ts @@ -0,0 +1,1453 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// A tiny virtual Docker daemon for the Docker Commands game. There is no real Docker here: a +// world is plain data (containers, images, networks, volumes), and `runLine` runs one typed +// command against it and returns the output lines. Everything is pure and deterministic (no clock, +// no Math.random): ids come from a hash, and time is a counter that goes up once per command. +// It never throws; a bad command returns an error line, like a real shell would. + +import { hashString } from "../daily"; + +export type Status = "created" | "running" | "exited" | "restarting"; +export type RestartPolicy = "no" | "always" | "on-failure" | "unless-stopped"; + +export type PortMap = { host: number; container: number }; +export type Mount = { source: string; target: string; kind: "volume" | "bind" }; + +export type Container = { + id: string; + name: string; + /** "repo:tag" */ + image: string; + command: string; + status: Status; + exitCode: number; + oomKilled: boolean; + restartCount: number; + ports: PortMap[]; + env: Record; + mounts: Mount[]; + networks: string[]; + restart: RestartPolicy; + /** Memory limit in MB, 0 means no limit. */ + memoryMb: number; + logs: string[]; + /** When the container was created: a tick number, or a ready made label like "2 hours". */ + createdAt: number | string; + /** When the status last changed: a tick number, or a ready made label like "2 hours". */ + since: number | string; + project?: string; + service?: string; +}; + +export type LocalImage = { id: string; repo: string; tag: string; sizeMb: number; created: string }; + +export type ComposeService = { + name: string; + image: string; + ports: string[]; + env: Record; + volumes: string[]; + dependsOn: string[]; + restart?: RestartPolicy; +}; + +export type DockerWorld = { + /** Goes up by one for every command. */ + tick: number; + /** Counts things created, so new ids are different and repeatable. */ + seq: number; + containers: Container[]; + images: LocalImage[]; + networks: string[]; + volumes: string[]; + /** Set only in scenarios that show a compose file. */ + compose?: { project: string; file: string[]; services: ComposeService[] }; +}; + +export type OutLine = { kind: "out" | "err" | "sys"; text: string }; + +export type DockerEvent = { + type: "created" | "started" | "stopped" | "crashed" | "restarting" | "removed" | "pulled" | "network" | "volume" | "blocked" | "pruned"; + name: string; +}; + +export type RunResult = { lines: OutLine[]; ok: boolean; events: DockerEvent[] }; + +// --------------------------------------------------------------------------------------------- +// What each image does when it runs. Anything not listed behaves like a small generic app. + +export type ImageSpec = { + sizeMb: number; + /** The port the app listens on inside the container. */ + port?: number; + cmd: string; + /** Environment variables that must be set, or the app stops at once. */ + requiredEnv?: string[]; + /** The log lines printed when a required variable is missing. */ + missingEnv?: Record; + /** An environment variable that names a host (the database) the app must be able to reach. */ + needsHost?: string; + /** Memory the app needs, in MB. With a smaller limit it is killed (exit 137). */ + memoryMb?: number; + /** Memory it uses while running, in MB. */ + useMb?: number; + /** What `curl` gets back. */ + body?: string; + startLogs: string[]; + dataPath?: string; + /** What the app prints when it listens but a client sends it a non-HTTP request. */ + rawPort?: boolean; +}; + +const GENERIC: ImageSpec = { sizeMb: 90, cmd: "app", startLogs: ["app started"] }; + +export const CATALOG: Record = { + "nginx:latest": { sizeMb: 188, port: 80, cmd: "nginx -g 'daemon off;'", body: "

Welcome to nginx!

", useMb: 8, startLogs: ["/docker-entrypoint.sh: Configuration complete; ready for start up", "nginx: [notice] start worker processes"] }, + "nginx:1.25": { sizeMb: 187, port: 80, cmd: "nginx -g 'daemon off;'", body: "

Welcome to nginx!

", useMb: 8, startLogs: ["/docker-entrypoint.sh: Configuration complete; ready for start up", "nginx: [notice] start worker processes"] }, + "nginx:1.25-alpine": { sizeMb: 43.2, port: 80, cmd: "nginx -g 'daemon off;'", body: "

Welcome to nginx!

", useMb: 5, startLogs: ["/docker-entrypoint.sh: Configuration complete; ready for start up", "nginx: [notice] start worker processes"] }, + "postgres:16": { + sizeMb: 432, port: 5432, cmd: "postgres", requiredEnv: ["POSTGRES_PASSWORD"], dataPath: "/var/lib/postgresql/data", memoryMb: 100, useMb: 45, rawPort: true, + missingEnv: { + POSTGRES_PASSWORD: [ + "Error: Database is uninitialized and superuser password is not specified.", + " You must specify POSTGRES_PASSWORD to a non-empty value for the", + " superuser. For example, \"-e POSTGRES_PASSWORD=password\" on \"docker run\".", + ], + }, + startLogs: ["PostgreSQL init process complete; ready for start up.", "LOG: database system is ready to accept connections"], + }, + "redis:7": { sizeMb: 117, port: 6379, cmd: "redis-server", useMb: 6, rawPort: true, startLogs: ["Ready to accept connections tcp"] }, + "shop/web:2.0": { + sizeMb: 212, port: 3000, cmd: "node server.js", needsHost: "DB_HOST", useMb: 60, + body: "Shop is open: 3 products, connected to the database.", + startLogs: ["shop-web listening on :3000"], + }, + "acme/site:1.0": { sizeMb: 62, port: 80, cmd: "nginx -g 'daemon off;'", body: "Acme site v1 (old release)", useMb: 6, startLogs: ["site 1.0 ready"] }, + "acme/site:2.0": { + sizeMb: 64, port: 80, cmd: "nginx -g 'daemon off;'", requiredEnv: ["SITE_NAME"], body: "Acme site v2 (new release)", useMb: 6, + missingEnv: { SITE_NAME: ["site: fatal: SITE_NAME is required (example: -e SITE_NAME=Acme)"] }, + startLogs: ["site 2.0 ready"], + }, + "acme/worker:3.1": { + sizeMb: 310, cmd: "python worker.py", memoryMb: 400, useMb: 380, + startLogs: ["worker: loading model into memory (needs about 400 MB)", "worker: ready, waiting for jobs"], + }, + "shop/api:1.2": { sizeMb: 164, port: 4000, cmd: "node api.js", startLogs: ["api listening on :4000"] }, + "legacy/app:0.9": { sizeMb: 270, port: 8000, cmd: "python app.py", startLogs: ["legacy app started"] }, +}; + +function specFor(image: string): ImageSpec { + return CATALOG[image] ?? GENERIC; +} + +const COMMON_BINS = ["sh", "bash", "sleep", "env", "ls", "cat", "echo", "tail", "true", "false"]; + +// --------------------------------------------------------------------------------------------- +// Small helpers. + +export function hex(seed: string, length: number): string { + let out = ""; + for (let i = 0; out.length < length; i++) out += hashString(`${seed}:${i}`).toString(16).padStart(8, "0"); + return out.slice(0, length); +} + +const shortId = (id: string) => id.slice(0, 12); + +export function normalizeImage(ref: string): string { + const slash = ref.lastIndexOf("/"); + const colon = ref.lastIndexOf(":"); + return colon > slash ? ref : `${ref}:latest`; +} + +export function splitImage(ref: string): { repo: string; tag: string } { + const full = normalizeImage(ref); + const colon = full.lastIndexOf(":"); + return { repo: full.slice(0, colon), tag: full.slice(colon + 1) }; +} + +export function fmtSize(mb: number): string { + if (mb >= 1000) return `${(mb / 1000).toFixed(2).replace(/0$/, "")}GB`; + return `${mb < 100 ? mb.toFixed(1).replace(/\.0$/, "") : Math.round(mb)}MB`; +} + +function age(world: DockerWorld, value: number | string): string { + if (typeof value === "string") return value; + const diff = world.tick - value; + if (diff <= 0) return "Less than a second"; + const seconds = diff * 6; + return seconds < 60 ? `${seconds} seconds` : `${Math.floor(seconds / 60)} minutes`; +} + +function table(rows: string[][]): string[] { + const widths: number[] = []; + for (const row of rows) row.forEach((cell, i) => { widths[i] = Math.max(widths[i] ?? 0, cell.length); }); + return rows.map((row) => row.map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i]! + 2))).join("").trimEnd()); +} + +const clone = (value: T): T => JSON.parse(JSON.stringify(value)) as T; +export const cloneWorld = (world: DockerWorld): DockerWorld => clone(world); + +export function emptyWorld(): DockerWorld { + return { tick: 0, seq: 0, containers: [], images: [], networks: ["bridge", "host", "none"], volumes: [] }; +} + +export function makeImage(ref: string, created = "3 weeks ago"): LocalImage { + const { repo, tag } = splitImage(ref); + return { id: hex(`image:${repo}:${tag}`, 12), repo, tag, sizeMb: specFor(`${repo}:${tag}`).sizeMb, created }; +} + +export function danglingImage(seed: string, sizeMb: number, created = "5 days ago"): LocalImage { + return { id: hex(`dangling:${seed}`, 12), repo: "", tag: "", sizeMb, created }; +} + +export function makeContainer(p: Partial & { name: string; image: string }): Container { + const image = normalizeImage(p.image); + return { + id: hex(`container:${p.name}`, 64), command: specFor(image).cmd, status: "running", exitCode: 0, oomKilled: false, restartCount: 0, + ports: [], env: {}, mounts: [], networks: ["bridge"], restart: "no", memoryMb: 0, logs: [], createdAt: "2 hours", since: "2 hours", + ...p, + image, + }; +} + +const isUserNetwork = (name: string) => !["bridge", "host", "none"].includes(name); + +function findContainer(world: DockerWorld, ref: string): Container | undefined { + const name = ref.replace(/^\//, ""); + const exact = world.containers.find((c) => c.name === name || c.id === ref); + if (exact) return exact; + if (/^[0-9a-f]{1,64}$/.test(ref)) { + const byId = world.containers.filter((c) => c.id.startsWith(ref)); + if (byId.length === 1) return byId[0]; + } + return undefined; +} + +function findImage(world: DockerWorld, ref: string): LocalImage | undefined { + if (/^[0-9a-f]{3,12}$/.test(ref)) { + const byId = world.images.find((i) => i.id.startsWith(ref)); + if (byId) return byId; + } + const { repo, tag } = splitImage(ref); + return world.images.find((i) => i.repo === repo && i.tag === tag); +} + +const imageRef = (i: LocalImage) => `${i.repo}:${i.tag}`; + +/** The container that answers to `host` for a container on user networks, or null. */ +function resolveName(world: DockerWorld, from: Container, host: string): Container | null { + if (host === from.name) return from; + const shared = from.networks.filter(isUserNetwork); + for (const other of world.containers) { + if (other === from || (other.name !== host && other.service !== host) || other.status !== "running") continue; + if (other.networks.some((n) => shared.includes(n))) return other; + } + return null; +} + +function ipOf(world: DockerWorld, c: Container): string { + const net = c.networks.find(isUserNetwork) ?? "bridge"; + const base = net === "bridge" ? 17 : 18 + Math.max(0, world.networks.indexOf(net) - 3); + return `172.${base}.0.${2 + world.containers.indexOf(c)}`; +} + +// --------------------------------------------------------------------------------------------- +// Starting a container: this is where the scenarios' faults show up. + +function hostPortBusy(world: DockerWorld, port: number, self: Container): Container | undefined { + return world.containers.find((c) => c !== self && (c.status === "running" || c.status === "restarting") && c.ports.some((p) => p.host === port)); +} + +function setState(world: DockerWorld, c: Container, status: Status, exitCode: number, events: DockerEvent[]) { + const previous = c.status; + c.status = status; + c.exitCode = exitCode; + c.since = world.tick; + if (status === "running" && previous !== "running") events.push({ type: "started", name: c.name }); + else if (status === "exited" && previous === "running") events.push({ type: "stopped", name: c.name }); +} + +function pushLogs(c: Container, lines: string[]) { + c.logs.push(...lines); + if (c.logs.length > 120) c.logs.splice(0, c.logs.length - 120); +} + +/** Try to start a container. Returns an error line when a port is taken (the container stays "created"). */ +function boot(world: DockerWorld, c: Container, events: DockerEvent[]): string | null { + for (const p of c.ports) { + const other = hostPortBusy(world, p.host, c); + if (other) { + if (c.status !== "restarting") setState(world, c, "created", 0, events); + events.push({ type: "blocked", name: c.name }); + return `Error response from daemon: driver failed programming external connectivity on endpoint ${c.name} (${hex(`ep:${c.name}:${world.seq}`, 64)}): Bind for 0.0.0.0:${p.host} failed: port is already allocated`; + } + } + const spec = specFor(c.image); + const fail = (code: number, lines: string[], oom = false) => { + pushLogs(c, lines); + c.oomKilled = oom; + if (c.restart !== "no") { + c.restartCount += 1; + setState(world, c, "restarting", code, events); + events.push({ type: "restarting", name: c.name }); + } else { + setState(world, c, "exited", code, events); + events.push({ type: "crashed", name: c.name }); + } + return null; + }; + + const first = c.command.split(/\s+/)[0] ?? ""; + const appCmd = c.command === spec.cmd; + if (!appCmd && !COMMON_BINS.includes(first) && first !== (spec.cmd.split(/\s+/)[0] ?? "")) { + return fail(127, [`exec: "${first}": executable file not found in $PATH`]); + } + if (appCmd) { + for (const key of spec.requiredEnv ?? []) { + if (!c.env[key]) return fail(1, spec.missingEnv?.[key] ?? [`Error: ${key} is required`]); + } + if (spec.needsHost) { + const host = c.env[spec.needsHost]; + if (!host) return fail(1, [`Error: ${spec.needsHost} is not set`]); + if (host === "localhost" || host === "127.0.0.1") return fail(1, [`Error: connect ECONNREFUSED 127.0.0.1:5432`, " at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1555:16)"]); + if (!resolveName(world, c, host)) return fail(1, [`Error: getaddrinfo ENOTFOUND ${host}`, " at GetAddrInfoReqWrap.onlookup [as oncomplete] (node:dns:109:26)"]); + } + if (spec.memoryMb && c.memoryMb > 0 && c.memoryMb < spec.memoryMb) { + return fail(137, [spec.startLogs[0] ?? "starting", "Killed"], true); + } + pushLogs(c, spec.startLogs); + if (spec.needsHost) pushLogs(c, [`connected to database at ${c.env[spec.needsHost]}`]); + } else { + pushLogs(c, [`(running "${c.command}")`]); + } + c.oomKilled = false; + setState(world, c, "running", 0, events); + return null; +} + +/** Containers on a restart policy try again after every command, so they heal when the cause is fixed. */ +function settle(world: DockerWorld, touched: Set, events: DockerEvent[]) { + for (const c of world.containers) { + if (c.status === "restarting" && !touched.has(c.id)) { + const before = c.restartCount; + boot(world, c, events); + if (c.status === "restarting") c.restartCount = before + 1; + } + } +} + +// --------------------------------------------------------------------------------------------- +// Parsing a shell line. + +function tokenize(text: string): string[] | null { + const tokens: string[] = []; + let current = ""; + let has = false; + let quote: string | null = null; + for (const ch of text) { + if (quote) { + if (ch === quote) quote = null; + else current += ch; + } else if (ch === "'" || ch === '"') { + quote = ch; + has = true; + } else if (/\s/.test(ch)) { + if (has || current) tokens.push(current); + current = ""; + has = false; + } else { + current += ch; + } + } + if (quote) return null; + if (has || current) tokens.push(current); + return tokens; +} + +function splitAnd(line: string): string[] { + const parts: string[] = []; + let current = ""; + let quote: string | null = null; + for (let i = 0; i < line.length; i++) { + const ch = line[i]!; + if (quote) { + if (ch === quote) quote = null; + current += ch; + } else if (ch === "'" || ch === '"') { + quote = ch; + current += ch; + } else if (ch === "&" && line[i + 1] === "&") { + parts.push(current); + current = ""; + i++; + } else current += ch; + } + parts.push(current); + return parts; +} + +type FlagSpec = { bool?: string[]; value?: string[]; alias?: Record; stopAtPositional?: boolean }; +type Parsed = { flags: Record; has: Set; rest: string[]; error?: string }; + +function parseFlags(args: string[], spec: FlagSpec): Parsed { + const flags: Record = {}; + const has = new Set(); + const rest: string[] = []; + const bool = new Set(spec.bool ?? []); + const value = new Set(spec.value ?? []); + const alias = spec.alias ?? {}; + for (let i = 0; i < args.length; i++) { + const arg = args[i]!; + if (arg === "--") { rest.push(...args.slice(i + 1)); break; } + if (arg.startsWith("--")) { + const eq = arg.indexOf("="); + const name = (eq >= 0 ? arg.slice(2, eq) : arg.slice(2)); + const long = alias[`--${name}`]?.slice(2) ?? name; + if (bool.has(long)) { has.add(long); continue; } + if (value.has(long)) { + const val = eq >= 0 ? arg.slice(eq + 1) : args[++i]; + if (val === undefined) return { flags, has, rest, error: `flag needs an argument: --${name}` }; + (flags[long] ??= []).push(val); + continue; + } + return { flags, has, rest, error: `unknown flag: --${name}` }; + } + if (arg.startsWith("-") && arg.length > 1) { + for (let j = 1; j < arg.length; j++) { + const short = arg[j]!; + const long = alias[`-${short}`]?.slice(2) ?? short; + if (bool.has(long)) { has.add(long); continue; } + if (value.has(long)) { + const attached = arg.slice(j + 1); + const val = attached || args[++i]; + if (val === undefined) return { flags, has, rest, error: `flag needs an argument: '${short}' in -${short}` }; + (flags[long] ??= []).push(val.replace(/^=/, "")); + break; + } + return { flags, has, rest, error: `unknown shorthand flag: '${short}' in -${arg.slice(j)}` }; + } + continue; + } + rest.push(arg); + if (spec.stopAtPositional) { rest.push(...args.slice(i + 1)); break; } + } + return { flags, has, rest }; +} + +// --------------------------------------------------------------------------------------------- +// The command runner. + +type Ctx = { world: DockerWorld; lines: OutLine[]; events: DockerEvent[]; touched: Set }; + +const out = (ctx: Ctx, text: string) => { ctx.lines.push({ kind: "out", text }); }; +const err = (ctx: Ctx, text: string) => { ctx.lines.push({ kind: "err", text }); }; +const outAll = (ctx: Ctx, texts: string[]) => texts.forEach((t) => out(ctx, t)); + +const USAGE: Record = { + run: [1, "docker run [OPTIONS] IMAGE [COMMAND] [ARG...]", "Create and run a new container from an image"], + start: [1, "docker start [OPTIONS] CONTAINER [CONTAINER...]", "Start one or more stopped containers"], + stop: [1, "docker stop [OPTIONS] CONTAINER [CONTAINER...]", "Stop one or more running containers"], + restart: [1, "docker restart [OPTIONS] CONTAINER [CONTAINER...]", "Restart one or more containers"], + rm: [1, "docker rm [OPTIONS] CONTAINER [CONTAINER...]", "Remove one or more containers"], + rmi: [1, "docker rmi [OPTIONS] IMAGE [IMAGE...]", "Remove one or more images"], + logs: [1, "docker logs [OPTIONS] CONTAINER", "Fetch the logs of a container"], + inspect: [1, "docker inspect [OPTIONS] NAME|ID [NAME|ID...]", "Return low-level information on Docker objects"], + exec: [2, "docker exec [OPTIONS] CONTAINER COMMAND [ARG...]", "Execute a command in a running container"], + pull: [1, "docker pull [OPTIONS] NAME[:TAG|@DIGEST]", "Download an image from a registry"], + kill: [1, "docker kill [OPTIONS] CONTAINER [CONTAINER...]", "Kill one or more running containers"], +}; + +function needArgs(ctx: Ctx, cmd: string, count: number): boolean { + const u = USAGE[cmd]; + if (!u) return true; + if (count >= u[0]) return true; + err(ctx, `docker: "docker ${cmd}" requires at least ${u[0]} argument${u[0] > 1 ? "s" : ""}.`); + err(ctx, `See 'docker ${cmd} --help'.`); + out(ctx, ""); + out(ctx, `Usage: ${u[1]}`); + out(ctx, ""); + out(ctx, u[2]); + return false; +} + +function flagError(ctx: Ctx, cmd: string, message: string) { + err(ctx, message); + err(ctx, `See 'docker ${cmd} --help'.`); +} + +function noContainer(ctx: Ctx, ref: string) { + err(ctx, `Error response from daemon: No such container: ${ref}`); +} + +function parseMemory(text: string): number | null { + const m = /^(\d+)([bkmg]?)b?$/i.exec(text.trim()); + if (!m) return null; + const n = Number(m[1]); + const unit = (m[2] ?? "").toLowerCase(); + if (unit === "g") return n * 1024; + if (unit === "m") return n; + if (unit === "k") return n / 1024; + return n / 1048576; +} + +function parsePort(text: string): { host: number; container: number } | string { + const m = /^(?:(\d{1,3}(?:\.\d{1,3}){3}):)?(\d{1,5})(?::(\d{1,5}))?(?:\/(tcp|udp))?$/.exec(text); + if (!m) return `invalid containerPort: ${text.split(":").pop() ?? text}`; + const a = Number(m[2]); + const b = m[3] !== undefined ? Number(m[3]) : null; + const host = b === null ? 0 : a; + const container = b === null ? a : b; + if (container < 1 || container > 65535) return `invalid containerPort: ${container}`; + if (host > 65535) return `invalid hostPort: ${host}`; + return { host, container }; +} + +function pullImage(ctx: Ctx, ref: string): LocalImage | null { + const world = ctx.world; + const { repo, tag } = splitImage(ref); + const key = `${repo}:${tag}`; + if (!CATALOG[key]) { + const known = Object.keys(CATALOG).some((k) => k.startsWith(`${repo}:`)); + if (known) err(ctx, `Error response from daemon: manifest for ${key} not found: manifest unknown: manifest unknown`); + else err(ctx, `Error response from daemon: pull access denied for ${repo}, repository does not exist or may require 'docker login': denied: requested access to the resource is denied`); + return null; + } + const existing = world.images.find((i) => i.repo === repo && i.tag === tag); + const official = !repo.includes("/"); + out(ctx, `${tag}: Pulling from ${official ? "library/" : ""}${repo}`); + if (existing) { + out(ctx, `Digest: sha256:${hex(`digest:${key}`, 64)}`); + out(ctx, `Status: Image is up to date for ${key}`); + } else { + for (let i = 0; i < 2; i++) out(ctx, `${hex(`layer:${key}:${i}`, 12)}: Pull complete`); + out(ctx, `Digest: sha256:${hex(`digest:${key}`, 64)}`); + out(ctx, `Status: Downloaded newer image for ${key}`); + } + out(ctx, `docker.io/${official ? "library/" : ""}${key}`); + if (existing) return existing; + const image = makeImage(key, "2 weeks ago"); + world.images.push(image); + ctx.events.push({ type: "pulled", name: key }); + return image; +} + +function cmdRun(ctx: Ctx, args: string[]) { + const world = ctx.world; + const p = parseFlags(args, { + bool: ["detach", "interactive", "tty", "rm", "publish-all"], + value: ["publish", "env", "volume", "name", "network", "restart", "memory", "workdir", "hostname", "user"], + alias: { "-d": "--detach", "-i": "--interactive", "-t": "--tty", "-p": "--publish", "-e": "--env", "-v": "--volume", "-P": "--publish-all", "-m": "--memory", "-w": "--workdir", "-h": "--hostname", "-u": "--user", "--net": "--network" }, + stopAtPositional: true, + }); + if (p.error) return flagError(ctx, "run", p.error); + if (!needArgs(ctx, "run", p.rest.length)) return; + const imageArg = p.rest[0]!; + if (!/^[a-z0-9][a-z0-9._/-]*(:[A-Za-z0-9_][A-Za-z0-9_.-]*)?$/.test(imageArg)) { + return flagError(ctx, "run", `docker: invalid reference format.`); + } + const name = p.flags.name?.[0]; + if (name !== undefined && !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name)) { + return flagError(ctx, "run", `docker: Error response from daemon: Invalid container name (${name}), only [a-zA-Z0-9][a-zA-Z0-9_.-] are allowed`); + } + const containerName = name ?? ["eager_turing", "calm_lovelace", "brave_hopper", "quick_ritchie", "happy_torvalds", "clever_knuth"][world.seq % 6]!; + const taken = world.containers.find((c) => c.name === containerName); + if (taken) { + return err(ctx, `docker: Error response from daemon: Conflict. The container name "/${containerName}" is already in use by container "${taken.id}". You have to remove (or rename) that container to be able to reuse that name.`); + } + const ports: PortMap[] = []; + for (const spec of p.flags.publish ?? []) { + const parsed = parsePort(spec); + if (typeof parsed === "string") return err(ctx, `docker: ${parsed}.`); + ports.push({ host: parsed.host || 32768 + ((world.seq + ports.length) % 1000), container: parsed.container }); + } + if (p.has.has("publish-all")) { + const port = specFor(normalizeImage(imageArg)).port; + if (port) ports.push({ host: 32768 + (world.seq % 1000), container: port }); + } + const env: Record = {}; + for (const item of p.flags.env ?? []) { + const eq = item.indexOf("="); + if (eq === 0) return err(ctx, `docker: invalid env file: "${item}"`); + if (eq > 0) env[item.slice(0, eq)] = item.slice(eq + 1); + } + const mounts: Mount[] = []; + const newVolumes: string[] = []; + for (const item of p.flags.volume ?? []) { + const parts = item.split(":"); + const target = parts.length === 1 ? parts[0]! : parts[1]!; + const source = parts.length === 1 ? "" : parts[0]!; + if (!target.startsWith("/")) { + return err(ctx, `docker: Error response from daemon: invalid mount config for type "volume": invalid mount path: '${target}' mount path must be absolute.`); + } + if (source.startsWith("/") || source.startsWith("./") || source.startsWith("~")) mounts.push({ source, target, kind: "bind" }); + else if (source === "") { + const anon = hex(`anon:${world.seq}:${mounts.length}`, 64); + mounts.push({ source: anon, target, kind: "volume" }); + newVolumes.push(anon); + } else if (/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(source)) { + mounts.push({ source, target, kind: "volume" }); + if (!world.volumes.includes(source)) newVolumes.push(source); + } else return err(ctx, `docker: Error response from daemon: invalid volume name "${source}"`); + } + const net = p.flags.network?.[0]; + if (net !== undefined && !world.networks.includes(net)) { + return err(ctx, `docker: Error response from daemon: network ${net} not found.`); + } + const restartArg = p.flags.restart?.[0] ?? "no"; + const restart = /^(no|always|unless-stopped|on-failure)(:\d+)?$/.exec(restartArg); + if (!restart) return err(ctx, `docker: Error response from daemon: invalid restart policy ${restartArg}`); + let memoryMb = 0; + if (p.flags.memory) { + const mb = parseMemory(p.flags.memory[0]!); + if (mb === null) return err(ctx, `docker: invalid argument "${p.flags.memory[0]}" for "-m, --memory" flag: invalid size: '${p.flags.memory[0]}'`); + if (mb < 6) return err(ctx, "docker: Error response from daemon: Minimum memory limit allowed is 6MB"); + memoryMb = Math.round(mb); + } + + const ref = normalizeImage(imageArg); + let image = findImage(world, ref); + if (!image) { + out(ctx, `Unable to find image '${ref}' locally`); + image = pullImage(ctx, ref) ?? undefined; + if (!image) { + err(ctx, "See 'docker run --help'."); + return; + } + } + const spec = specFor(imageRef(image)); + const command = p.rest.slice(1).join(" ") || spec.cmd; + world.seq += 1; + for (const v of newVolumes) { + world.volumes.push(v); + ctx.events.push({ type: "volume", name: v }); + } + const c: Container = makeContainer({ + name: containerName, image: imageRef(image), command, status: "created", ports, env, mounts, + networks: [net ?? "bridge"], restart: restart[1] as RestartPolicy, memoryMb, createdAt: world.tick, since: world.tick, + }); + c.id = hex(`container:${containerName}:${world.seq}`, 64); + world.containers.push(c); + ctx.events.push({ type: "created", name: c.name }); + ctx.touched.add(c.id); + const problem = boot(world, c, ctx.events); + if (problem) { + err(ctx, `docker: ${problem}.`); + return; + } + if (p.has.has("detach")) out(ctx, c.id); + else { + outAll(ctx, c.logs); + if (c.status === "running") ctx.lines.push({ kind: "sys", text: "Tip: add -d to run the container in the background and keep using this terminal." }); + } +} + +function cmdPs(ctx: Ctx, args: string[]) { + const world = ctx.world; + const p = parseFlags(args, { bool: ["all", "quiet", "no-trunc"], value: ["filter", "format"], alias: { "-a": "--all", "-q": "--quiet", "-f": "--filter" } }); + if (p.error) return flagError(ctx, "ps", p.error); + if (p.rest.length) return err(ctx, `"docker ps" accepts no arguments.`); + let list = world.containers.filter((c) => p.has.has("all") || c.status === "running" || c.status === "restarting"); + for (const f of p.flags.filter ?? []) { + const [k, v] = f.split("="); + if (k === "status") list = list.filter((c) => c.status === v); + else if (k === "name") list = list.filter((c) => c.name.includes(v ?? "")); + else return err(ctx, `Error response from daemon: Invalid filter '${k}'`); + } + list = [...list].reverse(); + if (p.has.has("quiet")) return outAll(ctx, list.map((c) => shortId(c.id))); + const format = p.flags.format?.[0]; + if (format) { + return outAll(ctx, list.map((c) => format.replace(/\{\{\.(\w+)\}\}/g, (_m, field: string) => ({ ID: shortId(c.id), Names: c.name, Image: c.image, Status: statusText(world, c), Ports: portsText(c), Command: `"${c.command}"` } as Record)[field] ?? ""))); + } + // A shorter table than the real one (no COMMAND and CREATED columns), so it fits a small terminal. + const rows = [["CONTAINER ID", "IMAGE", "STATUS", "PORTS", "NAMES"]]; + for (const c of list) rows.push([shortId(c.id), c.image, statusText(world, c), portsText(c), c.name]); + outAll(ctx, table(rows)); +} + +export function statusText(world: DockerWorld, c: Container): string { + if (c.status === "running") return `Up ${age(world, c.since)}`; + if (c.status === "created") return "Created"; + if (c.status === "restarting") return `Restarting (${c.exitCode}) ${age(world, c.since)} ago`; + return `Exited (${c.exitCode}) ${age(world, c.since)} ago`; +} + +export function portsText(c: Container): string { + if (c.status !== "running" && c.status !== "restarting") return ""; + const list = c.ports.map((p) => `0.0.0.0:${p.host}->${p.container}/tcp`); + if (list.length === 0) { + const port = specFor(c.image).port; + return port ? `${port}/tcp` : ""; + } + return list.join(", "); +} + +function cmdImages(ctx: Ctx, args: string[]) { + const world = ctx.world; + const p = parseFlags(args, { bool: ["all", "quiet", "no-trunc"], value: ["filter"], alias: { "-a": "--all", "-q": "--quiet", "-f": "--filter" } }); + if (p.error) return flagError(ctx, "images", p.error); + let list = [...world.images].reverse(); + for (const f of p.flags.filter ?? []) { + if (f === "dangling=true") list = list.filter((i) => i.repo === ""); + else if (f === "dangling=false") list = list.filter((i) => i.repo !== ""); + else return err(ctx, `Error response from daemon: Invalid filter '${f.split("=")[0]}'`); + } + const wanted = p.rest[0]; + if (wanted) list = list.filter((i) => i.repo === splitImage(wanted).repo && (!wanted.includes(":") || i.tag === splitImage(wanted).tag)); + if (p.has.has("quiet")) return outAll(ctx, list.map((i) => i.id)); + const rows = [["REPOSITORY", "TAG", "IMAGE ID", "CREATED", "SIZE"]]; + for (const i of list) rows.push([i.repo, i.tag, i.id, i.created, fmtSize(i.sizeMb)]); + outAll(ctx, table(rows)); +} + +function stop(ctx: Ctx, c: Container, code = 0) { + if (c.status === "running" || c.status === "restarting") { + const was = c.status; + setState(ctx.world, c, "exited", code, ctx.events); + if (was === "restarting") ctx.events.push({ type: "stopped", name: c.name }); + } +} + +function eachContainer(ctx: Ctx, refs: string[], action: (c: Container) => void) { + for (const ref of refs) { + const c = findContainer(ctx.world, ref); + if (!c) noContainer(ctx, ref); + else action(c); + } +} + +function startOne(ctx: Ctx, c: Container) { + if (c.status === "running") return out(ctx, c.name); + ctx.touched.add(c.id); + const problem = boot(ctx.world, c, ctx.events); + if (problem) { + err(ctx, problem); + err(ctx, `Error: failed to start containers: ${c.name}`); + return; + } + out(ctx, c.name); +} + +function removeContainer(world: DockerWorld, c: Container, events: DockerEvent[]) { + world.containers = world.containers.filter((x) => x !== c); + events.push({ type: "removed", name: c.name }); +} + +function cmdLogs(ctx: Ctx, args: string[]) { + const p = parseFlags(args, { bool: ["follow", "timestamps"], value: ["tail", "since"], alias: { "-f": "--follow", "-t": "--timestamps", "-n": "--tail" } }); + if (p.error) return flagError(ctx, "logs", p.error); + if (!needArgs(ctx, "logs", p.rest.length)) return; + if (p.rest.length > 1) return err(ctx, `docker: "docker logs" requires exactly 1 argument.`); + const c = findContainer(ctx.world, p.rest[0]!); + if (!c) return noContainer(ctx, p.rest[0]!); + let lines = c.logs; + const tail = p.flags.tail?.[0]; + if (tail !== undefined && tail !== "all") { + if (!/^\d+$/.test(tail)) return err(ctx, `invalid argument "${tail}" for "-n, --tail" flag: strconv.ParseUint: parsing "${tail}": invalid syntax`); + lines = Number(tail) === 0 ? [] : lines.slice(-Number(tail)); + } + outAll(ctx, lines); + if (p.has.has("follow")) ctx.lines.push({ kind: "sys", text: "(-f would keep waiting for new lines; the game shows the lines so far.)" }); +} + +function inspectObject(world: DockerWorld, c: Container): Record { + const env = Object.entries(c.env).map(([k, v]) => `${k}=${v}`); + const networks: Record = {}; + for (const n of c.networks) networks[n] = { NetworkID: hex(`net:${n}`, 64), IPAddress: c.status === "running" ? ipOf(world, c) : "" }; + const bindings: Record = {}; + for (const p of c.ports) bindings[`${p.container}/tcp`] = [{ HostIp: "", HostPort: String(p.host) }]; + return { + Id: c.id, + Name: `/${c.name}`, + State: { + Status: c.status, Running: c.status === "running", Restarting: c.status === "restarting", OOMKilled: c.oomKilled, + ExitCode: c.exitCode, Error: "", RestartCount: c.restartCount, + }, + Config: { Image: c.image, Cmd: c.command.split(" "), Env: env }, + HostConfig: { Memory: Math.round(c.memoryMb * 1048576), RestartPolicy: { Name: c.restart }, PortBindings: bindings }, + Mounts: c.mounts.map((m) => ({ Type: m.kind, Name: m.kind === "volume" ? m.source : "", Source: m.source, Destination: m.target })), + NetworkSettings: { Networks: networks }, + }; +} + +function cmdInspect(ctx: Ctx, args: string[]) { + const p = parseFlags(args, { value: ["format", "type"], alias: { "-f": "--format" } }); + if (p.error) return flagError(ctx, "inspect", p.error); + if (!needArgs(ctx, "inspect", p.rest.length)) return; + const format = p.flags.format?.[0]; + const results: Record[] = []; + for (const ref of p.rest) { + const c = findContainer(ctx.world, ref); + if (!c) { + err(ctx, `Error: No such object: ${ref}`); + continue; + } + results.push(inspectObject(ctx.world, c)); + } + if (format) { + for (const obj of results) { + out(ctx, format.replace(/\{\{\s*\.([\w.]+)\s*\}\}/g, (_m, path: string) => { + let cur: unknown = obj; + for (const key of path.split(".")) cur = cur && typeof cur === "object" ? (cur as Record)[key] : undefined; + if (cur === undefined) return ""; + return typeof cur === "object" ? JSON.stringify(cur) : String(cur); + })); + } + return; + } + if (results.length === 0 && p.rest.length) return out(ctx, "[]"); + outAll(ctx, JSON.stringify(results, null, 4).split("\n")); +} + +function curlFrom(ctx: Ctx, from: Container | null, target: string): { ok: boolean; text: string } { + const world = ctx.world; + let url = target.replace(/^https?:\/\//, ""); + url = url.split("/")[0] ?? ""; + const m = /^([A-Za-z0-9._-]+)(?::(\d{1,5}))?$/.exec(url); + if (!m) return { ok: false, text: `curl: (3) URL rejected: Bad hostname` }; + const host = m[1]!; + const port = m[2] ? Number(m[2]) : 80; + const refused = `curl: (7) Failed to connect to ${host} port ${port} after 0 ms: Couldn't connect to server`; + let container: Container | undefined; + let containerPort = port; + if (host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0") { + if (from) { + container = from; + } else { + container = world.containers.find((c) => c.status === "running" && c.ports.some((pp) => pp.host === port)); + containerPort = container?.ports.find((pp) => pp.host === port)?.container ?? port; + } + } else if (from) { + container = resolveName(world, from, host) ?? undefined; + if (!container) return { ok: false, text: `curl: (6) Could not resolve host: ${host}` }; + } else { + return { ok: false, text: `curl: (6) Could not resolve host: ${host}` }; + } + if (!container || container.status !== "running") return { ok: false, text: refused }; + const spec = specFor(container.image); + const runs = container.command === spec.cmd; + if (!runs || spec.port !== containerPort) { + return { ok: false, text: from ? refused : `curl: (56) Recv failure: Connection reset by peer` }; + } + if (spec.rawPort || spec.body === undefined) return { ok: false, text: "curl: (52) Empty reply from server" }; + return { ok: true, text: spec.body }; +} + +function cmdExec(ctx: Ctx, args: string[]) { + const p = parseFlags(args, { bool: ["interactive", "tty", "detach"], value: ["env", "workdir", "user"], alias: { "-i": "--interactive", "-t": "--tty", "-d": "--detach", "-e": "--env", "-w": "--workdir", "-u": "--user" }, stopAtPositional: true }); + if (p.error) return flagError(ctx, "exec", p.error); + if (!needArgs(ctx, "exec", p.rest.length)) return; + const c = findContainer(ctx.world, p.rest[0]!); + if (!c) return noContainer(ctx, p.rest[0]!); + if (c.status !== "running") return err(ctx, `Error response from daemon: container ${c.id} is not running`); + const [cmd, ...rest] = p.rest.slice(1); + const spec = specFor(c.image); + switch (cmd) { + case "env": + case "printenv": { + const base = { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", HOSTNAME: shortId(c.id), ...c.env, HOME: "/root" }; + if (cmd === "printenv" && rest[0]) { + const v = (base as Record)[rest[0]]; + if (v === undefined) return; + return out(ctx, v); + } + return outAll(ctx, Object.entries(base).map(([k, v]) => `${k}=${v}`)); + } + case "hostname": return out(ctx, shortId(c.id)); + case "whoami": return out(ctx, "root"); + case "ls": { + const dir = rest.find((r) => !r.startsWith("-")) ?? "/"; + const mounted = c.mounts.find((m) => m.target === dir); + if (mounted) return out(ctx, mounted.kind === "volume" ? "PG_VERSION base global pg_wal postgresql.conf" : "(bind mount from the host)"); + if (dir === "/" ) return out(ctx, "bin dev etc home proc root usr var" + (c.mounts.length ? " " + c.mounts.map((m) => m.target.split("/")[1]).filter(Boolean).join(" ") : "")); + if (dir === spec.dataPath) return out(ctx, "PG_VERSION base global pg_wal postgresql.conf"); + return out(ctx, ""); + } + case "cat": { + const file = rest[0]; + if (!file) return; + if (file === "/etc/hostname") return out(ctx, shortId(c.id)); + if (file === "/etc/hosts") return outAll(ctx, ["127.0.0.1\tlocalhost", `${ipOf(ctx.world, c)}\t${shortId(c.id)}`]); + return err(ctx, `cat: ${file}: No such file or directory`); + } + case "curl": { + const target = rest.filter((r) => !r.startsWith("-"))[0]; + if (!target) return err(ctx, "curl: try 'curl --help' for more information"); + const result = curlFrom(ctx, c, target); + return result.ok ? out(ctx, result.text) : err(ctx, result.text); + } + case "ping": { + const host = rest.filter((r) => !r.startsWith("-") && !/^\d+$/.test(r))[0]; + if (!host) return err(ctx, "ping: usage error: Destination address required"); + const target = host === "localhost" ? c : resolveName(ctx.world, c, host); + if (!target) return err(ctx, `ping: ${host}: Temporary failure in name resolution`); + const ip = host === "localhost" ? "127.0.0.1" : ipOf(ctx.world, target); + return outAll(ctx, [ + `PING ${host} (${ip}) 56(84) bytes of data.`, + `64 bytes from ${host} (${ip}): icmp_seq=1 ttl=64 time=0.08 ms`, + `64 bytes from ${host} (${ip}): icmp_seq=2 ttl=64 time=0.06 ms`, + `--- ${host} ping statistics ---`, + "2 packets transmitted, 2 received, 0% packet loss", + ]); + } + case "sh": + case "bash": + return ctx.lines.push({ kind: "sys", text: `This game has no interactive shell. Try: docker exec ${c.name} env, ls or curl.` }), undefined; + default: + return err(ctx, `OCI runtime exec failed: exec failed: unable to start container process: exec: "${cmd}": executable file not found in $PATH: unknown`); + } +} + +function cmdStats(ctx: Ctx, args: string[]) { + const p = parseFlags(args, { bool: ["no-stream", "all"], value: ["format"], alias: { "-a": "--all" } }); + if (p.error) return flagError(ctx, "stats", p.error); + let list = ctx.world.containers.filter((c) => c.status === "running"); + if (p.rest.length) { + const picked: Container[] = []; + for (const ref of p.rest) { + const c = findContainer(ctx.world, ref); + if (!c) return noContainer(ctx, ref); + picked.push(c); + } + list = picked.filter((c) => c.status === "running"); + } + const rows = [["CONTAINER ID", "NAME", "CPU %", "MEM USAGE / LIMIT", "MEM %", "PIDS"]]; + for (const c of [...list].reverse()) { + const use = specFor(c.image).useMb ?? 20; + const limit = c.memoryMb > 0 ? c.memoryMb : 7870; + rows.push([shortId(c.id), c.name, "0.02%", `${use}MiB / ${c.memoryMb > 0 ? `${limit}MiB` : "7.686GiB"}`, `${((use / limit) * 100).toFixed(2)}%`, "4"]); + } + outAll(ctx, table(rows)); + if (!p.has.has("no-stream")) ctx.lines.push({ kind: "sys", text: "(The real command keeps refreshing until Ctrl+C. Add --no-stream for one snapshot.)" }); +} + +function cmdNetwork(ctx: Ctx, args: string[]) { + const world = ctx.world; + const [sub, ...rest] = args; + if (sub === "ls" || sub === "list") { + const rows = [["NETWORK ID", "NAME", "DRIVER", "SCOPE"]]; + for (const n of world.networks) rows.push([hex(`net:${n}`, 12), n, n === "host" ? "host" : n === "none" ? "null" : "bridge", "local"]); + return outAll(ctx, table(rows)); + } + if (sub === "create") { + const p = parseFlags(rest, { value: ["driver"], alias: { "-d": "--driver" } }); + if (p.error) return flagError(ctx, "network create", p.error); + if (p.rest.length !== 1) return err(ctx, `docker: "docker network create" requires exactly 1 argument.`); + const name = p.rest[0]!; + if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name)) return err(ctx, `Error response from daemon: invalid network name ${name}`); + if (world.networks.includes(name)) return err(ctx, `Error response from daemon: network with name ${name} already exists`); + world.networks.push(name); + ctx.events.push({ type: "network", name }); + return out(ctx, hex(`net:${name}`, 64)); + } + if (sub === "connect") { + if (rest.length !== 2) return err(ctx, `docker: "docker network connect" requires exactly 2 arguments.`); + const [net, ref] = rest as [string, string]; + if (!world.networks.includes(net)) return err(ctx, `Error response from daemon: network ${net} not found`); + const c = findContainer(world, ref); + if (!c) return noContainer(ctx, ref); + if (c.networks.includes(net)) return err(ctx, `Error response from daemon: endpoint with name ${c.name} already exists in network ${net}`); + c.networks.push(net); + ctx.events.push({ type: "network", name: net }); + return; + } + if (sub === "disconnect") { + if (rest.length !== 2) return err(ctx, `docker: "docker network disconnect" requires exactly 2 arguments.`); + const [net, ref] = rest as [string, string]; + const c = findContainer(world, ref); + if (!c) return noContainer(ctx, ref); + if (!c.networks.includes(net)) return err(ctx, `Error response from daemon: container ${c.id} is not connected to network ${net}`); + c.networks = c.networks.filter((n) => n !== net); + return; + } + if (sub === "rm") { + for (const net of rest) { + if (["bridge", "host", "none"].includes(net)) { err(ctx, `Error response from daemon: ${net} is a pre-defined network and cannot be removed`); continue; } + if (!world.networks.includes(net)) { err(ctx, `Error response from daemon: network ${net} not found`); continue; } + if (world.containers.some((c) => c.networks.includes(net))) { err(ctx, `Error response from daemon: error while removing network: network ${net} has active endpoints`); continue; } + world.networks = world.networks.filter((n) => n !== net); + out(ctx, net); + } + return; + } + err(ctx, sub ? `docker network: '${sub}' is not a docker network command.` : "Usage: docker network COMMAND (ls, create, connect, disconnect, rm)"); +} + +function cmdVolume(ctx: Ctx, args: string[]) { + const world = ctx.world; + const [sub, ...rest] = args; + if (sub === "ls" || sub === "list") { + const rows = [["DRIVER", "VOLUME NAME"]]; + for (const v of world.volumes) rows.push(["local", v]); + return outAll(ctx, table(rows)); + } + if (sub === "create") { + if (rest.length > 1 || rest[0]?.startsWith("-")) return err(ctx, `docker: "docker volume create" requires at most 1 argument.`); + const name = rest[0] ?? hex(`vol:${world.seq++}`, 64); + if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name)) return err(ctx, `Error response from daemon: create ${name}: "${name}" includes invalid characters for a local volume name`); + if (!world.volumes.includes(name)) world.volumes.push(name); + ctx.events.push({ type: "volume", name }); + return out(ctx, name); + } + if (sub === "rm") { + for (const v of rest) { + if (!world.volumes.includes(v)) { err(ctx, `Error response from daemon: get ${v}: no such volume`); continue; } + const users = world.containers.filter((c) => c.mounts.some((m) => m.source === v)); + if (users.length) { err(ctx, `Error response from daemon: remove ${v}: volume is in use - [${users.map((c) => c.id).join(", ")}]`); continue; } + world.volumes = world.volumes.filter((x) => x !== v); + out(ctx, v); + } + return; + } + if (sub === "prune") { + const p = parseFlags(rest, { bool: ["force", "all"], alias: { "-f": "--force", "-a": "--all" } }); + if (!p.has.has("force")) return promptNo(ctx, "all local volumes not used by at least one container"); + return prune(ctx, { volumes: true }); + } + err(ctx, sub ? `docker volume: '${sub}' is not a docker volume command.` : "Usage: docker volume COMMAND (ls, create, rm, prune)"); +} + +function promptNo(ctx: Ctx, what: string) { + out(ctx, `WARNING! This will remove ${what}.`); + out(ctx, "Are you sure you want to continue? [y/N] "); + ctx.lines.push({ kind: "sys", text: "No answer was given, so nothing was removed. Add -f to skip the question." }); +} + +function prune(ctx: Ctx, opt: { containers?: boolean; images?: boolean; allImages?: boolean; volumes?: boolean; networks?: boolean }) { + const world = ctx.world; + let reclaimed = 0; + if (opt.containers) { + const gone = world.containers.filter((c) => c.status === "exited" || c.status === "created"); + if (gone.length) out(ctx, "Deleted Containers:"); + for (const c of gone) { + out(ctx, c.id); + reclaimed += 6; + removeContainer(world, c, ctx.events); + } + } + if (opt.networks) { + const gone = world.networks.filter((n) => isUserNetwork(n) && !world.containers.some((c) => c.networks.includes(n))); + if (gone.length) out(ctx, "Deleted Networks:"); + for (const n of gone) out(ctx, n); + world.networks = world.networks.filter((n) => !gone.includes(n)); + } + if (opt.volumes) { + const gone = world.volumes.filter((v) => !world.containers.some((c) => c.mounts.some((m) => m.source === v))); + if (gone.length) out(ctx, "Deleted Volumes:"); + for (const v of gone) out(ctx, v); + world.volumes = world.volumes.filter((v) => !gone.includes(v)); + reclaimed += gone.length * 40; + } + if (opt.images) { + const used = new Set(world.containers.map((c) => c.image)); + const gone = world.images.filter((i) => (i.repo === "") || (opt.allImages && !used.has(imageRef(i)))); + if (gone.length) out(ctx, "Deleted Images:"); + for (const i of gone) { + out(ctx, i.repo === "" ? `deleted: sha256:${hex(`sha:${i.id}`, 64)}` : `untagged: ${imageRef(i)}`); + reclaimed += i.sizeMb; + } + world.images = world.images.filter((i) => !gone.includes(i)); + } + ctx.events.push({ type: "pruned", name: "prune" }); + out(ctx, ""); + out(ctx, `Total reclaimed space: ${fmtSize(reclaimed)}`); +} + +export function diskUsedMb(world: DockerWorld): number { + return world.images.reduce((sum, i) => sum + i.sizeMb, 0) + world.containers.length * 6 + world.volumes.length * 40; +} + +function cmdSystem(ctx: Ctx, args: string[]) { + const [sub, ...rest] = args; + if (sub === "df") { + const w = ctx.world; + const rows = [["TYPE", "TOTAL", "ACTIVE", "SIZE"]]; + rows.push(["Images", String(w.images.length), String(new Set(w.containers.map((c) => c.image)).size), fmtSize(w.images.reduce((s, i) => s + i.sizeMb, 0))]); + rows.push(["Containers", String(w.containers.length), String(w.containers.filter((c) => c.status === "running").length), fmtSize(w.containers.length * 6)]); + rows.push(["Local Volumes", String(w.volumes.length), String(w.volumes.filter((v) => w.containers.some((c) => c.mounts.some((m) => m.source === v))).length), fmtSize(w.volumes.length * 40)]); + return outAll(ctx, table(rows)); + } + if (sub === "prune") { + const p = parseFlags(rest, { bool: ["force", "all", "volumes"], alias: { "-f": "--force", "-a": "--all" } }); + if (p.error) return flagError(ctx, "system prune", p.error); + if (!p.has.has("force")) { + out(ctx, "WARNING! This will remove:"); + out(ctx, " - all stopped containers"); + out(ctx, " - all networks not used by at least one container"); + if (p.has.has("volumes")) out(ctx, " - all anonymous volumes not used by at least one container"); + out(ctx, p.has.has("all") ? " - all images without at least one container associated to them" : " - all dangling images"); + out(ctx, ""); + out(ctx, "Are you sure you want to continue? [y/N] "); + ctx.lines.push({ kind: "sys", text: "No answer was given, so nothing was removed. Add -f to skip the question." }); + return; + } + return prune(ctx, { containers: true, networks: true, images: true, allImages: p.has.has("all"), volumes: p.has.has("volumes") }); + } + err(ctx, sub ? `docker system: '${sub}' is not a docker system command.` : "Usage: docker system COMMAND (df, prune)"); +} + +// --------------------------------------------------------------------------------------------- +// docker compose (only when the scenario has a compose file). + +function composeOrder(services: ComposeService[]): ComposeService[] { + const done: ComposeService[] = []; + const visit = (s: ComposeService, depth: number) => { + if (done.includes(s) || depth > 10) return; + for (const d of s.dependsOn) { + const dep = services.find((x) => x.name === d); + if (dep) visit(dep, depth + 1); + } + done.push(s); + }; + services.forEach((s) => visit(s, 0)); + return done; +} + +function cmdCompose(ctx: Ctx, args: string[]) { + const world = ctx.world; + const compose = world.compose; + if (!compose) return err(ctx, "no configuration file provided: not found"); + const [sub, ...rest] = args; + const net = `${compose.project}_default`; + const mine = () => world.containers.filter((c) => c.project === compose.project); + if (sub === "up") { + const p = parseFlags(rest, { bool: ["detach", "build", "force-recreate"], alias: { "-d": "--detach" } }); + if (p.error) return flagError(ctx, "compose up", p.error); + if (!p.has.has("detach")) return err(ctx, "This game runs compose in the background. Use: docker compose up -d"); + const order = composeOrder(compose.services); + const lines: string[] = []; + let failed = 0; + if (!world.networks.includes(net)) { + world.networks.push(net); + ctx.events.push({ type: "network", name: net }); + lines.push(` ✔ Network ${net}`.padEnd(40) + "Created"); + } else lines.push(` ✔ Network ${net}`.padEnd(40) + "Running"); + for (const s of compose.services) { + for (const v of s.volumes) { + const src = v.split(":")[0]!; + if (src.startsWith("/") || src.startsWith(".")) continue; + const full = `${compose.project}_${src}`; + if (!world.volumes.includes(full)) { + world.volumes.push(full); + ctx.events.push({ type: "volume", name: full }); + lines.push(` ✔ Volume ${full}`.padEnd(40) + "Created"); + } + } + } + const errors: string[] = []; + for (const s of order) { + const name = `${compose.project}-${s.name}-1`; + let c = world.containers.find((x) => x.name === name); + const label = ` ✔ Container ${name}`.padEnd(40); + if (c && c.status === "running") { lines.push(label + "Running"); continue; } + if (!c) { + world.seq += 1; + const ports: PortMap[] = []; + for (const spec of s.ports) { + const parsed = parsePort(spec); + if (typeof parsed !== "string") ports.push({ host: parsed.host, container: parsed.container }); + } + const mounts: Mount[] = s.volumes.map((v) => { + const [src, dst] = v.split(":") as [string, string]; + return src.startsWith("/") || src.startsWith(".") ? { source: src, target: dst, kind: "bind" as const } : { source: `${compose.project}_${src}`, target: dst, kind: "volume" as const }; + }); + c = makeContainer({ + name, image: s.image, status: "created", ports, env: { ...s.env }, mounts, networks: [net], restart: s.restart ?? "no", + createdAt: world.tick, since: world.tick, project: compose.project, service: s.name, + }); + c.id = hex(`container:${name}:${world.seq}`, 64); + world.containers.push(c); + ctx.events.push({ type: "created", name }); + } + ctx.touched.add(c.id); + const problem = boot(world, c, ctx.events); + if (problem) { + failed += 1; + lines.push(` ✘ Container ${name}`.padEnd(40) + "Error"); + errors.push(problem); + } else lines.push(label + "Started"); + } + out(ctx, `[+] Running ${lines.length - failed}/${lines.length}`); + outAll(ctx, lines); + for (const e of errors) err(ctx, e); + return; + } + if (sub === "ps") { + const p = parseFlags(rest, { bool: ["all", "quiet"], alias: { "-a": "--all", "-q": "--quiet" } }); + const list = mine().filter((c) => p.has.has("all") || c.status === "running" || c.status === "restarting"); + const rows = [["NAME", "IMAGE", "SERVICE", "STATUS", "PORTS"]]; + for (const c of list) rows.push([c.name, c.image, c.service ?? "", statusText(world, c), portsText(c)]); + return outAll(ctx, table(rows)); + } + if (sub === "logs") { + const want = rest.filter((r) => !r.startsWith("-")); + for (const c of mine()) { + if (want.length && !want.includes(c.service ?? "")) continue; + for (const line of c.logs) out(ctx, `${c.name} | ${line}`); + } + return; + } + if (sub === "down") { + const gone = mine(); + for (const c of gone) { + out(ctx, ` ✔ Container ${c.name}`.padEnd(40) + "Removed"); + removeContainer(world, c, ctx.events); + } + if (world.networks.includes(net)) { + world.networks = world.networks.filter((n) => n !== net); + out(ctx, ` ✔ Network ${net}`.padEnd(40) + "Removed"); + } + return; + } + err(ctx, sub ? `docker: 'compose ${sub}' is not supported here. Try: docker compose up -d, ps, logs, down` : "Usage: docker compose COMMAND (up -d, ps, logs, down)"); +} + +// --------------------------------------------------------------------------------------------- + +function cmdDocker(ctx: Ctx, args: string[]) { + const world = ctx.world; + let [cmd, ...rest] = args; + if (cmd === undefined) { + return outAll(ctx, ["Usage: docker [OPTIONS] COMMAND", "", "Commands: ps, images, run, start, stop, restart, rm, rmi, logs, inspect, exec, pull,", " network, volume, stats, system, compose"]); + } + if (cmd === "--version" || cmd === "-v" || cmd === "version") return out(ctx, "Docker version 27.3.1, build ce12230"); + if (cmd === "container" || cmd === "image") { + const sub = rest[0]; + const map: Record = cmd === "container" + ? { ls: "ps", list: "ps", ps: "ps", rm: "rm", stop: "stop", start: "start", restart: "restart", logs: "logs", inspect: "inspect", run: "run", exec: "exec", kill: "kill", prune: "container-prune", stats: "stats" } + : { ls: "images", list: "images", rm: "rmi", pull: "pull", prune: "image-prune", inspect: "inspect" }; + const mapped = sub ? map[sub] : undefined; + if (!mapped) return err(ctx, `docker ${cmd}: '${sub ?? ""}' is not a docker ${cmd} command.`); + cmd = mapped; + rest = rest.slice(1); + } + switch (cmd) { + case "run": return cmdRun(ctx, rest); + case "ps": return cmdPs(ctx, rest); + case "images": return cmdImages(ctx, rest); + case "pull": { + const p = parseFlags(rest, {}); + if (p.error) return flagError(ctx, "pull", p.error); + if (!needArgs(ctx, "pull", p.rest.length)) return; + if (!/^[a-z0-9][a-z0-9._/-]*(:[A-Za-z0-9_][A-Za-z0-9_.-]*)?$/.test(p.rest[0]!)) return err(ctx, "invalid reference format"); + pullImage(ctx, p.rest[0]!); + return; + } + case "start": { + const p = parseFlags(rest, { bool: ["attach", "interactive"], alias: { "-a": "--attach", "-i": "--interactive" } }); + if (p.error) return flagError(ctx, "start", p.error); + if (!needArgs(ctx, "start", p.rest.length)) return; + return eachContainer(ctx, p.rest, (c) => startOne(ctx, c)); + } + case "stop": + case "kill": { + const p = parseFlags(rest, { value: ["time", "signal"], alias: { "-t": "--time", "-s": "--signal" } }); + if (p.error) return flagError(ctx, cmd, p.error); + if (!needArgs(ctx, cmd, p.rest.length)) return; + return eachContainer(ctx, p.rest, (c) => { + if (cmd === "kill" && c.status !== "running") return err(ctx, `Error response from daemon: cannot kill container: ${c.name}: container ${c.id} is not running`); + stop(ctx, c, cmd === "kill" ? 137 : 0); + out(ctx, c.name); + }); + } + case "restart": { + const p = parseFlags(rest, { value: ["time"], alias: { "-t": "--time" } }); + if (p.error) return flagError(ctx, "restart", p.error); + if (!needArgs(ctx, "restart", p.rest.length)) return; + return eachContainer(ctx, p.rest, (c) => { + stop(ctx, c); + startOne(ctx, c); + }); + } + case "rm": { + const p = parseFlags(rest, { bool: ["force", "volumes"], alias: { "-f": "--force", "-v": "--volumes" } }); + if (p.error) return flagError(ctx, "rm", p.error); + if (!needArgs(ctx, "rm", p.rest.length)) return; + return eachContainer(ctx, p.rest, (c) => { + if ((c.status === "running" || c.status === "restarting") && !p.has.has("force")) { + return err(ctx, `Error response from daemon: You cannot remove a ${c.status === "running" ? "running" : "restarting"} container ${c.id}. Stop the container before attempting removal or force remove`); + } + removeContainer(world, c, ctx.events); + out(ctx, c.name); + }); + } + case "rmi": { + const p = parseFlags(rest, { bool: ["force"], alias: { "-f": "--force" } }); + if (p.error) return flagError(ctx, "rmi", p.error); + if (!needArgs(ctx, "rmi", p.rest.length)) return; + for (const ref of p.rest) { + const image = findImage(world, ref); + if (!image) { err(ctx, `Error response from daemon: No such image: ${normalizeImage(ref)}`); continue; } + const users = world.containers.filter((c) => c.image === imageRef(image)); + if (users.length && !p.has.has("force")) { + err(ctx, `Error response from daemon: conflict: unable to remove repository reference "${imageRef(image)}" (must force) - container ${shortId(users[0]!.id)} is using its referenced image ${image.id}`); + continue; + } + world.images = world.images.filter((i) => i !== image); + out(ctx, image.repo === "" ? `Deleted: sha256:${hex(`sha:${image.id}`, 64)}` : `Untagged: ${imageRef(image)}`); + } + return; + } + case "logs": return cmdLogs(ctx, rest); + case "inspect": return cmdInspect(ctx, rest); + case "exec": return cmdExec(ctx, rest); + case "stats": return cmdStats(ctx, rest); + case "network": return cmdNetwork(ctx, rest); + case "volume": return cmdVolume(ctx, rest); + case "system": return cmdSystem(ctx, rest); + case "compose": return cmdCompose(ctx, rest); + case "container-prune": + case "image-prune": { + const p = parseFlags(rest, { bool: ["force", "all"], alias: { "-f": "--force", "-a": "--all" } }); + if (p.error) return flagError(ctx, cmd, p.error); + if (!p.has.has("force")) return promptNo(ctx, cmd === "container-prune" ? "all stopped containers" : "all dangling images"); + return cmd === "container-prune" ? prune(ctx, { containers: true }) : prune(ctx, { images: true, allImages: p.has.has("all") }); + } + default: + err(ctx, `docker: '${cmd}' is not a docker command.`); + err(ctx, "See 'docker --help'"); + } +} + +function runSimple(ctx: Ctx, segment: string, depth: number): boolean { + let text = segment.trim(); + if (!text) return true; + // $(...) is replaced by what the inner command prints, one word per line. + for (let guard = 0; guard < 4 && /\$\(([^()]*)\)/.test(text); guard++) { + text = text.replace(/\$\(([^()]*)\)/g, (_m, inner: string) => { + if (depth >= 2) return ""; + const sub: Ctx = { world: ctx.world, lines: [], events: ctx.events, touched: ctx.touched }; + runSimple(sub, inner, depth + 1); + return sub.lines.filter((l) => l.kind === "out").map((l) => l.text.trim()).filter(Boolean).join(" "); + }); + } + const tokens = tokenize(text); + if (tokens === null) { + err(ctx, "bash: unexpected EOF while looking for matching quote"); + return false; + } + const before = ctx.lines.length; + const head = tokens[0]; + if (head === undefined) return true; + if (head === "docker" || head === "docker-compose") cmdDocker(ctx, head === "docker" ? tokens.slice(1) : ["compose", ...tokens.slice(1)]); + else if (head === "curl") { + const target = tokens.slice(1).filter((t) => !t.startsWith("-"))[0]; + if (!target) err(ctx, "curl: try 'curl --help' or 'curl --manual' for more information"); + else { + const result = curlFrom(ctx, null, target); + if (result.ok) { + out(ctx, result.text); + ctx.events.push({ type: "pulled", name: "curl" }); + } else err(ctx, result.text); + } + } else if ((head === "cat" || head === "less") && ctx.world.compose && /^(\.\/)?(docker-)?compose\.ya?ml$/.test(tokens[1] ?? "")) { + outAll(ctx, ctx.world.compose.file); + } else if (head === "ls") outAll(ctx, ctx.world.compose ? ["docker-compose.yml"] : []); + else if (head === "pwd") out(ctx, "/home/learner"); + else if (head === "whoami") out(ctx, "learner"); + else err(ctx, `bash: ${head}: command not found`); + const failed = ctx.lines.slice(before).some((l) => l.kind === "err"); + return !failed; +} + +export const HELP_LINES = [ + "Docker commands you can use here:", + " docker ps [-a] list containers", + " docker images list images", + " docker run -d -p 8080:80 --name web [-e K=V] [-v vol:/path] [--network n] [--restart always] [--memory 512m] IMAGE", + " docker start|stop|restart|rm [-f] NAME", + " docker rmi IMAGE docker pull IMAGE[:TAG]", + " docker logs [--tail N] NAME docker inspect [-f '{{.State.ExitCode}}'] NAME", + " docker exec NAME env | ls | cat FILE | curl HOST:PORT | ping HOST", + " docker network ls|create|connect docker volume ls|create", + " docker stats --no-stream docker system df|prune [-f]", + " curl localhost:8080 (the host side check)", + " docker compose up -d | ps | down (only when a compose file is shown)", + " hint clear reset", +]; + +/** Run one typed line (it may hold several commands joined with &&). Changes the world in place. */ +export function runLine(world: DockerWorld, line: string): RunResult { + const ctx: Ctx = { world, lines: [], events: [], touched: new Set() }; + try { + if (line.length > 300) { + err(ctx, "bash: command line too long"); + return { lines: ctx.lines, ok: false, events: ctx.events }; + } + let ok = true; + for (const part of splitAnd(line)) { + world.tick += 1; + ok = runSimple(ctx, part, 0); + settle(world, ctx.touched, ctx.events); + if (!ok) break; + } + return { lines: ctx.lines, ok, events: ctx.events }; + } catch { + err(ctx, "bash: something went wrong with that command"); + return { lines: ctx.lines, ok: false, events: ctx.events }; + } +} + +// --------------------------------------------------------------------------------------------- +// Goals: what must be true at the end. Pure data, so a round can travel as JSON. + +export type Goal = + | { kind: "running"; name: string; label: string } + | { kind: "absent"; name: string; label: string } + | { kind: "image"; name: string; image: string; label: string } + | { kind: "served"; name: string; contains?: string; label: string } + | { kind: "publishes"; name: string; port: number; label: string } + | { kind: "env"; name: string; key: string; value?: string; label: string } + | { kind: "mount"; name: string; target: string; label: string } + | { kind: "sharedNetwork"; a: string; b: string; label: string } + | { kind: "noExited"; label: string } + | { kind: "noDangling"; label: string } + | { kind: "restartPolicy"; name: string; policy: RestartPolicy; label: string } + | { kind: "memoryAtLeast"; name: string; mb: number; label: string } + | { kind: "imageExists"; image: string; label: string } + | { kind: "volumeExists"; name: string; label: string }; + +/** What a host `curl` would get for a container, trying each published port. */ +export function servedBody(world: DockerWorld, name: string): string | null { + const c = world.containers.find((x) => x.name === name); + if (!c || c.status !== "running") return null; + for (const p of c.ports) { + const ctx: Ctx = { world, lines: [], events: [], touched: new Set() }; + const res = curlFrom(ctx, null, `localhost:${p.host}`); + if (res.ok) return res.text; + } + return null; +} + +export function checkGoal(world: DockerWorld, goal: Goal): boolean { + const find = (name: string) => world.containers.find((c) => c.name === name); + switch (goal.kind) { + case "running": return find(goal.name)?.status === "running"; + case "absent": return !find(goal.name); + case "image": return find(goal.name)?.image === normalizeImage(goal.image); + case "served": { + const body = servedBody(world, goal.name); + return body !== null && (goal.contains === undefined || body.includes(goal.contains)); + } + case "publishes": return find(goal.name)?.ports.some((p) => p.container === goal.port) ?? false; + case "env": { + const v = find(goal.name)?.env[goal.key]; + return v !== undefined && v !== "" && (goal.value === undefined || v === goal.value); + } + case "mount": return find(goal.name)?.mounts.some((m) => m.target === goal.target && m.kind === "volume") ?? false; + case "sharedNetwork": { + const a = find(goal.a); + const b = find(goal.b); + return !!a && !!b && a.networks.some((n) => isUserNetwork(n) && b.networks.includes(n)); + } + case "noExited": return !world.containers.some((c) => c.status === "exited" || c.status === "created"); + case "noDangling": return !world.images.some((i) => i.repo === ""); + case "restartPolicy": return find(goal.name)?.restart === goal.policy; + case "memoryAtLeast": { + const c = find(goal.name); + return !!c && c.status === "running" && (c.memoryMb === 0 || c.memoryMb >= goal.mb); + } + case "imageExists": return !!findImage(world, goal.image); + case "volumeExists": return world.volumes.includes(goal.name); + } +} diff --git a/frontend/src/shared/games/docker/engine.ts b/frontend/src/shared/games/docker/engine.ts new file mode 100644 index 00000000..74f926cf --- /dev/null +++ b/frontend/src/shared/games/docker/engine.ts @@ -0,0 +1,145 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +/* eslint-disable no-control-regex -- the shell engines reject or use control characters on purpose */ +// The Docker Commands daily game. Two modes share each day: "fix" (a virtual Docker host that is +// broken; the player types real commands to repair it) and "build" (the player assembles a +// Dockerfile or a compose file from pieces). The engine is pure: it replays the commands or the +// pieces from the start state and checks the goals. It never throws. + +import { dayNumber, hashString, pickDaily } from "../daily"; +import type { GameEngine, Stars, VerifyResult } from "../types"; +import { checkBuildGoal, simulateBuild, type BuildReport } from "./builder"; +import { checkGoal, cloneWorld, runLine } from "./daemon"; +import { POOL, type BuildRound, type DockerRound, type FixRound } from "./scenarios"; + +export type { BuildRound, DockerRound, FixRound } from "./scenarios"; + +export type FixSubmission = { mode: "fix"; commands: string[]; hints: number }; +export type BuildSubmission = { mode: "build"; steps: string[]; hints: number }; +export type DockerSubmission = FixSubmission | BuildSubmission; + +export const MAX_COMMANDS = 100; +export const MAX_COMMAND_LENGTH = 300; +export const MAX_STEPS = 40; +const MAX_HINTS = 50; + +const POOL_BY_ID = new Map(POOL.map((r) => [r.id, r])); + +/** Today's three rounds: one per difficulty, and always at least one fix and one build round. */ +export function roundsFor(dayKey: string): DockerRound[] { + const picked = pickDaily(POOL, dayKey, "docker"); + const modes = new Set(picked.map((r) => r.mode)); + if (modes.size === 2) return picked; + // All three share a mode: swap the medium round for the nearest medium round of the other mode. + const want = picked[0]!.mode === "fix" ? "build" : "fix"; + const tier = POOL.filter((r) => r.difficulty === "medium"); + const start = tier.indexOf(picked[1]!); + for (let step = 1; step <= tier.length; step++) { + const candidate = tier[(Math.max(0, start) + step + dayNumber(dayKey)) % tier.length]!; + if (candidate.mode === want) return [picked[0]!, candidate, picked[2]!]; + } + const any = tier.find((r) => r.mode === want); + return any ? [picked[0]!, any, picked[2]!] : picked; +} + +const isObject = (v: unknown): v is Record => typeof v === "object" && v !== null && !Array.isArray(v); + +export function parseSubmission(input: unknown): DockerSubmission | null { + try { + if (!isObject(input)) return null; + const keys = Object.keys(input); + const hints = input.hints; + if (typeof hints !== "number" || !Number.isInteger(hints) || hints < 0 || hints > MAX_HINTS) return null; + if (input.mode === "fix") { + if (keys.some((k) => !["mode", "commands", "hints"].includes(k))) return null; + const commands = input.commands; + if (!Array.isArray(commands) || commands.length > MAX_COMMANDS) return null; + for (const c of commands) { + if (typeof c !== "string" || c.trim().length === 0 || c.length > MAX_COMMAND_LENGTH || /[\u0000-\u0008\u000b-\u001f\u007f]/.test(c)) return null; + } + return { mode: "fix", commands: commands as string[], hints }; + } + if (input.mode === "build") { + if (keys.some((k) => !["mode", "steps", "hints"].includes(k))) return null; + const steps = input.steps; + if (!Array.isArray(steps) || steps.length > MAX_STEPS) return null; + for (const s of steps) if (typeof s !== "string" || !/^[A-Za-z0-9_.:-]{1,64}$/.test(s)) return null; + return { mode: "build", steps: steps as string[], hints }; + } + return null; + } catch { + return null; + } +} + +const fail = (message: string, score = 0): VerifyResult => ({ passed: false, stars: 0, score, message }); + +function plural(n: number, word: string) { + return `${n} ${word}${n === 1 ? "" : "s"}`; +} + +function verifyFix(round: FixRound, sub: FixSubmission): VerifyResult { + if (sub.commands.length === 0) return fail("You have not typed any command yet."); + const world = cloneWorld(round.world); + for (const command of sub.commands.slice(0, MAX_COMMANDS)) runLine(world, command); + const unmet = round.goals.filter((g) => !checkGoal(world, g)); + const count = sub.commands.length; + if (unmet.length > 0) return fail(`Not fixed yet: ${unmet[0]!.label}.`, count); + let stars: Stars = 1; + if (sub.hints <= 1 && count <= round.par + 4) stars = 2; + if (sub.hints === 0 && count <= round.par + 1) stars = 3; + const message = + stars === 3 ? `Fixed in ${plural(count, "command")} with no hints, very clean.` + : stars === 2 ? `Fixed in ${plural(count, "command")}. Fewer commands and no hints give the third star.` + : `Fixed in ${plural(count, "command")}. Use fewer commands and fewer hints for more stars.`; + return { passed: true, stars, score: count, message }; +} + +export function buildReportFor(round: BuildRound, steps: string[]): BuildReport { + return simulateBuild(round, steps); +} + +function verifyBuild(round: BuildRound, sub: BuildSubmission): VerifyResult { + if (sub.steps.length === 0) return fail("You have not placed any piece yet."); + const report = simulateBuild(round, sub.steps); + const count = sub.steps.length; + const unmet = round.goals.filter((g) => !checkBuildGoal(report, g)); + if (unmet.length > 0) return fail(report.error ?? `Not done yet: ${unmet[0]!.label}.`, count); + const clean = report.cacheFriendly && report.warnings.length === 0; + const best = simulateBuild(round, round.solution); + let stars: Stars = 1; + if (clean && sub.hints <= 1 && count <= round.par + 2) stars = 2; + if (clean && sub.hints === 0 && count <= round.par && report.sizeMb <= best.sizeMb * 1.05 + 1) stars = 3; + const what = round.kind === "compose" + ? `The stack starts and localhost:${report.port ?? ""} answers.` + : `The image builds in ${report.coldSec} s, a rebuild takes ${report.rebuildSec} s, and it is ${report.sizeMb} MB.`; + const tip = stars === 3 ? " Clean and with no hints." : !report.cacheFriendly ? " Put the dependency install before the code copy for more stars." : report.warnings.length ? ` ${report.warnings[0]}` : " Fewer hints and no extra pieces give more stars."; + return { passed: true, stars, score: count, message: `${what}${tip}` }; +} + +export function verify(round: DockerRound, submission: DockerSubmission): VerifyResult { + try { + const known = isObject(round) && typeof round.id === "string" ? POOL_BY_ID.get(round.id) : undefined; + const real = known ?? (isObject(round) && (round.mode === "fix" || round.mode === "build") ? round : undefined); + if (!real) return fail("That round could not be checked."); + const sub = parseSubmission(submission); + if (!sub) return fail("That did not look like a finished round."); + if (real.mode !== sub.mode) { + return fail(real.mode === "fix" ? "This is a fix round: use the terminal to repair it." : "This is a build round: put the pieces together."); + } + return real.mode === "fix" ? verifyFix(real, sub as FixSubmission) : verifyBuild(real, sub as BuildSubmission); + } catch { + return fail("That answer could not be checked."); + } +} + +export const dockerEngine: GameEngine = { + id: "docker", + title: "Docker Commands", + tagline: "Fix broken containers in a terminal, and build Dockerfiles and compose files from pieces.", + roundsFor, + parseSubmission, + verify, +}; + +/** A small stable number for a round id, for tests and for shuffles that must repeat. */ +export const roundHash = (id: string) => hashString(id); diff --git a/frontend/src/shared/games/docker/scenarios.ts b/frontend/src/shared/games/docker/scenarios.ts new file mode 100644 index 00000000..5d38247f --- /dev/null +++ b/frontend/src/shared/games/docker/scenarios.ts @@ -0,0 +1,503 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The pool of Docker Commands rounds. Each one is plain data (no functions), so it can travel as +// JSON to the browser: a fix round holds a starting world and goals, a build round holds pieces. +// Every round carries a `solution` that the tests replay. + +import type { RoundBase } from "../types"; +import type { AppSpec, BuildData, BuildGoal, BuildPiece, BuildSlot, ComposeFact, ComposeLine } from "./builder"; +import { + danglingImage, emptyWorld, makeContainer, makeImage, type DockerWorld, type Goal, +} from "./daemon"; + +export type FixRound = RoundBase & { + mode: "fix"; + /** The starting state of the virtual Docker host. */ + world: DockerWorld; + goals: Goal[]; + /** Commands the shortest sensible fix takes, including one look at what is wrong. */ + par: number; + hints: string[]; + solution: string[]; +}; + +export type BuildRound = RoundBase & BuildData & { + mode: "build"; + goals: BuildGoal[]; + par: number; + hints: string[]; + solution: string[]; +}; + +export type DockerRound = FixRound | BuildRound; + +const world = (p: Partial): DockerWorld => ({ ...emptyWorld(), ...p }); + +const NGINX_STOP_LOGS = ["nginx: [notice] signal 15 (SIGTERM) received, exiting"]; + +// --------------------------------------------------------------------------------------------- +// Fix rounds. + +const startStopped: FixRound = { + id: "docker-start-stopped", mode: "fix", difficulty: "easy", + title: "The site is down", + brief: "The web container was stopped and now http://localhost:8080 shows nothing. Bring the site back with the same container.", + world: world({ + images: [makeImage("nginx:1.25")], + containers: [makeContainer({ name: "web", image: "nginx:1.25", status: "exited", exitCode: 0, ports: [{ host: 8080, container: 80 }], logs: NGINX_STOP_LOGS, since: "10 minutes" })], + }), + goals: [ + { kind: "running", name: "web", label: "Container web is running" }, + { kind: "served", name: "web", contains: "Welcome to nginx", label: "curl localhost:8080 shows the nginx page" }, + ], + par: 2, + hints: ["List all containers, also the stopped ones: docker ps -a", "The container is called web. It only needs to be started again.", "Run: docker start web"], + solution: ["docker ps -a", "docker start web"], +}; + +const wrongPort: FixRound = { + id: "docker-wrong-port", mode: "fix", difficulty: "easy", + title: "Nothing answers on 8080", + brief: "The container web is running, but curl localhost:8080 fails. The nginx server inside listens on port 80.", + world: world({ + images: [makeImage("nginx:1.25")], + containers: [makeContainer({ name: "web", image: "nginx:1.25", ports: [{ host: 8080, container: 8080 }], logs: ["/docker-entrypoint.sh: Configuration complete; ready for start up", "nginx: [notice] start worker processes"], since: "5 minutes" })], + }), + goals: [ + { kind: "running", name: "web", label: "Container web is running" }, + { kind: "publishes", name: "web", port: 80, label: "Host port 8080 leads to container port 80" }, + { kind: "served", name: "web", contains: "Welcome to nginx", label: "curl localhost:8080 shows the nginx page" }, + ], + par: 3, + hints: ["Try curl localhost:8080 and read the error. Then look at the PORTS column of docker ps.", "The mapping is -p HOST:CONTAINER. The container side must be 80. A running container cannot change its ports, so remove it with docker rm -f web.", "Run it again: docker run -d --name web -p 8080:80 nginx:1.25"], + solution: ["curl localhost:8080", "docker rm -f web", "docker run -d --name web -p 8080:80 nginx:1.25"], +}; + +const missingEnv: FixRound = { + id: "docker-missing-env", mode: "fix", difficulty: "medium", + title: "The database stops at once", + brief: "Container db (postgres:16) exits a second after it starts. Find out why and get it running.", + world: world({ + images: [makeImage("postgres:16")], + containers: [makeContainer({ + name: "db", image: "postgres:16", status: "exited", exitCode: 1, since: "2 minutes", + logs: [ + "Error: Database is uninitialized and superuser password is not specified.", + " You must specify POSTGRES_PASSWORD to a non-empty value for the", + " superuser. For example, \"-e POSTGRES_PASSWORD=password\" on \"docker run\".", + ], + })], + }), + goals: [ + { kind: "running", name: "db", label: "Container db is running" }, + { kind: "env", name: "db", key: "POSTGRES_PASSWORD", label: "db has a POSTGRES_PASSWORD" }, + ], + par: 3, + hints: ["docker ps -a shows the exit code. docker logs db shows the reason.", "The log asks for POSTGRES_PASSWORD. A container keeps the environment it was created with, so remove it first: docker rm db", "docker run -d --name db -e POSTGRES_PASSWORD=secret postgres:16"], + solution: ["docker logs db", "docker rm db", "docker run -d --name db -e POSTGRES_PASSWORD=secret postgres:16"], +}; + +const portTaken: FixRound = { + id: "docker-port-taken", mode: "fix", difficulty: "medium", + title: "Port 8080 is already taken", + brief: "Start a container named web from nginx:1.25 that answers on localhost. Port 8080 is the plan, but something may be using it. Free the port or pick another one.", + world: world({ + images: [makeImage("nginx:1.25")], + containers: [makeContainer({ name: "old-site", image: "nginx:1.25", ports: [{ host: 8080, container: 80 }], logs: ["nginx: [notice] start worker processes"], since: "3 hours" })], + }), + goals: [ + { kind: "running", name: "web", label: "Container web is running" }, + { kind: "publishes", name: "web", port: 80, label: "web publishes container port 80" }, + { kind: "served", name: "web", contains: "Welcome to nginx", label: "curl on its host port shows the nginx page" }, + ], + par: 3, + hints: ["docker ps shows who uses 8080.", "Either stop the old container (docker stop old-site) or use another host port, like -p 8081:80.", "docker run -d --name web -p 8081:80 nginx:1.25 works. If a run fails, a half made container stays: remove it with docker rm web."], + solution: ["docker ps", "docker stop old-site", "docker run -d --name web -p 8080:80 nginx:1.25"], +}; + +const lostData: FixRound = { + id: "docker-lost-data", mode: "fix", difficulty: "medium", + title: "The database forgets everything", + brief: "Every time the db container is removed and recreated, the orders are gone. Keep the data on a named volume called pgdata, mounted at /var/lib/postgresql/data.", + world: world({ + images: [makeImage("postgres:16")], + containers: [makeContainer({ + name: "db", image: "postgres:16", env: { POSTGRES_PASSWORD: "secret" }, ports: [{ host: 5432, container: 5432 }], + logs: ["PostgreSQL init process complete; ready for start up.", "LOG: database system is ready to accept connections"], since: "1 hour", + })], + }), + goals: [ + { kind: "running", name: "db", label: "Container db is running" }, + { kind: "mount", name: "db", target: "/var/lib/postgresql/data", label: "A named volume is mounted at /var/lib/postgresql/data" }, + { kind: "env", name: "db", key: "POSTGRES_PASSWORD", label: "db still has its POSTGRES_PASSWORD" }, + ], + par: 3, + hints: ["docker inspect db has a Mounts list. It is empty, so the data lives inside the container.", "A volume must be given when the container is created. Remove db, then run it again with -v pgdata:/var/lib/postgresql/data", "docker run -d --name db -e POSTGRES_PASSWORD=secret -v pgdata:/var/lib/postgresql/data postgres:16"], + solution: ["docker inspect db", "docker rm -f db", "docker run -d --name db -e POSTGRES_PASSWORD=secret -v pgdata:/var/lib/postgresql/data postgres:16"], +}; + +const noNetwork: FixRound = { + id: "docker-no-network", mode: "fix", difficulty: "medium", + title: "The web container cannot find the database", + brief: "web talks to the host name db, but it crashes. Both containers are on the default bridge network, where names do not work. Connect them so that web runs and curl localhost:8080 works.", + world: world({ + images: [makeImage("shop/web:2.0"), makeImage("postgres:16")], + containers: [ + makeContainer({ name: "db", image: "postgres:16", env: { POSTGRES_PASSWORD: "secret" }, logs: ["LOG: database system is ready to accept connections"], since: "20 minutes" }), + makeContainer({ + name: "web", image: "shop/web:2.0", status: "exited", exitCode: 1, env: { DB_HOST: "db" }, ports: [{ host: 8080, container: 3000 }], since: "19 minutes", + logs: ["Error: getaddrinfo ENOTFOUND db", " at GetAddrInfoReqWrap.onlookup [as oncomplete] (node:dns:109:26)"], + }), + ], + }), + goals: [ + { kind: "running", name: "db", label: "Container db is running" }, + { kind: "sharedNetwork", a: "web", b: "db", label: "web and db share a network you created" }, + { kind: "running", name: "web", label: "Container web is running" }, + { kind: "served", name: "web", contains: "database", label: "curl localhost:8080 says it is connected to the database" }, + ], + par: 5, + hints: ["docker logs web says it cannot find the host db. Names only work on a network you create yourself.", "Create one with docker network create appnet, then connect db and web with docker network connect appnet NAME.", "Finish with docker start web."], + solution: ["docker logs web", "docker network create appnet", "docker network connect appnet db", "docker network connect appnet web", "docker start web"], +}; + +const oomLoop: FixRound = { + id: "docker-oom-loop", mode: "fix", difficulty: "hard", + title: "The worker keeps restarting", + brief: "The container worker restarts again and again. Find the reason, then run it so it stays up. Keep the restart policy unless-stopped.", + world: world({ + images: [makeImage("acme/worker:3.1")], + containers: [makeContainer({ + name: "worker", image: "acme/worker:3.1", status: "restarting", exitCode: 137, oomKilled: true, restartCount: 14, restart: "unless-stopped", memoryMb: 256, + logs: ["worker: loading model into memory (needs about 400 MB)", "Killed", "worker: loading model into memory (needs about 400 MB)", "Killed"], since: "4 seconds", + })], + }), + goals: [ + { kind: "memoryAtLeast", name: "worker", mb: 400, label: "worker is running with enough memory (400 MB or more, or no limit)" }, + { kind: "restartPolicy", name: "worker", policy: "unless-stopped", label: "The restart policy is still unless-stopped" }, + ], + par: 5, + hints: ["docker ps shows Restarting. docker logs worker ends with Killed.", "docker inspect worker (try -f '{{.State.OOMKilled}}') shows OOMKilled true and a Memory limit of 256 MB. The app needs about 400 MB.", "Memory cannot be changed on the old container. Remove it and run again with --memory 512m and --restart unless-stopped."], + solution: ["docker ps", "docker logs worker", "docker inspect worker", "docker rm -f worker", "docker run -d --name worker --restart unless-stopped --memory 512m acme/worker:3.1"], +}; + +const newRelease: FixRound = { + id: "docker-new-release", mode: "fix", difficulty: "hard", + title: "Ship release 2.0", + brief: "The site container runs acme/site:1.0 on port 8080. Replace it with acme/site:2.0 on the same port, and keep the cache container running. The new release has its own needs, so read what it says if it fails.", + world: world({ + images: [makeImage("acme/site:1.0"), makeImage("redis:7")], + containers: [ + makeContainer({ name: "cache", image: "redis:7", logs: ["Ready to accept connections tcp"], since: "2 days" }), + makeContainer({ name: "site", image: "acme/site:1.0", ports: [{ host: 8080, container: 80 }], logs: ["site 1.0 ready"], since: "2 days" }), + ], + }), + goals: [ + { kind: "image", name: "site", image: "acme/site:2.0", label: "Container site uses acme/site:2.0" }, + { kind: "running", name: "site", label: "Container site is running" }, + { kind: "served", name: "site", contains: "v2", label: "curl localhost:8080 shows the v2 page" }, + { kind: "running", name: "cache", label: "Container cache is still running" }, + ], + par: 4, + hints: ["docker pull acme/site:2.0 downloads the new release. Then stop and remove the old site container to free the name and port 8080.", "If the new container exits, docker logs site tells you what it needs. Here it is the variable SITE_NAME.", "docker run -d --name site -p 8080:80 -e SITE_NAME=Acme acme/site:2.0"], + solution: ["docker pull acme/site:2.0", "docker stop site", "docker rm site", "docker run -d --name site -p 8080:80 -e SITE_NAME=Acme acme/site:2.0"], +}; + +const diskFull: FixRound = { + id: "docker-disk-full", mode: "fix", difficulty: "hard", + title: "Free some disk space", + brief: "The server disk is almost full. Remove the stopped containers and the dangling images (the ones shown as ). Keep the running containers, the image shop/api:1.2 and both volumes.", + world: world({ + images: [ + makeImage("nginx:1.25"), makeImage("postgres:16"), makeImage("shop/api:1.2"), makeImage("legacy/app:0.9"), + danglingImage("a", 320), danglingImage("b", 210), danglingImage("c", 150), + ], + volumes: ["pgdata", "old-cache"], + containers: [ + makeContainer({ name: "web", image: "nginx:1.25", ports: [{ host: 8080, container: 80 }], since: "3 days" }), + makeContainer({ name: "db", image: "postgres:16", env: { POSTGRES_PASSWORD: "secret" }, mounts: [{ source: "pgdata", target: "/var/lib/postgresql/data", kind: "volume" }], since: "3 days" }), + makeContainer({ name: "build-tmp", image: "legacy/app:0.9", status: "exited", exitCode: 0, since: "6 days" }), + makeContainer({ name: "test-run", image: "nginx:1.25", status: "exited", exitCode: 1, since: "4 days" }), + makeContainer({ name: "old-api", image: "shop/api:1.2", status: "exited", exitCode: 137, since: "9 days" }), + ], + }), + goals: [ + { kind: "noExited", label: "No stopped containers are left" }, + { kind: "noDangling", label: "No dangling images are left" }, + { kind: "running", name: "web", label: "web is still running" }, + { kind: "running", name: "db", label: "db is still running" }, + { kind: "imageExists", image: "shop/api:1.2", label: "Image shop/api:1.2 is kept" }, + { kind: "volumeExists", name: "pgdata", label: "Volume pgdata is kept" }, + { kind: "volumeExists", name: "old-cache", label: "Volume old-cache is kept" }, + ], + par: 2, + hints: ["docker system df shows what takes the space. docker ps -a shows the stopped containers.", "docker system prune -f removes stopped containers and dangling images. Be careful with -a (all unused images) and --volumes: they also remove things you must keep.", "Run: docker system prune -f"], + solution: ["docker system df", "docker system prune -f"], +}; + +const COMPOSE_FILE = [ + "services:", + " web:", + " image: shop/web:2.0", + " ports: [\"8080:3000\"]", + " environment:", + " DB_HOST: db", + " depends_on: [db]", + " db:", + " image: postgres:16", + " environment:", + " POSTGRES_PASSWORD: secret", + " volumes:", + " - pgdata:/var/lib/postgresql/data", + "volumes:", + " pgdata:", +]; + +const composeConflict: FixRound = { + id: "docker-compose-conflict", mode: "fix", difficulty: "hard", + title: "The stack will not come up", + brief: "docker-compose.yml describes a web app and its database (project shop). Start the whole stack with compose and make the app answer on localhost:8080. Type cat docker-compose.yml to read the file.", + world: world({ + images: [makeImage("shop/web:2.0"), makeImage("postgres:16"), makeImage("nginx:1.25")], + containers: [makeContainer({ name: "scratch", image: "nginx:1.25", ports: [{ host: 8080, container: 80 }], logs: ["nginx: [notice] start worker processes"], since: "1 day" })], + compose: { + project: "shop", + file: COMPOSE_FILE, + services: [ + { name: "web", image: "shop/web:2.0", ports: ["8080:3000"], env: { DB_HOST: "db" }, volumes: [], dependsOn: ["db"] }, + { name: "db", image: "postgres:16", ports: [], env: { POSTGRES_PASSWORD: "secret" }, volumes: ["pgdata:/var/lib/postgresql/data"], dependsOn: [] }, + ], + }, + }), + goals: [ + { kind: "running", name: "shop-db-1", label: "shop-db-1 is running" }, + { kind: "running", name: "shop-web-1", label: "shop-web-1 is running" }, + { kind: "served", name: "shop-web-1", contains: "database", label: "curl localhost:8080 says it is connected to the database" }, + ], + par: 4, + hints: ["Start with docker compose up -d, then docker compose ps -a or docker ps -a to see what did not start.", "The web service wants host port 8080, but the container scratch holds it. Stop it: docker stop scratch", "After stopping scratch, run docker compose up -d again. It starts what is missing."], + solution: ["docker compose up -d", "docker ps -a", "docker stop scratch", "docker compose up -d"], +}; + +// --------------------------------------------------------------------------------------------- +// Build rounds. + +const piece = (id: string, text: string): BuildPiece => ({ id, text }); +const NODE_APP: AppSpec = { runtime: "node", manifest: "package*.json", defaultPort: 3000, start: ["node server.js", "npm start"] }; + +const buildNodeOrder: BuildRound = { + id: "docker-build-node-order", mode: "build", difficulty: "easy", kind: "dockerfile", + title: "Order a Node Dockerfile", + brief: "Put the lines of this Node app's Dockerfile in the right order. It must build, answer on port 3000, and rebuild fast after a code change (10 seconds or less).", + app: { ...NODE_APP }, + pieces: [ + piece("cp-src", "COPY . ."), piece("cmd", 'CMD ["node", "server.js"]'), piece("npm-ci", "RUN npm ci"), piece("from", "FROM node:20-slim"), + piece("expose", "EXPOSE 3000"), piece("cp-pkg", "COPY package*.json ./"), piece("workdir", "WORKDIR /app"), + ], + goals: [ + { kind: "builds", label: "The image builds" }, + { kind: "reachable", port: 3000, label: "The app answers on port 3000" }, + { kind: "rebuild", maxSec: 10, label: "A rebuild after a code change takes 10 seconds or less" }, + ], + par: 7, + hints: ["FROM always comes first. WORKDIR comes before any COPY.", "Docker reuses a layer when nothing above it changed. Copy only package*.json first, run npm ci, and only then copy the rest of the code.", "Order: FROM, WORKDIR, COPY package*.json, RUN npm ci, COPY . ., EXPOSE, CMD."], + solution: ["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "expose", "cmd"], +}; + +const buildSlim: BuildRound = { + id: "docker-build-slim", mode: "build", difficulty: "easy", kind: "dockerfile", + title: "Pick the right base image", + brief: "Build a small image for this Python app. Choose one base image and put the lines in order. The image must be under 400 MB, answer on port 8000, and rebuild fast.", + app: { runtime: "python", manifest: "requirements.txt", defaultPort: 8000, start: ["python app.py"] }, + pieces: [ + piece("from-full", "FROM python:3.12"), piece("pip", "RUN pip install -r requirements.txt"), piece("expose", "EXPOSE 8000"), piece("from-ubuntu", "FROM ubuntu:22.04"), + piece("cp-src", "COPY . ."), piece("from-slim", "FROM python:3.12-slim"), piece("cmd", 'CMD ["python", "app.py"]'), piece("cp-req", "COPY requirements.txt ./"), piece("workdir", "WORKDIR /app"), + ], + goals: [ + { kind: "builds", label: "The image builds" }, + { kind: "reachable", port: 8000, label: "The app answers on port 8000" }, + { kind: "size", maxMb: 400, label: "The image is under 400 MB" }, + { kind: "rebuild", maxSec: 10, label: "A rebuild takes 10 seconds or less" }, + ], + par: 7, + hints: ["Use only one FROM. python:3.12 is the full image (about 1 GB). ubuntu has no Python at all.", "python:3.12-slim has Python and is small. Copy requirements.txt, install, then copy the code.", "Order: FROM python:3.12-slim, WORKDIR, COPY requirements.txt, RUN pip install, COPY . ., EXPOSE 8000, CMD."], + solution: ["from-slim", "workdir", "cp-req", "pip", "cp-src", "expose", "cmd"], +}; + +const buildPortEnv: BuildRound = { + id: "docker-build-port-env", mode: "build", difficulty: "easy", kind: "dockerfile", + title: "Set the port and the start command", + brief: "The platform sends traffic to port 8080. This Node app listens on the port in the PORT variable (3000 if it is not set). Choose the lines so the app answers on 8080.", + app: { ...NODE_APP, portEnv: "PORT", start: ["node server.js"] }, + pieces: [ + piece("env-3000", "ENV PORT=3000"), piece("cp-pkg", "COPY package*.json ./"), piece("cmd-dev", 'CMD ["npm", "run", "dev"]'), piece("expose-3000", "EXPOSE 3000"), + piece("from", "FROM node:20-slim"), piece("npm-ci", "RUN npm ci"), piece("env-8080", "ENV PORT=8080"), piece("workdir", "WORKDIR /app"), + piece("cmd-node", 'CMD ["node", "server.js"]'), piece("expose-8080", "EXPOSE 8080"), piece("cp-src", "COPY . ."), + ], + goals: [ + { kind: "builds", label: "The image builds" }, + { kind: "reachable", port: 8080, label: "The app answers on port 8080" }, + ], + par: 8, + hints: ["The app listens on the port in PORT, and EXPOSE must name that same port. Use 8080 for both.", "npm run dev needs dev tools that are not installed in a production image. Start the server with node.", "FROM, WORKDIR, COPY package*.json, RUN npm ci, COPY . ., ENV PORT=8080, EXPOSE 8080, CMD node server.js."], + solution: ["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "env-8080", "expose-8080", "cmd-node"], +}; + +const buildPythonService: BuildRound = { + id: "docker-build-python-service", mode: "build", difficulty: "medium", kind: "dockerfile", + title: "A small Python service on port 9000", + brief: "This Python service listens on the port in the PORT variable (5000 if it is not set). Build a small image (under 250 MB) that answers on port 9000 and rebuilds fast after a code change.", + app: { runtime: "python", manifest: "requirements.txt", defaultPort: 5000, portEnv: "PORT", start: ["python app.py"] }, + pieces: [ + piece("expose-5000", "EXPOSE 5000"), piece("from-full", "FROM python:3.12"), piece("cp-src", "COPY . ."), piece("env-9000", "ENV PORT=9000"), + piece("pip", "RUN pip install --no-cache-dir -r requirements.txt"), piece("cmd-flask", 'CMD ["flask", "run"]'), piece("from-slim", "FROM python:3.12-slim"), + piece("expose-9000", "EXPOSE 9000"), piece("workdir", "WORKDIR /srv"), piece("cp-req", "COPY requirements.txt ./"), piece("cmd", 'CMD ["python", "app.py"]'), + ], + goals: [ + { kind: "builds", label: "The image builds" }, + { kind: "reachable", port: 9000, label: "The service answers on port 9000" }, + { kind: "size", maxMb: 250, label: "The image is under 250 MB" }, + { kind: "rebuild", maxSec: 10, label: "A rebuild after a code change takes 10 seconds or less" }, + ], + par: 8, + hints: ["python:3.12 is about 1 GB. The slim variant is far smaller. Use one FROM only.", "The service reads PORT, so set ENV PORT=9000 and EXPOSE 9000. Copy requirements.txt and install before you copy the code.", "FROM python:3.12-slim, WORKDIR, COPY requirements.txt, RUN pip install, COPY . ., ENV PORT=9000, EXPOSE 9000, CMD python app.py."], + solution: ["from-slim", "workdir", "cp-req", "pip", "cp-src", "env-9000", "expose-9000", "cmd"], +}; + +function slotPiece(slot: string, id: string, text: string, facts: ComposeFact[] = []): BuildPiece { + return { id, slot, text, facts }; +} + +const basicSlots: BuildSlot[] = [ + { id: "web-port", label: "web: published port", indent: 4 }, + { id: "web-env", label: "web: database host", indent: 4 }, + { id: "web-dep", label: "web: start order", indent: 4 }, + { id: "db-env", label: "db: settings", indent: 4 }, + { id: "db-vol", label: "db: where the data lives", indent: 4 }, + { id: "top-vol", label: "named volumes", indent: 0 }, +]; +const basicSkeleton: ComposeLine[] = [ + { text: "services:" }, { text: " web:" }, { text: " image: shop/web:2.0" }, { slot: "web-port" }, { slot: "web-env" }, { slot: "web-dep" }, + { text: " db:" }, { text: " image: postgres:16" }, { slot: "db-env" }, { slot: "db-vol" }, { slot: "top-vol" }, +]; + +const buildComposeBasic: BuildRound = { + id: "docker-build-compose-basic", mode: "build", difficulty: "medium", kind: "compose", + title: "Wire the web app to its database", + brief: "Fill the blanks of this compose file. web listens on port 3000 inside its container and must answer on localhost:8080. It reaches the database by the name db, so db must start first. The database data must survive on the named volume pgdata.", + slots: basicSlots, skeleton: basicSkeleton, + pieces: [ + slotPiece("web-port", "wp-ok", 'ports: ["8080:3000"]', [{ service: "web", key: "port", value: "8080:3000" }]), + slotPiece("web-port", "wp-same", 'ports: ["8080:8080"]', [{ service: "web", key: "port", value: "8080:8080" }]), + slotPiece("web-port", "wp-swap", 'ports: ["3000:8080"]', [{ service: "web", key: "port", value: "3000:8080" }]), + slotPiece("web-env", "we-localhost", "environment: [DB_HOST=localhost]", [{ service: "web", key: "env", value: "DB_HOST=localhost" }]), + slotPiece("web-env", "we-db", "environment: [DB_HOST=db]", [{ service: "web", key: "env", value: "DB_HOST=db" }]), + slotPiece("web-env", "we-postgres", "environment: [DB_HOST=postgres]", [{ service: "web", key: "env", value: "DB_HOST=postgres" }]), + slotPiece("web-dep", "wd-cache", "depends_on: [cache]", [{ service: "web", key: "depends", value: "cache" }]), + slotPiece("web-dep", "wd-db", "depends_on: [db]", [{ service: "web", key: "depends", value: "db" }]), + slotPiece("web-dep", "wd-restart", "restart: always"), + slotPiece("db-env", "de-db", "environment: [POSTGRES_DB=shop]", [{ service: "db", key: "env", value: "POSTGRES_DB=shop" }]), + slotPiece("db-env", "de-empty", "environment: [POSTGRES_PASSWORD=]", [{ service: "db", key: "env", value: "POSTGRES_PASSWORD=" }]), + slotPiece("db-env", "de-ok", "environment: [POSTGRES_PASSWORD=secret]", [{ service: "db", key: "env", value: "POSTGRES_PASSWORD=secret" }]), + slotPiece("db-vol", "dv-data", 'volumes: ["pgdata:/data"]', [{ service: "db", key: "volume", value: "pgdata:/data" }]), + slotPiece("db-vol", "dv-ok", 'volumes: ["pgdata:/var/lib/postgresql/data"]', [{ service: "db", key: "volume", value: "pgdata:/var/lib/postgresql/data" }]), + slotPiece("db-vol", "dv-bind", 'volumes: ["./pg:/tmp/pg"]', [{ service: "db", key: "volume", value: "./pg:/tmp/pg" }]), + slotPiece("top-vol", "tv-none", "# no named volumes"), + slotPiece("top-vol", "tv-data", "volumes: { data: {} }", [{ service: "", key: "decl-volume", value: "data" }]), + slotPiece("top-vol", "tv-pgdata", "volumes: { pgdata: {} }", [{ service: "", key: "decl-volume", value: "pgdata" }]), + ], + stack: { + services: { + web: { image: "shop/web:2.0", sizeMb: 212, port: 3000, hostEnv: { key: "DB_HOST", value: "db" }, mustDependOn: ["db"], mustReach: ["db"] }, + db: { image: "postgres:16", sizeMb: 432, port: 5432, requiredEnv: ["POSTGRES_PASSWORD"], dataPath: "/var/lib/postgresql/data" }, + }, + publish: { service: "web", host: 8080 }, + }, + goals: [ + { kind: "builds", label: "The compose file is valid" }, + { kind: "runs", label: "Both services start and stay up" }, + { kind: "reachable", port: 8080, label: "localhost:8080 answers" }, + { kind: "persists", label: "The database data is on a volume" }, + ], + par: 6, + hints: ["The port line is HOST:CONTAINER. web listens on 3000 inside, so the right side must be 3000.", "Inside a compose project, services find each other by service name: DB_HOST=db. depends_on makes db start first. Postgres needs a non-empty POSTGRES_PASSWORD.", "Mount pgdata at /var/lib/postgresql/data, and declare pgdata under the top level volumes."], + solution: ["web-port:wp-ok", "web-env:we-db", "web-dep:wd-db", "db-env:de-ok", "db-vol:dv-ok", "top-vol:tv-pgdata"], +}; + +const tierSlots: BuildSlot[] = [ + { id: "web-port", label: "web: published port", indent: 4 }, + { id: "web-net", label: "web: networks", indent: 4 }, + { id: "api-env", label: "api: database host", indent: 4 }, + { id: "api-net", label: "api: networks", indent: 4 }, + { id: "db-env", label: "db: settings", indent: 4 }, + { id: "db-vol", label: "db: where the data lives", indent: 4 }, + { id: "db-net", label: "db: networks", indent: 4 }, + { id: "top-net", label: "networks", indent: 0 }, + { id: "top-vol", label: "named volumes", indent: 0 }, +]; +const tierSkeleton: ComposeLine[] = [ + { text: "services:" }, + { text: " web:" }, { text: " image: nginx:1.25-alpine" }, { text: " depends_on: [api]" }, { slot: "web-port" }, { slot: "web-net" }, + { text: " api:" }, { text: " image: shop/api:1.2" }, { text: " depends_on: [db]" }, { slot: "api-env" }, { slot: "api-net" }, + { text: " db:" }, { text: " image: postgres:16" }, { slot: "db-env" }, { slot: "db-vol" }, { slot: "db-net" }, + { slot: "top-net" }, { slot: "top-vol" }, +]; + +const net = (slot: string, id: string, service: string, nets: string[]) => + slotPiece(slot, id, `networks: [${nets.join(", ")}]`, nets.map((n) => ({ service, key: "network" as const, value: n }))); + +const buildComposeTiers: BuildRound = { + id: "docker-build-compose-tiers", mode: "build", difficulty: "hard", kind: "compose", + title: "Three tiers on two networks", + brief: "Wire web, api and db. web must reach api, api must reach db, but web must not reach db directly: use the networks front and back. web answers on localhost:8080 (nginx listens on port 80). api reaches the database by the name db. The data stays on the volume pgdata.", + slots: tierSlots, skeleton: tierSkeleton, + fixed: [{ service: "web", key: "depends", value: "api" }, { service: "api", key: "depends", value: "db" }], + pieces: [ + slotPiece("web-port", "wp-ok", 'ports: ["8080:80"]', [{ service: "web", key: "port", value: "8080:80" }]), + slotPiece("web-port", "wp-same", 'ports: ["8080:8080"]', [{ service: "web", key: "port", value: "8080:8080" }]), + slotPiece("web-port", "wp-swap", 'ports: ["80:8080"]', [{ service: "web", key: "port", value: "80:8080" }]), + net("web-net", "wn-both", "web", ["front", "back"]), net("web-net", "wn-front", "web", ["front"]), net("web-net", "wn-back", "web", ["back"]), + slotPiece("api-env", "ae-local", "environment: [DB_HOST=localhost]", [{ service: "api", key: "env", value: "DB_HOST=localhost" }]), + slotPiece("api-env", "ae-db", "environment: [DB_HOST=db]", [{ service: "api", key: "env", value: "DB_HOST=db" }]), + slotPiece("api-env", "ae-pg", "environment: [DB_HOST=postgres]", [{ service: "api", key: "env", value: "DB_HOST=postgres" }]), + net("api-net", "an-front", "api", ["front"]), net("api-net", "an-back", "api", ["back"]), net("api-net", "an-both", "api", ["front", "back"]), + slotPiece("db-env", "de-ok", "environment: [POSTGRES_PASSWORD=secret]", [{ service: "db", key: "env", value: "POSTGRES_PASSWORD=secret" }]), + slotPiece("db-env", "de-user", "environment: [POSTGRES_USER=shop]", [{ service: "db", key: "env", value: "POSTGRES_USER=shop" }]), + slotPiece("db-env", "de-empty", "environment: [POSTGRES_PASSWORD=]", [{ service: "db", key: "env", value: "POSTGRES_PASSWORD=" }]), + slotPiece("db-vol", "dv-ok", 'volumes: ["pgdata:/var/lib/postgresql/data"]', [{ service: "db", key: "volume", value: "pgdata:/var/lib/postgresql/data" }]), + slotPiece("db-vol", "dv-tmp", 'volumes: ["pgdata:/tmp"]', [{ service: "db", key: "volume", value: "pgdata:/tmp" }]), + slotPiece("db-vol", "dv-bind", 'volumes: ["./pg:/var/lib/postgresql/data"]', [{ service: "db", key: "volume", value: "./pg:/var/lib/postgresql/data" }]), + net("db-net", "dn-front", "db", ["front"]), net("db-net", "dn-both", "db", ["front", "back"]), net("db-net", "dn-back", "db", ["back"]), + slotPiece("top-net", "tn-front", "networks: { front: {} }", [{ service: "", key: "decl-network", value: "front" }]), + slotPiece("top-net", "tn-both", "networks: { front: {}, back: {} }", [{ service: "", key: "decl-network", value: "front" }, { service: "", key: "decl-network", value: "back" }]), + slotPiece("top-net", "tn-back", "networks: { back: {} }", [{ service: "", key: "decl-network", value: "back" }]), + slotPiece("top-vol", "tv-pgdata", "volumes: { pgdata: {} }", [{ service: "", key: "decl-volume", value: "pgdata" }]), + slotPiece("top-vol", "tv-data", "volumes: { data: {} }", [{ service: "", key: "decl-volume", value: "data" }]), + slotPiece("top-vol", "tv-none", "# no named volumes"), + ], + stack: { + services: { + web: { image: "nginx:1.25-alpine", sizeMb: 43, port: 80, mustReach: ["api"] }, + api: { image: "shop/api:1.2", sizeMb: 164, port: 4000, hostEnv: { key: "DB_HOST", value: "db" }, mustReach: ["db"], mustDependOn: ["db"] }, + db: { image: "postgres:16", sizeMb: 432, port: 5432, requiredEnv: ["POSTGRES_PASSWORD"], dataPath: "/var/lib/postgresql/data" }, + }, + publish: { service: "web", host: 8080 }, + isolate: ["web", "db"], + }, + goals: [ + { kind: "builds", label: "The compose file is valid" }, + { kind: "runs", label: "All three services start and stay up" }, + { kind: "reachable", port: 8080, label: "localhost:8080 answers" }, + { kind: "isolated", label: "web cannot reach db directly" }, + { kind: "persists", label: "The database data is on a volume" }, + ], + par: 9, + hints: ["Networks: web needs front (to reach api), db needs back, and api sits on both so it can talk to each side. Declare every network you use at the top level.", "The port line is HOST:CONTAINER. nginx listens on 80 inside. api reaches the database as DB_HOST=db, not localhost.", "web: 8080:80, front. api: DB_HOST=db, front and back. db: POSTGRES_PASSWORD=secret, pgdata at /var/lib/postgresql/data, back. Declare front, back and pgdata."], + solution: ["web-port:wp-ok", "web-net:wn-front", "api-env:ae-db", "api-net:an-both", "db-env:de-ok", "db-vol:dv-ok", "db-net:dn-back", "top-net:tn-both", "top-vol:tv-pgdata"], +}; + +/** Every round of the game. Easy leans to build, medium and hard to fix. */ +export const POOL: readonly DockerRound[] = [ + buildNodeOrder, buildSlim, buildPortEnv, startStopped, wrongPort, + missingEnv, portTaken, lostData, noNetwork, buildComposeBasic, buildPythonService, + oomLoop, newRelease, diskFull, composeConflict, buildComposeTiers, +]; diff --git a/frontend/src/shared/games/index.ts b/frontend/src/shared/games/index.ts new file mode 100644 index 00000000..49b1d1b9 --- /dev/null +++ b/frontend/src/shared/games/index.ts @@ -0,0 +1,19 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +import type { AnyGameEngine, GameId } from "./types"; +import { sysdesignEngine } from "./sysdesign/engine"; +import { linuxEngine } from "./linux/engine"; +import { dockerEngine } from "./docker/engine"; + +export * from "./types"; +export * from "./daily"; + +/** Every daily game, by id. The server verifies submissions and the browser plays with these. */ +export const GAME_ENGINES: Record = { + sysdesign: sysdesignEngine as unknown as AnyGameEngine, + linux: linuxEngine as unknown as AnyGameEngine, + docker: dockerEngine as unknown as AnyGameEngine, +}; + +export function engineFor(game: GameId): AnyGameEngine { + return GAME_ENGINES[game]; +} diff --git a/frontend/src/shared/games/linux/commands.ts b/frontend/src/shared/games/linux/commands.ts new file mode 100644 index 00000000..8a2b5b69 --- /dev/null +++ b/frontend/src/shared/games/linux/commands.ts @@ -0,0 +1,1642 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The commands of the practice shell. Each one is a small pure function of the shell state. They +// follow the real tools closely enough that what a player learns here works on a real server. +import { + BLOCK, DAY, ERR_TEXT, baseName, can, diskUsage, dirName, formatTime, humanSize, joinPath, modeString, normalizePath, sizeOf, + type Err, type VNode, +} from "./fs"; +import { compilePatterns, globMatch, spend, type Matcher } from "./regex"; +import type { Cmd, Ctx, Proc } from "./model"; + +const cmp = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0); + +export function toLines(text: string): string[] { + if (text === "") return []; + const parts = text.split("\n"); + if (parts[parts.length - 1] === "") parts.pop(); + return parts; +} +const fromLines = (lines: string[]): string => (lines.length ? lines.join("\n") + "\n" : ""); + +// ---------------------------------------------------------------- helpers + +type OptSpec = { bool?: string; val?: string; long?: Record; numeric?: boolean; stop?: boolean }; +type Opts = { f: Set; v: Map; rest: string[]; num: string | null }; + +function parseOpts(c: Ctx, name: string, spec: OptSpec): Opts | null { + const o: Opts = { f: new Set(), v: new Map(), rest: [], num: null }; + const bool = spec.bool ?? ""; + const val = spec.val ?? ""; + const args = c.args; + const bad = (msg: string): null => { + c.err(`${name}: ${msg}`); + c.err(`Try 'man ${name}' to see how it works.`); + return null; + }; + const addVal = (k: string, v: string) => o.v.set(k, [...(o.v.get(k) ?? []), v]); + let done = false; + for (let i = 0; i < args.length; i++) { + const a = args[i]!; + if (done || a === "-" || !a.startsWith("-")) { + o.rest.push(a); + if (spec.stop) done = true; + continue; + } + if (a === "--") { + done = true; + continue; + } + if (a.startsWith("--")) { + const eq = a.indexOf("="); + const long = eq < 0 ? a.slice(2) : a.slice(2, eq); + const letter = spec.long?.[long]; + if (!letter) return bad(`unrecognized option '--${long}'`); + if (val.includes(letter)) { + if (eq >= 0) addVal(letter, a.slice(eq + 1)); + else if (i + 1 < args.length) addVal(letter, args[++i]!); + else return bad(`option '--${long}' requires an argument`); + } else o.f.add(letter); + continue; + } + for (let j = 1; j < a.length; j++) { + const ch = a[j]!; + if (bool.includes(ch)) o.f.add(ch); + else if (val.includes(ch)) { + const rest = a.slice(j + 1); + if (rest) addVal(ch, rest); + else if (i + 1 < args.length) addVal(ch, args[++i]!); + else return bad(`option requires an argument -- '${ch}'`); + break; + } else if (spec.numeric && ch >= "0" && ch <= "9") { + o.num = (o.num ?? "") + ch; + } else return bad(`invalid option -- '${ch}'`); + } + } + return o; +} + +function absOf(c: Ctx, path: string): string { + return normalizePath(c.st.cwd, path, c.st.env.HOME ?? "/"); +} + +/** Read a file for a command, printing the usual error when it cannot be read. */ +function readText(c: Ctx, name: string, path: string): string | null { + const res = c.st.fs.walk(absOf(c, path), c.st.user); + if (!res.node) { + c.err(`${name}: ${path}: ${ERR_TEXT[res.err ?? "ENOENT"]}`); + return null; + } + if (res.node.kind === "dir") { + c.err(`${name}: ${path}: Is a directory`); + return null; + } + if (!can(c.st.user, res.node, 4)) { + c.err(`${name}: ${path}: Permission denied`); + return null; + } + return res.node.content; +} + +/** Inputs for a filter command: the named files, or standard input. */ +function inputs(c: Ctx, name: string, files: string[]): Array<{ name: string; text: string }> | null { + if (files.length === 0) { + if (c.stdin === null) { + c.err(`${name}: no input. Give a file name or use a pipe, like: cat file | ${name}`); + return null; + } + return [{ name: "-", text: c.stdin }]; + } + const out: Array<{ name: string; text: string }> = []; + let ok = true; + for (const f of files) { + if (f === "-" && c.stdin !== null) { + out.push({ name: "-", text: c.stdin }); + continue; + } + const text = readText(c, name, f); + if (text === null) ok = false; + else out.push({ name: f, text }); + } + return ok || out.length > 0 ? out : null; +} + +const childList = (node: VNode): VNode[] => [...node.children.values()].sort((a, b) => cmp(a.name, b.name)); +const isHidden = (name: string) => name.startsWith("."); +const nlink = (n: VNode) => (n.kind === "dir" ? 2 + [...n.children.values()].filter((x) => x.kind === "dir").length : 1); + +// ---------------------------------------------------------------- navigation and listing + +const pwd: Cmd = (c) => { + c.out(c.st.cwd + "\n"); + return 0; +}; + +const cd: Cmd = (c) => { + if (c.args.length > 1) { + c.err("bash: cd: too many arguments"); + return 1; + } + let target = c.args[0] ?? c.st.env.HOME ?? "/"; + let show = false; + if (target === "-") { + target = c.st.oldpwd; + show = true; + } + const abs = absOf(c, target); + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + c.err(`bash: cd: ${c.args[0] ?? target}: ${ERR_TEXT[res.err ?? "ENOENT"]}`); + return 1; + } + if (res.node.kind !== "dir") { + c.err(`bash: cd: ${c.args[0]}: Not a directory`); + return 1; + } + if (!can(c.st.user, res.node, 1)) { + c.err(`bash: cd: ${c.args[0]}: Permission denied`); + return 1; + } + c.st.oldpwd = c.st.cwd; + c.st.cwd = abs; + c.st.env.PWD = abs; + c.st.env.OLDPWD = c.st.oldpwd; + if (show) c.out(abs + "\n"); + return 0; +}; + +type Ent = { name: string; node: VNode }; + +const ls: Cmd = (c) => { + const o = parseOpts(c, "ls", { + bool: "lahARSrtd1", + long: { all: "a", "almost-all": "A", "human-readable": "h", recursive: "R", reverse: "r", directory: "d" }, + }); + if (!o) return 2; + const long = o.f.has("l"); + const human = o.f.has("h"); + const now = c.st.fs.now; + let code = 0; + + const sortEnts = (ents: Ent[]) => { + ents.sort((a, b) => { + if (o.f.has("S")) return sizeOf(b.node) - sizeOf(a.node) || cmp(a.name, b.name); + if (o.f.has("t")) return b.node.mtime - a.node.mtime || cmp(a.name, b.name); + return cmp(a.name, b.name); + }); + if (o.f.has("r")) ents.reverse(); + }; + + const render = (ents: Ent[], withTotal: boolean): string => { + if (!long) { + if (c.tty && !o.f.has("1")) return ents.length ? ents.map((e) => e.name).join(" ") + "\n" : ""; + return ents.map((e) => e.name + "\n").join(""); + } + const size = (n: VNode) => (human ? humanSize(sizeOf(n)) : String(sizeOf(n))); + const rows = ents.map((e) => [modeString(e.node), String(nlink(e.node)), e.node.owner, e.node.group, size(e.node), formatTime(e.node.mtime, now), e.name]); + const w = [1, 2, 3, 4].map((k) => Math.max(0, ...rows.map((r) => r[k]!.length))); + let text = ""; + if (withTotal) { + const kb = ents.reduce((sum, e) => sum + (e.node.kind === "dir" ? 4 : Math.ceil(sizeOf(e.node) / BLOCK) * 4), 0); + text += `total ${human ? humanSize(kb * 1024) : kb}\n`; + } + for (const r of rows) text += `${r[0]} ${r[1]!.padStart(w[0]!)} ${r[2]!.padEnd(w[1]!)} ${r[3]!.padEnd(w[2]!)} ${r[4]!.padStart(w[3]!)} ${r[5]} ${r[6]}\n`; + return text; + }; + + const sections: string[] = []; + const listDir = (display: string, node: VNode, abs: string, header: boolean) => { + if (!can(c.st.user, node, 4)) { + c.err(`ls: cannot open directory '${display}': Permission denied`); + code = 2; + return; + } + let ents: Ent[] = [...node.children.values()].map((n) => ({ name: n.name, node: n })); + if (!o.f.has("a") && !o.f.has("A")) ents = ents.filter((e) => !isHidden(e.name)); + if (o.f.has("a")) { + const parent = c.st.fs.peek(dirName(abs)) ?? node; + ents.push({ name: ".", node }, { name: "..", node: parent }); + } + sortEnts(ents); + sections.push((header ? `${display}:\n` : "") + render(ents, true)); + if (o.f.has("R")) { + for (const child of childList(node)) { + if (child.kind === "dir" && (!isHidden(child.name) || o.f.has("a") || o.f.has("A"))) { + listDir(display === "/" ? "/" + child.name : `${display}/${child.name}`, child, joinPath(abs, child.name), true); + } + } + } + }; + + const files: Ent[] = []; + const dirs: Array<{ display: string; node: VNode; abs: string }> = []; + for (const t of o.rest.length ? o.rest : ["."]) { + const abs = absOf(c, t); + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + c.err(`ls: cannot access '${t}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 2; + } else if (res.node.kind === "dir" && !o.f.has("d")) dirs.push({ display: t, node: res.node, abs }); + else files.push({ name: t, node: res.node }); + } + if (files.length) { + sortEnts(files); + sections.push(render(files, false)); + } + const header = dirs.length + files.length > 1 || o.f.has("R"); + dirs.sort((a, b) => cmp(a.display, b.display)); + for (const d of dirs) listDir(d.display, d.node, d.abs, header && (dirs.length > 1 || files.length > 0 || o.f.has("R"))); + c.out(sections.join("\n")); + return code; +}; + +// ---------------------------------------------------------------- reading files + +const cat: Cmd = (c) => { + const o = parseOpts(c, "cat", { bool: "nAbs", long: { number: "n" } }); + if (!o) return 1; + const parts = inputs(c, "cat", o.rest); + if (!parts) return 1; + let code = o.rest.length > parts.length ? 1 : 0; + let n = 0; + for (const p of parts) { + if (o.f.has("n")) { + const lines = toLines(p.text); + c.out(lines.map((l) => `${String(++n).padStart(6)}\t${l}\n`).join("")); + } else c.out(p.text); + } + if (parts.length === 0) code = 1; + return code; +}; + +function headTail(c: Ctx, name: "head" | "tail"): number { + const o = parseOpts(c, name, { bool: "qvf", val: "nc", numeric: true, long: { lines: "n", bytes: "c" } }); + if (!o) return 1; + const raw = o.v.get("n")?.[0] ?? o.num ?? "10"; + const bytes = o.v.get("c")?.[0]; + if (!/^[+-]?\d+$/.test(bytes ?? raw)) { + c.err(`${name}: invalid number of ${bytes !== undefined ? "bytes" : "lines"}: '${bytes ?? raw}'`); + return 1; + } + const parts = inputs(c, name, o.rest); + if (!parts) return 1; + const headers = parts.length > 1 && !o.f.has("q"); + parts.forEach((p, i) => { + if (headers) c.out(`${i ? "\n" : ""}==> ${p.name === "-" ? "standard input" : p.name} <==\n`); + if (bytes !== undefined) { + const n = Math.abs(Number(bytes)); + c.out(name === "head" ? p.text.slice(0, n) : n === 0 ? "" : p.text.slice(-n)); + return; + } + const lines = toLines(p.text); + const n = Math.abs(Number(raw)); + if (name === "head") c.out(fromLines(raw.startsWith("-") ? lines.slice(0, Math.max(0, lines.length - n)) : lines.slice(0, n))); + else c.out(fromLines(raw.startsWith("+") ? lines.slice(Math.max(0, n - 1)) : n === 0 ? [] : lines.slice(-n))); + }); + return 0; +} + +// ---------------------------------------------------------------- searching + + +function grepCmd(c: Ctx, forceRecursive: boolean): number { + const o = parseOpts(c, "grep", { + bool: "ivnchrREFlowxqsHaIT", + val: "e", + long: { + "ignore-case": "i", "invert-match": "v", "line-number": "n", count: "c", recursive: "r", "dereference-recursive": "R", + "extended-regexp": "E", "fixed-strings": "F", "files-with-matches": "l", "only-matching": "o", "word-regexp": "w", + "line-regexp": "x", "no-filename": "h", "with-filename": "H", quiet: "q", silent: "q", "no-messages": "s", regexp: "e", + }, + }); + if (!o) return 2; + const rest = [...o.rest]; + let patterns = (o.v.get("e") ?? []).flatMap((p) => p.split("\n")); + if (patterns.length === 0) { + const p = rest.shift(); + if (p === undefined) { + c.err("Usage: grep [OPTION]... PATTERNS [FILE]..."); + return 2; + } + patterns = p.split("\n"); + } + const recursive = forceRecursive || o.f.has("r") || o.f.has("R"); + const matcher = compilePatterns(patterns, { + ere: o.f.has("E"), ignoreCase: o.f.has("i"), fixed: o.f.has("F"), word: o.f.has("w"), line: o.f.has("x"), + }); + if ("error" in matcher) { + c.err(`grep: ${matcher.error}`); + return 2; + } + const invert = o.f.has("v"); + const count = o.f.has("c"); + const listFiles = o.f.has("l"); + const quiet = o.f.has("q"); + const only = o.f.has("o"); + let files = rest; + let useStdin = false; + if (files.length === 0) { + if (recursive) files = ["."]; + else useStdin = true; + } + const showName = o.f.has("H") || (!o.f.has("h") && (files.length > 1 || recursive)); + const dotFree = recursive && rest.length === 0; + let matchedAny = false; + let errored = false; + + const scan = (label: string, text: string): void => { + let hits = 0; + const lines = toLines(text); + const prefix = (n: number) => (showName ? label + ":" : "") + (o.f.has("n") ? n + ":" : ""); + for (let i = 0; i < lines.length; i++) { + const line = lines[i]!; + spend(1); + const m = (matcher as Matcher).test(line); + if (m === invert) continue; + hits++; + matchedAny = true; + if (quiet) return; + if (listFiles) break; + if (count) continue; + if (only && !invert) { + let from = 0; + while (from <= line.length) { + const r = (matcher as Matcher).find(line, from); + if (!r) break; + if (r[1] > r[0]) c.out(prefix(i + 1) + line.slice(r[0], r[1]) + "\n"); + from = r[1] > r[0] ? r[1] : r[1] + 1; + } + } else c.out(prefix(i + 1) + line + "\n"); + } + if (listFiles && hits > 0) c.out(label + "\n"); + else if (count) c.out((showName ? label + ":" : "") + hits + "\n"); + }; + + const walkFiles = (abs: string, display: string, node: VNode): void => { + if (node.kind === "file") { + if (!can(c.st.user, node, 4)) { + if (!o.f.has("s")) c.err(`grep: ${display}: Permission denied`); + errored = true; + return; + } + scan(display, node.content); + return; + } + if (!recursive) { + if (!o.f.has("s")) c.err(`grep: ${display}: Is a directory`); + errored = true; + return; + } + if (!can(c.st.user, node, 4) || !can(c.st.user, node, 1)) { + if (!o.f.has("s")) c.err(`grep: ${display}: Permission denied`); + errored = true; + return; + } + for (const child of childList(node)) { + walkFiles(joinPath(abs, child.name), display === "." && dotFree ? child.name : display === "/" ? "/" + child.name : `${display}/${child.name}`, child); + } + }; + + if (useStdin) { + if (c.stdin === null) { + c.err("grep: no input. Give a file name or use a pipe, like: cat file | grep word"); + return 2; + } + scan("(standard input)", c.stdin); + } else { + for (const f of files) { + const abs = absOf(c, f); + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + if (!o.f.has("s")) c.err(`grep: ${f}: ${ERR_TEXT[res.err ?? "ENOENT"]}`); + errored = true; + continue; + } + walkFiles(abs, f, res.node); + } + } + return matchedAny ? 0 : errored ? 2 : 1; +} + +class FindError extends Error {} + +type FindItem = { node: VNode; abs: string; display: string; depth: number }; + +const find: Cmd = (c) => { + const args = c.args; + let i = 0; + const starts: string[] = []; + while (i < args.length && !args[i]!.startsWith("-") && args[i] !== "!" && args[i] !== "(") starts.push(args[i++]!); + if (starts.length === 0) starts.push("."); + const tokens = args.slice(i); + let maxDepth = Infinity; + let minDepth = 0; + let hasAction = false; + let hasDelete = false; + let code = 0; + const now = c.st.fs.now; + let p = 0; + + const need = (name: string): string => { + const v = tokens[p++]; + if (v === undefined) throw new FindError(`missing argument to '${name}'`); + return v; + }; + + const orExpr = (): ((f: FindItem) => boolean) => { + let left = andExpr(); + while (tokens[p] === "-o" || tokens[p] === "-or") { + p++; + const l = left; + const r = andExpr(); + left = (f) => l(f) || r(f); + } + return left; + }; + const andExpr = (): ((f: FindItem) => boolean) => { + let left = unary(); + while (p < tokens.length && tokens[p] !== "-o" && tokens[p] !== "-or" && tokens[p] !== ")") { + if (tokens[p] === "-a" || tokens[p] === "-and") p++; + const l = left; + const r = unary(); + left = (f) => l(f) && r(f); + } + return left; + }; + const unary = (): ((f: FindItem) => boolean) => { + const t = tokens[p]; + if (t === "!" || t === "-not") { + p++; + const inner = unary(); + return (f) => !inner(f); + } + if (t === "(") { + p++; + const inner = orExpr(); + if (tokens[p] !== ")") throw new FindError("missing closing ')'"); + p++; + return inner; + } + return primary(); + }; + + const numTest = (spec: string, value: number): boolean => { + const m = /^([+-]?)(\d+)$/.exec(spec); + if (!m) throw new FindError(`invalid argument '${spec}'`); + const n = Number(m[2]); + return m[1] === "+" ? value > n : m[1] === "-" ? value < n : value === n; + }; + + const primary = (): ((f: FindItem) => boolean) => { + const t = tokens[p++]; + switch (t) { + case "-name": { const pat = need(t); return (f) => globMatch(pat, baseName(f.display) || f.display); } + case "-iname": { const pat = need(t); return (f) => globMatch(pat, baseName(f.display) || f.display, true); } + case "-path": { const pat = need(t); return (f) => globMatch(pat, f.display); } + case "-type": { + const k = need(t); + if (k !== "f" && k !== "d") throw new FindError(`Unknown argument to -type: ${k}`); + return (f) => (k === "f" ? f.node.kind === "file" : f.node.kind === "dir"); + } + case "-size": { + const spec = need(t); + const m = /^([+-]?)(\d+)([cwbkMG]?)$/.exec(spec); + if (!m) throw new FindError(`invalid argument '${spec}' to '-size'`); + const unit = { c: 1, w: 2, b: 512, "": 512, k: 1024, M: 1048576, G: 1073741824 }[m[3] as "c"]!; + const n = Number(m[2]); + return (f) => { + const units = Math.ceil(sizeOf(f.node) / unit); + return m[1] === "+" ? units > n : m[1] === "-" ? units < n : units === n; + }; + } + case "-mtime": { const spec = need(t); numTest(spec, 0); return (f) => numTest(spec, Math.floor((now - f.node.mtime) / DAY)); } + case "-mmin": { const spec = need(t); numTest(spec, 0); return (f) => numTest(spec, Math.floor((now - f.node.mtime) / 60)); } + case "-user": { const u = need(t); return (f) => f.node.owner === u; } + case "-empty": return (f) => (f.node.kind === "dir" ? f.node.children.size === 0 : sizeOf(f.node) === 0); + case "-maxdepth": { maxDepth = Number(need(t)); if (!Number.isFinite(maxDepth) || maxDepth < 0) throw new FindError("Expected a positive decimal integer argument to -maxdepth"); return () => true; } + case "-mindepth": { minDepth = Number(need(t)); if (!Number.isFinite(minDepth) || minDepth < 0) throw new FindError("Expected a positive decimal integer argument to -mindepth"); return () => true; } + case "-print": hasAction = true; return (f) => (c.out(f.display + "\n"), true); + case "-delete": { + hasAction = true; + hasDelete = true; + return (f) => { + if (f.node.kind === "dir" && f.node.children.size > 0) { + c.err(`find: cannot delete '${f.display}': Directory not empty`); + code = 1; + return false; + } + const e = c.st.fs.remove(f.abs, c.st.user); + if (e) { + c.err(`find: cannot delete '${f.display}': ${ERR_TEXT[e]}`); + code = 1; + return false; + } + return true; + }; + } + case "-exec": { + hasAction = true; + const argv: string[] = []; + for (;;) { + const a = tokens[p++]; + if (a === undefined) throw new FindError("missing argument to '-exec'"); + if (a === ";" || a === "+") break; + argv.push(a); + } + if (argv.length === 0) throw new FindError("missing argument to '-exec'"); + return (f) => { + const r = c.exec(argv.map((a) => a.split("{}").join(f.display)), null); + c.out(r.out); + return r.code === 0; + }; + } + default: + throw new FindError(`unknown predicate '${t}'`); + } + }; + + let expr: (f: FindItem) => boolean; + try { + expr = tokens.length ? orExpr() : () => true; + if (p < tokens.length) throw new FindError(`paths must precede expression: '${tokens[p]}'`); + } catch (error) { + if (error instanceof FindError) { + c.err(`find: ${error.message}`); + return 1; + } + throw error; + } + const finalExpr = hasAction ? expr : (f: FindItem) => (expr(f) ? (c.out(f.display + "\n"), true) : false); + + const visit = (item: FindItem): void => { + spend(1); + const { node } = item; + const inDepth = item.depth >= minDepth; + if (!hasDelete && inDepth) finalExpr(item); + if (node.kind === "dir" && item.depth < maxDepth) { + if (!can(c.st.user, node, 4) || !can(c.st.user, node, 1)) { + c.err(`find: '${item.display}': Permission denied`); + code = 1; + } else { + for (const child of childList(node)) { + visit({ + node: child, + abs: joinPath(item.abs, child.name), + display: item.display.endsWith("/") ? item.display + child.name : item.display + "/" + child.name, + depth: item.depth + 1, + }); + } + } + } + if (hasDelete && inDepth) finalExpr(item); + }; + + for (const s of starts) { + const abs = absOf(c, s); + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + c.err(`find: '${s}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + visit({ node: res.node, abs, display: s, depth: 0 }); + } + return code; +}; + +// ---------------------------------------------------------------- text filters + +function wc(c: Ctx): number { + const o = parseOpts(c, "wc", { bool: "lwcm", long: { lines: "l", words: "w", bytes: "c", chars: "m" } }); + if (!o) return 1; + const parts = inputs(c, "wc", o.rest); + if (!parts) return 1; + let showL = o.f.has("l"); + let showW = o.f.has("w"); + let showC = o.f.has("c") || o.f.has("m"); + if (!showL && !showW && !showC) showL = showW = showC = true; + const rows = parts.map((p) => ({ + name: p.name === "-" && o.rest.length === 0 ? "" : p.name, + l: (p.text.match(/\n/g) ?? []).length, + w: p.text.split(/\s+/).filter(Boolean).length, + c: p.text.length, + })); + if (rows.length > 1) rows.push({ name: "total", l: rows.reduce((a, r) => a + r.l, 0), w: rows.reduce((a, r) => a + r.w, 0), c: rows.reduce((a, r) => a + r.c, 0) }); + const shown = [showL, showW, showC].filter(Boolean).length; + const width = shown === 1 && rows.length === 1 ? 0 : o.rest.length === 0 ? 7 : Math.max(...rows.map((r) => String(r.c).length)); + for (const r of rows) { + const cols: string[] = []; + if (showL) cols.push(String(r.l).padStart(width)); + if (showW) cols.push(String(r.w).padStart(width)); + if (showC) cols.push(String(r.c).padStart(width)); + c.out(cols.join(" ") + (r.name ? " " + r.name : "") + "\n"); + } + return 0; +} + +function numberOf(text: string): number { + const m = /^\s*([+-]?\d*\.?\d+)/.exec(text); + return m ? Number(m[1]) : 0; +} + +function humanNumber(text: string): number { + const m = /^\s*(\d*\.?\d+)\s*([KMGT]?)/i.exec(text); + if (!m) return 0; + return Number(m[1]) * ({ "": 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3, T: 1024 ** 4 }[m[2]!.toUpperCase() as ""] ?? 1); +} + +function sort(c: Ctx): number { + const o = parseOpts(c, "sort", { bool: "rnuhfsb", val: "kt", long: { reverse: "r", "numeric-sort": "n", unique: "u", "human-numeric-sort": "h", "ignore-case": "f" } }); + if (!o) return 2; + const parts = inputs(c, "sort", o.rest); + if (!parts) return 2; + const lines = parts.flatMap((p) => toLines(p.text)); + const sep = o.v.get("t")?.[0]; + const keySpec = o.v.get("k")?.[0]; + let km: RegExpExecArray | null = null; + if (keySpec !== undefined) { + km = /^(\d+)(?:\.\d+)?[bnrhf]*(?:,(\d+)(?:\.\d+)?)?([bnrhf]*)$/.exec(keySpec); + if (!km) { + c.err(`sort: invalid field specification '${keySpec}'`); + return 2; + } + } + const mods = (km ? keySpec!.replace(/[\d.,]/g, "") : "") + ""; + const numeric = o.f.has("n") || mods.includes("n"); + const human = o.f.has("h") || mods.includes("h"); + const fold = o.f.has("f") || mods.includes("f"); + const keyOf = (line: string): string => { + if (!km) return line; + const fields = sep ? line.split(sep) : line.trim().split(/\s+/); + const from = Number(km[1]) - 1; + const to = km[2] ? Number(km[2]) : from + 1; + return fields.slice(from, to).join(sep ?? " "); + }; + const keyed = lines.map((line) => ({ line, key: keyOf(line) })); + keyed.sort((a, b) => { + let r = 0; + if (human) r = humanNumber(a.key) - humanNumber(b.key); + else if (numeric) r = numberOf(a.key) - numberOf(b.key); + else r = fold ? cmp(a.key.toLowerCase(), b.key.toLowerCase()) : cmp(a.key, b.key); + if (r === 0 && !o.f.has("s")) r = cmp(a.line, b.line); + return o.f.has("r") || mods.includes("r") ? -r : r; + }); + let out = keyed.map((k) => k.line); + if (o.f.has("u")) out = out.filter((l, i) => i === 0 || l !== out[i - 1]); + c.out(fromLines(out)); + return 0; +} + +function uniq(c: Ctx): number { + const o = parseOpts(c, "uniq", { bool: "cduiD", long: { count: "c", repeated: "d", unique: "u", "ignore-case": "i" } }); + if (!o) return 1; + const parts = inputs(c, "uniq", o.rest.slice(0, 1)); + if (!parts) return 1; + const lines = toLines(parts[0]!.text); + const same = (a: string, b: string) => (o.f.has("i") ? a.toLowerCase() === b.toLowerCase() : a === b); + const groups: Array<{ line: string; n: number }> = []; + for (const line of lines) { + const last = groups[groups.length - 1]; + if (last && same(last.line, line)) last.n++; + else groups.push({ line, n: 1 }); + } + for (const g of groups) { + if (o.f.has("d") && g.n < 2) continue; + if (o.f.has("u") && g.n > 1) continue; + c.out((o.f.has("c") ? String(g.n).padStart(7) + " " : "") + g.line + "\n"); + } + return 0; +} + +function parseRanges(spec: string): Array<[number, number]> | null { + const out: Array<[number, number]> = []; + for (const part of spec.split(",")) { + const m = /^(\d*)(-?)(\d*)$/.exec(part); + if (!m || part === "" || part === "-") return null; + const a = m[1] === "" ? 1 : Number(m[1]); + const b = m[2] === "" ? a : m[3] === "" ? Infinity : Number(m[3]); + if (a < 1) return null; + out.push([a, b]); + } + return out; +} + +function cut(c: Ctx): number { + const o = parseOpts(c, "cut", { bool: "s", val: "dfc", long: { delimiter: "d", fields: "f", characters: "c", "only-delimited": "s" } }); + if (!o) return 1; + const fSpec = o.v.get("f")?.[0]; + const cSpec = o.v.get("c")?.[0]; + if (fSpec === undefined && cSpec === undefined) { + c.err("cut: you must specify a list of bytes, characters, or fields"); + return 1; + } + const ranges = parseRanges((fSpec ?? cSpec)!); + if (!ranges) { + c.err("cut: invalid field range"); + return 1; + } + const delim = o.v.get("d")?.[0] ?? "\t"; + if (delim.length !== 1) { + c.err("cut: the delimiter must be a single character"); + return 1; + } + const parts = inputs(c, "cut", o.rest); + if (!parts) return 1; + const pick = (idx: number) => ranges.some(([a, b]) => idx >= a && idx <= b); + for (const p of parts) { + for (const line of toLines(p.text)) { + if (fSpec === undefined) c.out([...line].filter((_, i) => pick(i + 1)).join("") + "\n"); + else if (!line.includes(delim)) { + if (!o.f.has("s")) c.out(line + "\n"); + } else c.out(line.split(delim).filter((_, i) => pick(i + 1)).join(delim) + "\n"); + } + } + return 0; +} + +function awk(c: Ctx): number { + const o = parseOpts(c, "awk", { val: "F", stop: false }); + if (!o) return 1; + const prog = o.rest[0]; + const m = prog === undefined ? null : /^\s*\{\s*print\b([\s\S]*)\}\s*$/.exec(prog); + if (!m) { + c.err("awk: this practice shell only runs programs like '{print $1}' or '{print $1, $3}'"); + return 1; + } + // The print list: items separated by commas (a space between them) or written side by side. + const items: Array<{ kind: "field"; n: number | "NF" } | { kind: "nr" } | { kind: "nf" } | { kind: "str"; v: string } | { kind: "comma" }> = []; + const src = m[1]!.trim(); + const re = /\$(\d+|NF)|"((?:[^"\\]|\\.)*)"|\bNR\b|\bNF\b|(,)/g; + let last = 0; + let mm: RegExpExecArray | null; + while ((mm = re.exec(src))) { + if (src.slice(last, mm.index).trim() !== "") { + c.err("awk: this practice shell only runs programs like '{print $1}' or '{print $1, $3}'"); + return 1; + } + last = re.lastIndex; + if (mm[1] !== undefined) items.push({ kind: "field", n: mm[1] === "NF" ? "NF" : Number(mm[1]) }); + else if (mm[2] !== undefined) items.push({ kind: "str", v: mm[2].replace(/\\n/g, "\n").replace(/\\t/g, "\t").replace(/\\(.)/g, "$1") }); + else if (mm[3] !== undefined) items.push({ kind: "comma" }); + else items.push(mm[0] === "NR" ? { kind: "nr" } : { kind: "nf" }); + } + if (src.slice(last).trim() !== "") { + c.err("awk: this practice shell only runs programs like '{print $1}' or '{print $1, $3}'"); + return 1; + } + const sep = o.v.get("F")?.[0]; + const parts = inputs(c, "awk", o.rest.slice(1)); + if (!parts) return 1; + let nr = 0; + for (const p of parts) { + for (const line of toLines(p.text)) { + nr++; + const fields = sep === undefined || sep === " " ? line.trim().split(/\s+/).filter(Boolean) : line.split(sep.length === 1 ? sep : new RegExp(sep.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))); + const field = (n: number | "NF") => (n === "NF" ? fields[fields.length - 1] ?? "" : n === 0 ? line : fields[n - 1] ?? ""); + if (items.length === 0) { + c.out(line + "\n"); + continue; + } + let outLine = ""; + for (const it of items) { + if (it.kind === "comma") outLine += " "; + else if (it.kind === "field") outLine += field(it.n); + else if (it.kind === "str") outLine += it.v; + else if (it.kind === "nr") outLine += nr; + else outLine += fields.length; + } + c.out(outLine + "\n"); + } + } + return 0; +} + +type SedCmd = { from?: number; to?: number; re?: Matcher; kind: "s" | "d" | "p"; sub?: { m: Matcher; repl: string; global: boolean } }; + +function sed(c: Ctx): number { + const o = parseOpts(c, "sed", { bool: "inErE", val: "e", long: { quiet: "n", silent: "n", "in-place": "i", "regexp-extended": "E" } }); + if (!o) return 1; + const rest = [...o.rest]; + const scripts = o.v.get("e") ?? []; + if (scripts.length === 0) { + const s = rest.shift(); + if (s === undefined) { + c.err("Usage: sed [OPTION]... {script} [input-file]..."); + return 1; + } + scripts.push(s); + } + const ere = o.f.has("E") || o.f.has("r"); + const cmds: SedCmd[] = []; + const bad = (msg: string): number => { + c.err(`sed: ${msg}`); + return 1; + }; + for (const script of scripts.flatMap((s) => s.split("\n"))) { + const text = script.trim(); + if (!text) continue; + let i = 0; + const cmd: SedCmd = { kind: "p" }; + const num = /^(\d+)(?:,(\d+))?/.exec(text); + if (num) { + cmd.from = Number(num[1]); + cmd.to = num[2] ? Number(num[2]) : cmd.from; + i = num[0].length; + } else if (text[0] === "/") { + const end = text.indexOf("/", 1); + if (end < 0) return bad("unterminated address regex"); + const m = compilePatterns([text.slice(1, end)], { ere, ignoreCase: false }); + if ("error" in m) return bad(m.error); + cmd.re = m; + i = end + 1; + } + const k = text[i]; + if (k === "d" || k === "p") { + cmd.kind = k; + cmds.push(cmd); + } else if (k === "s") { + const delim = text[i + 1]; + if (!delim) return bad("unterminated `s' command"); + const fields: string[] = []; + let cur = ""; + let j = i + 2; + for (; j < text.length && fields.length < 2; j++) { + const ch = text[j]!; + if (ch === "\\" && j + 1 < text.length) { + if (text[j + 1] === delim) cur += delim; + else cur += ch + text[j + 1]; + j++; + } else if (ch === delim) { + fields.push(cur); + cur = ""; + } else cur += ch; + } + if (fields.length < 2) return bad("unterminated `s' command"); + const flags = text.slice(j); + const m = compilePatterns([fields[0]!], { ere, ignoreCase: flags.includes("i") }); + if ("error" in m) return bad(m.error); + cmd.kind = "s"; + cmd.sub = { m, repl: fields[1]!, global: flags.includes("g") }; + cmds.push(cmd); + } else return bad(`unknown command: '${k ?? ""}' (this practice shell knows s, d and p)`); + } + const apply = (text: string): string => { + let n = 0; + const out: string[] = []; + for (let line of toLines(text)) { + n++; + let deleted = false; + let printed = false; + for (const cm of cmds) { + const hit = cm.from !== undefined ? n >= cm.from && n <= (cm.to ?? cm.from) : cm.re ? cm.re.test(line) : true; + if (!hit) continue; + if (cm.kind === "d") { + deleted = true; + break; + } + if (cm.kind === "p") { + out.push(line); + printed = true; + } else if (cm.sub) { + let result = ""; + let pos = 0; + let from = 0; + for (;;) { + spend(1); + const r = cm.sub.m.find(line, from); + if (!r) break; + result += line.slice(pos, r[0]) + cm.sub.repl.replace(/\\(.)|&/g, (all, esc?: string) => (all === "&" ? line.slice(r[0], r[1]) : esc === "n" ? "\n" : esc ?? "")); + pos = r[1]; + from = r[1] > r[0] ? r[1] : r[1] + 1; + if (r[1] === r[0] && r[0] < line.length) { + result += line[r[0]]; + pos = r[0] + 1; + } + if (!cm.sub.global || from > line.length) break; + } + line = result + line.slice(pos); + } + } + if (!deleted && !o.f.has("n")) out.push(line); + void printed; + } + return fromLines(out); + }; + if (o.f.has("i")) { + if (rest.length === 0) return bad("no input files"); + let code = 0; + for (const f of rest) { + const text = readText(c, "sed", f); + if (text === null) { + code = 1; + continue; + } + const e = c.st.fs.writeFile(absOf(c, f), c.st.user, apply(text), false); + if (e) { + c.err(`sed: couldn't open temporary file for '${f}': ${ERR_TEXT[e]}`); + code = 1; + } + } + return code; + } + const parts = inputs(c, "sed", rest); + if (!parts) return 1; + for (const p of parts) c.out(apply(p.text)); + return 0; +} + +// ---------------------------------------------------------------- changing files + +function echo(c: Ctx): number { + let args = c.args; + let newline = true; + let escapes = false; + while (args[0] && /^-[neE]+$/.test(args[0])) { + if (args[0].includes("n")) newline = false; + if (args[0].includes("e")) escapes = true; + if (args[0].includes("E")) escapes = false; + args = args.slice(1); + } + let text = args.join(" "); + if (escapes) text = text.replace(/\\(n|t|\\)/g, (_, k: string) => (k === "n" ? "\n" : k === "t" ? "\t" : "\\")); + c.out(text + (newline ? "\n" : "")); + return 0; +} + +function touch(c: Ctx): number { + const o = parseOpts(c, "touch", { bool: "c" }); + if (!o) return 1; + if (o.rest.length === 0) { + c.err("touch: missing file operand"); + return 1; + } + let code = 0; + for (const f of o.rest) { + const abs = absOf(c, f); + const res = c.st.fs.walk(abs, c.st.user); + if (res.node) { + if (!can(c.st.user, res.node, 2) && res.node.owner !== c.st.user.name) { + c.err(`touch: cannot touch '${f}': Permission denied`); + code = 1; + } else res.node.mtime = c.st.fs.now; + continue; + } + if (o.f.has("c")) continue; + const e = res.err === "ENOENT" ? c.st.fs.writeFile(abs, c.st.user, "", false) : res.err; + if (e) { + c.err(`touch: cannot touch '${f}': ${ERR_TEXT[e]}`); + code = 1; + } + } + return code; +} + +function mkdir(c: Ctx): number { + const o = parseOpts(c, "mkdir", { bool: "pv", long: { parents: "p" } }); + if (!o) return 1; + if (o.rest.length === 0) { + c.err("mkdir: missing operand"); + return 1; + } + let code = 0; + for (const f of o.rest) { + const abs = absOf(c, f); + if (o.f.has("p")) { + let cur = ""; + let failed: Err | null = null; + for (const part of abs.split("/").filter(Boolean)) { + cur += "/" + part; + const res = c.st.fs.walk(cur, c.st.user); + if (res.node) { + if (res.node.kind !== "dir") failed = "ENOTDIR"; + continue; + } + if (res.err !== "ENOENT") { + failed = res.err; + break; + } + failed = c.st.fs.mkdir(cur, c.st.user); + if (failed) break; + } + if (failed) { + c.err(`mkdir: cannot create directory '${f}': ${ERR_TEXT[failed]}`); + code = 1; + } + continue; + } + const e = c.st.fs.mkdir(abs, c.st.user); + if (e) { + c.err(`mkdir: cannot create directory '${f}': ${ERR_TEXT[e]}`); + code = 1; + } + } + return code; +} + +function rm(c: Ctx): number { + const o = parseOpts(c, "rm", { bool: "rRfvid", long: { recursive: "r", force: "f", verbose: "v" } }); + if (!o) return 1; + if (o.rest.length === 0) { + if (!o.f.has("f")) c.err("rm: missing operand"); + return o.f.has("f") ? 0 : 1; + } + const recursive = o.f.has("r") || o.f.has("R"); + let code = 0; + for (const f of o.rest) { + const abs = absOf(c, f); + if (baseName(f) === "." || baseName(f) === "..") { + c.err(`rm: refusing to remove '.' or '..' directory: skipping '${f}'`); + code = 1; + continue; + } + if (abs === "/") { + c.err("rm: it is dangerous to operate recursively on '/'"); + c.err("rm: use --no-preserve-root to override this failsafe"); + code = 1; + continue; + } + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + if (!(o.f.has("f") && res.err === "ENOENT")) { + c.err(`rm: cannot remove '${f}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + } + continue; + } + if (res.node.kind === "dir" && !recursive) { + c.err(`rm: cannot remove '${f}': Is a directory`); + code = 1; + continue; + } + const e = c.st.fs.remove(abs, c.st.user); + if (e) { + if (!o.f.has("f")) c.err(`rm: cannot remove '${f}': ${ERR_TEXT[e]}`); + code = 1; + } else if (o.f.has("v")) c.out(`removed '${f}'\n`); + if (!e && (abs === c.st.cwd || c.st.cwd.startsWith(abs + "/"))) c.st.cwd = dirName(abs); + } + return code; +} + +/** For cp and mv: where does each source go? */ +function destinations(c: Ctx, name: string, srcs: string[], dest: string): Array<{ src: string; target: string; display: string }> | null { + const dabs = absOf(c, dest); + const res = c.st.fs.walk(dabs, c.st.user); + const isDir = !!res.node && res.node.kind === "dir"; + if (srcs.length > 1 && !isDir) { + c.err(`${name}: target '${dest}' is not a directory`); + return null; + } + return srcs.map((s) => { + const sabs = absOf(c, s); + return isDir + ? { src: s, target: joinPath(dabs, baseName(sabs)), display: dest.endsWith("/") ? dest + baseName(sabs) : dest + "/" + baseName(sabs) } + : { src: s, target: dabs, display: dest }; + }); +} + +function cp(c: Ctx): number { + const o = parseOpts(c, "cp", { bool: "rRapfvin", long: { recursive: "r", verbose: "v", archive: "a" } }); + if (!o) return 1; + if (o.rest.length < 2) { + c.err(o.rest.length === 0 ? "cp: missing file operand" : `cp: missing destination file operand after '${o.rest[0]}'`); + return 1; + } + const dest = o.rest[o.rest.length - 1]!; + const dests = destinations(c, "cp", o.rest.slice(0, -1), dest); + if (!dests) return 1; + const recursive = o.f.has("r") || o.f.has("R") || o.f.has("a"); + let code = 0; + for (const d of dests) { + const sabs = absOf(c, d.src); + const res = c.st.fs.walk(sabs, c.st.user); + if (!res.node) { + c.err(`cp: cannot stat '${d.src}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + if (res.node.kind === "dir" && !recursive) { + c.err(`cp: -r not specified; omitting directory '${d.src}'`); + code = 1; + continue; + } + if (sabs === d.target) { + c.err(`cp: '${d.src}' and '${d.display}' are the same file`); + code = 1; + continue; + } + if (res.node.kind === "dir" && d.target.startsWith(sabs + "/")) { + c.err(`cp: cannot copy a directory, '${d.src}', into itself, '${d.display}'`); + code = 1; + continue; + } + if (res.node.kind === "file" && !can(c.st.user, res.node, 4)) { + c.err(`cp: cannot open '${d.src}' for reading: Permission denied`); + code = 1; + continue; + } + const e = c.st.fs.copy(res.node, d.target, c.st.user); + if (e) { + const what = res.node.kind === "dir" ? "directory" : "regular file"; + c.err(e === "EISDIR" ? `cp: cannot overwrite directory '${d.display}' with non-directory` : `cp: cannot create ${what} '${d.display}': ${ERR_TEXT[e]}`); + code = 1; + } else if (o.f.has("v")) c.out(`'${d.src}' -> '${d.display}'\n`); + } + return code; +} + +function mv(c: Ctx): number { + const o = parseOpts(c, "mv", { bool: "fvin", long: { verbose: "v", force: "f" } }); + if (!o) return 1; + if (o.rest.length < 2) { + c.err(o.rest.length === 0 ? "mv: missing file operand" : `mv: missing destination file operand after '${o.rest[0]}'`); + return 1; + } + const dest = o.rest[o.rest.length - 1]!; + const dests = destinations(c, "mv", o.rest.slice(0, -1), dest); + if (!dests) return 1; + let code = 0; + for (const d of dests) { + const sabs = absOf(c, d.src); + const res = c.st.fs.walk(sabs, c.st.user); + if (!res.node) { + c.err(`mv: cannot stat '${d.src}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + if (sabs === d.target) { + c.err(`mv: '${d.src}' and '${d.display}' are the same file`); + code = 1; + continue; + } + const e = c.st.fs.move(sabs, d.target, c.st.user); + if (e) { + c.err( + e === "EINVAL" + ? `mv: cannot move '${d.src}' to a subdirectory of itself, '${d.display}'` + : e === "EEXIST" + ? `mv: cannot move '${d.src}' to '${d.display}': Directory not empty` + : `mv: cannot move '${d.src}' to '${d.display}': ${ERR_TEXT[e]}`, + ); + code = 1; + } else if (o.f.has("v")) c.out(`renamed '${d.src}' -> '${d.display}'\n`); + if (!e && (sabs === c.st.cwd || c.st.cwd.startsWith(sabs + "/"))) c.st.cwd = dirName(sabs); + } + return code; +} + +function applyMode(spec: string, node: VNode): number | null { + if (/^[0-7]{1,4}$/.test(spec)) return parseInt(spec, 8) & 0o777; + let mode = node.mode; + for (const clause of spec.split(",")) { + const m = /^([ugoa]*)([-+=])([rwxXst]*)$/.exec(clause); + if (!m) return null; + const who = m[1] === "" ? "a" : m[1]!; + let bits = 0; + for (const ch of m[3]!) bits |= ch === "r" ? 4 : ch === "w" ? 2 : ch === "x" ? 1 : ch === "X" && (node.kind === "dir" || (node.mode & 0o111) !== 0) ? 1 : 0; + let mask = 0; + for (const w of who.includes("a") ? "ugo" : who) mask |= (bits << (w === "u" ? 6 : w === "g" ? 3 : 0)); + const clear = (who.includes("a") ? 0o777 : [...who].reduce((a, w) => a | (7 << (w === "u" ? 6 : w === "g" ? 3 : 0)), 0)); + if (m[2] === "+") mode |= mask; + else if (m[2] === "-") mode &= ~mask; + else mode = (mode & ~clear) | mask; + } + return mode & 0o777; +} + +function chmod(c: Ctx): number { + // A mode such as "-x" looks like an option, so take the mode out first. + const args = c.args.filter((a) => a !== "-R" && a !== "-v" && a !== "--recursive"); + const recursive = args.length !== c.args.length && c.args.some((a) => a === "-R" || a === "--recursive"); + if (args.length === 0) { + c.err("chmod: missing operand"); + return 1; + } + const mode = args[0]!; + const files = args.slice(1); + if (files.length === 0) { + c.err(`chmod: missing operand after '${mode}'`); + return 1; + } + let code = 0; + const setNode = (node: VNode, display: string): boolean => { + const next = applyMode(mode, node); + if (next === null) { + c.err(`chmod: invalid mode: '${mode}'`); + c.err("Try 'man chmod' to see how it works."); + return false; + } + if (c.st.user.name !== "root" && node.owner !== c.st.user.name) { + c.err(`chmod: changing permissions of '${display}': Operation not permitted`); + code = 1; + return true; + } + node.mode = next; + return true; + }; + const walk = (node: VNode, display: string): boolean => { + if (!setNode(node, display)) return false; + if (recursive && node.kind === "dir") for (const ch of childList(node)) if (!walk(ch, `${display}/${ch.name}`)) return false; + return true; + }; + for (const f of files) { + const res = c.st.fs.walk(absOf(c, f), c.st.user); + if (!res.node) { + c.err(`chmod: cannot access '${f}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + if (!walk(res.node, f)) return 1; + } + return code; +} + +function chown(c: Ctx): number { + const o = parseOpts(c, "chown", { bool: "R" }); + if (!o) return 1; + if (o.rest.length < 2) { + c.err(o.rest.length ? `chown: missing operand after '${o.rest[0]}'` : "chown: missing operand"); + return 1; + } + const [who, ...files] = o.rest as [string, ...string[]]; + const [owner, group] = who.split(":"); + let code = 0; + for (const f of files) { + const res = c.st.fs.walk(absOf(c, f), c.st.user); + if (!res.node) { + c.err(`chown: cannot access '${f}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + const allowed = c.st.user.name === "root" || (res.node.owner === c.st.user.name && (!owner || owner === c.st.user.name)); + if (!allowed) { + c.err(`chown: changing ownership of '${f}': Operation not permitted`); + code = 1; + continue; + } + if (owner) res.node.owner = owner; + if (group) res.node.group = group; + } + return code; +} + +// ---------------------------------------------------------------- disk + +function du(c: Ctx): number { + const o = parseOpts(c, "du", { bool: "shak", val: "d", long: { summarize: "s", "human-readable": "h", all: "a", "max-depth": "d" } }); + if (!o) return 1; + const maxDepth = o.f.has("s") ? 0 : o.v.get("d") ? Number(o.v.get("d")![0]) : Infinity; + if (Number.isNaN(maxDepth)) { + c.err(`du: invalid maximum depth '${o.v.get("d")![0]}'`); + return 1; + } + const fmt = (n: number) => (o.f.has("h") ? humanSize(n) : String(Math.ceil(n / 1024))); + let code = 0; + const walk = (node: VNode, display: string, depth: number): number => { + spend(1); + if (node.kind === "file") { + const size = diskUsage(node); + if (depth === 0 || (o.f.has("a") && depth <= maxDepth)) c.out(`${fmt(size)}\t${display}\n`); + return size; + } + if (!can(c.st.user, node, 4) || !can(c.st.user, node, 1)) { + c.err(`du: cannot read directory '${display}': Permission denied`); + code = 1; + if (depth <= maxDepth) c.out(`${fmt(BLOCK)}\t${display}\n`); + return BLOCK; + } + let total = BLOCK; + for (const child of childList(node)) total += walk(child, display.endsWith("/") ? display + child.name : display + "/" + child.name, depth + 1); + if (depth <= maxDepth) c.out(`${fmt(total)}\t${display}\n`); + return total; + }; + for (const t of o.rest.length ? o.rest : ["."]) { + const res = c.st.fs.walk(absOf(c, t), c.st.user); + if (!res.node) { + c.err(`du: cannot access '${t}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + walk(res.node, t, 0); + } + return code; +} + +function df(c: Ctx): number { + const rows: string[][] = [["Filesystem", "Size", "Used", "Avail", "Use%", "Mounted on"], ...c.st.df.map((r) => [...r])]; + const w = [0, 1, 2, 3, 4].map((k) => Math.max(...rows.map((r) => r[k]!.length))); + for (const r of rows) c.out(`${r[0]!.padEnd(w[0]!)} ${r[1]!.padStart(w[1]!)} ${r[2]!.padStart(w[2]!)} ${r[3]!.padStart(w[3]!)} ${r[4]!.padStart(w[4]!)} ${r[5]}\n`); + return 0; +} + +// ---------------------------------------------------------------- processes + +function psLine(p: Proc): string { + return `${p.user.padEnd(10)} ${String(p.pid).padStart(6)} ${p.cpu.toFixed(1).padStart(4)} ${p.mem.toFixed(1).padStart(4)} ${String(p.vsz).padStart(7)} ${String(p.rss).padStart(6)} ${(p.tty ?? "?").padEnd(8)} ${p.stat.padEnd(4)} ${p.start.padEnd(5)} ${p.time.padStart(6)} ${p.command}`; +} + +function ps(c: Ctx): number { + const all = c.args.some((a) => /^-?[a-zA-Z]*[aeA][a-zA-Z]*x?$/.test(a) && a !== "-"); + if (all || c.args.length > 0) { + c.out(`${"USER".padEnd(10)} ${"PID".padStart(6)} ${"%CPU".padStart(4)} ${"%MEM".padStart(4)} ${"VSZ".padStart(7)} ${"RSS".padStart(6)} ${"TTY".padEnd(8)} ${"STAT".padEnd(4)} ${"START".padEnd(5)} ${"TIME".padStart(6)} COMMAND\n`); + for (const p of [...c.st.procs].sort((a, b) => a.pid - b.pid)) c.out(psLine(p) + "\n"); + return 0; + } + c.out(" PID TTY TIME CMD\n"); + for (const p of c.st.procs.filter((x) => x.user === c.st.user.name && x.tty).sort((a, b) => a.pid - b.pid)) { + c.out(`${String(p.pid).padStart(7)} ${(p.tty ?? "?").padEnd(8)} ${p.time.padStart(8)} ${baseName(p.command.split(" ")[0]!.replace(/^-/, ""))}\n`); + } + return 0; +} + +const SIGNALS: Record = { HUP: 1, INT: 2, QUIT: 3, KILL: 9, USR1: 10, USR2: 12, TERM: 15, CONT: 18, STOP: 19 }; + +function signalNumber(spec: string): number | null { + if (/^\d+$/.test(spec)) return Number(spec); + const name = spec.replace(/^SIG/, "").toUpperCase(); + return SIGNALS[name] ?? null; +} + +function deliver(c: Ctx, proc: Proc, sig: number): boolean { + if (sig === 0 || sig === 18 || sig === 19) return true; + if (proc.ignoresTerm && sig !== 9) return true; + c.st.procs = c.st.procs.filter((p) => p.pid !== proc.pid); + return true; +} + +function kill(c: Ctx): number { + let sig = 15; + const args = [...c.args]; + if (args[0] === "-s" || args[0] === "-n") { + const s = signalNumber(args[1] ?? ""); + if (s === null) { + c.err(`bash: kill: ${args[1] ?? ""}: invalid signal specification`); + return 1; + } + sig = s; + args.splice(0, 2); + } else if (args[0] && /^-[A-Za-z0-9]+$/.test(args[0])) { + const s = signalNumber(args[0].slice(1)); + if (s === null) { + c.err(`bash: kill: ${args[0]}: invalid signal specification`); + return 1; + } + sig = s; + args.shift(); + } + if (args.length === 0) { + c.err("kill: usage: kill [-s sigspec | -n signum | -sigspec] pid | jobspec ... or kill -l [sigspec]"); + return 2; + } + let code = 0; + for (const a of args) { + if (!/^\d+$/.test(a)) { + c.err(`bash: kill: ${a}: arguments must be process or job IDs`); + code = 1; + continue; + } + const proc = c.st.procs.find((p) => p.pid === Number(a)); + if (!proc) { + c.err(`bash: kill: (${a}) - No such process`); + code = 1; + } else if (proc.user !== c.st.user.name && c.st.user.name !== "root") { + c.err(`bash: kill: (${a}) - Operation not permitted`); + code = 1; + } else deliver(c, proc, sig); + } + return code; +} + +const procName = (p: Proc, full: boolean): string => (full ? p.command : baseName(p.command.split(" ")[0]!.replace(/^-/, ""))); + +function pgrepFamily(c: Ctx, which: "pgrep" | "pkill" | "killall"): number { + const o = parseOpts(c, which, { bool: "lfx", val: "s", numeric: which !== "pgrep" }); + // pkill -9 name: the digits are the signal. + if (!o) return 2; + const sig = o.num !== null ? Number(o.num) : 15; + const name = o.rest[0]; + if (name === undefined) { + c.err(`${which}: no matching criteria specified`); + return 2; + } + const full = o.f.has("f"); + const hits = c.st.procs.filter((p) => (o.f.has("x") ? procName(p, full) === name : procName(p, full).includes(name))).sort((a, b) => a.pid - b.pid); + if (hits.length === 0) { + if (which === "killall") c.err(`${name}: no process found`); + return 1; + } + if (which === "pgrep") { + for (const p of hits) c.out(o.f.has("l") ? `${p.pid} ${procName(p, false)}\n` : `${p.pid}\n`); + return 0; + } + let code = 0; + for (const p of hits) { + if (p.user !== c.st.user.name && c.st.user.name !== "root") { + c.err(`${which}: killing pid ${p.pid} failed: Operation not permitted`); + code = 1; + } else deliver(c, p, sig); + } + return code; +} + +// ---------------------------------------------------------------- small commands + +const KNOWN_IDS: Record = { root: 0, ops: 1000, dev: 1001, alice: 1002, bob: 1003, carol: 1004, deploy: 1005 }; + +function id(c: Ctx): number { + const u = c.st.user; + const num = (n: string) => KNOWN_IDS[n] ?? 1500; + c.out(`uid=${num(u.name)}(${u.name}) gid=${num(u.groups[0] ?? u.name)}(${u.groups[0] ?? u.name}) groups=${u.groups.map((g) => `${num(g)}(${g})`).join(",")}\n`); + return 0; +} + +function tee(c: Ctx): number { + const o = parseOpts(c, "tee", { bool: "a" }); + if (!o) return 1; + const text = c.stdin ?? ""; + let code = 0; + for (const f of o.rest) { + const e = c.st.fs.writeFile(absOf(c, f), c.st.user, text, o.f.has("a")); + if (e) { + c.err(`tee: ${f}: ${ERR_TEXT[e]}`); + code = 1; + } + } + c.out(text); + return code; +} + +function xargs(c: Ctx): number { + const o = parseOpts(c, "xargs", { stop: true }); + if (!o) return 1; + const items = (c.stdin ?? "").split(/\s+/).filter(Boolean).slice(0, 500); + const base = o.rest.length ? o.rest : ["echo"]; + if (items.length === 0) return 0; + const r = c.exec([...base, ...items], null); + c.out(r.out); + return r.code === 0 ? 0 : 123; +} + +function exportCmd(c: Ctx): number { + for (const a of c.args) { + const m = /^([A-Za-z_][A-Za-z0-9_]*)(?:=([\s\S]*))?$/.exec(a); + if (!m) { + c.err(`bash: export: \`${a}': not a valid identifier`); + return 1; + } + if (m[2] !== undefined) c.st.env[m[1]!] = m[2]; + } + return 0; +} + +function env(c: Ctx): number { + for (const k of Object.keys(c.st.env).sort()) c.out(`${k}=${c.st.env[k]}\n`); + return 0; +} + +const DATE_DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]; +const DATE_MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]; + +function date(c: Ctx): number { + const d = new Date(c.st.fs.now * 1000); + const p = (n: number) => String(n).padStart(2, "0"); + c.out(`${DATE_DAYS[d.getUTCDay()]} ${DATE_MONTHS[d.getUTCMonth()]} ${String(d.getUTCDate()).padStart(2, " ")} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())} UTC ${d.getUTCFullYear()}\n`); + return 0; +} + +export const COMMANDS: Record = { + pwd, + cd, + ls, + cat, + less: cat, + more: cat, + head: (c) => headTail(c, "head"), + tail: (c) => headTail(c, "tail"), + grep: (c) => grepCmd(c, false), + egrep: (c) => grepCmd({ ...c, args: ["-E", ...c.args] }, false), + find, + wc, + sort, + uniq, + cut, + awk, + sed, + echo, + touch, + mkdir, + rm, + cp, + mv, + chmod, + chown, + du, + df, + ps, + kill, + pgrep: (c) => pgrepFamily(c, "pgrep"), + pkill: (c) => pgrepFamily(c, "pkill"), + killall: (c) => pgrepFamily(c, "killall"), + whoami: (c) => (c.out(c.st.user.name + "\n"), 0), + id, + hostname: (c) => (c.out(c.st.hostname + "\n"), 0), + uname: (c) => (c.out(c.args.includes("-a") ? `Linux ${c.st.hostname} 6.1.0-18-amd64 #1 SMP Debian 6.1.76-1 x86_64 GNU/Linux\n` : "Linux\n"), 0), + date, + tee, + xargs, + export: exportCmd, + env, + printenv: env, + true: () => 0, + false: () => 1, + sleep: () => 0, + which: (c) => { + let code = 0; + for (const a of c.args) { + if (a in COMMANDS && !["cd", "export"].includes(a)) c.out(`/usr/bin/${a}\n`); + else code = 1; + } + return c.args.length ? code : 1; + }, + sudo: (c) => (c.err(`${c.st.user.name} is not in the sudoers file. Ask the admin, or fix it as your own user.`), 1), + su: (c) => (c.err("su: Authentication failure"), 1), +}; + +/** Real commands a learner may try that this practice server does not have. */ +export const NOT_HERE: Record = { + vi: "Edit files with echo and the > and >> redirects, or sed -i.", + vim: "Edit files with echo and the > and >> redirects, or sed -i.", + nano: "Edit files with echo and the > and >> redirects, or sed -i.", + top: "Use ps aux to see the processes.", + htop: "Use ps aux to see the processes.", + ssh: "This practice server has no network.", + curl: "This practice server has no network.", + wget: "This practice server has no network.", + ping: "This practice server has no network.", + apt: "You cannot install software here.", + "apt-get": "You cannot install software here.", + systemctl: "There is no service manager here.", + docker: "There is no Docker here. Try the Docker game.", + python: "Only the commands in 'help' work.", + python3: "Only the commands in 'help' work.", + node: "Only the commands in 'help' work.", + ln: "Links are not part of this game.", + tar: "Archives are not part of this game.", + zip: "Archives are not part of this game.", + unzip: "Archives are not part of this game.", + tree: "Try ls -R instead.", + diff: "Try cat on both files and compare.", + stat: "Try ls -l instead.", + file: "Try cat or ls -l instead.", +}; + +/** Help text for `man`, `help` and the cheat sheet. */ +export const USAGE: Record = { + pwd: { usage: "pwd", desc: "show the folder you are in", group: "Move and look" }, + cd: { usage: "cd [DIR] (cd .. goes up, cd - goes back, cd alone goes home)", desc: "change folder", group: "Move and look" }, + ls: { usage: "ls [-l] [-a] [-h] [-R] [-S] [-t] [-r] [PATH]...", desc: "list files (-l details, -a hidden, -h readable sizes, -S by size, -t by time)", group: "Move and look" }, + cat: { usage: "cat [-n] FILE...", desc: "print a file (less and more work the same)", group: "Read" }, + head: { usage: "head [-n N] [FILE]", desc: "the first N lines (10 by default)", group: "Read" }, + tail: { usage: "tail [-n N] [FILE]", desc: "the last N lines (10 by default)", group: "Read" }, + grep: { usage: "grep [-i] [-v] [-n] [-c] [-r] [-E] [-l] [-o] [-w] PATTERN [FILE]...", desc: "show lines that match a pattern", group: "Search" }, + find: { usage: "find [PATH] [-name PAT] [-type f|d] [-size +10M] [-mtime +7] [-maxdepth N] [-delete]", desc: "find files by name, type, size or age", group: "Search" }, + wc: { usage: "wc [-l] [-w] [-c] [FILE]", desc: "count lines, words and bytes", group: "Filters (use with |)" }, + sort: { usage: "sort [-r] [-n] [-h] [-u] [-k N] [-t SEP] [FILE]", desc: "sort lines (-n numbers, -h sizes like 4K, -r backwards)", group: "Filters (use with |)" }, + uniq: { usage: "uniq [-c] [-d] [FILE]", desc: "remove repeated lines next to each other (-c counts them; sort first)", group: "Filters (use with |)" }, + cut: { usage: "cut -d SEP -f N [FILE]", desc: "pick a column from each line", group: "Filters (use with |)" }, + awk: { usage: "awk [-F SEP] '{print $1, $3}' [FILE]", desc: "print chosen columns", group: "Filters (use with |)" }, + sed: { usage: "sed [-i] 's/old/new/g' [FILE]", desc: "replace text (-i changes the file)", group: "Filters (use with |)" }, + xargs: { usage: "xargs COMMAND", desc: "use the lines from a pipe as arguments", group: "Filters (use with |)" }, + tee: { usage: "tee [-a] FILE", desc: "show the input and also save it to a file", group: "Filters (use with |)" }, + echo: { usage: "echo [-n] TEXT", desc: "print text (use > file to write it into a file)", group: "Change files" }, + touch: { usage: "touch FILE...", desc: "make an empty file or update its time", group: "Change files" }, + mkdir: { usage: "mkdir [-p] DIR...", desc: "make a folder", group: "Change files" }, + rm: { usage: "rm [-r] [-f] FILE...", desc: "delete files (-r for folders). There is no undo", group: "Change files" }, + cp: { usage: "cp [-r] SOURCE... DEST", desc: "copy files (-r for folders)", group: "Change files" }, + mv: { usage: "mv SOURCE... DEST", desc: "move or rename", group: "Change files" }, + chmod: { usage: "chmod MODE FILE... (755, 644, +x, u+x, go-w)", desc: "change who may read, write or run a file", group: "Change files" }, + chown: { usage: "chown USER[:GROUP] FILE...", desc: "change the owner (only root can give files away)", group: "Change files" }, + du: { usage: "du [-s] [-h] [-d N] [PATH]...", desc: "how much disk each folder uses", group: "System" }, + df: { usage: "df -h", desc: "how full each disk is", group: "System" }, + ps: { usage: "ps aux", desc: "list running processes with their PID", group: "System" }, + kill: { usage: "kill [-9] PID...", desc: "stop a process (-9 forces it)", group: "System" }, + pgrep: { usage: "pgrep [-l] NAME", desc: "find process IDs by name (pkill and killall stop them)", group: "System" }, + whoami: { usage: "whoami", desc: "show your user name", group: "System" }, + id: { usage: "id", desc: "show your user and groups", group: "System" }, + which: { usage: "which COMMAND", desc: "show where a command lives", group: "System" }, + hostname: { usage: "hostname", desc: "show the server name", group: "System" }, + date: { usage: "date", desc: "show the date", group: "System" }, + export: { usage: "export NAME=VALUE", desc: "set a variable (use it as $NAME)", group: "System" }, + history: { usage: "history", desc: "list the commands you ran", group: "This game" }, + clear: { usage: "clear", desc: "clear the screen", group: "This game" }, + hint: { usage: "hint", desc: "show the next hint (it can cost a star)", group: "This game" }, + submit: { usage: "submit ANSWER", desc: "give your answer (for missions that ask a question)", group: "This game" }, + help: { usage: "help", desc: "list the commands that work here (man NAME shows one)", group: "This game" }, +}; + +export const SHELL_TIPS = [ + "Pipe: cmd1 | cmd2 sends the output of cmd1 into cmd2", + "Redirect: > writes a file, >> adds to it", + "&& runs the next command only if the first worked", + "Quotes keep spaces together. $HOME, $USER and $PWD work", + "Tab finishes a name. Arrow up repeats a command", +]; diff --git a/frontend/src/shared/games/linux/engine.ts b/frontend/src/shared/games/linux/engine.ts new file mode 100644 index 00000000..a3ca752f --- /dev/null +++ b/frontend/src/shared/games/linux/engine.ts @@ -0,0 +1,108 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +/* eslint-disable no-control-regex -- the shell engines reject or use control characters on purpose */ +// Linux Command Explorer: a terminal quest on a made-up server. The player solves a mission with +// real commands in a fake shell. The browser plays it live; the server replays the same commands +// from a fresh state before it gives XP. Pure and deterministic, so both sides always agree. +import { pickDaily } from "../daily"; +import type { GameEngine, RoundBase, Stars, VerifyResult } from "../types"; +import { USAGE } from "./commands"; +import { MISSIONS, missionById } from "./missions"; +import { MAX_COMMANDS, MAX_LINE, Shell } from "./shell"; + +export type { OutLine, Progress, RunResult } from "./shell"; +export { Shell } from "./shell"; + +/** What the browser needs to show a mission. The server definition (files, goal) stays in the engine. */ +export type LinuxRound = RoundBase & { + story: string; + /** The checklist, in order. The last one is the goal. */ + objectives: string[]; + /** Commands a good player needs. Three stars need this many or fewer, with no hints. */ + par: number; + hintCount: number; + /** "answer": give an answer with submit. "state": change the server until the goal is true. */ + kind: "answer" | "state"; +}; + +export type LinuxSubmission = { commands: string[]; hints: number }; + +const POOL: LinuxRound[] = MISSIONS.map((m) => ({ + id: m.id, + difficulty: m.difficulty, + title: m.title, + brief: m.brief, + story: m.story, + objectives: m.objectives.map((o) => o.label), + par: m.par, + hintCount: m.hints.length, + kind: m.answer ? "answer" : "state", +})); + +const CONTROL = /[\u0000-\u0008\u000a-\u001f\u007f]/; + +function parseSubmission(input: unknown): LinuxSubmission | null { + if (typeof input !== "object" || input === null || Array.isArray(input)) return null; + const keys = Object.keys(input); + if (keys.some((k) => k !== "commands" && k !== "hints")) return null; + const { commands, hints } = input as { commands?: unknown; hints?: unknown }; + if (!Array.isArray(commands) || commands.length > MAX_COMMANDS) return null; + for (const line of commands) { + if (typeof line !== "string" || line.length > MAX_LINE || CONTROL.test(line)) return null; + } + if (typeof hints !== "number" || !Number.isInteger(hints) || hints < 0 || hints > 20) return null; + return { commands: [...(commands as string[])], hints }; +} + +const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`; + +function verify(round: LinuxRound, submission: LinuxSubmission): VerifyResult { + const fail = (message: string, score = 0): VerifyResult => ({ passed: false, stars: 0, score, message }); + try { + const mission = missionById(round?.id); + if (!mission) return fail("This mission is not known."); + const parsed = parseSubmission(submission); + if (!parsed) return fail("That did not look like a finished round."); + if (parsed.commands.length === 0) return fail("No commands were run yet. Try ls to look around."); + const shell = new Shell(mission); + for (const line of parsed.commands) shell.run(line); + const progress = shell.progress(); + if (!shell.isSolved) { + const open = mission.objectives.find((_, i) => !progress.done[i]); + return fail(open ? `The goal is not reached yet. Still open: ${open.label}.` : "The goal is not reached yet.", shell.commandCount); + } + const commands = shell.commandCount; + const hints = Math.max(shell.hintCount, parsed.hints); + const stars: Stars = hints === 0 && commands <= mission.par ? 3 : hints <= 1 && commands <= mission.par + 4 ? 2 : 1; + const message = + stars === 3 + ? `Solved in ${plural(commands, "command")}, par is ${mission.par}, with no hints.` + : `Solved in ${plural(commands, "command")} (par ${mission.par}) with ${plural(hints, "hint")}; use par or fewer commands and no hints for 3 stars.`; + return { passed: true, stars, score: commands, message }; + } catch { + return fail("That run could not be checked."); + } +} + +export const linuxEngine: GameEngine = { + id: "linux", + title: "Linux Command Explorer", + tagline: "Solve missions on a made-up Linux server with real commands.", + roundsFor: (dayKey) => pickDaily(POOL, dayKey, "linux"), + parseSubmission, + verify, +}; + +/** A new shell for a round, or null when the round is not one of ours. */ +export function createLinuxSession(round: { id: string }): Shell | null { + const mission = missionById(round?.id); + return mission ? new Shell(mission) : null; +} + +/** The "what works" cheat sheet, grouped. */ +export function linuxCheatSheet(): Array<{ group: string; items: Array<{ name: string; usage: string; desc: string }> }> { + const groups = new Map>(); + for (const [name, u] of Object.entries(USAGE)) groups.set(u.group, [...(groups.get(u.group) ?? []), { name, usage: u.usage, desc: u.desc }]); + return [...groups].map(([group, items]) => ({ group, items })); +} + +export const LINUX_LIMITS = { maxCommands: MAX_COMMANDS, maxLine: MAX_LINE }; diff --git a/frontend/src/shared/games/linux/fs.ts b/frontend/src/shared/games/linux/fs.ts new file mode 100644 index 00000000..fe89f292 --- /dev/null +++ b/frontend/src/shared/games/linux/fs.ts @@ -0,0 +1,362 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// An in-memory file system for the Linux Command Explorer. Pure and deterministic: no real files, +// no clock. "Now" is a fixed number that moves forward one minute per command the player runs. + +export const NOW = 1767225600; // 2026-01-01 00:00:00 UTC +export const DAY = 86400; +export const MAX_NODES = 1500; +export const MAX_FILE_SIZE = 200_000; +export const MAX_PATH = 1024; +export const BLOCK = 4096; + +export type Err = "ENOENT" | "EACCES" | "ENOTDIR" | "EEXIST" | "EISDIR" | "ENOSPC" | "EINVAL"; + +export const ERR_TEXT: Record = { + ENOENT: "No such file or directory", + EACCES: "Permission denied", + ENOTDIR: "Not a directory", + EEXIST: "File exists", + EISDIR: "Is a directory", + ENOSPC: "No space left on device", + EINVAL: "Invalid argument", +}; + +export type User = { name: string; groups: string[] }; + +export type VNode = { + kind: "file" | "dir"; + name: string; + owner: string; + group: string; + mode: number; + mtime: number; + content: string; + /** A made-up size in bytes for a big file whose text is short. */ + size: number | null; + children: Map; +}; + +export type FileOpts = { + content?: string; + size?: number; + owner?: string; + group?: string; + mode?: number; + mtime?: number; + /** Age in days at the fixed "now". */ + age?: number; +}; +/** A path ending in "/" is a directory. A string value is the text of a file. */ +export type FsSpec = Record; + +/** Turn a path into an absolute one with no "." or ".." parts. */ +export function normalizePath(cwd: string, input: string, home = "/"): string { + let path = input; + if (path === "~" || path.startsWith("~/")) path = home + path.slice(1); + if (!path.startsWith("/")) path = cwd + "/" + path; + const out: string[] = []; + for (const part of path.split("/")) { + if (part === "" || part === ".") continue; + if (part === "..") out.pop(); + else out.push(part); + } + return "/" + out.join("/"); +} + +export function baseName(abs: string): string { + const i = abs.lastIndexOf("/"); + return i < 0 ? abs : abs.slice(i + 1); +} + +export function dirName(abs: string): string { + const i = abs.lastIndexOf("/"); + return i <= 0 ? "/" : abs.slice(0, i); +} + +export function joinPath(dir: string, name: string): string { + return dir === "/" ? "/" + name : dir + "/" + name; +} + +/** Permission bits for a user on a node: 4 read, 2 write, 1 execute. */ +export function permBits(user: User, node: VNode): number { + if (user.name === "root") return 7; + if (node.owner === user.name) return (node.mode >> 6) & 7; + if (user.groups.includes(node.group)) return (node.mode >> 3) & 7; + return node.mode & 7; +} + +export function can(user: User, node: VNode, bit: 1 | 2 | 4): boolean { + return (permBits(user, node) & bit) !== 0; +} + +export function modeString(node: VNode): string { + const m = node.mode; + const triple = (v: number) => (v & 4 ? "r" : "-") + (v & 2 ? "w" : "-") + (v & 1 ? "x" : "-"); + return (node.kind === "dir" ? "d" : "-") + triple((m >> 6) & 7) + triple((m >> 3) & 7) + triple(m & 7); +} + +const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]; + +/** The date column of `ls -l`. */ +export function formatTime(mtime: number, now: number): string { + const d = new Date(mtime * 1000); + const day = String(d.getUTCDate()).padStart(2, " "); + if (now - mtime > 180 * DAY || mtime > now + DAY) return `${MONTHS[d.getUTCMonth()]} ${day} ${d.getUTCFullYear()}`; + const hh = String(d.getUTCHours()).padStart(2, "0"); + const mm = String(d.getUTCMinutes()).padStart(2, "0"); + return `${MONTHS[d.getUTCMonth()]} ${day} ${hh}:${mm}`; +} + +/** Sizes like GNU `-h`: 1.5K, 12M, 4.0K. */ +export function humanSize(bytes: number): string { + if (bytes < 1024) return String(bytes); + const units = ["K", "M", "G", "T"]; + let v = bytes / 1024; + let i = 0; + while (v >= 1024 && i < units.length - 1) { + v /= 1024; + i++; + } + const rounded = Math.ceil(v * 10) / 10; + return (rounded < 10 ? rounded.toFixed(1) : String(Math.ceil(v))) + units[i]; +} + +function newNode(kind: "file" | "dir", name: string, owner: string, opts: FileOpts = {}): VNode { + return { + kind, + name, + owner: opts.owner ?? owner, + group: opts.group ?? opts.owner ?? owner, + mode: opts.mode ?? (kind === "dir" ? 0o755 : 0o644), + mtime: opts.mtime ?? (opts.age !== undefined ? NOW - Math.round(opts.age * DAY) : NOW - 2 * DAY), + content: opts.content ?? "", + size: opts.size ?? null, + children: new Map(), + }; +} + +/** Who owns a path when the mission does not say: a home folder belongs to its user. */ +function defaultOwner(abs: string): string { + const m = /^\/home\/([^/]+)/.exec(abs); + return m ? m[1]! : "root"; +} + +export function sizeOf(node: VNode): number { + return node.kind === "dir" ? BLOCK : node.size ?? node.content.length; +} + +/** Disk blocks used, like `du`: files in 4K blocks, a folder counts itself too. */ +export function diskUsage(node: VNode): number { + if (node.kind === "file") { + const size = sizeOf(node); + return size === 0 ? 0 : Math.ceil(size / BLOCK) * BLOCK; + } + let total = BLOCK; + for (const child of node.children.values()) total += diskUsage(child); + return total; +} + +export type Walk = { node: VNode | null; err: Err | null }; + +export class VFS { + root: VNode; + count = 1; + /** The fixed "now", moved forward by the shell. */ + now = NOW; + + constructor(spec: FsSpec) { + this.root = newNode("dir", "", "root"); + const keys = Object.keys(spec).sort((a, b) => a.length - b.length); + for (const key of keys) { + const value = spec[key]!; + const opts: FileOpts = typeof value === "string" ? { content: value } : value; + const abs = normalizePath("/", key); + if (abs === "/") { + Object.assign(this.root, { mode: opts.mode ?? this.root.mode, owner: opts.owner ?? this.root.owner }); + continue; + } + if (key.endsWith("/")) this.build(abs, "dir", opts); + else this.build(abs, "file", opts); + } + } + + private build(abs: string, kind: "file" | "dir", opts: FileOpts): void { + const parts = abs.split("/").filter(Boolean); + let cur = this.root; + let path = ""; + for (let i = 0; i < parts.length; i++) { + const part = parts[i]!; + path += "/" + part; + const last = i === parts.length - 1; + let next = cur.children.get(part); + if (!next) { + next = newNode(last ? kind : "dir", part, defaultOwner(path), last ? opts : {}); + cur.children.set(part, next); + this.count++; + } else if (last) { + if (kind === "dir") Object.assign(next, { owner: opts.owner ?? next.owner, group: opts.group ?? opts.owner ?? next.group, mode: opts.mode ?? next.mode, mtime: opts.mtime ?? (opts.age !== undefined ? NOW - opts.age * DAY : next.mtime) }); + } + cur = next; + } + } + + /** Find a node by absolute path, checking that the user may walk into every folder on the way. */ + walk(abs: string, user: User): Walk { + let cur = this.root; + for (const part of abs.split("/")) { + if (part === "") continue; + if (cur.kind !== "dir") return { node: null, err: "ENOTDIR" }; + if (!can(user, cur, 1)) return { node: null, err: "EACCES" }; + const next = cur.children.get(part); + if (!next) return { node: null, err: "ENOENT" }; + cur = next; + } + return { node: cur, err: null }; + } + + /** No permission checks. For the game's own goal checks. */ + peek(abs: string): VNode | null { + let cur: VNode | undefined = this.root; + for (const part of abs.split("/")) { + if (part === "") continue; + if (!cur || cur.kind !== "dir") return null; + cur = cur.children.get(part); + } + return cur ?? null; + } + + /** The folder that would hold a new entry at this path, and the name of the entry. */ + parentFor(abs: string, user: User): { dir: VNode | null; name: string; err: Err | null } { + const name = baseName(abs); + const res = this.walk(dirName(abs), user); + if (!res.node) return { dir: null, name, err: res.err }; + if (res.node.kind !== "dir") return { dir: null, name, err: "ENOTDIR" }; + return { dir: res.node, name, err: null }; + } + + private checkNew(abs: string, user: User): { dir: VNode; name: string } | Err { + if (abs.length > MAX_PATH) return "EINVAL"; + const p = this.parentFor(abs, user); + if (!p.dir) return p.err ?? "ENOENT"; + if (!can(user, p.dir, 2) || !can(user, p.dir, 1)) return "EACCES"; + if (p.name.length > 255 || p.name === "") return "EINVAL"; + return { dir: p.dir, name: p.name }; + } + + /** Create or replace a file. */ + writeFile(abs: string, user: User, text: string, append: boolean): Err | null { + const existing = this.walk(abs, user); + if (existing.node) { + const node = existing.node; + if (node.kind === "dir") return "EISDIR"; + if (!can(user, node, 2)) return "EACCES"; + const next = append ? node.content + text : text; + if (next.length > MAX_FILE_SIZE) return "ENOSPC"; + node.content = next; + node.size = null; + node.mtime = this.now; + return null; + } + if (existing.err !== "ENOENT") return existing.err; + const target = this.checkNew(abs, user); + if (typeof target === "string") return target; + if (this.count >= MAX_NODES || text.length > MAX_FILE_SIZE) return "ENOSPC"; + const node = newNode("file", target.name, user.name, { content: text, mtime: this.now }); + node.group = user.groups[0] ?? user.name; + target.dir.children.set(target.name, node); + target.dir.mtime = this.now; + this.count++; + return null; + } + + mkdir(abs: string, user: User): Err | null { + const existing = this.walk(abs, user); + if (existing.node) return "EEXIST"; + if (existing.err !== "ENOENT") return existing.err; + const target = this.checkNew(abs, user); + if (typeof target === "string") return target; + if (this.count >= MAX_NODES) return "ENOSPC"; + const node = newNode("dir", target.name, user.name, { mtime: this.now }); + node.group = user.groups[0] ?? user.name; + target.dir.children.set(target.name, node); + target.dir.mtime = this.now; + this.count++; + return null; + } + + private countNodes(node: VNode): number { + let n = 1; + for (const c of node.children.values()) n += this.countNodes(c); + return n; + } + + /** Delete a file or a folder with everything in it. The caller checks the "-r" rule. */ + remove(abs: string, user: User): Err | null { + if (abs === "/") return "EINVAL"; + const p = this.parentFor(abs, user); + if (!p.dir) return p.err; + const node = p.dir.children.get(p.name); + if (!node) return "ENOENT"; + if (!can(user, p.dir, 2)) return "EACCES"; + p.dir.children.delete(p.name); + p.dir.mtime = this.now; + this.count -= this.countNodes(node); + return null; + } + + private copyNode(node: VNode, name: string, owner: string, group: string): VNode { + const copy: VNode = { ...node, name, owner, group, mtime: this.now, children: new Map() }; + for (const [key, child] of node.children) copy.children.set(key, this.copyNode(child, child.name, owner, group)); + return copy; + } + + /** Copy a node to a new absolute path (the path of the copy itself). */ + copy(node: VNode, destAbs: string, user: User): Err | null { + const target = this.checkNew(destAbs, user); + if (typeof target === "string") return target; + if (target.dir.children.has(target.name)) { + const old = target.dir.children.get(target.name)!; + if (old.kind === "dir") return "EISDIR"; + if (!can(user, old, 2)) return "EACCES"; + this.count -= 1; + } + if (this.count + this.countNodes(node) > MAX_NODES) return "ENOSPC"; + const copy = this.copyNode(node, target.name, user.name, user.groups[0] ?? user.name); + copy.mode = node.mode; + target.dir.children.set(target.name, copy); + target.dir.mtime = this.now; + this.count += this.countNodes(copy); + return null; + } + + /** Move a node to a new absolute path. */ + move(srcAbs: string, destAbs: string, user: User): Err | null { + const from = this.parentFor(srcAbs, user); + if (!from.dir) return from.err; + const node = from.dir.children.get(from.name); + if (!node) return "ENOENT"; + if (!can(user, from.dir, 2)) return "EACCES"; + if (destAbs === srcAbs) return null; + if (destAbs.startsWith(srcAbs + "/")) return "EINVAL"; + const target = this.checkNew(destAbs, user); + if (typeof target === "string") return target; + const old = target.dir.children.get(target.name); + if (old) { + if (old.kind === "dir" && node.kind !== "dir") return "EISDIR"; + if (old.kind === "dir" && old.children.size > 0) return "EEXIST"; + this.count -= this.countNodes(old); + } + from.dir.children.delete(from.name); + node.name = target.name; + target.dir.children.set(target.name, node); + from.dir.mtime = this.now; + target.dir.mtime = this.now; + return null; + } + + /** Read a file's text with no permission checks, or null. For goal checks. */ + text(abs: string): string | null { + const node = this.peek(abs); + return node && node.kind === "file" ? node.content : null; + } +} diff --git a/frontend/src/shared/games/linux/missions.ts b/frontend/src/shared/games/linux/missions.ts new file mode 100644 index 00000000..099d59a3 --- /dev/null +++ b/frontend/src/shared/games/linux/missions.ts @@ -0,0 +1,589 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The missions of the Linux Command Explorer. Each one is a small made-up server (orbit-01) and a +// goal. The player is the user "ops". Everything here is fixed data, so every day is the same for +// everyone and every mission can be replayed from its `solution`. +import { hashString, seededRandom } from "../daily"; +import type { FsSpec } from "./fs"; +import type { Mission, Proc, ShellState } from "./model"; + +// ---------------------------------------------------------------- helpers + +const lines = (...l: string[]): string => l.join("\n") + "\n"; +const ran = (s: ShellState, re: RegExp): boolean => s.history.some((h) => re.test(h)); +const saw = (s: ShellState, what: string | RegExp): boolean => (typeof what === "string" ? s.shown.includes(what) : what.test(s.shown)); +const exists = (s: ShellState, path: string): boolean => s.fs.peek(path) !== null; +const pad2 = (n: number): string => String(n).padStart(2, "0"); + +/** The parts every server has. A mission adds to these (and may replace them). */ +function base(): FsSpec { + return { + "/etc/hostname": "orbit-01\n", + "/etc/hosts": lines("127.0.0.1 localhost", "10.0.0.10 orbit-01"), + "/etc/os-release": lines('NAME="Debian GNU/Linux"', 'VERSION="12 (bookworm)"'), + "/etc/passwd": lines( + "root:x:0:0:root:/root:/bin/bash", + "ops:x:1000:1000:Ops:/home/ops:/bin/bash", + "alice:x:1002:1002:Alice:/home/alice:/bin/bash", + "bob:x:1003:1003:Bob:/home/bob:/bin/bash", + "www-data:x:33:33:www-data:/var/www:/usr/sbin/nologin", + ), + "/home/ops/.bashrc": lines("# ~/.bashrc", "alias ll='ls -l'"), + "/home/ops/todo.txt": lines("1. read the mission panel", "2. explore with ls and cat", "3. ask for a hint only when stuck"), + "/root/": { owner: "root", mode: 0o700 }, + "/root/notes.txt": { content: "root only\n", mode: 0o600 }, + "/tmp/": { mode: 0o777 }, + "/var/log/": {}, + }; +} + +function accessLog(seed: string, count: number): string { + const r = seededRandom(hashString(seed)); + const ips = ["10.0.0.4", "10.0.0.7", "10.0.1.12", "192.168.1.5", "172.16.0.9"]; + const paths = ["/", "/login", "/api/items", "/api/orders", "/static/app.js", "/health", "/about"]; + const statuses = [200, 200, 200, 200, 304, 404, 500]; + const out: string[] = []; + for (let i = 0; i < count; i++) { + const t = i * 97; + const ip = ips[Math.floor(r() * ips.length)]!; + const path = paths[Math.floor(r() * paths.length)]!; + const status = statuses[Math.floor(r() * statuses.length)]!; + out.push(`${ip} - - [01/Jan/2026:${pad2(Math.floor(t / 3600) % 24)}:${pad2(Math.floor(t / 60) % 60)}:${pad2(t % 60)}] "GET ${path} HTTP/1.1" ${status} ${200 + Math.floor(r() * 9000)}`); + } + return out.join("\n") + "\n"; +} + +/** A login log. `failed` and `accepted` say how many lines each address gets. Lines are shuffled. */ +function authLog(seed: string, failed: Array<[string, number]>, accepted: Array<[string, number]>, noise: number): { text: string; failedTotal: number } { + const r = seededRandom(hashString(seed)); + const users = ["root", "admin", "deploy", "test", "oracle", "ubuntu"]; + const port = () => 30000 + Math.floor(r() * 30000); + const pid = () => 1000 + Math.floor(r() * 8000); + const events: string[] = []; + let failedTotal = 0; + for (const [ip, n] of failed) { + for (let i = 0; i < n; i++) { + const user = users[Math.floor(r() * users.length)]!; + const invalid = r() < 0.4 ? "invalid user " : ""; + events.push(`orbit-01 sshd[${pid()}]: Failed password for ${invalid}${user} from ${ip} port ${port()} ssh2`); + failedTotal++; + } + } + for (const [ip, n] of accepted) { + for (let i = 0; i < n; i++) events.push(`orbit-01 sshd[${pid()}]: Accepted password for deploy from ${ip} port ${port()} ssh2`); + } + for (let i = 0; i < noise; i++) { + const pick = Math.floor(r() * 4); + if (pick === 0) events.push(`orbit-01 sshd[${pid()}]: Connection closed by 10.0.0.9 port ${port()} [preauth]`); + else if (pick === 1) events.push(`orbit-01 sshd[${pid()}]: pam_unix(sshd:session): session opened for user ops(uid=1000) by (uid=0)`); + else if (pick === 2) events.push(`orbit-01 sshd[${pid()}]: Invalid user guest from 198.51.100.200 port ${port()}`); + else events.push(`orbit-01 CRON[${pid()}]: pam_unix(cron:session): session closed for user root`); + } + for (let i = events.length - 1; i > 0; i--) { + const j = Math.floor(r() * (i + 1)); + [events[i], events[j]] = [events[j]!, events[i]!]; + } + const text = events.map((e, i) => { + const t = (i * 41) % 86400; + return `2026-01-01T${pad2(Math.floor(t / 3600))}:${pad2(Math.floor(t / 60) % 60)}:${pad2(t % 60)} ${e}`; + }); + return { text: text.join("\n") + "\n", failedTotal }; +} + +const ACCESS_LINES = 214; +const AUTH_EASY = authLog("auth-medium", [["203.0.113.9", 23], ["198.51.100.4", 17], ["192.0.2.88", 11]], [["10.0.0.5", 30]], 60); +const AUTH_HARD = authLog( + "auth-hard", + [["203.0.113.77", 91], ["198.51.100.23", 64], ["192.0.2.14", 37], ["203.0.113.5", 22], ["198.51.100.99", 15], ["192.0.2.200", 8]], + [["10.0.0.5", 120], ["10.0.0.6", 40]], + 80, +); + +// ---------------------------------------------------------------- easy + +const hiddenNote: Mission = { + id: "linux-hidden-note", + difficulty: "easy", + title: "The hidden note", + brief: "A file in the app folder is hiding. Find it and read the release word.", + story: "Priya just joined the team. She needs the release word for tonight's deploy, but nobody can find it. Someone said it is in a hidden file inside the app folder.", + par: 3, + hints: [ + "Files whose names start with a dot are hidden. A plain ls does not show them.", + "ls -a shows hidden files too. Try: ls -a app", + "Read the hidden file with cat, then answer with: submit WORD", + ], + files: { + ...base(), + "/home/ops/app/README.md": lines("# Orbit app", "Run main.py to start the app."), + "/home/ops/app/main.py": lines("print('orbit app starting')"), + "/home/ops/app/requirements.txt": lines("flask==3.0.0", "gunicorn==21.2.0"), + "/home/ops/app/.deploy_note": lines("Release word: BLUEFOX-42", "Do not share this word outside the team."), + "/home/ops/app/static/": {}, + "/home/ops/app/static/logo.txt": "(a tiny logo)\n", + }, + answer: ["BLUEFOX-42"], + objectives: [ + { label: "Show the hidden files in the app folder", done: (s) => saw(s, ".deploy_note") }, + { label: "Read the hidden file", done: (s) => saw(s, "BLUEFOX-42") }, + { label: "Submit the release word with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["ls -a app", "cat app/.deploy_note", "submit BLUEFOX-42"], +}; + +const configPort: Mission = { + id: "linux-config-port", + difficulty: "easy", + title: "Which port?", + brief: "Read the web app's config file and find the port it listens on.", + story: "The proxy team needs to point at the web app, but nobody remembers its port. The settings live in a config folder under /etc/webapp.", + par: 3, + hints: [ + "Config files usually live in /etc. Try: ls /etc/webapp", + "Use app.conf (the .old file is outdated). Read it with cat.", + "Look for the line with listen_port, then: submit NUMBER", + ], + files: { + ...base(), + "/etc/webapp/app.conf": lines("# webapp settings", "name=orbit-web", "listen_host=0.0.0.0", "listen_port=8472", "workers=4", "log_level=info"), + "/etc/webapp/app.conf.old": lines("# old settings (do not use)", "name=orbit-web", "listen_host=127.0.0.1", "listen_port=8080", "workers=2"), + "/etc/webapp/mime.types": lines("text/html html", "text/css css"), + }, + answer: ["8472"], + objectives: [ + { label: "Look in the /etc/webapp folder", done: (s) => saw(s, "app.conf") }, + { label: "Read the current config file", done: (s) => saw(s, "listen_port=8472") }, + { label: "Submit the port with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["ls /etc/webapp", "cat /etc/webapp/app.conf", "submit 8472"], +}; + +const countLines: Mission = { + id: "linux-count-requests", + difficulty: "easy", + title: "How many requests?", + brief: "Count how many lines the web server's access log has. Each line is one request.", + story: "The boss asks how many requests the web server handled today. The server writes one line per request into an access log in /var/log/webapp.", + par: 3, + hints: [ + "Find the log first: ls /var/log/webapp", + "wc counts things. wc -l counts lines.", + "Try: wc -l /var/log/webapp/access.log and then submit the number", + ], + files: { + ...base(), + "/var/log/webapp/access.log": accessLog("access-easy", ACCESS_LINES), + "/var/log/webapp/error.log": lines("2026-01-01 03:12:44 error: upstream timed out", "2026-01-01 09:40:02 error: bad gateway"), + }, + answer: [String(ACCESS_LINES)], + objectives: [ + { label: "Find the web server logs", done: (s) => saw(s, "access.log") }, + { label: "Count the lines in access.log", done: (s) => saw(s, new RegExp(`\\b${ACCESS_LINES}\\b`)) }, + { label: "Submit the number with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["ls /var/log/webapp", "wc -l /var/log/webapp/access.log", `submit ${ACCESS_LINES}`], +}; + +const biggestFile: Mission = { + id: "linux-biggest-file", + difficulty: "easy", + title: "The biggest file", + brief: "The downloads folder is eating the disk. Find the biggest file in it.", + story: "Your disk is almost full. Most of the space is in the downloads folder. Which single file is the biggest?", + par: 3, + hints: [ + "ls -l shows the size of each file in bytes.", + "Add -S to sort by size, biggest first: ls -lS downloads", + "Or use ls -lh to see sizes like 870M. Then: submit FILENAME", + ], + files: { + ...base(), + "/home/ops/downloads/notes.txt": { content: "meeting notes\n", size: 2300 }, + "/home/ops/downloads/invoice-march.pdf": { content: "pdf", size: 480_000 }, + "/home/ops/downloads/photo-001.jpg": { content: "jpg", size: 3_400_000 }, + "/home/ops/downloads/photo-002.jpg": { content: "jpg", size: 2_900_000 }, + "/home/ops/downloads/holiday-video.mp4": { content: "mp4", size: 912_000_000 }, + "/home/ops/downloads/backup-old.zip": { content: "zip", size: 410_000_000 }, + "/home/ops/downloads/setup.iso": { content: "iso", size: 702_000_000 }, + "/home/ops/downloads/music.mp3": { content: "mp3", size: 7_800_000 }, + }, + answer: ["holiday-video.mp4"], + objectives: [ + { label: "Look at the downloads folder", done: (s) => saw(s, "holiday-video.mp4") }, + { label: "Show the file sizes (try ls -l)", done: (s) => ran(s, /\bls\b[^|;&]*\s-[a-zA-Z]*l|\bdu\b/) }, + { label: "Submit the name of the biggest file", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["ls -lS downloads", "submit holiday-video.mp4"], +}; + +// ---------------------------------------------------------------- medium + +const failedLogins: Mission = { + id: "linux-failed-logins", + difficulty: "medium", + title: "Failed logins", + brief: "Count the failed password attempts in the login log.", + story: "Security saw strange traffic last night. The login log is /var/log/auth.log. Each failed password attempt has the words Failed password. How many are there?", + par: 3, + hints: [ + "grep prints the lines that match a word: grep 'Failed password' /var/log/auth.log", + "Count them with grep -c, or send the lines to wc -l with a pipe.", + "Try: grep -c 'Failed password' /var/log/auth.log then submit NUMBER", + ], + files: { ...base(), "/var/log/auth.log": AUTH_EASY.text }, + answer: [String(AUTH_EASY.failedTotal)], + objectives: [ + { label: "Search auth.log for Failed password", done: (s) => ran(s, /grep/) && ran(s, /auth\.log/) && ran(s, /failed password/i) }, + { label: "Count the matching lines", done: (s) => saw(s, new RegExp(`(^|\\n)\\s*${AUTH_EASY.failedTotal}\\s*(\\n|$)`)) }, + { label: "Submit the count with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["grep -c 'Failed password' /var/log/auth.log", `submit ${AUTH_EASY.failedTotal}`], +}; + +const OLD_TMP = ["/var/tmp/cache-a.tmp", "/var/tmp/cache-b.tmp", "/var/tmp/session-91.tmp", "/var/tmp/render/frame1.tmp"]; +const KEEP_TMP = ["/var/tmp/upload-77.tmp", "/var/tmp/lock-now.tmp", "/var/tmp/render/frame2.tmp", "/var/tmp/report.txt", "/var/tmp/old.log"]; + +const oldTmp: Mission = { + id: "linux-old-temp-files", + difficulty: "medium", + title: "Clean the temp folder", + brief: "Delete the .tmp files in /var/tmp that are older than 7 days. Keep everything else.", + story: "/var/tmp is full of leftovers. The rule: .tmp files older than 7 days can go. Fresh .tmp files are still used by running jobs, and other file types must stay.", + par: 3, + hints: [ + "find can test the age of files: -mtime +7 means older than 7 days.", + "Combine tests: find /var/tmp -name '*.tmp' -mtime +7 (first only look at what it finds).", + "When the list looks right, add -delete at the end.", + ], + files: { + ...base(), + "/var/tmp/": { owner: "ops" }, + "/var/tmp/render/": { owner: "ops" }, + "/var/tmp/cache-a.tmp": { content: "x", age: 12 }, + "/var/tmp/cache-b.tmp": { content: "x", age: 30 }, + "/var/tmp/session-91.tmp": { content: "x", age: 9 }, + "/var/tmp/upload-77.tmp": { content: "x", age: 2 }, + "/var/tmp/lock-now.tmp": { content: "x", age: 0 }, + "/var/tmp/report.txt": { content: "quarterly numbers\n", age: 40 }, + "/var/tmp/old.log": { content: "old log\n", age: 60 }, + "/var/tmp/render/frame1.tmp": { content: "x", age: 20 }, + "/var/tmp/render/frame2.tmp": { content: "x", age: 1 }, + }, + objectives: [ + { label: "Find the .tmp files older than 7 days", done: (s) => ran(s, /find[^|;&]*-mtime/) }, + { label: "Delete the old .tmp files", done: (s) => OLD_TMP.every((p) => !exists(s, p)) }, + { label: "Keep the fresh .tmp files and the other files", done: (s) => OLD_TMP.every((p) => !exists(s, p)) && KEEP_TMP.every((p) => exists(s, p)) }, + ], + goal: (s) => OLD_TMP.every((p) => !exists(s, p)) && KEEP_TMP.every((p) => exists(s, p)), + solution: ["find /var/tmp -name '*.tmp' -mtime +7", "find /var/tmp -name '*.tmp' -mtime +7 -delete"], +}; + +const PROCS: Proc[] = [ + { pid: 1, user: "root", cpu: 0, mem: 0.1, vsz: 168000, rss: 11000, stat: "Ss", start: "Jan01", time: "0:03", command: "/sbin/init" }, + { pid: 77, user: "root", cpu: 0, mem: 0.1, vsz: 8500, rss: 2200, stat: "Ss", start: "Jan01", time: "0:00", command: "/usr/sbin/cron -f" }, + { pid: 311, user: "postgres", cpu: 1.2, mem: 3.4, vsz: 320000, rss: 56000, stat: "Ss", start: "Jan01", time: "1:12", command: "postgres: main" }, + { pid: 520, user: "www-data", cpu: 0.3, mem: 1.1, vsz: 98000, rss: 18000, stat: "S", start: "Jan01", time: "0:20", command: "nginx: worker process" }, + { pid: 988, user: "root", cpu: 0, mem: 0.2, vsz: 15400, rss: 6000, stat: "Ss", start: "Jan01", time: "0:00", command: "sshd: /usr/sbin/sshd -D" }, + { pid: 1204, user: "ops", cpu: 0, mem: 0.2, vsz: 9100, rss: 4800, tty: "pts/0", stat: "Ss", start: "00:00", time: "0:00", command: "-bash" }, + { pid: 4242, user: "ops", cpu: 99.8, mem: 12.5, vsz: 2048000, rss: 410000, stat: "Rl", start: "23:41", time: "412:08", command: "/opt/tools/reindex --all --forever", ignoresTerm: true }, +]; + +const runaway: Mission = { + id: "linux-runaway-process", + difficulty: "medium", + title: "Runaway process", + brief: "One process uses all the CPU. Stop it, but leave the other services running.", + story: "The server is crawling. Something is using almost the whole CPU. Find it with ps, then stop it. Do not touch the database or the web server.", + par: 3, + hints: [ + "ps aux lists every process. Look at the %CPU column and note the PID.", + "kill PID asks the process to stop. Some programs ignore that polite request.", + "If it is still there in ps aux, force it with kill -9 PID.", + ], + files: base(), + procs: PROCS, + objectives: [ + { label: "List the processes and find the one using the CPU", done: (s) => ran(s, /\bps\b|\bpgrep\b/) }, + { label: "Stop the runaway process", done: (s) => !s.procs.some((p) => p.pid === 4242) }, + { label: "Leave the database and the web server running", done: (s) => !s.procs.some((p) => p.pid === 4242) && s.procs.some((p) => p.pid === 311) && s.procs.some((p) => p.pid === 520) }, + ], + goal: (s) => !s.procs.some((p) => p.pid === 4242) && s.procs.some((p) => p.pid === 311) && s.procs.some((p) => p.pid === 520), + solution: ["ps aux", "kill 4242", "kill -9 4242"], +}; + +const NOTES = lines("project notes", "1. ship the report", "2. call the vendor"); + +const fixPermissions: Mission = { + id: "linux-script-permissions", + difficulty: "medium", + title: "Script will not run", + brief: "backup.sh says Permission denied. Fix its permissions and run it.", + story: "The nightly backup script was copied to the server, but it will not start. Fix it, then run it once so the notes are backed up into ~/backup.", + cwd: "/home/ops/scripts", + par: 3, + hints: [ + "Run ./backup.sh and read the error. Then ls -l shows the permission letters (rw-r--r--).", + "There is no x (execute) in the letters. chmod +x adds it.", + "chmod +x backup.sh and then ./backup.sh", + ], + files: { + ...base(), + "/home/ops/scripts/backup.sh": { + content: lines("#!/bin/bash", 'echo "Starting backup..."', "cp /home/ops/data/notes.txt /home/ops/backup/notes.txt", 'echo "Backup complete"'), + mode: 0o644, + }, + "/home/ops/scripts/cleanup.sh": { content: lines("#!/bin/bash", 'echo "Cleaning..."'), mode: 0o755 }, + "/home/ops/data/notes.txt": NOTES, + "/home/ops/backup/": {}, + }, + objectives: [ + { label: "Check the permissions of backup.sh", done: (s) => ran(s, /\bls\b[^|;&]*-[a-zA-Z]*l/) || saw(s, "Permission denied") }, + { label: "Make backup.sh executable", done: (s) => ((s.fs.peek("/home/ops/scripts/backup.sh")?.mode ?? 0) & 0o100) !== 0 }, + { label: "Run it so the notes are backed up", done: (s) => s.fs.text("/home/ops/backup/notes.txt") === NOTES }, + ], + goal: (s) => ((s.fs.peek("/home/ops/scripts/backup.sh")?.mode ?? 0) & 0o100) !== 0 && s.fs.text("/home/ops/backup/notes.txt") === NOTES, + solution: ["ls -l", "chmod +x backup.sh", "./backup.sh"], +}; + +const fullDisk: Mission = { + id: "linux-full-disk", + difficulty: "medium", + title: "Who fills /var?", + brief: "The disk is 97 percent full. Find which folder directly under /var uses the most space.", + story: "An alert says the disk is almost full, and most of it is under /var. Use du to measure the folders and find the culprit. Submit its full path.", + par: 3, + hints: [ + "df -h shows how full each disk is.", + "du -sh PATH prints the total size of one folder. The * matches every folder: du -sh /var/*", + "Look for the biggest number (G is bigger than M), then submit its path, like /var/xyz", + ], + files: { + ...base(), + "/var/backups/db-2025-12-01.dump": { content: "dump", size: 1_900_000_000 }, + "/var/backups/db-2025-12-15.dump": { content: "dump", size: 1_850_000_000 }, + "/var/backups/db-2025-12-29.dump": { content: "dump", size: 1_800_000_000 }, + "/var/lib/mysql/ibdata1": { content: "db", size: 900_000_000 }, + "/var/lib/dpkg/status": "package list\n", + "/var/cache/apt/archives/libfoo.deb": { content: "deb", size: 120_000_000 }, + "/var/cache/apt/archives/libbar.deb": { content: "deb", size: 60_000_000 }, + "/var/log/syslog": { content: "log", size: 150_000_000 }, + "/var/log/app.log": { content: "log", size: 140_000_000 }, + "/var/spool/cron/": { owner: "root", mode: 0o700 }, + "/var/spool/cron/root": { content: "0 3 * * * backup\n", owner: "root", mode: 0o600 }, + "/var/tmp/scratch.txt": "scratch\n", + }, + df: [ + ["/dev/sda1", "20G", "19G", "600M", "97%", "/"], + ["tmpfs", "2.0G", "0", "2.0G", "0%", "/dev/shm"], + ], + answer: ["/var/backups"], + pathAnswer: true, + objectives: [ + { label: "Check how full the disk is", done: (s) => ran(s, /\bdf\b/) }, + { label: "Measure the folders under /var", done: (s) => ran(s, /\bdu\b/) }, + { label: "Submit the path of the biggest folder", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["df -h", "du -sh /var/*", "submit /var/backups"], +}; + +// ---------------------------------------------------------------- hard + +const topAttacker: Mission = { + id: "linux-top-attacker", + difficulty: "hard", + title: "Who is attacking?", + brief: "Find the IP address with the most failed logins in the login log.", + story: "Someone is guessing passwords. The log /var/log/auth.log has thousands of lines, and some are normal logins that you must ignore. Which IP address failed the most?", + par: 3, + hints: [ + "Keep only the failed lines first: grep 'Failed password' /var/log/auth.log", + "grep -o -E '([0-9]+\\.){3}[0-9]+' prints only the IP address of each line.", + "Then: sort | uniq -c | sort -rn | head -3 counts each IP and shows the top ones. Submit the top IP.", + ], + files: { ...base(), "/var/log/auth.log": AUTH_HARD.text }, + answer: ["203.0.113.77"], + objectives: [ + { label: "Keep only the Failed password lines", done: (s) => ran(s, /grep[^|]*failed password/i) }, + { label: "Count how often each IP address appears", done: (s) => ran(s, /uniq\s+-c/) && ran(s, /sort/) }, + { label: "Submit the IP address with the most failures", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: [ + "grep 'Failed password' /var/log/auth.log | grep -o -E '([0-9]+\\.){3}[0-9]+' | sort | uniq -c | sort -rn | head -3", + "submit 203.0.113.77", + ], +}; + +const CONF_START = lines("# orbit-web config", "name=orbit-web", "port=8080", "max_connections=50", "debug=true", "log_level=info"); + +function confLines(s: ShellState): string[] | null { + const t = s.fs.text("/home/ops/app/app.conf"); + return t === null ? null : t.split("\n").map((x) => x.trim()).filter((x) => x && !x.startsWith("#")); +} +const hasOnce = (l: string[], key: string, value: string): boolean => l.filter((x) => x.startsWith(key + "=")).length === 1 && l.includes(`${key}=${value}`); + +const editConfig: Mission = { + id: "linux-edit-config", + difficulty: "hard", + title: "Tune the config", + brief: "Edit ~/app/app.conf: max_connections=200, debug=false, and a new line cache_ttl=300. Keep every other setting.", + story: "Tonight the app goes to production. The config must change: more connections, debug off, and a cache time. There is no editor here, so use redirects and filters. Careful: > replaces a whole file.", + par: 4, + hints: [ + "echo 'cache_ttl=300' >> app.conf adds a line. One > would erase the file, so use >> to add.", + "sed -i 's/old/new/' FILE changes text inside the file. Try it for max_connections=50.", + "Or rebuild the file: grep -v removes lines, > writes to a new file, then mv it over the old one. Never write > onto the file you are reading.", + ], + files: { ...base(), "/home/ops/app/app.conf": CONF_START, "/home/ops/app/main.py": "print('hello')\n" }, + objectives: [ + { label: "max_connections is 200 (and only once)", done: (s) => { const l = confLines(s); return !!l && hasOnce(l, "max_connections", "200"); } }, + { label: "debug is false (and only once)", done: (s) => { const l = confLines(s); return !!l && hasOnce(l, "debug", "false"); } }, + { + label: "cache_ttl=300 is added and the other settings are kept", + done: (s) => { const l = confLines(s); return !!l && hasOnce(l, "cache_ttl", "300") && l.includes("name=orbit-web") && l.includes("port=8080") && l.includes("log_level=info"); }, + }, + ], + goal: (s) => { + const l = confLines(s); + return !!l && hasOnce(l, "max_connections", "200") && hasOnce(l, "debug", "false") && hasOnce(l, "cache_ttl", "300") && l.includes("name=orbit-web") && l.includes("port=8080") && l.includes("log_level=info"); + }, + solution: ["cd app", "sed -i 's/max_connections=50/max_connections=200/' app.conf", "sed -i 's/debug=true/debug=false/' app.conf", "echo cache_ttl=300 >> app.conf"], +}; + +const trail: Mission = { + id: "linux-follow-the-trail", + difficulty: "hard", + title: "Follow the trail", + brief: "Alice left a trail of notes across users and folders. Follow it to the current vault code.", + story: "Alice left the company and her notes are scattered. Start with mission.txt in your home folder and follow the trail. Some doors are locked, and some notes are old or wrong. You are in the dev group.", + groups: ["dev"], + par: 7, + hints: [ + "Read mission.txt first. Each note tells you where the next one is.", + "grep -r WORD FOLDER searches inside all files of a folder. Use it for the word HANDOVER under /srv. Two files match: trust the one from Bob.", + "In Bob's vault, grep -r CODE /home/bob/.vault shows every code with its file. Ignore the ones marked expired or draft.", + ], + files: { + ...base(), + "/home/ops/mission.txt": lines("Mission: find the current vault code.", "Alice started an audit trail before she left.", "Her first note is /home/alice/notes/note1.txt. Read it and follow the trail."), + "/home/alice/notes/note1.txt": lines("Audit trail, step 1.", "I handed this over to Bob. His handover note is somewhere under /srv.", "It contains the word HANDOVER. Use grep -r to find it."), + "/srv/shared/projects/alpha/readme.txt": "Alpha project. Nothing here.\n", + "/srv/shared/projects/beta/todo.txt": "TODO: renew certificates\n", + "/srv/shared/archive/old-handover.txt": lines("Old HANDOVER from 2023. Ignore this one.", "The vault used to be in /home/carol/vault."), + "/srv/shared/handover/bob-note.txt": { content: lines("HANDOVER note from Bob.", "I moved the vault code into my private vault folder: /home/bob/.vault", "Ignore any file marked expired or draft."), owner: "bob", group: "dev", mode: 0o640 }, + "/home/bob/": { owner: "bob", group: "dev", mode: 0o750 }, + "/home/bob/.vault/": { owner: "bob", group: "dev", mode: 0o750 }, + "/home/bob/.vault/code-2023.txt": { content: "VAULT CODE: OLD-0001 (expired)\n", owner: "bob", group: "dev", mode: 0o640, age: 400 }, + "/home/bob/.vault/code-current.txt": { content: "VAULT CODE: ORBIT-7731\n", owner: "bob", group: "dev", mode: 0o640, age: 3 }, + "/home/bob/.vault/code-new.txt": { content: "VAULT CODE: NEXT-0000 (draft, not approved)\n", owner: "bob", group: "dev", mode: 0o640, age: 1 }, + "/home/carol/": { owner: "carol", mode: 0o700 }, + "/home/carol/vault/secret.txt": { content: "carol private\n", owner: "carol", mode: 0o600 }, + }, + answer: ["ORBIT-7731"], + objectives: [ + { label: "Read Alice's first note", done: (s) => saw(s, "Audit trail, step 1") }, + { label: "Find and read Bob's handover note", done: (s) => saw(s, "HANDOVER note from Bob") }, + { label: "Open Bob's vault and find the valid code", done: (s) => saw(s, "VAULT CODE: ORBIT-7731") }, + { label: "Submit the vault code with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: [ + "cat mission.txt", + "cat /home/alice/notes/note1.txt", + "grep -r HANDOVER /srv", + "cat /srv/shared/handover/bob-note.txt", + "grep -r CODE /home/bob/.vault", + "submit ORBIT-7731", + ], +}; + +const LIVE_KEY = "acme_live_51Hx9QzLmN3pRtUvWxYz2A4b"; + +const leakedSecret: Mission = { + id: "linux-leaked-secret", + difficulty: "hard", + title: "The leaked key", + brief: "A live payment key was committed by mistake. Find the file that holds it.", + story: "The payment provider warns that a live key leaked into the code. Live keys start with acme_live_ followed by 24 letters and digits. Search /srv/app, ignore test keys and placeholders, and submit the path of the file with the real key.", + par: 3, + hints: [ + "grep -r searches every file in a folder. Try: grep -r acme_live_ /srv/app", + "Some hits are only examples. The real key has 24 letters and digits right after acme_live_.", + "A stricter search: grep -rE 'acme_live_[A-Za-z0-9]{24}' /srv/app. Then: submit THE-PATH", + ], + files: { + ...base(), + "/srv/app/src/main.py": lines("import os", 'API_KEY = os.environ["API_KEY"]', "def run():", " print('running')"), + "/srv/app/src/config.py": lines('SECRET_KEY = "changeme"', 'PAY_KEY = "acme_test_4eC39HqLyjWDarjtT1zdp7dc"'), + "/srv/app/tests/fixtures.py": lines('LIVE_KEY_PLACEHOLDER = "acme_live_REPLACE_ME_BEFORE_USE"'), + "/srv/app/docs/payments.md": lines("# Payments", "Live keys look like acme_live_<24 characters>. Never commit them."), + "/srv/app/.env.example": lines("DB_URL=postgres://localhost/app", "PAY_KEY=acme_test_xxxxxxxxxxxxxxxxxxxxxxxx", "SECRET_KEY=changeme"), + "/srv/app/old/deploy.env.bak": lines("# backup of the old deploy settings", "DB_URL=postgres://db.internal/app", `PAY_KEY=${LIVE_KEY}`, "DEBUG=false"), + "/srv/secrets/": { owner: "root", mode: 0o700 }, + "/srv/secrets/vault.txt": { content: "locked\n", owner: "root", mode: 0o600 }, + }, + answer: ["/srv/app/old/deploy.env.bak"], + pathAnswer: true, + objectives: [ + { label: "Search the code for acme_live_", done: (s) => ran(s, /grep[^|;&]*sk_live/) }, + { label: "Spot the real key among the placeholders", done: (s) => saw(s, LIVE_KEY) }, + { label: "Submit the path of the file with the key", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["grep -rE 'acme_live_[A-Za-z0-9]{24}' /srv/app", "submit /srv/app/old/deploy.env.bak"], +}; + +const PROD_YML = lines("version: 8", "replicas: 4", "debug: false"); + +const restoreFile: Mission = { + id: "linux-restore-backup", + difficulty: "hard", + title: "Oops, deleted", + brief: "prod.yml was deleted from ~/site/config. Restore the newest copy from the backups.", + story: "A cleanup script removed ~/site/config/prod.yml. The backups are in /backups (daily and weekly, with the date in the folder name). Restore the newest copy that still has the file, and do not damage the backups.", + par: 3, + hints: [ + "find /backups -name prod.yml shows every copy of the file.", + "The date is in the folder name. The newest daily folder that has the file is the best copy. The 12-31 backup was taken after the deletion.", + "cp SOURCE ~/site/config/ puts a copy back. Use cat to check it says version 8.", + ], + files: { + ...base(), + "/home/ops/site/index.html": lines("

Orbit

"), + "/home/ops/site/config/app.yml": lines("name: orbit", "port: 80"), + "/backups/weekly/2025-12-21/site/config/prod.yml": { content: lines("version: 3", "replicas: 2"), age: 11 }, + "/backups/daily/2025-12-27/site/config/prod.yml": { content: lines("version: 5", "replicas: 3"), age: 5 }, + "/backups/daily/2025-12-28/site/config/prod.yml": { content: lines("version: 6", "replicas: 3"), age: 4 }, + "/backups/daily/2025-12-29/site/config/prod.yml": { content: lines("version: 7", "replicas: 4"), age: 3 }, + "/backups/daily/2025-12-30/site/config/prod.yml": { content: PROD_YML, age: 2 }, + "/backups/daily/2025-12-31/site/config/app.yml": { content: lines("name: orbit", "port: 80"), age: 1 }, + }, + objectives: [ + { label: "Find the copies of prod.yml in /backups", done: (s) => saw(s, "2025-12-30/site/config/prod.yml") || saw(s, "2025-12-30") }, + { label: "Put prod.yml back in ~/site/config", done: (s) => exists(s, "/home/ops/site/config/prod.yml") }, + { + label: "It is the newest version, and the backups are untouched", + done: (s) => s.fs.text("/home/ops/site/config/prod.yml") === PROD_YML && s.fs.text("/backups/daily/2025-12-30/site/config/prod.yml") === PROD_YML, + }, + ], + goal: (s) => s.fs.text("/home/ops/site/config/prod.yml") === PROD_YML && s.fs.text("/backups/daily/2025-12-30/site/config/prod.yml") === PROD_YML, + solution: ["find /backups -name prod.yml", "cp /backups/daily/2025-12-30/site/config/prod.yml ~/site/config/"], +}; + +/** The pool. A day shows one mission per difficulty; each tier rotates through its missions. */ +export const MISSIONS: Mission[] = [ + hiddenNote, configPort, countLines, biggestFile, + failedLogins, oldTmp, runaway, fixPermissions, fullDisk, + topAttacker, editConfig, trail, leakedSecret, restoreFile, +]; + +const BY_ID = new Map(MISSIONS.map((m) => [m.id, m])); + +export function missionById(id: unknown): Mission | null { + return typeof id === "string" ? BY_ID.get(id) ?? null : null; +} diff --git a/frontend/src/shared/games/linux/model.ts b/frontend/src/shared/games/linux/model.ts new file mode 100644 index 00000000..4360f1af --- /dev/null +++ b/frontend/src/shared/games/linux/model.ts @@ -0,0 +1,92 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// Shared types for the Linux Command Explorer engine. +import type { Difficulty } from "../types"; +import type { FsSpec, User, VFS } from "./fs"; + +export type Proc = { + pid: number; + user: string; + cpu: number; + mem: number; + vsz: number; + rss: number; + tty?: string; + stat: string; + start: string; + time: string; + command: string; + /** A gentle `kill` (TERM) does not stop it. Only `kill -9` does. */ + ignoresTerm?: boolean; +}; + +/** One row of `df -h`: filesystem, size, used, avail, use%, mount point. */ +export type DfRow = [string, string, string, string, string, string]; + +/** Everything a goal check may look at. It is the whole state of the shell after a command. */ +export type ShellState = { + fs: VFS; + user: User; + hostname: string; + cwd: string; + oldpwd: string; + env: Record; + procs: Proc[]; + df: DfRow[]; + /** Every command line the player ran, in order (only the ones the shell accepted). */ + history: string[]; + /** All the text shown on the terminal so far (the end of it, when it gets long). */ + shown: string; + /** The player gave the right answer with `submit`. */ + answerOk: boolean; + /** Scripts that were run, with their exit codes. */ + executed: Array<{ path: string; code: number }>; +}; + +export type Objective = { + label: string; + /** Once true, the shell keeps it ticked. */ + done: (s: ShellState) => boolean; +}; + +export type Mission = { + id: string; + difficulty: Difficulty; + title: string; + brief: string; + story: string; + /** The number of commands a good player needs. Three stars need this many or fewer. */ + par: number; + hints: string[]; + files: FsSpec; + /** Where the player starts. Default is the home folder. */ + cwd?: string; + /** Extra groups for the player (the player is "ops"). */ + groups?: string[]; + procs?: Proc[]; + df?: DfRow[]; + /** For an answer mission: the accepted answers for `submit`. */ + answer?: string[]; + /** The answer is a path, so "backups" and "/var/backups/" both count. */ + pathAnswer?: boolean; + objectives: Objective[]; + /** The mission is done when this is true. For an answer mission it is `s.answerOk`. */ + goal: (s: ShellState) => boolean; + /** A list of commands that solves the mission. The tests replay it. */ + solution: string[]; +}; + +/** What a command can do while it runs. */ +export type Ctx = { + st: ShellState; + args: string[]; + stdin: string | null; + /** The output goes to the screen, not into a pipe or a file. */ + tty: boolean; + out(text: string): void; + /** One line on standard error (a newline is added). */ + err(message: string): void; + /** Run another command and capture what it prints. */ + exec(argv: string[], stdin: string | null): { code: number; out: string }; +}; + +export type Cmd = (c: Ctx) => number; diff --git a/frontend/src/shared/games/linux/regex.ts b/frontend/src/shared/games/linux/regex.ts new file mode 100644 index 00000000..f026bddd --- /dev/null +++ b/frontend/src/shared/games/linux/regex.ts @@ -0,0 +1,496 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// Pattern matching for grep, sed and find. The regular expression engine is a small NFA simulator +// (no backtracking), so a hostile pattern cannot hang the game. A work budget stops anything big. + +export class BudgetError extends Error {} + +let budgetLeft = 0; + +/** Start a new work allowance. The shell calls this before every command line. */ +export function resetBudget(units: number): void { + budgetLeft = units; +} + +export function spend(units = 1): void { + budgetLeft -= units; + if (budgetLeft < 0) throw new BudgetError("budget"); +} + +// ---------------------------------------------------------------- glob + +type GlobTok = { t: "lit"; c: string } | { t: "one" } | { t: "star" } | { t: "set"; neg: boolean; items: Array<[string, string]> }; + +function globTokens(pattern: string): GlobTok[] { + const toks: GlobTok[] = []; + for (let i = 0; i < pattern.length; i++) { + const ch = pattern[i]!; + if (ch === "\\" && i + 1 < pattern.length) { + toks.push({ t: "lit", c: pattern[++i]! }); + } else if (ch === "*") { + if (toks.length === 0 || toks[toks.length - 1]!.t !== "star") toks.push({ t: "star" }); + } else if (ch === "?") { + toks.push({ t: "one" }); + } else if (ch === "[") { + let j = i + 1; + let neg = false; + if (pattern[j] === "!" || pattern[j] === "^") { + neg = true; + j++; + } + const items: Array<[string, string]> = []; + let first = true; + let closed = false; + while (j < pattern.length) { + const c = pattern[j]!; + if (c === "]" && !first) { + closed = true; + break; + } + first = false; + if (pattern[j + 1] === "-" && j + 2 < pattern.length && pattern[j + 2] !== "]") { + items.push([c, pattern[j + 2]!]); + j += 3; + } else { + items.push([c, c]); + j++; + } + } + if (closed) { + toks.push({ t: "set", neg, items }); + i = j; + } else toks.push({ t: "lit", c: "[" }); + } else toks.push({ t: "lit", c: ch }); + } + return toks; +} + +function globOne(tok: GlobTok, ch: string): boolean { + if (tok.t === "lit") return tok.c === ch; + if (tok.t === "one") return true; + if (tok.t === "set") return tok.items.some(([a, b]) => ch >= a && ch <= b) !== tok.neg; + return false; +} + +/** Shell and `find -name` patterns: * ? [abc] [a-z] [!x]. */ +export function globMatch(pattern: string, text: string, ignoreCase = false): boolean { + const toks = globTokens(ignoreCase ? pattern.toLowerCase() : pattern); + const s = ignoreCase ? text.toLowerCase() : text; + let p = 0; + let i = 0; + let starP = -1; + let starI = 0; + while (i < s.length) { + spend(1); + const tok = toks[p]; + if (tok && tok.t === "star") { + starP = p++; + starI = i; + } else if (tok && globOne(tok, s[i]!)) { + p++; + i++; + } else if (starP >= 0) { + p = starP + 1; + i = ++starI; + } else return false; + } + while (toks[p] && toks[p]!.t === "star") p++; + return p === toks.length; +} + +export function hasGlob(text: string): boolean { + return /[*?[]/.test(text); +} + +// ---------------------------------------------------------------- regular expressions + +type Ast = + | { t: "char"; c: string } + | { t: "any" } + | { t: "set"; neg: boolean; items: Array<[string, string]> } + | { t: "cat"; a: Ast[] } + | { t: "alt"; a: Ast[] } + | { t: "rep"; n: Ast; min: number; max: number } + | { t: "assert"; k: "bol" | "eol" | "wordb" | "nwordb" | "wstart" | "wend" | "nwprev" | "nwnext" }; + +const CLASSES: Record boolean> = { + alpha: (c) => /[A-Za-z]/.test(c), + digit: (c) => /[0-9]/.test(c), + alnum: (c) => /[A-Za-z0-9]/.test(c), + upper: (c) => /[A-Z]/.test(c), + lower: (c) => /[a-z]/.test(c), + space: (c) => /\s/.test(c), + blank: (c) => c === " " || c === "\t", + punct: (c) => /[!-/:-@[-`{-~]/.test(c), + xdigit: (c) => /[0-9A-Fa-f]/.test(c), + word: (c) => /[A-Za-z0-9_]/.test(c), +}; + +const isWord = (c: string | undefined) => c !== undefined && /[A-Za-z0-9_]/.test(c); + +class RegexError extends Error {} + +type Tok = { k: "lit" | "op" | "cls" | "end"; c: string; len: number }; + +class Parser { + i = 0; + constructor( + private src: string, + private ere: boolean, + ) {} + + private peek(): Tok { + const s = this.src; + if (this.i >= s.length) return { k: "end", c: "", len: 0 }; + const ch = s[this.i]!; + if (ch === "\\") { + if (this.i + 1 >= s.length) throw new RegexError("Trailing backslash"); + const nx = s[this.i + 1]!; + if (!this.ere && "(){}|+?".includes(nx)) return { k: "op", c: nx, len: 2 }; + if ("wWsSbB<>".includes(nx)) return { k: "cls", c: nx, len: 2 }; + if (nx >= "1" && nx <= "9") throw new RegexError("Back references are not supported here"); + return { k: "lit", c: nx, len: 2 }; + } + if (this.ere && "(){}|+?".includes(ch)) return { k: "op", c: ch, len: 1 }; + if ("*.[^$".includes(ch)) return { k: "op", c: ch, len: 1 }; + return { k: "lit", c: ch, len: 1 }; + } + + parse(): Ast { + const ast = this.alt(0); + if (this.i < this.src.length) throw new RegexError("Unmatched ) or \\)"); + return ast; + } + + private alt(depth: number): Ast { + const parts = [this.cat(depth)]; + for (;;) { + const t = this.peek(); + if (t.k === "op" && t.c === "|") { + this.i += t.len; + parts.push(this.cat(depth)); + } else break; + } + return parts.length === 1 ? parts[0]! : { t: "alt", a: parts }; + } + + private cat(depth: number): Ast { + const items: Ast[] = []; + for (;;) { + const t = this.peek(); + if (t.k === "end") break; + if (t.k === "op" && t.c === "|") break; + if (t.k === "op" && t.c === ")") { + if (depth > 0) break; + if (this.ere) { + // A lone ")" is a plain character in ERE. + this.i += t.len; + items.push({ t: "char", c: ")" }); + continue; + } + throw new RegexError("Unmatched ) or \\)"); + } + let atom = this.atom(items.length === 0, depth); + for (;;) { + const q = this.peek(); + if (q.k !== "op") break; + if (q.c === "*") { + this.i += q.len; + atom = { t: "rep", n: atom, min: 0, max: Infinity }; + } else if (q.c === "+") { + this.i += q.len; + atom = { t: "rep", n: atom, min: 1, max: Infinity }; + } else if (q.c === "?") { + this.i += q.len; + atom = { t: "rep", n: atom, min: 0, max: 1 }; + } else if (q.c === "{") { + const range = this.interval(q.len); + if (!range) break; + atom = { t: "rep", n: atom, min: range[0], max: range[1] }; + } else break; + } + items.push(atom); + } + return items.length === 1 ? items[0]! : { t: "cat", a: items }; + } + + private interval(openLen: number): [number, number] | null { + const m = /^(\d*)(,(\d*))?/.exec(this.src.slice(this.i + openLen)); + if (!m || (m[1] === "" && m[3] === undefined)) return null; + const after = this.i + openLen + m[0].length; + const close = this.ere ? this.src[after] === "}" : this.src.slice(after, after + 2) === "\\}"; + if (!close) { + if (this.ere) return null; + throw new RegexError("Unmatched { or \\{"); + } + const min = m[1] === "" ? 0 : Number(m[1]); + const max = m[2] === undefined ? min : m[3] === "" ? Infinity : Number(m[3]); + if (min > 100 || (max !== Infinity && max > 100) || max < min) throw new RegexError("Invalid content of \\{\\}"); + this.i = after + (this.ere ? 1 : 2); + return [min, max]; + } + + private atom(first: boolean, depth: number): Ast { + const t = this.peek(); + this.i += t.len; + if (t.k === "lit") return { t: "char", c: t.c }; + if (t.k === "cls") { + switch (t.c) { + case "w": return { t: "set", neg: false, items: [["a", "z"], ["A", "Z"], ["0", "9"], ["_", "_"]] }; + case "W": return { t: "set", neg: true, items: [["a", "z"], ["A", "Z"], ["0", "9"], ["_", "_"]] }; + case "s": return { t: "set", neg: false, items: [[" ", " "], ["\t", "\t"]] }; + case "S": return { t: "set", neg: true, items: [[" ", " "], ["\t", "\t"]] }; + case "b": return { t: "assert", k: "wordb" }; + case "B": return { t: "assert", k: "nwordb" }; + case "<": return { t: "assert", k: "wstart" }; + default: return { t: "assert", k: "wend" }; + } + } + // t.k === "op" from here + switch (t.c) { + case ".": return { t: "any" }; + case "[": return this.bracket(); + case "^": { + if (this.ere || first) return { t: "assert", k: "bol" }; + return { t: "char", c: "^" }; + } + case "$": { + const nx = this.peek(); + const atEnd = nx.k === "end" || (nx.k === "op" && (nx.c === "|" || nx.c === ")")); + if (this.ere || atEnd) return { t: "assert", k: "eol" }; + return { t: "char", c: "$" }; + } + case "*": return { t: "char", c: "*" }; + case "(": { + const inner = this.alt(depth + 1); + const close = this.peek(); + if (!(close.k === "op" && close.c === ")")) throw new RegexError("Unmatched ( or \\("); + this.i += close.len; + return inner; + } + case "{": return { t: "char", c: "{" }; + default: return { t: "char", c: t.c }; + } + } + + private bracket(): Ast { + const s = this.src; + let neg = false; + if (s[this.i] === "^") { + neg = true; + this.i++; + } + const items: Array<[string, string]> = []; + let first = true; + for (;;) { + if (this.i >= s.length) throw new RegexError("Unmatched [, [^, [:, [., or [="); + const c = s[this.i]!; + if (c === "]" && !first) { + this.i++; + break; + } + first = false; + if (c === "[" && s[this.i + 1] === ":") { + const end = s.indexOf(":]", this.i + 2); + if (end < 0) throw new RegexError("Unmatched [, [^, [:, [., or [="); + const name = s.slice(this.i + 2, end); + const fn = CLASSES[name]; + if (!fn) throw new RegexError("Invalid character class name"); + for (let code = 1; code < 128; code++) { + const ch = String.fromCharCode(code); + if (fn(ch)) items.push([ch, ch]); + } + this.i = end + 2; + continue; + } + if (s[this.i + 1] === "-" && this.i + 2 < s.length && s[this.i + 2] !== "]") { + if (s[this.i + 2]! < c) throw new RegexError("Invalid range end"); + items.push([c, s[this.i + 2]!]); + this.i += 3; + } else { + items.push([c, c]); + this.i++; + } + } + return { t: "set", neg, items }; + } +} + +// An NFA built from the tree. State kinds: c char, a any, s set, p split, x assert, m match. +type State = { k: "c" | "a" | "s" | "p" | "x" | "m"; c?: string; set?: Extract; a: number; b: number; as?: string }; + +const MAX_STATES = 4000; + +function build(ast: Ast, ignoreCase: boolean): { states: State[]; start: number } { + const states: State[] = []; + const add = (s: State): number => { + if (states.length >= MAX_STATES) throw new RegexError("Regular expression too big"); + states.push(s); + return states.length - 1; + }; + const match = add({ k: "m", a: -1, b: -1 }); + const comp = (n: Ast, next: number): number => { + switch (n.t) { + case "char": return add({ k: "c", c: ignoreCase ? n.c.toLowerCase() : n.c, a: next, b: -1 }); + case "any": return add({ k: "a", a: next, b: -1 }); + case "set": return add({ k: "s", set: n, a: next, b: -1 }); + case "assert": return add({ k: "x", as: n.k, a: next, b: -1 }); + case "cat": { + let cur = next; + for (let i = n.a.length - 1; i >= 0; i--) cur = comp(n.a[i]!, cur); + return cur; + } + case "alt": { + let cur = comp(n.a[n.a.length - 1]!, next); + for (let i = n.a.length - 2; i >= 0; i--) cur = add({ k: "p", a: comp(n.a[i]!, next), b: cur }); + return cur; + } + case "rep": { + let cur = next; + if (n.max === Infinity) { + const split = add({ k: "p", a: -1, b: next }); + states[split]!.a = comp(n.n, split); + cur = split; + } else { + for (let i = 0; i < n.max - n.min; i++) cur = add({ k: "p", a: comp(n.n, cur), b: next }); + } + for (let i = 0; i < n.min; i++) cur = comp(n.n, cur); + return cur; + } + } + }; + return { states, start: comp(ast, match) }; +} + +export type Matcher = { + /** Does the pattern match anywhere in the text? */ + test(text: string): boolean; + /** The leftmost, longest match at or after `from`, as [start, end], or null. */ + find(text: string, from: number): [number, number] | null; +}; + +function setHas(set: Extract, ch: string, ignoreCase: boolean): boolean { + const hit = (c: string) => set.items.some(([a, b]) => c >= a && c <= b); + let r = hit(ch); + if (!r && ignoreCase) r = hit(ch.toLowerCase()) || hit(ch.toUpperCase()); + return r !== set.neg; +} + +function makeMatcher(ast: Ast, ignoreCase: boolean): Matcher { + const { states, start } = build(ast, ignoreCase); + const n = states.length; + const seen = new Int32Array(n).fill(-1); + let stamp = 0; + + const assertOk = (kind: string, s: string, p: number): boolean => { + const prev = isWord(s[p - 1]); + const next = isWord(s[p]); + switch (kind) { + case "bol": return p === 0; + case "eol": return p === s.length; + case "wordb": return prev !== next; + case "nwordb": return prev === next; + case "wstart": return !prev && next; + case "wend": return prev && !next; + case "nwprev": return !prev; + default: return !next; + } + }; + + // Add a state and everything reachable without reading a character. + const close = (list: number[], st: number, s: string, p: number): boolean => { + let matched = false; + const stack = [st]; + while (stack.length) { + const id = stack.pop()!; + if (id < 0 || seen[id] === stamp) continue; + seen[id] = stamp; + spend(1); + const state = states[id]!; + if (state.k === "p") { + stack.push(state.b, state.a); + } else if (state.k === "x") { + if (assertOk(state.as!, s, p)) stack.push(state.a); + } else if (state.k === "m") { + matched = true; + list.push(id); + } else list.push(id); + } + return matched; + }; + + const consumes = (state: State, ch: string): boolean => { + if (state.k === "a") return true; + if (state.k === "c") return (ignoreCase ? ch.toLowerCase() : ch) === state.c; + if (state.k === "s") return setHas(state.set!, ch, ignoreCase); + return false; + }; + + return { + test(s: string): boolean { + let cur: number[] = []; + for (let p = 0; p <= s.length; p++) { + // A new match may begin at every position. + stamp++; + const next: number[] = []; + let hit = false; + for (const id of cur) if (close(next, id, s, p)) hit = true; + if (close(next, start, s, p)) hit = true; + if (hit) return true; + cur = next; + if (p === s.length) break; + const ch = s[p]!; + const moved: number[] = []; + for (const id of cur) { + const state = states[id]!; + if (state.k !== "m" && consumes(state, ch)) moved.push(state.a); + } + cur = moved; + } + return false; + }, + find(s: string, from: number): [number, number] | null { + for (let begin = from; begin <= s.length; begin++) { + let best = -1; + stamp++; + let cur: number[] = []; + if (close(cur, start, s, begin)) best = begin; + for (let p = begin; p < s.length && cur.length; p++) { + const ch = s[p]!; + const moved: number[] = []; + for (const id of cur) { + const state = states[id]!; + if (state.k !== "m" && consumes(state, ch)) moved.push(state.a); + } + stamp++; + cur = []; + for (const id of moved) { + if (close(cur, id, s, p + 1)) best = p + 1; + } + } + if (best >= 0) return [begin, best]; + } + return null; + }, + }; +} + +export type PatternOptions = { ere: boolean; ignoreCase: boolean; fixed?: boolean; word?: boolean; line?: boolean }; + +/** Compile one or more patterns (they are joined with "or"). Returns an error text on a bad pattern. */ +export function compilePatterns(patterns: string[], opts: PatternOptions): Matcher | { error: string } { + try { + const alts: Ast[] = patterns.map((p) => { + if (p.length > 500) throw new RegexError("Regular expression too big"); + if (opts.fixed) return { t: "cat", a: [...p].map((c) => ({ t: "char", c }) as Ast) } as Ast; + return new Parser(p, opts.ere).parse(); + }); + let ast: Ast = alts.length === 1 ? alts[0]! : { t: "alt", a: alts }; + if (opts.line) ast = { t: "cat", a: [{ t: "assert", k: "bol" }, ast, { t: "assert", k: "eol" }] }; + else if (opts.word) ast = { t: "cat", a: [{ t: "assert", k: "nwprev" }, ast, { t: "assert", k: "nwnext" }] }; + return makeMatcher(ast, opts.ignoreCase); + } catch (error) { + if (error instanceof RegexError) return { error: error.message }; + if (error instanceof BudgetError) throw error; + return { error: "Invalid regular expression" }; + } +} diff --git a/frontend/src/shared/games/linux/shell.ts b/frontend/src/shared/games/linux/shell.ts new file mode 100644 index 00000000..25c65738 --- /dev/null +++ b/frontend/src/shared/games/linux/shell.ts @@ -0,0 +1,942 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +/* eslint-disable no-control-regex -- the shell engines reject or use control characters on purpose */ +// The practice shell: reads a command line, runs it on the virtual server, and keeps score for the +// mission. It runs one command at a time, so the browser can show the output as the player types. +// Nothing here touches the real file system, real processes, the clock or Math.random. +import { COMMANDS, NOT_HERE, SHELL_TIPS, USAGE } from "./commands"; +import { ERR_TEXT, NOW, VFS, can, joinPath, normalizePath, type VNode } from "./fs"; +import type { Ctx, Mission, Proc, ShellState } from "./model"; +import { BudgetError, globMatch, hasGlob, resetBudget, spend } from "./regex"; + +export const MAX_LINE = 500; +export const MAX_COMMANDS = 250; +const MAX_OUTPUT_LINES = 1500; +const MAX_BUFFER = 300_000; +const MAX_DEPTH = 4; +const WORK_BUDGET = 3_000_000; + +export type OutLine = { kind: "out" | "err" | "sys"; text: string }; +export type RunResult = { + lines: OutLine[]; + clear: boolean; + /** False when the shell refused the line (empty, too long, too many commands). It is not recorded. */ + accepted: boolean; + /** Indexes of objectives that became done with this command. */ + newlyDone: number[]; + solved: boolean; +}; +export type Progress = { done: boolean[]; solved: boolean; commands: number; hints: number; hintsTotal: number }; + +type Sink = { out(text: string): void; err(text: string): void }; + +// ---------------------------------------------------------------- parsing + +type Token = { t: "word"; raw: string } | { t: "op"; op: string }; +type Redir = { op: ">" | ">>" | "<" | "2>" | "2>>" | "2>&1"; target: string | null }; +type SimpleCmd = { words: string[]; redirs: Redir[] }; +type ListItem = { pipe: SimpleCmd[]; next: "&&" | "||" | ";" | null }; + +class SyntaxErr extends Error {} + +/** Find the ")" that closes a "$(" whose opening bracket is just before `start`. */ +function findClose(raw: string, start: number): number { + let depth = 1; + for (let i = start; i < raw.length; i++) { + const ch = raw[i]!; + if (ch === "'") { + const e = raw.indexOf("'", i + 1); + if (e < 0) return -1; + i = e; + } else if (ch === '"') { + for (i++; i < raw.length && raw[i] !== '"'; i++) if (raw[i] === "\\") i++; + } else if (ch === "\\") i++; + else if (ch === "(") depth++; + else if (ch === ")" && --depth === 0) return i; + } + return -1; +} + +function tokenize(line: string): Token[] { + const tokens: Token[] = []; + let cur = ""; + let has = false; + let plain = true; // the word so far has no quotes or escapes + const flush = () => { + if (has) tokens.push({ t: "word", raw: cur }); + cur = ""; + has = false; + plain = true; + }; + const unclosed = (q: string) => new SyntaxErr(`unexpected EOF while looking for matching \`${q}'`); + for (let i = 0; i < line.length; i++) { + const ch = line[i]!; + if (ch === " " || ch === "\t") flush(); + else if (ch === "#" && !has) break; + else if (ch === "'") { + const e = line.indexOf("'", i + 1); + if (e < 0) throw unclosed("'"); + cur += line.slice(i, e + 1); + i = e; + has = true; + plain = false; + } else if (ch === '"') { + let j = i + 1; + for (; j < line.length && line[j] !== '"'; j++) { + if (line[j] === "\\") j++; + else if (line[j] === "$" && line[j + 1] === "(") { + const e = findClose(line, j + 2); + if (e < 0) throw unclosed(")"); + j = e; + } + } + if (j >= line.length) throw unclosed('"'); + cur += line.slice(i, j + 1); + i = j; + has = true; + plain = false; + } else if (ch === "\\") { + cur += ch + (line[i + 1] ?? ""); + i++; + has = true; + plain = false; + } else if (ch === "$" && line[i + 1] === "(") { + const e = findClose(line, i + 2); + if (e < 0) throw unclosed(")"); + cur += line.slice(i, e + 1); + i = e; + has = true; + plain = false; + } else if (ch === "`") { + const e = line.indexOf("`", i + 1); + if (e < 0) throw unclosed("`"); + cur += line.slice(i, e + 1); + i = e; + has = true; + plain = false; + } else if (ch === "|" || ch === "&" || ch === ";" || ch === ">" || ch === "<") { + if (ch === ">" && has && plain && cur === "2") { + cur = ""; + has = false; + if (line[i + 1] === "&" && line[i + 2] === "1") { + tokens.push({ t: "op", op: "2>&1" }); + i += 2; + } else if (line[i + 1] === ">") { + tokens.push({ t: "op", op: "2>>" }); + i++; + } else tokens.push({ t: "op", op: "2>" }); + continue; + } + flush(); + const two = line.slice(i, i + 2); + if (two === "||" || two === "&&" || two === ">>") { + tokens.push({ t: "op", op: two }); + i++; + } else if (ch === "&") throw new SyntaxErr("background jobs (&) are not supported in this practice shell"); + else tokens.push({ t: "op", op: ch }); + } else { + cur += ch; + has = true; + } + } + flush(); + return tokens; +} + +function parseLine(line: string): ListItem[] { + const tokens = tokenize(line); + const items: ListItem[] = []; + let pipe: SimpleCmd[] = []; + let cmd: SimpleCmd = { words: [], redirs: [] }; + let pending: Redir | null = null; + const near = (op: string) => new SyntaxErr(`syntax error near unexpected token \`${op}'`); + const endCmd = (op: string) => { + if (cmd.words.length === 0 && cmd.redirs.length === 0) throw near(op); + pipe.push(cmd); + cmd = { words: [], redirs: [] }; + }; + for (const tok of tokens) { + if (tok.t === "word") { + if (pending) { + pending.target = tok.raw; + pending = null; + } else cmd.words.push(tok.raw); + continue; + } + const op = tok.op; + if (pending) throw near(op); + if (op === ">" || op === ">>" || op === "<" || op === "2>" || op === "2>>") { + pending = { op, target: null }; + cmd.redirs.push(pending); + } else if (op === "2>&1") cmd.redirs.push({ op, target: null }); + else if (op === "|") endCmd("|"); + else { + // && || ; + if (cmd.words.length === 0 && cmd.redirs.length === 0 && pipe.length === 0) { + if (op === ";" && items.length > 0) continue; + throw near(op); + } + endCmd(op); + items.push({ pipe, next: op as "&&" | "||" | ";" }); + pipe = []; + } + } + if (pending) throw new SyntaxErr("syntax error near unexpected token `newline'"); + if (cmd.words.length || cmd.redirs.length) endCmd("newline"); + else if (pipe.length) throw near("newline"); + if (pipe.length) items.push({ pipe, next: null }); + const last = items[items.length - 1]; + if (last && (last.next === "&&" || last.next === "||")) throw new SyntaxErr("syntax error: unexpected end of file"); + return items; +} + +// ---------------------------------------------------------------- the shell + +const DEFAULT_PROCS: Proc[] = [ + { pid: 1, user: "root", cpu: 0, mem: 0.1, vsz: 168000, rss: 11000, stat: "Ss", start: "Jan01", time: "0:03", command: "/sbin/init" }, + { pid: 77, user: "root", cpu: 0, mem: 0.1, vsz: 8500, rss: 2200, stat: "Ss", start: "Jan01", time: "0:00", command: "/usr/sbin/cron -f" }, + { pid: 988, user: "root", cpu: 0, mem: 0.2, vsz: 15400, rss: 6000, stat: "Ss", start: "Jan01", time: "0:00", command: "sshd: /usr/sbin/sshd -D" }, + { pid: 1204, user: "ops", cpu: 0, mem: 0.2, vsz: 9100, rss: 4800, tty: "pts/0", stat: "Ss", start: "00:00", time: "0:00", command: "-bash" }, +]; + +const FREE = new Set(["hint", "help", "commands", "man", "clear", "history"]); +const BUILTINS = ["hint", "submit", "history", "clear", "help", "commands", "man", "exit", "logout", "bash", "sh"]; +const SENTINEL: Record = { "*": "\u0001", "?": "\u0002", "[": "\u0003" }; +const UNSENTINEL = (s: string) => s.replace(/\u0001/g, "*").replace(/\u0002/g, "?").replace(/\u0003/g, "["); +const quoteGlob = (s: string) => s.replace(/[*?[]/g, (m) => SENTINEL[m]!); + +function normalizeAnswer(text: string): string { + return text.trim().replace(/^["']|["']$/g, "").replace(/\s+/g, " ").toLowerCase(); +} + +export class Shell { + readonly st: ShellState; + readonly mission: Mission; + private hintsShown = 0; + private counted = 0; + private done: boolean[]; + private solved = false; + private solvedCounted = 0; + private solvedHints = 0; + private depth = 0; + private lines: OutLine[] = []; + private cleared = false; + private lineCap = false; + private lastCode = 0; + + constructor(mission: Mission) { + this.mission = mission; + const home = "/home/ops"; + const fs = new VFS(mission.files); + this.st = { + fs, + user: { name: "ops", groups: ["ops", ...(mission.groups ?? [])] }, + hostname: "orbit-01", + cwd: normalizePath("/", mission.cwd ?? home), + oldpwd: home, + env: { HOME: home, USER: "ops", LOGNAME: "ops", SHELL: "/bin/bash", HOSTNAME: "orbit-01", PWD: mission.cwd ?? home, PATH: "/usr/local/bin:/usr/bin:/bin", LANG: "C.UTF-8", TERM: "xterm" }, + procs: (mission.procs ?? DEFAULT_PROCS).map((p) => ({ ...p })), + df: mission.df ?? [ + ["/dev/sda1", "40G", "18G", "20G", "48%", "/"], + ["tmpfs", "2.0G", "0", "2.0G", "0%", "/dev/shm"], + ["/dev/sdb1", "100G", "62G", "38G", "62%", "/srv"], + ], + history: [], + shown: "", + answerOk: false, + executed: [], + }; + this.st.env.PWD = this.st.cwd; + this.done = mission.objectives.map(() => false); + } + + // ---- what the UI reads + + prompt(): string { + const home = this.st.env.HOME ?? "/"; + let path = this.st.cwd; + if (path === home) path = "~"; + else if (path.startsWith(home + "/")) path = "~" + path.slice(home.length); + if (path.length > 18) { + const parts = path.split("/").filter(Boolean); + path = "…/" + parts.slice(-2).join("/"); + } + return `${this.st.user.name}:${path}$`; + } + + progress(): Progress { + return { done: [...this.done], solved: this.solved, commands: this.solved ? this.solvedCounted : this.counted, hints: this.solved ? this.solvedHints : this.hintsShown, hintsTotal: this.mission.hints.length }; + } + + /** Commands that counted toward par when the mission was solved (or so far). */ + get commandCount(): number { + return this.solved ? this.solvedCounted : this.counted; + } + + get hintCount(): number { + return this.solved ? this.solvedHints : this.hintsShown; + } + + get isSolved(): boolean { + return this.solved; + } + + get commands(): string[] { + return [...this.st.history]; + } + + /** Words Tab can finish: command names, then names of files and folders near the player. */ + completions(): string[] { + const names = new Set([...Object.keys(COMMANDS), ...BUILTINS]); + const add = (node: VNode, prefix: string) => { + for (const child of node.children.values()) names.add(prefix + child.name + (child.kind === "dir" ? "/" : "")); + }; + const cwdNode = this.st.fs.peek(this.st.cwd); + if (cwdNode && cwdNode.kind === "dir" && can(this.st.user, cwdNode, 4)) { + add(cwdNode, ""); + for (const child of cwdNode.children.values()) { + if (child.kind === "dir" && can(this.st.user, child, 4) && can(this.st.user, child, 1)) add(child, child.name + "/"); + else if (child.kind === "file" && (child.mode & 0o100) !== 0) names.add("./" + child.name); + } + } + add(this.st.fs.root, "/"); + for (const top of this.st.fs.root.children.values()) { + if (top.kind === "dir" && can(this.st.user, top, 4) && can(this.st.user, top, 1)) add(top, "/" + top.name + "/"); + } + return [...names].sort().slice(0, 500); + } + + bootLines(): string[] { + return [`Connecting to ${this.st.hostname} as ${this.st.user.name} ...`, "Connected. Type help to see what works, hint if you are stuck."]; + } + + // ---- running one line + + run(rawLine: string): RunResult { + this.lines = []; + this.cleared = false; + this.lineCap = false; + const line = typeof rawLine === "string" ? rawLine : ""; + const refuse = (text: string): RunResult => { + if (text) this.emit("err", text); + return { lines: this.lines, clear: false, accepted: false, newlyDone: [], solved: this.solved }; + }; + if (line.trim() === "") return refuse(""); + if (line.length > MAX_LINE) return refuse(`bash: that line is too long (more than ${MAX_LINE} characters). It was not run.`); + if (/[\u0000-\u0008\u000a-\u001f\u007f]/.test(line)) return refuse("bash: that line has control characters. It was not run."); + if (this.st.history.length >= MAX_COMMANDS) return refuse("bash: too many commands in this session. Press Reset to start again."); + + this.st.history.push(line); + this.st.fs.now = NOW + this.st.history.length * 60; + resetBudget(WORK_BUDGET); + this.depth = 0; + + let items: ListItem[] | null = null; + try { + items = parseLine(line); + } catch (error) { + this.counted++; + this.emit("err", `bash: ${error instanceof SyntaxErr ? error.message : "syntax error"}`); + this.lastCode = 2; + } + if (items) { + const free = items.length === 1 && items[0]!.pipe.length === 1 && FREE.has(this.firstWord(items[0]!.pipe[0]!)); + if (!free) this.counted++; + try { + this.runItems(items, this.topSink()); + } catch (error) { + if (error instanceof BudgetError) this.emit("err", "bash: that command was stopped because it was taking too long"); + else this.emit("err", "bash: something went wrong with that command"); + this.lastCode = 1; + } + } + + const newlyDone = this.evaluate(); + return { lines: this.lines, clear: this.cleared, accepted: true, newlyDone, solved: this.solved }; + } + + private firstWord(cmd: SimpleCmd): string { + const w = cmd.words[0] ?? ""; + return /^[a-z]+$/.test(w) ? w : ""; + } + + private evaluate(): number[] { + const newly: number[] = []; + this.mission.objectives.forEach((obj, i) => { + if (this.done[i]) return; + let ok = false; + try { + ok = obj.done(this.st); + } catch { + ok = false; + } + if (ok) { + this.done[i] = true; + newly.push(i); + } + }); + if (!this.solved) { + let ok = false; + try { + ok = this.mission.goal(this.st); + } catch { + ok = false; + } + if (ok) { + this.solved = true; + this.solvedCounted = this.counted; + this.solvedHints = this.hintsShown; + this.done.forEach((d, i) => { + if (!d) { + this.done[i] = true; + newly.push(i); + } + }); + } + } + return newly; + } + + // ---- output + + private emit(kind: OutLine["kind"], text: string): void { + const parts = text.split("\n"); + if (parts[parts.length - 1] === "") parts.pop(); + for (const part of parts) { + if (this.lines.length >= MAX_OUTPUT_LINES) { + if (!this.lineCap) { + this.lineCap = true; + this.lines.push({ kind: "sys", text: "(output cut: it was too long. Narrow it down, for example with grep or head.)" }); + } + return; + } + this.lines.push({ kind, text: part }); + } + if (kind !== "sys") this.st.shown = (this.st.shown + text + (text.endsWith("\n") ? "" : "\n")).slice(-120_000); + } + + private topSink(): Sink { + return { out: (t) => this.emit("out", t), err: (t) => this.emit("err", t) }; + } + + // ---- running a parsed line + + private runItems(items: ListItem[], sink: Sink): number { + let code = this.lastCode; + let skip: "&&" | "||" | null = null; + for (let i = 0; i < items.length; i++) { + const item = items[i]!; + if (skip === "&&" && code !== 0) { + // A failed "&&" skips this pipeline; the next connector decides again. + } else if (skip === "||" && code === 0) { + // A passed "||" skips this pipeline. + } else code = this.runPipeline(item.pipe, sink, this.depth === 0); + this.lastCode = code; + skip = item.next === "&&" || item.next === "||" ? item.next : null; + } + return code; + } + + /** Run a line inside the shell (a script line or a command substitution). */ + private runInner(line: string, sink: Sink): number { + let items: ListItem[]; + try { + items = parseLine(line); + } catch (error) { + sink.err(`bash: ${error instanceof SyntaxErr ? error.message : "syntax error"}\n`); + return 2; + } + return this.runItems(items, sink); + } + + private capture(line: string, parent: Sink): string { + if (this.depth >= MAX_DEPTH) return ""; + this.depth++; + let buf = ""; + try { + this.runInner(line, { + out: (t) => { + if (buf.length < MAX_BUFFER) buf += t; + }, + err: parent.err, + }); + } finally { + this.depth--; + } + return buf.replace(/\n+$/, ""); + } + + // ---- expansion + + private lookupVar(name: string): string { + if (name === "?") return String(this.lastCode); + if (name === "$") return "4242"; + if (name === "0") return "bash"; + return this.st.env[name] ?? ""; + } + + private expandWord(raw: string, sink: Sink): string[] { + const fields: string[] = []; + let cur = ""; + let has = false; + const env = this.st.env; + const addSplit = (text: string) => { + // An unquoted expansion splits at spaces. + const pieces = text.split(/\s+/); + pieces.forEach((piece, k) => { + if (k > 0) { + fields.push(cur); + cur = ""; + has = false; + } + if (piece !== "") { + cur += quoteGlob(piece); + has = true; + } + }); + }; + const dollar = (i: number, quoted: boolean): number => { + const nx = raw[i + 1]; + let text = ""; + let next = i + 1; + if (nx === "(" && raw[i + 2] === "(") { + throw new SyntaxErr("arithmetic like $((1+2)) is not supported in this practice shell"); + } else if (nx === "(") { + const e = findClose(raw, i + 2); + if (e < 0) throw new SyntaxErr("unexpected EOF while looking for matching `)'"); + text = this.capture(raw.slice(i + 2, e), sink); + next = e + 1; + } else if (nx === "{") { + const e = raw.indexOf("}", i + 2); + if (e < 0) throw new SyntaxErr("bad substitution"); + const body = raw.slice(i + 2, e); + const m = /^([A-Za-z_][A-Za-z0-9_]*)(?::-([\s\S]*))?$/.exec(body); + if (!m) throw new SyntaxErr("${" + body + "}: bad substitution"); + const v = this.lookupVar(m[1]!); + text = v === "" && m[2] !== undefined ? m[2] : v; + next = e + 1; + } else if (nx !== undefined && /[A-Za-z_]/.test(nx)) { + const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(raw.slice(i + 1))!; + text = this.lookupVar(m[0]); + next = i + 1 + m[0].length; + } else if (nx === "?" || nx === "$" || nx === "0") { + text = this.lookupVar(nx); + next = i + 2; + } else if (nx !== undefined && /[1-9]/.test(nx)) { + next = i + 2; + } else { + cur += "$"; + has = true; + return i + 1; + } + if (quoted) { + cur += quoteGlob(text); + has = true; + } else addSplit(text); + return next; + }; + for (let i = 0; i < raw.length; i++) { + const ch = raw[i]!; + if (ch === "'") { + const e = raw.indexOf("'", i + 1); + cur += quoteGlob(raw.slice(i + 1, e)); + has = true; + i = e; + } else if (ch === '"') { + has = true; + let j = i + 1; + while (j < raw.length && raw[j] !== '"') { + const c = raw[j]!; + if (c === "\\" && j + 1 < raw.length && '$"\\`'.includes(raw[j + 1]!)) { + cur += quoteGlob(raw[j + 1]!); + j += 2; + } else if (c === "$") j = dollar(j, true); + else if (c === "`") { + const e = raw.indexOf("`", j + 1); + cur += quoteGlob(this.capture(raw.slice(j + 1, e), sink)); + j = e + 1; + } else { + cur += quoteGlob(c); + j++; + } + } + i = j; + } else if (ch === "\\") { + const nx = raw[i + 1]; + if (nx !== undefined) { + cur += quoteGlob(nx); + has = true; + i++; + } + } else if (ch === "$") i = dollar(i, false) - 1; + else if (ch === "`") { + const e = raw.indexOf("`", i + 1); + addSplit(this.capture(raw.slice(i + 1, e), sink)); + i = e; + } else if (ch === "~" && i === 0 && (raw[1] === "/" || raw.length === 1)) { + cur += quoteGlob(env.HOME ?? "/"); + has = true; + } else { + cur += ch; + has = true; + } + } + if (has) fields.push(cur); + const out: string[] = []; + for (const f of fields) { + if (/[*?[]/.test(f)) { + const hits = this.glob(f); + if (hits.length) { + out.push(...hits); + continue; + } + } + out.push(UNSENTINEL(f)); + } + return out; + } + + /** Expand a path pattern against the virtual file system. `pattern` has real glob characters. */ + private glob(pattern: string): string[] { + // Quoted glob characters are still sentinels here and are plain letters for matching. + const absolute = pattern.startsWith("/"); + const segs = pattern.split("/").filter((s, i) => s !== "" || i === 0); + let results: Array<{ abs: string; display: string }> = [{ abs: absolute ? "/" : this.st.cwd, display: absolute ? "/" : "" }]; + for (const seg of segs) { + if (seg === "") continue; + const next: typeof results = []; + for (const r of results) { + const show = (name: string) => (r.display === "" ? name : r.display.endsWith("/") ? r.display + name : r.display + "/" + name); + if (!hasGlob(seg)) { + const lit = UNSENTINEL(seg); + if (lit === ".") next.push(r); + else next.push({ abs: normalizePath(r.abs, lit), display: show(lit) }); + continue; + } + const res = this.st.fs.walk(r.abs, this.st.user); + if (!res.node || res.node.kind !== "dir" || !can(this.st.user, res.node, 4)) continue; + const pat = seg.replace(/\u0001/g, "\\*").replace(/\u0002/g, "\\?").replace(/\u0003/g, "\\["); + for (const name of [...res.node.children.keys()].sort()) { + spend(1); + if (name.startsWith(".") && !seg.startsWith(".")) continue; + if (globMatch(pat, name)) next.push({ abs: joinPath(r.abs, name), display: show(name) }); + } + } + results = next.slice(0, 500); + } + const hits: string[] = []; + for (const r of results) { + if (this.st.fs.walk(r.abs, this.st.user).node) hits.push(r.display); + } + return hits; + } + + private expandAll(words: string[], sink: Sink): string[] | null { + try { + return words.flatMap((w) => this.expandWord(w, sink)); + } catch (error) { + if (error instanceof SyntaxErr) { + sink.err(`bash: ${error.message}\n`); + return null; + } + throw error; + } + } + + // ---- pipelines + + private runPipeline(pipe: SimpleCmd[], sink: Sink, top: boolean): number { + type Prepared = { + argv: string[]; + outTargets: Array<{ path: string; append: boolean }>; + errTarget: { path: string; append: boolean } | null; + errToOut: boolean; + stdin: string | null; + failed: boolean; + }; + const prepared: Prepared[] = []; + for (const cmd of pipe) { + const argv = this.expandAll(cmd.words, sink); + if (argv === null) return 1; + const p: Prepared = { argv, outTargets: [], errTarget: null, errToOut: false, stdin: null, failed: false }; + for (const r of cmd.redirs) { + if (r.op === "2>&1") { + p.errToOut = true; + continue; + } + const targets = this.expandAll([r.target ?? ""], sink); + if (targets === null) return 1; + if (targets.length !== 1) { + sink.err(`bash: ${r.target}: ambiguous redirect\n`); + p.failed = true; + continue; + } + const path = targets[0]!; + const abs = normalizePath(this.st.cwd, path, this.st.env.HOME ?? "/"); + if (r.op === "<") { + const res = this.st.fs.walk(abs, this.st.user); + if (!res.node) { + sink.err(`bash: ${path}: ${ERR_TEXT[res.err ?? "ENOENT"]}\n`); + p.failed = true; + } else if (res.node.kind === "dir") { + sink.err(`bash: ${path}: Is a directory\n`); + p.failed = true; + } else if (!can(this.st.user, res.node, 4)) { + sink.err(`bash: ${path}: Permission denied\n`); + p.failed = true; + } else p.stdin = res.node.content; + continue; + } + const append = r.op === ">>" || r.op === "2>>"; + if (path !== "/dev/null") { + // The shell opens (and empties) the file before the command runs. + const e = this.st.fs.writeFile(abs, this.st.user, "", append); + if (e) { + sink.err(`bash: ${path}: ${ERR_TEXT[e]}\n`); + p.failed = true; + continue; + } + } + if (r.op === ">" || r.op === ">>") p.outTargets.push({ path, append }); + else p.errTarget = { path, append }; + } + prepared.push(p); + } + + let prev: string | null = null; + let code = 0; + for (let i = 0; i < prepared.length; i++) { + const p = prepared[i]!; + const last = i === prepared.length - 1; + if (p.failed) { + code = 1; + prev = ""; + continue; + } + const toTerminal = last && p.outTargets.length === 0; + let outBuf = ""; + let errBuf = ""; + const emitOut = (t: string) => { + if (toTerminal) sink.out(t); + else if (outBuf.length < MAX_BUFFER) outBuf += t; + }; + const emitErr = (t: string) => { + if (p.errToOut) emitOut(t); + else if (p.errTarget) { + if (p.errTarget.path !== "/dev/null" && errBuf.length < MAX_BUFFER) errBuf += t; + } else sink.err(t); + }; + const local: Sink = { out: emitOut, err: emitErr }; + const stdin = i === 0 ? p.stdin : prev; + code = this.runCommand(p.argv, stdin, local, toTerminal && top); + if (p.errTarget && p.errTarget.path !== "/dev/null") { + const e = this.st.fs.writeFile(normalizePath(this.st.cwd, p.errTarget.path, this.st.env.HOME ?? "/"), this.st.user, errBuf, true); + if (e) sink.err(`bash: ${p.errTarget.path}: ${ERR_TEXT[e]}\n`); + } + for (const t of p.outTargets) { + if (t.path === "/dev/null") continue; + const e = this.st.fs.writeFile(normalizePath(this.st.cwd, t.path, this.st.env.HOME ?? "/"), this.st.user, outBuf, true); + if (e) sink.err(`bash: write error: ${ERR_TEXT[e]}\n`); + } + prev = toTerminal ? "" : outBuf; + } + return code; + } + + // ---- one command + + private runCommand(argvIn: string[], stdin: string | null, sink: Sink, tty: boolean): number { + let argv = argvIn; + // NAME=value words before the command. + const assigned: Array<[string, string | undefined]> = []; + while (argv.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(argv[0]!)) { + const eq = argv[0]!.indexOf("="); + assigned.push([argv[0]!.slice(0, eq), this.st.env[argv[0]!.slice(0, eq)]]); + this.st.env[argv[0]!.slice(0, eq)] = argv[0]!.slice(eq + 1); + argv = argv.slice(1); + } + if (argv.length === 0) return 0; + const code = this.invoke(argv, stdin, sink, tty); + if (assigned.length && argv.length) { + for (const [k, old] of assigned) { + if (old === undefined) delete this.st.env[k]; + else this.st.env[k] = old; + } + } + return code; + } + + private ctx(argv: string[], stdin: string | null, sink: Sink, tty: boolean): Ctx { + return { + st: this.st, + args: argv.slice(1), + stdin, + tty, + out: sink.out, + err: (m) => sink.err(m + "\n"), + exec: (sub, input) => { + let out = ""; + const code = this.invoke(sub, input, { out: (t) => (out.length < MAX_BUFFER ? (out += t) : out), err: sink.err }, false); + return { code, out }; + }, + }; + } + + private invoke(argv: string[], stdin: string | null, sink: Sink, tty: boolean): number { + const name = argv[0]!; + const sys = /^\/(?:usr\/)?s?bin\/([a-z]+)$/.exec(name); + if (sys && (COMMANDS[sys[1]!] || BUILTINS.includes(sys[1]!))) return this.invoke([sys[1]!, ...argv.slice(1)], stdin, sink, tty); + if (name.includes("/")) return this.runFile(name, [], sink, true); + if (argv.length === 2 && argv[1] === "--help" && USAGE[name]) { + this.help(name, sink); + return 0; + } + switch (name) { + case "hint": return this.hint(); + case "submit": return this.submit(argv.slice(1), sink); + case "history": { + this.st.history.forEach((h, i) => sink.out(`${String(i + 1).padStart(5)} ${h}\n`)); + return 0; + } + case "clear": this.cleared = true; this.lines = []; return 0; + case "help": + case "commands": this.helpAll(sink); return 0; + case "man": { + if (!argv[1]) { + sink.err("What manual page do you want? Try: man ls\n"); + return 1; + } + if (!USAGE[argv[1]]) { + sink.err(`No manual entry for ${argv[1]}. Type help to see what works.\n`); + return 16; + } + this.help(argv[1], sink); + return 0; + } + case "exit": + case "logout": + sink.out("This practice shell stays open. Keep going.\n"); + return 0; + case "bash": + case "sh": { + const file = argv.slice(1).find((a) => !a.startsWith("-")); + if (!file) { + sink.err(`${name}: give a script file to run, like: ${name} script.sh\n`); + return 2; + } + return this.runFile(file, argv.slice(2), sink, false); + } + default: + } + const fn = COMMANDS[name]; + if (fn) { + try { + return fn(this.ctx(argv, stdin, sink, tty)); + } catch (error) { + if (error instanceof BudgetError) throw error; + sink.err(`${name}: something went wrong\n`); + return 1; + } + } + const note = NOT_HERE[name]; + if (note) { + sink.err(`${name}: not available on this practice server. ${note}\n`); + return 127; + } + sink.err(`bash: ${name}: command not found\n`); + return 127; + } + + /** Run a script file with the shell itself. `needExec` is true for ./script and false for bash script. */ + private runFile(path: string, _args: string[], sink: Sink, needExec: boolean): number { + const abs = normalizePath(this.st.cwd, path, this.st.env.HOME ?? "/"); + const res = this.st.fs.walk(abs, this.st.user); + if (!res.node) { + sink.err(`bash: ${path}: ${ERR_TEXT[res.err ?? "ENOENT"]}\n`); + return 127; + } + if (res.node.kind === "dir") { + sink.err(`bash: ${path}: Is a directory\n`); + return 126; + } + const node = res.node; + if (!can(this.st.user, node, 4) || (needExec && !can(this.st.user, node, 1))) { + sink.err(`bash: ${path}: Permission denied\n`); + return 126; + } + if (this.depth >= MAX_DEPTH) { + sink.err(`bash: ${path}: too many scripts running inside each other\n`); + return 1; + } + this.depth++; + const savedCwd = this.st.cwd; + let code = 0; + try { + const lines = node.content.split("\n").slice(0, 80); + for (const line of lines) { + spend(1); + const t = line.trim(); + if (t === "" || t.startsWith("#") || t.length > MAX_LINE) continue; + code = this.runInner(t, sink); + } + } finally { + this.depth--; + this.st.cwd = savedCwd; + this.st.env.PWD = savedCwd; + } + this.st.executed.push({ path: abs, code }); + return code; + } + + // ---- game commands + + private hint(): number { + const hints = this.mission.hints; + if (this.hintsShown >= hints.length) { + this.emit("sys", "No more hints. Read the objectives again and try a new command."); + return 0; + } + this.hintsShown++; + this.emit("sys", `Hint ${this.hintsShown} of ${hints.length}: ${hints[this.hintsShown - 1]}`); + return 0; + } + + private submit(args: string[], sink: Sink): number { + const m = this.mission; + if (!m.answer) { + this.emit("sys", "This mission has no question to answer. Reach the goal with commands."); + return 1; + } + if (args.length === 0) { + sink.err("Usage: submit ANSWER\n"); + return 2; + } + const given = normalizeAnswer(args.join(" ")); + const toPath = (text: string) => normalizePath(this.st.cwd, text, this.st.env.HOME ?? "/"); + const ok = m.answer.some((a) => (m.pathAnswer ? toPath(a) === toPath(given === "" ? "." : args.join(" ").trim()) : normalizeAnswer(a) === given)); + if (ok) { + this.st.answerOk = true; + this.emit("sys", "Correct. Answer accepted."); + return 0; + } + this.emit("sys", "Not quite. Look at the output again and try once more."); + return 1; + } + + private help(name: string, sink: Sink): void { + const u = USAGE[name]; + if (!u) return; + sink.out(`${name}: ${u.desc}\nUsage: ${u.usage}\n`); + } + + private helpAll(sink: Sink): void { + sink.out("Commands that work here (type man NAME for details):\n"); + const groups = new Map(); + for (const [name, u] of Object.entries(USAGE)) groups.set(u.group, [...(groups.get(u.group) ?? []), name]); + for (const [group, names] of groups) sink.out(` ${group}: ${names.join(" ")}\n`); + sink.out(SHELL_TIPS.map((t) => ` ${t}\n`).join("")); + } +} + +export function createShell(mission: Mission): Shell { + return new Shell(mission); +} diff --git a/frontend/src/shared/games/sysdesign/engine.ts b/frontend/src/shared/games/sysdesign/engine.ts new file mode 100644 index 00000000..b280e18a --- /dev/null +++ b/frontend/src/shared/games/sysdesign/engine.ts @@ -0,0 +1,74 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// System Design Runner: each round is a production incident on a small AWS system. The player +// picks a few changes, and a deterministic traffic simulation says whether the goals are met. +import { pickDaily } from "../daily"; +import type { GameEngine, Stars, VerifyResult } from "../types"; +import { SYSDESIGN_POOL } from "./scenarios"; +import { evaluateGoals, simulate } from "./sim"; +import type { SysdesignRound, SysdesignSubmission } from "./types"; + +export type { SysdesignRound, SysdesignSubmission } from "./types"; +export type { ChangeDef, ComponentId, CostLine, GoalCheck, Goals, Model, Pricing, SimResult, StepResult, StepStatus, Stretch } from "./types"; +export { STEPS } from "./types"; +export { applyChanges, costDelta, evaluateGoals, simulate } from "./sim"; +export { SYSDESIGN_POOL } from "./scenarios"; + +/** Hard ceiling on a submission, whatever the round allows. */ +const MAX_PARSED_CHANGES = 8; + +function fail(message: string): VerifyResult { + return { passed: false, stars: 0, score: 0, message }; +} + +export const sysdesignEngine: GameEngine = { + id: "sysdesign", + title: "System Design Runner", + tagline: "A real incident on a small AWS system. Pick the fixes, run the traffic, and meet the goals.", + roundsFor: (dayKey) => pickDaily(SYSDESIGN_POOL, dayKey, "sysdesign"), + + parseSubmission(input) { + if (typeof input !== "object" || input === null || Array.isArray(input)) return null; + const keys = Object.keys(input); + if (keys.length !== 1 || keys[0] !== "changes") return null; + const changes = (input as { changes?: unknown }).changes; + if (!Array.isArray(changes) || changes.length > MAX_PARSED_CHANGES) return null; + const seen = new Set(); + for (const id of changes) { + if (typeof id !== "string" || id.length === 0 || id.length > 64 || seen.has(id)) return null; + seen.add(id); + } + return { changes: [...changes] as string[] }; + }, + + verify(round, submission) { + try { + const ids = Array.isArray(submission?.changes) ? submission.changes.filter((id): id is string => typeof id === "string") : []; + if (new Set(ids).size !== ids.length) return fail("Each change can be used only once."); + if (ids.length > round.maxChanges) return fail(`You can apply at most ${round.maxChanges} changes in this round.`); + const offered = new Set(round.changes.map((c) => c.id)); + if (ids.some((id) => !offered.has(id))) return fail("One of those changes is not part of this round."); + + const sim = simulate(round, ids); + const checks = evaluateGoals(round.goals, sim); + const missed = checks.find((c) => !c.met); + if (missed) { + return { passed: false, stars: 0, score: sim.costUsd, message: `Goal missed: ${missed.label.toLowerCase()} is ${missed.actual}, the goal is ${missed.target}.` }; + } + + const stretch = round.stretch; + const tighter = (stretch.maxCostUsd === undefined || sim.costUsd <= stretch.maxCostUsd) && (stretch.maxP95Ms === undefined || sim.p95Ms <= stretch.maxP95Ms); + const lean = ids.length <= round.solution.length && !(round.trap !== undefined && ids.includes(round.trap)); + const stars: Stars = tighter ? (lean ? 3 : 2) : 1; + const target = [stretch.maxCostUsd !== undefined ? `$${stretch.maxCostUsd} a month` : "", stretch.maxP95Ms !== undefined ? `${stretch.maxP95Ms} ms p95` : ""].filter(Boolean).join(" and "); + const message = + stars === 3 + ? `All goals met with ${ids.length} change${ids.length === 1 ? "" : "s"}: p95 ${sim.p95Ms} ms, ${sim.availability}% available, $${sim.costUsd} a month.` + : stars === 2 + ? "All goals met and under the tighter target. For 3 stars, use fewer changes and skip the tempting trap." + : `All goals met. For more stars, get under the tighter target of ${target}.`; + return { passed: true, stars, score: sim.costUsd, message }; + } catch { + return fail("That set of changes could not be checked. Try again."); + } + }, +}; diff --git a/frontend/src/shared/games/sysdesign/scenarios.ts b/frontend/src/shared/games/sysdesign/scenarios.ts new file mode 100644 index 00000000..b87fa35d --- /dev/null +++ b/frontend/src/shared/games/sysdesign/scenarios.ts @@ -0,0 +1,394 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The pool of production incidents. Every round is plain data: a system, 24 hours of traffic, the +// goals, and a catalog of changes (each one a patch on the model). All prices are round, illustrative +// numbers made up for the game. They are not AWS quotes. +import type { Difficulty } from "../types"; +import { STEPS, type ChangeDef, type DeepPartial, type Model, type SysdesignRound } from "./types"; + +/** A model with sensible defaults. A scenario overrides only what it needs. */ +function model(over: DeepPartial = {}): Model { + const base: Model = { + app: { label: "m5.large", count: 4, rpsEach: 100, monthlyEach: 70, baseMs: 20, zones: 1, healthChecks: false, autoscale: false, scaleMin: 2, scaleMax: 8, pricing: "ondemand" }, + db: { kind: "rds", label: "db.m5.large", capacity: 400, monthly: 140, replicas: 0, replicaMonthly: 140, multiAz: false, pricing: "ondemand", readMs: 12, writeMs: 20, readCost: 1, skew: 1 }, + cache: { on: false, hit: 0.85, monthly: 90 }, + cdn: { on: false, offload: 0.9, monthly: 40 }, + queue: { on: false, monthly: 10 }, + batch: { separate: false, workersMonthly: 60 }, + net: { egressGb: 500, natGb: 500, s3Share: 0.7, s3Endpoint: false, natGateways: 1 }, + logs: { gb: 200, hotRate: 0.023, coldRate: 0.004, coldShare: 0 }, + }; + return { + app: { ...base.app, ...over.app }, + db: { ...base.db, ...over.db }, + cache: { ...base.cache, ...over.cache }, + cdn: { ...base.cdn, ...over.cdn }, + queue: { ...base.queue, ...over.queue }, + batch: { ...base.batch, ...over.batch }, + net: { ...base.net, ...over.net }, + logs: { ...base.logs, ...over.logs }, + }; +} + +/** Traffic for 24 hours, by straight lines between [hour, requests per second] points. */ +function shape(points: Array<[number, number]>): number[] { + const out: number[] = []; + for (let t = 0; t < STEPS; t++) { + let value = points[points.length - 1]![1]; + for (let i = 0; i < points.length - 1; i++) { + const [t0, v0] = points[i]!; + const [t1, v1] = points[i + 1]!; + if (t >= t0 && t <= t1) { + value = t1 === t0 ? v1 : v0 + ((v1 - v0) * (t - t0)) / (t1 - t0); + break; + } + } + out.push(Math.round(value)); + } + return out; +} + +/** A normal day: quiet at night, busy in the afternoon. */ +const day = (low: number, high: number) => shape([[0, low], [6, low], [11, high], [17, high], [23, low]]); + +type Scenario = SysdesignRound; + +const POOL: Scenario[] = [ + // ───────────────────────────── EASY ───────────────────────────── + { + id: "sd-bill-tripled", + difficulty: "easy", + title: "The bill tripled", + brief: "Finance says the AWS bill is three times higher than last quarter. Traffic did not grow. Cut the bill and keep the site fast.", + incident: "COST ALERT: monthly spend is 3x the budget. Servers and database run at under 10% busy.", + model: model({ + app: { label: "m5.2xlarge", count: 6, rpsEach: 400, monthlyEach: 280 }, + db: { label: "db.r5.2xlarge", capacity: 2400, monthly: 700 }, + net: { egressGb: 1500, natGb: 400 }, + }), + traffic: day(25, 90), + mix: { staticShare: 0.3, readShare: 0.8 }, + goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 700 }, + stretch: { maxCostUsd: 520 }, + changes: [ + { id: "rightsize-app", label: "Right-size servers to 3x m5.large", description: "The fleet is much bigger than the traffic needs. Three m5.large servers still handle the peak with room to spare.", patch: { app: { label: "m5.large", count: 3, rpsEach: 100, monthlyEach: 70 } } }, + { id: "rightsize-db", label: "Right-size the database to db.m5.large", description: "A db.r5.2xlarge is built for memory-heavy work. This database is almost idle, so a db.m5.large is enough.", patch: { db: { label: "db.m5.large", capacity: 600, monthly: 140 } } }, + { id: "savings-plan", label: "Buy a 1-year Compute Savings Plan", description: "Commit to steady EC2 use for one year and pay about 30% less per server than on-demand.", patch: { app: { pricing: "savings" } } }, + { id: "reserved-rds", label: "Buy a 1-year RDS Reserved Instance", description: "Commit to one database size for one year and pay about 38% less than on-demand.", patch: { db: { pricing: "reserved" } } }, + { id: "bigger-4xl", label: "Move up to m5.4xlarge for headroom", description: "Bigger servers feel safe, but they cost twice as much per server.", patch: { app: { label: "m5.4xlarge", rpsEach: 800, monthlyEach: 560 } } }, + { id: "add-replica", label: "Add a read replica for safety", description: "A second copy of the database for reads. It costs as much as the database itself.", patch: { db: { replicas: 1, replicaMonthly: 700 } } }, + ], + maxChanges: 3, + solution: ["rightsize-app", "rightsize-db", "savings-plan"], + trap: "bigger-4xl", + trapNote: "Bigger servers do not help when the old ones were already idle. They only raise the bill.", + hints: [ + "Look at the busy bars: the servers and the database are almost idle.", + "Paying for capacity you do not use is the problem. Make the machines smaller.", + "Right-size both the servers and the database, then commit to a steady price with a savings plan or a reserved instance.", + ], + focus: "app", + }, + { + id: "sd-static-flood", + difficulty: "easy", + title: "Images are crushing the web servers", + brief: "The shop is slow all afternoon. Most requests are for images, CSS and JavaScript files that never change.", + incident: "LATENCY ALERT: p95 is over 1 second. App servers are above 90% busy serving static files.", + model: model({ app: { count: 4 }, net: { egressGb: 3000 } }), + traffic: shape([[0, 150], [6, 150], [10, 900], [17, 900], [23, 150]]), + mix: { staticShare: 0.8, readShare: 0.8 }, + goals: { maxP95Ms: 140, minAvailability: 99.5, maxCostUsd: 720 }, + stretch: { maxCostUsd: 680 }, + changes: [ + { id: "add-cdn", label: "Put CloudFront in front", description: "A CDN keeps copies of static files near the user, so most of them never reach your servers. It also cuts data transfer cost.", patch: { cdn: { on: true } } }, + { id: "more-servers", label: "Add 4 more app servers", description: "More servers share the load. It works, but you pay for them every hour.", patch: { app: { count: 8 } } }, + { id: "bigger-db", label: "Move to a bigger database", description: "A bigger database is stronger, but the database is not the busy part here.", patch: { db: { label: "db.r5.xlarge", capacity: 1200, monthly: 350 } } }, + { id: "add-cache", label: "Add an ElastiCache node", description: "A cache answers repeated database reads fast. Static files do not come from the database.", patch: { cache: { on: true } } }, + ], + maxChanges: 2, + solution: ["add-cdn"], + trap: "bigger-db", + trapNote: "The database was never the busy part, so a bigger one only costs more.", + hints: ["Check which bar is red. It is the app servers.", "Most traffic is static files. They can be served from somewhere else.", "Use a CDN (CloudFront) for static files."], + focus: "app", + }, + { + id: "sd-logs-forever", + difficulty: "easy", + title: "Logs that never end", + brief: "Application logs are kept in S3 Standard forever. The storage line grows every month. Nobody reads logs older than a month.", + incident: "COST ALERT: S3 storage is now the biggest line on the bill and grows 5 TB each month.", + model: model({ logs: { gb: 60000, coldShare: 0 }, net: { egressGb: 300 } }), + traffic: day(20, 60), + mix: { staticShare: 0.3, readShare: 0.8 }, + goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 900 }, + stretch: { maxCostUsd: 650 }, + changes: [ + { id: "glacier-lifecycle", label: "Lifecycle rule: move to Glacier after 30 days", description: "S3 moves old logs to Glacier on its own. Glacier costs about a fifth of S3 Standard per GB.", patch: { logs: { coldShare: 0.9 } } }, + { id: "compress-logs", label: "Compress logs with gzip before upload", description: "Text logs shrink to about a third of their size, so you store and pay for less.", patch: { logs: { gb: 20000 } } }, + { id: "ebs-volumes", label: "Keep the logs on bigger EBS volumes", description: "Block storage is for running servers. It costs more per GB than S3.", patch: { logs: { hotRate: 0.08 } } }, + { id: "intelligent-tiering", label: "Turn on S3 Intelligent-Tiering", description: "S3 watches access and moves some data to a cheaper tier. Fine for unknown patterns, but it also adds a monitoring fee per object.", patch: { logs: { coldShare: 0.5, coldRate: 0.0125 } } }, + ], + maxChanges: 3, + solution: ["glacier-lifecycle", "compress-logs"], + trap: "ebs-volumes", + trapNote: "EBS costs more per GB than S3, so it makes the log bill bigger.", + hints: ["The big line is log storage, not servers.", "Old logs are almost never read. They do not need the most expensive storage class.", "Move old logs to Glacier with a lifecycle rule, and store fewer bytes by compressing."], + focus: "storage", + }, + { + id: "sd-nat-bill", + difficulty: "easy", + title: "The NAT gateway line explodes", + brief: "Servers in private subnets download big files from S3 through a NAT gateway. NAT charges for every GB that passes through.", + incident: "COST ALERT: NAT Gateway data processing is the top line on the bill, 30 TB this month.", + model: model({ net: { natGb: 30000, s3Share: 0.8, egressGb: 7000 } }), + traffic: day(30, 80), + mix: { staticShare: 0.4, readShare: 0.8 }, + goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 1500 }, + stretch: { maxCostUsd: 1100 }, + changes: [ + { id: "s3-endpoint", label: "Add an S3 gateway VPC endpoint", description: "Traffic to S3 goes over the AWS network directly, not through NAT. A gateway endpoint for S3 has no hourly or per-GB charge.", patch: { net: { s3Endpoint: true } } }, + { id: "add-cdn", label: "Put CloudFront in front of downloads", description: "A CDN serves popular files from the edge. Data transfer out gets cheaper and your servers are asked less often.", patch: { cdn: { on: true } } }, + { id: "second-nat", label: "Add a second NAT gateway per AZ", description: "It is good for availability, but it adds another monthly fee and does not reduce the data that passes through NAT.", patch: { net: { natGateways: 2 } } }, + { id: "bigger-app", label: "Use bigger servers", description: "The servers are fine. The traffic path is the problem.", patch: { app: { label: "m5.xlarge", rpsEach: 200, monthlyEach: 140 } } }, + ], + maxChanges: 2, + solution: ["s3-endpoint", "add-cdn"], + trap: "second-nat", + trapNote: "A second NAT gateway adds a fixed fee and does not reduce the GB that cross NAT.", + hints: ["Look at the cost lines: the NAT gateway is the biggest.", "Most of that traffic is only S3 traffic. It does not need to go through NAT at all.", "Add an S3 gateway endpoint. A CDN also cuts the data transfer line."], + focus: "nat", + }, + // ───────────────────────────── MEDIUM ───────────────────────────── + { + id: "sd-flash-sale-db", + difficulty: "medium", + title: "Flash sale crushes the database", + brief: "A flash sale at noon sends 6 times the normal traffic. The web servers cope, but the single database is melting.", + incident: "PAGE: database CPU at 100% and checkout errors rising. Flash sale in progress.", + model: model({ app: { count: 10 }, db: { label: "db.r5.large", capacity: 330, monthly: 300, replicaMonthly: 300 }, net: { egressGb: 400 } }), + traffic: shape([[0, 100], [9, 100], [11, 120], [12, 700], [15, 700], [16, 120], [23, 100]]), + mix: { staticShare: 0.1, readShare: 0.7 }, + goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 1700, maxPeakDbUtil: 0.9 }, + stretch: { maxCostUsd: 1500 }, + changes: [ + { id: "add-cache", label: "Add ElastiCache (Redis) for hot products", description: "Hot product pages are read again and again. A cache answers them from memory so the database sees fewer reads.", patch: { cache: { on: true, hit: 0.6 } } }, + { id: "add-replica", label: "Add a read replica", description: "A second database copy that answers reads. The primary only handles writes and half of the reads.", patch: { db: { replicas: 1 } } }, + { id: "add-queue", label: "Put orders in an SQS queue", description: "Writes wait in a queue and the database drains them at its own pace. The user gets a fast answer, the database never gets a spike.", patch: { queue: { on: true } } }, + { id: "more-servers", label: "Double the app servers", description: "More web servers, but they were not the busy part. The database is.", patch: { app: { count: 16 } } }, + { id: "bigger-db", label: "Upgrade to db.r5.4xlarge", description: "A much bigger database. It fixes the spike but costs a lot every month, also on quiet days.", patch: { db: { label: "db.r5.4xlarge", capacity: 1320, monthly: 1200 } } }, + ], + maxChanges: 3, + solution: ["add-cache", "add-replica"], + trap: "more-servers", + trapNote: "The web servers were not the problem. More of them only raises cost and sends even more work to the database.", + hints: ["Look at the bars during the sale: the database is at 100%, the servers are fine.", "Reads dominate. Take reads away from the primary database.", "Use a cache and a read replica together. A queue can smooth the writes."], + focus: "db", + }, + { + id: "sd-p95-four-seconds", + difficulty: "medium", + title: "p95 latency is 4 seconds", + brief: "Every page request hits the database, and static files come from the same servers. Pages feel slow all afternoon.", + incident: "LATENCY ALERT: p95 is 4 s. Database and app servers are both near 100% busy.", + model: model({ app: { count: 3 }, db: { capacity: 200 }, net: { egressGb: 1500 } }), + traffic: shape([[0, 80], [7, 80], [10, 420], [18, 420], [23, 80]]), + mix: { staticShare: 0.5, readShare: 0.9 }, + goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 650 }, + stretch: { maxCostUsd: 620, maxP95Ms: 130 }, + changes: [ + { id: "add-cache", label: "Add ElastiCache for repeated reads", description: "Most pages ask the database the same questions. A cache returns the answer in about 2 ms.", patch: { cache: { on: true, hit: 0.85 } } }, + { id: "add-cdn", label: "Put CloudFront in front for static files", description: "Images and scripts come from the edge, so the web servers only do dynamic work.", patch: { cdn: { on: true } } }, + { id: "add-replica", label: "Add a read replica", description: "A replica doubles read capacity, but every read is still a database read, and you pay for a second database.", patch: { db: { replicas: 1 } } }, + { id: "more-servers", label: "Add 3 more app servers", description: "More servers handle more requests, but they all still wait for the same database.", patch: { app: { count: 6 } } }, + { id: "bigger-db", label: "Use a bigger database", description: "More database power. Pricey, and static files still hit the servers.", patch: { db: { label: "db.r5.xlarge", capacity: 800, monthly: 350 } } }, + ], + maxChanges: 3, + solution: ["add-cache", "add-cdn"], + trap: "more-servers", + trapNote: "More servers do nothing for slow reads. They all wait for the same database, and they cost money.", + hints: ["Two parts are busy: the database and the app servers.", "Do not answer the same question from the database again and again, and do not make servers send files.", "Add a cache for reads and a CDN for static files."], + focus: "db", + }, + { + id: "sd-az-outage", + difficulty: "medium", + title: "One AZ goes dark", + brief: "At 1 pm one Availability Zone fails. Everything runs in that one zone. Make the site survive a zone failure.", + incident: "OUTAGE: us-east-1a is unreachable. All servers and the database are in 1a. The site is down.", + model: model({ app: { count: 4 }, net: { egressGb: 400 } }), + traffic: day(30, 140), + mix: { staticShare: 0.2, readShare: 0.8 }, + outage: { from: 13, to: 17 }, + goals: { maxP95Ms: 250, minAvailability: 99, maxCostUsd: 750 }, + stretch: { maxCostUsd: 680 }, + changes: [ + { id: "two-azs", label: "Spread servers across 2 AZs", description: "Half of the servers run in a second Availability Zone, behind a load balancer.", patch: { app: { zones: 2 } } }, + { id: "health-checks", label: "Add load balancer health checks", description: "The load balancer stops sending users to servers that do not answer.", patch: { app: { healthChecks: true } } }, + { id: "rds-multi-az", label: "Turn on RDS Multi-AZ", description: "A standby database in the other zone takes over by itself if the primary fails.", patch: { db: { multiAz: true } } }, + { id: "autoscaling", label: "Add an Auto Scaling group", description: "Servers are added when load grows and removed when it falls, so you pay for less at night.", patch: { app: { autoscale: true, scaleMin: 2, scaleMax: 8 } } }, + { id: "bigger-servers", label: "Use bigger servers", description: "Bigger servers in the same zone still go down with the zone.", patch: { app: { label: "m5.xlarge", rpsEach: 200, monthlyEach: 140, count: 4 } } }, + ], + maxChanges: 4, + solution: ["two-azs", "health-checks", "rds-multi-az"], + trap: "bigger-servers", + trapNote: "A bigger server is still one server in one zone. It does not survive a zone failure and it costs twice as much.", + hints: ["Everything lives in one zone, so one failure takes down everything.", "You need copies of the servers and of the database in a second zone.", "Spread servers over two AZs, let the load balancer find dead servers, and give the database a standby."], + focus: "lb", + }, + { + id: "sd-batch-starves-web", + difficulty: "medium", + title: "The report job starves the shop", + brief: "A heavy report job runs at midday on the same servers and database as the shop. While it runs, customers wait.", + incident: "LATENCY ALERT: p95 jumps to 3 s from 11:00 to 15:00, the same time the reports run.", + model: model({ app: { count: 4, monthlyEach: 120, label: "m5.xlarge", rpsEach: 100 }, db: { capacity: 400, monthly: 200 }, net: { egressGb: 600 } }), + traffic: shape([[0, 40], [6, 40], [10, 130], [17, 130], [23, 40]]), + mix: { staticShare: 0.2, readShare: 0.8 }, + batchJob: { from: 11, to: 15, appLoad: 240, dbLoad: 240 }, + goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 800 }, + stretch: { maxCostUsd: 720 }, + changes: [ + { id: "spot-workers", label: "Run the job on Spot workers", description: "Move the report job to its own Spot instances, which cost about 70% less and can be interrupted. The shop stops competing with it.", patch: { batch: { separate: true } } }, + { id: "savings-plan", label: "Buy a 1-year Compute Savings Plan", description: "Pay about 30% less for the steady web servers.", patch: { app: { pricing: "savings" } } }, + { id: "autoscaling", label: "Add an Auto Scaling group", description: "Adds servers when the load grows. It helps the web tier but does nothing for the shared database.", patch: { app: { autoscale: true, scaleMin: 2, scaleMax: 8 } } }, + { id: "more-servers", label: "Add 4 more app servers", description: "Bigger fleet all day, to survive 4 hours. Costly, and the database still gets the job load.", patch: { app: { count: 8 } } }, + { id: "reserved-rds", label: "Buy a 1-year RDS Reserved Instance", description: "Pay about 38% less for the database.", patch: { db: { pricing: "reserved" } } }, + ], + maxChanges: 3, + solution: ["spot-workers", "savings-plan"], + trap: "more-servers", + trapNote: "Extra servers for four busy hours cost money all month, and the database still has to carry the job.", + hints: ["Look at the times: the slow period matches the job.", "The shop and the job share the same machines. Separate them.", "Move the job to Spot workers. A savings plan keeps the bill in budget."], + focus: "workers", + }, + // ───────────────────────────── HARD ───────────────────────────── + { + id: "sd-missing-index", + difficulty: "hard", + title: "A query scans a million rows", + brief: "The product search runs a full table scan on every request. At lunch the database cannot keep up.", + incident: "PAGE: slow query log shows 180 ms scans on orders. Database CPU 100% at lunch.", + model: model({ + app: { count: 5 }, + db: { label: "db.m5.xlarge", capacity: 600, monthly: 250, readCost: 6, readMs: 180 }, + net: { egressGb: 500 }, + }), + traffic: shape([[0, 40], [8, 60], [11, 250], [15, 250], [18, 80], [23, 40]]), + mix: { staticShare: 0.2, readShare: 0.85 }, + goals: { maxP95Ms: 100, minAvailability: 99.5, maxCostUsd: 850, maxPeakDbUtil: 0.7 }, + stretch: { maxCostUsd: 800 }, + changes: [ + { id: "add-index", label: "Add an index on the search column", description: "An index lets the database find rows directly instead of reading the whole table. Reads get both faster and cheaper.", patch: { db: { readCost: 1, readMs: 12 } } }, + { id: "add-cache", label: "Add ElastiCache for repeated searches", description: "Popular searches repeat. A cache answers them in memory.", patch: { cache: { on: true, hit: 0.7 } } }, + { id: "bigger-db", label: "Upgrade to db.m5.4xlarge", description: "Four times the database power. A scan is still a scan, and the bill goes way up.", patch: { db: { label: "db.m5.4xlarge", capacity: 2400, monthly: 1000 } } }, + { id: "add-replica", label: "Add two read replicas", description: "More copies to scan the table. Each costs as much as the database.", patch: { db: { replicas: 2, replicaMonthly: 250 } } }, + { id: "more-servers", label: "Add more app servers", description: "The servers are not the slow part.", patch: { app: { count: 10 } } }, + ], + maxChanges: 3, + solution: ["add-index", "add-cache"], + trap: "bigger-db", + trapNote: "A bigger database still scans the whole table, so each query stays slow, and the cost goes over the limit.", + hints: ["Read the incident: a query takes 180 ms because it reads every row.", "Fix the query first, because power does not fix a bad query.", "Add the index. Then take the repeated reads off the database with a cache."], + focus: "db", + }, + { + id: "sd-hot-partition", + difficulty: "hard", + title: "One hot key, throttled writes", + brief: "A DynamoDB table uses the date as its partition key. Today's partition gets almost all the writes and is throttled, while the table has plenty of capacity overall.", + incident: "ALARM: ThrottledRequests on orders-table. Total capacity use is 20% but one partition is at 100%.", + model: model({ + app: { count: 10 }, + db: { kind: "dynamodb", label: "DynamoDB orders", capacity: 1100, monthly: 450, skew: 6, readMs: 6, writeMs: 10, readCost: 1 }, + net: { egressGb: 400 }, + }), + traffic: shape([[0, 150], [8, 200], [12, 800], [16, 800], [19, 250], [23, 150]]), + mix: { staticShare: 0.1, readShare: 0.45 }, + goals: { maxP95Ms: 220, minAvailability: 99.5, maxCostUsd: 1500, maxPeakDbUtil: 0.85 }, + stretch: { maxCostUsd: 1450 }, + changes: [ + { id: "shard-key", label: "Add a random suffix to the partition key", description: "Writes for the same date spread over many partitions, so no single partition is hot. This is called write sharding.", patch: { db: { skew: 1.5 } } }, + { id: "add-dax", label: "Add DAX, a DynamoDB cache", description: "A cache in front of DynamoDB answers repeated reads. Fewer reads means more room for writes.", patch: { cache: { on: true, hit: 0.7, monthly: 150 } } }, + { id: "add-queue", label: "Buffer writes with SQS", description: "Writes wait in a queue and are written at a steady pace instead of in a burst.", patch: { queue: { on: true } } }, + { id: "double-capacity", label: "Double the provisioned capacity", description: "More capacity for the table. It is spread over partitions, so the hot one gets only a bit more.", patch: { db: { capacity: 2200, monthly: 900 } } }, + { id: "more-servers", label: "Add more app servers", description: "The throttling is in the table, not in the servers.", patch: { app: { count: 12 } } }, + ], + maxChanges: 3, + solution: ["shard-key", "add-dax"], + trap: "double-capacity", + trapNote: "Capacity is shared across partitions. The hot partition is still hot, and you pay double.", + hints: ["Total capacity is fine, but one partition gets almost all the work.", "The cause is the key, not the capacity. Spread the key.", "Shard the partition key. A cache for reads gives the writes more room."], + focus: "db", + }, + { + id: "sd-black-friday-az", + difficulty: "hard", + title: "Peak day plus a lost zone", + brief: "It is the biggest sales day. Traffic triples, and in the middle of it one Availability Zone fails. The fixed fleet is too small and sits in one zone.", + incident: "OUTAGE: us-east-1a lost during peak sales. Fleet at 100% before the failure.", + model: model({ + app: { count: 6, label: "m5.xlarge", rpsEach: 100, monthlyEach: 100 }, + db: { label: "db.r5.large", capacity: 900, monthly: 300 }, + net: { egressGb: 800 }, + }), + traffic: shape([[0, 60], [7, 100], [10, 500], [17, 500], [20, 120], [23, 60]]), + mix: { staticShare: 0.15, readShare: 0.8 }, + outage: { from: 13, to: 16 }, + goals: { maxP95Ms: 350, minAvailability: 99, maxCostUsd: 1800 }, + stretch: { maxCostUsd: 1600 }, + changes: [ + { id: "asg-two-azs", label: "Auto Scaling group across 2 AZs", description: "Servers are spread over two zones and the group adds more when load rises, and removes them when it falls.", patch: { app: { zones: 2, autoscale: true, scaleMin: 4, scaleMax: 16 } } }, + { id: "health-checks", label: "Load balancer health checks", description: "Dead servers are removed from rotation within seconds.", patch: { app: { healthChecks: true } } }, + { id: "rds-multi-az", label: "RDS Multi-AZ", description: "A standby database in the second zone takes over after a failure.", patch: { db: { multiAz: true } } }, + { id: "add-cache", label: "Add ElastiCache", description: "Fewer reads reach the database. It helps speed, not zone failure.", patch: { cache: { on: true, hit: 0.8 } } }, + { id: "oversize-fleet", label: "Double the fixed fleet to 12 servers", description: "Always-on capacity for the peak. It does not fix the zone problem and it is on the bill for the whole month.", patch: { app: { count: 12 } } }, + ], + maxChanges: 4, + solution: ["asg-two-azs", "health-checks", "rds-multi-az"], + trap: "oversize-fleet", + trapNote: "A fixed, doubled fleet costs the same at night as at peak, and still lives in one zone.", + hints: ["Two problems at once: too little capacity at peak, and one zone.", "You need servers in two zones that can grow, plus a way to remove dead ones.", "Auto Scaling over two AZs, health checks, and a Multi-AZ database."], + focus: "app", + }, + { + id: "sd-halve-the-bill", + difficulty: "hard", + title: "Halve the bill, keep it fast", + brief: "The CFO wants the monthly bill cut in half without hurting speed or uptime. Money leaks in four places.", + incident: "COST ALERT: bill is $3,400 a month. Target is under $2,000. Latency and uptime must not suffer.", + model: model({ + app: { label: "m5.xlarge", count: 6, rpsEach: 200, monthlyEach: 140 }, + db: { label: "db.r5.xlarge", capacity: 1200, monthly: 350 }, + net: { egressGb: 6000, natGb: 15000, s3Share: 0.8 }, + logs: { gb: 40000 }, + }), + traffic: day(60, 160), + mix: { staticShare: 0.5, readShare: 0.8 }, + goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 2000 }, + stretch: { maxCostUsd: 1750 }, + changes: [ + { id: "add-cdn", label: "Add CloudFront", description: "Cheaper data transfer out, and static files stop reaching the servers.", patch: { cdn: { on: true } } }, + { id: "s3-endpoint", label: "S3 gateway VPC endpoint", description: "Stops S3 traffic from going through the NAT gateway.", patch: { net: { s3Endpoint: true } } }, + { id: "glacier-lifecycle", label: "Lifecycle old logs to Glacier", description: "Old logs move to a much cheaper storage class.", patch: { logs: { coldShare: 0.9 } } }, + { id: "savings-plan", label: "1-year Compute Savings Plan", description: "About 30% off the servers.", patch: { app: { pricing: "savings" } } }, + { id: "tiny-server", label: "Run everything on 1 t3.micro", description: "The cheapest possible server. It cuts the bill and cannot carry the traffic.", patch: { app: { label: "t3.micro", count: 1, rpsEach: 15, monthlyEach: 9 } } }, + { id: "second-nat", label: "A NAT gateway in every AZ", description: "Better resilience, more fixed cost.", patch: { net: { natGateways: 2 } } }, + ], + maxChanges: 4, + solution: ["add-cdn", "s3-endpoint", "glacier-lifecycle", "savings-plan"], + trap: "tiny-server", + trapNote: "A tiny server makes the bill small, but it cannot serve the traffic. Uptime and speed fall.", + hints: ["Open the cost lines. Four of them are big: transfer, NAT, logs, servers.", "Each leak has a cheap plug. Do not shrink the servers below the traffic.", "CDN, S3 endpoint, Glacier lifecycle, savings plan."], + focus: "nat", + }, +]; + +export const SYSDESIGN_POOL: readonly SysdesignRound[] = POOL; + +export function scenariosByDifficulty(difficulty: Difficulty): SysdesignRound[] { + return POOL.filter((r) => r.difficulty === difficulty); +} + +export type { ChangeDef }; diff --git a/frontend/src/shared/games/sysdesign/sim.ts b/frontend/src/shared/games/sysdesign/sim.ts new file mode 100644 index 00000000..e8fb5194 --- /dev/null +++ b/frontend/src/shared/games/sysdesign/sim.ts @@ -0,0 +1,277 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// A small, pure, deterministic traffic simulation. It uses only + - * / and min, max, ceil, round, +// so the browser and the server always agree to the last digit. No clock, no randomness. +import { + STEPS, + type CostLine, + type DeepPartial, + type GoalCheck, + type Goals, + type Model, + type SimResult, + type StepResult, + type SysdesignRound, +} from "./types"; + +const APP_PRICING = { ondemand: 1, savings: 0.68, reserved: 0.6 } as const; +const DB_PRICING = { ondemand: 1, reserved: 0.62 } as const; +/** Illustrative unit prices, in dollars. They are round numbers, not real quotes. */ +export const PRICES = { egressPerGb: 0.09, cdnPerGb: 0.04, natPerGb: 0.045, natPerMonth: 33 } as const; + +function isObject(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +/** Merge a patch onto a copy of a model. Only objects are merged, everything else is replaced. */ +export function mergePatch(base: T, patch: DeepPartial): T { + if (!isObject(base) || !isObject(patch)) return base; + const out: Record = { ...base }; + for (const key of Object.keys(patch)) { + const next = (patch as Record)[key]; + const prev = out[key]; + out[key] = isObject(prev) && isObject(next) ? mergePatch(prev, next as never) : next; + } + return out as T; +} + +/** The model after the changes, applied in order. Ids that are not offered are ignored. */ +export function applyChanges(round: SysdesignRound, ids: readonly string[]): Model { + let model = round.model; + for (const id of ids) { + const change = round.changes.find((c) => c.id === id); + if (change) model = mergePatch(model, change.patch); + } + return model; +} + +const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, n)); +/** Queueing delay: grows fast as a part gets busy. Capped so a saturated part reads as a timeout. */ +const slow = (baseMs: number, util: number) => Math.min(4000, baseMs / (1 - clamp(util, 0, 0.97))); + +type Point = { ms: number; weight: number }; + +/** A class of requests has a spread: most are near the typical time, a few are much slower. */ +function spread(ms: number, weight: number, out: Point[]) { + if (weight <= 0) return; + out.push({ ms: ms * 0.8, weight: weight * 0.6 }, { ms: ms * 1.3, weight: weight * 0.3 }, { ms: ms * 2.6, weight: weight * 0.1 }); +} + +function weightedPercentile(points: Point[], q: number): number { + const sorted = [...points].sort((a, b) => a.ms - b.ms); + const total = sorted.reduce((sum, p) => sum + p.weight, 0); + if (total <= 0) return 0; + let seen = 0; + for (const p of sorted) { + seen += p.weight; + if (seen >= total * q) return Math.min(4000, Math.round(p.ms)); + } + return Math.min(4000, Math.round(sorted[sorted.length - 1]!.ms)); +} + +export function costLines(model: Model, appInstancesAvg: number): CostLine[] { + const appF = APP_PRICING[model.app.pricing] ?? 1; + const dbF = DB_PRICING[model.db.pricing] ?? 1; + const lines: CostLine[] = []; + const add = (id: string, label: string, usd: number) => { + const rounded = Math.round(usd); + if (rounded > 0) lines.push({ id, label, usd: rounded }); + }; + add("app", `${model.app.label} servers`, appInstancesAvg * model.app.monthlyEach * appF); + add("db", `${model.db.label} database`, (model.db.monthly + (model.db.multiAz ? model.db.monthly : 0)) * dbF); + add("replica", "Read replicas", model.db.replicas * model.db.replicaMonthly * dbF); + if (model.cache.on) add("cache", "ElastiCache", model.cache.monthly); + if (model.cdn.on) add("cdn", "CloudFront", model.cdn.monthly); + if (model.queue.on) add("queue", "SQS queue", model.queue.monthly); + if (model.batch.separate) add("workers", "Spot workers", model.batch.workersMonthly); + const off = model.cdn.on ? model.cdn.offload : 0; + add("egress", "Data transfer out", model.net.egressGb * ((1 - off) * PRICES.egressPerGb + off * PRICES.cdnPerGb)); + const natGb = model.net.natGb * (1 - (model.net.s3Endpoint ? model.net.s3Share : 0)); + add("nat", "NAT gateway", model.net.natGateways * PRICES.natPerMonth + natGb * PRICES.natPerGb); + add("logs", "Log storage", model.logs.gb * ((1 - model.logs.coldShare) * model.logs.hotRate + model.logs.coldShare * model.logs.coldRate)); + return lines; +} + +/** Run the day. The same inputs always give the same result. */ +export function simulate(round: SysdesignRound, changeIds: readonly string[]): SimResult { + const m = applyChanges(round, changeIds); + const { mix, outage, batchJob } = round; + const traffic = Array.from({ length: STEPS }, (_, i) => Math.max(0, round.traffic[i] ?? 0)); + + const batchApp = (t: number) => (batchJob && t >= batchJob.from && t <= batchJob.to && !m.batch.separate ? batchJob.appLoad : 0); + const appWorkFor = (t: number) => { + const load = traffic[t]!; + const st = load * mix.staticShare; + const off = m.cdn.on ? m.cdn.offload : 0; + return st * (1 - off) * 0.25 + (load - st) + batchApp(t); + }; + + const hit = m.cache.on ? m.cache.hit : 0; + const dbCap = Math.max(1, m.db.capacity / Math.max(1, m.db.skew)); + const replicas = Math.max(0, Math.round(m.db.replicas)); + + const steps: StepResult[] = []; + const all: Point[] = []; + const instances: number[] = []; + let backlog = 0; + let totalReq = 0; + let totalOk = 0; + let peakApp = 0; + let peakDb = 0; + let peakBacklog = 0; + + for (let t = 0; t < STEPS; t++) { + const load = traffic[t]!; + const zoneDown = !!outage && t >= outage.from && t <= outage.to; + const outageStart = !!outage && t === outage.from; + const prevWork = appWorkFor(Math.max(0, t - 1)); + + const target = m.app.autoscale ? clamp(Math.ceil(prevWork / (m.app.rpsEach * (m.app.zones === 2 ? 0.4 : 0.6))), m.app.scaleMin, m.app.scaleMax) : m.app.count; + instances.push(target); + + // How many servers are alive, and how much traffic still goes to the dead zone. + let alive = target; + let deadRoute = 0; + if (zoneDown) { + if (m.app.zones === 1) { + alive = 0; + deadRoute = 1; + } else { + alive = m.app.autoscale && !outageStart ? clamp(target, Math.ceil(m.app.scaleMin / 2), m.app.scaleMax) : Math.ceil(target / 2); + deadRoute = m.app.healthChecks ? (outageStart ? 0.04 : 0) : 0.5; + } + } + const reach = 1 - deadRoute; + + const st = load * mix.staticShare; + const dyn = load - st; + const reads = dyn * mix.readShare; + const writes = dyn - reads; + const off = m.cdn.on ? m.cdn.offload : 0; + const stCdn = st * off; + const stOrigin = st - stCdn; + const hitReads = reads * hit; + const missReads = reads - hitReads; + + const running = !!batchJob && t >= batchJob.from && t <= batchJob.to && !m.batch.separate; + const appWork = (stOrigin * 0.25 + dyn + batchApp(t)) * reach; + const cap = alive * m.app.rpsEach; + const fa = appWork <= 0 ? 1 : alive === 0 ? 0 : Math.min(1, cap / appWork); + const appUtil = alive === 0 ? 0 : cap > 0 ? appWork / cap : 0; + + // The database. A single-zone database is lost with the zone. A standby takes over quickly. + const dbDown = zoneDown && !m.db.multiAz; + const failover = zoneDown && m.db.multiAz && outageStart ? 0.97 : 1; + const missIn = missReads * reach * fa; + const writeIn = writes * reach * fa + (m.queue.on ? backlog : 0); + const readsPrimary = missIn / (1 + replicas); + const readsReplica = replicas > 0 ? missIn / (1 + replicas) : 0; + const batchDb = running ? batchJob!.dbLoad : 0; + const fixedLoad = readsPrimary * m.db.readCost + batchDb; + let writesDone = writeIn; + if (m.queue.on) { + writesDone = dbDown ? 0 : Math.min(writeIn, Math.max(0, dbCap - fixedLoad)); + backlog = Math.max(0, writeIn - writesDone); + } else { + backlog = 0; + } + const primaryDemand = writesDone + fixedLoad; + const pu = dbDown ? 0 : primaryDemand / dbCap; + const ru = (readsReplica * m.db.readCost) / dbCap; + const okPrimary = dbDown ? 0 : pu <= 1 ? 1 : 1 / pu; + const okReplica = ru <= 1 ? 1 : 1 / ru; + const okWrite = m.queue.on ? 1 : okPrimary; + const okRead = (okPrimary + replicas * okReplica) / (1 + replicas); + + // Success per class of request. + const successStOrigin = reach * fa; + const successHit = reach * fa; + const successMiss = reach * fa * okRead * failover; + const successWrite = reach * fa * okWrite * failover; + + const appMs = alive === 0 ? 4000 : slow(m.app.baseMs, appUtil); + const readUtil = (pu + replicas * ru) / (1 + replicas); + const dbReadMs = slow(m.db.readMs, readUtil); + const dbWriteMs = slow(m.db.writeMs, pu); + const points: Point[] = []; + spread(12, stCdn, points); + spread(appMs * 0.6, stOrigin * successStOrigin, points); + spread(appMs + 2, hitReads * successHit, points); + spread(appMs + dbReadMs, missReads * successMiss, points); + spread(appMs + (m.queue.on ? 6 : dbWriteMs), writes * successWrite, points); + all.push(...points); + + const ok = stCdn + stOrigin * successStOrigin + hitReads * successHit + missReads * successMiss + writes * successWrite; + const success = load > 0 ? Math.min(1, ok / load) : 1; + totalReq += load; + totalOk += ok; + const p95Ms = weightedPercentile(points, 0.95); + peakApp = Math.max(peakApp, appUtil); + peakDb = Math.max(peakDb, pu, ru); + peakBacklog = Math.max(peakBacklog, backlog); + + steps.push({ + t, + load, + appInstances: alive, + appUtil, + dbUtil: pu, + replicaUtil: ru, + success, + appDrop: clamp(1 - reach * fa, 0, 1), + dbDrop: clamp(1 - okRead * failover, 0, 1), + p95Ms, + status: success < 0.9 ? "down" : success < 0.995 || p95Ms > round.goals.maxP95Ms ? "slow" : "ok", + zoneDown, + batchRunning: running, + backlog, + costToDate: 0, + }); + } + + const avgInstances = instances.reduce((a, b) => a + b, 0) / STEPS; + const lines = costLines(m, avgInstances); + const costUsd = lines.reduce((sum, l) => sum + l.usd, 0); + const appLine = lines.find((l) => l.id === "app")?.usd ?? 0; + const fixedPerStep = (costUsd - appLine) / STEPS; + let acc = 0; + steps.forEach((s, i) => { + acc += (avgInstances > 0 ? (instances[i]! / (avgInstances * STEPS)) * appLine : 0) + fixedPerStep; + s.costToDate = Math.round(acc); + }); + if (steps.length > 0) steps[steps.length - 1]!.costToDate = costUsd; + + return { + model: m, + steps, + p95Ms: weightedPercentile(all, 0.95), + availability: totalReq > 0 ? Math.round((totalOk / totalReq) * 10000) / 100 : 100, + costUsd, + costLines: lines, + peakAppUtil: peakApp, + peakDbUtil: peakDb, + peakBacklog, + }; +} + +const pct = (n: number) => `${Math.round(n * 100)}%`; + +/** Every goal with a yes or no. Used by verify and by the result panel. */ +export function evaluateGoals(goals: Goals, sim: SimResult): GoalCheck[] { + const checks: GoalCheck[] = [ + { id: "p95", label: "Latency (p95)", met: sim.p95Ms <= goals.maxP95Ms, actual: `${sim.p95Ms} ms`, target: `at most ${goals.maxP95Ms} ms` }, + { id: "availability", label: "Availability", met: sim.availability >= goals.minAvailability, actual: `${sim.availability}%`, target: `at least ${goals.minAvailability}%` }, + { id: "cost", label: "Monthly cost", met: sim.costUsd <= goals.maxCostUsd, actual: `$${sim.costUsd}`, target: `at most $${goals.maxCostUsd}` }, + ]; + if (goals.maxPeakAppUtil !== undefined) { + checks.push({ id: "appUtil", label: "App servers peak load", met: sim.peakAppUtil <= goals.maxPeakAppUtil, actual: pct(sim.peakAppUtil), target: `at most ${pct(goals.maxPeakAppUtil)}` }); + } + if (goals.maxPeakDbUtil !== undefined) { + checks.push({ id: "dbUtil", label: "Database peak load", met: sim.peakDbUtil <= goals.maxPeakDbUtil, actual: pct(sim.peakDbUtil), target: `at most ${pct(goals.maxPeakDbUtil)}` }); + } + return checks; +} + +/** What one change alone does to the monthly bill, in dollars (negative saves money). */ +export function costDelta(round: SysdesignRound, id: string): number { + return simulate(round, [id]).costUsd - simulate(round, []).costUsd; +} diff --git a/frontend/src/shared/games/sysdesign/types.ts b/frontend/src/shared/games/sysdesign/types.ts new file mode 100644 index 00000000..92af9efc --- /dev/null +++ b/frontend/src/shared/games/sysdesign/types.ts @@ -0,0 +1,167 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// Shared types for the System Design Runner. Everything here is plain data (no functions), because +// a round travels from the server to the browser as JSON. +import type { RoundBase } from "../types"; + +/** Number of traffic steps in one simulated day. One step is one hour. */ +export const STEPS = 24; + +export type Pricing = "ondemand" | "savings" | "reserved"; + +/** The system as the player sees it. A change patches some of these numbers. */ +export type Model = { + app: { + /** For example "m5.2xlarge". */ + label: string; + count: number; + /** Requests per second one server can handle. */ + rpsEach: number; + /** Illustrative on-demand dollars per server per month. */ + monthlyEach: number; + /** Time to answer when the server is idle, in ms. */ + baseMs: number; + /** 1 means one Availability Zone, 2 means two. */ + zones: 1 | 2; + healthChecks: boolean; + autoscale: boolean; + /** Autoscaling keeps at least this many servers and at most scaleMax. */ + scaleMin: number; + scaleMax: number; + pricing: Pricing; + }; + db: { + kind: "rds" | "dynamodb"; + label: string; + /** Work units per second the primary can do. */ + capacity: number; + monthly: number; + replicas: number; + replicaMonthly: number; + /** A standby in a second zone. Costs about the same as the primary again. */ + multiAz: boolean; + pricing: "ondemand" | "reserved"; + /** Time for a read and for a write when idle, in ms. */ + readMs: number; + writeMs: number; + /** Work units one read uses (a missing index makes this big). */ + readCost: number; + /** 1 is an even spread. 4 means one hot key gets 4 times its fair share of work. */ + skew: number; + }; + cache: { on: boolean; /** Share of reads answered by the cache, 0 to 1. */ hit: number; monthly: number }; + cdn: { on: boolean; /** Share of static files served at the edge, 0 to 1. */ offload: number; monthly: number }; + queue: { on: boolean; monthly: number }; + /** Where the nightly batch job runs. Separate means spot workers away from the web tier. */ + batch: { separate: boolean; workersMonthly: number }; + net: { + /** GB per month leaving to the internet from the origin. */ + egressGb: number; + /** GB per month through the NAT gateway. */ + natGb: number; + /** Share of NAT traffic that is really S3 or DynamoDB traffic, 0 to 1. */ + s3Share: number; + /** A gateway VPC endpoint for S3 is in place. */ + s3Endpoint: boolean; + natGateways: number; + }; + logs: { gb: number; hotRate: number; coldRate: number; /** Share kept in cold storage, 0 to 1. */ coldShare: number }; +}; + +export type DeepPartial = { [K in keyof T]?: T[K] extends object ? DeepPartial : T[K] }; + +/** A change the player can apply. It is data: a patch merged onto the model. */ +export type ChangeDef = { + id: string; + label: string; + /** Plain English: what it does and why it helps (or what it costs). */ + description: string; + patch: DeepPartial; +}; + +export type Goals = { + /** The p95 request latency over the whole day must be at or below this, in ms. */ + maxP95Ms: number; + /** Share of requests that must succeed, in percent. */ + minAvailability: number; + /** Monthly bill must be at or below this, in dollars. */ + maxCostUsd: number; + /** Optional extras. */ + maxPeakAppUtil?: number; + maxPeakDbUtil?: number; +}; + +export type Stretch = { maxCostUsd?: number; maxP95Ms?: number }; + +export type ComponentId = "users" | "cdn" | "lb" | "app" | "cache" | "queue" | "db" | "replica" | "workers" | "storage" | "nat"; + +export type SysdesignRound = RoundBase & { + /** Alarm text shown in the incident banner. */ + incident: string; + /** The system before the player changes anything. */ + model: Model; + /** Requests per second at each of the 24 steps. */ + traffic: number[]; + /** Share of requests that are static files, and share of dynamic requests that are reads. */ + mix: { staticShare: number; readShare: number }; + /** An Availability Zone fails during these steps (inclusive), if set. */ + outage?: { from: number; to: number }; + /** A batch job adds this load on the web tier and the database during these steps. */ + batchJob?: { from: number; to: number; appLoad: number; dbLoad: number }; + goals: Goals; + stretch: Stretch; + changes: ChangeDef[]; + maxChanges: number; + /** A change set that earns three stars. */ + solution: string[]; + /** A tempting change that does not help, or makes things worse. */ + trap?: string; + trapNote?: string; + /** Clues, from vague to clear. */ + hints: string[]; + /** The component to highlight as the problem. */ + focus: ComponentId; +}; + +export type SysdesignSubmission = { changes: string[] }; + +export type StepStatus = "ok" | "slow" | "down"; + +export type StepResult = { + t: number; + load: number; + appInstances: number; + /** Utilisation of each part, 0 upwards. Above 1 means it is overloaded. */ + appUtil: number; + dbUtil: number; + replicaUtil: number; + /** Share of requests that succeeded this step, 0 to 1. */ + success: number; + p95Ms: number; + status: StepStatus; + /** Share of requests lost before the app tier (dead zone or full servers), and share lost at the database, 0 to 1. */ + appDrop: number; + dbDrop: number; + zoneDown: boolean; + batchRunning: boolean; + /** Writes waiting in the queue after this step. */ + backlog: number; + /** Bill so far, in dollars per month (grows to the monthly total by the last step). */ + costToDate: number; +}; + +export type CostLine = { id: string; label: string; usd: number }; + +export type SimResult = { + model: Model; + steps: StepResult[]; + p95Ms: number; + /** Percent, 0 to 100. */ + availability: number; + costUsd: number; + costLines: CostLine[]; + peakAppUtil: number; + peakDbUtil: number; + peakBacklog: number; +}; + +export type GoalCheck = { id: string; label: string; met: boolean; actual: string; target: string }; diff --git a/frontend/src/shared/games/types.ts b/frontend/src/shared/games/types.ts new file mode 100644 index 00000000..92cd7543 --- /dev/null +++ b/frontend/src/shared/games/types.ts @@ -0,0 +1,54 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The contract every daily game follows. A game is a pure, deterministic engine that runs in the +// browser (so the player gets instant feedback) and again on the server (which replays the +// submission before it gives XP). Nothing here may touch the DOM, the clock or Math.random. + +export const GAME_IDS = ["sysdesign", "linux", "docker"] as const; +export type GameId = (typeof GAME_IDS)[number]; + +export function isGameId(value: unknown): value is GameId { + return typeof value === "string" && (GAME_IDS as readonly string[]).includes(value); +} + +/** Rounds in one game on one day: easy, medium, hard. Round numbers start at 0. */ +export const ROUNDS_PER_DAY = 3; +export const DIFFICULTIES = ["easy", "medium", "hard"] as const; +export type Difficulty = (typeof DIFFICULTIES)[number]; + +export type Stars = 0 | 1 | 2 | 3; + +/** What every round needs so the shell can list and label it. A game adds its own fields. */ +export type RoundBase = { + /** Stable id of the scenario, for example "sd-bill-tripled". Never reused for another scenario. */ + id: string; + difficulty: Difficulty; + title: string; + /** One or two plain sentences: what is wrong or what to do. */ + brief: string; +}; + +export type VerifyResult = { + /** The round is solved. Only a solved round records progress and earns XP. */ + passed: boolean; + /** 1 to 3 when passed, 0 when not. Better play (fewer commands, lower cost, no hints) earns more. */ + stars: Stars; + /** A number the game shows, for example a cost or a command count. Higher is not always better. */ + score: number; + /** One short sentence shown to the player: why it passed or what is still wrong. */ + message: string; +}; + +export interface GameEngine { + id: GameId; + title: string; + tagline: string; + /** Today's rounds in order easy, medium, hard. Same for everyone, from the day key only. */ + roundsFor(dayKey: string): R[]; + /** Narrow an unknown value from the network to a submission, or null when it is malformed. */ + parseSubmission(input: unknown): S | null; + /** Replay a submission against a round. Pure and deterministic, and must never throw. */ + verify(round: R, submission: S): VerifyResult; +} + +/** A loosely typed engine, for the registry and the API where the round type is not known. */ +export type AnyGameEngine = GameEngine, unknown>; diff --git a/frontend/src/shared/gamification/xp.ts b/frontend/src/shared/gamification/xp.ts index c6f541a8..9dbddcc4 100644 --- a/frontend/src/shared/gamification/xp.ts +++ b/frontend/src/shared/gamification/xp.ts @@ -12,6 +12,8 @@ export const XP_SOURCES = [ "course_completed", "weekly_goal_met", "daily_goal_met", + "game_round", + "game_set", ] as const; export type XpSource = (typeof XP_SOURCES)[number]; @@ -30,6 +32,10 @@ export const XP_AMOUNTS = { weekly_goal_met: 25, /** Brand daily-goal reward; no streak freeze (freezes stay on the weekly goal). */ daily_goal_met: 10, + /** A daily game round solved for the first time that day. Small on purpose: nine rounds a day. */ + game_round: 3, + /** All three rounds of one daily game solved in the same day. */ + game_set: 2, } as const satisfies Record; /** XP for passing a quiz chapter on a given try. Retakes after passing earn nothing (one key per chapter). */ @@ -45,6 +51,9 @@ export function quizPassedXp(attempt: number): number { */ export const XP_DAILY_CAPS: Partial> = { light_chapter_completed: 5, + // 3 games x 3 rounds. The key already makes each round once-a-day; this bounds a bug or a bad client. + game_round: 9, + game_set: 3, }; /** Award keys: one per moment, so retries, two tabs or a progress recompute award once. */ @@ -56,4 +65,6 @@ export const xpKeys = { course: (courseId: string) => `course:${courseId}`, weeklyGoal: (weekStartDayKey: string) => `weekly_goal:${weekStartDayKey}`, dailyGoal: (dayKey: string) => `daily_goal:${dayKey}`, + gameRound: (dayKey: string, game: string, roundIndex: number) => `game_round:${dayKey}:${game}:${roundIndex}`, + gameSet: (dayKey: string, game: string) => `game_set:${dayKey}:${game}`, }; diff --git a/server/prisma/migrations/20261118120000_game_plays/migration.sql b/server/prisma/migrations/20261118120000_game_plays/migration.sql new file mode 100644 index 00000000..6b1010b7 --- /dev/null +++ b/server/prisma/migrations/20261118120000_game_plays/migration.sql @@ -0,0 +1,24 @@ +-- CreateTable +CREATE TABLE "GamePlay" ( + "id" TEXT NOT NULL, + "userId" TEXT NOT NULL, + "game" TEXT NOT NULL, + "dayKey" DATE NOT NULL, + "roundIndex" INTEGER NOT NULL, + "stars" INTEGER NOT NULL, + "score" INTEGER NOT NULL, + "xpAwarded" INTEGER NOT NULL DEFAULT 0, + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" TIMESTAMP(3) NOT NULL, + + CONSTRAINT "GamePlay_pkey" PRIMARY KEY ("id") +); + +-- CreateIndex +CREATE UNIQUE INDEX "GamePlay_userId_game_dayKey_roundIndex_key" ON "GamePlay"("userId", "game", "dayKey", "roundIndex"); + +-- CreateIndex +CREATE INDEX "GamePlay_userId_dayKey_idx" ON "GamePlay"("userId", "dayKey"); + +-- AddForeignKey +ALTER TABLE "GamePlay" ADD CONSTRAINT "GamePlay_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE; diff --git a/server/prisma/schema.prisma b/server/prisma/schema.prisma index 4fd45dbc..7a16ec73 100644 --- a/server/prisma/schema.prisma +++ b/server/prisma/schema.prisma @@ -258,102 +258,103 @@ enum CareerTier { } model User { - id String @id @default(cuid()) - email String @unique - emailVerified DateTime? - name String? - image String? - role Role @default(MENTEE) - passwordHash String? + id String @id @default(cuid()) + email String @unique + emailVerified DateTime? + name String? + image String? + role Role @default(MENTEE) + passwordHash String? /// Base32 TOTP secret while MFA is set up. Null means MFA is off. - totpSecret String? @db.VarChar(64) + totpSecret String? @db.VarChar(64) /// Set once the account confirmed a TOTP code; MFA is enforced from then on. - totpEnabledAt DateTime? + totpEnabledAt DateTime? /// SHA-256 hashes of unused recovery codes. The plaintext is shown exactly once. - totpRecoveryCodes String[] @default([]) - zipImportEnabled Boolean @default(false) + totpRecoveryCodes String[] @default([]) + zipImportEnabled Boolean @default(false) /// Admin-granted tester: still a normal learner, but sequential chapter locks are skipped. - testerEnabled Boolean @default(false) + testerEnabled Boolean @default(false) /// Set by a platform admin to block sign-in; null means the account is active. - suspendedAt DateTime? - suspensionNote String? @db.VarChar(240) - weeklyGoalKind WeeklyGoalKind? - weeklyGoalTarget Int? + suspendedAt DateTime? + suspensionNote String? @db.VarChar(240) + weeklyGoalKind WeeklyGoalKind? + weeklyGoalTarget Int? /// DAILY or WEEKLY when a goal is set; null means no goal. - goalPeriod GoalPeriod? - weeklyGoalNote String? @db.VarChar(240) - weeklyGoalReminderEnabled Boolean @default(false) - weeklyGoalReminderSentOn DateTime? @db.Date + goalPeriod GoalPeriod? + weeklyGoalNote String? @db.VarChar(240) + weeklyGoalReminderEnabled Boolean @default(false) + weeklyGoalReminderSentOn DateTime? @db.Date /// Local calendar day the learner last dismissed the daily streak popup. - streakPopupSeenOn DateTime? @db.Date - celebratedStreakMilestones Int[] @default([]) + streakPopupSeenOn DateTime? @db.Date + celebratedStreakMilestones Int[] @default([]) /// Cached sum of XpEntry.amount; the ledger is the source of truth. - xpTotal Int @default(0) + xpTotal Int @default(0) /// Cached build-credit balance; the CreditEntry ledger is the source of truth. - buildCredits Int @default(0) + buildCredits Int @default(0) /// The equipped reward cosmetic applied to the mascot; must be owned. - activeCosmetic String? + activeCosmetic String? /// A purchased "session XP boost" is active until this instant (XP ×2 while active). - xpBoostUntil DateTime? + xpBoostUntil DateTime? /// Streak freezes held, 0..2 (shared/lib/streak.ts MAX_STREAK_FREEZES). - streakFreezes Int @default(0) + streakFreezes Int @default(0) /// "Hide game elements": no XP, levels, freezes or leaderboards shown, and off every board. - gamificationHidden Boolean @default(false) - leaderboardOptIn Boolean @default(false) + gamificationHidden Boolean @default(false) + leaderboardOptIn Boolean @default(false) /// Current league tier for the global weekly XP board. Set by the Monday reset. - leagueTier LeagueTier @default(BRONZE) + leagueTier LeagueTier @default(BRONZE) /// Highest career tier reached, permanently (never demotes). Advanced on verified mastery. - careerTier CareerTier @default(INTERN) + careerTier CareerTier @default(INTERN) /// Public Career Identity page: opt-in switch + unique handle used at /u/. Null until set. - profilePublic Boolean @default(false) - publicSlug String? @unique - createdAt DateTime @default(now()) - accounts Account[] - sessions Session[] - profile UserProfile? - learnerProfile LearnerProfile? - coursesOwned Course[] @relation("CourseMentor") - instructorCouponsCreated InstructorCoupon[] @relation("InstructorCouponCreator") - discountCampaignsCreated CourseDiscountCampaign[] - instructorCouponRedemptions InstructorCouponRedemption[] - courseMemberships CourseInstructor[] - courseInstructorInvitesSent CourseInstructorInvite[] @relation("CourseInstructorInviteSender") - enrollments Enrollment[] - courseRatings CourseRating[] - responses Response[] - reviewsGiven Review[] @relation("Reviewer") - invitesSent Invite[] @relation("InviteSender") - helpThreadsAsked HelpThread[] @relation("HelpThreadsAsked") - helpMessagesAuthored HelpMessage[] @relation("HelpMessagesAuthored") - headingNotes HeadingNote[] - highlights ChapterHighlight[] - organizationCourseRequestsReviewed OrganizationCourseRequest[] @relation("OrgCourseRequestReviewer") - instructorAccessRequest InstructorAccessRequest? - instructorAccessReviews InstructorAccessRequest[] @relation("InstructorAccessReviewer") - aiCredential AiCredential? - aiInterviewSessions AiInterviewSession[] - learnerQuestions LearnerQuestion[] - capstoneChecks CapstoneCheck[] - shellLabProgress ShellLabProgress[] - certificates Certificate[] - appActivity UserAppActivity? - appActivityDays AppActivityDay[] - notifications Notification[] - notificationPreference NotificationPreference? - emailOutbox EmailOutbox[] - studyReminders StudyReminderLog[] - engagementEvents EngagementEvent[] - desktopUpdatePolicies DesktopUpdatePolicy[] - xpEntries XpEntry[] - streakFreezeDays StreakFreezeDay[] - leaderboardMemberships LeaderboardMember[] - leaderboardPlacements LeaderboardPlacement[] - leaguePlacements LeaguePlacement[] - couponUsages CouponUsage[] - creditEntries CreditEntry[] - unlockedCosmetics UnlockedCosmetic[] - rewardInventory RewardInventory[] - instructorWithdrawals InstructorWithdrawal[] + profilePublic Boolean @default(false) + publicSlug String? @unique + createdAt DateTime @default(now()) + accounts Account[] + sessions Session[] + profile UserProfile? + learnerProfile LearnerProfile? + coursesOwned Course[] @relation("CourseMentor") + instructorCouponsCreated InstructorCoupon[] @relation("InstructorCouponCreator") + discountCampaignsCreated CourseDiscountCampaign[] + instructorCouponRedemptions InstructorCouponRedemption[] + courseMemberships CourseInstructor[] + courseInstructorInvitesSent CourseInstructorInvite[] @relation("CourseInstructorInviteSender") + enrollments Enrollment[] + courseRatings CourseRating[] + responses Response[] + reviewsGiven Review[] @relation("Reviewer") + invitesSent Invite[] @relation("InviteSender") + helpThreadsAsked HelpThread[] @relation("HelpThreadsAsked") + helpMessagesAuthored HelpMessage[] @relation("HelpMessagesAuthored") + headingNotes HeadingNote[] + highlights ChapterHighlight[] + organizationCourseRequestsReviewed OrganizationCourseRequest[] @relation("OrgCourseRequestReviewer") + instructorAccessRequest InstructorAccessRequest? + instructorAccessReviews InstructorAccessRequest[] @relation("InstructorAccessReviewer") + aiCredential AiCredential? + aiInterviewSessions AiInterviewSession[] + learnerQuestions LearnerQuestion[] + capstoneChecks CapstoneCheck[] + shellLabProgress ShellLabProgress[] + certificates Certificate[] + appActivity UserAppActivity? + appActivityDays AppActivityDay[] + notifications Notification[] + notificationPreference NotificationPreference? + emailOutbox EmailOutbox[] + studyReminders StudyReminderLog[] + engagementEvents EngagementEvent[] + desktopUpdatePolicies DesktopUpdatePolicy[] + xpEntries XpEntry[] + gamePlays GamePlay[] + streakFreezeDays StreakFreezeDay[] + leaderboardMemberships LeaderboardMember[] + leaderboardPlacements LeaderboardPlacement[] + leaguePlacements LeaguePlacement[] + couponUsages CouponUsage[] + creditEntries CreditEntry[] + unlockedCosmetics UnlockedCosmetic[] + rewardInventory RewardInventory[] + instructorWithdrawals InstructorWithdrawal[] } /// A learner's own AI provider key for AI interviews. Only the AES-256-GCM @@ -379,27 +380,27 @@ model AiCredential { /// learner's own words plus the interviewer's questions; the rubric lives only /// in Block.config and is never copied here. model AiInterviewSession { - id String @id @default(cuid()) - userId String - user User @relation(fields: [userId], references: [id], onDelete: Cascade) - blockId String - block Block @relation(fields: [blockId], references: [id], onDelete: Cascade) - status AiInterviewStatus @default(ACTIVE) + id String @id @default(cuid()) + userId String + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + blockId String + block Block @relation(fields: [blockId], references: [id], onDelete: Cascade) + status AiInterviewStatus @default(ACTIVE) /// Resume or project text the learner pasted, when the block asks for it. - context String? @db.Text + context String? @db.Text /// The "important work" box, when the block asks for a resume and work together. - contextWork String? @db.Text + contextWork String? @db.Text /// Ordered turns: [{ role: "interviewer" | "candidate", content, focus?, depth?, at }]. - transcript Json @default("[]") + transcript Json @default("[]") /// Validated AiInterviewFeedback, set when the session finishes. - feedback Json? + feedback Json? /// Answers the learner has given so far. - turnCount Int @default(0) + turnCount Int @default(0) /// Model id used, kept so a mentor can see what produced the feedback. - model String? @db.VarChar(120) - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt - finishedAt DateTime? + model String? @db.VarChar(120) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + finishedAt DateTime? @@index([userId, blockId, status]) @@index([blockId]) @@ -420,15 +421,15 @@ model InstructorAccessRequest { } model UserProfile { - userId String @id - user User @relation(fields: [userId], references: [id], onDelete: Cascade) - timezone String @default("UTC") - skills String[] @default([]) + userId String @id + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + timezone String @default("UTC") + skills String[] @default([]) /// One-line profile headline shown on the Career Identity page (e.g. "Backend Engineering · Learning in public"). headline String? /// Appends " · Learning in public" to the headline on the public page. - learningInPublic Boolean @default(false) - updatedAt DateTime @updatedAt + learningInPublic Boolean @default(false) + updatedAt DateTime @updatedAt } model LearnerProfile { @@ -442,69 +443,69 @@ model LearnerProfile { } model Course { - id String @id @default(cuid()) - slug String @unique - title String - description String? - coverUrl String? - projectGoal String? // "Build a multi-vendor marketplace" - difficulty String? - estimatedHours Int? - category CourseCategory @default(TECH) - subcategory String? - tags String[] @default([]) - status CourseStatus @default(DRAFT) - pricingType CoursePricingType @default(FREE) - priceCents Int @default(0) - currency String @default("USD") + id String @id @default(cuid()) + slug String @unique + title String + description String? + coverUrl String? + projectGoal String? // "Build a multi-vendor marketplace" + difficulty String? + estimatedHours Int? + category CourseCategory @default(TECH) + subcategory String? + tags String[] @default([]) + status CourseStatus @default(DRAFT) + pricingType CoursePricingType @default(FREE) + priceCents Int @default(0) + currency String @default("USD") /// The course's Polar product, created on its first paid checkout. Null until then. - polarProductId String? @unique + polarProductId String? @unique /// Global instructor share used by the financial calculator. - instructorPayoutPercent Int @default(70) - sequential Boolean @default(true) + instructorPayoutPercent Int @default(70) + sequential Boolean @default(true) /// When true, text open questions grade instantly with the learner's OpenRouter key instead of the mentor queue. - autoGradeOpenQuestions Boolean @default(false) - familySlug String? // course family in src/shared/lib/course-tracks.ts; null = no variants - variantFamily Json? // creator-defined variant catalog; null uses a built-in family - assistant Json? // tutor settings from course.yaml (effort, guidance, starters); null means defaults - certificate Json? // certificate settings from course.yaml (program, title, code, skills); null means no certificate - certificates Certificate[] - availableVariantSlugs String[] @default([]) // empty means every family variant is available - variantAssignment VariantAssignment @default(SELF_SELECT) - activeReleaseId String? // latest approved content release; set atomically with publication - repositorySourceHash String? // last repository package published by the backend release - repositoryReleaseId String? // release active when that package was published - releases CourseRelease[] + autoGradeOpenQuestions Boolean @default(false) + familySlug String? // course family in src/shared/lib/course-tracks.ts; null = no variants + variantFamily Json? // creator-defined variant catalog; null uses a built-in family + assistant Json? // tutor settings from course.yaml (effort, guidance, starters); null means defaults + certificate Json? // certificate settings from course.yaml (program, title, code, skills); null means no certificate + certificates Certificate[] + availableVariantSlugs String[] @default([]) // empty means every family variant is available + variantAssignment VariantAssignment @default(SELF_SELECT) + activeReleaseId String? // latest approved content release; set atomically with publication + repositorySourceHash String? // last repository package published by the backend release + repositoryReleaseId String? // release active when that package was published + releases CourseRelease[] /// Quiz camera photos are opt-in per course and never required; quiz integrity signals are always on. - integritySnapshots Boolean @default(false) - mentorId String - mentor User @relation("CourseMentor", fields: [mentorId], references: [id]) - instructors CourseInstructor[] - instructorInvites CourseInstructorInvite[] - modules Module[] - importPreviews CourseImportPreview[] - chapters Chapter[] - chapterDrafts CourseChapterDraft[] - enrollments Enrollment[] - organizationCourses OrganizationCourse[] - organizationFreeAccesses CourseOrganizationAccess[] + integritySnapshots Boolean @default(false) + mentorId String + mentor User @relation("CourseMentor", fields: [mentorId], references: [id]) + instructors CourseInstructor[] + instructorInvites CourseInstructorInvite[] + modules Module[] + importPreviews CourseImportPreview[] + chapters Chapter[] + chapterDrafts CourseChapterDraft[] + enrollments Enrollment[] + organizationCourses OrganizationCourse[] + organizationFreeAccesses CourseOrganizationAccess[] organizationCourseRequests OrganizationCourseRequest[] - couponPools OrganizationCouponPool[] - couponUsages CouponUsage[] - instructorCoupons InstructorCoupon[] - invites Invite[] - helpThreads HelpThread[] - ratings CourseRating[] + couponPools OrganizationCouponPool[] + couponUsages CouponUsage[] + instructorCoupons InstructorCoupon[] + invites Invite[] + helpThreads HelpThread[] + ratings CourseRating[] /// Cached aggregate of CourseRating, maintained on every write so catalog cards stay one query. - ratingAverage Float? - ratingCount Int @default(0) - publishedAt DateTime? - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt + ratingAverage Float? + ratingCount Int @default(0) + publishedAt DateTime? + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + leaderboardGroups LeaderboardGroup[] + leaderboardPlacements LeaderboardPlacement[] @@index([mentorId, status]) - leaderboardGroups LeaderboardGroup[] - leaderboardPlacements LeaderboardPlacement[] } /// One learner's rating of a completed course. Editable, never duplicated. @@ -599,14 +600,14 @@ model CourseInstructorInvite { } model Module { - id String @id @default(cuid()) - courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + id String @id @default(cuid()) + courseId String + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) contentKey String? // stable author key, independent of title, path and order - title String - order Int + title String + order Int archivedAt DateTime? - chapters Chapter[] + chapters Chapter[] @@unique([courseId, order]) @@unique([courseId, contentKey]) @@ -618,24 +619,24 @@ enum ChapterReaderMode { } model Chapter { - id String @id @default(cuid()) + id String @id @default(cuid()) courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) moduleId String? - module Module? @relation(fields: [moduleId], references: [id], onDelete: SetNull) - contentKey String? // stable author key, independent of title, path and module + module Module? @relation(fields: [moduleId], references: [id], onDelete: SetNull) + contentKey String? // stable author key, independent of title, path and module slug String title String summary String? order Int estimatedMinutes Int? - readerMode ChapterReaderMode @default(DEFAULT) + readerMode ChapterReaderMode @default(DEFAULT) /// Minimum weighted assessment percentage required in quiz mode. - quizPassingScore Int @default(70) - source String @db.Text // raw MDX (draft) - compiled String? @db.Text // compiled MDX at publish + quizPassingScore Int @default(70) + source String @db.Text // raw MDX (draft) + compiled String? @db.Text // compiled MDX at publish publishedAt DateTime? - isMilestone Boolean @default(false) + isMilestone Boolean @default(false) archivedAt DateTime? blocks Block[] progress ChapterProgress[] @@ -644,7 +645,7 @@ model Chapter { headingNotes HeadingNote[] highlights ChapterHighlight[] integrityAttempts IntegrityAttempt[] - releaseDraft CourseChapterDraft? + releaseDraft CourseChapterDraft? @@unique([courseId, slug]) @@unique([courseId, contentKey]) @@ -652,35 +653,35 @@ model Chapter { } model CourseChapterDraft { - chapterId String @id - chapter Chapter @relation(fields: [chapterId], references: [id], onDelete: Cascade) - courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) - baseReleaseId String - title String - summary String? + chapterId String @id + chapter Chapter @relation(fields: [chapterId], references: [id], onDelete: Cascade) + courseId String + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + baseReleaseId String + title String + summary String? estimatedMinutes Int? - readerMode ChapterReaderMode - quizPassingScore Int @default(70) - isMilestone Boolean - source String @db.Text - updatedAt DateTime @updatedAt + readerMode ChapterReaderMode + quizPassingScore Int @default(70) + isMilestone Boolean + source String @db.Text + updatedAt DateTime @updatedAt @@index([courseId]) } // Server-owned preview: clients approve an immutable, expiring update, never send a plan to apply. model CourseImportPreview { - id String @id @default(cuid()) + id String @id @default(cuid()) courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) userId String fingerprint String plan Json diff Json expiresAt DateTime appliedAt DateTime? - createdAt DateTime @default(now()) + createdAt DateTime @default(now()) @@index([courseId, userId]) @@index([expiresAt]) @@ -689,13 +690,13 @@ model CourseImportPreview { // Immutable, materialized curriculum. Each variant lists the chapter rows it uses; // shared chapters may be referenced by several variants and releases. model CourseRelease { - id String @id @default(cuid()) + id String @id @default(cuid()) courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) number Int content Json sourceHash String? - createdAt DateTime @default(now()) + createdAt DateTime @default(now()) enrollments Enrollment[] @@unique([courseId, number]) @@ -703,79 +704,79 @@ model CourseRelease { } model Block { - id String @id // ULID authored into the MDX - chapterId String - chapter Chapter @relation(fields: [chapterId], references: [id], onDelete: Cascade) - type BlockType - order Int - version Int @default(1) - required Boolean @default(true) - blocking Boolean @default(false) - points Int @default(1) - config Json // answers, rubric, tests — SERVER ONLY, never sent to the client - sourceHash String? // hash of the block's MDX subtree; change detection bumps version (docs/02-content-authoring.mdx) - tags String[] // for weak-area reporting - archivedAt DateTime? + id String @id // ULID authored into the MDX + chapterId String + chapter Chapter @relation(fields: [chapterId], references: [id], onDelete: Cascade) + type BlockType + order Int + version Int @default(1) + required Boolean @default(true) + blocking Boolean @default(false) + points Int @default(1) + config Json // answers, rubric, tests — SERVER ONLY, never sent to the client + sourceHash String? // hash of the block's MDX subtree; change detection bumps version (docs/02-content-authoring.mdx) + tags String[] // for weak-area reporting + archivedAt DateTime? // Null for blocks that existed before this column. Progress uses it so a // block added after a learner finished a chapter cannot reopen it. - createdAt DateTime? @default(now()) - responses Response[] - stats BlockStats? + createdAt DateTime? @default(now()) + responses Response[] + stats BlockStats? aiInterviewSessions AiInterviewSession[] - capstoneChecks CapstoneCheck[] + capstoneChecks CapstoneCheck[] @@index([chapterId, order]) } model Enrollment { - id String @id @default(cuid()) - courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) - userId String? - user User? @relation(fields: [userId], references: [id], onDelete: Cascade) - learnerProfileId String? - learnerProfile LearnerProfile? @relation(fields: [learnerProfileId], references: [id], onDelete: Cascade) - organizationId String? - organization Organization? @relation(fields: [organizationId], references: [id], onDelete: SetNull) - lifecycle EnrollmentLifecycle @default(ACTIVE) - source EnrollmentSource @default(DIRECT) - externalMentorId String? - externalAssignmentId String? - status EnrollStatus @default(ASSIGNED) - assignedById String? - percentComplete Int @default(0) - chaptersCompleted Int @default(0) - totalScore Int @default(0) - maxScore Int @default(0) - pendingReviews Int @default(0) // denormalized for reports — maintained at Response write/review time - xpTotal Int @default(0) // cached sum of this enrollment's XpEntry rows - lastActiveAt DateTime? - lastNudgeSentAt DateTime? - startedAt DateTime? - completedAt DateTime? + id String @id @default(cuid()) + courseId String + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + userId String? + user User? @relation(fields: [userId], references: [id], onDelete: Cascade) + learnerProfileId String? + learnerProfile LearnerProfile? @relation(fields: [learnerProfileId], references: [id], onDelete: Cascade) + organizationId String? + organization Organization? @relation(fields: [organizationId], references: [id], onDelete: SetNull) + lifecycle EnrollmentLifecycle @default(ACTIVE) + source EnrollmentSource @default(DIRECT) + externalMentorId String? + externalAssignmentId String? + status EnrollStatus @default(ASSIGNED) + assignedById String? + percentComplete Int @default(0) + chaptersCompleted Int @default(0) + totalScore Int @default(0) + maxScore Int @default(0) + pendingReviews Int @default(0) // denormalized for reports — maintained at Response write/review time + xpTotal Int @default(0) // cached sum of this enrollment's XpEntry rows + lastActiveAt DateTime? + lastNudgeSentAt DateTime? + startedAt DateTime? + completedAt DateTime? /// Set when the learner dismisses the post-completion rating prompt. Keeps /// the one-time ask from reappearing; the course page keeps a small link. - ratingDismissedAt DateTime? - variantSlug String? // learner's variant in the course family; null = not picked yet - variantChosenAt DateTime? - variantLockedAt DateTime? // first chapter start fixes the learner's variant - variantAssignedAt DateTime? // assignment at enrollment, never inferred from the current course setting - releaseId String? - release CourseRelease? @relation(fields: [releaseId], references: [id], onDelete: SetNull) - specialisationSlug String? // follow-up track picked once the course is complete - specialisationChosenAt DateTime? - createdAt DateTime @default(now()) - chapterProgress ChapterProgress[] - highlights ChapterHighlight[] - dailyActivity DailyActivity[] - studySessions StudySession[] - integrityAttempts IntegrityAttempt[] - payment Payment? - instructorCouponRedemption InstructorCouponRedemption? - xpEntries XpEntry[] - couponUsage CouponUsage? + ratingDismissedAt DateTime? + variantSlug String? // learner's variant in the course family; null = not picked yet + variantChosenAt DateTime? + variantLockedAt DateTime? // first chapter start fixes the learner's variant + variantAssignedAt DateTime? // assignment at enrollment, never inferred from the current course setting + releaseId String? + release CourseRelease? @relation(fields: [releaseId], references: [id], onDelete: SetNull) + specialisationSlug String? // follow-up track picked once the course is complete + specialisationChosenAt DateTime? + createdAt DateTime @default(now()) + chapterProgress ChapterProgress[] + highlights ChapterHighlight[] + dailyActivity DailyActivity[] + studySessions StudySession[] + integrityAttempts IntegrityAttempt[] + payment Payment? + instructorCouponRedemption InstructorCouponRedemption? + xpEntries XpEntry[] + couponUsage CouponUsage? organizationCreditTransaction OrganizationCreditTransaction? - certificate Certificate? + certificate Certificate? @@unique([courseId, userId]) @@unique([courseId, learnerProfileId]) @@ -786,19 +787,19 @@ model Enrollment { } model Organization { - id String @id @default(cuid()) - slug String @unique - name String - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt - apiCredentials OrganizationApiCredential[] - courseAllocations OrganizationCourse[] - courseRequests OrganizationCourseRequest[] - enrollments Enrollment[] - couponPools OrganizationCouponPool[] - couponUsages CouponUsage[] + id String @id @default(cuid()) + slug String @unique + name String + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + apiCredentials OrganizationApiCredential[] + courseAllocations OrganizationCourse[] + courseRequests OrganizationCourseRequest[] + enrollments Enrollment[] + couponPools OrganizationCouponPool[] + couponUsages CouponUsage[] freeCourseAccesses CourseOrganizationAccess[] - creditBalance Int @default(0) + creditBalance Int @default(0) creditTransactions OrganizationCreditTransaction[] } @@ -807,7 +808,7 @@ model CourseOrganizationAccess { courseId String organizationId String course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) - organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) + organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) createdAt DateTime @default(now()) @@id([courseId, organizationId]) @@ -816,16 +817,16 @@ model CourseOrganizationAccess { /// Append-only organization credit movement linked to the enrollment it funds. model OrganizationCreditTransaction { - id String @id @default(cuid()) + id String @id @default(cuid()) organizationId String - organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) - enrollmentId String @unique - enrollment Enrollment @relation(fields: [enrollmentId], references: [id], onDelete: Cascade) - amountCredits Int - status OrganizationCreditTransactionStatus @default(RESERVED) - createdAt DateTime @default(now()) - committedAt DateTime? - releasedAt DateTime? + organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) + enrollmentId String @unique + enrollment Enrollment @relation(fields: [enrollmentId], references: [id], onDelete: Cascade) + amountCredits Int + status OrganizationCreditTransactionStatus @default(RESERVED) + createdAt DateTime @default(now()) + committedAt DateTime? + releasedAt DateTime? @@index([organizationId, status]) } @@ -833,22 +834,22 @@ model OrganizationCreditTransaction { /// Limited coupon seats an organization can grant for one course, or for any allocated course /// when courseId is null. Checkout can later show the discount; 100% off unlocks content now. model OrganizationCouponPool { - id String @id @default(cuid()) + id String @id @default(cuid()) organizationId String - organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) + organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) /// Null = general pool usable on any course allocated to the organization. courseId String? - course Course? @relation(fields: [courseId], references: [id], onDelete: Cascade) + course Course? @relation(fields: [courseId], references: [id], onDelete: Cascade) label String /// Optional human code for later learner redeem / checkout flows. code String? - percentOff Int @default(100) + percentOff Int @default(100) maxRedemptions Int - redemptionCount Int @default(0) - active Boolean @default(true) + redemptionCount Int @default(0) + active Boolean @default(true) expiresAt DateTime? - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt usages CouponUsage[] @@index([organizationId, courseId, active]) @@ -857,23 +858,23 @@ model OrganizationCouponPool { /// Course-specific percentage coupons and automatic discounts created by instructors or admins. model InstructorCoupon { - id String @id @default(cuid()) + id String @id @default(cuid()) courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) createdById String - createdBy User @relation("InstructorCouponCreator", fields: [createdById], references: [id], onDelete: Cascade) + createdBy User @relation("InstructorCouponCreator", fields: [createdById], references: [id], onDelete: Cascade) code String? label String - percentOff Int @default(100) - autoApply Boolean @default(false) + percentOff Int @default(100) + autoApply Boolean @default(false) maxRedemptions Int - redemptionCount Int @default(0) - active Boolean @default(true) + redemptionCount Int @default(0) + active Boolean @default(true) expiresAt DateTime? campaignId String? - campaign CourseDiscountCampaign? @relation(fields: [campaignId], references: [id], onDelete: Cascade) - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt + campaign CourseDiscountCampaign? @relation(fields: [campaignId], references: [id], onDelete: Cascade) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt redemptions InstructorCouponRedemption[] @@unique([courseId, code]) @@ -908,15 +909,15 @@ model CourseDiscountCampaign { } model InstructorCouponRedemption { - id String @id @default(cuid()) - couponId String - coupon InstructorCoupon @relation(fields: [couponId], references: [id], onDelete: Cascade) - enrollmentId String @unique - enrollment Enrollment @relation(fields: [enrollmentId], references: [id], onDelete: Cascade) - userId String - user User @relation(fields: [userId], references: [id], onDelete: Cascade) - percentOff Int - redeemedAt DateTime @default(now()) + id String @id @default(cuid()) + couponId String + coupon InstructorCoupon @relation(fields: [couponId], references: [id], onDelete: Cascade) + enrollmentId String @unique + enrollment Enrollment @relation(fields: [enrollmentId], references: [id], onDelete: Cascade) + userId String + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + percentOff Int + redeemedAt DateTime @default(now()) @@index([couponId, redeemedAt]) } @@ -924,23 +925,23 @@ model InstructorCouponRedemption { /// One reserved seat from a pool, created when a mentor/Pathment assigns the course. /// Marked redeemed when access is granted (immediately for full discounts, after manual approval for partial discounts). model CouponUsage { - id String @id @default(cuid()) + id String @id @default(cuid()) poolId String pool OrganizationCouponPool @relation(fields: [poolId], references: [id], onDelete: Cascade) organizationId String - organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) + organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) - enrollmentId String? @unique - enrollment Enrollment? @relation(fields: [enrollmentId], references: [id], onDelete: SetNull) + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + enrollmentId String? @unique + enrollment Enrollment? @relation(fields: [enrollmentId], references: [id], onDelete: SetNull) userId String? - user User? @relation(fields: [userId], references: [id], onDelete: SetNull) + user User? @relation(fields: [userId], references: [id], onDelete: SetNull) learnerEmail String? - status CouponUsageStatus @default(ISSUED) + status CouponUsageStatus @default(ISSUED) percentOff Int displayLabel String assignedById String? - issuedAt DateTime @default(now()) + issuedAt DateTime @default(now()) redeemedAt DateTime? cancelledAt DateTime? @@ -999,30 +1000,30 @@ model OrganizationCourseRequest { } model Payment { - id String @id @default(cuid()) - enrollmentId String @unique - enrollment Enrollment @relation(fields: [enrollmentId], references: [id], onDelete: Cascade) - amountCents Int - currency String @default("USD") - status PaymentStatus @default(PENDING) - provider String? - providerRef String? - originalAmountCents Int @default(0) - discountAmountCents Int @default(0) - organizationContributionCents Int @default(0) - learnerAmountCents Int @default(0) - instructorPayoutPercent Int @default(0) - platformRevenueCents Int @default(0) - fundingSource String? - paidAt DateTime? - instructorShareCents Int @default(0) - instructorPayoutStatus InstructorPayoutStatus @default(NOT_DUE) - instructorPayoutPaidAt DateTime? + id String @id @default(cuid()) + enrollmentId String @unique + enrollment Enrollment @relation(fields: [enrollmentId], references: [id], onDelete: Cascade) + amountCents Int + currency String @default("USD") + status PaymentStatus @default(PENDING) + provider String? + providerRef String? + originalAmountCents Int @default(0) + discountAmountCents Int @default(0) + organizationContributionCents Int @default(0) + learnerAmountCents Int @default(0) + instructorPayoutPercent Int @default(0) + platformRevenueCents Int @default(0) + fundingSource String? + paidAt DateTime? + instructorShareCents Int @default(0) + instructorPayoutStatus InstructorPayoutStatus @default(NOT_DUE) + instructorPayoutPaidAt DateTime? /// Set while these earnings are reserved by a withdrawal request, and kept after that request is paid. - payoutWithdrawalId String? - payoutWithdrawal InstructorWithdrawal? @relation(fields: [payoutWithdrawalId], references: [id], onDelete: SetNull) - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt + payoutWithdrawalId String? + payoutWithdrawal InstructorWithdrawal? @relation(fields: [payoutWithdrawalId], references: [id], onDelete: SetNull) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt @@index([instructorPayoutStatus, status]) @@index([payoutWithdrawalId]) @@ -1030,17 +1031,17 @@ model Payment { /// Instructor request to be paid the earnings already calculated on Payment rows. model InstructorWithdrawal { - id String @id @default(cuid()) + id String @id @default(cuid()) instructorId String - instructor User @relation(fields: [instructorId], references: [id], onDelete: Cascade) + instructor User @relation(fields: [instructorId], references: [id], onDelete: Cascade) amountCents Int - currency String @default("USD") - status InstructorWithdrawalStatus @default(REQUESTED) + currency String @default("USD") + status InstructorWithdrawalStatus @default(REQUESTED) /// Where the instructor asked to receive the transfer. - note String @db.VarChar(240) + note String @db.VarChar(240) /// Payment ids included when the request was created. Kept after a rejection. paymentIds String[] - requestedAt DateTime @default(now()) + requestedAt DateTime @default(now()) resolvedAt DateTime? resolvedById String? payments Payment[] @@ -1216,13 +1217,13 @@ model LeaguePlacement { } model Notification { - id String @id @default(cuid()) + id String @id @default(cuid()) userId String - user User @relation(fields: [userId], references: [id], onDelete: Cascade) + user User @relation(fields: [userId], references: [id], onDelete: Cascade) type String category String title String - body String @db.Text + body String @db.Text /// App-relative link, e.g. /my-questions/abc. url String? courseId String? @@ -1343,22 +1344,22 @@ model ChapterProgress { } model Response { - id String @id @default(cuid()) - blockId String - block Block @relation(fields: [blockId], references: [id], onDelete: Cascade) - userId String - user User @relation(fields: [userId], references: [id], onDelete: Cascade) - enrollmentId String - attempt Int @default(1) - status ResponseStatus @default(SUBMITTED) - payload Json // shape depends on block type — see docs/08-data-model.mdx - score Int? - maxScore Int? - isCorrect Boolean? - durationMs Int? - startedAt DateTime? - submittedAt DateTime @default(now()) - review Review? + id String @id @default(cuid()) + blockId String + block Block @relation(fields: [blockId], references: [id], onDelete: Cascade) + userId String + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + enrollmentId String + attempt Int @default(1) + status ResponseStatus @default(SUBMITTED) + payload Json // shape depends on block type — see docs/08-data-model.mdx + score Int? + maxScore Int? + isCorrect Boolean? + durationMs Int? + startedAt DateTime? + submittedAt DateTime @default(now()) + review Review? capstoneCheck CapstoneCheck? @@index([blockId, userId, attempt]) @@ -1395,26 +1396,26 @@ enum HelpThreadCategory { } model HelpThread { - id String @id @default(cuid()) - courseId String - course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) - chapterId String? - chapter Chapter? @relation(fields: [chapterId], references: [id], onDelete: SetNull) - menteeId String - mentee User @relation("HelpThreadsAsked", fields: [menteeId], references: [id], onDelete: Cascade) - status HelpThreadStatus @default(OPEN) + id String @id @default(cuid()) + courseId String + course Course @relation(fields: [courseId], references: [id], onDelete: Cascade) + chapterId String? + chapter Chapter? @relation(fields: [chapterId], references: [id], onDelete: SetNull) + menteeId String + mentee User @relation("HelpThreadsAsked", fields: [menteeId], references: [id], onDelete: Cascade) + status HelpThreadStatus @default(OPEN) // A question is a conversation the learner starts with the mentor. A lesson // report is the same thread machinery, tagged with a category and an optional // block/quote so the instructor can find the exact passage that is wrong. - kind HelpThreadKind @default(QUESTION) - category HelpThreadCategory? - blockId String? - quote String? @db.Text + kind HelpThreadKind @default(QUESTION) + category HelpThreadCategory? + blockId String? + quote String? @db.Text menteeLastReadAt DateTime? - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt - resolvedAt DateTime? - messages HelpMessage[] + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + resolvedAt DateTime? + messages HelpMessage[] @@index([courseId, status, updatedAt]) @@index([menteeId, updatedAt]) @@ -1423,22 +1424,22 @@ model HelpThread { } model HelpMessage { - id String @id @default(cuid()) - threadId String - thread HelpThread @relation(fields: [threadId], references: [id], onDelete: Cascade) - authorId String - author User @relation("HelpMessagesAuthored", fields: [authorId], references: [id], onDelete: Cascade) - body String @db.Text + id String @id @default(cuid()) + threadId String + thread HelpThread @relation(fields: [threadId], references: [id], onDelete: Cascade) + authorId String + author User @relation("HelpMessagesAuthored", fields: [authorId], references: [id], onDelete: Cascade) + body String @db.Text // Reply points at the specific earlier message it answers; null for a plain // follow-up or the first message in a thread. - replyToId String? - replyTo HelpMessage? @relation("HelpMessageReplies", fields: [replyToId], references: [id], onDelete: SetNull) - replies HelpMessage[] @relation("HelpMessageReplies") + replyToId String? + replyTo HelpMessage? @relation("HelpMessageReplies", fields: [replyToId], references: [id], onDelete: SetNull) + replies HelpMessage[] @relation("HelpMessageReplies") // Chat receipts for the author's ticks: delivered = the other side was online / came // online (grey double tick), seen = they opened the conversation (blue double tick). deliveredAt DateTime? seenAt DateTime? - createdAt DateTime @default(now()) + createdAt DateTime @default(now()) @@index([threadId, createdAt]) @@index([replyToId]) @@ -1781,3 +1782,25 @@ model DesktopUpdatePolicy { @@map("desktop_update_policies") } + +/// One solved daily game round. Only solved rounds are stored, once per learner, game, day and round. +/// The best stars win if a learner replays a round the same day. +model GamePlay { + id String @id @default(cuid()) + userId String + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + /// "sysdesign", "linux" or "docker" (shared/games/types.ts GAME_IDS). + game String + /// The learner's local calendar day. + dayKey DateTime @db.Date + /// 0 easy, 1 medium, 2 hard. + roundIndex Int + stars Int + score Int + xpAwarded Int @default(0) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([userId, game, dayKey, roundIndex]) + @@index([userId, dayKey]) +} diff --git a/server/src/controllers/games.ts b/server/src/controllers/games.ts new file mode 100644 index 00000000..c527f8e6 --- /dev/null +++ b/server/src/controllers/games.ts @@ -0,0 +1,14 @@ +import type { Request, Response } from "express"; +import { ok } from "../utils/responses.js"; +import { loadDailyGames, submitRound } from "../services/games/daily.js"; + +// GET /api/v1/games/daily +export async function daily(req: Request, res: Response) { + ok(res, await loadDailyGames(req.user?.id ?? null)); +} + +// POST /api/v1/games/:game/rounds/:index/submit +export async function submit(req: Request, res: Response) { + const { game, index } = req.params as { game: string; index: string }; + ok(res, await submitRound(req.user!.id, game, Number(index), (req.body as { submission: unknown }).submission)); +} diff --git a/server/src/routes/v1/games.ts b/server/src/routes/v1/games.ts new file mode 100644 index 00000000..39923140 --- /dev/null +++ b/server/src/routes/v1/games.ts @@ -0,0 +1,21 @@ +import { Router } from "express"; +import * as games from "../../controllers/games.js"; +import { authenticate, optionalAuth } from "../../middlewares/authenticate.js"; +import { userRateLimit } from "../../middlewares/rate-limit.js"; +import { validate } from "../../middlewares/validate.js"; +import { submitRoundBody, submitRoundParams } from "../../validations/games.js"; + +// Daily games (docs/17-daily-games.mdx). Reading today's set is open to visitors, so they can play +// without signing in; only a signed-in learner records progress and earns XP. +const router = Router(); + +router.get("/daily", optionalAuth, games.daily); +router.post( + "/:game/rounds/:index/submit", + authenticate, + userRateLimit({ scope: "game-submit", max: 40 }), + validate({ params: submitRoundParams, body: submitRoundBody }), + games.submit, +); + +export default router; diff --git a/server/src/routes/v1/index.ts b/server/src/routes/v1/index.ts index bb9e67bb..50bee432 100644 --- a/server/src/routes/v1/index.ts +++ b/server/src/routes/v1/index.ts @@ -18,6 +18,7 @@ import activityRoutes from "./activity.js"; import notificationRoutes from "./notifications.js"; import engagementRoutes from "./engagement.js"; import eventRoutes from "./events.js"; +import gamesRoutes from "./games.js"; import publicRoutes from "./public.js"; import certificateRoutes from "./certificates.js"; import shellLabRoutes from "./shell-labs.js"; @@ -49,6 +50,7 @@ router.use("/integrity", integrityRoutes); router.use("/activity", activityRoutes); router.use("/notifications", notificationRoutes); router.use("/events", engagementRoutes); +router.use("/games", gamesRoutes); router.use("/events", eventRoutes); router.use("/public", publicRoutes); router.use("/certificates", certificateRoutes); diff --git a/server/src/services/games/daily.ts b/server/src/services/games/daily.ts new file mode 100644 index 00000000..101be4e5 --- /dev/null +++ b/server/src/services/games/daily.ts @@ -0,0 +1,76 @@ +import { prisma } from "../../db/prisma.js"; +import { learnerTimeZone } from "../learner/time-zone.js"; +import { awardXp } from "../gamification/xp.js"; +import { BadRequestError, NotFoundError } from "../../utils/errors.js"; +import { XP_AMOUNTS, xpKeys } from "../../shared/gamification/xp.js"; +import { dayKeyToDate, localDayKey, shiftDayKey, startOfLocalDay } from "../../shared/lib/local-date.js"; +import { GAME_IDS, ROUNDS_PER_DAY, engineFor, isGameId, type GameId } from "../../shared/games/index.js"; +import type { DailyGameView, DailyGamesView, GameRoundProgress, SubmitRoundResult } from "../../shared/api/games.js"; +import type { Stars } from "../../shared/games/types.js"; + +/** The most XP the games can give in one day: every round and every set bonus. */ +export const GAMES_XP_PER_DAY = GAME_IDS.length * (ROUNDS_PER_DAY * XP_AMOUNTS.game_round + XP_AMOUNTS.game_set); + +async function dayFor(userId: string | null, now: Date) { + const timeZone = userId ? await learnerTimeZone(userId) : "UTC"; + const dayKey = localDayKey(now, timeZone); + return { timeZone, dayKey, resetsAt: startOfLocalDay(shiftDayKey(dayKey, 1), timeZone) }; +} + +/** Today's games for a learner, or for a visitor with no progress. */ +export async function loadDailyGames(userId: string | null, now = new Date()): Promise { + const { dayKey, resetsAt } = await dayFor(userId, now); + const plays = userId + ? await prisma.gamePlay.findMany({ where: { userId, dayKey: dayKeyToDate(dayKey) }, select: { game: true, roundIndex: true, stars: true, score: true, xpAwarded: true } }) + : []; + const bonus = userId + ? await prisma.xpEntry.findMany({ where: { userId, source: "game_set", dayKey: dayKeyToDate(dayKey) }, select: { amount: true } }) + : []; + const xpToday = plays.reduce((sum, play) => sum + play.xpAwarded, 0) + bonus.reduce((sum, entry) => sum + entry.amount, 0); + + const games: DailyGameView[] = GAME_IDS.map((id) => { + const engine = engineFor(id); + const progress: GameRoundProgress[] = plays + .filter((play) => play.game === id) + .map((play) => ({ roundIndex: play.roundIndex, stars: play.stars as Stars, score: play.score })) + .sort((a, b) => a.roundIndex - b.roundIndex); + return { id, title: engine.title, tagline: engine.tagline, rounds: engine.roundsFor(dayKey), progress, setComplete: progress.length >= ROUNDS_PER_DAY }; + }); + return { dayKey, resetsAt: resetsAt.toISOString(), signedIn: Boolean(userId), xpToday, xpLeft: Math.max(0, GAMES_XP_PER_DAY - xpToday), games }; +} + +/** + * Replay a submission against today's round. A passed round is stored once per day (the best stars + * win) and earns XP once; the set bonus is paid when the third round of a game is solved. + */ +export async function submitRound(userId: string, gameParam: string, roundIndex: number, submissionInput: unknown, now = new Date()): Promise { + if (!isGameId(gameParam)) throw new NotFoundError("Unknown game"); + const game: GameId = gameParam; + if (!Number.isInteger(roundIndex) || roundIndex < 0 || roundIndex >= ROUNDS_PER_DAY) throw new BadRequestError("Unknown round"); + + const engine = engineFor(game); + const { dayKey } = await dayFor(userId, now); + const round = engine.roundsFor(dayKey)[roundIndex]; + if (!round) throw new BadRequestError("Unknown round"); + const submission = engine.parseSubmission(submissionInput); + if (submission === null) throw new BadRequestError("That submission is not valid for this game"); + + const result = engine.verify(round, submission); + const base = { passed: result.passed, stars: result.stars, score: result.score, message: result.message }; + if (!result.passed) return { ...base, alreadySolved: false, xpAwarded: 0, setBonus: 0, setComplete: false }; + + const day = dayKeyToDate(dayKey); + return prisma.$transaction(async (tx) => { + const existing = await tx.gamePlay.findUnique({ where: { userId_game_dayKey_roundIndex: { userId, game, dayKey: day, roundIndex } } }); + const xpAwarded = await awardXp(tx, { userId, enrollmentId: null, courseId: null, source: "game_round", sourceKey: xpKeys.gameRound(dayKey, game, roundIndex), at: now }); + if (!existing) { + await tx.gamePlay.create({ data: { userId, game, dayKey: day, roundIndex, stars: result.stars, score: result.score, xpAwarded } }); + } else if (result.stars > existing.stars) { + await tx.gamePlay.update({ where: { id: existing.id }, data: { stars: result.stars, score: result.score } }); + } + const solved = await tx.gamePlay.count({ where: { userId, game, dayKey: day } }); + const setComplete = solved >= ROUNDS_PER_DAY; + const setBonus = setComplete ? await awardXp(tx, { userId, enrollmentId: null, courseId: null, source: "game_set", sourceKey: xpKeys.gameSet(dayKey, game), at: now }) : 0; + return { ...base, alreadySolved: Boolean(existing), xpAwarded, setBonus, setComplete }; + }); +} diff --git a/server/src/shared/api/games.ts b/server/src/shared/api/games.ts new file mode 100644 index 00000000..868c2c8b --- /dev/null +++ b/server/src/shared/api/games.ts @@ -0,0 +1,45 @@ +// Wire types for the daily games (docs/17-daily-games.mdx). +import type { GameId, RoundBase, Stars } from "../games/types.js"; + +/** What one solved round left behind. */ +export type GameRoundProgress = { roundIndex: number; stars: Stars; score: number }; + +export type DailyGameView = { + id: GameId; + title: string; + tagline: string; + /** Today's three rounds. The game component knows its own round shape. */ + rounds: Array>; + /** Solved rounds only, for a signed-in learner. */ + progress: GameRoundProgress[]; + /** All three rounds solved today. */ + setComplete: boolean; +}; + +export type DailyGamesView = { + /** The learner's local day (UTC for a visitor who is not signed in). */ + dayKey: string; + /** When the next set opens, as an ISO time. */ + resetsAt: string; + signedIn: boolean; + /** XP earned from the games today. */ + xpToday: number; + /** XP a learner can still earn from the games today. */ + xpLeft: number; + games: DailyGameView[]; +}; + +export type SubmitRoundBody = { submission: unknown }; + +export type SubmitRoundResult = { + passed: boolean; + stars: Stars; + score: number; + message: string; + /** This round was already solved today; nothing new was recorded for XP. */ + alreadySolved: boolean; + xpAwarded: number; + /** Extra XP for finishing all three rounds of the game today. */ + setBonus: number; + setComplete: boolean; +}; diff --git a/server/src/shared/games/daily.ts b/server/src/shared/games/daily.ts new file mode 100644 index 00000000..8b889659 --- /dev/null +++ b/server/src/shared/games/daily.ts @@ -0,0 +1,44 @@ +import { DIFFICULTIES, type Difficulty } from "./types.js"; + +/** Whole days since 1970-01-01 for a "YYYY-MM-DD" day key. Pure, no time zone involved. */ +export function dayNumber(dayKey: string): number { + const [y, m, d] = dayKey.split("-").map(Number); + return Math.floor(Date.UTC(y!, (m ?? 1) - 1, d ?? 1) / 86_400_000); +} + +/** A small stable hash, so two games do not rotate in step. */ +export function hashString(text: string): number { + let h = 2166136261; + for (let i = 0; i < text.length; i++) { + h ^= text.charCodeAt(i); + h = Math.imul(h, 16777619); + } + return h >>> 0; +} + +/** + * One scenario per difficulty for the day. The pool for a difficulty is walked in a fixed order, + * so a scenario does not repeat until the whole pool has been shown, and a game with N scenarios + * per difficulty shows each one every N days. The start offset differs per game and difficulty. + */ +export function pickDaily(pool: readonly T[], dayKey: string, gameId: string): T[] { + const day = dayNumber(dayKey); + return DIFFICULTIES.map((difficulty) => { + const tier = pool.filter((round) => round.difficulty === difficulty); + if (tier.length === 0) throw new Error(`${gameId}: no ${difficulty} scenarios`); + const offset = hashString(`${gameId}:${difficulty}`) % tier.length; + return tier[(day + offset) % tier.length]!; + }); +} + +/** Seeded pseudo random numbers (mulberry32), for engines that need repeatable noise. */ +export function seededRandom(seed: number): () => number { + let a = seed >>> 0; + return () => { + a = (a + 0x6d2b79f5) >>> 0; + let t = a; + t = Math.imul(t ^ (t >>> 15), t | 1); + t ^= t + Math.imul(t ^ (t >>> 7), t | 61); + return ((t ^ (t >>> 14)) >>> 0) / 4294967296; + }; +} diff --git a/server/src/shared/games/docker/builder.ts b/server/src/shared/games/docker/builder.ts new file mode 100644 index 00000000..b1863193 --- /dev/null +++ b/server/src/shared/games/docker/builder.ts @@ -0,0 +1,483 @@ +// The build simulation for the Docker Commands game. The player puts together a Dockerfile (pieces +// in an order) or a small compose file (one choice per blank). `simulateBuild` reads the result the +// way Docker would and reports whether it builds, how long a build and a rebuild take, how big the +// image is, and whether the app can be reached. Pure and deterministic, and it never throws. + +export type BuildKind = "dockerfile" | "compose"; + +export type ComposeFact = { + service: string; + key: "port" | "env" | "depends" | "volume" | "network" | "decl-volume" | "decl-network"; + value: string; +}; + +export type BuildPiece = { + id: string; + /** What the player reads, for example `RUN npm ci`. */ + text: string; + /** Compose only: the blank this piece can fill. */ + slot?: string; + /** Compose only: what the piece means. */ + facts?: ComposeFact[]; +}; + +/** The app a Dockerfile builds. */ +export type AppSpec = { + runtime: "node" | "python"; + /** The file or pattern that lists the dependencies, as written in COPY. */ + manifest: string; + /** What the app listens on when nothing sets the port. */ + defaultPort: number; + /** An environment variable the app reads for its port. */ + portEnv?: string; + /** Start commands that work, for example `node server.js`. */ + start: string[]; +}; + +export type StackService = { + image: string; + sizeMb: number; + /** The port the app listens on inside its container. */ + port?: number; + requiredEnv?: string[]; + dataPath?: string; + /** An environment variable that must name another service (DB_HOST=db). */ + hostEnv?: { key: string; value: string }; + mustDependOn?: string[]; + /** Services this one talks to, so they must share a network. */ + mustReach?: string[]; +}; + +export type StackSpec = { + services: Record; + publish: { service: string; host: number }; + /** These two services must not share a network. */ + isolate?: [string, string]; +}; + +export type ComposeLine = { text: string } | { slot: string }; + +export type BuildSlot = { id: string; label: string; indent: number }; + +export type BuildGoal = + | { kind: "builds"; label: string } + | { kind: "runs"; label: string } + | { kind: "reachable"; port: number; label: string } + | { kind: "size"; maxMb: number; label: string } + | { kind: "rebuild"; maxSec: number; label: string } + | { kind: "persists"; label: string } + | { kind: "isolated"; label: string }; + +export type BuildData = { + kind: BuildKind; + pieces: BuildPiece[]; + app?: AppSpec; + slots?: BuildSlot[]; + skeleton?: ComposeLine[]; + fixed?: ComposeFact[]; + stack?: StackSpec; +}; + +export type BuildLayer = { + /** The instruction or service, for example `RUN npm ci`. */ + label: string; + sizeMb: number; + seconds: number; + /** True when a rebuild after a code change reuses this layer. */ + cached: boolean; + failed: boolean; +}; + +export type BuildReport = { + kind: BuildKind; + /** The image (or the compose file) was built. */ + ok: boolean; + /** Why the build stopped, or null. */ + error: string | null; + layers: BuildLayer[]; + warnings: string[]; + /** Seconds for a first build. */ + coldSec: number; + /** Seconds to build again after one source file changed. */ + rebuildSec: number; + sizeMb: number; + cacheFriendly: boolean; + /** The container (or every service) started. */ + started: boolean; + /** Something answers on `port`. */ + reachable: boolean; + port: number | null; + persists: boolean | null; + isolated: boolean | null; + runLog: string[]; +}; + +const BASES: Record = { + "node:20": { sizeMb: 1100, runtime: "node" }, + "node:20-slim": { sizeMb: 240, runtime: "node" }, + "node:20-alpine": { sizeMb: 180, runtime: "node" }, + "python:3.12": { sizeMb: 1010, runtime: "python" }, + "python:3.12-slim": { sizeMb: 150, runtime: "python" }, + "ubuntu:22.04": { sizeMb: 77, runtime: "none" }, + "alpine:3.19": { sizeMb: 8, runtime: "none" }, +}; + +const round1 = (n: number) => Math.round(n * 10) / 10; + +function emptyReport(kind: BuildKind): BuildReport { + return { + kind, ok: false, error: null, layers: [], warnings: [], coldSec: 0, rebuildSec: 0, sizeMb: 0, cacheFriendly: false, + started: false, reachable: false, port: null, persists: null, isolated: null, runLog: [], + }; +} + +function normalizeCmd(arg: string): string { + const t = arg.trim(); + if (t.startsWith("[")) { + try { + const parsed: unknown = JSON.parse(t); + if (Array.isArray(parsed)) return parsed.map(String).join(" "); + } catch { + return t; + } + } + return t.replace(/\s+/g, " "); +} + +// --------------------------------------------------------------------------------------------- +// Dockerfile. + +function simulateDockerfile(data: BuildData, steps: string[]): BuildReport { + const report = emptyReport("dockerfile"); + const app = data.app; + if (!app) { + report.error = "This round has no app to build."; + return report; + } + const byId = new Map(data.pieces.map((p) => [p.id, p])); + const texts: string[] = []; + for (const id of steps) { + const piece = byId.get(id); + if (!piece) { + report.error = `Unknown piece "${id}".`; + return report; + } + texts.push(piece.text); + } + if (texts.length === 0) { + report.error = "The Dockerfile is empty. Add FROM first."; + return report; + } + + let base: { sizeMb: number; runtime: "node" | "python" | "none" } | null = null; + let workdir = "/"; + let workdirSet = false; + let manifestDir: string | null = null; + let sourceDir: string | null = null; + let installed = false; + const env: Record = {}; + let exposed: number | null = null; + let cmd: string | null = null; + let installIdx = -1; + let sourceIdx = -1; + let cmdIdx = -1; + let lastBuildIdx = -1; + let size = 0; + let cold = 0; + + const addLayer = (label: string, sizeMb: number, seconds: number, failed = false) => { + report.layers.push({ label, sizeMb: round1(sizeMb), seconds: round1(seconds), cached: false, failed }); + size += sizeMb; + cold += seconds; + }; + + for (let i = 0; i < texts.length; i++) { + const text = texts[i]!; + const space = text.indexOf(" "); + const op = (space < 0 ? text : text.slice(0, space)).toUpperCase(); + const arg = space < 0 ? "" : text.slice(space + 1).trim(); + if (i === 0 && op !== "FROM") { + addLayer(text, 0, 0, true); + report.error = "A Dockerfile must start with FROM. Put FROM first."; + return finishFailed(report, cold, size); + } + if (op === "FROM") { + if (i > 0) { + addLayer(text, 0, 0, true); + report.error = "This round uses one FROM only. Take the other FROM out."; + return finishFailed(report, cold, size); + } + base = BASES[arg] ?? null; + if (!base) { + addLayer(text, 0, 0, true); + report.error = `pull access denied for ${arg}: the image does not exist.`; + return finishFailed(report, cold, size); + } + addLayer(text, base.sizeMb, base.sizeMb / 40); + } else if (op === "WORKDIR") { + workdir = arg; + workdirSet = true; + addLayer(text, 0, 0.1); + } else if (op === "COPY") { + const [src] = arg.split(/\s+/); + if (src !== "." && src !== app.manifest) { + addLayer(text, 0, 0, true); + report.error = `COPY failed: "${src ?? ""}" was not found in the build folder.`; + return finishFailed(report, cold, size); + } + if (src === ".") { + sourceDir = workdir; + manifestDir = workdir; + sourceIdx = i; + addLayer(text, 4, 0.8); + } else { + manifestDir = workdir; + addLayer(text, 0.1, 0.2); + } + lastBuildIdx = i; + } else if (op === "RUN") { + const cmdText = normalizeCmd(arg); + const installs = app.runtime === "node" ? ["npm ci", "npm install"] : ["pip install -r requirements.txt", "pip install --no-cache-dir -r requirements.txt"]; + if (installs.includes(cmdText)) { + if (!base || base.runtime !== app.runtime) { + addLayer(text, 0, 0.3, true); + report.error = `/bin/sh: ${app.runtime === "node" ? "npm" : "pip"}: not found. The base image has no ${app.runtime === "node" ? "Node" : "Python"}.`; + return finishFailed(report, cold, size); + } + if (manifestDir !== workdir) { + addLayer(text, 0, 0.3, true); + report.error = app.runtime === "node" + ? "npm error: could not read package.json. Copy the dependency file before this RUN." + : "ERROR: Could not open requirements file. Copy requirements.txt before this RUN."; + return finishFailed(report, cold, size); + } + installed = true; + installIdx = i; + const heavy = app.runtime === "node" ? (cmdText === "npm ci" ? 34 : 46) : 28; + addLayer(text, app.runtime === "node" ? 95 : 60, heavy); + } else if (/^(npm start|npm run \w+|node |python )/.test(cmdText)) { + addLayer(text, 0, 60, true); + report.error = "The build never finishes: RUN runs while building. Start the app with CMD."; + return finishFailed(report, cold, size); + } else { + addLayer(text, 1, 1); + } + lastBuildIdx = i; + } else if (op === "ENV") { + const [k, v] = arg.split("="); + if (k && v !== undefined) env[k] = v.replace(/^"|"$/g, ""); + addLayer(text, 0, 0.1); + } else if (op === "EXPOSE") { + const port = Number(arg.split("/")[0]); + if (!Number.isInteger(port) || port < 1 || port > 65535) { + addLayer(text, 0, 0, true); + report.error = `EXPOSE needs a port number, not "${arg}".`; + return finishFailed(report, cold, size); + } + exposed = port; + addLayer(text, 0, 0.1); + } else if (op === "CMD") { + cmd = normalizeCmd(arg); + cmdIdx = i; + addLayer(text, 0, 0.1); + } else { + addLayer(text, 0, 0, true); + report.error = `Unknown instruction ${op}.`; + return finishFailed(report, cold, size); + } + } + + report.ok = true; + report.coldSec = round1(cold); + report.sizeMb = Math.round(size); + const boundary = sourceIdx === -1 ? Number.POSITIVE_INFINITY : sourceIdx; + let rebuild = 0; + report.layers.forEach((layer, i) => { + layer.cached = i < boundary; + rebuild += layer.cached ? 0.1 : layer.seconds; + }); + report.rebuildSec = round1(rebuild); + report.cacheFriendly = installIdx !== -1 && sourceIdx !== -1 && installIdx < sourceIdx; + if (cmdIdx !== -1 && cmdIdx < lastBuildIdx) report.warnings.push("CMD comes before COPY or RUN. It works, but keep CMD last so the file reads in order."); + if (!workdirSet) report.warnings.push("There is no WORKDIR, so the files land in the root folder."); + + // Run it. + const log = report.runLog; + const listening = env[app.portEnv ?? ""] !== undefined ? Number(env[app.portEnv ?? ""]) : app.defaultPort; + const entry = app.start[0] ?? ""; + if (cmd === null) { + log.push("The image has no CMD, so the container has nothing to run and stops at once."); + } else if (!app.start.includes(cmd)) { + log.push(`${cmd.split(" ")[0]}: command not found or wrong for this app. Expected something like: ${entry}`); + } else if (sourceDir === null || sourceDir !== workdir) { + log.push(app.runtime === "node" ? `Error: Cannot find module '${workdir === "/" ? "" : workdir}/server.js'` : `python: can't open file '${workdir === "/" ? "" : workdir}/app.py': No such file`); + } else if (!installed) { + log.push(app.runtime === "node" ? "Error: Cannot find module 'express'. The dependencies were not installed." : "ModuleNotFoundError: No module named 'flask'. The dependencies were not installed."); + } else { + report.started = true; + log.push(`app listening on port ${listening}`); + } + if (report.started) { + report.port = listening; + report.reachable = exposed !== null && exposed === listening; + if (exposed === null) log.push("Nothing is published: add EXPOSE with the port the app listens on."); + else if (!report.reachable) log.push(`The app listens on ${listening} but port ${exposed} is the one published. Connection reset.`); + else log.push(`localhost:${listening} answers. 200 OK`); + } + return report; +} + +function finishFailed(report: BuildReport, cold: number, size: number): BuildReport { + report.coldSec = round1(cold); + report.sizeMb = Math.round(size); + return report; +} + +// --------------------------------------------------------------------------------------------- +// Compose. + +function simulateCompose(data: BuildData, steps: string[]): BuildReport { + const report = emptyReport("compose"); + const stack = data.stack; + const slots = data.slots ?? []; + if (!stack) { + report.error = "This round has no stack to start."; + return report; + } + const picks = new Map(); + for (const step of steps) { + const [slot, id] = step.split(":"); + const piece = data.pieces.find((p) => p.id === id && p.slot === slot); + if (!slot || !id || !piece) { + report.error = `Unknown choice "${step}".`; + return report; + } + if (picks.has(slot)) { + report.error = `The blank "${slot}" was filled twice.`; + return report; + } + picks.set(slot, piece); + } + const empty = slots.filter((s) => !picks.has(s.id)); + if (empty.length > 0) { + report.error = `Fill every blank first (${empty.length} left).`; + return report; + } + + const facts: ComposeFact[] = [...(data.fixed ?? [])]; + for (const piece of picks.values()) facts.push(...(piece.facts ?? [])); + const declaredVolumes = new Set(facts.filter((f) => f.key === "decl-volume").map((f) => f.value)); + const declaredNetworks = new Set(facts.filter((f) => f.key === "decl-network").map((f) => f.value)); + const names = Object.keys(stack.services); + const of = (service: string, key: ComposeFact["key"]) => facts.filter((f) => f.service === service && f.key === key).map((f) => f.value); + + for (const name of names) { + for (const v of of(name, "volume")) { + const src = v.split(":")[0]!; + if (!src.startsWith(".") && !src.startsWith("/") && !declaredVolumes.has(src)) { + report.error = `service "${name}" refers to undefined volume ${src}: invalid compose project`; + return report; + } + } + for (const n of of(name, "network")) { + if (!declaredNetworks.has(n)) { + report.error = `service "${name}" refers to undefined network ${n}: invalid compose project`; + return report; + } + } + for (const d of of(name, "depends")) { + if (!names.includes(d)) { + report.error = `service "${name}" depends on undefined service "${d}": invalid compose project`; + return report; + } + } + } + report.ok = true; + + // Start order: dependencies first. + const order: string[] = []; + const visit = (name: string, depth: number) => { + if (order.includes(name) || depth > 8) return; + for (const d of of(name, "depends")) visit(d, depth + 1); + order.push(name); + }; + names.forEach((n) => visit(n, 0)); + + const networksOf = (name: string) => { + const list = of(name, "network"); + return list.length ? list : ["default"]; + }; + const shares = (a: string, b: string) => networksOf(a).some((n) => networksOf(b).includes(n)); + const status = new Map(); + let size = 0; + let cold = 0; + for (const name of order) { + const svc = stack.services[name]!; + const seconds = round1(svc.sizeMb / 40); + report.layers.push({ label: `${name}: pull ${svc.image}`, sizeMb: svc.sizeMb, seconds, cached: false, failed: false }); + size += svc.sizeMb; + cold += seconds; + const env = new Map(of(name, "env").map((e) => [e.split("=")[0]!, e.slice(e.indexOf("=") + 1)])); + let crash: string | null = null; + for (const key of svc.requiredEnv ?? []) if (!env.get(key)) crash ??= `${key} is not set. The container exited with code 1.`; + for (const d of svc.mustDependOn ?? []) if (!of(name, "depends").includes(d)) crash ??= `started before ${d} was ready: connect ECONNREFUSED. Add depends_on: [${d}].`; + if (svc.hostEnv && env.get(svc.hostEnv.key) !== svc.hostEnv.value) { + const got = env.get(svc.hostEnv.key); + crash ??= got === "localhost" || got === undefined ? `connect ECONNREFUSED 127.0.0.1: "${got ?? "(unset)"}" is the container itself. Use the service name ${svc.hostEnv.value}.` : `getaddrinfo ENOTFOUND ${got}`; + } + for (const target of svc.mustReach ?? []) { + if (!shares(name, target)) crash ??= `getaddrinfo ENOTFOUND ${target}: ${name} and ${target} share no network.`; + else if (status.get(target) === false) crash ??= `connect ECONNREFUSED ${target}: ${target} is not running.`; + } + status.set(name, crash === null); + report.runLog.push(crash === null ? `${name} | started` : `${name} | ${crash}`); + if (crash) report.layers[report.layers.length - 1]!.failed = true; + } + report.coldSec = round1(cold); + report.rebuildSec = round1(cold); + report.sizeMb = Math.round(size); + report.cacheFriendly = true; + report.started = order.every((n) => status.get(n) === true); + + const pub = stack.publish; + const pubSvc = stack.services[pub.service]; + const mapped = of(pub.service, "port").some((p) => { + const [h, c] = p.split(":"); + return Number(h) === pub.host && Number(c) === pubSvc?.port; + }); + report.port = pub.host; + report.reachable = status.get(pub.service) === true && mapped; + if (status.get(pub.service) === true && !mapped) report.runLog.push(`localhost:${pub.host} does not answer: the published port does not lead to port ${pubSvc?.port ?? "?"} inside ${pub.service}.`); + else if (report.reachable) report.runLog.push(`localhost:${pub.host} answers. 200 OK`); + + const dataServices = names.filter((n) => stack.services[n]!.dataPath); + if (dataServices.length > 0) { + report.persists = dataServices.every((n) => of(n, "volume").some((v) => v.split(":")[1] === stack.services[n]!.dataPath)); + if (!report.persists) report.warnings.push("The database data is not on a volume, so it is lost when the container is removed."); + } + if (stack.isolate) report.isolated = !shares(stack.isolate[0], stack.isolate[1]); + if (report.isolated === false) report.warnings.push(`${stack.isolate![0]} can reach ${stack.isolate![1]} directly. Keep them on different networks.`); + return report; +} + +export function simulateBuild(data: BuildData, steps: string[]): BuildReport { + try { + return data.kind === "compose" ? simulateCompose(data, steps) : simulateDockerfile(data, steps); + } catch { + const report = emptyReport(data.kind); + report.error = "The build could not be read."; + return report; + } +} + +export function checkBuildGoal(report: BuildReport, goal: BuildGoal): boolean { + switch (goal.kind) { + case "builds": return report.ok; + case "runs": return report.ok && report.started; + case "reachable": return report.started && report.reachable && report.port === goal.port; + case "size": return report.ok && report.sizeMb <= goal.maxMb; + case "rebuild": return report.ok && report.rebuildSec <= goal.maxSec; + case "persists": return report.persists === true; + case "isolated": return report.isolated === true; + } +} diff --git a/server/src/shared/games/docker/daemon.ts b/server/src/shared/games/docker/daemon.ts new file mode 100644 index 00000000..35e225e3 --- /dev/null +++ b/server/src/shared/games/docker/daemon.ts @@ -0,0 +1,1452 @@ +// A tiny virtual Docker daemon for the Docker Commands game. There is no real Docker here: a +// world is plain data (containers, images, networks, volumes), and `runLine` runs one typed +// command against it and returns the output lines. Everything is pure and deterministic (no clock, +// no Math.random): ids come from a hash, and time is a counter that goes up once per command. +// It never throws; a bad command returns an error line, like a real shell would. + +import { hashString } from "../daily.js"; + +export type Status = "created" | "running" | "exited" | "restarting"; +export type RestartPolicy = "no" | "always" | "on-failure" | "unless-stopped"; + +export type PortMap = { host: number; container: number }; +export type Mount = { source: string; target: string; kind: "volume" | "bind" }; + +export type Container = { + id: string; + name: string; + /** "repo:tag" */ + image: string; + command: string; + status: Status; + exitCode: number; + oomKilled: boolean; + restartCount: number; + ports: PortMap[]; + env: Record; + mounts: Mount[]; + networks: string[]; + restart: RestartPolicy; + /** Memory limit in MB, 0 means no limit. */ + memoryMb: number; + logs: string[]; + /** When the container was created: a tick number, or a ready made label like "2 hours". */ + createdAt: number | string; + /** When the status last changed: a tick number, or a ready made label like "2 hours". */ + since: number | string; + project?: string; + service?: string; +}; + +export type LocalImage = { id: string; repo: string; tag: string; sizeMb: number; created: string }; + +export type ComposeService = { + name: string; + image: string; + ports: string[]; + env: Record; + volumes: string[]; + dependsOn: string[]; + restart?: RestartPolicy; +}; + +export type DockerWorld = { + /** Goes up by one for every command. */ + tick: number; + /** Counts things created, so new ids are different and repeatable. */ + seq: number; + containers: Container[]; + images: LocalImage[]; + networks: string[]; + volumes: string[]; + /** Set only in scenarios that show a compose file. */ + compose?: { project: string; file: string[]; services: ComposeService[] }; +}; + +export type OutLine = { kind: "out" | "err" | "sys"; text: string }; + +export type DockerEvent = { + type: "created" | "started" | "stopped" | "crashed" | "restarting" | "removed" | "pulled" | "network" | "volume" | "blocked" | "pruned"; + name: string; +}; + +export type RunResult = { lines: OutLine[]; ok: boolean; events: DockerEvent[] }; + +// --------------------------------------------------------------------------------------------- +// What each image does when it runs. Anything not listed behaves like a small generic app. + +export type ImageSpec = { + sizeMb: number; + /** The port the app listens on inside the container. */ + port?: number; + cmd: string; + /** Environment variables that must be set, or the app stops at once. */ + requiredEnv?: string[]; + /** The log lines printed when a required variable is missing. */ + missingEnv?: Record; + /** An environment variable that names a host (the database) the app must be able to reach. */ + needsHost?: string; + /** Memory the app needs, in MB. With a smaller limit it is killed (exit 137). */ + memoryMb?: number; + /** Memory it uses while running, in MB. */ + useMb?: number; + /** What `curl` gets back. */ + body?: string; + startLogs: string[]; + dataPath?: string; + /** What the app prints when it listens but a client sends it a non-HTTP request. */ + rawPort?: boolean; +}; + +const GENERIC: ImageSpec = { sizeMb: 90, cmd: "app", startLogs: ["app started"] }; + +export const CATALOG: Record = { + "nginx:latest": { sizeMb: 188, port: 80, cmd: "nginx -g 'daemon off;'", body: "

Welcome to nginx!

", useMb: 8, startLogs: ["/docker-entrypoint.sh: Configuration complete; ready for start up", "nginx: [notice] start worker processes"] }, + "nginx:1.25": { sizeMb: 187, port: 80, cmd: "nginx -g 'daemon off;'", body: "

Welcome to nginx!

", useMb: 8, startLogs: ["/docker-entrypoint.sh: Configuration complete; ready for start up", "nginx: [notice] start worker processes"] }, + "nginx:1.25-alpine": { sizeMb: 43.2, port: 80, cmd: "nginx -g 'daemon off;'", body: "

Welcome to nginx!

", useMb: 5, startLogs: ["/docker-entrypoint.sh: Configuration complete; ready for start up", "nginx: [notice] start worker processes"] }, + "postgres:16": { + sizeMb: 432, port: 5432, cmd: "postgres", requiredEnv: ["POSTGRES_PASSWORD"], dataPath: "/var/lib/postgresql/data", memoryMb: 100, useMb: 45, rawPort: true, + missingEnv: { + POSTGRES_PASSWORD: [ + "Error: Database is uninitialized and superuser password is not specified.", + " You must specify POSTGRES_PASSWORD to a non-empty value for the", + " superuser. For example, \"-e POSTGRES_PASSWORD=password\" on \"docker run\".", + ], + }, + startLogs: ["PostgreSQL init process complete; ready for start up.", "LOG: database system is ready to accept connections"], + }, + "redis:7": { sizeMb: 117, port: 6379, cmd: "redis-server", useMb: 6, rawPort: true, startLogs: ["Ready to accept connections tcp"] }, + "shop/web:2.0": { + sizeMb: 212, port: 3000, cmd: "node server.js", needsHost: "DB_HOST", useMb: 60, + body: "Shop is open: 3 products, connected to the database.", + startLogs: ["shop-web listening on :3000"], + }, + "acme/site:1.0": { sizeMb: 62, port: 80, cmd: "nginx -g 'daemon off;'", body: "Acme site v1 (old release)", useMb: 6, startLogs: ["site 1.0 ready"] }, + "acme/site:2.0": { + sizeMb: 64, port: 80, cmd: "nginx -g 'daemon off;'", requiredEnv: ["SITE_NAME"], body: "Acme site v2 (new release)", useMb: 6, + missingEnv: { SITE_NAME: ["site: fatal: SITE_NAME is required (example: -e SITE_NAME=Acme)"] }, + startLogs: ["site 2.0 ready"], + }, + "acme/worker:3.1": { + sizeMb: 310, cmd: "python worker.py", memoryMb: 400, useMb: 380, + startLogs: ["worker: loading model into memory (needs about 400 MB)", "worker: ready, waiting for jobs"], + }, + "shop/api:1.2": { sizeMb: 164, port: 4000, cmd: "node api.js", startLogs: ["api listening on :4000"] }, + "legacy/app:0.9": { sizeMb: 270, port: 8000, cmd: "python app.py", startLogs: ["legacy app started"] }, +}; + +function specFor(image: string): ImageSpec { + return CATALOG[image] ?? GENERIC; +} + +const COMMON_BINS = ["sh", "bash", "sleep", "env", "ls", "cat", "echo", "tail", "true", "false"]; + +// --------------------------------------------------------------------------------------------- +// Small helpers. + +export function hex(seed: string, length: number): string { + let out = ""; + for (let i = 0; out.length < length; i++) out += hashString(`${seed}:${i}`).toString(16).padStart(8, "0"); + return out.slice(0, length); +} + +const shortId = (id: string) => id.slice(0, 12); + +export function normalizeImage(ref: string): string { + const slash = ref.lastIndexOf("/"); + const colon = ref.lastIndexOf(":"); + return colon > slash ? ref : `${ref}:latest`; +} + +export function splitImage(ref: string): { repo: string; tag: string } { + const full = normalizeImage(ref); + const colon = full.lastIndexOf(":"); + return { repo: full.slice(0, colon), tag: full.slice(colon + 1) }; +} + +export function fmtSize(mb: number): string { + if (mb >= 1000) return `${(mb / 1000).toFixed(2).replace(/0$/, "")}GB`; + return `${mb < 100 ? mb.toFixed(1).replace(/\.0$/, "") : Math.round(mb)}MB`; +} + +function age(world: DockerWorld, value: number | string): string { + if (typeof value === "string") return value; + const diff = world.tick - value; + if (diff <= 0) return "Less than a second"; + const seconds = diff * 6; + return seconds < 60 ? `${seconds} seconds` : `${Math.floor(seconds / 60)} minutes`; +} + +function table(rows: string[][]): string[] { + const widths: number[] = []; + for (const row of rows) row.forEach((cell, i) => { widths[i] = Math.max(widths[i] ?? 0, cell.length); }); + return rows.map((row) => row.map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i]! + 2))).join("").trimEnd()); +} + +const clone = (value: T): T => JSON.parse(JSON.stringify(value)) as T; +export const cloneWorld = (world: DockerWorld): DockerWorld => clone(world); + +export function emptyWorld(): DockerWorld { + return { tick: 0, seq: 0, containers: [], images: [], networks: ["bridge", "host", "none"], volumes: [] }; +} + +export function makeImage(ref: string, created = "3 weeks ago"): LocalImage { + const { repo, tag } = splitImage(ref); + return { id: hex(`image:${repo}:${tag}`, 12), repo, tag, sizeMb: specFor(`${repo}:${tag}`).sizeMb, created }; +} + +export function danglingImage(seed: string, sizeMb: number, created = "5 days ago"): LocalImage { + return { id: hex(`dangling:${seed}`, 12), repo: "", tag: "", sizeMb, created }; +} + +export function makeContainer(p: Partial & { name: string; image: string }): Container { + const image = normalizeImage(p.image); + return { + id: hex(`container:${p.name}`, 64), command: specFor(image).cmd, status: "running", exitCode: 0, oomKilled: false, restartCount: 0, + ports: [], env: {}, mounts: [], networks: ["bridge"], restart: "no", memoryMb: 0, logs: [], createdAt: "2 hours", since: "2 hours", + ...p, + image, + }; +} + +const isUserNetwork = (name: string) => !["bridge", "host", "none"].includes(name); + +function findContainer(world: DockerWorld, ref: string): Container | undefined { + const name = ref.replace(/^\//, ""); + const exact = world.containers.find((c) => c.name === name || c.id === ref); + if (exact) return exact; + if (/^[0-9a-f]{1,64}$/.test(ref)) { + const byId = world.containers.filter((c) => c.id.startsWith(ref)); + if (byId.length === 1) return byId[0]; + } + return undefined; +} + +function findImage(world: DockerWorld, ref: string): LocalImage | undefined { + if (/^[0-9a-f]{3,12}$/.test(ref)) { + const byId = world.images.find((i) => i.id.startsWith(ref)); + if (byId) return byId; + } + const { repo, tag } = splitImage(ref); + return world.images.find((i) => i.repo === repo && i.tag === tag); +} + +const imageRef = (i: LocalImage) => `${i.repo}:${i.tag}`; + +/** The container that answers to `host` for a container on user networks, or null. */ +function resolveName(world: DockerWorld, from: Container, host: string): Container | null { + if (host === from.name) return from; + const shared = from.networks.filter(isUserNetwork); + for (const other of world.containers) { + if (other === from || (other.name !== host && other.service !== host) || other.status !== "running") continue; + if (other.networks.some((n) => shared.includes(n))) return other; + } + return null; +} + +function ipOf(world: DockerWorld, c: Container): string { + const net = c.networks.find(isUserNetwork) ?? "bridge"; + const base = net === "bridge" ? 17 : 18 + Math.max(0, world.networks.indexOf(net) - 3); + return `172.${base}.0.${2 + world.containers.indexOf(c)}`; +} + +// --------------------------------------------------------------------------------------------- +// Starting a container: this is where the scenarios' faults show up. + +function hostPortBusy(world: DockerWorld, port: number, self: Container): Container | undefined { + return world.containers.find((c) => c !== self && (c.status === "running" || c.status === "restarting") && c.ports.some((p) => p.host === port)); +} + +function setState(world: DockerWorld, c: Container, status: Status, exitCode: number, events: DockerEvent[]) { + const previous = c.status; + c.status = status; + c.exitCode = exitCode; + c.since = world.tick; + if (status === "running" && previous !== "running") events.push({ type: "started", name: c.name }); + else if (status === "exited" && previous === "running") events.push({ type: "stopped", name: c.name }); +} + +function pushLogs(c: Container, lines: string[]) { + c.logs.push(...lines); + if (c.logs.length > 120) c.logs.splice(0, c.logs.length - 120); +} + +/** Try to start a container. Returns an error line when a port is taken (the container stays "created"). */ +function boot(world: DockerWorld, c: Container, events: DockerEvent[]): string | null { + for (const p of c.ports) { + const other = hostPortBusy(world, p.host, c); + if (other) { + if (c.status !== "restarting") setState(world, c, "created", 0, events); + events.push({ type: "blocked", name: c.name }); + return `Error response from daemon: driver failed programming external connectivity on endpoint ${c.name} (${hex(`ep:${c.name}:${world.seq}`, 64)}): Bind for 0.0.0.0:${p.host} failed: port is already allocated`; + } + } + const spec = specFor(c.image); + const fail = (code: number, lines: string[], oom = false) => { + pushLogs(c, lines); + c.oomKilled = oom; + if (c.restart !== "no") { + c.restartCount += 1; + setState(world, c, "restarting", code, events); + events.push({ type: "restarting", name: c.name }); + } else { + setState(world, c, "exited", code, events); + events.push({ type: "crashed", name: c.name }); + } + return null; + }; + + const first = c.command.split(/\s+/)[0] ?? ""; + const appCmd = c.command === spec.cmd; + if (!appCmd && !COMMON_BINS.includes(first) && first !== (spec.cmd.split(/\s+/)[0] ?? "")) { + return fail(127, [`exec: "${first}": executable file not found in $PATH`]); + } + if (appCmd) { + for (const key of spec.requiredEnv ?? []) { + if (!c.env[key]) return fail(1, spec.missingEnv?.[key] ?? [`Error: ${key} is required`]); + } + if (spec.needsHost) { + const host = c.env[spec.needsHost]; + if (!host) return fail(1, [`Error: ${spec.needsHost} is not set`]); + if (host === "localhost" || host === "127.0.0.1") return fail(1, [`Error: connect ECONNREFUSED 127.0.0.1:5432`, " at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1555:16)"]); + if (!resolveName(world, c, host)) return fail(1, [`Error: getaddrinfo ENOTFOUND ${host}`, " at GetAddrInfoReqWrap.onlookup [as oncomplete] (node:dns:109:26)"]); + } + if (spec.memoryMb && c.memoryMb > 0 && c.memoryMb < spec.memoryMb) { + return fail(137, [spec.startLogs[0] ?? "starting", "Killed"], true); + } + pushLogs(c, spec.startLogs); + if (spec.needsHost) pushLogs(c, [`connected to database at ${c.env[spec.needsHost]}`]); + } else { + pushLogs(c, [`(running "${c.command}")`]); + } + c.oomKilled = false; + setState(world, c, "running", 0, events); + return null; +} + +/** Containers on a restart policy try again after every command, so they heal when the cause is fixed. */ +function settle(world: DockerWorld, touched: Set, events: DockerEvent[]) { + for (const c of world.containers) { + if (c.status === "restarting" && !touched.has(c.id)) { + const before = c.restartCount; + boot(world, c, events); + if (c.status === "restarting") c.restartCount = before + 1; + } + } +} + +// --------------------------------------------------------------------------------------------- +// Parsing a shell line. + +function tokenize(text: string): string[] | null { + const tokens: string[] = []; + let current = ""; + let has = false; + let quote: string | null = null; + for (const ch of text) { + if (quote) { + if (ch === quote) quote = null; + else current += ch; + } else if (ch === "'" || ch === '"') { + quote = ch; + has = true; + } else if (/\s/.test(ch)) { + if (has || current) tokens.push(current); + current = ""; + has = false; + } else { + current += ch; + } + } + if (quote) return null; + if (has || current) tokens.push(current); + return tokens; +} + +function splitAnd(line: string): string[] { + const parts: string[] = []; + let current = ""; + let quote: string | null = null; + for (let i = 0; i < line.length; i++) { + const ch = line[i]!; + if (quote) { + if (ch === quote) quote = null; + current += ch; + } else if (ch === "'" || ch === '"') { + quote = ch; + current += ch; + } else if (ch === "&" && line[i + 1] === "&") { + parts.push(current); + current = ""; + i++; + } else current += ch; + } + parts.push(current); + return parts; +} + +type FlagSpec = { bool?: string[]; value?: string[]; alias?: Record; stopAtPositional?: boolean }; +type Parsed = { flags: Record; has: Set; rest: string[]; error?: string }; + +function parseFlags(args: string[], spec: FlagSpec): Parsed { + const flags: Record = {}; + const has = new Set(); + const rest: string[] = []; + const bool = new Set(spec.bool ?? []); + const value = new Set(spec.value ?? []); + const alias = spec.alias ?? {}; + for (let i = 0; i < args.length; i++) { + const arg = args[i]!; + if (arg === "--") { rest.push(...args.slice(i + 1)); break; } + if (arg.startsWith("--")) { + const eq = arg.indexOf("="); + const name = (eq >= 0 ? arg.slice(2, eq) : arg.slice(2)); + const long = alias[`--${name}`]?.slice(2) ?? name; + if (bool.has(long)) { has.add(long); continue; } + if (value.has(long)) { + const val = eq >= 0 ? arg.slice(eq + 1) : args[++i]; + if (val === undefined) return { flags, has, rest, error: `flag needs an argument: --${name}` }; + (flags[long] ??= []).push(val); + continue; + } + return { flags, has, rest, error: `unknown flag: --${name}` }; + } + if (arg.startsWith("-") && arg.length > 1) { + for (let j = 1; j < arg.length; j++) { + const short = arg[j]!; + const long = alias[`-${short}`]?.slice(2) ?? short; + if (bool.has(long)) { has.add(long); continue; } + if (value.has(long)) { + const attached = arg.slice(j + 1); + const val = attached || args[++i]; + if (val === undefined) return { flags, has, rest, error: `flag needs an argument: '${short}' in -${short}` }; + (flags[long] ??= []).push(val.replace(/^=/, "")); + break; + } + return { flags, has, rest, error: `unknown shorthand flag: '${short}' in -${arg.slice(j)}` }; + } + continue; + } + rest.push(arg); + if (spec.stopAtPositional) { rest.push(...args.slice(i + 1)); break; } + } + return { flags, has, rest }; +} + +// --------------------------------------------------------------------------------------------- +// The command runner. + +type Ctx = { world: DockerWorld; lines: OutLine[]; events: DockerEvent[]; touched: Set }; + +const out = (ctx: Ctx, text: string) => { ctx.lines.push({ kind: "out", text }); }; +const err = (ctx: Ctx, text: string) => { ctx.lines.push({ kind: "err", text }); }; +const outAll = (ctx: Ctx, texts: string[]) => texts.forEach((t) => out(ctx, t)); + +const USAGE: Record = { + run: [1, "docker run [OPTIONS] IMAGE [COMMAND] [ARG...]", "Create and run a new container from an image"], + start: [1, "docker start [OPTIONS] CONTAINER [CONTAINER...]", "Start one or more stopped containers"], + stop: [1, "docker stop [OPTIONS] CONTAINER [CONTAINER...]", "Stop one or more running containers"], + restart: [1, "docker restart [OPTIONS] CONTAINER [CONTAINER...]", "Restart one or more containers"], + rm: [1, "docker rm [OPTIONS] CONTAINER [CONTAINER...]", "Remove one or more containers"], + rmi: [1, "docker rmi [OPTIONS] IMAGE [IMAGE...]", "Remove one or more images"], + logs: [1, "docker logs [OPTIONS] CONTAINER", "Fetch the logs of a container"], + inspect: [1, "docker inspect [OPTIONS] NAME|ID [NAME|ID...]", "Return low-level information on Docker objects"], + exec: [2, "docker exec [OPTIONS] CONTAINER COMMAND [ARG...]", "Execute a command in a running container"], + pull: [1, "docker pull [OPTIONS] NAME[:TAG|@DIGEST]", "Download an image from a registry"], + kill: [1, "docker kill [OPTIONS] CONTAINER [CONTAINER...]", "Kill one or more running containers"], +}; + +function needArgs(ctx: Ctx, cmd: string, count: number): boolean { + const u = USAGE[cmd]; + if (!u) return true; + if (count >= u[0]) return true; + err(ctx, `docker: "docker ${cmd}" requires at least ${u[0]} argument${u[0] > 1 ? "s" : ""}.`); + err(ctx, `See 'docker ${cmd} --help'.`); + out(ctx, ""); + out(ctx, `Usage: ${u[1]}`); + out(ctx, ""); + out(ctx, u[2]); + return false; +} + +function flagError(ctx: Ctx, cmd: string, message: string) { + err(ctx, message); + err(ctx, `See 'docker ${cmd} --help'.`); +} + +function noContainer(ctx: Ctx, ref: string) { + err(ctx, `Error response from daemon: No such container: ${ref}`); +} + +function parseMemory(text: string): number | null { + const m = /^(\d+)([bkmg]?)b?$/i.exec(text.trim()); + if (!m) return null; + const n = Number(m[1]); + const unit = (m[2] ?? "").toLowerCase(); + if (unit === "g") return n * 1024; + if (unit === "m") return n; + if (unit === "k") return n / 1024; + return n / 1048576; +} + +function parsePort(text: string): { host: number; container: number } | string { + const m = /^(?:(\d{1,3}(?:\.\d{1,3}){3}):)?(\d{1,5})(?::(\d{1,5}))?(?:\/(tcp|udp))?$/.exec(text); + if (!m) return `invalid containerPort: ${text.split(":").pop() ?? text}`; + const a = Number(m[2]); + const b = m[3] !== undefined ? Number(m[3]) : null; + const host = b === null ? 0 : a; + const container = b === null ? a : b; + if (container < 1 || container > 65535) return `invalid containerPort: ${container}`; + if (host > 65535) return `invalid hostPort: ${host}`; + return { host, container }; +} + +function pullImage(ctx: Ctx, ref: string): LocalImage | null { + const world = ctx.world; + const { repo, tag } = splitImage(ref); + const key = `${repo}:${tag}`; + if (!CATALOG[key]) { + const known = Object.keys(CATALOG).some((k) => k.startsWith(`${repo}:`)); + if (known) err(ctx, `Error response from daemon: manifest for ${key} not found: manifest unknown: manifest unknown`); + else err(ctx, `Error response from daemon: pull access denied for ${repo}, repository does not exist or may require 'docker login': denied: requested access to the resource is denied`); + return null; + } + const existing = world.images.find((i) => i.repo === repo && i.tag === tag); + const official = !repo.includes("/"); + out(ctx, `${tag}: Pulling from ${official ? "library/" : ""}${repo}`); + if (existing) { + out(ctx, `Digest: sha256:${hex(`digest:${key}`, 64)}`); + out(ctx, `Status: Image is up to date for ${key}`); + } else { + for (let i = 0; i < 2; i++) out(ctx, `${hex(`layer:${key}:${i}`, 12)}: Pull complete`); + out(ctx, `Digest: sha256:${hex(`digest:${key}`, 64)}`); + out(ctx, `Status: Downloaded newer image for ${key}`); + } + out(ctx, `docker.io/${official ? "library/" : ""}${key}`); + if (existing) return existing; + const image = makeImage(key, "2 weeks ago"); + world.images.push(image); + ctx.events.push({ type: "pulled", name: key }); + return image; +} + +function cmdRun(ctx: Ctx, args: string[]) { + const world = ctx.world; + const p = parseFlags(args, { + bool: ["detach", "interactive", "tty", "rm", "publish-all"], + value: ["publish", "env", "volume", "name", "network", "restart", "memory", "workdir", "hostname", "user"], + alias: { "-d": "--detach", "-i": "--interactive", "-t": "--tty", "-p": "--publish", "-e": "--env", "-v": "--volume", "-P": "--publish-all", "-m": "--memory", "-w": "--workdir", "-h": "--hostname", "-u": "--user", "--net": "--network" }, + stopAtPositional: true, + }); + if (p.error) return flagError(ctx, "run", p.error); + if (!needArgs(ctx, "run", p.rest.length)) return; + const imageArg = p.rest[0]!; + if (!/^[a-z0-9][a-z0-9._/-]*(:[A-Za-z0-9_][A-Za-z0-9_.-]*)?$/.test(imageArg)) { + return flagError(ctx, "run", `docker: invalid reference format.`); + } + const name = p.flags.name?.[0]; + if (name !== undefined && !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name)) { + return flagError(ctx, "run", `docker: Error response from daemon: Invalid container name (${name}), only [a-zA-Z0-9][a-zA-Z0-9_.-] are allowed`); + } + const containerName = name ?? ["eager_turing", "calm_lovelace", "brave_hopper", "quick_ritchie", "happy_torvalds", "clever_knuth"][world.seq % 6]!; + const taken = world.containers.find((c) => c.name === containerName); + if (taken) { + return err(ctx, `docker: Error response from daemon: Conflict. The container name "/${containerName}" is already in use by container "${taken.id}". You have to remove (or rename) that container to be able to reuse that name.`); + } + const ports: PortMap[] = []; + for (const spec of p.flags.publish ?? []) { + const parsed = parsePort(spec); + if (typeof parsed === "string") return err(ctx, `docker: ${parsed}.`); + ports.push({ host: parsed.host || 32768 + ((world.seq + ports.length) % 1000), container: parsed.container }); + } + if (p.has.has("publish-all")) { + const port = specFor(normalizeImage(imageArg)).port; + if (port) ports.push({ host: 32768 + (world.seq % 1000), container: port }); + } + const env: Record = {}; + for (const item of p.flags.env ?? []) { + const eq = item.indexOf("="); + if (eq === 0) return err(ctx, `docker: invalid env file: "${item}"`); + if (eq > 0) env[item.slice(0, eq)] = item.slice(eq + 1); + } + const mounts: Mount[] = []; + const newVolumes: string[] = []; + for (const item of p.flags.volume ?? []) { + const parts = item.split(":"); + const target = parts.length === 1 ? parts[0]! : parts[1]!; + const source = parts.length === 1 ? "" : parts[0]!; + if (!target.startsWith("/")) { + return err(ctx, `docker: Error response from daemon: invalid mount config for type "volume": invalid mount path: '${target}' mount path must be absolute.`); + } + if (source.startsWith("/") || source.startsWith("./") || source.startsWith("~")) mounts.push({ source, target, kind: "bind" }); + else if (source === "") { + const anon = hex(`anon:${world.seq}:${mounts.length}`, 64); + mounts.push({ source: anon, target, kind: "volume" }); + newVolumes.push(anon); + } else if (/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(source)) { + mounts.push({ source, target, kind: "volume" }); + if (!world.volumes.includes(source)) newVolumes.push(source); + } else return err(ctx, `docker: Error response from daemon: invalid volume name "${source}"`); + } + const net = p.flags.network?.[0]; + if (net !== undefined && !world.networks.includes(net)) { + return err(ctx, `docker: Error response from daemon: network ${net} not found.`); + } + const restartArg = p.flags.restart?.[0] ?? "no"; + const restart = /^(no|always|unless-stopped|on-failure)(:\d+)?$/.exec(restartArg); + if (!restart) return err(ctx, `docker: Error response from daemon: invalid restart policy ${restartArg}`); + let memoryMb = 0; + if (p.flags.memory) { + const mb = parseMemory(p.flags.memory[0]!); + if (mb === null) return err(ctx, `docker: invalid argument "${p.flags.memory[0]}" for "-m, --memory" flag: invalid size: '${p.flags.memory[0]}'`); + if (mb < 6) return err(ctx, "docker: Error response from daemon: Minimum memory limit allowed is 6MB"); + memoryMb = Math.round(mb); + } + + const ref = normalizeImage(imageArg); + let image = findImage(world, ref); + if (!image) { + out(ctx, `Unable to find image '${ref}' locally`); + image = pullImage(ctx, ref) ?? undefined; + if (!image) { + err(ctx, "See 'docker run --help'."); + return; + } + } + const spec = specFor(imageRef(image)); + const command = p.rest.slice(1).join(" ") || spec.cmd; + world.seq += 1; + for (const v of newVolumes) { + world.volumes.push(v); + ctx.events.push({ type: "volume", name: v }); + } + const c: Container = makeContainer({ + name: containerName, image: imageRef(image), command, status: "created", ports, env, mounts, + networks: [net ?? "bridge"], restart: restart[1] as RestartPolicy, memoryMb, createdAt: world.tick, since: world.tick, + }); + c.id = hex(`container:${containerName}:${world.seq}`, 64); + world.containers.push(c); + ctx.events.push({ type: "created", name: c.name }); + ctx.touched.add(c.id); + const problem = boot(world, c, ctx.events); + if (problem) { + err(ctx, `docker: ${problem}.`); + return; + } + if (p.has.has("detach")) out(ctx, c.id); + else { + outAll(ctx, c.logs); + if (c.status === "running") ctx.lines.push({ kind: "sys", text: "Tip: add -d to run the container in the background and keep using this terminal." }); + } +} + +function cmdPs(ctx: Ctx, args: string[]) { + const world = ctx.world; + const p = parseFlags(args, { bool: ["all", "quiet", "no-trunc"], value: ["filter", "format"], alias: { "-a": "--all", "-q": "--quiet", "-f": "--filter" } }); + if (p.error) return flagError(ctx, "ps", p.error); + if (p.rest.length) return err(ctx, `"docker ps" accepts no arguments.`); + let list = world.containers.filter((c) => p.has.has("all") || c.status === "running" || c.status === "restarting"); + for (const f of p.flags.filter ?? []) { + const [k, v] = f.split("="); + if (k === "status") list = list.filter((c) => c.status === v); + else if (k === "name") list = list.filter((c) => c.name.includes(v ?? "")); + else return err(ctx, `Error response from daemon: Invalid filter '${k}'`); + } + list = [...list].reverse(); + if (p.has.has("quiet")) return outAll(ctx, list.map((c) => shortId(c.id))); + const format = p.flags.format?.[0]; + if (format) { + return outAll(ctx, list.map((c) => format.replace(/\{\{\.(\w+)\}\}/g, (_m, field: string) => ({ ID: shortId(c.id), Names: c.name, Image: c.image, Status: statusText(world, c), Ports: portsText(c), Command: `"${c.command}"` } as Record)[field] ?? ""))); + } + // A shorter table than the real one (no COMMAND and CREATED columns), so it fits a small terminal. + const rows = [["CONTAINER ID", "IMAGE", "STATUS", "PORTS", "NAMES"]]; + for (const c of list) rows.push([shortId(c.id), c.image, statusText(world, c), portsText(c), c.name]); + outAll(ctx, table(rows)); +} + +export function statusText(world: DockerWorld, c: Container): string { + if (c.status === "running") return `Up ${age(world, c.since)}`; + if (c.status === "created") return "Created"; + if (c.status === "restarting") return `Restarting (${c.exitCode}) ${age(world, c.since)} ago`; + return `Exited (${c.exitCode}) ${age(world, c.since)} ago`; +} + +export function portsText(c: Container): string { + if (c.status !== "running" && c.status !== "restarting") return ""; + const list = c.ports.map((p) => `0.0.0.0:${p.host}->${p.container}/tcp`); + if (list.length === 0) { + const port = specFor(c.image).port; + return port ? `${port}/tcp` : ""; + } + return list.join(", "); +} + +function cmdImages(ctx: Ctx, args: string[]) { + const world = ctx.world; + const p = parseFlags(args, { bool: ["all", "quiet", "no-trunc"], value: ["filter"], alias: { "-a": "--all", "-q": "--quiet", "-f": "--filter" } }); + if (p.error) return flagError(ctx, "images", p.error); + let list = [...world.images].reverse(); + for (const f of p.flags.filter ?? []) { + if (f === "dangling=true") list = list.filter((i) => i.repo === ""); + else if (f === "dangling=false") list = list.filter((i) => i.repo !== ""); + else return err(ctx, `Error response from daemon: Invalid filter '${f.split("=")[0]}'`); + } + const wanted = p.rest[0]; + if (wanted) list = list.filter((i) => i.repo === splitImage(wanted).repo && (!wanted.includes(":") || i.tag === splitImage(wanted).tag)); + if (p.has.has("quiet")) return outAll(ctx, list.map((i) => i.id)); + const rows = [["REPOSITORY", "TAG", "IMAGE ID", "CREATED", "SIZE"]]; + for (const i of list) rows.push([i.repo, i.tag, i.id, i.created, fmtSize(i.sizeMb)]); + outAll(ctx, table(rows)); +} + +function stop(ctx: Ctx, c: Container, code = 0) { + if (c.status === "running" || c.status === "restarting") { + const was = c.status; + setState(ctx.world, c, "exited", code, ctx.events); + if (was === "restarting") ctx.events.push({ type: "stopped", name: c.name }); + } +} + +function eachContainer(ctx: Ctx, refs: string[], action: (c: Container) => void) { + for (const ref of refs) { + const c = findContainer(ctx.world, ref); + if (!c) noContainer(ctx, ref); + else action(c); + } +} + +function startOne(ctx: Ctx, c: Container) { + if (c.status === "running") return out(ctx, c.name); + ctx.touched.add(c.id); + const problem = boot(ctx.world, c, ctx.events); + if (problem) { + err(ctx, problem); + err(ctx, `Error: failed to start containers: ${c.name}`); + return; + } + out(ctx, c.name); +} + +function removeContainer(world: DockerWorld, c: Container, events: DockerEvent[]) { + world.containers = world.containers.filter((x) => x !== c); + events.push({ type: "removed", name: c.name }); +} + +function cmdLogs(ctx: Ctx, args: string[]) { + const p = parseFlags(args, { bool: ["follow", "timestamps"], value: ["tail", "since"], alias: { "-f": "--follow", "-t": "--timestamps", "-n": "--tail" } }); + if (p.error) return flagError(ctx, "logs", p.error); + if (!needArgs(ctx, "logs", p.rest.length)) return; + if (p.rest.length > 1) return err(ctx, `docker: "docker logs" requires exactly 1 argument.`); + const c = findContainer(ctx.world, p.rest[0]!); + if (!c) return noContainer(ctx, p.rest[0]!); + let lines = c.logs; + const tail = p.flags.tail?.[0]; + if (tail !== undefined && tail !== "all") { + if (!/^\d+$/.test(tail)) return err(ctx, `invalid argument "${tail}" for "-n, --tail" flag: strconv.ParseUint: parsing "${tail}": invalid syntax`); + lines = Number(tail) === 0 ? [] : lines.slice(-Number(tail)); + } + outAll(ctx, lines); + if (p.has.has("follow")) ctx.lines.push({ kind: "sys", text: "(-f would keep waiting for new lines; the game shows the lines so far.)" }); +} + +function inspectObject(world: DockerWorld, c: Container): Record { + const env = Object.entries(c.env).map(([k, v]) => `${k}=${v}`); + const networks: Record = {}; + for (const n of c.networks) networks[n] = { NetworkID: hex(`net:${n}`, 64), IPAddress: c.status === "running" ? ipOf(world, c) : "" }; + const bindings: Record = {}; + for (const p of c.ports) bindings[`${p.container}/tcp`] = [{ HostIp: "", HostPort: String(p.host) }]; + return { + Id: c.id, + Name: `/${c.name}`, + State: { + Status: c.status, Running: c.status === "running", Restarting: c.status === "restarting", OOMKilled: c.oomKilled, + ExitCode: c.exitCode, Error: "", RestartCount: c.restartCount, + }, + Config: { Image: c.image, Cmd: c.command.split(" "), Env: env }, + HostConfig: { Memory: Math.round(c.memoryMb * 1048576), RestartPolicy: { Name: c.restart }, PortBindings: bindings }, + Mounts: c.mounts.map((m) => ({ Type: m.kind, Name: m.kind === "volume" ? m.source : "", Source: m.source, Destination: m.target })), + NetworkSettings: { Networks: networks }, + }; +} + +function cmdInspect(ctx: Ctx, args: string[]) { + const p = parseFlags(args, { value: ["format", "type"], alias: { "-f": "--format" } }); + if (p.error) return flagError(ctx, "inspect", p.error); + if (!needArgs(ctx, "inspect", p.rest.length)) return; + const format = p.flags.format?.[0]; + const results: Record[] = []; + for (const ref of p.rest) { + const c = findContainer(ctx.world, ref); + if (!c) { + err(ctx, `Error: No such object: ${ref}`); + continue; + } + results.push(inspectObject(ctx.world, c)); + } + if (format) { + for (const obj of results) { + out(ctx, format.replace(/\{\{\s*\.([\w.]+)\s*\}\}/g, (_m, path: string) => { + let cur: unknown = obj; + for (const key of path.split(".")) cur = cur && typeof cur === "object" ? (cur as Record)[key] : undefined; + if (cur === undefined) return ""; + return typeof cur === "object" ? JSON.stringify(cur) : String(cur); + })); + } + return; + } + if (results.length === 0 && p.rest.length) return out(ctx, "[]"); + outAll(ctx, JSON.stringify(results, null, 4).split("\n")); +} + +function curlFrom(ctx: Ctx, from: Container | null, target: string): { ok: boolean; text: string } { + const world = ctx.world; + let url = target.replace(/^https?:\/\//, ""); + url = url.split("/")[0] ?? ""; + const m = /^([A-Za-z0-9._-]+)(?::(\d{1,5}))?$/.exec(url); + if (!m) return { ok: false, text: `curl: (3) URL rejected: Bad hostname` }; + const host = m[1]!; + const port = m[2] ? Number(m[2]) : 80; + const refused = `curl: (7) Failed to connect to ${host} port ${port} after 0 ms: Couldn't connect to server`; + let container: Container | undefined; + let containerPort = port; + if (host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0") { + if (from) { + container = from; + } else { + container = world.containers.find((c) => c.status === "running" && c.ports.some((pp) => pp.host === port)); + containerPort = container?.ports.find((pp) => pp.host === port)?.container ?? port; + } + } else if (from) { + container = resolveName(world, from, host) ?? undefined; + if (!container) return { ok: false, text: `curl: (6) Could not resolve host: ${host}` }; + } else { + return { ok: false, text: `curl: (6) Could not resolve host: ${host}` }; + } + if (!container || container.status !== "running") return { ok: false, text: refused }; + const spec = specFor(container.image); + const runs = container.command === spec.cmd; + if (!runs || spec.port !== containerPort) { + return { ok: false, text: from ? refused : `curl: (56) Recv failure: Connection reset by peer` }; + } + if (spec.rawPort || spec.body === undefined) return { ok: false, text: "curl: (52) Empty reply from server" }; + return { ok: true, text: spec.body }; +} + +function cmdExec(ctx: Ctx, args: string[]) { + const p = parseFlags(args, { bool: ["interactive", "tty", "detach"], value: ["env", "workdir", "user"], alias: { "-i": "--interactive", "-t": "--tty", "-d": "--detach", "-e": "--env", "-w": "--workdir", "-u": "--user" }, stopAtPositional: true }); + if (p.error) return flagError(ctx, "exec", p.error); + if (!needArgs(ctx, "exec", p.rest.length)) return; + const c = findContainer(ctx.world, p.rest[0]!); + if (!c) return noContainer(ctx, p.rest[0]!); + if (c.status !== "running") return err(ctx, `Error response from daemon: container ${c.id} is not running`); + const [cmd, ...rest] = p.rest.slice(1); + const spec = specFor(c.image); + switch (cmd) { + case "env": + case "printenv": { + const base = { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", HOSTNAME: shortId(c.id), ...c.env, HOME: "/root" }; + if (cmd === "printenv" && rest[0]) { + const v = (base as Record)[rest[0]]; + if (v === undefined) return; + return out(ctx, v); + } + return outAll(ctx, Object.entries(base).map(([k, v]) => `${k}=${v}`)); + } + case "hostname": return out(ctx, shortId(c.id)); + case "whoami": return out(ctx, "root"); + case "ls": { + const dir = rest.find((r) => !r.startsWith("-")) ?? "/"; + const mounted = c.mounts.find((m) => m.target === dir); + if (mounted) return out(ctx, mounted.kind === "volume" ? "PG_VERSION base global pg_wal postgresql.conf" : "(bind mount from the host)"); + if (dir === "/" ) return out(ctx, "bin dev etc home proc root usr var" + (c.mounts.length ? " " + c.mounts.map((m) => m.target.split("/")[1]).filter(Boolean).join(" ") : "")); + if (dir === spec.dataPath) return out(ctx, "PG_VERSION base global pg_wal postgresql.conf"); + return out(ctx, ""); + } + case "cat": { + const file = rest[0]; + if (!file) return; + if (file === "/etc/hostname") return out(ctx, shortId(c.id)); + if (file === "/etc/hosts") return outAll(ctx, ["127.0.0.1\tlocalhost", `${ipOf(ctx.world, c)}\t${shortId(c.id)}`]); + return err(ctx, `cat: ${file}: No such file or directory`); + } + case "curl": { + const target = rest.filter((r) => !r.startsWith("-"))[0]; + if (!target) return err(ctx, "curl: try 'curl --help' for more information"); + const result = curlFrom(ctx, c, target); + return result.ok ? out(ctx, result.text) : err(ctx, result.text); + } + case "ping": { + const host = rest.filter((r) => !r.startsWith("-") && !/^\d+$/.test(r))[0]; + if (!host) return err(ctx, "ping: usage error: Destination address required"); + const target = host === "localhost" ? c : resolveName(ctx.world, c, host); + if (!target) return err(ctx, `ping: ${host}: Temporary failure in name resolution`); + const ip = host === "localhost" ? "127.0.0.1" : ipOf(ctx.world, target); + return outAll(ctx, [ + `PING ${host} (${ip}) 56(84) bytes of data.`, + `64 bytes from ${host} (${ip}): icmp_seq=1 ttl=64 time=0.08 ms`, + `64 bytes from ${host} (${ip}): icmp_seq=2 ttl=64 time=0.06 ms`, + `--- ${host} ping statistics ---`, + "2 packets transmitted, 2 received, 0% packet loss", + ]); + } + case "sh": + case "bash": + return ctx.lines.push({ kind: "sys", text: `This game has no interactive shell. Try: docker exec ${c.name} env, ls or curl.` }), undefined; + default: + return err(ctx, `OCI runtime exec failed: exec failed: unable to start container process: exec: "${cmd}": executable file not found in $PATH: unknown`); + } +} + +function cmdStats(ctx: Ctx, args: string[]) { + const p = parseFlags(args, { bool: ["no-stream", "all"], value: ["format"], alias: { "-a": "--all" } }); + if (p.error) return flagError(ctx, "stats", p.error); + let list = ctx.world.containers.filter((c) => c.status === "running"); + if (p.rest.length) { + const picked: Container[] = []; + for (const ref of p.rest) { + const c = findContainer(ctx.world, ref); + if (!c) return noContainer(ctx, ref); + picked.push(c); + } + list = picked.filter((c) => c.status === "running"); + } + const rows = [["CONTAINER ID", "NAME", "CPU %", "MEM USAGE / LIMIT", "MEM %", "PIDS"]]; + for (const c of [...list].reverse()) { + const use = specFor(c.image).useMb ?? 20; + const limit = c.memoryMb > 0 ? c.memoryMb : 7870; + rows.push([shortId(c.id), c.name, "0.02%", `${use}MiB / ${c.memoryMb > 0 ? `${limit}MiB` : "7.686GiB"}`, `${((use / limit) * 100).toFixed(2)}%`, "4"]); + } + outAll(ctx, table(rows)); + if (!p.has.has("no-stream")) ctx.lines.push({ kind: "sys", text: "(The real command keeps refreshing until Ctrl+C. Add --no-stream for one snapshot.)" }); +} + +function cmdNetwork(ctx: Ctx, args: string[]) { + const world = ctx.world; + const [sub, ...rest] = args; + if (sub === "ls" || sub === "list") { + const rows = [["NETWORK ID", "NAME", "DRIVER", "SCOPE"]]; + for (const n of world.networks) rows.push([hex(`net:${n}`, 12), n, n === "host" ? "host" : n === "none" ? "null" : "bridge", "local"]); + return outAll(ctx, table(rows)); + } + if (sub === "create") { + const p = parseFlags(rest, { value: ["driver"], alias: { "-d": "--driver" } }); + if (p.error) return flagError(ctx, "network create", p.error); + if (p.rest.length !== 1) return err(ctx, `docker: "docker network create" requires exactly 1 argument.`); + const name = p.rest[0]!; + if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name)) return err(ctx, `Error response from daemon: invalid network name ${name}`); + if (world.networks.includes(name)) return err(ctx, `Error response from daemon: network with name ${name} already exists`); + world.networks.push(name); + ctx.events.push({ type: "network", name }); + return out(ctx, hex(`net:${name}`, 64)); + } + if (sub === "connect") { + if (rest.length !== 2) return err(ctx, `docker: "docker network connect" requires exactly 2 arguments.`); + const [net, ref] = rest as [string, string]; + if (!world.networks.includes(net)) return err(ctx, `Error response from daemon: network ${net} not found`); + const c = findContainer(world, ref); + if (!c) return noContainer(ctx, ref); + if (c.networks.includes(net)) return err(ctx, `Error response from daemon: endpoint with name ${c.name} already exists in network ${net}`); + c.networks.push(net); + ctx.events.push({ type: "network", name: net }); + return; + } + if (sub === "disconnect") { + if (rest.length !== 2) return err(ctx, `docker: "docker network disconnect" requires exactly 2 arguments.`); + const [net, ref] = rest as [string, string]; + const c = findContainer(world, ref); + if (!c) return noContainer(ctx, ref); + if (!c.networks.includes(net)) return err(ctx, `Error response from daemon: container ${c.id} is not connected to network ${net}`); + c.networks = c.networks.filter((n) => n !== net); + return; + } + if (sub === "rm") { + for (const net of rest) { + if (["bridge", "host", "none"].includes(net)) { err(ctx, `Error response from daemon: ${net} is a pre-defined network and cannot be removed`); continue; } + if (!world.networks.includes(net)) { err(ctx, `Error response from daemon: network ${net} not found`); continue; } + if (world.containers.some((c) => c.networks.includes(net))) { err(ctx, `Error response from daemon: error while removing network: network ${net} has active endpoints`); continue; } + world.networks = world.networks.filter((n) => n !== net); + out(ctx, net); + } + return; + } + err(ctx, sub ? `docker network: '${sub}' is not a docker network command.` : "Usage: docker network COMMAND (ls, create, connect, disconnect, rm)"); +} + +function cmdVolume(ctx: Ctx, args: string[]) { + const world = ctx.world; + const [sub, ...rest] = args; + if (sub === "ls" || sub === "list") { + const rows = [["DRIVER", "VOLUME NAME"]]; + for (const v of world.volumes) rows.push(["local", v]); + return outAll(ctx, table(rows)); + } + if (sub === "create") { + if (rest.length > 1 || rest[0]?.startsWith("-")) return err(ctx, `docker: "docker volume create" requires at most 1 argument.`); + const name = rest[0] ?? hex(`vol:${world.seq++}`, 64); + if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name)) return err(ctx, `Error response from daemon: create ${name}: "${name}" includes invalid characters for a local volume name`); + if (!world.volumes.includes(name)) world.volumes.push(name); + ctx.events.push({ type: "volume", name }); + return out(ctx, name); + } + if (sub === "rm") { + for (const v of rest) { + if (!world.volumes.includes(v)) { err(ctx, `Error response from daemon: get ${v}: no such volume`); continue; } + const users = world.containers.filter((c) => c.mounts.some((m) => m.source === v)); + if (users.length) { err(ctx, `Error response from daemon: remove ${v}: volume is in use - [${users.map((c) => c.id).join(", ")}]`); continue; } + world.volumes = world.volumes.filter((x) => x !== v); + out(ctx, v); + } + return; + } + if (sub === "prune") { + const p = parseFlags(rest, { bool: ["force", "all"], alias: { "-f": "--force", "-a": "--all" } }); + if (!p.has.has("force")) return promptNo(ctx, "all local volumes not used by at least one container"); + return prune(ctx, { volumes: true }); + } + err(ctx, sub ? `docker volume: '${sub}' is not a docker volume command.` : "Usage: docker volume COMMAND (ls, create, rm, prune)"); +} + +function promptNo(ctx: Ctx, what: string) { + out(ctx, `WARNING! This will remove ${what}.`); + out(ctx, "Are you sure you want to continue? [y/N] "); + ctx.lines.push({ kind: "sys", text: "No answer was given, so nothing was removed. Add -f to skip the question." }); +} + +function prune(ctx: Ctx, opt: { containers?: boolean; images?: boolean; allImages?: boolean; volumes?: boolean; networks?: boolean }) { + const world = ctx.world; + let reclaimed = 0; + if (opt.containers) { + const gone = world.containers.filter((c) => c.status === "exited" || c.status === "created"); + if (gone.length) out(ctx, "Deleted Containers:"); + for (const c of gone) { + out(ctx, c.id); + reclaimed += 6; + removeContainer(world, c, ctx.events); + } + } + if (opt.networks) { + const gone = world.networks.filter((n) => isUserNetwork(n) && !world.containers.some((c) => c.networks.includes(n))); + if (gone.length) out(ctx, "Deleted Networks:"); + for (const n of gone) out(ctx, n); + world.networks = world.networks.filter((n) => !gone.includes(n)); + } + if (opt.volumes) { + const gone = world.volumes.filter((v) => !world.containers.some((c) => c.mounts.some((m) => m.source === v))); + if (gone.length) out(ctx, "Deleted Volumes:"); + for (const v of gone) out(ctx, v); + world.volumes = world.volumes.filter((v) => !gone.includes(v)); + reclaimed += gone.length * 40; + } + if (opt.images) { + const used = new Set(world.containers.map((c) => c.image)); + const gone = world.images.filter((i) => (i.repo === "") || (opt.allImages && !used.has(imageRef(i)))); + if (gone.length) out(ctx, "Deleted Images:"); + for (const i of gone) { + out(ctx, i.repo === "" ? `deleted: sha256:${hex(`sha:${i.id}`, 64)}` : `untagged: ${imageRef(i)}`); + reclaimed += i.sizeMb; + } + world.images = world.images.filter((i) => !gone.includes(i)); + } + ctx.events.push({ type: "pruned", name: "prune" }); + out(ctx, ""); + out(ctx, `Total reclaimed space: ${fmtSize(reclaimed)}`); +} + +export function diskUsedMb(world: DockerWorld): number { + return world.images.reduce((sum, i) => sum + i.sizeMb, 0) + world.containers.length * 6 + world.volumes.length * 40; +} + +function cmdSystem(ctx: Ctx, args: string[]) { + const [sub, ...rest] = args; + if (sub === "df") { + const w = ctx.world; + const rows = [["TYPE", "TOTAL", "ACTIVE", "SIZE"]]; + rows.push(["Images", String(w.images.length), String(new Set(w.containers.map((c) => c.image)).size), fmtSize(w.images.reduce((s, i) => s + i.sizeMb, 0))]); + rows.push(["Containers", String(w.containers.length), String(w.containers.filter((c) => c.status === "running").length), fmtSize(w.containers.length * 6)]); + rows.push(["Local Volumes", String(w.volumes.length), String(w.volumes.filter((v) => w.containers.some((c) => c.mounts.some((m) => m.source === v))).length), fmtSize(w.volumes.length * 40)]); + return outAll(ctx, table(rows)); + } + if (sub === "prune") { + const p = parseFlags(rest, { bool: ["force", "all", "volumes"], alias: { "-f": "--force", "-a": "--all" } }); + if (p.error) return flagError(ctx, "system prune", p.error); + if (!p.has.has("force")) { + out(ctx, "WARNING! This will remove:"); + out(ctx, " - all stopped containers"); + out(ctx, " - all networks not used by at least one container"); + if (p.has.has("volumes")) out(ctx, " - all anonymous volumes not used by at least one container"); + out(ctx, p.has.has("all") ? " - all images without at least one container associated to them" : " - all dangling images"); + out(ctx, ""); + out(ctx, "Are you sure you want to continue? [y/N] "); + ctx.lines.push({ kind: "sys", text: "No answer was given, so nothing was removed. Add -f to skip the question." }); + return; + } + return prune(ctx, { containers: true, networks: true, images: true, allImages: p.has.has("all"), volumes: p.has.has("volumes") }); + } + err(ctx, sub ? `docker system: '${sub}' is not a docker system command.` : "Usage: docker system COMMAND (df, prune)"); +} + +// --------------------------------------------------------------------------------------------- +// docker compose (only when the scenario has a compose file). + +function composeOrder(services: ComposeService[]): ComposeService[] { + const done: ComposeService[] = []; + const visit = (s: ComposeService, depth: number) => { + if (done.includes(s) || depth > 10) return; + for (const d of s.dependsOn) { + const dep = services.find((x) => x.name === d); + if (dep) visit(dep, depth + 1); + } + done.push(s); + }; + services.forEach((s) => visit(s, 0)); + return done; +} + +function cmdCompose(ctx: Ctx, args: string[]) { + const world = ctx.world; + const compose = world.compose; + if (!compose) return err(ctx, "no configuration file provided: not found"); + const [sub, ...rest] = args; + const net = `${compose.project}_default`; + const mine = () => world.containers.filter((c) => c.project === compose.project); + if (sub === "up") { + const p = parseFlags(rest, { bool: ["detach", "build", "force-recreate"], alias: { "-d": "--detach" } }); + if (p.error) return flagError(ctx, "compose up", p.error); + if (!p.has.has("detach")) return err(ctx, "This game runs compose in the background. Use: docker compose up -d"); + const order = composeOrder(compose.services); + const lines: string[] = []; + let failed = 0; + if (!world.networks.includes(net)) { + world.networks.push(net); + ctx.events.push({ type: "network", name: net }); + lines.push(` ✔ Network ${net}`.padEnd(40) + "Created"); + } else lines.push(` ✔ Network ${net}`.padEnd(40) + "Running"); + for (const s of compose.services) { + for (const v of s.volumes) { + const src = v.split(":")[0]!; + if (src.startsWith("/") || src.startsWith(".")) continue; + const full = `${compose.project}_${src}`; + if (!world.volumes.includes(full)) { + world.volumes.push(full); + ctx.events.push({ type: "volume", name: full }); + lines.push(` ✔ Volume ${full}`.padEnd(40) + "Created"); + } + } + } + const errors: string[] = []; + for (const s of order) { + const name = `${compose.project}-${s.name}-1`; + let c = world.containers.find((x) => x.name === name); + const label = ` ✔ Container ${name}`.padEnd(40); + if (c && c.status === "running") { lines.push(label + "Running"); continue; } + if (!c) { + world.seq += 1; + const ports: PortMap[] = []; + for (const spec of s.ports) { + const parsed = parsePort(spec); + if (typeof parsed !== "string") ports.push({ host: parsed.host, container: parsed.container }); + } + const mounts: Mount[] = s.volumes.map((v) => { + const [src, dst] = v.split(":") as [string, string]; + return src.startsWith("/") || src.startsWith(".") ? { source: src, target: dst, kind: "bind" as const } : { source: `${compose.project}_${src}`, target: dst, kind: "volume" as const }; + }); + c = makeContainer({ + name, image: s.image, status: "created", ports, env: { ...s.env }, mounts, networks: [net], restart: s.restart ?? "no", + createdAt: world.tick, since: world.tick, project: compose.project, service: s.name, + }); + c.id = hex(`container:${name}:${world.seq}`, 64); + world.containers.push(c); + ctx.events.push({ type: "created", name }); + } + ctx.touched.add(c.id); + const problem = boot(world, c, ctx.events); + if (problem) { + failed += 1; + lines.push(` ✘ Container ${name}`.padEnd(40) + "Error"); + errors.push(problem); + } else lines.push(label + "Started"); + } + out(ctx, `[+] Running ${lines.length - failed}/${lines.length}`); + outAll(ctx, lines); + for (const e of errors) err(ctx, e); + return; + } + if (sub === "ps") { + const p = parseFlags(rest, { bool: ["all", "quiet"], alias: { "-a": "--all", "-q": "--quiet" } }); + const list = mine().filter((c) => p.has.has("all") || c.status === "running" || c.status === "restarting"); + const rows = [["NAME", "IMAGE", "SERVICE", "STATUS", "PORTS"]]; + for (const c of list) rows.push([c.name, c.image, c.service ?? "", statusText(world, c), portsText(c)]); + return outAll(ctx, table(rows)); + } + if (sub === "logs") { + const want = rest.filter((r) => !r.startsWith("-")); + for (const c of mine()) { + if (want.length && !want.includes(c.service ?? "")) continue; + for (const line of c.logs) out(ctx, `${c.name} | ${line}`); + } + return; + } + if (sub === "down") { + const gone = mine(); + for (const c of gone) { + out(ctx, ` ✔ Container ${c.name}`.padEnd(40) + "Removed"); + removeContainer(world, c, ctx.events); + } + if (world.networks.includes(net)) { + world.networks = world.networks.filter((n) => n !== net); + out(ctx, ` ✔ Network ${net}`.padEnd(40) + "Removed"); + } + return; + } + err(ctx, sub ? `docker: 'compose ${sub}' is not supported here. Try: docker compose up -d, ps, logs, down` : "Usage: docker compose COMMAND (up -d, ps, logs, down)"); +} + +// --------------------------------------------------------------------------------------------- + +function cmdDocker(ctx: Ctx, args: string[]) { + const world = ctx.world; + let [cmd, ...rest] = args; + if (cmd === undefined) { + return outAll(ctx, ["Usage: docker [OPTIONS] COMMAND", "", "Commands: ps, images, run, start, stop, restart, rm, rmi, logs, inspect, exec, pull,", " network, volume, stats, system, compose"]); + } + if (cmd === "--version" || cmd === "-v" || cmd === "version") return out(ctx, "Docker version 27.3.1, build ce12230"); + if (cmd === "container" || cmd === "image") { + const sub = rest[0]; + const map: Record = cmd === "container" + ? { ls: "ps", list: "ps", ps: "ps", rm: "rm", stop: "stop", start: "start", restart: "restart", logs: "logs", inspect: "inspect", run: "run", exec: "exec", kill: "kill", prune: "container-prune", stats: "stats" } + : { ls: "images", list: "images", rm: "rmi", pull: "pull", prune: "image-prune", inspect: "inspect" }; + const mapped = sub ? map[sub] : undefined; + if (!mapped) return err(ctx, `docker ${cmd}: '${sub ?? ""}' is not a docker ${cmd} command.`); + cmd = mapped; + rest = rest.slice(1); + } + switch (cmd) { + case "run": return cmdRun(ctx, rest); + case "ps": return cmdPs(ctx, rest); + case "images": return cmdImages(ctx, rest); + case "pull": { + const p = parseFlags(rest, {}); + if (p.error) return flagError(ctx, "pull", p.error); + if (!needArgs(ctx, "pull", p.rest.length)) return; + if (!/^[a-z0-9][a-z0-9._/-]*(:[A-Za-z0-9_][A-Za-z0-9_.-]*)?$/.test(p.rest[0]!)) return err(ctx, "invalid reference format"); + pullImage(ctx, p.rest[0]!); + return; + } + case "start": { + const p = parseFlags(rest, { bool: ["attach", "interactive"], alias: { "-a": "--attach", "-i": "--interactive" } }); + if (p.error) return flagError(ctx, "start", p.error); + if (!needArgs(ctx, "start", p.rest.length)) return; + return eachContainer(ctx, p.rest, (c) => startOne(ctx, c)); + } + case "stop": + case "kill": { + const p = parseFlags(rest, { value: ["time", "signal"], alias: { "-t": "--time", "-s": "--signal" } }); + if (p.error) return flagError(ctx, cmd, p.error); + if (!needArgs(ctx, cmd, p.rest.length)) return; + return eachContainer(ctx, p.rest, (c) => { + if (cmd === "kill" && c.status !== "running") return err(ctx, `Error response from daemon: cannot kill container: ${c.name}: container ${c.id} is not running`); + stop(ctx, c, cmd === "kill" ? 137 : 0); + out(ctx, c.name); + }); + } + case "restart": { + const p = parseFlags(rest, { value: ["time"], alias: { "-t": "--time" } }); + if (p.error) return flagError(ctx, "restart", p.error); + if (!needArgs(ctx, "restart", p.rest.length)) return; + return eachContainer(ctx, p.rest, (c) => { + stop(ctx, c); + startOne(ctx, c); + }); + } + case "rm": { + const p = parseFlags(rest, { bool: ["force", "volumes"], alias: { "-f": "--force", "-v": "--volumes" } }); + if (p.error) return flagError(ctx, "rm", p.error); + if (!needArgs(ctx, "rm", p.rest.length)) return; + return eachContainer(ctx, p.rest, (c) => { + if ((c.status === "running" || c.status === "restarting") && !p.has.has("force")) { + return err(ctx, `Error response from daemon: You cannot remove a ${c.status === "running" ? "running" : "restarting"} container ${c.id}. Stop the container before attempting removal or force remove`); + } + removeContainer(world, c, ctx.events); + out(ctx, c.name); + }); + } + case "rmi": { + const p = parseFlags(rest, { bool: ["force"], alias: { "-f": "--force" } }); + if (p.error) return flagError(ctx, "rmi", p.error); + if (!needArgs(ctx, "rmi", p.rest.length)) return; + for (const ref of p.rest) { + const image = findImage(world, ref); + if (!image) { err(ctx, `Error response from daemon: No such image: ${normalizeImage(ref)}`); continue; } + const users = world.containers.filter((c) => c.image === imageRef(image)); + if (users.length && !p.has.has("force")) { + err(ctx, `Error response from daemon: conflict: unable to remove repository reference "${imageRef(image)}" (must force) - container ${shortId(users[0]!.id)} is using its referenced image ${image.id}`); + continue; + } + world.images = world.images.filter((i) => i !== image); + out(ctx, image.repo === "" ? `Deleted: sha256:${hex(`sha:${image.id}`, 64)}` : `Untagged: ${imageRef(image)}`); + } + return; + } + case "logs": return cmdLogs(ctx, rest); + case "inspect": return cmdInspect(ctx, rest); + case "exec": return cmdExec(ctx, rest); + case "stats": return cmdStats(ctx, rest); + case "network": return cmdNetwork(ctx, rest); + case "volume": return cmdVolume(ctx, rest); + case "system": return cmdSystem(ctx, rest); + case "compose": return cmdCompose(ctx, rest); + case "container-prune": + case "image-prune": { + const p = parseFlags(rest, { bool: ["force", "all"], alias: { "-f": "--force", "-a": "--all" } }); + if (p.error) return flagError(ctx, cmd, p.error); + if (!p.has.has("force")) return promptNo(ctx, cmd === "container-prune" ? "all stopped containers" : "all dangling images"); + return cmd === "container-prune" ? prune(ctx, { containers: true }) : prune(ctx, { images: true, allImages: p.has.has("all") }); + } + default: + err(ctx, `docker: '${cmd}' is not a docker command.`); + err(ctx, "See 'docker --help'"); + } +} + +function runSimple(ctx: Ctx, segment: string, depth: number): boolean { + let text = segment.trim(); + if (!text) return true; + // $(...) is replaced by what the inner command prints, one word per line. + for (let guard = 0; guard < 4 && /\$\(([^()]*)\)/.test(text); guard++) { + text = text.replace(/\$\(([^()]*)\)/g, (_m, inner: string) => { + if (depth >= 2) return ""; + const sub: Ctx = { world: ctx.world, lines: [], events: ctx.events, touched: ctx.touched }; + runSimple(sub, inner, depth + 1); + return sub.lines.filter((l) => l.kind === "out").map((l) => l.text.trim()).filter(Boolean).join(" "); + }); + } + const tokens = tokenize(text); + if (tokens === null) { + err(ctx, "bash: unexpected EOF while looking for matching quote"); + return false; + } + const before = ctx.lines.length; + const head = tokens[0]; + if (head === undefined) return true; + if (head === "docker" || head === "docker-compose") cmdDocker(ctx, head === "docker" ? tokens.slice(1) : ["compose", ...tokens.slice(1)]); + else if (head === "curl") { + const target = tokens.slice(1).filter((t) => !t.startsWith("-"))[0]; + if (!target) err(ctx, "curl: try 'curl --help' or 'curl --manual' for more information"); + else { + const result = curlFrom(ctx, null, target); + if (result.ok) { + out(ctx, result.text); + ctx.events.push({ type: "pulled", name: "curl" }); + } else err(ctx, result.text); + } + } else if ((head === "cat" || head === "less") && ctx.world.compose && /^(\.\/)?(docker-)?compose\.ya?ml$/.test(tokens[1] ?? "")) { + outAll(ctx, ctx.world.compose.file); + } else if (head === "ls") outAll(ctx, ctx.world.compose ? ["docker-compose.yml"] : []); + else if (head === "pwd") out(ctx, "/home/learner"); + else if (head === "whoami") out(ctx, "learner"); + else err(ctx, `bash: ${head}: command not found`); + const failed = ctx.lines.slice(before).some((l) => l.kind === "err"); + return !failed; +} + +export const HELP_LINES = [ + "Docker commands you can use here:", + " docker ps [-a] list containers", + " docker images list images", + " docker run -d -p 8080:80 --name web [-e K=V] [-v vol:/path] [--network n] [--restart always] [--memory 512m] IMAGE", + " docker start|stop|restart|rm [-f] NAME", + " docker rmi IMAGE docker pull IMAGE[:TAG]", + " docker logs [--tail N] NAME docker inspect [-f '{{.State.ExitCode}}'] NAME", + " docker exec NAME env | ls | cat FILE | curl HOST:PORT | ping HOST", + " docker network ls|create|connect docker volume ls|create", + " docker stats --no-stream docker system df|prune [-f]", + " curl localhost:8080 (the host side check)", + " docker compose up -d | ps | down (only when a compose file is shown)", + " hint clear reset", +]; + +/** Run one typed line (it may hold several commands joined with &&). Changes the world in place. */ +export function runLine(world: DockerWorld, line: string): RunResult { + const ctx: Ctx = { world, lines: [], events: [], touched: new Set() }; + try { + if (line.length > 300) { + err(ctx, "bash: command line too long"); + return { lines: ctx.lines, ok: false, events: ctx.events }; + } + let ok = true; + for (const part of splitAnd(line)) { + world.tick += 1; + ok = runSimple(ctx, part, 0); + settle(world, ctx.touched, ctx.events); + if (!ok) break; + } + return { lines: ctx.lines, ok, events: ctx.events }; + } catch { + err(ctx, "bash: something went wrong with that command"); + return { lines: ctx.lines, ok: false, events: ctx.events }; + } +} + +// --------------------------------------------------------------------------------------------- +// Goals: what must be true at the end. Pure data, so a round can travel as JSON. + +export type Goal = + | { kind: "running"; name: string; label: string } + | { kind: "absent"; name: string; label: string } + | { kind: "image"; name: string; image: string; label: string } + | { kind: "served"; name: string; contains?: string; label: string } + | { kind: "publishes"; name: string; port: number; label: string } + | { kind: "env"; name: string; key: string; value?: string; label: string } + | { kind: "mount"; name: string; target: string; label: string } + | { kind: "sharedNetwork"; a: string; b: string; label: string } + | { kind: "noExited"; label: string } + | { kind: "noDangling"; label: string } + | { kind: "restartPolicy"; name: string; policy: RestartPolicy; label: string } + | { kind: "memoryAtLeast"; name: string; mb: number; label: string } + | { kind: "imageExists"; image: string; label: string } + | { kind: "volumeExists"; name: string; label: string }; + +/** What a host `curl` would get for a container, trying each published port. */ +export function servedBody(world: DockerWorld, name: string): string | null { + const c = world.containers.find((x) => x.name === name); + if (!c || c.status !== "running") return null; + for (const p of c.ports) { + const ctx: Ctx = { world, lines: [], events: [], touched: new Set() }; + const res = curlFrom(ctx, null, `localhost:${p.host}`); + if (res.ok) return res.text; + } + return null; +} + +export function checkGoal(world: DockerWorld, goal: Goal): boolean { + const find = (name: string) => world.containers.find((c) => c.name === name); + switch (goal.kind) { + case "running": return find(goal.name)?.status === "running"; + case "absent": return !find(goal.name); + case "image": return find(goal.name)?.image === normalizeImage(goal.image); + case "served": { + const body = servedBody(world, goal.name); + return body !== null && (goal.contains === undefined || body.includes(goal.contains)); + } + case "publishes": return find(goal.name)?.ports.some((p) => p.container === goal.port) ?? false; + case "env": { + const v = find(goal.name)?.env[goal.key]; + return v !== undefined && v !== "" && (goal.value === undefined || v === goal.value); + } + case "mount": return find(goal.name)?.mounts.some((m) => m.target === goal.target && m.kind === "volume") ?? false; + case "sharedNetwork": { + const a = find(goal.a); + const b = find(goal.b); + return !!a && !!b && a.networks.some((n) => isUserNetwork(n) && b.networks.includes(n)); + } + case "noExited": return !world.containers.some((c) => c.status === "exited" || c.status === "created"); + case "noDangling": return !world.images.some((i) => i.repo === ""); + case "restartPolicy": return find(goal.name)?.restart === goal.policy; + case "memoryAtLeast": { + const c = find(goal.name); + return !!c && c.status === "running" && (c.memoryMb === 0 || c.memoryMb >= goal.mb); + } + case "imageExists": return !!findImage(world, goal.image); + case "volumeExists": return world.volumes.includes(goal.name); + } +} diff --git a/server/src/shared/games/docker/engine.ts b/server/src/shared/games/docker/engine.ts new file mode 100644 index 00000000..a76ee215 --- /dev/null +++ b/server/src/shared/games/docker/engine.ts @@ -0,0 +1,144 @@ +/* eslint-disable no-control-regex -- the shell engines reject or use control characters on purpose */ +// The Docker Commands daily game. Two modes share each day: "fix" (a virtual Docker host that is +// broken; the player types real commands to repair it) and "build" (the player assembles a +// Dockerfile or a compose file from pieces). The engine is pure: it replays the commands or the +// pieces from the start state and checks the goals. It never throws. + +import { dayNumber, hashString, pickDaily } from "../daily.js"; +import type { GameEngine, Stars, VerifyResult } from "../types.js"; +import { checkBuildGoal, simulateBuild, type BuildReport } from "./builder.js"; +import { checkGoal, cloneWorld, runLine } from "./daemon.js"; +import { POOL, type BuildRound, type DockerRound, type FixRound } from "./scenarios.js"; + +export type { BuildRound, DockerRound, FixRound } from "./scenarios.js"; + +export type FixSubmission = { mode: "fix"; commands: string[]; hints: number }; +export type BuildSubmission = { mode: "build"; steps: string[]; hints: number }; +export type DockerSubmission = FixSubmission | BuildSubmission; + +export const MAX_COMMANDS = 100; +export const MAX_COMMAND_LENGTH = 300; +export const MAX_STEPS = 40; +const MAX_HINTS = 50; + +const POOL_BY_ID = new Map(POOL.map((r) => [r.id, r])); + +/** Today's three rounds: one per difficulty, and always at least one fix and one build round. */ +export function roundsFor(dayKey: string): DockerRound[] { + const picked = pickDaily(POOL, dayKey, "docker"); + const modes = new Set(picked.map((r) => r.mode)); + if (modes.size === 2) return picked; + // All three share a mode: swap the medium round for the nearest medium round of the other mode. + const want = picked[0]!.mode === "fix" ? "build" : "fix"; + const tier = POOL.filter((r) => r.difficulty === "medium"); + const start = tier.indexOf(picked[1]!); + for (let step = 1; step <= tier.length; step++) { + const candidate = tier[(Math.max(0, start) + step + dayNumber(dayKey)) % tier.length]!; + if (candidate.mode === want) return [picked[0]!, candidate, picked[2]!]; + } + const any = tier.find((r) => r.mode === want); + return any ? [picked[0]!, any, picked[2]!] : picked; +} + +const isObject = (v: unknown): v is Record => typeof v === "object" && v !== null && !Array.isArray(v); + +export function parseSubmission(input: unknown): DockerSubmission | null { + try { + if (!isObject(input)) return null; + const keys = Object.keys(input); + const hints = input.hints; + if (typeof hints !== "number" || !Number.isInteger(hints) || hints < 0 || hints > MAX_HINTS) return null; + if (input.mode === "fix") { + if (keys.some((k) => !["mode", "commands", "hints"].includes(k))) return null; + const commands = input.commands; + if (!Array.isArray(commands) || commands.length > MAX_COMMANDS) return null; + for (const c of commands) { + if (typeof c !== "string" || c.trim().length === 0 || c.length > MAX_COMMAND_LENGTH || /[\u0000-\u0008\u000b-\u001f\u007f]/.test(c)) return null; + } + return { mode: "fix", commands: commands as string[], hints }; + } + if (input.mode === "build") { + if (keys.some((k) => !["mode", "steps", "hints"].includes(k))) return null; + const steps = input.steps; + if (!Array.isArray(steps) || steps.length > MAX_STEPS) return null; + for (const s of steps) if (typeof s !== "string" || !/^[A-Za-z0-9_.:-]{1,64}$/.test(s)) return null; + return { mode: "build", steps: steps as string[], hints }; + } + return null; + } catch { + return null; + } +} + +const fail = (message: string, score = 0): VerifyResult => ({ passed: false, stars: 0, score, message }); + +function plural(n: number, word: string) { + return `${n} ${word}${n === 1 ? "" : "s"}`; +} + +function verifyFix(round: FixRound, sub: FixSubmission): VerifyResult { + if (sub.commands.length === 0) return fail("You have not typed any command yet."); + const world = cloneWorld(round.world); + for (const command of sub.commands.slice(0, MAX_COMMANDS)) runLine(world, command); + const unmet = round.goals.filter((g) => !checkGoal(world, g)); + const count = sub.commands.length; + if (unmet.length > 0) return fail(`Not fixed yet: ${unmet[0]!.label}.`, count); + let stars: Stars = 1; + if (sub.hints <= 1 && count <= round.par + 4) stars = 2; + if (sub.hints === 0 && count <= round.par + 1) stars = 3; + const message = + stars === 3 ? `Fixed in ${plural(count, "command")} with no hints, very clean.` + : stars === 2 ? `Fixed in ${plural(count, "command")}. Fewer commands and no hints give the third star.` + : `Fixed in ${plural(count, "command")}. Use fewer commands and fewer hints for more stars.`; + return { passed: true, stars, score: count, message }; +} + +export function buildReportFor(round: BuildRound, steps: string[]): BuildReport { + return simulateBuild(round, steps); +} + +function verifyBuild(round: BuildRound, sub: BuildSubmission): VerifyResult { + if (sub.steps.length === 0) return fail("You have not placed any piece yet."); + const report = simulateBuild(round, sub.steps); + const count = sub.steps.length; + const unmet = round.goals.filter((g) => !checkBuildGoal(report, g)); + if (unmet.length > 0) return fail(report.error ?? `Not done yet: ${unmet[0]!.label}.`, count); + const clean = report.cacheFriendly && report.warnings.length === 0; + const best = simulateBuild(round, round.solution); + let stars: Stars = 1; + if (clean && sub.hints <= 1 && count <= round.par + 2) stars = 2; + if (clean && sub.hints === 0 && count <= round.par && report.sizeMb <= best.sizeMb * 1.05 + 1) stars = 3; + const what = round.kind === "compose" + ? `The stack starts and localhost:${report.port ?? ""} answers.` + : `The image builds in ${report.coldSec} s, a rebuild takes ${report.rebuildSec} s, and it is ${report.sizeMb} MB.`; + const tip = stars === 3 ? " Clean and with no hints." : !report.cacheFriendly ? " Put the dependency install before the code copy for more stars." : report.warnings.length ? ` ${report.warnings[0]}` : " Fewer hints and no extra pieces give more stars."; + return { passed: true, stars, score: count, message: `${what}${tip}` }; +} + +export function verify(round: DockerRound, submission: DockerSubmission): VerifyResult { + try { + const known = isObject(round) && typeof round.id === "string" ? POOL_BY_ID.get(round.id) : undefined; + const real = known ?? (isObject(round) && (round.mode === "fix" || round.mode === "build") ? round : undefined); + if (!real) return fail("That round could not be checked."); + const sub = parseSubmission(submission); + if (!sub) return fail("That did not look like a finished round."); + if (real.mode !== sub.mode) { + return fail(real.mode === "fix" ? "This is a fix round: use the terminal to repair it." : "This is a build round: put the pieces together."); + } + return real.mode === "fix" ? verifyFix(real, sub as FixSubmission) : verifyBuild(real, sub as BuildSubmission); + } catch { + return fail("That answer could not be checked."); + } +} + +export const dockerEngine: GameEngine = { + id: "docker", + title: "Docker Commands", + tagline: "Fix broken containers in a terminal, and build Dockerfiles and compose files from pieces.", + roundsFor, + parseSubmission, + verify, +}; + +/** A small stable number for a round id, for tests and for shuffles that must repeat. */ +export const roundHash = (id: string) => hashString(id); diff --git a/server/src/shared/games/docker/scenarios.ts b/server/src/shared/games/docker/scenarios.ts new file mode 100644 index 00000000..6f652f3c --- /dev/null +++ b/server/src/shared/games/docker/scenarios.ts @@ -0,0 +1,502 @@ +// The pool of Docker Commands rounds. Each one is plain data (no functions), so it can travel as +// JSON to the browser: a fix round holds a starting world and goals, a build round holds pieces. +// Every round carries a `solution` that the tests replay. + +import type { RoundBase } from "../types.js"; +import type { AppSpec, BuildData, BuildGoal, BuildPiece, BuildSlot, ComposeFact, ComposeLine } from "./builder.js"; +import { + danglingImage, emptyWorld, makeContainer, makeImage, type DockerWorld, type Goal, +} from "./daemon.js"; + +export type FixRound = RoundBase & { + mode: "fix"; + /** The starting state of the virtual Docker host. */ + world: DockerWorld; + goals: Goal[]; + /** Commands the shortest sensible fix takes, including one look at what is wrong. */ + par: number; + hints: string[]; + solution: string[]; +}; + +export type BuildRound = RoundBase & BuildData & { + mode: "build"; + goals: BuildGoal[]; + par: number; + hints: string[]; + solution: string[]; +}; + +export type DockerRound = FixRound | BuildRound; + +const world = (p: Partial): DockerWorld => ({ ...emptyWorld(), ...p }); + +const NGINX_STOP_LOGS = ["nginx: [notice] signal 15 (SIGTERM) received, exiting"]; + +// --------------------------------------------------------------------------------------------- +// Fix rounds. + +const startStopped: FixRound = { + id: "docker-start-stopped", mode: "fix", difficulty: "easy", + title: "The site is down", + brief: "The web container was stopped and now http://localhost:8080 shows nothing. Bring the site back with the same container.", + world: world({ + images: [makeImage("nginx:1.25")], + containers: [makeContainer({ name: "web", image: "nginx:1.25", status: "exited", exitCode: 0, ports: [{ host: 8080, container: 80 }], logs: NGINX_STOP_LOGS, since: "10 minutes" })], + }), + goals: [ + { kind: "running", name: "web", label: "Container web is running" }, + { kind: "served", name: "web", contains: "Welcome to nginx", label: "curl localhost:8080 shows the nginx page" }, + ], + par: 2, + hints: ["List all containers, also the stopped ones: docker ps -a", "The container is called web. It only needs to be started again.", "Run: docker start web"], + solution: ["docker ps -a", "docker start web"], +}; + +const wrongPort: FixRound = { + id: "docker-wrong-port", mode: "fix", difficulty: "easy", + title: "Nothing answers on 8080", + brief: "The container web is running, but curl localhost:8080 fails. The nginx server inside listens on port 80.", + world: world({ + images: [makeImage("nginx:1.25")], + containers: [makeContainer({ name: "web", image: "nginx:1.25", ports: [{ host: 8080, container: 8080 }], logs: ["/docker-entrypoint.sh: Configuration complete; ready for start up", "nginx: [notice] start worker processes"], since: "5 minutes" })], + }), + goals: [ + { kind: "running", name: "web", label: "Container web is running" }, + { kind: "publishes", name: "web", port: 80, label: "Host port 8080 leads to container port 80" }, + { kind: "served", name: "web", contains: "Welcome to nginx", label: "curl localhost:8080 shows the nginx page" }, + ], + par: 3, + hints: ["Try curl localhost:8080 and read the error. Then look at the PORTS column of docker ps.", "The mapping is -p HOST:CONTAINER. The container side must be 80. A running container cannot change its ports, so remove it with docker rm -f web.", "Run it again: docker run -d --name web -p 8080:80 nginx:1.25"], + solution: ["curl localhost:8080", "docker rm -f web", "docker run -d --name web -p 8080:80 nginx:1.25"], +}; + +const missingEnv: FixRound = { + id: "docker-missing-env", mode: "fix", difficulty: "medium", + title: "The database stops at once", + brief: "Container db (postgres:16) exits a second after it starts. Find out why and get it running.", + world: world({ + images: [makeImage("postgres:16")], + containers: [makeContainer({ + name: "db", image: "postgres:16", status: "exited", exitCode: 1, since: "2 minutes", + logs: [ + "Error: Database is uninitialized and superuser password is not specified.", + " You must specify POSTGRES_PASSWORD to a non-empty value for the", + " superuser. For example, \"-e POSTGRES_PASSWORD=password\" on \"docker run\".", + ], + })], + }), + goals: [ + { kind: "running", name: "db", label: "Container db is running" }, + { kind: "env", name: "db", key: "POSTGRES_PASSWORD", label: "db has a POSTGRES_PASSWORD" }, + ], + par: 3, + hints: ["docker ps -a shows the exit code. docker logs db shows the reason.", "The log asks for POSTGRES_PASSWORD. A container keeps the environment it was created with, so remove it first: docker rm db", "docker run -d --name db -e POSTGRES_PASSWORD=secret postgres:16"], + solution: ["docker logs db", "docker rm db", "docker run -d --name db -e POSTGRES_PASSWORD=secret postgres:16"], +}; + +const portTaken: FixRound = { + id: "docker-port-taken", mode: "fix", difficulty: "medium", + title: "Port 8080 is already taken", + brief: "Start a container named web from nginx:1.25 that answers on localhost. Port 8080 is the plan, but something may be using it. Free the port or pick another one.", + world: world({ + images: [makeImage("nginx:1.25")], + containers: [makeContainer({ name: "old-site", image: "nginx:1.25", ports: [{ host: 8080, container: 80 }], logs: ["nginx: [notice] start worker processes"], since: "3 hours" })], + }), + goals: [ + { kind: "running", name: "web", label: "Container web is running" }, + { kind: "publishes", name: "web", port: 80, label: "web publishes container port 80" }, + { kind: "served", name: "web", contains: "Welcome to nginx", label: "curl on its host port shows the nginx page" }, + ], + par: 3, + hints: ["docker ps shows who uses 8080.", "Either stop the old container (docker stop old-site) or use another host port, like -p 8081:80.", "docker run -d --name web -p 8081:80 nginx:1.25 works. If a run fails, a half made container stays: remove it with docker rm web."], + solution: ["docker ps", "docker stop old-site", "docker run -d --name web -p 8080:80 nginx:1.25"], +}; + +const lostData: FixRound = { + id: "docker-lost-data", mode: "fix", difficulty: "medium", + title: "The database forgets everything", + brief: "Every time the db container is removed and recreated, the orders are gone. Keep the data on a named volume called pgdata, mounted at /var/lib/postgresql/data.", + world: world({ + images: [makeImage("postgres:16")], + containers: [makeContainer({ + name: "db", image: "postgres:16", env: { POSTGRES_PASSWORD: "secret" }, ports: [{ host: 5432, container: 5432 }], + logs: ["PostgreSQL init process complete; ready for start up.", "LOG: database system is ready to accept connections"], since: "1 hour", + })], + }), + goals: [ + { kind: "running", name: "db", label: "Container db is running" }, + { kind: "mount", name: "db", target: "/var/lib/postgresql/data", label: "A named volume is mounted at /var/lib/postgresql/data" }, + { kind: "env", name: "db", key: "POSTGRES_PASSWORD", label: "db still has its POSTGRES_PASSWORD" }, + ], + par: 3, + hints: ["docker inspect db has a Mounts list. It is empty, so the data lives inside the container.", "A volume must be given when the container is created. Remove db, then run it again with -v pgdata:/var/lib/postgresql/data", "docker run -d --name db -e POSTGRES_PASSWORD=secret -v pgdata:/var/lib/postgresql/data postgres:16"], + solution: ["docker inspect db", "docker rm -f db", "docker run -d --name db -e POSTGRES_PASSWORD=secret -v pgdata:/var/lib/postgresql/data postgres:16"], +}; + +const noNetwork: FixRound = { + id: "docker-no-network", mode: "fix", difficulty: "medium", + title: "The web container cannot find the database", + brief: "web talks to the host name db, but it crashes. Both containers are on the default bridge network, where names do not work. Connect them so that web runs and curl localhost:8080 works.", + world: world({ + images: [makeImage("shop/web:2.0"), makeImage("postgres:16")], + containers: [ + makeContainer({ name: "db", image: "postgres:16", env: { POSTGRES_PASSWORD: "secret" }, logs: ["LOG: database system is ready to accept connections"], since: "20 minutes" }), + makeContainer({ + name: "web", image: "shop/web:2.0", status: "exited", exitCode: 1, env: { DB_HOST: "db" }, ports: [{ host: 8080, container: 3000 }], since: "19 minutes", + logs: ["Error: getaddrinfo ENOTFOUND db", " at GetAddrInfoReqWrap.onlookup [as oncomplete] (node:dns:109:26)"], + }), + ], + }), + goals: [ + { kind: "running", name: "db", label: "Container db is running" }, + { kind: "sharedNetwork", a: "web", b: "db", label: "web and db share a network you created" }, + { kind: "running", name: "web", label: "Container web is running" }, + { kind: "served", name: "web", contains: "database", label: "curl localhost:8080 says it is connected to the database" }, + ], + par: 5, + hints: ["docker logs web says it cannot find the host db. Names only work on a network you create yourself.", "Create one with docker network create appnet, then connect db and web with docker network connect appnet NAME.", "Finish with docker start web."], + solution: ["docker logs web", "docker network create appnet", "docker network connect appnet db", "docker network connect appnet web", "docker start web"], +}; + +const oomLoop: FixRound = { + id: "docker-oom-loop", mode: "fix", difficulty: "hard", + title: "The worker keeps restarting", + brief: "The container worker restarts again and again. Find the reason, then run it so it stays up. Keep the restart policy unless-stopped.", + world: world({ + images: [makeImage("acme/worker:3.1")], + containers: [makeContainer({ + name: "worker", image: "acme/worker:3.1", status: "restarting", exitCode: 137, oomKilled: true, restartCount: 14, restart: "unless-stopped", memoryMb: 256, + logs: ["worker: loading model into memory (needs about 400 MB)", "Killed", "worker: loading model into memory (needs about 400 MB)", "Killed"], since: "4 seconds", + })], + }), + goals: [ + { kind: "memoryAtLeast", name: "worker", mb: 400, label: "worker is running with enough memory (400 MB or more, or no limit)" }, + { kind: "restartPolicy", name: "worker", policy: "unless-stopped", label: "The restart policy is still unless-stopped" }, + ], + par: 5, + hints: ["docker ps shows Restarting. docker logs worker ends with Killed.", "docker inspect worker (try -f '{{.State.OOMKilled}}') shows OOMKilled true and a Memory limit of 256 MB. The app needs about 400 MB.", "Memory cannot be changed on the old container. Remove it and run again with --memory 512m and --restart unless-stopped."], + solution: ["docker ps", "docker logs worker", "docker inspect worker", "docker rm -f worker", "docker run -d --name worker --restart unless-stopped --memory 512m acme/worker:3.1"], +}; + +const newRelease: FixRound = { + id: "docker-new-release", mode: "fix", difficulty: "hard", + title: "Ship release 2.0", + brief: "The site container runs acme/site:1.0 on port 8080. Replace it with acme/site:2.0 on the same port, and keep the cache container running. The new release has its own needs, so read what it says if it fails.", + world: world({ + images: [makeImage("acme/site:1.0"), makeImage("redis:7")], + containers: [ + makeContainer({ name: "cache", image: "redis:7", logs: ["Ready to accept connections tcp"], since: "2 days" }), + makeContainer({ name: "site", image: "acme/site:1.0", ports: [{ host: 8080, container: 80 }], logs: ["site 1.0 ready"], since: "2 days" }), + ], + }), + goals: [ + { kind: "image", name: "site", image: "acme/site:2.0", label: "Container site uses acme/site:2.0" }, + { kind: "running", name: "site", label: "Container site is running" }, + { kind: "served", name: "site", contains: "v2", label: "curl localhost:8080 shows the v2 page" }, + { kind: "running", name: "cache", label: "Container cache is still running" }, + ], + par: 4, + hints: ["docker pull acme/site:2.0 downloads the new release. Then stop and remove the old site container to free the name and port 8080.", "If the new container exits, docker logs site tells you what it needs. Here it is the variable SITE_NAME.", "docker run -d --name site -p 8080:80 -e SITE_NAME=Acme acme/site:2.0"], + solution: ["docker pull acme/site:2.0", "docker stop site", "docker rm site", "docker run -d --name site -p 8080:80 -e SITE_NAME=Acme acme/site:2.0"], +}; + +const diskFull: FixRound = { + id: "docker-disk-full", mode: "fix", difficulty: "hard", + title: "Free some disk space", + brief: "The server disk is almost full. Remove the stopped containers and the dangling images (the ones shown as ). Keep the running containers, the image shop/api:1.2 and both volumes.", + world: world({ + images: [ + makeImage("nginx:1.25"), makeImage("postgres:16"), makeImage("shop/api:1.2"), makeImage("legacy/app:0.9"), + danglingImage("a", 320), danglingImage("b", 210), danglingImage("c", 150), + ], + volumes: ["pgdata", "old-cache"], + containers: [ + makeContainer({ name: "web", image: "nginx:1.25", ports: [{ host: 8080, container: 80 }], since: "3 days" }), + makeContainer({ name: "db", image: "postgres:16", env: { POSTGRES_PASSWORD: "secret" }, mounts: [{ source: "pgdata", target: "/var/lib/postgresql/data", kind: "volume" }], since: "3 days" }), + makeContainer({ name: "build-tmp", image: "legacy/app:0.9", status: "exited", exitCode: 0, since: "6 days" }), + makeContainer({ name: "test-run", image: "nginx:1.25", status: "exited", exitCode: 1, since: "4 days" }), + makeContainer({ name: "old-api", image: "shop/api:1.2", status: "exited", exitCode: 137, since: "9 days" }), + ], + }), + goals: [ + { kind: "noExited", label: "No stopped containers are left" }, + { kind: "noDangling", label: "No dangling images are left" }, + { kind: "running", name: "web", label: "web is still running" }, + { kind: "running", name: "db", label: "db is still running" }, + { kind: "imageExists", image: "shop/api:1.2", label: "Image shop/api:1.2 is kept" }, + { kind: "volumeExists", name: "pgdata", label: "Volume pgdata is kept" }, + { kind: "volumeExists", name: "old-cache", label: "Volume old-cache is kept" }, + ], + par: 2, + hints: ["docker system df shows what takes the space. docker ps -a shows the stopped containers.", "docker system prune -f removes stopped containers and dangling images. Be careful with -a (all unused images) and --volumes: they also remove things you must keep.", "Run: docker system prune -f"], + solution: ["docker system df", "docker system prune -f"], +}; + +const COMPOSE_FILE = [ + "services:", + " web:", + " image: shop/web:2.0", + " ports: [\"8080:3000\"]", + " environment:", + " DB_HOST: db", + " depends_on: [db]", + " db:", + " image: postgres:16", + " environment:", + " POSTGRES_PASSWORD: secret", + " volumes:", + " - pgdata:/var/lib/postgresql/data", + "volumes:", + " pgdata:", +]; + +const composeConflict: FixRound = { + id: "docker-compose-conflict", mode: "fix", difficulty: "hard", + title: "The stack will not come up", + brief: "docker-compose.yml describes a web app and its database (project shop). Start the whole stack with compose and make the app answer on localhost:8080. Type cat docker-compose.yml to read the file.", + world: world({ + images: [makeImage("shop/web:2.0"), makeImage("postgres:16"), makeImage("nginx:1.25")], + containers: [makeContainer({ name: "scratch", image: "nginx:1.25", ports: [{ host: 8080, container: 80 }], logs: ["nginx: [notice] start worker processes"], since: "1 day" })], + compose: { + project: "shop", + file: COMPOSE_FILE, + services: [ + { name: "web", image: "shop/web:2.0", ports: ["8080:3000"], env: { DB_HOST: "db" }, volumes: [], dependsOn: ["db"] }, + { name: "db", image: "postgres:16", ports: [], env: { POSTGRES_PASSWORD: "secret" }, volumes: ["pgdata:/var/lib/postgresql/data"], dependsOn: [] }, + ], + }, + }), + goals: [ + { kind: "running", name: "shop-db-1", label: "shop-db-1 is running" }, + { kind: "running", name: "shop-web-1", label: "shop-web-1 is running" }, + { kind: "served", name: "shop-web-1", contains: "database", label: "curl localhost:8080 says it is connected to the database" }, + ], + par: 4, + hints: ["Start with docker compose up -d, then docker compose ps -a or docker ps -a to see what did not start.", "The web service wants host port 8080, but the container scratch holds it. Stop it: docker stop scratch", "After stopping scratch, run docker compose up -d again. It starts what is missing."], + solution: ["docker compose up -d", "docker ps -a", "docker stop scratch", "docker compose up -d"], +}; + +// --------------------------------------------------------------------------------------------- +// Build rounds. + +const piece = (id: string, text: string): BuildPiece => ({ id, text }); +const NODE_APP: AppSpec = { runtime: "node", manifest: "package*.json", defaultPort: 3000, start: ["node server.js", "npm start"] }; + +const buildNodeOrder: BuildRound = { + id: "docker-build-node-order", mode: "build", difficulty: "easy", kind: "dockerfile", + title: "Order a Node Dockerfile", + brief: "Put the lines of this Node app's Dockerfile in the right order. It must build, answer on port 3000, and rebuild fast after a code change (10 seconds or less).", + app: { ...NODE_APP }, + pieces: [ + piece("cp-src", "COPY . ."), piece("cmd", 'CMD ["node", "server.js"]'), piece("npm-ci", "RUN npm ci"), piece("from", "FROM node:20-slim"), + piece("expose", "EXPOSE 3000"), piece("cp-pkg", "COPY package*.json ./"), piece("workdir", "WORKDIR /app"), + ], + goals: [ + { kind: "builds", label: "The image builds" }, + { kind: "reachable", port: 3000, label: "The app answers on port 3000" }, + { kind: "rebuild", maxSec: 10, label: "A rebuild after a code change takes 10 seconds or less" }, + ], + par: 7, + hints: ["FROM always comes first. WORKDIR comes before any COPY.", "Docker reuses a layer when nothing above it changed. Copy only package*.json first, run npm ci, and only then copy the rest of the code.", "Order: FROM, WORKDIR, COPY package*.json, RUN npm ci, COPY . ., EXPOSE, CMD."], + solution: ["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "expose", "cmd"], +}; + +const buildSlim: BuildRound = { + id: "docker-build-slim", mode: "build", difficulty: "easy", kind: "dockerfile", + title: "Pick the right base image", + brief: "Build a small image for this Python app. Choose one base image and put the lines in order. The image must be under 400 MB, answer on port 8000, and rebuild fast.", + app: { runtime: "python", manifest: "requirements.txt", defaultPort: 8000, start: ["python app.py"] }, + pieces: [ + piece("from-full", "FROM python:3.12"), piece("pip", "RUN pip install -r requirements.txt"), piece("expose", "EXPOSE 8000"), piece("from-ubuntu", "FROM ubuntu:22.04"), + piece("cp-src", "COPY . ."), piece("from-slim", "FROM python:3.12-slim"), piece("cmd", 'CMD ["python", "app.py"]'), piece("cp-req", "COPY requirements.txt ./"), piece("workdir", "WORKDIR /app"), + ], + goals: [ + { kind: "builds", label: "The image builds" }, + { kind: "reachable", port: 8000, label: "The app answers on port 8000" }, + { kind: "size", maxMb: 400, label: "The image is under 400 MB" }, + { kind: "rebuild", maxSec: 10, label: "A rebuild takes 10 seconds or less" }, + ], + par: 7, + hints: ["Use only one FROM. python:3.12 is the full image (about 1 GB). ubuntu has no Python at all.", "python:3.12-slim has Python and is small. Copy requirements.txt, install, then copy the code.", "Order: FROM python:3.12-slim, WORKDIR, COPY requirements.txt, RUN pip install, COPY . ., EXPOSE 8000, CMD."], + solution: ["from-slim", "workdir", "cp-req", "pip", "cp-src", "expose", "cmd"], +}; + +const buildPortEnv: BuildRound = { + id: "docker-build-port-env", mode: "build", difficulty: "easy", kind: "dockerfile", + title: "Set the port and the start command", + brief: "The platform sends traffic to port 8080. This Node app listens on the port in the PORT variable (3000 if it is not set). Choose the lines so the app answers on 8080.", + app: { ...NODE_APP, portEnv: "PORT", start: ["node server.js"] }, + pieces: [ + piece("env-3000", "ENV PORT=3000"), piece("cp-pkg", "COPY package*.json ./"), piece("cmd-dev", 'CMD ["npm", "run", "dev"]'), piece("expose-3000", "EXPOSE 3000"), + piece("from", "FROM node:20-slim"), piece("npm-ci", "RUN npm ci"), piece("env-8080", "ENV PORT=8080"), piece("workdir", "WORKDIR /app"), + piece("cmd-node", 'CMD ["node", "server.js"]'), piece("expose-8080", "EXPOSE 8080"), piece("cp-src", "COPY . ."), + ], + goals: [ + { kind: "builds", label: "The image builds" }, + { kind: "reachable", port: 8080, label: "The app answers on port 8080" }, + ], + par: 8, + hints: ["The app listens on the port in PORT, and EXPOSE must name that same port. Use 8080 for both.", "npm run dev needs dev tools that are not installed in a production image. Start the server with node.", "FROM, WORKDIR, COPY package*.json, RUN npm ci, COPY . ., ENV PORT=8080, EXPOSE 8080, CMD node server.js."], + solution: ["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "env-8080", "expose-8080", "cmd-node"], +}; + +const buildPythonService: BuildRound = { + id: "docker-build-python-service", mode: "build", difficulty: "medium", kind: "dockerfile", + title: "A small Python service on port 9000", + brief: "This Python service listens on the port in the PORT variable (5000 if it is not set). Build a small image (under 250 MB) that answers on port 9000 and rebuilds fast after a code change.", + app: { runtime: "python", manifest: "requirements.txt", defaultPort: 5000, portEnv: "PORT", start: ["python app.py"] }, + pieces: [ + piece("expose-5000", "EXPOSE 5000"), piece("from-full", "FROM python:3.12"), piece("cp-src", "COPY . ."), piece("env-9000", "ENV PORT=9000"), + piece("pip", "RUN pip install --no-cache-dir -r requirements.txt"), piece("cmd-flask", 'CMD ["flask", "run"]'), piece("from-slim", "FROM python:3.12-slim"), + piece("expose-9000", "EXPOSE 9000"), piece("workdir", "WORKDIR /srv"), piece("cp-req", "COPY requirements.txt ./"), piece("cmd", 'CMD ["python", "app.py"]'), + ], + goals: [ + { kind: "builds", label: "The image builds" }, + { kind: "reachable", port: 9000, label: "The service answers on port 9000" }, + { kind: "size", maxMb: 250, label: "The image is under 250 MB" }, + { kind: "rebuild", maxSec: 10, label: "A rebuild after a code change takes 10 seconds or less" }, + ], + par: 8, + hints: ["python:3.12 is about 1 GB. The slim variant is far smaller. Use one FROM only.", "The service reads PORT, so set ENV PORT=9000 and EXPOSE 9000. Copy requirements.txt and install before you copy the code.", "FROM python:3.12-slim, WORKDIR, COPY requirements.txt, RUN pip install, COPY . ., ENV PORT=9000, EXPOSE 9000, CMD python app.py."], + solution: ["from-slim", "workdir", "cp-req", "pip", "cp-src", "env-9000", "expose-9000", "cmd"], +}; + +function slotPiece(slot: string, id: string, text: string, facts: ComposeFact[] = []): BuildPiece { + return { id, slot, text, facts }; +} + +const basicSlots: BuildSlot[] = [ + { id: "web-port", label: "web: published port", indent: 4 }, + { id: "web-env", label: "web: database host", indent: 4 }, + { id: "web-dep", label: "web: start order", indent: 4 }, + { id: "db-env", label: "db: settings", indent: 4 }, + { id: "db-vol", label: "db: where the data lives", indent: 4 }, + { id: "top-vol", label: "named volumes", indent: 0 }, +]; +const basicSkeleton: ComposeLine[] = [ + { text: "services:" }, { text: " web:" }, { text: " image: shop/web:2.0" }, { slot: "web-port" }, { slot: "web-env" }, { slot: "web-dep" }, + { text: " db:" }, { text: " image: postgres:16" }, { slot: "db-env" }, { slot: "db-vol" }, { slot: "top-vol" }, +]; + +const buildComposeBasic: BuildRound = { + id: "docker-build-compose-basic", mode: "build", difficulty: "medium", kind: "compose", + title: "Wire the web app to its database", + brief: "Fill the blanks of this compose file. web listens on port 3000 inside its container and must answer on localhost:8080. It reaches the database by the name db, so db must start first. The database data must survive on the named volume pgdata.", + slots: basicSlots, skeleton: basicSkeleton, + pieces: [ + slotPiece("web-port", "wp-ok", 'ports: ["8080:3000"]', [{ service: "web", key: "port", value: "8080:3000" }]), + slotPiece("web-port", "wp-same", 'ports: ["8080:8080"]', [{ service: "web", key: "port", value: "8080:8080" }]), + slotPiece("web-port", "wp-swap", 'ports: ["3000:8080"]', [{ service: "web", key: "port", value: "3000:8080" }]), + slotPiece("web-env", "we-localhost", "environment: [DB_HOST=localhost]", [{ service: "web", key: "env", value: "DB_HOST=localhost" }]), + slotPiece("web-env", "we-db", "environment: [DB_HOST=db]", [{ service: "web", key: "env", value: "DB_HOST=db" }]), + slotPiece("web-env", "we-postgres", "environment: [DB_HOST=postgres]", [{ service: "web", key: "env", value: "DB_HOST=postgres" }]), + slotPiece("web-dep", "wd-cache", "depends_on: [cache]", [{ service: "web", key: "depends", value: "cache" }]), + slotPiece("web-dep", "wd-db", "depends_on: [db]", [{ service: "web", key: "depends", value: "db" }]), + slotPiece("web-dep", "wd-restart", "restart: always"), + slotPiece("db-env", "de-db", "environment: [POSTGRES_DB=shop]", [{ service: "db", key: "env", value: "POSTGRES_DB=shop" }]), + slotPiece("db-env", "de-empty", "environment: [POSTGRES_PASSWORD=]", [{ service: "db", key: "env", value: "POSTGRES_PASSWORD=" }]), + slotPiece("db-env", "de-ok", "environment: [POSTGRES_PASSWORD=secret]", [{ service: "db", key: "env", value: "POSTGRES_PASSWORD=secret" }]), + slotPiece("db-vol", "dv-data", 'volumes: ["pgdata:/data"]', [{ service: "db", key: "volume", value: "pgdata:/data" }]), + slotPiece("db-vol", "dv-ok", 'volumes: ["pgdata:/var/lib/postgresql/data"]', [{ service: "db", key: "volume", value: "pgdata:/var/lib/postgresql/data" }]), + slotPiece("db-vol", "dv-bind", 'volumes: ["./pg:/tmp/pg"]', [{ service: "db", key: "volume", value: "./pg:/tmp/pg" }]), + slotPiece("top-vol", "tv-none", "# no named volumes"), + slotPiece("top-vol", "tv-data", "volumes: { data: {} }", [{ service: "", key: "decl-volume", value: "data" }]), + slotPiece("top-vol", "tv-pgdata", "volumes: { pgdata: {} }", [{ service: "", key: "decl-volume", value: "pgdata" }]), + ], + stack: { + services: { + web: { image: "shop/web:2.0", sizeMb: 212, port: 3000, hostEnv: { key: "DB_HOST", value: "db" }, mustDependOn: ["db"], mustReach: ["db"] }, + db: { image: "postgres:16", sizeMb: 432, port: 5432, requiredEnv: ["POSTGRES_PASSWORD"], dataPath: "/var/lib/postgresql/data" }, + }, + publish: { service: "web", host: 8080 }, + }, + goals: [ + { kind: "builds", label: "The compose file is valid" }, + { kind: "runs", label: "Both services start and stay up" }, + { kind: "reachable", port: 8080, label: "localhost:8080 answers" }, + { kind: "persists", label: "The database data is on a volume" }, + ], + par: 6, + hints: ["The port line is HOST:CONTAINER. web listens on 3000 inside, so the right side must be 3000.", "Inside a compose project, services find each other by service name: DB_HOST=db. depends_on makes db start first. Postgres needs a non-empty POSTGRES_PASSWORD.", "Mount pgdata at /var/lib/postgresql/data, and declare pgdata under the top level volumes."], + solution: ["web-port:wp-ok", "web-env:we-db", "web-dep:wd-db", "db-env:de-ok", "db-vol:dv-ok", "top-vol:tv-pgdata"], +}; + +const tierSlots: BuildSlot[] = [ + { id: "web-port", label: "web: published port", indent: 4 }, + { id: "web-net", label: "web: networks", indent: 4 }, + { id: "api-env", label: "api: database host", indent: 4 }, + { id: "api-net", label: "api: networks", indent: 4 }, + { id: "db-env", label: "db: settings", indent: 4 }, + { id: "db-vol", label: "db: where the data lives", indent: 4 }, + { id: "db-net", label: "db: networks", indent: 4 }, + { id: "top-net", label: "networks", indent: 0 }, + { id: "top-vol", label: "named volumes", indent: 0 }, +]; +const tierSkeleton: ComposeLine[] = [ + { text: "services:" }, + { text: " web:" }, { text: " image: nginx:1.25-alpine" }, { text: " depends_on: [api]" }, { slot: "web-port" }, { slot: "web-net" }, + { text: " api:" }, { text: " image: shop/api:1.2" }, { text: " depends_on: [db]" }, { slot: "api-env" }, { slot: "api-net" }, + { text: " db:" }, { text: " image: postgres:16" }, { slot: "db-env" }, { slot: "db-vol" }, { slot: "db-net" }, + { slot: "top-net" }, { slot: "top-vol" }, +]; + +const net = (slot: string, id: string, service: string, nets: string[]) => + slotPiece(slot, id, `networks: [${nets.join(", ")}]`, nets.map((n) => ({ service, key: "network" as const, value: n }))); + +const buildComposeTiers: BuildRound = { + id: "docker-build-compose-tiers", mode: "build", difficulty: "hard", kind: "compose", + title: "Three tiers on two networks", + brief: "Wire web, api and db. web must reach api, api must reach db, but web must not reach db directly: use the networks front and back. web answers on localhost:8080 (nginx listens on port 80). api reaches the database by the name db. The data stays on the volume pgdata.", + slots: tierSlots, skeleton: tierSkeleton, + fixed: [{ service: "web", key: "depends", value: "api" }, { service: "api", key: "depends", value: "db" }], + pieces: [ + slotPiece("web-port", "wp-ok", 'ports: ["8080:80"]', [{ service: "web", key: "port", value: "8080:80" }]), + slotPiece("web-port", "wp-same", 'ports: ["8080:8080"]', [{ service: "web", key: "port", value: "8080:8080" }]), + slotPiece("web-port", "wp-swap", 'ports: ["80:8080"]', [{ service: "web", key: "port", value: "80:8080" }]), + net("web-net", "wn-both", "web", ["front", "back"]), net("web-net", "wn-front", "web", ["front"]), net("web-net", "wn-back", "web", ["back"]), + slotPiece("api-env", "ae-local", "environment: [DB_HOST=localhost]", [{ service: "api", key: "env", value: "DB_HOST=localhost" }]), + slotPiece("api-env", "ae-db", "environment: [DB_HOST=db]", [{ service: "api", key: "env", value: "DB_HOST=db" }]), + slotPiece("api-env", "ae-pg", "environment: [DB_HOST=postgres]", [{ service: "api", key: "env", value: "DB_HOST=postgres" }]), + net("api-net", "an-front", "api", ["front"]), net("api-net", "an-back", "api", ["back"]), net("api-net", "an-both", "api", ["front", "back"]), + slotPiece("db-env", "de-ok", "environment: [POSTGRES_PASSWORD=secret]", [{ service: "db", key: "env", value: "POSTGRES_PASSWORD=secret" }]), + slotPiece("db-env", "de-user", "environment: [POSTGRES_USER=shop]", [{ service: "db", key: "env", value: "POSTGRES_USER=shop" }]), + slotPiece("db-env", "de-empty", "environment: [POSTGRES_PASSWORD=]", [{ service: "db", key: "env", value: "POSTGRES_PASSWORD=" }]), + slotPiece("db-vol", "dv-ok", 'volumes: ["pgdata:/var/lib/postgresql/data"]', [{ service: "db", key: "volume", value: "pgdata:/var/lib/postgresql/data" }]), + slotPiece("db-vol", "dv-tmp", 'volumes: ["pgdata:/tmp"]', [{ service: "db", key: "volume", value: "pgdata:/tmp" }]), + slotPiece("db-vol", "dv-bind", 'volumes: ["./pg:/var/lib/postgresql/data"]', [{ service: "db", key: "volume", value: "./pg:/var/lib/postgresql/data" }]), + net("db-net", "dn-front", "db", ["front"]), net("db-net", "dn-both", "db", ["front", "back"]), net("db-net", "dn-back", "db", ["back"]), + slotPiece("top-net", "tn-front", "networks: { front: {} }", [{ service: "", key: "decl-network", value: "front" }]), + slotPiece("top-net", "tn-both", "networks: { front: {}, back: {} }", [{ service: "", key: "decl-network", value: "front" }, { service: "", key: "decl-network", value: "back" }]), + slotPiece("top-net", "tn-back", "networks: { back: {} }", [{ service: "", key: "decl-network", value: "back" }]), + slotPiece("top-vol", "tv-pgdata", "volumes: { pgdata: {} }", [{ service: "", key: "decl-volume", value: "pgdata" }]), + slotPiece("top-vol", "tv-data", "volumes: { data: {} }", [{ service: "", key: "decl-volume", value: "data" }]), + slotPiece("top-vol", "tv-none", "# no named volumes"), + ], + stack: { + services: { + web: { image: "nginx:1.25-alpine", sizeMb: 43, port: 80, mustReach: ["api"] }, + api: { image: "shop/api:1.2", sizeMb: 164, port: 4000, hostEnv: { key: "DB_HOST", value: "db" }, mustReach: ["db"], mustDependOn: ["db"] }, + db: { image: "postgres:16", sizeMb: 432, port: 5432, requiredEnv: ["POSTGRES_PASSWORD"], dataPath: "/var/lib/postgresql/data" }, + }, + publish: { service: "web", host: 8080 }, + isolate: ["web", "db"], + }, + goals: [ + { kind: "builds", label: "The compose file is valid" }, + { kind: "runs", label: "All three services start and stay up" }, + { kind: "reachable", port: 8080, label: "localhost:8080 answers" }, + { kind: "isolated", label: "web cannot reach db directly" }, + { kind: "persists", label: "The database data is on a volume" }, + ], + par: 9, + hints: ["Networks: web needs front (to reach api), db needs back, and api sits on both so it can talk to each side. Declare every network you use at the top level.", "The port line is HOST:CONTAINER. nginx listens on 80 inside. api reaches the database as DB_HOST=db, not localhost.", "web: 8080:80, front. api: DB_HOST=db, front and back. db: POSTGRES_PASSWORD=secret, pgdata at /var/lib/postgresql/data, back. Declare front, back and pgdata."], + solution: ["web-port:wp-ok", "web-net:wn-front", "api-env:ae-db", "api-net:an-both", "db-env:de-ok", "db-vol:dv-ok", "db-net:dn-back", "top-net:tn-both", "top-vol:tv-pgdata"], +}; + +/** Every round of the game. Easy leans to build, medium and hard to fix. */ +export const POOL: readonly DockerRound[] = [ + buildNodeOrder, buildSlim, buildPortEnv, startStopped, wrongPort, + missingEnv, portTaken, lostData, noNetwork, buildComposeBasic, buildPythonService, + oomLoop, newRelease, diskFull, composeConflict, buildComposeTiers, +]; diff --git a/server/src/shared/games/index.ts b/server/src/shared/games/index.ts new file mode 100644 index 00000000..673d6b68 --- /dev/null +++ b/server/src/shared/games/index.ts @@ -0,0 +1,18 @@ +import type { AnyGameEngine, GameId } from "./types.js"; +import { sysdesignEngine } from "./sysdesign/engine.js"; +import { linuxEngine } from "./linux/engine.js"; +import { dockerEngine } from "./docker/engine.js"; + +export * from "./types.js"; +export * from "./daily.js"; + +/** Every daily game, by id. The server verifies submissions and the browser plays with these. */ +export const GAME_ENGINES: Record = { + sysdesign: sysdesignEngine as unknown as AnyGameEngine, + linux: linuxEngine as unknown as AnyGameEngine, + docker: dockerEngine as unknown as AnyGameEngine, +}; + +export function engineFor(game: GameId): AnyGameEngine { + return GAME_ENGINES[game]; +} diff --git a/server/src/shared/games/linux/commands.ts b/server/src/shared/games/linux/commands.ts new file mode 100644 index 00000000..3afd2653 --- /dev/null +++ b/server/src/shared/games/linux/commands.ts @@ -0,0 +1,1641 @@ +// The commands of the practice shell. Each one is a small pure function of the shell state. They +// follow the real tools closely enough that what a player learns here works on a real server. +import { + BLOCK, DAY, ERR_TEXT, baseName, can, diskUsage, dirName, formatTime, humanSize, joinPath, modeString, normalizePath, sizeOf, + type Err, type VNode, +} from "./fs.js"; +import { compilePatterns, globMatch, spend, type Matcher } from "./regex.js"; +import type { Cmd, Ctx, Proc } from "./model.js"; + +const cmp = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0); + +export function toLines(text: string): string[] { + if (text === "") return []; + const parts = text.split("\n"); + if (parts[parts.length - 1] === "") parts.pop(); + return parts; +} +const fromLines = (lines: string[]): string => (lines.length ? lines.join("\n") + "\n" : ""); + +// ---------------------------------------------------------------- helpers + +type OptSpec = { bool?: string; val?: string; long?: Record; numeric?: boolean; stop?: boolean }; +type Opts = { f: Set; v: Map; rest: string[]; num: string | null }; + +function parseOpts(c: Ctx, name: string, spec: OptSpec): Opts | null { + const o: Opts = { f: new Set(), v: new Map(), rest: [], num: null }; + const bool = spec.bool ?? ""; + const val = spec.val ?? ""; + const args = c.args; + const bad = (msg: string): null => { + c.err(`${name}: ${msg}`); + c.err(`Try 'man ${name}' to see how it works.`); + return null; + }; + const addVal = (k: string, v: string) => o.v.set(k, [...(o.v.get(k) ?? []), v]); + let done = false; + for (let i = 0; i < args.length; i++) { + const a = args[i]!; + if (done || a === "-" || !a.startsWith("-")) { + o.rest.push(a); + if (spec.stop) done = true; + continue; + } + if (a === "--") { + done = true; + continue; + } + if (a.startsWith("--")) { + const eq = a.indexOf("="); + const long = eq < 0 ? a.slice(2) : a.slice(2, eq); + const letter = spec.long?.[long]; + if (!letter) return bad(`unrecognized option '--${long}'`); + if (val.includes(letter)) { + if (eq >= 0) addVal(letter, a.slice(eq + 1)); + else if (i + 1 < args.length) addVal(letter, args[++i]!); + else return bad(`option '--${long}' requires an argument`); + } else o.f.add(letter); + continue; + } + for (let j = 1; j < a.length; j++) { + const ch = a[j]!; + if (bool.includes(ch)) o.f.add(ch); + else if (val.includes(ch)) { + const rest = a.slice(j + 1); + if (rest) addVal(ch, rest); + else if (i + 1 < args.length) addVal(ch, args[++i]!); + else return bad(`option requires an argument -- '${ch}'`); + break; + } else if (spec.numeric && ch >= "0" && ch <= "9") { + o.num = (o.num ?? "") + ch; + } else return bad(`invalid option -- '${ch}'`); + } + } + return o; +} + +function absOf(c: Ctx, path: string): string { + return normalizePath(c.st.cwd, path, c.st.env.HOME ?? "/"); +} + +/** Read a file for a command, printing the usual error when it cannot be read. */ +function readText(c: Ctx, name: string, path: string): string | null { + const res = c.st.fs.walk(absOf(c, path), c.st.user); + if (!res.node) { + c.err(`${name}: ${path}: ${ERR_TEXT[res.err ?? "ENOENT"]}`); + return null; + } + if (res.node.kind === "dir") { + c.err(`${name}: ${path}: Is a directory`); + return null; + } + if (!can(c.st.user, res.node, 4)) { + c.err(`${name}: ${path}: Permission denied`); + return null; + } + return res.node.content; +} + +/** Inputs for a filter command: the named files, or standard input. */ +function inputs(c: Ctx, name: string, files: string[]): Array<{ name: string; text: string }> | null { + if (files.length === 0) { + if (c.stdin === null) { + c.err(`${name}: no input. Give a file name or use a pipe, like: cat file | ${name}`); + return null; + } + return [{ name: "-", text: c.stdin }]; + } + const out: Array<{ name: string; text: string }> = []; + let ok = true; + for (const f of files) { + if (f === "-" && c.stdin !== null) { + out.push({ name: "-", text: c.stdin }); + continue; + } + const text = readText(c, name, f); + if (text === null) ok = false; + else out.push({ name: f, text }); + } + return ok || out.length > 0 ? out : null; +} + +const childList = (node: VNode): VNode[] => [...node.children.values()].sort((a, b) => cmp(a.name, b.name)); +const isHidden = (name: string) => name.startsWith("."); +const nlink = (n: VNode) => (n.kind === "dir" ? 2 + [...n.children.values()].filter((x) => x.kind === "dir").length : 1); + +// ---------------------------------------------------------------- navigation and listing + +const pwd: Cmd = (c) => { + c.out(c.st.cwd + "\n"); + return 0; +}; + +const cd: Cmd = (c) => { + if (c.args.length > 1) { + c.err("bash: cd: too many arguments"); + return 1; + } + let target = c.args[0] ?? c.st.env.HOME ?? "/"; + let show = false; + if (target === "-") { + target = c.st.oldpwd; + show = true; + } + const abs = absOf(c, target); + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + c.err(`bash: cd: ${c.args[0] ?? target}: ${ERR_TEXT[res.err ?? "ENOENT"]}`); + return 1; + } + if (res.node.kind !== "dir") { + c.err(`bash: cd: ${c.args[0]}: Not a directory`); + return 1; + } + if (!can(c.st.user, res.node, 1)) { + c.err(`bash: cd: ${c.args[0]}: Permission denied`); + return 1; + } + c.st.oldpwd = c.st.cwd; + c.st.cwd = abs; + c.st.env.PWD = abs; + c.st.env.OLDPWD = c.st.oldpwd; + if (show) c.out(abs + "\n"); + return 0; +}; + +type Ent = { name: string; node: VNode }; + +const ls: Cmd = (c) => { + const o = parseOpts(c, "ls", { + bool: "lahARSrtd1", + long: { all: "a", "almost-all": "A", "human-readable": "h", recursive: "R", reverse: "r", directory: "d" }, + }); + if (!o) return 2; + const long = o.f.has("l"); + const human = o.f.has("h"); + const now = c.st.fs.now; + let code = 0; + + const sortEnts = (ents: Ent[]) => { + ents.sort((a, b) => { + if (o.f.has("S")) return sizeOf(b.node) - sizeOf(a.node) || cmp(a.name, b.name); + if (o.f.has("t")) return b.node.mtime - a.node.mtime || cmp(a.name, b.name); + return cmp(a.name, b.name); + }); + if (o.f.has("r")) ents.reverse(); + }; + + const render = (ents: Ent[], withTotal: boolean): string => { + if (!long) { + if (c.tty && !o.f.has("1")) return ents.length ? ents.map((e) => e.name).join(" ") + "\n" : ""; + return ents.map((e) => e.name + "\n").join(""); + } + const size = (n: VNode) => (human ? humanSize(sizeOf(n)) : String(sizeOf(n))); + const rows = ents.map((e) => [modeString(e.node), String(nlink(e.node)), e.node.owner, e.node.group, size(e.node), formatTime(e.node.mtime, now), e.name]); + const w = [1, 2, 3, 4].map((k) => Math.max(0, ...rows.map((r) => r[k]!.length))); + let text = ""; + if (withTotal) { + const kb = ents.reduce((sum, e) => sum + (e.node.kind === "dir" ? 4 : Math.ceil(sizeOf(e.node) / BLOCK) * 4), 0); + text += `total ${human ? humanSize(kb * 1024) : kb}\n`; + } + for (const r of rows) text += `${r[0]} ${r[1]!.padStart(w[0]!)} ${r[2]!.padEnd(w[1]!)} ${r[3]!.padEnd(w[2]!)} ${r[4]!.padStart(w[3]!)} ${r[5]} ${r[6]}\n`; + return text; + }; + + const sections: string[] = []; + const listDir = (display: string, node: VNode, abs: string, header: boolean) => { + if (!can(c.st.user, node, 4)) { + c.err(`ls: cannot open directory '${display}': Permission denied`); + code = 2; + return; + } + let ents: Ent[] = [...node.children.values()].map((n) => ({ name: n.name, node: n })); + if (!o.f.has("a") && !o.f.has("A")) ents = ents.filter((e) => !isHidden(e.name)); + if (o.f.has("a")) { + const parent = c.st.fs.peek(dirName(abs)) ?? node; + ents.push({ name: ".", node }, { name: "..", node: parent }); + } + sortEnts(ents); + sections.push((header ? `${display}:\n` : "") + render(ents, true)); + if (o.f.has("R")) { + for (const child of childList(node)) { + if (child.kind === "dir" && (!isHidden(child.name) || o.f.has("a") || o.f.has("A"))) { + listDir(display === "/" ? "/" + child.name : `${display}/${child.name}`, child, joinPath(abs, child.name), true); + } + } + } + }; + + const files: Ent[] = []; + const dirs: Array<{ display: string; node: VNode; abs: string }> = []; + for (const t of o.rest.length ? o.rest : ["."]) { + const abs = absOf(c, t); + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + c.err(`ls: cannot access '${t}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 2; + } else if (res.node.kind === "dir" && !o.f.has("d")) dirs.push({ display: t, node: res.node, abs }); + else files.push({ name: t, node: res.node }); + } + if (files.length) { + sortEnts(files); + sections.push(render(files, false)); + } + const header = dirs.length + files.length > 1 || o.f.has("R"); + dirs.sort((a, b) => cmp(a.display, b.display)); + for (const d of dirs) listDir(d.display, d.node, d.abs, header && (dirs.length > 1 || files.length > 0 || o.f.has("R"))); + c.out(sections.join("\n")); + return code; +}; + +// ---------------------------------------------------------------- reading files + +const cat: Cmd = (c) => { + const o = parseOpts(c, "cat", { bool: "nAbs", long: { number: "n" } }); + if (!o) return 1; + const parts = inputs(c, "cat", o.rest); + if (!parts) return 1; + let code = o.rest.length > parts.length ? 1 : 0; + let n = 0; + for (const p of parts) { + if (o.f.has("n")) { + const lines = toLines(p.text); + c.out(lines.map((l) => `${String(++n).padStart(6)}\t${l}\n`).join("")); + } else c.out(p.text); + } + if (parts.length === 0) code = 1; + return code; +}; + +function headTail(c: Ctx, name: "head" | "tail"): number { + const o = parseOpts(c, name, { bool: "qvf", val: "nc", numeric: true, long: { lines: "n", bytes: "c" } }); + if (!o) return 1; + const raw = o.v.get("n")?.[0] ?? o.num ?? "10"; + const bytes = o.v.get("c")?.[0]; + if (!/^[+-]?\d+$/.test(bytes ?? raw)) { + c.err(`${name}: invalid number of ${bytes !== undefined ? "bytes" : "lines"}: '${bytes ?? raw}'`); + return 1; + } + const parts = inputs(c, name, o.rest); + if (!parts) return 1; + const headers = parts.length > 1 && !o.f.has("q"); + parts.forEach((p, i) => { + if (headers) c.out(`${i ? "\n" : ""}==> ${p.name === "-" ? "standard input" : p.name} <==\n`); + if (bytes !== undefined) { + const n = Math.abs(Number(bytes)); + c.out(name === "head" ? p.text.slice(0, n) : n === 0 ? "" : p.text.slice(-n)); + return; + } + const lines = toLines(p.text); + const n = Math.abs(Number(raw)); + if (name === "head") c.out(fromLines(raw.startsWith("-") ? lines.slice(0, Math.max(0, lines.length - n)) : lines.slice(0, n))); + else c.out(fromLines(raw.startsWith("+") ? lines.slice(Math.max(0, n - 1)) : n === 0 ? [] : lines.slice(-n))); + }); + return 0; +} + +// ---------------------------------------------------------------- searching + + +function grepCmd(c: Ctx, forceRecursive: boolean): number { + const o = parseOpts(c, "grep", { + bool: "ivnchrREFlowxqsHaIT", + val: "e", + long: { + "ignore-case": "i", "invert-match": "v", "line-number": "n", count: "c", recursive: "r", "dereference-recursive": "R", + "extended-regexp": "E", "fixed-strings": "F", "files-with-matches": "l", "only-matching": "o", "word-regexp": "w", + "line-regexp": "x", "no-filename": "h", "with-filename": "H", quiet: "q", silent: "q", "no-messages": "s", regexp: "e", + }, + }); + if (!o) return 2; + const rest = [...o.rest]; + let patterns = (o.v.get("e") ?? []).flatMap((p) => p.split("\n")); + if (patterns.length === 0) { + const p = rest.shift(); + if (p === undefined) { + c.err("Usage: grep [OPTION]... PATTERNS [FILE]..."); + return 2; + } + patterns = p.split("\n"); + } + const recursive = forceRecursive || o.f.has("r") || o.f.has("R"); + const matcher = compilePatterns(patterns, { + ere: o.f.has("E"), ignoreCase: o.f.has("i"), fixed: o.f.has("F"), word: o.f.has("w"), line: o.f.has("x"), + }); + if ("error" in matcher) { + c.err(`grep: ${matcher.error}`); + return 2; + } + const invert = o.f.has("v"); + const count = o.f.has("c"); + const listFiles = o.f.has("l"); + const quiet = o.f.has("q"); + const only = o.f.has("o"); + let files = rest; + let useStdin = false; + if (files.length === 0) { + if (recursive) files = ["."]; + else useStdin = true; + } + const showName = o.f.has("H") || (!o.f.has("h") && (files.length > 1 || recursive)); + const dotFree = recursive && rest.length === 0; + let matchedAny = false; + let errored = false; + + const scan = (label: string, text: string): void => { + let hits = 0; + const lines = toLines(text); + const prefix = (n: number) => (showName ? label + ":" : "") + (o.f.has("n") ? n + ":" : ""); + for (let i = 0; i < lines.length; i++) { + const line = lines[i]!; + spend(1); + const m = (matcher as Matcher).test(line); + if (m === invert) continue; + hits++; + matchedAny = true; + if (quiet) return; + if (listFiles) break; + if (count) continue; + if (only && !invert) { + let from = 0; + while (from <= line.length) { + const r = (matcher as Matcher).find(line, from); + if (!r) break; + if (r[1] > r[0]) c.out(prefix(i + 1) + line.slice(r[0], r[1]) + "\n"); + from = r[1] > r[0] ? r[1] : r[1] + 1; + } + } else c.out(prefix(i + 1) + line + "\n"); + } + if (listFiles && hits > 0) c.out(label + "\n"); + else if (count) c.out((showName ? label + ":" : "") + hits + "\n"); + }; + + const walkFiles = (abs: string, display: string, node: VNode): void => { + if (node.kind === "file") { + if (!can(c.st.user, node, 4)) { + if (!o.f.has("s")) c.err(`grep: ${display}: Permission denied`); + errored = true; + return; + } + scan(display, node.content); + return; + } + if (!recursive) { + if (!o.f.has("s")) c.err(`grep: ${display}: Is a directory`); + errored = true; + return; + } + if (!can(c.st.user, node, 4) || !can(c.st.user, node, 1)) { + if (!o.f.has("s")) c.err(`grep: ${display}: Permission denied`); + errored = true; + return; + } + for (const child of childList(node)) { + walkFiles(joinPath(abs, child.name), display === "." && dotFree ? child.name : display === "/" ? "/" + child.name : `${display}/${child.name}`, child); + } + }; + + if (useStdin) { + if (c.stdin === null) { + c.err("grep: no input. Give a file name or use a pipe, like: cat file | grep word"); + return 2; + } + scan("(standard input)", c.stdin); + } else { + for (const f of files) { + const abs = absOf(c, f); + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + if (!o.f.has("s")) c.err(`grep: ${f}: ${ERR_TEXT[res.err ?? "ENOENT"]}`); + errored = true; + continue; + } + walkFiles(abs, f, res.node); + } + } + return matchedAny ? 0 : errored ? 2 : 1; +} + +class FindError extends Error {} + +type FindItem = { node: VNode; abs: string; display: string; depth: number }; + +const find: Cmd = (c) => { + const args = c.args; + let i = 0; + const starts: string[] = []; + while (i < args.length && !args[i]!.startsWith("-") && args[i] !== "!" && args[i] !== "(") starts.push(args[i++]!); + if (starts.length === 0) starts.push("."); + const tokens = args.slice(i); + let maxDepth = Infinity; + let minDepth = 0; + let hasAction = false; + let hasDelete = false; + let code = 0; + const now = c.st.fs.now; + let p = 0; + + const need = (name: string): string => { + const v = tokens[p++]; + if (v === undefined) throw new FindError(`missing argument to '${name}'`); + return v; + }; + + const orExpr = (): ((f: FindItem) => boolean) => { + let left = andExpr(); + while (tokens[p] === "-o" || tokens[p] === "-or") { + p++; + const l = left; + const r = andExpr(); + left = (f) => l(f) || r(f); + } + return left; + }; + const andExpr = (): ((f: FindItem) => boolean) => { + let left = unary(); + while (p < tokens.length && tokens[p] !== "-o" && tokens[p] !== "-or" && tokens[p] !== ")") { + if (tokens[p] === "-a" || tokens[p] === "-and") p++; + const l = left; + const r = unary(); + left = (f) => l(f) && r(f); + } + return left; + }; + const unary = (): ((f: FindItem) => boolean) => { + const t = tokens[p]; + if (t === "!" || t === "-not") { + p++; + const inner = unary(); + return (f) => !inner(f); + } + if (t === "(") { + p++; + const inner = orExpr(); + if (tokens[p] !== ")") throw new FindError("missing closing ')'"); + p++; + return inner; + } + return primary(); + }; + + const numTest = (spec: string, value: number): boolean => { + const m = /^([+-]?)(\d+)$/.exec(spec); + if (!m) throw new FindError(`invalid argument '${spec}'`); + const n = Number(m[2]); + return m[1] === "+" ? value > n : m[1] === "-" ? value < n : value === n; + }; + + const primary = (): ((f: FindItem) => boolean) => { + const t = tokens[p++]; + switch (t) { + case "-name": { const pat = need(t); return (f) => globMatch(pat, baseName(f.display) || f.display); } + case "-iname": { const pat = need(t); return (f) => globMatch(pat, baseName(f.display) || f.display, true); } + case "-path": { const pat = need(t); return (f) => globMatch(pat, f.display); } + case "-type": { + const k = need(t); + if (k !== "f" && k !== "d") throw new FindError(`Unknown argument to -type: ${k}`); + return (f) => (k === "f" ? f.node.kind === "file" : f.node.kind === "dir"); + } + case "-size": { + const spec = need(t); + const m = /^([+-]?)(\d+)([cwbkMG]?)$/.exec(spec); + if (!m) throw new FindError(`invalid argument '${spec}' to '-size'`); + const unit = { c: 1, w: 2, b: 512, "": 512, k: 1024, M: 1048576, G: 1073741824 }[m[3] as "c"]!; + const n = Number(m[2]); + return (f) => { + const units = Math.ceil(sizeOf(f.node) / unit); + return m[1] === "+" ? units > n : m[1] === "-" ? units < n : units === n; + }; + } + case "-mtime": { const spec = need(t); numTest(spec, 0); return (f) => numTest(spec, Math.floor((now - f.node.mtime) / DAY)); } + case "-mmin": { const spec = need(t); numTest(spec, 0); return (f) => numTest(spec, Math.floor((now - f.node.mtime) / 60)); } + case "-user": { const u = need(t); return (f) => f.node.owner === u; } + case "-empty": return (f) => (f.node.kind === "dir" ? f.node.children.size === 0 : sizeOf(f.node) === 0); + case "-maxdepth": { maxDepth = Number(need(t)); if (!Number.isFinite(maxDepth) || maxDepth < 0) throw new FindError("Expected a positive decimal integer argument to -maxdepth"); return () => true; } + case "-mindepth": { minDepth = Number(need(t)); if (!Number.isFinite(minDepth) || minDepth < 0) throw new FindError("Expected a positive decimal integer argument to -mindepth"); return () => true; } + case "-print": hasAction = true; return (f) => (c.out(f.display + "\n"), true); + case "-delete": { + hasAction = true; + hasDelete = true; + return (f) => { + if (f.node.kind === "dir" && f.node.children.size > 0) { + c.err(`find: cannot delete '${f.display}': Directory not empty`); + code = 1; + return false; + } + const e = c.st.fs.remove(f.abs, c.st.user); + if (e) { + c.err(`find: cannot delete '${f.display}': ${ERR_TEXT[e]}`); + code = 1; + return false; + } + return true; + }; + } + case "-exec": { + hasAction = true; + const argv: string[] = []; + for (;;) { + const a = tokens[p++]; + if (a === undefined) throw new FindError("missing argument to '-exec'"); + if (a === ";" || a === "+") break; + argv.push(a); + } + if (argv.length === 0) throw new FindError("missing argument to '-exec'"); + return (f) => { + const r = c.exec(argv.map((a) => a.split("{}").join(f.display)), null); + c.out(r.out); + return r.code === 0; + }; + } + default: + throw new FindError(`unknown predicate '${t}'`); + } + }; + + let expr: (f: FindItem) => boolean; + try { + expr = tokens.length ? orExpr() : () => true; + if (p < tokens.length) throw new FindError(`paths must precede expression: '${tokens[p]}'`); + } catch (error) { + if (error instanceof FindError) { + c.err(`find: ${error.message}`); + return 1; + } + throw error; + } + const finalExpr = hasAction ? expr : (f: FindItem) => (expr(f) ? (c.out(f.display + "\n"), true) : false); + + const visit = (item: FindItem): void => { + spend(1); + const { node } = item; + const inDepth = item.depth >= minDepth; + if (!hasDelete && inDepth) finalExpr(item); + if (node.kind === "dir" && item.depth < maxDepth) { + if (!can(c.st.user, node, 4) || !can(c.st.user, node, 1)) { + c.err(`find: '${item.display}': Permission denied`); + code = 1; + } else { + for (const child of childList(node)) { + visit({ + node: child, + abs: joinPath(item.abs, child.name), + display: item.display.endsWith("/") ? item.display + child.name : item.display + "/" + child.name, + depth: item.depth + 1, + }); + } + } + } + if (hasDelete && inDepth) finalExpr(item); + }; + + for (const s of starts) { + const abs = absOf(c, s); + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + c.err(`find: '${s}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + visit({ node: res.node, abs, display: s, depth: 0 }); + } + return code; +}; + +// ---------------------------------------------------------------- text filters + +function wc(c: Ctx): number { + const o = parseOpts(c, "wc", { bool: "lwcm", long: { lines: "l", words: "w", bytes: "c", chars: "m" } }); + if (!o) return 1; + const parts = inputs(c, "wc", o.rest); + if (!parts) return 1; + let showL = o.f.has("l"); + let showW = o.f.has("w"); + let showC = o.f.has("c") || o.f.has("m"); + if (!showL && !showW && !showC) showL = showW = showC = true; + const rows = parts.map((p) => ({ + name: p.name === "-" && o.rest.length === 0 ? "" : p.name, + l: (p.text.match(/\n/g) ?? []).length, + w: p.text.split(/\s+/).filter(Boolean).length, + c: p.text.length, + })); + if (rows.length > 1) rows.push({ name: "total", l: rows.reduce((a, r) => a + r.l, 0), w: rows.reduce((a, r) => a + r.w, 0), c: rows.reduce((a, r) => a + r.c, 0) }); + const shown = [showL, showW, showC].filter(Boolean).length; + const width = shown === 1 && rows.length === 1 ? 0 : o.rest.length === 0 ? 7 : Math.max(...rows.map((r) => String(r.c).length)); + for (const r of rows) { + const cols: string[] = []; + if (showL) cols.push(String(r.l).padStart(width)); + if (showW) cols.push(String(r.w).padStart(width)); + if (showC) cols.push(String(r.c).padStart(width)); + c.out(cols.join(" ") + (r.name ? " " + r.name : "") + "\n"); + } + return 0; +} + +function numberOf(text: string): number { + const m = /^\s*([+-]?\d*\.?\d+)/.exec(text); + return m ? Number(m[1]) : 0; +} + +function humanNumber(text: string): number { + const m = /^\s*(\d*\.?\d+)\s*([KMGT]?)/i.exec(text); + if (!m) return 0; + return Number(m[1]) * ({ "": 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3, T: 1024 ** 4 }[m[2]!.toUpperCase() as ""] ?? 1); +} + +function sort(c: Ctx): number { + const o = parseOpts(c, "sort", { bool: "rnuhfsb", val: "kt", long: { reverse: "r", "numeric-sort": "n", unique: "u", "human-numeric-sort": "h", "ignore-case": "f" } }); + if (!o) return 2; + const parts = inputs(c, "sort", o.rest); + if (!parts) return 2; + const lines = parts.flatMap((p) => toLines(p.text)); + const sep = o.v.get("t")?.[0]; + const keySpec = o.v.get("k")?.[0]; + let km: RegExpExecArray | null = null; + if (keySpec !== undefined) { + km = /^(\d+)(?:\.\d+)?[bnrhf]*(?:,(\d+)(?:\.\d+)?)?([bnrhf]*)$/.exec(keySpec); + if (!km) { + c.err(`sort: invalid field specification '${keySpec}'`); + return 2; + } + } + const mods = (km ? keySpec!.replace(/[\d.,]/g, "") : "") + ""; + const numeric = o.f.has("n") || mods.includes("n"); + const human = o.f.has("h") || mods.includes("h"); + const fold = o.f.has("f") || mods.includes("f"); + const keyOf = (line: string): string => { + if (!km) return line; + const fields = sep ? line.split(sep) : line.trim().split(/\s+/); + const from = Number(km[1]) - 1; + const to = km[2] ? Number(km[2]) : from + 1; + return fields.slice(from, to).join(sep ?? " "); + }; + const keyed = lines.map((line) => ({ line, key: keyOf(line) })); + keyed.sort((a, b) => { + let r = 0; + if (human) r = humanNumber(a.key) - humanNumber(b.key); + else if (numeric) r = numberOf(a.key) - numberOf(b.key); + else r = fold ? cmp(a.key.toLowerCase(), b.key.toLowerCase()) : cmp(a.key, b.key); + if (r === 0 && !o.f.has("s")) r = cmp(a.line, b.line); + return o.f.has("r") || mods.includes("r") ? -r : r; + }); + let out = keyed.map((k) => k.line); + if (o.f.has("u")) out = out.filter((l, i) => i === 0 || l !== out[i - 1]); + c.out(fromLines(out)); + return 0; +} + +function uniq(c: Ctx): number { + const o = parseOpts(c, "uniq", { bool: "cduiD", long: { count: "c", repeated: "d", unique: "u", "ignore-case": "i" } }); + if (!o) return 1; + const parts = inputs(c, "uniq", o.rest.slice(0, 1)); + if (!parts) return 1; + const lines = toLines(parts[0]!.text); + const same = (a: string, b: string) => (o.f.has("i") ? a.toLowerCase() === b.toLowerCase() : a === b); + const groups: Array<{ line: string; n: number }> = []; + for (const line of lines) { + const last = groups[groups.length - 1]; + if (last && same(last.line, line)) last.n++; + else groups.push({ line, n: 1 }); + } + for (const g of groups) { + if (o.f.has("d") && g.n < 2) continue; + if (o.f.has("u") && g.n > 1) continue; + c.out((o.f.has("c") ? String(g.n).padStart(7) + " " : "") + g.line + "\n"); + } + return 0; +} + +function parseRanges(spec: string): Array<[number, number]> | null { + const out: Array<[number, number]> = []; + for (const part of spec.split(",")) { + const m = /^(\d*)(-?)(\d*)$/.exec(part); + if (!m || part === "" || part === "-") return null; + const a = m[1] === "" ? 1 : Number(m[1]); + const b = m[2] === "" ? a : m[3] === "" ? Infinity : Number(m[3]); + if (a < 1) return null; + out.push([a, b]); + } + return out; +} + +function cut(c: Ctx): number { + const o = parseOpts(c, "cut", { bool: "s", val: "dfc", long: { delimiter: "d", fields: "f", characters: "c", "only-delimited": "s" } }); + if (!o) return 1; + const fSpec = o.v.get("f")?.[0]; + const cSpec = o.v.get("c")?.[0]; + if (fSpec === undefined && cSpec === undefined) { + c.err("cut: you must specify a list of bytes, characters, or fields"); + return 1; + } + const ranges = parseRanges((fSpec ?? cSpec)!); + if (!ranges) { + c.err("cut: invalid field range"); + return 1; + } + const delim = o.v.get("d")?.[0] ?? "\t"; + if (delim.length !== 1) { + c.err("cut: the delimiter must be a single character"); + return 1; + } + const parts = inputs(c, "cut", o.rest); + if (!parts) return 1; + const pick = (idx: number) => ranges.some(([a, b]) => idx >= a && idx <= b); + for (const p of parts) { + for (const line of toLines(p.text)) { + if (fSpec === undefined) c.out([...line].filter((_, i) => pick(i + 1)).join("") + "\n"); + else if (!line.includes(delim)) { + if (!o.f.has("s")) c.out(line + "\n"); + } else c.out(line.split(delim).filter((_, i) => pick(i + 1)).join(delim) + "\n"); + } + } + return 0; +} + +function awk(c: Ctx): number { + const o = parseOpts(c, "awk", { val: "F", stop: false }); + if (!o) return 1; + const prog = o.rest[0]; + const m = prog === undefined ? null : /^\s*\{\s*print\b([\s\S]*)\}\s*$/.exec(prog); + if (!m) { + c.err("awk: this practice shell only runs programs like '{print $1}' or '{print $1, $3}'"); + return 1; + } + // The print list: items separated by commas (a space between them) or written side by side. + const items: Array<{ kind: "field"; n: number | "NF" } | { kind: "nr" } | { kind: "nf" } | { kind: "str"; v: string } | { kind: "comma" }> = []; + const src = m[1]!.trim(); + const re = /\$(\d+|NF)|"((?:[^"\\]|\\.)*)"|\bNR\b|\bNF\b|(,)/g; + let last = 0; + let mm: RegExpExecArray | null; + while ((mm = re.exec(src))) { + if (src.slice(last, mm.index).trim() !== "") { + c.err("awk: this practice shell only runs programs like '{print $1}' or '{print $1, $3}'"); + return 1; + } + last = re.lastIndex; + if (mm[1] !== undefined) items.push({ kind: "field", n: mm[1] === "NF" ? "NF" : Number(mm[1]) }); + else if (mm[2] !== undefined) items.push({ kind: "str", v: mm[2].replace(/\\n/g, "\n").replace(/\\t/g, "\t").replace(/\\(.)/g, "$1") }); + else if (mm[3] !== undefined) items.push({ kind: "comma" }); + else items.push(mm[0] === "NR" ? { kind: "nr" } : { kind: "nf" }); + } + if (src.slice(last).trim() !== "") { + c.err("awk: this practice shell only runs programs like '{print $1}' or '{print $1, $3}'"); + return 1; + } + const sep = o.v.get("F")?.[0]; + const parts = inputs(c, "awk", o.rest.slice(1)); + if (!parts) return 1; + let nr = 0; + for (const p of parts) { + for (const line of toLines(p.text)) { + nr++; + const fields = sep === undefined || sep === " " ? line.trim().split(/\s+/).filter(Boolean) : line.split(sep.length === 1 ? sep : new RegExp(sep.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))); + const field = (n: number | "NF") => (n === "NF" ? fields[fields.length - 1] ?? "" : n === 0 ? line : fields[n - 1] ?? ""); + if (items.length === 0) { + c.out(line + "\n"); + continue; + } + let outLine = ""; + for (const it of items) { + if (it.kind === "comma") outLine += " "; + else if (it.kind === "field") outLine += field(it.n); + else if (it.kind === "str") outLine += it.v; + else if (it.kind === "nr") outLine += nr; + else outLine += fields.length; + } + c.out(outLine + "\n"); + } + } + return 0; +} + +type SedCmd = { from?: number; to?: number; re?: Matcher; kind: "s" | "d" | "p"; sub?: { m: Matcher; repl: string; global: boolean } }; + +function sed(c: Ctx): number { + const o = parseOpts(c, "sed", { bool: "inErE", val: "e", long: { quiet: "n", silent: "n", "in-place": "i", "regexp-extended": "E" } }); + if (!o) return 1; + const rest = [...o.rest]; + const scripts = o.v.get("e") ?? []; + if (scripts.length === 0) { + const s = rest.shift(); + if (s === undefined) { + c.err("Usage: sed [OPTION]... {script} [input-file]..."); + return 1; + } + scripts.push(s); + } + const ere = o.f.has("E") || o.f.has("r"); + const cmds: SedCmd[] = []; + const bad = (msg: string): number => { + c.err(`sed: ${msg}`); + return 1; + }; + for (const script of scripts.flatMap((s) => s.split("\n"))) { + const text = script.trim(); + if (!text) continue; + let i = 0; + const cmd: SedCmd = { kind: "p" }; + const num = /^(\d+)(?:,(\d+))?/.exec(text); + if (num) { + cmd.from = Number(num[1]); + cmd.to = num[2] ? Number(num[2]) : cmd.from; + i = num[0].length; + } else if (text[0] === "/") { + const end = text.indexOf("/", 1); + if (end < 0) return bad("unterminated address regex"); + const m = compilePatterns([text.slice(1, end)], { ere, ignoreCase: false }); + if ("error" in m) return bad(m.error); + cmd.re = m; + i = end + 1; + } + const k = text[i]; + if (k === "d" || k === "p") { + cmd.kind = k; + cmds.push(cmd); + } else if (k === "s") { + const delim = text[i + 1]; + if (!delim) return bad("unterminated `s' command"); + const fields: string[] = []; + let cur = ""; + let j = i + 2; + for (; j < text.length && fields.length < 2; j++) { + const ch = text[j]!; + if (ch === "\\" && j + 1 < text.length) { + if (text[j + 1] === delim) cur += delim; + else cur += ch + text[j + 1]; + j++; + } else if (ch === delim) { + fields.push(cur); + cur = ""; + } else cur += ch; + } + if (fields.length < 2) return bad("unterminated `s' command"); + const flags = text.slice(j); + const m = compilePatterns([fields[0]!], { ere, ignoreCase: flags.includes("i") }); + if ("error" in m) return bad(m.error); + cmd.kind = "s"; + cmd.sub = { m, repl: fields[1]!, global: flags.includes("g") }; + cmds.push(cmd); + } else return bad(`unknown command: '${k ?? ""}' (this practice shell knows s, d and p)`); + } + const apply = (text: string): string => { + let n = 0; + const out: string[] = []; + for (let line of toLines(text)) { + n++; + let deleted = false; + let printed = false; + for (const cm of cmds) { + const hit = cm.from !== undefined ? n >= cm.from && n <= (cm.to ?? cm.from) : cm.re ? cm.re.test(line) : true; + if (!hit) continue; + if (cm.kind === "d") { + deleted = true; + break; + } + if (cm.kind === "p") { + out.push(line); + printed = true; + } else if (cm.sub) { + let result = ""; + let pos = 0; + let from = 0; + for (;;) { + spend(1); + const r = cm.sub.m.find(line, from); + if (!r) break; + result += line.slice(pos, r[0]) + cm.sub.repl.replace(/\\(.)|&/g, (all, esc?: string) => (all === "&" ? line.slice(r[0], r[1]) : esc === "n" ? "\n" : esc ?? "")); + pos = r[1]; + from = r[1] > r[0] ? r[1] : r[1] + 1; + if (r[1] === r[0] && r[0] < line.length) { + result += line[r[0]]; + pos = r[0] + 1; + } + if (!cm.sub.global || from > line.length) break; + } + line = result + line.slice(pos); + } + } + if (!deleted && !o.f.has("n")) out.push(line); + void printed; + } + return fromLines(out); + }; + if (o.f.has("i")) { + if (rest.length === 0) return bad("no input files"); + let code = 0; + for (const f of rest) { + const text = readText(c, "sed", f); + if (text === null) { + code = 1; + continue; + } + const e = c.st.fs.writeFile(absOf(c, f), c.st.user, apply(text), false); + if (e) { + c.err(`sed: couldn't open temporary file for '${f}': ${ERR_TEXT[e]}`); + code = 1; + } + } + return code; + } + const parts = inputs(c, "sed", rest); + if (!parts) return 1; + for (const p of parts) c.out(apply(p.text)); + return 0; +} + +// ---------------------------------------------------------------- changing files + +function echo(c: Ctx): number { + let args = c.args; + let newline = true; + let escapes = false; + while (args[0] && /^-[neE]+$/.test(args[0])) { + if (args[0].includes("n")) newline = false; + if (args[0].includes("e")) escapes = true; + if (args[0].includes("E")) escapes = false; + args = args.slice(1); + } + let text = args.join(" "); + if (escapes) text = text.replace(/\\(n|t|\\)/g, (_, k: string) => (k === "n" ? "\n" : k === "t" ? "\t" : "\\")); + c.out(text + (newline ? "\n" : "")); + return 0; +} + +function touch(c: Ctx): number { + const o = parseOpts(c, "touch", { bool: "c" }); + if (!o) return 1; + if (o.rest.length === 0) { + c.err("touch: missing file operand"); + return 1; + } + let code = 0; + for (const f of o.rest) { + const abs = absOf(c, f); + const res = c.st.fs.walk(abs, c.st.user); + if (res.node) { + if (!can(c.st.user, res.node, 2) && res.node.owner !== c.st.user.name) { + c.err(`touch: cannot touch '${f}': Permission denied`); + code = 1; + } else res.node.mtime = c.st.fs.now; + continue; + } + if (o.f.has("c")) continue; + const e = res.err === "ENOENT" ? c.st.fs.writeFile(abs, c.st.user, "", false) : res.err; + if (e) { + c.err(`touch: cannot touch '${f}': ${ERR_TEXT[e]}`); + code = 1; + } + } + return code; +} + +function mkdir(c: Ctx): number { + const o = parseOpts(c, "mkdir", { bool: "pv", long: { parents: "p" } }); + if (!o) return 1; + if (o.rest.length === 0) { + c.err("mkdir: missing operand"); + return 1; + } + let code = 0; + for (const f of o.rest) { + const abs = absOf(c, f); + if (o.f.has("p")) { + let cur = ""; + let failed: Err | null = null; + for (const part of abs.split("/").filter(Boolean)) { + cur += "/" + part; + const res = c.st.fs.walk(cur, c.st.user); + if (res.node) { + if (res.node.kind !== "dir") failed = "ENOTDIR"; + continue; + } + if (res.err !== "ENOENT") { + failed = res.err; + break; + } + failed = c.st.fs.mkdir(cur, c.st.user); + if (failed) break; + } + if (failed) { + c.err(`mkdir: cannot create directory '${f}': ${ERR_TEXT[failed]}`); + code = 1; + } + continue; + } + const e = c.st.fs.mkdir(abs, c.st.user); + if (e) { + c.err(`mkdir: cannot create directory '${f}': ${ERR_TEXT[e]}`); + code = 1; + } + } + return code; +} + +function rm(c: Ctx): number { + const o = parseOpts(c, "rm", { bool: "rRfvid", long: { recursive: "r", force: "f", verbose: "v" } }); + if (!o) return 1; + if (o.rest.length === 0) { + if (!o.f.has("f")) c.err("rm: missing operand"); + return o.f.has("f") ? 0 : 1; + } + const recursive = o.f.has("r") || o.f.has("R"); + let code = 0; + for (const f of o.rest) { + const abs = absOf(c, f); + if (baseName(f) === "." || baseName(f) === "..") { + c.err(`rm: refusing to remove '.' or '..' directory: skipping '${f}'`); + code = 1; + continue; + } + if (abs === "/") { + c.err("rm: it is dangerous to operate recursively on '/'"); + c.err("rm: use --no-preserve-root to override this failsafe"); + code = 1; + continue; + } + const res = c.st.fs.walk(abs, c.st.user); + if (!res.node) { + if (!(o.f.has("f") && res.err === "ENOENT")) { + c.err(`rm: cannot remove '${f}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + } + continue; + } + if (res.node.kind === "dir" && !recursive) { + c.err(`rm: cannot remove '${f}': Is a directory`); + code = 1; + continue; + } + const e = c.st.fs.remove(abs, c.st.user); + if (e) { + if (!o.f.has("f")) c.err(`rm: cannot remove '${f}': ${ERR_TEXT[e]}`); + code = 1; + } else if (o.f.has("v")) c.out(`removed '${f}'\n`); + if (!e && (abs === c.st.cwd || c.st.cwd.startsWith(abs + "/"))) c.st.cwd = dirName(abs); + } + return code; +} + +/** For cp and mv: where does each source go? */ +function destinations(c: Ctx, name: string, srcs: string[], dest: string): Array<{ src: string; target: string; display: string }> | null { + const dabs = absOf(c, dest); + const res = c.st.fs.walk(dabs, c.st.user); + const isDir = !!res.node && res.node.kind === "dir"; + if (srcs.length > 1 && !isDir) { + c.err(`${name}: target '${dest}' is not a directory`); + return null; + } + return srcs.map((s) => { + const sabs = absOf(c, s); + return isDir + ? { src: s, target: joinPath(dabs, baseName(sabs)), display: dest.endsWith("/") ? dest + baseName(sabs) : dest + "/" + baseName(sabs) } + : { src: s, target: dabs, display: dest }; + }); +} + +function cp(c: Ctx): number { + const o = parseOpts(c, "cp", { bool: "rRapfvin", long: { recursive: "r", verbose: "v", archive: "a" } }); + if (!o) return 1; + if (o.rest.length < 2) { + c.err(o.rest.length === 0 ? "cp: missing file operand" : `cp: missing destination file operand after '${o.rest[0]}'`); + return 1; + } + const dest = o.rest[o.rest.length - 1]!; + const dests = destinations(c, "cp", o.rest.slice(0, -1), dest); + if (!dests) return 1; + const recursive = o.f.has("r") || o.f.has("R") || o.f.has("a"); + let code = 0; + for (const d of dests) { + const sabs = absOf(c, d.src); + const res = c.st.fs.walk(sabs, c.st.user); + if (!res.node) { + c.err(`cp: cannot stat '${d.src}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + if (res.node.kind === "dir" && !recursive) { + c.err(`cp: -r not specified; omitting directory '${d.src}'`); + code = 1; + continue; + } + if (sabs === d.target) { + c.err(`cp: '${d.src}' and '${d.display}' are the same file`); + code = 1; + continue; + } + if (res.node.kind === "dir" && d.target.startsWith(sabs + "/")) { + c.err(`cp: cannot copy a directory, '${d.src}', into itself, '${d.display}'`); + code = 1; + continue; + } + if (res.node.kind === "file" && !can(c.st.user, res.node, 4)) { + c.err(`cp: cannot open '${d.src}' for reading: Permission denied`); + code = 1; + continue; + } + const e = c.st.fs.copy(res.node, d.target, c.st.user); + if (e) { + const what = res.node.kind === "dir" ? "directory" : "regular file"; + c.err(e === "EISDIR" ? `cp: cannot overwrite directory '${d.display}' with non-directory` : `cp: cannot create ${what} '${d.display}': ${ERR_TEXT[e]}`); + code = 1; + } else if (o.f.has("v")) c.out(`'${d.src}' -> '${d.display}'\n`); + } + return code; +} + +function mv(c: Ctx): number { + const o = parseOpts(c, "mv", { bool: "fvin", long: { verbose: "v", force: "f" } }); + if (!o) return 1; + if (o.rest.length < 2) { + c.err(o.rest.length === 0 ? "mv: missing file operand" : `mv: missing destination file operand after '${o.rest[0]}'`); + return 1; + } + const dest = o.rest[o.rest.length - 1]!; + const dests = destinations(c, "mv", o.rest.slice(0, -1), dest); + if (!dests) return 1; + let code = 0; + for (const d of dests) { + const sabs = absOf(c, d.src); + const res = c.st.fs.walk(sabs, c.st.user); + if (!res.node) { + c.err(`mv: cannot stat '${d.src}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + if (sabs === d.target) { + c.err(`mv: '${d.src}' and '${d.display}' are the same file`); + code = 1; + continue; + } + const e = c.st.fs.move(sabs, d.target, c.st.user); + if (e) { + c.err( + e === "EINVAL" + ? `mv: cannot move '${d.src}' to a subdirectory of itself, '${d.display}'` + : e === "EEXIST" + ? `mv: cannot move '${d.src}' to '${d.display}': Directory not empty` + : `mv: cannot move '${d.src}' to '${d.display}': ${ERR_TEXT[e]}`, + ); + code = 1; + } else if (o.f.has("v")) c.out(`renamed '${d.src}' -> '${d.display}'\n`); + if (!e && (sabs === c.st.cwd || c.st.cwd.startsWith(sabs + "/"))) c.st.cwd = dirName(sabs); + } + return code; +} + +function applyMode(spec: string, node: VNode): number | null { + if (/^[0-7]{1,4}$/.test(spec)) return parseInt(spec, 8) & 0o777; + let mode = node.mode; + for (const clause of spec.split(",")) { + const m = /^([ugoa]*)([-+=])([rwxXst]*)$/.exec(clause); + if (!m) return null; + const who = m[1] === "" ? "a" : m[1]!; + let bits = 0; + for (const ch of m[3]!) bits |= ch === "r" ? 4 : ch === "w" ? 2 : ch === "x" ? 1 : ch === "X" && (node.kind === "dir" || (node.mode & 0o111) !== 0) ? 1 : 0; + let mask = 0; + for (const w of who.includes("a") ? "ugo" : who) mask |= (bits << (w === "u" ? 6 : w === "g" ? 3 : 0)); + const clear = (who.includes("a") ? 0o777 : [...who].reduce((a, w) => a | (7 << (w === "u" ? 6 : w === "g" ? 3 : 0)), 0)); + if (m[2] === "+") mode |= mask; + else if (m[2] === "-") mode &= ~mask; + else mode = (mode & ~clear) | mask; + } + return mode & 0o777; +} + +function chmod(c: Ctx): number { + // A mode such as "-x" looks like an option, so take the mode out first. + const args = c.args.filter((a) => a !== "-R" && a !== "-v" && a !== "--recursive"); + const recursive = args.length !== c.args.length && c.args.some((a) => a === "-R" || a === "--recursive"); + if (args.length === 0) { + c.err("chmod: missing operand"); + return 1; + } + const mode = args[0]!; + const files = args.slice(1); + if (files.length === 0) { + c.err(`chmod: missing operand after '${mode}'`); + return 1; + } + let code = 0; + const setNode = (node: VNode, display: string): boolean => { + const next = applyMode(mode, node); + if (next === null) { + c.err(`chmod: invalid mode: '${mode}'`); + c.err("Try 'man chmod' to see how it works."); + return false; + } + if (c.st.user.name !== "root" && node.owner !== c.st.user.name) { + c.err(`chmod: changing permissions of '${display}': Operation not permitted`); + code = 1; + return true; + } + node.mode = next; + return true; + }; + const walk = (node: VNode, display: string): boolean => { + if (!setNode(node, display)) return false; + if (recursive && node.kind === "dir") for (const ch of childList(node)) if (!walk(ch, `${display}/${ch.name}`)) return false; + return true; + }; + for (const f of files) { + const res = c.st.fs.walk(absOf(c, f), c.st.user); + if (!res.node) { + c.err(`chmod: cannot access '${f}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + if (!walk(res.node, f)) return 1; + } + return code; +} + +function chown(c: Ctx): number { + const o = parseOpts(c, "chown", { bool: "R" }); + if (!o) return 1; + if (o.rest.length < 2) { + c.err(o.rest.length ? `chown: missing operand after '${o.rest[0]}'` : "chown: missing operand"); + return 1; + } + const [who, ...files] = o.rest as [string, ...string[]]; + const [owner, group] = who.split(":"); + let code = 0; + for (const f of files) { + const res = c.st.fs.walk(absOf(c, f), c.st.user); + if (!res.node) { + c.err(`chown: cannot access '${f}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + const allowed = c.st.user.name === "root" || (res.node.owner === c.st.user.name && (!owner || owner === c.st.user.name)); + if (!allowed) { + c.err(`chown: changing ownership of '${f}': Operation not permitted`); + code = 1; + continue; + } + if (owner) res.node.owner = owner; + if (group) res.node.group = group; + } + return code; +} + +// ---------------------------------------------------------------- disk + +function du(c: Ctx): number { + const o = parseOpts(c, "du", { bool: "shak", val: "d", long: { summarize: "s", "human-readable": "h", all: "a", "max-depth": "d" } }); + if (!o) return 1; + const maxDepth = o.f.has("s") ? 0 : o.v.get("d") ? Number(o.v.get("d")![0]) : Infinity; + if (Number.isNaN(maxDepth)) { + c.err(`du: invalid maximum depth '${o.v.get("d")![0]}'`); + return 1; + } + const fmt = (n: number) => (o.f.has("h") ? humanSize(n) : String(Math.ceil(n / 1024))); + let code = 0; + const walk = (node: VNode, display: string, depth: number): number => { + spend(1); + if (node.kind === "file") { + const size = diskUsage(node); + if (depth === 0 || (o.f.has("a") && depth <= maxDepth)) c.out(`${fmt(size)}\t${display}\n`); + return size; + } + if (!can(c.st.user, node, 4) || !can(c.st.user, node, 1)) { + c.err(`du: cannot read directory '${display}': Permission denied`); + code = 1; + if (depth <= maxDepth) c.out(`${fmt(BLOCK)}\t${display}\n`); + return BLOCK; + } + let total = BLOCK; + for (const child of childList(node)) total += walk(child, display.endsWith("/") ? display + child.name : display + "/" + child.name, depth + 1); + if (depth <= maxDepth) c.out(`${fmt(total)}\t${display}\n`); + return total; + }; + for (const t of o.rest.length ? o.rest : ["."]) { + const res = c.st.fs.walk(absOf(c, t), c.st.user); + if (!res.node) { + c.err(`du: cannot access '${t}': ${ERR_TEXT[res.err ?? "ENOENT"]}`); + code = 1; + continue; + } + walk(res.node, t, 0); + } + return code; +} + +function df(c: Ctx): number { + const rows: string[][] = [["Filesystem", "Size", "Used", "Avail", "Use%", "Mounted on"], ...c.st.df.map((r) => [...r])]; + const w = [0, 1, 2, 3, 4].map((k) => Math.max(...rows.map((r) => r[k]!.length))); + for (const r of rows) c.out(`${r[0]!.padEnd(w[0]!)} ${r[1]!.padStart(w[1]!)} ${r[2]!.padStart(w[2]!)} ${r[3]!.padStart(w[3]!)} ${r[4]!.padStart(w[4]!)} ${r[5]}\n`); + return 0; +} + +// ---------------------------------------------------------------- processes + +function psLine(p: Proc): string { + return `${p.user.padEnd(10)} ${String(p.pid).padStart(6)} ${p.cpu.toFixed(1).padStart(4)} ${p.mem.toFixed(1).padStart(4)} ${String(p.vsz).padStart(7)} ${String(p.rss).padStart(6)} ${(p.tty ?? "?").padEnd(8)} ${p.stat.padEnd(4)} ${p.start.padEnd(5)} ${p.time.padStart(6)} ${p.command}`; +} + +function ps(c: Ctx): number { + const all = c.args.some((a) => /^-?[a-zA-Z]*[aeA][a-zA-Z]*x?$/.test(a) && a !== "-"); + if (all || c.args.length > 0) { + c.out(`${"USER".padEnd(10)} ${"PID".padStart(6)} ${"%CPU".padStart(4)} ${"%MEM".padStart(4)} ${"VSZ".padStart(7)} ${"RSS".padStart(6)} ${"TTY".padEnd(8)} ${"STAT".padEnd(4)} ${"START".padEnd(5)} ${"TIME".padStart(6)} COMMAND\n`); + for (const p of [...c.st.procs].sort((a, b) => a.pid - b.pid)) c.out(psLine(p) + "\n"); + return 0; + } + c.out(" PID TTY TIME CMD\n"); + for (const p of c.st.procs.filter((x) => x.user === c.st.user.name && x.tty).sort((a, b) => a.pid - b.pid)) { + c.out(`${String(p.pid).padStart(7)} ${(p.tty ?? "?").padEnd(8)} ${p.time.padStart(8)} ${baseName(p.command.split(" ")[0]!.replace(/^-/, ""))}\n`); + } + return 0; +} + +const SIGNALS: Record = { HUP: 1, INT: 2, QUIT: 3, KILL: 9, USR1: 10, USR2: 12, TERM: 15, CONT: 18, STOP: 19 }; + +function signalNumber(spec: string): number | null { + if (/^\d+$/.test(spec)) return Number(spec); + const name = spec.replace(/^SIG/, "").toUpperCase(); + return SIGNALS[name] ?? null; +} + +function deliver(c: Ctx, proc: Proc, sig: number): boolean { + if (sig === 0 || sig === 18 || sig === 19) return true; + if (proc.ignoresTerm && sig !== 9) return true; + c.st.procs = c.st.procs.filter((p) => p.pid !== proc.pid); + return true; +} + +function kill(c: Ctx): number { + let sig = 15; + const args = [...c.args]; + if (args[0] === "-s" || args[0] === "-n") { + const s = signalNumber(args[1] ?? ""); + if (s === null) { + c.err(`bash: kill: ${args[1] ?? ""}: invalid signal specification`); + return 1; + } + sig = s; + args.splice(0, 2); + } else if (args[0] && /^-[A-Za-z0-9]+$/.test(args[0])) { + const s = signalNumber(args[0].slice(1)); + if (s === null) { + c.err(`bash: kill: ${args[0]}: invalid signal specification`); + return 1; + } + sig = s; + args.shift(); + } + if (args.length === 0) { + c.err("kill: usage: kill [-s sigspec | -n signum | -sigspec] pid | jobspec ... or kill -l [sigspec]"); + return 2; + } + let code = 0; + for (const a of args) { + if (!/^\d+$/.test(a)) { + c.err(`bash: kill: ${a}: arguments must be process or job IDs`); + code = 1; + continue; + } + const proc = c.st.procs.find((p) => p.pid === Number(a)); + if (!proc) { + c.err(`bash: kill: (${a}) - No such process`); + code = 1; + } else if (proc.user !== c.st.user.name && c.st.user.name !== "root") { + c.err(`bash: kill: (${a}) - Operation not permitted`); + code = 1; + } else deliver(c, proc, sig); + } + return code; +} + +const procName = (p: Proc, full: boolean): string => (full ? p.command : baseName(p.command.split(" ")[0]!.replace(/^-/, ""))); + +function pgrepFamily(c: Ctx, which: "pgrep" | "pkill" | "killall"): number { + const o = parseOpts(c, which, { bool: "lfx", val: "s", numeric: which !== "pgrep" }); + // pkill -9 name: the digits are the signal. + if (!o) return 2; + const sig = o.num !== null ? Number(o.num) : 15; + const name = o.rest[0]; + if (name === undefined) { + c.err(`${which}: no matching criteria specified`); + return 2; + } + const full = o.f.has("f"); + const hits = c.st.procs.filter((p) => (o.f.has("x") ? procName(p, full) === name : procName(p, full).includes(name))).sort((a, b) => a.pid - b.pid); + if (hits.length === 0) { + if (which === "killall") c.err(`${name}: no process found`); + return 1; + } + if (which === "pgrep") { + for (const p of hits) c.out(o.f.has("l") ? `${p.pid} ${procName(p, false)}\n` : `${p.pid}\n`); + return 0; + } + let code = 0; + for (const p of hits) { + if (p.user !== c.st.user.name && c.st.user.name !== "root") { + c.err(`${which}: killing pid ${p.pid} failed: Operation not permitted`); + code = 1; + } else deliver(c, p, sig); + } + return code; +} + +// ---------------------------------------------------------------- small commands + +const KNOWN_IDS: Record = { root: 0, ops: 1000, dev: 1001, alice: 1002, bob: 1003, carol: 1004, deploy: 1005 }; + +function id(c: Ctx): number { + const u = c.st.user; + const num = (n: string) => KNOWN_IDS[n] ?? 1500; + c.out(`uid=${num(u.name)}(${u.name}) gid=${num(u.groups[0] ?? u.name)}(${u.groups[0] ?? u.name}) groups=${u.groups.map((g) => `${num(g)}(${g})`).join(",")}\n`); + return 0; +} + +function tee(c: Ctx): number { + const o = parseOpts(c, "tee", { bool: "a" }); + if (!o) return 1; + const text = c.stdin ?? ""; + let code = 0; + for (const f of o.rest) { + const e = c.st.fs.writeFile(absOf(c, f), c.st.user, text, o.f.has("a")); + if (e) { + c.err(`tee: ${f}: ${ERR_TEXT[e]}`); + code = 1; + } + } + c.out(text); + return code; +} + +function xargs(c: Ctx): number { + const o = parseOpts(c, "xargs", { stop: true }); + if (!o) return 1; + const items = (c.stdin ?? "").split(/\s+/).filter(Boolean).slice(0, 500); + const base = o.rest.length ? o.rest : ["echo"]; + if (items.length === 0) return 0; + const r = c.exec([...base, ...items], null); + c.out(r.out); + return r.code === 0 ? 0 : 123; +} + +function exportCmd(c: Ctx): number { + for (const a of c.args) { + const m = /^([A-Za-z_][A-Za-z0-9_]*)(?:=([\s\S]*))?$/.exec(a); + if (!m) { + c.err(`bash: export: \`${a}': not a valid identifier`); + return 1; + } + if (m[2] !== undefined) c.st.env[m[1]!] = m[2]; + } + return 0; +} + +function env(c: Ctx): number { + for (const k of Object.keys(c.st.env).sort()) c.out(`${k}=${c.st.env[k]}\n`); + return 0; +} + +const DATE_DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]; +const DATE_MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]; + +function date(c: Ctx): number { + const d = new Date(c.st.fs.now * 1000); + const p = (n: number) => String(n).padStart(2, "0"); + c.out(`${DATE_DAYS[d.getUTCDay()]} ${DATE_MONTHS[d.getUTCMonth()]} ${String(d.getUTCDate()).padStart(2, " ")} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())} UTC ${d.getUTCFullYear()}\n`); + return 0; +} + +export const COMMANDS: Record = { + pwd, + cd, + ls, + cat, + less: cat, + more: cat, + head: (c) => headTail(c, "head"), + tail: (c) => headTail(c, "tail"), + grep: (c) => grepCmd(c, false), + egrep: (c) => grepCmd({ ...c, args: ["-E", ...c.args] }, false), + find, + wc, + sort, + uniq, + cut, + awk, + sed, + echo, + touch, + mkdir, + rm, + cp, + mv, + chmod, + chown, + du, + df, + ps, + kill, + pgrep: (c) => pgrepFamily(c, "pgrep"), + pkill: (c) => pgrepFamily(c, "pkill"), + killall: (c) => pgrepFamily(c, "killall"), + whoami: (c) => (c.out(c.st.user.name + "\n"), 0), + id, + hostname: (c) => (c.out(c.st.hostname + "\n"), 0), + uname: (c) => (c.out(c.args.includes("-a") ? `Linux ${c.st.hostname} 6.1.0-18-amd64 #1 SMP Debian 6.1.76-1 x86_64 GNU/Linux\n` : "Linux\n"), 0), + date, + tee, + xargs, + export: exportCmd, + env, + printenv: env, + true: () => 0, + false: () => 1, + sleep: () => 0, + which: (c) => { + let code = 0; + for (const a of c.args) { + if (a in COMMANDS && !["cd", "export"].includes(a)) c.out(`/usr/bin/${a}\n`); + else code = 1; + } + return c.args.length ? code : 1; + }, + sudo: (c) => (c.err(`${c.st.user.name} is not in the sudoers file. Ask the admin, or fix it as your own user.`), 1), + su: (c) => (c.err("su: Authentication failure"), 1), +}; + +/** Real commands a learner may try that this practice server does not have. */ +export const NOT_HERE: Record = { + vi: "Edit files with echo and the > and >> redirects, or sed -i.", + vim: "Edit files with echo and the > and >> redirects, or sed -i.", + nano: "Edit files with echo and the > and >> redirects, or sed -i.", + top: "Use ps aux to see the processes.", + htop: "Use ps aux to see the processes.", + ssh: "This practice server has no network.", + curl: "This practice server has no network.", + wget: "This practice server has no network.", + ping: "This practice server has no network.", + apt: "You cannot install software here.", + "apt-get": "You cannot install software here.", + systemctl: "There is no service manager here.", + docker: "There is no Docker here. Try the Docker game.", + python: "Only the commands in 'help' work.", + python3: "Only the commands in 'help' work.", + node: "Only the commands in 'help' work.", + ln: "Links are not part of this game.", + tar: "Archives are not part of this game.", + zip: "Archives are not part of this game.", + unzip: "Archives are not part of this game.", + tree: "Try ls -R instead.", + diff: "Try cat on both files and compare.", + stat: "Try ls -l instead.", + file: "Try cat or ls -l instead.", +}; + +/** Help text for `man`, `help` and the cheat sheet. */ +export const USAGE: Record = { + pwd: { usage: "pwd", desc: "show the folder you are in", group: "Move and look" }, + cd: { usage: "cd [DIR] (cd .. goes up, cd - goes back, cd alone goes home)", desc: "change folder", group: "Move and look" }, + ls: { usage: "ls [-l] [-a] [-h] [-R] [-S] [-t] [-r] [PATH]...", desc: "list files (-l details, -a hidden, -h readable sizes, -S by size, -t by time)", group: "Move and look" }, + cat: { usage: "cat [-n] FILE...", desc: "print a file (less and more work the same)", group: "Read" }, + head: { usage: "head [-n N] [FILE]", desc: "the first N lines (10 by default)", group: "Read" }, + tail: { usage: "tail [-n N] [FILE]", desc: "the last N lines (10 by default)", group: "Read" }, + grep: { usage: "grep [-i] [-v] [-n] [-c] [-r] [-E] [-l] [-o] [-w] PATTERN [FILE]...", desc: "show lines that match a pattern", group: "Search" }, + find: { usage: "find [PATH] [-name PAT] [-type f|d] [-size +10M] [-mtime +7] [-maxdepth N] [-delete]", desc: "find files by name, type, size or age", group: "Search" }, + wc: { usage: "wc [-l] [-w] [-c] [FILE]", desc: "count lines, words and bytes", group: "Filters (use with |)" }, + sort: { usage: "sort [-r] [-n] [-h] [-u] [-k N] [-t SEP] [FILE]", desc: "sort lines (-n numbers, -h sizes like 4K, -r backwards)", group: "Filters (use with |)" }, + uniq: { usage: "uniq [-c] [-d] [FILE]", desc: "remove repeated lines next to each other (-c counts them; sort first)", group: "Filters (use with |)" }, + cut: { usage: "cut -d SEP -f N [FILE]", desc: "pick a column from each line", group: "Filters (use with |)" }, + awk: { usage: "awk [-F SEP] '{print $1, $3}' [FILE]", desc: "print chosen columns", group: "Filters (use with |)" }, + sed: { usage: "sed [-i] 's/old/new/g' [FILE]", desc: "replace text (-i changes the file)", group: "Filters (use with |)" }, + xargs: { usage: "xargs COMMAND", desc: "use the lines from a pipe as arguments", group: "Filters (use with |)" }, + tee: { usage: "tee [-a] FILE", desc: "show the input and also save it to a file", group: "Filters (use with |)" }, + echo: { usage: "echo [-n] TEXT", desc: "print text (use > file to write it into a file)", group: "Change files" }, + touch: { usage: "touch FILE...", desc: "make an empty file or update its time", group: "Change files" }, + mkdir: { usage: "mkdir [-p] DIR...", desc: "make a folder", group: "Change files" }, + rm: { usage: "rm [-r] [-f] FILE...", desc: "delete files (-r for folders). There is no undo", group: "Change files" }, + cp: { usage: "cp [-r] SOURCE... DEST", desc: "copy files (-r for folders)", group: "Change files" }, + mv: { usage: "mv SOURCE... DEST", desc: "move or rename", group: "Change files" }, + chmod: { usage: "chmod MODE FILE... (755, 644, +x, u+x, go-w)", desc: "change who may read, write or run a file", group: "Change files" }, + chown: { usage: "chown USER[:GROUP] FILE...", desc: "change the owner (only root can give files away)", group: "Change files" }, + du: { usage: "du [-s] [-h] [-d N] [PATH]...", desc: "how much disk each folder uses", group: "System" }, + df: { usage: "df -h", desc: "how full each disk is", group: "System" }, + ps: { usage: "ps aux", desc: "list running processes with their PID", group: "System" }, + kill: { usage: "kill [-9] PID...", desc: "stop a process (-9 forces it)", group: "System" }, + pgrep: { usage: "pgrep [-l] NAME", desc: "find process IDs by name (pkill and killall stop them)", group: "System" }, + whoami: { usage: "whoami", desc: "show your user name", group: "System" }, + id: { usage: "id", desc: "show your user and groups", group: "System" }, + which: { usage: "which COMMAND", desc: "show where a command lives", group: "System" }, + hostname: { usage: "hostname", desc: "show the server name", group: "System" }, + date: { usage: "date", desc: "show the date", group: "System" }, + export: { usage: "export NAME=VALUE", desc: "set a variable (use it as $NAME)", group: "System" }, + history: { usage: "history", desc: "list the commands you ran", group: "This game" }, + clear: { usage: "clear", desc: "clear the screen", group: "This game" }, + hint: { usage: "hint", desc: "show the next hint (it can cost a star)", group: "This game" }, + submit: { usage: "submit ANSWER", desc: "give your answer (for missions that ask a question)", group: "This game" }, + help: { usage: "help", desc: "list the commands that work here (man NAME shows one)", group: "This game" }, +}; + +export const SHELL_TIPS = [ + "Pipe: cmd1 | cmd2 sends the output of cmd1 into cmd2", + "Redirect: > writes a file, >> adds to it", + "&& runs the next command only if the first worked", + "Quotes keep spaces together. $HOME, $USER and $PWD work", + "Tab finishes a name. Arrow up repeats a command", +]; diff --git a/server/src/shared/games/linux/engine.ts b/server/src/shared/games/linux/engine.ts new file mode 100644 index 00000000..e5acb29a --- /dev/null +++ b/server/src/shared/games/linux/engine.ts @@ -0,0 +1,107 @@ +/* eslint-disable no-control-regex -- the shell engines reject or use control characters on purpose */ +// Linux Command Explorer: a terminal quest on a made-up server. The player solves a mission with +// real commands in a fake shell. The browser plays it live; the server replays the same commands +// from a fresh state before it gives XP. Pure and deterministic, so both sides always agree. +import { pickDaily } from "../daily.js"; +import type { GameEngine, RoundBase, Stars, VerifyResult } from "../types.js"; +import { USAGE } from "./commands.js"; +import { MISSIONS, missionById } from "./missions.js"; +import { MAX_COMMANDS, MAX_LINE, Shell } from "./shell.js"; + +export type { OutLine, Progress, RunResult } from "./shell.js"; +export { Shell } from "./shell.js"; + +/** What the browser needs to show a mission. The server definition (files, goal) stays in the engine. */ +export type LinuxRound = RoundBase & { + story: string; + /** The checklist, in order. The last one is the goal. */ + objectives: string[]; + /** Commands a good player needs. Three stars need this many or fewer, with no hints. */ + par: number; + hintCount: number; + /** "answer": give an answer with submit. "state": change the server until the goal is true. */ + kind: "answer" | "state"; +}; + +export type LinuxSubmission = { commands: string[]; hints: number }; + +const POOL: LinuxRound[] = MISSIONS.map((m) => ({ + id: m.id, + difficulty: m.difficulty, + title: m.title, + brief: m.brief, + story: m.story, + objectives: m.objectives.map((o) => o.label), + par: m.par, + hintCount: m.hints.length, + kind: m.answer ? "answer" : "state", +})); + +const CONTROL = /[\u0000-\u0008\u000a-\u001f\u007f]/; + +function parseSubmission(input: unknown): LinuxSubmission | null { + if (typeof input !== "object" || input === null || Array.isArray(input)) return null; + const keys = Object.keys(input); + if (keys.some((k) => k !== "commands" && k !== "hints")) return null; + const { commands, hints } = input as { commands?: unknown; hints?: unknown }; + if (!Array.isArray(commands) || commands.length > MAX_COMMANDS) return null; + for (const line of commands) { + if (typeof line !== "string" || line.length > MAX_LINE || CONTROL.test(line)) return null; + } + if (typeof hints !== "number" || !Number.isInteger(hints) || hints < 0 || hints > 20) return null; + return { commands: [...(commands as string[])], hints }; +} + +const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`; + +function verify(round: LinuxRound, submission: LinuxSubmission): VerifyResult { + const fail = (message: string, score = 0): VerifyResult => ({ passed: false, stars: 0, score, message }); + try { + const mission = missionById(round?.id); + if (!mission) return fail("This mission is not known."); + const parsed = parseSubmission(submission); + if (!parsed) return fail("That did not look like a finished round."); + if (parsed.commands.length === 0) return fail("No commands were run yet. Try ls to look around."); + const shell = new Shell(mission); + for (const line of parsed.commands) shell.run(line); + const progress = shell.progress(); + if (!shell.isSolved) { + const open = mission.objectives.find((_, i) => !progress.done[i]); + return fail(open ? `The goal is not reached yet. Still open: ${open.label}.` : "The goal is not reached yet.", shell.commandCount); + } + const commands = shell.commandCount; + const hints = Math.max(shell.hintCount, parsed.hints); + const stars: Stars = hints === 0 && commands <= mission.par ? 3 : hints <= 1 && commands <= mission.par + 4 ? 2 : 1; + const message = + stars === 3 + ? `Solved in ${plural(commands, "command")}, par is ${mission.par}, with no hints.` + : `Solved in ${plural(commands, "command")} (par ${mission.par}) with ${plural(hints, "hint")}; use par or fewer commands and no hints for 3 stars.`; + return { passed: true, stars, score: commands, message }; + } catch { + return fail("That run could not be checked."); + } +} + +export const linuxEngine: GameEngine = { + id: "linux", + title: "Linux Command Explorer", + tagline: "Solve missions on a made-up Linux server with real commands.", + roundsFor: (dayKey) => pickDaily(POOL, dayKey, "linux"), + parseSubmission, + verify, +}; + +/** A new shell for a round, or null when the round is not one of ours. */ +export function createLinuxSession(round: { id: string }): Shell | null { + const mission = missionById(round?.id); + return mission ? new Shell(mission) : null; +} + +/** The "what works" cheat sheet, grouped. */ +export function linuxCheatSheet(): Array<{ group: string; items: Array<{ name: string; usage: string; desc: string }> }> { + const groups = new Map>(); + for (const [name, u] of Object.entries(USAGE)) groups.set(u.group, [...(groups.get(u.group) ?? []), { name, usage: u.usage, desc: u.desc }]); + return [...groups].map(([group, items]) => ({ group, items })); +} + +export const LINUX_LIMITS = { maxCommands: MAX_COMMANDS, maxLine: MAX_LINE }; diff --git a/server/src/shared/games/linux/fs.ts b/server/src/shared/games/linux/fs.ts new file mode 100644 index 00000000..a656b183 --- /dev/null +++ b/server/src/shared/games/linux/fs.ts @@ -0,0 +1,361 @@ +// An in-memory file system for the Linux Command Explorer. Pure and deterministic: no real files, +// no clock. "Now" is a fixed number that moves forward one minute per command the player runs. + +export const NOW = 1767225600; // 2026-01-01 00:00:00 UTC +export const DAY = 86400; +export const MAX_NODES = 1500; +export const MAX_FILE_SIZE = 200_000; +export const MAX_PATH = 1024; +export const BLOCK = 4096; + +export type Err = "ENOENT" | "EACCES" | "ENOTDIR" | "EEXIST" | "EISDIR" | "ENOSPC" | "EINVAL"; + +export const ERR_TEXT: Record = { + ENOENT: "No such file or directory", + EACCES: "Permission denied", + ENOTDIR: "Not a directory", + EEXIST: "File exists", + EISDIR: "Is a directory", + ENOSPC: "No space left on device", + EINVAL: "Invalid argument", +}; + +export type User = { name: string; groups: string[] }; + +export type VNode = { + kind: "file" | "dir"; + name: string; + owner: string; + group: string; + mode: number; + mtime: number; + content: string; + /** A made-up size in bytes for a big file whose text is short. */ + size: number | null; + children: Map; +}; + +export type FileOpts = { + content?: string; + size?: number; + owner?: string; + group?: string; + mode?: number; + mtime?: number; + /** Age in days at the fixed "now". */ + age?: number; +}; +/** A path ending in "/" is a directory. A string value is the text of a file. */ +export type FsSpec = Record; + +/** Turn a path into an absolute one with no "." or ".." parts. */ +export function normalizePath(cwd: string, input: string, home = "/"): string { + let path = input; + if (path === "~" || path.startsWith("~/")) path = home + path.slice(1); + if (!path.startsWith("/")) path = cwd + "/" + path; + const out: string[] = []; + for (const part of path.split("/")) { + if (part === "" || part === ".") continue; + if (part === "..") out.pop(); + else out.push(part); + } + return "/" + out.join("/"); +} + +export function baseName(abs: string): string { + const i = abs.lastIndexOf("/"); + return i < 0 ? abs : abs.slice(i + 1); +} + +export function dirName(abs: string): string { + const i = abs.lastIndexOf("/"); + return i <= 0 ? "/" : abs.slice(0, i); +} + +export function joinPath(dir: string, name: string): string { + return dir === "/" ? "/" + name : dir + "/" + name; +} + +/** Permission bits for a user on a node: 4 read, 2 write, 1 execute. */ +export function permBits(user: User, node: VNode): number { + if (user.name === "root") return 7; + if (node.owner === user.name) return (node.mode >> 6) & 7; + if (user.groups.includes(node.group)) return (node.mode >> 3) & 7; + return node.mode & 7; +} + +export function can(user: User, node: VNode, bit: 1 | 2 | 4): boolean { + return (permBits(user, node) & bit) !== 0; +} + +export function modeString(node: VNode): string { + const m = node.mode; + const triple = (v: number) => (v & 4 ? "r" : "-") + (v & 2 ? "w" : "-") + (v & 1 ? "x" : "-"); + return (node.kind === "dir" ? "d" : "-") + triple((m >> 6) & 7) + triple((m >> 3) & 7) + triple(m & 7); +} + +const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]; + +/** The date column of `ls -l`. */ +export function formatTime(mtime: number, now: number): string { + const d = new Date(mtime * 1000); + const day = String(d.getUTCDate()).padStart(2, " "); + if (now - mtime > 180 * DAY || mtime > now + DAY) return `${MONTHS[d.getUTCMonth()]} ${day} ${d.getUTCFullYear()}`; + const hh = String(d.getUTCHours()).padStart(2, "0"); + const mm = String(d.getUTCMinutes()).padStart(2, "0"); + return `${MONTHS[d.getUTCMonth()]} ${day} ${hh}:${mm}`; +} + +/** Sizes like GNU `-h`: 1.5K, 12M, 4.0K. */ +export function humanSize(bytes: number): string { + if (bytes < 1024) return String(bytes); + const units = ["K", "M", "G", "T"]; + let v = bytes / 1024; + let i = 0; + while (v >= 1024 && i < units.length - 1) { + v /= 1024; + i++; + } + const rounded = Math.ceil(v * 10) / 10; + return (rounded < 10 ? rounded.toFixed(1) : String(Math.ceil(v))) + units[i]; +} + +function newNode(kind: "file" | "dir", name: string, owner: string, opts: FileOpts = {}): VNode { + return { + kind, + name, + owner: opts.owner ?? owner, + group: opts.group ?? opts.owner ?? owner, + mode: opts.mode ?? (kind === "dir" ? 0o755 : 0o644), + mtime: opts.mtime ?? (opts.age !== undefined ? NOW - Math.round(opts.age * DAY) : NOW - 2 * DAY), + content: opts.content ?? "", + size: opts.size ?? null, + children: new Map(), + }; +} + +/** Who owns a path when the mission does not say: a home folder belongs to its user. */ +function defaultOwner(abs: string): string { + const m = /^\/home\/([^/]+)/.exec(abs); + return m ? m[1]! : "root"; +} + +export function sizeOf(node: VNode): number { + return node.kind === "dir" ? BLOCK : node.size ?? node.content.length; +} + +/** Disk blocks used, like `du`: files in 4K blocks, a folder counts itself too. */ +export function diskUsage(node: VNode): number { + if (node.kind === "file") { + const size = sizeOf(node); + return size === 0 ? 0 : Math.ceil(size / BLOCK) * BLOCK; + } + let total = BLOCK; + for (const child of node.children.values()) total += diskUsage(child); + return total; +} + +export type Walk = { node: VNode | null; err: Err | null }; + +export class VFS { + root: VNode; + count = 1; + /** The fixed "now", moved forward by the shell. */ + now = NOW; + + constructor(spec: FsSpec) { + this.root = newNode("dir", "", "root"); + const keys = Object.keys(spec).sort((a, b) => a.length - b.length); + for (const key of keys) { + const value = spec[key]!; + const opts: FileOpts = typeof value === "string" ? { content: value } : value; + const abs = normalizePath("/", key); + if (abs === "/") { + Object.assign(this.root, { mode: opts.mode ?? this.root.mode, owner: opts.owner ?? this.root.owner }); + continue; + } + if (key.endsWith("/")) this.build(abs, "dir", opts); + else this.build(abs, "file", opts); + } + } + + private build(abs: string, kind: "file" | "dir", opts: FileOpts): void { + const parts = abs.split("/").filter(Boolean); + let cur = this.root; + let path = ""; + for (let i = 0; i < parts.length; i++) { + const part = parts[i]!; + path += "/" + part; + const last = i === parts.length - 1; + let next = cur.children.get(part); + if (!next) { + next = newNode(last ? kind : "dir", part, defaultOwner(path), last ? opts : {}); + cur.children.set(part, next); + this.count++; + } else if (last) { + if (kind === "dir") Object.assign(next, { owner: opts.owner ?? next.owner, group: opts.group ?? opts.owner ?? next.group, mode: opts.mode ?? next.mode, mtime: opts.mtime ?? (opts.age !== undefined ? NOW - opts.age * DAY : next.mtime) }); + } + cur = next; + } + } + + /** Find a node by absolute path, checking that the user may walk into every folder on the way. */ + walk(abs: string, user: User): Walk { + let cur = this.root; + for (const part of abs.split("/")) { + if (part === "") continue; + if (cur.kind !== "dir") return { node: null, err: "ENOTDIR" }; + if (!can(user, cur, 1)) return { node: null, err: "EACCES" }; + const next = cur.children.get(part); + if (!next) return { node: null, err: "ENOENT" }; + cur = next; + } + return { node: cur, err: null }; + } + + /** No permission checks. For the game's own goal checks. */ + peek(abs: string): VNode | null { + let cur: VNode | undefined = this.root; + for (const part of abs.split("/")) { + if (part === "") continue; + if (!cur || cur.kind !== "dir") return null; + cur = cur.children.get(part); + } + return cur ?? null; + } + + /** The folder that would hold a new entry at this path, and the name of the entry. */ + parentFor(abs: string, user: User): { dir: VNode | null; name: string; err: Err | null } { + const name = baseName(abs); + const res = this.walk(dirName(abs), user); + if (!res.node) return { dir: null, name, err: res.err }; + if (res.node.kind !== "dir") return { dir: null, name, err: "ENOTDIR" }; + return { dir: res.node, name, err: null }; + } + + private checkNew(abs: string, user: User): { dir: VNode; name: string } | Err { + if (abs.length > MAX_PATH) return "EINVAL"; + const p = this.parentFor(abs, user); + if (!p.dir) return p.err ?? "ENOENT"; + if (!can(user, p.dir, 2) || !can(user, p.dir, 1)) return "EACCES"; + if (p.name.length > 255 || p.name === "") return "EINVAL"; + return { dir: p.dir, name: p.name }; + } + + /** Create or replace a file. */ + writeFile(abs: string, user: User, text: string, append: boolean): Err | null { + const existing = this.walk(abs, user); + if (existing.node) { + const node = existing.node; + if (node.kind === "dir") return "EISDIR"; + if (!can(user, node, 2)) return "EACCES"; + const next = append ? node.content + text : text; + if (next.length > MAX_FILE_SIZE) return "ENOSPC"; + node.content = next; + node.size = null; + node.mtime = this.now; + return null; + } + if (existing.err !== "ENOENT") return existing.err; + const target = this.checkNew(abs, user); + if (typeof target === "string") return target; + if (this.count >= MAX_NODES || text.length > MAX_FILE_SIZE) return "ENOSPC"; + const node = newNode("file", target.name, user.name, { content: text, mtime: this.now }); + node.group = user.groups[0] ?? user.name; + target.dir.children.set(target.name, node); + target.dir.mtime = this.now; + this.count++; + return null; + } + + mkdir(abs: string, user: User): Err | null { + const existing = this.walk(abs, user); + if (existing.node) return "EEXIST"; + if (existing.err !== "ENOENT") return existing.err; + const target = this.checkNew(abs, user); + if (typeof target === "string") return target; + if (this.count >= MAX_NODES) return "ENOSPC"; + const node = newNode("dir", target.name, user.name, { mtime: this.now }); + node.group = user.groups[0] ?? user.name; + target.dir.children.set(target.name, node); + target.dir.mtime = this.now; + this.count++; + return null; + } + + private countNodes(node: VNode): number { + let n = 1; + for (const c of node.children.values()) n += this.countNodes(c); + return n; + } + + /** Delete a file or a folder with everything in it. The caller checks the "-r" rule. */ + remove(abs: string, user: User): Err | null { + if (abs === "/") return "EINVAL"; + const p = this.parentFor(abs, user); + if (!p.dir) return p.err; + const node = p.dir.children.get(p.name); + if (!node) return "ENOENT"; + if (!can(user, p.dir, 2)) return "EACCES"; + p.dir.children.delete(p.name); + p.dir.mtime = this.now; + this.count -= this.countNodes(node); + return null; + } + + private copyNode(node: VNode, name: string, owner: string, group: string): VNode { + const copy: VNode = { ...node, name, owner, group, mtime: this.now, children: new Map() }; + for (const [key, child] of node.children) copy.children.set(key, this.copyNode(child, child.name, owner, group)); + return copy; + } + + /** Copy a node to a new absolute path (the path of the copy itself). */ + copy(node: VNode, destAbs: string, user: User): Err | null { + const target = this.checkNew(destAbs, user); + if (typeof target === "string") return target; + if (target.dir.children.has(target.name)) { + const old = target.dir.children.get(target.name)!; + if (old.kind === "dir") return "EISDIR"; + if (!can(user, old, 2)) return "EACCES"; + this.count -= 1; + } + if (this.count + this.countNodes(node) > MAX_NODES) return "ENOSPC"; + const copy = this.copyNode(node, target.name, user.name, user.groups[0] ?? user.name); + copy.mode = node.mode; + target.dir.children.set(target.name, copy); + target.dir.mtime = this.now; + this.count += this.countNodes(copy); + return null; + } + + /** Move a node to a new absolute path. */ + move(srcAbs: string, destAbs: string, user: User): Err | null { + const from = this.parentFor(srcAbs, user); + if (!from.dir) return from.err; + const node = from.dir.children.get(from.name); + if (!node) return "ENOENT"; + if (!can(user, from.dir, 2)) return "EACCES"; + if (destAbs === srcAbs) return null; + if (destAbs.startsWith(srcAbs + "/")) return "EINVAL"; + const target = this.checkNew(destAbs, user); + if (typeof target === "string") return target; + const old = target.dir.children.get(target.name); + if (old) { + if (old.kind === "dir" && node.kind !== "dir") return "EISDIR"; + if (old.kind === "dir" && old.children.size > 0) return "EEXIST"; + this.count -= this.countNodes(old); + } + from.dir.children.delete(from.name); + node.name = target.name; + target.dir.children.set(target.name, node); + from.dir.mtime = this.now; + target.dir.mtime = this.now; + return null; + } + + /** Read a file's text with no permission checks, or null. For goal checks. */ + text(abs: string): string | null { + const node = this.peek(abs); + return node && node.kind === "file" ? node.content : null; + } +} diff --git a/server/src/shared/games/linux/missions.ts b/server/src/shared/games/linux/missions.ts new file mode 100644 index 00000000..ea1b8b8b --- /dev/null +++ b/server/src/shared/games/linux/missions.ts @@ -0,0 +1,588 @@ +// The missions of the Linux Command Explorer. Each one is a small made-up server (orbit-01) and a +// goal. The player is the user "ops". Everything here is fixed data, so every day is the same for +// everyone and every mission can be replayed from its `solution`. +import { hashString, seededRandom } from "../daily.js"; +import type { FsSpec } from "./fs.js"; +import type { Mission, Proc, ShellState } from "./model.js"; + +// ---------------------------------------------------------------- helpers + +const lines = (...l: string[]): string => l.join("\n") + "\n"; +const ran = (s: ShellState, re: RegExp): boolean => s.history.some((h) => re.test(h)); +const saw = (s: ShellState, what: string | RegExp): boolean => (typeof what === "string" ? s.shown.includes(what) : what.test(s.shown)); +const exists = (s: ShellState, path: string): boolean => s.fs.peek(path) !== null; +const pad2 = (n: number): string => String(n).padStart(2, "0"); + +/** The parts every server has. A mission adds to these (and may replace them). */ +function base(): FsSpec { + return { + "/etc/hostname": "orbit-01\n", + "/etc/hosts": lines("127.0.0.1 localhost", "10.0.0.10 orbit-01"), + "/etc/os-release": lines('NAME="Debian GNU/Linux"', 'VERSION="12 (bookworm)"'), + "/etc/passwd": lines( + "root:x:0:0:root:/root:/bin/bash", + "ops:x:1000:1000:Ops:/home/ops:/bin/bash", + "alice:x:1002:1002:Alice:/home/alice:/bin/bash", + "bob:x:1003:1003:Bob:/home/bob:/bin/bash", + "www-data:x:33:33:www-data:/var/www:/usr/sbin/nologin", + ), + "/home/ops/.bashrc": lines("# ~/.bashrc", "alias ll='ls -l'"), + "/home/ops/todo.txt": lines("1. read the mission panel", "2. explore with ls and cat", "3. ask for a hint only when stuck"), + "/root/": { owner: "root", mode: 0o700 }, + "/root/notes.txt": { content: "root only\n", mode: 0o600 }, + "/tmp/": { mode: 0o777 }, + "/var/log/": {}, + }; +} + +function accessLog(seed: string, count: number): string { + const r = seededRandom(hashString(seed)); + const ips = ["10.0.0.4", "10.0.0.7", "10.0.1.12", "192.168.1.5", "172.16.0.9"]; + const paths = ["/", "/login", "/api/items", "/api/orders", "/static/app.js", "/health", "/about"]; + const statuses = [200, 200, 200, 200, 304, 404, 500]; + const out: string[] = []; + for (let i = 0; i < count; i++) { + const t = i * 97; + const ip = ips[Math.floor(r() * ips.length)]!; + const path = paths[Math.floor(r() * paths.length)]!; + const status = statuses[Math.floor(r() * statuses.length)]!; + out.push(`${ip} - - [01/Jan/2026:${pad2(Math.floor(t / 3600) % 24)}:${pad2(Math.floor(t / 60) % 60)}:${pad2(t % 60)}] "GET ${path} HTTP/1.1" ${status} ${200 + Math.floor(r() * 9000)}`); + } + return out.join("\n") + "\n"; +} + +/** A login log. `failed` and `accepted` say how many lines each address gets. Lines are shuffled. */ +function authLog(seed: string, failed: Array<[string, number]>, accepted: Array<[string, number]>, noise: number): { text: string; failedTotal: number } { + const r = seededRandom(hashString(seed)); + const users = ["root", "admin", "deploy", "test", "oracle", "ubuntu"]; + const port = () => 30000 + Math.floor(r() * 30000); + const pid = () => 1000 + Math.floor(r() * 8000); + const events: string[] = []; + let failedTotal = 0; + for (const [ip, n] of failed) { + for (let i = 0; i < n; i++) { + const user = users[Math.floor(r() * users.length)]!; + const invalid = r() < 0.4 ? "invalid user " : ""; + events.push(`orbit-01 sshd[${pid()}]: Failed password for ${invalid}${user} from ${ip} port ${port()} ssh2`); + failedTotal++; + } + } + for (const [ip, n] of accepted) { + for (let i = 0; i < n; i++) events.push(`orbit-01 sshd[${pid()}]: Accepted password for deploy from ${ip} port ${port()} ssh2`); + } + for (let i = 0; i < noise; i++) { + const pick = Math.floor(r() * 4); + if (pick === 0) events.push(`orbit-01 sshd[${pid()}]: Connection closed by 10.0.0.9 port ${port()} [preauth]`); + else if (pick === 1) events.push(`orbit-01 sshd[${pid()}]: pam_unix(sshd:session): session opened for user ops(uid=1000) by (uid=0)`); + else if (pick === 2) events.push(`orbit-01 sshd[${pid()}]: Invalid user guest from 198.51.100.200 port ${port()}`); + else events.push(`orbit-01 CRON[${pid()}]: pam_unix(cron:session): session closed for user root`); + } + for (let i = events.length - 1; i > 0; i--) { + const j = Math.floor(r() * (i + 1)); + [events[i], events[j]] = [events[j]!, events[i]!]; + } + const text = events.map((e, i) => { + const t = (i * 41) % 86400; + return `2026-01-01T${pad2(Math.floor(t / 3600))}:${pad2(Math.floor(t / 60) % 60)}:${pad2(t % 60)} ${e}`; + }); + return { text: text.join("\n") + "\n", failedTotal }; +} + +const ACCESS_LINES = 214; +const AUTH_EASY = authLog("auth-medium", [["203.0.113.9", 23], ["198.51.100.4", 17], ["192.0.2.88", 11]], [["10.0.0.5", 30]], 60); +const AUTH_HARD = authLog( + "auth-hard", + [["203.0.113.77", 91], ["198.51.100.23", 64], ["192.0.2.14", 37], ["203.0.113.5", 22], ["198.51.100.99", 15], ["192.0.2.200", 8]], + [["10.0.0.5", 120], ["10.0.0.6", 40]], + 80, +); + +// ---------------------------------------------------------------- easy + +const hiddenNote: Mission = { + id: "linux-hidden-note", + difficulty: "easy", + title: "The hidden note", + brief: "A file in the app folder is hiding. Find it and read the release word.", + story: "Priya just joined the team. She needs the release word for tonight's deploy, but nobody can find it. Someone said it is in a hidden file inside the app folder.", + par: 3, + hints: [ + "Files whose names start with a dot are hidden. A plain ls does not show them.", + "ls -a shows hidden files too. Try: ls -a app", + "Read the hidden file with cat, then answer with: submit WORD", + ], + files: { + ...base(), + "/home/ops/app/README.md": lines("# Orbit app", "Run main.py to start the app."), + "/home/ops/app/main.py": lines("print('orbit app starting')"), + "/home/ops/app/requirements.txt": lines("flask==3.0.0", "gunicorn==21.2.0"), + "/home/ops/app/.deploy_note": lines("Release word: BLUEFOX-42", "Do not share this word outside the team."), + "/home/ops/app/static/": {}, + "/home/ops/app/static/logo.txt": "(a tiny logo)\n", + }, + answer: ["BLUEFOX-42"], + objectives: [ + { label: "Show the hidden files in the app folder", done: (s) => saw(s, ".deploy_note") }, + { label: "Read the hidden file", done: (s) => saw(s, "BLUEFOX-42") }, + { label: "Submit the release word with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["ls -a app", "cat app/.deploy_note", "submit BLUEFOX-42"], +}; + +const configPort: Mission = { + id: "linux-config-port", + difficulty: "easy", + title: "Which port?", + brief: "Read the web app's config file and find the port it listens on.", + story: "The proxy team needs to point at the web app, but nobody remembers its port. The settings live in a config folder under /etc/webapp.", + par: 3, + hints: [ + "Config files usually live in /etc. Try: ls /etc/webapp", + "Use app.conf (the .old file is outdated). Read it with cat.", + "Look for the line with listen_port, then: submit NUMBER", + ], + files: { + ...base(), + "/etc/webapp/app.conf": lines("# webapp settings", "name=orbit-web", "listen_host=0.0.0.0", "listen_port=8472", "workers=4", "log_level=info"), + "/etc/webapp/app.conf.old": lines("# old settings (do not use)", "name=orbit-web", "listen_host=127.0.0.1", "listen_port=8080", "workers=2"), + "/etc/webapp/mime.types": lines("text/html html", "text/css css"), + }, + answer: ["8472"], + objectives: [ + { label: "Look in the /etc/webapp folder", done: (s) => saw(s, "app.conf") }, + { label: "Read the current config file", done: (s) => saw(s, "listen_port=8472") }, + { label: "Submit the port with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["ls /etc/webapp", "cat /etc/webapp/app.conf", "submit 8472"], +}; + +const countLines: Mission = { + id: "linux-count-requests", + difficulty: "easy", + title: "How many requests?", + brief: "Count how many lines the web server's access log has. Each line is one request.", + story: "The boss asks how many requests the web server handled today. The server writes one line per request into an access log in /var/log/webapp.", + par: 3, + hints: [ + "Find the log first: ls /var/log/webapp", + "wc counts things. wc -l counts lines.", + "Try: wc -l /var/log/webapp/access.log and then submit the number", + ], + files: { + ...base(), + "/var/log/webapp/access.log": accessLog("access-easy", ACCESS_LINES), + "/var/log/webapp/error.log": lines("2026-01-01 03:12:44 error: upstream timed out", "2026-01-01 09:40:02 error: bad gateway"), + }, + answer: [String(ACCESS_LINES)], + objectives: [ + { label: "Find the web server logs", done: (s) => saw(s, "access.log") }, + { label: "Count the lines in access.log", done: (s) => saw(s, new RegExp(`\\b${ACCESS_LINES}\\b`)) }, + { label: "Submit the number with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["ls /var/log/webapp", "wc -l /var/log/webapp/access.log", `submit ${ACCESS_LINES}`], +}; + +const biggestFile: Mission = { + id: "linux-biggest-file", + difficulty: "easy", + title: "The biggest file", + brief: "The downloads folder is eating the disk. Find the biggest file in it.", + story: "Your disk is almost full. Most of the space is in the downloads folder. Which single file is the biggest?", + par: 3, + hints: [ + "ls -l shows the size of each file in bytes.", + "Add -S to sort by size, biggest first: ls -lS downloads", + "Or use ls -lh to see sizes like 870M. Then: submit FILENAME", + ], + files: { + ...base(), + "/home/ops/downloads/notes.txt": { content: "meeting notes\n", size: 2300 }, + "/home/ops/downloads/invoice-march.pdf": { content: "pdf", size: 480_000 }, + "/home/ops/downloads/photo-001.jpg": { content: "jpg", size: 3_400_000 }, + "/home/ops/downloads/photo-002.jpg": { content: "jpg", size: 2_900_000 }, + "/home/ops/downloads/holiday-video.mp4": { content: "mp4", size: 912_000_000 }, + "/home/ops/downloads/backup-old.zip": { content: "zip", size: 410_000_000 }, + "/home/ops/downloads/setup.iso": { content: "iso", size: 702_000_000 }, + "/home/ops/downloads/music.mp3": { content: "mp3", size: 7_800_000 }, + }, + answer: ["holiday-video.mp4"], + objectives: [ + { label: "Look at the downloads folder", done: (s) => saw(s, "holiday-video.mp4") }, + { label: "Show the file sizes (try ls -l)", done: (s) => ran(s, /\bls\b[^|;&]*\s-[a-zA-Z]*l|\bdu\b/) }, + { label: "Submit the name of the biggest file", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["ls -lS downloads", "submit holiday-video.mp4"], +}; + +// ---------------------------------------------------------------- medium + +const failedLogins: Mission = { + id: "linux-failed-logins", + difficulty: "medium", + title: "Failed logins", + brief: "Count the failed password attempts in the login log.", + story: "Security saw strange traffic last night. The login log is /var/log/auth.log. Each failed password attempt has the words Failed password. How many are there?", + par: 3, + hints: [ + "grep prints the lines that match a word: grep 'Failed password' /var/log/auth.log", + "Count them with grep -c, or send the lines to wc -l with a pipe.", + "Try: grep -c 'Failed password' /var/log/auth.log then submit NUMBER", + ], + files: { ...base(), "/var/log/auth.log": AUTH_EASY.text }, + answer: [String(AUTH_EASY.failedTotal)], + objectives: [ + { label: "Search auth.log for Failed password", done: (s) => ran(s, /grep/) && ran(s, /auth\.log/) && ran(s, /failed password/i) }, + { label: "Count the matching lines", done: (s) => saw(s, new RegExp(`(^|\\n)\\s*${AUTH_EASY.failedTotal}\\s*(\\n|$)`)) }, + { label: "Submit the count with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["grep -c 'Failed password' /var/log/auth.log", `submit ${AUTH_EASY.failedTotal}`], +}; + +const OLD_TMP = ["/var/tmp/cache-a.tmp", "/var/tmp/cache-b.tmp", "/var/tmp/session-91.tmp", "/var/tmp/render/frame1.tmp"]; +const KEEP_TMP = ["/var/tmp/upload-77.tmp", "/var/tmp/lock-now.tmp", "/var/tmp/render/frame2.tmp", "/var/tmp/report.txt", "/var/tmp/old.log"]; + +const oldTmp: Mission = { + id: "linux-old-temp-files", + difficulty: "medium", + title: "Clean the temp folder", + brief: "Delete the .tmp files in /var/tmp that are older than 7 days. Keep everything else.", + story: "/var/tmp is full of leftovers. The rule: .tmp files older than 7 days can go. Fresh .tmp files are still used by running jobs, and other file types must stay.", + par: 3, + hints: [ + "find can test the age of files: -mtime +7 means older than 7 days.", + "Combine tests: find /var/tmp -name '*.tmp' -mtime +7 (first only look at what it finds).", + "When the list looks right, add -delete at the end.", + ], + files: { + ...base(), + "/var/tmp/": { owner: "ops" }, + "/var/tmp/render/": { owner: "ops" }, + "/var/tmp/cache-a.tmp": { content: "x", age: 12 }, + "/var/tmp/cache-b.tmp": { content: "x", age: 30 }, + "/var/tmp/session-91.tmp": { content: "x", age: 9 }, + "/var/tmp/upload-77.tmp": { content: "x", age: 2 }, + "/var/tmp/lock-now.tmp": { content: "x", age: 0 }, + "/var/tmp/report.txt": { content: "quarterly numbers\n", age: 40 }, + "/var/tmp/old.log": { content: "old log\n", age: 60 }, + "/var/tmp/render/frame1.tmp": { content: "x", age: 20 }, + "/var/tmp/render/frame2.tmp": { content: "x", age: 1 }, + }, + objectives: [ + { label: "Find the .tmp files older than 7 days", done: (s) => ran(s, /find[^|;&]*-mtime/) }, + { label: "Delete the old .tmp files", done: (s) => OLD_TMP.every((p) => !exists(s, p)) }, + { label: "Keep the fresh .tmp files and the other files", done: (s) => OLD_TMP.every((p) => !exists(s, p)) && KEEP_TMP.every((p) => exists(s, p)) }, + ], + goal: (s) => OLD_TMP.every((p) => !exists(s, p)) && KEEP_TMP.every((p) => exists(s, p)), + solution: ["find /var/tmp -name '*.tmp' -mtime +7", "find /var/tmp -name '*.tmp' -mtime +7 -delete"], +}; + +const PROCS: Proc[] = [ + { pid: 1, user: "root", cpu: 0, mem: 0.1, vsz: 168000, rss: 11000, stat: "Ss", start: "Jan01", time: "0:03", command: "/sbin/init" }, + { pid: 77, user: "root", cpu: 0, mem: 0.1, vsz: 8500, rss: 2200, stat: "Ss", start: "Jan01", time: "0:00", command: "/usr/sbin/cron -f" }, + { pid: 311, user: "postgres", cpu: 1.2, mem: 3.4, vsz: 320000, rss: 56000, stat: "Ss", start: "Jan01", time: "1:12", command: "postgres: main" }, + { pid: 520, user: "www-data", cpu: 0.3, mem: 1.1, vsz: 98000, rss: 18000, stat: "S", start: "Jan01", time: "0:20", command: "nginx: worker process" }, + { pid: 988, user: "root", cpu: 0, mem: 0.2, vsz: 15400, rss: 6000, stat: "Ss", start: "Jan01", time: "0:00", command: "sshd: /usr/sbin/sshd -D" }, + { pid: 1204, user: "ops", cpu: 0, mem: 0.2, vsz: 9100, rss: 4800, tty: "pts/0", stat: "Ss", start: "00:00", time: "0:00", command: "-bash" }, + { pid: 4242, user: "ops", cpu: 99.8, mem: 12.5, vsz: 2048000, rss: 410000, stat: "Rl", start: "23:41", time: "412:08", command: "/opt/tools/reindex --all --forever", ignoresTerm: true }, +]; + +const runaway: Mission = { + id: "linux-runaway-process", + difficulty: "medium", + title: "Runaway process", + brief: "One process uses all the CPU. Stop it, but leave the other services running.", + story: "The server is crawling. Something is using almost the whole CPU. Find it with ps, then stop it. Do not touch the database or the web server.", + par: 3, + hints: [ + "ps aux lists every process. Look at the %CPU column and note the PID.", + "kill PID asks the process to stop. Some programs ignore that polite request.", + "If it is still there in ps aux, force it with kill -9 PID.", + ], + files: base(), + procs: PROCS, + objectives: [ + { label: "List the processes and find the one using the CPU", done: (s) => ran(s, /\bps\b|\bpgrep\b/) }, + { label: "Stop the runaway process", done: (s) => !s.procs.some((p) => p.pid === 4242) }, + { label: "Leave the database and the web server running", done: (s) => !s.procs.some((p) => p.pid === 4242) && s.procs.some((p) => p.pid === 311) && s.procs.some((p) => p.pid === 520) }, + ], + goal: (s) => !s.procs.some((p) => p.pid === 4242) && s.procs.some((p) => p.pid === 311) && s.procs.some((p) => p.pid === 520), + solution: ["ps aux", "kill 4242", "kill -9 4242"], +}; + +const NOTES = lines("project notes", "1. ship the report", "2. call the vendor"); + +const fixPermissions: Mission = { + id: "linux-script-permissions", + difficulty: "medium", + title: "Script will not run", + brief: "backup.sh says Permission denied. Fix its permissions and run it.", + story: "The nightly backup script was copied to the server, but it will not start. Fix it, then run it once so the notes are backed up into ~/backup.", + cwd: "/home/ops/scripts", + par: 3, + hints: [ + "Run ./backup.sh and read the error. Then ls -l shows the permission letters (rw-r--r--).", + "There is no x (execute) in the letters. chmod +x adds it.", + "chmod +x backup.sh and then ./backup.sh", + ], + files: { + ...base(), + "/home/ops/scripts/backup.sh": { + content: lines("#!/bin/bash", 'echo "Starting backup..."', "cp /home/ops/data/notes.txt /home/ops/backup/notes.txt", 'echo "Backup complete"'), + mode: 0o644, + }, + "/home/ops/scripts/cleanup.sh": { content: lines("#!/bin/bash", 'echo "Cleaning..."'), mode: 0o755 }, + "/home/ops/data/notes.txt": NOTES, + "/home/ops/backup/": {}, + }, + objectives: [ + { label: "Check the permissions of backup.sh", done: (s) => ran(s, /\bls\b[^|;&]*-[a-zA-Z]*l/) || saw(s, "Permission denied") }, + { label: "Make backup.sh executable", done: (s) => ((s.fs.peek("/home/ops/scripts/backup.sh")?.mode ?? 0) & 0o100) !== 0 }, + { label: "Run it so the notes are backed up", done: (s) => s.fs.text("/home/ops/backup/notes.txt") === NOTES }, + ], + goal: (s) => ((s.fs.peek("/home/ops/scripts/backup.sh")?.mode ?? 0) & 0o100) !== 0 && s.fs.text("/home/ops/backup/notes.txt") === NOTES, + solution: ["ls -l", "chmod +x backup.sh", "./backup.sh"], +}; + +const fullDisk: Mission = { + id: "linux-full-disk", + difficulty: "medium", + title: "Who fills /var?", + brief: "The disk is 97 percent full. Find which folder directly under /var uses the most space.", + story: "An alert says the disk is almost full, and most of it is under /var. Use du to measure the folders and find the culprit. Submit its full path.", + par: 3, + hints: [ + "df -h shows how full each disk is.", + "du -sh PATH prints the total size of one folder. The * matches every folder: du -sh /var/*", + "Look for the biggest number (G is bigger than M), then submit its path, like /var/xyz", + ], + files: { + ...base(), + "/var/backups/db-2025-12-01.dump": { content: "dump", size: 1_900_000_000 }, + "/var/backups/db-2025-12-15.dump": { content: "dump", size: 1_850_000_000 }, + "/var/backups/db-2025-12-29.dump": { content: "dump", size: 1_800_000_000 }, + "/var/lib/mysql/ibdata1": { content: "db", size: 900_000_000 }, + "/var/lib/dpkg/status": "package list\n", + "/var/cache/apt/archives/libfoo.deb": { content: "deb", size: 120_000_000 }, + "/var/cache/apt/archives/libbar.deb": { content: "deb", size: 60_000_000 }, + "/var/log/syslog": { content: "log", size: 150_000_000 }, + "/var/log/app.log": { content: "log", size: 140_000_000 }, + "/var/spool/cron/": { owner: "root", mode: 0o700 }, + "/var/spool/cron/root": { content: "0 3 * * * backup\n", owner: "root", mode: 0o600 }, + "/var/tmp/scratch.txt": "scratch\n", + }, + df: [ + ["/dev/sda1", "20G", "19G", "600M", "97%", "/"], + ["tmpfs", "2.0G", "0", "2.0G", "0%", "/dev/shm"], + ], + answer: ["/var/backups"], + pathAnswer: true, + objectives: [ + { label: "Check how full the disk is", done: (s) => ran(s, /\bdf\b/) }, + { label: "Measure the folders under /var", done: (s) => ran(s, /\bdu\b/) }, + { label: "Submit the path of the biggest folder", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["df -h", "du -sh /var/*", "submit /var/backups"], +}; + +// ---------------------------------------------------------------- hard + +const topAttacker: Mission = { + id: "linux-top-attacker", + difficulty: "hard", + title: "Who is attacking?", + brief: "Find the IP address with the most failed logins in the login log.", + story: "Someone is guessing passwords. The log /var/log/auth.log has thousands of lines, and some are normal logins that you must ignore. Which IP address failed the most?", + par: 3, + hints: [ + "Keep only the failed lines first: grep 'Failed password' /var/log/auth.log", + "grep -o -E '([0-9]+\\.){3}[0-9]+' prints only the IP address of each line.", + "Then: sort | uniq -c | sort -rn | head -3 counts each IP and shows the top ones. Submit the top IP.", + ], + files: { ...base(), "/var/log/auth.log": AUTH_HARD.text }, + answer: ["203.0.113.77"], + objectives: [ + { label: "Keep only the Failed password lines", done: (s) => ran(s, /grep[^|]*failed password/i) }, + { label: "Count how often each IP address appears", done: (s) => ran(s, /uniq\s+-c/) && ran(s, /sort/) }, + { label: "Submit the IP address with the most failures", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: [ + "grep 'Failed password' /var/log/auth.log | grep -o -E '([0-9]+\\.){3}[0-9]+' | sort | uniq -c | sort -rn | head -3", + "submit 203.0.113.77", + ], +}; + +const CONF_START = lines("# orbit-web config", "name=orbit-web", "port=8080", "max_connections=50", "debug=true", "log_level=info"); + +function confLines(s: ShellState): string[] | null { + const t = s.fs.text("/home/ops/app/app.conf"); + return t === null ? null : t.split("\n").map((x) => x.trim()).filter((x) => x && !x.startsWith("#")); +} +const hasOnce = (l: string[], key: string, value: string): boolean => l.filter((x) => x.startsWith(key + "=")).length === 1 && l.includes(`${key}=${value}`); + +const editConfig: Mission = { + id: "linux-edit-config", + difficulty: "hard", + title: "Tune the config", + brief: "Edit ~/app/app.conf: max_connections=200, debug=false, and a new line cache_ttl=300. Keep every other setting.", + story: "Tonight the app goes to production. The config must change: more connections, debug off, and a cache time. There is no editor here, so use redirects and filters. Careful: > replaces a whole file.", + par: 4, + hints: [ + "echo 'cache_ttl=300' >> app.conf adds a line. One > would erase the file, so use >> to add.", + "sed -i 's/old/new/' FILE changes text inside the file. Try it for max_connections=50.", + "Or rebuild the file: grep -v removes lines, > writes to a new file, then mv it over the old one. Never write > onto the file you are reading.", + ], + files: { ...base(), "/home/ops/app/app.conf": CONF_START, "/home/ops/app/main.py": "print('hello')\n" }, + objectives: [ + { label: "max_connections is 200 (and only once)", done: (s) => { const l = confLines(s); return !!l && hasOnce(l, "max_connections", "200"); } }, + { label: "debug is false (and only once)", done: (s) => { const l = confLines(s); return !!l && hasOnce(l, "debug", "false"); } }, + { + label: "cache_ttl=300 is added and the other settings are kept", + done: (s) => { const l = confLines(s); return !!l && hasOnce(l, "cache_ttl", "300") && l.includes("name=orbit-web") && l.includes("port=8080") && l.includes("log_level=info"); }, + }, + ], + goal: (s) => { + const l = confLines(s); + return !!l && hasOnce(l, "max_connections", "200") && hasOnce(l, "debug", "false") && hasOnce(l, "cache_ttl", "300") && l.includes("name=orbit-web") && l.includes("port=8080") && l.includes("log_level=info"); + }, + solution: ["cd app", "sed -i 's/max_connections=50/max_connections=200/' app.conf", "sed -i 's/debug=true/debug=false/' app.conf", "echo cache_ttl=300 >> app.conf"], +}; + +const trail: Mission = { + id: "linux-follow-the-trail", + difficulty: "hard", + title: "Follow the trail", + brief: "Alice left a trail of notes across users and folders. Follow it to the current vault code.", + story: "Alice left the company and her notes are scattered. Start with mission.txt in your home folder and follow the trail. Some doors are locked, and some notes are old or wrong. You are in the dev group.", + groups: ["dev"], + par: 7, + hints: [ + "Read mission.txt first. Each note tells you where the next one is.", + "grep -r WORD FOLDER searches inside all files of a folder. Use it for the word HANDOVER under /srv. Two files match: trust the one from Bob.", + "In Bob's vault, grep -r CODE /home/bob/.vault shows every code with its file. Ignore the ones marked expired or draft.", + ], + files: { + ...base(), + "/home/ops/mission.txt": lines("Mission: find the current vault code.", "Alice started an audit trail before she left.", "Her first note is /home/alice/notes/note1.txt. Read it and follow the trail."), + "/home/alice/notes/note1.txt": lines("Audit trail, step 1.", "I handed this over to Bob. His handover note is somewhere under /srv.", "It contains the word HANDOVER. Use grep -r to find it."), + "/srv/shared/projects/alpha/readme.txt": "Alpha project. Nothing here.\n", + "/srv/shared/projects/beta/todo.txt": "TODO: renew certificates\n", + "/srv/shared/archive/old-handover.txt": lines("Old HANDOVER from 2023. Ignore this one.", "The vault used to be in /home/carol/vault."), + "/srv/shared/handover/bob-note.txt": { content: lines("HANDOVER note from Bob.", "I moved the vault code into my private vault folder: /home/bob/.vault", "Ignore any file marked expired or draft."), owner: "bob", group: "dev", mode: 0o640 }, + "/home/bob/": { owner: "bob", group: "dev", mode: 0o750 }, + "/home/bob/.vault/": { owner: "bob", group: "dev", mode: 0o750 }, + "/home/bob/.vault/code-2023.txt": { content: "VAULT CODE: OLD-0001 (expired)\n", owner: "bob", group: "dev", mode: 0o640, age: 400 }, + "/home/bob/.vault/code-current.txt": { content: "VAULT CODE: ORBIT-7731\n", owner: "bob", group: "dev", mode: 0o640, age: 3 }, + "/home/bob/.vault/code-new.txt": { content: "VAULT CODE: NEXT-0000 (draft, not approved)\n", owner: "bob", group: "dev", mode: 0o640, age: 1 }, + "/home/carol/": { owner: "carol", mode: 0o700 }, + "/home/carol/vault/secret.txt": { content: "carol private\n", owner: "carol", mode: 0o600 }, + }, + answer: ["ORBIT-7731"], + objectives: [ + { label: "Read Alice's first note", done: (s) => saw(s, "Audit trail, step 1") }, + { label: "Find and read Bob's handover note", done: (s) => saw(s, "HANDOVER note from Bob") }, + { label: "Open Bob's vault and find the valid code", done: (s) => saw(s, "VAULT CODE: ORBIT-7731") }, + { label: "Submit the vault code with submit", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: [ + "cat mission.txt", + "cat /home/alice/notes/note1.txt", + "grep -r HANDOVER /srv", + "cat /srv/shared/handover/bob-note.txt", + "grep -r CODE /home/bob/.vault", + "submit ORBIT-7731", + ], +}; + +const LIVE_KEY = "acme_live_51Hx9QzLmN3pRtUvWxYz2A4b"; + +const leakedSecret: Mission = { + id: "linux-leaked-secret", + difficulty: "hard", + title: "The leaked key", + brief: "A live payment key was committed by mistake. Find the file that holds it.", + story: "The payment provider warns that a live key leaked into the code. Live keys start with acme_live_ followed by 24 letters and digits. Search /srv/app, ignore test keys and placeholders, and submit the path of the file with the real key.", + par: 3, + hints: [ + "grep -r searches every file in a folder. Try: grep -r acme_live_ /srv/app", + "Some hits are only examples. The real key has 24 letters and digits right after acme_live_.", + "A stricter search: grep -rE 'acme_live_[A-Za-z0-9]{24}' /srv/app. Then: submit THE-PATH", + ], + files: { + ...base(), + "/srv/app/src/main.py": lines("import os", 'API_KEY = os.environ["API_KEY"]', "def run():", " print('running')"), + "/srv/app/src/config.py": lines('SECRET_KEY = "changeme"', 'PAY_KEY = "acme_test_4eC39HqLyjWDarjtT1zdp7dc"'), + "/srv/app/tests/fixtures.py": lines('LIVE_KEY_PLACEHOLDER = "acme_live_REPLACE_ME_BEFORE_USE"'), + "/srv/app/docs/payments.md": lines("# Payments", "Live keys look like acme_live_<24 characters>. Never commit them."), + "/srv/app/.env.example": lines("DB_URL=postgres://localhost/app", "PAY_KEY=acme_test_xxxxxxxxxxxxxxxxxxxxxxxx", "SECRET_KEY=changeme"), + "/srv/app/old/deploy.env.bak": lines("# backup of the old deploy settings", "DB_URL=postgres://db.internal/app", `PAY_KEY=${LIVE_KEY}`, "DEBUG=false"), + "/srv/secrets/": { owner: "root", mode: 0o700 }, + "/srv/secrets/vault.txt": { content: "locked\n", owner: "root", mode: 0o600 }, + }, + answer: ["/srv/app/old/deploy.env.bak"], + pathAnswer: true, + objectives: [ + { label: "Search the code for acme_live_", done: (s) => ran(s, /grep[^|;&]*sk_live/) }, + { label: "Spot the real key among the placeholders", done: (s) => saw(s, LIVE_KEY) }, + { label: "Submit the path of the file with the key", done: (s) => s.answerOk }, + ], + goal: (s) => s.answerOk, + solution: ["grep -rE 'acme_live_[A-Za-z0-9]{24}' /srv/app", "submit /srv/app/old/deploy.env.bak"], +}; + +const PROD_YML = lines("version: 8", "replicas: 4", "debug: false"); + +const restoreFile: Mission = { + id: "linux-restore-backup", + difficulty: "hard", + title: "Oops, deleted", + brief: "prod.yml was deleted from ~/site/config. Restore the newest copy from the backups.", + story: "A cleanup script removed ~/site/config/prod.yml. The backups are in /backups (daily and weekly, with the date in the folder name). Restore the newest copy that still has the file, and do not damage the backups.", + par: 3, + hints: [ + "find /backups -name prod.yml shows every copy of the file.", + "The date is in the folder name. The newest daily folder that has the file is the best copy. The 12-31 backup was taken after the deletion.", + "cp SOURCE ~/site/config/ puts a copy back. Use cat to check it says version 8.", + ], + files: { + ...base(), + "/home/ops/site/index.html": lines("

Orbit

"), + "/home/ops/site/config/app.yml": lines("name: orbit", "port: 80"), + "/backups/weekly/2025-12-21/site/config/prod.yml": { content: lines("version: 3", "replicas: 2"), age: 11 }, + "/backups/daily/2025-12-27/site/config/prod.yml": { content: lines("version: 5", "replicas: 3"), age: 5 }, + "/backups/daily/2025-12-28/site/config/prod.yml": { content: lines("version: 6", "replicas: 3"), age: 4 }, + "/backups/daily/2025-12-29/site/config/prod.yml": { content: lines("version: 7", "replicas: 4"), age: 3 }, + "/backups/daily/2025-12-30/site/config/prod.yml": { content: PROD_YML, age: 2 }, + "/backups/daily/2025-12-31/site/config/app.yml": { content: lines("name: orbit", "port: 80"), age: 1 }, + }, + objectives: [ + { label: "Find the copies of prod.yml in /backups", done: (s) => saw(s, "2025-12-30/site/config/prod.yml") || saw(s, "2025-12-30") }, + { label: "Put prod.yml back in ~/site/config", done: (s) => exists(s, "/home/ops/site/config/prod.yml") }, + { + label: "It is the newest version, and the backups are untouched", + done: (s) => s.fs.text("/home/ops/site/config/prod.yml") === PROD_YML && s.fs.text("/backups/daily/2025-12-30/site/config/prod.yml") === PROD_YML, + }, + ], + goal: (s) => s.fs.text("/home/ops/site/config/prod.yml") === PROD_YML && s.fs.text("/backups/daily/2025-12-30/site/config/prod.yml") === PROD_YML, + solution: ["find /backups -name prod.yml", "cp /backups/daily/2025-12-30/site/config/prod.yml ~/site/config/"], +}; + +/** The pool. A day shows one mission per difficulty; each tier rotates through its missions. */ +export const MISSIONS: Mission[] = [ + hiddenNote, configPort, countLines, biggestFile, + failedLogins, oldTmp, runaway, fixPermissions, fullDisk, + topAttacker, editConfig, trail, leakedSecret, restoreFile, +]; + +const BY_ID = new Map(MISSIONS.map((m) => [m.id, m])); + +export function missionById(id: unknown): Mission | null { + return typeof id === "string" ? BY_ID.get(id) ?? null : null; +} diff --git a/server/src/shared/games/linux/model.ts b/server/src/shared/games/linux/model.ts new file mode 100644 index 00000000..36e7764b --- /dev/null +++ b/server/src/shared/games/linux/model.ts @@ -0,0 +1,91 @@ +// Shared types for the Linux Command Explorer engine. +import type { Difficulty } from "../types.js"; +import type { FsSpec, User, VFS } from "./fs.js"; + +export type Proc = { + pid: number; + user: string; + cpu: number; + mem: number; + vsz: number; + rss: number; + tty?: string; + stat: string; + start: string; + time: string; + command: string; + /** A gentle `kill` (TERM) does not stop it. Only `kill -9` does. */ + ignoresTerm?: boolean; +}; + +/** One row of `df -h`: filesystem, size, used, avail, use%, mount point. */ +export type DfRow = [string, string, string, string, string, string]; + +/** Everything a goal check may look at. It is the whole state of the shell after a command. */ +export type ShellState = { + fs: VFS; + user: User; + hostname: string; + cwd: string; + oldpwd: string; + env: Record; + procs: Proc[]; + df: DfRow[]; + /** Every command line the player ran, in order (only the ones the shell accepted). */ + history: string[]; + /** All the text shown on the terminal so far (the end of it, when it gets long). */ + shown: string; + /** The player gave the right answer with `submit`. */ + answerOk: boolean; + /** Scripts that were run, with their exit codes. */ + executed: Array<{ path: string; code: number }>; +}; + +export type Objective = { + label: string; + /** Once true, the shell keeps it ticked. */ + done: (s: ShellState) => boolean; +}; + +export type Mission = { + id: string; + difficulty: Difficulty; + title: string; + brief: string; + story: string; + /** The number of commands a good player needs. Three stars need this many or fewer. */ + par: number; + hints: string[]; + files: FsSpec; + /** Where the player starts. Default is the home folder. */ + cwd?: string; + /** Extra groups for the player (the player is "ops"). */ + groups?: string[]; + procs?: Proc[]; + df?: DfRow[]; + /** For an answer mission: the accepted answers for `submit`. */ + answer?: string[]; + /** The answer is a path, so "backups" and "/var/backups/" both count. */ + pathAnswer?: boolean; + objectives: Objective[]; + /** The mission is done when this is true. For an answer mission it is `s.answerOk`. */ + goal: (s: ShellState) => boolean; + /** A list of commands that solves the mission. The tests replay it. */ + solution: string[]; +}; + +/** What a command can do while it runs. */ +export type Ctx = { + st: ShellState; + args: string[]; + stdin: string | null; + /** The output goes to the screen, not into a pipe or a file. */ + tty: boolean; + out(text: string): void; + /** One line on standard error (a newline is added). */ + err(message: string): void; + /** Run another command and capture what it prints. */ + exec(argv: string[], stdin: string | null): { code: number; out: string }; +}; + +export type Cmd = (c: Ctx) => number; diff --git a/server/src/shared/games/linux/regex.ts b/server/src/shared/games/linux/regex.ts new file mode 100644 index 00000000..8c84e89e --- /dev/null +++ b/server/src/shared/games/linux/regex.ts @@ -0,0 +1,495 @@ +// Pattern matching for grep, sed and find. The regular expression engine is a small NFA simulator +// (no backtracking), so a hostile pattern cannot hang the game. A work budget stops anything big. + +export class BudgetError extends Error {} + +let budgetLeft = 0; + +/** Start a new work allowance. The shell calls this before every command line. */ +export function resetBudget(units: number): void { + budgetLeft = units; +} + +export function spend(units = 1): void { + budgetLeft -= units; + if (budgetLeft < 0) throw new BudgetError("budget"); +} + +// ---------------------------------------------------------------- glob + +type GlobTok = { t: "lit"; c: string } | { t: "one" } | { t: "star" } | { t: "set"; neg: boolean; items: Array<[string, string]> }; + +function globTokens(pattern: string): GlobTok[] { + const toks: GlobTok[] = []; + for (let i = 0; i < pattern.length; i++) { + const ch = pattern[i]!; + if (ch === "\\" && i + 1 < pattern.length) { + toks.push({ t: "lit", c: pattern[++i]! }); + } else if (ch === "*") { + if (toks.length === 0 || toks[toks.length - 1]!.t !== "star") toks.push({ t: "star" }); + } else if (ch === "?") { + toks.push({ t: "one" }); + } else if (ch === "[") { + let j = i + 1; + let neg = false; + if (pattern[j] === "!" || pattern[j] === "^") { + neg = true; + j++; + } + const items: Array<[string, string]> = []; + let first = true; + let closed = false; + while (j < pattern.length) { + const c = pattern[j]!; + if (c === "]" && !first) { + closed = true; + break; + } + first = false; + if (pattern[j + 1] === "-" && j + 2 < pattern.length && pattern[j + 2] !== "]") { + items.push([c, pattern[j + 2]!]); + j += 3; + } else { + items.push([c, c]); + j++; + } + } + if (closed) { + toks.push({ t: "set", neg, items }); + i = j; + } else toks.push({ t: "lit", c: "[" }); + } else toks.push({ t: "lit", c: ch }); + } + return toks; +} + +function globOne(tok: GlobTok, ch: string): boolean { + if (tok.t === "lit") return tok.c === ch; + if (tok.t === "one") return true; + if (tok.t === "set") return tok.items.some(([a, b]) => ch >= a && ch <= b) !== tok.neg; + return false; +} + +/** Shell and `find -name` patterns: * ? [abc] [a-z] [!x]. */ +export function globMatch(pattern: string, text: string, ignoreCase = false): boolean { + const toks = globTokens(ignoreCase ? pattern.toLowerCase() : pattern); + const s = ignoreCase ? text.toLowerCase() : text; + let p = 0; + let i = 0; + let starP = -1; + let starI = 0; + while (i < s.length) { + spend(1); + const tok = toks[p]; + if (tok && tok.t === "star") { + starP = p++; + starI = i; + } else if (tok && globOne(tok, s[i]!)) { + p++; + i++; + } else if (starP >= 0) { + p = starP + 1; + i = ++starI; + } else return false; + } + while (toks[p] && toks[p]!.t === "star") p++; + return p === toks.length; +} + +export function hasGlob(text: string): boolean { + return /[*?[]/.test(text); +} + +// ---------------------------------------------------------------- regular expressions + +type Ast = + | { t: "char"; c: string } + | { t: "any" } + | { t: "set"; neg: boolean; items: Array<[string, string]> } + | { t: "cat"; a: Ast[] } + | { t: "alt"; a: Ast[] } + | { t: "rep"; n: Ast; min: number; max: number } + | { t: "assert"; k: "bol" | "eol" | "wordb" | "nwordb" | "wstart" | "wend" | "nwprev" | "nwnext" }; + +const CLASSES: Record boolean> = { + alpha: (c) => /[A-Za-z]/.test(c), + digit: (c) => /[0-9]/.test(c), + alnum: (c) => /[A-Za-z0-9]/.test(c), + upper: (c) => /[A-Z]/.test(c), + lower: (c) => /[a-z]/.test(c), + space: (c) => /\s/.test(c), + blank: (c) => c === " " || c === "\t", + punct: (c) => /[!-/:-@[-`{-~]/.test(c), + xdigit: (c) => /[0-9A-Fa-f]/.test(c), + word: (c) => /[A-Za-z0-9_]/.test(c), +}; + +const isWord = (c: string | undefined) => c !== undefined && /[A-Za-z0-9_]/.test(c); + +class RegexError extends Error {} + +type Tok = { k: "lit" | "op" | "cls" | "end"; c: string; len: number }; + +class Parser { + i = 0; + constructor( + private src: string, + private ere: boolean, + ) {} + + private peek(): Tok { + const s = this.src; + if (this.i >= s.length) return { k: "end", c: "", len: 0 }; + const ch = s[this.i]!; + if (ch === "\\") { + if (this.i + 1 >= s.length) throw new RegexError("Trailing backslash"); + const nx = s[this.i + 1]!; + if (!this.ere && "(){}|+?".includes(nx)) return { k: "op", c: nx, len: 2 }; + if ("wWsSbB<>".includes(nx)) return { k: "cls", c: nx, len: 2 }; + if (nx >= "1" && nx <= "9") throw new RegexError("Back references are not supported here"); + return { k: "lit", c: nx, len: 2 }; + } + if (this.ere && "(){}|+?".includes(ch)) return { k: "op", c: ch, len: 1 }; + if ("*.[^$".includes(ch)) return { k: "op", c: ch, len: 1 }; + return { k: "lit", c: ch, len: 1 }; + } + + parse(): Ast { + const ast = this.alt(0); + if (this.i < this.src.length) throw new RegexError("Unmatched ) or \\)"); + return ast; + } + + private alt(depth: number): Ast { + const parts = [this.cat(depth)]; + for (;;) { + const t = this.peek(); + if (t.k === "op" && t.c === "|") { + this.i += t.len; + parts.push(this.cat(depth)); + } else break; + } + return parts.length === 1 ? parts[0]! : { t: "alt", a: parts }; + } + + private cat(depth: number): Ast { + const items: Ast[] = []; + for (;;) { + const t = this.peek(); + if (t.k === "end") break; + if (t.k === "op" && t.c === "|") break; + if (t.k === "op" && t.c === ")") { + if (depth > 0) break; + if (this.ere) { + // A lone ")" is a plain character in ERE. + this.i += t.len; + items.push({ t: "char", c: ")" }); + continue; + } + throw new RegexError("Unmatched ) or \\)"); + } + let atom = this.atom(items.length === 0, depth); + for (;;) { + const q = this.peek(); + if (q.k !== "op") break; + if (q.c === "*") { + this.i += q.len; + atom = { t: "rep", n: atom, min: 0, max: Infinity }; + } else if (q.c === "+") { + this.i += q.len; + atom = { t: "rep", n: atom, min: 1, max: Infinity }; + } else if (q.c === "?") { + this.i += q.len; + atom = { t: "rep", n: atom, min: 0, max: 1 }; + } else if (q.c === "{") { + const range = this.interval(q.len); + if (!range) break; + atom = { t: "rep", n: atom, min: range[0], max: range[1] }; + } else break; + } + items.push(atom); + } + return items.length === 1 ? items[0]! : { t: "cat", a: items }; + } + + private interval(openLen: number): [number, number] | null { + const m = /^(\d*)(,(\d*))?/.exec(this.src.slice(this.i + openLen)); + if (!m || (m[1] === "" && m[3] === undefined)) return null; + const after = this.i + openLen + m[0].length; + const close = this.ere ? this.src[after] === "}" : this.src.slice(after, after + 2) === "\\}"; + if (!close) { + if (this.ere) return null; + throw new RegexError("Unmatched { or \\{"); + } + const min = m[1] === "" ? 0 : Number(m[1]); + const max = m[2] === undefined ? min : m[3] === "" ? Infinity : Number(m[3]); + if (min > 100 || (max !== Infinity && max > 100) || max < min) throw new RegexError("Invalid content of \\{\\}"); + this.i = after + (this.ere ? 1 : 2); + return [min, max]; + } + + private atom(first: boolean, depth: number): Ast { + const t = this.peek(); + this.i += t.len; + if (t.k === "lit") return { t: "char", c: t.c }; + if (t.k === "cls") { + switch (t.c) { + case "w": return { t: "set", neg: false, items: [["a", "z"], ["A", "Z"], ["0", "9"], ["_", "_"]] }; + case "W": return { t: "set", neg: true, items: [["a", "z"], ["A", "Z"], ["0", "9"], ["_", "_"]] }; + case "s": return { t: "set", neg: false, items: [[" ", " "], ["\t", "\t"]] }; + case "S": return { t: "set", neg: true, items: [[" ", " "], ["\t", "\t"]] }; + case "b": return { t: "assert", k: "wordb" }; + case "B": return { t: "assert", k: "nwordb" }; + case "<": return { t: "assert", k: "wstart" }; + default: return { t: "assert", k: "wend" }; + } + } + // t.k === "op" from here + switch (t.c) { + case ".": return { t: "any" }; + case "[": return this.bracket(); + case "^": { + if (this.ere || first) return { t: "assert", k: "bol" }; + return { t: "char", c: "^" }; + } + case "$": { + const nx = this.peek(); + const atEnd = nx.k === "end" || (nx.k === "op" && (nx.c === "|" || nx.c === ")")); + if (this.ere || atEnd) return { t: "assert", k: "eol" }; + return { t: "char", c: "$" }; + } + case "*": return { t: "char", c: "*" }; + case "(": { + const inner = this.alt(depth + 1); + const close = this.peek(); + if (!(close.k === "op" && close.c === ")")) throw new RegexError("Unmatched ( or \\("); + this.i += close.len; + return inner; + } + case "{": return { t: "char", c: "{" }; + default: return { t: "char", c: t.c }; + } + } + + private bracket(): Ast { + const s = this.src; + let neg = false; + if (s[this.i] === "^") { + neg = true; + this.i++; + } + const items: Array<[string, string]> = []; + let first = true; + for (;;) { + if (this.i >= s.length) throw new RegexError("Unmatched [, [^, [:, [., or [="); + const c = s[this.i]!; + if (c === "]" && !first) { + this.i++; + break; + } + first = false; + if (c === "[" && s[this.i + 1] === ":") { + const end = s.indexOf(":]", this.i + 2); + if (end < 0) throw new RegexError("Unmatched [, [^, [:, [., or [="); + const name = s.slice(this.i + 2, end); + const fn = CLASSES[name]; + if (!fn) throw new RegexError("Invalid character class name"); + for (let code = 1; code < 128; code++) { + const ch = String.fromCharCode(code); + if (fn(ch)) items.push([ch, ch]); + } + this.i = end + 2; + continue; + } + if (s[this.i + 1] === "-" && this.i + 2 < s.length && s[this.i + 2] !== "]") { + if (s[this.i + 2]! < c) throw new RegexError("Invalid range end"); + items.push([c, s[this.i + 2]!]); + this.i += 3; + } else { + items.push([c, c]); + this.i++; + } + } + return { t: "set", neg, items }; + } +} + +// An NFA built from the tree. State kinds: c char, a any, s set, p split, x assert, m match. +type State = { k: "c" | "a" | "s" | "p" | "x" | "m"; c?: string; set?: Extract; a: number; b: number; as?: string }; + +const MAX_STATES = 4000; + +function build(ast: Ast, ignoreCase: boolean): { states: State[]; start: number } { + const states: State[] = []; + const add = (s: State): number => { + if (states.length >= MAX_STATES) throw new RegexError("Regular expression too big"); + states.push(s); + return states.length - 1; + }; + const match = add({ k: "m", a: -1, b: -1 }); + const comp = (n: Ast, next: number): number => { + switch (n.t) { + case "char": return add({ k: "c", c: ignoreCase ? n.c.toLowerCase() : n.c, a: next, b: -1 }); + case "any": return add({ k: "a", a: next, b: -1 }); + case "set": return add({ k: "s", set: n, a: next, b: -1 }); + case "assert": return add({ k: "x", as: n.k, a: next, b: -1 }); + case "cat": { + let cur = next; + for (let i = n.a.length - 1; i >= 0; i--) cur = comp(n.a[i]!, cur); + return cur; + } + case "alt": { + let cur = comp(n.a[n.a.length - 1]!, next); + for (let i = n.a.length - 2; i >= 0; i--) cur = add({ k: "p", a: comp(n.a[i]!, next), b: cur }); + return cur; + } + case "rep": { + let cur = next; + if (n.max === Infinity) { + const split = add({ k: "p", a: -1, b: next }); + states[split]!.a = comp(n.n, split); + cur = split; + } else { + for (let i = 0; i < n.max - n.min; i++) cur = add({ k: "p", a: comp(n.n, cur), b: next }); + } + for (let i = 0; i < n.min; i++) cur = comp(n.n, cur); + return cur; + } + } + }; + return { states, start: comp(ast, match) }; +} + +export type Matcher = { + /** Does the pattern match anywhere in the text? */ + test(text: string): boolean; + /** The leftmost, longest match at or after `from`, as [start, end], or null. */ + find(text: string, from: number): [number, number] | null; +}; + +function setHas(set: Extract, ch: string, ignoreCase: boolean): boolean { + const hit = (c: string) => set.items.some(([a, b]) => c >= a && c <= b); + let r = hit(ch); + if (!r && ignoreCase) r = hit(ch.toLowerCase()) || hit(ch.toUpperCase()); + return r !== set.neg; +} + +function makeMatcher(ast: Ast, ignoreCase: boolean): Matcher { + const { states, start } = build(ast, ignoreCase); + const n = states.length; + const seen = new Int32Array(n).fill(-1); + let stamp = 0; + + const assertOk = (kind: string, s: string, p: number): boolean => { + const prev = isWord(s[p - 1]); + const next = isWord(s[p]); + switch (kind) { + case "bol": return p === 0; + case "eol": return p === s.length; + case "wordb": return prev !== next; + case "nwordb": return prev === next; + case "wstart": return !prev && next; + case "wend": return prev && !next; + case "nwprev": return !prev; + default: return !next; + } + }; + + // Add a state and everything reachable without reading a character. + const close = (list: number[], st: number, s: string, p: number): boolean => { + let matched = false; + const stack = [st]; + while (stack.length) { + const id = stack.pop()!; + if (id < 0 || seen[id] === stamp) continue; + seen[id] = stamp; + spend(1); + const state = states[id]!; + if (state.k === "p") { + stack.push(state.b, state.a); + } else if (state.k === "x") { + if (assertOk(state.as!, s, p)) stack.push(state.a); + } else if (state.k === "m") { + matched = true; + list.push(id); + } else list.push(id); + } + return matched; + }; + + const consumes = (state: State, ch: string): boolean => { + if (state.k === "a") return true; + if (state.k === "c") return (ignoreCase ? ch.toLowerCase() : ch) === state.c; + if (state.k === "s") return setHas(state.set!, ch, ignoreCase); + return false; + }; + + return { + test(s: string): boolean { + let cur: number[] = []; + for (let p = 0; p <= s.length; p++) { + // A new match may begin at every position. + stamp++; + const next: number[] = []; + let hit = false; + for (const id of cur) if (close(next, id, s, p)) hit = true; + if (close(next, start, s, p)) hit = true; + if (hit) return true; + cur = next; + if (p === s.length) break; + const ch = s[p]!; + const moved: number[] = []; + for (const id of cur) { + const state = states[id]!; + if (state.k !== "m" && consumes(state, ch)) moved.push(state.a); + } + cur = moved; + } + return false; + }, + find(s: string, from: number): [number, number] | null { + for (let begin = from; begin <= s.length; begin++) { + let best = -1; + stamp++; + let cur: number[] = []; + if (close(cur, start, s, begin)) best = begin; + for (let p = begin; p < s.length && cur.length; p++) { + const ch = s[p]!; + const moved: number[] = []; + for (const id of cur) { + const state = states[id]!; + if (state.k !== "m" && consumes(state, ch)) moved.push(state.a); + } + stamp++; + cur = []; + for (const id of moved) { + if (close(cur, id, s, p + 1)) best = p + 1; + } + } + if (best >= 0) return [begin, best]; + } + return null; + }, + }; +} + +export type PatternOptions = { ere: boolean; ignoreCase: boolean; fixed?: boolean; word?: boolean; line?: boolean }; + +/** Compile one or more patterns (they are joined with "or"). Returns an error text on a bad pattern. */ +export function compilePatterns(patterns: string[], opts: PatternOptions): Matcher | { error: string } { + try { + const alts: Ast[] = patterns.map((p) => { + if (p.length > 500) throw new RegexError("Regular expression too big"); + if (opts.fixed) return { t: "cat", a: [...p].map((c) => ({ t: "char", c }) as Ast) } as Ast; + return new Parser(p, opts.ere).parse(); + }); + let ast: Ast = alts.length === 1 ? alts[0]! : { t: "alt", a: alts }; + if (opts.line) ast = { t: "cat", a: [{ t: "assert", k: "bol" }, ast, { t: "assert", k: "eol" }] }; + else if (opts.word) ast = { t: "cat", a: [{ t: "assert", k: "nwprev" }, ast, { t: "assert", k: "nwnext" }] }; + return makeMatcher(ast, opts.ignoreCase); + } catch (error) { + if (error instanceof RegexError) return { error: error.message }; + if (error instanceof BudgetError) throw error; + return { error: "Invalid regular expression" }; + } +} diff --git a/server/src/shared/games/linux/shell.ts b/server/src/shared/games/linux/shell.ts new file mode 100644 index 00000000..95b5136b --- /dev/null +++ b/server/src/shared/games/linux/shell.ts @@ -0,0 +1,941 @@ +/* eslint-disable no-control-regex -- the shell engines reject or use control characters on purpose */ +// The practice shell: reads a command line, runs it on the virtual server, and keeps score for the +// mission. It runs one command at a time, so the browser can show the output as the player types. +// Nothing here touches the real file system, real processes, the clock or Math.random. +import { COMMANDS, NOT_HERE, SHELL_TIPS, USAGE } from "./commands.js"; +import { ERR_TEXT, NOW, VFS, can, joinPath, normalizePath, type VNode } from "./fs.js"; +import type { Ctx, Mission, Proc, ShellState } from "./model.js"; +import { BudgetError, globMatch, hasGlob, resetBudget, spend } from "./regex.js"; + +export const MAX_LINE = 500; +export const MAX_COMMANDS = 250; +const MAX_OUTPUT_LINES = 1500; +const MAX_BUFFER = 300_000; +const MAX_DEPTH = 4; +const WORK_BUDGET = 3_000_000; + +export type OutLine = { kind: "out" | "err" | "sys"; text: string }; +export type RunResult = { + lines: OutLine[]; + clear: boolean; + /** False when the shell refused the line (empty, too long, too many commands). It is not recorded. */ + accepted: boolean; + /** Indexes of objectives that became done with this command. */ + newlyDone: number[]; + solved: boolean; +}; +export type Progress = { done: boolean[]; solved: boolean; commands: number; hints: number; hintsTotal: number }; + +type Sink = { out(text: string): void; err(text: string): void }; + +// ---------------------------------------------------------------- parsing + +type Token = { t: "word"; raw: string } | { t: "op"; op: string }; +type Redir = { op: ">" | ">>" | "<" | "2>" | "2>>" | "2>&1"; target: string | null }; +type SimpleCmd = { words: string[]; redirs: Redir[] }; +type ListItem = { pipe: SimpleCmd[]; next: "&&" | "||" | ";" | null }; + +class SyntaxErr extends Error {} + +/** Find the ")" that closes a "$(" whose opening bracket is just before `start`. */ +function findClose(raw: string, start: number): number { + let depth = 1; + for (let i = start; i < raw.length; i++) { + const ch = raw[i]!; + if (ch === "'") { + const e = raw.indexOf("'", i + 1); + if (e < 0) return -1; + i = e; + } else if (ch === '"') { + for (i++; i < raw.length && raw[i] !== '"'; i++) if (raw[i] === "\\") i++; + } else if (ch === "\\") i++; + else if (ch === "(") depth++; + else if (ch === ")" && --depth === 0) return i; + } + return -1; +} + +function tokenize(line: string): Token[] { + const tokens: Token[] = []; + let cur = ""; + let has = false; + let plain = true; // the word so far has no quotes or escapes + const flush = () => { + if (has) tokens.push({ t: "word", raw: cur }); + cur = ""; + has = false; + plain = true; + }; + const unclosed = (q: string) => new SyntaxErr(`unexpected EOF while looking for matching \`${q}'`); + for (let i = 0; i < line.length; i++) { + const ch = line[i]!; + if (ch === " " || ch === "\t") flush(); + else if (ch === "#" && !has) break; + else if (ch === "'") { + const e = line.indexOf("'", i + 1); + if (e < 0) throw unclosed("'"); + cur += line.slice(i, e + 1); + i = e; + has = true; + plain = false; + } else if (ch === '"') { + let j = i + 1; + for (; j < line.length && line[j] !== '"'; j++) { + if (line[j] === "\\") j++; + else if (line[j] === "$" && line[j + 1] === "(") { + const e = findClose(line, j + 2); + if (e < 0) throw unclosed(")"); + j = e; + } + } + if (j >= line.length) throw unclosed('"'); + cur += line.slice(i, j + 1); + i = j; + has = true; + plain = false; + } else if (ch === "\\") { + cur += ch + (line[i + 1] ?? ""); + i++; + has = true; + plain = false; + } else if (ch === "$" && line[i + 1] === "(") { + const e = findClose(line, i + 2); + if (e < 0) throw unclosed(")"); + cur += line.slice(i, e + 1); + i = e; + has = true; + plain = false; + } else if (ch === "`") { + const e = line.indexOf("`", i + 1); + if (e < 0) throw unclosed("`"); + cur += line.slice(i, e + 1); + i = e; + has = true; + plain = false; + } else if (ch === "|" || ch === "&" || ch === ";" || ch === ">" || ch === "<") { + if (ch === ">" && has && plain && cur === "2") { + cur = ""; + has = false; + if (line[i + 1] === "&" && line[i + 2] === "1") { + tokens.push({ t: "op", op: "2>&1" }); + i += 2; + } else if (line[i + 1] === ">") { + tokens.push({ t: "op", op: "2>>" }); + i++; + } else tokens.push({ t: "op", op: "2>" }); + continue; + } + flush(); + const two = line.slice(i, i + 2); + if (two === "||" || two === "&&" || two === ">>") { + tokens.push({ t: "op", op: two }); + i++; + } else if (ch === "&") throw new SyntaxErr("background jobs (&) are not supported in this practice shell"); + else tokens.push({ t: "op", op: ch }); + } else { + cur += ch; + has = true; + } + } + flush(); + return tokens; +} + +function parseLine(line: string): ListItem[] { + const tokens = tokenize(line); + const items: ListItem[] = []; + let pipe: SimpleCmd[] = []; + let cmd: SimpleCmd = { words: [], redirs: [] }; + let pending: Redir | null = null; + const near = (op: string) => new SyntaxErr(`syntax error near unexpected token \`${op}'`); + const endCmd = (op: string) => { + if (cmd.words.length === 0 && cmd.redirs.length === 0) throw near(op); + pipe.push(cmd); + cmd = { words: [], redirs: [] }; + }; + for (const tok of tokens) { + if (tok.t === "word") { + if (pending) { + pending.target = tok.raw; + pending = null; + } else cmd.words.push(tok.raw); + continue; + } + const op = tok.op; + if (pending) throw near(op); + if (op === ">" || op === ">>" || op === "<" || op === "2>" || op === "2>>") { + pending = { op, target: null }; + cmd.redirs.push(pending); + } else if (op === "2>&1") cmd.redirs.push({ op, target: null }); + else if (op === "|") endCmd("|"); + else { + // && || ; + if (cmd.words.length === 0 && cmd.redirs.length === 0 && pipe.length === 0) { + if (op === ";" && items.length > 0) continue; + throw near(op); + } + endCmd(op); + items.push({ pipe, next: op as "&&" | "||" | ";" }); + pipe = []; + } + } + if (pending) throw new SyntaxErr("syntax error near unexpected token `newline'"); + if (cmd.words.length || cmd.redirs.length) endCmd("newline"); + else if (pipe.length) throw near("newline"); + if (pipe.length) items.push({ pipe, next: null }); + const last = items[items.length - 1]; + if (last && (last.next === "&&" || last.next === "||")) throw new SyntaxErr("syntax error: unexpected end of file"); + return items; +} + +// ---------------------------------------------------------------- the shell + +const DEFAULT_PROCS: Proc[] = [ + { pid: 1, user: "root", cpu: 0, mem: 0.1, vsz: 168000, rss: 11000, stat: "Ss", start: "Jan01", time: "0:03", command: "/sbin/init" }, + { pid: 77, user: "root", cpu: 0, mem: 0.1, vsz: 8500, rss: 2200, stat: "Ss", start: "Jan01", time: "0:00", command: "/usr/sbin/cron -f" }, + { pid: 988, user: "root", cpu: 0, mem: 0.2, vsz: 15400, rss: 6000, stat: "Ss", start: "Jan01", time: "0:00", command: "sshd: /usr/sbin/sshd -D" }, + { pid: 1204, user: "ops", cpu: 0, mem: 0.2, vsz: 9100, rss: 4800, tty: "pts/0", stat: "Ss", start: "00:00", time: "0:00", command: "-bash" }, +]; + +const FREE = new Set(["hint", "help", "commands", "man", "clear", "history"]); +const BUILTINS = ["hint", "submit", "history", "clear", "help", "commands", "man", "exit", "logout", "bash", "sh"]; +const SENTINEL: Record = { "*": "\u0001", "?": "\u0002", "[": "\u0003" }; +const UNSENTINEL = (s: string) => s.replace(/\u0001/g, "*").replace(/\u0002/g, "?").replace(/\u0003/g, "["); +const quoteGlob = (s: string) => s.replace(/[*?[]/g, (m) => SENTINEL[m]!); + +function normalizeAnswer(text: string): string { + return text.trim().replace(/^["']|["']$/g, "").replace(/\s+/g, " ").toLowerCase(); +} + +export class Shell { + readonly st: ShellState; + readonly mission: Mission; + private hintsShown = 0; + private counted = 0; + private done: boolean[]; + private solved = false; + private solvedCounted = 0; + private solvedHints = 0; + private depth = 0; + private lines: OutLine[] = []; + private cleared = false; + private lineCap = false; + private lastCode = 0; + + constructor(mission: Mission) { + this.mission = mission; + const home = "/home/ops"; + const fs = new VFS(mission.files); + this.st = { + fs, + user: { name: "ops", groups: ["ops", ...(mission.groups ?? [])] }, + hostname: "orbit-01", + cwd: normalizePath("/", mission.cwd ?? home), + oldpwd: home, + env: { HOME: home, USER: "ops", LOGNAME: "ops", SHELL: "/bin/bash", HOSTNAME: "orbit-01", PWD: mission.cwd ?? home, PATH: "/usr/local/bin:/usr/bin:/bin", LANG: "C.UTF-8", TERM: "xterm" }, + procs: (mission.procs ?? DEFAULT_PROCS).map((p) => ({ ...p })), + df: mission.df ?? [ + ["/dev/sda1", "40G", "18G", "20G", "48%", "/"], + ["tmpfs", "2.0G", "0", "2.0G", "0%", "/dev/shm"], + ["/dev/sdb1", "100G", "62G", "38G", "62%", "/srv"], + ], + history: [], + shown: "", + answerOk: false, + executed: [], + }; + this.st.env.PWD = this.st.cwd; + this.done = mission.objectives.map(() => false); + } + + // ---- what the UI reads + + prompt(): string { + const home = this.st.env.HOME ?? "/"; + let path = this.st.cwd; + if (path === home) path = "~"; + else if (path.startsWith(home + "/")) path = "~" + path.slice(home.length); + if (path.length > 18) { + const parts = path.split("/").filter(Boolean); + path = "…/" + parts.slice(-2).join("/"); + } + return `${this.st.user.name}:${path}$`; + } + + progress(): Progress { + return { done: [...this.done], solved: this.solved, commands: this.solved ? this.solvedCounted : this.counted, hints: this.solved ? this.solvedHints : this.hintsShown, hintsTotal: this.mission.hints.length }; + } + + /** Commands that counted toward par when the mission was solved (or so far). */ + get commandCount(): number { + return this.solved ? this.solvedCounted : this.counted; + } + + get hintCount(): number { + return this.solved ? this.solvedHints : this.hintsShown; + } + + get isSolved(): boolean { + return this.solved; + } + + get commands(): string[] { + return [...this.st.history]; + } + + /** Words Tab can finish: command names, then names of files and folders near the player. */ + completions(): string[] { + const names = new Set([...Object.keys(COMMANDS), ...BUILTINS]); + const add = (node: VNode, prefix: string) => { + for (const child of node.children.values()) names.add(prefix + child.name + (child.kind === "dir" ? "/" : "")); + }; + const cwdNode = this.st.fs.peek(this.st.cwd); + if (cwdNode && cwdNode.kind === "dir" && can(this.st.user, cwdNode, 4)) { + add(cwdNode, ""); + for (const child of cwdNode.children.values()) { + if (child.kind === "dir" && can(this.st.user, child, 4) && can(this.st.user, child, 1)) add(child, child.name + "/"); + else if (child.kind === "file" && (child.mode & 0o100) !== 0) names.add("./" + child.name); + } + } + add(this.st.fs.root, "/"); + for (const top of this.st.fs.root.children.values()) { + if (top.kind === "dir" && can(this.st.user, top, 4) && can(this.st.user, top, 1)) add(top, "/" + top.name + "/"); + } + return [...names].sort().slice(0, 500); + } + + bootLines(): string[] { + return [`Connecting to ${this.st.hostname} as ${this.st.user.name} ...`, "Connected. Type help to see what works, hint if you are stuck."]; + } + + // ---- running one line + + run(rawLine: string): RunResult { + this.lines = []; + this.cleared = false; + this.lineCap = false; + const line = typeof rawLine === "string" ? rawLine : ""; + const refuse = (text: string): RunResult => { + if (text) this.emit("err", text); + return { lines: this.lines, clear: false, accepted: false, newlyDone: [], solved: this.solved }; + }; + if (line.trim() === "") return refuse(""); + if (line.length > MAX_LINE) return refuse(`bash: that line is too long (more than ${MAX_LINE} characters). It was not run.`); + if (/[\u0000-\u0008\u000a-\u001f\u007f]/.test(line)) return refuse("bash: that line has control characters. It was not run."); + if (this.st.history.length >= MAX_COMMANDS) return refuse("bash: too many commands in this session. Press Reset to start again."); + + this.st.history.push(line); + this.st.fs.now = NOW + this.st.history.length * 60; + resetBudget(WORK_BUDGET); + this.depth = 0; + + let items: ListItem[] | null = null; + try { + items = parseLine(line); + } catch (error) { + this.counted++; + this.emit("err", `bash: ${error instanceof SyntaxErr ? error.message : "syntax error"}`); + this.lastCode = 2; + } + if (items) { + const free = items.length === 1 && items[0]!.pipe.length === 1 && FREE.has(this.firstWord(items[0]!.pipe[0]!)); + if (!free) this.counted++; + try { + this.runItems(items, this.topSink()); + } catch (error) { + if (error instanceof BudgetError) this.emit("err", "bash: that command was stopped because it was taking too long"); + else this.emit("err", "bash: something went wrong with that command"); + this.lastCode = 1; + } + } + + const newlyDone = this.evaluate(); + return { lines: this.lines, clear: this.cleared, accepted: true, newlyDone, solved: this.solved }; + } + + private firstWord(cmd: SimpleCmd): string { + const w = cmd.words[0] ?? ""; + return /^[a-z]+$/.test(w) ? w : ""; + } + + private evaluate(): number[] { + const newly: number[] = []; + this.mission.objectives.forEach((obj, i) => { + if (this.done[i]) return; + let ok = false; + try { + ok = obj.done(this.st); + } catch { + ok = false; + } + if (ok) { + this.done[i] = true; + newly.push(i); + } + }); + if (!this.solved) { + let ok = false; + try { + ok = this.mission.goal(this.st); + } catch { + ok = false; + } + if (ok) { + this.solved = true; + this.solvedCounted = this.counted; + this.solvedHints = this.hintsShown; + this.done.forEach((d, i) => { + if (!d) { + this.done[i] = true; + newly.push(i); + } + }); + } + } + return newly; + } + + // ---- output + + private emit(kind: OutLine["kind"], text: string): void { + const parts = text.split("\n"); + if (parts[parts.length - 1] === "") parts.pop(); + for (const part of parts) { + if (this.lines.length >= MAX_OUTPUT_LINES) { + if (!this.lineCap) { + this.lineCap = true; + this.lines.push({ kind: "sys", text: "(output cut: it was too long. Narrow it down, for example with grep or head.)" }); + } + return; + } + this.lines.push({ kind, text: part }); + } + if (kind !== "sys") this.st.shown = (this.st.shown + text + (text.endsWith("\n") ? "" : "\n")).slice(-120_000); + } + + private topSink(): Sink { + return { out: (t) => this.emit("out", t), err: (t) => this.emit("err", t) }; + } + + // ---- running a parsed line + + private runItems(items: ListItem[], sink: Sink): number { + let code = this.lastCode; + let skip: "&&" | "||" | null = null; + for (let i = 0; i < items.length; i++) { + const item = items[i]!; + if (skip === "&&" && code !== 0) { + // A failed "&&" skips this pipeline; the next connector decides again. + } else if (skip === "||" && code === 0) { + // A passed "||" skips this pipeline. + } else code = this.runPipeline(item.pipe, sink, this.depth === 0); + this.lastCode = code; + skip = item.next === "&&" || item.next === "||" ? item.next : null; + } + return code; + } + + /** Run a line inside the shell (a script line or a command substitution). */ + private runInner(line: string, sink: Sink): number { + let items: ListItem[]; + try { + items = parseLine(line); + } catch (error) { + sink.err(`bash: ${error instanceof SyntaxErr ? error.message : "syntax error"}\n`); + return 2; + } + return this.runItems(items, sink); + } + + private capture(line: string, parent: Sink): string { + if (this.depth >= MAX_DEPTH) return ""; + this.depth++; + let buf = ""; + try { + this.runInner(line, { + out: (t) => { + if (buf.length < MAX_BUFFER) buf += t; + }, + err: parent.err, + }); + } finally { + this.depth--; + } + return buf.replace(/\n+$/, ""); + } + + // ---- expansion + + private lookupVar(name: string): string { + if (name === "?") return String(this.lastCode); + if (name === "$") return "4242"; + if (name === "0") return "bash"; + return this.st.env[name] ?? ""; + } + + private expandWord(raw: string, sink: Sink): string[] { + const fields: string[] = []; + let cur = ""; + let has = false; + const env = this.st.env; + const addSplit = (text: string) => { + // An unquoted expansion splits at spaces. + const pieces = text.split(/\s+/); + pieces.forEach((piece, k) => { + if (k > 0) { + fields.push(cur); + cur = ""; + has = false; + } + if (piece !== "") { + cur += quoteGlob(piece); + has = true; + } + }); + }; + const dollar = (i: number, quoted: boolean): number => { + const nx = raw[i + 1]; + let text = ""; + let next = i + 1; + if (nx === "(" && raw[i + 2] === "(") { + throw new SyntaxErr("arithmetic like $((1+2)) is not supported in this practice shell"); + } else if (nx === "(") { + const e = findClose(raw, i + 2); + if (e < 0) throw new SyntaxErr("unexpected EOF while looking for matching `)'"); + text = this.capture(raw.slice(i + 2, e), sink); + next = e + 1; + } else if (nx === "{") { + const e = raw.indexOf("}", i + 2); + if (e < 0) throw new SyntaxErr("bad substitution"); + const body = raw.slice(i + 2, e); + const m = /^([A-Za-z_][A-Za-z0-9_]*)(?::-([\s\S]*))?$/.exec(body); + if (!m) throw new SyntaxErr("${" + body + "}: bad substitution"); + const v = this.lookupVar(m[1]!); + text = v === "" && m[2] !== undefined ? m[2] : v; + next = e + 1; + } else if (nx !== undefined && /[A-Za-z_]/.test(nx)) { + const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(raw.slice(i + 1))!; + text = this.lookupVar(m[0]); + next = i + 1 + m[0].length; + } else if (nx === "?" || nx === "$" || nx === "0") { + text = this.lookupVar(nx); + next = i + 2; + } else if (nx !== undefined && /[1-9]/.test(nx)) { + next = i + 2; + } else { + cur += "$"; + has = true; + return i + 1; + } + if (quoted) { + cur += quoteGlob(text); + has = true; + } else addSplit(text); + return next; + }; + for (let i = 0; i < raw.length; i++) { + const ch = raw[i]!; + if (ch === "'") { + const e = raw.indexOf("'", i + 1); + cur += quoteGlob(raw.slice(i + 1, e)); + has = true; + i = e; + } else if (ch === '"') { + has = true; + let j = i + 1; + while (j < raw.length && raw[j] !== '"') { + const c = raw[j]!; + if (c === "\\" && j + 1 < raw.length && '$"\\`'.includes(raw[j + 1]!)) { + cur += quoteGlob(raw[j + 1]!); + j += 2; + } else if (c === "$") j = dollar(j, true); + else if (c === "`") { + const e = raw.indexOf("`", j + 1); + cur += quoteGlob(this.capture(raw.slice(j + 1, e), sink)); + j = e + 1; + } else { + cur += quoteGlob(c); + j++; + } + } + i = j; + } else if (ch === "\\") { + const nx = raw[i + 1]; + if (nx !== undefined) { + cur += quoteGlob(nx); + has = true; + i++; + } + } else if (ch === "$") i = dollar(i, false) - 1; + else if (ch === "`") { + const e = raw.indexOf("`", i + 1); + addSplit(this.capture(raw.slice(i + 1, e), sink)); + i = e; + } else if (ch === "~" && i === 0 && (raw[1] === "/" || raw.length === 1)) { + cur += quoteGlob(env.HOME ?? "/"); + has = true; + } else { + cur += ch; + has = true; + } + } + if (has) fields.push(cur); + const out: string[] = []; + for (const f of fields) { + if (/[*?[]/.test(f)) { + const hits = this.glob(f); + if (hits.length) { + out.push(...hits); + continue; + } + } + out.push(UNSENTINEL(f)); + } + return out; + } + + /** Expand a path pattern against the virtual file system. `pattern` has real glob characters. */ + private glob(pattern: string): string[] { + // Quoted glob characters are still sentinels here and are plain letters for matching. + const absolute = pattern.startsWith("/"); + const segs = pattern.split("/").filter((s, i) => s !== "" || i === 0); + let results: Array<{ abs: string; display: string }> = [{ abs: absolute ? "/" : this.st.cwd, display: absolute ? "/" : "" }]; + for (const seg of segs) { + if (seg === "") continue; + const next: typeof results = []; + for (const r of results) { + const show = (name: string) => (r.display === "" ? name : r.display.endsWith("/") ? r.display + name : r.display + "/" + name); + if (!hasGlob(seg)) { + const lit = UNSENTINEL(seg); + if (lit === ".") next.push(r); + else next.push({ abs: normalizePath(r.abs, lit), display: show(lit) }); + continue; + } + const res = this.st.fs.walk(r.abs, this.st.user); + if (!res.node || res.node.kind !== "dir" || !can(this.st.user, res.node, 4)) continue; + const pat = seg.replace(/\u0001/g, "\\*").replace(/\u0002/g, "\\?").replace(/\u0003/g, "\\["); + for (const name of [...res.node.children.keys()].sort()) { + spend(1); + if (name.startsWith(".") && !seg.startsWith(".")) continue; + if (globMatch(pat, name)) next.push({ abs: joinPath(r.abs, name), display: show(name) }); + } + } + results = next.slice(0, 500); + } + const hits: string[] = []; + for (const r of results) { + if (this.st.fs.walk(r.abs, this.st.user).node) hits.push(r.display); + } + return hits; + } + + private expandAll(words: string[], sink: Sink): string[] | null { + try { + return words.flatMap((w) => this.expandWord(w, sink)); + } catch (error) { + if (error instanceof SyntaxErr) { + sink.err(`bash: ${error.message}\n`); + return null; + } + throw error; + } + } + + // ---- pipelines + + private runPipeline(pipe: SimpleCmd[], sink: Sink, top: boolean): number { + type Prepared = { + argv: string[]; + outTargets: Array<{ path: string; append: boolean }>; + errTarget: { path: string; append: boolean } | null; + errToOut: boolean; + stdin: string | null; + failed: boolean; + }; + const prepared: Prepared[] = []; + for (const cmd of pipe) { + const argv = this.expandAll(cmd.words, sink); + if (argv === null) return 1; + const p: Prepared = { argv, outTargets: [], errTarget: null, errToOut: false, stdin: null, failed: false }; + for (const r of cmd.redirs) { + if (r.op === "2>&1") { + p.errToOut = true; + continue; + } + const targets = this.expandAll([r.target ?? ""], sink); + if (targets === null) return 1; + if (targets.length !== 1) { + sink.err(`bash: ${r.target}: ambiguous redirect\n`); + p.failed = true; + continue; + } + const path = targets[0]!; + const abs = normalizePath(this.st.cwd, path, this.st.env.HOME ?? "/"); + if (r.op === "<") { + const res = this.st.fs.walk(abs, this.st.user); + if (!res.node) { + sink.err(`bash: ${path}: ${ERR_TEXT[res.err ?? "ENOENT"]}\n`); + p.failed = true; + } else if (res.node.kind === "dir") { + sink.err(`bash: ${path}: Is a directory\n`); + p.failed = true; + } else if (!can(this.st.user, res.node, 4)) { + sink.err(`bash: ${path}: Permission denied\n`); + p.failed = true; + } else p.stdin = res.node.content; + continue; + } + const append = r.op === ">>" || r.op === "2>>"; + if (path !== "/dev/null") { + // The shell opens (and empties) the file before the command runs. + const e = this.st.fs.writeFile(abs, this.st.user, "", append); + if (e) { + sink.err(`bash: ${path}: ${ERR_TEXT[e]}\n`); + p.failed = true; + continue; + } + } + if (r.op === ">" || r.op === ">>") p.outTargets.push({ path, append }); + else p.errTarget = { path, append }; + } + prepared.push(p); + } + + let prev: string | null = null; + let code = 0; + for (let i = 0; i < prepared.length; i++) { + const p = prepared[i]!; + const last = i === prepared.length - 1; + if (p.failed) { + code = 1; + prev = ""; + continue; + } + const toTerminal = last && p.outTargets.length === 0; + let outBuf = ""; + let errBuf = ""; + const emitOut = (t: string) => { + if (toTerminal) sink.out(t); + else if (outBuf.length < MAX_BUFFER) outBuf += t; + }; + const emitErr = (t: string) => { + if (p.errToOut) emitOut(t); + else if (p.errTarget) { + if (p.errTarget.path !== "/dev/null" && errBuf.length < MAX_BUFFER) errBuf += t; + } else sink.err(t); + }; + const local: Sink = { out: emitOut, err: emitErr }; + const stdin = i === 0 ? p.stdin : prev; + code = this.runCommand(p.argv, stdin, local, toTerminal && top); + if (p.errTarget && p.errTarget.path !== "/dev/null") { + const e = this.st.fs.writeFile(normalizePath(this.st.cwd, p.errTarget.path, this.st.env.HOME ?? "/"), this.st.user, errBuf, true); + if (e) sink.err(`bash: ${p.errTarget.path}: ${ERR_TEXT[e]}\n`); + } + for (const t of p.outTargets) { + if (t.path === "/dev/null") continue; + const e = this.st.fs.writeFile(normalizePath(this.st.cwd, t.path, this.st.env.HOME ?? "/"), this.st.user, outBuf, true); + if (e) sink.err(`bash: write error: ${ERR_TEXT[e]}\n`); + } + prev = toTerminal ? "" : outBuf; + } + return code; + } + + // ---- one command + + private runCommand(argvIn: string[], stdin: string | null, sink: Sink, tty: boolean): number { + let argv = argvIn; + // NAME=value words before the command. + const assigned: Array<[string, string | undefined]> = []; + while (argv.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(argv[0]!)) { + const eq = argv[0]!.indexOf("="); + assigned.push([argv[0]!.slice(0, eq), this.st.env[argv[0]!.slice(0, eq)]]); + this.st.env[argv[0]!.slice(0, eq)] = argv[0]!.slice(eq + 1); + argv = argv.slice(1); + } + if (argv.length === 0) return 0; + const code = this.invoke(argv, stdin, sink, tty); + if (assigned.length && argv.length) { + for (const [k, old] of assigned) { + if (old === undefined) delete this.st.env[k]; + else this.st.env[k] = old; + } + } + return code; + } + + private ctx(argv: string[], stdin: string | null, sink: Sink, tty: boolean): Ctx { + return { + st: this.st, + args: argv.slice(1), + stdin, + tty, + out: sink.out, + err: (m) => sink.err(m + "\n"), + exec: (sub, input) => { + let out = ""; + const code = this.invoke(sub, input, { out: (t) => (out.length < MAX_BUFFER ? (out += t) : out), err: sink.err }, false); + return { code, out }; + }, + }; + } + + private invoke(argv: string[], stdin: string | null, sink: Sink, tty: boolean): number { + const name = argv[0]!; + const sys = /^\/(?:usr\/)?s?bin\/([a-z]+)$/.exec(name); + if (sys && (COMMANDS[sys[1]!] || BUILTINS.includes(sys[1]!))) return this.invoke([sys[1]!, ...argv.slice(1)], stdin, sink, tty); + if (name.includes("/")) return this.runFile(name, [], sink, true); + if (argv.length === 2 && argv[1] === "--help" && USAGE[name]) { + this.help(name, sink); + return 0; + } + switch (name) { + case "hint": return this.hint(); + case "submit": return this.submit(argv.slice(1), sink); + case "history": { + this.st.history.forEach((h, i) => sink.out(`${String(i + 1).padStart(5)} ${h}\n`)); + return 0; + } + case "clear": this.cleared = true; this.lines = []; return 0; + case "help": + case "commands": this.helpAll(sink); return 0; + case "man": { + if (!argv[1]) { + sink.err("What manual page do you want? Try: man ls\n"); + return 1; + } + if (!USAGE[argv[1]]) { + sink.err(`No manual entry for ${argv[1]}. Type help to see what works.\n`); + return 16; + } + this.help(argv[1], sink); + return 0; + } + case "exit": + case "logout": + sink.out("This practice shell stays open. Keep going.\n"); + return 0; + case "bash": + case "sh": { + const file = argv.slice(1).find((a) => !a.startsWith("-")); + if (!file) { + sink.err(`${name}: give a script file to run, like: ${name} script.sh\n`); + return 2; + } + return this.runFile(file, argv.slice(2), sink, false); + } + default: + } + const fn = COMMANDS[name]; + if (fn) { + try { + return fn(this.ctx(argv, stdin, sink, tty)); + } catch (error) { + if (error instanceof BudgetError) throw error; + sink.err(`${name}: something went wrong\n`); + return 1; + } + } + const note = NOT_HERE[name]; + if (note) { + sink.err(`${name}: not available on this practice server. ${note}\n`); + return 127; + } + sink.err(`bash: ${name}: command not found\n`); + return 127; + } + + /** Run a script file with the shell itself. `needExec` is true for ./script and false for bash script. */ + private runFile(path: string, _args: string[], sink: Sink, needExec: boolean): number { + const abs = normalizePath(this.st.cwd, path, this.st.env.HOME ?? "/"); + const res = this.st.fs.walk(abs, this.st.user); + if (!res.node) { + sink.err(`bash: ${path}: ${ERR_TEXT[res.err ?? "ENOENT"]}\n`); + return 127; + } + if (res.node.kind === "dir") { + sink.err(`bash: ${path}: Is a directory\n`); + return 126; + } + const node = res.node; + if (!can(this.st.user, node, 4) || (needExec && !can(this.st.user, node, 1))) { + sink.err(`bash: ${path}: Permission denied\n`); + return 126; + } + if (this.depth >= MAX_DEPTH) { + sink.err(`bash: ${path}: too many scripts running inside each other\n`); + return 1; + } + this.depth++; + const savedCwd = this.st.cwd; + let code = 0; + try { + const lines = node.content.split("\n").slice(0, 80); + for (const line of lines) { + spend(1); + const t = line.trim(); + if (t === "" || t.startsWith("#") || t.length > MAX_LINE) continue; + code = this.runInner(t, sink); + } + } finally { + this.depth--; + this.st.cwd = savedCwd; + this.st.env.PWD = savedCwd; + } + this.st.executed.push({ path: abs, code }); + return code; + } + + // ---- game commands + + private hint(): number { + const hints = this.mission.hints; + if (this.hintsShown >= hints.length) { + this.emit("sys", "No more hints. Read the objectives again and try a new command."); + return 0; + } + this.hintsShown++; + this.emit("sys", `Hint ${this.hintsShown} of ${hints.length}: ${hints[this.hintsShown - 1]}`); + return 0; + } + + private submit(args: string[], sink: Sink): number { + const m = this.mission; + if (!m.answer) { + this.emit("sys", "This mission has no question to answer. Reach the goal with commands."); + return 1; + } + if (args.length === 0) { + sink.err("Usage: submit ANSWER\n"); + return 2; + } + const given = normalizeAnswer(args.join(" ")); + const toPath = (text: string) => normalizePath(this.st.cwd, text, this.st.env.HOME ?? "/"); + const ok = m.answer.some((a) => (m.pathAnswer ? toPath(a) === toPath(given === "" ? "." : args.join(" ").trim()) : normalizeAnswer(a) === given)); + if (ok) { + this.st.answerOk = true; + this.emit("sys", "Correct. Answer accepted."); + return 0; + } + this.emit("sys", "Not quite. Look at the output again and try once more."); + return 1; + } + + private help(name: string, sink: Sink): void { + const u = USAGE[name]; + if (!u) return; + sink.out(`${name}: ${u.desc}\nUsage: ${u.usage}\n`); + } + + private helpAll(sink: Sink): void { + sink.out("Commands that work here (type man NAME for details):\n"); + const groups = new Map(); + for (const [name, u] of Object.entries(USAGE)) groups.set(u.group, [...(groups.get(u.group) ?? []), name]); + for (const [group, names] of groups) sink.out(` ${group}: ${names.join(" ")}\n`); + sink.out(SHELL_TIPS.map((t) => ` ${t}\n`).join("")); + } +} + +export function createShell(mission: Mission): Shell { + return new Shell(mission); +} diff --git a/server/src/shared/games/sysdesign/engine.ts b/server/src/shared/games/sysdesign/engine.ts new file mode 100644 index 00000000..d03f363a --- /dev/null +++ b/server/src/shared/games/sysdesign/engine.ts @@ -0,0 +1,73 @@ +// System Design Runner: each round is a production incident on a small AWS system. The player +// picks a few changes, and a deterministic traffic simulation says whether the goals are met. +import { pickDaily } from "../daily.js"; +import type { GameEngine, Stars, VerifyResult } from "../types.js"; +import { SYSDESIGN_POOL } from "./scenarios.js"; +import { evaluateGoals, simulate } from "./sim.js"; +import type { SysdesignRound, SysdesignSubmission } from "./types.js"; + +export type { SysdesignRound, SysdesignSubmission } from "./types.js"; +export type { ChangeDef, ComponentId, CostLine, GoalCheck, Goals, Model, Pricing, SimResult, StepResult, StepStatus, Stretch } from "./types.js"; +export { STEPS } from "./types.js"; +export { applyChanges, costDelta, evaluateGoals, simulate } from "./sim.js"; +export { SYSDESIGN_POOL } from "./scenarios.js"; + +/** Hard ceiling on a submission, whatever the round allows. */ +const MAX_PARSED_CHANGES = 8; + +function fail(message: string): VerifyResult { + return { passed: false, stars: 0, score: 0, message }; +} + +export const sysdesignEngine: GameEngine = { + id: "sysdesign", + title: "System Design Runner", + tagline: "A real incident on a small AWS system. Pick the fixes, run the traffic, and meet the goals.", + roundsFor: (dayKey) => pickDaily(SYSDESIGN_POOL, dayKey, "sysdesign"), + + parseSubmission(input) { + if (typeof input !== "object" || input === null || Array.isArray(input)) return null; + const keys = Object.keys(input); + if (keys.length !== 1 || keys[0] !== "changes") return null; + const changes = (input as { changes?: unknown }).changes; + if (!Array.isArray(changes) || changes.length > MAX_PARSED_CHANGES) return null; + const seen = new Set(); + for (const id of changes) { + if (typeof id !== "string" || id.length === 0 || id.length > 64 || seen.has(id)) return null; + seen.add(id); + } + return { changes: [...changes] as string[] }; + }, + + verify(round, submission) { + try { + const ids = Array.isArray(submission?.changes) ? submission.changes.filter((id): id is string => typeof id === "string") : []; + if (new Set(ids).size !== ids.length) return fail("Each change can be used only once."); + if (ids.length > round.maxChanges) return fail(`You can apply at most ${round.maxChanges} changes in this round.`); + const offered = new Set(round.changes.map((c) => c.id)); + if (ids.some((id) => !offered.has(id))) return fail("One of those changes is not part of this round."); + + const sim = simulate(round, ids); + const checks = evaluateGoals(round.goals, sim); + const missed = checks.find((c) => !c.met); + if (missed) { + return { passed: false, stars: 0, score: sim.costUsd, message: `Goal missed: ${missed.label.toLowerCase()} is ${missed.actual}, the goal is ${missed.target}.` }; + } + + const stretch = round.stretch; + const tighter = (stretch.maxCostUsd === undefined || sim.costUsd <= stretch.maxCostUsd) && (stretch.maxP95Ms === undefined || sim.p95Ms <= stretch.maxP95Ms); + const lean = ids.length <= round.solution.length && !(round.trap !== undefined && ids.includes(round.trap)); + const stars: Stars = tighter ? (lean ? 3 : 2) : 1; + const target = [stretch.maxCostUsd !== undefined ? `$${stretch.maxCostUsd} a month` : "", stretch.maxP95Ms !== undefined ? `${stretch.maxP95Ms} ms p95` : ""].filter(Boolean).join(" and "); + const message = + stars === 3 + ? `All goals met with ${ids.length} change${ids.length === 1 ? "" : "s"}: p95 ${sim.p95Ms} ms, ${sim.availability}% available, $${sim.costUsd} a month.` + : stars === 2 + ? "All goals met and under the tighter target. For 3 stars, use fewer changes and skip the tempting trap." + : `All goals met. For more stars, get under the tighter target of ${target}.`; + return { passed: true, stars, score: sim.costUsd, message }; + } catch { + return fail("That set of changes could not be checked. Try again."); + } + }, +}; diff --git a/server/src/shared/games/sysdesign/scenarios.ts b/server/src/shared/games/sysdesign/scenarios.ts new file mode 100644 index 00000000..1abe658b --- /dev/null +++ b/server/src/shared/games/sysdesign/scenarios.ts @@ -0,0 +1,393 @@ +// The pool of production incidents. Every round is plain data: a system, 24 hours of traffic, the +// goals, and a catalog of changes (each one a patch on the model). All prices are round, illustrative +// numbers made up for the game. They are not AWS quotes. +import type { Difficulty } from "../types.js"; +import { STEPS, type ChangeDef, type DeepPartial, type Model, type SysdesignRound } from "./types.js"; + +/** A model with sensible defaults. A scenario overrides only what it needs. */ +function model(over: DeepPartial = {}): Model { + const base: Model = { + app: { label: "m5.large", count: 4, rpsEach: 100, monthlyEach: 70, baseMs: 20, zones: 1, healthChecks: false, autoscale: false, scaleMin: 2, scaleMax: 8, pricing: "ondemand" }, + db: { kind: "rds", label: "db.m5.large", capacity: 400, monthly: 140, replicas: 0, replicaMonthly: 140, multiAz: false, pricing: "ondemand", readMs: 12, writeMs: 20, readCost: 1, skew: 1 }, + cache: { on: false, hit: 0.85, monthly: 90 }, + cdn: { on: false, offload: 0.9, monthly: 40 }, + queue: { on: false, monthly: 10 }, + batch: { separate: false, workersMonthly: 60 }, + net: { egressGb: 500, natGb: 500, s3Share: 0.7, s3Endpoint: false, natGateways: 1 }, + logs: { gb: 200, hotRate: 0.023, coldRate: 0.004, coldShare: 0 }, + }; + return { + app: { ...base.app, ...over.app }, + db: { ...base.db, ...over.db }, + cache: { ...base.cache, ...over.cache }, + cdn: { ...base.cdn, ...over.cdn }, + queue: { ...base.queue, ...over.queue }, + batch: { ...base.batch, ...over.batch }, + net: { ...base.net, ...over.net }, + logs: { ...base.logs, ...over.logs }, + }; +} + +/** Traffic for 24 hours, by straight lines between [hour, requests per second] points. */ +function shape(points: Array<[number, number]>): number[] { + const out: number[] = []; + for (let t = 0; t < STEPS; t++) { + let value = points[points.length - 1]![1]; + for (let i = 0; i < points.length - 1; i++) { + const [t0, v0] = points[i]!; + const [t1, v1] = points[i + 1]!; + if (t >= t0 && t <= t1) { + value = t1 === t0 ? v1 : v0 + ((v1 - v0) * (t - t0)) / (t1 - t0); + break; + } + } + out.push(Math.round(value)); + } + return out; +} + +/** A normal day: quiet at night, busy in the afternoon. */ +const day = (low: number, high: number) => shape([[0, low], [6, low], [11, high], [17, high], [23, low]]); + +type Scenario = SysdesignRound; + +const POOL: Scenario[] = [ + // ───────────────────────────── EASY ───────────────────────────── + { + id: "sd-bill-tripled", + difficulty: "easy", + title: "The bill tripled", + brief: "Finance says the AWS bill is three times higher than last quarter. Traffic did not grow. Cut the bill and keep the site fast.", + incident: "COST ALERT: monthly spend is 3x the budget. Servers and database run at under 10% busy.", + model: model({ + app: { label: "m5.2xlarge", count: 6, rpsEach: 400, monthlyEach: 280 }, + db: { label: "db.r5.2xlarge", capacity: 2400, monthly: 700 }, + net: { egressGb: 1500, natGb: 400 }, + }), + traffic: day(25, 90), + mix: { staticShare: 0.3, readShare: 0.8 }, + goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 700 }, + stretch: { maxCostUsd: 520 }, + changes: [ + { id: "rightsize-app", label: "Right-size servers to 3x m5.large", description: "The fleet is much bigger than the traffic needs. Three m5.large servers still handle the peak with room to spare.", patch: { app: { label: "m5.large", count: 3, rpsEach: 100, monthlyEach: 70 } } }, + { id: "rightsize-db", label: "Right-size the database to db.m5.large", description: "A db.r5.2xlarge is built for memory-heavy work. This database is almost idle, so a db.m5.large is enough.", patch: { db: { label: "db.m5.large", capacity: 600, monthly: 140 } } }, + { id: "savings-plan", label: "Buy a 1-year Compute Savings Plan", description: "Commit to steady EC2 use for one year and pay about 30% less per server than on-demand.", patch: { app: { pricing: "savings" } } }, + { id: "reserved-rds", label: "Buy a 1-year RDS Reserved Instance", description: "Commit to one database size for one year and pay about 38% less than on-demand.", patch: { db: { pricing: "reserved" } } }, + { id: "bigger-4xl", label: "Move up to m5.4xlarge for headroom", description: "Bigger servers feel safe, but they cost twice as much per server.", patch: { app: { label: "m5.4xlarge", rpsEach: 800, monthlyEach: 560 } } }, + { id: "add-replica", label: "Add a read replica for safety", description: "A second copy of the database for reads. It costs as much as the database itself.", patch: { db: { replicas: 1, replicaMonthly: 700 } } }, + ], + maxChanges: 3, + solution: ["rightsize-app", "rightsize-db", "savings-plan"], + trap: "bigger-4xl", + trapNote: "Bigger servers do not help when the old ones were already idle. They only raise the bill.", + hints: [ + "Look at the busy bars: the servers and the database are almost idle.", + "Paying for capacity you do not use is the problem. Make the machines smaller.", + "Right-size both the servers and the database, then commit to a steady price with a savings plan or a reserved instance.", + ], + focus: "app", + }, + { + id: "sd-static-flood", + difficulty: "easy", + title: "Images are crushing the web servers", + brief: "The shop is slow all afternoon. Most requests are for images, CSS and JavaScript files that never change.", + incident: "LATENCY ALERT: p95 is over 1 second. App servers are above 90% busy serving static files.", + model: model({ app: { count: 4 }, net: { egressGb: 3000 } }), + traffic: shape([[0, 150], [6, 150], [10, 900], [17, 900], [23, 150]]), + mix: { staticShare: 0.8, readShare: 0.8 }, + goals: { maxP95Ms: 140, minAvailability: 99.5, maxCostUsd: 720 }, + stretch: { maxCostUsd: 680 }, + changes: [ + { id: "add-cdn", label: "Put CloudFront in front", description: "A CDN keeps copies of static files near the user, so most of them never reach your servers. It also cuts data transfer cost.", patch: { cdn: { on: true } } }, + { id: "more-servers", label: "Add 4 more app servers", description: "More servers share the load. It works, but you pay for them every hour.", patch: { app: { count: 8 } } }, + { id: "bigger-db", label: "Move to a bigger database", description: "A bigger database is stronger, but the database is not the busy part here.", patch: { db: { label: "db.r5.xlarge", capacity: 1200, monthly: 350 } } }, + { id: "add-cache", label: "Add an ElastiCache node", description: "A cache answers repeated database reads fast. Static files do not come from the database.", patch: { cache: { on: true } } }, + ], + maxChanges: 2, + solution: ["add-cdn"], + trap: "bigger-db", + trapNote: "The database was never the busy part, so a bigger one only costs more.", + hints: ["Check which bar is red. It is the app servers.", "Most traffic is static files. They can be served from somewhere else.", "Use a CDN (CloudFront) for static files."], + focus: "app", + }, + { + id: "sd-logs-forever", + difficulty: "easy", + title: "Logs that never end", + brief: "Application logs are kept in S3 Standard forever. The storage line grows every month. Nobody reads logs older than a month.", + incident: "COST ALERT: S3 storage is now the biggest line on the bill and grows 5 TB each month.", + model: model({ logs: { gb: 60000, coldShare: 0 }, net: { egressGb: 300 } }), + traffic: day(20, 60), + mix: { staticShare: 0.3, readShare: 0.8 }, + goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 900 }, + stretch: { maxCostUsd: 650 }, + changes: [ + { id: "glacier-lifecycle", label: "Lifecycle rule: move to Glacier after 30 days", description: "S3 moves old logs to Glacier on its own. Glacier costs about a fifth of S3 Standard per GB.", patch: { logs: { coldShare: 0.9 } } }, + { id: "compress-logs", label: "Compress logs with gzip before upload", description: "Text logs shrink to about a third of their size, so you store and pay for less.", patch: { logs: { gb: 20000 } } }, + { id: "ebs-volumes", label: "Keep the logs on bigger EBS volumes", description: "Block storage is for running servers. It costs more per GB than S3.", patch: { logs: { hotRate: 0.08 } } }, + { id: "intelligent-tiering", label: "Turn on S3 Intelligent-Tiering", description: "S3 watches access and moves some data to a cheaper tier. Fine for unknown patterns, but it also adds a monitoring fee per object.", patch: { logs: { coldShare: 0.5, coldRate: 0.0125 } } }, + ], + maxChanges: 3, + solution: ["glacier-lifecycle", "compress-logs"], + trap: "ebs-volumes", + trapNote: "EBS costs more per GB than S3, so it makes the log bill bigger.", + hints: ["The big line is log storage, not servers.", "Old logs are almost never read. They do not need the most expensive storage class.", "Move old logs to Glacier with a lifecycle rule, and store fewer bytes by compressing."], + focus: "storage", + }, + { + id: "sd-nat-bill", + difficulty: "easy", + title: "The NAT gateway line explodes", + brief: "Servers in private subnets download big files from S3 through a NAT gateway. NAT charges for every GB that passes through.", + incident: "COST ALERT: NAT Gateway data processing is the top line on the bill, 30 TB this month.", + model: model({ net: { natGb: 30000, s3Share: 0.8, egressGb: 7000 } }), + traffic: day(30, 80), + mix: { staticShare: 0.4, readShare: 0.8 }, + goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 1500 }, + stretch: { maxCostUsd: 1100 }, + changes: [ + { id: "s3-endpoint", label: "Add an S3 gateway VPC endpoint", description: "Traffic to S3 goes over the AWS network directly, not through NAT. A gateway endpoint for S3 has no hourly or per-GB charge.", patch: { net: { s3Endpoint: true } } }, + { id: "add-cdn", label: "Put CloudFront in front of downloads", description: "A CDN serves popular files from the edge. Data transfer out gets cheaper and your servers are asked less often.", patch: { cdn: { on: true } } }, + { id: "second-nat", label: "Add a second NAT gateway per AZ", description: "It is good for availability, but it adds another monthly fee and does not reduce the data that passes through NAT.", patch: { net: { natGateways: 2 } } }, + { id: "bigger-app", label: "Use bigger servers", description: "The servers are fine. The traffic path is the problem.", patch: { app: { label: "m5.xlarge", rpsEach: 200, monthlyEach: 140 } } }, + ], + maxChanges: 2, + solution: ["s3-endpoint", "add-cdn"], + trap: "second-nat", + trapNote: "A second NAT gateway adds a fixed fee and does not reduce the GB that cross NAT.", + hints: ["Look at the cost lines: the NAT gateway is the biggest.", "Most of that traffic is only S3 traffic. It does not need to go through NAT at all.", "Add an S3 gateway endpoint. A CDN also cuts the data transfer line."], + focus: "nat", + }, + // ───────────────────────────── MEDIUM ───────────────────────────── + { + id: "sd-flash-sale-db", + difficulty: "medium", + title: "Flash sale crushes the database", + brief: "A flash sale at noon sends 6 times the normal traffic. The web servers cope, but the single database is melting.", + incident: "PAGE: database CPU at 100% and checkout errors rising. Flash sale in progress.", + model: model({ app: { count: 10 }, db: { label: "db.r5.large", capacity: 330, monthly: 300, replicaMonthly: 300 }, net: { egressGb: 400 } }), + traffic: shape([[0, 100], [9, 100], [11, 120], [12, 700], [15, 700], [16, 120], [23, 100]]), + mix: { staticShare: 0.1, readShare: 0.7 }, + goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 1700, maxPeakDbUtil: 0.9 }, + stretch: { maxCostUsd: 1500 }, + changes: [ + { id: "add-cache", label: "Add ElastiCache (Redis) for hot products", description: "Hot product pages are read again and again. A cache answers them from memory so the database sees fewer reads.", patch: { cache: { on: true, hit: 0.6 } } }, + { id: "add-replica", label: "Add a read replica", description: "A second database copy that answers reads. The primary only handles writes and half of the reads.", patch: { db: { replicas: 1 } } }, + { id: "add-queue", label: "Put orders in an SQS queue", description: "Writes wait in a queue and the database drains them at its own pace. The user gets a fast answer, the database never gets a spike.", patch: { queue: { on: true } } }, + { id: "more-servers", label: "Double the app servers", description: "More web servers, but they were not the busy part. The database is.", patch: { app: { count: 16 } } }, + { id: "bigger-db", label: "Upgrade to db.r5.4xlarge", description: "A much bigger database. It fixes the spike but costs a lot every month, also on quiet days.", patch: { db: { label: "db.r5.4xlarge", capacity: 1320, monthly: 1200 } } }, + ], + maxChanges: 3, + solution: ["add-cache", "add-replica"], + trap: "more-servers", + trapNote: "The web servers were not the problem. More of them only raises cost and sends even more work to the database.", + hints: ["Look at the bars during the sale: the database is at 100%, the servers are fine.", "Reads dominate. Take reads away from the primary database.", "Use a cache and a read replica together. A queue can smooth the writes."], + focus: "db", + }, + { + id: "sd-p95-four-seconds", + difficulty: "medium", + title: "p95 latency is 4 seconds", + brief: "Every page request hits the database, and static files come from the same servers. Pages feel slow all afternoon.", + incident: "LATENCY ALERT: p95 is 4 s. Database and app servers are both near 100% busy.", + model: model({ app: { count: 3 }, db: { capacity: 200 }, net: { egressGb: 1500 } }), + traffic: shape([[0, 80], [7, 80], [10, 420], [18, 420], [23, 80]]), + mix: { staticShare: 0.5, readShare: 0.9 }, + goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 650 }, + stretch: { maxCostUsd: 620, maxP95Ms: 130 }, + changes: [ + { id: "add-cache", label: "Add ElastiCache for repeated reads", description: "Most pages ask the database the same questions. A cache returns the answer in about 2 ms.", patch: { cache: { on: true, hit: 0.85 } } }, + { id: "add-cdn", label: "Put CloudFront in front for static files", description: "Images and scripts come from the edge, so the web servers only do dynamic work.", patch: { cdn: { on: true } } }, + { id: "add-replica", label: "Add a read replica", description: "A replica doubles read capacity, but every read is still a database read, and you pay for a second database.", patch: { db: { replicas: 1 } } }, + { id: "more-servers", label: "Add 3 more app servers", description: "More servers handle more requests, but they all still wait for the same database.", patch: { app: { count: 6 } } }, + { id: "bigger-db", label: "Use a bigger database", description: "More database power. Pricey, and static files still hit the servers.", patch: { db: { label: "db.r5.xlarge", capacity: 800, monthly: 350 } } }, + ], + maxChanges: 3, + solution: ["add-cache", "add-cdn"], + trap: "more-servers", + trapNote: "More servers do nothing for slow reads. They all wait for the same database, and they cost money.", + hints: ["Two parts are busy: the database and the app servers.", "Do not answer the same question from the database again and again, and do not make servers send files.", "Add a cache for reads and a CDN for static files."], + focus: "db", + }, + { + id: "sd-az-outage", + difficulty: "medium", + title: "One AZ goes dark", + brief: "At 1 pm one Availability Zone fails. Everything runs in that one zone. Make the site survive a zone failure.", + incident: "OUTAGE: us-east-1a is unreachable. All servers and the database are in 1a. The site is down.", + model: model({ app: { count: 4 }, net: { egressGb: 400 } }), + traffic: day(30, 140), + mix: { staticShare: 0.2, readShare: 0.8 }, + outage: { from: 13, to: 17 }, + goals: { maxP95Ms: 250, minAvailability: 99, maxCostUsd: 750 }, + stretch: { maxCostUsd: 680 }, + changes: [ + { id: "two-azs", label: "Spread servers across 2 AZs", description: "Half of the servers run in a second Availability Zone, behind a load balancer.", patch: { app: { zones: 2 } } }, + { id: "health-checks", label: "Add load balancer health checks", description: "The load balancer stops sending users to servers that do not answer.", patch: { app: { healthChecks: true } } }, + { id: "rds-multi-az", label: "Turn on RDS Multi-AZ", description: "A standby database in the other zone takes over by itself if the primary fails.", patch: { db: { multiAz: true } } }, + { id: "autoscaling", label: "Add an Auto Scaling group", description: "Servers are added when load grows and removed when it falls, so you pay for less at night.", patch: { app: { autoscale: true, scaleMin: 2, scaleMax: 8 } } }, + { id: "bigger-servers", label: "Use bigger servers", description: "Bigger servers in the same zone still go down with the zone.", patch: { app: { label: "m5.xlarge", rpsEach: 200, monthlyEach: 140, count: 4 } } }, + ], + maxChanges: 4, + solution: ["two-azs", "health-checks", "rds-multi-az"], + trap: "bigger-servers", + trapNote: "A bigger server is still one server in one zone. It does not survive a zone failure and it costs twice as much.", + hints: ["Everything lives in one zone, so one failure takes down everything.", "You need copies of the servers and of the database in a second zone.", "Spread servers over two AZs, let the load balancer find dead servers, and give the database a standby."], + focus: "lb", + }, + { + id: "sd-batch-starves-web", + difficulty: "medium", + title: "The report job starves the shop", + brief: "A heavy report job runs at midday on the same servers and database as the shop. While it runs, customers wait.", + incident: "LATENCY ALERT: p95 jumps to 3 s from 11:00 to 15:00, the same time the reports run.", + model: model({ app: { count: 4, monthlyEach: 120, label: "m5.xlarge", rpsEach: 100 }, db: { capacity: 400, monthly: 200 }, net: { egressGb: 600 } }), + traffic: shape([[0, 40], [6, 40], [10, 130], [17, 130], [23, 40]]), + mix: { staticShare: 0.2, readShare: 0.8 }, + batchJob: { from: 11, to: 15, appLoad: 240, dbLoad: 240 }, + goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 800 }, + stretch: { maxCostUsd: 720 }, + changes: [ + { id: "spot-workers", label: "Run the job on Spot workers", description: "Move the report job to its own Spot instances, which cost about 70% less and can be interrupted. The shop stops competing with it.", patch: { batch: { separate: true } } }, + { id: "savings-plan", label: "Buy a 1-year Compute Savings Plan", description: "Pay about 30% less for the steady web servers.", patch: { app: { pricing: "savings" } } }, + { id: "autoscaling", label: "Add an Auto Scaling group", description: "Adds servers when the load grows. It helps the web tier but does nothing for the shared database.", patch: { app: { autoscale: true, scaleMin: 2, scaleMax: 8 } } }, + { id: "more-servers", label: "Add 4 more app servers", description: "Bigger fleet all day, to survive 4 hours. Costly, and the database still gets the job load.", patch: { app: { count: 8 } } }, + { id: "reserved-rds", label: "Buy a 1-year RDS Reserved Instance", description: "Pay about 38% less for the database.", patch: { db: { pricing: "reserved" } } }, + ], + maxChanges: 3, + solution: ["spot-workers", "savings-plan"], + trap: "more-servers", + trapNote: "Extra servers for four busy hours cost money all month, and the database still has to carry the job.", + hints: ["Look at the times: the slow period matches the job.", "The shop and the job share the same machines. Separate them.", "Move the job to Spot workers. A savings plan keeps the bill in budget."], + focus: "workers", + }, + // ───────────────────────────── HARD ───────────────────────────── + { + id: "sd-missing-index", + difficulty: "hard", + title: "A query scans a million rows", + brief: "The product search runs a full table scan on every request. At lunch the database cannot keep up.", + incident: "PAGE: slow query log shows 180 ms scans on orders. Database CPU 100% at lunch.", + model: model({ + app: { count: 5 }, + db: { label: "db.m5.xlarge", capacity: 600, monthly: 250, readCost: 6, readMs: 180 }, + net: { egressGb: 500 }, + }), + traffic: shape([[0, 40], [8, 60], [11, 250], [15, 250], [18, 80], [23, 40]]), + mix: { staticShare: 0.2, readShare: 0.85 }, + goals: { maxP95Ms: 100, minAvailability: 99.5, maxCostUsd: 850, maxPeakDbUtil: 0.7 }, + stretch: { maxCostUsd: 800 }, + changes: [ + { id: "add-index", label: "Add an index on the search column", description: "An index lets the database find rows directly instead of reading the whole table. Reads get both faster and cheaper.", patch: { db: { readCost: 1, readMs: 12 } } }, + { id: "add-cache", label: "Add ElastiCache for repeated searches", description: "Popular searches repeat. A cache answers them in memory.", patch: { cache: { on: true, hit: 0.7 } } }, + { id: "bigger-db", label: "Upgrade to db.m5.4xlarge", description: "Four times the database power. A scan is still a scan, and the bill goes way up.", patch: { db: { label: "db.m5.4xlarge", capacity: 2400, monthly: 1000 } } }, + { id: "add-replica", label: "Add two read replicas", description: "More copies to scan the table. Each costs as much as the database.", patch: { db: { replicas: 2, replicaMonthly: 250 } } }, + { id: "more-servers", label: "Add more app servers", description: "The servers are not the slow part.", patch: { app: { count: 10 } } }, + ], + maxChanges: 3, + solution: ["add-index", "add-cache"], + trap: "bigger-db", + trapNote: "A bigger database still scans the whole table, so each query stays slow, and the cost goes over the limit.", + hints: ["Read the incident: a query takes 180 ms because it reads every row.", "Fix the query first, because power does not fix a bad query.", "Add the index. Then take the repeated reads off the database with a cache."], + focus: "db", + }, + { + id: "sd-hot-partition", + difficulty: "hard", + title: "One hot key, throttled writes", + brief: "A DynamoDB table uses the date as its partition key. Today's partition gets almost all the writes and is throttled, while the table has plenty of capacity overall.", + incident: "ALARM: ThrottledRequests on orders-table. Total capacity use is 20% but one partition is at 100%.", + model: model({ + app: { count: 10 }, + db: { kind: "dynamodb", label: "DynamoDB orders", capacity: 1100, monthly: 450, skew: 6, readMs: 6, writeMs: 10, readCost: 1 }, + net: { egressGb: 400 }, + }), + traffic: shape([[0, 150], [8, 200], [12, 800], [16, 800], [19, 250], [23, 150]]), + mix: { staticShare: 0.1, readShare: 0.45 }, + goals: { maxP95Ms: 220, minAvailability: 99.5, maxCostUsd: 1500, maxPeakDbUtil: 0.85 }, + stretch: { maxCostUsd: 1450 }, + changes: [ + { id: "shard-key", label: "Add a random suffix to the partition key", description: "Writes for the same date spread over many partitions, so no single partition is hot. This is called write sharding.", patch: { db: { skew: 1.5 } } }, + { id: "add-dax", label: "Add DAX, a DynamoDB cache", description: "A cache in front of DynamoDB answers repeated reads. Fewer reads means more room for writes.", patch: { cache: { on: true, hit: 0.7, monthly: 150 } } }, + { id: "add-queue", label: "Buffer writes with SQS", description: "Writes wait in a queue and are written at a steady pace instead of in a burst.", patch: { queue: { on: true } } }, + { id: "double-capacity", label: "Double the provisioned capacity", description: "More capacity for the table. It is spread over partitions, so the hot one gets only a bit more.", patch: { db: { capacity: 2200, monthly: 900 } } }, + { id: "more-servers", label: "Add more app servers", description: "The throttling is in the table, not in the servers.", patch: { app: { count: 12 } } }, + ], + maxChanges: 3, + solution: ["shard-key", "add-dax"], + trap: "double-capacity", + trapNote: "Capacity is shared across partitions. The hot partition is still hot, and you pay double.", + hints: ["Total capacity is fine, but one partition gets almost all the work.", "The cause is the key, not the capacity. Spread the key.", "Shard the partition key. A cache for reads gives the writes more room."], + focus: "db", + }, + { + id: "sd-black-friday-az", + difficulty: "hard", + title: "Peak day plus a lost zone", + brief: "It is the biggest sales day. Traffic triples, and in the middle of it one Availability Zone fails. The fixed fleet is too small and sits in one zone.", + incident: "OUTAGE: us-east-1a lost during peak sales. Fleet at 100% before the failure.", + model: model({ + app: { count: 6, label: "m5.xlarge", rpsEach: 100, monthlyEach: 100 }, + db: { label: "db.r5.large", capacity: 900, monthly: 300 }, + net: { egressGb: 800 }, + }), + traffic: shape([[0, 60], [7, 100], [10, 500], [17, 500], [20, 120], [23, 60]]), + mix: { staticShare: 0.15, readShare: 0.8 }, + outage: { from: 13, to: 16 }, + goals: { maxP95Ms: 350, minAvailability: 99, maxCostUsd: 1800 }, + stretch: { maxCostUsd: 1600 }, + changes: [ + { id: "asg-two-azs", label: "Auto Scaling group across 2 AZs", description: "Servers are spread over two zones and the group adds more when load rises, and removes them when it falls.", patch: { app: { zones: 2, autoscale: true, scaleMin: 4, scaleMax: 16 } } }, + { id: "health-checks", label: "Load balancer health checks", description: "Dead servers are removed from rotation within seconds.", patch: { app: { healthChecks: true } } }, + { id: "rds-multi-az", label: "RDS Multi-AZ", description: "A standby database in the second zone takes over after a failure.", patch: { db: { multiAz: true } } }, + { id: "add-cache", label: "Add ElastiCache", description: "Fewer reads reach the database. It helps speed, not zone failure.", patch: { cache: { on: true, hit: 0.8 } } }, + { id: "oversize-fleet", label: "Double the fixed fleet to 12 servers", description: "Always-on capacity for the peak. It does not fix the zone problem and it is on the bill for the whole month.", patch: { app: { count: 12 } } }, + ], + maxChanges: 4, + solution: ["asg-two-azs", "health-checks", "rds-multi-az"], + trap: "oversize-fleet", + trapNote: "A fixed, doubled fleet costs the same at night as at peak, and still lives in one zone.", + hints: ["Two problems at once: too little capacity at peak, and one zone.", "You need servers in two zones that can grow, plus a way to remove dead ones.", "Auto Scaling over two AZs, health checks, and a Multi-AZ database."], + focus: "app", + }, + { + id: "sd-halve-the-bill", + difficulty: "hard", + title: "Halve the bill, keep it fast", + brief: "The CFO wants the monthly bill cut in half without hurting speed or uptime. Money leaks in four places.", + incident: "COST ALERT: bill is $3,400 a month. Target is under $2,000. Latency and uptime must not suffer.", + model: model({ + app: { label: "m5.xlarge", count: 6, rpsEach: 200, monthlyEach: 140 }, + db: { label: "db.r5.xlarge", capacity: 1200, monthly: 350 }, + net: { egressGb: 6000, natGb: 15000, s3Share: 0.8 }, + logs: { gb: 40000 }, + }), + traffic: day(60, 160), + mix: { staticShare: 0.5, readShare: 0.8 }, + goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 2000 }, + stretch: { maxCostUsd: 1750 }, + changes: [ + { id: "add-cdn", label: "Add CloudFront", description: "Cheaper data transfer out, and static files stop reaching the servers.", patch: { cdn: { on: true } } }, + { id: "s3-endpoint", label: "S3 gateway VPC endpoint", description: "Stops S3 traffic from going through the NAT gateway.", patch: { net: { s3Endpoint: true } } }, + { id: "glacier-lifecycle", label: "Lifecycle old logs to Glacier", description: "Old logs move to a much cheaper storage class.", patch: { logs: { coldShare: 0.9 } } }, + { id: "savings-plan", label: "1-year Compute Savings Plan", description: "About 30% off the servers.", patch: { app: { pricing: "savings" } } }, + { id: "tiny-server", label: "Run everything on 1 t3.micro", description: "The cheapest possible server. It cuts the bill and cannot carry the traffic.", patch: { app: { label: "t3.micro", count: 1, rpsEach: 15, monthlyEach: 9 } } }, + { id: "second-nat", label: "A NAT gateway in every AZ", description: "Better resilience, more fixed cost.", patch: { net: { natGateways: 2 } } }, + ], + maxChanges: 4, + solution: ["add-cdn", "s3-endpoint", "glacier-lifecycle", "savings-plan"], + trap: "tiny-server", + trapNote: "A tiny server makes the bill small, but it cannot serve the traffic. Uptime and speed fall.", + hints: ["Open the cost lines. Four of them are big: transfer, NAT, logs, servers.", "Each leak has a cheap plug. Do not shrink the servers below the traffic.", "CDN, S3 endpoint, Glacier lifecycle, savings plan."], + focus: "nat", + }, +]; + +export const SYSDESIGN_POOL: readonly SysdesignRound[] = POOL; + +export function scenariosByDifficulty(difficulty: Difficulty): SysdesignRound[] { + return POOL.filter((r) => r.difficulty === difficulty); +} + +export type { ChangeDef }; diff --git a/server/src/shared/games/sysdesign/sim.ts b/server/src/shared/games/sysdesign/sim.ts new file mode 100644 index 00000000..207dc341 --- /dev/null +++ b/server/src/shared/games/sysdesign/sim.ts @@ -0,0 +1,276 @@ +// A small, pure, deterministic traffic simulation. It uses only + - * / and min, max, ceil, round, +// so the browser and the server always agree to the last digit. No clock, no randomness. +import { + STEPS, + type CostLine, + type DeepPartial, + type GoalCheck, + type Goals, + type Model, + type SimResult, + type StepResult, + type SysdesignRound, +} from "./types.js"; + +const APP_PRICING = { ondemand: 1, savings: 0.68, reserved: 0.6 } as const; +const DB_PRICING = { ondemand: 1, reserved: 0.62 } as const; +/** Illustrative unit prices, in dollars. They are round numbers, not real quotes. */ +export const PRICES = { egressPerGb: 0.09, cdnPerGb: 0.04, natPerGb: 0.045, natPerMonth: 33 } as const; + +function isObject(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +/** Merge a patch onto a copy of a model. Only objects are merged, everything else is replaced. */ +export function mergePatch(base: T, patch: DeepPartial): T { + if (!isObject(base) || !isObject(patch)) return base; + const out: Record = { ...base }; + for (const key of Object.keys(patch)) { + const next = (patch as Record)[key]; + const prev = out[key]; + out[key] = isObject(prev) && isObject(next) ? mergePatch(prev, next as never) : next; + } + return out as T; +} + +/** The model after the changes, applied in order. Ids that are not offered are ignored. */ +export function applyChanges(round: SysdesignRound, ids: readonly string[]): Model { + let model = round.model; + for (const id of ids) { + const change = round.changes.find((c) => c.id === id); + if (change) model = mergePatch(model, change.patch); + } + return model; +} + +const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, n)); +/** Queueing delay: grows fast as a part gets busy. Capped so a saturated part reads as a timeout. */ +const slow = (baseMs: number, util: number) => Math.min(4000, baseMs / (1 - clamp(util, 0, 0.97))); + +type Point = { ms: number; weight: number }; + +/** A class of requests has a spread: most are near the typical time, a few are much slower. */ +function spread(ms: number, weight: number, out: Point[]) { + if (weight <= 0) return; + out.push({ ms: ms * 0.8, weight: weight * 0.6 }, { ms: ms * 1.3, weight: weight * 0.3 }, { ms: ms * 2.6, weight: weight * 0.1 }); +} + +function weightedPercentile(points: Point[], q: number): number { + const sorted = [...points].sort((a, b) => a.ms - b.ms); + const total = sorted.reduce((sum, p) => sum + p.weight, 0); + if (total <= 0) return 0; + let seen = 0; + for (const p of sorted) { + seen += p.weight; + if (seen >= total * q) return Math.min(4000, Math.round(p.ms)); + } + return Math.min(4000, Math.round(sorted[sorted.length - 1]!.ms)); +} + +export function costLines(model: Model, appInstancesAvg: number): CostLine[] { + const appF = APP_PRICING[model.app.pricing] ?? 1; + const dbF = DB_PRICING[model.db.pricing] ?? 1; + const lines: CostLine[] = []; + const add = (id: string, label: string, usd: number) => { + const rounded = Math.round(usd); + if (rounded > 0) lines.push({ id, label, usd: rounded }); + }; + add("app", `${model.app.label} servers`, appInstancesAvg * model.app.monthlyEach * appF); + add("db", `${model.db.label} database`, (model.db.monthly + (model.db.multiAz ? model.db.monthly : 0)) * dbF); + add("replica", "Read replicas", model.db.replicas * model.db.replicaMonthly * dbF); + if (model.cache.on) add("cache", "ElastiCache", model.cache.monthly); + if (model.cdn.on) add("cdn", "CloudFront", model.cdn.monthly); + if (model.queue.on) add("queue", "SQS queue", model.queue.monthly); + if (model.batch.separate) add("workers", "Spot workers", model.batch.workersMonthly); + const off = model.cdn.on ? model.cdn.offload : 0; + add("egress", "Data transfer out", model.net.egressGb * ((1 - off) * PRICES.egressPerGb + off * PRICES.cdnPerGb)); + const natGb = model.net.natGb * (1 - (model.net.s3Endpoint ? model.net.s3Share : 0)); + add("nat", "NAT gateway", model.net.natGateways * PRICES.natPerMonth + natGb * PRICES.natPerGb); + add("logs", "Log storage", model.logs.gb * ((1 - model.logs.coldShare) * model.logs.hotRate + model.logs.coldShare * model.logs.coldRate)); + return lines; +} + +/** Run the day. The same inputs always give the same result. */ +export function simulate(round: SysdesignRound, changeIds: readonly string[]): SimResult { + const m = applyChanges(round, changeIds); + const { mix, outage, batchJob } = round; + const traffic = Array.from({ length: STEPS }, (_, i) => Math.max(0, round.traffic[i] ?? 0)); + + const batchApp = (t: number) => (batchJob && t >= batchJob.from && t <= batchJob.to && !m.batch.separate ? batchJob.appLoad : 0); + const appWorkFor = (t: number) => { + const load = traffic[t]!; + const st = load * mix.staticShare; + const off = m.cdn.on ? m.cdn.offload : 0; + return st * (1 - off) * 0.25 + (load - st) + batchApp(t); + }; + + const hit = m.cache.on ? m.cache.hit : 0; + const dbCap = Math.max(1, m.db.capacity / Math.max(1, m.db.skew)); + const replicas = Math.max(0, Math.round(m.db.replicas)); + + const steps: StepResult[] = []; + const all: Point[] = []; + const instances: number[] = []; + let backlog = 0; + let totalReq = 0; + let totalOk = 0; + let peakApp = 0; + let peakDb = 0; + let peakBacklog = 0; + + for (let t = 0; t < STEPS; t++) { + const load = traffic[t]!; + const zoneDown = !!outage && t >= outage.from && t <= outage.to; + const outageStart = !!outage && t === outage.from; + const prevWork = appWorkFor(Math.max(0, t - 1)); + + const target = m.app.autoscale ? clamp(Math.ceil(prevWork / (m.app.rpsEach * (m.app.zones === 2 ? 0.4 : 0.6))), m.app.scaleMin, m.app.scaleMax) : m.app.count; + instances.push(target); + + // How many servers are alive, and how much traffic still goes to the dead zone. + let alive = target; + let deadRoute = 0; + if (zoneDown) { + if (m.app.zones === 1) { + alive = 0; + deadRoute = 1; + } else { + alive = m.app.autoscale && !outageStart ? clamp(target, Math.ceil(m.app.scaleMin / 2), m.app.scaleMax) : Math.ceil(target / 2); + deadRoute = m.app.healthChecks ? (outageStart ? 0.04 : 0) : 0.5; + } + } + const reach = 1 - deadRoute; + + const st = load * mix.staticShare; + const dyn = load - st; + const reads = dyn * mix.readShare; + const writes = dyn - reads; + const off = m.cdn.on ? m.cdn.offload : 0; + const stCdn = st * off; + const stOrigin = st - stCdn; + const hitReads = reads * hit; + const missReads = reads - hitReads; + + const running = !!batchJob && t >= batchJob.from && t <= batchJob.to && !m.batch.separate; + const appWork = (stOrigin * 0.25 + dyn + batchApp(t)) * reach; + const cap = alive * m.app.rpsEach; + const fa = appWork <= 0 ? 1 : alive === 0 ? 0 : Math.min(1, cap / appWork); + const appUtil = alive === 0 ? 0 : cap > 0 ? appWork / cap : 0; + + // The database. A single-zone database is lost with the zone. A standby takes over quickly. + const dbDown = zoneDown && !m.db.multiAz; + const failover = zoneDown && m.db.multiAz && outageStart ? 0.97 : 1; + const missIn = missReads * reach * fa; + const writeIn = writes * reach * fa + (m.queue.on ? backlog : 0); + const readsPrimary = missIn / (1 + replicas); + const readsReplica = replicas > 0 ? missIn / (1 + replicas) : 0; + const batchDb = running ? batchJob!.dbLoad : 0; + const fixedLoad = readsPrimary * m.db.readCost + batchDb; + let writesDone = writeIn; + if (m.queue.on) { + writesDone = dbDown ? 0 : Math.min(writeIn, Math.max(0, dbCap - fixedLoad)); + backlog = Math.max(0, writeIn - writesDone); + } else { + backlog = 0; + } + const primaryDemand = writesDone + fixedLoad; + const pu = dbDown ? 0 : primaryDemand / dbCap; + const ru = (readsReplica * m.db.readCost) / dbCap; + const okPrimary = dbDown ? 0 : pu <= 1 ? 1 : 1 / pu; + const okReplica = ru <= 1 ? 1 : 1 / ru; + const okWrite = m.queue.on ? 1 : okPrimary; + const okRead = (okPrimary + replicas * okReplica) / (1 + replicas); + + // Success per class of request. + const successStOrigin = reach * fa; + const successHit = reach * fa; + const successMiss = reach * fa * okRead * failover; + const successWrite = reach * fa * okWrite * failover; + + const appMs = alive === 0 ? 4000 : slow(m.app.baseMs, appUtil); + const readUtil = (pu + replicas * ru) / (1 + replicas); + const dbReadMs = slow(m.db.readMs, readUtil); + const dbWriteMs = slow(m.db.writeMs, pu); + const points: Point[] = []; + spread(12, stCdn, points); + spread(appMs * 0.6, stOrigin * successStOrigin, points); + spread(appMs + 2, hitReads * successHit, points); + spread(appMs + dbReadMs, missReads * successMiss, points); + spread(appMs + (m.queue.on ? 6 : dbWriteMs), writes * successWrite, points); + all.push(...points); + + const ok = stCdn + stOrigin * successStOrigin + hitReads * successHit + missReads * successMiss + writes * successWrite; + const success = load > 0 ? Math.min(1, ok / load) : 1; + totalReq += load; + totalOk += ok; + const p95Ms = weightedPercentile(points, 0.95); + peakApp = Math.max(peakApp, appUtil); + peakDb = Math.max(peakDb, pu, ru); + peakBacklog = Math.max(peakBacklog, backlog); + + steps.push({ + t, + load, + appInstances: alive, + appUtil, + dbUtil: pu, + replicaUtil: ru, + success, + appDrop: clamp(1 - reach * fa, 0, 1), + dbDrop: clamp(1 - okRead * failover, 0, 1), + p95Ms, + status: success < 0.9 ? "down" : success < 0.995 || p95Ms > round.goals.maxP95Ms ? "slow" : "ok", + zoneDown, + batchRunning: running, + backlog, + costToDate: 0, + }); + } + + const avgInstances = instances.reduce((a, b) => a + b, 0) / STEPS; + const lines = costLines(m, avgInstances); + const costUsd = lines.reduce((sum, l) => sum + l.usd, 0); + const appLine = lines.find((l) => l.id === "app")?.usd ?? 0; + const fixedPerStep = (costUsd - appLine) / STEPS; + let acc = 0; + steps.forEach((s, i) => { + acc += (avgInstances > 0 ? (instances[i]! / (avgInstances * STEPS)) * appLine : 0) + fixedPerStep; + s.costToDate = Math.round(acc); + }); + if (steps.length > 0) steps[steps.length - 1]!.costToDate = costUsd; + + return { + model: m, + steps, + p95Ms: weightedPercentile(all, 0.95), + availability: totalReq > 0 ? Math.round((totalOk / totalReq) * 10000) / 100 : 100, + costUsd, + costLines: lines, + peakAppUtil: peakApp, + peakDbUtil: peakDb, + peakBacklog, + }; +} + +const pct = (n: number) => `${Math.round(n * 100)}%`; + +/** Every goal with a yes or no. Used by verify and by the result panel. */ +export function evaluateGoals(goals: Goals, sim: SimResult): GoalCheck[] { + const checks: GoalCheck[] = [ + { id: "p95", label: "Latency (p95)", met: sim.p95Ms <= goals.maxP95Ms, actual: `${sim.p95Ms} ms`, target: `at most ${goals.maxP95Ms} ms` }, + { id: "availability", label: "Availability", met: sim.availability >= goals.minAvailability, actual: `${sim.availability}%`, target: `at least ${goals.minAvailability}%` }, + { id: "cost", label: "Monthly cost", met: sim.costUsd <= goals.maxCostUsd, actual: `$${sim.costUsd}`, target: `at most $${goals.maxCostUsd}` }, + ]; + if (goals.maxPeakAppUtil !== undefined) { + checks.push({ id: "appUtil", label: "App servers peak load", met: sim.peakAppUtil <= goals.maxPeakAppUtil, actual: pct(sim.peakAppUtil), target: `at most ${pct(goals.maxPeakAppUtil)}` }); + } + if (goals.maxPeakDbUtil !== undefined) { + checks.push({ id: "dbUtil", label: "Database peak load", met: sim.peakDbUtil <= goals.maxPeakDbUtil, actual: pct(sim.peakDbUtil), target: `at most ${pct(goals.maxPeakDbUtil)}` }); + } + return checks; +} + +/** What one change alone does to the monthly bill, in dollars (negative saves money). */ +export function costDelta(round: SysdesignRound, id: string): number { + return simulate(round, [id]).costUsd - simulate(round, []).costUsd; +} diff --git a/server/src/shared/games/sysdesign/types.ts b/server/src/shared/games/sysdesign/types.ts new file mode 100644 index 00000000..eb63a765 --- /dev/null +++ b/server/src/shared/games/sysdesign/types.ts @@ -0,0 +1,166 @@ +// Shared types for the System Design Runner. Everything here is plain data (no functions), because +// a round travels from the server to the browser as JSON. +import type { RoundBase } from "../types.js"; + +/** Number of traffic steps in one simulated day. One step is one hour. */ +export const STEPS = 24; + +export type Pricing = "ondemand" | "savings" | "reserved"; + +/** The system as the player sees it. A change patches some of these numbers. */ +export type Model = { + app: { + /** For example "m5.2xlarge". */ + label: string; + count: number; + /** Requests per second one server can handle. */ + rpsEach: number; + /** Illustrative on-demand dollars per server per month. */ + monthlyEach: number; + /** Time to answer when the server is idle, in ms. */ + baseMs: number; + /** 1 means one Availability Zone, 2 means two. */ + zones: 1 | 2; + healthChecks: boolean; + autoscale: boolean; + /** Autoscaling keeps at least this many servers and at most scaleMax. */ + scaleMin: number; + scaleMax: number; + pricing: Pricing; + }; + db: { + kind: "rds" | "dynamodb"; + label: string; + /** Work units per second the primary can do. */ + capacity: number; + monthly: number; + replicas: number; + replicaMonthly: number; + /** A standby in a second zone. Costs about the same as the primary again. */ + multiAz: boolean; + pricing: "ondemand" | "reserved"; + /** Time for a read and for a write when idle, in ms. */ + readMs: number; + writeMs: number; + /** Work units one read uses (a missing index makes this big). */ + readCost: number; + /** 1 is an even spread. 4 means one hot key gets 4 times its fair share of work. */ + skew: number; + }; + cache: { on: boolean; /** Share of reads answered by the cache, 0 to 1. */ hit: number; monthly: number }; + cdn: { on: boolean; /** Share of static files served at the edge, 0 to 1. */ offload: number; monthly: number }; + queue: { on: boolean; monthly: number }; + /** Where the nightly batch job runs. Separate means spot workers away from the web tier. */ + batch: { separate: boolean; workersMonthly: number }; + net: { + /** GB per month leaving to the internet from the origin. */ + egressGb: number; + /** GB per month through the NAT gateway. */ + natGb: number; + /** Share of NAT traffic that is really S3 or DynamoDB traffic, 0 to 1. */ + s3Share: number; + /** A gateway VPC endpoint for S3 is in place. */ + s3Endpoint: boolean; + natGateways: number; + }; + logs: { gb: number; hotRate: number; coldRate: number; /** Share kept in cold storage, 0 to 1. */ coldShare: number }; +}; + +export type DeepPartial = { [K in keyof T]?: T[K] extends object ? DeepPartial : T[K] }; + +/** A change the player can apply. It is data: a patch merged onto the model. */ +export type ChangeDef = { + id: string; + label: string; + /** Plain English: what it does and why it helps (or what it costs). */ + description: string; + patch: DeepPartial; +}; + +export type Goals = { + /** The p95 request latency over the whole day must be at or below this, in ms. */ + maxP95Ms: number; + /** Share of requests that must succeed, in percent. */ + minAvailability: number; + /** Monthly bill must be at or below this, in dollars. */ + maxCostUsd: number; + /** Optional extras. */ + maxPeakAppUtil?: number; + maxPeakDbUtil?: number; +}; + +export type Stretch = { maxCostUsd?: number; maxP95Ms?: number }; + +export type ComponentId = "users" | "cdn" | "lb" | "app" | "cache" | "queue" | "db" | "replica" | "workers" | "storage" | "nat"; + +export type SysdesignRound = RoundBase & { + /** Alarm text shown in the incident banner. */ + incident: string; + /** The system before the player changes anything. */ + model: Model; + /** Requests per second at each of the 24 steps. */ + traffic: number[]; + /** Share of requests that are static files, and share of dynamic requests that are reads. */ + mix: { staticShare: number; readShare: number }; + /** An Availability Zone fails during these steps (inclusive), if set. */ + outage?: { from: number; to: number }; + /** A batch job adds this load on the web tier and the database during these steps. */ + batchJob?: { from: number; to: number; appLoad: number; dbLoad: number }; + goals: Goals; + stretch: Stretch; + changes: ChangeDef[]; + maxChanges: number; + /** A change set that earns three stars. */ + solution: string[]; + /** A tempting change that does not help, or makes things worse. */ + trap?: string; + trapNote?: string; + /** Clues, from vague to clear. */ + hints: string[]; + /** The component to highlight as the problem. */ + focus: ComponentId; +}; + +export type SysdesignSubmission = { changes: string[] }; + +export type StepStatus = "ok" | "slow" | "down"; + +export type StepResult = { + t: number; + load: number; + appInstances: number; + /** Utilisation of each part, 0 upwards. Above 1 means it is overloaded. */ + appUtil: number; + dbUtil: number; + replicaUtil: number; + /** Share of requests that succeeded this step, 0 to 1. */ + success: number; + p95Ms: number; + status: StepStatus; + /** Share of requests lost before the app tier (dead zone or full servers), and share lost at the database, 0 to 1. */ + appDrop: number; + dbDrop: number; + zoneDown: boolean; + batchRunning: boolean; + /** Writes waiting in the queue after this step. */ + backlog: number; + /** Bill so far, in dollars per month (grows to the monthly total by the last step). */ + costToDate: number; +}; + +export type CostLine = { id: string; label: string; usd: number }; + +export type SimResult = { + model: Model; + steps: StepResult[]; + p95Ms: number; + /** Percent, 0 to 100. */ + availability: number; + costUsd: number; + costLines: CostLine[]; + peakAppUtil: number; + peakDbUtil: number; + peakBacklog: number; +}; + +export type GoalCheck = { id: string; label: string; met: boolean; actual: string; target: string }; diff --git a/server/src/shared/games/types.ts b/server/src/shared/games/types.ts new file mode 100644 index 00000000..ab77ea46 --- /dev/null +++ b/server/src/shared/games/types.ts @@ -0,0 +1,53 @@ +// The contract every daily game follows. A game is a pure, deterministic engine that runs in the +// browser (so the player gets instant feedback) and again on the server (which replays the +// submission before it gives XP). Nothing here may touch the DOM, the clock or Math.random. + +export const GAME_IDS = ["sysdesign", "linux", "docker"] as const; +export type GameId = (typeof GAME_IDS)[number]; + +export function isGameId(value: unknown): value is GameId { + return typeof value === "string" && (GAME_IDS as readonly string[]).includes(value); +} + +/** Rounds in one game on one day: easy, medium, hard. Round numbers start at 0. */ +export const ROUNDS_PER_DAY = 3; +export const DIFFICULTIES = ["easy", "medium", "hard"] as const; +export type Difficulty = (typeof DIFFICULTIES)[number]; + +export type Stars = 0 | 1 | 2 | 3; + +/** What every round needs so the shell can list and label it. A game adds its own fields. */ +export type RoundBase = { + /** Stable id of the scenario, for example "sd-bill-tripled". Never reused for another scenario. */ + id: string; + difficulty: Difficulty; + title: string; + /** One or two plain sentences: what is wrong or what to do. */ + brief: string; +}; + +export type VerifyResult = { + /** The round is solved. Only a solved round records progress and earns XP. */ + passed: boolean; + /** 1 to 3 when passed, 0 when not. Better play (fewer commands, lower cost, no hints) earns more. */ + stars: Stars; + /** A number the game shows, for example a cost or a command count. Higher is not always better. */ + score: number; + /** One short sentence shown to the player: why it passed or what is still wrong. */ + message: string; +}; + +export interface GameEngine { + id: GameId; + title: string; + tagline: string; + /** Today's rounds in order easy, medium, hard. Same for everyone, from the day key only. */ + roundsFor(dayKey: string): R[]; + /** Narrow an unknown value from the network to a submission, or null when it is malformed. */ + parseSubmission(input: unknown): S | null; + /** Replay a submission against a round. Pure and deterministic, and must never throw. */ + verify(round: R, submission: S): VerifyResult; +} + +/** A loosely typed engine, for the registry and the API where the round type is not known. */ +export type AnyGameEngine = GameEngine, unknown>; diff --git a/server/src/shared/gamification/xp.ts b/server/src/shared/gamification/xp.ts index 8b0e09e5..57fb0761 100644 --- a/server/src/shared/gamification/xp.ts +++ b/server/src/shared/gamification/xp.ts @@ -11,6 +11,8 @@ export const XP_SOURCES = [ "course_completed", "weekly_goal_met", "daily_goal_met", + "game_round", + "game_set", ] as const; export type XpSource = (typeof XP_SOURCES)[number]; @@ -29,6 +31,10 @@ export const XP_AMOUNTS = { weekly_goal_met: 25, /** Brand daily-goal reward; no streak freeze (freezes stay on the weekly goal). */ daily_goal_met: 10, + /** A daily game round solved for the first time that day. Small on purpose: nine rounds a day. */ + game_round: 3, + /** All three rounds of one daily game solved in the same day. */ + game_set: 2, } as const satisfies Record; /** XP for passing a quiz chapter on a given try. Retakes after passing earn nothing (one key per chapter). */ @@ -44,6 +50,9 @@ export function quizPassedXp(attempt: number): number { */ export const XP_DAILY_CAPS: Partial> = { light_chapter_completed: 5, + // 3 games x 3 rounds. The key already makes each round once-a-day; this bounds a bug or a bad client. + game_round: 9, + game_set: 3, }; /** Award keys: one per moment, so retries, two tabs or a progress recompute award once. */ @@ -55,4 +64,6 @@ export const xpKeys = { course: (courseId: string) => `course:${courseId}`, weeklyGoal: (weekStartDayKey: string) => `weekly_goal:${weekStartDayKey}`, dailyGoal: (dayKey: string) => `daily_goal:${dayKey}`, + gameRound: (dayKey: string, game: string, roundIndex: number) => `game_round:${dayKey}:${game}:${roundIndex}`, + gameSet: (dayKey: string, game: string) => `game_set:${dayKey}:${game}`, }; diff --git a/server/src/validations/games.ts b/server/src/validations/games.ts new file mode 100644 index 00000000..46471603 --- /dev/null +++ b/server/src/validations/games.ts @@ -0,0 +1,11 @@ +import { z } from "zod"; + +export const submitRoundParams = z.object({ + game: z.string().min(1).max(32), + index: z.string().regex(/^\d{1,2}$/), +}); + +/** The submission is checked by the game's own engine, so it is only size-limited here. */ +export const submitRoundBody = z.object({ + submission: z.unknown().refine((value) => JSON.stringify(value ?? null).length <= 60_000, "Submission is too large"), +}); diff --git a/server/tests/api/games.test.ts b/server/tests/api/games.test.ts new file mode 100644 index 00000000..278664ed --- /dev/null +++ b/server/tests/api/games.test.ts @@ -0,0 +1,97 @@ +import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest"; +import request from "supertest"; +import { createApp } from "../../src/app.js"; +import { prisma } from "../../src/db/prisma.js"; +import { GAME_ENGINES } from "../../src/shared/games/index.js"; +import { XP_AMOUNTS } from "../../src/shared/gamification/xp.js"; +import { createCourseFixture } from "../helpers/fixtures.js"; + +const app = createApp(); +let fx: Awaited>; + +beforeAll(async () => { + fx = await createCourseFixture(); +}); +afterEach(() => vi.restoreAllMocks()); +afterAll(async () => { + await prisma.gamePlay.deleteMany({ where: { userId: fx.learner.id } }); + await fx.cleanup(); +}); + +const auth = () => ({ Authorization: `Bearer ${fx.learnerToken}` }); +const submit = (game: string, index: number | string, submission: unknown = { any: true }) => + request(app).post(`/api/v1/games/${game}/rounds/${index}/submit`).set(auth()).send({ submission }); + +/** Replace one engine's rules, so these tests check the server, not any one game. */ +function engineSays(game: "linux" | "docker" | "sysdesign", result: { passed: boolean; stars: 0 | 1 | 2 | 3 }) { + vi.spyOn(GAME_ENGINES[game], "parseSubmission").mockReturnValue({ any: true }); + vi.spyOn(GAME_ENGINES[game], "verify").mockReturnValue({ ...result, score: 10, message: "checked" }); +} +const xpTotal = async () => (await prisma.user.findUniqueOrThrow({ where: { id: fx.learner.id }, select: { xpTotal: true } })).xpTotal; + +describe("GET /api/v1/games/daily", () => { + it("shows today's three games to a visitor, with no progress", async () => { + const res = await request(app).get("/api/v1/games/daily"); + expect(res.status).toBe(200); + expect(res.body.data.signedIn).toBe(false); + expect(res.body.data.games.map((g: { id: string }) => g.id)).toEqual(["sysdesign", "linux", "docker"]); + for (const game of res.body.data.games) { + expect(game.rounds).toHaveLength(3); + expect(game.progress).toEqual([]); + } + expect(res.body.data.xpLeft).toBe(33); + }); +}); + +describe("POST /api/v1/games/:game/rounds/:index/submit", () => { + it("needs a signed-in learner", async () => { + const res = await request(app).post("/api/v1/games/linux/rounds/0/submit").send({ submission: {} }); + expect(res.status).toBe(401); + }); + + it("rejects an unknown game, a bad round and a malformed submission", async () => { + expect((await submit("chess", 0)).status).toBe(404); + expect((await submit("linux", 3)).status).toBe(400); + expect((await submit("linux", "x")).status).toBe(400); + vi.spyOn(GAME_ENGINES.linux, "parseSubmission").mockReturnValue(null); + expect((await submit("linux", 0)).status).toBe(400); + }); + + it("records nothing and pays nothing for a round that is not solved", async () => { + engineSays("linux", { passed: false, stars: 0 }); + const res = await submit("linux", 0); + expect(res.status).toBe(200); + expect(res.body.data).toMatchObject({ passed: false, xpAwarded: 0, setBonus: 0 }); + expect(await prisma.gamePlay.count({ where: { userId: fx.learner.id } })).toBe(0); + }); + + it("pays a solved round once, keeps the best stars, and pays the set bonus once", async () => { + const before = await xpTotal(); + engineSays("docker", { passed: true, stars: 1 }); + + const first = await submit("docker", 0); + expect(first.body.data).toMatchObject({ passed: true, alreadySolved: false, xpAwarded: XP_AMOUNTS.game_round, setBonus: 0 }); + + // Solving it again the same day is practice: no XP, but better stars are kept. + engineSays("docker", { passed: true, stars: 3 }); + const again = await submit("docker", 0); + expect(again.body.data).toMatchObject({ alreadySolved: true, xpAwarded: 0 }); + const kept = await prisma.gamePlay.findFirstOrThrow({ where: { userId: fx.learner.id, game: "docker", roundIndex: 0 } }); + expect(kept.stars).toBe(3); + + await submit("docker", 1); + const last = await submit("docker", 2); + expect(last.body.data).toMatchObject({ xpAwarded: XP_AMOUNTS.game_round, setBonus: XP_AMOUNTS.game_set, setComplete: true }); + + const repeat = await submit("docker", 2); + expect(repeat.body.data).toMatchObject({ xpAwarded: 0, setBonus: 0 }); + expect(await xpTotal()).toBe(before + 3 * XP_AMOUNTS.game_round + XP_AMOUNTS.game_set); + + const daily = await request(app).get("/api/v1/games/daily").set(auth()); + const docker = daily.body.data.games.find((g: { id: string }) => g.id === "docker"); + expect(docker.setComplete).toBe(true); + expect(docker.progress).toHaveLength(3); + expect(daily.body.data.signedIn).toBe(true); + expect(daily.body.data.xpToday).toBe(3 * XP_AMOUNTS.game_round + XP_AMOUNTS.game_set); + }); +}); diff --git a/server/tests/unit/shared/games/daily.test.ts b/server/tests/unit/shared/games/daily.test.ts new file mode 100644 index 00000000..4884f2e4 --- /dev/null +++ b/server/tests/unit/shared/games/daily.test.ts @@ -0,0 +1,74 @@ +import { describe, expect, it } from "vitest"; +import { dayNumber, hashString, pickDaily, seededRandom } from "../../../../src/shared/games/daily.js"; +import { DIFFICULTIES, GAME_IDS, ROUNDS_PER_DAY, isGameId } from "../../../../src/shared/games/types.js"; +import { GAME_ENGINES } from "../../../../src/shared/games/index.js"; +import { XP_AMOUNTS, XP_DAILY_CAPS, xpKeys } from "../../../../src/shared/gamification/xp.js"; + +const pool = DIFFICULTIES.flatMap((difficulty) => + [1, 2, 3, 4].map((n) => ({ id: `${difficulty}-${n}`, difficulty })), +); + +describe("daily rotation", () => { + it("counts days since 1970 without a time zone", () => { + expect(dayNumber("1970-01-01")).toBe(0); + expect(dayNumber("1970-01-02")).toBe(1); + expect(dayNumber("2026-11-18") - dayNumber("2026-11-17")).toBe(1); + }); + + it("picks one scenario per difficulty, in order", () => { + const day = pickDaily(pool, "2026-11-18", "demo"); + expect(day).toHaveLength(ROUNDS_PER_DAY); + expect(day.map((round) => round.difficulty)).toEqual([...DIFFICULTIES]); + }); + + it("is the same for everyone on one day and varies from day to day", () => { + expect(pickDaily(pool, "2026-11-18", "demo")).toEqual(pickDaily(pool, "2026-11-18", "demo")); + expect(pickDaily(pool, "2026-11-18", "demo")).not.toEqual(pickDaily(pool, "2026-11-19", "demo")); + }); + + it("shows every scenario of a tier before it repeats", () => { + const seen = new Set(); + for (let d = 0; d < 4; d++) seen.add(pickDaily(pool, `2026-11-${10 + d}`, "demo")[0]!.id); + expect(seen.size).toBe(4); + }); + + it("does not rotate two games in step", () => { + expect(hashString("sysdesign:easy")).not.toBe(hashString("linux:easy")); + }); + + it("refuses a pool with a missing difficulty", () => { + expect(() => pickDaily(pool.filter((round) => round.difficulty !== "hard"), "2026-11-18", "demo")).toThrow(/hard/); + }); + + it("gives repeatable noise from a seed", () => { + const a = seededRandom(7); + const b = seededRandom(7); + expect([a(), a(), a()]).toEqual([b(), b(), b()]); + }); +}); + +describe("game registry and XP", () => { + it("has an engine for every game id, and only those ids", () => { + expect(Object.keys(GAME_ENGINES).sort()).toEqual([...GAME_IDS].sort()); + expect(isGameId("linux")).toBe(true); + expect(isGameId("chess")).toBe(false); + for (const id of GAME_IDS) expect(GAME_ENGINES[id].id).toBe(id); + }); + + it("serves three rounds, one per difficulty, from every engine", () => { + for (const id of GAME_IDS) { + const rounds = GAME_ENGINES[id].roundsFor("2026-11-18"); + expect(rounds).toHaveLength(ROUNDS_PER_DAY); + expect(rounds.map((round) => round.difficulty)).toEqual([...DIFFICULTIES]); + } + }); + + it("keeps game XP small and keyed once per round and per set", () => { + expect(XP_AMOUNTS.game_round).toBe(3); + expect(XP_AMOUNTS.game_set).toBe(2); + expect(XP_DAILY_CAPS.game_round).toBe(GAME_IDS.length * ROUNDS_PER_DAY); + expect(XP_DAILY_CAPS.game_set).toBe(GAME_IDS.length); + expect(xpKeys.gameRound("2026-11-18", "linux", 1)).toBe("game_round:2026-11-18:linux:1"); + expect(xpKeys.gameSet("2026-11-18", "linux")).toBe("game_set:2026-11-18:linux"); + }); +}); diff --git a/server/tests/unit/shared/games/docker.test.ts b/server/tests/unit/shared/games/docker.test.ts new file mode 100644 index 00000000..36912294 --- /dev/null +++ b/server/tests/unit/shared/games/docker.test.ts @@ -0,0 +1,344 @@ +import { describe, expect, it } from "vitest"; +import { dockerEngine, parseSubmission, roundsFor, verify, type BuildRound, type DockerRound, type DockerSubmission, type FixRound } from "../../../../src/shared/games/docker/engine.js"; +import { POOL } from "../../../../src/shared/games/docker/scenarios.js"; +import { simulateBuild } from "../../../../src/shared/games/docker/builder.js"; +import { cloneWorld, runLine, type DockerWorld } from "../../../../src/shared/games/docker/daemon.js"; +import { engineFor } from "../../../../src/shared/games/index.js"; + +const fixes = POOL.filter((r): r is FixRound => r.mode === "fix"); +const builds = POOL.filter((r): r is BuildRound => r.mode === "build"); +const byId = (id: string) => POOL.find((r) => r.id === id)!; +const fixSub = (commands: string[], hints = 0): DockerSubmission => ({ mode: "fix", commands, hints }); +const buildSub = (steps: string[], hints = 0): DockerSubmission => ({ mode: "build", steps, hints }); +const solutionOf = (r: DockerRound, hints = 0): DockerSubmission => (r.mode === "fix" ? fixSub(r.solution, hints) : buildSub(r.solution, hints)); + +function play(round: FixRound, lines: string[]): { world: DockerWorld; out: string[] } { + const world = cloneWorld(round.world); + const out: string[] = []; + for (const line of lines) out.push(...runLine(world, line).lines.map((l) => l.text)); + return { world, out }; +} + +describe("docker pool", () => { + it("has at least four scenarios per difficulty and both modes", () => { + for (const d of ["easy", "medium", "hard"] as const) expect(POOL.filter((r) => r.difficulty === d).length).toBeGreaterThanOrEqual(4); + expect(fixes.length).toBeGreaterThan(0); + expect(builds.length).toBeGreaterThan(0); + for (const d of ["easy", "medium", "hard"] as const) { + expect(POOL.some((r) => r.difficulty === d && r.mode === "fix")).toBe(true); + expect(POOL.some((r) => r.difficulty === d && r.mode === "build")).toBe(true); + } + }); + + it("has unique ids, three hints each and no dashes in the text", () => { + expect(new Set(POOL.map((r) => r.id)).size).toBe(POOL.length); + for (const r of POOL) { + expect(r.hints).toHaveLength(3); + const text = JSON.stringify([r.title, r.brief, r.hints, r.goals.map((g) => g.label)]); + expect(text).not.toMatch(new RegExp(`[${String.fromCharCode(0x2013)}${String.fromCharCode(0x2014)}]`)); + } + }); + + it("is plain JSON, so a round can travel to the browser", () => { + for (const r of POOL) expect(JSON.parse(JSON.stringify(r))).toEqual(r); + }); + + it("solves every scenario with its stated solution, with three stars", () => { + for (const r of POOL) { + const result = verify(r, solutionOf(r)); + expect(result.passed, `${r.id}: ${result.message}`).toBe(true); + expect(result.stars, r.id).toBe(3); + } + }); + + it("gives fewer stars when hints are used", () => { + for (const r of POOL) { + expect(verify(r, solutionOf(r, 1)).stars, r.id).toBe(2); + expect(verify(r, solutionOf(r, 3)).stars, r.id).toBe(1); + } + }); + + it("does not pass empty or unrelated submissions", () => { + for (const r of POOL) { + const empty = r.mode === "fix" ? fixSub([]) : buildSub([]); + expect(verify(r, empty).passed, r.id).toBe(false); + const wrong = r.mode === "fix" ? fixSub(["docker ps", "docker images"]) : buildSub([r.pieces[0]!.id]); + expect(verify(r, wrong).passed, r.id).toBe(false); + expect(verify(r, wrong).stars).toBe(0); + } + }); + + it("starts every fix scenario broken, with at least one goal unmet", () => { + for (const r of fixes) expect(verify(r, fixSub(["docker ps"])).passed, r.id).toBe(false); + }); + + it("gives one star for a slow fix and two for a medium one", () => { + const r = byId("docker-start-stopped") as FixRound; + const slow = verify(r, fixSub(["docker ps", "docker ps -a", "docker images", "docker network ls", "docker volume ls", "docker ps -a", "docker start web"])); + expect(slow.passed).toBe(true); + expect(slow.stars).toBe(1); + const medium = verify(r, fixSub(["docker ps", "docker ps -a", "docker images", "docker start web"])); + expect(medium.stars).toBe(2); + }); +}); + +describe("daily rounds", () => { + it("always has one round per difficulty with at least one fix and one build round", () => { + for (let day = 0; day < 120; day++) { + const key = new Date(Date.UTC(2026, 0, 1 + day)).toISOString().slice(0, 10); + const rounds = roundsFor(key); + expect(rounds.map((r) => r.difficulty)).toEqual(["easy", "medium", "hard"]); + const modes = rounds.map((r) => r.mode); + expect(modes, key).toContain("fix"); + expect(modes, key).toContain("build"); + } + }); + + it("is deterministic and varies by day", () => { + expect(roundsFor("2026-11-18").map((r) => r.id)).toEqual(roundsFor("2026-11-18").map((r) => r.id)); + const seen = new Set(); + for (let day = 0; day < 30; day++) roundsFor(new Date(Date.UTC(2026, 10, 1 + day)).toISOString().slice(0, 10)).forEach((r) => seen.add(r.id)); + expect(seen.size).toBeGreaterThanOrEqual(12); + const today = roundsFor("2026-11-18").map((r) => r.id).join(); + const other = Array.from({ length: 5 }, (_, i) => roundsFor(`2026-11-${19 + i}`).map((r) => r.id).join()); + expect(other.some((o) => o !== today)).toBe(true); + }); + + it("is registered as the docker engine", () => { + expect(engineFor("docker").id).toBe("docker"); + expect(dockerEngine.roundsFor("2026-11-18")).toHaveLength(3); + }); +}); + +describe("parseSubmission", () => { + it("accepts good fix and build submissions", () => { + expect(parseSubmission({ mode: "fix", commands: ["docker ps"], hints: 0 })).toEqual({ mode: "fix", commands: ["docker ps"], hints: 0 }); + expect(parseSubmission({ mode: "build", steps: ["from", "web-port:wp-ok"], hints: 2 })).toEqual({ mode: "build", steps: ["from", "web-port:wp-ok"], hints: 2 }); + }); + + it("rejects junk", () => { + const junk: unknown[] = [ + null, undefined, 5, "fix", [], {}, { mode: "fix" }, { mode: "fix", commands: "docker ps", hints: 0 }, + { mode: "fix", commands: [1], hints: 0 }, { mode: "fix", commands: [""], hints: 0 }, { mode: "fix", commands: [" "], hints: 0 }, + { mode: "fix", commands: ["x".repeat(301)], hints: 0 }, { mode: "fix", commands: Array(101).fill("docker ps"), hints: 0 }, + { mode: "fix", commands: ["docker ps"], hints: -1 }, { mode: "fix", commands: ["docker ps"], hints: 1.5 }, { mode: "fix", commands: ["docker ps"], hints: "0" }, + { mode: "fix", commands: ["docker ps"], hints: 0, extra: true }, { mode: "fix", commands: ["a\u0000b"], hints: 0 }, + { mode: "build", steps: ["has space"], hints: 0 }, { mode: "build", steps: [1], hints: 0 }, { mode: "build", steps: Array(41).fill("a"), hints: 0 }, + { mode: "build", commands: ["a"], hints: 0 }, { mode: "other", steps: [], hints: 0 }, { done: true }, + ]; + for (const j of junk) expect(parseSubmission(j), JSON.stringify(j)).toBeNull(); + }); + + it("fails verify when the mode does not match the round", () => { + const fix = byId("docker-start-stopped"); + const build = byId("docker-build-node-order") as BuildRound; + expect(verify(fix, buildSub(["from"])).passed).toBe(false); + expect(verify(build, fixSub(["docker ps"])).passed).toBe(false); + expect(verify(fix, buildSub(["from"])).message).toMatch(/fix round/); + expect(verify(build, fixSub(["docker ps"])).message).toMatch(/build round/); + }); + + it("never throws on odd input", () => { + const rounds: unknown[] = [null, undefined, 3, "x", {}, { id: 4 }, { mode: "fix" }, { mode: "build", pieces: 5 }, { mode: "fix", world: null, goals: null }, ...POOL]; + const subs: unknown[] = [null, 1, "a", [], {}, { mode: "fix", commands: [null], hints: 0 }, { mode: "build", steps: [{}], hints: 0 }, fixSub(["docker run"]), fixSub(["$(", "'"]), buildSub(["nope"])]; + for (const r of rounds) for (const s of subs) { + expect(() => verify(r as DockerRound, s as DockerSubmission)).not.toThrow(); + expect(verify(r as DockerRound, s as DockerSubmission).passed).toBe(false); + } + }); + + it("returns one short sentence message", () => { + for (const r of POOL) { + const m = verify(r, solutionOf(r)).message; + expect(m.length).toBeGreaterThan(5); + expect(m).not.toMatch(new RegExp(`[${String.fromCharCode(0x2013)}${String.fromCharCode(0x2014)}!]`)); + } + }); +}); + +describe("virtual docker daemon", () => { + it("shows a table for docker ps and hides stopped containers without -a", () => { + const r = byId("docker-start-stopped") as FixRound; + const a = play(r, ["docker ps"]).out; + expect(a).toHaveLength(1); + expect(a[0]).toMatch(/^CONTAINER ID\s+IMAGE\s+STATUS\s+PORTS\s+NAMES$/); + const b = play(r, ["docker ps -a"]).out; + expect(b).toHaveLength(2); + expect(b[1]).toMatch(/Exited \(0\)/); + }); + + it("explains a container that exits because of a missing variable", () => { + const r = byId("docker-missing-env") as FixRound; + expect(play(r, ["docker logs db"]).out.join("\n")).toContain("POSTGRES_PASSWORD"); + const again = play(r, ["docker rm db", "docker run -d --name db postgres:16", "docker ps -a", "docker logs --tail 1 db"]); + expect(again.world.containers[0]!.status).toBe("exited"); + expect(again.out.join("\n")).toContain("Exited (1)"); + }); + + it("reports a name conflict and a port conflict like Docker", () => { + const r = byId("docker-port-taken") as FixRound; + const first = play(r, ["docker run -d --name web -p 8080:80 nginx:1.25"]); + expect(first.out.join("\n")).toContain("port is already allocated"); + expect(first.world.containers.find((c) => c.name === "web")!.status).toBe("created"); + const second = play(r, ["docker run -d --name old-site nginx:1.25"]); + expect(second.out.join("\n")).toContain("is already in use by container"); + }); + + it("curl shows connection errors and then the page", () => { + const r = byId("docker-wrong-port") as FixRound; + expect(play(r, ["curl localhost:8080"]).out.join("\n")).toContain("(56)"); + expect(play(r, ["curl localhost:9999"]).out.join("\n")).toContain("(7) Failed to connect"); + const ok = play(r, ["docker rm -f web", "docker run -d --name web -p 8080:80 nginx:1.25", "curl http://localhost:8080/"]); + expect(ok.out.join("\n")).toContain("Welcome to nginx"); + }); + + it("starts containers on a user network and resolves names with exec", () => { + const r = byId("docker-no-network") as FixRound; + const before = play(r, ["docker start web", "docker ps -a"]); + expect(before.world.containers.find((c) => c.name === "web")!.status).toBe("exited"); + const fixed = play(r, ["docker network create appnet", "docker network connect appnet db", "docker network connect appnet web", "docker start web", "docker exec web ping -c 1 db", "docker exec web curl db:5432"]); + expect(fixed.out.join("\n")).toContain("PING db"); + expect(fixed.world.containers.find((c) => c.name === "web")!.status).toBe("running"); + expect(play(r, ["docker exec web ping db"]).out.join("\n")).toMatch(/not running/); + }); + + it("restarts a crashing container on its policy and shows OOM in inspect", () => { + const r = byId("docker-oom-loop") as FixRound; + const info = play(r, ["docker inspect -f '{{.State.OOMKilled}} {{.State.ExitCode}}' worker", "docker ps", "docker stats --no-stream"]); + expect(info.out[0]).toBe("true 137"); + expect(info.out.join("\n")).toContain("Restarting (137)"); + const loop = play(r, ["docker run -d --name w2 --restart always --memory 128m acme/worker:3.1", "docker ps -a"]); + expect(loop.world.containers.find((c) => c.name === "w2")!.status).toBe("restarting"); + }); + + it("heals a restarting container once its cause is fixed", () => { + const r = byId("docker-no-network") as FixRound; + const world = cloneWorld(r.world); + world.containers.find((c) => c.name === "web")!.restart = "always"; + runLine(world, "docker start web"); + expect(world.containers.find((c) => c.name === "web")!.status).toBe("restarting"); + runLine(world, "docker network create n1 && docker network connect n1 db && docker network connect n1 web"); + expect(world.containers.find((c) => c.name === "web")!.status).toBe("running"); + }); + + it("supports && and $( ) and prune with a safe default", () => { + const r = byId("docker-disk-full") as FixRound; + expect(play(r, ["docker rm $(docker ps -aq -f status=exited)"]).world.containers.filter((c) => c.status === "exited")).toHaveLength(0); + expect(play(r, ["docker system prune"]).out.join("\n")).toContain("[y/N]"); + expect(verify(r, fixSub(["docker container prune -f", "docker image prune -f"])).passed).toBe(true); + expect(verify(r, fixSub(["docker system prune -af --volumes"])).passed).toBe(false); + expect(verify(r, fixSub(["docker system prune -a -f"])).passed).toBe(false); + }); + + it("only runs compose where the scenario has a file", () => { + expect(play(byId("docker-wrong-port") as FixRound, ["docker compose up -d"]).out.join("\n")).toContain("no configuration file"); + const r = byId("docker-compose-conflict") as FixRound; + const once = play(r, ["cat docker-compose.yml", "docker compose up -d"]); + expect(once.out.join("\n")).toContain("services:"); + expect(once.out.join("\n")).toContain("port is already allocated"); + expect(once.world.containers.find((c) => c.name === "shop-db-1")!.status).toBe("running"); + }); + + it("is strict about flags and arguments", () => { + const r = byId("docker-start-stopped") as FixRound; + const o = (line: string) => play(r, [line]).out.join("\n"); + expect(o("docker run")).toContain('requires at least 1 argument'); + expect(o("docker run --bogus nginx")).toContain("unknown flag: --bogus"); + expect(o("docker run -x nginx")).toContain("unknown shorthand flag"); + expect(o("docker run -p 99999:80 nginx")).toContain("invalid"); + expect(o("docker run -d --name x --network nope nginx:1.25")).toContain("network nope not found"); + expect(o("docker run -d nginx:latst")).toContain("manifest for nginx:latst not found"); + expect(o("docker run -d nosuchrepo")).toContain("pull access denied"); + expect(o("docker stop ghost")).toContain("No such container: ghost"); + expect(o("docker rm web nope")).toContain("No such container: nope"); + expect(o("docker frobnicate")).toContain("is not a docker command"); + expect(o("docker ps 'unterminated")).toContain("unexpected EOF"); + expect(o("docker exec web env")).toContain("is not running"); + expect(o("rm -rf /")).toContain("command not found"); + expect(o("docker run -d -m 1m nginx")).toContain("Minimum memory"); + expect(o("x".repeat(400))).toContain("too long"); + }); + + it("is deterministic", () => { + const r = byId("docker-no-network") as FixRound; + const lines = ["docker ps -a", "docker network create a", "docker run -d --name z nginx:1.25", "docker images"]; + expect(play(r, lines).out).toEqual(play(r, lines).out); + const w = cloneWorld(r.world); + runLine(w, "docker run -d --name z nginx:1.25"); + expect(r.world.containers.some((c) => c.name === "z")).toBe(false); + }); +}); + +describe("build simulation", () => { + const node = byId("docker-build-node-order") as BuildRound; + const slim = byId("docker-build-slim") as BuildRound; + const portEnv = byId("docker-build-port-env") as BuildRound; + const basic = byId("docker-build-compose-basic") as BuildRound; + const tiers = byId("docker-build-compose-tiers") as BuildRound; + + it("builds fast when the dependencies are installed before the code is copied", () => { + const good = simulateBuild(node, node.solution); + expect(good.ok && good.started && good.reachable).toBe(true); + expect(good.cacheFriendly).toBe(true); + expect(good.rebuildSec).toBeLessThan(3); + const bad = simulateBuild(node, ["from", "workdir", "cp-src", "npm-ci", "expose", "cmd"]); + expect(bad.ok).toBe(true); + expect(bad.cacheFriendly).toBe(false); + expect(bad.rebuildSec).toBeGreaterThan(30); + expect(verify(node, buildSub(["from", "workdir", "cp-pkg", "cp-src", "npm-ci", "expose", "cmd"])).passed).toBe(false); + }); + + it("reports the build problems a real Dockerfile has", () => { + expect(simulateBuild(node, ["workdir", "from"]).error).toMatch(/start with FROM/); + expect(simulateBuild(node, []).error).toMatch(/empty/); + expect(simulateBuild(node, ["from", "workdir", "npm-ci"]).error).toMatch(/package\.json/); + expect(simulateBuild(slim, ["from-ubuntu", "workdir", "cp-req", "pip"]).error).toMatch(/not found/); + expect(simulateBuild(slim, ["from-slim", "from-full"]).error).toMatch(/one FROM/); + expect(simulateBuild(node, ["nope"]).error).toMatch(/Unknown piece/); + const noCmd = simulateBuild(node, ["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "expose"]); + expect(noCmd.ok).toBe(true); + expect(noCmd.started).toBe(false); + const cmdFirst = simulateBuild(node, ["from", "cmd", "workdir", "cp-pkg", "npm-ci", "cp-src", "expose"]); + expect(cmdFirst.warnings.join()).toMatch(/CMD/); + expect(verify(node, buildSub(["from", "cmd", "workdir", "cp-pkg", "npm-ci", "cp-src", "expose"])).stars).toBe(1); + const copyBeforeWorkdir = simulateBuild(node, ["from", "cp-pkg", "workdir", "npm-ci"]); + expect(copyBeforeWorkdir.error).toMatch(/package\.json/); + }); + + it("needs the right base image and port", () => { + const full = simulateBuild(slim, ["from-full", "workdir", "cp-req", "pip", "cp-src", "expose", "cmd"]); + expect(full.sizeMb).toBeGreaterThan(1000); + expect(verify(slim, buildSub(["from-full", "workdir", "cp-req", "pip", "cp-src", "expose", "cmd"])).passed).toBe(false); + const wrongPort = simulateBuild(portEnv, ["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "env-3000", "expose-8080", "cmd-node"]); + expect(wrongPort.started).toBe(true); + expect(wrongPort.reachable).toBe(false); + expect(simulateBuild(portEnv, ["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "expose-3000", "cmd-node"]).reachable).toBe(true); + expect(verify(portEnv, buildSub(["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "expose-3000", "cmd-node"])).passed).toBe(false); + expect(simulateBuild(portEnv, ["from", "workdir", "cp-pkg", "npm-ci", "cp-src", "env-8080", "expose-8080", "cmd-dev"]).started).toBe(false); + }); + + it("checks a compose file", () => { + const solved = simulateBuild(basic, basic.solution); + expect(solved.started && solved.reachable && solved.persists).toBe(true); + const swap = (slot: string, pick: string) => basic.solution.map((s) => (s.startsWith(slot + ":") ? `${slot}:${pick}` : s)); + expect(simulateBuild(basic, swap("web-port", "wp-same")).reachable).toBe(false); + expect(simulateBuild(basic, swap("web-env", "we-localhost")).started).toBe(false); + expect(simulateBuild(basic, swap("web-dep", "wd-restart")).started).toBe(false); + expect(simulateBuild(basic, swap("web-dep", "wd-cache")).error).toMatch(/undefined service/); + expect(simulateBuild(basic, swap("db-env", "de-empty")).started).toBe(false); + expect(simulateBuild(basic, swap("top-vol", "tv-none")).error).toMatch(/undefined volume/); + expect(simulateBuild(basic, swap("db-vol", "dv-bind")).persists).toBe(false); + expect(simulateBuild(basic, basic.solution.slice(1)).error).toMatch(/Fill every blank/); + expect(simulateBuild(basic, [...basic.solution, "web-port:wp-ok"]).error).toMatch(/twice/); + expect(simulateBuild(basic, ["web-port:zzz"]).error).toMatch(/Unknown choice/); + }); + + it("keeps the three tier networks apart", () => { + expect(simulateBuild(tiers, tiers.solution).isolated).toBe(true); + const swap = (slot: string, pick: string) => tiers.solution.map((s) => (s.startsWith(slot + ":") ? `${slot}:${pick}` : s)); + expect(simulateBuild(tiers, swap("web-net", "wn-both")).isolated).toBe(false); + expect(verify(tiers, buildSub(swap("web-net", "wn-both"))).passed).toBe(false); + expect(simulateBuild(tiers, swap("api-net", "an-front")).started).toBe(false); + expect(simulateBuild(tiers, swap("top-net", "tn-front")).error).toMatch(/undefined network/); + }); +}); diff --git a/server/tests/unit/shared/games/linux.test.ts b/server/tests/unit/shared/games/linux.test.ts new file mode 100644 index 00000000..fae1fcb2 --- /dev/null +++ b/server/tests/unit/shared/games/linux.test.ts @@ -0,0 +1,463 @@ +import { describe, expect, it } from "vitest"; +import { linuxEngine, createLinuxSession, type LinuxSubmission } from "../../../../src/shared/games/linux/engine.js"; +import { MISSIONS, missionById } from "../../../../src/shared/games/linux/missions.js"; +import { Shell } from "../../../../src/shared/games/linux/shell.js"; +import { compilePatterns, globMatch } from "../../../../src/shared/games/linux/regex.js"; +import { DIFFICULTIES } from "../../../../src/shared/games/types.js"; + +const round = (id: string) => linuxEngine.roundsFor("2026-11-18").find((r) => r.id === id) ?? { ...linuxEngine.roundsFor("2026-11-18")[0]!, id }; + +/** Run commands on a mission and return everything that was printed. */ +function play(id: string, commands: string[]): { shell: Shell; text: string[]; last: string } { + const shell = new Shell(missionById(id)!); + const text: string[] = []; + let last = ""; + for (const c of commands) { + const res = shell.run(c); + last = res.lines.map((l) => l.text).join("\n"); + text.push(last); + } + return { shell, text, last }; +} + +const run1 = (id: string, command: string) => play(id, [command]).last; + +describe("linux missions", () => { + it("has at least four missions in every difficulty, with unique ids", () => { + for (const d of DIFFICULTIES) expect(MISSIONS.filter((m) => m.difficulty === d).length).toBeGreaterThanOrEqual(4); + expect(new Set(MISSIONS.map((m) => m.id)).size).toBe(MISSIONS.length); + }); + + it("gives every mission a story, objectives, par and hints, and plain text", () => { + for (const m of MISSIONS) { + expect(m.story.length).toBeGreaterThan(30); + expect(m.objectives.length).toBeGreaterThanOrEqual(3); + expect(m.hints.length).toBeGreaterThanOrEqual(3); + expect(m.par).toBeGreaterThan(0); + const all = [m.title, m.brief, m.story, ...m.hints, ...m.objectives.map((o) => o.label)].join(" "); + expect(all).not.toMatch(/[–—]/); + } + }); + + for (const m of MISSIONS) { + describe(m.id, () => { + const r = linuxEngine.roundsFor("2026-11-18")[0]!; + const target = { ...r, id: m.id, difficulty: m.difficulty, par: m.par }; + + it("is solved by its stated solution, with three stars", () => { + const result = linuxEngine.verify(target, { commands: m.solution, hints: 0 }); + expect(result.message).toBeTruthy(); + expect(result.passed).toBe(true); + expect(result.stars).toBe(3); + expect(result.score).toBeLessThanOrEqual(m.par); + }); + + it("is not solved by an empty or a lazy submission", () => { + expect(linuxEngine.verify(target, { commands: [], hints: 0 }).passed).toBe(false); + expect(linuxEngine.verify(target, { commands: ["ls", "pwd", "whoami"], hints: 0 }).passed).toBe(false); + }); + + it("is not solved by half of the solution (unless it has one command)", () => { + if (m.solution.length < 2) return; + expect(linuxEngine.verify(target, { commands: m.solution.slice(0, -1), hints: 0 }).passed).toBe(false); + }); + + it("ticks every objective when solved", () => { + const { shell } = play(m.id, m.solution); + expect(shell.isSolved).toBe(true); + expect(shell.progress().done.every(Boolean)).toBe(true); + }); + }); + } + + it("also accepts other ways to solve the config mission", () => { + const redirect = ["cd app", "grep -v -e '^max_connections' -e '^debug' app.conf > app.conf.new", "echo max_connections=200 >> app.conf.new", "echo debug=false >> app.conf.new", "echo cache_ttl=300 >> app.conf.new", "mv app.conf.new app.conf"]; + const { shell } = play("linux-edit-config", redirect); + expect(shell.isSolved).toBe(true); + }); + + it("fails the config mission when a redirect wipes the file", () => { + const { shell, text } = play("linux-edit-config", ["cd app", "grep -v debug app.conf > app.conf", "cat app.conf"]); + expect(text[2]).toBe(""); + expect(shell.isSolved).toBe(false); + }); + + it("does not let rm -r in /var/tmp pass the temp file mission", () => { + const { shell } = play("linux-old-temp-files", ["rm -r /var/tmp/*"]); + expect(shell.isSolved).toBe(false); + }); + + it("needs the newest backup copy, not the last one in the list", () => { + const wrong = play("linux-restore-backup", ["cp /backups/weekly/2025-12-21/site/config/prod.yml ~/site/config/"]); + expect(wrong.shell.isSolved).toBe(false); + }); + + it("needs kill -9 for the stubborn process", () => { + const soft = play("linux-runaway-process", ["kill 4242"]); + expect(soft.shell.st.procs.some((p) => p.pid === 4242)).toBe(true); + expect(run1("linux-runaway-process", "kill 77")).toContain("Operation not permitted"); + expect(run1("linux-runaway-process", "kill 99999")).toContain("No such process"); + }); + + it("rejects a wrong answer and keeps playing", () => { + const { shell, last } = play("linux-hidden-note", ["submit wrong"]); + expect(last).toContain("Not quite"); + expect(shell.isSolved).toBe(false); + }); +}); + +describe("the shell behaves like Linux", () => { + const E = "linux-hidden-note"; + + it("lists files, hides dotfiles, and shows them with -a and -l", () => { + expect(run1(E, "ls app")).toBe("README.md main.py requirements.txt static"); + expect(run1(E, "ls -a app")).toContain(".deploy_note"); + expect(run1(E, "ls app | wc -l")).toBe("4"); + const long = run1(E, "ls -l app"); + expect(long).toMatch(/^total \d+/); + expect(long).toMatch(/-rw-r--r-- 1 ops ops +\d+ \w{3} +\d+ +[\d:]+ main\.py/); + expect(long).toMatch(/drwxr-xr-x 2 ops ops +4096 .* static/); + }); + + it("changes folder and prints it", () => { + const { text, shell } = play(E, ["pwd", "cd app", "pwd", "cd ..", "pwd", "cd /nope", "cd app/main.py", "cd -", "cd"]); + expect(text.slice(0, 5)).toEqual(["/home/ops", "", "/home/ops/app", "", "/home/ops"]); + expect(text[5]).toBe("bash: cd: /nope: No such file or directory"); + expect(text[6]).toBe("bash: cd: app/main.py: Not a directory"); + expect(text[7]).toBe("/home/ops/app"); + expect(shell.st.cwd).toBe("/home/ops"); + expect(shell.prompt()).toBe("ops:~$"); + }); + + it("reads files and says when they are missing or locked", () => { + expect(run1(E, "cat app/.deploy_note")).toContain("Release word: BLUEFOX-42"); + expect(run1(E, "cat nothing.txt")).toBe("cat: nothing.txt: No such file or directory"); + expect(run1(E, "cat /root/notes.txt")).toBe("cat: /root/notes.txt: Permission denied"); + expect(run1(E, "ls /root")).toBe("ls: cannot open directory '/root': Permission denied"); + expect(run1(E, "cat app")).toBe("cat: app: Is a directory"); + expect(run1(E, "head -n 1 app/.deploy_note")).toBe("Release word: BLUEFOX-42"); + expect(run1(E, "tail -n 1 app/.deploy_note")).toBe("Do not share this word outside the team."); + }); + + it("greps with the common flags", () => { + const f = "app/.deploy_note"; + expect(run1(E, `grep word ${f}`)).toContain("Release word"); + expect(run1(E, `grep -i RELEASE ${f}`)).toContain("Release word"); + expect(run1(E, `grep RELEASE ${f}`)).toBe(""); + expect(run1(E, `grep -n share ${f}`)).toBe("2:Do not share this word outside the team."); + expect(run1(E, `grep -c o ${f}`)).toBe("2"); + expect(run1(E, `grep -v Release ${f}`)).toBe("Do not share this word outside the team."); + expect(run1(E, `grep -E 'BLUE(FOX|BIRD)-[0-9]+' ${f}`)).toContain("BLUEFOX-42"); + expect(run1(E, `grep -o -E '[A-Z]+-[0-9]+' ${f}`)).toBe("BLUEFOX-42"); + expect(run1(E, "grep -r BLUEFOX app")).toBe("app/.deploy_note:Release word: BLUEFOX-42"); + expect(run1(E, "grep -rl flask app")).toBe("app/requirements.txt"); + expect(run1(E, "grep x missing.txt")).toBe("grep: missing.txt: No such file or directory"); + expect(run1(E, "grep '(' app/main.py")).toContain("print("); + expect(run1(E, "grep -E '(' app/main.py")).toBe("grep: Unmatched ( or \\("); + }); + + it("finds files by name, type, size and age", () => { + expect(run1(E, "find app -name '*.py'")).toBe("app/main.py"); + expect(run1(E, "find app -type d")).toBe("app\napp/static"); + expect(run1(E, "find . -iname readme.md")).toBe("./app/README.md"); + const big = run1("linux-biggest-file", "find downloads -size +500M"); + expect(big.split("\n").sort()).toEqual(["downloads/holiday-video.mp4", "downloads/setup.iso"]); + expect(run1("linux-biggest-file", "find downloads -type f -size -10k")).toBe("downloads/notes.txt"); + expect(run1("linux-old-temp-files", "find /var/tmp -name '*.tmp' -mtime +7").split("\n")).toEqual([ + "/var/tmp/cache-a.tmp", "/var/tmp/cache-b.tmp", "/var/tmp/render/frame1.tmp", "/var/tmp/session-91.tmp", + ]); + expect(run1(E, "find / -name '*.zzz'")).toContain("Permission denied"); + expect(run1(E, "find / -name '*.zzz' 2>/dev/null")).toBe(""); + expect(run1(E, "find /nope")).toBe("find: '/nope': No such file or directory"); + }); + + it("pipes data between commands", () => { + const L = "linux-count-requests"; + const log = "/var/log/webapp/access.log"; + expect(run1(L, `wc -l ${log}`)).toBe(`214 ${log}`); + expect(run1(L, `wc -l < ${log}`)).toBe("214"); + expect(run1(L, `cat ${log} | wc -l`)).toBe("214"); + expect(run1(L, `cat ${log} | head -n 3 | wc -l`)).toBe("3"); + const top = run1(L, `cut -d' ' -f1 ${log} | sort | uniq -c | sort -rn | head -n 2`); + expect(top.split("\n")).toHaveLength(2); + expect(top).toMatch(/^ +\d+ 10\.0\./); + const counts = top.split("\n").map((l) => Number(l.trim().split(" ")[0])); + expect(counts[0]!).toBeGreaterThanOrEqual(counts[1]!); + expect(run1(L, `grep -c ' 500 ' ${log}`)).toMatch(/^\d+$/); + expect(run1(L, `awk '{print $1}' ${log} | sort -u | wc -l`)).toBe("5"); + expect(run1(L, "echo a b c | wc -w")).toBe("3"); + expect(run1(L, "echo b; echo a")).toBe("b\na"); + }); + + it("sorts like sort", () => { + const { text } = play("linux-hidden-note", ["echo 10 > n.txt", "echo 9 >> n.txt", "echo 100 >> n.txt", "sort n.txt", "sort -n n.txt", "sort -rn n.txt", "sort -n n.txt | uniq -c"]); + expect(text[3]).toBe("10\n100\n9"); + expect(text[4]).toBe("9\n10\n100"); + expect(text[5]).toBe("100\n10\n9"); + expect(text[6]).toBe(" 1 9\n 1 10\n 1 100"); + }); + + it("writes files with redirects and appends", () => { + const { text, shell } = play("linux-hidden-note", ["echo hello > a.txt", "echo again >> a.txt", "cat a.txt", "echo new > a.txt", "cat a.txt", "ls > list.txt", "cat list.txt | wc -l"]); + expect(text[2]).toBe("hello\nagain"); + expect(text[4]).toBe("new"); + expect(Number(text[6])).toBeGreaterThan(1); + expect(shell.st.fs.text("/home/ops/a.txt")).toBe("new\n"); + expect(run1("linux-hidden-note", "echo x > /etc/hosts")).toBe("bash: /etc/hosts: Permission denied"); + expect(run1("linux-hidden-note", "echo x > /nope/a.txt")).toBe("bash: /nope/a.txt: No such file or directory"); + expect(run1("linux-hidden-note", "ls /nope 2> err.txt; cat err.txt")).toContain("No such file or directory"); + }); + + it("copies, moves, makes and removes", () => { + const { text, shell } = play("linux-hidden-note", [ + "mkdir work", "cp app/main.py work/", "ls work", "mv work/main.py work/run.py", "ls work", "mkdir -p a/b/c", "rm work", "rm -r work", "touch x y", "rm x", "rm nothing", "rm -f nothing", "cp app work2", "cp -r app app2", "ls app2", + ]); + expect(text[2]).toBe("main.py"); + expect(text[4]).toBe("run.py"); + expect(text[6]).toBe("rm: cannot remove 'work': Is a directory"); + expect(text[10]).toBe("rm: cannot remove 'nothing': No such file or directory"); + expect(text[11]).toBe(""); + expect(text[12]).toBe("cp: -r not specified; omitting directory 'app'"); + expect(text[14]).toContain("main.py"); + expect(shell.st.fs.peek("/home/ops/a/b/c")).not.toBeNull(); + expect(shell.st.fs.peek("/home/ops/work")).toBeNull(); + expect(shell.st.fs.peek("/home/ops/y")).not.toBeNull(); + expect(run1("linux-hidden-note", "rm -rf /")).toContain("dangerous"); + expect(run1("linux-hidden-note", "rm /etc/hosts")).toBe("rm: cannot remove '/etc/hosts': Permission denied"); + }); + + it("handles permissions: chmod, execute, denied", () => { + const P = "linux-script-permissions"; + expect(run1(P, "./backup.sh")).toBe("bash: ./backup.sh: Permission denied"); + expect(run1(P, "ls -l backup.sh")).toContain("-rw-r--r--"); + const { text, shell } = play(P, ["chmod +x backup.sh", "ls -l backup.sh", "./backup.sh", "ls ~/backup", "chmod 600 backup.sh", "ls -l backup.sh", "chmod u+x,go-r backup.sh", "ls -l backup.sh"]); + expect(text[1]).toContain("-rwxr-xr-x"); + expect(text[2]).toBe("Starting backup...\nBackup complete"); + expect(text[3]).toBe("notes.txt"); + expect(text[5]).toContain("-rw-------"); + expect(text[7]).toContain("-rwx------"); + expect(shell.st.executed).toEqual([{ path: "/home/ops/scripts/backup.sh", code: 0 }]); + expect(run1(P, "chmod 755 /etc/hosts")).toBe("chmod: changing permissions of '/etc/hosts': Operation not permitted"); + expect(run1(P, "chmod 999 backup.sh")).toContain("invalid mode"); + expect(run1(P, "bash backup.sh")).toContain("Backup complete"); + }); + + it("measures disk use with du and df", () => { + const D = "linux-full-disk"; + expect(run1(D, "df -h")).toContain("97%"); + const du = run1(D, "du -sh /var/*"); + expect(du).toMatch(/^5\.\d+G\t\/var\/backups$/m); + expect(du).toMatch(/\t\/var\/lib$/m); + expect(du).toContain("Permission denied"); + expect(run1(D, "du -sh /var/backups")).toMatch(/^5\.\dG\t\/var\/backups$/); + expect(run1(D, "du -h --max-depth=1 /var/cache")).toContain("/var/cache/apt"); + expect(run1(D, "du -sh /var/* 2>/dev/null | sort -h | tail -n 1")).toMatch(/\/var\/backups$/); + }); + + it("lists processes and finds them by name", () => { + const K = "linux-runaway-process"; + const out = run1(K, "ps aux"); + expect(out).toMatch(/^USER +PID +%CPU/); + expect(out).toContain("/opt/tools/reindex"); + expect(run1(K, "ps aux | grep reindex")).toContain("4242"); + expect(run1(K, "pgrep reindex")).toBe("4242"); + expect(play(K, ["kill $(pgrep reindex)", "pgrep reindex"]).last).toBe("4242"); + const killed = play(K, ["kill -9 $(pgrep reindex)", "pgrep reindex"]); + expect(killed.last).toBe(""); + expect(play(K, ["pkill -9 reindex", "ps aux"]).last).not.toContain("reindex"); + expect(run1(K, "kill abc")).toContain("arguments must be process or job IDs"); + }); + + it("expands variables, globs, quotes and command substitution", () => { + const E = "linux-hidden-note"; + expect(run1(E, "echo $HOME $USER")).toBe("/home/ops ops"); + expect(run1(E, "echo '$HOME'")).toBe("$HOME"); + expect(run1(E, 'echo "a b"')).toBe("a b"); + expect(run1(E, "echo a b")).toBe("a b"); + expect(run1(E, "echo ~")).toBe("/home/ops"); + expect(run1(E, "echo app/*.py")).toBe("app/main.py"); + expect(run1(E, "echo app/*.zip")).toBe("app/*.zip"); + expect(run1(E, "echo $(whoami)")).toBe("ops"); + expect(run1(E, "export NAME=Eda && echo hi $NAME")).toBe("hi Eda"); + expect(run1(E, "echo $?")).toBe("0"); + expect(run1(E, "cat app/*.md app/main.py")).toContain("orbit app starting"); + }); + + it("chains with && and ||", () => { + const E = "linux-hidden-note"; + expect(run1(E, "ls app && echo yes")).toContain("yes"); + expect(run1(E, "ls nope && echo yes")).not.toContain("yes"); + expect(run1(E, "ls nope || echo recovered")).toContain("recovered"); + expect(run1(E, "ls nope 2>/dev/null || echo recovered")).toBe("recovered"); + expect(run1(E, "false || true && echo ok")).toBe("ok"); + }); + + it("says command not found, and explains what is missing", () => { + expect(run1("linux-hidden-note", "foobar")).toBe("bash: foobar: command not found"); + expect(run1("linux-hidden-note", "nano x")).toContain("not available on this practice server"); + expect(run1("linux-hidden-note", "sudo ls")).toContain("sudoers"); + expect(run1("linux-hidden-note", "ls -z")).toContain("invalid option -- 'z'"); + expect(run1("linux-hidden-note", "echo 'open")).toContain("unexpected EOF"); + expect(run1("linux-hidden-note", "ls | | wc")).toContain("syntax error"); + expect(run1("linux-hidden-note", "ls &")).toContain("background"); + }); + + it("whoami, id, which, history, help, man, clear", () => { + const E = "linux-hidden-note"; + expect(run1(E, "whoami")).toBe("ops"); + expect(run1(E, "id")).toContain("uid=1000(ops)"); + expect(run1(E, "which ls")).toBe("/usr/bin/ls"); + expect(play(E, ["pwd", "ls", "history"]).last).toContain("3 history"); + expect(run1(E, "help")).toContain("grep"); + expect(run1(E, "commands")).toContain("find"); + expect(run1(E, "man grep")).toContain("Usage: grep"); + expect(run1(E, "man zzz")).toContain("No manual entry"); + expect(run1(E, "grep --help")).toContain("Usage: grep"); + const shell = new Shell(missionById(E)!); + shell.run("ls"); + expect(shell.run("clear").clear).toBe(true); + }); + + it("counts hints and commands (help, hint, history, clear and man are free)", () => { + const shell = new Shell(missionById("linux-hidden-note")!); + expect(shell.run("hint").lines[0]!.text).toMatch(/^Hint 1 of 3:/); + shell.run("help"); + shell.run("history"); + shell.run("clear"); + shell.run("man ls"); + expect(shell.commandCount).toBe(0); + expect(shell.hintCount).toBe(1); + shell.run("ls"); + expect(shell.commandCount).toBe(1); + shell.run("hint"); + shell.run("hint"); + expect(shell.run("hint").lines[0]!.text).toContain("No more hints"); + expect(shell.hintCount).toBe(3); + }); + + it("gives stars by commands and hints", () => { + const m = missionById("linux-hidden-note")!; + const r = { ...linuxEngine.roundsFor("2026-11-18")[0]!, id: m.id }; + const slow = [...m.solution.slice(0, 2), "pwd", "pwd", "pwd", "pwd", ...m.solution.slice(2)]; + expect(linuxEngine.verify(r, { commands: m.solution, hints: 0 }).stars).toBe(3); + expect(linuxEngine.verify(r, { commands: ["hint", ...m.solution], hints: 0 }).stars).toBe(2); + expect(linuxEngine.verify(r, { commands: ["hint", "hint", ...m.solution], hints: 0 }).stars).toBe(1); + expect(linuxEngine.verify(r, { commands: m.solution, hints: 2 }).stars).toBe(1); + expect(linuxEngine.verify(r, { commands: ["ls", ...m.solution], hints: 0 }).stars).toBe(2); + expect(linuxEngine.verify(r, { commands: slow, hints: 0 }).stars).toBe(2); + expect(linuxEngine.verify(r, { commands: [...slow, "ls"], hints: 0 }).stars).toBe(2); + expect(linuxEngine.verify(r, { commands: ["pwd", "pwd", "pwd", "pwd", "pwd", "pwd", ...m.solution], hints: 0 }).stars).toBe(1); + }); + + it("matches patterns without backtracking trouble", () => { + const m = compilePatterns(["(a+)+b"], { ere: true, ignoreCase: false }); + expect("error" in m).toBe(false); + if (!("error" in m)) { + const start = Date.now(); + expect(m.test("a".repeat(400))).toBe(false); + expect(Date.now() - start).toBeLessThan(2000); + expect(m.test("aaab")).toBe(true); + } + expect(globMatch("*.log", "a.log")).toBe(true); + expect(globMatch("a?c", "abc")).toBe(true); + expect(globMatch("[a-c]x", "bx")).toBe(true); + expect(globMatch("*a*a*a*b", "a".repeat(200))).toBe(false); + expect("error" in compilePatterns(["(unclosed"], { ere: true, ignoreCase: false })).toBe(true); + expect("error" in compilePatterns(["[abc"], { ere: false, ignoreCase: false })).toBe(true); + }); +}); + +describe("submissions", () => { + const good: LinuxSubmission = { commands: ["ls", "pwd"], hints: 0 }; + + it("parseSubmission accepts a well formed submission", () => { + expect(linuxEngine.parseSubmission(good)).toEqual(good); + expect(linuxEngine.parseSubmission({ commands: [], hints: 0 })).toEqual({ commands: [], hints: 0 }); + }); + + it("parseSubmission rejects junk", () => { + const junk: unknown[] = [ + null, undefined, 0, "ls", [], [["ls"]], {}, { commands: "ls", hints: 0 }, { commands: ["ls"] }, { commands: ["ls"], hints: -1 }, + { commands: ["ls"], hints: 1.5 }, { commands: ["ls"], hints: "0" }, { commands: ["ls"], hints: 99 }, { commands: [1, 2], hints: 0 }, + { commands: [null], hints: 0 }, { commands: ["x".repeat(501)], hints: 0 }, { commands: Array(251).fill("ls"), hints: 0 }, + { commands: ["ls\nrm -rf x"], hints: 0 }, { commands: ["ls\u0000"], hints: 0 }, { commands: ["ls"], hints: 0, extra: true }, + { done: true }, { commands: { length: 1, 0: "ls" }, hints: 0 }, + ]; + for (const j of junk) expect(linuxEngine.parseSubmission(j)).toBeNull(); + }); + + it("verify never throws on odd input", () => { + const r = linuxEngine.roundsFor("2026-11-18")[2]!; + const odd: string[] = [ + "x".repeat(5000), "x".repeat(500), "\u0000\u0001", "💥🔥 ünï", "$(" + "$(".repeat(30), "echo $(echo $(echo $(echo $(echo hi))))", + "((((((((", "\\", "'", '"', "`", "| | |", "&&", ">>", "> ", "2>&1", "ls " + "../".repeat(200), "cat " + "a/".repeat(300), "grep -E '(((((((a' x", "grep '[' x", "find / -exec", "find / -exec ls", + "find / -name", "sed s/a/b", "sed -i", "awk", "awk '{", "sort -k", "cut", "cut -d", "head -n x", "tail -n", "kill", "kill -", "chmod", "chmod +x", "cp", "mv a", "xargs", "wc -z", "ls -R /", "du -ah /", + "find / -type f | xargs cat | sort | uniq -c | sort -rn | head", "echo * * * * *", "echo ?????????? [[[[", "cat /dev/null", "yes", "rm -rf *", "rm -rf /home", "cd ../../../../..", "echo $HOME$HOME$HOME > /tmp/" + "a".repeat(300), + "ls /*/*/*/*", "grep -r . /", "cat /etc/passwd | cat | cat | cat", "history", "hint", "submit", "submit " + "9".repeat(400), "man", "bash", "bash x", "./nope", "/bin/ls", "FOO=bar", "FOO=bar ls", + ]; + for (const m of MISSIONS) { + const target = { ...r, id: m.id }; + expect(() => linuxEngine.verify(target, { commands: odd, hints: 0 })).not.toThrow(); + const res = linuxEngine.verify(target, { commands: odd, hints: 0 }); + expect(typeof res.message).toBe("string"); + expect(res.stars).toBeGreaterThanOrEqual(0); + } + expect(() => linuxEngine.verify({ ...r, id: "does-not-exist" }, good)).not.toThrow(); + expect(linuxEngine.verify({ ...r, id: "does-not-exist" }, good).passed).toBe(false); + expect(() => linuxEngine.verify(null as never, null as never)).not.toThrow(); + expect(() => linuxEngine.verify({} as never, { commands: [5 as never], hints: 0 })).not.toThrow(); + }); + + it("keeps long and fast runs bounded", () => { + const start = Date.now(); + const cmds = Array(200).fill("cat /etc/passwd /etc/passwd /etc/passwd | grep -E '(a|b)*c' | sort | uniq -c"); + cmds.push("echo aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa > big", ...Array(30).fill("cat big big big big big big big big >> big")); + const r = linuxEngine.verify({ ...linuxEngine.roundsFor("2026-11-18")[0]!, id: "linux-hidden-note" }, { commands: cmds.slice(0, 250), hints: 0 }); + expect(r.passed).toBe(false); + expect(Date.now() - start).toBeLessThan(10_000); + }); + + it("is a replay: the same commands always give the same result", () => { + const m = MISSIONS[0]!; + const sub = { commands: [...m.solution], hints: 0 }; + const r = linuxEngine.roundsFor("2026-11-18")[0]!; + const a = linuxEngine.verify({ ...r, id: m.id }, sub); + const b = linuxEngine.verify({ ...r, id: m.id }, sub); + expect(a).toEqual(b); + }); +}); + +describe("daily rotation", () => { + it("returns one mission per difficulty, in order, with plain JSON round data", () => { + const rounds = linuxEngine.roundsFor("2026-11-18"); + expect(rounds.map((r) => r.difficulty)).toEqual([...DIFFICULTIES]); + for (const r of rounds) { + expect(JSON.parse(JSON.stringify(r))).toEqual(r); + expect(missionById(r.id)).not.toBeNull(); + expect(r.objectives.length).toBeGreaterThanOrEqual(3); + expect(["answer", "state"]).toContain(r.kind); + } + }); + + it("is the same for everyone on one day and varies by day", () => { + expect(linuxEngine.roundsFor("2026-11-18")).toEqual(linuxEngine.roundsFor("2026-11-18")); + const ids = (d: string) => linuxEngine.roundsFor(d).map((r) => r.id).join(); + expect(ids("2026-11-18")).not.toBe(ids("2026-11-19")); + const seen = new Set(); + for (let d = 1; d <= 6; d++) for (const r of linuxEngine.roundsFor(`2026-12-${String(d).padStart(2, "0")}`)) seen.add(r.id); + expect(seen.size).toBeGreaterThanOrEqual(10); + }); + + it("builds a session for a known round only", () => { + expect(createLinuxSession(linuxEngine.roundsFor("2026-11-18")[0]!)).not.toBeNull(); + expect(createLinuxSession({ id: "nope" })).toBeNull(); + }); + + it("uses plain text with no dashes in titles and briefs", () => { + for (const r of MISSIONS) expect(`${r.title} ${r.brief}`).not.toMatch(/[–—]/); + }); + + it("round helper is available", () => { + expect(round("linux-hidden-note").id).toBe("linux-hidden-note"); + }); +}); diff --git a/server/tests/unit/shared/games/sysdesign.test.ts b/server/tests/unit/shared/games/sysdesign.test.ts new file mode 100644 index 00000000..4f03acdc --- /dev/null +++ b/server/tests/unit/shared/games/sysdesign.test.ts @@ -0,0 +1,186 @@ +import { describe, expect, it } from "vitest"; +import { seededRandom } from "../../../../src/shared/games/daily.js"; +import { sysdesignEngine, simulate, STEPS, SYSDESIGN_POOL, type SysdesignRound } from "../../../../src/shared/games/sysdesign/engine.js"; + +const engine = sysdesignEngine; +const verify = (round: SysdesignRound, changes: string[]) => engine.verify(round, { changes }); + +function subsets(ids: string[], max: number): string[][] { + const out: string[][] = [[]]; + const walk = (start: number, current: string[]) => { + if (current.length >= max) return; + for (let i = start; i < ids.length; i++) { + const next = [...current, ids[i]!]; + out.push(next); + walk(i + 1, next); + } + }; + walk(0, []); + return out; +} + +describe("sysdesign pool", () => { + it("has at least four scenarios per difficulty and twelve in total, with unique ids", () => { + for (const difficulty of ["easy", "medium", "hard"] as const) { + expect(SYSDESIGN_POOL.filter((r) => r.difficulty === difficulty).length).toBeGreaterThanOrEqual(4); + } + expect(SYSDESIGN_POOL.length).toBeGreaterThanOrEqual(12); + expect(new Set(SYSDESIGN_POOL.map((r) => r.id)).size).toBe(SYSDESIGN_POOL.length); + expect(new Set(SYSDESIGN_POOL.map((r) => r.title)).size).toBe(SYSDESIGN_POOL.length); + }); + + it("has well formed data and plain text (no long dashes)", () => { + for (const r of SYSDESIGN_POOL) { + expect(r.traffic).toHaveLength(STEPS); + expect(r.traffic.every((n) => Number.isFinite(n) && n >= 0)).toBe(true); + expect(new Set(r.changes.map((c) => c.id)).size).toBe(r.changes.length); + expect(r.hints.length).toBeGreaterThanOrEqual(3); + expect(r.maxChanges).toBeGreaterThanOrEqual(r.solution.length); + expect(r.maxChanges).toBeLessThanOrEqual(5); + expect(JSON.stringify(r)).not.toMatch(/[–—]/); + } + }); + + it("round data survives JSON, because rounds travel as JSON", () => { + for (const r of SYSDESIGN_POOL) { + const copy = JSON.parse(JSON.stringify(r)) as SysdesignRound; + expect(verify(copy, r.solution)).toEqual(verify(r, r.solution)); + } + }); +}); + +describe.each(SYSDESIGN_POOL.map((r) => [r.id, r] as const))("scenario %s", (_id, round) => { + it("is really an incident: doing nothing fails", () => { + const result = verify(round, []); + expect(result.passed).toBe(false); + expect(result.stars).toBe(0); + expect(result.message.length).toBeGreaterThan(10); + }); + + it("is solved by its stated solution, with three stars", () => { + expect(round.solution.every((id) => round.changes.some((c) => c.id === id))).toBe(true); + const result = verify(round, round.solution); + expect(result.passed).toBe(true); + expect(result.stars).toBe(3); + expect(result.message).toMatch(/goals met/i); + }); + + it("does not give three stars to a single change when the solution needs several", () => { + if (round.solution.length < 2) return; + for (const change of round.changes) expect(verify(round, [change.id]).stars).toBeLessThan(3); + }); + + it("has a real trap that does not fix the incident and makes something worse", () => { + expect(round.trap).toBeTruthy(); + expect(round.changes.some((c) => c.id === round.trap)).toBe(true); + expect(round.solution).not.toContain(round.trap); + expect(verify(round, [round.trap!]).passed).toBe(false); + const base = simulate(round, []); + const trapped = simulate(round, [round.trap!]); + const worse = trapped.costUsd > base.costUsd || trapped.p95Ms > base.p95Ms || trapped.availability < base.availability; + expect(worse).toBe(true); + // Using the trap never earns three stars, even with the solution. + if (round.solution.length < round.maxChanges) { + expect(verify(round, [...round.solution, round.trap!]).stars).toBeLessThan(3); + } + }); + + it("explains which goal failed in one plain sentence", () => { + const result = verify(round, []); + expect(result.message).toMatch(/^Goal missed: .+ is .+, the goal is .+\.$/); + }); + + it("gives finite numbers and never throws for every allowed set of changes", () => { + for (const ids of subsets(round.changes.map((c) => c.id), round.maxChanges)) { + const sim = simulate(round, ids); + expect(sim.steps).toHaveLength(STEPS); + for (const n of [sim.p95Ms, sim.availability, sim.costUsd, sim.peakAppUtil, sim.peakDbUtil]) expect(Number.isFinite(n)).toBe(true); + expect(sim.availability).toBeGreaterThanOrEqual(0); + expect(sim.availability).toBeLessThanOrEqual(100); + expect(sim.steps.at(-1)!.costToDate).toBe(sim.costUsd); + const result = verify(round, ids); + if (!result.passed) expect(result.stars).toBe(0); + } + }); + + it("is deterministic and does not depend on a previous run", () => { + expect(simulate(round, round.solution)).toEqual(simulate(round, round.solution)); + }); + + it("rejects too many changes, repeated changes and unknown changes", () => { + const ids = round.changes.map((c) => c.id); + expect(verify(round, ids.slice(0, round.maxChanges + 1)).passed).toBe(false); + expect(verify(round, [...round.solution, round.solution[0]!]).passed).toBe(false); + expect(verify(round, ["not-a-real-change"]).passed).toBe(false); + }); +}); + +describe("daily rotation", () => { + it("gives easy, medium, hard, the same for everyone on a day", () => { + const a = engine.roundsFor("2026-11-18"); + expect(a.map((r) => r.difficulty)).toEqual(["easy", "medium", "hard"]); + expect(engine.roundsFor("2026-11-18").map((r) => r.id)).toEqual(a.map((r) => r.id)); + }); + + it("changes from day to day and walks the whole pool", () => { + const seen = new Set(); + let sameAsPrevious = 0; + let previous = ""; + for (let d = 1; d <= 8; d++) { + const day = `2026-12-0${d}`; + const ids = engine.roundsFor(day).map((r) => r.id).join(","); + if (ids === previous) sameAsPrevious++; + previous = ids; + engine.roundsFor(day).forEach((r) => seen.add(r.id)); + } + expect(sameAsPrevious).toBe(0); + expect(seen.size).toBe(SYSDESIGN_POOL.length); + }); +}); + +describe("parseSubmission", () => { + it("accepts a list of unique change ids", () => { + expect(engine.parseSubmission({ changes: [] })).toEqual({ changes: [] }); + expect(engine.parseSubmission({ changes: ["a", "b"] })).toEqual({ changes: ["a", "b"] }); + }); + + it("rejects junk", () => { + const junk: unknown[] = [ + null, undefined, 0, 1, "changes", true, [], ["a"], {}, { changes: "a" }, { changes: null }, { changes: [1] }, + { changes: [null] }, { changes: [""] }, { changes: ["a", "a"] }, { changes: ["x".repeat(65)] }, { changes: Array.from({ length: 9 }, (_, i) => `c${i}`) }, + { changes: ["a"], extra: 1 }, { done: true }, { changes: { 0: "a", length: 1 } }, { changes: [["a"]] }, { changes: [{ id: "a" }] }, + ]; + for (const value of junk) expect(engine.parseSubmission(value)).toBeNull(); + }); +}); + +describe("verify never throws", () => { + it("copes with random and broken parsed input", () => { + const rand = seededRandom(7); + for (const round of SYSDESIGN_POOL) { + const ids = [...round.changes.map((c) => c.id), "zzz", "", "__proto__", "constructor"]; + for (let i = 0; i < 40; i++) { + const count = Math.floor(rand() * 7); + const changes = Array.from({ length: count }, () => ids[Math.floor(rand() * ids.length)]!); + expect(() => engine.verify(round, { changes })).not.toThrow(); + } + expect(() => engine.verify(round, { changes: [1, null, {}] as unknown as string[] })).not.toThrow(); + expect(() => engine.verify(round, {} as never)).not.toThrow(); + expect(() => engine.verify(round, null as never)).not.toThrow(); + } + }); +}); + +describe("stars", () => { + it("gives one star for meeting the goals only, and more for the tighter target and fewer changes", () => { + const logs = SYSDESIGN_POOL.find((r) => r.id === "sd-logs-forever")!; + expect(verify(logs, ["glacier-lifecycle"]).stars).toBe(1); + expect(verify(logs, ["glacier-lifecycle", "compress-logs"]).stars).toBe(3); + const bill = SYSDESIGN_POOL.find((r) => r.id === "sd-bill-tripled")!; + expect(verify(bill, ["rightsize-app", "rightsize-db"]).stars).toBe(1); + expect(verify(bill, bill.solution).stars).toBe(3); + const outage = SYSDESIGN_POOL.find((r) => r.id === "sd-az-outage")!; + // The autoscaling group is extra, so it earns two stars (a fourth change), not three. + expect(verify(outage, [...outage.solution, "autoscaling"]).stars).toBeLessThan(3); + }); +}); From c67dad46b5f1fd24808ef7417bd42756d3fd855e Mon Sep 17 00:00:00 2001 From: Aqib Nawab Date: Wed, 18 Nov 2026 14:51:22 +0500 Subject: [PATCH 2/2] Rebuild the games in the lab look; System Design Runner now plays on the lab board The three daily games now share GameFrame, which copies the lab board's look: a dark header bar with the level and actions, three plain steps, the brief, and a checks list with Wait and Pass badges. The /puzzles hub has a how-it-works strip and flat cards with one Start button each. System Design Runner is now six real incident labs (two per difficulty, with a broken starting board, checks and a reference solution) played on the platform's own HldBoard. The lab model (catalog, types, tiered model, challenge) moved to server/src/shared/lab/engine so the server replays a submitted board with runChallenge before it records the round or pays XP. The old paths in packages/learning-ui re-export it, so existing labs are unchanged. HldBoard gets an optional onRunComplete callback. Linux Command Explorer and Docker Commands are redesigned around GameFrame: a dark terminal, a clear first command, a checks list, one primary action, and a mobile layout. Decorative stars, glow and ship art are removed. --- docs/17-daily-games.mdx | 5 + .../components/games/docker/build-play.tsx | 487 ++++++++------- .../src/components/games/docker/dock-view.tsx | 307 ++++------ .../components/games/docker/docker-play.tsx | 10 +- .../components/games/docker/docker-styles.tsx | 20 +- .../src/components/games/docker/fix-play.tsx | 122 ++-- .../components/games/docker/mission-panel.tsx | 172 ++++-- frontend/src/components/games/game-frame.tsx | 135 +++++ frontend/src/components/games/game-host.tsx | 24 +- frontend/src/components/games/games-hub.tsx | 79 ++- .../src/components/games/linux/linux-play.tsx | 124 +++- .../components/games/linux/mission-panel.tsx | 166 ++---- .../components/games/sysdesign/diagram.tsx | 247 -------- .../games/sysdesign/sysdesign-play.tsx | 493 ++++----------- frontend/src/shared/games/sysdesign/engine.ts | 204 +++++-- .../src/shared/games/sysdesign/incidents.ts | 563 ++++++++++++++++++ .../src/shared/games/sysdesign/scenarios.ts | 394 ------------ frontend/src/shared/games/sysdesign/sim.ts | 277 --------- frontend/src/shared/games/sysdesign/types.ts | 170 +----- frontend/src/shared/lab/engine/catalog.ts | 437 ++++++++++++++ frontend/src/shared/lab/engine/challenge.ts | 291 +++++++++ frontend/src/shared/lab/engine/hld-types.ts | 144 +++++ .../shared/lab/engine/tiered-architecture.ts | 538 +++++++++++++++++ packages/learning-ui/contracts.json | 6 +- packages/learning-ui/src/labs/HldBoard.tsx | 14 +- packages/learning-ui/src/labs/Lab.tsx | 7 +- packages/learning-ui/src/labs/catalog.ts | 437 +------------- packages/learning-ui/src/labs/challenge.ts | 291 +-------- .../src/labs/tiered-architecture.ts | 538 +---------------- packages/learning-ui/src/labs/types.ts | 157 +---- .../src/shared/lab/engine/catalog.ts | 437 ++++++++++++++ .../src/shared/lab/engine/challenge.ts | 291 +++++++++ .../src/shared/lab/engine/hld-types.ts | 144 +++++ .../shared/lab/engine/tiered-architecture.ts | 538 +++++++++++++++++ server/src/shared/games/sysdesign/engine.ts | 204 +++++-- .../src/shared/games/sysdesign/incidents.ts | 562 +++++++++++++++++ .../src/shared/games/sysdesign/scenarios.ts | 393 ------------ server/src/shared/games/sysdesign/sim.ts | 276 --------- server/src/shared/games/sysdesign/types.ts | 170 +----- server/src/shared/lab/engine/catalog.ts | 436 ++++++++++++++ server/src/shared/lab/engine/challenge.ts | 290 +++++++++ server/src/shared/lab/engine/hld-types.ts | 143 +++++ .../shared/lab/engine/tiered-architecture.ts | 537 +++++++++++++++++ .../tests/unit/shared/games/sysdesign.test.ts | 448 ++++++++++---- 44 files changed, 7097 insertions(+), 4631 deletions(-) create mode 100644 frontend/src/components/games/game-frame.tsx delete mode 100644 frontend/src/components/games/sysdesign/diagram.tsx create mode 100644 frontend/src/shared/games/sysdesign/incidents.ts delete mode 100644 frontend/src/shared/games/sysdesign/scenarios.ts delete mode 100644 frontend/src/shared/games/sysdesign/sim.ts create mode 100644 frontend/src/shared/lab/engine/catalog.ts create mode 100644 frontend/src/shared/lab/engine/challenge.ts create mode 100644 frontend/src/shared/lab/engine/hld-types.ts create mode 100644 frontend/src/shared/lab/engine/tiered-architecture.ts create mode 100644 packages/learning-ui/src/shared/lab/engine/catalog.ts create mode 100644 packages/learning-ui/src/shared/lab/engine/challenge.ts create mode 100644 packages/learning-ui/src/shared/lab/engine/hld-types.ts create mode 100644 packages/learning-ui/src/shared/lab/engine/tiered-architecture.ts create mode 100644 server/src/shared/games/sysdesign/incidents.ts delete mode 100644 server/src/shared/games/sysdesign/scenarios.ts delete mode 100644 server/src/shared/games/sysdesign/sim.ts create mode 100644 server/src/shared/lab/engine/catalog.ts create mode 100644 server/src/shared/lab/engine/challenge.ts create mode 100644 server/src/shared/lab/engine/hld-types.ts create mode 100644 server/src/shared/lab/engine/tiered-architecture.ts diff --git a/docs/17-daily-games.mdx b/docs/17-daily-games.mdx index a61e9ac4..5d42b76d 100644 --- a/docs/17-daily-games.mdx +++ b/docs/17-daily-games.mdx @@ -23,6 +23,10 @@ The same engine runs in the browser (instant feedback, animation) and on the ser The browser part is a play component, `frontend/src/components/games//-play.tsx`, default export, props `GamePlayProps` (`components/games/types.ts`). It draws the board or terminal and calls `onFinish(submission)` when the player is done. The shell (`game-host.tsx`) verifies, plays the result sound, shows stars, XP and confetti, saves the round for a signed-in learner, and offers the next round. A play component must reset itself when `attempt` changes (the shell also remounts it with a new `key`), and must ignore input while `locked`. +## System Design Runner uses the lab board + +The System Design game is not a separate board. Each round is a real lab spec (`HldLabSpec`) with a broken starting board, played on the same `HldBoard` as the labs, with the same Run tests flow, results and reference solution. The lab model moved to the shared contract (`server/src/shared/lab/engine/`: `catalog`, `hld-types`, `tiered-architecture`, `challenge`) so the server can replay a submitted board with `runChallenge`. The old paths in `packages/learning-ui/src/labs/` re-export it, so every lab works as before. A round passes when every check passes; stars come from cost against the reference solution. The six incidents are in `server/src/shared/games/sysdesign/incidents.ts` (two per difficulty). + ## Look and feel These are real games, not forms. Every game must have: @@ -30,6 +34,7 @@ These are real games, not forms. Every game must have: - **Sound.** Use `sounds` from props (`lib/games/audio.ts`: `key`, `enter`, `ok`, `error`, `snap`, `coin`, `whoosh`, `alarm`, `boot`, `win`, `fanfare`, `lose`). Add new synthesized effects to that file if a game needs one (keep them short and quiet). Sound is off for people who ask for reduced motion, and the shell has a mute switch. - **Motion with meaning:** packets flowing, bars filling, containers pulsing or shaking, layers stacking, counters ticking, shake on a mistake. Wrap decorative motion in `motion-safe:`; the game must still work with `motion-reduce`. - **Feedback on every action** (sound plus a visible change), a clear goal, a visible progress or score, a hint that costs a star, and a short, friendly message when something is wrong. +- Sit inside `GameFrame` (`components/games/game-frame.tsx`): the dark header bar with the level tag and actions, three plain steps, the brief, and a `CheckList` of Wait and Pass checks. It copies the lab board so a game looks like part of the platform. One obvious primary action per screen, no decoration that does not help the player act. - Use the Tailwind theme tokens (`bg-card`, `border-border`, `text-muted-foreground`, `bg-secondary`, `text-primary`, `brand-yellow`) so light and dark both work, and `GameTerminal` (`components/games/game-terminal.tsx`) for any terminal. Phone first: it must be playable at 375 px wide and with the keyboard alone, with labels on controls. - No em dashes or en dashes in any text, comment or test. Plain, short English, for a learner who may read English as a second language. diff --git a/frontend/src/components/games/docker/build-play.tsx b/frontend/src/components/games/docker/build-play.tsx index c52f36ac..05a656e1 100644 --- a/frontend/src/components/games/docker/build-play.tsx +++ b/frontend/src/components/games/docker/build-play.tsx @@ -1,17 +1,18 @@ "use client"; import { useCallback, useEffect, useMemo, useRef, useState, type DragEvent } from "react"; -import { AlertTriangle, ArrowDown, ArrowUp, CheckCircle2, Clock, Hammer, GripVertical, HardDrive, Layers, Play, X, Zap } from "lucide-react"; -import { Button } from "@/components/ui/button"; +import { ArrowDown, ArrowUp, GripVertical, X } from "lucide-react"; import { cn } from "@/lib/utils"; import type { GameSounds } from "@/lib/games/audio"; import { checkBuildGoal, simulateBuild, type BuildGoal, type BuildLayer, type BuildReport } from "@/shared/games/docker/builder"; import type { BuildRound, BuildSubmission } from "@/shared/games/docker/engine"; -import { MissionPanel } from "./mission-panel"; +import { GameFrame, type FrameCheck } from "../game-frame"; +import { HeaderActions, levelOf, MissionPanel, MobileBar, SectionLabel, Strip, type Primary } from "./mission-panel"; import { useReducedMotion } from "./docker-styles"; type Props = { round: BuildRound; + roundIndex: number; attempt: number; locked: boolean; sounds: GameSounds; @@ -22,56 +23,77 @@ type Phase = "edit" | "cold" | "rebuild" | "built" | "running" | "ran"; const RUN_GOALS = new Set(["runs", "reachable"]); -function layerTone(label: string): string { - const word = label.split(/[\s:]/)[0]?.toUpperCase() ?? ""; - if (word === "FROM") return "border-sky-500/60 bg-sky-500/10"; - if (word === "COPY") return "border-amber-500/60 bg-amber-500/10"; - if (word === "RUN") return "border-violet-500/60 bg-violet-500/10"; - return "border-border bg-secondary/60"; -} +const STEPS = [ + "Read the brief and the checks", + "Tap a piece to add it, or drag it. Drag to reorder", + "Press Build image, then Run", +]; +const COMPOSE_STEPS = [ + "Read the brief and the checks", + "Tap a choice for each blank, or drag it onto the blank", + "Press Build stack, then Run", +]; + +const seconds = (n: number) => `${n.toFixed(1)} s`; -function seconds(n: number) { - return `${n.toFixed(1)} s`; +type LiveNote = { tone: "good" | "bad"; tag: string; text: string; line: number | null }; + +/** Instant feedback while the player orders a Dockerfile, in plain words. It reads the same simulation the Build button uses. */ +function liveNote(round: BuildRound, texts: string[], steps: string[]): LiveNote | null { + if (round.kind !== "dockerfile" || texts.length === 0) return null; + const op = (t: string) => t.split(/\s+/)[0]?.toUpperCase() ?? ""; + if (op(texts[0]!) !== "FROM") return { tone: "bad", tag: "Fix this", text: "A Dockerfile starts with FROM. Move FROM to line 1.", line: 0 }; + const report = simulateBuild(round, steps); + if (report.error) return { tone: "bad", tag: "Fix this", text: report.error, line: Math.max(0, report.layers.length - 1) }; + const isInstall = (t: string) => /^RUN\s+(npm (ci|install)|pip install)/i.test(t); + const copyAll = texts.findIndex((t) => /^COPY\s+\.\s+\S+/i.test(t)); + const install = texts.findIndex(isInstall); + if (copyAll !== -1 && install !== -1 && copyAll < install) { + return { tone: "bad", tag: "Fix this", text: "COPY . . before the install breaks the cache. Every code change would reinstall all packages. Move COPY . . below the install.", line: copyAll }; + } + const cmd = texts.findIndex((t) => op(t) === "CMD"); + if (cmd !== -1 && cmd < texts.length - 1 && texts.slice(cmd + 1).some((t) => ["COPY", "RUN"].includes(op(t)))) { + return { tone: "bad", tag: "Fix this", text: "CMD should be the last line. It runs after the image is built.", line: cmd }; + } + if (report.cacheFriendly) return { tone: "good", tag: "Good", text: "This order keeps the cache: a code change only rebuilds the last layers.", line: null }; + return null; } -function LayerStack({ layers, mode, total }: { layers: BuildLayer[]; mode: "cold" | "rebuild"; total: number }) { +function LayerList({ layers, mode, compose }: { layers: BuildLayer[]; mode: "cold" | "rebuild"; compose: boolean }) { return ( -
    - {layers.map((layer, i) => ( -
  1. - - {layer.label} - {mode === "rebuild" ? ( - {layer.cached ? "CACHED" : "REBUILT"} - ) : null} - - {mode === "rebuild" ? (layer.cached ? "0.1 s" : seconds(layer.seconds)) : `${layer.sizeMb > 0 ? `+${layer.sizeMb} MB, ` : ""}${seconds(layer.seconds)}`} - - {layer.failed ? : null} -
  2. - ))} - {layers.length === 0 ?
  3. Waiting for the first layer ({total} in all)...
  4. : null} +
      + {layers.map((layer, i) => { + const cached = mode === "rebuild" && layer.cached; + const tag = layer.failed ? "Failed" : cached ? "Cached" : compose ? "Started" : "Built"; + return ( +
    1. + {i + 1} + {layer.label} + + {tag} + + {cached ? "0.1 s" : seconds(layer.seconds)} +
    2. + ); + })}
    ); } -function Tile({ icon, label, value, tone }: { icon: React.ReactNode; label: string; value: string; tone?: "good" | "bad" }) { - return ( -
    -

    {icon} {label}

    -

    {value}

    -
    - ); +function failDetail(report: BuildReport, goal: BuildGoal): string | undefined { + if (goal.kind === "rebuild") return `A rebuild takes ${seconds(report.rebuildSec)} now.`; + if (goal.kind === "size") return `The image is ${report.sizeMb} MB now.`; + if (goal.kind === "builds") return report.error ?? undefined; + return undefined; } /** Build mode: put a Dockerfile or a compose file together from pieces, build it, then run it. */ -export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { +export function BuildPlay({ round, roundIndex, attempt, locked, sounds, onFinish }: Props) { const compose = round.kind === "compose"; const reduced = useReducedMotion(); const [steps, setSteps] = useState([]); @@ -85,16 +107,21 @@ export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { const [runShown, setRunShown] = useState(0); const [note, setNote] = useState(null); const [dragOver, setDragOver] = useState(null); + const [dragging, setDragging] = useState(false); const timers = useRef([]); const firstAttempt = useRef(attempt); const byId = useMemo(() => new Map(round.pieces.map((p) => [p.id, p])), [round.pieces]); - const slots = round.slots ?? []; + const slots = useMemo(() => round.slots ?? [], [round.slots]); const submissionSteps = useMemo( () => (compose ? slots.filter((s) => picks[s.id]).map((s) => `${s.id}:${picks[s.id]}`) : steps), [compose, slots, picks, steps], ); const placed = compose ? Object.keys(picks).length : steps.length; + const live = useMemo( + () => liveNote(round, steps.map((id) => byId.get(id)?.text ?? ""), steps), + [round, steps, byId], + ); const clearTimers = useCallback(() => { timers.current.forEach((t) => window.clearTimeout(t)); @@ -164,11 +191,16 @@ export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { function onDragStart(event: DragEvent, payload: string) { event.dataTransfer.setData("text/plain", payload); event.dataTransfer.effectAllowed = "move"; + setDragging(true); + } + function onDragEnd() { + setDragging(false); + setDragOver(null); } function onDropAt(event: DragEvent, index: number) { event.preventDefault(); event.stopPropagation(); - setDragOver(null); + onDragEnd(); const payload = event.dataTransfer.getData("text/plain"); if (payload.startsWith("tray:")) addPiece(payload.slice(5), index); else if (payload.startsWith("row:")) { @@ -178,6 +210,7 @@ export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { } function onDropTray(event: DragEvent) { event.preventDefault(); + onDragEnd(); const payload = event.dataTransfer.getData("text/plain"); if (payload.startsWith("row:")) removePiece(Number(payload.slice(4))); } @@ -193,13 +226,14 @@ export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { } function dropOnSlot(event: DragEvent, slot: string) { event.preventDefault(); + onDragEnd(); const payload = event.dataTransfer.getData("text/plain"); if (!payload.startsWith("tray:")) return; const piece = byId.get(payload.slice(5)); if (piece?.slot === slot) pickPiece(slot, piece.id); else { sounds.error(); - setNote("That piece belongs to a different blank."); + setNote("That choice belongs to a different blank."); } } @@ -217,28 +251,31 @@ export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { setColdShown(layers.length); setRebuildShown(result.ok && !compose ? layers.length : 0); setPhase("built"); - result.ok ? sounds.ok() : sounds.error(); + if (result.ok) sounds.ok(); + else sounds.error(); return; } setColdShown(0); setPhase("cold"); sounds.whoosh(); - layers.forEach((_, i) => later(() => { setColdShown(i + 1); sounds.snap(); }, 420 * (i + 1))); - const coldEnd = 420 * (layers.length + 1); + layers.forEach((_, i) => later(() => { setColdShown(i + 1); sounds.snap(); }, 250 * (i + 1))); + const coldEnd = 250 * (layers.length + 1); if (!result.ok || compose) { later(() => { setPhase("built"); - result.ok ? sounds.ok() : sounds.error(); + if (result.ok) sounds.ok(); + else sounds.error(); }, coldEnd); return; } - later(() => { setPhase("rebuild"); setRebuildShown(0); sounds.whoosh(); }, coldEnd + 200); - let at = coldEnd + 200; + later(() => { setPhase("rebuild"); setRebuildShown(0); sounds.whoosh(); }, coldEnd + 150); + let at = coldEnd + 150; layers.forEach((layer, i) => { - at += layer.cached ? 160 : 420; - later(() => { setRebuildShown(i + 1); layer.cached ? sounds.coin() : sounds.snap(); }, at); + at += layer.cached ? 100 : 250; + later(() => { setRebuildShown(i + 1); if (layer.cached) sounds.coin(); + else sounds.snap(); }, at); }); - later(() => { setPhase("built"); sounds.ok(); }, at + 250); + later(() => { setPhase("built"); sounds.ok(); }, at + 200); } function run() { @@ -250,14 +287,15 @@ export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { const total = report.runLog.length; const finish = () => { setPhase("ran"); - report.started && report.reachable ? sounds.win(2) : sounds.error(); + if (report.started && report.reachable) sounds.win(2); + else sounds.error(); }; if (reduced || total === 0) { setRunShown(total); return finish(); } - report.runLog.forEach((_, i) => later(() => { setRunShown(i + 1); sounds.key(); }, 500 * (i + 1))); - later(finish, 500 * (total + 1)); + report.runLog.forEach((_, i) => later(() => { setRunShown(i + 1); sounds.key(); }, 350 * (i + 1))); + later(finish, 350 * (total + 1)); } function revealHint() { @@ -267,38 +305,37 @@ export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { } const ranOrBuilt = phase === "built" || phase === "running" || phase === "ran"; - const goals = round.goals.map((g) => { - if (!report) return { label: g.label, met: null }; - if (RUN_GOALS.has(g.kind) && phase !== "ran") return { label: g.label, met: null }; - if (phase === "cold" || phase === "rebuild") return { label: g.label, met: null }; - return { label: g.label, met: checkBuildGoal(report, g) }; + const checks: FrameCheck[] = round.goals.map((g, i) => { + const id = String(i); + if (!report || (RUN_GOALS.has(g.kind) && phase !== "ran") || phase === "cold" || phase === "rebuild") return { id, label: g.label, state: "wait" }; + const met = checkBuildGoal(report, g); + return { id, label: g.label, state: met ? "pass" : "fail", detail: met ? undefined : failDetail(report, g) }; }); - const allMet = phase === "ran" && goals.every((g) => g.met); + const passed = checks.filter((c) => c.state === "pass").length; + const allMet = phase === "ran" && passed === checks.length; const unplaced = round.pieces.filter((p) => !steps.includes(p.id)); const slotPieces = round.pieces.filter((p) => p.slot === activeSlot); - const busy = phase === "cold" || phase === "rebuild" || phase === "running"; + const activeLabel = slots.find((s) => s.id === activeSlot)?.label; + + let primary: Primary; + if (phase === "cold" || phase === "rebuild") primary = { label: "Building...", onClick: () => {}, disabled: true }; + else if (phase === "running") primary = { label: "Running...", onClick: () => {}, disabled: true }; + else if (phase === "built" && report?.ok) primary = { label: "Run", onClick: run, pulse: true }; + else if (phase === "ran") primary = { label: "Finish", onClick: () => onFinish({ mode: "build", steps: submissionSteps, hints: hintsUsed }), disabled: !allMet, pulse: allMet }; + else primary = { label: compose ? "Build stack" : "Build image", onClick: build, disabled: placed === 0 }; const coldLayers = report ? report.layers.slice(0, coldShown) : []; const coldDone = report !== null && coldShown >= report.layers.length; - const pct = report && report.layers.length ? Math.round((coldShown / report.layers.length) * 100) : 0; const rebuildLayers = report ? report.layers.slice(0, rebuildShown) : []; - const rebuildTime = rebuildLayers.reduce((sum, l) => sum + (l.cached ? 0.1 : l.seconds), 0); - const coldTime = coldLayers.reduce((sum, l) => sum + l.seconds, 0); const rebuildActive = report?.ok && !compose && (phase === "rebuild" || ranOrBuilt); + const noun = compose ? "blanks" : "pieces"; const tray = ( -
    e.preventDefault()} - onDrop={onDropTray} - > -

    - {compose ? `Choices for: ${slots.find((s) => s.id === activeSlot)?.label ?? "pick a blank"}` : "Pieces"} -

    -

    - {compose ? "Tap a choice, or drag it onto its blank. Only one is right." : "Tap a piece to add it, or drag it into the Dockerfile. Drag a line back here to take it out."} -

    -
    +
    e.preventDefault()} onDrop={onDropTray}> + + {compose ? `Choices for: ${activeLabel ?? "pick a blank"}` : "Pieces"} + +
    {(compose ? slotPieces : unplaced).map((p) => { const selected = compose && picks[p.slot ?? ""] === p.id; return ( @@ -308,193 +345,201 @@ export function BuildPlay({ round, attempt, locked, sounds, onFinish }: Props) { draggable={!locked} disabled={locked} onDragStart={(e) => onDragStart(e, `tray:${p.id}`)} + onDragEnd={onDragEnd} onClick={() => (compose ? pickPiece(p.slot ?? "", p.id) : addPiece(p.id))} aria-pressed={compose ? selected : undefined} className={cn( - "min-h-10 cursor-grab rounded-md border bg-secondary px-3 py-2 text-left font-mono text-[13px] shadow-sm transition-transform hover:-translate-y-0.5 hover:border-primary focus-visible:outline focus-visible:outline-2 focus-visible:outline-primary active:cursor-grabbing disabled:opacity-50", - selected ? "border-emerald-500 bg-emerald-500/10" : "border-border", + "min-h-11 cursor-grab break-all border px-3 py-2 text-left font-mono text-[14px] transition-colors hover:border-primary focus-visible:outline focus-visible:outline-2 focus-visible:outline-primary active:cursor-grabbing disabled:opacity-50", + selected ? "border-emerald-500 bg-emerald-50 dark:bg-emerald-950/40" : "border-border bg-card", )} > {p.text} ); })} - {!compose && unplaced.length === 0 ?

    Every piece is placed. Take one out if you want to change it.

    : null} + {!compose && unplaced.length === 0 ?

    Every piece is placed. Take one out to change the order.

    : null}
    -
    + ); + const gutter = "w-8 shrink-0 select-none border-r border-[var(--code-border)] bg-black/[0.04] pr-2 text-right font-mono text-[12px] leading-[2.75rem] text-muted-foreground dark:bg-white/[0.04]"; + const surface = compose ? ( -
    -

    docker-compose.yml

    -
    +
    + docker-compose.yml +
      {(round.skeleton ?? []).map((line, i) => { - if ("text" in line) return
      {line.text}
      ; + if ("text" in line) { + return ( +
    1. + {i + 1} + {line.text} +
    2. + ); + } const slot = slots.find((s) => s.id === line.slot)!; const chosen = picks[slot.id] ? byId.get(picks[slot.id]!) : undefined; + const active = activeSlot === slot.id; return ( - +
    3. + {i + 1} + +
    4. ); })} -
    -
    - ) : ( -
    e.preventDefault()} onDrop={(e) => onDropAt(e, steps.length)}> -

    Dockerfile

    -
      - {steps.map((id, i) => ( -
    1. onDragStart(e, `row:${i}`)} - onDragOver={(e) => { e.preventDefault(); setDragOver(i); }} - onDragLeave={() => setDragOver(null)} - onDrop={(e) => onDropAt(e, i)} - className={cn( - "flex items-center gap-1.5 rounded-sm border border-transparent bg-background/60 py-0.5 pl-1 pr-0.5 motion-safe:animate-[bm-pop_0.25s_ease-out_both]", - dragOver === i && "border-primary", - )} - > - - {i + 1} - {byId.get(id)?.text} - - - -
    2. - ))}
    - {steps.length === 0 ?

    Empty. Add the first line (FROM).

    : null} - {steps.length > 0 && dragOver === null ?
    : null} -
    + {note ?

    {note}

    : null} + + ) : ( +
    e.preventDefault()} onDrop={(e) => onDropAt(e, steps.length)}> + Dockerfile +
    + {steps.length === 0 ? ( +

    Tap a piece to add the first line

    + ) : ( +
      + {steps.map((id, i) => { + const bad = live?.tone === "bad" && live.line === i; + return ( +
    1. onDragStart(e, `row:${i}`)} + onDragEnd={onDragEnd} + onDragOver={(e) => { e.preventDefault(); setDragOver(i); }} + onDragLeave={() => setDragOver(null)} + onDrop={(e) => onDropAt(e, i)} + className={cn( + "flex min-h-11 items-stretch border-b border-[var(--code-border)] last:border-b-0 sm:cursor-grab", + bad && "bg-red-50 dark:bg-red-950/40", + dragOver === i && "shadow-[inset_0_2px_0_0_var(--color-primary)]", + )} + > + {i + 1} + + {byId.get(id)?.text} + + + +
    2. + ); + })} +
    + )} + {dragging ?

    Drop here to add at the end

    : null} +
    +
    + {live ? ( + {live.text} + ) : steps.length > 0 ? ( +

    No problem found so far. Press Build image when the lines are in order.

    + ) : null} +
    +
    ); const buildPanel = ( -
    -
    - - - {note ? {note} : null} -
    +
    + + {compose ? "Pull and start" : "Build"} + {!report ? ( -

    - {compose ? "Fill every blank, then build. Docker pulls each image and starts the services in order." : "Put the lines in order, then build. Each line becomes a layer, and Docker reuses a layer when nothing above it changed."} +

    + {compose + ? "Nothing started yet. Fill every blank, then press Build stack." + : "Nothing built yet. Each line becomes a layer. Docker reuses a layer when nothing above it changed."}

    ) : ( -
    -
    -
    - {compose ? "Pull and create" : "Build"} - {coldShown}/{report.layers.length || 0} {compose ? "images" : "layers"} -
    -
    -
    -
    - - {coldDone && report.error ? ( -

    - {report.error} -

    - ) : null} - {coldDone && !report.error && report.warnings.length > 0 ? ( -
      {report.warnings.map((w) =>
    • Warning: {w}
    • )}
    - ) : null} -
    - - {rebuildActive ? ( -
    -
    - Change one line of code, build again - {rebuildShown}/{report.layers.length} -
    - -
    + <> + + {coldDone && report.error ? {report.error} : null} + {coldDone && report.ok ? ( + + {compose + ? `${report.layers.length} services ready in ${seconds(report.coldSec)}.` + : `Built in ${seconds(report.coldSec)}. Image is ${report.sizeMb} MB. A rebuild takes ${seconds(report.rebuildSec)}.`} + ) : null} + {coldDone && report.ok && phase !== "cold" ? report.warnings.map((w) => {w}) : null} - {report.ok ? ( -
    - } label={compose ? "Pull time" : "Build time"} value={seconds(phase === "cold" ? coldTime : report.coldSec)} /> - {compose ? ( - } label="Services" value={String(report.layers.length)} /> - ) : ( - } label="Rebuild" value={seconds(phase === "rebuild" ? rebuildTime : report.rebuildSec)} tone={ranOrBuilt ? (report.cacheFriendly ? "good" : "bad") : undefined} /> - )} - } label="Image size" value={`${report.sizeMb} MB`} /> + {rebuildActive ? ( +
    + Rebuild after a code change +
    ) : null} {(phase === "running" || phase === "ran") && report.ok ? ( -
    -

    {compose ? "Services" : "Container"}

    -
    +
    + {compose ? "Services" : "Container"} +
    {report.runLog.slice(0, runShown).map((line, i) => ( -
    {line}
    +
    {line}
    ))}
    {phase === "ran" ? ( -

    - {report.started && report.reachable ? : } - {report.started && report.reachable ? (compose ? `Everything is up and localhost:${report.port} answers.` : `The container is running and localhost:${report.port} answers.`) : report.started ? "It runs, but nobody can reach it yet." : "It did not start."} -

    + report.started && report.reachable ? ( + {compose ? `Every service is up and localhost:${report.port} answers.` : `The container runs and localhost:${report.port} answers.`} + ) : ( + {report.started ? "It runs, but nobody can reach it yet. Check the port." : "It did not start. Read the log above."} + ) ) : null}
    ) : null} -
    + )}
    ); + const { level, levelNumber } = levelOf(roundIndex); return ( -
    - { sounds.whoosh(); resetAll(); }} - onFinish={() => onFinish({ mode: "build", steps: submissionSteps, hints: hintsUsed })} - finishLabel={allMet ? "Finish: all goals met" : "Finish and check"} - canFinish={placed > 0} - ready={allMet} - locked={locked} - /> -
    -
    - {tray} - {surface} + <> + { sounds.whoosh(); resetAll(); }} primary={primary} locked={locked} />} + > + {/* On a phone the order is pieces, Dockerfile, checks, build. On a desktop it is two columns: pieces and checks, then Dockerfile and build. */} +
    +
    +
    {tray}
    +
    + +
    +
    +
    +
    {surface}
    +
    {buildPanel}
    +
    -
    {buildPanel}
    -
    -
    + + + ); } diff --git a/frontend/src/components/games/docker/dock-view.tsx b/frontend/src/components/games/docker/dock-view.tsx index d7779bfe..0dbeb5ca 100644 --- a/frontend/src/components/games/docker/dock-view.tsx +++ b/frontend/src/components/games/docker/dock-view.tsx @@ -1,222 +1,169 @@ "use client"; -import { Box, Cylinder, Globe, HardDrive, Network, RotateCw, X } from "lucide-react"; -import { CATALOG, diskUsedMb, fmtSize, portsText, statusText, type Container, type DockerWorld } from "@/shared/games/docker/daemon"; +import type { ReactNode } from "react"; +import { diskUsedMb, fmtSize, portsText, statusText, type Container, type DockerWorld } from "@/shared/games/docker/daemon"; import { cn } from "@/lib/utils"; +import { SectionLabel } from "./mission-panel"; const DISK_MB = 2000; - -const NET_TONES = [ - "border-sky-500/50 bg-sky-500/10 text-sky-700 dark:text-sky-300", - "border-violet-500/50 bg-violet-500/10 text-violet-700 dark:text-violet-300", - "border-pink-500/50 bg-pink-500/10 text-pink-700 dark:text-pink-300", - "border-teal-500/50 bg-teal-500/10 text-teal-700 dark:text-teal-300", -]; +const BUILT_IN_NETWORKS = ["bridge", "host", "none"]; export type Probe = { port: number; ok: boolean } | null; +export type ContainerState = "running" | "exited" | "crashed" | "restarting" | "created"; -function Whale({ className }: { className?: string }) { - return ( - - - - - - - - - - - - - - - - ); -} - -function stateOf(c: Container): "running" | "exited" | "crashed" | "restarting" | "created" { +/** "crashed" is an exit with a code other than 0. */ +export function stateOf(c: Container): ContainerState { if (c.status === "exited" && c.exitCode !== 0) return "crashed"; return c.status; } -const TONE: Record, string> = { - running: "border-emerald-500/70 bg-emerald-500/10", - exited: "border-border bg-muted/50 opacity-80", - crashed: "border-red-500/70 bg-red-500/10", - restarting: "border-amber-500/70 bg-amber-500/10", - created: "border-dashed border-border bg-muted/30", +const LOOK: Record = { + running: { box: "border-l-emerald-500 bg-emerald-50 dark:bg-emerald-950/30", tag: "bg-emerald-600 text-white", label: "Running" }, + exited: { box: "border-l-slate-400 bg-secondary/60", tag: "bg-slate-500 text-white", label: "Exited" }, + crashed: { box: "border-l-red-500 bg-red-50 dark:bg-red-950/30", tag: "bg-red-600 text-white", label: "Crashed" }, + restarting: { box: "border-l-amber-500 bg-amber-50 dark:bg-amber-950/30", tag: "bg-amber-500 text-slate-950", label: "Restarting" }, + created: { box: "border-l-slate-300 bg-secondary/40", tag: "bg-slate-400 text-white", label: "Created" }, }; -function StateDot({ state }: { state: ReturnType }) { - if (state === "restarting") return ; - const color = state === "running" ? "bg-emerald-500" : state === "crashed" ? "bg-red-500" : "bg-muted-foreground/60"; - return ; +function Row({ label, children }: { label: string; children: ReactNode }) { + return ( +
    +
    {label}
    +
    {children}
    +
    + ); } -/** Colour for a network name, the same every time. */ -function netTone(world: DockerWorld, name: string): string { - const user = world.networks.filter((n) => !["bridge", "host", "none"].includes(n)); - const i = user.indexOf(name); - return i < 0 ? "border-border bg-secondary text-muted-foreground" : NET_TONES[i % NET_TONES.length]!; +function ContainerBox({ c, world, flash }: { c: Container; world: DockerWorld; flash: boolean }) { + const state = stateOf(c); + const look = LOOK[state]; + const live = c.status === "running" || c.status === "restarting"; + const ports = portsText(c); + return ( +
  5. +
    + {c.name} + {look.label} +
    +
    + {c.image} + {statusText(world, c)} + {live ? {ports || "none"} : null} + {c.networks.length > 0 ? {c.networks.join(", ")} : null} + {c.mounts.length > 0 ? {c.mounts.map((m) => `${m.kind === "volume" ? m.source.slice(0, 14) : m.source} at ${m.target}`).join(", ")} : null} + {c.oomKilled ? ran out of memory (limit {c.memoryMb} MB) : null} +
    +
  6. + ); } /** - * The live picture of the virtual Docker host: container boxes coloured by state, arrows from - * "localhost" to the published ports, and chips for volumes, networks and images. It only reads - * the world; the terminal changes it. + * A plain diagram of the virtual Docker host: one flat box per container (name, image, status, + * ports), then the published ports, networks, volumes and images. It only reads the world, and + * updates after every command. `changed` names the containers whose status just changed. */ -export function DockView({ world, crashed, probe }: { world: DockerWorld; crashed: ReadonlySet; probe: Probe }) { +export function DockView({ world, changed, probe }: { world: DockerWorld; changed: ReadonlySet; probe: Probe }) { const running = world.containers.filter((c) => c.status === "running").length; - const published = world.containers.filter((c) => c.status !== "exited").flatMap((c) => c.ports.map((p) => ({ c, p }))); + const published = world.containers.flatMap((c) => c.ports.map((p) => ({ c, p }))); + const userNets = world.networks.filter((n) => !BUILT_IN_NETWORKS.includes(n)); const used = diskUsedMb(world); const pct = Math.min(100, Math.round((used / DISK_MB) * 100)); - const userNets = world.networks.filter((n) => !["bridge", "host", "none"].includes(n)); return ( -
    -
    - -
    -

    Docker host

    -

    - {running} running, {world.containers.length - running} not running -

    -
    -
    -
    - Disk - {pct}% -
    -
    -
    85 ? "bg-red-500" : pct > 60 ? "bg-amber-500" : "bg-emerald-500")} style={{ width: `${pct}%` }} /> -
    -
    -
    +
    + {running} running, {world.containers.length - running} not}>The host now + + {world.containers.length === 0 ? ( +

    + No containers on this host. Start one with docker run -d -p 8080:80 nginx +

    + ) : ( +
      + {world.containers.map((c) => ( + + ))} +
    + )} -
    - {published.length > 0 ? ( -
    + {published.length > 0 ? ( +
    + Open ports +
      {published.map(({ c, p }) => { const live = c.status === "running"; const probed = live && probe && probe.port === p.host ? probe : null; return ( -
      - - localhost:{p.host} - - - - {live ? : } {c.name}:{p.container} +
    • + localhost:{p.host} to {c.name}:{p.container} + + {live ? "Open" : "Closed"} {probed ? ( - {probed.ok ? "200 OK" : "no answer"} - ) : null} -
    • - ); - })} -
    - ) : null} - - {world.containers.length === 0 ? ( -

    No containers yet. Try docker run -d -p 8080:80 nginx

    - ) : ( -
      - {world.containers.map((c) => { - const state = stateOf(c); - return ( -
    • -
      - - {c.name} - {state === "crashed" ? "crashed" : c.status} -
      -

      {c.image}

      -

      {statusText(world, c)}

      - {c.status === "running" || c.status === "restarting" ? ( -

      {portsText(c) || (CATALOG[c.image]?.port ? `${CATALOG[c.image]!.port}/tcp (not published)` : "no ports")}

      - ) : null} - {c.oomKilled ?

      Out of memory ({c.memoryMb} MB limit)

      : null} - {c.mounts.length + c.networks.length > 0 ? ( -
      - {c.mounts.map((m) => ( - - {m.kind === "volume" ? m.source.slice(0, 12) : m.source} - - ))} - {c.networks.map((n) => ( - - {n} - - ))} -
      + {probed.ok ? "curl: 200 OK" : "curl: no answer"} ) : null}
    • ); })}
    - )} - - {(world.volumes.length > 0 || userNets.length > 0) ? ( -
    - {world.volumes.length > 0 ? ( -
    -

    Volumes

    -
    - {world.volumes.map((v) => { - const user = world.containers.filter((c) => c.mounts.some((m) => m.source === v)); - return ( - - {v.slice(0, 14)}{user.length ? ` (${user.map((c) => c.name).join(", ")})` : " (unused)"} - - ); - })} -
    -
    - ) : null} - {userNets.length > 0 ? ( -
    -

    Networks

    -
    - {userNets.map((n) => { - const members = world.containers.filter((c) => c.networks.includes(n)); - return ( - - {n}{members.length ? `: ${members.map((c) => c.name).join(", ")}` : " (empty)"} - - ); - })} -
    -
    - ) : null} -
    - ) : null} +
    + ) : null} - {world.images.length > 0 ? ( -
    -

    Images

    -
    - {world.images.map((i) => ( - " ? "border-dashed border-amber-500/60 text-amber-700 dark:text-amber-300" : "border-border bg-secondary")}> - {i.repo === "" ? "" : `${i.repo}:${i.tag}`} {fmtSize(i.sizeMb)} - - ))} + {userNets.length > 0 || world.volumes.length > 0 ? ( +
    + {userNets.length > 0 ? ( +
    + Networks +
      + {userNets.map((n) => { + const members = world.containers.filter((c) => c.networks.includes(n)); + return ( +
    • + {n} + {members.length ? members.map((c) => c.name).join(", ") : "no containers"} +
    • + ); + })} +
    -
    - ) : null} + ) : null} + {world.volumes.length > 0 ? ( +
    + Volumes +
      + {world.volumes.map((v) => { + const users = world.containers.filter((c) => c.mounts.some((m) => m.source === v)); + return ( +
    • + {v.slice(0, 14)} + {users.length ? `used by ${users.map((c) => c.name).join(", ")}` : "not used"} +
    • + ); + })} +
    +
    + ) : null} +
    + ) : null} + + {world.images.length > 0 ? ( +
    + Images +
      + {world.images.map((i) => ( +
    • + " && "text-amber-700 dark:text-amber-400")}>{i.repo === "" ? " (unused layer)" : `${i.repo}:${i.tag}`} + {fmtSize(i.sizeMb)} +
    • + ))} +
    +
    + ) : null} + +
    + Disk +
    +
    85 ? "bg-red-500" : pct > 60 ? "bg-amber-500" : "bg-emerald-500")} style={{ width: `${pct}%` }} /> +
    ); diff --git a/frontend/src/components/games/docker/docker-play.tsx b/frontend/src/components/games/docker/docker-play.tsx index 7caaee28..4f82a441 100644 --- a/frontend/src/components/games/docker/docker-play.tsx +++ b/frontend/src/components/games/docker/docker-play.tsx @@ -8,17 +8,17 @@ import { FixPlay } from "./fix-play"; /** * Docker Commands. A round is either "fix" (repair a broken virtual Docker host in a terminal, - * watching a live picture of it) or "build" (put a Dockerfile or compose file together from - * pieces, build it, then run it). + * watching a diagram of it) or "build" (put a Dockerfile or compose file together from pieces, + * build it, then run it). Both sit in the shared game frame. */ -export default function DockerPlay({ round, attempt, locked, sounds, onFinish }: GamePlayProps) { +export default function DockerPlay({ round, roundIndex, attempt, locked, sounds, onFinish }: GamePlayProps) { return (
    {round.mode === "fix" ? ( - + ) : ( - + )}
    ); diff --git a/frontend/src/components/games/docker/docker-styles.tsx b/frontend/src/components/games/docker/docker-styles.tsx index d8f5682e..e4150578 100644 --- a/frontend/src/components/games/docker/docker-styles.tsx +++ b/frontend/src/components/games/docker/docker-styles.tsx @@ -1,27 +1,15 @@ "use client"; /** - * The few keyframes the Docker game needs. They only run when the system has not asked for reduced - * motion, so the game works the same without them. + * The one animation the Docker game uses: a short colour flash on a container box when its status + * changes. It only runs when the system has not asked for reduced motion. */ export function DockerStyles() { return ( ); diff --git a/frontend/src/components/games/docker/fix-play.tsx b/frontend/src/components/games/docker/fix-play.tsx index f35a787d..d9756047 100644 --- a/frontend/src/components/games/docker/fix-play.tsx +++ b/frontend/src/components/games/docker/fix-play.tsx @@ -5,47 +5,56 @@ import { GameTerminal, type TerminalLine } from "../game-terminal"; import type { GameSounds } from "@/lib/games/audio"; import { checkGoal, cloneWorld, HELP_LINES, runLine, type DockerEvent, type DockerWorld } from "@/shared/games/docker/daemon"; import { MAX_COMMANDS, type FixRound, type FixSubmission } from "@/shared/games/docker/engine"; -import { DockView, type Probe } from "./dock-view"; -import { MissionPanel } from "./mission-panel"; +import { GameFrame, type FrameCheck } from "../game-frame"; +import { DockView, stateOf, type Probe } from "./dock-view"; +import { HeaderActions, levelOf, MissionPanel, MobileBar, type Primary } from "./mission-panel"; type Props = { round: FixRound; + roundIndex: number; attempt: number; locked: boolean; sounds: GameSounds; onFinish: (submission: FixSubmission) => void; }; +const STEPS = [ + "Read the brief and the checks", + "Type Docker commands in the terminal. Type help to see what works", + "When every check is Pass, press Finish", +]; + const COMPLETIONS = [ "docker", "ps", "images", "run", "start", "stop", "restart", "rm", "rmi", "logs", "inspect", "exec", "pull", "network", "volume", "stats", "system", "compose", "curl", "help", "hint", "clear", "reset", "--name", "--network", "--restart", "--memory", "--tail", "prune", "create", "connect", "ls", ]; function intro(round: FixRound): TerminalLine[] { - const lines: TerminalLine[] = [{ kind: "sys", text: "Virtual Docker host. Type help to see the commands, hint for a clue." }]; + const lines: TerminalLine[] = [{ kind: "sys", text: "Practice Docker host. Type help to see the commands that work here." }]; if (round.world.compose) lines.push({ kind: "sys", text: "This project has a docker-compose.yml. Read it with: cat docker-compose.yml" }); return lines; } /** Fix mode: a broken virtual Docker host, a terminal to repair it, and a live picture of the host. */ -export function FixPlay({ round, attempt, locked, sounds, onFinish }: Props) { +export function FixPlay({ round, roundIndex, attempt, locked, sounds, onFinish }: Props) { const [world, setWorld] = useState(() => cloneWorld(round.world)); const [lines, setLines] = useState(() => intro(round)); const [commands, setCommands] = useState([]); const [hintsUsed, setHintsUsed] = useState(0); - const [crashed, setCrashed] = useState>(new Set()); + const [changed, setChanged] = useState>(new Set()); const [probe, setProbe] = useState(null); const [announced, setAnnounced] = useState(false); const firstAttempt = useRef(attempt); - const goals = useMemo(() => round.goals.map((g) => ({ label: g.label, met: checkGoal(world, g) })), [round.goals, world]); - const allMet = goals.every((g) => g.met); + const checks = useMemo(() => round.goals.map((g, i) => ({ id: String(i), label: g.label, state: checkGoal(world, g) ? "pass" : "wait" })), [round.goals, world]); + const passed = checks.filter((c) => c.state === "pass").length; + const allMet = passed === checks.length; const reset = useCallback(() => { setWorld(cloneWorld(round.world)); - setLines([...intro(round), { kind: "sys", text: "The host is back to how it started. Your hints stay counted." }]); + setLines([...intro(round), { kind: "sys", text: "The host is back to how it started. Hints you used stay counted." }]); setCommands([]); - setCrashed(new Set()); + setChanged(new Set()); setProbe(null); setAnnounced(false); }, [round]); @@ -98,7 +107,8 @@ export function FixPlay({ round, attempt, locked, sounds, onFinish }: Props) { const result = runLine(next, line); setWorld(next); setCommands((c) => [...c, line]); - setCrashed(new Set(result.events.filter((e) => e.type === "crashed").map((e) => e.name))); + const before = new Map(world.containers.map((c) => [c.name, stateOf(c)])); + setChanged(new Set(next.containers.filter((c) => before.get(c.name) !== stateOf(c)).map((c) => c.name))); const curl = /^curl\s/.test(line); if (curl) { const port = Number(/:(\d{1,5})/.exec(line)?.[1] ?? 80); @@ -107,7 +117,7 @@ export function FixPlay({ round, attempt, locked, sounds, onFinish }: Props) { const out: TerminalLine[] = result.lines.map((l) => ({ kind: l.kind, text: l.text })); const nowMet = round.goals.every((g) => checkGoal(next, g)); if (nowMet && !announced) { - out.push({ kind: "sys", text: "Every goal is met. Press Finish to check your fix." }); + out.push({ kind: "sys", text: "Every check is Pass. Press Finish." }); setAnnounced(true); } setLines((l) => [...l, echo, ...out]); @@ -115,39 +125,63 @@ export function FixPlay({ round, attempt, locked, sounds, onFinish }: Props) { } const count = commands.length; + const primary: Primary = { label: "Finish", onClick: () => onFinish({ mode: "fix", commands, hints: hintsUsed }), disabled: !allMet, pulse: allMet }; + const { level, levelNumber } = levelOf(roundIndex); + const onReset = () => { sounds.whoosh(); reset(); }; + return ( -
    -
    - { sounds.whoosh(); reset(); }} - onFinish={() => onFinish({ mode: "fix", commands, hints: hintsUsed })} - finishLabel={allMet ? "Finish: all goals met" : "Finish and check"} - canFinish={count > 0} - ready={allMet} - locked={locked} - /> -
    -
    - -
    -
    - -
    -
    + <> + } + > +
    +
    { + // On a phone the keyboard covers the lower half, so bring the input to the middle. + const el = e.target as HTMLElement; + if (el.tagName === "INPUT" && window.innerWidth < 1024) window.setTimeout(() => el.scrollIntoView({ block: "center" }), 300); + }} + > +
    +

    Terminal

    + {count} {count === 1 ? "command" : "commands"} +
    + {count === 0 ? ( +

    + Start here: type docker ps and press Enter +

    + ) : null} + +

    + Type help for the command list. Press Tab to finish a word. Press the up arrow to repeat a command. +

    +
    + +
    + + {allMet ?

    Every check is Pass. Press Finish.

    : null} + +
    +
    +
    + + ); } diff --git a/frontend/src/components/games/docker/mission-panel.tsx b/frontend/src/components/games/docker/mission-panel.tsx index 1dfbd5c5..b33f3b2c 100644 --- a/frontend/src/components/games/docker/mission-panel.tsx +++ b/frontend/src/components/games/docker/mission-panel.tsx @@ -1,76 +1,136 @@ "use client"; -import { CheckCircle2, Circle, Lightbulb, RotateCcw, Send } from "lucide-react"; -import { Button } from "@/components/ui/button"; +import type { ReactNode } from "react"; +import { CheckList, FrameButton, type FrameCheck } from "../game-frame"; import { cn } from "@/lib/utils"; -export type MissionGoal = { label: string; met: boolean | null }; +export const LEVELS = ["EASY", "MEDIUM", "HARD"] as const; -type Props = { - title: string; - goals: MissionGoal[]; - /** The count line, for example "3 commands, par 3". */ - counter: { label: string; value: number; par: number; limit: number; text?: string }; +export function levelOf(roundIndex: number): { level: string; levelNumber: number } { + const i = Math.min(Math.max(roundIndex, 0), LEVELS.length - 1); + return { level: LEVELS[i]!, levelNumber: i + 1 }; +} + +export type Primary = { label: string; onClick: () => void; disabled?: boolean; pulse?: boolean }; + +type ActionProps = { hints: string[]; hintsUsed: number; onHint: () => void; onReset: () => void; - onFinish: () => void; - finishLabel: string; - canFinish: boolean; - ready: boolean; + primary: Primary; locked: boolean; }; -/** The objective checklist, the command counter against par, the hints and the reset and finish buttons. */ -export function MissionPanel({ title, goals, counter, hints, hintsUsed, onHint, onReset, onFinish, finishLabel, canFinish, ready, locked }: Props) { - const pace = counter.value <= counter.par + 1 ? "text-emerald-600 dark:text-emerald-400" : counter.value <= counter.par + 4 ? "text-amber-600 dark:text-amber-400" : "text-red-600 dark:text-red-400"; - const fill = Math.min(100, Math.round((counter.value / Math.max(1, counter.par + 4)) * 100)); - const more = hintsUsed < hints.length; +/** The buttons in the dark header bar: Hint, Reset and one green primary action. */ +export function HeaderActions({ hints, hintsUsed, onHint, onReset, primary, locked }: ActionProps) { + const left = hints.length - hintsUsed; + return ( + <> + + {left > 0 ? `Hint (${left} left)` : "No hints left"} + + + Reset + + {/* On a phone the primary action sits in the bar at the bottom, so it is always in reach. */} + + {primary.label} + + + ); +} + +/** Phone only: the same primary action, pinned to the bottom of the screen while the game is in view. */ +export function MobileBar({ primary, passed, total, locked }: { primary: Primary; passed: number; total: number; locked: boolean }) { + return ( +
    +

    + {passed}/{total} pass +

    + + {primary.label} + +
    + ); +} + +export function SectionLabel({ children, right }: { children: ReactNode; right?: ReactNode }) { + return ( +
    +

    {children}

    + {right ? {right} : null} +
    + ); +} + +type PanelProps = { + checks: FrameCheck[]; + counter: { noun: string; value: number; par: number; threeStarsAt: number }; + hints: string[]; + hintsUsed: number; +}; + +/** The checks (Wait or Pass), the count against par, and the hints already used. */ +export function MissionPanel({ checks, counter, hints, hintsUsed }: PanelProps) { + const { noun, value, par, threeStarsAt } = counter; + const tone = value <= par ? "text-emerald-700 dark:text-emerald-400" : value <= threeStarsAt ? "text-foreground" : "text-amber-700 dark:text-amber-400"; return ( -
    -
    -

    {title}

    -

    - {counter.text ?? `${counter.value} ${counter.label}, par ${counter.par}`} -

    -
    -
    -
    -
    +
    + -
      - {goals.map((g) => ( -
    • - {g.met ? : } - - {g.label} - {g.met ? " (done)" : " (not done)"} - -
    • - ))} -
    +
    +
    + {noun} used + + {value} + / par {par} + +
    +

    Three stars: no hints and {threeStarsAt} {noun} or fewer.

    +
    {hintsUsed > 0 ? ( -
      - {hints.slice(0, hintsUsed).map((h, i) => ( -
    1. Hint {i + 1}. {h}
    2. - ))} -
    +
    + Hints +
      + {hints.slice(0, hintsUsed).map((h, i) => ( +
    1. + {i + 1} + {h} +
    2. + ))} +
    +
    ) : null} +
    + ); +} + +export type StripTone = "good" | "bad" | "info"; + +const STRIP: Record = { + good: "border-l-emerald-500 bg-emerald-50 dark:bg-emerald-950/40", + bad: "border-l-red-500 bg-red-50 dark:bg-red-950/40", + info: "border-l-slate-400 bg-secondary", +}; +const STRIP_TAG: Record = { + good: "bg-emerald-100 text-emerald-800 dark:bg-emerald-950 dark:text-emerald-300", + bad: "bg-red-100 text-red-800 dark:bg-red-950 dark:text-red-300", + info: "bg-background text-muted-foreground", +}; -
    - - - -
    -

    Hints cost stars: no hints and few {counter.label} give three stars.

    -
    +/** A flat one-line message with a small tag, used for results and for order feedback. */ +export function Strip({ tone, tag, children, role }: { tone: StripTone; tag: string; children: ReactNode; role?: "status" | "alert" }) { + return ( +
    + {tag} + {children} +
    ); } diff --git a/frontend/src/components/games/game-frame.tsx b/frontend/src/components/games/game-frame.tsx new file mode 100644 index 00000000..13a925ec --- /dev/null +++ b/frontend/src/components/games/game-frame.tsx @@ -0,0 +1,135 @@ +"use client"; + +import type { ReactNode } from "react"; +import { Check, Circle, X } from "lucide-react"; +import { cn } from "@/lib/utils"; + +// The frame every daily game sits in. It copies the lab board's look (a dark header bar with a +// level tag and the action button, a bench below, and a "checks" list with PASS and WAIT badges), +// so a game feels like part of the platform and learners already know where to look. + +export type CheckState = "wait" | "pass" | "fail"; +export type FrameCheck = { id: string; label: string; state: CheckState; detail?: string; /** Set for a moment when the check has just turned Pass, for a small tick animation. */ flash?: boolean }; + +type FrameButtonProps = { + children: ReactNode; + onClick?: () => void; + disabled?: boolean; + /** "primary" is the one thing to press next. There should be one per screen. */ + tone?: "primary" | "ghost"; + pulse?: boolean; + title?: string; + className?: string; + "aria-pressed"?: boolean; +}; + +/** Buttons for the dark header bar. */ +export function FrameButton({ children, onClick, disabled, tone = "ghost", pulse = false, title, className, ...rest }: FrameButtonProps) { + return ( + + ); +} + +const STATE_LOOK: Record = { + wait: { label: "Wait", pill: "bg-secondary text-muted-foreground", icon: }, + pass: { label: "Pass", pill: "bg-emerald-100 text-emerald-800 dark:bg-emerald-950 dark:text-emerald-300", icon: }, + fail: { label: "Miss", pill: "bg-red-100 text-red-800 dark:bg-red-950 dark:text-red-300", icon: }, +}; + +/** The list of things to get done, each Wait until it is Pass. The same idea as the lab's checks. */ +export function CheckList({ title = "Checks", checks }: { title?: string; checks: FrameCheck[] }) { + const passed = checks.filter((c) => c.state === "pass").length; + return ( +
    +
    +

    {title}

    + {passed}/{checks.length} +
    +
      + {checks.map((check) => { + const look = STATE_LOOK[check.state]; + return ( +
    • + + {look.icon} + {look.label} + + + {check.label} + {check.detail ? {check.detail} : null} + +
    • + ); + })} +
    +
    + ); +} + +/** Three short steps that say what to do, shown at the top of every game. */ +export function HowToPlay({ steps }: { steps: string[] }) { + return ( +
      + {steps.map((step, i) => ( +
    1. + {i + 1} + {step} +
    2. + ))} +
    + ); +} + +type FrameProps = { + /** "EASY", "MEDIUM" or "HARD". */ + level: string; + levelNumber: number; + title: string; + /** What the player does, in 3 short steps. */ + steps: string[]; + /** Buttons for the header bar, right side. */ + actions?: ReactNode; + /** The story of the round: what is wrong or what to do, in plain words. */ + brief: string; + children: ReactNode; + /** Shown under the play area. */ + below?: ReactNode; + className?: string; +}; + +export function GameFrame({ level, levelNumber, title, steps, actions, brief, children, below, className }: FrameProps) { + return ( +
    +
    + + LVL {levelNumber} · {level} + +

    {title}

    +
    {actions}
    +
    + +
    +

    The brief

    +

    {brief}

    +
    +
    {children}
    + {below ?
    {below}
    : null} +
    + ); +} diff --git a/frontend/src/components/games/game-host.tsx b/frontend/src/components/games/game-host.tsx index dd246b27..1e99e68d 100644 --- a/frontend/src/components/games/game-host.tsx +++ b/frontend/src/components/games/game-host.tsx @@ -145,7 +145,7 @@ export function GameHost({ game }: { game: GameId }) {
    -
    +
    {[0, 1, 2].map((i) => { const done = solved(i); return ( @@ -156,23 +156,22 @@ export function GameHost({ game }: { game: GameId }) { type="button" onClick={() => pick(i)} className={cn( - "flex flex-col items-start gap-1 rounded-md border p-3 text-left transition-colors", - i === roundIndex ? "border-primary bg-secondary" : "border-border bg-card hover:bg-secondary/60", + "flex min-h-16 flex-col items-start justify-center gap-1 px-3 py-2 text-left transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-primary", + i === roundIndex ? "bg-secondary" : "bg-card hover:bg-secondary/60", )} > - {TIER_LABEL[i]} + + + {i + 1}. {TIER_LABEL[i]} + + {done ? : Open} + {view.rounds[i]!.title} - {done ? : Not solved yet} ); })}
    -
    -

    {round.title}

    -

    {round.brief}

    -
    -
    }> @@ -183,14 +182,15 @@ export function GameHost({ game }: { game: GameId }) {
    {passed ? : null}
    -

    {passed ? (setDone ? "All three solved today!" : "Solved!") : "Not yet"}

    +

    Result

    +

    {passed ? (setDone ? "All three solved today" : "Solved") : "Not yet"}

    {outcome.local.message}

    diff --git a/frontend/src/components/games/games-hub.tsx b/frontend/src/components/games/games-hub.tsx index 56809950..c62d86df 100644 --- a/frontend/src/components/games/games-hub.tsx +++ b/frontend/src/components/games/games-hub.tsx @@ -7,12 +7,13 @@ import { fetchDailyGames } from "@/lib/games/client"; import type { DailyGamesView } from "@/shared/api/games"; import type { GameId } from "@/shared/games"; import { cn } from "@/lib/utils"; +import { buttonVariants } from "@/components/ui/button"; import { StarRow } from "./celebration"; -const LOOK: Record = { - sysdesign: { icon: Network, accent: "bg-sky-500/15 text-sky-700 dark:text-sky-300", cta: "Fix today's incidents" }, - linux: { icon: Terminal, accent: "bg-emerald-500/15 text-emerald-700 dark:text-emerald-300", cta: "Start today's quests" }, - docker: { icon: Boxes, accent: "bg-orange-500/15 text-orange-700 dark:text-orange-300", cta: "Fix today's containers" }, +const LOOK: Record = { + sysdesign: { icon: Network, label: "System design", does: "A live system is breaking. Change the design on the lab board until every check passes.", cta: "Start" }, + linux: { icon: Terminal, label: "Linux", does: "Type real commands on a made-up server to find, count or fix something.", cta: "Start" }, + docker: { icon: Boxes, label: "Docker", does: "Repair a broken container with commands, or put a Dockerfile together from pieces.", cta: "Start" }, }; function timeLeft(resetsAt: string, now: number): string { @@ -45,13 +46,26 @@ export function GamesHub() { return (
    -
    +
      + {[ + ["Pick a game", "Each game has three rounds today: easy, medium and hard."], + ["Solve a round", "Do what the round asks. Press Check when you think you are done."], + ["Collect XP", "A solved round gives 3 XP. All three rounds in one game give 2 more."], + ].map(([title, body], i) => ( +
    1. + {i + 1} + {title}{body} +
    2. + ))} +
    + +

    {daily.signedIn ? ( - {daily.xpToday} XP earned today, up to {daily.xpToday + daily.xpLeft} from the games. + {daily.xpToday} XP earned today. Up to {daily.xpToday + daily.xpLeft} are possible. ) : ( - Play without an account. Sign in to save stars and earn XP. + You can play now. Sign in to save your stars and earn XP. )}

    New games in {timeLeft(daily.resetsAt, now)}

    @@ -63,29 +77,34 @@ export function GamesHub() { const Icon = look.icon; const solved = game.progress.length; return ( - - -

    {game.title}

    -

    {game.tagline}

    -
      - {[0, 1, 2].map((i) => { - const done = game.progress.find((p) => p.roundIndex === i); - return ( -
    1. - {["Easy", "Medium", "Hard"][i]} - {done ? : Open} -
    2. - ); - })} -
    - - {game.setComplete ? "All solved. Play again for practice" : solved > 0 ? "Keep going" : look.cta} - - +
    +
    + + {look.label} + {solved}/3 +
    +
    +

    {game.title}

    +

    {look.does}

    +
      + {[0, 1, 2].map((i) => { + const done = game.progress.find((p) => p.roundIndex === i); + return ( +
    1. + {["Easy", "Medium", "Hard"][i]} + {done ? : Open} +
    2. + ); + })} +
    + + {game.setComplete ? "Play again for practice" : solved > 0 ? "Continue" : look.cta} + +
    +
    ); })}
    diff --git a/frontend/src/components/games/linux/linux-play.tsx b/frontend/src/components/games/linux/linux-play.tsx index ace695d8..ee16670a 100644 --- a/frontend/src/components/games/linux/linux-play.tsx +++ b/frontend/src/components/games/linux/linux-play.tsx @@ -1,10 +1,22 @@ "use client"; +import type React from "react"; import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import { GameTerminal, type TerminalLine } from "../game-terminal"; import type { GamePlayProps } from "../types"; import { createLinuxSession, type LinuxRound, type LinuxSubmission, type Shell } from "@/shared/games/linux/engine"; -import { Controls, Counter, MissionPanel, type MissionStats } from "./mission-panel"; +import { FrameButton, GameFrame } from "../game-frame"; +import { MissionPanel, type MissionStats } from "./mission-panel"; + +const LEVELS = ["EASY", "MEDIUM", "HARD"] as const; + +// The terminal is dark in both themes, like a real one. These are the dark code tokens. +const DARK_TERMINAL = { + "--code-surface": "#070b20", + "--code-border": "#26305f", + "--code-lang-fg": "#aab3de", + "--code-fg": "#e8ebff", +} as React.CSSProperties; const MAX_LINES = 600; /** The pause between reaching the goal and handing the run to the shell, so the win can be seen. */ @@ -19,7 +31,7 @@ function prefersReducedMotion(): boolean { * The shared engine runs one command at a time; this component draws the screen, plays the sounds * and calls `onFinish` with the commands when the goal is reached. */ -export default function LinuxPlay({ round, attempt, locked, sounds, onFinish }: GamePlayProps) { +export default function LinuxPlay({ round, roundIndex, attempt, locked, sounds, onFinish }: GamePlayProps) { const [session, setSession] = useState(() => createLinuxSession(round)); const [run, setRun] = useState(0); const [lines, setLines] = useState([]); @@ -28,6 +40,7 @@ export default function LinuxPlay({ round, attempt, locked, sounds, onFinish }: const [prompt, setPrompt] = useState(() => session?.prompt() ?? "$"); const [stats, setStats] = useState(() => blankStats(round)); const [finished, setFinished] = useState(false); + const [started, setStarted] = useState(false); const timers = useRef[]>([]); const sent = useRef(false); const box = useRef(null); @@ -51,6 +64,7 @@ export default function LinuxPlay({ round, attempt, locked, sounds, onFinish }: setTyped(0); setShowBoot(true); setFinished(false); + setStarted(false); setPrompt(next?.prompt() ?? "$"); setStats(blankStats(round)); setRun((n) => n + 1); @@ -94,6 +108,7 @@ export default function LinuxPlay({ round, attempt, locked, sounds, onFinish }: const runLine = useCallback( (line: string) => { if (!session || locked || finished) return; + setStarted(true); const before = session.prompt(); const res = session.run(line); const out: TerminalLine[] = res.lines.map((l) => ({ kind: l.kind, text: l.text })); @@ -119,7 +134,7 @@ export default function LinuxPlay({ round, attempt, locked, sounds, onFinish }: if (res.solved && !sent.current) { sent.current = true; setFinished(true); - setLines((prev) => [...prev, { kind: "sys", text: "Mission complete! Checking your run ..." }]); + setLines((prev) => [...prev, { kind: "sys", text: "All checks pass. Checking your run ..." }]); const t = setTimeout(() => onFinish({ commands: session.commands, hints: session.hintCount }), FINISH_DELAY_MS); timers.current.push(t); } @@ -135,8 +150,8 @@ export default function LinuxPlay({ round, attempt, locked, sounds, onFinish }: if (!session) { return ( -
    -

    This mission could not be loaded.

    +
    +

    This mission could not be loaded. Reload the page to try again.

    ); } @@ -144,38 +159,83 @@ export default function LinuxPlay({ round, attempt, locked, sounds, onFinish }: const booting = typed < bootFull.length; const shown: TerminalLine[] = showBoot ? [{ kind: "sys", text: bootFull.slice(0, typed) + (booting ? "_" : "") }, ...lines] : lines; const disabled = locked || finished; + const hintsLeft = stats.hintsTotal - stats.hints; + const level = LEVELS[roundIndex] ?? LEVELS[0]; + + const steps = [ + "Read the brief and the checks list.", + "Type a command and press Enter. Type help to see what works.", + round.kind === "answer" + ? "Finish with: submit . The game checks it for you." + : "When every check shows Pass, you are done. There is no Check button: the game checks for you.", + ]; + + // On a phone the keyboard covers the lower half, so bring the input into the middle of what is left. + function keepInputVisible(event: React.FocusEvent) { + const target = event.target; + if (!(target instanceof HTMLInputElement)) return; + setTimeout(() => target.scrollIntoView({ block: "center", behavior: prefersReducedMotion() ? "auto" : "smooth" }), 300); + } return ( -
    -
    -
    -
    - - Objectives {stats.done.filter(Boolean).length}/{round.objectives.length} - - + + + Hint · {hintsLeft} left + + + Reset + + + } + > +
    +
    +
    + Terminal + Tab finishes a name. Up arrow repeats a command. +
    +
    + {started ? ( +

    + Stuck? Type help to see what works, or press Hint. +

    + ) : ( + <> + Start here +

    + Type ls and press Enter. +

    + + )}
    - +
    - -

    - Tab finishes a name. Arrow up repeats a command. Type help to see what works. -

    -
    -
    - +
    -
    + ); } diff --git a/frontend/src/components/games/linux/mission-panel.tsx b/frontend/src/components/games/linux/mission-panel.tsx index d76f74bb..d32b6c76 100644 --- a/frontend/src/components/games/linux/mission-panel.tsx +++ b/frontend/src/components/games/linux/mission-panel.tsx @@ -1,10 +1,9 @@ "use client"; import { useState } from "react"; -import { BookOpen, Check, ChevronDown, Lightbulb, RotateCcw } from "lucide-react"; -import { Button } from "@/components/ui/button"; +import { ChevronDown } from "lucide-react"; import { cn } from "@/lib/utils"; -import { StarRow } from "../celebration"; +import { CheckList, type FrameCheck } from "../game-frame"; import { linuxCheatSheet, type LinuxRound } from "@/shared/games/linux/engine"; export type MissionStats = { @@ -12,7 +11,7 @@ export type MissionStats = { commands: number; hints: number; hintsTotal: number; - /** Objectives that just ticked, for a short animation. */ + /** Objectives that just turned done, for a short tick animation. */ flash: number[]; }; @@ -23,147 +22,82 @@ export function starsNow(round: LinuxRound, commands: number, hints: number): 1 return 1; } -/** The command counter against par: a bar that fills and changes colour as stars are lost. */ -export function Counter({ round, stats, compact = false }: { round: LinuxRound; stats: MissionStats; compact?: boolean }) { - const stars = starsNow(round, stats.commands, stats.hints); - const width = Math.min(100, Math.round((stats.commands / Math.max(1, round.par + 4)) * 100)); - return ( -
    -
    - - {stats.commands} - / par {round.par} - - {compact ? null : } -
    -
    -
    -
    -
    - ); +/** The objectives as checks: Wait until done, Pass when done. */ +export function missionChecks(round: LinuxRound, stats: MissionStats): FrameCheck[] { + const last = round.objectives.length - 1; + return round.objectives.map((label, i) => ({ + id: String(i), + label, + state: stats.done[i] ? "pass" : "wait", + flash: stats.flash.includes(i), + detail: i === last && round.kind === "answer" && !stats.done[i] ? "Finish with: submit " : undefined, + })); } -/** The mission checklist. A tick pops in when an objective is done. */ -export function Checklist({ round, stats }: { round: LinuxRound; stats: MissionStats }) { +/** Commands used against par, in plain words, with the stars still in reach. */ +export function CommandCount({ round, stats }: { round: LinuxRound; stats: MissionStats }) { + const stars = starsNow(round, stats.commands, stats.hints); return ( -
      - {round.objectives.map((label, i) => { - const done = stats.done[i] ?? false; - return ( -
    1. - - - - - {label} - {done ? " (done)" : " (not done yet)"} - -
    2. - ); - })} -
    +
    +

    Commands

    +
    +

    + {stats.commands} {stats.commands === 1 ? "command" : "commands"}, par {round.par} +

    +

    + You can still get {stars} {stars === 1 ? "star" : "stars"}. For 3 stars, stay within par and use no hints. Each hint lowers your stars. help, man and history do not count. +

    +
    +
    ); } -/** A small "what works" list that opens on demand. */ +/** "What works here": a closed list that opens on demand. Plain words, one line per command. */ export function CheatSheet() { const [open, setOpen] = useState(false); return ( -
    +
    {open ? ( -
    +
    {linuxCheatSheet().map((group) => (
    -

    {group.group}

    -
      +

      {group.group}

      +
      {group.items.map((item) => ( -
    • - {item.usage} - {item.desc} -
    • +
      +
      {item.usage}
      +
      {item.desc}
      +
      ))} -
    +
    ))} -

    Pipes (|), redirects (> and >>), quotes, &&, $HOME and * all work. Tab finishes names. Arrow up repeats a command.

    +

    + These also work: pipes (|), redirects (> and >>), quotes, &&, $HOME and *. Press Tab to finish a name. Press the up arrow to repeat a command. +

    ) : null} -
    +
    ); } -/** Hint and reset buttons. */ -export function Controls({ stats, disabled, onHint, onReset }: { stats: MissionStats; disabled: boolean; onHint: () => void; onReset: () => void }) { - const left = stats.hintsTotal - stats.hints; +/** The right-hand column: the checks, the command count and the cheat sheet. */ +export function MissionPanel({ round, stats }: { round: LinuxRound; stats: MissionStats }) { return ( -
    - - -
    - ); -} - -export function MissionPanel({ round, stats, disabled, onHint, onReset }: { round: LinuxRound; stats: MissionStats; disabled: boolean; onHint: () => void; onReset: () => void }) { - const doneCount = stats.done.filter(Boolean).length; - return ( - +
    ); } diff --git a/frontend/src/components/games/sysdesign/diagram.tsx b/frontend/src/components/games/sysdesign/diagram.tsx deleted file mode 100644 index 8811b51c..00000000 --- a/frontend/src/components/games/sysdesign/diagram.tsx +++ /dev/null @@ -1,247 +0,0 @@ -"use client"; - -// The architecture diagram: inline SVG, drawn top to bottom so it stays readable at 375 px wide. -// Packets are animated with the Web Animations API, and only when the player allows motion. -import { useEffect, useRef } from "react"; -import type { ComponentId, Model, SimResult, StepResult, SysdesignRound } from "@/shared/games/sysdesign/engine"; -import { cn } from "@/lib/utils"; - -type Pt = [number, number]; -type Tone = "ok" | "warn" | "bad" | "dead" | "off"; - -const toneStroke: Record = { - ok: "stroke-emerald-500", - warn: "stroke-amber-500", - bad: "stroke-red-500", - dead: "stroke-red-600", - off: "stroke-border", -}; -const toneFill: Record = { - ok: "fill-emerald-500", - warn: "fill-amber-500", - bad: "fill-red-500", - dead: "fill-red-600", - off: "fill-muted-foreground", -}; - -export function utilTone(util: number): Tone { - return util >= 1 ? "bad" : util >= 0.8 ? "warn" : "ok"; -} - -function Node(props: { - id: ComponentId | string; - x: number; - y: number; - w: number; - h: number; - title: string; - sub?: string; - tone?: Tone; - util?: number; - ring?: boolean; - dim?: boolean; -}) { - const { x, y, w, h, title, sub, tone = "off", util, ring, dim } = props; - return ( - - {ring ? ( - - ) : null} - - - {title} - - {sub ? ( - - {sub} - - ) : null} - {util !== undefined ? ( - - - - - ) : null} - {ring ? ( - - - - ! - - - ) : null} - - ); -} - -function lengthOf(points: Pt[]) { - let total = 0; - for (let i = 1; i < points.length; i++) total += Math.hypot(points[i]![0] - points[i - 1]![0], points[i]![1] - points[i - 1]![1]); - return total; -} - -/** Cut a path short, so a dropped packet dies part of the way along. */ -function truncate(points: Pt[], share: number): Pt[] { - const total = lengthOf(points) * share; - const out: Pt[] = [points[0]!]; - let walked = 0; - for (let i = 1; i < points.length; i++) { - const [x0, y0] = points[i - 1]!; - const [x1, y1] = points[i]!; - const seg = Math.hypot(x1 - x0, y1 - y0); - if (walked + seg >= total) { - const k = seg === 0 ? 0 : (total - walked) / seg; - out.push([x0 + (x1 - x0) * k, y0 + (y1 - y0) * k]); - return out; - } - out.push([x1, y1]); - walked += seg; - } - return out; -} - -function Packet({ points, delay, dur, dropped }: { points: Pt[]; delay: number; dur: number; dropped: boolean }) { - const ref = useRef(null); - useEffect(() => { - const el = ref.current; - if (!el || typeof el.animate !== "function") return; - const path = dropped ? truncate(points, 0.55) : points; - const total = lengthOf(path) || 1; - let walked = 0; - const frames: Keyframe[] = path.map((p, i) => { - if (i > 0) walked += Math.hypot(p[0] - path[i - 1]![0], p[1] - path[i - 1]![1]); - const edge = i === 0 || i === path.length - 1; - return { offset: walked / total, transform: `translate(${p[0]}px, ${p[1]}px)`, opacity: edge ? 0.2 : 1 }; - }); - frames[0]!.offset = 0; - frames[frames.length - 1]!.offset = 1; - if (dropped) frames[frames.length - 1]!.opacity = 0; - const anim = el.animate(frames, { duration: dur, delay, fill: "both", easing: "linear" }); - return () => anim.cancel(); - }, [points, delay, dur, dropped]); - return ; -} - -type Edge = { id: string; pts: Pt[]; layer: number; drop: number; count: number; dashed?: boolean }; - -export type DiagramProps = { - round: SysdesignRound; - model: Model; - preview: SimResult; - /** The step being played, or null when the player is planning. */ - step: StepResult | null; - /** Show the red "problem" marker. */ - problem: boolean; - animate: boolean; - /** Playing right now. */ - running: boolean; -}; - -export function SystemDiagram({ round, model: m, preview, step, problem, animate, running }: DiagramProps) { - const zoneDown = !!step?.zoneDown; - const appUtil = step ? step.appUtil : preview.peakAppUtil; - const dbUtil = step ? step.dbUtil : preview.peakDbUtil; - const repUtil = step ? step.replicaUtil : Math.max(0, ...preview.steps.map((s) => s.replicaUtil)); - const twoZones = m.app.zones === 2; - const hasBatch = !!round.batchJob; - const batchOn = !!step?.batchRunning; - const showNat = round.focus === "nat" || m.net.natGb >= 10000; - const showLogs = round.focus === "storage" || m.logs.gb >= 10000; - const replicas = Math.min(2, Math.round(m.db.replicas)); - const ring = (id: ComponentId) => problem && round.focus === id; - - const appToneA: Tone = zoneDown ? "dead" : step ? utilTone(appUtil) : appUtil >= 1 ? "bad" : appUtil >= 0.8 ? "warn" : "ok"; - const appToneB: Tone = step ? utilTone(appUtil) : utilTone(appUtil); - const dbTone: Tone = zoneDown && !m.db.multiAz ? "dead" : utilTone(dbUtil); - - const instances = m.app.autoscale ? `${m.app.scaleMin}-${m.app.scaleMax}` : String(m.app.count); - const appSub = step && m.app.autoscale ? `${step.appInstances} running` : `${twoZones ? Math.ceil((m.app.autoscale ? m.app.scaleMin : m.app.count) / 2) : instances} x ${m.app.label}`; - const appSubB = step && m.app.autoscale ? `${step.appInstances} running` : `${Math.floor(m.app.count / 2) || 1} x ${m.app.label}`; - - const edges: Edge[] = []; - const add = (e: Edge | null) => e && edges.push(e); - const appDrop = step?.appDrop ?? 0; - const dbDrop = step?.dbDrop ?? 0; - const lbDrop = zoneDown && !twoZones ? 1 : 0; - add({ id: "u-lb", pts: [[180, 42], [180, 66]], layer: 0, drop: lbDrop, count: 2 }); - if (m.cdn.on) add({ id: "u-cdn", pts: [[150, 42], [60, 66]], layer: 0, drop: 0, count: 1 }); - add({ id: "lb-a", pts: [[160, 100], [92, 140]], layer: 1, drop: twoZones && zoneDown ? (m.app.healthChecks ? 0.1 : 1) : appDrop, count: 2 }); - if (twoZones) add({ id: "lb-b", pts: [[200, 100], [268, 140]], layer: 1, drop: appDrop > 0.5 ? appDrop : 0, count: 2 }); - if (m.cache.on) add({ id: "a-cache", pts: [[50, 196], [50, 214]], layer: 2, drop: appDrop, count: 1 }); - if (m.queue.on) add({ id: "a-queue", pts: [[133, 196], [133, 214]], layer: 2, drop: appDrop, count: 1 }); - add({ id: "a-db", pts: [[92, 196], [92, 300]], layer: 2, drop: zoneDown && !m.db.multiAz ? 1 : dbDrop, count: 2 }); - if (m.queue.on) add({ id: "q-db", pts: [[133, 248], [133, 300]], layer: 3, drop: zoneDown && !m.db.multiAz ? 1 : 0, count: 1 }); - if (twoZones) { - const standbyPath: Pt[] = [[268, 196], [268, 300]]; - add({ id: "b-db", pts: zoneDown && m.db.multiAz ? standbyPath : [[300, 196], [300, 276], [50, 276], [50, 300]], layer: 2, drop: dbDrop, count: 2 }); - } - if (m.db.multiAz) add({ id: "sync", pts: [[168, 328], [192, 328]], layer: 3, drop: 0, count: 1, dashed: true }); - if (replicas > 0) { - add({ id: "rep1", pts: [[130, 356], [130, 368], [228, 368], [228, 380]], layer: 3, drop: repUtil > 1 ? 1 - 1 / repUtil : 0, count: 1, dashed: true }); - if (replicas > 1) add({ id: "rep2", pts: [[228, 368], [306, 368], [306, 380]], layer: 3, drop: repUtil > 1 ? 1 - 1 / repUtil : 0, count: 1, dashed: true }); - } - if (hasBatch && batchOn) { - add({ id: "job-db", pts: [[214, 262], [214, 286], [150, 286], [150, 300]], layer: 2, drop: dbDrop, count: 2, dashed: true }); - if (!m.batch.separate) add({ id: "job-app", pts: twoZones ? [[268, 222], [268, 196]] : [[200, 222], [170, 190]], layer: 2, drop: appDrop, count: 2, dashed: true }); - } - - const dur = 480; - const edgeClass = (e: Edge) => { - if (!step) return "stroke-border"; - if (e.drop >= 0.5) return "stroke-red-500"; - if (e.drop >= 0.04) return "stroke-amber-500"; - return "stroke-emerald-500/70"; - }; - - return ( - - {/* Availability Zone panels */} - - - - {zoneDown ? "ZONE A DOWN" : "Availability Zone A"} - - - Availability Zone B - - {!twoZones && !m.db.multiAz && !hasBatch && !replicas ? ( - - nothing here yet - - ) : null} - - {/* Connections */} - {edges.map((e) => ( - p.join(",")).join(" ")} fill="none" strokeWidth={2} strokeDasharray={e.dashed ? "4 3" : undefined} className={cn("transition-colors", edgeClass(e))} /> - ))} - - {/* Nodes */} - - {m.cdn.on ? : null} - = 1 ? "dead" : m.app.healthChecks ? "ok" : "off"} ring={ring("lb")} /> - - {twoZones ? : null} - {m.cache.on ? : null} - {m.queue.on ? 50 ? "warn" : "ok"} ring={ring("queue")} /> : null} - {hasBatch ? ( - - ) : null} - = 2 ? "hot key on one partition" : "DynamoDB table") : "primary database"} tone={dbTone} util={zoneDown && !m.db.multiAz ? 0 : dbUtil} ring={ring("db")} /> - {m.db.multiAz ? : null} - {replicas > 0 ? : null} - {replicas > 1 ? : null} - {showNat ? : null} - {showLogs ? 0 ? "old logs in Glacier" : "all in Standard"} tone={m.logs.coldShare > 0 ? "ok" : "off"} ring={ring("storage")} /> : null} - - {/* Packets, one set per step */} - {animate && running && step - ? edges.flatMap((e) => { - const dropped = Math.round(e.count * Math.min(1, e.drop)); - return Array.from({ length: e.count }, (_, i) => ( - = 0.04 && e.drop < 0.5 && i === 0)} /> - )); - }) - : null} - - ); -} diff --git a/frontend/src/components/games/sysdesign/sysdesign-play.tsx b/frontend/src/components/games/sysdesign/sysdesign-play.tsx index f385d055..c2ed8ff3 100644 --- a/frontend/src/components/games/sysdesign/sysdesign-play.tsx +++ b/frontend/src/components/games/sysdesign/sysdesign-play.tsx @@ -1,420 +1,131 @@ "use client"; -// System Design Runner. A production incident on a small AWS system: pick a few changes, press Run, -// and watch 24 hours of traffic play out. The result comes from the shared engine, so the browser and -// the server always agree. -import { useCallback, useEffect, useMemo, useRef, useState } from "react"; -import { Check, Lightbulb, Play, RotateCcw, SkipForward, TriangleAlert, X } from "lucide-react"; -import { Button } from "@/components/ui/button"; +// System Design Runner. A production incident on the platform's own lab board: the player fixes a +// broken AWS design and presses Run tests, exactly like in a lab. When every check passes, the +// design is handed to the shell, which replays it with the shared engine (the same one the server +// uses) before it gives stars and XP. +import { useCallback, useEffect, useRef, useState } from "react"; +import { Lightbulb } from "lucide-react"; +import { HldBoard } from "@buildment/learning-ui/labs/HldBoard"; +import { writeNameMode } from "@buildment/learning-ui/labs/aws-names"; +import type { ChallengeReport } from "@buildment/learning-ui/labs/challenge"; +import type { Board } from "@buildment/learning-ui/labs/types"; import { cn } from "@/lib/utils"; -import { costDelta, evaluateGoals, simulate, STEPS, type SimResult, type SysdesignRound, type SysdesignSubmission } from "@/shared/games/sysdesign/engine"; +import { sysdesignEngine, type SysdesignRound, type SysdesignSubmission } from "@/shared/games/sysdesign/engine"; +import { FrameButton, GameFrame } from "../game-frame"; import type { GamePlayProps } from "../types"; -import { SystemDiagram, utilTone } from "./diagram"; -const STEP_MS = 520; -const STEP_MS_REDUCED = 160; - -function useReducedMotion() { - const [reduced, setReduced] = useState(false); - // The reduced motion setting can only be read in the browser, after mount. - useEffect(() => { - const query = window.matchMedia("(prefers-reduced-motion: reduce)"); - // eslint-disable-next-line react-hooks/set-state-in-effect - setReduced(query.matches); - const on = () => setReduced(query.matches); - query.addEventListener("change", on); - return () => query.removeEventListener("change", on); - }, []); - return reduced; -} - -const usd = (n: number) => `$${n.toLocaleString("en-US")}`; -const toneText = (ok: boolean) => (ok ? "text-emerald-600 dark:text-emerald-400" : "text-red-600 dark:text-red-400"); - -function Gauge({ label, text, fill, goal, ok, goalText }: { label: string; text: string; fill: number; goal: number; ok: boolean; goalText: string }) { - const pct = (n: number) => `${Math.round(Math.max(0, Math.min(1, n)) * 100)}%`; - return ( -
    -

    {label}

    -

    {text}

    -
    -
    -
    -
    -

    {goalText}

    -
    - ); -} - -function UtilBar({ label, value, note }: { label: string; value: number; note?: string }) { - const tone = utilTone(value); - const color = tone === "bad" ? "bg-red-500" : tone === "warn" ? "bg-amber-500" : "bg-emerald-500"; - const percent = Math.round(value * 100); - return ( -
    -
    - {label} - {note ?? `${percent}%`} -
    -
    -
    -
    -
    - ); -} - -/** 24 bars, one per hour: the traffic of the day, coloured by how the system did while it ran. */ -function Timeline({ round, sim, step, ran }: { round: SysdesignRound; sim: SimResult; step: number; ran: boolean }) { - const max = Math.max(1, ...round.traffic); - return ( -
    -
    - {round.traffic.map((load, t) => { - const result = sim.steps[t]!; - const seen = ran && t <= step; - const color = !seen ? "bg-muted-foreground/35" : result.status === "down" ? "bg-red-500" : result.status === "slow" ? "bg-amber-500" : "bg-emerald-500"; - const inOutage = round.outage && t >= round.outage.from && t <= round.outage.to; - const inBatch = round.batchJob && t >= round.batchJob.from && t <= round.batchJob.to; - return ( -
    -
    - {inOutage || inBatch ? : null} -
    - ); - })} -
    -
    - 00:00 - 12:00 - 23:00 -
    -

    - One bar is one hour of traffic. - {round.outage ? " Red line: a zone fails." : ""} - {round.batchJob ? " Amber line: the report job runs." : ""} -

    -
    - ); +const LEVELS = ["EASY", "MEDIUM", "HARD"] as const; +const STEPS = [ + "Read the incident and look at the red parts of the board", + "Change the design: size parts, add a cache, add a second zone", + "Press Run tests until every check passes", +]; +/** A short pause after the last check turns green, so the player sees the pass before the result opens. */ +const BEAT_MS = 900; +const NAMES_KEY = "lab-names"; + +type Status = { tone: "idle" | "fail" | "pass" | "rejected"; text: string }; + +/** The first time a player opens a lab board here, show the real AWS service names. Their own choice is never overwritten. */ +function preferAwsNames() { + try { + if (window.localStorage.getItem(NAMES_KEY) === null) writeNameMode("aws"); + } catch { + // Storage can be blocked. The board then keeps plain names, which still work. + } } -export default function SysdesignPlay({ round, attempt, locked, sounds, onFinish }: GamePlayProps) { - const reduced = useReducedMotion(); - const [picked, setPicked] = useState([]); - const [phase, setPhase] = useState<"plan" | "run" | "done">("plan"); - const [step, setStep] = useState(0); - const [runSim, setRunSim] = useState(null); - const [hints, setHints] = useState(0); - const [notice, setNotice] = useState(null); - const [shaking, setShaking] = useState(false); - const finishRef = useRef(onFinish); - // eslint-disable-next-line react-hooks/refs -- keeps the latest callback for timers that outlive a render - finishRef.current = onFinish; - const lastStatus = useRef("ok"); - const runPicked = useRef([]); - - const baseline = useMemo(() => simulate(round, []), [round]); - const preview = useMemo(() => simulate(round, picked), [round, picked]); - const deltas = useMemo(() => Object.fromEntries(round.changes.map((c) => [c.id, costDelta(round, c.id)])), [round]); - const forecastOk = useMemo(() => evaluateGoals(round.goals, preview).every((g) => g.met), [round, preview]); +export default function SysdesignPlay({ round, roundIndex, locked, sounds, onFinish }: GamePlayProps) { + const [status, setStatus] = useState({ tone: "idle", text: "Nothing has run yet. Press Run tests on the board." }); + const [hintsShown, setHintsShown] = useState(0); + const timer = useRef | null>(null); + const finished = useRef(false); + const spec = round.spec; + const hints = spec.hints; - // A new attempt (or a new round) starts from scratch. + // The shell remounts this component for every round and every retry, so the board starts fresh. useEffect(() => { - // eslint-disable-next-line react-hooks/set-state-in-effect - setPicked([]); - setPhase("plan"); - setStep(0); - setRunSim(null); - setHints(0); - setNotice(null); - lastStatus.current = "ok"; - sounds.alarm(); - // eslint-disable-next-line react-hooks/exhaustive-deps - }, [attempt, round.id]); - - // Plays the day, one hour at a time. - useEffect(() => { - if (phase !== "run" || !runSim) return; - const current = runSim.steps[step]; - if (current) { - if (current.status !== "ok" && lastStatus.current === "ok") sounds.alarm(); - lastStatus.current = current.status; - } - const wait = step >= STEPS - 1 ? 700 : reduced ? STEP_MS_REDUCED : STEP_MS; - const timer = window.setTimeout(() => { - if (step >= STEPS - 1) { - setPhase("done"); - finishRef.current({ changes: runPicked.current }); - } else { - setStep(step + 1); - } - }, wait); - return () => window.clearTimeout(timer); - // eslint-disable-next-line react-hooks/exhaustive-deps - }, [phase, step, runSim, reduced]); + preferAwsNames(); + return () => { + if (timer.current) clearTimeout(timer.current); + }; + }, []); - const toggle = useCallback( - (id: string) => { - if (locked || phase === "run") return; - if (phase === "done") { - setPhase("plan"); - setRunSim(null); - } - setNotice(null); - if (picked.includes(id)) { - sounds.key(); - setPicked(picked.filter((p) => p !== id)); + const onRunComplete = useCallback( + (report: ChallengeReport, board: Board) => { + if (locked || finished.current) return; + if (!report.allPass) { + sounds.error(); + const first = report.checks.find((c) => !c.pass); + setStatus({ tone: "fail", text: `${report.passed} of ${report.total} checks pass. The results panel shows what fails${first ? `, starting with "${first.label}"` : ""}.` }); return; } - if (picked.length >= round.maxChanges) { + // The lab lets you type any number; the game checks the board against its own rules as well. + const local = sysdesignEngine.verify(round, { board }); + if (!local.passed) { sounds.error(); - setShaking(true); - window.setTimeout(() => setShaking(false), 450); - setNotice(`You can use only ${round.maxChanges} changes. Remove one first.`); + setStatus({ tone: "rejected", text: local.message }); return; } - sounds.snap(); - setPicked([...picked, id]); + finished.current = true; + sounds.ok(); + setStatus({ tone: "pass", text: `All ${report.total} checks pass.` }); + timer.current = setTimeout(() => { + setStatus({ tone: "pass", text: `All ${report.total} checks pass. Your result is below.` }); + onFinish({ board }); + }, BEAT_MS); }, - [locked, phase, picked, round.maxChanges, sounds], + [locked, round, sounds, onFinish], ); - function run() { - if (locked || phase === "run") return; - const sim = simulate(round, picked); - runPicked.current = picked; - lastStatus.current = "ok"; - setNotice(null); - setRunSim(sim); - setStep(0); - setPhase("run"); - sounds.boot(); - sounds.whoosh(); - } - - function hint() { - if (hints >= round.hints.length) return; - sounds.ok(); - setHints(hints + 1); - } - - function clearAll() { - if (locked || phase === "run") return; + function showHint() { sounds.key(); - setPicked([]); - setNotice(null); - if (phase === "done") { - setPhase("plan"); - setRunSim(null); - } - } - - const running = phase === "run"; - const shown = running && runSim ? runSim : preview; - const current = running && runSim ? runSim.steps[step]! : null; - const showFinal = phase === "done"; - const goals = round.goals; - - let availability = shown.availability; - if (current && runSim) { - let load = 0; - let ok = 0; - for (let t = 0; t <= step; t++) { - load += runSim.steps[t]!.load; - ok += runSim.steps[t]!.load * runSim.steps[t]!.success; - } - availability = load > 0 ? Math.round((ok / load) * 10000) / 100 : 100; + setHintsShown((n) => Math.min(hints.length, n + 1)); } - const p95 = current ? current.p95Ms : shown.p95Ms; - const cost = current ? current.costToDate : shown.costUsd; - const checks = evaluateGoals(goals, shown); - const allMet = checks.every((c) => c.met); - const peakReplica = Math.max(0, ...shown.steps.map((s) => s.replicaUtil)); - const m = shown.model; - const resolved = showFinal ? allMet : forecastOk; - const lines = [...shown.costLines].sort((a, b) => b.usd - a.usd); - const costMax = Math.max(1, ...lines.map((l) => l.usd)); return ( -
    - {/* Incident banner */} -
    - {!resolved ? : null} - -
    -

    - {resolved ? (showFinal ? "Incident resolved" : "Forecast looks stable. Press Run to prove it.") : "Incident"} + 0 ? ( + = hints.length} title="Show the next hint"> + {hintsShown === 0 ? "Hint" : `Hint ${hintsShown} of ${hints.length}`} + + ) : null + } + below={ +

    +

    + {status.text}

    -

    {round.incident}

    -
    -
    - -
    - {/* Left: gauges, diagram, timeline, bars */} -
    -
    -

    {running ? `Live, hour ${String(step).padStart(2, "0")}:00` : showFinal ? "Result of the run" : "Forecast"}

    - {running ? ( - - Running - - ) : null} -
    - -
    - - = goals.minAvailability} goalText={`goal ${goals.minAvailability}%`} /> - -
    -

    Prices are illustrative round numbers for the game. They are not AWS quotes.

    - - - - - -
    -

    {current ? "How busy, now" : "How busy, at the peak"}

    - - - {m.db.replicas > 0 ? : null} - {m.cache.on ? : null} - {m.queue.on ? : null} -
    - -
    - Where the money goes -
      - {lines.map((l) => ( -
    • -
      - {l.label} - {usd(l.usd)} -
      -
      -
      -
      -
    • - ))} -
    -

    Today it is {usd(baseline.costUsd)} a month with no changes.

    -
    -
    - - {/* Right: goals, change cards, controls */} -
    -
    -

    {showFinal ? "Result: your goals" : "Your goals"}

    -
      - {checks.map((c) => ( -
    • - - {c.met ? : } - - - {c.label} {c.target} - {showFinal ? "Result" : running ? "This run" : "Forecast"}: {c.actual} - + {hintsShown > 0 ? ( +
        + {hints.slice(0, hintsShown).map((hint, i) => ( +
      1. + Hint {i + 1} + {hint}
      2. ))} -
    -
    - -
    -
    -

    Pick your changes

    -

    - - {Array.from({ length: round.maxChanges }, (_, i) => ( - - ))} - - {round.maxChanges - picked.length} of {round.maxChanges} left -

    -
    - {notice ? ( -

    - {notice} -

    - ) : null} -
      - {round.changes.map((c) => { - const index = picked.indexOf(c.id); - const on = index >= 0; - const delta = deltas[c.id] ?? 0; - return ( -
    • - -
    • - ); - })} -
    -
    - - {hints > 0 ? ( -
    -

    - Clues -

    -
      - {round.hints.slice(0, hints).map((h) => ( -
    1. {h}
    2. - ))} -
    -
    +
) : null} - -
- {running ? ( - <> - - - - ) : ( - - )} - - -
-
-
+ } + > + + ); } diff --git a/frontend/src/shared/games/sysdesign/engine.ts b/frontend/src/shared/games/sysdesign/engine.ts index b280e18a..f4cb8b37 100644 --- a/frontend/src/shared/games/sysdesign/engine.ts +++ b/frontend/src/shared/games/sysdesign/engine.ts @@ -1,74 +1,188 @@ // GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. -// System Design Runner: each round is a production incident on a small AWS system. The player -// picks a few changes, and a deterministic traffic simulation says whether the goals are met. +// System Design Runner: each round is a production incident on a small AWS system, played on the +// platform's own lab board. The player changes the design and runs the lab's tests; this engine +// replays the submitted board through the same challenge (runChallenge), so the browser and the +// server always agree. A design passes only when every check of the lab passes. +import { COMPONENT_CATALOG, canConnect, isComponentKind, sizesFor, type ComponentKind } from "../../lab/engine/catalog"; +import { runChallenge, runModel } from "../../lab/engine/challenge"; +import type { Board, BoardEdge, BoardNode, HldLabSpec } from "../../lab/engine/hld-types"; import { pickDaily } from "../daily"; import type { GameEngine, Stars, VerifyResult } from "../types"; -import { SYSDESIGN_POOL } from "./scenarios"; -import { evaluateGoals, simulate } from "./sim"; +import { SYSDESIGN_POOL } from "./incidents"; import type { SysdesignRound, SysdesignSubmission } from "./types"; export type { SysdesignRound, SysdesignSubmission } from "./types"; -export type { ChangeDef, ComponentId, CostLine, GoalCheck, Goals, Model, Pricing, SimResult, StepResult, StepStatus, Stretch } from "./types"; -export { STEPS } from "./types"; -export { applyChanges, costDelta, evaluateGoals, simulate } from "./sim"; -export { SYSDESIGN_POOL } from "./scenarios"; +export { SYSDESIGN_POOL } from "./incidents"; -/** Hard ceiling on a submission, whatever the round allows. */ -const MAX_PARSED_CHANGES = 8; +/** Hard limits on a submitted board, whatever the round allows. The biggest reference has 6 parts. */ +export const MAX_NODES = 14; +export const MAX_EDGES = 30; +/** Most parts of one kind. A board has exactly one client. */ +export const MAX_PER_KIND = 3; +/** In this game a cache or a CDN counts only up to this hit rate, so nobody wins by typing 100%. */ +export const MAX_HIT_RATE = 0.9; +/** Settings that describe the traffic, not the design. They must keep the value the incident gives them. */ +const WORKLOAD_PROPS = ["readRatio", "load", "blockRate", "ttl"] as const; -function fail(message: string): VerifyResult { - return { passed: false, stars: 0, score: 0, message }; +const isObject = (value: unknown): value is Record => typeof value === "object" && value !== null && !Array.isArray(value); +const onlyKeys = (value: Record, allowed: readonly string[]) => Object.keys(value).every((k) => allowed.includes(k)); +const ID = /^[A-Za-z0-9_-]{1,32}$/; +const HANDLES = ["t", "r", "b", "l"]; +const COORD = 100_000; + +/** Every part any incident allows. A board with another kind is not read at all. */ +const KINDS_IN_GAME: ReadonlySet = new Set(SYSDESIGN_POOL.flatMap((r) => r.spec.allowedComponents)); + +function parseProps(kind: ComponentKind, raw: unknown): Record | null { + if (raw !== undefined && !isObject(raw)) return null; + const given = raw ?? {}; + const props: Record = {}; + const defs = COMPONENT_CATALOG[kind].properties; + if (!onlyKeys(given, defs.map((d) => d.id))) return null; + for (const def of defs) { + const value = given[def.id] ?? def.default; + if (def.type === "size") { + if (typeof value !== "string" || !sizesFor(def.sizeSet!).some((t) => t.id === value)) return null; + } else if (def.type === "enum") { + if (typeof value !== "string" || !(def.options ?? []).includes(value)) return null; + } else if (def.type === "toggle") { + if (value !== 0 && value !== 1) return null; + } else { + if (typeof value !== "number" || !Number.isFinite(value)) return null; + if (value < (def.min ?? -Infinity) || value > (def.max ?? Infinity)) return null; + if (def.type === "count" && !Number.isInteger(value)) return null; + } + props[def.id] = value; + } + return props; +} + +function parseBoard(raw: unknown): Board | null { + if (!isObject(raw) || !onlyKeys(raw, ["nodes", "edges"])) return null; + const { nodes: rawNodes, edges: rawEdges } = raw; + if (!Array.isArray(rawNodes) || !Array.isArray(rawEdges)) return null; + if (rawNodes.length === 0 || rawNodes.length > MAX_NODES || rawEdges.length > MAX_EDGES) return null; + + const nodes: BoardNode[] = []; + const byId = new Map(); + for (const entry of rawNodes) { + if (!isObject(entry) || !onlyKeys(entry, ["id", "kind", "x", "y", "props"])) return null; + const { id, kind, x = 0, y = 0 } = entry; + if (typeof id !== "string" || !ID.test(id) || byId.has(id)) return null; + if (typeof kind !== "string" || !isComponentKind(kind) || !KINDS_IN_GAME.has(kind)) return null; + if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y) || Math.abs(x) > COORD || Math.abs(y) > COORD) return null; + const props = parseProps(kind, entry.props); + if (props === null) return null; + const node: BoardNode = { id, kind, x, y, props }; + nodes.push(node); + byId.set(id, node); + } + + const edges: BoardEdge[] = []; + const seen = new Set(); + for (const entry of rawEdges) { + if (!isObject(entry) || !onlyKeys(entry, ["from", "to", "via"])) return null; + const { from, to, via } = entry; + if (typeof from !== "string" || typeof to !== "string" || from === to) return null; + const a = byId.get(from); + const b = byId.get(to); + if (!a || !b || !canConnect(a.kind, b.kind)) return null; + if (via !== undefined && !(Array.isArray(via) && via.length === 2 && via.every((h) => typeof h === "string" && HANDLES.includes(h)))) return null; + const key = `${from}>${to}`; + if (seen.has(key)) return null; + seen.add(key); + edges.push({ from, to }); + } + return { nodes, edges }; +} + +const fail = (message: string): VerifyResult => ({ passed: false, stars: 0, score: 0, message }); +const usd = (n: number) => `$${n.toFixed(2)}`; + +/** The value a workload setting must keep: the one the incident's starting board gives that kind, else the default. */ +function workloadValue(spec: HldLabSpec, kind: ComponentKind, key: string): number | string | undefined { + const start = spec.startingBoard?.nodes.find((n) => n.kind === kind); + return start?.props?.[key] ?? COMPONENT_CATALOG[kind].properties.find((p) => p.id === key)?.default; } +/** + * The rules about what a board may contain for this incident, in one plain sentence when broken. + * The lab itself lets you type any number; the game does not accept a design that cheats. + */ +export function boardProblem(spec: HldLabSpec, board: Board): string | null { + const counts = new Map(); + for (const node of board.nodes) { + if (!spec.allowedComponents.includes(node.kind)) return `${COMPONENT_CATALOG[node.kind].label} is not one of the parts you can use in this round.`; + counts.set(node.kind, (counts.get(node.kind) ?? 0) + 1); + } + if ((counts.get("client") ?? 0) !== 1) return "The design needs exactly one client."; + for (const [kind, n] of counts) { + if (n > MAX_PER_KIND && kind !== "client") return `A design can have at most ${MAX_PER_KIND} ${COMPONENT_CATALOG[kind].label} parts.`; + } + for (const node of board.nodes) { + const role = COMPONENT_CATALOG[node.kind].role; + const hit = node.props?.hitRate; + if ((role === "cache" || role === "cdn") && typeof hit === "number" && hit > MAX_HIT_RATE) { + return `A hit rate above ${Math.round(MAX_HIT_RATE * 100)}% is not realistic. Set the ${COMPONENT_CATALOG[node.kind].label} hit rate to ${Math.round(MAX_HIT_RATE * 100)}% or less.`; + } + for (const key of WORKLOAD_PROPS) { + const value = node.props?.[key]; + if (value !== undefined && value !== workloadValue(spec, node.kind, key)) { + const label = COMPONENT_CATALOG[node.kind].properties.find((p) => p.id === key)?.label ?? key; + return `"${label}" describes the traffic, not the design. Keep it at ${String(workloadValue(spec, node.kind, key))}.`; + } + } + } + return null; +} + +const partsOf = (board: Board) => board.nodes.filter((n) => n.kind !== "client").length; + export const sysdesignEngine: GameEngine = { id: "sysdesign", title: "System Design Runner", - tagline: "A real incident on a small AWS system. Pick the fixes, run the traffic, and meet the goals.", + tagline: "A real AWS system is breaking. Fix the design on the lab board until every check passes.", roundsFor: (dayKey) => pickDaily(SYSDESIGN_POOL, dayKey, "sysdesign"), parseSubmission(input) { - if (typeof input !== "object" || input === null || Array.isArray(input)) return null; - const keys = Object.keys(input); - if (keys.length !== 1 || keys[0] !== "changes") return null; - const changes = (input as { changes?: unknown }).changes; - if (!Array.isArray(changes) || changes.length > MAX_PARSED_CHANGES) return null; - const seen = new Set(); - for (const id of changes) { - if (typeof id !== "string" || id.length === 0 || id.length > 64 || seen.has(id)) return null; - seen.add(id); - } - return { changes: [...changes] as string[] }; + if (!isObject(input) || !onlyKeys(input, ["board"])) return null; + const board = parseBoard(input.board); + return board === null ? null : { board }; }, verify(round, submission) { try { - const ids = Array.isArray(submission?.changes) ? submission.changes.filter((id): id is string => typeof id === "string") : []; - if (new Set(ids).size !== ids.length) return fail("Each change can be used only once."); - if (ids.length > round.maxChanges) return fail(`You can apply at most ${round.maxChanges} changes in this round.`); - const offered = new Set(round.changes.map((c) => c.id)); - if (ids.some((id) => !offered.has(id))) return fail("One of those changes is not part of this round."); - - const sim = simulate(round, ids); - const checks = evaluateGoals(round.goals, sim); - const missed = checks.find((c) => !c.met); - if (missed) { - return { passed: false, stars: 0, score: sim.costUsd, message: `Goal missed: ${missed.label.toLowerCase()} is ${missed.actual}, the goal is ${missed.target}.` }; + const spec = round.spec; + const challenge = spec.challenge; + const solution = spec.solution; + if (!challenge || !solution) return fail("This round is not set up correctly."); + const parsed = sysdesignEngine.parseSubmission(submission); + if (parsed === null) return fail("That design could not be read. Build it on the board and press Run tests."); + const board = parsed.board; + const problem = boardProblem(spec, board); + if (problem) return fail(problem); + + const report = runChallenge(spec, board, challenge.peakLoad); + const first = report.checks.find((c) => !c.pass); + if (first) { + return fail(`Not yet: "${first.label}" fails. Found: ${first.measured}. Needed: ${first.target}.`); } - const stretch = round.stretch; - const tighter = (stretch.maxCostUsd === undefined || sim.costUsd <= stretch.maxCostUsd) && (stretch.maxP95Ms === undefined || sim.p95Ms <= stretch.maxP95Ms); - const lean = ids.length <= round.solution.length && !(round.trap !== undefined && ids.includes(round.trap)); - const stars: Stars = tighter ? (lean ? 3 : 2) : 1; - const target = [stretch.maxCostUsd !== undefined ? `$${stretch.maxCostUsd} a month` : "", stretch.maxP95Ms !== undefined ? `${stretch.maxP95Ms} ms p95` : ""].filter(Boolean).join(" and "); + const spend = runModel(spec, board, challenge.peakLoad).costPerHour; + const reference = runModel(spec, solution.board, challenge.peakLoad).costPerHour; + const refParts = partsOf(solution.board); + const lean = spend <= reference * 1.1 && partsOf(board) <= refParts + 1; + const near = spend <= reference * 1.4; + const stars: Stars = lean ? 3 : near ? 2 : 1; const message = stars === 3 - ? `All goals met with ${ids.length} change${ids.length === 1 ? "" : "s"}: p95 ${sim.p95Ms} ms, ${sim.availability}% available, $${sim.costUsd} a month.` + ? `All ${report.total} checks pass at ${usd(spend)} an hour with ${partsOf(board)} parts, within 10% of the reference cost.` : stars === 2 - ? "All goals met and under the tighter target. For 3 stars, use fewer changes and skip the tempting trap." - : `All goals met. For more stars, get under the tighter target of ${target}.`; - return { passed: true, stars, score: sim.costUsd, message }; + ? `All ${report.total} checks pass at ${usd(spend)} an hour. For 3 stars, get the cost to ${usd(reference * 1.1)} or less with at most ${refParts + 1} parts.` + : `All ${report.total} checks pass at ${usd(spend)} an hour. For 2 stars, get the cost to ${usd(reference * 1.4)} or less.`; + return { passed: true, stars, score: Math.round(spend * 100) / 100, message }; } catch { - return fail("That set of changes could not be checked. Try again."); + return fail("That design could not be checked. Try again."); } }, }; diff --git a/frontend/src/shared/games/sysdesign/incidents.ts b/frontend/src/shared/games/sysdesign/incidents.ts new file mode 100644 index 00000000..e03a4084 --- /dev/null +++ b/frontend/src/shared/games/sysdesign/incidents.ts @@ -0,0 +1,563 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The six production incidents of the System Design Runner, two for each difficulty. Each one is +// a real lab spec (HldLabSpec, the same shape the platform's labs use) on AWS parts: a broken +// starting board, the checks it must pass, hints and a reference fix with a reason for every part. +// The numbers were set with the real model (runChallenge): every starting board fails and every +// reference solution passes. Prices are the catalog's illustrative us-east-1 on-demand prices. +import type { Board, ChallengeScenario, CheckDef, CheckMetric, HldLabSpec, SolutionDef } from "../../lab/engine/hld-types"; +import type { SysdesignRound } from "./types"; + +const LIMITS = + "A simplified model, not a real AWS bill. Prices are illustrative us-east-1 on-demand prices from late 2026. Times are in model milliseconds. In this game a cache or CDN hit rate counts only up to 90%."; + +// ---- small builders, so each incident reads as data ------------------------------------- + +type Op = "<=" | ">="; +const metric = (id: string, label: string, scenario: string, m: CheckMetric, op: Op, value: number): CheckDef => ({ + type: "metric", id, kind: "non-functional", label, scenario, metric: m, op, value, +}); +const capacity = (peak: number) => metric("capacity", "Serves the whole peak", "steady", "capacity", ">=", peak); +const p99 = (ms: number) => metric("p99", "Slowest 1 in 100 requests is fast enough (p99)", "steady", "p99", "<=", ms); +const availability = (v: number) => metric("availability", "Stays up (availability)", "steady", "availability", ">=", v); +const cost = (usd: number) => metric("cost", "Cost per hour is within the budget", "steady", "cost", "<=", usd); +const served = (id: string, label: string, scenario: string) => metric(id, label, scenario, "served", ">=", 0.999); +const slow = (id: string, label: string, scenario: string, ms: number) => metric(id, label, scenario, "p99", "<=", ms); +const reads: CheckDef = { + type: "path", id: "read", kind: "functional", label: "A request reaches the database", + chain: ["client", "balancer", "compute", "database"], target: "client > load balancer > app servers > database", +}; +const cached: CheckDef = { + type: "path", id: "cached", kind: "functional", label: "Repeated reads can come from a cache", + chain: ["client", "compute", "cache"], target: "the app servers are linked to a cache", +}; + +const LOSE_APP: ChallengeScenario = { + id: "lose-app", title: "A server dies", story: "One EC2 server stops. The load balancer sends its share to the others.", + faults: [{ type: "lose-instance", role: "compute" }], +}; +const LOSE_CACHE: ChallengeScenario = { + id: "lose-cache", title: "The cache is flushed", story: "The cache is empty. Every read goes to the database.", + faults: [{ type: "down", role: "cache" }], +}; +const ZONE_DOWN: ChallengeScenario = { + id: "zone-down", title: "A zone goes down", story: "An app server and the cache in that zone are gone at the same time.", + faults: [{ type: "lose-instance", role: "compute" }, { type: "down", role: "cache" }], +}; +const LOSE_WORKERS: ChallengeScenario = { + id: "lose-workers", title: "The workers stop for 2 minutes", story: "Orders keep arriving. They wait in the queue until the workers return.", + faults: [{ type: "down", role: "worker" }], +}; + +const board = (nodes: Board["nodes"], edges: Board["edges"]): Board => ({ nodes, edges }); + +// ---- 1. easy: the bill tripled ------------------------------------------------------------ + +const BILL_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "m5.xlarge", count: 12, autoscale: 0, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.2xlarge", replicas: 3, multiAz: 1, readRatio: 0.8 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const BILL_FIX: SolutionDef = { + summary: "Size each part for the real peak, plus one spare server. Keep Multi-AZ, because a standby copy is what keeps the site up.", + board: board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "m5.large", count: 3, autoscale: 0, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 1, multiAz: 1, readRatio: 0.8 } }, + ], + BILL_START.edges, + ), + parts: { + alb: { + why: "The ALB spreads requests over the servers. It is managed and billed per request, so its $1.32 an hour follows the traffic and is not the part to cut.", + checks: ["read", "capacity"], + without: "Nothing else in this design spreads the traffic over the servers, so there is no way to reach more than one of them.", + }, + web: { + why: "Three m5.large servers in two zones carry 1,800 requests a second at 38% busy each. If one dies, the other two are 56% busy. That is enough and costs $0.29 an hour, not $2.30.", + checks: ["capacity", "p99", "app-dies", "app-dies-p99", "availability", "cost"], + without: "With two servers, losing one leaves 113% load on the other, so only 89% of requests are served and the slowest 1 in 100 takes over 1,300 ms. With one server, nothing is left when it dies.", + }, + db: { + why: "A db.r5.large with one read replica is 60% busy at the real peak. Multi-AZ keeps a standby in a second zone, so the database is not the weak link. It costs $0.72 an hour, not $4.80.", + checks: ["capacity", "p99", "availability", "cost"], + without: "With no read replica the database is 120% busy, it serves only 1,500 requests a second and the slowest 1 in 100 takes 577 ms. Without Multi-AZ, availability drops to 99.84% and fails the 99.9% target.", + }, + }, +}; + +const billTripled: HldLabSpec = { + slug: "sd-bill-tripled", + family: "hld", + title: "The bill tripled", + purpose: "Right-size an AWS web tier that is far bigger than its traffic, and keep it safe while you cut the cost.", + limits: LIMITS, + hints: [ + "Run the tests first. Only one check fails: the cost. The reason names the part that costs the most.", + "The ALB is billed per request, so you cannot make it cheaper. EC2 and RDS are the parts you can change.", + "12 big servers for 1,800 requests a second is far too many. But keep at least 3: one can die and the rest must still carry the load.", + "Keep Multi-AZ on the database. Without it, availability falls below 99.9%. A smaller size and fewer read replicas are the real savings.", + ], + allowedComponents: ["client", "aws-alb", "aws-ec2-asg", "aws-rds", "aws-elasticache"], + startingBoard: BILL_START, + scenario: + "The AWS bill is $8.42 an hour, about three times what it should be. Real traffic peaks at only 1,800 requests a second, but the team rented a huge fleet during the launch and never gave it back. Cut the cost to $3.00 an hour or less. The site must stay fast (p99 under 100 ms), stay 99.9% up, and keep serving when one server dies.", + levels: [{ id: "l1", load: 1_800, targets: { rps: 1_800, p99Ms: 100, availability: 0.999, budgetPerHour: 3 } }], + solution: BILL_FIX, + challenge: { + peakLoad: 1_800, + scenarios: [LOSE_APP], + checks: [ + reads, + capacity(1_800), + p99(100), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + slow("app-dies-p99", "Slowest 1 in 100 while a server is down (p99)", "lose-app", 130), + availability(0.999), + cost(3), + ], + }, +}; + +// ---- 2. easy: launch day is slow --------------------------------------------------------- + +const LAUNCH_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "m5.large", count: 2, autoscale: 0, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 0, multiAz: 1, readRatio: 0.85 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const LAUNCH_FIX: SolutionDef = { + summary: "A cache answers the repeated reads from memory, so the database only sees the misses. Then add one more, faster server so the site survives losing one.", + board: board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.large", count: 3, autoscale: 0, azs: 2 } }, + { id: "cache", kind: "aws-elasticache", x: 1, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 1, hitRate: 0.85, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 0, multiAz: 1, readRatio: 0.85 } }, + ], + [...LAUNCH_START.edges, { from: "web", to: "cache" }], + ), + parts: { + alb: { + why: "The ALB spreads the 3,000 requests a second over the servers. It is managed, so it never becomes the limit, and it costs $2.18 an hour.", + checks: ["read", "capacity"], + without: "Without the ALB nothing spreads the traffic over the servers.", + }, + web: { + why: "Three c5.large servers (compute sized, 2,400 requests a second each) are 42% busy at the peak and 63% busy with one gone. Two m5.large servers were 94% busy.", + checks: ["capacity", "p99", "app-dies", "app-dies-p99"], + without: "With the first two m5.large servers the web tier is 94% busy and the slowest 1 in 100 takes 344 ms. When one dies the other is 188% busy and the slowest 1 in 100 takes over 1,300 ms.", + }, + cache: { + why: "At an 85% hit rate the cache answers 2,550 of the 3,000 reads a second from memory. Only about 450 reach the database, which falls from 213% busy to 32% busy. It costs $0.41 an hour.", + checks: ["capacity", "p99", "app-dies", "app-dies-p99", "cost"], + without: "With no cache the database is 213% busy, so it can serve only 1,412 requests a second and the slowest 1 in 100 takes 580 ms. CloudFront also removes the repeats, but at this load it costs $8.10 an hour and breaks the $5.00 budget.", + }, + db: { + why: "The database keeps the data. With the cache in front it is only 32% busy. Multi-AZ keeps a standby in a second zone, so it is not the weak link for availability.", + checks: ["read", "capacity", "p99", "availability"], + without: "Without Multi-AZ, availability falls to 99.84% and fails the 99.9% target.", + }, + }, +}; + +const launchDaySlow: HldLabSpec = { + slug: "sd-launch-slow", + family: "hld", + title: "Launch day is slow", + purpose: "Find why a new site is slow under launch traffic, and fix it without a huge bill.", + limits: LIMITS, + hints: [ + "Run the tests. Read the reasons: the database (RDS) is over 200% busy, and the two servers are almost full. Many requests ask for the same pages again and again.", + "A cache answers repeated reads from memory, so only the misses reach the database. ElastiCache is the AWS cache. Link the app servers to it.", + "CloudFront also stops repeated requests, but it is billed per request. Look at what it adds to the cost before you choose it.", + "When the database is safe, the two web servers are still too busy. Use a faster size or add a server, so the site survives when one dies.", + ], + allowedComponents: ["client", "aws-cloudfront", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds"], + startingBoard: LAUNCH_START, + scenario: + "Launch day: 3,000 requests a second hit a small site. Pages take almost a second and some time out. The database is over 200% busy and the two web servers are almost full. Make the site fast (p99 under 100 ms), keep it serving when one server dies, and keep the bill at $5.00 an hour or less.", + levels: [{ id: "l1", load: 3_000, targets: { rps: 3_000, p99Ms: 100, availability: 0.999, budgetPerHour: 5 } }], + solution: LAUNCH_FIX, + challenge: { + peakLoad: 3_000, + scenarios: [LOSE_APP], + checks: [ + reads, + capacity(3_000), + p99(100), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + slow("app-dies-p99", "Slowest 1 in 100 while a server is down (p99)", "lose-app", 150), + availability(0.999), + cost(5), + ], + }, +}; + +// ---- 3. medium: the flash sale melts the database ------------------------------------------ + +const SALE_WEB = { size: "c5.large", count: 4, autoscale: 0, azs: 2 }; +const SALE_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: SALE_WEB }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.xlarge", replicas: 0, multiAz: 1, readRatio: 0.9 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const SALE_FIX: SolutionDef = { + summary: "Put a cache in front of the database so most reads never reach it. Then add read replicas, so the database can still cope on the minute the cache is empty.", + board: board( + [ + { id: "client", kind: "client", x: 1, y: 0 }, + { id: "alb", kind: "aws-alb", x: 1, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 1, y: 2, props: SALE_WEB }, + { id: "cache", kind: "aws-elasticache", x: 0, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 1, hitRate: 0.85, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 2, y: 3, props: { size: "db.r5.xlarge", replicas: 2, multiAz: 1, readRatio: 0.9 } }, + ], + [...SALE_START.edges, { from: "web", to: "cache" }], + ), + parts: { + alb: { + why: "The ALB spreads the 6,000 requests a second over the servers. It is billed per request, so it is the biggest line in the bill at $4.34 an hour.", + checks: ["read", "capacity"], + without: "Without the ALB nothing spreads the traffic over the servers.", + }, + web: { + why: "Four c5.large servers handle 6,000 requests a second at 63% busy. If one dies, the other three can still carry it. They were never the problem.", + checks: ["capacity", "p99", "app-dies"], + without: "With three servers the slowest 1 in 100 takes 141 ms, over the 90 ms limit, and losing one leaves only 80% of requests served. The fleet was sized right.", + }, + cache: { + why: "At an 85% hit rate the cache answers 5,100 of 6,000 reads a second from memory. The database sees about 900 a second instead of 6,000, and falls from 225% busy to 11% busy.", + checks: ["cached", "capacity", "p99", "app-dies"], + without: "With no cache the cache path check fails, and even with two replicas the database is 75% busy and the slowest 1 in 100 takes 97 ms, over 90 ms. With no cache and no replica (the starting board) the database is 225% busy and serves only 2,667 requests a second.", + }, + db: { + why: "Two read replicas share the reads. When the cache is flushed, all 6,000 requests a second hit the database, and three copies keep it 75% busy. Multi-AZ keeps it up when a zone fails.", + checks: ["cache-dies", "cache-dies-p99", "capacity", "availability", "cost"], + without: "With a cache and no replica, a flushed cache sends 225% load to the database and only 44% of requests are served. With one replica it is 113% busy and 89% are served. A bigger db.r5.2xlarge with two replicas works but costs $8.93 an hour, almost the whole $9.00 budget.", + }, + }, +}; + +const flashSale: HldLabSpec = { + slug: "sd-flash-sale", + family: "hld", + title: "The flash sale melts the database", + purpose: "Protect a database from a read flood with a cache and read replicas, and prove it still holds when the cache is empty.", + limits: LIMITS, + hints: [ + "The database is 225% busy. Nine in ten requests only read. Reads are what a cache and read replicas are for.", + "Add ElastiCache and link the app servers to it. At an 85% hit rate, only 15% of the reads reach the database.", + "A cache can be flushed or restart empty. Run the tests and read the cache check: then every read hits the database again. Read replicas (copies that only read) share that load.", + "A bigger RDS size also helps, but every replica costs as much as the primary. Compare the price of two replicas on a smaller size with one big size before you decide.", + ], + allowedComponents: ["client", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds"], + startingBoard: SALE_START, + scenario: + "A flash sale has started and 6,000 requests a second arrive. Most of them read the same product pages, and every read goes to one database. It is 225% busy, pages take 600 ms and many fail. Take the load off it with a cache. Make sure the database can still cope if the cache is flushed. Stay at $9.00 an hour or less.", + levels: [{ id: "l1", load: 6_000, targets: { rps: 6_000, p99Ms: 90, availability: 0.999, budgetPerHour: 9 } }], + solution: SALE_FIX, + challenge: { + peakLoad: 6_000, + scenarios: [LOSE_APP, LOSE_CACHE], + checks: [ + reads, + cached, + capacity(6_000), + p99(90), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + served("cache-dies", "Everyone is still served when the cache is flushed", "lose-cache"), + slow("cache-dies-p99", "Slowest 1 in 100 while the cache is empty (p99)", "lose-cache", 150), + availability(0.999), + cost(9), + ], + }, +}; + +// ---- 4. medium: we lost a zone ----------------------------------------------------------------- + +const ZONE_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.large", count: 3, autoscale: 0, azs: 1 } }, + { id: "cache", kind: "aws-elasticache", x: 1, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 0, hitRate: 0.85, azs: 1 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 1, multiAz: 0, readRatio: 0.85 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }, { from: "web", to: "cache" }], +); + +const ZONE_FIX: SolutionDef = { + summary: "Give every layer a second zone: servers in two zones with a spare, a Multi-AZ database and a cache with a replica. Then one zone cannot take the site down.", + board: board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.large", count: 4, autoscale: 0, azs: 2 } }, + { id: "cache", kind: "aws-elasticache", x: 1, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 1, hitRate: 0.85, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 1, multiAz: 1, readRatio: 0.85 } }, + ], + ZONE_START.edges, + ), + parts: { + alb: { + why: "The ALB already runs in two zones, so it is not the weak link. It costs $3.62 an hour at 5,000 requests a second.", + checks: ["read", "capacity", "availability"], + without: "Without the ALB nothing spreads the traffic over the servers in the two zones.", + }, + web: { + why: "Four servers in two zones: if a whole zone is lost, two are left in the other. If a single server dies, three still carry the 5,000 requests a second, at 69% busy each.", + checks: ["capacity", "p99", "app-dies", "app-dies-p99", "availability"], + without: "With three servers, one dying leaves 104% load, so only 96% of requests are served and the slowest 1 in 100 takes over 1,300 ms. With all servers in one zone, availability is 99.94%, just under the 99.95% target.", + }, + cache: { + why: "The cache sits in two zones with a replica, so one zone cannot take it away. A single cache node in one zone is only 99.9% available, and it sits in series with everything else.", + checks: ["availability"], + without: "A single cache node in one zone brings availability down to 99.84%, which fails the 99.95% target.", + }, + db: { + why: "Multi-AZ keeps a synchronous standby in a second zone. If the main copy's zone fails, RDS fails over to the standby. This lifts the database from 99.85% to about 99.999% available. It costs $0.72 an hour.", + checks: ["availability", "cost"], + without: "Without Multi-AZ the database is the weak link. Availability for the whole site is 99.84%, under the 99.95% target.", + }, + }, +}; + +const lostZone: HldLabSpec = { + slug: "sd-lost-zone", + family: "hld", + title: "We lost a zone", + purpose: "Spread a system over two Availability Zones so one data centre cannot take it down, without paying for much more.", + limits: LIMITS, + hints: [ + "Run the tests. Read the availability reason: it names the weakest part. Fix it, run again, and the next weak part shows up.", + "RDS Multi-AZ keeps a standby copy in a second zone. If the zone of the main copy fails, the standby takes over.", + "EC2 Auto Scaling can spread servers over zones: set zones to 2. ElastiCache can too, and a replica keeps the cache alive.", + "Three servers cannot lose one and still carry 5,000 requests a second. Count what is left after one dies, then add what is needed.", + ], + allowedComponents: ["client", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds"], + startingBoard: ZONE_START, + scenario: + "Last night one AWS Availability Zone (a separate data centre) lost power. The servers, the cache and the main database were all in that zone, so the site was down for 40 minutes. Traffic peaks at 5,000 requests a second. The goal is 99.95% uptime, which allows about 22 minutes of downtime a month. The site must also keep serving when one server dies. Stay at $6.00 an hour or less.", + levels: [{ id: "l1", load: 5_000, targets: { rps: 5_000, p99Ms: 90, availability: 0.9995, budgetPerHour: 6 } }], + solution: ZONE_FIX, + challenge: { + peakLoad: 5_000, + scenarios: [LOSE_APP], + checks: [ + reads, + capacity(5_000), + p99(90), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + slow("app-dies-p99", "Slowest 1 in 100 while a server is down (p99)", "lose-app", 130), + availability(0.9995), + cost(6), + ], + }, +}; + +// ---- 5. hard: peak day, one zone down, tight budget ---------------------------------------------- + +const PEAK_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.2xlarge", count: 6, autoscale: 0, azs: 1 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.xlarge", replicas: 0, multiAz: 0, readRatio: 0.85 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const PEAK_FIX: SolutionDef = { + summary: "Fix the database side, not the fleet: add a cache, give the database Multi-AZ and read replicas, and cut the web fleet to what the traffic needs, in two zones. That frees the money for the database.", + board: board( + [ + { id: "client", kind: "client", x: 1, y: 0 }, + { id: "alb", kind: "aws-alb", x: 1, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 1, y: 2, props: { size: "c5.xlarge", count: 3, autoscale: 0, azs: 2 } }, + { id: "cache", kind: "aws-elasticache", x: 0, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 1, hitRate: 0.85, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 2, y: 3, props: { size: "db.r5.xlarge", replicas: 3, multiAz: 1, readRatio: 0.85 } }, + ], + [...PEAK_START.edges, { from: "web", to: "cache" }], + ), + parts: { + alb: { + why: "The ALB spreads the 8,000 requests a second over the servers in both zones. It is billed per request, so it is $5.78 an hour of the budget, and nothing you can shrink.", + checks: ["read", "capacity", "availability"], + without: "Without the ALB nothing spreads the traffic over the servers.", + }, + web: { + why: "Three c5.xlarge servers in two zones carry 8,000 requests a second at 56% busy and cost $0.51 an hour. When a zone goes down and one server with it, two are left at 83% busy. The old fleet of six c5.2xlarge cost $2.04 an hour and was only 14% busy.", + checks: ["capacity", "p99", "zone-served", "zone-p99", "availability", "cost"], + without: "The old fleet of six c5.2xlarge servers in one zone adds $1.53 an hour, which pushes the bill to $10.63 with the other fixes and breaks the $10.00 budget. In one zone it also fails availability.", + }, + cache: { + why: "At an 85% hit rate the cache answers 6,800 of 8,000 reads a second, so the database sees only 1,200 a second. It costs $0.41 an hour. It also has a replica in a second zone.", + checks: ["cached", "capacity", "p99", "availability"], + without: "With no cache the cache path check fails. With no cache and no replicas (the starting board) the database is 283% busy: it serves only 2,824 requests a second and the slowest 1 in 100 takes 569 ms.", + }, + db: { + why: "The database must carry all the reads for the minute the cache is gone. Three read replicas keep db.r5.xlarge at 71% busy with no cache and one server less. Multi-AZ keeps a standby in the second zone. It costs $2.40 an hour.", + checks: ["zone-served", "zone-p99", "availability", "cost"], + without: "With two replicas instead of three, the database is 94% busy when a zone goes down and the slowest 1 in 100 reaches 276 ms, over the 200 ms limit. Without Multi-AZ, availability falls to 99.84%.", + }, + }, +}; + +const peakDay: HldLabSpec = { + slug: "sd-peak-day", + family: "hld", + title: "Peak day, one zone down, tight budget", + purpose: "Make several changes that work together: cache, replicas, Multi-AZ and a right-sized fleet, under a budget that rules out buying big everywhere.", + limits: LIMITS, + hints: [ + "The fleet is far too big for the traffic. The database is the weak part: it is 283% busy. Fix the database side first.", + "Add a cache so most reads never reach the database. Then give the database read replicas and Multi-AZ.", + "The zone check removes the cache and one server at the same moment. The database must then carry all the reads. Count replicas for that case, not only for the normal one.", + "Right-size the fleet and spread it over two zones. The budget leaves room for the database copies only if you cut the fleet first.", + "CloudFront is billed per request. At 8,000 requests a second it costs more than your whole budget.", + ], + allowedComponents: ["client", "aws-cloudfront", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds"], + startingBoard: PEAK_START, + scenario: + "It is the busiest day of the year: 8,000 requests a second. Last year a zone failed at the peak and the site went down. The app fleet is huge, but the database is one RDS with no copy and no cache, and it is 283% busy. The site must survive a zone loss (an app server and the cache gone together), stay 99.95% up, and cost $10.00 an hour or less. Bigger machines everywhere will not fit the budget.", + levels: [{ id: "l1", load: 8_000, targets: { rps: 8_000, p99Ms: 90, availability: 0.9995, budgetPerHour: 10 } }], + solution: PEAK_FIX, + challenge: { + peakLoad: 8_000, + scenarios: [ZONE_DOWN], + checks: [ + reads, + cached, + capacity(8_000), + p99(90), + served("zone-served", "Everyone is still served when a zone goes down", "zone-down"), + slow("zone-p99", "Slowest 1 in 100 while a zone is down (p99)", "zone-down", 200), + availability(0.9995), + cost(10), + ], + }, +}; + +// ---- 6. hard: orders are piling up ------------------------------------------------------------------ + +const ORDERS_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.large", count: 2, autoscale: 0, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 0, multiAz: 1, readRatio: 0.7 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const ORDERS_FIX: SolutionDef = { + summary: "Save orders off the request. The web servers put each order on an SQS queue, two workers take them and save them to the database in groups, and the database is sized for the real load.", + board: board( + [ + { id: "client", kind: "client", x: 1, y: 0 }, + { id: "alb", kind: "aws-alb", x: 1, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 1, y: 2, props: { size: "c5.large", count: 3, autoscale: 0, azs: 2 } }, + { id: "q", kind: "aws-sqs", x: 0, y: 3, props: { queueType: "standard" } }, + { id: "db", kind: "aws-rds", x: 2, y: 3, props: { size: "db.r5.xlarge", replicas: 1, multiAz: 1, readRatio: 0.7 } }, + { id: "w", kind: "worker", x: 0, y: 4, props: { size: "compute-small", count: 2, batchSize: 100 } }, + ], + [...ORDERS_START.edges, { from: "web", to: "q" }, { from: "q", to: "w" }, { from: "w", to: "db", via: ["r", "l"] }], + ), + parts: { + alb: { + why: "The ALB spreads the 4,000 requests a second over the servers. It is billed per request: $2.90 an hour.", + checks: ["read", "capacity"], + without: "Without the ALB nothing spreads the traffic over the servers.", + }, + web: { + why: "Three c5.large servers are 56% busy at the peak. If one dies, the other two carry it. The two original servers were 83% busy, and one dying left only 60% of requests served.", + checks: ["capacity", "p99", "app-dies"], + without: "With two servers, losing one leaves 167% load on the other, so only 60% of requests are served.", + }, + q: { + why: "The queue holds each order until a worker saves it. About 1 request in 4 is an order, so about 1,000 orders a second arrive. The web server hands the order over and is free. No order is lost while the workers are away. It costs $1.44 an hour.", + checks: ["order", "worker-dies", "cost"], + without: "With no queue an order has nowhere to wait: 120,000 orders are lost in a 2 minute outage and the order path check fails.", + }, + w: { + why: "Two small workers handle 4,800 orders a second against 1,000 arriving. They have 3,800 a second to spare, so the 120,000 orders that waited in 2 minutes clear in 32 seconds. They save in groups of 100, so the database sees about 10 saves a second, not 1,000.", + checks: ["order", "worker-dies", "p99"], + without: "With one worker the spare is only 1,400 a second and the pile takes 86 seconds to clear, over the 60 second limit. With a batch size of 1 the database is 73% busy and p99 rises to 87 ms, over the 80 ms limit.", + }, + db: { + why: "The database is 58% busy with one read replica and Multi-AZ. The old db.r5.large was 233% busy. The replica shares the reads and Multi-AZ keeps the database from being the weak link.", + checks: ["capacity", "p99", "app-dies", "availability", "cost"], + without: "With the first db.r5.large and no replica the database is 234% busy and serves only 1,710 requests a second. A db.r5.2xlarge with three replicas works but costs $9.64 an hour, over the $7.00 budget.", + }, + }, +}; + +const ordersPile: HldLabSpec = { + slug: "sd-orders-pile", + family: "hld", + title: "Orders are piling up", + purpose: "Move order saving off the web request with a queue and workers, prove nothing is lost when the workers stop, and stay within the budget.", + limits: LIMITS + " About 1 request in 4 is an order and leaves one message in the queue.", + hints: [ + "Run the tests. Orders have no queue, so they have nowhere to wait. The failing reasons say which link is missing.", + "Link the web servers to an SQS queue, the queue to a worker, and the worker to the database. Orders then wait safely in the queue.", + "A worker can save many orders in one trip: raise its batch size. Many tiny saves hurt the database.", + "When the workers stop, orders pile up. After they return, they must clear the pile fast. The spare capacity of the workers is what the drain check measures.", + "Workers and queue cost money. The budget is $7.00 an hour, so a few small workers are better than many big ones. The database also needs to be bigger.", + ], + allowedComponents: ["client", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds", "aws-sqs", "worker"], + startingBoard: ORDERS_START, + scenario: + "Sale day: 4,000 requests a second, and about 1 in 4 is an order. The web servers save every order themselves, the database is 233% busy, and orders fail. If the order service stops for 2 minutes, those orders are lost for good. Put orders on a queue, add workers that save them, and make sure a 2 minute stop is fully cleared within 60 seconds. Stay at $7.00 an hour or less.", + levels: [{ id: "l1", load: 4_000, targets: { rps: 4_000, p99Ms: 80, availability: 0.999, budgetPerHour: 7 } }], + solution: ORDERS_FIX, + challenge: { + peakLoad: 4_000, + shares: { queue: 0.25 }, + scenarios: [LOSE_APP, LOSE_WORKERS], + checks: [ + reads, + { + type: "path", id: "order", kind: "functional", label: "An order is saved without making the buyer wait", + chain: ["client", "compute", "queue", "worker", "database"], target: "the path app servers > queue > worker > database", + }, + capacity(4_000), + p99(80), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + { + type: "drain", id: "worker-dies", kind: "non-functional", label: "No order is lost when the workers stop", + outageSeconds: 120, maxDrainSeconds: 60, items: "orders", done: "saved", + }, + availability(0.999), + cost(7), + ], + }, +}; + +// ---- the pool --------------------------------------------------------------------------------------- + +export const SYSDESIGN_POOL: SysdesignRound[] = [ + { id: "sd-bill-tripled", difficulty: "easy", title: "The bill tripled", brief: "The AWS bill is three times too high for the real traffic. Make the system cheaper, and keep it safe.", spec: billTripled }, + { id: "sd-launch-slow", difficulty: "easy", title: "Launch day is slow", brief: "Launch traffic made the site slow, and the database is overloaded. Speed it up without a huge bill.", spec: launchDaySlow }, + { id: "sd-flash-sale", difficulty: "medium", title: "The flash sale melts the database", brief: "A flash sale sends every read to one database. Take the load off it, even when the cache is empty.", spec: flashSale }, + { id: "sd-lost-zone", difficulty: "medium", title: "We lost a zone", brief: "One AWS zone failed and the whole site went down. Make sure one zone can never stop it again.", spec: lostZone }, + { id: "sd-peak-day", difficulty: "hard", title: "Peak day, one zone down, tight budget", brief: "Peak day with a zone down and a tight budget. Several parts must change together.", spec: peakDay }, + { id: "sd-orders-pile", difficulty: "hard", title: "Orders are piling up", brief: "Orders are saved inside the web request and get lost or pile up. Use a queue and workers, within the budget.", spec: ordersPile }, +]; diff --git a/frontend/src/shared/games/sysdesign/scenarios.ts b/frontend/src/shared/games/sysdesign/scenarios.ts deleted file mode 100644 index b87fa35d..00000000 --- a/frontend/src/shared/games/sysdesign/scenarios.ts +++ /dev/null @@ -1,394 +0,0 @@ -// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. -// The pool of production incidents. Every round is plain data: a system, 24 hours of traffic, the -// goals, and a catalog of changes (each one a patch on the model). All prices are round, illustrative -// numbers made up for the game. They are not AWS quotes. -import type { Difficulty } from "../types"; -import { STEPS, type ChangeDef, type DeepPartial, type Model, type SysdesignRound } from "./types"; - -/** A model with sensible defaults. A scenario overrides only what it needs. */ -function model(over: DeepPartial = {}): Model { - const base: Model = { - app: { label: "m5.large", count: 4, rpsEach: 100, monthlyEach: 70, baseMs: 20, zones: 1, healthChecks: false, autoscale: false, scaleMin: 2, scaleMax: 8, pricing: "ondemand" }, - db: { kind: "rds", label: "db.m5.large", capacity: 400, monthly: 140, replicas: 0, replicaMonthly: 140, multiAz: false, pricing: "ondemand", readMs: 12, writeMs: 20, readCost: 1, skew: 1 }, - cache: { on: false, hit: 0.85, monthly: 90 }, - cdn: { on: false, offload: 0.9, monthly: 40 }, - queue: { on: false, monthly: 10 }, - batch: { separate: false, workersMonthly: 60 }, - net: { egressGb: 500, natGb: 500, s3Share: 0.7, s3Endpoint: false, natGateways: 1 }, - logs: { gb: 200, hotRate: 0.023, coldRate: 0.004, coldShare: 0 }, - }; - return { - app: { ...base.app, ...over.app }, - db: { ...base.db, ...over.db }, - cache: { ...base.cache, ...over.cache }, - cdn: { ...base.cdn, ...over.cdn }, - queue: { ...base.queue, ...over.queue }, - batch: { ...base.batch, ...over.batch }, - net: { ...base.net, ...over.net }, - logs: { ...base.logs, ...over.logs }, - }; -} - -/** Traffic for 24 hours, by straight lines between [hour, requests per second] points. */ -function shape(points: Array<[number, number]>): number[] { - const out: number[] = []; - for (let t = 0; t < STEPS; t++) { - let value = points[points.length - 1]![1]; - for (let i = 0; i < points.length - 1; i++) { - const [t0, v0] = points[i]!; - const [t1, v1] = points[i + 1]!; - if (t >= t0 && t <= t1) { - value = t1 === t0 ? v1 : v0 + ((v1 - v0) * (t - t0)) / (t1 - t0); - break; - } - } - out.push(Math.round(value)); - } - return out; -} - -/** A normal day: quiet at night, busy in the afternoon. */ -const day = (low: number, high: number) => shape([[0, low], [6, low], [11, high], [17, high], [23, low]]); - -type Scenario = SysdesignRound; - -const POOL: Scenario[] = [ - // ───────────────────────────── EASY ───────────────────────────── - { - id: "sd-bill-tripled", - difficulty: "easy", - title: "The bill tripled", - brief: "Finance says the AWS bill is three times higher than last quarter. Traffic did not grow. Cut the bill and keep the site fast.", - incident: "COST ALERT: monthly spend is 3x the budget. Servers and database run at under 10% busy.", - model: model({ - app: { label: "m5.2xlarge", count: 6, rpsEach: 400, monthlyEach: 280 }, - db: { label: "db.r5.2xlarge", capacity: 2400, monthly: 700 }, - net: { egressGb: 1500, natGb: 400 }, - }), - traffic: day(25, 90), - mix: { staticShare: 0.3, readShare: 0.8 }, - goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 700 }, - stretch: { maxCostUsd: 520 }, - changes: [ - { id: "rightsize-app", label: "Right-size servers to 3x m5.large", description: "The fleet is much bigger than the traffic needs. Three m5.large servers still handle the peak with room to spare.", patch: { app: { label: "m5.large", count: 3, rpsEach: 100, monthlyEach: 70 } } }, - { id: "rightsize-db", label: "Right-size the database to db.m5.large", description: "A db.r5.2xlarge is built for memory-heavy work. This database is almost idle, so a db.m5.large is enough.", patch: { db: { label: "db.m5.large", capacity: 600, monthly: 140 } } }, - { id: "savings-plan", label: "Buy a 1-year Compute Savings Plan", description: "Commit to steady EC2 use for one year and pay about 30% less per server than on-demand.", patch: { app: { pricing: "savings" } } }, - { id: "reserved-rds", label: "Buy a 1-year RDS Reserved Instance", description: "Commit to one database size for one year and pay about 38% less than on-demand.", patch: { db: { pricing: "reserved" } } }, - { id: "bigger-4xl", label: "Move up to m5.4xlarge for headroom", description: "Bigger servers feel safe, but they cost twice as much per server.", patch: { app: { label: "m5.4xlarge", rpsEach: 800, monthlyEach: 560 } } }, - { id: "add-replica", label: "Add a read replica for safety", description: "A second copy of the database for reads. It costs as much as the database itself.", patch: { db: { replicas: 1, replicaMonthly: 700 } } }, - ], - maxChanges: 3, - solution: ["rightsize-app", "rightsize-db", "savings-plan"], - trap: "bigger-4xl", - trapNote: "Bigger servers do not help when the old ones were already idle. They only raise the bill.", - hints: [ - "Look at the busy bars: the servers and the database are almost idle.", - "Paying for capacity you do not use is the problem. Make the machines smaller.", - "Right-size both the servers and the database, then commit to a steady price with a savings plan or a reserved instance.", - ], - focus: "app", - }, - { - id: "sd-static-flood", - difficulty: "easy", - title: "Images are crushing the web servers", - brief: "The shop is slow all afternoon. Most requests are for images, CSS and JavaScript files that never change.", - incident: "LATENCY ALERT: p95 is over 1 second. App servers are above 90% busy serving static files.", - model: model({ app: { count: 4 }, net: { egressGb: 3000 } }), - traffic: shape([[0, 150], [6, 150], [10, 900], [17, 900], [23, 150]]), - mix: { staticShare: 0.8, readShare: 0.8 }, - goals: { maxP95Ms: 140, minAvailability: 99.5, maxCostUsd: 720 }, - stretch: { maxCostUsd: 680 }, - changes: [ - { id: "add-cdn", label: "Put CloudFront in front", description: "A CDN keeps copies of static files near the user, so most of them never reach your servers. It also cuts data transfer cost.", patch: { cdn: { on: true } } }, - { id: "more-servers", label: "Add 4 more app servers", description: "More servers share the load. It works, but you pay for them every hour.", patch: { app: { count: 8 } } }, - { id: "bigger-db", label: "Move to a bigger database", description: "A bigger database is stronger, but the database is not the busy part here.", patch: { db: { label: "db.r5.xlarge", capacity: 1200, monthly: 350 } } }, - { id: "add-cache", label: "Add an ElastiCache node", description: "A cache answers repeated database reads fast. Static files do not come from the database.", patch: { cache: { on: true } } }, - ], - maxChanges: 2, - solution: ["add-cdn"], - trap: "bigger-db", - trapNote: "The database was never the busy part, so a bigger one only costs more.", - hints: ["Check which bar is red. It is the app servers.", "Most traffic is static files. They can be served from somewhere else.", "Use a CDN (CloudFront) for static files."], - focus: "app", - }, - { - id: "sd-logs-forever", - difficulty: "easy", - title: "Logs that never end", - brief: "Application logs are kept in S3 Standard forever. The storage line grows every month. Nobody reads logs older than a month.", - incident: "COST ALERT: S3 storage is now the biggest line on the bill and grows 5 TB each month.", - model: model({ logs: { gb: 60000, coldShare: 0 }, net: { egressGb: 300 } }), - traffic: day(20, 60), - mix: { staticShare: 0.3, readShare: 0.8 }, - goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 900 }, - stretch: { maxCostUsd: 650 }, - changes: [ - { id: "glacier-lifecycle", label: "Lifecycle rule: move to Glacier after 30 days", description: "S3 moves old logs to Glacier on its own. Glacier costs about a fifth of S3 Standard per GB.", patch: { logs: { coldShare: 0.9 } } }, - { id: "compress-logs", label: "Compress logs with gzip before upload", description: "Text logs shrink to about a third of their size, so you store and pay for less.", patch: { logs: { gb: 20000 } } }, - { id: "ebs-volumes", label: "Keep the logs on bigger EBS volumes", description: "Block storage is for running servers. It costs more per GB than S3.", patch: { logs: { hotRate: 0.08 } } }, - { id: "intelligent-tiering", label: "Turn on S3 Intelligent-Tiering", description: "S3 watches access and moves some data to a cheaper tier. Fine for unknown patterns, but it also adds a monitoring fee per object.", patch: { logs: { coldShare: 0.5, coldRate: 0.0125 } } }, - ], - maxChanges: 3, - solution: ["glacier-lifecycle", "compress-logs"], - trap: "ebs-volumes", - trapNote: "EBS costs more per GB than S3, so it makes the log bill bigger.", - hints: ["The big line is log storage, not servers.", "Old logs are almost never read. They do not need the most expensive storage class.", "Move old logs to Glacier with a lifecycle rule, and store fewer bytes by compressing."], - focus: "storage", - }, - { - id: "sd-nat-bill", - difficulty: "easy", - title: "The NAT gateway line explodes", - brief: "Servers in private subnets download big files from S3 through a NAT gateway. NAT charges for every GB that passes through.", - incident: "COST ALERT: NAT Gateway data processing is the top line on the bill, 30 TB this month.", - model: model({ net: { natGb: 30000, s3Share: 0.8, egressGb: 7000 } }), - traffic: day(30, 80), - mix: { staticShare: 0.4, readShare: 0.8 }, - goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 1500 }, - stretch: { maxCostUsd: 1100 }, - changes: [ - { id: "s3-endpoint", label: "Add an S3 gateway VPC endpoint", description: "Traffic to S3 goes over the AWS network directly, not through NAT. A gateway endpoint for S3 has no hourly or per-GB charge.", patch: { net: { s3Endpoint: true } } }, - { id: "add-cdn", label: "Put CloudFront in front of downloads", description: "A CDN serves popular files from the edge. Data transfer out gets cheaper and your servers are asked less often.", patch: { cdn: { on: true } } }, - { id: "second-nat", label: "Add a second NAT gateway per AZ", description: "It is good for availability, but it adds another monthly fee and does not reduce the data that passes through NAT.", patch: { net: { natGateways: 2 } } }, - { id: "bigger-app", label: "Use bigger servers", description: "The servers are fine. The traffic path is the problem.", patch: { app: { label: "m5.xlarge", rpsEach: 200, monthlyEach: 140 } } }, - ], - maxChanges: 2, - solution: ["s3-endpoint", "add-cdn"], - trap: "second-nat", - trapNote: "A second NAT gateway adds a fixed fee and does not reduce the GB that cross NAT.", - hints: ["Look at the cost lines: the NAT gateway is the biggest.", "Most of that traffic is only S3 traffic. It does not need to go through NAT at all.", "Add an S3 gateway endpoint. A CDN also cuts the data transfer line."], - focus: "nat", - }, - // ───────────────────────────── MEDIUM ───────────────────────────── - { - id: "sd-flash-sale-db", - difficulty: "medium", - title: "Flash sale crushes the database", - brief: "A flash sale at noon sends 6 times the normal traffic. The web servers cope, but the single database is melting.", - incident: "PAGE: database CPU at 100% and checkout errors rising. Flash sale in progress.", - model: model({ app: { count: 10 }, db: { label: "db.r5.large", capacity: 330, monthly: 300, replicaMonthly: 300 }, net: { egressGb: 400 } }), - traffic: shape([[0, 100], [9, 100], [11, 120], [12, 700], [15, 700], [16, 120], [23, 100]]), - mix: { staticShare: 0.1, readShare: 0.7 }, - goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 1700, maxPeakDbUtil: 0.9 }, - stretch: { maxCostUsd: 1500 }, - changes: [ - { id: "add-cache", label: "Add ElastiCache (Redis) for hot products", description: "Hot product pages are read again and again. A cache answers them from memory so the database sees fewer reads.", patch: { cache: { on: true, hit: 0.6 } } }, - { id: "add-replica", label: "Add a read replica", description: "A second database copy that answers reads. The primary only handles writes and half of the reads.", patch: { db: { replicas: 1 } } }, - { id: "add-queue", label: "Put orders in an SQS queue", description: "Writes wait in a queue and the database drains them at its own pace. The user gets a fast answer, the database never gets a spike.", patch: { queue: { on: true } } }, - { id: "more-servers", label: "Double the app servers", description: "More web servers, but they were not the busy part. The database is.", patch: { app: { count: 16 } } }, - { id: "bigger-db", label: "Upgrade to db.r5.4xlarge", description: "A much bigger database. It fixes the spike but costs a lot every month, also on quiet days.", patch: { db: { label: "db.r5.4xlarge", capacity: 1320, monthly: 1200 } } }, - ], - maxChanges: 3, - solution: ["add-cache", "add-replica"], - trap: "more-servers", - trapNote: "The web servers were not the problem. More of them only raises cost and sends even more work to the database.", - hints: ["Look at the bars during the sale: the database is at 100%, the servers are fine.", "Reads dominate. Take reads away from the primary database.", "Use a cache and a read replica together. A queue can smooth the writes."], - focus: "db", - }, - { - id: "sd-p95-four-seconds", - difficulty: "medium", - title: "p95 latency is 4 seconds", - brief: "Every page request hits the database, and static files come from the same servers. Pages feel slow all afternoon.", - incident: "LATENCY ALERT: p95 is 4 s. Database and app servers are both near 100% busy.", - model: model({ app: { count: 3 }, db: { capacity: 200 }, net: { egressGb: 1500 } }), - traffic: shape([[0, 80], [7, 80], [10, 420], [18, 420], [23, 80]]), - mix: { staticShare: 0.5, readShare: 0.9 }, - goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 650 }, - stretch: { maxCostUsd: 620, maxP95Ms: 130 }, - changes: [ - { id: "add-cache", label: "Add ElastiCache for repeated reads", description: "Most pages ask the database the same questions. A cache returns the answer in about 2 ms.", patch: { cache: { on: true, hit: 0.85 } } }, - { id: "add-cdn", label: "Put CloudFront in front for static files", description: "Images and scripts come from the edge, so the web servers only do dynamic work.", patch: { cdn: { on: true } } }, - { id: "add-replica", label: "Add a read replica", description: "A replica doubles read capacity, but every read is still a database read, and you pay for a second database.", patch: { db: { replicas: 1 } } }, - { id: "more-servers", label: "Add 3 more app servers", description: "More servers handle more requests, but they all still wait for the same database.", patch: { app: { count: 6 } } }, - { id: "bigger-db", label: "Use a bigger database", description: "More database power. Pricey, and static files still hit the servers.", patch: { db: { label: "db.r5.xlarge", capacity: 800, monthly: 350 } } }, - ], - maxChanges: 3, - solution: ["add-cache", "add-cdn"], - trap: "more-servers", - trapNote: "More servers do nothing for slow reads. They all wait for the same database, and they cost money.", - hints: ["Two parts are busy: the database and the app servers.", "Do not answer the same question from the database again and again, and do not make servers send files.", "Add a cache for reads and a CDN for static files."], - focus: "db", - }, - { - id: "sd-az-outage", - difficulty: "medium", - title: "One AZ goes dark", - brief: "At 1 pm one Availability Zone fails. Everything runs in that one zone. Make the site survive a zone failure.", - incident: "OUTAGE: us-east-1a is unreachable. All servers and the database are in 1a. The site is down.", - model: model({ app: { count: 4 }, net: { egressGb: 400 } }), - traffic: day(30, 140), - mix: { staticShare: 0.2, readShare: 0.8 }, - outage: { from: 13, to: 17 }, - goals: { maxP95Ms: 250, minAvailability: 99, maxCostUsd: 750 }, - stretch: { maxCostUsd: 680 }, - changes: [ - { id: "two-azs", label: "Spread servers across 2 AZs", description: "Half of the servers run in a second Availability Zone, behind a load balancer.", patch: { app: { zones: 2 } } }, - { id: "health-checks", label: "Add load balancer health checks", description: "The load balancer stops sending users to servers that do not answer.", patch: { app: { healthChecks: true } } }, - { id: "rds-multi-az", label: "Turn on RDS Multi-AZ", description: "A standby database in the other zone takes over by itself if the primary fails.", patch: { db: { multiAz: true } } }, - { id: "autoscaling", label: "Add an Auto Scaling group", description: "Servers are added when load grows and removed when it falls, so you pay for less at night.", patch: { app: { autoscale: true, scaleMin: 2, scaleMax: 8 } } }, - { id: "bigger-servers", label: "Use bigger servers", description: "Bigger servers in the same zone still go down with the zone.", patch: { app: { label: "m5.xlarge", rpsEach: 200, monthlyEach: 140, count: 4 } } }, - ], - maxChanges: 4, - solution: ["two-azs", "health-checks", "rds-multi-az"], - trap: "bigger-servers", - trapNote: "A bigger server is still one server in one zone. It does not survive a zone failure and it costs twice as much.", - hints: ["Everything lives in one zone, so one failure takes down everything.", "You need copies of the servers and of the database in a second zone.", "Spread servers over two AZs, let the load balancer find dead servers, and give the database a standby."], - focus: "lb", - }, - { - id: "sd-batch-starves-web", - difficulty: "medium", - title: "The report job starves the shop", - brief: "A heavy report job runs at midday on the same servers and database as the shop. While it runs, customers wait.", - incident: "LATENCY ALERT: p95 jumps to 3 s from 11:00 to 15:00, the same time the reports run.", - model: model({ app: { count: 4, monthlyEach: 120, label: "m5.xlarge", rpsEach: 100 }, db: { capacity: 400, monthly: 200 }, net: { egressGb: 600 } }), - traffic: shape([[0, 40], [6, 40], [10, 130], [17, 130], [23, 40]]), - mix: { staticShare: 0.2, readShare: 0.8 }, - batchJob: { from: 11, to: 15, appLoad: 240, dbLoad: 240 }, - goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 800 }, - stretch: { maxCostUsd: 720 }, - changes: [ - { id: "spot-workers", label: "Run the job on Spot workers", description: "Move the report job to its own Spot instances, which cost about 70% less and can be interrupted. The shop stops competing with it.", patch: { batch: { separate: true } } }, - { id: "savings-plan", label: "Buy a 1-year Compute Savings Plan", description: "Pay about 30% less for the steady web servers.", patch: { app: { pricing: "savings" } } }, - { id: "autoscaling", label: "Add an Auto Scaling group", description: "Adds servers when the load grows. It helps the web tier but does nothing for the shared database.", patch: { app: { autoscale: true, scaleMin: 2, scaleMax: 8 } } }, - { id: "more-servers", label: "Add 4 more app servers", description: "Bigger fleet all day, to survive 4 hours. Costly, and the database still gets the job load.", patch: { app: { count: 8 } } }, - { id: "reserved-rds", label: "Buy a 1-year RDS Reserved Instance", description: "Pay about 38% less for the database.", patch: { db: { pricing: "reserved" } } }, - ], - maxChanges: 3, - solution: ["spot-workers", "savings-plan"], - trap: "more-servers", - trapNote: "Extra servers for four busy hours cost money all month, and the database still has to carry the job.", - hints: ["Look at the times: the slow period matches the job.", "The shop and the job share the same machines. Separate them.", "Move the job to Spot workers. A savings plan keeps the bill in budget."], - focus: "workers", - }, - // ───────────────────────────── HARD ───────────────────────────── - { - id: "sd-missing-index", - difficulty: "hard", - title: "A query scans a million rows", - brief: "The product search runs a full table scan on every request. At lunch the database cannot keep up.", - incident: "PAGE: slow query log shows 180 ms scans on orders. Database CPU 100% at lunch.", - model: model({ - app: { count: 5 }, - db: { label: "db.m5.xlarge", capacity: 600, monthly: 250, readCost: 6, readMs: 180 }, - net: { egressGb: 500 }, - }), - traffic: shape([[0, 40], [8, 60], [11, 250], [15, 250], [18, 80], [23, 40]]), - mix: { staticShare: 0.2, readShare: 0.85 }, - goals: { maxP95Ms: 100, minAvailability: 99.5, maxCostUsd: 850, maxPeakDbUtil: 0.7 }, - stretch: { maxCostUsd: 800 }, - changes: [ - { id: "add-index", label: "Add an index on the search column", description: "An index lets the database find rows directly instead of reading the whole table. Reads get both faster and cheaper.", patch: { db: { readCost: 1, readMs: 12 } } }, - { id: "add-cache", label: "Add ElastiCache for repeated searches", description: "Popular searches repeat. A cache answers them in memory.", patch: { cache: { on: true, hit: 0.7 } } }, - { id: "bigger-db", label: "Upgrade to db.m5.4xlarge", description: "Four times the database power. A scan is still a scan, and the bill goes way up.", patch: { db: { label: "db.m5.4xlarge", capacity: 2400, monthly: 1000 } } }, - { id: "add-replica", label: "Add two read replicas", description: "More copies to scan the table. Each costs as much as the database.", patch: { db: { replicas: 2, replicaMonthly: 250 } } }, - { id: "more-servers", label: "Add more app servers", description: "The servers are not the slow part.", patch: { app: { count: 10 } } }, - ], - maxChanges: 3, - solution: ["add-index", "add-cache"], - trap: "bigger-db", - trapNote: "A bigger database still scans the whole table, so each query stays slow, and the cost goes over the limit.", - hints: ["Read the incident: a query takes 180 ms because it reads every row.", "Fix the query first, because power does not fix a bad query.", "Add the index. Then take the repeated reads off the database with a cache."], - focus: "db", - }, - { - id: "sd-hot-partition", - difficulty: "hard", - title: "One hot key, throttled writes", - brief: "A DynamoDB table uses the date as its partition key. Today's partition gets almost all the writes and is throttled, while the table has plenty of capacity overall.", - incident: "ALARM: ThrottledRequests on orders-table. Total capacity use is 20% but one partition is at 100%.", - model: model({ - app: { count: 10 }, - db: { kind: "dynamodb", label: "DynamoDB orders", capacity: 1100, monthly: 450, skew: 6, readMs: 6, writeMs: 10, readCost: 1 }, - net: { egressGb: 400 }, - }), - traffic: shape([[0, 150], [8, 200], [12, 800], [16, 800], [19, 250], [23, 150]]), - mix: { staticShare: 0.1, readShare: 0.45 }, - goals: { maxP95Ms: 220, minAvailability: 99.5, maxCostUsd: 1500, maxPeakDbUtil: 0.85 }, - stretch: { maxCostUsd: 1450 }, - changes: [ - { id: "shard-key", label: "Add a random suffix to the partition key", description: "Writes for the same date spread over many partitions, so no single partition is hot. This is called write sharding.", patch: { db: { skew: 1.5 } } }, - { id: "add-dax", label: "Add DAX, a DynamoDB cache", description: "A cache in front of DynamoDB answers repeated reads. Fewer reads means more room for writes.", patch: { cache: { on: true, hit: 0.7, monthly: 150 } } }, - { id: "add-queue", label: "Buffer writes with SQS", description: "Writes wait in a queue and are written at a steady pace instead of in a burst.", patch: { queue: { on: true } } }, - { id: "double-capacity", label: "Double the provisioned capacity", description: "More capacity for the table. It is spread over partitions, so the hot one gets only a bit more.", patch: { db: { capacity: 2200, monthly: 900 } } }, - { id: "more-servers", label: "Add more app servers", description: "The throttling is in the table, not in the servers.", patch: { app: { count: 12 } } }, - ], - maxChanges: 3, - solution: ["shard-key", "add-dax"], - trap: "double-capacity", - trapNote: "Capacity is shared across partitions. The hot partition is still hot, and you pay double.", - hints: ["Total capacity is fine, but one partition gets almost all the work.", "The cause is the key, not the capacity. Spread the key.", "Shard the partition key. A cache for reads gives the writes more room."], - focus: "db", - }, - { - id: "sd-black-friday-az", - difficulty: "hard", - title: "Peak day plus a lost zone", - brief: "It is the biggest sales day. Traffic triples, and in the middle of it one Availability Zone fails. The fixed fleet is too small and sits in one zone.", - incident: "OUTAGE: us-east-1a lost during peak sales. Fleet at 100% before the failure.", - model: model({ - app: { count: 6, label: "m5.xlarge", rpsEach: 100, monthlyEach: 100 }, - db: { label: "db.r5.large", capacity: 900, monthly: 300 }, - net: { egressGb: 800 }, - }), - traffic: shape([[0, 60], [7, 100], [10, 500], [17, 500], [20, 120], [23, 60]]), - mix: { staticShare: 0.15, readShare: 0.8 }, - outage: { from: 13, to: 16 }, - goals: { maxP95Ms: 350, minAvailability: 99, maxCostUsd: 1800 }, - stretch: { maxCostUsd: 1600 }, - changes: [ - { id: "asg-two-azs", label: "Auto Scaling group across 2 AZs", description: "Servers are spread over two zones and the group adds more when load rises, and removes them when it falls.", patch: { app: { zones: 2, autoscale: true, scaleMin: 4, scaleMax: 16 } } }, - { id: "health-checks", label: "Load balancer health checks", description: "Dead servers are removed from rotation within seconds.", patch: { app: { healthChecks: true } } }, - { id: "rds-multi-az", label: "RDS Multi-AZ", description: "A standby database in the second zone takes over after a failure.", patch: { db: { multiAz: true } } }, - { id: "add-cache", label: "Add ElastiCache", description: "Fewer reads reach the database. It helps speed, not zone failure.", patch: { cache: { on: true, hit: 0.8 } } }, - { id: "oversize-fleet", label: "Double the fixed fleet to 12 servers", description: "Always-on capacity for the peak. It does not fix the zone problem and it is on the bill for the whole month.", patch: { app: { count: 12 } } }, - ], - maxChanges: 4, - solution: ["asg-two-azs", "health-checks", "rds-multi-az"], - trap: "oversize-fleet", - trapNote: "A fixed, doubled fleet costs the same at night as at peak, and still lives in one zone.", - hints: ["Two problems at once: too little capacity at peak, and one zone.", "You need servers in two zones that can grow, plus a way to remove dead ones.", "Auto Scaling over two AZs, health checks, and a Multi-AZ database."], - focus: "app", - }, - { - id: "sd-halve-the-bill", - difficulty: "hard", - title: "Halve the bill, keep it fast", - brief: "The CFO wants the monthly bill cut in half without hurting speed or uptime. Money leaks in four places.", - incident: "COST ALERT: bill is $3,400 a month. Target is under $2,000. Latency and uptime must not suffer.", - model: model({ - app: { label: "m5.xlarge", count: 6, rpsEach: 200, monthlyEach: 140 }, - db: { label: "db.r5.xlarge", capacity: 1200, monthly: 350 }, - net: { egressGb: 6000, natGb: 15000, s3Share: 0.8 }, - logs: { gb: 40000 }, - }), - traffic: day(60, 160), - mix: { staticShare: 0.5, readShare: 0.8 }, - goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 2000 }, - stretch: { maxCostUsd: 1750 }, - changes: [ - { id: "add-cdn", label: "Add CloudFront", description: "Cheaper data transfer out, and static files stop reaching the servers.", patch: { cdn: { on: true } } }, - { id: "s3-endpoint", label: "S3 gateway VPC endpoint", description: "Stops S3 traffic from going through the NAT gateway.", patch: { net: { s3Endpoint: true } } }, - { id: "glacier-lifecycle", label: "Lifecycle old logs to Glacier", description: "Old logs move to a much cheaper storage class.", patch: { logs: { coldShare: 0.9 } } }, - { id: "savings-plan", label: "1-year Compute Savings Plan", description: "About 30% off the servers.", patch: { app: { pricing: "savings" } } }, - { id: "tiny-server", label: "Run everything on 1 t3.micro", description: "The cheapest possible server. It cuts the bill and cannot carry the traffic.", patch: { app: { label: "t3.micro", count: 1, rpsEach: 15, monthlyEach: 9 } } }, - { id: "second-nat", label: "A NAT gateway in every AZ", description: "Better resilience, more fixed cost.", patch: { net: { natGateways: 2 } } }, - ], - maxChanges: 4, - solution: ["add-cdn", "s3-endpoint", "glacier-lifecycle", "savings-plan"], - trap: "tiny-server", - trapNote: "A tiny server makes the bill small, but it cannot serve the traffic. Uptime and speed fall.", - hints: ["Open the cost lines. Four of them are big: transfer, NAT, logs, servers.", "Each leak has a cheap plug. Do not shrink the servers below the traffic.", "CDN, S3 endpoint, Glacier lifecycle, savings plan."], - focus: "nat", - }, -]; - -export const SYSDESIGN_POOL: readonly SysdesignRound[] = POOL; - -export function scenariosByDifficulty(difficulty: Difficulty): SysdesignRound[] { - return POOL.filter((r) => r.difficulty === difficulty); -} - -export type { ChangeDef }; diff --git a/frontend/src/shared/games/sysdesign/sim.ts b/frontend/src/shared/games/sysdesign/sim.ts deleted file mode 100644 index e8fb5194..00000000 --- a/frontend/src/shared/games/sysdesign/sim.ts +++ /dev/null @@ -1,277 +0,0 @@ -// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. -// A small, pure, deterministic traffic simulation. It uses only + - * / and min, max, ceil, round, -// so the browser and the server always agree to the last digit. No clock, no randomness. -import { - STEPS, - type CostLine, - type DeepPartial, - type GoalCheck, - type Goals, - type Model, - type SimResult, - type StepResult, - type SysdesignRound, -} from "./types"; - -const APP_PRICING = { ondemand: 1, savings: 0.68, reserved: 0.6 } as const; -const DB_PRICING = { ondemand: 1, reserved: 0.62 } as const; -/** Illustrative unit prices, in dollars. They are round numbers, not real quotes. */ -export const PRICES = { egressPerGb: 0.09, cdnPerGb: 0.04, natPerGb: 0.045, natPerMonth: 33 } as const; - -function isObject(value: unknown): value is Record { - return typeof value === "object" && value !== null && !Array.isArray(value); -} - -/** Merge a patch onto a copy of a model. Only objects are merged, everything else is replaced. */ -export function mergePatch(base: T, patch: DeepPartial): T { - if (!isObject(base) || !isObject(patch)) return base; - const out: Record = { ...base }; - for (const key of Object.keys(patch)) { - const next = (patch as Record)[key]; - const prev = out[key]; - out[key] = isObject(prev) && isObject(next) ? mergePatch(prev, next as never) : next; - } - return out as T; -} - -/** The model after the changes, applied in order. Ids that are not offered are ignored. */ -export function applyChanges(round: SysdesignRound, ids: readonly string[]): Model { - let model = round.model; - for (const id of ids) { - const change = round.changes.find((c) => c.id === id); - if (change) model = mergePatch(model, change.patch); - } - return model; -} - -const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, n)); -/** Queueing delay: grows fast as a part gets busy. Capped so a saturated part reads as a timeout. */ -const slow = (baseMs: number, util: number) => Math.min(4000, baseMs / (1 - clamp(util, 0, 0.97))); - -type Point = { ms: number; weight: number }; - -/** A class of requests has a spread: most are near the typical time, a few are much slower. */ -function spread(ms: number, weight: number, out: Point[]) { - if (weight <= 0) return; - out.push({ ms: ms * 0.8, weight: weight * 0.6 }, { ms: ms * 1.3, weight: weight * 0.3 }, { ms: ms * 2.6, weight: weight * 0.1 }); -} - -function weightedPercentile(points: Point[], q: number): number { - const sorted = [...points].sort((a, b) => a.ms - b.ms); - const total = sorted.reduce((sum, p) => sum + p.weight, 0); - if (total <= 0) return 0; - let seen = 0; - for (const p of sorted) { - seen += p.weight; - if (seen >= total * q) return Math.min(4000, Math.round(p.ms)); - } - return Math.min(4000, Math.round(sorted[sorted.length - 1]!.ms)); -} - -export function costLines(model: Model, appInstancesAvg: number): CostLine[] { - const appF = APP_PRICING[model.app.pricing] ?? 1; - const dbF = DB_PRICING[model.db.pricing] ?? 1; - const lines: CostLine[] = []; - const add = (id: string, label: string, usd: number) => { - const rounded = Math.round(usd); - if (rounded > 0) lines.push({ id, label, usd: rounded }); - }; - add("app", `${model.app.label} servers`, appInstancesAvg * model.app.monthlyEach * appF); - add("db", `${model.db.label} database`, (model.db.monthly + (model.db.multiAz ? model.db.monthly : 0)) * dbF); - add("replica", "Read replicas", model.db.replicas * model.db.replicaMonthly * dbF); - if (model.cache.on) add("cache", "ElastiCache", model.cache.monthly); - if (model.cdn.on) add("cdn", "CloudFront", model.cdn.monthly); - if (model.queue.on) add("queue", "SQS queue", model.queue.monthly); - if (model.batch.separate) add("workers", "Spot workers", model.batch.workersMonthly); - const off = model.cdn.on ? model.cdn.offload : 0; - add("egress", "Data transfer out", model.net.egressGb * ((1 - off) * PRICES.egressPerGb + off * PRICES.cdnPerGb)); - const natGb = model.net.natGb * (1 - (model.net.s3Endpoint ? model.net.s3Share : 0)); - add("nat", "NAT gateway", model.net.natGateways * PRICES.natPerMonth + natGb * PRICES.natPerGb); - add("logs", "Log storage", model.logs.gb * ((1 - model.logs.coldShare) * model.logs.hotRate + model.logs.coldShare * model.logs.coldRate)); - return lines; -} - -/** Run the day. The same inputs always give the same result. */ -export function simulate(round: SysdesignRound, changeIds: readonly string[]): SimResult { - const m = applyChanges(round, changeIds); - const { mix, outage, batchJob } = round; - const traffic = Array.from({ length: STEPS }, (_, i) => Math.max(0, round.traffic[i] ?? 0)); - - const batchApp = (t: number) => (batchJob && t >= batchJob.from && t <= batchJob.to && !m.batch.separate ? batchJob.appLoad : 0); - const appWorkFor = (t: number) => { - const load = traffic[t]!; - const st = load * mix.staticShare; - const off = m.cdn.on ? m.cdn.offload : 0; - return st * (1 - off) * 0.25 + (load - st) + batchApp(t); - }; - - const hit = m.cache.on ? m.cache.hit : 0; - const dbCap = Math.max(1, m.db.capacity / Math.max(1, m.db.skew)); - const replicas = Math.max(0, Math.round(m.db.replicas)); - - const steps: StepResult[] = []; - const all: Point[] = []; - const instances: number[] = []; - let backlog = 0; - let totalReq = 0; - let totalOk = 0; - let peakApp = 0; - let peakDb = 0; - let peakBacklog = 0; - - for (let t = 0; t < STEPS; t++) { - const load = traffic[t]!; - const zoneDown = !!outage && t >= outage.from && t <= outage.to; - const outageStart = !!outage && t === outage.from; - const prevWork = appWorkFor(Math.max(0, t - 1)); - - const target = m.app.autoscale ? clamp(Math.ceil(prevWork / (m.app.rpsEach * (m.app.zones === 2 ? 0.4 : 0.6))), m.app.scaleMin, m.app.scaleMax) : m.app.count; - instances.push(target); - - // How many servers are alive, and how much traffic still goes to the dead zone. - let alive = target; - let deadRoute = 0; - if (zoneDown) { - if (m.app.zones === 1) { - alive = 0; - deadRoute = 1; - } else { - alive = m.app.autoscale && !outageStart ? clamp(target, Math.ceil(m.app.scaleMin / 2), m.app.scaleMax) : Math.ceil(target / 2); - deadRoute = m.app.healthChecks ? (outageStart ? 0.04 : 0) : 0.5; - } - } - const reach = 1 - deadRoute; - - const st = load * mix.staticShare; - const dyn = load - st; - const reads = dyn * mix.readShare; - const writes = dyn - reads; - const off = m.cdn.on ? m.cdn.offload : 0; - const stCdn = st * off; - const stOrigin = st - stCdn; - const hitReads = reads * hit; - const missReads = reads - hitReads; - - const running = !!batchJob && t >= batchJob.from && t <= batchJob.to && !m.batch.separate; - const appWork = (stOrigin * 0.25 + dyn + batchApp(t)) * reach; - const cap = alive * m.app.rpsEach; - const fa = appWork <= 0 ? 1 : alive === 0 ? 0 : Math.min(1, cap / appWork); - const appUtil = alive === 0 ? 0 : cap > 0 ? appWork / cap : 0; - - // The database. A single-zone database is lost with the zone. A standby takes over quickly. - const dbDown = zoneDown && !m.db.multiAz; - const failover = zoneDown && m.db.multiAz && outageStart ? 0.97 : 1; - const missIn = missReads * reach * fa; - const writeIn = writes * reach * fa + (m.queue.on ? backlog : 0); - const readsPrimary = missIn / (1 + replicas); - const readsReplica = replicas > 0 ? missIn / (1 + replicas) : 0; - const batchDb = running ? batchJob!.dbLoad : 0; - const fixedLoad = readsPrimary * m.db.readCost + batchDb; - let writesDone = writeIn; - if (m.queue.on) { - writesDone = dbDown ? 0 : Math.min(writeIn, Math.max(0, dbCap - fixedLoad)); - backlog = Math.max(0, writeIn - writesDone); - } else { - backlog = 0; - } - const primaryDemand = writesDone + fixedLoad; - const pu = dbDown ? 0 : primaryDemand / dbCap; - const ru = (readsReplica * m.db.readCost) / dbCap; - const okPrimary = dbDown ? 0 : pu <= 1 ? 1 : 1 / pu; - const okReplica = ru <= 1 ? 1 : 1 / ru; - const okWrite = m.queue.on ? 1 : okPrimary; - const okRead = (okPrimary + replicas * okReplica) / (1 + replicas); - - // Success per class of request. - const successStOrigin = reach * fa; - const successHit = reach * fa; - const successMiss = reach * fa * okRead * failover; - const successWrite = reach * fa * okWrite * failover; - - const appMs = alive === 0 ? 4000 : slow(m.app.baseMs, appUtil); - const readUtil = (pu + replicas * ru) / (1 + replicas); - const dbReadMs = slow(m.db.readMs, readUtil); - const dbWriteMs = slow(m.db.writeMs, pu); - const points: Point[] = []; - spread(12, stCdn, points); - spread(appMs * 0.6, stOrigin * successStOrigin, points); - spread(appMs + 2, hitReads * successHit, points); - spread(appMs + dbReadMs, missReads * successMiss, points); - spread(appMs + (m.queue.on ? 6 : dbWriteMs), writes * successWrite, points); - all.push(...points); - - const ok = stCdn + stOrigin * successStOrigin + hitReads * successHit + missReads * successMiss + writes * successWrite; - const success = load > 0 ? Math.min(1, ok / load) : 1; - totalReq += load; - totalOk += ok; - const p95Ms = weightedPercentile(points, 0.95); - peakApp = Math.max(peakApp, appUtil); - peakDb = Math.max(peakDb, pu, ru); - peakBacklog = Math.max(peakBacklog, backlog); - - steps.push({ - t, - load, - appInstances: alive, - appUtil, - dbUtil: pu, - replicaUtil: ru, - success, - appDrop: clamp(1 - reach * fa, 0, 1), - dbDrop: clamp(1 - okRead * failover, 0, 1), - p95Ms, - status: success < 0.9 ? "down" : success < 0.995 || p95Ms > round.goals.maxP95Ms ? "slow" : "ok", - zoneDown, - batchRunning: running, - backlog, - costToDate: 0, - }); - } - - const avgInstances = instances.reduce((a, b) => a + b, 0) / STEPS; - const lines = costLines(m, avgInstances); - const costUsd = lines.reduce((sum, l) => sum + l.usd, 0); - const appLine = lines.find((l) => l.id === "app")?.usd ?? 0; - const fixedPerStep = (costUsd - appLine) / STEPS; - let acc = 0; - steps.forEach((s, i) => { - acc += (avgInstances > 0 ? (instances[i]! / (avgInstances * STEPS)) * appLine : 0) + fixedPerStep; - s.costToDate = Math.round(acc); - }); - if (steps.length > 0) steps[steps.length - 1]!.costToDate = costUsd; - - return { - model: m, - steps, - p95Ms: weightedPercentile(all, 0.95), - availability: totalReq > 0 ? Math.round((totalOk / totalReq) * 10000) / 100 : 100, - costUsd, - costLines: lines, - peakAppUtil: peakApp, - peakDbUtil: peakDb, - peakBacklog, - }; -} - -const pct = (n: number) => `${Math.round(n * 100)}%`; - -/** Every goal with a yes or no. Used by verify and by the result panel. */ -export function evaluateGoals(goals: Goals, sim: SimResult): GoalCheck[] { - const checks: GoalCheck[] = [ - { id: "p95", label: "Latency (p95)", met: sim.p95Ms <= goals.maxP95Ms, actual: `${sim.p95Ms} ms`, target: `at most ${goals.maxP95Ms} ms` }, - { id: "availability", label: "Availability", met: sim.availability >= goals.minAvailability, actual: `${sim.availability}%`, target: `at least ${goals.minAvailability}%` }, - { id: "cost", label: "Monthly cost", met: sim.costUsd <= goals.maxCostUsd, actual: `$${sim.costUsd}`, target: `at most $${goals.maxCostUsd}` }, - ]; - if (goals.maxPeakAppUtil !== undefined) { - checks.push({ id: "appUtil", label: "App servers peak load", met: sim.peakAppUtil <= goals.maxPeakAppUtil, actual: pct(sim.peakAppUtil), target: `at most ${pct(goals.maxPeakAppUtil)}` }); - } - if (goals.maxPeakDbUtil !== undefined) { - checks.push({ id: "dbUtil", label: "Database peak load", met: sim.peakDbUtil <= goals.maxPeakDbUtil, actual: pct(sim.peakDbUtil), target: `at most ${pct(goals.maxPeakDbUtil)}` }); - } - return checks; -} - -/** What one change alone does to the monthly bill, in dollars (negative saves money). */ -export function costDelta(round: SysdesignRound, id: string): number { - return simulate(round, [id]).costUsd - simulate(round, []).costUsd; -} diff --git a/frontend/src/shared/games/sysdesign/types.ts b/frontend/src/shared/games/sysdesign/types.ts index 92af9efc..8361ef3b 100644 --- a/frontend/src/shared/games/sysdesign/types.ts +++ b/frontend/src/shared/games/sysdesign/types.ts @@ -1,167 +1,15 @@ // GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. -// Shared types for the System Design Runner. Everything here is plain data (no functions), because -// a round travels from the server to the browser as JSON. +// Shared types for the System Design Runner. A round is a real lab spec (the same HldLabSpec the +// platform's labs use) with a broken starting board, so the game plays on the lab's own board. +// Everything here is plain data, because a round travels from the server to the browser as JSON. +import type { Board, HldLabSpec } from "../../lab/engine/hld-types"; import type { RoundBase } from "../types"; -/** Number of traffic steps in one simulated day. One step is one hour. */ -export const STEPS = 24; - -export type Pricing = "ondemand" | "savings" | "reserved"; - -/** The system as the player sees it. A change patches some of these numbers. */ -export type Model = { - app: { - /** For example "m5.2xlarge". */ - label: string; - count: number; - /** Requests per second one server can handle. */ - rpsEach: number; - /** Illustrative on-demand dollars per server per month. */ - monthlyEach: number; - /** Time to answer when the server is idle, in ms. */ - baseMs: number; - /** 1 means one Availability Zone, 2 means two. */ - zones: 1 | 2; - healthChecks: boolean; - autoscale: boolean; - /** Autoscaling keeps at least this many servers and at most scaleMax. */ - scaleMin: number; - scaleMax: number; - pricing: Pricing; - }; - db: { - kind: "rds" | "dynamodb"; - label: string; - /** Work units per second the primary can do. */ - capacity: number; - monthly: number; - replicas: number; - replicaMonthly: number; - /** A standby in a second zone. Costs about the same as the primary again. */ - multiAz: boolean; - pricing: "ondemand" | "reserved"; - /** Time for a read and for a write when idle, in ms. */ - readMs: number; - writeMs: number; - /** Work units one read uses (a missing index makes this big). */ - readCost: number; - /** 1 is an even spread. 4 means one hot key gets 4 times its fair share of work. */ - skew: number; - }; - cache: { on: boolean; /** Share of reads answered by the cache, 0 to 1. */ hit: number; monthly: number }; - cdn: { on: boolean; /** Share of static files served at the edge, 0 to 1. */ offload: number; monthly: number }; - queue: { on: boolean; monthly: number }; - /** Where the nightly batch job runs. Separate means spot workers away from the web tier. */ - batch: { separate: boolean; workersMonthly: number }; - net: { - /** GB per month leaving to the internet from the origin. */ - egressGb: number; - /** GB per month through the NAT gateway. */ - natGb: number; - /** Share of NAT traffic that is really S3 or DynamoDB traffic, 0 to 1. */ - s3Share: number; - /** A gateway VPC endpoint for S3 is in place. */ - s3Endpoint: boolean; - natGateways: number; - }; - logs: { gb: number; hotRate: number; coldRate: number; /** Share kept in cold storage, 0 to 1. */ coldShare: number }; -}; - -export type DeepPartial = { [K in keyof T]?: T[K] extends object ? DeepPartial : T[K] }; - -/** A change the player can apply. It is data: a patch merged onto the model. */ -export type ChangeDef = { - id: string; - label: string; - /** Plain English: what it does and why it helps (or what it costs). */ - description: string; - patch: DeepPartial; -}; - -export type Goals = { - /** The p95 request latency over the whole day must be at or below this, in ms. */ - maxP95Ms: number; - /** Share of requests that must succeed, in percent. */ - minAvailability: number; - /** Monthly bill must be at or below this, in dollars. */ - maxCostUsd: number; - /** Optional extras. */ - maxPeakAppUtil?: number; - maxPeakDbUtil?: number; -}; - -export type Stretch = { maxCostUsd?: number; maxP95Ms?: number }; - -export type ComponentId = "users" | "cdn" | "lb" | "app" | "cache" | "queue" | "db" | "replica" | "workers" | "storage" | "nat"; - +/** One production incident: a broken AWS system, the checks it must pass and a reference fix. */ export type SysdesignRound = RoundBase & { - /** Alarm text shown in the incident banner. */ - incident: string; - /** The system before the player changes anything. */ - model: Model; - /** Requests per second at each of the 24 steps. */ - traffic: number[]; - /** Share of requests that are static files, and share of dynamic requests that are reads. */ - mix: { staticShare: number; readShare: number }; - /** An Availability Zone fails during these steps (inclusive), if set. */ - outage?: { from: number; to: number }; - /** A batch job adds this load on the web tier and the database during these steps. */ - batchJob?: { from: number; to: number; appLoad: number; dbLoad: number }; - goals: Goals; - stretch: Stretch; - changes: ChangeDef[]; - maxChanges: number; - /** A change set that earns three stars. */ - solution: string[]; - /** A tempting change that does not help, or makes things worse. */ - trap?: string; - trapNote?: string; - /** Clues, from vague to clear. */ - hints: string[]; - /** The component to highlight as the problem. */ - focus: ComponentId; -}; - -export type SysdesignSubmission = { changes: string[] }; - -export type StepStatus = "ok" | "slow" | "down"; - -export type StepResult = { - t: number; - load: number; - appInstances: number; - /** Utilisation of each part, 0 upwards. Above 1 means it is overloaded. */ - appUtil: number; - dbUtil: number; - replicaUtil: number; - /** Share of requests that succeeded this step, 0 to 1. */ - success: number; - p95Ms: number; - status: StepStatus; - /** Share of requests lost before the app tier (dead zone or full servers), and share lost at the database, 0 to 1. */ - appDrop: number; - dbDrop: number; - zoneDown: boolean; - batchRunning: boolean; - /** Writes waiting in the queue after this step. */ - backlog: number; - /** Bill so far, in dollars per month (grows to the monthly total by the last step). */ - costToDate: number; -}; - -export type CostLine = { id: string; label: string; usd: number }; - -export type SimResult = { - model: Model; - steps: StepResult[]; - p95Ms: number; - /** Percent, 0 to 100. */ - availability: number; - costUsd: number; - costLines: CostLine[]; - peakAppUtil: number; - peakDbUtil: number; - peakBacklog: number; + /** The lab spec: starting board, allowed parts, challenge checks, hints and reference solution. */ + spec: HldLabSpec; }; -export type GoalCheck = { id: string; label: string; met: boolean; actual: string; target: string }; +/** What the player sends: the board they built. Positions do not matter. */ +export type SysdesignSubmission = { board: Board }; diff --git a/frontend/src/shared/lab/engine/catalog.ts b/frontend/src/shared/lab/engine/catalog.ts new file mode 100644 index 00000000..fd1aff11 --- /dev/null +++ b/frontend/src/shared/lab/engine/catalog.ts @@ -0,0 +1,437 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The shared component catalog for the lab platform. +// +// Every block a lab can use is described once here: its family (which course it +// belongs to), its role (what it does in a request path), its configurable +// properties (with range, default, unit and the panel group they show in), and +// the size catalogs its size pickers draw from. The board, the scoring model and +// the authoring validator all read this file. Links are allowed by role, so a new +// family (Kubernetes, Docker, Linux) is mostly new entries here, not new code. +// +// Prices and capacities are illustrative and dated (one region, on-demand, late +// 2026). Use them to compare the shapes of designs, not to quote a real bill. + +export type Family = "hld" | "aws" | "k8s" | "docker" | "linux"; +export const FAMILIES: readonly Family[] = ["hld", "aws", "k8s", "docker", "linux"]; + +export type Role = + | "client" + | "dns" + | "cdn" + | "firewall" + | "limiter" + | "balancer" + | "gateway" + | "compute" + | "function" + | "worker" + | "cache" + | "database" + | "nosql" + | "search" + | "queue" + | "stream" + | "storage"; + +export type ComponentKind = + // Generic building blocks for the high-level design course + | "client" + | "dns" + | "cdn" + | "waf" + | "rate-limiter" + | "load-balancer" + | "api-gateway" + | "app-server" + | "worker" + | "cache" + | "database" + | "nosql" + | "search" + | "queue" + | "stream" + | "object-storage" + // AWS services for the AWS course + | "aws-route53" + | "aws-cloudfront" + | "aws-waf" + | "aws-alb" + | "aws-nlb" + | "aws-api-gateway" + | "aws-ec2-asg" + | "aws-fargate" + | "aws-lambda" + | "aws-elasticache" + | "aws-rds" + | "aws-dynamodb" + | "aws-opensearch" + | "aws-sqs" + | "aws-kinesis" + | "aws-s3" + // Kubernetes objects for the Kubernetes course + | "k8s-ingress" + | "k8s-service" + | "k8s-deployment" + | "k8s-statefulset" + // Containers for the Docker course + | "docker-proxy" + | "docker-container" + | "docker-postgres" + // One host's services for the Linux course + | "linux-nginx" + | "linux-service" + | "linux-postgres"; + +export type PortDir = "in" | "out"; + +export interface PortDef { + id: string; + dir: PortDir; + accepts: ComponentKind[]; +} + +export type SizeSet = "generic" | "ec2" | "fargate" | "rds" | "elasticache" | "opensearch" | "pod" | "container" | "host"; +export type PropertyGroup = "Capacity" | "Scaling" | "Resilience" | "Behaviour"; + +export interface PropertyDef { + id: string; + label: string; + type: "size" | "count" | "ratio" | "enum" | "toggle"; + min?: number; + max?: number; + step?: number; + default: number | string; + unit: string; + options?: string[]; + /** Which size catalog a size picker draws from. */ + sizeSet?: SizeSet; + group?: PropertyGroup; + /** One line shown as a tooltip in the config panel. */ + help?: string; +} + +/** A managed, elastic service: priced per hour plus per million requests. */ +export interface ManagedPricing { + capacity: number; + pricePerHour: number; + pricePerMillion: number; +} + +export interface ComponentDef { + kind: ComponentKind; + label: string; + family: Family; + role: Role; + /** The product or engine name shown under the label. */ + vendor: string; + icon: string; + ports: PortDef[]; + properties: PropertyDef[]; + managed?: ManagedPricing; +} + +export interface SizeTier { + id: string; + set: SizeSet; + family: "general" | "compute" | "memory"; + vcpu: number; + memoryGb: number; + capacityRule: string; + pricePerHour: number; +} + +// Which role may send requests to which. Links follow the request, not the data. +const ROLE_NEXT: Record = { + client: ["dns", "cdn", "firewall", "limiter", "balancer", "gateway"], + dns: [], + cdn: ["firewall", "limiter", "balancer", "gateway", "compute", "storage"], + firewall: ["cdn", "limiter", "balancer", "gateway", "compute"], + limiter: ["balancer", "gateway", "compute", "function"], + balancer: ["balancer", "compute", "function"], + gateway: ["balancer", "compute", "function", "queue", "stream", "nosql", "storage"], + compute: ["function", "cache", "database", "nosql", "search", "queue", "stream", "storage"], + function: ["cache", "database", "nosql", "search", "queue", "stream", "storage"], + worker: ["cache", "database", "nosql", "search", "queue", "storage"], + queue: ["worker", "function"], + stream: ["worker", "function"], + // A cache may load from a database on a miss (read-through). Linking it is optional: + // an app server linked to both a cache and a database is cache-aside, with the same maths. + cache: ["database", "nosql"], + database: [], + nosql: [], + search: [], + storage: [], +}; + +// ---- property builders --------------------------------------------------- + +const size = (sizeSet: SizeSet, defaultId: string): PropertyDef => ({ + id: "size", + label: "Machine size", + type: "size", + sizeSet, + default: defaultId, + unit: "tier", + group: "Capacity", +}); +const count = (id: string, label: string, unit: string, def: number, min: number, max: number, group: PropertyGroup = "Capacity", help?: string): PropertyDef => ({ + id, label, type: "count", min, max, step: 1, default: def, unit, group, help, +}); +const ratio = (id: string, label: string, def: number, group: PropertyGroup = "Behaviour", help?: string): PropertyDef => ({ + id, label, type: "ratio", min: 0, max: 1, step: 0.05, default: def, unit: "fraction", group, help, +}); +const toggle = (id: string, label: string, def: 0 | 1, group: PropertyGroup, help?: string): PropertyDef => ({ + id, label, type: "toggle", default: def, unit: "on/off", group, help, +}); +const choice = (id: string, label: string, options: string[], def: string, group: PropertyGroup = "Behaviour", help?: string): PropertyDef => ({ + id, label, type: "enum", options, default: def, unit: "option", group, help, +}); +const azs = (def: number, min = 1): PropertyDef => + count("azs", "Zones (separate data centres)", "zones", def, min, 3, "Resilience", "Spreading across zones means one zone going down does not stop the service."); +const scaling = (on: 0 | 1, min: number, max: number, target: number): PropertyDef[] => [ + toggle("autoscale", "Add machines automatically (autoscaling)", on, "Scaling", "Adds or removes machines to stay near the target busyness."), + count("minCount", "Fewest machines", "machines", min, 1, 100, "Scaling"), + count("maxCount", "Most machines", "machines", max, 1, 200, "Scaling"), + ratio("targetUtil", "Aim to stay this busy (target utilisation)", target, "Scaling", "Add machines before this level. Waiting time starts to climb near 70% busy."), +]; + +// ---- the catalog ----------------------------------------------------------- + +type Entry = Omit; + +const ENTRIES: Record = { + // Generic high-level design blocks + client: { label: "Client", family: "hld", role: "client", vendor: "Users", icon: "client", + properties: [count("load", "Traffic sent (offered load)", "req/s", 1000, 1, 10_000_000)] }, + dns: { label: "DNS", family: "hld", role: "dns", vendor: "Resolver", icon: "dns", + managed: { capacity: 1_000_000, pricePerHour: 0.001, pricePerMillion: 0 }, + properties: [count("ttl", "Record TTL", "seconds", 300, 1, 86_400, "Behaviour")] }, + cdn: { label: "CDN", family: "hld", role: "cdn", vendor: "Edge cache", icon: "cdn", + managed: { capacity: 1_000_000, pricePerHour: 0.02, pricePerMillion: 0.75 }, + properties: [ratio("hitRate", "Answered nearby (edge hit rate)", 0.8, "Behaviour", "A hit is answered close to the user. Only misses reach your servers.")] }, + waf: { label: "Firewall", family: "hld", role: "firewall", vendor: "WAF", icon: "firewall", + managed: { capacity: 1_000_000, pricePerHour: 0.007, pricePerMillion: 0.6 }, + properties: [ratio("blockRate", "Blocked share", 0.02, "Behaviour", "Share of traffic dropped as malicious.")] }, + "rate-limiter": { label: "Rate limiter", family: "hld", role: "limiter", vendor: "Token bucket", icon: "limiter", + managed: { capacity: 1_000_000, pricePerHour: 0.01, pricePerMillion: 0 }, + properties: [count("limit", "Limit", "req/s", 5000, 10, 1_000_000, "Behaviour", "Requests above this are rejected, protecting what sits behind it.")] }, + "load-balancer": { label: "Load balancer", family: "hld", role: "balancer", vendor: "L7 LB", icon: "balancer", + properties: [size("generic", "general-small"), count("zones", "Zones (separate data centres)", "zones", 1, 1, 3, "Resilience")] }, + "api-gateway": { label: "API gateway", family: "hld", role: "gateway", vendor: "Gateway", icon: "gateway", + properties: [size("generic", "general-small"), count("count", "Machines (instances)", "machines", 2, 1, 50)] }, + "app-server": { label: "App server", family: "hld", role: "compute", vendor: "Compute", icon: "compute", + properties: [size("generic", "compute-small"), count("count", "Machines (instances)", "machines", 2, 1, 50), ...scaling(0, 2, 10, 0.6), azs(1)] }, + worker: { label: "Worker", family: "hld", role: "worker", vendor: "Consumer", icon: "worker", + properties: [size("generic", "compute-small"), count("count", "Workers", "workers", 2, 1, 100), count("batchSize", "Items saved per trip (batch size)", "events", 1, 1, 1000, "Behaviour", "How many items (clicks, posts, events) go to the store in one trip. Saving many at once turns thousands of writes a second into a few."), ...scaling(0, 1, 20, 0.7)] }, + cache: { label: "Cache", family: "hld", role: "cache", vendor: "Redis", icon: "cache", + properties: [size("generic", "memory-small"), count("count", "Machines (nodes)", "nodes", 1, 1, 20), ratio("hitRate", "Answered by the cache (hit rate)", 0.85, "Behaviour", "A hit means the database is never asked. A miss goes on to the database."), azs(1)] }, + database: { label: "Database", family: "hld", role: "database", vendor: "PostgreSQL", icon: "database", + properties: [ + size("generic", "memory-medium"), + count("replicas", "Read-only copies (read replicas)", "copies", 0, 0, 5, "Capacity", "Extra copies that share the reads. Every write still goes to the main copy (the primary)."), + ratio("readRatio", "Share that only reads", 0.8, "Behaviour", "Reads look data up. Writes change it."), + toggle("multiAz", "Extra copy that takes over (failover standby)", 0, "Resilience", "A standby copy in a second zone takes over if the main copy's zone fails. It doubles the main copy's cost."), + ] }, + nosql: { label: "NoSQL store", family: "hld", role: "nosql", vendor: "Key-value", icon: "nosql", + properties: [size("generic", "memory-medium"), count("count", "Machines (nodes)", "nodes", 3, 1, 30), azs(1)] }, + search: { label: "Search", family: "hld", role: "search", vendor: "Index", icon: "search", + properties: [size("generic", "memory-medium"), count("count", "Machines (nodes)", "nodes", 2, 1, 20), azs(1)] }, + queue: { label: "Queue", family: "hld", role: "queue", vendor: "Broker", icon: "queue", + managed: { capacity: 100_000, pricePerHour: 0.01, pricePerMillion: 0.04 }, + properties: [count("maxInFlight", "Most messages handled at once (max in flight)", "messages", 1000, 1, 1_000_000, "Behaviour")] }, + stream: { label: "Event stream", family: "hld", role: "stream", vendor: "Kafka", icon: "stream", + properties: [count("partitions", "Lanes (partitions)", "lanes", 4, 1, 256, "Capacity", "Each lane takes about 1,000 events a second."), count("retentionHours", "Keep events for (retention)", "hours", 24, 1, 8760, "Behaviour")] }, + "object-storage": { label: "Object storage", family: "hld", role: "storage", vendor: "Blob store", icon: "storage", + managed: { capacity: 1_000_000, pricePerHour: 0.01, pricePerMillion: 0.4 }, + properties: [count("capacityGb", "Capacity", "GB", 100, 1, 1_000_000)] }, + + // AWS services + "aws-route53": { label: "Route 53", family: "aws", role: "dns", vendor: "AWS DNS", icon: "dns", + managed: { capacity: 1_000_000, pricePerHour: 0.0007, pricePerMillion: 0 }, + properties: [choice("routing", "Routing policy", ["simple", "latency", "failover", "weighted"], "simple")] }, + "aws-cloudfront": { label: "CloudFront", family: "aws", role: "cdn", vendor: "AWS CDN", icon: "cdn", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.75 }, + properties: [ratio("hitRate", "Cache hit rate", 0.85), choice("priceClass", "Price class", ["100", "200", "All"], "100")] }, + "aws-waf": { label: "AWS WAF", family: "aws", role: "firewall", vendor: "Web ACL", icon: "firewall", + managed: { capacity: 1_000_000, pricePerHour: 0.007, pricePerMillion: 0.6 }, + properties: [ratio("blockRate", "Blocked share", 0.02), count("rules", "Rules", "rules", 10, 1, 100, "Behaviour")] }, + "aws-alb": { label: "ALB", family: "aws", role: "balancer", vendor: "Application LB", icon: "balancer", + managed: { capacity: 100_000, pricePerHour: 0.0225, pricePerMillion: 0.2 }, + properties: [azs(2, 2), toggle("crossZone", "Cross-zone balancing", 1, "Resilience")] }, + "aws-nlb": { label: "NLB", family: "aws", role: "balancer", vendor: "Network LB", icon: "balancer", + managed: { capacity: 200_000, pricePerHour: 0.0225, pricePerMillion: 0.1 }, + properties: [azs(2, 1)] }, + "aws-api-gateway": { label: "API Gateway", family: "aws", role: "gateway", vendor: "AWS API Gateway", icon: "gateway", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 1 }, + properties: [ + choice("apiType", "API type", ["HTTP", "REST"], "HTTP", "Behaviour", "REST APIs cost about 3.5 times more per request."), + count("limit", "Throttle", "req/s", 10_000, 10, 100_000, "Behaviour", "Account throttle; requests above it get 429 errors."), + ] }, + "aws-ec2-asg": { label: "EC2 Auto Scaling", family: "aws", role: "compute", vendor: "EC2", icon: "compute", + properties: [size("ec2", "m5.large"), count("count", "Desired instances", "instances", 2, 1, 200), ...scaling(1, 2, 10, 0.5), azs(2)] }, + "aws-fargate": { label: "ECS Fargate", family: "aws", role: "compute", vendor: "Containers", icon: "compute", + properties: [size("fargate", "1 vCPU / 2 GB"), count("count", "Tasks", "tasks", 2, 1, 500), ...scaling(1, 2, 20, 0.6), azs(2)] }, + "aws-lambda": { label: "Lambda", family: "aws", role: "function", vendor: "Serverless", icon: "function", + properties: [ + choice("memoryMb", "Memory", ["128", "256", "512", "1024", "2048"], "512", "Capacity", "More memory also means more CPU and a higher GB-second price."), + count("durationMs", "Duration", "ms", 120, 1, 900_000, "Behaviour"), + count("concurrency", "Reserved concurrency", "executions", 1000, 1, 10_000, "Capacity", "Concurrency divided by duration is the most it can serve; beyond that it throttles."), + ] }, + "aws-elasticache": { label: "ElastiCache", family: "aws", role: "cache", vendor: "Redis", icon: "cache", + properties: [size("elasticache", "cache.r6g.large"), count("count", "Shards", "shards", 1, 1, 50), count("replicasPerShard", "Replicas per shard", "replicas", 1, 0, 5, "Resilience"), ratio("hitRate", "Hit rate", 0.85), azs(2)] }, + "aws-rds": { label: "RDS", family: "aws", role: "database", vendor: "Managed SQL", icon: "database", + properties: [ + choice("engine", "Engine", ["PostgreSQL", "MySQL"], "PostgreSQL", "Behaviour"), + size("rds", "db.r5.large"), + count("replicas", "Read replicas", "replicas", 1, 0, 15, "Capacity", "Replicas share the reads; every write still goes to the primary."), + ratio("readRatio", "Read share", 0.8), + toggle("multiAz", "Multi-AZ", 1, "Resilience", "A synchronous standby in another zone. Doubles the primary cost."), + ] }, + "aws-dynamodb": { label: "DynamoDB", family: "aws", role: "nosql", vendor: "Key-value", icon: "nosql", + managed: { capacity: 40_000, pricePerHour: 0, pricePerMillion: 0 }, + properties: [ + choice("capacityMode", "Capacity mode", ["on-demand", "provisioned"], "on-demand", "Capacity", "On-demand bills per request; provisioned bills per hour for the units you reserve."), + count("rcu", "Read units", "RCU", 1000, 1, 100_000, "Capacity"), + count("wcu", "Write units", "WCU", 500, 1, 100_000, "Capacity"), + ratio("readRatio", "Read share", 0.8), + ] }, + "aws-opensearch": { label: "OpenSearch", family: "aws", role: "search", vendor: "Search", icon: "search", + properties: [size("opensearch", "m5.large.search"), count("count", "Data nodes", "nodes", 2, 1, 40), azs(2)] }, + "aws-sqs": { label: "SQS", family: "aws", role: "queue", vendor: "AWS queue", icon: "queue", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.4 }, + properties: [choice("queueType", "Queue type", ["standard", "FIFO"], "standard", "Behaviour", "FIFO keeps order but tops out near 3,000 messages/s with batching.")] }, + "aws-kinesis": { label: "Kinesis", family: "aws", role: "stream", vendor: "Data Streams", icon: "stream", + properties: [count("partitions", "Shards", "shards", 2, 1, 500, "Capacity", "Each shard takes about 1,000 records/s."), count("retentionHours", "Retention", "hours", 24, 24, 8760, "Behaviour")] }, + "aws-s3": { label: "S3", family: "aws", role: "storage", vendor: "Object storage", icon: "storage", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.4 }, + properties: [choice("storageClass", "Storage class", ["Standard", "Intelligent-Tiering", "Glacier IR"], "Standard")] }, + + // Kubernetes + "k8s-ingress": { label: "Ingress", family: "k8s", role: "balancer", vendor: "ingress-nginx", icon: "balancer", + properties: [size("pod", "500m / 512Mi"), count("count", "Controller replicas", "pods", 2, 1, 20), azs(1)] }, + "k8s-service": { label: "Service", family: "k8s", role: "balancer", vendor: "ClusterIP", icon: "balancer", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0 }, + properties: [choice("serviceType", "Type", ["ClusterIP", "NodePort", "LoadBalancer"], "ClusterIP", "Behaviour", "A LoadBalancer Service also rents a cloud load balancer.")] }, + "k8s-deployment": { label: "Deployment", family: "k8s", role: "compute", vendor: "Pods", icon: "compute", + properties: [size("pod", "500m / 512Mi"), count("count", "Replicas", "pods", 2, 1, 200), ...scaling(1, 2, 10, 0.6), azs(1)] }, + "k8s-statefulset": { label: "StatefulSet", family: "k8s", role: "database", vendor: "PostgreSQL", icon: "database", + properties: [size("pod", "2 CPU / 4Gi"), count("replicas", "Read replicas", "pods", 0, 0, 5), ratio("readRatio", "Read share", 0.8)] }, + + // Docker + "docker-proxy": { label: "Reverse proxy", family: "docker", role: "balancer", vendor: "Traefik", icon: "balancer", + properties: [size("container", "1 CPU / 1GB"), count("count", "Containers", "containers", 1, 1, 10)] }, + "docker-container": { label: "App container", family: "docker", role: "compute", vendor: "Container", icon: "compute", + properties: [size("container", "1 CPU / 1GB"), count("count", "Replicas", "containers", 1, 1, 20)] }, + "docker-postgres": { label: "Postgres", family: "docker", role: "database", vendor: "postgres:16", icon: "database", + properties: [size("container", "2 CPU / 2GB"), count("replicas", "Read replicas", "containers", 0, 0, 3), ratio("readRatio", "Read share", 0.8)] }, + + // Linux, one host + "linux-nginx": { label: "nginx", family: "linux", role: "balancer", vendor: "Reverse proxy", icon: "balancer", + properties: [size("host", "2 cores / 4GB")] }, + "linux-service": { label: "App service", family: "linux", role: "compute", vendor: "systemd", icon: "compute", + properties: [size("host", "2 cores / 4GB"), count("count", "Hosts", "hosts", 1, 1, 10)] }, + "linux-postgres": { label: "PostgreSQL", family: "linux", role: "database", vendor: "postgresql.service", icon: "database", + properties: [size("host", "4 cores / 8GB"), count("replicas", "Read replicas", "hosts", 0, 0, 3), ratio("readRatio", "Read share", 0.8)] }, +}; + +const COMPONENT_KINDS = Object.keys(ENTRIES) as ComponentKind[]; +const KIND_SET = new Set(COMPONENT_KINDS); + +export function isComponentKind(value: string): value is ComponentKind { + return KIND_SET.has(value); +} + +export function roleOf(kind: ComponentKind): Role { + return ENTRIES[kind].role; +} + +function portsFor(kind: ComponentKind): PortDef[] { + const role = ENTRIES[kind].role; + const inbound = COMPONENT_KINDS.filter((k) => ROLE_NEXT[ENTRIES[k].role].includes(role)); + const outbound = COMPONENT_KINDS.filter((k) => ROLE_NEXT[role].includes(ENTRIES[k].role)); + const ports: PortDef[] = []; + if (inbound.length > 0) ports.push({ id: "in", dir: "in", accepts: inbound }); + if (outbound.length > 0) ports.push({ id: "out", dir: "out", accepts: outbound }); + return ports; +} + +export const COMPONENT_CATALOG: Record = Object.fromEntries( + COMPONENT_KINDS.map((kind) => [kind, { kind, ...ENTRIES[kind], ports: portsFor(kind) }]), +) as Record; + +export function canConnect(from: ComponentKind, to: ComponentKind): boolean { + return ROLE_NEXT[ENTRIES[from].role].includes(ENTRIES[to].role); +} + +export function kindsInFamily(family: Family): ComponentKind[] { + return COMPONENT_KINDS.filter((k) => ENTRIES[k].family === family); +} + +// ---- size catalogs ----------------------------------------------------------- + +const GENERIC_RULE = { general: "~800 req/s per vCPU at a light mix", compute: "~1,200 req/s per vCPU at a CPU-bound mix", memory: "~600 req/s per vCPU; holds a large working set" }; +const tier = (set: SizeSet, id: string, family: SizeTier["family"], vcpu: number, memoryGb: number, pricePerHour: number, capacityRule = GENERIC_RULE[family]): SizeTier => ({ + id, set, family, vcpu, memoryGb, capacityRule, pricePerHour, +}); + +export const SIZE_CATALOG: SizeTier[] = [ + tier("generic", "general-small", "general", 2, 8, 0.1), + tier("generic", "general-medium", "general", 4, 16, 0.2), + tier("generic", "general-large", "general", 8, 32, 0.4), + tier("generic", "general-xlarge", "general", 16, 64, 0.8), + tier("generic", "compute-small", "compute", 2, 4, 0.12), + tier("generic", "compute-medium", "compute", 4, 8, 0.24), + tier("generic", "compute-large", "compute", 8, 16, 0.48), + tier("generic", "compute-xlarge", "compute", 16, 32, 0.96), + tier("generic", "memory-small", "memory", 2, 16, 0.15), + tier("generic", "memory-medium", "memory", 4, 32, 0.3), + tier("generic", "memory-large", "memory", 8, 64, 0.6), + tier("generic", "memory-xlarge", "memory", 16, 128, 1.2), + + tier("ec2", "t3.medium", "general", 2, 4, 0.0416, "burstable; ~800 req/s per vCPU while it has credits"), + tier("ec2", "m5.large", "general", 2, 8, 0.096), + tier("ec2", "m5.xlarge", "general", 4, 16, 0.192), + tier("ec2", "c5.large", "compute", 2, 4, 0.085), + tier("ec2", "c5.xlarge", "compute", 4, 8, 0.17), + tier("ec2", "c5.2xlarge", "compute", 8, 16, 0.34), + tier("ec2", "r5.large", "memory", 2, 16, 0.126), + + tier("fargate", "0.25 vCPU / 0.5 GB", "general", 0.25, 0.5, 0.0123), + tier("fargate", "0.5 vCPU / 1 GB", "general", 0.5, 1, 0.0247), + tier("fargate", "1 vCPU / 2 GB", "general", 1, 2, 0.0494), + tier("fargate", "2 vCPU / 4 GB", "general", 2, 4, 0.0988), + tier("fargate", "4 vCPU / 8 GB", "general", 4, 8, 0.1975), + + tier("rds", "db.t3.medium", "memory", 2, 4, 0.068), + tier("rds", "db.m5.large", "memory", 2, 8, 0.171), + tier("rds", "db.r5.large", "memory", 2, 16, 0.24), + tier("rds", "db.r5.xlarge", "memory", 4, 32, 0.48), + tier("rds", "db.r5.2xlarge", "memory", 8, 64, 0.96), + + tier("elasticache", "cache.t3.small", "memory", 2, 1.37, 0.034, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.m5.large", "memory", 2, 6.38, 0.156, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.r6g.large", "memory", 2, 13.07, 0.206, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.r6g.xlarge", "memory", 4, 26.32, 0.411, "~15,000 ops/s per vCPU"), + + tier("opensearch", "t3.medium.search", "memory", 2, 4, 0.073, "~300 queries/s per vCPU"), + tier("opensearch", "m5.large.search", "memory", 2, 8, 0.142, "~300 queries/s per vCPU"), + tier("opensearch", "r5.large.search", "memory", 2, 16, 0.186, "~300 queries/s per vCPU"), + + tier("pod", "250m / 256Mi", "general", 0.25, 0.25, 0.01, "CPU request; ~800 req/s per full core"), + tier("pod", "500m / 512Mi", "general", 0.5, 0.5, 0.02, "CPU request; ~800 req/s per full core"), + tier("pod", "1 CPU / 1Gi", "general", 1, 1, 0.04, "CPU request; ~800 req/s per full core"), + tier("pod", "2 CPU / 4Gi", "general", 2, 4, 0.09, "CPU request; ~800 req/s per full core"), + + tier("container", "0.5 CPU / 512MB", "general", 0.5, 0.5, 0.02, "--cpus limit; ~800 req/s per full core"), + tier("container", "1 CPU / 1GB", "general", 1, 1, 0.04, "--cpus limit; ~800 req/s per full core"), + tier("container", "2 CPU / 2GB", "general", 2, 2, 0.08, "--cpus limit; ~800 req/s per full core"), + + tier("host", "1 core / 2GB", "general", 1, 2, 0.02, "~800 req/s per core"), + tier("host", "2 cores / 4GB", "general", 2, 4, 0.04, "~800 req/s per core"), + tier("host", "4 cores / 8GB", "general", 4, 8, 0.08, "~800 req/s per core"), + tier("host", "8 cores / 16GB", "general", 8, 16, 0.16, "~800 req/s per core"), +]; + +export function sizesFor(set: SizeSet): SizeTier[] { + return SIZE_CATALOG.filter((t) => t.set === set); +} diff --git a/frontend/src/shared/lab/engine/challenge.ts b/frontend/src/shared/lab/engine/challenge.ts new file mode 100644 index 00000000..d4c10e23 --- /dev/null +++ b/frontend/src/shared/lab/engine/challenge.ts @@ -0,0 +1,291 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The run behind a visual challenge: pure and server-importable like the model it +// wraps. It takes a board and plays it through the challenge's scenarios (peak +// traffic, then each fault), asks the tiered-architecture model for the numbers in +// every one, and turns them into a pass or fail per check, each with the measured +// value, the target and, when it fails, the reason. +// +// Functional checks are about structure: can a request travel the path the feature +// needs? Non-functional checks are measurements: latency, how much is still served +// when something dies, whether queued work is all counted, and cost. + +import type { Board, BoardNode, ChallengeDef, ChallengeScenario, CheckDef, CheckMetric, Fault, HldLabSpec } from "./hld-types"; +import type { ComponentKind, Role } from "./catalog"; +import { COMPONENT_CATALOG, roleOf } from "./catalog"; +import { runTieredModel, type ModelOptions, type ModelResult, type Targets, type TierLoad } from "./tiered-architecture"; + +export const STEADY: ChallengeScenario = { + id: "steady", + title: "Peak traffic", + story: "Everything is healthy and traffic is at its busiest.", + faults: [], +}; + +export interface CheckResult { + id: string; + kind: "functional" | "non-functional"; + label: string; + pass: boolean; + /** What the run found, with its unit. */ + measured: string; + /** What it had to be. */ + target: string; + /** Why it failed and what to look at; absent when it passed. */ + reason?: string; + /** The scenario the number comes from, so the board can replay it. */ + scenario: string; +} + +export interface PhaseReport { + id: string; + title: string; + story: string; + load: number; + /** The board as the scenario left it (fault applied). */ + board: Board; + /** The components the fault took down or thinned out. */ + hit: string[]; + /** False when the fault named a part this design does not have. */ + applicable: boolean; + /** The part the fault names when the design has none: "cache". */ + missing?: string; + result: ModelResult; +} + +export interface ChallengeReport { + phases: PhaseReport[]; + checks: CheckResult[]; + passed: number; + total: number; + allPass: boolean; +} + +const labelOf = (kind: ComponentKind) => COMPONENT_CATALOG[kind].label; +// Lowercases the first letter of a label for use mid-sentence, but leaves acronyms such as CDN alone. +const lower = (text: string) => (/^[A-Z]{2}/.test(text) ? text : text.charAt(0).toLowerCase() + text.slice(1)); +const pct = (n: number) => `${(Math.floor(n * 10000) / 100).toFixed(2)}%`; +const roleLabel = (role: Role) => Object.values(COMPONENT_CATALOG).find((c) => c.role === role)?.label ?? role; +const perSec = (n: number) => `${Math.round(n).toLocaleString("en-US")}/s`; + +function metricText(metric: CheckMetric, v: number): string { + switch (metric) { + case "p99": return `${Math.round(v)} ms`; + case "capacity": return perSec(v); + case "served": return `${(Math.floor(v * 1000) / 10).toFixed(1)}%`; + case "availability": return pct(v); + case "cost": return `$${v.toFixed(2)}/h`; + } +} +const targetText = (metric: CheckMetric, op: "<=" | ">=", v: number) => + `${op === "<=" ? "at most" : "at least"} ${metric === "availability" ? pct(v) : metricText(metric, v)}`; + +// ---- faults ------------------------------------------------------------------- + +function applyFaults(board: Board, faults: Fault[], steady: ModelResult): { board: Board; hit: string[]; applicable: boolean } { + const nodes: BoardNode[] = board.nodes.map((n) => ({ ...n, props: { ...(n.props ?? {}) } })); + const hit: string[] = []; + for (const fault of faults) { + const targets = nodes.filter((n) => roleOf(n.kind) === fault.role); + if (targets.length === 0) continue; + if (fault.type === "down") { + for (const n of targets) { n.props!.down = 1; hit.push(n.id); } + } else { + const first = targets[0]!; + const units = steady.tiers.find((t) => t.id === first.id)?.units ?? 1; + if (units <= 1) first.props!.down = 1; + else { first.props!.autoscale = 0; first.props!.count = units - 1; } + hit.push(first.id); + } + } + return { board: { ...board, nodes }, hit, applicable: hit.length > 0 }; +} + +// ---- functional checks: can a request travel the path? --------------------------- + +function reachFrom(board: Board, starts: string[]): Set { + const next = new Map(); + for (const e of board.edges) next.set(e.from, [...(next.get(e.from) ?? []), e.to]); + const seen = new Set(); + const queue = [...starts]; + while (queue.length > 0) { + const id = queue.shift()!; + for (const to of next.get(id) ?? []) if (!seen.has(to)) { seen.add(to); queue.push(to); } + } + return seen; +} + +/** Walks the roles in order. Returns the labels found so far and the first role that has no way in. */ +export function followChain(board: Board, chain: Role[]): { trail: string[]; missing?: Role } { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + let frontier = board.nodes.filter((n) => roleOf(n.kind) === chain[0] && !n.props?.down).map((n) => n.id); + const trail: string[] = frontier.length > 0 ? [labelOf(byId.get(frontier[0]!)!.kind)] : []; + if (frontier.length === 0) return { trail, missing: chain[0] }; + for (const role of chain.slice(1)) { + const reached = reachFrom(board, frontier); + frontier = [...reached].filter((id) => roleOf(byId.get(id)!.kind) === role && !byId.get(id)!.props?.down); + if (frontier.length === 0) return { trail, missing: role }; + trail.push(labelOf(byId.get(frontier[0]!)!.kind)); + } + return { trail }; +} + +const ROLE_NAME: Partial> = { + client: "a client", compute: "an app server", database: "a database", queue: "a queue", worker: "a worker", cache: "a cache", balancer: "a load balancer", +}; +const roleName = (role: Role) => ROLE_NAME[role] ?? `a ${role}`; + +function pathCheck(def: Extract, board: Board): CheckResult { + const { trail, missing } = followChain(board, def.chain); + if (missing !== undefined && def.inlineIfNo && !board.nodes.some((n) => roleOf(n.kind) === def.inlineIfNo)) { + return { + id: def.id, kind: def.kind, label: def.label, pass: true, scenario: "steady", target: def.target, + measured: `saved during the request (inline), no ${lower(roleLabel(def.inlineIfNo))}`, + }; + } + const pass = missing === undefined; + const last = trail.at(-1); + return { + id: def.id, kind: def.kind, label: def.label, pass, scenario: "steady", target: def.target, + measured: pass ? trail.join(" > ") : trail.length > 0 ? `${trail.join(" > ")} > ?` : "no path", + reason: pass ? undefined : trail.length === 0 + ? `There is no ${missing === "client" ? "client" : roleName(missing!).replace(/^an? /, "")} on the board.` + : `The path stops at ${lower(last!)}: link it to ${roleName(missing!)}.`, + }; +} + +// ---- non-functional checks: measured in a scenario --------------------------------- + +function worstTier(result: ModelResult): TierLoad | undefined { + return [...result.tiers].filter((t) => t.reachable && !t.managed).sort((a, b) => b.utilisation - a.utilisation)[0]; +} +const busy = (t: TierLoad) => `${labelOf(t.kind)} is ${Math.round(t.utilisation * 100)}% busy`; + +function measure(metric: CheckMetric, r: ModelResult, load: number): number { + switch (metric) { + case "p99": return r.p99Ms; + case "capacity": return r.capacityCeiling; + case "served": return load > 0 ? Math.min(1, r.capacityCeiling / load) : 1; + case "availability": return r.availability; + case "cost": return r.costPerHour; + } +} + +function whyMetricFailed(metric: CheckMetric, r: ModelResult, scenario: PhaseReport): string { + const worst = worstTier(r); + const during = scenario.id === "steady" ? "" : ` while ${lower(scenario.title)}`; + if (r.failure) return r.failure; + switch (metric) { + case "p99": { + const slow = [...r.tiers].filter((t) => t.waitMs > 0.5).sort((x, y) => y.waitMs - x.waitMs).slice(0, 2); + return slow.length > 0 + ? `Requests wait in line at ${slow.map((t) => `the ${lower(labelOf(t.kind))} (${Math.round(t.utilisation * 100)}% busy, +${Math.round(t.waitMs)} ms)`).join(" and ")}${during}. Give them more capacity, or take load off them.` + : "The path itself is too slow: fewer hops would help."; + } + case "capacity": + case "served": + return worst ? `${busy(worst)}${during}, so it cannot serve the whole load. Add machines, read-only copies or a cache in front of it.` : "Nothing on the board can serve the load."; + case "availability": { + const role = r.weakest?.role; + return role ? `${roleLabel(role)} is the weak link (${pct(r.weakest!.availability)}): run more than one, or in two zones.` : "Add redundancy."; + } + case "cost": { + const priciest = [...r.tiers].sort((a, b) => b.cost - a.cost)[0]; + return priciest ? `${labelOf(priciest.kind)} costs the most ($${priciest.cost.toFixed(2)}/h). Try a smaller size or fewer machines.` : "Over budget."; + } + } +} + +function metricCheck(def: Extract, phases: Map): CheckResult { + const phase = phases.get(def.scenario) ?? phases.get("steady")!; + const value = measure(def.metric, phase.result, phase.load); + const pass = def.op === "<=" ? value <= def.value : value >= def.value; + return { + id: def.id, kind: def.kind, label: def.label, pass, scenario: phase.id, + measured: metricText(def.metric, value) + (phase.applicable || phase.id === "steady" ? "" : ` (no ${phase.missing} to lose)`), + target: targetText(def.metric, def.op, def.value), + reason: pass ? undefined : whyMetricFailed(def.metric, phase.result, phase), + }; +} + +function drainCheck(def: Extract, steady: PhaseReport, scenarioId: string, inlineClicks: boolean, share = 1): CheckResult { + const { board, result, load } = steady; + const queue = board.nodes.find((n) => roleOf(n.kind) === "queue" && result.tiers.find((t) => t.id === n.id)?.reachable); + const items = def.items ?? "clicks"; + const done = def.done ?? "counted"; + const Items = items.charAt(0).toUpperCase() + items.slice(1); + const target = `no ${items} lost, all ${done} within ${def.maxDrainSeconds} s of the worker coming back`; + const base = { id: def.id, kind: def.kind, label: def.label, scenario: scenarioId, target }; + if (!queue && inlineClicks && !board.nodes.some((n) => roleOf(n.kind) === "queue")) { + return { ...base, pass: true, measured: `no worker to lose: ${items} are saved during the request (inline)` }; + } + if (!queue) { + // With no queue there is no link to read the rate from, so take the queue's share of the stream. + const lost = Math.round(load * share * def.outageSeconds); + return { ...base, pass: false, measured: `${lost.toLocaleString("en-US")} ${items} lost in ${def.outageSeconds} s`, reason: `${Items} have nowhere to wait while the worker is down. Put a queue between the app server and the worker.` }; + } + const workers = board.edges.filter((e) => e.from === queue.id).map((e) => result.tiers.find((t) => t.id === e.to)).filter((t): t is TierLoad => !!t && roleOf(t.kind) === "worker"); + if (workers.length === 0) { + return { ...base, pass: false, measured: `${items} pile up and are never ${done}`, reason: "The queue has no worker. Link the queue to a worker, and the worker to where it saves its work." }; + } + const arriving = board.edges.filter((e) => e.to === queue.id).reduce((sum, e) => sum + (result.edgeFlows[`${e.from}>${e.to}`] ?? 0), 0); + const capacity = workers.reduce((sum, w) => sum + w.capacity, 0); + const spare = capacity - arriving; + const backlog = Math.round(arriving * def.outageSeconds); + if (spare <= 0) { + return { ...base, pass: false, measured: `${backlog.toLocaleString("en-US")} ${items} waiting, never all ${done}`, reason: `Workers handle ${perSec(capacity)} but ${items} arrive at ${perSec(arriving)}: they can never catch up. Add workers or a bigger size.` }; + } + const drain = Math.ceil(backlog / spare); + const pass = drain <= def.maxDrainSeconds; + return { + ...base, pass, measured: `${backlog.toLocaleString("en-US")} ${items} waiting, all ${done} after ${drain} s`, + reason: pass ? undefined : `Workers have only ${perSec(spare)} to spare, so ${backlog.toLocaleString("en-US")} waiting ${items} take ${drain} s. Add workers or a bigger size.`, + }; +} + +// ---- the run ---------------------------------------------------------------------- + +/** Labs with no authored challenge are scored on their targets, as non-functional checks. */ +export function challengeFor(spec: HldLabSpec): ChallengeDef { + if (spec.challenge) return spec.challenge; + const level = spec.levels[0]; + const t = level?.targets ?? {}; + const checks: CheckDef[] = []; + const add = (id: string, label: string, metric: CheckMetric, op: "<=" | ">=", value?: number) => { + if (value != null) checks.push({ type: "metric", id, kind: "non-functional", label, scenario: "steady", metric, op, value }); + }; + add("capacity", "Serves the load", "capacity", ">=", t.rps); + add("p99", "Slowest 1 in 100 requests (p99)", "p99", "<=", t.p99Ms); + add("availability", "Stays up (availability)", "availability", ">=", t.availability); + add("cost", "Cost per hour", "cost", "<=", t.budgetPerHour); + return { peakLoad: level?.load ?? 1000, scenarios: [], checks }; +} + +/** The model run for a lab: the same options the challenge's own scenarios use, so every number agrees. */ +export function runModel(spec: HldLabSpec, board: Board, load: number, targets: Targets = {}): ModelResult { + const options: ModelOptions = { + inlineWrites: Boolean(spec.challenge?.inlineClicks) && !board.nodes.some((n) => roleOf(n.kind) === "queue"), + shares: spec.challenge?.shares, + }; + return runTieredModel(board, load, targets, options); +} + +/** Plays the board through the challenge. `board` must already carry the learner's properties. */ +export function runChallenge(spec: HldLabSpec, board: Board, load: number): ChallengeReport { + const challenge = challengeFor(spec); + const steadyResult = runModel(spec, board, load); + const phases: PhaseReport[] = [{ ...STEADY, load, board, hit: [], applicable: true, result: steadyResult }]; + for (const scenario of challenge.scenarios) { + const { board: faulted, hit, applicable } = applyFaults(board, scenario.faults, steadyResult); + const missing = applicable ? undefined : lower(roleLabel(scenario.faults[0]?.role ?? "compute")); + phases.push({ id: scenario.id, title: scenario.title, story: scenario.story, load, board: faulted, hit, applicable, missing, result: runModel(spec, faulted, load) }); + } + const byId = new Map(phases.map((p) => [p.id, p])); + const steady = phases[0]!; + const checks: CheckResult[] = challenge.checks.map((def) => { + if (def.type === "path") return pathCheck(def, board); + if (def.type === "drain") return drainCheck(def, steady, challenge.scenarios.find((s) => s.faults.some((f) => f.type === "down" && f.role === "worker"))?.id ?? "steady", Boolean(challenge.inlineClicks), challenge.shares?.queue ?? 1); + return metricCheck(def, byId); + }); + const passed = checks.filter((c) => c.pass).length; + return { phases, checks, passed, total: checks.length, allPass: passed === checks.length }; +} diff --git a/frontend/src/shared/lab/engine/hld-types.ts b/frontend/src/shared/lab/engine/hld-types.ts new file mode 100644 index 00000000..7ffcb2a4 --- /dev/null +++ b/frontend/src/shared/lab/engine/hld-types.ts @@ -0,0 +1,144 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The pure data shapes of a high-level design (HLD) lab: the board, the challenge, the +// reference solution and the HLD spec. No UI and no network imports, so the server can +// replay a design with the same types the lab board uses. + +import type { ComponentKind, Role } from "./catalog"; + +export type LabFamily = "hld" | "db" | "net"; + +export interface BoardNode { + id: string; + kind: ComponentKind; + x: number; + y: number; + props?: Record; +} + +export interface BoardEdge { + from: string; + to: string; + /** Which dot each end uses (t, r, b, l); the board picks bottom to top when absent. */ + via?: [string, string]; +} + +export interface Board { + nodes: BoardNode[]; + edges: BoardEdge[]; +} + +export interface LabLevel { + id: string; + load: number; + targets: { rps?: number; p99Ms?: number; availability?: number; budgetPerHour?: number }; + event?: string; +} + +// ---- challenge: the checks a visual lab's Run puts the design through ---------- + +/** Something that goes wrong in a scenario. */ +export type Fault = + /** One instance of the first component with this role dies; a fleet of one dies whole. */ + | { type: "lose-instance"; role: Role } + /** Every component with this role goes down. */ + | { type: "down"; role: Role }; + +export interface ChallengeScenario { + id: string; + /** Short name, shown on the run strip: "The cache dies". */ + title: string; + /** One line shown while this phase plays. */ + story: string; + faults: Fault[]; +} + +export type CheckMetric = "p99" | "capacity" | "served" | "availability" | "cost"; + +interface CheckBase { + id: string; + kind: "functional" | "non-functional"; + label: string; +} + +export type CheckDef = + /** A functional check: a request can travel client -> ... -> the next role, in order. */ + | (CheckBase & { + type: "path"; + chain: Role[]; + target: string; + /** A design with no component of this role passes without the chain: the work is done inline instead. */ + inlineIfNo?: Role; + }) + /** A measured check: one number from one scenario against a limit. */ + | (CheckBase & { type: "metric"; scenario: string; metric: CheckMetric; op: "<=" | ">="; value: number }) + /** Work queued while its consumer is down must be fully counted once it is back. */ + | (CheckBase & { + type: "drain"; + outageSeconds: number; + maxDrainSeconds: number; + /** What waits in the queue, plural: "clicks" (the default), "posts", "messages". */ + items?: string; + /** What happens to each item once a worker takes it: "counted" (the default), "delivered", "saved". */ + done?: string; + }); + +export interface ChallengeDef { + /** Requests a second at the busiest moment; every scenario runs at this load. */ + peakLoad: number; + /** + * With no queue on the board, each request writes its click to the database before it + * answers, so counting works but costs a database write per request. + */ + inlineClicks?: boolean; + /** + * The share of requests that send work to parts of a role, for side jobs only some + * requests need: { queue: 0.1 } means 1 request in 10 leaves a job in the queue. + * Each share is above 0 and at most 1; a role with no share gets the whole stream. + */ + shares?: Partial>; + scenarios: ChallengeScenario[]; + checks: CheckDef[]; +} + +// ---- solution: a reference design a learner can open and compare with ---------- + +/** Why one part is in the reference design. */ +export interface SolutionPart { + /** Plain words: what this part does in the design. */ + why: string; + /** Ids of the checks this part helps pass. */ + checks: string[]; + /** What goes wrong without it, with numbers from the model. */ + without: string; +} + +export interface SolutionDef { + /** The reference design. It must pass every check of the lab. */ + board: Board; + /** One or two plain sentences: the idea behind the design. */ + summary: string; + /** Keyed by node id in `board`. */ + parts: Record; +} + +export interface LabBase { + slug: string; + family: LabFamily; + title: string; + purpose: string; + limits: string; + hints: string[]; + referenceSlug?: string; +} + +export interface HldLabSpec extends LabBase { + family: "hld"; + allowedComponents: ComponentKind[]; + startingBoard?: Board; + scenario: string; + levels: LabLevel[]; + /** A visual challenge: functional and non-functional checks and the scenarios that test them. */ + challenge?: ChallengeDef; + /** A reference design the learner can open after pressing Run, and compare with their own. */ + solution?: SolutionDef; +} diff --git a/frontend/src/shared/lab/engine/tiered-architecture.ts b/frontend/src/shared/lab/engine/tiered-architecture.ts new file mode 100644 index 00000000..d3e8152a --- /dev/null +++ b/frontend/src/shared/lab/engine/tiered-architecture.ts @@ -0,0 +1,538 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The tiered-architecture model: the engine behind the lab board. Pure and +// server-importable (no DOM, no React), so a graded lab can run it on the server. +// +// From a board and an offered load it routes requests down the links, evaluates +// every component by its role and configuration (instance fleets, autoscaling, +// zones, read replicas, managed services billed per request, Lambda concurrency, +// rate limits, queues), and returns utilisation, the capacity ceiling, p50/p99 +// latency with the queueing knee, availability and cost, scored against targets. +// +// Numbers are illustrative. The rules below are stated so a "how this is +// calculated" panel can show them. + +import type { Board, BoardNode } from "./hld-types"; +import type { ComponentKind, Role, SizeTier } from "./catalog"; +import { COMPONENT_CATALOG, SIZE_CATALOG, roleOf } from "./catalog"; + +const PER_VCPU: Record = { general: 800, compute: 1200, memory: 600 }; +/** Roles that serve far more, or far less, per vCPU than a typical app server. */ +const ROLE_RATE: Partial> = { cache: 15_000, search: 300, nosql: 2_000 }; +const NETWORK_MS = 10; +/** Chance a single Availability Zone is up. */ +const AZ_AVAIL = 0.9995; +/** Regional managed services are spread across zones by the provider. */ +const MANAGED_AVAIL = 0.9999; + +const SERVICE_MS: Record = { + client: 0, dns: 1, cdn: 2, firewall: 1, limiter: 1, balancer: 2, gateway: 5, + compute: 20, function: 0, worker: 15, cache: 1, database: 8, nosql: 5, search: 25, + queue: 5, stream: 10, storage: 20, +}; +const SINGLE_AVAIL: Partial> = { + balancer: 0.9995, gateway: 0.9995, compute: 0.99, worker: 0.99, cache: 0.999, + database: 0.999, nosql: 0.9995, search: 0.999, stream: 0.999, +}; + +export interface TierLoad { + id: string; + kind: ComponentKind; + capacity: number; + utilisation: number; + down: boolean; + reachable: boolean; + /** Instances actually running, after autoscaling. */ + units: number; + /** Managed services scale for you; their utilisation is rarely the story. */ + managed: boolean; + /** A short line for the card: autoscaled, throttling, backlog, and so on. */ + note?: string; + /** What this component costs per hour whether or not it is serving. */ + cost: number; + /** Milliseconds a request spends waiting in line here, on top of its service time. Zero off the request path. */ + waitMs: number; + /** For a cache: what it was asked, what it answered itself, and what went on to the database. */ + cacheStats?: { hitRate: number; reads: number; hits: number; misses: number }; +} + +/** One labelled share of the traffic on a link, such as "cache misses" or "click writes". */ +export interface EdgePart { + label: string; + rate: number; +} + +/** Optional rules a lab can switch on for the whole run. */ +export interface ModelOptions { + /** + * Every request an app server serves also writes one row (a click) to the database + * before it answers. Labs turn this on when the board has no queue to carry the clicks. + */ + inlineWrites?: boolean; + /** + * The share of requests that send work to parts of a role, for side jobs that only + * some requests need: { queue: 0.1 } means 1 request in 10 leaves a job in the queue. + * Applied wherever a part of another role sends to that role, so it holds however the + * learner links the board. A role with no share gets the whole stream. + */ + shares?: Partial>; +} + +export interface Targets { + rps?: number; + p99Ms?: number; + availability?: number; + budgetPerHour?: number; +} + +export interface ModelResult { + capacityCeiling: number; + p50Ms: number; + p99Ms: number; + availability: number; + costPerHour: number; + tiers: TierLoad[]; + pass: { rps: boolean; p99: boolean; availability: boolean; budget: boolean }; + allPass: boolean; + /** Why the design is broken, when a component is down or unlinked. */ + failure?: string; + /** Request rate on each live link, keyed "from>to". */ + edgeFlows: Record; + /** What the traffic on a link is made of, where that is worth saying (cache reads, misses, writes). */ + edgeParts: Record; + /** Requests rejected by rate limits and throttles, per second. */ + dropped: number; + /** Requests filtered out by firewalls, per second. */ + blocked: number; + /** How fast queued work piles up because consumers are too slow, per second. */ + backlog: number; + /** The role on the request path with the lowest availability, for "add redundancy here". */ + weakest?: { role: Role; availability: number }; +} + +// ---- reading a node's configuration ------------------------------------------- + +function propOf(node: BoardNode, key: string): number | string | undefined { + const own = node.props?.[key]; + if (own !== undefined) return own; + return COMPONENT_CATALOG[node.kind].properties.find((p) => p.id === key)?.default; +} +function num(node: BoardNode, key: string, fallback: number): number { + const v = propOf(node, key); + return typeof v === "number" ? v : fallback; +} +function str(node: BoardNode, key: string, fallback: string): string { + const v = propOf(node, key); + return typeof v === "string" ? v : fallback; +} +function tierOf(node: BoardNode): SizeTier { + const id = propOf(node, "size"); + return SIZE_CATALOG.find((t) => t.id === id) ?? SIZE_CATALOG[0]; +} +const isDown = (node: BoardNode) => Boolean(node.props?.down); +const rate = (n: number) => Math.round(n).toLocaleString("en-US"); + +/** A fleet of `units` spread over `zones`; it is up while any zone has a live instance. */ +function fleetAvailability(single: number, units: number, zones: number): number { + const n = Math.max(1, Math.round(zones)); + const perZone = Math.max(1, units / n); + const zone = AZ_AVAIL * (1 - Math.pow(1 - single, perZone)); + return 1 - Math.pow(1 - zone, n); +} + +// ---- routing -------------------------------------------------------------------- + +/** Nodes a request can reach from any live client, following the links and skipping down nodes. */ +function reachableFrom(board: Board): Set { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + const next = new Map(); + for (const e of board.edges) next.set(e.from, [...(next.get(e.from) ?? []), e.to]); + const seen = new Set(); + const queue = board.nodes.filter((n) => n.kind === "client" && !isDown(n)).map((n) => n.id); + for (const id of queue) seen.add(id); + while (queue.length > 0) { + const id = queue.shift()!; + for (const to of next.get(id) ?? []) { + const node = byId.get(to); + if (node && !isDown(node) && !seen.has(to)) { + seen.add(to); + queue.push(to); + } + } + } + return seen; +} + +/** Live links between reachable nodes, deduplicated, as parent to children and child to parents. */ +function liveLinks(board: Board, reachable: Set) { + const children = new Map(); + const parents = new Map(); + for (const e of board.edges) { + if (!reachable.has(e.from) || !reachable.has(e.to) || e.from === e.to) continue; + const kids = children.get(e.from) ?? []; + if (kids.includes(e.to)) continue; + children.set(e.from, [...kids, e.to]); + parents.set(e.to, [...(parents.get(e.to) ?? []), e.from]); + } + return { children, parents }; +} + +/** Reachable nodes in topological order (Kahn), so load and latency flow parent before child. */ +function topoOrder(reachable: Set, children: Map, parents: Map): string[] { + const indegree = new Map([...reachable].map((id) => [id, (parents.get(id) ?? []).length])); + const queue = [...reachable].filter((id) => indegree.get(id) === 0); + const order: string[] = []; + while (queue.length > 0) { + const id = queue.shift()!; + order.push(id); + for (const kid of children.get(id) ?? []) { + indegree.set(kid, (indegree.get(kid) ?? 1) - 1); + if (indegree.get(kid) === 0) queue.push(kid); + } + } + return order; +} + +const ASYNC_ROLES = new Set(["queue", "stream"]); + +/** Nodes on the synchronous request path: reachable without passing through a queue or stream. */ +function synchronous(order: string[], byId: Map, children: Map): Set { + const seen = new Set(order.filter((id) => byId.get(id)!.kind === "client")); + const queue = [...seen]; + while (queue.length > 0) { + const id = queue.shift()!; + if (ASYNC_ROLES.has(roleOf(byId.get(id)!.kind))) continue; + for (const kid of children.get(id) ?? []) { + if (!seen.has(kid)) { + seen.add(kid); + queue.push(kid); + } + } + } + return seen; +} + +/** The most a node lets through per second; above it, requests are rejected. */ +function limitOf(node: BoardNode): number | undefined { + if (node.kind === "rate-limiter" || node.kind === "aws-api-gateway") return num(node, "limit", Infinity); + if (node.kind === "aws-lambda") return lambdaCapacity(node); + return undefined; +} +/** Share of what a node serves that continues downstream (CDN misses, traffic a firewall lets in). */ +function passOn(node: BoardNode): number { + const role = roleOf(node.kind); + if (role === "cdn") return 1 - num(node, "hitRate", 0); + if (role === "firewall") return 1 - num(node, "blockRate", 0); + // A cache answers its hits itself; only the misses go on to a database linked behind it. + if (role === "cache") return 1 - num(node, "hitRate", 0); + return 1; +} +function lambdaCapacity(node: BoardNode): number { + return (num(node, "concurrency", 1000) * 1000) / Math.max(1, num(node, "durationMs", 120)); +} + +// ---- evaluating one component ---------------------------------------------------- + +interface Evaluation { + capacity: number; + units: number; + cost: number; + serviceMs: number; + availability: number; + /** Whether requests wait in line as it gets busy (the p99 knee), or are throttled instead. */ + queueing: boolean; + managed: boolean; + note?: string; +} + +function evaluate(node: BoardNode, flow: number, inlineWrites = 0): Evaluation { + const def = COMPONENT_CATALOG[node.kind]; + const role = def.role; + + if (node.kind === "aws-lambda") { + const duration = Math.max(1, num(node, "durationMs", 120)); + const memoryGb = Number(str(node, "memoryMb", "512")) / 1024; + const capacity = lambdaCapacity(node); + const cost = flow * 3600 * (0.2 / 1e6 + (duration / 1000) * memoryGb * 0.0000166667); + const note = flow > capacity ? `throttling ${rate(flow - capacity)}/s` : flow > 0 ? `~${rate(Math.ceil((flow * duration) / 1000))} running at once` : undefined; + return { capacity, units: 1, cost, serviceMs: duration, availability: MANAGED_AVAIL, queueing: false, managed: true, note }; + } + + if (node.kind === "aws-dynamodb") { + const reads = num(node, "readRatio", 0.8); + if (str(node, "capacityMode", "on-demand") === "provisioned") { + const rcu = num(node, "rcu", 1000); + const wcu = num(node, "wcu", 500); + const util = Math.max((flow * reads) / (rcu * 2), (flow * (1 - reads)) / wcu); + return { + capacity: util > 0 ? flow / util : rcu * 2 + wcu, units: 1, cost: rcu * 0.00013 + wcu * 0.00065, + serviceMs: 5, availability: MANAGED_AVAIL, queueing: false, managed: true, + note: util > 1 ? "throttled: raise RCU/WCU or go on-demand" : undefined, + }; + } + return { + capacity: 40_000, units: 1, cost: (flow * 3600 * (reads * 0.25 + (1 - reads) * 1.25)) / 1e6, + serviceMs: 5, availability: MANAGED_AVAIL, queueing: false, managed: true, + }; + } + + if (role === "stream") { + const shards = num(node, "partitions", 2); + const aws = def.family === "aws"; + return { + capacity: shards * 1000, units: shards, cost: shards * 0.015 + (aws ? (flow * 3600 * 0.014) / 1e6 : 0), + serviceMs: SERVICE_MS.stream, availability: aws ? MANAGED_AVAIL : fleetAvailability(0.999, shards, 1), + queueing: false, managed: aws, note: flow > shards * 1000 ? "producers throttled: add shards" : undefined, + }; + } + + if (def.managed) { + let capacity = def.managed.capacity; + let perMillion = def.managed.pricePerMillion; + if (node.kind === "aws-api-gateway" && str(node, "apiType", "HTTP") === "REST") perMillion = 3.5; + if (node.kind === "aws-sqs" && str(node, "queueType", "standard") === "FIFO") capacity = 3000; + const hourly = node.kind === "k8s-service" && str(node, "serviceType", "ClusterIP") === "LoadBalancer" ? 0.0225 : def.managed.pricePerHour; + const limit = limitOf(node); + if (limit != null) capacity = Math.min(capacity, limit); + const hasZones = def.properties.some((p) => p.id === "azs"); + const availability = hasZones ? fleetAvailability(0.99999, 1, num(node, "azs", 2)) : MANAGED_AVAIL; + const note = limit != null && flow > limit ? `rejecting ${rate(flow - limit)}/s` : undefined; + return { + capacity, units: 1, cost: hourly + (flow * 3600 * perMillion) / 1e6, + serviceMs: SERVICE_MS[role] + (node.kind === "aws-api-gateway" ? 5 : 0), + availability, queueing: false, managed: true, note, + }; + } + + // Instance-based: a fleet of servers of one size. + const tier = tierOf(node); + const perUnit = tier.vcpu * (ROLE_RATE[role] ?? PER_VCPU[tier.family]); + const single = SINGLE_AVAIL[role] ?? 0.99; + + if (role === "database") { + const replicas = num(node, "replicas", 0); + const reads = num(node, "readRatio", 0.8); + const multiAz = num(node, "multiAz", 0) > 0; + // Every write goes to the primary; reads spread over the primary and its replicas. + // Inline writes are all writes: they are part of the flow but never reads. + const other = Math.max(0, flow - inlineWrites); + const util = Math.max(other * (1 - reads) + inlineWrites, (other * reads) / (1 + replicas)) / perUnit; + const parts = [replicas > 0 ? `${replicas} read replica${replicas === 1 ? "" : "s"}` : null, multiAz ? "Multi-AZ" : null].filter(Boolean); + return { + capacity: util > 0 ? flow / util : perUnit * (1 + replicas), units: 1 + replicas, + cost: tier.pricePerHour * ((multiAz ? 2 : 1) + replicas), serviceMs: SERVICE_MS.database, + availability: fleetAvailability(single, 1, multiAz ? 2 : 1), queueing: true, managed: false, + note: parts.length > 0 ? parts.join(", ") : undefined, + }; + } + + let units = node.kind === "load-balancer" ? num(node, "zones", 1) : num(node, "count", 1); + let note: string | undefined; + if (num(node, "autoscale", 0) > 0) { + const min = Math.max(1, num(node, "minCount", 1)); + const max = Math.max(min, num(node, "maxCount", 10)); + const target = Math.min(1, Math.max(0.05, num(node, "targetUtil", 0.6))); + units = Math.min(max, Math.max(min, Math.ceil(flow / (perUnit * target) - 1e-9))); + note = units === max && flow / (perUnit * units) > target ? `at max ${max}: raise the max or the size` : `autoscaled to ${units} (${min} to ${max})`; + } + + let cost = tier.pricePerHour * units; + let availabilityUnits = units; + if (node.kind === "aws-elasticache") { + const replicasPerShard = num(node, "replicasPerShard", 1); + cost = tier.pricePerHour * units * (1 + replicasPerShard); + availabilityUnits = 1 + replicasPerShard; + } + const zones = node.kind === "load-balancer" ? units : num(node, "azs", 1); + return { + capacity: perUnit * units, units, cost, serviceMs: SERVICE_MS[role], + availability: fleetAvailability(single, availabilityUnits, zones), queueing: true, managed: false, note, + }; +} + +// ---- the model ------------------------------------------------------------------- + +export function runTieredModel(board: Board, load: number, targets: Targets, options: ModelOptions = {}): ModelResult { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + const reachable = reachableFrom(board); + const { children, parents } = liveLinks(board, reachable); + const order = topoOrder(reachable, children, parents); + const sync = synchronous(order, byId, children); + + // Load enters at the live clients and flows down the links. A node first applies + // its limit (rejecting the excess), then passes on what continues (CDN misses, + // traffic the firewall lets in). Parallel children with the same role share it; + // different roles are different services and each see the whole stream; a + // database or key-value store beside a cache only sees the cache misses. + const incoming = new Map(); + const inlineWrites = new Map(); + const edgeFlows: Record = {}; + const edgeParts: Record = {}; + const addPart = (key: string, label: string, rate: number) => { (edgeParts[key] ??= []).push({ label, rate }); }; + let dropped = 0; + let blocked = 0; + const clients = order.filter((id) => byId.get(id)!.kind === "client"); + for (const id of clients) incoming.set(id, load / clients.length); + for (const id of order) { + const node = byId.get(id)!; + const flowIn = incoming.get(id) ?? 0; + const limit = limitOf(node); + const served = limit != null ? Math.min(flowIn, limit) : flowIn; + dropped += flowIn - served; + const out = served * passOn(node); + if (roleOf(node.kind) === "firewall") blocked += served - out; + + const kids = (children.get(id) ?? []).map((k) => byId.get(k)!); + const cache = kids.find((n) => roleOf(n.kind) === "cache"); + const missRate = cache ? 1 - num(cache, "hitRate", 0) : 1; + // Read-through: a store that the cache itself links to is loaded by the cache on a miss, + // so the app server's own link to it carries no reads (it never counts twice). + const behindCache = new Set(cache ? children.get(cache.id) ?? [] : []); + const byRole = new Map(); + for (const kid of kids) { + if (behindCache.has(kid.id)) continue; + byRole.set(roleOf(kid.kind), [...(byRole.get(roleOf(kid.kind)) ?? []), kid.id]); + } + for (const [role, ids] of byRole) { + const stores = role === "database" || role === "nosql"; + // A worker batches its writes: one trip to the store carries `batchSize` events. + const batch = node.kind === "worker" && stores ? Math.max(1, num(node, "batchSize", 1)) : 1; + // A side job only some requests need (an alert, an index update) carries its share of the stream. + const part = role !== roleOf(node.kind) ? (options.shares?.[role] ?? 1) : 1; + const share = (stores ? (out * missRate) / batch : out) * part; + for (const k of ids) { + const key = `${id}>${k}`; + const rate = share / ids.length; + incoming.set(k, (incoming.get(k) ?? 0) + rate); + edgeFlows[key] = (edgeFlows[key] ?? 0) + rate; + if (part < 1) addPart(key, `${Math.round(part * 1000) / 10}% of requests send work here`, rate); + if (role === "cache") addPart(key, `reads, ${Math.round(num(byId.get(k)!, "hitRate", 0) * 100)}% answered by the cache`, rate); + else if (stores && node.kind === "worker" && batch > 1) addPart(key, `writes, ${batch} per trip`, rate); + else if (stores && cache) addPart(key, "cache misses", rate); + else if (stores && roleOf(node.kind) === "cache") addPart(key, "cache misses", rate); + } + } + if (options.inlineWrites && roleOf(node.kind) === "compute") { + // The click write goes to the store whether the app server reaches it directly or through its cache. + const direct = kids.filter((k) => roleOf(k.kind) === "database"); + const through = (cache ? children.get(cache.id) ?? [] : []).map((k) => byId.get(k)!).filter((k) => roleOf(k.kind) === "database"); + const stores = [...new Map([...direct, ...through].map((k) => [k.id, k])).values()]; + for (const store of stores) { + const writes = out / stores.length; + const key = direct.some((d) => d.id === store.id) ? `${id}>${store.id}` : `${cache!.id}>${store.id}`; + incoming.set(store.id, (incoming.get(store.id) ?? 0) + writes); + inlineWrites.set(store.id, (inlineWrites.get(store.id) ?? 0) + writes); + edgeFlows[key] = (edgeFlows[key] ?? 0) + writes; + addPart(key, direct.some((d) => d.id === store.id) ? "click writes" : "click writes, written directly", writes); + } + } + } + + const evaluations = new Map(); + const tiers: TierLoad[] = []; + let cost = 0; + for (const node of board.nodes) { + if (node.kind === "client") continue; + const down = isDown(node); + const onPath = reachable.has(node.id); + const flow = onPath ? incoming.get(node.id) ?? 0 : 0; + const ev = evaluate(node, flow, inlineWrites.get(node.id) ?? 0); + const capacity = down ? 0 : ev.capacity; + evaluations.set(node.id, ev); + cost += ev.cost; // placed hardware costs money whether or not it is serving + tiers.push({ + id: node.id, kind: node.kind, capacity, utilisation: capacity > 0 ? flow / capacity : 0, + down, reachable: onPath, units: ev.units, managed: ev.managed, note: ev.note, cost: ev.cost, waitMs: 0, + cacheStats: roleOf(node.kind) === "cache" && onPath + ? { hitRate: num(node, "hitRate", 0), reads: flow, hits: flow * num(node, "hitRate", 0), misses: flow * (1 - num(node, "hitRate", 0)) } + : undefined, + }); + } + const tierById = new Map(tiers.map((t) => [t.id, t])); + + // Work behind a queue is asynchronous: slow consumers build a backlog, not slow requests. + let backlog = 0; + for (const id of order) { + const node = byId.get(id)!; + if (!ASYNC_ROLES.has(roleOf(node.kind))) continue; + const consumers = (children.get(id) ?? []).reduce((sum, k) => sum + (tierById.get(k)?.capacity ?? 0), 0); + const behind = Math.max(0, (incoming.get(id) ?? 0) - consumers); + backlog += behind; + const tier = tierById.get(id); + // A consumer that is down is still linked: say so, instead of "no consumers linked". + const linkedButDown = board.edges.some((e) => e.from === id && isDown(byId.get(e.to)!)); + if (tier) tier.note = consumers === 0 ? (linkedButDown ? `consumers down, backlog grows ${rate(behind)}/s` : "no consumers linked") : behind > 0 ? `backlog grows ${rate(behind)}/s` : "consumers keeping up"; + } + + // Capacity, latency and availability of the synchronous request path. + let ceiling = Number.POSITIVE_INFINITY; + const roleAvail = new Map(); + const lat50 = new Map(); + const lat99 = new Map(); + for (const id of order) { + if (!sync.has(id)) continue; + const tier = tierById.get(id); + const ev = evaluations.get(id); + if (tier && ev) { + const flow = incoming.get(id) ?? 0; + if (flow > 0 && tier.capacity > 0) ceiling = Math.min(ceiling, (tier.capacity * load) / flow); + const role = roleOf(tier.kind); + roleAvail.set(role, [...(roleAvail.get(role) ?? []), ev.availability]); + } + const service = ev?.serviceMs ?? 0; + const u = ev?.queueing && tier ? Math.min(tier.utilisation, 0.985) : 0; + const before = (parents.get(id) ?? []).filter((p) => sync.has(p)); + lat50.set(id, service + Math.max(0, ...before.map((p) => lat50.get(p) ?? 0))); + lat99.set(id, service / (1 - u) + Math.max(0, ...before.map((p) => lat99.get(p) ?? 0))); + if (tier) tier.waitMs = service / (1 - u) - service; + } + const p50 = NETWORK_MS + Math.max(0, ...lat50.values()); + const p99 = NETWORK_MS + Math.max(0, ...lat99.values()); + + // Parallel components with the same role back each other up; the roles are in series. + let availability = 1; + let weakest: ModelResult["weakest"]; + for (const [role, parts] of roleAvail) { + const roleUp = 1 - parts.reduce((all, a) => all * (1 - a), 1); + availability *= roleUp; + if (!weakest || roleUp < weakest.availability) weakest = { role, availability: roleUp }; + } + + // A placed database that requests cannot reach means nothing is served. + let failure: string | undefined; + const stores = board.nodes.filter((n) => roleOf(n.kind) === "database" || roleOf(n.kind) === "nosql"); + if (stores.length > 0 && !stores.some((n) => reachable.has(n.id))) { + ceiling = 0; + availability = 0; + const blocker = board.nodes.find((n) => isDown(n) && board.edges.some((e) => e.from === n.id || e.to === n.id)); + failure = blocker + ? `${COMPONENT_CATALOG[blocker.kind].label} is down: requests through it fail.` + : "The database is not linked into the request path."; + } + + if (!Number.isFinite(ceiling)) ceiling = 0; + + const pass = { + rps: targets.rps == null ? true : ceiling >= targets.rps, + p99: targets.p99Ms == null ? true : p99 <= targets.p99Ms, + availability: targets.availability == null ? true : availability >= targets.availability, + budget: targets.budgetPerHour == null ? true : cost <= targets.budgetPerHour, + }; + + return { + capacityCeiling: Math.round(ceiling), + p50Ms: Math.round(p50), + p99Ms: Math.round(p99), + availability, + failure, + edgeFlows, + edgeParts, + dropped, + blocked, + backlog, + weakest, + costPerHour: cost, + tiers, + pass, + allPass: pass.rps && pass.p99 && pass.availability && pass.budget, + }; +} diff --git a/packages/learning-ui/contracts.json b/packages/learning-ui/contracts.json index c7123783..a4d30819 100644 --- a/packages/learning-ui/contracts.json +++ b/packages/learning-ui/contracts.json @@ -20,5 +20,9 @@ "api/syllabus.ts", "domain/enums.ts", "lib/course-tracks.ts", - "html-preview/spec.ts" + "html-preview/spec.ts", + "lab/engine/catalog.ts", + "lab/engine/hld-types.ts", + "lab/engine/tiered-architecture.ts", + "lab/engine/challenge.ts" ] diff --git a/packages/learning-ui/src/labs/HldBoard.tsx b/packages/learning-ui/src/labs/HldBoard.tsx index aeeff434..7dca90ed 100644 --- a/packages/learning-ui/src/labs/HldBoard.tsx +++ b/packages/learning-ui/src/labs/HldBoard.tsx @@ -46,7 +46,7 @@ import { COMPONENT_CATALOG, SIZE_CATALOG, canConnect, isComponentKind, roleOf } import type { Board, HldLabSpec } from "./types"; import { initialControls, type BoardControls, type NodeConfig } from "./hld-board-model"; import type { EdgePart, ModelResult, TierLoad } from "./tiered-architecture"; -import { runChallenge, runModel } from "./challenge"; +import { runChallenge, runModel, type ChallengeReport } from "./challenge"; import { ResultsDialog, RunPanel, PHASE_MS, type RunState } from "./RunPanel"; import { SettingsDrawer, anchorStyle, cacheSentence } from "./SettingsDrawer"; import { CompareView, ConfirmBar, PartExplainer, PartList } from "./SolutionPanel"; @@ -266,9 +266,11 @@ interface EditorProps { onHideCompare?: () => void; isFullscreen?: boolean; onToggleFullscreen?: () => void; + /** Called once when a run finishes, with the report the board shows, the design that ran and its load. */ + onRunComplete?: (report: ChallengeReport, board: Board, load: number) => void; } -function Editor({ spec, onReset, solutionMode = false, onRun, onSnapshot, canOpenSolution = false, onOpenSolution, onBack, onCopy, onCompare, compare, onHideCompare, isFullscreen = false, onToggleFullscreen }: EditorProps) { +function Editor({ spec, onReset, solutionMode = false, onRun, onRunComplete, onSnapshot, canOpenSolution = false, onOpenSolution, onBack, onCopy, onCompare, compare, onHideCompare, isFullscreen = false, onToggleFullscreen }: EditorProps) { const readOnly = solutionMode; const [confirm, setConfirm] = useState<"solution" | "copy" | null>(null); const start: Board = spec.startingBoard ?? { nodes: [], edges: [] }; @@ -374,6 +376,7 @@ function Editor({ spec, onReset, solutionMode = false, onRun, onSnapshot, canOpe const key = designKey; if (typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) { setRanKey(key); + onRunComplete?.(report, board, load); return; } const total = report.phases.length; @@ -382,7 +385,7 @@ function Editor({ spec, onReset, solutionMode = false, onRun, onSnapshot, canOpe timers.current.push( setTimeout(() => { if (i + 1 < total) step(i + 1); - else { setRunPhase(null); setRanKey(key); } + else { setRunPhase(null); setRanKey(key); onRunComplete?.(report, board, load); } }, PHASE_MS), ); }; @@ -392,6 +395,7 @@ function Editor({ spec, onReset, solutionMode = false, onRun, onSnapshot, canOpe clearTimers(); setRunPhase(null); setRanKey(designKey); + onRunComplete?.(report, board, load); } // What the board shows: the learner's design, or one scenario of the run. @@ -1063,6 +1067,7 @@ export function HldBoard({ fullscreenActive, hideWhenInline = false, onExitFullscreen, + onRunComplete, }: { spec: HldLabSpec; initialFullscreen?: boolean; @@ -1072,6 +1077,8 @@ export function HldBoard({ hideWhenInline?: boolean; /** Course launchers close the workspace when the learner exits full screen. */ onExitFullscreen?: () => void; + /** Called once when a run finishes, with the same report the board shows. */ + onRunComplete?: (report: ChallengeReport, board: Board, load: number) => void; }) { const [generation, setGeneration] = useState(0); const [mode, setMode] = useState<"mine" | "solution">("mine"); @@ -1155,6 +1162,7 @@ export function HldBoard({ spec={mineSpec} onReset={() => { setSeed(null); setGeneration((g) => g + 1); }} onRun={() => setEverRan(true)} + onRunComplete={onRunComplete} onSnapshot={onSnapshot} canOpenSolution={everRan} onOpenSolution={() => { setCompare(null); setMode("solution"); }} diff --git a/packages/learning-ui/src/labs/Lab.tsx b/packages/learning-ui/src/labs/Lab.tsx index 022ae594..55f613c4 100644 --- a/packages/learning-ui/src/labs/Lab.tsx +++ b/packages/learning-ui/src/labs/Lab.tsx @@ -1,6 +1,8 @@ import type { ReactNode } from "react"; import { validateLabSpec, type LabSpec } from "./types"; import { HldBoard } from "./HldBoard"; +import type { ChallengeReport } from "./challenge"; +import type { Board } from "./types"; import { getLabSpec } from "./registry"; import { BuildBoard } from "./net/BuildBoard"; import { NetBoard } from "./net/NetBoard"; @@ -80,6 +82,7 @@ export function Lab({ version, presentation, courseMode = false, + onRunComplete, }: { spec?: LabSpec | null; slug?: unknown; @@ -87,6 +90,8 @@ export function Lab({ presentation?: unknown; /** Course readers use a compact launcher; galleries and previews keep the full inline board. */ courseMode?: boolean; + /** For an hld lab: called once when a run finishes, with the report the board shows. */ + onRunComplete?: (report: ChallengeReport, board: Board, load: number) => void; }) { const pres = presentationSchema.safeParse(presentation); const presOptions = pres.success ? pres.data : undefined; @@ -153,7 +158,7 @@ export function Lab({ {resolvedSpec.family === "hld" ? ( - + ) : resolvedSpec.family === "net" ? ( resolvedSpec.mode === "plan" && resolvedSpec.plan ? ( diff --git a/packages/learning-ui/src/labs/catalog.ts b/packages/learning-ui/src/labs/catalog.ts index 739ac2f9..63caf356 100644 --- a/packages/learning-ui/src/labs/catalog.ts +++ b/packages/learning-ui/src/labs/catalog.ts @@ -1,436 +1 @@ -// The shared component catalog for the lab platform. -// -// Every block a lab can use is described once here: its family (which course it -// belongs to), its role (what it does in a request path), its configurable -// properties (with range, default, unit and the panel group they show in), and -// the size catalogs its size pickers draw from. The board, the scoring model and -// the authoring validator all read this file. Links are allowed by role, so a new -// family (Kubernetes, Docker, Linux) is mostly new entries here, not new code. -// -// Prices and capacities are illustrative and dated (one region, on-demand, late -// 2026). Use them to compare the shapes of designs, not to quote a real bill. - -export type Family = "hld" | "aws" | "k8s" | "docker" | "linux"; -export const FAMILIES: readonly Family[] = ["hld", "aws", "k8s", "docker", "linux"]; - -export type Role = - | "client" - | "dns" - | "cdn" - | "firewall" - | "limiter" - | "balancer" - | "gateway" - | "compute" - | "function" - | "worker" - | "cache" - | "database" - | "nosql" - | "search" - | "queue" - | "stream" - | "storage"; - -export type ComponentKind = - // Generic building blocks for the high-level design course - | "client" - | "dns" - | "cdn" - | "waf" - | "rate-limiter" - | "load-balancer" - | "api-gateway" - | "app-server" - | "worker" - | "cache" - | "database" - | "nosql" - | "search" - | "queue" - | "stream" - | "object-storage" - // AWS services for the AWS course - | "aws-route53" - | "aws-cloudfront" - | "aws-waf" - | "aws-alb" - | "aws-nlb" - | "aws-api-gateway" - | "aws-ec2-asg" - | "aws-fargate" - | "aws-lambda" - | "aws-elasticache" - | "aws-rds" - | "aws-dynamodb" - | "aws-opensearch" - | "aws-sqs" - | "aws-kinesis" - | "aws-s3" - // Kubernetes objects for the Kubernetes course - | "k8s-ingress" - | "k8s-service" - | "k8s-deployment" - | "k8s-statefulset" - // Containers for the Docker course - | "docker-proxy" - | "docker-container" - | "docker-postgres" - // One host's services for the Linux course - | "linux-nginx" - | "linux-service" - | "linux-postgres"; - -export type PortDir = "in" | "out"; - -export interface PortDef { - id: string; - dir: PortDir; - accepts: ComponentKind[]; -} - -export type SizeSet = "generic" | "ec2" | "fargate" | "rds" | "elasticache" | "opensearch" | "pod" | "container" | "host"; -export type PropertyGroup = "Capacity" | "Scaling" | "Resilience" | "Behaviour"; - -export interface PropertyDef { - id: string; - label: string; - type: "size" | "count" | "ratio" | "enum" | "toggle"; - min?: number; - max?: number; - step?: number; - default: number | string; - unit: string; - options?: string[]; - /** Which size catalog a size picker draws from. */ - sizeSet?: SizeSet; - group?: PropertyGroup; - /** One line shown as a tooltip in the config panel. */ - help?: string; -} - -/** A managed, elastic service: priced per hour plus per million requests. */ -export interface ManagedPricing { - capacity: number; - pricePerHour: number; - pricePerMillion: number; -} - -export interface ComponentDef { - kind: ComponentKind; - label: string; - family: Family; - role: Role; - /** The product or engine name shown under the label. */ - vendor: string; - icon: string; - ports: PortDef[]; - properties: PropertyDef[]; - managed?: ManagedPricing; -} - -export interface SizeTier { - id: string; - set: SizeSet; - family: "general" | "compute" | "memory"; - vcpu: number; - memoryGb: number; - capacityRule: string; - pricePerHour: number; -} - -// Which role may send requests to which. Links follow the request, not the data. -const ROLE_NEXT: Record = { - client: ["dns", "cdn", "firewall", "limiter", "balancer", "gateway"], - dns: [], - cdn: ["firewall", "limiter", "balancer", "gateway", "compute", "storage"], - firewall: ["cdn", "limiter", "balancer", "gateway", "compute"], - limiter: ["balancer", "gateway", "compute", "function"], - balancer: ["balancer", "compute", "function"], - gateway: ["balancer", "compute", "function", "queue", "stream", "nosql", "storage"], - compute: ["function", "cache", "database", "nosql", "search", "queue", "stream", "storage"], - function: ["cache", "database", "nosql", "search", "queue", "stream", "storage"], - worker: ["cache", "database", "nosql", "search", "queue", "storage"], - queue: ["worker", "function"], - stream: ["worker", "function"], - // A cache may load from a database on a miss (read-through). Linking it is optional: - // an app server linked to both a cache and a database is cache-aside, with the same maths. - cache: ["database", "nosql"], - database: [], - nosql: [], - search: [], - storage: [], -}; - -// ---- property builders --------------------------------------------------- - -const size = (sizeSet: SizeSet, defaultId: string): PropertyDef => ({ - id: "size", - label: "Machine size", - type: "size", - sizeSet, - default: defaultId, - unit: "tier", - group: "Capacity", -}); -const count = (id: string, label: string, unit: string, def: number, min: number, max: number, group: PropertyGroup = "Capacity", help?: string): PropertyDef => ({ - id, label, type: "count", min, max, step: 1, default: def, unit, group, help, -}); -const ratio = (id: string, label: string, def: number, group: PropertyGroup = "Behaviour", help?: string): PropertyDef => ({ - id, label, type: "ratio", min: 0, max: 1, step: 0.05, default: def, unit: "fraction", group, help, -}); -const toggle = (id: string, label: string, def: 0 | 1, group: PropertyGroup, help?: string): PropertyDef => ({ - id, label, type: "toggle", default: def, unit: "on/off", group, help, -}); -const choice = (id: string, label: string, options: string[], def: string, group: PropertyGroup = "Behaviour", help?: string): PropertyDef => ({ - id, label, type: "enum", options, default: def, unit: "option", group, help, -}); -const azs = (def: number, min = 1): PropertyDef => - count("azs", "Zones (separate data centres)", "zones", def, min, 3, "Resilience", "Spreading across zones means one zone going down does not stop the service."); -const scaling = (on: 0 | 1, min: number, max: number, target: number): PropertyDef[] => [ - toggle("autoscale", "Add machines automatically (autoscaling)", on, "Scaling", "Adds or removes machines to stay near the target busyness."), - count("minCount", "Fewest machines", "machines", min, 1, 100, "Scaling"), - count("maxCount", "Most machines", "machines", max, 1, 200, "Scaling"), - ratio("targetUtil", "Aim to stay this busy (target utilisation)", target, "Scaling", "Add machines before this level. Waiting time starts to climb near 70% busy."), -]; - -// ---- the catalog ----------------------------------------------------------- - -type Entry = Omit; - -const ENTRIES: Record = { - // Generic high-level design blocks - client: { label: "Client", family: "hld", role: "client", vendor: "Users", icon: "client", - properties: [count("load", "Traffic sent (offered load)", "req/s", 1000, 1, 10_000_000)] }, - dns: { label: "DNS", family: "hld", role: "dns", vendor: "Resolver", icon: "dns", - managed: { capacity: 1_000_000, pricePerHour: 0.001, pricePerMillion: 0 }, - properties: [count("ttl", "Record TTL", "seconds", 300, 1, 86_400, "Behaviour")] }, - cdn: { label: "CDN", family: "hld", role: "cdn", vendor: "Edge cache", icon: "cdn", - managed: { capacity: 1_000_000, pricePerHour: 0.02, pricePerMillion: 0.75 }, - properties: [ratio("hitRate", "Answered nearby (edge hit rate)", 0.8, "Behaviour", "A hit is answered close to the user. Only misses reach your servers.")] }, - waf: { label: "Firewall", family: "hld", role: "firewall", vendor: "WAF", icon: "firewall", - managed: { capacity: 1_000_000, pricePerHour: 0.007, pricePerMillion: 0.6 }, - properties: [ratio("blockRate", "Blocked share", 0.02, "Behaviour", "Share of traffic dropped as malicious.")] }, - "rate-limiter": { label: "Rate limiter", family: "hld", role: "limiter", vendor: "Token bucket", icon: "limiter", - managed: { capacity: 1_000_000, pricePerHour: 0.01, pricePerMillion: 0 }, - properties: [count("limit", "Limit", "req/s", 5000, 10, 1_000_000, "Behaviour", "Requests above this are rejected, protecting what sits behind it.")] }, - "load-balancer": { label: "Load balancer", family: "hld", role: "balancer", vendor: "L7 LB", icon: "balancer", - properties: [size("generic", "general-small"), count("zones", "Zones (separate data centres)", "zones", 1, 1, 3, "Resilience")] }, - "api-gateway": { label: "API gateway", family: "hld", role: "gateway", vendor: "Gateway", icon: "gateway", - properties: [size("generic", "general-small"), count("count", "Machines (instances)", "machines", 2, 1, 50)] }, - "app-server": { label: "App server", family: "hld", role: "compute", vendor: "Compute", icon: "compute", - properties: [size("generic", "compute-small"), count("count", "Machines (instances)", "machines", 2, 1, 50), ...scaling(0, 2, 10, 0.6), azs(1)] }, - worker: { label: "Worker", family: "hld", role: "worker", vendor: "Consumer", icon: "worker", - properties: [size("generic", "compute-small"), count("count", "Workers", "workers", 2, 1, 100), count("batchSize", "Items saved per trip (batch size)", "events", 1, 1, 1000, "Behaviour", "How many items (clicks, posts, events) go to the store in one trip. Saving many at once turns thousands of writes a second into a few."), ...scaling(0, 1, 20, 0.7)] }, - cache: { label: "Cache", family: "hld", role: "cache", vendor: "Redis", icon: "cache", - properties: [size("generic", "memory-small"), count("count", "Machines (nodes)", "nodes", 1, 1, 20), ratio("hitRate", "Answered by the cache (hit rate)", 0.85, "Behaviour", "A hit means the database is never asked. A miss goes on to the database."), azs(1)] }, - database: { label: "Database", family: "hld", role: "database", vendor: "PostgreSQL", icon: "database", - properties: [ - size("generic", "memory-medium"), - count("replicas", "Read-only copies (read replicas)", "copies", 0, 0, 5, "Capacity", "Extra copies that share the reads. Every write still goes to the main copy (the primary)."), - ratio("readRatio", "Share that only reads", 0.8, "Behaviour", "Reads look data up. Writes change it."), - toggle("multiAz", "Extra copy that takes over (failover standby)", 0, "Resilience", "A standby copy in a second zone takes over if the main copy's zone fails. It doubles the main copy's cost."), - ] }, - nosql: { label: "NoSQL store", family: "hld", role: "nosql", vendor: "Key-value", icon: "nosql", - properties: [size("generic", "memory-medium"), count("count", "Machines (nodes)", "nodes", 3, 1, 30), azs(1)] }, - search: { label: "Search", family: "hld", role: "search", vendor: "Index", icon: "search", - properties: [size("generic", "memory-medium"), count("count", "Machines (nodes)", "nodes", 2, 1, 20), azs(1)] }, - queue: { label: "Queue", family: "hld", role: "queue", vendor: "Broker", icon: "queue", - managed: { capacity: 100_000, pricePerHour: 0.01, pricePerMillion: 0.04 }, - properties: [count("maxInFlight", "Most messages handled at once (max in flight)", "messages", 1000, 1, 1_000_000, "Behaviour")] }, - stream: { label: "Event stream", family: "hld", role: "stream", vendor: "Kafka", icon: "stream", - properties: [count("partitions", "Lanes (partitions)", "lanes", 4, 1, 256, "Capacity", "Each lane takes about 1,000 events a second."), count("retentionHours", "Keep events for (retention)", "hours", 24, 1, 8760, "Behaviour")] }, - "object-storage": { label: "Object storage", family: "hld", role: "storage", vendor: "Blob store", icon: "storage", - managed: { capacity: 1_000_000, pricePerHour: 0.01, pricePerMillion: 0.4 }, - properties: [count("capacityGb", "Capacity", "GB", 100, 1, 1_000_000)] }, - - // AWS services - "aws-route53": { label: "Route 53", family: "aws", role: "dns", vendor: "AWS DNS", icon: "dns", - managed: { capacity: 1_000_000, pricePerHour: 0.0007, pricePerMillion: 0 }, - properties: [choice("routing", "Routing policy", ["simple", "latency", "failover", "weighted"], "simple")] }, - "aws-cloudfront": { label: "CloudFront", family: "aws", role: "cdn", vendor: "AWS CDN", icon: "cdn", - managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.75 }, - properties: [ratio("hitRate", "Cache hit rate", 0.85), choice("priceClass", "Price class", ["100", "200", "All"], "100")] }, - "aws-waf": { label: "AWS WAF", family: "aws", role: "firewall", vendor: "Web ACL", icon: "firewall", - managed: { capacity: 1_000_000, pricePerHour: 0.007, pricePerMillion: 0.6 }, - properties: [ratio("blockRate", "Blocked share", 0.02), count("rules", "Rules", "rules", 10, 1, 100, "Behaviour")] }, - "aws-alb": { label: "ALB", family: "aws", role: "balancer", vendor: "Application LB", icon: "balancer", - managed: { capacity: 100_000, pricePerHour: 0.0225, pricePerMillion: 0.2 }, - properties: [azs(2, 2), toggle("crossZone", "Cross-zone balancing", 1, "Resilience")] }, - "aws-nlb": { label: "NLB", family: "aws", role: "balancer", vendor: "Network LB", icon: "balancer", - managed: { capacity: 200_000, pricePerHour: 0.0225, pricePerMillion: 0.1 }, - properties: [azs(2, 1)] }, - "aws-api-gateway": { label: "API Gateway", family: "aws", role: "gateway", vendor: "AWS API Gateway", icon: "gateway", - managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 1 }, - properties: [ - choice("apiType", "API type", ["HTTP", "REST"], "HTTP", "Behaviour", "REST APIs cost about 3.5 times more per request."), - count("limit", "Throttle", "req/s", 10_000, 10, 100_000, "Behaviour", "Account throttle; requests above it get 429 errors."), - ] }, - "aws-ec2-asg": { label: "EC2 Auto Scaling", family: "aws", role: "compute", vendor: "EC2", icon: "compute", - properties: [size("ec2", "m5.large"), count("count", "Desired instances", "instances", 2, 1, 200), ...scaling(1, 2, 10, 0.5), azs(2)] }, - "aws-fargate": { label: "ECS Fargate", family: "aws", role: "compute", vendor: "Containers", icon: "compute", - properties: [size("fargate", "1 vCPU / 2 GB"), count("count", "Tasks", "tasks", 2, 1, 500), ...scaling(1, 2, 20, 0.6), azs(2)] }, - "aws-lambda": { label: "Lambda", family: "aws", role: "function", vendor: "Serverless", icon: "function", - properties: [ - choice("memoryMb", "Memory", ["128", "256", "512", "1024", "2048"], "512", "Capacity", "More memory also means more CPU and a higher GB-second price."), - count("durationMs", "Duration", "ms", 120, 1, 900_000, "Behaviour"), - count("concurrency", "Reserved concurrency", "executions", 1000, 1, 10_000, "Capacity", "Concurrency divided by duration is the most it can serve; beyond that it throttles."), - ] }, - "aws-elasticache": { label: "ElastiCache", family: "aws", role: "cache", vendor: "Redis", icon: "cache", - properties: [size("elasticache", "cache.r6g.large"), count("count", "Shards", "shards", 1, 1, 50), count("replicasPerShard", "Replicas per shard", "replicas", 1, 0, 5, "Resilience"), ratio("hitRate", "Hit rate", 0.85), azs(2)] }, - "aws-rds": { label: "RDS", family: "aws", role: "database", vendor: "Managed SQL", icon: "database", - properties: [ - choice("engine", "Engine", ["PostgreSQL", "MySQL"], "PostgreSQL", "Behaviour"), - size("rds", "db.r5.large"), - count("replicas", "Read replicas", "replicas", 1, 0, 15, "Capacity", "Replicas share the reads; every write still goes to the primary."), - ratio("readRatio", "Read share", 0.8), - toggle("multiAz", "Multi-AZ", 1, "Resilience", "A synchronous standby in another zone. Doubles the primary cost."), - ] }, - "aws-dynamodb": { label: "DynamoDB", family: "aws", role: "nosql", vendor: "Key-value", icon: "nosql", - managed: { capacity: 40_000, pricePerHour: 0, pricePerMillion: 0 }, - properties: [ - choice("capacityMode", "Capacity mode", ["on-demand", "provisioned"], "on-demand", "Capacity", "On-demand bills per request; provisioned bills per hour for the units you reserve."), - count("rcu", "Read units", "RCU", 1000, 1, 100_000, "Capacity"), - count("wcu", "Write units", "WCU", 500, 1, 100_000, "Capacity"), - ratio("readRatio", "Read share", 0.8), - ] }, - "aws-opensearch": { label: "OpenSearch", family: "aws", role: "search", vendor: "Search", icon: "search", - properties: [size("opensearch", "m5.large.search"), count("count", "Data nodes", "nodes", 2, 1, 40), azs(2)] }, - "aws-sqs": { label: "SQS", family: "aws", role: "queue", vendor: "AWS queue", icon: "queue", - managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.4 }, - properties: [choice("queueType", "Queue type", ["standard", "FIFO"], "standard", "Behaviour", "FIFO keeps order but tops out near 3,000 messages/s with batching.")] }, - "aws-kinesis": { label: "Kinesis", family: "aws", role: "stream", vendor: "Data Streams", icon: "stream", - properties: [count("partitions", "Shards", "shards", 2, 1, 500, "Capacity", "Each shard takes about 1,000 records/s."), count("retentionHours", "Retention", "hours", 24, 24, 8760, "Behaviour")] }, - "aws-s3": { label: "S3", family: "aws", role: "storage", vendor: "Object storage", icon: "storage", - managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.4 }, - properties: [choice("storageClass", "Storage class", ["Standard", "Intelligent-Tiering", "Glacier IR"], "Standard")] }, - - // Kubernetes - "k8s-ingress": { label: "Ingress", family: "k8s", role: "balancer", vendor: "ingress-nginx", icon: "balancer", - properties: [size("pod", "500m / 512Mi"), count("count", "Controller replicas", "pods", 2, 1, 20), azs(1)] }, - "k8s-service": { label: "Service", family: "k8s", role: "balancer", vendor: "ClusterIP", icon: "balancer", - managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0 }, - properties: [choice("serviceType", "Type", ["ClusterIP", "NodePort", "LoadBalancer"], "ClusterIP", "Behaviour", "A LoadBalancer Service also rents a cloud load balancer.")] }, - "k8s-deployment": { label: "Deployment", family: "k8s", role: "compute", vendor: "Pods", icon: "compute", - properties: [size("pod", "500m / 512Mi"), count("count", "Replicas", "pods", 2, 1, 200), ...scaling(1, 2, 10, 0.6), azs(1)] }, - "k8s-statefulset": { label: "StatefulSet", family: "k8s", role: "database", vendor: "PostgreSQL", icon: "database", - properties: [size("pod", "2 CPU / 4Gi"), count("replicas", "Read replicas", "pods", 0, 0, 5), ratio("readRatio", "Read share", 0.8)] }, - - // Docker - "docker-proxy": { label: "Reverse proxy", family: "docker", role: "balancer", vendor: "Traefik", icon: "balancer", - properties: [size("container", "1 CPU / 1GB"), count("count", "Containers", "containers", 1, 1, 10)] }, - "docker-container": { label: "App container", family: "docker", role: "compute", vendor: "Container", icon: "compute", - properties: [size("container", "1 CPU / 1GB"), count("count", "Replicas", "containers", 1, 1, 20)] }, - "docker-postgres": { label: "Postgres", family: "docker", role: "database", vendor: "postgres:16", icon: "database", - properties: [size("container", "2 CPU / 2GB"), count("replicas", "Read replicas", "containers", 0, 0, 3), ratio("readRatio", "Read share", 0.8)] }, - - // Linux, one host - "linux-nginx": { label: "nginx", family: "linux", role: "balancer", vendor: "Reverse proxy", icon: "balancer", - properties: [size("host", "2 cores / 4GB")] }, - "linux-service": { label: "App service", family: "linux", role: "compute", vendor: "systemd", icon: "compute", - properties: [size("host", "2 cores / 4GB"), count("count", "Hosts", "hosts", 1, 1, 10)] }, - "linux-postgres": { label: "PostgreSQL", family: "linux", role: "database", vendor: "postgresql.service", icon: "database", - properties: [size("host", "4 cores / 8GB"), count("replicas", "Read replicas", "hosts", 0, 0, 3), ratio("readRatio", "Read share", 0.8)] }, -}; - -const COMPONENT_KINDS = Object.keys(ENTRIES) as ComponentKind[]; -const KIND_SET = new Set(COMPONENT_KINDS); - -export function isComponentKind(value: string): value is ComponentKind { - return KIND_SET.has(value); -} - -export function roleOf(kind: ComponentKind): Role { - return ENTRIES[kind].role; -} - -function portsFor(kind: ComponentKind): PortDef[] { - const role = ENTRIES[kind].role; - const inbound = COMPONENT_KINDS.filter((k) => ROLE_NEXT[ENTRIES[k].role].includes(role)); - const outbound = COMPONENT_KINDS.filter((k) => ROLE_NEXT[role].includes(ENTRIES[k].role)); - const ports: PortDef[] = []; - if (inbound.length > 0) ports.push({ id: "in", dir: "in", accepts: inbound }); - if (outbound.length > 0) ports.push({ id: "out", dir: "out", accepts: outbound }); - return ports; -} - -export const COMPONENT_CATALOG: Record = Object.fromEntries( - COMPONENT_KINDS.map((kind) => [kind, { kind, ...ENTRIES[kind], ports: portsFor(kind) }]), -) as Record; - -export function canConnect(from: ComponentKind, to: ComponentKind): boolean { - return ROLE_NEXT[ENTRIES[from].role].includes(ENTRIES[to].role); -} - -export function kindsInFamily(family: Family): ComponentKind[] { - return COMPONENT_KINDS.filter((k) => ENTRIES[k].family === family); -} - -// ---- size catalogs ----------------------------------------------------------- - -const GENERIC_RULE = { general: "~800 req/s per vCPU at a light mix", compute: "~1,200 req/s per vCPU at a CPU-bound mix", memory: "~600 req/s per vCPU; holds a large working set" }; -const tier = (set: SizeSet, id: string, family: SizeTier["family"], vcpu: number, memoryGb: number, pricePerHour: number, capacityRule = GENERIC_RULE[family]): SizeTier => ({ - id, set, family, vcpu, memoryGb, capacityRule, pricePerHour, -}); - -export const SIZE_CATALOG: SizeTier[] = [ - tier("generic", "general-small", "general", 2, 8, 0.1), - tier("generic", "general-medium", "general", 4, 16, 0.2), - tier("generic", "general-large", "general", 8, 32, 0.4), - tier("generic", "general-xlarge", "general", 16, 64, 0.8), - tier("generic", "compute-small", "compute", 2, 4, 0.12), - tier("generic", "compute-medium", "compute", 4, 8, 0.24), - tier("generic", "compute-large", "compute", 8, 16, 0.48), - tier("generic", "compute-xlarge", "compute", 16, 32, 0.96), - tier("generic", "memory-small", "memory", 2, 16, 0.15), - tier("generic", "memory-medium", "memory", 4, 32, 0.3), - tier("generic", "memory-large", "memory", 8, 64, 0.6), - tier("generic", "memory-xlarge", "memory", 16, 128, 1.2), - - tier("ec2", "t3.medium", "general", 2, 4, 0.0416, "burstable; ~800 req/s per vCPU while it has credits"), - tier("ec2", "m5.large", "general", 2, 8, 0.096), - tier("ec2", "m5.xlarge", "general", 4, 16, 0.192), - tier("ec2", "c5.large", "compute", 2, 4, 0.085), - tier("ec2", "c5.xlarge", "compute", 4, 8, 0.17), - tier("ec2", "c5.2xlarge", "compute", 8, 16, 0.34), - tier("ec2", "r5.large", "memory", 2, 16, 0.126), - - tier("fargate", "0.25 vCPU / 0.5 GB", "general", 0.25, 0.5, 0.0123), - tier("fargate", "0.5 vCPU / 1 GB", "general", 0.5, 1, 0.0247), - tier("fargate", "1 vCPU / 2 GB", "general", 1, 2, 0.0494), - tier("fargate", "2 vCPU / 4 GB", "general", 2, 4, 0.0988), - tier("fargate", "4 vCPU / 8 GB", "general", 4, 8, 0.1975), - - tier("rds", "db.t3.medium", "memory", 2, 4, 0.068), - tier("rds", "db.m5.large", "memory", 2, 8, 0.171), - tier("rds", "db.r5.large", "memory", 2, 16, 0.24), - tier("rds", "db.r5.xlarge", "memory", 4, 32, 0.48), - tier("rds", "db.r5.2xlarge", "memory", 8, 64, 0.96), - - tier("elasticache", "cache.t3.small", "memory", 2, 1.37, 0.034, "~15,000 ops/s per vCPU"), - tier("elasticache", "cache.m5.large", "memory", 2, 6.38, 0.156, "~15,000 ops/s per vCPU"), - tier("elasticache", "cache.r6g.large", "memory", 2, 13.07, 0.206, "~15,000 ops/s per vCPU"), - tier("elasticache", "cache.r6g.xlarge", "memory", 4, 26.32, 0.411, "~15,000 ops/s per vCPU"), - - tier("opensearch", "t3.medium.search", "memory", 2, 4, 0.073, "~300 queries/s per vCPU"), - tier("opensearch", "m5.large.search", "memory", 2, 8, 0.142, "~300 queries/s per vCPU"), - tier("opensearch", "r5.large.search", "memory", 2, 16, 0.186, "~300 queries/s per vCPU"), - - tier("pod", "250m / 256Mi", "general", 0.25, 0.25, 0.01, "CPU request; ~800 req/s per full core"), - tier("pod", "500m / 512Mi", "general", 0.5, 0.5, 0.02, "CPU request; ~800 req/s per full core"), - tier("pod", "1 CPU / 1Gi", "general", 1, 1, 0.04, "CPU request; ~800 req/s per full core"), - tier("pod", "2 CPU / 4Gi", "general", 2, 4, 0.09, "CPU request; ~800 req/s per full core"), - - tier("container", "0.5 CPU / 512MB", "general", 0.5, 0.5, 0.02, "--cpus limit; ~800 req/s per full core"), - tier("container", "1 CPU / 1GB", "general", 1, 1, 0.04, "--cpus limit; ~800 req/s per full core"), - tier("container", "2 CPU / 2GB", "general", 2, 2, 0.08, "--cpus limit; ~800 req/s per full core"), - - tier("host", "1 core / 2GB", "general", 1, 2, 0.02, "~800 req/s per core"), - tier("host", "2 cores / 4GB", "general", 2, 4, 0.04, "~800 req/s per core"), - tier("host", "4 cores / 8GB", "general", 4, 8, 0.08, "~800 req/s per core"), - tier("host", "8 cores / 16GB", "general", 8, 16, 0.16, "~800 req/s per core"), -]; - -export function sizesFor(set: SizeSet): SizeTier[] { - return SIZE_CATALOG.filter((t) => t.set === set); -} +export * from "../shared/lab/engine/catalog"; diff --git a/packages/learning-ui/src/labs/challenge.ts b/packages/learning-ui/src/labs/challenge.ts index dafc9552..b053376e 100644 --- a/packages/learning-ui/src/labs/challenge.ts +++ b/packages/learning-ui/src/labs/challenge.ts @@ -1,290 +1 @@ -// The run behind a visual challenge: pure and server-importable like the model it -// wraps. It takes a board and plays it through the challenge's scenarios (peak -// traffic, then each fault), asks the tiered-architecture model for the numbers in -// every one, and turns them into a pass or fail per check, each with the measured -// value, the target and, when it fails, the reason. -// -// Functional checks are about structure: can a request travel the path the feature -// needs? Non-functional checks are measurements: latency, how much is still served -// when something dies, whether queued work is all counted, and cost. - -import type { Board, BoardNode, ChallengeDef, ChallengeScenario, CheckDef, CheckMetric, Fault, HldLabSpec } from "./types"; -import type { ComponentKind, Role } from "./catalog"; -import { COMPONENT_CATALOG, roleOf } from "./catalog"; -import { runTieredModel, type ModelOptions, type ModelResult, type Targets, type TierLoad } from "./tiered-architecture"; - -export const STEADY: ChallengeScenario = { - id: "steady", - title: "Peak traffic", - story: "Everything is healthy and traffic is at its busiest.", - faults: [], -}; - -export interface CheckResult { - id: string; - kind: "functional" | "non-functional"; - label: string; - pass: boolean; - /** What the run found, with its unit. */ - measured: string; - /** What it had to be. */ - target: string; - /** Why it failed and what to look at; absent when it passed. */ - reason?: string; - /** The scenario the number comes from, so the board can replay it. */ - scenario: string; -} - -export interface PhaseReport { - id: string; - title: string; - story: string; - load: number; - /** The board as the scenario left it (fault applied). */ - board: Board; - /** The components the fault took down or thinned out. */ - hit: string[]; - /** False when the fault named a part this design does not have. */ - applicable: boolean; - /** The part the fault names when the design has none: "cache". */ - missing?: string; - result: ModelResult; -} - -export interface ChallengeReport { - phases: PhaseReport[]; - checks: CheckResult[]; - passed: number; - total: number; - allPass: boolean; -} - -const labelOf = (kind: ComponentKind) => COMPONENT_CATALOG[kind].label; -// Lowercases the first letter of a label for use mid-sentence, but leaves acronyms such as CDN alone. -const lower = (text: string) => (/^[A-Z]{2}/.test(text) ? text : text.charAt(0).toLowerCase() + text.slice(1)); -const pct = (n: number) => `${(Math.floor(n * 10000) / 100).toFixed(2)}%`; -const roleLabel = (role: Role) => Object.values(COMPONENT_CATALOG).find((c) => c.role === role)?.label ?? role; -const perSec = (n: number) => `${Math.round(n).toLocaleString("en-US")}/s`; - -function metricText(metric: CheckMetric, v: number): string { - switch (metric) { - case "p99": return `${Math.round(v)} ms`; - case "capacity": return perSec(v); - case "served": return `${(Math.floor(v * 1000) / 10).toFixed(1)}%`; - case "availability": return pct(v); - case "cost": return `$${v.toFixed(2)}/h`; - } -} -const targetText = (metric: CheckMetric, op: "<=" | ">=", v: number) => - `${op === "<=" ? "at most" : "at least"} ${metric === "availability" ? pct(v) : metricText(metric, v)}`; - -// ---- faults ------------------------------------------------------------------- - -function applyFaults(board: Board, faults: Fault[], steady: ModelResult): { board: Board; hit: string[]; applicable: boolean } { - const nodes: BoardNode[] = board.nodes.map((n) => ({ ...n, props: { ...(n.props ?? {}) } })); - const hit: string[] = []; - for (const fault of faults) { - const targets = nodes.filter((n) => roleOf(n.kind) === fault.role); - if (targets.length === 0) continue; - if (fault.type === "down") { - for (const n of targets) { n.props!.down = 1; hit.push(n.id); } - } else { - const first = targets[0]!; - const units = steady.tiers.find((t) => t.id === first.id)?.units ?? 1; - if (units <= 1) first.props!.down = 1; - else { first.props!.autoscale = 0; first.props!.count = units - 1; } - hit.push(first.id); - } - } - return { board: { ...board, nodes }, hit, applicable: hit.length > 0 }; -} - -// ---- functional checks: can a request travel the path? --------------------------- - -function reachFrom(board: Board, starts: string[]): Set { - const next = new Map(); - for (const e of board.edges) next.set(e.from, [...(next.get(e.from) ?? []), e.to]); - const seen = new Set(); - const queue = [...starts]; - while (queue.length > 0) { - const id = queue.shift()!; - for (const to of next.get(id) ?? []) if (!seen.has(to)) { seen.add(to); queue.push(to); } - } - return seen; -} - -/** Walks the roles in order. Returns the labels found so far and the first role that has no way in. */ -export function followChain(board: Board, chain: Role[]): { trail: string[]; missing?: Role } { - const byId = new Map(board.nodes.map((n) => [n.id, n])); - let frontier = board.nodes.filter((n) => roleOf(n.kind) === chain[0] && !n.props?.down).map((n) => n.id); - const trail: string[] = frontier.length > 0 ? [labelOf(byId.get(frontier[0]!)!.kind)] : []; - if (frontier.length === 0) return { trail, missing: chain[0] }; - for (const role of chain.slice(1)) { - const reached = reachFrom(board, frontier); - frontier = [...reached].filter((id) => roleOf(byId.get(id)!.kind) === role && !byId.get(id)!.props?.down); - if (frontier.length === 0) return { trail, missing: role }; - trail.push(labelOf(byId.get(frontier[0]!)!.kind)); - } - return { trail }; -} - -const ROLE_NAME: Partial> = { - client: "a client", compute: "an app server", database: "a database", queue: "a queue", worker: "a worker", cache: "a cache", balancer: "a load balancer", -}; -const roleName = (role: Role) => ROLE_NAME[role] ?? `a ${role}`; - -function pathCheck(def: Extract, board: Board): CheckResult { - const { trail, missing } = followChain(board, def.chain); - if (missing !== undefined && def.inlineIfNo && !board.nodes.some((n) => roleOf(n.kind) === def.inlineIfNo)) { - return { - id: def.id, kind: def.kind, label: def.label, pass: true, scenario: "steady", target: def.target, - measured: `saved during the request (inline), no ${lower(roleLabel(def.inlineIfNo))}`, - }; - } - const pass = missing === undefined; - const last = trail.at(-1); - return { - id: def.id, kind: def.kind, label: def.label, pass, scenario: "steady", target: def.target, - measured: pass ? trail.join(" > ") : trail.length > 0 ? `${trail.join(" > ")} > ?` : "no path", - reason: pass ? undefined : trail.length === 0 - ? `There is no ${missing === "client" ? "client" : roleName(missing!).replace(/^an? /, "")} on the board.` - : `The path stops at ${lower(last!)}: link it to ${roleName(missing!)}.`, - }; -} - -// ---- non-functional checks: measured in a scenario --------------------------------- - -function worstTier(result: ModelResult): TierLoad | undefined { - return [...result.tiers].filter((t) => t.reachable && !t.managed).sort((a, b) => b.utilisation - a.utilisation)[0]; -} -const busy = (t: TierLoad) => `${labelOf(t.kind)} is ${Math.round(t.utilisation * 100)}% busy`; - -function measure(metric: CheckMetric, r: ModelResult, load: number): number { - switch (metric) { - case "p99": return r.p99Ms; - case "capacity": return r.capacityCeiling; - case "served": return load > 0 ? Math.min(1, r.capacityCeiling / load) : 1; - case "availability": return r.availability; - case "cost": return r.costPerHour; - } -} - -function whyMetricFailed(metric: CheckMetric, r: ModelResult, scenario: PhaseReport): string { - const worst = worstTier(r); - const during = scenario.id === "steady" ? "" : ` while ${lower(scenario.title)}`; - if (r.failure) return r.failure; - switch (metric) { - case "p99": { - const slow = [...r.tiers].filter((t) => t.waitMs > 0.5).sort((x, y) => y.waitMs - x.waitMs).slice(0, 2); - return slow.length > 0 - ? `Requests wait in line at ${slow.map((t) => `the ${lower(labelOf(t.kind))} (${Math.round(t.utilisation * 100)}% busy, +${Math.round(t.waitMs)} ms)`).join(" and ")}${during}. Give them more capacity, or take load off them.` - : "The path itself is too slow: fewer hops would help."; - } - case "capacity": - case "served": - return worst ? `${busy(worst)}${during}, so it cannot serve the whole load. Add machines, read-only copies or a cache in front of it.` : "Nothing on the board can serve the load."; - case "availability": { - const role = r.weakest?.role; - return role ? `${roleLabel(role)} is the weak link (${pct(r.weakest!.availability)}): run more than one, or in two zones.` : "Add redundancy."; - } - case "cost": { - const priciest = [...r.tiers].sort((a, b) => b.cost - a.cost)[0]; - return priciest ? `${labelOf(priciest.kind)} costs the most ($${priciest.cost.toFixed(2)}/h). Try a smaller size or fewer machines.` : "Over budget."; - } - } -} - -function metricCheck(def: Extract, phases: Map): CheckResult { - const phase = phases.get(def.scenario) ?? phases.get("steady")!; - const value = measure(def.metric, phase.result, phase.load); - const pass = def.op === "<=" ? value <= def.value : value >= def.value; - return { - id: def.id, kind: def.kind, label: def.label, pass, scenario: phase.id, - measured: metricText(def.metric, value) + (phase.applicable || phase.id === "steady" ? "" : ` (no ${phase.missing} to lose)`), - target: targetText(def.metric, def.op, def.value), - reason: pass ? undefined : whyMetricFailed(def.metric, phase.result, phase), - }; -} - -function drainCheck(def: Extract, steady: PhaseReport, scenarioId: string, inlineClicks: boolean, share = 1): CheckResult { - const { board, result, load } = steady; - const queue = board.nodes.find((n) => roleOf(n.kind) === "queue" && result.tiers.find((t) => t.id === n.id)?.reachable); - const items = def.items ?? "clicks"; - const done = def.done ?? "counted"; - const Items = items.charAt(0).toUpperCase() + items.slice(1); - const target = `no ${items} lost, all ${done} within ${def.maxDrainSeconds} s of the worker coming back`; - const base = { id: def.id, kind: def.kind, label: def.label, scenario: scenarioId, target }; - if (!queue && inlineClicks && !board.nodes.some((n) => roleOf(n.kind) === "queue")) { - return { ...base, pass: true, measured: `no worker to lose: ${items} are saved during the request (inline)` }; - } - if (!queue) { - // With no queue there is no link to read the rate from, so take the queue's share of the stream. - const lost = Math.round(load * share * def.outageSeconds); - return { ...base, pass: false, measured: `${lost.toLocaleString("en-US")} ${items} lost in ${def.outageSeconds} s`, reason: `${Items} have nowhere to wait while the worker is down. Put a queue between the app server and the worker.` }; - } - const workers = board.edges.filter((e) => e.from === queue.id).map((e) => result.tiers.find((t) => t.id === e.to)).filter((t): t is TierLoad => !!t && roleOf(t.kind) === "worker"); - if (workers.length === 0) { - return { ...base, pass: false, measured: `${items} pile up and are never ${done}`, reason: "The queue has no worker. Link the queue to a worker, and the worker to where it saves its work." }; - } - const arriving = board.edges.filter((e) => e.to === queue.id).reduce((sum, e) => sum + (result.edgeFlows[`${e.from}>${e.to}`] ?? 0), 0); - const capacity = workers.reduce((sum, w) => sum + w.capacity, 0); - const spare = capacity - arriving; - const backlog = Math.round(arriving * def.outageSeconds); - if (spare <= 0) { - return { ...base, pass: false, measured: `${backlog.toLocaleString("en-US")} ${items} waiting, never all ${done}`, reason: `Workers handle ${perSec(capacity)} but ${items} arrive at ${perSec(arriving)}: they can never catch up. Add workers or a bigger size.` }; - } - const drain = Math.ceil(backlog / spare); - const pass = drain <= def.maxDrainSeconds; - return { - ...base, pass, measured: `${backlog.toLocaleString("en-US")} ${items} waiting, all ${done} after ${drain} s`, - reason: pass ? undefined : `Workers have only ${perSec(spare)} to spare, so ${backlog.toLocaleString("en-US")} waiting ${items} take ${drain} s. Add workers or a bigger size.`, - }; -} - -// ---- the run ---------------------------------------------------------------------- - -/** Labs with no authored challenge are scored on their targets, as non-functional checks. */ -export function challengeFor(spec: HldLabSpec): ChallengeDef { - if (spec.challenge) return spec.challenge; - const level = spec.levels[0]; - const t = level?.targets ?? {}; - const checks: CheckDef[] = []; - const add = (id: string, label: string, metric: CheckMetric, op: "<=" | ">=", value?: number) => { - if (value != null) checks.push({ type: "metric", id, kind: "non-functional", label, scenario: "steady", metric, op, value }); - }; - add("capacity", "Serves the load", "capacity", ">=", t.rps); - add("p99", "Slowest 1 in 100 requests (p99)", "p99", "<=", t.p99Ms); - add("availability", "Stays up (availability)", "availability", ">=", t.availability); - add("cost", "Cost per hour", "cost", "<=", t.budgetPerHour); - return { peakLoad: level?.load ?? 1000, scenarios: [], checks }; -} - -/** The model run for a lab: the same options the challenge's own scenarios use, so every number agrees. */ -export function runModel(spec: HldLabSpec, board: Board, load: number, targets: Targets = {}): ModelResult { - const options: ModelOptions = { - inlineWrites: Boolean(spec.challenge?.inlineClicks) && !board.nodes.some((n) => roleOf(n.kind) === "queue"), - shares: spec.challenge?.shares, - }; - return runTieredModel(board, load, targets, options); -} - -/** Plays the board through the challenge. `board` must already carry the learner's properties. */ -export function runChallenge(spec: HldLabSpec, board: Board, load: number): ChallengeReport { - const challenge = challengeFor(spec); - const steadyResult = runModel(spec, board, load); - const phases: PhaseReport[] = [{ ...STEADY, load, board, hit: [], applicable: true, result: steadyResult }]; - for (const scenario of challenge.scenarios) { - const { board: faulted, hit, applicable } = applyFaults(board, scenario.faults, steadyResult); - const missing = applicable ? undefined : lower(roleLabel(scenario.faults[0]?.role ?? "compute")); - phases.push({ id: scenario.id, title: scenario.title, story: scenario.story, load, board: faulted, hit, applicable, missing, result: runModel(spec, faulted, load) }); - } - const byId = new Map(phases.map((p) => [p.id, p])); - const steady = phases[0]!; - const checks: CheckResult[] = challenge.checks.map((def) => { - if (def.type === "path") return pathCheck(def, board); - if (def.type === "drain") return drainCheck(def, steady, challenge.scenarios.find((s) => s.faults.some((f) => f.type === "down" && f.role === "worker"))?.id ?? "steady", Boolean(challenge.inlineClicks), challenge.shares?.queue ?? 1); - return metricCheck(def, byId); - }); - const passed = checks.filter((c) => c.pass).length; - return { phases, checks, passed, total: checks.length, allPass: passed === checks.length }; -} +export * from "../shared/lab/engine/challenge"; diff --git a/packages/learning-ui/src/labs/tiered-architecture.ts b/packages/learning-ui/src/labs/tiered-architecture.ts index 8f0deb84..c8d20fca 100644 --- a/packages/learning-ui/src/labs/tiered-architecture.ts +++ b/packages/learning-ui/src/labs/tiered-architecture.ts @@ -1,537 +1 @@ -// The tiered-architecture model: the engine behind the lab board. Pure and -// server-importable (no DOM, no React), so a graded lab can run it on the server. -// -// From a board and an offered load it routes requests down the links, evaluates -// every component by its role and configuration (instance fleets, autoscaling, -// zones, read replicas, managed services billed per request, Lambda concurrency, -// rate limits, queues), and returns utilisation, the capacity ceiling, p50/p99 -// latency with the queueing knee, availability and cost, scored against targets. -// -// Numbers are illustrative. The rules below are stated so a "how this is -// calculated" panel can show them. - -import type { Board, BoardNode } from "./types"; -import type { ComponentKind, Role, SizeTier } from "./catalog"; -import { COMPONENT_CATALOG, SIZE_CATALOG, roleOf } from "./catalog"; - -const PER_VCPU: Record = { general: 800, compute: 1200, memory: 600 }; -/** Roles that serve far more, or far less, per vCPU than a typical app server. */ -const ROLE_RATE: Partial> = { cache: 15_000, search: 300, nosql: 2_000 }; -const NETWORK_MS = 10; -/** Chance a single Availability Zone is up. */ -const AZ_AVAIL = 0.9995; -/** Regional managed services are spread across zones by the provider. */ -const MANAGED_AVAIL = 0.9999; - -const SERVICE_MS: Record = { - client: 0, dns: 1, cdn: 2, firewall: 1, limiter: 1, balancer: 2, gateway: 5, - compute: 20, function: 0, worker: 15, cache: 1, database: 8, nosql: 5, search: 25, - queue: 5, stream: 10, storage: 20, -}; -const SINGLE_AVAIL: Partial> = { - balancer: 0.9995, gateway: 0.9995, compute: 0.99, worker: 0.99, cache: 0.999, - database: 0.999, nosql: 0.9995, search: 0.999, stream: 0.999, -}; - -export interface TierLoad { - id: string; - kind: ComponentKind; - capacity: number; - utilisation: number; - down: boolean; - reachable: boolean; - /** Instances actually running, after autoscaling. */ - units: number; - /** Managed services scale for you; their utilisation is rarely the story. */ - managed: boolean; - /** A short line for the card: autoscaled, throttling, backlog, and so on. */ - note?: string; - /** What this component costs per hour whether or not it is serving. */ - cost: number; - /** Milliseconds a request spends waiting in line here, on top of its service time. Zero off the request path. */ - waitMs: number; - /** For a cache: what it was asked, what it answered itself, and what went on to the database. */ - cacheStats?: { hitRate: number; reads: number; hits: number; misses: number }; -} - -/** One labelled share of the traffic on a link, such as "cache misses" or "click writes". */ -export interface EdgePart { - label: string; - rate: number; -} - -/** Optional rules a lab can switch on for the whole run. */ -export interface ModelOptions { - /** - * Every request an app server serves also writes one row (a click) to the database - * before it answers. Labs turn this on when the board has no queue to carry the clicks. - */ - inlineWrites?: boolean; - /** - * The share of requests that send work to parts of a role, for side jobs that only - * some requests need: { queue: 0.1 } means 1 request in 10 leaves a job in the queue. - * Applied wherever a part of another role sends to that role, so it holds however the - * learner links the board. A role with no share gets the whole stream. - */ - shares?: Partial>; -} - -export interface Targets { - rps?: number; - p99Ms?: number; - availability?: number; - budgetPerHour?: number; -} - -export interface ModelResult { - capacityCeiling: number; - p50Ms: number; - p99Ms: number; - availability: number; - costPerHour: number; - tiers: TierLoad[]; - pass: { rps: boolean; p99: boolean; availability: boolean; budget: boolean }; - allPass: boolean; - /** Why the design is broken, when a component is down or unlinked. */ - failure?: string; - /** Request rate on each live link, keyed "from>to". */ - edgeFlows: Record; - /** What the traffic on a link is made of, where that is worth saying (cache reads, misses, writes). */ - edgeParts: Record; - /** Requests rejected by rate limits and throttles, per second. */ - dropped: number; - /** Requests filtered out by firewalls, per second. */ - blocked: number; - /** How fast queued work piles up because consumers are too slow, per second. */ - backlog: number; - /** The role on the request path with the lowest availability, for "add redundancy here". */ - weakest?: { role: Role; availability: number }; -} - -// ---- reading a node's configuration ------------------------------------------- - -function propOf(node: BoardNode, key: string): number | string | undefined { - const own = node.props?.[key]; - if (own !== undefined) return own; - return COMPONENT_CATALOG[node.kind].properties.find((p) => p.id === key)?.default; -} -function num(node: BoardNode, key: string, fallback: number): number { - const v = propOf(node, key); - return typeof v === "number" ? v : fallback; -} -function str(node: BoardNode, key: string, fallback: string): string { - const v = propOf(node, key); - return typeof v === "string" ? v : fallback; -} -function tierOf(node: BoardNode): SizeTier { - const id = propOf(node, "size"); - return SIZE_CATALOG.find((t) => t.id === id) ?? SIZE_CATALOG[0]; -} -const isDown = (node: BoardNode) => Boolean(node.props?.down); -const rate = (n: number) => Math.round(n).toLocaleString("en-US"); - -/** A fleet of `units` spread over `zones`; it is up while any zone has a live instance. */ -function fleetAvailability(single: number, units: number, zones: number): number { - const n = Math.max(1, Math.round(zones)); - const perZone = Math.max(1, units / n); - const zone = AZ_AVAIL * (1 - Math.pow(1 - single, perZone)); - return 1 - Math.pow(1 - zone, n); -} - -// ---- routing -------------------------------------------------------------------- - -/** Nodes a request can reach from any live client, following the links and skipping down nodes. */ -function reachableFrom(board: Board): Set { - const byId = new Map(board.nodes.map((n) => [n.id, n])); - const next = new Map(); - for (const e of board.edges) next.set(e.from, [...(next.get(e.from) ?? []), e.to]); - const seen = new Set(); - const queue = board.nodes.filter((n) => n.kind === "client" && !isDown(n)).map((n) => n.id); - for (const id of queue) seen.add(id); - while (queue.length > 0) { - const id = queue.shift()!; - for (const to of next.get(id) ?? []) { - const node = byId.get(to); - if (node && !isDown(node) && !seen.has(to)) { - seen.add(to); - queue.push(to); - } - } - } - return seen; -} - -/** Live links between reachable nodes, deduplicated, as parent to children and child to parents. */ -function liveLinks(board: Board, reachable: Set) { - const children = new Map(); - const parents = new Map(); - for (const e of board.edges) { - if (!reachable.has(e.from) || !reachable.has(e.to) || e.from === e.to) continue; - const kids = children.get(e.from) ?? []; - if (kids.includes(e.to)) continue; - children.set(e.from, [...kids, e.to]); - parents.set(e.to, [...(parents.get(e.to) ?? []), e.from]); - } - return { children, parents }; -} - -/** Reachable nodes in topological order (Kahn), so load and latency flow parent before child. */ -function topoOrder(reachable: Set, children: Map, parents: Map): string[] { - const indegree = new Map([...reachable].map((id) => [id, (parents.get(id) ?? []).length])); - const queue = [...reachable].filter((id) => indegree.get(id) === 0); - const order: string[] = []; - while (queue.length > 0) { - const id = queue.shift()!; - order.push(id); - for (const kid of children.get(id) ?? []) { - indegree.set(kid, (indegree.get(kid) ?? 1) - 1); - if (indegree.get(kid) === 0) queue.push(kid); - } - } - return order; -} - -const ASYNC_ROLES = new Set(["queue", "stream"]); - -/** Nodes on the synchronous request path: reachable without passing through a queue or stream. */ -function synchronous(order: string[], byId: Map, children: Map): Set { - const seen = new Set(order.filter((id) => byId.get(id)!.kind === "client")); - const queue = [...seen]; - while (queue.length > 0) { - const id = queue.shift()!; - if (ASYNC_ROLES.has(roleOf(byId.get(id)!.kind))) continue; - for (const kid of children.get(id) ?? []) { - if (!seen.has(kid)) { - seen.add(kid); - queue.push(kid); - } - } - } - return seen; -} - -/** The most a node lets through per second; above it, requests are rejected. */ -function limitOf(node: BoardNode): number | undefined { - if (node.kind === "rate-limiter" || node.kind === "aws-api-gateway") return num(node, "limit", Infinity); - if (node.kind === "aws-lambda") return lambdaCapacity(node); - return undefined; -} -/** Share of what a node serves that continues downstream (CDN misses, traffic a firewall lets in). */ -function passOn(node: BoardNode): number { - const role = roleOf(node.kind); - if (role === "cdn") return 1 - num(node, "hitRate", 0); - if (role === "firewall") return 1 - num(node, "blockRate", 0); - // A cache answers its hits itself; only the misses go on to a database linked behind it. - if (role === "cache") return 1 - num(node, "hitRate", 0); - return 1; -} -function lambdaCapacity(node: BoardNode): number { - return (num(node, "concurrency", 1000) * 1000) / Math.max(1, num(node, "durationMs", 120)); -} - -// ---- evaluating one component ---------------------------------------------------- - -interface Evaluation { - capacity: number; - units: number; - cost: number; - serviceMs: number; - availability: number; - /** Whether requests wait in line as it gets busy (the p99 knee), or are throttled instead. */ - queueing: boolean; - managed: boolean; - note?: string; -} - -function evaluate(node: BoardNode, flow: number, inlineWrites = 0): Evaluation { - const def = COMPONENT_CATALOG[node.kind]; - const role = def.role; - - if (node.kind === "aws-lambda") { - const duration = Math.max(1, num(node, "durationMs", 120)); - const memoryGb = Number(str(node, "memoryMb", "512")) / 1024; - const capacity = lambdaCapacity(node); - const cost = flow * 3600 * (0.2 / 1e6 + (duration / 1000) * memoryGb * 0.0000166667); - const note = flow > capacity ? `throttling ${rate(flow - capacity)}/s` : flow > 0 ? `~${rate(Math.ceil((flow * duration) / 1000))} running at once` : undefined; - return { capacity, units: 1, cost, serviceMs: duration, availability: MANAGED_AVAIL, queueing: false, managed: true, note }; - } - - if (node.kind === "aws-dynamodb") { - const reads = num(node, "readRatio", 0.8); - if (str(node, "capacityMode", "on-demand") === "provisioned") { - const rcu = num(node, "rcu", 1000); - const wcu = num(node, "wcu", 500); - const util = Math.max((flow * reads) / (rcu * 2), (flow * (1 - reads)) / wcu); - return { - capacity: util > 0 ? flow / util : rcu * 2 + wcu, units: 1, cost: rcu * 0.00013 + wcu * 0.00065, - serviceMs: 5, availability: MANAGED_AVAIL, queueing: false, managed: true, - note: util > 1 ? "throttled: raise RCU/WCU or go on-demand" : undefined, - }; - } - return { - capacity: 40_000, units: 1, cost: (flow * 3600 * (reads * 0.25 + (1 - reads) * 1.25)) / 1e6, - serviceMs: 5, availability: MANAGED_AVAIL, queueing: false, managed: true, - }; - } - - if (role === "stream") { - const shards = num(node, "partitions", 2); - const aws = def.family === "aws"; - return { - capacity: shards * 1000, units: shards, cost: shards * 0.015 + (aws ? (flow * 3600 * 0.014) / 1e6 : 0), - serviceMs: SERVICE_MS.stream, availability: aws ? MANAGED_AVAIL : fleetAvailability(0.999, shards, 1), - queueing: false, managed: aws, note: flow > shards * 1000 ? "producers throttled: add shards" : undefined, - }; - } - - if (def.managed) { - let capacity = def.managed.capacity; - let perMillion = def.managed.pricePerMillion; - if (node.kind === "aws-api-gateway" && str(node, "apiType", "HTTP") === "REST") perMillion = 3.5; - if (node.kind === "aws-sqs" && str(node, "queueType", "standard") === "FIFO") capacity = 3000; - const hourly = node.kind === "k8s-service" && str(node, "serviceType", "ClusterIP") === "LoadBalancer" ? 0.0225 : def.managed.pricePerHour; - const limit = limitOf(node); - if (limit != null) capacity = Math.min(capacity, limit); - const hasZones = def.properties.some((p) => p.id === "azs"); - const availability = hasZones ? fleetAvailability(0.99999, 1, num(node, "azs", 2)) : MANAGED_AVAIL; - const note = limit != null && flow > limit ? `rejecting ${rate(flow - limit)}/s` : undefined; - return { - capacity, units: 1, cost: hourly + (flow * 3600 * perMillion) / 1e6, - serviceMs: SERVICE_MS[role] + (node.kind === "aws-api-gateway" ? 5 : 0), - availability, queueing: false, managed: true, note, - }; - } - - // Instance-based: a fleet of servers of one size. - const tier = tierOf(node); - const perUnit = tier.vcpu * (ROLE_RATE[role] ?? PER_VCPU[tier.family]); - const single = SINGLE_AVAIL[role] ?? 0.99; - - if (role === "database") { - const replicas = num(node, "replicas", 0); - const reads = num(node, "readRatio", 0.8); - const multiAz = num(node, "multiAz", 0) > 0; - // Every write goes to the primary; reads spread over the primary and its replicas. - // Inline writes are all writes: they are part of the flow but never reads. - const other = Math.max(0, flow - inlineWrites); - const util = Math.max(other * (1 - reads) + inlineWrites, (other * reads) / (1 + replicas)) / perUnit; - const parts = [replicas > 0 ? `${replicas} read replica${replicas === 1 ? "" : "s"}` : null, multiAz ? "Multi-AZ" : null].filter(Boolean); - return { - capacity: util > 0 ? flow / util : perUnit * (1 + replicas), units: 1 + replicas, - cost: tier.pricePerHour * ((multiAz ? 2 : 1) + replicas), serviceMs: SERVICE_MS.database, - availability: fleetAvailability(single, 1, multiAz ? 2 : 1), queueing: true, managed: false, - note: parts.length > 0 ? parts.join(", ") : undefined, - }; - } - - let units = node.kind === "load-balancer" ? num(node, "zones", 1) : num(node, "count", 1); - let note: string | undefined; - if (num(node, "autoscale", 0) > 0) { - const min = Math.max(1, num(node, "minCount", 1)); - const max = Math.max(min, num(node, "maxCount", 10)); - const target = Math.min(1, Math.max(0.05, num(node, "targetUtil", 0.6))); - units = Math.min(max, Math.max(min, Math.ceil(flow / (perUnit * target) - 1e-9))); - note = units === max && flow / (perUnit * units) > target ? `at max ${max}: raise the max or the size` : `autoscaled to ${units} (${min} to ${max})`; - } - - let cost = tier.pricePerHour * units; - let availabilityUnits = units; - if (node.kind === "aws-elasticache") { - const replicasPerShard = num(node, "replicasPerShard", 1); - cost = tier.pricePerHour * units * (1 + replicasPerShard); - availabilityUnits = 1 + replicasPerShard; - } - const zones = node.kind === "load-balancer" ? units : num(node, "azs", 1); - return { - capacity: perUnit * units, units, cost, serviceMs: SERVICE_MS[role], - availability: fleetAvailability(single, availabilityUnits, zones), queueing: true, managed: false, note, - }; -} - -// ---- the model ------------------------------------------------------------------- - -export function runTieredModel(board: Board, load: number, targets: Targets, options: ModelOptions = {}): ModelResult { - const byId = new Map(board.nodes.map((n) => [n.id, n])); - const reachable = reachableFrom(board); - const { children, parents } = liveLinks(board, reachable); - const order = topoOrder(reachable, children, parents); - const sync = synchronous(order, byId, children); - - // Load enters at the live clients and flows down the links. A node first applies - // its limit (rejecting the excess), then passes on what continues (CDN misses, - // traffic the firewall lets in). Parallel children with the same role share it; - // different roles are different services and each see the whole stream; a - // database or key-value store beside a cache only sees the cache misses. - const incoming = new Map(); - const inlineWrites = new Map(); - const edgeFlows: Record = {}; - const edgeParts: Record = {}; - const addPart = (key: string, label: string, rate: number) => { (edgeParts[key] ??= []).push({ label, rate }); }; - let dropped = 0; - let blocked = 0; - const clients = order.filter((id) => byId.get(id)!.kind === "client"); - for (const id of clients) incoming.set(id, load / clients.length); - for (const id of order) { - const node = byId.get(id)!; - const flowIn = incoming.get(id) ?? 0; - const limit = limitOf(node); - const served = limit != null ? Math.min(flowIn, limit) : flowIn; - dropped += flowIn - served; - const out = served * passOn(node); - if (roleOf(node.kind) === "firewall") blocked += served - out; - - const kids = (children.get(id) ?? []).map((k) => byId.get(k)!); - const cache = kids.find((n) => roleOf(n.kind) === "cache"); - const missRate = cache ? 1 - num(cache, "hitRate", 0) : 1; - // Read-through: a store that the cache itself links to is loaded by the cache on a miss, - // so the app server's own link to it carries no reads (it never counts twice). - const behindCache = new Set(cache ? children.get(cache.id) ?? [] : []); - const byRole = new Map(); - for (const kid of kids) { - if (behindCache.has(kid.id)) continue; - byRole.set(roleOf(kid.kind), [...(byRole.get(roleOf(kid.kind)) ?? []), kid.id]); - } - for (const [role, ids] of byRole) { - const stores = role === "database" || role === "nosql"; - // A worker batches its writes: one trip to the store carries `batchSize` events. - const batch = node.kind === "worker" && stores ? Math.max(1, num(node, "batchSize", 1)) : 1; - // A side job only some requests need (an alert, an index update) carries its share of the stream. - const part = role !== roleOf(node.kind) ? (options.shares?.[role] ?? 1) : 1; - const share = (stores ? (out * missRate) / batch : out) * part; - for (const k of ids) { - const key = `${id}>${k}`; - const rate = share / ids.length; - incoming.set(k, (incoming.get(k) ?? 0) + rate); - edgeFlows[key] = (edgeFlows[key] ?? 0) + rate; - if (part < 1) addPart(key, `${Math.round(part * 1000) / 10}% of requests send work here`, rate); - if (role === "cache") addPart(key, `reads, ${Math.round(num(byId.get(k)!, "hitRate", 0) * 100)}% answered by the cache`, rate); - else if (stores && node.kind === "worker" && batch > 1) addPart(key, `writes, ${batch} per trip`, rate); - else if (stores && cache) addPart(key, "cache misses", rate); - else if (stores && roleOf(node.kind) === "cache") addPart(key, "cache misses", rate); - } - } - if (options.inlineWrites && roleOf(node.kind) === "compute") { - // The click write goes to the store whether the app server reaches it directly or through its cache. - const direct = kids.filter((k) => roleOf(k.kind) === "database"); - const through = (cache ? children.get(cache.id) ?? [] : []).map((k) => byId.get(k)!).filter((k) => roleOf(k.kind) === "database"); - const stores = [...new Map([...direct, ...through].map((k) => [k.id, k])).values()]; - for (const store of stores) { - const writes = out / stores.length; - const key = direct.some((d) => d.id === store.id) ? `${id}>${store.id}` : `${cache!.id}>${store.id}`; - incoming.set(store.id, (incoming.get(store.id) ?? 0) + writes); - inlineWrites.set(store.id, (inlineWrites.get(store.id) ?? 0) + writes); - edgeFlows[key] = (edgeFlows[key] ?? 0) + writes; - addPart(key, direct.some((d) => d.id === store.id) ? "click writes" : "click writes, written directly", writes); - } - } - } - - const evaluations = new Map(); - const tiers: TierLoad[] = []; - let cost = 0; - for (const node of board.nodes) { - if (node.kind === "client") continue; - const down = isDown(node); - const onPath = reachable.has(node.id); - const flow = onPath ? incoming.get(node.id) ?? 0 : 0; - const ev = evaluate(node, flow, inlineWrites.get(node.id) ?? 0); - const capacity = down ? 0 : ev.capacity; - evaluations.set(node.id, ev); - cost += ev.cost; // placed hardware costs money whether or not it is serving - tiers.push({ - id: node.id, kind: node.kind, capacity, utilisation: capacity > 0 ? flow / capacity : 0, - down, reachable: onPath, units: ev.units, managed: ev.managed, note: ev.note, cost: ev.cost, waitMs: 0, - cacheStats: roleOf(node.kind) === "cache" && onPath - ? { hitRate: num(node, "hitRate", 0), reads: flow, hits: flow * num(node, "hitRate", 0), misses: flow * (1 - num(node, "hitRate", 0)) } - : undefined, - }); - } - const tierById = new Map(tiers.map((t) => [t.id, t])); - - // Work behind a queue is asynchronous: slow consumers build a backlog, not slow requests. - let backlog = 0; - for (const id of order) { - const node = byId.get(id)!; - if (!ASYNC_ROLES.has(roleOf(node.kind))) continue; - const consumers = (children.get(id) ?? []).reduce((sum, k) => sum + (tierById.get(k)?.capacity ?? 0), 0); - const behind = Math.max(0, (incoming.get(id) ?? 0) - consumers); - backlog += behind; - const tier = tierById.get(id); - // A consumer that is down is still linked: say so, instead of "no consumers linked". - const linkedButDown = board.edges.some((e) => e.from === id && isDown(byId.get(e.to)!)); - if (tier) tier.note = consumers === 0 ? (linkedButDown ? `consumers down, backlog grows ${rate(behind)}/s` : "no consumers linked") : behind > 0 ? `backlog grows ${rate(behind)}/s` : "consumers keeping up"; - } - - // Capacity, latency and availability of the synchronous request path. - let ceiling = Number.POSITIVE_INFINITY; - const roleAvail = new Map(); - const lat50 = new Map(); - const lat99 = new Map(); - for (const id of order) { - if (!sync.has(id)) continue; - const tier = tierById.get(id); - const ev = evaluations.get(id); - if (tier && ev) { - const flow = incoming.get(id) ?? 0; - if (flow > 0 && tier.capacity > 0) ceiling = Math.min(ceiling, (tier.capacity * load) / flow); - const role = roleOf(tier.kind); - roleAvail.set(role, [...(roleAvail.get(role) ?? []), ev.availability]); - } - const service = ev?.serviceMs ?? 0; - const u = ev?.queueing && tier ? Math.min(tier.utilisation, 0.985) : 0; - const before = (parents.get(id) ?? []).filter((p) => sync.has(p)); - lat50.set(id, service + Math.max(0, ...before.map((p) => lat50.get(p) ?? 0))); - lat99.set(id, service / (1 - u) + Math.max(0, ...before.map((p) => lat99.get(p) ?? 0))); - if (tier) tier.waitMs = service / (1 - u) - service; - } - const p50 = NETWORK_MS + Math.max(0, ...lat50.values()); - const p99 = NETWORK_MS + Math.max(0, ...lat99.values()); - - // Parallel components with the same role back each other up; the roles are in series. - let availability = 1; - let weakest: ModelResult["weakest"]; - for (const [role, parts] of roleAvail) { - const roleUp = 1 - parts.reduce((all, a) => all * (1 - a), 1); - availability *= roleUp; - if (!weakest || roleUp < weakest.availability) weakest = { role, availability: roleUp }; - } - - // A placed database that requests cannot reach means nothing is served. - let failure: string | undefined; - const stores = board.nodes.filter((n) => roleOf(n.kind) === "database" || roleOf(n.kind) === "nosql"); - if (stores.length > 0 && !stores.some((n) => reachable.has(n.id))) { - ceiling = 0; - availability = 0; - const blocker = board.nodes.find((n) => isDown(n) && board.edges.some((e) => e.from === n.id || e.to === n.id)); - failure = blocker - ? `${COMPONENT_CATALOG[blocker.kind].label} is down: requests through it fail.` - : "The database is not linked into the request path."; - } - - if (!Number.isFinite(ceiling)) ceiling = 0; - - const pass = { - rps: targets.rps == null ? true : ceiling >= targets.rps, - p99: targets.p99Ms == null ? true : p99 <= targets.p99Ms, - availability: targets.availability == null ? true : availability >= targets.availability, - budget: targets.budgetPerHour == null ? true : cost <= targets.budgetPerHour, - }; - - return { - capacityCeiling: Math.round(ceiling), - p50Ms: Math.round(p50), - p99Ms: Math.round(p99), - availability, - failure, - edgeFlows, - edgeParts, - dropped, - blocked, - backlog, - weakest, - costPerHour: cost, - tiers, - pass, - allPass: pass.rps && pass.p99 && pass.availability && pass.budget, - }; -} +export * from "../shared/lab/engine/tiered-architecture"; diff --git a/packages/learning-ui/src/labs/types.ts b/packages/learning-ui/src/labs/types.ts index fcd8472e..27f6bb21 100644 --- a/packages/learning-ui/src/labs/types.ts +++ b/packages/learning-ui/src/labs/types.ts @@ -2,7 +2,7 @@ // registry, the runtime and the validator all read it. validateLabSpec is the // runtime guard the registry test runs over every registered lab. -import type { ComponentKind, Role } from "./catalog"; +import type { ComponentKind } from "./catalog"; import { canConnect, isComponentKind } from "./catalog"; import type { BuildGoal, BuildPart, BuildSolution } from "./net/build-model"; import { validateBuildLab } from "./net/build-validate"; @@ -10,144 +10,23 @@ import type { NetCheck } from "./net/checks"; import type { NetTopology } from "./net/model"; import type { PlanSpec } from "./net/plan"; import { validateChecks, validatePlan, validateSolution as validateNetSolution, validateTopology } from "./net/validate"; - -export type LabFamily = "hld" | "db" | "net"; - -export interface BoardNode { - id: string; - kind: ComponentKind; - x: number; - y: number; - props?: Record; -} - -export interface BoardEdge { - from: string; - to: string; - /** Which dot each end uses (t, r, b, l); the board picks bottom to top when absent. */ - via?: [string, string]; -} - -export interface Board { - nodes: BoardNode[]; - edges: BoardEdge[]; -} - -export interface LabLevel { - id: string; - load: number; - targets: { rps?: number; p99Ms?: number; availability?: number; budgetPerHour?: number }; - event?: string; -} - -// ---- challenge: the checks a visual lab's Run puts the design through ---------- - -/** Something that goes wrong in a scenario. */ -export type Fault = - /** One instance of the first component with this role dies; a fleet of one dies whole. */ - | { type: "lose-instance"; role: Role } - /** Every component with this role goes down. */ - | { type: "down"; role: Role }; - -export interface ChallengeScenario { - id: string; - /** Short name, shown on the run strip: "The cache dies". */ - title: string; - /** One line shown while this phase plays. */ - story: string; - faults: Fault[]; -} - -export type CheckMetric = "p99" | "capacity" | "served" | "availability" | "cost"; - -interface CheckBase { - id: string; - kind: "functional" | "non-functional"; - label: string; -} - -export type CheckDef = - /** A functional check: a request can travel client -> ... -> the next role, in order. */ - | (CheckBase & { - type: "path"; - chain: Role[]; - target: string; - /** A design with no component of this role passes without the chain: the work is done inline instead. */ - inlineIfNo?: Role; - }) - /** A measured check: one number from one scenario against a limit. */ - | (CheckBase & { type: "metric"; scenario: string; metric: CheckMetric; op: "<=" | ">="; value: number }) - /** Work queued while its consumer is down must be fully counted once it is back. */ - | (CheckBase & { - type: "drain"; - outageSeconds: number; - maxDrainSeconds: number; - /** What waits in the queue, plural: "clicks" (the default), "posts", "messages". */ - items?: string; - /** What happens to each item once a worker takes it: "counted" (the default), "delivered", "saved". */ - done?: string; - }); - -export interface ChallengeDef { - /** Requests a second at the busiest moment; every scenario runs at this load. */ - peakLoad: number; - /** - * With no queue on the board, each request writes its click to the database before it - * answers, so counting works but costs a database write per request. - */ - inlineClicks?: boolean; - /** - * The share of requests that send work to parts of a role, for side jobs only some - * requests need: { queue: 0.1 } means 1 request in 10 leaves a job in the queue. - * Each share is above 0 and at most 1; a role with no share gets the whole stream. - */ - shares?: Partial>; - scenarios: ChallengeScenario[]; - checks: CheckDef[]; -} - -// ---- solution: a reference design a learner can open and compare with ---------- - -/** Why one part is in the reference design. */ -export interface SolutionPart { - /** Plain words: what this part does in the design. */ - why: string; - /** Ids of the checks this part helps pass. */ - checks: string[]; - /** What goes wrong without it, with numbers from the model. */ - without: string; -} - -export interface SolutionDef { - /** The reference design. It must pass every check of the lab. */ - board: Board; - /** One or two plain sentences: the idea behind the design. */ - summary: string; - /** Keyed by node id in `board`. */ - parts: Record; -} - -export interface LabBase { - slug: string; - family: LabFamily; - title: string; - purpose: string; - limits: string; - hints: string[]; - referenceSlug?: string; -} - -export interface HldLabSpec extends LabBase { - family: "hld"; - allowedComponents: ComponentKind[]; - startingBoard?: Board; - scenario: string; - levels: LabLevel[]; - /** A visual challenge: functional and non-functional checks and the scenarios that test them. */ - challenge?: ChallengeDef; - /** A reference design the learner can open after pressing Run, and compare with their own. */ - solution?: SolutionDef; -} +import type { Board, BoardNode, ChallengeDef, HldLabSpec, LabBase } from "../shared/lab/engine/hld-types"; +export type { + Board, + BoardEdge, + BoardNode, + ChallengeDef, + ChallengeScenario, + CheckDef, + CheckMetric, + Fault, + HldLabSpec, + LabBase, + LabFamily, + LabLevel, + SolutionDef, + SolutionPart, +} from "../shared/lab/engine/hld-types"; export interface DbLabSpec extends LabBase { family: "db"; diff --git a/packages/learning-ui/src/shared/lab/engine/catalog.ts b/packages/learning-ui/src/shared/lab/engine/catalog.ts new file mode 100644 index 00000000..fd1aff11 --- /dev/null +++ b/packages/learning-ui/src/shared/lab/engine/catalog.ts @@ -0,0 +1,437 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The shared component catalog for the lab platform. +// +// Every block a lab can use is described once here: its family (which course it +// belongs to), its role (what it does in a request path), its configurable +// properties (with range, default, unit and the panel group they show in), and +// the size catalogs its size pickers draw from. The board, the scoring model and +// the authoring validator all read this file. Links are allowed by role, so a new +// family (Kubernetes, Docker, Linux) is mostly new entries here, not new code. +// +// Prices and capacities are illustrative and dated (one region, on-demand, late +// 2026). Use them to compare the shapes of designs, not to quote a real bill. + +export type Family = "hld" | "aws" | "k8s" | "docker" | "linux"; +export const FAMILIES: readonly Family[] = ["hld", "aws", "k8s", "docker", "linux"]; + +export type Role = + | "client" + | "dns" + | "cdn" + | "firewall" + | "limiter" + | "balancer" + | "gateway" + | "compute" + | "function" + | "worker" + | "cache" + | "database" + | "nosql" + | "search" + | "queue" + | "stream" + | "storage"; + +export type ComponentKind = + // Generic building blocks for the high-level design course + | "client" + | "dns" + | "cdn" + | "waf" + | "rate-limiter" + | "load-balancer" + | "api-gateway" + | "app-server" + | "worker" + | "cache" + | "database" + | "nosql" + | "search" + | "queue" + | "stream" + | "object-storage" + // AWS services for the AWS course + | "aws-route53" + | "aws-cloudfront" + | "aws-waf" + | "aws-alb" + | "aws-nlb" + | "aws-api-gateway" + | "aws-ec2-asg" + | "aws-fargate" + | "aws-lambda" + | "aws-elasticache" + | "aws-rds" + | "aws-dynamodb" + | "aws-opensearch" + | "aws-sqs" + | "aws-kinesis" + | "aws-s3" + // Kubernetes objects for the Kubernetes course + | "k8s-ingress" + | "k8s-service" + | "k8s-deployment" + | "k8s-statefulset" + // Containers for the Docker course + | "docker-proxy" + | "docker-container" + | "docker-postgres" + // One host's services for the Linux course + | "linux-nginx" + | "linux-service" + | "linux-postgres"; + +export type PortDir = "in" | "out"; + +export interface PortDef { + id: string; + dir: PortDir; + accepts: ComponentKind[]; +} + +export type SizeSet = "generic" | "ec2" | "fargate" | "rds" | "elasticache" | "opensearch" | "pod" | "container" | "host"; +export type PropertyGroup = "Capacity" | "Scaling" | "Resilience" | "Behaviour"; + +export interface PropertyDef { + id: string; + label: string; + type: "size" | "count" | "ratio" | "enum" | "toggle"; + min?: number; + max?: number; + step?: number; + default: number | string; + unit: string; + options?: string[]; + /** Which size catalog a size picker draws from. */ + sizeSet?: SizeSet; + group?: PropertyGroup; + /** One line shown as a tooltip in the config panel. */ + help?: string; +} + +/** A managed, elastic service: priced per hour plus per million requests. */ +export interface ManagedPricing { + capacity: number; + pricePerHour: number; + pricePerMillion: number; +} + +export interface ComponentDef { + kind: ComponentKind; + label: string; + family: Family; + role: Role; + /** The product or engine name shown under the label. */ + vendor: string; + icon: string; + ports: PortDef[]; + properties: PropertyDef[]; + managed?: ManagedPricing; +} + +export interface SizeTier { + id: string; + set: SizeSet; + family: "general" | "compute" | "memory"; + vcpu: number; + memoryGb: number; + capacityRule: string; + pricePerHour: number; +} + +// Which role may send requests to which. Links follow the request, not the data. +const ROLE_NEXT: Record = { + client: ["dns", "cdn", "firewall", "limiter", "balancer", "gateway"], + dns: [], + cdn: ["firewall", "limiter", "balancer", "gateway", "compute", "storage"], + firewall: ["cdn", "limiter", "balancer", "gateway", "compute"], + limiter: ["balancer", "gateway", "compute", "function"], + balancer: ["balancer", "compute", "function"], + gateway: ["balancer", "compute", "function", "queue", "stream", "nosql", "storage"], + compute: ["function", "cache", "database", "nosql", "search", "queue", "stream", "storage"], + function: ["cache", "database", "nosql", "search", "queue", "stream", "storage"], + worker: ["cache", "database", "nosql", "search", "queue", "storage"], + queue: ["worker", "function"], + stream: ["worker", "function"], + // A cache may load from a database on a miss (read-through). Linking it is optional: + // an app server linked to both a cache and a database is cache-aside, with the same maths. + cache: ["database", "nosql"], + database: [], + nosql: [], + search: [], + storage: [], +}; + +// ---- property builders --------------------------------------------------- + +const size = (sizeSet: SizeSet, defaultId: string): PropertyDef => ({ + id: "size", + label: "Machine size", + type: "size", + sizeSet, + default: defaultId, + unit: "tier", + group: "Capacity", +}); +const count = (id: string, label: string, unit: string, def: number, min: number, max: number, group: PropertyGroup = "Capacity", help?: string): PropertyDef => ({ + id, label, type: "count", min, max, step: 1, default: def, unit, group, help, +}); +const ratio = (id: string, label: string, def: number, group: PropertyGroup = "Behaviour", help?: string): PropertyDef => ({ + id, label, type: "ratio", min: 0, max: 1, step: 0.05, default: def, unit: "fraction", group, help, +}); +const toggle = (id: string, label: string, def: 0 | 1, group: PropertyGroup, help?: string): PropertyDef => ({ + id, label, type: "toggle", default: def, unit: "on/off", group, help, +}); +const choice = (id: string, label: string, options: string[], def: string, group: PropertyGroup = "Behaviour", help?: string): PropertyDef => ({ + id, label, type: "enum", options, default: def, unit: "option", group, help, +}); +const azs = (def: number, min = 1): PropertyDef => + count("azs", "Zones (separate data centres)", "zones", def, min, 3, "Resilience", "Spreading across zones means one zone going down does not stop the service."); +const scaling = (on: 0 | 1, min: number, max: number, target: number): PropertyDef[] => [ + toggle("autoscale", "Add machines automatically (autoscaling)", on, "Scaling", "Adds or removes machines to stay near the target busyness."), + count("minCount", "Fewest machines", "machines", min, 1, 100, "Scaling"), + count("maxCount", "Most machines", "machines", max, 1, 200, "Scaling"), + ratio("targetUtil", "Aim to stay this busy (target utilisation)", target, "Scaling", "Add machines before this level. Waiting time starts to climb near 70% busy."), +]; + +// ---- the catalog ----------------------------------------------------------- + +type Entry = Omit; + +const ENTRIES: Record = { + // Generic high-level design blocks + client: { label: "Client", family: "hld", role: "client", vendor: "Users", icon: "client", + properties: [count("load", "Traffic sent (offered load)", "req/s", 1000, 1, 10_000_000)] }, + dns: { label: "DNS", family: "hld", role: "dns", vendor: "Resolver", icon: "dns", + managed: { capacity: 1_000_000, pricePerHour: 0.001, pricePerMillion: 0 }, + properties: [count("ttl", "Record TTL", "seconds", 300, 1, 86_400, "Behaviour")] }, + cdn: { label: "CDN", family: "hld", role: "cdn", vendor: "Edge cache", icon: "cdn", + managed: { capacity: 1_000_000, pricePerHour: 0.02, pricePerMillion: 0.75 }, + properties: [ratio("hitRate", "Answered nearby (edge hit rate)", 0.8, "Behaviour", "A hit is answered close to the user. Only misses reach your servers.")] }, + waf: { label: "Firewall", family: "hld", role: "firewall", vendor: "WAF", icon: "firewall", + managed: { capacity: 1_000_000, pricePerHour: 0.007, pricePerMillion: 0.6 }, + properties: [ratio("blockRate", "Blocked share", 0.02, "Behaviour", "Share of traffic dropped as malicious.")] }, + "rate-limiter": { label: "Rate limiter", family: "hld", role: "limiter", vendor: "Token bucket", icon: "limiter", + managed: { capacity: 1_000_000, pricePerHour: 0.01, pricePerMillion: 0 }, + properties: [count("limit", "Limit", "req/s", 5000, 10, 1_000_000, "Behaviour", "Requests above this are rejected, protecting what sits behind it.")] }, + "load-balancer": { label: "Load balancer", family: "hld", role: "balancer", vendor: "L7 LB", icon: "balancer", + properties: [size("generic", "general-small"), count("zones", "Zones (separate data centres)", "zones", 1, 1, 3, "Resilience")] }, + "api-gateway": { label: "API gateway", family: "hld", role: "gateway", vendor: "Gateway", icon: "gateway", + properties: [size("generic", "general-small"), count("count", "Machines (instances)", "machines", 2, 1, 50)] }, + "app-server": { label: "App server", family: "hld", role: "compute", vendor: "Compute", icon: "compute", + properties: [size("generic", "compute-small"), count("count", "Machines (instances)", "machines", 2, 1, 50), ...scaling(0, 2, 10, 0.6), azs(1)] }, + worker: { label: "Worker", family: "hld", role: "worker", vendor: "Consumer", icon: "worker", + properties: [size("generic", "compute-small"), count("count", "Workers", "workers", 2, 1, 100), count("batchSize", "Items saved per trip (batch size)", "events", 1, 1, 1000, "Behaviour", "How many items (clicks, posts, events) go to the store in one trip. Saving many at once turns thousands of writes a second into a few."), ...scaling(0, 1, 20, 0.7)] }, + cache: { label: "Cache", family: "hld", role: "cache", vendor: "Redis", icon: "cache", + properties: [size("generic", "memory-small"), count("count", "Machines (nodes)", "nodes", 1, 1, 20), ratio("hitRate", "Answered by the cache (hit rate)", 0.85, "Behaviour", "A hit means the database is never asked. A miss goes on to the database."), azs(1)] }, + database: { label: "Database", family: "hld", role: "database", vendor: "PostgreSQL", icon: "database", + properties: [ + size("generic", "memory-medium"), + count("replicas", "Read-only copies (read replicas)", "copies", 0, 0, 5, "Capacity", "Extra copies that share the reads. Every write still goes to the main copy (the primary)."), + ratio("readRatio", "Share that only reads", 0.8, "Behaviour", "Reads look data up. Writes change it."), + toggle("multiAz", "Extra copy that takes over (failover standby)", 0, "Resilience", "A standby copy in a second zone takes over if the main copy's zone fails. It doubles the main copy's cost."), + ] }, + nosql: { label: "NoSQL store", family: "hld", role: "nosql", vendor: "Key-value", icon: "nosql", + properties: [size("generic", "memory-medium"), count("count", "Machines (nodes)", "nodes", 3, 1, 30), azs(1)] }, + search: { label: "Search", family: "hld", role: "search", vendor: "Index", icon: "search", + properties: [size("generic", "memory-medium"), count("count", "Machines (nodes)", "nodes", 2, 1, 20), azs(1)] }, + queue: { label: "Queue", family: "hld", role: "queue", vendor: "Broker", icon: "queue", + managed: { capacity: 100_000, pricePerHour: 0.01, pricePerMillion: 0.04 }, + properties: [count("maxInFlight", "Most messages handled at once (max in flight)", "messages", 1000, 1, 1_000_000, "Behaviour")] }, + stream: { label: "Event stream", family: "hld", role: "stream", vendor: "Kafka", icon: "stream", + properties: [count("partitions", "Lanes (partitions)", "lanes", 4, 1, 256, "Capacity", "Each lane takes about 1,000 events a second."), count("retentionHours", "Keep events for (retention)", "hours", 24, 1, 8760, "Behaviour")] }, + "object-storage": { label: "Object storage", family: "hld", role: "storage", vendor: "Blob store", icon: "storage", + managed: { capacity: 1_000_000, pricePerHour: 0.01, pricePerMillion: 0.4 }, + properties: [count("capacityGb", "Capacity", "GB", 100, 1, 1_000_000)] }, + + // AWS services + "aws-route53": { label: "Route 53", family: "aws", role: "dns", vendor: "AWS DNS", icon: "dns", + managed: { capacity: 1_000_000, pricePerHour: 0.0007, pricePerMillion: 0 }, + properties: [choice("routing", "Routing policy", ["simple", "latency", "failover", "weighted"], "simple")] }, + "aws-cloudfront": { label: "CloudFront", family: "aws", role: "cdn", vendor: "AWS CDN", icon: "cdn", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.75 }, + properties: [ratio("hitRate", "Cache hit rate", 0.85), choice("priceClass", "Price class", ["100", "200", "All"], "100")] }, + "aws-waf": { label: "AWS WAF", family: "aws", role: "firewall", vendor: "Web ACL", icon: "firewall", + managed: { capacity: 1_000_000, pricePerHour: 0.007, pricePerMillion: 0.6 }, + properties: [ratio("blockRate", "Blocked share", 0.02), count("rules", "Rules", "rules", 10, 1, 100, "Behaviour")] }, + "aws-alb": { label: "ALB", family: "aws", role: "balancer", vendor: "Application LB", icon: "balancer", + managed: { capacity: 100_000, pricePerHour: 0.0225, pricePerMillion: 0.2 }, + properties: [azs(2, 2), toggle("crossZone", "Cross-zone balancing", 1, "Resilience")] }, + "aws-nlb": { label: "NLB", family: "aws", role: "balancer", vendor: "Network LB", icon: "balancer", + managed: { capacity: 200_000, pricePerHour: 0.0225, pricePerMillion: 0.1 }, + properties: [azs(2, 1)] }, + "aws-api-gateway": { label: "API Gateway", family: "aws", role: "gateway", vendor: "AWS API Gateway", icon: "gateway", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 1 }, + properties: [ + choice("apiType", "API type", ["HTTP", "REST"], "HTTP", "Behaviour", "REST APIs cost about 3.5 times more per request."), + count("limit", "Throttle", "req/s", 10_000, 10, 100_000, "Behaviour", "Account throttle; requests above it get 429 errors."), + ] }, + "aws-ec2-asg": { label: "EC2 Auto Scaling", family: "aws", role: "compute", vendor: "EC2", icon: "compute", + properties: [size("ec2", "m5.large"), count("count", "Desired instances", "instances", 2, 1, 200), ...scaling(1, 2, 10, 0.5), azs(2)] }, + "aws-fargate": { label: "ECS Fargate", family: "aws", role: "compute", vendor: "Containers", icon: "compute", + properties: [size("fargate", "1 vCPU / 2 GB"), count("count", "Tasks", "tasks", 2, 1, 500), ...scaling(1, 2, 20, 0.6), azs(2)] }, + "aws-lambda": { label: "Lambda", family: "aws", role: "function", vendor: "Serverless", icon: "function", + properties: [ + choice("memoryMb", "Memory", ["128", "256", "512", "1024", "2048"], "512", "Capacity", "More memory also means more CPU and a higher GB-second price."), + count("durationMs", "Duration", "ms", 120, 1, 900_000, "Behaviour"), + count("concurrency", "Reserved concurrency", "executions", 1000, 1, 10_000, "Capacity", "Concurrency divided by duration is the most it can serve; beyond that it throttles."), + ] }, + "aws-elasticache": { label: "ElastiCache", family: "aws", role: "cache", vendor: "Redis", icon: "cache", + properties: [size("elasticache", "cache.r6g.large"), count("count", "Shards", "shards", 1, 1, 50), count("replicasPerShard", "Replicas per shard", "replicas", 1, 0, 5, "Resilience"), ratio("hitRate", "Hit rate", 0.85), azs(2)] }, + "aws-rds": { label: "RDS", family: "aws", role: "database", vendor: "Managed SQL", icon: "database", + properties: [ + choice("engine", "Engine", ["PostgreSQL", "MySQL"], "PostgreSQL", "Behaviour"), + size("rds", "db.r5.large"), + count("replicas", "Read replicas", "replicas", 1, 0, 15, "Capacity", "Replicas share the reads; every write still goes to the primary."), + ratio("readRatio", "Read share", 0.8), + toggle("multiAz", "Multi-AZ", 1, "Resilience", "A synchronous standby in another zone. Doubles the primary cost."), + ] }, + "aws-dynamodb": { label: "DynamoDB", family: "aws", role: "nosql", vendor: "Key-value", icon: "nosql", + managed: { capacity: 40_000, pricePerHour: 0, pricePerMillion: 0 }, + properties: [ + choice("capacityMode", "Capacity mode", ["on-demand", "provisioned"], "on-demand", "Capacity", "On-demand bills per request; provisioned bills per hour for the units you reserve."), + count("rcu", "Read units", "RCU", 1000, 1, 100_000, "Capacity"), + count("wcu", "Write units", "WCU", 500, 1, 100_000, "Capacity"), + ratio("readRatio", "Read share", 0.8), + ] }, + "aws-opensearch": { label: "OpenSearch", family: "aws", role: "search", vendor: "Search", icon: "search", + properties: [size("opensearch", "m5.large.search"), count("count", "Data nodes", "nodes", 2, 1, 40), azs(2)] }, + "aws-sqs": { label: "SQS", family: "aws", role: "queue", vendor: "AWS queue", icon: "queue", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.4 }, + properties: [choice("queueType", "Queue type", ["standard", "FIFO"], "standard", "Behaviour", "FIFO keeps order but tops out near 3,000 messages/s with batching.")] }, + "aws-kinesis": { label: "Kinesis", family: "aws", role: "stream", vendor: "Data Streams", icon: "stream", + properties: [count("partitions", "Shards", "shards", 2, 1, 500, "Capacity", "Each shard takes about 1,000 records/s."), count("retentionHours", "Retention", "hours", 24, 24, 8760, "Behaviour")] }, + "aws-s3": { label: "S3", family: "aws", role: "storage", vendor: "Object storage", icon: "storage", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.4 }, + properties: [choice("storageClass", "Storage class", ["Standard", "Intelligent-Tiering", "Glacier IR"], "Standard")] }, + + // Kubernetes + "k8s-ingress": { label: "Ingress", family: "k8s", role: "balancer", vendor: "ingress-nginx", icon: "balancer", + properties: [size("pod", "500m / 512Mi"), count("count", "Controller replicas", "pods", 2, 1, 20), azs(1)] }, + "k8s-service": { label: "Service", family: "k8s", role: "balancer", vendor: "ClusterIP", icon: "balancer", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0 }, + properties: [choice("serviceType", "Type", ["ClusterIP", "NodePort", "LoadBalancer"], "ClusterIP", "Behaviour", "A LoadBalancer Service also rents a cloud load balancer.")] }, + "k8s-deployment": { label: "Deployment", family: "k8s", role: "compute", vendor: "Pods", icon: "compute", + properties: [size("pod", "500m / 512Mi"), count("count", "Replicas", "pods", 2, 1, 200), ...scaling(1, 2, 10, 0.6), azs(1)] }, + "k8s-statefulset": { label: "StatefulSet", family: "k8s", role: "database", vendor: "PostgreSQL", icon: "database", + properties: [size("pod", "2 CPU / 4Gi"), count("replicas", "Read replicas", "pods", 0, 0, 5), ratio("readRatio", "Read share", 0.8)] }, + + // Docker + "docker-proxy": { label: "Reverse proxy", family: "docker", role: "balancer", vendor: "Traefik", icon: "balancer", + properties: [size("container", "1 CPU / 1GB"), count("count", "Containers", "containers", 1, 1, 10)] }, + "docker-container": { label: "App container", family: "docker", role: "compute", vendor: "Container", icon: "compute", + properties: [size("container", "1 CPU / 1GB"), count("count", "Replicas", "containers", 1, 1, 20)] }, + "docker-postgres": { label: "Postgres", family: "docker", role: "database", vendor: "postgres:16", icon: "database", + properties: [size("container", "2 CPU / 2GB"), count("replicas", "Read replicas", "containers", 0, 0, 3), ratio("readRatio", "Read share", 0.8)] }, + + // Linux, one host + "linux-nginx": { label: "nginx", family: "linux", role: "balancer", vendor: "Reverse proxy", icon: "balancer", + properties: [size("host", "2 cores / 4GB")] }, + "linux-service": { label: "App service", family: "linux", role: "compute", vendor: "systemd", icon: "compute", + properties: [size("host", "2 cores / 4GB"), count("count", "Hosts", "hosts", 1, 1, 10)] }, + "linux-postgres": { label: "PostgreSQL", family: "linux", role: "database", vendor: "postgresql.service", icon: "database", + properties: [size("host", "4 cores / 8GB"), count("replicas", "Read replicas", "hosts", 0, 0, 3), ratio("readRatio", "Read share", 0.8)] }, +}; + +const COMPONENT_KINDS = Object.keys(ENTRIES) as ComponentKind[]; +const KIND_SET = new Set(COMPONENT_KINDS); + +export function isComponentKind(value: string): value is ComponentKind { + return KIND_SET.has(value); +} + +export function roleOf(kind: ComponentKind): Role { + return ENTRIES[kind].role; +} + +function portsFor(kind: ComponentKind): PortDef[] { + const role = ENTRIES[kind].role; + const inbound = COMPONENT_KINDS.filter((k) => ROLE_NEXT[ENTRIES[k].role].includes(role)); + const outbound = COMPONENT_KINDS.filter((k) => ROLE_NEXT[role].includes(ENTRIES[k].role)); + const ports: PortDef[] = []; + if (inbound.length > 0) ports.push({ id: "in", dir: "in", accepts: inbound }); + if (outbound.length > 0) ports.push({ id: "out", dir: "out", accepts: outbound }); + return ports; +} + +export const COMPONENT_CATALOG: Record = Object.fromEntries( + COMPONENT_KINDS.map((kind) => [kind, { kind, ...ENTRIES[kind], ports: portsFor(kind) }]), +) as Record; + +export function canConnect(from: ComponentKind, to: ComponentKind): boolean { + return ROLE_NEXT[ENTRIES[from].role].includes(ENTRIES[to].role); +} + +export function kindsInFamily(family: Family): ComponentKind[] { + return COMPONENT_KINDS.filter((k) => ENTRIES[k].family === family); +} + +// ---- size catalogs ----------------------------------------------------------- + +const GENERIC_RULE = { general: "~800 req/s per vCPU at a light mix", compute: "~1,200 req/s per vCPU at a CPU-bound mix", memory: "~600 req/s per vCPU; holds a large working set" }; +const tier = (set: SizeSet, id: string, family: SizeTier["family"], vcpu: number, memoryGb: number, pricePerHour: number, capacityRule = GENERIC_RULE[family]): SizeTier => ({ + id, set, family, vcpu, memoryGb, capacityRule, pricePerHour, +}); + +export const SIZE_CATALOG: SizeTier[] = [ + tier("generic", "general-small", "general", 2, 8, 0.1), + tier("generic", "general-medium", "general", 4, 16, 0.2), + tier("generic", "general-large", "general", 8, 32, 0.4), + tier("generic", "general-xlarge", "general", 16, 64, 0.8), + tier("generic", "compute-small", "compute", 2, 4, 0.12), + tier("generic", "compute-medium", "compute", 4, 8, 0.24), + tier("generic", "compute-large", "compute", 8, 16, 0.48), + tier("generic", "compute-xlarge", "compute", 16, 32, 0.96), + tier("generic", "memory-small", "memory", 2, 16, 0.15), + tier("generic", "memory-medium", "memory", 4, 32, 0.3), + tier("generic", "memory-large", "memory", 8, 64, 0.6), + tier("generic", "memory-xlarge", "memory", 16, 128, 1.2), + + tier("ec2", "t3.medium", "general", 2, 4, 0.0416, "burstable; ~800 req/s per vCPU while it has credits"), + tier("ec2", "m5.large", "general", 2, 8, 0.096), + tier("ec2", "m5.xlarge", "general", 4, 16, 0.192), + tier("ec2", "c5.large", "compute", 2, 4, 0.085), + tier("ec2", "c5.xlarge", "compute", 4, 8, 0.17), + tier("ec2", "c5.2xlarge", "compute", 8, 16, 0.34), + tier("ec2", "r5.large", "memory", 2, 16, 0.126), + + tier("fargate", "0.25 vCPU / 0.5 GB", "general", 0.25, 0.5, 0.0123), + tier("fargate", "0.5 vCPU / 1 GB", "general", 0.5, 1, 0.0247), + tier("fargate", "1 vCPU / 2 GB", "general", 1, 2, 0.0494), + tier("fargate", "2 vCPU / 4 GB", "general", 2, 4, 0.0988), + tier("fargate", "4 vCPU / 8 GB", "general", 4, 8, 0.1975), + + tier("rds", "db.t3.medium", "memory", 2, 4, 0.068), + tier("rds", "db.m5.large", "memory", 2, 8, 0.171), + tier("rds", "db.r5.large", "memory", 2, 16, 0.24), + tier("rds", "db.r5.xlarge", "memory", 4, 32, 0.48), + tier("rds", "db.r5.2xlarge", "memory", 8, 64, 0.96), + + tier("elasticache", "cache.t3.small", "memory", 2, 1.37, 0.034, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.m5.large", "memory", 2, 6.38, 0.156, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.r6g.large", "memory", 2, 13.07, 0.206, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.r6g.xlarge", "memory", 4, 26.32, 0.411, "~15,000 ops/s per vCPU"), + + tier("opensearch", "t3.medium.search", "memory", 2, 4, 0.073, "~300 queries/s per vCPU"), + tier("opensearch", "m5.large.search", "memory", 2, 8, 0.142, "~300 queries/s per vCPU"), + tier("opensearch", "r5.large.search", "memory", 2, 16, 0.186, "~300 queries/s per vCPU"), + + tier("pod", "250m / 256Mi", "general", 0.25, 0.25, 0.01, "CPU request; ~800 req/s per full core"), + tier("pod", "500m / 512Mi", "general", 0.5, 0.5, 0.02, "CPU request; ~800 req/s per full core"), + tier("pod", "1 CPU / 1Gi", "general", 1, 1, 0.04, "CPU request; ~800 req/s per full core"), + tier("pod", "2 CPU / 4Gi", "general", 2, 4, 0.09, "CPU request; ~800 req/s per full core"), + + tier("container", "0.5 CPU / 512MB", "general", 0.5, 0.5, 0.02, "--cpus limit; ~800 req/s per full core"), + tier("container", "1 CPU / 1GB", "general", 1, 1, 0.04, "--cpus limit; ~800 req/s per full core"), + tier("container", "2 CPU / 2GB", "general", 2, 2, 0.08, "--cpus limit; ~800 req/s per full core"), + + tier("host", "1 core / 2GB", "general", 1, 2, 0.02, "~800 req/s per core"), + tier("host", "2 cores / 4GB", "general", 2, 4, 0.04, "~800 req/s per core"), + tier("host", "4 cores / 8GB", "general", 4, 8, 0.08, "~800 req/s per core"), + tier("host", "8 cores / 16GB", "general", 8, 16, 0.16, "~800 req/s per core"), +]; + +export function sizesFor(set: SizeSet): SizeTier[] { + return SIZE_CATALOG.filter((t) => t.set === set); +} diff --git a/packages/learning-ui/src/shared/lab/engine/challenge.ts b/packages/learning-ui/src/shared/lab/engine/challenge.ts new file mode 100644 index 00000000..d4c10e23 --- /dev/null +++ b/packages/learning-ui/src/shared/lab/engine/challenge.ts @@ -0,0 +1,291 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The run behind a visual challenge: pure and server-importable like the model it +// wraps. It takes a board and plays it through the challenge's scenarios (peak +// traffic, then each fault), asks the tiered-architecture model for the numbers in +// every one, and turns them into a pass or fail per check, each with the measured +// value, the target and, when it fails, the reason. +// +// Functional checks are about structure: can a request travel the path the feature +// needs? Non-functional checks are measurements: latency, how much is still served +// when something dies, whether queued work is all counted, and cost. + +import type { Board, BoardNode, ChallengeDef, ChallengeScenario, CheckDef, CheckMetric, Fault, HldLabSpec } from "./hld-types"; +import type { ComponentKind, Role } from "./catalog"; +import { COMPONENT_CATALOG, roleOf } from "./catalog"; +import { runTieredModel, type ModelOptions, type ModelResult, type Targets, type TierLoad } from "./tiered-architecture"; + +export const STEADY: ChallengeScenario = { + id: "steady", + title: "Peak traffic", + story: "Everything is healthy and traffic is at its busiest.", + faults: [], +}; + +export interface CheckResult { + id: string; + kind: "functional" | "non-functional"; + label: string; + pass: boolean; + /** What the run found, with its unit. */ + measured: string; + /** What it had to be. */ + target: string; + /** Why it failed and what to look at; absent when it passed. */ + reason?: string; + /** The scenario the number comes from, so the board can replay it. */ + scenario: string; +} + +export interface PhaseReport { + id: string; + title: string; + story: string; + load: number; + /** The board as the scenario left it (fault applied). */ + board: Board; + /** The components the fault took down or thinned out. */ + hit: string[]; + /** False when the fault named a part this design does not have. */ + applicable: boolean; + /** The part the fault names when the design has none: "cache". */ + missing?: string; + result: ModelResult; +} + +export interface ChallengeReport { + phases: PhaseReport[]; + checks: CheckResult[]; + passed: number; + total: number; + allPass: boolean; +} + +const labelOf = (kind: ComponentKind) => COMPONENT_CATALOG[kind].label; +// Lowercases the first letter of a label for use mid-sentence, but leaves acronyms such as CDN alone. +const lower = (text: string) => (/^[A-Z]{2}/.test(text) ? text : text.charAt(0).toLowerCase() + text.slice(1)); +const pct = (n: number) => `${(Math.floor(n * 10000) / 100).toFixed(2)}%`; +const roleLabel = (role: Role) => Object.values(COMPONENT_CATALOG).find((c) => c.role === role)?.label ?? role; +const perSec = (n: number) => `${Math.round(n).toLocaleString("en-US")}/s`; + +function metricText(metric: CheckMetric, v: number): string { + switch (metric) { + case "p99": return `${Math.round(v)} ms`; + case "capacity": return perSec(v); + case "served": return `${(Math.floor(v * 1000) / 10).toFixed(1)}%`; + case "availability": return pct(v); + case "cost": return `$${v.toFixed(2)}/h`; + } +} +const targetText = (metric: CheckMetric, op: "<=" | ">=", v: number) => + `${op === "<=" ? "at most" : "at least"} ${metric === "availability" ? pct(v) : metricText(metric, v)}`; + +// ---- faults ------------------------------------------------------------------- + +function applyFaults(board: Board, faults: Fault[], steady: ModelResult): { board: Board; hit: string[]; applicable: boolean } { + const nodes: BoardNode[] = board.nodes.map((n) => ({ ...n, props: { ...(n.props ?? {}) } })); + const hit: string[] = []; + for (const fault of faults) { + const targets = nodes.filter((n) => roleOf(n.kind) === fault.role); + if (targets.length === 0) continue; + if (fault.type === "down") { + for (const n of targets) { n.props!.down = 1; hit.push(n.id); } + } else { + const first = targets[0]!; + const units = steady.tiers.find((t) => t.id === first.id)?.units ?? 1; + if (units <= 1) first.props!.down = 1; + else { first.props!.autoscale = 0; first.props!.count = units - 1; } + hit.push(first.id); + } + } + return { board: { ...board, nodes }, hit, applicable: hit.length > 0 }; +} + +// ---- functional checks: can a request travel the path? --------------------------- + +function reachFrom(board: Board, starts: string[]): Set { + const next = new Map(); + for (const e of board.edges) next.set(e.from, [...(next.get(e.from) ?? []), e.to]); + const seen = new Set(); + const queue = [...starts]; + while (queue.length > 0) { + const id = queue.shift()!; + for (const to of next.get(id) ?? []) if (!seen.has(to)) { seen.add(to); queue.push(to); } + } + return seen; +} + +/** Walks the roles in order. Returns the labels found so far and the first role that has no way in. */ +export function followChain(board: Board, chain: Role[]): { trail: string[]; missing?: Role } { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + let frontier = board.nodes.filter((n) => roleOf(n.kind) === chain[0] && !n.props?.down).map((n) => n.id); + const trail: string[] = frontier.length > 0 ? [labelOf(byId.get(frontier[0]!)!.kind)] : []; + if (frontier.length === 0) return { trail, missing: chain[0] }; + for (const role of chain.slice(1)) { + const reached = reachFrom(board, frontier); + frontier = [...reached].filter((id) => roleOf(byId.get(id)!.kind) === role && !byId.get(id)!.props?.down); + if (frontier.length === 0) return { trail, missing: role }; + trail.push(labelOf(byId.get(frontier[0]!)!.kind)); + } + return { trail }; +} + +const ROLE_NAME: Partial> = { + client: "a client", compute: "an app server", database: "a database", queue: "a queue", worker: "a worker", cache: "a cache", balancer: "a load balancer", +}; +const roleName = (role: Role) => ROLE_NAME[role] ?? `a ${role}`; + +function pathCheck(def: Extract, board: Board): CheckResult { + const { trail, missing } = followChain(board, def.chain); + if (missing !== undefined && def.inlineIfNo && !board.nodes.some((n) => roleOf(n.kind) === def.inlineIfNo)) { + return { + id: def.id, kind: def.kind, label: def.label, pass: true, scenario: "steady", target: def.target, + measured: `saved during the request (inline), no ${lower(roleLabel(def.inlineIfNo))}`, + }; + } + const pass = missing === undefined; + const last = trail.at(-1); + return { + id: def.id, kind: def.kind, label: def.label, pass, scenario: "steady", target: def.target, + measured: pass ? trail.join(" > ") : trail.length > 0 ? `${trail.join(" > ")} > ?` : "no path", + reason: pass ? undefined : trail.length === 0 + ? `There is no ${missing === "client" ? "client" : roleName(missing!).replace(/^an? /, "")} on the board.` + : `The path stops at ${lower(last!)}: link it to ${roleName(missing!)}.`, + }; +} + +// ---- non-functional checks: measured in a scenario --------------------------------- + +function worstTier(result: ModelResult): TierLoad | undefined { + return [...result.tiers].filter((t) => t.reachable && !t.managed).sort((a, b) => b.utilisation - a.utilisation)[0]; +} +const busy = (t: TierLoad) => `${labelOf(t.kind)} is ${Math.round(t.utilisation * 100)}% busy`; + +function measure(metric: CheckMetric, r: ModelResult, load: number): number { + switch (metric) { + case "p99": return r.p99Ms; + case "capacity": return r.capacityCeiling; + case "served": return load > 0 ? Math.min(1, r.capacityCeiling / load) : 1; + case "availability": return r.availability; + case "cost": return r.costPerHour; + } +} + +function whyMetricFailed(metric: CheckMetric, r: ModelResult, scenario: PhaseReport): string { + const worst = worstTier(r); + const during = scenario.id === "steady" ? "" : ` while ${lower(scenario.title)}`; + if (r.failure) return r.failure; + switch (metric) { + case "p99": { + const slow = [...r.tiers].filter((t) => t.waitMs > 0.5).sort((x, y) => y.waitMs - x.waitMs).slice(0, 2); + return slow.length > 0 + ? `Requests wait in line at ${slow.map((t) => `the ${lower(labelOf(t.kind))} (${Math.round(t.utilisation * 100)}% busy, +${Math.round(t.waitMs)} ms)`).join(" and ")}${during}. Give them more capacity, or take load off them.` + : "The path itself is too slow: fewer hops would help."; + } + case "capacity": + case "served": + return worst ? `${busy(worst)}${during}, so it cannot serve the whole load. Add machines, read-only copies or a cache in front of it.` : "Nothing on the board can serve the load."; + case "availability": { + const role = r.weakest?.role; + return role ? `${roleLabel(role)} is the weak link (${pct(r.weakest!.availability)}): run more than one, or in two zones.` : "Add redundancy."; + } + case "cost": { + const priciest = [...r.tiers].sort((a, b) => b.cost - a.cost)[0]; + return priciest ? `${labelOf(priciest.kind)} costs the most ($${priciest.cost.toFixed(2)}/h). Try a smaller size or fewer machines.` : "Over budget."; + } + } +} + +function metricCheck(def: Extract, phases: Map): CheckResult { + const phase = phases.get(def.scenario) ?? phases.get("steady")!; + const value = measure(def.metric, phase.result, phase.load); + const pass = def.op === "<=" ? value <= def.value : value >= def.value; + return { + id: def.id, kind: def.kind, label: def.label, pass, scenario: phase.id, + measured: metricText(def.metric, value) + (phase.applicable || phase.id === "steady" ? "" : ` (no ${phase.missing} to lose)`), + target: targetText(def.metric, def.op, def.value), + reason: pass ? undefined : whyMetricFailed(def.metric, phase.result, phase), + }; +} + +function drainCheck(def: Extract, steady: PhaseReport, scenarioId: string, inlineClicks: boolean, share = 1): CheckResult { + const { board, result, load } = steady; + const queue = board.nodes.find((n) => roleOf(n.kind) === "queue" && result.tiers.find((t) => t.id === n.id)?.reachable); + const items = def.items ?? "clicks"; + const done = def.done ?? "counted"; + const Items = items.charAt(0).toUpperCase() + items.slice(1); + const target = `no ${items} lost, all ${done} within ${def.maxDrainSeconds} s of the worker coming back`; + const base = { id: def.id, kind: def.kind, label: def.label, scenario: scenarioId, target }; + if (!queue && inlineClicks && !board.nodes.some((n) => roleOf(n.kind) === "queue")) { + return { ...base, pass: true, measured: `no worker to lose: ${items} are saved during the request (inline)` }; + } + if (!queue) { + // With no queue there is no link to read the rate from, so take the queue's share of the stream. + const lost = Math.round(load * share * def.outageSeconds); + return { ...base, pass: false, measured: `${lost.toLocaleString("en-US")} ${items} lost in ${def.outageSeconds} s`, reason: `${Items} have nowhere to wait while the worker is down. Put a queue between the app server and the worker.` }; + } + const workers = board.edges.filter((e) => e.from === queue.id).map((e) => result.tiers.find((t) => t.id === e.to)).filter((t): t is TierLoad => !!t && roleOf(t.kind) === "worker"); + if (workers.length === 0) { + return { ...base, pass: false, measured: `${items} pile up and are never ${done}`, reason: "The queue has no worker. Link the queue to a worker, and the worker to where it saves its work." }; + } + const arriving = board.edges.filter((e) => e.to === queue.id).reduce((sum, e) => sum + (result.edgeFlows[`${e.from}>${e.to}`] ?? 0), 0); + const capacity = workers.reduce((sum, w) => sum + w.capacity, 0); + const spare = capacity - arriving; + const backlog = Math.round(arriving * def.outageSeconds); + if (spare <= 0) { + return { ...base, pass: false, measured: `${backlog.toLocaleString("en-US")} ${items} waiting, never all ${done}`, reason: `Workers handle ${perSec(capacity)} but ${items} arrive at ${perSec(arriving)}: they can never catch up. Add workers or a bigger size.` }; + } + const drain = Math.ceil(backlog / spare); + const pass = drain <= def.maxDrainSeconds; + return { + ...base, pass, measured: `${backlog.toLocaleString("en-US")} ${items} waiting, all ${done} after ${drain} s`, + reason: pass ? undefined : `Workers have only ${perSec(spare)} to spare, so ${backlog.toLocaleString("en-US")} waiting ${items} take ${drain} s. Add workers or a bigger size.`, + }; +} + +// ---- the run ---------------------------------------------------------------------- + +/** Labs with no authored challenge are scored on their targets, as non-functional checks. */ +export function challengeFor(spec: HldLabSpec): ChallengeDef { + if (spec.challenge) return spec.challenge; + const level = spec.levels[0]; + const t = level?.targets ?? {}; + const checks: CheckDef[] = []; + const add = (id: string, label: string, metric: CheckMetric, op: "<=" | ">=", value?: number) => { + if (value != null) checks.push({ type: "metric", id, kind: "non-functional", label, scenario: "steady", metric, op, value }); + }; + add("capacity", "Serves the load", "capacity", ">=", t.rps); + add("p99", "Slowest 1 in 100 requests (p99)", "p99", "<=", t.p99Ms); + add("availability", "Stays up (availability)", "availability", ">=", t.availability); + add("cost", "Cost per hour", "cost", "<=", t.budgetPerHour); + return { peakLoad: level?.load ?? 1000, scenarios: [], checks }; +} + +/** The model run for a lab: the same options the challenge's own scenarios use, so every number agrees. */ +export function runModel(spec: HldLabSpec, board: Board, load: number, targets: Targets = {}): ModelResult { + const options: ModelOptions = { + inlineWrites: Boolean(spec.challenge?.inlineClicks) && !board.nodes.some((n) => roleOf(n.kind) === "queue"), + shares: spec.challenge?.shares, + }; + return runTieredModel(board, load, targets, options); +} + +/** Plays the board through the challenge. `board` must already carry the learner's properties. */ +export function runChallenge(spec: HldLabSpec, board: Board, load: number): ChallengeReport { + const challenge = challengeFor(spec); + const steadyResult = runModel(spec, board, load); + const phases: PhaseReport[] = [{ ...STEADY, load, board, hit: [], applicable: true, result: steadyResult }]; + for (const scenario of challenge.scenarios) { + const { board: faulted, hit, applicable } = applyFaults(board, scenario.faults, steadyResult); + const missing = applicable ? undefined : lower(roleLabel(scenario.faults[0]?.role ?? "compute")); + phases.push({ id: scenario.id, title: scenario.title, story: scenario.story, load, board: faulted, hit, applicable, missing, result: runModel(spec, faulted, load) }); + } + const byId = new Map(phases.map((p) => [p.id, p])); + const steady = phases[0]!; + const checks: CheckResult[] = challenge.checks.map((def) => { + if (def.type === "path") return pathCheck(def, board); + if (def.type === "drain") return drainCheck(def, steady, challenge.scenarios.find((s) => s.faults.some((f) => f.type === "down" && f.role === "worker"))?.id ?? "steady", Boolean(challenge.inlineClicks), challenge.shares?.queue ?? 1); + return metricCheck(def, byId); + }); + const passed = checks.filter((c) => c.pass).length; + return { phases, checks, passed, total: checks.length, allPass: passed === checks.length }; +} diff --git a/packages/learning-ui/src/shared/lab/engine/hld-types.ts b/packages/learning-ui/src/shared/lab/engine/hld-types.ts new file mode 100644 index 00000000..7ffcb2a4 --- /dev/null +++ b/packages/learning-ui/src/shared/lab/engine/hld-types.ts @@ -0,0 +1,144 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The pure data shapes of a high-level design (HLD) lab: the board, the challenge, the +// reference solution and the HLD spec. No UI and no network imports, so the server can +// replay a design with the same types the lab board uses. + +import type { ComponentKind, Role } from "./catalog"; + +export type LabFamily = "hld" | "db" | "net"; + +export interface BoardNode { + id: string; + kind: ComponentKind; + x: number; + y: number; + props?: Record; +} + +export interface BoardEdge { + from: string; + to: string; + /** Which dot each end uses (t, r, b, l); the board picks bottom to top when absent. */ + via?: [string, string]; +} + +export interface Board { + nodes: BoardNode[]; + edges: BoardEdge[]; +} + +export interface LabLevel { + id: string; + load: number; + targets: { rps?: number; p99Ms?: number; availability?: number; budgetPerHour?: number }; + event?: string; +} + +// ---- challenge: the checks a visual lab's Run puts the design through ---------- + +/** Something that goes wrong in a scenario. */ +export type Fault = + /** One instance of the first component with this role dies; a fleet of one dies whole. */ + | { type: "lose-instance"; role: Role } + /** Every component with this role goes down. */ + | { type: "down"; role: Role }; + +export interface ChallengeScenario { + id: string; + /** Short name, shown on the run strip: "The cache dies". */ + title: string; + /** One line shown while this phase plays. */ + story: string; + faults: Fault[]; +} + +export type CheckMetric = "p99" | "capacity" | "served" | "availability" | "cost"; + +interface CheckBase { + id: string; + kind: "functional" | "non-functional"; + label: string; +} + +export type CheckDef = + /** A functional check: a request can travel client -> ... -> the next role, in order. */ + | (CheckBase & { + type: "path"; + chain: Role[]; + target: string; + /** A design with no component of this role passes without the chain: the work is done inline instead. */ + inlineIfNo?: Role; + }) + /** A measured check: one number from one scenario against a limit. */ + | (CheckBase & { type: "metric"; scenario: string; metric: CheckMetric; op: "<=" | ">="; value: number }) + /** Work queued while its consumer is down must be fully counted once it is back. */ + | (CheckBase & { + type: "drain"; + outageSeconds: number; + maxDrainSeconds: number; + /** What waits in the queue, plural: "clicks" (the default), "posts", "messages". */ + items?: string; + /** What happens to each item once a worker takes it: "counted" (the default), "delivered", "saved". */ + done?: string; + }); + +export interface ChallengeDef { + /** Requests a second at the busiest moment; every scenario runs at this load. */ + peakLoad: number; + /** + * With no queue on the board, each request writes its click to the database before it + * answers, so counting works but costs a database write per request. + */ + inlineClicks?: boolean; + /** + * The share of requests that send work to parts of a role, for side jobs only some + * requests need: { queue: 0.1 } means 1 request in 10 leaves a job in the queue. + * Each share is above 0 and at most 1; a role with no share gets the whole stream. + */ + shares?: Partial>; + scenarios: ChallengeScenario[]; + checks: CheckDef[]; +} + +// ---- solution: a reference design a learner can open and compare with ---------- + +/** Why one part is in the reference design. */ +export interface SolutionPart { + /** Plain words: what this part does in the design. */ + why: string; + /** Ids of the checks this part helps pass. */ + checks: string[]; + /** What goes wrong without it, with numbers from the model. */ + without: string; +} + +export interface SolutionDef { + /** The reference design. It must pass every check of the lab. */ + board: Board; + /** One or two plain sentences: the idea behind the design. */ + summary: string; + /** Keyed by node id in `board`. */ + parts: Record; +} + +export interface LabBase { + slug: string; + family: LabFamily; + title: string; + purpose: string; + limits: string; + hints: string[]; + referenceSlug?: string; +} + +export interface HldLabSpec extends LabBase { + family: "hld"; + allowedComponents: ComponentKind[]; + startingBoard?: Board; + scenario: string; + levels: LabLevel[]; + /** A visual challenge: functional and non-functional checks and the scenarios that test them. */ + challenge?: ChallengeDef; + /** A reference design the learner can open after pressing Run, and compare with their own. */ + solution?: SolutionDef; +} diff --git a/packages/learning-ui/src/shared/lab/engine/tiered-architecture.ts b/packages/learning-ui/src/shared/lab/engine/tiered-architecture.ts new file mode 100644 index 00000000..d3e8152a --- /dev/null +++ b/packages/learning-ui/src/shared/lab/engine/tiered-architecture.ts @@ -0,0 +1,538 @@ +// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/. +// The tiered-architecture model: the engine behind the lab board. Pure and +// server-importable (no DOM, no React), so a graded lab can run it on the server. +// +// From a board and an offered load it routes requests down the links, evaluates +// every component by its role and configuration (instance fleets, autoscaling, +// zones, read replicas, managed services billed per request, Lambda concurrency, +// rate limits, queues), and returns utilisation, the capacity ceiling, p50/p99 +// latency with the queueing knee, availability and cost, scored against targets. +// +// Numbers are illustrative. The rules below are stated so a "how this is +// calculated" panel can show them. + +import type { Board, BoardNode } from "./hld-types"; +import type { ComponentKind, Role, SizeTier } from "./catalog"; +import { COMPONENT_CATALOG, SIZE_CATALOG, roleOf } from "./catalog"; + +const PER_VCPU: Record = { general: 800, compute: 1200, memory: 600 }; +/** Roles that serve far more, or far less, per vCPU than a typical app server. */ +const ROLE_RATE: Partial> = { cache: 15_000, search: 300, nosql: 2_000 }; +const NETWORK_MS = 10; +/** Chance a single Availability Zone is up. */ +const AZ_AVAIL = 0.9995; +/** Regional managed services are spread across zones by the provider. */ +const MANAGED_AVAIL = 0.9999; + +const SERVICE_MS: Record = { + client: 0, dns: 1, cdn: 2, firewall: 1, limiter: 1, balancer: 2, gateway: 5, + compute: 20, function: 0, worker: 15, cache: 1, database: 8, nosql: 5, search: 25, + queue: 5, stream: 10, storage: 20, +}; +const SINGLE_AVAIL: Partial> = { + balancer: 0.9995, gateway: 0.9995, compute: 0.99, worker: 0.99, cache: 0.999, + database: 0.999, nosql: 0.9995, search: 0.999, stream: 0.999, +}; + +export interface TierLoad { + id: string; + kind: ComponentKind; + capacity: number; + utilisation: number; + down: boolean; + reachable: boolean; + /** Instances actually running, after autoscaling. */ + units: number; + /** Managed services scale for you; their utilisation is rarely the story. */ + managed: boolean; + /** A short line for the card: autoscaled, throttling, backlog, and so on. */ + note?: string; + /** What this component costs per hour whether or not it is serving. */ + cost: number; + /** Milliseconds a request spends waiting in line here, on top of its service time. Zero off the request path. */ + waitMs: number; + /** For a cache: what it was asked, what it answered itself, and what went on to the database. */ + cacheStats?: { hitRate: number; reads: number; hits: number; misses: number }; +} + +/** One labelled share of the traffic on a link, such as "cache misses" or "click writes". */ +export interface EdgePart { + label: string; + rate: number; +} + +/** Optional rules a lab can switch on for the whole run. */ +export interface ModelOptions { + /** + * Every request an app server serves also writes one row (a click) to the database + * before it answers. Labs turn this on when the board has no queue to carry the clicks. + */ + inlineWrites?: boolean; + /** + * The share of requests that send work to parts of a role, for side jobs that only + * some requests need: { queue: 0.1 } means 1 request in 10 leaves a job in the queue. + * Applied wherever a part of another role sends to that role, so it holds however the + * learner links the board. A role with no share gets the whole stream. + */ + shares?: Partial>; +} + +export interface Targets { + rps?: number; + p99Ms?: number; + availability?: number; + budgetPerHour?: number; +} + +export interface ModelResult { + capacityCeiling: number; + p50Ms: number; + p99Ms: number; + availability: number; + costPerHour: number; + tiers: TierLoad[]; + pass: { rps: boolean; p99: boolean; availability: boolean; budget: boolean }; + allPass: boolean; + /** Why the design is broken, when a component is down or unlinked. */ + failure?: string; + /** Request rate on each live link, keyed "from>to". */ + edgeFlows: Record; + /** What the traffic on a link is made of, where that is worth saying (cache reads, misses, writes). */ + edgeParts: Record; + /** Requests rejected by rate limits and throttles, per second. */ + dropped: number; + /** Requests filtered out by firewalls, per second. */ + blocked: number; + /** How fast queued work piles up because consumers are too slow, per second. */ + backlog: number; + /** The role on the request path with the lowest availability, for "add redundancy here". */ + weakest?: { role: Role; availability: number }; +} + +// ---- reading a node's configuration ------------------------------------------- + +function propOf(node: BoardNode, key: string): number | string | undefined { + const own = node.props?.[key]; + if (own !== undefined) return own; + return COMPONENT_CATALOG[node.kind].properties.find((p) => p.id === key)?.default; +} +function num(node: BoardNode, key: string, fallback: number): number { + const v = propOf(node, key); + return typeof v === "number" ? v : fallback; +} +function str(node: BoardNode, key: string, fallback: string): string { + const v = propOf(node, key); + return typeof v === "string" ? v : fallback; +} +function tierOf(node: BoardNode): SizeTier { + const id = propOf(node, "size"); + return SIZE_CATALOG.find((t) => t.id === id) ?? SIZE_CATALOG[0]; +} +const isDown = (node: BoardNode) => Boolean(node.props?.down); +const rate = (n: number) => Math.round(n).toLocaleString("en-US"); + +/** A fleet of `units` spread over `zones`; it is up while any zone has a live instance. */ +function fleetAvailability(single: number, units: number, zones: number): number { + const n = Math.max(1, Math.round(zones)); + const perZone = Math.max(1, units / n); + const zone = AZ_AVAIL * (1 - Math.pow(1 - single, perZone)); + return 1 - Math.pow(1 - zone, n); +} + +// ---- routing -------------------------------------------------------------------- + +/** Nodes a request can reach from any live client, following the links and skipping down nodes. */ +function reachableFrom(board: Board): Set { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + const next = new Map(); + for (const e of board.edges) next.set(e.from, [...(next.get(e.from) ?? []), e.to]); + const seen = new Set(); + const queue = board.nodes.filter((n) => n.kind === "client" && !isDown(n)).map((n) => n.id); + for (const id of queue) seen.add(id); + while (queue.length > 0) { + const id = queue.shift()!; + for (const to of next.get(id) ?? []) { + const node = byId.get(to); + if (node && !isDown(node) && !seen.has(to)) { + seen.add(to); + queue.push(to); + } + } + } + return seen; +} + +/** Live links between reachable nodes, deduplicated, as parent to children and child to parents. */ +function liveLinks(board: Board, reachable: Set) { + const children = new Map(); + const parents = new Map(); + for (const e of board.edges) { + if (!reachable.has(e.from) || !reachable.has(e.to) || e.from === e.to) continue; + const kids = children.get(e.from) ?? []; + if (kids.includes(e.to)) continue; + children.set(e.from, [...kids, e.to]); + parents.set(e.to, [...(parents.get(e.to) ?? []), e.from]); + } + return { children, parents }; +} + +/** Reachable nodes in topological order (Kahn), so load and latency flow parent before child. */ +function topoOrder(reachable: Set, children: Map, parents: Map): string[] { + const indegree = new Map([...reachable].map((id) => [id, (parents.get(id) ?? []).length])); + const queue = [...reachable].filter((id) => indegree.get(id) === 0); + const order: string[] = []; + while (queue.length > 0) { + const id = queue.shift()!; + order.push(id); + for (const kid of children.get(id) ?? []) { + indegree.set(kid, (indegree.get(kid) ?? 1) - 1); + if (indegree.get(kid) === 0) queue.push(kid); + } + } + return order; +} + +const ASYNC_ROLES = new Set(["queue", "stream"]); + +/** Nodes on the synchronous request path: reachable without passing through a queue or stream. */ +function synchronous(order: string[], byId: Map, children: Map): Set { + const seen = new Set(order.filter((id) => byId.get(id)!.kind === "client")); + const queue = [...seen]; + while (queue.length > 0) { + const id = queue.shift()!; + if (ASYNC_ROLES.has(roleOf(byId.get(id)!.kind))) continue; + for (const kid of children.get(id) ?? []) { + if (!seen.has(kid)) { + seen.add(kid); + queue.push(kid); + } + } + } + return seen; +} + +/** The most a node lets through per second; above it, requests are rejected. */ +function limitOf(node: BoardNode): number | undefined { + if (node.kind === "rate-limiter" || node.kind === "aws-api-gateway") return num(node, "limit", Infinity); + if (node.kind === "aws-lambda") return lambdaCapacity(node); + return undefined; +} +/** Share of what a node serves that continues downstream (CDN misses, traffic a firewall lets in). */ +function passOn(node: BoardNode): number { + const role = roleOf(node.kind); + if (role === "cdn") return 1 - num(node, "hitRate", 0); + if (role === "firewall") return 1 - num(node, "blockRate", 0); + // A cache answers its hits itself; only the misses go on to a database linked behind it. + if (role === "cache") return 1 - num(node, "hitRate", 0); + return 1; +} +function lambdaCapacity(node: BoardNode): number { + return (num(node, "concurrency", 1000) * 1000) / Math.max(1, num(node, "durationMs", 120)); +} + +// ---- evaluating one component ---------------------------------------------------- + +interface Evaluation { + capacity: number; + units: number; + cost: number; + serviceMs: number; + availability: number; + /** Whether requests wait in line as it gets busy (the p99 knee), or are throttled instead. */ + queueing: boolean; + managed: boolean; + note?: string; +} + +function evaluate(node: BoardNode, flow: number, inlineWrites = 0): Evaluation { + const def = COMPONENT_CATALOG[node.kind]; + const role = def.role; + + if (node.kind === "aws-lambda") { + const duration = Math.max(1, num(node, "durationMs", 120)); + const memoryGb = Number(str(node, "memoryMb", "512")) / 1024; + const capacity = lambdaCapacity(node); + const cost = flow * 3600 * (0.2 / 1e6 + (duration / 1000) * memoryGb * 0.0000166667); + const note = flow > capacity ? `throttling ${rate(flow - capacity)}/s` : flow > 0 ? `~${rate(Math.ceil((flow * duration) / 1000))} running at once` : undefined; + return { capacity, units: 1, cost, serviceMs: duration, availability: MANAGED_AVAIL, queueing: false, managed: true, note }; + } + + if (node.kind === "aws-dynamodb") { + const reads = num(node, "readRatio", 0.8); + if (str(node, "capacityMode", "on-demand") === "provisioned") { + const rcu = num(node, "rcu", 1000); + const wcu = num(node, "wcu", 500); + const util = Math.max((flow * reads) / (rcu * 2), (flow * (1 - reads)) / wcu); + return { + capacity: util > 0 ? flow / util : rcu * 2 + wcu, units: 1, cost: rcu * 0.00013 + wcu * 0.00065, + serviceMs: 5, availability: MANAGED_AVAIL, queueing: false, managed: true, + note: util > 1 ? "throttled: raise RCU/WCU or go on-demand" : undefined, + }; + } + return { + capacity: 40_000, units: 1, cost: (flow * 3600 * (reads * 0.25 + (1 - reads) * 1.25)) / 1e6, + serviceMs: 5, availability: MANAGED_AVAIL, queueing: false, managed: true, + }; + } + + if (role === "stream") { + const shards = num(node, "partitions", 2); + const aws = def.family === "aws"; + return { + capacity: shards * 1000, units: shards, cost: shards * 0.015 + (aws ? (flow * 3600 * 0.014) / 1e6 : 0), + serviceMs: SERVICE_MS.stream, availability: aws ? MANAGED_AVAIL : fleetAvailability(0.999, shards, 1), + queueing: false, managed: aws, note: flow > shards * 1000 ? "producers throttled: add shards" : undefined, + }; + } + + if (def.managed) { + let capacity = def.managed.capacity; + let perMillion = def.managed.pricePerMillion; + if (node.kind === "aws-api-gateway" && str(node, "apiType", "HTTP") === "REST") perMillion = 3.5; + if (node.kind === "aws-sqs" && str(node, "queueType", "standard") === "FIFO") capacity = 3000; + const hourly = node.kind === "k8s-service" && str(node, "serviceType", "ClusterIP") === "LoadBalancer" ? 0.0225 : def.managed.pricePerHour; + const limit = limitOf(node); + if (limit != null) capacity = Math.min(capacity, limit); + const hasZones = def.properties.some((p) => p.id === "azs"); + const availability = hasZones ? fleetAvailability(0.99999, 1, num(node, "azs", 2)) : MANAGED_AVAIL; + const note = limit != null && flow > limit ? `rejecting ${rate(flow - limit)}/s` : undefined; + return { + capacity, units: 1, cost: hourly + (flow * 3600 * perMillion) / 1e6, + serviceMs: SERVICE_MS[role] + (node.kind === "aws-api-gateway" ? 5 : 0), + availability, queueing: false, managed: true, note, + }; + } + + // Instance-based: a fleet of servers of one size. + const tier = tierOf(node); + const perUnit = tier.vcpu * (ROLE_RATE[role] ?? PER_VCPU[tier.family]); + const single = SINGLE_AVAIL[role] ?? 0.99; + + if (role === "database") { + const replicas = num(node, "replicas", 0); + const reads = num(node, "readRatio", 0.8); + const multiAz = num(node, "multiAz", 0) > 0; + // Every write goes to the primary; reads spread over the primary and its replicas. + // Inline writes are all writes: they are part of the flow but never reads. + const other = Math.max(0, flow - inlineWrites); + const util = Math.max(other * (1 - reads) + inlineWrites, (other * reads) / (1 + replicas)) / perUnit; + const parts = [replicas > 0 ? `${replicas} read replica${replicas === 1 ? "" : "s"}` : null, multiAz ? "Multi-AZ" : null].filter(Boolean); + return { + capacity: util > 0 ? flow / util : perUnit * (1 + replicas), units: 1 + replicas, + cost: tier.pricePerHour * ((multiAz ? 2 : 1) + replicas), serviceMs: SERVICE_MS.database, + availability: fleetAvailability(single, 1, multiAz ? 2 : 1), queueing: true, managed: false, + note: parts.length > 0 ? parts.join(", ") : undefined, + }; + } + + let units = node.kind === "load-balancer" ? num(node, "zones", 1) : num(node, "count", 1); + let note: string | undefined; + if (num(node, "autoscale", 0) > 0) { + const min = Math.max(1, num(node, "minCount", 1)); + const max = Math.max(min, num(node, "maxCount", 10)); + const target = Math.min(1, Math.max(0.05, num(node, "targetUtil", 0.6))); + units = Math.min(max, Math.max(min, Math.ceil(flow / (perUnit * target) - 1e-9))); + note = units === max && flow / (perUnit * units) > target ? `at max ${max}: raise the max or the size` : `autoscaled to ${units} (${min} to ${max})`; + } + + let cost = tier.pricePerHour * units; + let availabilityUnits = units; + if (node.kind === "aws-elasticache") { + const replicasPerShard = num(node, "replicasPerShard", 1); + cost = tier.pricePerHour * units * (1 + replicasPerShard); + availabilityUnits = 1 + replicasPerShard; + } + const zones = node.kind === "load-balancer" ? units : num(node, "azs", 1); + return { + capacity: perUnit * units, units, cost, serviceMs: SERVICE_MS[role], + availability: fleetAvailability(single, availabilityUnits, zones), queueing: true, managed: false, note, + }; +} + +// ---- the model ------------------------------------------------------------------- + +export function runTieredModel(board: Board, load: number, targets: Targets, options: ModelOptions = {}): ModelResult { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + const reachable = reachableFrom(board); + const { children, parents } = liveLinks(board, reachable); + const order = topoOrder(reachable, children, parents); + const sync = synchronous(order, byId, children); + + // Load enters at the live clients and flows down the links. A node first applies + // its limit (rejecting the excess), then passes on what continues (CDN misses, + // traffic the firewall lets in). Parallel children with the same role share it; + // different roles are different services and each see the whole stream; a + // database or key-value store beside a cache only sees the cache misses. + const incoming = new Map(); + const inlineWrites = new Map(); + const edgeFlows: Record = {}; + const edgeParts: Record = {}; + const addPart = (key: string, label: string, rate: number) => { (edgeParts[key] ??= []).push({ label, rate }); }; + let dropped = 0; + let blocked = 0; + const clients = order.filter((id) => byId.get(id)!.kind === "client"); + for (const id of clients) incoming.set(id, load / clients.length); + for (const id of order) { + const node = byId.get(id)!; + const flowIn = incoming.get(id) ?? 0; + const limit = limitOf(node); + const served = limit != null ? Math.min(flowIn, limit) : flowIn; + dropped += flowIn - served; + const out = served * passOn(node); + if (roleOf(node.kind) === "firewall") blocked += served - out; + + const kids = (children.get(id) ?? []).map((k) => byId.get(k)!); + const cache = kids.find((n) => roleOf(n.kind) === "cache"); + const missRate = cache ? 1 - num(cache, "hitRate", 0) : 1; + // Read-through: a store that the cache itself links to is loaded by the cache on a miss, + // so the app server's own link to it carries no reads (it never counts twice). + const behindCache = new Set(cache ? children.get(cache.id) ?? [] : []); + const byRole = new Map(); + for (const kid of kids) { + if (behindCache.has(kid.id)) continue; + byRole.set(roleOf(kid.kind), [...(byRole.get(roleOf(kid.kind)) ?? []), kid.id]); + } + for (const [role, ids] of byRole) { + const stores = role === "database" || role === "nosql"; + // A worker batches its writes: one trip to the store carries `batchSize` events. + const batch = node.kind === "worker" && stores ? Math.max(1, num(node, "batchSize", 1)) : 1; + // A side job only some requests need (an alert, an index update) carries its share of the stream. + const part = role !== roleOf(node.kind) ? (options.shares?.[role] ?? 1) : 1; + const share = (stores ? (out * missRate) / batch : out) * part; + for (const k of ids) { + const key = `${id}>${k}`; + const rate = share / ids.length; + incoming.set(k, (incoming.get(k) ?? 0) + rate); + edgeFlows[key] = (edgeFlows[key] ?? 0) + rate; + if (part < 1) addPart(key, `${Math.round(part * 1000) / 10}% of requests send work here`, rate); + if (role === "cache") addPart(key, `reads, ${Math.round(num(byId.get(k)!, "hitRate", 0) * 100)}% answered by the cache`, rate); + else if (stores && node.kind === "worker" && batch > 1) addPart(key, `writes, ${batch} per trip`, rate); + else if (stores && cache) addPart(key, "cache misses", rate); + else if (stores && roleOf(node.kind) === "cache") addPart(key, "cache misses", rate); + } + } + if (options.inlineWrites && roleOf(node.kind) === "compute") { + // The click write goes to the store whether the app server reaches it directly or through its cache. + const direct = kids.filter((k) => roleOf(k.kind) === "database"); + const through = (cache ? children.get(cache.id) ?? [] : []).map((k) => byId.get(k)!).filter((k) => roleOf(k.kind) === "database"); + const stores = [...new Map([...direct, ...through].map((k) => [k.id, k])).values()]; + for (const store of stores) { + const writes = out / stores.length; + const key = direct.some((d) => d.id === store.id) ? `${id}>${store.id}` : `${cache!.id}>${store.id}`; + incoming.set(store.id, (incoming.get(store.id) ?? 0) + writes); + inlineWrites.set(store.id, (inlineWrites.get(store.id) ?? 0) + writes); + edgeFlows[key] = (edgeFlows[key] ?? 0) + writes; + addPart(key, direct.some((d) => d.id === store.id) ? "click writes" : "click writes, written directly", writes); + } + } + } + + const evaluations = new Map(); + const tiers: TierLoad[] = []; + let cost = 0; + for (const node of board.nodes) { + if (node.kind === "client") continue; + const down = isDown(node); + const onPath = reachable.has(node.id); + const flow = onPath ? incoming.get(node.id) ?? 0 : 0; + const ev = evaluate(node, flow, inlineWrites.get(node.id) ?? 0); + const capacity = down ? 0 : ev.capacity; + evaluations.set(node.id, ev); + cost += ev.cost; // placed hardware costs money whether or not it is serving + tiers.push({ + id: node.id, kind: node.kind, capacity, utilisation: capacity > 0 ? flow / capacity : 0, + down, reachable: onPath, units: ev.units, managed: ev.managed, note: ev.note, cost: ev.cost, waitMs: 0, + cacheStats: roleOf(node.kind) === "cache" && onPath + ? { hitRate: num(node, "hitRate", 0), reads: flow, hits: flow * num(node, "hitRate", 0), misses: flow * (1 - num(node, "hitRate", 0)) } + : undefined, + }); + } + const tierById = new Map(tiers.map((t) => [t.id, t])); + + // Work behind a queue is asynchronous: slow consumers build a backlog, not slow requests. + let backlog = 0; + for (const id of order) { + const node = byId.get(id)!; + if (!ASYNC_ROLES.has(roleOf(node.kind))) continue; + const consumers = (children.get(id) ?? []).reduce((sum, k) => sum + (tierById.get(k)?.capacity ?? 0), 0); + const behind = Math.max(0, (incoming.get(id) ?? 0) - consumers); + backlog += behind; + const tier = tierById.get(id); + // A consumer that is down is still linked: say so, instead of "no consumers linked". + const linkedButDown = board.edges.some((e) => e.from === id && isDown(byId.get(e.to)!)); + if (tier) tier.note = consumers === 0 ? (linkedButDown ? `consumers down, backlog grows ${rate(behind)}/s` : "no consumers linked") : behind > 0 ? `backlog grows ${rate(behind)}/s` : "consumers keeping up"; + } + + // Capacity, latency and availability of the synchronous request path. + let ceiling = Number.POSITIVE_INFINITY; + const roleAvail = new Map(); + const lat50 = new Map(); + const lat99 = new Map(); + for (const id of order) { + if (!sync.has(id)) continue; + const tier = tierById.get(id); + const ev = evaluations.get(id); + if (tier && ev) { + const flow = incoming.get(id) ?? 0; + if (flow > 0 && tier.capacity > 0) ceiling = Math.min(ceiling, (tier.capacity * load) / flow); + const role = roleOf(tier.kind); + roleAvail.set(role, [...(roleAvail.get(role) ?? []), ev.availability]); + } + const service = ev?.serviceMs ?? 0; + const u = ev?.queueing && tier ? Math.min(tier.utilisation, 0.985) : 0; + const before = (parents.get(id) ?? []).filter((p) => sync.has(p)); + lat50.set(id, service + Math.max(0, ...before.map((p) => lat50.get(p) ?? 0))); + lat99.set(id, service / (1 - u) + Math.max(0, ...before.map((p) => lat99.get(p) ?? 0))); + if (tier) tier.waitMs = service / (1 - u) - service; + } + const p50 = NETWORK_MS + Math.max(0, ...lat50.values()); + const p99 = NETWORK_MS + Math.max(0, ...lat99.values()); + + // Parallel components with the same role back each other up; the roles are in series. + let availability = 1; + let weakest: ModelResult["weakest"]; + for (const [role, parts] of roleAvail) { + const roleUp = 1 - parts.reduce((all, a) => all * (1 - a), 1); + availability *= roleUp; + if (!weakest || roleUp < weakest.availability) weakest = { role, availability: roleUp }; + } + + // A placed database that requests cannot reach means nothing is served. + let failure: string | undefined; + const stores = board.nodes.filter((n) => roleOf(n.kind) === "database" || roleOf(n.kind) === "nosql"); + if (stores.length > 0 && !stores.some((n) => reachable.has(n.id))) { + ceiling = 0; + availability = 0; + const blocker = board.nodes.find((n) => isDown(n) && board.edges.some((e) => e.from === n.id || e.to === n.id)); + failure = blocker + ? `${COMPONENT_CATALOG[blocker.kind].label} is down: requests through it fail.` + : "The database is not linked into the request path."; + } + + if (!Number.isFinite(ceiling)) ceiling = 0; + + const pass = { + rps: targets.rps == null ? true : ceiling >= targets.rps, + p99: targets.p99Ms == null ? true : p99 <= targets.p99Ms, + availability: targets.availability == null ? true : availability >= targets.availability, + budget: targets.budgetPerHour == null ? true : cost <= targets.budgetPerHour, + }; + + return { + capacityCeiling: Math.round(ceiling), + p50Ms: Math.round(p50), + p99Ms: Math.round(p99), + availability, + failure, + edgeFlows, + edgeParts, + dropped, + blocked, + backlog, + weakest, + costPerHour: cost, + tiers, + pass, + allPass: pass.rps && pass.p99 && pass.availability && pass.budget, + }; +} diff --git a/server/src/shared/games/sysdesign/engine.ts b/server/src/shared/games/sysdesign/engine.ts index d03f363a..efb4dbf8 100644 --- a/server/src/shared/games/sysdesign/engine.ts +++ b/server/src/shared/games/sysdesign/engine.ts @@ -1,73 +1,187 @@ -// System Design Runner: each round is a production incident on a small AWS system. The player -// picks a few changes, and a deterministic traffic simulation says whether the goals are met. +// System Design Runner: each round is a production incident on a small AWS system, played on the +// platform's own lab board. The player changes the design and runs the lab's tests; this engine +// replays the submitted board through the same challenge (runChallenge), so the browser and the +// server always agree. A design passes only when every check of the lab passes. +import { COMPONENT_CATALOG, canConnect, isComponentKind, sizesFor, type ComponentKind } from "../../lab/engine/catalog.js"; +import { runChallenge, runModel } from "../../lab/engine/challenge.js"; +import type { Board, BoardEdge, BoardNode, HldLabSpec } from "../../lab/engine/hld-types.js"; import { pickDaily } from "../daily.js"; import type { GameEngine, Stars, VerifyResult } from "../types.js"; -import { SYSDESIGN_POOL } from "./scenarios.js"; -import { evaluateGoals, simulate } from "./sim.js"; +import { SYSDESIGN_POOL } from "./incidents.js"; import type { SysdesignRound, SysdesignSubmission } from "./types.js"; export type { SysdesignRound, SysdesignSubmission } from "./types.js"; -export type { ChangeDef, ComponentId, CostLine, GoalCheck, Goals, Model, Pricing, SimResult, StepResult, StepStatus, Stretch } from "./types.js"; -export { STEPS } from "./types.js"; -export { applyChanges, costDelta, evaluateGoals, simulate } from "./sim.js"; -export { SYSDESIGN_POOL } from "./scenarios.js"; +export { SYSDESIGN_POOL } from "./incidents.js"; -/** Hard ceiling on a submission, whatever the round allows. */ -const MAX_PARSED_CHANGES = 8; +/** Hard limits on a submitted board, whatever the round allows. The biggest reference has 6 parts. */ +export const MAX_NODES = 14; +export const MAX_EDGES = 30; +/** Most parts of one kind. A board has exactly one client. */ +export const MAX_PER_KIND = 3; +/** In this game a cache or a CDN counts only up to this hit rate, so nobody wins by typing 100%. */ +export const MAX_HIT_RATE = 0.9; +/** Settings that describe the traffic, not the design. They must keep the value the incident gives them. */ +const WORKLOAD_PROPS = ["readRatio", "load", "blockRate", "ttl"] as const; -function fail(message: string): VerifyResult { - return { passed: false, stars: 0, score: 0, message }; +const isObject = (value: unknown): value is Record => typeof value === "object" && value !== null && !Array.isArray(value); +const onlyKeys = (value: Record, allowed: readonly string[]) => Object.keys(value).every((k) => allowed.includes(k)); +const ID = /^[A-Za-z0-9_-]{1,32}$/; +const HANDLES = ["t", "r", "b", "l"]; +const COORD = 100_000; + +/** Every part any incident allows. A board with another kind is not read at all. */ +const KINDS_IN_GAME: ReadonlySet = new Set(SYSDESIGN_POOL.flatMap((r) => r.spec.allowedComponents)); + +function parseProps(kind: ComponentKind, raw: unknown): Record | null { + if (raw !== undefined && !isObject(raw)) return null; + const given = raw ?? {}; + const props: Record = {}; + const defs = COMPONENT_CATALOG[kind].properties; + if (!onlyKeys(given, defs.map((d) => d.id))) return null; + for (const def of defs) { + const value = given[def.id] ?? def.default; + if (def.type === "size") { + if (typeof value !== "string" || !sizesFor(def.sizeSet!).some((t) => t.id === value)) return null; + } else if (def.type === "enum") { + if (typeof value !== "string" || !(def.options ?? []).includes(value)) return null; + } else if (def.type === "toggle") { + if (value !== 0 && value !== 1) return null; + } else { + if (typeof value !== "number" || !Number.isFinite(value)) return null; + if (value < (def.min ?? -Infinity) || value > (def.max ?? Infinity)) return null; + if (def.type === "count" && !Number.isInteger(value)) return null; + } + props[def.id] = value; + } + return props; +} + +function parseBoard(raw: unknown): Board | null { + if (!isObject(raw) || !onlyKeys(raw, ["nodes", "edges"])) return null; + const { nodes: rawNodes, edges: rawEdges } = raw; + if (!Array.isArray(rawNodes) || !Array.isArray(rawEdges)) return null; + if (rawNodes.length === 0 || rawNodes.length > MAX_NODES || rawEdges.length > MAX_EDGES) return null; + + const nodes: BoardNode[] = []; + const byId = new Map(); + for (const entry of rawNodes) { + if (!isObject(entry) || !onlyKeys(entry, ["id", "kind", "x", "y", "props"])) return null; + const { id, kind, x = 0, y = 0 } = entry; + if (typeof id !== "string" || !ID.test(id) || byId.has(id)) return null; + if (typeof kind !== "string" || !isComponentKind(kind) || !KINDS_IN_GAME.has(kind)) return null; + if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y) || Math.abs(x) > COORD || Math.abs(y) > COORD) return null; + const props = parseProps(kind, entry.props); + if (props === null) return null; + const node: BoardNode = { id, kind, x, y, props }; + nodes.push(node); + byId.set(id, node); + } + + const edges: BoardEdge[] = []; + const seen = new Set(); + for (const entry of rawEdges) { + if (!isObject(entry) || !onlyKeys(entry, ["from", "to", "via"])) return null; + const { from, to, via } = entry; + if (typeof from !== "string" || typeof to !== "string" || from === to) return null; + const a = byId.get(from); + const b = byId.get(to); + if (!a || !b || !canConnect(a.kind, b.kind)) return null; + if (via !== undefined && !(Array.isArray(via) && via.length === 2 && via.every((h) => typeof h === "string" && HANDLES.includes(h)))) return null; + const key = `${from}>${to}`; + if (seen.has(key)) return null; + seen.add(key); + edges.push({ from, to }); + } + return { nodes, edges }; +} + +const fail = (message: string): VerifyResult => ({ passed: false, stars: 0, score: 0, message }); +const usd = (n: number) => `$${n.toFixed(2)}`; + +/** The value a workload setting must keep: the one the incident's starting board gives that kind, else the default. */ +function workloadValue(spec: HldLabSpec, kind: ComponentKind, key: string): number | string | undefined { + const start = spec.startingBoard?.nodes.find((n) => n.kind === kind); + return start?.props?.[key] ?? COMPONENT_CATALOG[kind].properties.find((p) => p.id === key)?.default; } +/** + * The rules about what a board may contain for this incident, in one plain sentence when broken. + * The lab itself lets you type any number; the game does not accept a design that cheats. + */ +export function boardProblem(spec: HldLabSpec, board: Board): string | null { + const counts = new Map(); + for (const node of board.nodes) { + if (!spec.allowedComponents.includes(node.kind)) return `${COMPONENT_CATALOG[node.kind].label} is not one of the parts you can use in this round.`; + counts.set(node.kind, (counts.get(node.kind) ?? 0) + 1); + } + if ((counts.get("client") ?? 0) !== 1) return "The design needs exactly one client."; + for (const [kind, n] of counts) { + if (n > MAX_PER_KIND && kind !== "client") return `A design can have at most ${MAX_PER_KIND} ${COMPONENT_CATALOG[kind].label} parts.`; + } + for (const node of board.nodes) { + const role = COMPONENT_CATALOG[node.kind].role; + const hit = node.props?.hitRate; + if ((role === "cache" || role === "cdn") && typeof hit === "number" && hit > MAX_HIT_RATE) { + return `A hit rate above ${Math.round(MAX_HIT_RATE * 100)}% is not realistic. Set the ${COMPONENT_CATALOG[node.kind].label} hit rate to ${Math.round(MAX_HIT_RATE * 100)}% or less.`; + } + for (const key of WORKLOAD_PROPS) { + const value = node.props?.[key]; + if (value !== undefined && value !== workloadValue(spec, node.kind, key)) { + const label = COMPONENT_CATALOG[node.kind].properties.find((p) => p.id === key)?.label ?? key; + return `"${label}" describes the traffic, not the design. Keep it at ${String(workloadValue(spec, node.kind, key))}.`; + } + } + } + return null; +} + +const partsOf = (board: Board) => board.nodes.filter((n) => n.kind !== "client").length; + export const sysdesignEngine: GameEngine = { id: "sysdesign", title: "System Design Runner", - tagline: "A real incident on a small AWS system. Pick the fixes, run the traffic, and meet the goals.", + tagline: "A real AWS system is breaking. Fix the design on the lab board until every check passes.", roundsFor: (dayKey) => pickDaily(SYSDESIGN_POOL, dayKey, "sysdesign"), parseSubmission(input) { - if (typeof input !== "object" || input === null || Array.isArray(input)) return null; - const keys = Object.keys(input); - if (keys.length !== 1 || keys[0] !== "changes") return null; - const changes = (input as { changes?: unknown }).changes; - if (!Array.isArray(changes) || changes.length > MAX_PARSED_CHANGES) return null; - const seen = new Set(); - for (const id of changes) { - if (typeof id !== "string" || id.length === 0 || id.length > 64 || seen.has(id)) return null; - seen.add(id); - } - return { changes: [...changes] as string[] }; + if (!isObject(input) || !onlyKeys(input, ["board"])) return null; + const board = parseBoard(input.board); + return board === null ? null : { board }; }, verify(round, submission) { try { - const ids = Array.isArray(submission?.changes) ? submission.changes.filter((id): id is string => typeof id === "string") : []; - if (new Set(ids).size !== ids.length) return fail("Each change can be used only once."); - if (ids.length > round.maxChanges) return fail(`You can apply at most ${round.maxChanges} changes in this round.`); - const offered = new Set(round.changes.map((c) => c.id)); - if (ids.some((id) => !offered.has(id))) return fail("One of those changes is not part of this round."); - - const sim = simulate(round, ids); - const checks = evaluateGoals(round.goals, sim); - const missed = checks.find((c) => !c.met); - if (missed) { - return { passed: false, stars: 0, score: sim.costUsd, message: `Goal missed: ${missed.label.toLowerCase()} is ${missed.actual}, the goal is ${missed.target}.` }; + const spec = round.spec; + const challenge = spec.challenge; + const solution = spec.solution; + if (!challenge || !solution) return fail("This round is not set up correctly."); + const parsed = sysdesignEngine.parseSubmission(submission); + if (parsed === null) return fail("That design could not be read. Build it on the board and press Run tests."); + const board = parsed.board; + const problem = boardProblem(spec, board); + if (problem) return fail(problem); + + const report = runChallenge(spec, board, challenge.peakLoad); + const first = report.checks.find((c) => !c.pass); + if (first) { + return fail(`Not yet: "${first.label}" fails. Found: ${first.measured}. Needed: ${first.target}.`); } - const stretch = round.stretch; - const tighter = (stretch.maxCostUsd === undefined || sim.costUsd <= stretch.maxCostUsd) && (stretch.maxP95Ms === undefined || sim.p95Ms <= stretch.maxP95Ms); - const lean = ids.length <= round.solution.length && !(round.trap !== undefined && ids.includes(round.trap)); - const stars: Stars = tighter ? (lean ? 3 : 2) : 1; - const target = [stretch.maxCostUsd !== undefined ? `$${stretch.maxCostUsd} a month` : "", stretch.maxP95Ms !== undefined ? `${stretch.maxP95Ms} ms p95` : ""].filter(Boolean).join(" and "); + const spend = runModel(spec, board, challenge.peakLoad).costPerHour; + const reference = runModel(spec, solution.board, challenge.peakLoad).costPerHour; + const refParts = partsOf(solution.board); + const lean = spend <= reference * 1.1 && partsOf(board) <= refParts + 1; + const near = spend <= reference * 1.4; + const stars: Stars = lean ? 3 : near ? 2 : 1; const message = stars === 3 - ? `All goals met with ${ids.length} change${ids.length === 1 ? "" : "s"}: p95 ${sim.p95Ms} ms, ${sim.availability}% available, $${sim.costUsd} a month.` + ? `All ${report.total} checks pass at ${usd(spend)} an hour with ${partsOf(board)} parts, within 10% of the reference cost.` : stars === 2 - ? "All goals met and under the tighter target. For 3 stars, use fewer changes and skip the tempting trap." - : `All goals met. For more stars, get under the tighter target of ${target}.`; - return { passed: true, stars, score: sim.costUsd, message }; + ? `All ${report.total} checks pass at ${usd(spend)} an hour. For 3 stars, get the cost to ${usd(reference * 1.1)} or less with at most ${refParts + 1} parts.` + : `All ${report.total} checks pass at ${usd(spend)} an hour. For 2 stars, get the cost to ${usd(reference * 1.4)} or less.`; + return { passed: true, stars, score: Math.round(spend * 100) / 100, message }; } catch { - return fail("That set of changes could not be checked. Try again."); + return fail("That design could not be checked. Try again."); } }, }; diff --git a/server/src/shared/games/sysdesign/incidents.ts b/server/src/shared/games/sysdesign/incidents.ts new file mode 100644 index 00000000..a49eb2cd --- /dev/null +++ b/server/src/shared/games/sysdesign/incidents.ts @@ -0,0 +1,562 @@ +// The six production incidents of the System Design Runner, two for each difficulty. Each one is +// a real lab spec (HldLabSpec, the same shape the platform's labs use) on AWS parts: a broken +// starting board, the checks it must pass, hints and a reference fix with a reason for every part. +// The numbers were set with the real model (runChallenge): every starting board fails and every +// reference solution passes. Prices are the catalog's illustrative us-east-1 on-demand prices. +import type { Board, ChallengeScenario, CheckDef, CheckMetric, HldLabSpec, SolutionDef } from "../../lab/engine/hld-types.js"; +import type { SysdesignRound } from "./types.js"; + +const LIMITS = + "A simplified model, not a real AWS bill. Prices are illustrative us-east-1 on-demand prices from late 2026. Times are in model milliseconds. In this game a cache or CDN hit rate counts only up to 90%."; + +// ---- small builders, so each incident reads as data ------------------------------------- + +type Op = "<=" | ">="; +const metric = (id: string, label: string, scenario: string, m: CheckMetric, op: Op, value: number): CheckDef => ({ + type: "metric", id, kind: "non-functional", label, scenario, metric: m, op, value, +}); +const capacity = (peak: number) => metric("capacity", "Serves the whole peak", "steady", "capacity", ">=", peak); +const p99 = (ms: number) => metric("p99", "Slowest 1 in 100 requests is fast enough (p99)", "steady", "p99", "<=", ms); +const availability = (v: number) => metric("availability", "Stays up (availability)", "steady", "availability", ">=", v); +const cost = (usd: number) => metric("cost", "Cost per hour is within the budget", "steady", "cost", "<=", usd); +const served = (id: string, label: string, scenario: string) => metric(id, label, scenario, "served", ">=", 0.999); +const slow = (id: string, label: string, scenario: string, ms: number) => metric(id, label, scenario, "p99", "<=", ms); +const reads: CheckDef = { + type: "path", id: "read", kind: "functional", label: "A request reaches the database", + chain: ["client", "balancer", "compute", "database"], target: "client > load balancer > app servers > database", +}; +const cached: CheckDef = { + type: "path", id: "cached", kind: "functional", label: "Repeated reads can come from a cache", + chain: ["client", "compute", "cache"], target: "the app servers are linked to a cache", +}; + +const LOSE_APP: ChallengeScenario = { + id: "lose-app", title: "A server dies", story: "One EC2 server stops. The load balancer sends its share to the others.", + faults: [{ type: "lose-instance", role: "compute" }], +}; +const LOSE_CACHE: ChallengeScenario = { + id: "lose-cache", title: "The cache is flushed", story: "The cache is empty. Every read goes to the database.", + faults: [{ type: "down", role: "cache" }], +}; +const ZONE_DOWN: ChallengeScenario = { + id: "zone-down", title: "A zone goes down", story: "An app server and the cache in that zone are gone at the same time.", + faults: [{ type: "lose-instance", role: "compute" }, { type: "down", role: "cache" }], +}; +const LOSE_WORKERS: ChallengeScenario = { + id: "lose-workers", title: "The workers stop for 2 minutes", story: "Orders keep arriving. They wait in the queue until the workers return.", + faults: [{ type: "down", role: "worker" }], +}; + +const board = (nodes: Board["nodes"], edges: Board["edges"]): Board => ({ nodes, edges }); + +// ---- 1. easy: the bill tripled ------------------------------------------------------------ + +const BILL_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "m5.xlarge", count: 12, autoscale: 0, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.2xlarge", replicas: 3, multiAz: 1, readRatio: 0.8 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const BILL_FIX: SolutionDef = { + summary: "Size each part for the real peak, plus one spare server. Keep Multi-AZ, because a standby copy is what keeps the site up.", + board: board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "m5.large", count: 3, autoscale: 0, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 1, multiAz: 1, readRatio: 0.8 } }, + ], + BILL_START.edges, + ), + parts: { + alb: { + why: "The ALB spreads requests over the servers. It is managed and billed per request, so its $1.32 an hour follows the traffic and is not the part to cut.", + checks: ["read", "capacity"], + without: "Nothing else in this design spreads the traffic over the servers, so there is no way to reach more than one of them.", + }, + web: { + why: "Three m5.large servers in two zones carry 1,800 requests a second at 38% busy each. If one dies, the other two are 56% busy. That is enough and costs $0.29 an hour, not $2.30.", + checks: ["capacity", "p99", "app-dies", "app-dies-p99", "availability", "cost"], + without: "With two servers, losing one leaves 113% load on the other, so only 89% of requests are served and the slowest 1 in 100 takes over 1,300 ms. With one server, nothing is left when it dies.", + }, + db: { + why: "A db.r5.large with one read replica is 60% busy at the real peak. Multi-AZ keeps a standby in a second zone, so the database is not the weak link. It costs $0.72 an hour, not $4.80.", + checks: ["capacity", "p99", "availability", "cost"], + without: "With no read replica the database is 120% busy, it serves only 1,500 requests a second and the slowest 1 in 100 takes 577 ms. Without Multi-AZ, availability drops to 99.84% and fails the 99.9% target.", + }, + }, +}; + +const billTripled: HldLabSpec = { + slug: "sd-bill-tripled", + family: "hld", + title: "The bill tripled", + purpose: "Right-size an AWS web tier that is far bigger than its traffic, and keep it safe while you cut the cost.", + limits: LIMITS, + hints: [ + "Run the tests first. Only one check fails: the cost. The reason names the part that costs the most.", + "The ALB is billed per request, so you cannot make it cheaper. EC2 and RDS are the parts you can change.", + "12 big servers for 1,800 requests a second is far too many. But keep at least 3: one can die and the rest must still carry the load.", + "Keep Multi-AZ on the database. Without it, availability falls below 99.9%. A smaller size and fewer read replicas are the real savings.", + ], + allowedComponents: ["client", "aws-alb", "aws-ec2-asg", "aws-rds", "aws-elasticache"], + startingBoard: BILL_START, + scenario: + "The AWS bill is $8.42 an hour, about three times what it should be. Real traffic peaks at only 1,800 requests a second, but the team rented a huge fleet during the launch and never gave it back. Cut the cost to $3.00 an hour or less. The site must stay fast (p99 under 100 ms), stay 99.9% up, and keep serving when one server dies.", + levels: [{ id: "l1", load: 1_800, targets: { rps: 1_800, p99Ms: 100, availability: 0.999, budgetPerHour: 3 } }], + solution: BILL_FIX, + challenge: { + peakLoad: 1_800, + scenarios: [LOSE_APP], + checks: [ + reads, + capacity(1_800), + p99(100), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + slow("app-dies-p99", "Slowest 1 in 100 while a server is down (p99)", "lose-app", 130), + availability(0.999), + cost(3), + ], + }, +}; + +// ---- 2. easy: launch day is slow --------------------------------------------------------- + +const LAUNCH_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "m5.large", count: 2, autoscale: 0, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 0, multiAz: 1, readRatio: 0.85 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const LAUNCH_FIX: SolutionDef = { + summary: "A cache answers the repeated reads from memory, so the database only sees the misses. Then add one more, faster server so the site survives losing one.", + board: board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.large", count: 3, autoscale: 0, azs: 2 } }, + { id: "cache", kind: "aws-elasticache", x: 1, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 1, hitRate: 0.85, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 0, multiAz: 1, readRatio: 0.85 } }, + ], + [...LAUNCH_START.edges, { from: "web", to: "cache" }], + ), + parts: { + alb: { + why: "The ALB spreads the 3,000 requests a second over the servers. It is managed, so it never becomes the limit, and it costs $2.18 an hour.", + checks: ["read", "capacity"], + without: "Without the ALB nothing spreads the traffic over the servers.", + }, + web: { + why: "Three c5.large servers (compute sized, 2,400 requests a second each) are 42% busy at the peak and 63% busy with one gone. Two m5.large servers were 94% busy.", + checks: ["capacity", "p99", "app-dies", "app-dies-p99"], + without: "With the first two m5.large servers the web tier is 94% busy and the slowest 1 in 100 takes 344 ms. When one dies the other is 188% busy and the slowest 1 in 100 takes over 1,300 ms.", + }, + cache: { + why: "At an 85% hit rate the cache answers 2,550 of the 3,000 reads a second from memory. Only about 450 reach the database, which falls from 213% busy to 32% busy. It costs $0.41 an hour.", + checks: ["capacity", "p99", "app-dies", "app-dies-p99", "cost"], + without: "With no cache the database is 213% busy, so it can serve only 1,412 requests a second and the slowest 1 in 100 takes 580 ms. CloudFront also removes the repeats, but at this load it costs $8.10 an hour and breaks the $5.00 budget.", + }, + db: { + why: "The database keeps the data. With the cache in front it is only 32% busy. Multi-AZ keeps a standby in a second zone, so it is not the weak link for availability.", + checks: ["read", "capacity", "p99", "availability"], + without: "Without Multi-AZ, availability falls to 99.84% and fails the 99.9% target.", + }, + }, +}; + +const launchDaySlow: HldLabSpec = { + slug: "sd-launch-slow", + family: "hld", + title: "Launch day is slow", + purpose: "Find why a new site is slow under launch traffic, and fix it without a huge bill.", + limits: LIMITS, + hints: [ + "Run the tests. Read the reasons: the database (RDS) is over 200% busy, and the two servers are almost full. Many requests ask for the same pages again and again.", + "A cache answers repeated reads from memory, so only the misses reach the database. ElastiCache is the AWS cache. Link the app servers to it.", + "CloudFront also stops repeated requests, but it is billed per request. Look at what it adds to the cost before you choose it.", + "When the database is safe, the two web servers are still too busy. Use a faster size or add a server, so the site survives when one dies.", + ], + allowedComponents: ["client", "aws-cloudfront", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds"], + startingBoard: LAUNCH_START, + scenario: + "Launch day: 3,000 requests a second hit a small site. Pages take almost a second and some time out. The database is over 200% busy and the two web servers are almost full. Make the site fast (p99 under 100 ms), keep it serving when one server dies, and keep the bill at $5.00 an hour or less.", + levels: [{ id: "l1", load: 3_000, targets: { rps: 3_000, p99Ms: 100, availability: 0.999, budgetPerHour: 5 } }], + solution: LAUNCH_FIX, + challenge: { + peakLoad: 3_000, + scenarios: [LOSE_APP], + checks: [ + reads, + capacity(3_000), + p99(100), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + slow("app-dies-p99", "Slowest 1 in 100 while a server is down (p99)", "lose-app", 150), + availability(0.999), + cost(5), + ], + }, +}; + +// ---- 3. medium: the flash sale melts the database ------------------------------------------ + +const SALE_WEB = { size: "c5.large", count: 4, autoscale: 0, azs: 2 }; +const SALE_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: SALE_WEB }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.xlarge", replicas: 0, multiAz: 1, readRatio: 0.9 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const SALE_FIX: SolutionDef = { + summary: "Put a cache in front of the database so most reads never reach it. Then add read replicas, so the database can still cope on the minute the cache is empty.", + board: board( + [ + { id: "client", kind: "client", x: 1, y: 0 }, + { id: "alb", kind: "aws-alb", x: 1, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 1, y: 2, props: SALE_WEB }, + { id: "cache", kind: "aws-elasticache", x: 0, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 1, hitRate: 0.85, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 2, y: 3, props: { size: "db.r5.xlarge", replicas: 2, multiAz: 1, readRatio: 0.9 } }, + ], + [...SALE_START.edges, { from: "web", to: "cache" }], + ), + parts: { + alb: { + why: "The ALB spreads the 6,000 requests a second over the servers. It is billed per request, so it is the biggest line in the bill at $4.34 an hour.", + checks: ["read", "capacity"], + without: "Without the ALB nothing spreads the traffic over the servers.", + }, + web: { + why: "Four c5.large servers handle 6,000 requests a second at 63% busy. If one dies, the other three can still carry it. They were never the problem.", + checks: ["capacity", "p99", "app-dies"], + without: "With three servers the slowest 1 in 100 takes 141 ms, over the 90 ms limit, and losing one leaves only 80% of requests served. The fleet was sized right.", + }, + cache: { + why: "At an 85% hit rate the cache answers 5,100 of 6,000 reads a second from memory. The database sees about 900 a second instead of 6,000, and falls from 225% busy to 11% busy.", + checks: ["cached", "capacity", "p99", "app-dies"], + without: "With no cache the cache path check fails, and even with two replicas the database is 75% busy and the slowest 1 in 100 takes 97 ms, over 90 ms. With no cache and no replica (the starting board) the database is 225% busy and serves only 2,667 requests a second.", + }, + db: { + why: "Two read replicas share the reads. When the cache is flushed, all 6,000 requests a second hit the database, and three copies keep it 75% busy. Multi-AZ keeps it up when a zone fails.", + checks: ["cache-dies", "cache-dies-p99", "capacity", "availability", "cost"], + without: "With a cache and no replica, a flushed cache sends 225% load to the database and only 44% of requests are served. With one replica it is 113% busy and 89% are served. A bigger db.r5.2xlarge with two replicas works but costs $8.93 an hour, almost the whole $9.00 budget.", + }, + }, +}; + +const flashSale: HldLabSpec = { + slug: "sd-flash-sale", + family: "hld", + title: "The flash sale melts the database", + purpose: "Protect a database from a read flood with a cache and read replicas, and prove it still holds when the cache is empty.", + limits: LIMITS, + hints: [ + "The database is 225% busy. Nine in ten requests only read. Reads are what a cache and read replicas are for.", + "Add ElastiCache and link the app servers to it. At an 85% hit rate, only 15% of the reads reach the database.", + "A cache can be flushed or restart empty. Run the tests and read the cache check: then every read hits the database again. Read replicas (copies that only read) share that load.", + "A bigger RDS size also helps, but every replica costs as much as the primary. Compare the price of two replicas on a smaller size with one big size before you decide.", + ], + allowedComponents: ["client", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds"], + startingBoard: SALE_START, + scenario: + "A flash sale has started and 6,000 requests a second arrive. Most of them read the same product pages, and every read goes to one database. It is 225% busy, pages take 600 ms and many fail. Take the load off it with a cache. Make sure the database can still cope if the cache is flushed. Stay at $9.00 an hour or less.", + levels: [{ id: "l1", load: 6_000, targets: { rps: 6_000, p99Ms: 90, availability: 0.999, budgetPerHour: 9 } }], + solution: SALE_FIX, + challenge: { + peakLoad: 6_000, + scenarios: [LOSE_APP, LOSE_CACHE], + checks: [ + reads, + cached, + capacity(6_000), + p99(90), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + served("cache-dies", "Everyone is still served when the cache is flushed", "lose-cache"), + slow("cache-dies-p99", "Slowest 1 in 100 while the cache is empty (p99)", "lose-cache", 150), + availability(0.999), + cost(9), + ], + }, +}; + +// ---- 4. medium: we lost a zone ----------------------------------------------------------------- + +const ZONE_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.large", count: 3, autoscale: 0, azs: 1 } }, + { id: "cache", kind: "aws-elasticache", x: 1, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 0, hitRate: 0.85, azs: 1 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 1, multiAz: 0, readRatio: 0.85 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }, { from: "web", to: "cache" }], +); + +const ZONE_FIX: SolutionDef = { + summary: "Give every layer a second zone: servers in two zones with a spare, a Multi-AZ database and a cache with a replica. Then one zone cannot take the site down.", + board: board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.large", count: 4, autoscale: 0, azs: 2 } }, + { id: "cache", kind: "aws-elasticache", x: 1, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 1, hitRate: 0.85, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 1, multiAz: 1, readRatio: 0.85 } }, + ], + ZONE_START.edges, + ), + parts: { + alb: { + why: "The ALB already runs in two zones, so it is not the weak link. It costs $3.62 an hour at 5,000 requests a second.", + checks: ["read", "capacity", "availability"], + without: "Without the ALB nothing spreads the traffic over the servers in the two zones.", + }, + web: { + why: "Four servers in two zones: if a whole zone is lost, two are left in the other. If a single server dies, three still carry the 5,000 requests a second, at 69% busy each.", + checks: ["capacity", "p99", "app-dies", "app-dies-p99", "availability"], + without: "With three servers, one dying leaves 104% load, so only 96% of requests are served and the slowest 1 in 100 takes over 1,300 ms. With all servers in one zone, availability is 99.94%, just under the 99.95% target.", + }, + cache: { + why: "The cache sits in two zones with a replica, so one zone cannot take it away. A single cache node in one zone is only 99.9% available, and it sits in series with everything else.", + checks: ["availability"], + without: "A single cache node in one zone brings availability down to 99.84%, which fails the 99.95% target.", + }, + db: { + why: "Multi-AZ keeps a synchronous standby in a second zone. If the main copy's zone fails, RDS fails over to the standby. This lifts the database from 99.85% to about 99.999% available. It costs $0.72 an hour.", + checks: ["availability", "cost"], + without: "Without Multi-AZ the database is the weak link. Availability for the whole site is 99.84%, under the 99.95% target.", + }, + }, +}; + +const lostZone: HldLabSpec = { + slug: "sd-lost-zone", + family: "hld", + title: "We lost a zone", + purpose: "Spread a system over two Availability Zones so one data centre cannot take it down, without paying for much more.", + limits: LIMITS, + hints: [ + "Run the tests. Read the availability reason: it names the weakest part. Fix it, run again, and the next weak part shows up.", + "RDS Multi-AZ keeps a standby copy in a second zone. If the zone of the main copy fails, the standby takes over.", + "EC2 Auto Scaling can spread servers over zones: set zones to 2. ElastiCache can too, and a replica keeps the cache alive.", + "Three servers cannot lose one and still carry 5,000 requests a second. Count what is left after one dies, then add what is needed.", + ], + allowedComponents: ["client", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds"], + startingBoard: ZONE_START, + scenario: + "Last night one AWS Availability Zone (a separate data centre) lost power. The servers, the cache and the main database were all in that zone, so the site was down for 40 minutes. Traffic peaks at 5,000 requests a second. The goal is 99.95% uptime, which allows about 22 minutes of downtime a month. The site must also keep serving when one server dies. Stay at $6.00 an hour or less.", + levels: [{ id: "l1", load: 5_000, targets: { rps: 5_000, p99Ms: 90, availability: 0.9995, budgetPerHour: 6 } }], + solution: ZONE_FIX, + challenge: { + peakLoad: 5_000, + scenarios: [LOSE_APP], + checks: [ + reads, + capacity(5_000), + p99(90), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + slow("app-dies-p99", "Slowest 1 in 100 while a server is down (p99)", "lose-app", 130), + availability(0.9995), + cost(6), + ], + }, +}; + +// ---- 5. hard: peak day, one zone down, tight budget ---------------------------------------------- + +const PEAK_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.2xlarge", count: 6, autoscale: 0, azs: 1 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.xlarge", replicas: 0, multiAz: 0, readRatio: 0.85 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const PEAK_FIX: SolutionDef = { + summary: "Fix the database side, not the fleet: add a cache, give the database Multi-AZ and read replicas, and cut the web fleet to what the traffic needs, in two zones. That frees the money for the database.", + board: board( + [ + { id: "client", kind: "client", x: 1, y: 0 }, + { id: "alb", kind: "aws-alb", x: 1, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 1, y: 2, props: { size: "c5.xlarge", count: 3, autoscale: 0, azs: 2 } }, + { id: "cache", kind: "aws-elasticache", x: 0, y: 3, props: { size: "cache.r6g.large", count: 1, replicasPerShard: 1, hitRate: 0.85, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 2, y: 3, props: { size: "db.r5.xlarge", replicas: 3, multiAz: 1, readRatio: 0.85 } }, + ], + [...PEAK_START.edges, { from: "web", to: "cache" }], + ), + parts: { + alb: { + why: "The ALB spreads the 8,000 requests a second over the servers in both zones. It is billed per request, so it is $5.78 an hour of the budget, and nothing you can shrink.", + checks: ["read", "capacity", "availability"], + without: "Without the ALB nothing spreads the traffic over the servers.", + }, + web: { + why: "Three c5.xlarge servers in two zones carry 8,000 requests a second at 56% busy and cost $0.51 an hour. When a zone goes down and one server with it, two are left at 83% busy. The old fleet of six c5.2xlarge cost $2.04 an hour and was only 14% busy.", + checks: ["capacity", "p99", "zone-served", "zone-p99", "availability", "cost"], + without: "The old fleet of six c5.2xlarge servers in one zone adds $1.53 an hour, which pushes the bill to $10.63 with the other fixes and breaks the $10.00 budget. In one zone it also fails availability.", + }, + cache: { + why: "At an 85% hit rate the cache answers 6,800 of 8,000 reads a second, so the database sees only 1,200 a second. It costs $0.41 an hour. It also has a replica in a second zone.", + checks: ["cached", "capacity", "p99", "availability"], + without: "With no cache the cache path check fails. With no cache and no replicas (the starting board) the database is 283% busy: it serves only 2,824 requests a second and the slowest 1 in 100 takes 569 ms.", + }, + db: { + why: "The database must carry all the reads for the minute the cache is gone. Three read replicas keep db.r5.xlarge at 71% busy with no cache and one server less. Multi-AZ keeps a standby in the second zone. It costs $2.40 an hour.", + checks: ["zone-served", "zone-p99", "availability", "cost"], + without: "With two replicas instead of three, the database is 94% busy when a zone goes down and the slowest 1 in 100 reaches 276 ms, over the 200 ms limit. Without Multi-AZ, availability falls to 99.84%.", + }, + }, +}; + +const peakDay: HldLabSpec = { + slug: "sd-peak-day", + family: "hld", + title: "Peak day, one zone down, tight budget", + purpose: "Make several changes that work together: cache, replicas, Multi-AZ and a right-sized fleet, under a budget that rules out buying big everywhere.", + limits: LIMITS, + hints: [ + "The fleet is far too big for the traffic. The database is the weak part: it is 283% busy. Fix the database side first.", + "Add a cache so most reads never reach the database. Then give the database read replicas and Multi-AZ.", + "The zone check removes the cache and one server at the same moment. The database must then carry all the reads. Count replicas for that case, not only for the normal one.", + "Right-size the fleet and spread it over two zones. The budget leaves room for the database copies only if you cut the fleet first.", + "CloudFront is billed per request. At 8,000 requests a second it costs more than your whole budget.", + ], + allowedComponents: ["client", "aws-cloudfront", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds"], + startingBoard: PEAK_START, + scenario: + "It is the busiest day of the year: 8,000 requests a second. Last year a zone failed at the peak and the site went down. The app fleet is huge, but the database is one RDS with no copy and no cache, and it is 283% busy. The site must survive a zone loss (an app server and the cache gone together), stay 99.95% up, and cost $10.00 an hour or less. Bigger machines everywhere will not fit the budget.", + levels: [{ id: "l1", load: 8_000, targets: { rps: 8_000, p99Ms: 90, availability: 0.9995, budgetPerHour: 10 } }], + solution: PEAK_FIX, + challenge: { + peakLoad: 8_000, + scenarios: [ZONE_DOWN], + checks: [ + reads, + cached, + capacity(8_000), + p99(90), + served("zone-served", "Everyone is still served when a zone goes down", "zone-down"), + slow("zone-p99", "Slowest 1 in 100 while a zone is down (p99)", "zone-down", 200), + availability(0.9995), + cost(10), + ], + }, +}; + +// ---- 6. hard: orders are piling up ------------------------------------------------------------------ + +const ORDERS_START: Board = board( + [ + { id: "client", kind: "client", x: 0, y: 0 }, + { id: "alb", kind: "aws-alb", x: 0, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 0, y: 2, props: { size: "c5.large", count: 2, autoscale: 0, azs: 2 } }, + { id: "db", kind: "aws-rds", x: 0, y: 3, props: { size: "db.r5.large", replicas: 0, multiAz: 1, readRatio: 0.7 } }, + ], + [{ from: "client", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }], +); + +const ORDERS_FIX: SolutionDef = { + summary: "Save orders off the request. The web servers put each order on an SQS queue, two workers take them and save them to the database in groups, and the database is sized for the real load.", + board: board( + [ + { id: "client", kind: "client", x: 1, y: 0 }, + { id: "alb", kind: "aws-alb", x: 1, y: 1 }, + { id: "web", kind: "aws-ec2-asg", x: 1, y: 2, props: { size: "c5.large", count: 3, autoscale: 0, azs: 2 } }, + { id: "q", kind: "aws-sqs", x: 0, y: 3, props: { queueType: "standard" } }, + { id: "db", kind: "aws-rds", x: 2, y: 3, props: { size: "db.r5.xlarge", replicas: 1, multiAz: 1, readRatio: 0.7 } }, + { id: "w", kind: "worker", x: 0, y: 4, props: { size: "compute-small", count: 2, batchSize: 100 } }, + ], + [...ORDERS_START.edges, { from: "web", to: "q" }, { from: "q", to: "w" }, { from: "w", to: "db", via: ["r", "l"] }], + ), + parts: { + alb: { + why: "The ALB spreads the 4,000 requests a second over the servers. It is billed per request: $2.90 an hour.", + checks: ["read", "capacity"], + without: "Without the ALB nothing spreads the traffic over the servers.", + }, + web: { + why: "Three c5.large servers are 56% busy at the peak. If one dies, the other two carry it. The two original servers were 83% busy, and one dying left only 60% of requests served.", + checks: ["capacity", "p99", "app-dies"], + without: "With two servers, losing one leaves 167% load on the other, so only 60% of requests are served.", + }, + q: { + why: "The queue holds each order until a worker saves it. About 1 request in 4 is an order, so about 1,000 orders a second arrive. The web server hands the order over and is free. No order is lost while the workers are away. It costs $1.44 an hour.", + checks: ["order", "worker-dies", "cost"], + without: "With no queue an order has nowhere to wait: 120,000 orders are lost in a 2 minute outage and the order path check fails.", + }, + w: { + why: "Two small workers handle 4,800 orders a second against 1,000 arriving. They have 3,800 a second to spare, so the 120,000 orders that waited in 2 minutes clear in 32 seconds. They save in groups of 100, so the database sees about 10 saves a second, not 1,000.", + checks: ["order", "worker-dies", "p99"], + without: "With one worker the spare is only 1,400 a second and the pile takes 86 seconds to clear, over the 60 second limit. With a batch size of 1 the database is 73% busy and p99 rises to 87 ms, over the 80 ms limit.", + }, + db: { + why: "The database is 58% busy with one read replica and Multi-AZ. The old db.r5.large was 233% busy. The replica shares the reads and Multi-AZ keeps the database from being the weak link.", + checks: ["capacity", "p99", "app-dies", "availability", "cost"], + without: "With the first db.r5.large and no replica the database is 234% busy and serves only 1,710 requests a second. A db.r5.2xlarge with three replicas works but costs $9.64 an hour, over the $7.00 budget.", + }, + }, +}; + +const ordersPile: HldLabSpec = { + slug: "sd-orders-pile", + family: "hld", + title: "Orders are piling up", + purpose: "Move order saving off the web request with a queue and workers, prove nothing is lost when the workers stop, and stay within the budget.", + limits: LIMITS + " About 1 request in 4 is an order and leaves one message in the queue.", + hints: [ + "Run the tests. Orders have no queue, so they have nowhere to wait. The failing reasons say which link is missing.", + "Link the web servers to an SQS queue, the queue to a worker, and the worker to the database. Orders then wait safely in the queue.", + "A worker can save many orders in one trip: raise its batch size. Many tiny saves hurt the database.", + "When the workers stop, orders pile up. After they return, they must clear the pile fast. The spare capacity of the workers is what the drain check measures.", + "Workers and queue cost money. The budget is $7.00 an hour, so a few small workers are better than many big ones. The database also needs to be bigger.", + ], + allowedComponents: ["client", "aws-alb", "aws-ec2-asg", "aws-elasticache", "aws-rds", "aws-sqs", "worker"], + startingBoard: ORDERS_START, + scenario: + "Sale day: 4,000 requests a second, and about 1 in 4 is an order. The web servers save every order themselves, the database is 233% busy, and orders fail. If the order service stops for 2 minutes, those orders are lost for good. Put orders on a queue, add workers that save them, and make sure a 2 minute stop is fully cleared within 60 seconds. Stay at $7.00 an hour or less.", + levels: [{ id: "l1", load: 4_000, targets: { rps: 4_000, p99Ms: 80, availability: 0.999, budgetPerHour: 7 } }], + solution: ORDERS_FIX, + challenge: { + peakLoad: 4_000, + shares: { queue: 0.25 }, + scenarios: [LOSE_APP, LOSE_WORKERS], + checks: [ + reads, + { + type: "path", id: "order", kind: "functional", label: "An order is saved without making the buyer wait", + chain: ["client", "compute", "queue", "worker", "database"], target: "the path app servers > queue > worker > database", + }, + capacity(4_000), + p99(80), + served("app-dies", "Everyone is still served when one server dies", "lose-app"), + { + type: "drain", id: "worker-dies", kind: "non-functional", label: "No order is lost when the workers stop", + outageSeconds: 120, maxDrainSeconds: 60, items: "orders", done: "saved", + }, + availability(0.999), + cost(7), + ], + }, +}; + +// ---- the pool --------------------------------------------------------------------------------------- + +export const SYSDESIGN_POOL: SysdesignRound[] = [ + { id: "sd-bill-tripled", difficulty: "easy", title: "The bill tripled", brief: "The AWS bill is three times too high for the real traffic. Make the system cheaper, and keep it safe.", spec: billTripled }, + { id: "sd-launch-slow", difficulty: "easy", title: "Launch day is slow", brief: "Launch traffic made the site slow, and the database is overloaded. Speed it up without a huge bill.", spec: launchDaySlow }, + { id: "sd-flash-sale", difficulty: "medium", title: "The flash sale melts the database", brief: "A flash sale sends every read to one database. Take the load off it, even when the cache is empty.", spec: flashSale }, + { id: "sd-lost-zone", difficulty: "medium", title: "We lost a zone", brief: "One AWS zone failed and the whole site went down. Make sure one zone can never stop it again.", spec: lostZone }, + { id: "sd-peak-day", difficulty: "hard", title: "Peak day, one zone down, tight budget", brief: "Peak day with a zone down and a tight budget. Several parts must change together.", spec: peakDay }, + { id: "sd-orders-pile", difficulty: "hard", title: "Orders are piling up", brief: "Orders are saved inside the web request and get lost or pile up. Use a queue and workers, within the budget.", spec: ordersPile }, +]; diff --git a/server/src/shared/games/sysdesign/scenarios.ts b/server/src/shared/games/sysdesign/scenarios.ts deleted file mode 100644 index 1abe658b..00000000 --- a/server/src/shared/games/sysdesign/scenarios.ts +++ /dev/null @@ -1,393 +0,0 @@ -// The pool of production incidents. Every round is plain data: a system, 24 hours of traffic, the -// goals, and a catalog of changes (each one a patch on the model). All prices are round, illustrative -// numbers made up for the game. They are not AWS quotes. -import type { Difficulty } from "../types.js"; -import { STEPS, type ChangeDef, type DeepPartial, type Model, type SysdesignRound } from "./types.js"; - -/** A model with sensible defaults. A scenario overrides only what it needs. */ -function model(over: DeepPartial = {}): Model { - const base: Model = { - app: { label: "m5.large", count: 4, rpsEach: 100, monthlyEach: 70, baseMs: 20, zones: 1, healthChecks: false, autoscale: false, scaleMin: 2, scaleMax: 8, pricing: "ondemand" }, - db: { kind: "rds", label: "db.m5.large", capacity: 400, monthly: 140, replicas: 0, replicaMonthly: 140, multiAz: false, pricing: "ondemand", readMs: 12, writeMs: 20, readCost: 1, skew: 1 }, - cache: { on: false, hit: 0.85, monthly: 90 }, - cdn: { on: false, offload: 0.9, monthly: 40 }, - queue: { on: false, monthly: 10 }, - batch: { separate: false, workersMonthly: 60 }, - net: { egressGb: 500, natGb: 500, s3Share: 0.7, s3Endpoint: false, natGateways: 1 }, - logs: { gb: 200, hotRate: 0.023, coldRate: 0.004, coldShare: 0 }, - }; - return { - app: { ...base.app, ...over.app }, - db: { ...base.db, ...over.db }, - cache: { ...base.cache, ...over.cache }, - cdn: { ...base.cdn, ...over.cdn }, - queue: { ...base.queue, ...over.queue }, - batch: { ...base.batch, ...over.batch }, - net: { ...base.net, ...over.net }, - logs: { ...base.logs, ...over.logs }, - }; -} - -/** Traffic for 24 hours, by straight lines between [hour, requests per second] points. */ -function shape(points: Array<[number, number]>): number[] { - const out: number[] = []; - for (let t = 0; t < STEPS; t++) { - let value = points[points.length - 1]![1]; - for (let i = 0; i < points.length - 1; i++) { - const [t0, v0] = points[i]!; - const [t1, v1] = points[i + 1]!; - if (t >= t0 && t <= t1) { - value = t1 === t0 ? v1 : v0 + ((v1 - v0) * (t - t0)) / (t1 - t0); - break; - } - } - out.push(Math.round(value)); - } - return out; -} - -/** A normal day: quiet at night, busy in the afternoon. */ -const day = (low: number, high: number) => shape([[0, low], [6, low], [11, high], [17, high], [23, low]]); - -type Scenario = SysdesignRound; - -const POOL: Scenario[] = [ - // ───────────────────────────── EASY ───────────────────────────── - { - id: "sd-bill-tripled", - difficulty: "easy", - title: "The bill tripled", - brief: "Finance says the AWS bill is three times higher than last quarter. Traffic did not grow. Cut the bill and keep the site fast.", - incident: "COST ALERT: monthly spend is 3x the budget. Servers and database run at under 10% busy.", - model: model({ - app: { label: "m5.2xlarge", count: 6, rpsEach: 400, monthlyEach: 280 }, - db: { label: "db.r5.2xlarge", capacity: 2400, monthly: 700 }, - net: { egressGb: 1500, natGb: 400 }, - }), - traffic: day(25, 90), - mix: { staticShare: 0.3, readShare: 0.8 }, - goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 700 }, - stretch: { maxCostUsd: 520 }, - changes: [ - { id: "rightsize-app", label: "Right-size servers to 3x m5.large", description: "The fleet is much bigger than the traffic needs. Three m5.large servers still handle the peak with room to spare.", patch: { app: { label: "m5.large", count: 3, rpsEach: 100, monthlyEach: 70 } } }, - { id: "rightsize-db", label: "Right-size the database to db.m5.large", description: "A db.r5.2xlarge is built for memory-heavy work. This database is almost idle, so a db.m5.large is enough.", patch: { db: { label: "db.m5.large", capacity: 600, monthly: 140 } } }, - { id: "savings-plan", label: "Buy a 1-year Compute Savings Plan", description: "Commit to steady EC2 use for one year and pay about 30% less per server than on-demand.", patch: { app: { pricing: "savings" } } }, - { id: "reserved-rds", label: "Buy a 1-year RDS Reserved Instance", description: "Commit to one database size for one year and pay about 38% less than on-demand.", patch: { db: { pricing: "reserved" } } }, - { id: "bigger-4xl", label: "Move up to m5.4xlarge for headroom", description: "Bigger servers feel safe, but they cost twice as much per server.", patch: { app: { label: "m5.4xlarge", rpsEach: 800, monthlyEach: 560 } } }, - { id: "add-replica", label: "Add a read replica for safety", description: "A second copy of the database for reads. It costs as much as the database itself.", patch: { db: { replicas: 1, replicaMonthly: 700 } } }, - ], - maxChanges: 3, - solution: ["rightsize-app", "rightsize-db", "savings-plan"], - trap: "bigger-4xl", - trapNote: "Bigger servers do not help when the old ones were already idle. They only raise the bill.", - hints: [ - "Look at the busy bars: the servers and the database are almost idle.", - "Paying for capacity you do not use is the problem. Make the machines smaller.", - "Right-size both the servers and the database, then commit to a steady price with a savings plan or a reserved instance.", - ], - focus: "app", - }, - { - id: "sd-static-flood", - difficulty: "easy", - title: "Images are crushing the web servers", - brief: "The shop is slow all afternoon. Most requests are for images, CSS and JavaScript files that never change.", - incident: "LATENCY ALERT: p95 is over 1 second. App servers are above 90% busy serving static files.", - model: model({ app: { count: 4 }, net: { egressGb: 3000 } }), - traffic: shape([[0, 150], [6, 150], [10, 900], [17, 900], [23, 150]]), - mix: { staticShare: 0.8, readShare: 0.8 }, - goals: { maxP95Ms: 140, minAvailability: 99.5, maxCostUsd: 720 }, - stretch: { maxCostUsd: 680 }, - changes: [ - { id: "add-cdn", label: "Put CloudFront in front", description: "A CDN keeps copies of static files near the user, so most of them never reach your servers. It also cuts data transfer cost.", patch: { cdn: { on: true } } }, - { id: "more-servers", label: "Add 4 more app servers", description: "More servers share the load. It works, but you pay for them every hour.", patch: { app: { count: 8 } } }, - { id: "bigger-db", label: "Move to a bigger database", description: "A bigger database is stronger, but the database is not the busy part here.", patch: { db: { label: "db.r5.xlarge", capacity: 1200, monthly: 350 } } }, - { id: "add-cache", label: "Add an ElastiCache node", description: "A cache answers repeated database reads fast. Static files do not come from the database.", patch: { cache: { on: true } } }, - ], - maxChanges: 2, - solution: ["add-cdn"], - trap: "bigger-db", - trapNote: "The database was never the busy part, so a bigger one only costs more.", - hints: ["Check which bar is red. It is the app servers.", "Most traffic is static files. They can be served from somewhere else.", "Use a CDN (CloudFront) for static files."], - focus: "app", - }, - { - id: "sd-logs-forever", - difficulty: "easy", - title: "Logs that never end", - brief: "Application logs are kept in S3 Standard forever. The storage line grows every month. Nobody reads logs older than a month.", - incident: "COST ALERT: S3 storage is now the biggest line on the bill and grows 5 TB each month.", - model: model({ logs: { gb: 60000, coldShare: 0 }, net: { egressGb: 300 } }), - traffic: day(20, 60), - mix: { staticShare: 0.3, readShare: 0.8 }, - goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 900 }, - stretch: { maxCostUsd: 650 }, - changes: [ - { id: "glacier-lifecycle", label: "Lifecycle rule: move to Glacier after 30 days", description: "S3 moves old logs to Glacier on its own. Glacier costs about a fifth of S3 Standard per GB.", patch: { logs: { coldShare: 0.9 } } }, - { id: "compress-logs", label: "Compress logs with gzip before upload", description: "Text logs shrink to about a third of their size, so you store and pay for less.", patch: { logs: { gb: 20000 } } }, - { id: "ebs-volumes", label: "Keep the logs on bigger EBS volumes", description: "Block storage is for running servers. It costs more per GB than S3.", patch: { logs: { hotRate: 0.08 } } }, - { id: "intelligent-tiering", label: "Turn on S3 Intelligent-Tiering", description: "S3 watches access and moves some data to a cheaper tier. Fine for unknown patterns, but it also adds a monitoring fee per object.", patch: { logs: { coldShare: 0.5, coldRate: 0.0125 } } }, - ], - maxChanges: 3, - solution: ["glacier-lifecycle", "compress-logs"], - trap: "ebs-volumes", - trapNote: "EBS costs more per GB than S3, so it makes the log bill bigger.", - hints: ["The big line is log storage, not servers.", "Old logs are almost never read. They do not need the most expensive storage class.", "Move old logs to Glacier with a lifecycle rule, and store fewer bytes by compressing."], - focus: "storage", - }, - { - id: "sd-nat-bill", - difficulty: "easy", - title: "The NAT gateway line explodes", - brief: "Servers in private subnets download big files from S3 through a NAT gateway. NAT charges for every GB that passes through.", - incident: "COST ALERT: NAT Gateway data processing is the top line on the bill, 30 TB this month.", - model: model({ net: { natGb: 30000, s3Share: 0.8, egressGb: 7000 } }), - traffic: day(30, 80), - mix: { staticShare: 0.4, readShare: 0.8 }, - goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 1500 }, - stretch: { maxCostUsd: 1100 }, - changes: [ - { id: "s3-endpoint", label: "Add an S3 gateway VPC endpoint", description: "Traffic to S3 goes over the AWS network directly, not through NAT. A gateway endpoint for S3 has no hourly or per-GB charge.", patch: { net: { s3Endpoint: true } } }, - { id: "add-cdn", label: "Put CloudFront in front of downloads", description: "A CDN serves popular files from the edge. Data transfer out gets cheaper and your servers are asked less often.", patch: { cdn: { on: true } } }, - { id: "second-nat", label: "Add a second NAT gateway per AZ", description: "It is good for availability, but it adds another monthly fee and does not reduce the data that passes through NAT.", patch: { net: { natGateways: 2 } } }, - { id: "bigger-app", label: "Use bigger servers", description: "The servers are fine. The traffic path is the problem.", patch: { app: { label: "m5.xlarge", rpsEach: 200, monthlyEach: 140 } } }, - ], - maxChanges: 2, - solution: ["s3-endpoint", "add-cdn"], - trap: "second-nat", - trapNote: "A second NAT gateway adds a fixed fee and does not reduce the GB that cross NAT.", - hints: ["Look at the cost lines: the NAT gateway is the biggest.", "Most of that traffic is only S3 traffic. It does not need to go through NAT at all.", "Add an S3 gateway endpoint. A CDN also cuts the data transfer line."], - focus: "nat", - }, - // ───────────────────────────── MEDIUM ───────────────────────────── - { - id: "sd-flash-sale-db", - difficulty: "medium", - title: "Flash sale crushes the database", - brief: "A flash sale at noon sends 6 times the normal traffic. The web servers cope, but the single database is melting.", - incident: "PAGE: database CPU at 100% and checkout errors rising. Flash sale in progress.", - model: model({ app: { count: 10 }, db: { label: "db.r5.large", capacity: 330, monthly: 300, replicaMonthly: 300 }, net: { egressGb: 400 } }), - traffic: shape([[0, 100], [9, 100], [11, 120], [12, 700], [15, 700], [16, 120], [23, 100]]), - mix: { staticShare: 0.1, readShare: 0.7 }, - goals: { maxP95Ms: 250, minAvailability: 99.5, maxCostUsd: 1700, maxPeakDbUtil: 0.9 }, - stretch: { maxCostUsd: 1500 }, - changes: [ - { id: "add-cache", label: "Add ElastiCache (Redis) for hot products", description: "Hot product pages are read again and again. A cache answers them from memory so the database sees fewer reads.", patch: { cache: { on: true, hit: 0.6 } } }, - { id: "add-replica", label: "Add a read replica", description: "A second database copy that answers reads. The primary only handles writes and half of the reads.", patch: { db: { replicas: 1 } } }, - { id: "add-queue", label: "Put orders in an SQS queue", description: "Writes wait in a queue and the database drains them at its own pace. The user gets a fast answer, the database never gets a spike.", patch: { queue: { on: true } } }, - { id: "more-servers", label: "Double the app servers", description: "More web servers, but they were not the busy part. The database is.", patch: { app: { count: 16 } } }, - { id: "bigger-db", label: "Upgrade to db.r5.4xlarge", description: "A much bigger database. It fixes the spike but costs a lot every month, also on quiet days.", patch: { db: { label: "db.r5.4xlarge", capacity: 1320, monthly: 1200 } } }, - ], - maxChanges: 3, - solution: ["add-cache", "add-replica"], - trap: "more-servers", - trapNote: "The web servers were not the problem. More of them only raises cost and sends even more work to the database.", - hints: ["Look at the bars during the sale: the database is at 100%, the servers are fine.", "Reads dominate. Take reads away from the primary database.", "Use a cache and a read replica together. A queue can smooth the writes."], - focus: "db", - }, - { - id: "sd-p95-four-seconds", - difficulty: "medium", - title: "p95 latency is 4 seconds", - brief: "Every page request hits the database, and static files come from the same servers. Pages feel slow all afternoon.", - incident: "LATENCY ALERT: p95 is 4 s. Database and app servers are both near 100% busy.", - model: model({ app: { count: 3 }, db: { capacity: 200 }, net: { egressGb: 1500 } }), - traffic: shape([[0, 80], [7, 80], [10, 420], [18, 420], [23, 80]]), - mix: { staticShare: 0.5, readShare: 0.9 }, - goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 650 }, - stretch: { maxCostUsd: 620, maxP95Ms: 130 }, - changes: [ - { id: "add-cache", label: "Add ElastiCache for repeated reads", description: "Most pages ask the database the same questions. A cache returns the answer in about 2 ms.", patch: { cache: { on: true, hit: 0.85 } } }, - { id: "add-cdn", label: "Put CloudFront in front for static files", description: "Images and scripts come from the edge, so the web servers only do dynamic work.", patch: { cdn: { on: true } } }, - { id: "add-replica", label: "Add a read replica", description: "A replica doubles read capacity, but every read is still a database read, and you pay for a second database.", patch: { db: { replicas: 1 } } }, - { id: "more-servers", label: "Add 3 more app servers", description: "More servers handle more requests, but they all still wait for the same database.", patch: { app: { count: 6 } } }, - { id: "bigger-db", label: "Use a bigger database", description: "More database power. Pricey, and static files still hit the servers.", patch: { db: { label: "db.r5.xlarge", capacity: 800, monthly: 350 } } }, - ], - maxChanges: 3, - solution: ["add-cache", "add-cdn"], - trap: "more-servers", - trapNote: "More servers do nothing for slow reads. They all wait for the same database, and they cost money.", - hints: ["Two parts are busy: the database and the app servers.", "Do not answer the same question from the database again and again, and do not make servers send files.", "Add a cache for reads and a CDN for static files."], - focus: "db", - }, - { - id: "sd-az-outage", - difficulty: "medium", - title: "One AZ goes dark", - brief: "At 1 pm one Availability Zone fails. Everything runs in that one zone. Make the site survive a zone failure.", - incident: "OUTAGE: us-east-1a is unreachable. All servers and the database are in 1a. The site is down.", - model: model({ app: { count: 4 }, net: { egressGb: 400 } }), - traffic: day(30, 140), - mix: { staticShare: 0.2, readShare: 0.8 }, - outage: { from: 13, to: 17 }, - goals: { maxP95Ms: 250, minAvailability: 99, maxCostUsd: 750 }, - stretch: { maxCostUsd: 680 }, - changes: [ - { id: "two-azs", label: "Spread servers across 2 AZs", description: "Half of the servers run in a second Availability Zone, behind a load balancer.", patch: { app: { zones: 2 } } }, - { id: "health-checks", label: "Add load balancer health checks", description: "The load balancer stops sending users to servers that do not answer.", patch: { app: { healthChecks: true } } }, - { id: "rds-multi-az", label: "Turn on RDS Multi-AZ", description: "A standby database in the other zone takes over by itself if the primary fails.", patch: { db: { multiAz: true } } }, - { id: "autoscaling", label: "Add an Auto Scaling group", description: "Servers are added when load grows and removed when it falls, so you pay for less at night.", patch: { app: { autoscale: true, scaleMin: 2, scaleMax: 8 } } }, - { id: "bigger-servers", label: "Use bigger servers", description: "Bigger servers in the same zone still go down with the zone.", patch: { app: { label: "m5.xlarge", rpsEach: 200, monthlyEach: 140, count: 4 } } }, - ], - maxChanges: 4, - solution: ["two-azs", "health-checks", "rds-multi-az"], - trap: "bigger-servers", - trapNote: "A bigger server is still one server in one zone. It does not survive a zone failure and it costs twice as much.", - hints: ["Everything lives in one zone, so one failure takes down everything.", "You need copies of the servers and of the database in a second zone.", "Spread servers over two AZs, let the load balancer find dead servers, and give the database a standby."], - focus: "lb", - }, - { - id: "sd-batch-starves-web", - difficulty: "medium", - title: "The report job starves the shop", - brief: "A heavy report job runs at midday on the same servers and database as the shop. While it runs, customers wait.", - incident: "LATENCY ALERT: p95 jumps to 3 s from 11:00 to 15:00, the same time the reports run.", - model: model({ app: { count: 4, monthlyEach: 120, label: "m5.xlarge", rpsEach: 100 }, db: { capacity: 400, monthly: 200 }, net: { egressGb: 600 } }), - traffic: shape([[0, 40], [6, 40], [10, 130], [17, 130], [23, 40]]), - mix: { staticShare: 0.2, readShare: 0.8 }, - batchJob: { from: 11, to: 15, appLoad: 240, dbLoad: 240 }, - goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 800 }, - stretch: { maxCostUsd: 720 }, - changes: [ - { id: "spot-workers", label: "Run the job on Spot workers", description: "Move the report job to its own Spot instances, which cost about 70% less and can be interrupted. The shop stops competing with it.", patch: { batch: { separate: true } } }, - { id: "savings-plan", label: "Buy a 1-year Compute Savings Plan", description: "Pay about 30% less for the steady web servers.", patch: { app: { pricing: "savings" } } }, - { id: "autoscaling", label: "Add an Auto Scaling group", description: "Adds servers when the load grows. It helps the web tier but does nothing for the shared database.", patch: { app: { autoscale: true, scaleMin: 2, scaleMax: 8 } } }, - { id: "more-servers", label: "Add 4 more app servers", description: "Bigger fleet all day, to survive 4 hours. Costly, and the database still gets the job load.", patch: { app: { count: 8 } } }, - { id: "reserved-rds", label: "Buy a 1-year RDS Reserved Instance", description: "Pay about 38% less for the database.", patch: { db: { pricing: "reserved" } } }, - ], - maxChanges: 3, - solution: ["spot-workers", "savings-plan"], - trap: "more-servers", - trapNote: "Extra servers for four busy hours cost money all month, and the database still has to carry the job.", - hints: ["Look at the times: the slow period matches the job.", "The shop and the job share the same machines. Separate them.", "Move the job to Spot workers. A savings plan keeps the bill in budget."], - focus: "workers", - }, - // ───────────────────────────── HARD ───────────────────────────── - { - id: "sd-missing-index", - difficulty: "hard", - title: "A query scans a million rows", - brief: "The product search runs a full table scan on every request. At lunch the database cannot keep up.", - incident: "PAGE: slow query log shows 180 ms scans on orders. Database CPU 100% at lunch.", - model: model({ - app: { count: 5 }, - db: { label: "db.m5.xlarge", capacity: 600, monthly: 250, readCost: 6, readMs: 180 }, - net: { egressGb: 500 }, - }), - traffic: shape([[0, 40], [8, 60], [11, 250], [15, 250], [18, 80], [23, 40]]), - mix: { staticShare: 0.2, readShare: 0.85 }, - goals: { maxP95Ms: 100, minAvailability: 99.5, maxCostUsd: 850, maxPeakDbUtil: 0.7 }, - stretch: { maxCostUsd: 800 }, - changes: [ - { id: "add-index", label: "Add an index on the search column", description: "An index lets the database find rows directly instead of reading the whole table. Reads get both faster and cheaper.", patch: { db: { readCost: 1, readMs: 12 } } }, - { id: "add-cache", label: "Add ElastiCache for repeated searches", description: "Popular searches repeat. A cache answers them in memory.", patch: { cache: { on: true, hit: 0.7 } } }, - { id: "bigger-db", label: "Upgrade to db.m5.4xlarge", description: "Four times the database power. A scan is still a scan, and the bill goes way up.", patch: { db: { label: "db.m5.4xlarge", capacity: 2400, monthly: 1000 } } }, - { id: "add-replica", label: "Add two read replicas", description: "More copies to scan the table. Each costs as much as the database.", patch: { db: { replicas: 2, replicaMonthly: 250 } } }, - { id: "more-servers", label: "Add more app servers", description: "The servers are not the slow part.", patch: { app: { count: 10 } } }, - ], - maxChanges: 3, - solution: ["add-index", "add-cache"], - trap: "bigger-db", - trapNote: "A bigger database still scans the whole table, so each query stays slow, and the cost goes over the limit.", - hints: ["Read the incident: a query takes 180 ms because it reads every row.", "Fix the query first, because power does not fix a bad query.", "Add the index. Then take the repeated reads off the database with a cache."], - focus: "db", - }, - { - id: "sd-hot-partition", - difficulty: "hard", - title: "One hot key, throttled writes", - brief: "A DynamoDB table uses the date as its partition key. Today's partition gets almost all the writes and is throttled, while the table has plenty of capacity overall.", - incident: "ALARM: ThrottledRequests on orders-table. Total capacity use is 20% but one partition is at 100%.", - model: model({ - app: { count: 10 }, - db: { kind: "dynamodb", label: "DynamoDB orders", capacity: 1100, monthly: 450, skew: 6, readMs: 6, writeMs: 10, readCost: 1 }, - net: { egressGb: 400 }, - }), - traffic: shape([[0, 150], [8, 200], [12, 800], [16, 800], [19, 250], [23, 150]]), - mix: { staticShare: 0.1, readShare: 0.45 }, - goals: { maxP95Ms: 220, minAvailability: 99.5, maxCostUsd: 1500, maxPeakDbUtil: 0.85 }, - stretch: { maxCostUsd: 1450 }, - changes: [ - { id: "shard-key", label: "Add a random suffix to the partition key", description: "Writes for the same date spread over many partitions, so no single partition is hot. This is called write sharding.", patch: { db: { skew: 1.5 } } }, - { id: "add-dax", label: "Add DAX, a DynamoDB cache", description: "A cache in front of DynamoDB answers repeated reads. Fewer reads means more room for writes.", patch: { cache: { on: true, hit: 0.7, monthly: 150 } } }, - { id: "add-queue", label: "Buffer writes with SQS", description: "Writes wait in a queue and are written at a steady pace instead of in a burst.", patch: { queue: { on: true } } }, - { id: "double-capacity", label: "Double the provisioned capacity", description: "More capacity for the table. It is spread over partitions, so the hot one gets only a bit more.", patch: { db: { capacity: 2200, monthly: 900 } } }, - { id: "more-servers", label: "Add more app servers", description: "The throttling is in the table, not in the servers.", patch: { app: { count: 12 } } }, - ], - maxChanges: 3, - solution: ["shard-key", "add-dax"], - trap: "double-capacity", - trapNote: "Capacity is shared across partitions. The hot partition is still hot, and you pay double.", - hints: ["Total capacity is fine, but one partition gets almost all the work.", "The cause is the key, not the capacity. Spread the key.", "Shard the partition key. A cache for reads gives the writes more room."], - focus: "db", - }, - { - id: "sd-black-friday-az", - difficulty: "hard", - title: "Peak day plus a lost zone", - brief: "It is the biggest sales day. Traffic triples, and in the middle of it one Availability Zone fails. The fixed fleet is too small and sits in one zone.", - incident: "OUTAGE: us-east-1a lost during peak sales. Fleet at 100% before the failure.", - model: model({ - app: { count: 6, label: "m5.xlarge", rpsEach: 100, monthlyEach: 100 }, - db: { label: "db.r5.large", capacity: 900, monthly: 300 }, - net: { egressGb: 800 }, - }), - traffic: shape([[0, 60], [7, 100], [10, 500], [17, 500], [20, 120], [23, 60]]), - mix: { staticShare: 0.15, readShare: 0.8 }, - outage: { from: 13, to: 16 }, - goals: { maxP95Ms: 350, minAvailability: 99, maxCostUsd: 1800 }, - stretch: { maxCostUsd: 1600 }, - changes: [ - { id: "asg-two-azs", label: "Auto Scaling group across 2 AZs", description: "Servers are spread over two zones and the group adds more when load rises, and removes them when it falls.", patch: { app: { zones: 2, autoscale: true, scaleMin: 4, scaleMax: 16 } } }, - { id: "health-checks", label: "Load balancer health checks", description: "Dead servers are removed from rotation within seconds.", patch: { app: { healthChecks: true } } }, - { id: "rds-multi-az", label: "RDS Multi-AZ", description: "A standby database in the second zone takes over after a failure.", patch: { db: { multiAz: true } } }, - { id: "add-cache", label: "Add ElastiCache", description: "Fewer reads reach the database. It helps speed, not zone failure.", patch: { cache: { on: true, hit: 0.8 } } }, - { id: "oversize-fleet", label: "Double the fixed fleet to 12 servers", description: "Always-on capacity for the peak. It does not fix the zone problem and it is on the bill for the whole month.", patch: { app: { count: 12 } } }, - ], - maxChanges: 4, - solution: ["asg-two-azs", "health-checks", "rds-multi-az"], - trap: "oversize-fleet", - trapNote: "A fixed, doubled fleet costs the same at night as at peak, and still lives in one zone.", - hints: ["Two problems at once: too little capacity at peak, and one zone.", "You need servers in two zones that can grow, plus a way to remove dead ones.", "Auto Scaling over two AZs, health checks, and a Multi-AZ database."], - focus: "app", - }, - { - id: "sd-halve-the-bill", - difficulty: "hard", - title: "Halve the bill, keep it fast", - brief: "The CFO wants the monthly bill cut in half without hurting speed or uptime. Money leaks in four places.", - incident: "COST ALERT: bill is $3,400 a month. Target is under $2,000. Latency and uptime must not suffer.", - model: model({ - app: { label: "m5.xlarge", count: 6, rpsEach: 200, monthlyEach: 140 }, - db: { label: "db.r5.xlarge", capacity: 1200, monthly: 350 }, - net: { egressGb: 6000, natGb: 15000, s3Share: 0.8 }, - logs: { gb: 40000 }, - }), - traffic: day(60, 160), - mix: { staticShare: 0.5, readShare: 0.8 }, - goals: { maxP95Ms: 200, minAvailability: 99.5, maxCostUsd: 2000 }, - stretch: { maxCostUsd: 1750 }, - changes: [ - { id: "add-cdn", label: "Add CloudFront", description: "Cheaper data transfer out, and static files stop reaching the servers.", patch: { cdn: { on: true } } }, - { id: "s3-endpoint", label: "S3 gateway VPC endpoint", description: "Stops S3 traffic from going through the NAT gateway.", patch: { net: { s3Endpoint: true } } }, - { id: "glacier-lifecycle", label: "Lifecycle old logs to Glacier", description: "Old logs move to a much cheaper storage class.", patch: { logs: { coldShare: 0.9 } } }, - { id: "savings-plan", label: "1-year Compute Savings Plan", description: "About 30% off the servers.", patch: { app: { pricing: "savings" } } }, - { id: "tiny-server", label: "Run everything on 1 t3.micro", description: "The cheapest possible server. It cuts the bill and cannot carry the traffic.", patch: { app: { label: "t3.micro", count: 1, rpsEach: 15, monthlyEach: 9 } } }, - { id: "second-nat", label: "A NAT gateway in every AZ", description: "Better resilience, more fixed cost.", patch: { net: { natGateways: 2 } } }, - ], - maxChanges: 4, - solution: ["add-cdn", "s3-endpoint", "glacier-lifecycle", "savings-plan"], - trap: "tiny-server", - trapNote: "A tiny server makes the bill small, but it cannot serve the traffic. Uptime and speed fall.", - hints: ["Open the cost lines. Four of them are big: transfer, NAT, logs, servers.", "Each leak has a cheap plug. Do not shrink the servers below the traffic.", "CDN, S3 endpoint, Glacier lifecycle, savings plan."], - focus: "nat", - }, -]; - -export const SYSDESIGN_POOL: readonly SysdesignRound[] = POOL; - -export function scenariosByDifficulty(difficulty: Difficulty): SysdesignRound[] { - return POOL.filter((r) => r.difficulty === difficulty); -} - -export type { ChangeDef }; diff --git a/server/src/shared/games/sysdesign/sim.ts b/server/src/shared/games/sysdesign/sim.ts deleted file mode 100644 index 207dc341..00000000 --- a/server/src/shared/games/sysdesign/sim.ts +++ /dev/null @@ -1,276 +0,0 @@ -// A small, pure, deterministic traffic simulation. It uses only + - * / and min, max, ceil, round, -// so the browser and the server always agree to the last digit. No clock, no randomness. -import { - STEPS, - type CostLine, - type DeepPartial, - type GoalCheck, - type Goals, - type Model, - type SimResult, - type StepResult, - type SysdesignRound, -} from "./types.js"; - -const APP_PRICING = { ondemand: 1, savings: 0.68, reserved: 0.6 } as const; -const DB_PRICING = { ondemand: 1, reserved: 0.62 } as const; -/** Illustrative unit prices, in dollars. They are round numbers, not real quotes. */ -export const PRICES = { egressPerGb: 0.09, cdnPerGb: 0.04, natPerGb: 0.045, natPerMonth: 33 } as const; - -function isObject(value: unknown): value is Record { - return typeof value === "object" && value !== null && !Array.isArray(value); -} - -/** Merge a patch onto a copy of a model. Only objects are merged, everything else is replaced. */ -export function mergePatch(base: T, patch: DeepPartial): T { - if (!isObject(base) || !isObject(patch)) return base; - const out: Record = { ...base }; - for (const key of Object.keys(patch)) { - const next = (patch as Record)[key]; - const prev = out[key]; - out[key] = isObject(prev) && isObject(next) ? mergePatch(prev, next as never) : next; - } - return out as T; -} - -/** The model after the changes, applied in order. Ids that are not offered are ignored. */ -export function applyChanges(round: SysdesignRound, ids: readonly string[]): Model { - let model = round.model; - for (const id of ids) { - const change = round.changes.find((c) => c.id === id); - if (change) model = mergePatch(model, change.patch); - } - return model; -} - -const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, n)); -/** Queueing delay: grows fast as a part gets busy. Capped so a saturated part reads as a timeout. */ -const slow = (baseMs: number, util: number) => Math.min(4000, baseMs / (1 - clamp(util, 0, 0.97))); - -type Point = { ms: number; weight: number }; - -/** A class of requests has a spread: most are near the typical time, a few are much slower. */ -function spread(ms: number, weight: number, out: Point[]) { - if (weight <= 0) return; - out.push({ ms: ms * 0.8, weight: weight * 0.6 }, { ms: ms * 1.3, weight: weight * 0.3 }, { ms: ms * 2.6, weight: weight * 0.1 }); -} - -function weightedPercentile(points: Point[], q: number): number { - const sorted = [...points].sort((a, b) => a.ms - b.ms); - const total = sorted.reduce((sum, p) => sum + p.weight, 0); - if (total <= 0) return 0; - let seen = 0; - for (const p of sorted) { - seen += p.weight; - if (seen >= total * q) return Math.min(4000, Math.round(p.ms)); - } - return Math.min(4000, Math.round(sorted[sorted.length - 1]!.ms)); -} - -export function costLines(model: Model, appInstancesAvg: number): CostLine[] { - const appF = APP_PRICING[model.app.pricing] ?? 1; - const dbF = DB_PRICING[model.db.pricing] ?? 1; - const lines: CostLine[] = []; - const add = (id: string, label: string, usd: number) => { - const rounded = Math.round(usd); - if (rounded > 0) lines.push({ id, label, usd: rounded }); - }; - add("app", `${model.app.label} servers`, appInstancesAvg * model.app.monthlyEach * appF); - add("db", `${model.db.label} database`, (model.db.monthly + (model.db.multiAz ? model.db.monthly : 0)) * dbF); - add("replica", "Read replicas", model.db.replicas * model.db.replicaMonthly * dbF); - if (model.cache.on) add("cache", "ElastiCache", model.cache.monthly); - if (model.cdn.on) add("cdn", "CloudFront", model.cdn.monthly); - if (model.queue.on) add("queue", "SQS queue", model.queue.monthly); - if (model.batch.separate) add("workers", "Spot workers", model.batch.workersMonthly); - const off = model.cdn.on ? model.cdn.offload : 0; - add("egress", "Data transfer out", model.net.egressGb * ((1 - off) * PRICES.egressPerGb + off * PRICES.cdnPerGb)); - const natGb = model.net.natGb * (1 - (model.net.s3Endpoint ? model.net.s3Share : 0)); - add("nat", "NAT gateway", model.net.natGateways * PRICES.natPerMonth + natGb * PRICES.natPerGb); - add("logs", "Log storage", model.logs.gb * ((1 - model.logs.coldShare) * model.logs.hotRate + model.logs.coldShare * model.logs.coldRate)); - return lines; -} - -/** Run the day. The same inputs always give the same result. */ -export function simulate(round: SysdesignRound, changeIds: readonly string[]): SimResult { - const m = applyChanges(round, changeIds); - const { mix, outage, batchJob } = round; - const traffic = Array.from({ length: STEPS }, (_, i) => Math.max(0, round.traffic[i] ?? 0)); - - const batchApp = (t: number) => (batchJob && t >= batchJob.from && t <= batchJob.to && !m.batch.separate ? batchJob.appLoad : 0); - const appWorkFor = (t: number) => { - const load = traffic[t]!; - const st = load * mix.staticShare; - const off = m.cdn.on ? m.cdn.offload : 0; - return st * (1 - off) * 0.25 + (load - st) + batchApp(t); - }; - - const hit = m.cache.on ? m.cache.hit : 0; - const dbCap = Math.max(1, m.db.capacity / Math.max(1, m.db.skew)); - const replicas = Math.max(0, Math.round(m.db.replicas)); - - const steps: StepResult[] = []; - const all: Point[] = []; - const instances: number[] = []; - let backlog = 0; - let totalReq = 0; - let totalOk = 0; - let peakApp = 0; - let peakDb = 0; - let peakBacklog = 0; - - for (let t = 0; t < STEPS; t++) { - const load = traffic[t]!; - const zoneDown = !!outage && t >= outage.from && t <= outage.to; - const outageStart = !!outage && t === outage.from; - const prevWork = appWorkFor(Math.max(0, t - 1)); - - const target = m.app.autoscale ? clamp(Math.ceil(prevWork / (m.app.rpsEach * (m.app.zones === 2 ? 0.4 : 0.6))), m.app.scaleMin, m.app.scaleMax) : m.app.count; - instances.push(target); - - // How many servers are alive, and how much traffic still goes to the dead zone. - let alive = target; - let deadRoute = 0; - if (zoneDown) { - if (m.app.zones === 1) { - alive = 0; - deadRoute = 1; - } else { - alive = m.app.autoscale && !outageStart ? clamp(target, Math.ceil(m.app.scaleMin / 2), m.app.scaleMax) : Math.ceil(target / 2); - deadRoute = m.app.healthChecks ? (outageStart ? 0.04 : 0) : 0.5; - } - } - const reach = 1 - deadRoute; - - const st = load * mix.staticShare; - const dyn = load - st; - const reads = dyn * mix.readShare; - const writes = dyn - reads; - const off = m.cdn.on ? m.cdn.offload : 0; - const stCdn = st * off; - const stOrigin = st - stCdn; - const hitReads = reads * hit; - const missReads = reads - hitReads; - - const running = !!batchJob && t >= batchJob.from && t <= batchJob.to && !m.batch.separate; - const appWork = (stOrigin * 0.25 + dyn + batchApp(t)) * reach; - const cap = alive * m.app.rpsEach; - const fa = appWork <= 0 ? 1 : alive === 0 ? 0 : Math.min(1, cap / appWork); - const appUtil = alive === 0 ? 0 : cap > 0 ? appWork / cap : 0; - - // The database. A single-zone database is lost with the zone. A standby takes over quickly. - const dbDown = zoneDown && !m.db.multiAz; - const failover = zoneDown && m.db.multiAz && outageStart ? 0.97 : 1; - const missIn = missReads * reach * fa; - const writeIn = writes * reach * fa + (m.queue.on ? backlog : 0); - const readsPrimary = missIn / (1 + replicas); - const readsReplica = replicas > 0 ? missIn / (1 + replicas) : 0; - const batchDb = running ? batchJob!.dbLoad : 0; - const fixedLoad = readsPrimary * m.db.readCost + batchDb; - let writesDone = writeIn; - if (m.queue.on) { - writesDone = dbDown ? 0 : Math.min(writeIn, Math.max(0, dbCap - fixedLoad)); - backlog = Math.max(0, writeIn - writesDone); - } else { - backlog = 0; - } - const primaryDemand = writesDone + fixedLoad; - const pu = dbDown ? 0 : primaryDemand / dbCap; - const ru = (readsReplica * m.db.readCost) / dbCap; - const okPrimary = dbDown ? 0 : pu <= 1 ? 1 : 1 / pu; - const okReplica = ru <= 1 ? 1 : 1 / ru; - const okWrite = m.queue.on ? 1 : okPrimary; - const okRead = (okPrimary + replicas * okReplica) / (1 + replicas); - - // Success per class of request. - const successStOrigin = reach * fa; - const successHit = reach * fa; - const successMiss = reach * fa * okRead * failover; - const successWrite = reach * fa * okWrite * failover; - - const appMs = alive === 0 ? 4000 : slow(m.app.baseMs, appUtil); - const readUtil = (pu + replicas * ru) / (1 + replicas); - const dbReadMs = slow(m.db.readMs, readUtil); - const dbWriteMs = slow(m.db.writeMs, pu); - const points: Point[] = []; - spread(12, stCdn, points); - spread(appMs * 0.6, stOrigin * successStOrigin, points); - spread(appMs + 2, hitReads * successHit, points); - spread(appMs + dbReadMs, missReads * successMiss, points); - spread(appMs + (m.queue.on ? 6 : dbWriteMs), writes * successWrite, points); - all.push(...points); - - const ok = stCdn + stOrigin * successStOrigin + hitReads * successHit + missReads * successMiss + writes * successWrite; - const success = load > 0 ? Math.min(1, ok / load) : 1; - totalReq += load; - totalOk += ok; - const p95Ms = weightedPercentile(points, 0.95); - peakApp = Math.max(peakApp, appUtil); - peakDb = Math.max(peakDb, pu, ru); - peakBacklog = Math.max(peakBacklog, backlog); - - steps.push({ - t, - load, - appInstances: alive, - appUtil, - dbUtil: pu, - replicaUtil: ru, - success, - appDrop: clamp(1 - reach * fa, 0, 1), - dbDrop: clamp(1 - okRead * failover, 0, 1), - p95Ms, - status: success < 0.9 ? "down" : success < 0.995 || p95Ms > round.goals.maxP95Ms ? "slow" : "ok", - zoneDown, - batchRunning: running, - backlog, - costToDate: 0, - }); - } - - const avgInstances = instances.reduce((a, b) => a + b, 0) / STEPS; - const lines = costLines(m, avgInstances); - const costUsd = lines.reduce((sum, l) => sum + l.usd, 0); - const appLine = lines.find((l) => l.id === "app")?.usd ?? 0; - const fixedPerStep = (costUsd - appLine) / STEPS; - let acc = 0; - steps.forEach((s, i) => { - acc += (avgInstances > 0 ? (instances[i]! / (avgInstances * STEPS)) * appLine : 0) + fixedPerStep; - s.costToDate = Math.round(acc); - }); - if (steps.length > 0) steps[steps.length - 1]!.costToDate = costUsd; - - return { - model: m, - steps, - p95Ms: weightedPercentile(all, 0.95), - availability: totalReq > 0 ? Math.round((totalOk / totalReq) * 10000) / 100 : 100, - costUsd, - costLines: lines, - peakAppUtil: peakApp, - peakDbUtil: peakDb, - peakBacklog, - }; -} - -const pct = (n: number) => `${Math.round(n * 100)}%`; - -/** Every goal with a yes or no. Used by verify and by the result panel. */ -export function evaluateGoals(goals: Goals, sim: SimResult): GoalCheck[] { - const checks: GoalCheck[] = [ - { id: "p95", label: "Latency (p95)", met: sim.p95Ms <= goals.maxP95Ms, actual: `${sim.p95Ms} ms`, target: `at most ${goals.maxP95Ms} ms` }, - { id: "availability", label: "Availability", met: sim.availability >= goals.minAvailability, actual: `${sim.availability}%`, target: `at least ${goals.minAvailability}%` }, - { id: "cost", label: "Monthly cost", met: sim.costUsd <= goals.maxCostUsd, actual: `$${sim.costUsd}`, target: `at most $${goals.maxCostUsd}` }, - ]; - if (goals.maxPeakAppUtil !== undefined) { - checks.push({ id: "appUtil", label: "App servers peak load", met: sim.peakAppUtil <= goals.maxPeakAppUtil, actual: pct(sim.peakAppUtil), target: `at most ${pct(goals.maxPeakAppUtil)}` }); - } - if (goals.maxPeakDbUtil !== undefined) { - checks.push({ id: "dbUtil", label: "Database peak load", met: sim.peakDbUtil <= goals.maxPeakDbUtil, actual: pct(sim.peakDbUtil), target: `at most ${pct(goals.maxPeakDbUtil)}` }); - } - return checks; -} - -/** What one change alone does to the monthly bill, in dollars (negative saves money). */ -export function costDelta(round: SysdesignRound, id: string): number { - return simulate(round, [id]).costUsd - simulate(round, []).costUsd; -} diff --git a/server/src/shared/games/sysdesign/types.ts b/server/src/shared/games/sysdesign/types.ts index eb63a765..579f1552 100644 --- a/server/src/shared/games/sysdesign/types.ts +++ b/server/src/shared/games/sysdesign/types.ts @@ -1,166 +1,14 @@ -// Shared types for the System Design Runner. Everything here is plain data (no functions), because -// a round travels from the server to the browser as JSON. +// Shared types for the System Design Runner. A round is a real lab spec (the same HldLabSpec the +// platform's labs use) with a broken starting board, so the game plays on the lab's own board. +// Everything here is plain data, because a round travels from the server to the browser as JSON. +import type { Board, HldLabSpec } from "../../lab/engine/hld-types.js"; import type { RoundBase } from "../types.js"; -/** Number of traffic steps in one simulated day. One step is one hour. */ -export const STEPS = 24; - -export type Pricing = "ondemand" | "savings" | "reserved"; - -/** The system as the player sees it. A change patches some of these numbers. */ -export type Model = { - app: { - /** For example "m5.2xlarge". */ - label: string; - count: number; - /** Requests per second one server can handle. */ - rpsEach: number; - /** Illustrative on-demand dollars per server per month. */ - monthlyEach: number; - /** Time to answer when the server is idle, in ms. */ - baseMs: number; - /** 1 means one Availability Zone, 2 means two. */ - zones: 1 | 2; - healthChecks: boolean; - autoscale: boolean; - /** Autoscaling keeps at least this many servers and at most scaleMax. */ - scaleMin: number; - scaleMax: number; - pricing: Pricing; - }; - db: { - kind: "rds" | "dynamodb"; - label: string; - /** Work units per second the primary can do. */ - capacity: number; - monthly: number; - replicas: number; - replicaMonthly: number; - /** A standby in a second zone. Costs about the same as the primary again. */ - multiAz: boolean; - pricing: "ondemand" | "reserved"; - /** Time for a read and for a write when idle, in ms. */ - readMs: number; - writeMs: number; - /** Work units one read uses (a missing index makes this big). */ - readCost: number; - /** 1 is an even spread. 4 means one hot key gets 4 times its fair share of work. */ - skew: number; - }; - cache: { on: boolean; /** Share of reads answered by the cache, 0 to 1. */ hit: number; monthly: number }; - cdn: { on: boolean; /** Share of static files served at the edge, 0 to 1. */ offload: number; monthly: number }; - queue: { on: boolean; monthly: number }; - /** Where the nightly batch job runs. Separate means spot workers away from the web tier. */ - batch: { separate: boolean; workersMonthly: number }; - net: { - /** GB per month leaving to the internet from the origin. */ - egressGb: number; - /** GB per month through the NAT gateway. */ - natGb: number; - /** Share of NAT traffic that is really S3 or DynamoDB traffic, 0 to 1. */ - s3Share: number; - /** A gateway VPC endpoint for S3 is in place. */ - s3Endpoint: boolean; - natGateways: number; - }; - logs: { gb: number; hotRate: number; coldRate: number; /** Share kept in cold storage, 0 to 1. */ coldShare: number }; -}; - -export type DeepPartial = { [K in keyof T]?: T[K] extends object ? DeepPartial : T[K] }; - -/** A change the player can apply. It is data: a patch merged onto the model. */ -export type ChangeDef = { - id: string; - label: string; - /** Plain English: what it does and why it helps (or what it costs). */ - description: string; - patch: DeepPartial; -}; - -export type Goals = { - /** The p95 request latency over the whole day must be at or below this, in ms. */ - maxP95Ms: number; - /** Share of requests that must succeed, in percent. */ - minAvailability: number; - /** Monthly bill must be at or below this, in dollars. */ - maxCostUsd: number; - /** Optional extras. */ - maxPeakAppUtil?: number; - maxPeakDbUtil?: number; -}; - -export type Stretch = { maxCostUsd?: number; maxP95Ms?: number }; - -export type ComponentId = "users" | "cdn" | "lb" | "app" | "cache" | "queue" | "db" | "replica" | "workers" | "storage" | "nat"; - +/** One production incident: a broken AWS system, the checks it must pass and a reference fix. */ export type SysdesignRound = RoundBase & { - /** Alarm text shown in the incident banner. */ - incident: string; - /** The system before the player changes anything. */ - model: Model; - /** Requests per second at each of the 24 steps. */ - traffic: number[]; - /** Share of requests that are static files, and share of dynamic requests that are reads. */ - mix: { staticShare: number; readShare: number }; - /** An Availability Zone fails during these steps (inclusive), if set. */ - outage?: { from: number; to: number }; - /** A batch job adds this load on the web tier and the database during these steps. */ - batchJob?: { from: number; to: number; appLoad: number; dbLoad: number }; - goals: Goals; - stretch: Stretch; - changes: ChangeDef[]; - maxChanges: number; - /** A change set that earns three stars. */ - solution: string[]; - /** A tempting change that does not help, or makes things worse. */ - trap?: string; - trapNote?: string; - /** Clues, from vague to clear. */ - hints: string[]; - /** The component to highlight as the problem. */ - focus: ComponentId; -}; - -export type SysdesignSubmission = { changes: string[] }; - -export type StepStatus = "ok" | "slow" | "down"; - -export type StepResult = { - t: number; - load: number; - appInstances: number; - /** Utilisation of each part, 0 upwards. Above 1 means it is overloaded. */ - appUtil: number; - dbUtil: number; - replicaUtil: number; - /** Share of requests that succeeded this step, 0 to 1. */ - success: number; - p95Ms: number; - status: StepStatus; - /** Share of requests lost before the app tier (dead zone or full servers), and share lost at the database, 0 to 1. */ - appDrop: number; - dbDrop: number; - zoneDown: boolean; - batchRunning: boolean; - /** Writes waiting in the queue after this step. */ - backlog: number; - /** Bill so far, in dollars per month (grows to the monthly total by the last step). */ - costToDate: number; -}; - -export type CostLine = { id: string; label: string; usd: number }; - -export type SimResult = { - model: Model; - steps: StepResult[]; - p95Ms: number; - /** Percent, 0 to 100. */ - availability: number; - costUsd: number; - costLines: CostLine[]; - peakAppUtil: number; - peakDbUtil: number; - peakBacklog: number; + /** The lab spec: starting board, allowed parts, challenge checks, hints and reference solution. */ + spec: HldLabSpec; }; -export type GoalCheck = { id: string; label: string; met: boolean; actual: string; target: string }; +/** What the player sends: the board they built. Positions do not matter. */ +export type SysdesignSubmission = { board: Board }; diff --git a/server/src/shared/lab/engine/catalog.ts b/server/src/shared/lab/engine/catalog.ts new file mode 100644 index 00000000..739ac2f9 --- /dev/null +++ b/server/src/shared/lab/engine/catalog.ts @@ -0,0 +1,436 @@ +// The shared component catalog for the lab platform. +// +// Every block a lab can use is described once here: its family (which course it +// belongs to), its role (what it does in a request path), its configurable +// properties (with range, default, unit and the panel group they show in), and +// the size catalogs its size pickers draw from. The board, the scoring model and +// the authoring validator all read this file. Links are allowed by role, so a new +// family (Kubernetes, Docker, Linux) is mostly new entries here, not new code. +// +// Prices and capacities are illustrative and dated (one region, on-demand, late +// 2026). Use them to compare the shapes of designs, not to quote a real bill. + +export type Family = "hld" | "aws" | "k8s" | "docker" | "linux"; +export const FAMILIES: readonly Family[] = ["hld", "aws", "k8s", "docker", "linux"]; + +export type Role = + | "client" + | "dns" + | "cdn" + | "firewall" + | "limiter" + | "balancer" + | "gateway" + | "compute" + | "function" + | "worker" + | "cache" + | "database" + | "nosql" + | "search" + | "queue" + | "stream" + | "storage"; + +export type ComponentKind = + // Generic building blocks for the high-level design course + | "client" + | "dns" + | "cdn" + | "waf" + | "rate-limiter" + | "load-balancer" + | "api-gateway" + | "app-server" + | "worker" + | "cache" + | "database" + | "nosql" + | "search" + | "queue" + | "stream" + | "object-storage" + // AWS services for the AWS course + | "aws-route53" + | "aws-cloudfront" + | "aws-waf" + | "aws-alb" + | "aws-nlb" + | "aws-api-gateway" + | "aws-ec2-asg" + | "aws-fargate" + | "aws-lambda" + | "aws-elasticache" + | "aws-rds" + | "aws-dynamodb" + | "aws-opensearch" + | "aws-sqs" + | "aws-kinesis" + | "aws-s3" + // Kubernetes objects for the Kubernetes course + | "k8s-ingress" + | "k8s-service" + | "k8s-deployment" + | "k8s-statefulset" + // Containers for the Docker course + | "docker-proxy" + | "docker-container" + | "docker-postgres" + // One host's services for the Linux course + | "linux-nginx" + | "linux-service" + | "linux-postgres"; + +export type PortDir = "in" | "out"; + +export interface PortDef { + id: string; + dir: PortDir; + accepts: ComponentKind[]; +} + +export type SizeSet = "generic" | "ec2" | "fargate" | "rds" | "elasticache" | "opensearch" | "pod" | "container" | "host"; +export type PropertyGroup = "Capacity" | "Scaling" | "Resilience" | "Behaviour"; + +export interface PropertyDef { + id: string; + label: string; + type: "size" | "count" | "ratio" | "enum" | "toggle"; + min?: number; + max?: number; + step?: number; + default: number | string; + unit: string; + options?: string[]; + /** Which size catalog a size picker draws from. */ + sizeSet?: SizeSet; + group?: PropertyGroup; + /** One line shown as a tooltip in the config panel. */ + help?: string; +} + +/** A managed, elastic service: priced per hour plus per million requests. */ +export interface ManagedPricing { + capacity: number; + pricePerHour: number; + pricePerMillion: number; +} + +export interface ComponentDef { + kind: ComponentKind; + label: string; + family: Family; + role: Role; + /** The product or engine name shown under the label. */ + vendor: string; + icon: string; + ports: PortDef[]; + properties: PropertyDef[]; + managed?: ManagedPricing; +} + +export interface SizeTier { + id: string; + set: SizeSet; + family: "general" | "compute" | "memory"; + vcpu: number; + memoryGb: number; + capacityRule: string; + pricePerHour: number; +} + +// Which role may send requests to which. Links follow the request, not the data. +const ROLE_NEXT: Record = { + client: ["dns", "cdn", "firewall", "limiter", "balancer", "gateway"], + dns: [], + cdn: ["firewall", "limiter", "balancer", "gateway", "compute", "storage"], + firewall: ["cdn", "limiter", "balancer", "gateway", "compute"], + limiter: ["balancer", "gateway", "compute", "function"], + balancer: ["balancer", "compute", "function"], + gateway: ["balancer", "compute", "function", "queue", "stream", "nosql", "storage"], + compute: ["function", "cache", "database", "nosql", "search", "queue", "stream", "storage"], + function: ["cache", "database", "nosql", "search", "queue", "stream", "storage"], + worker: ["cache", "database", "nosql", "search", "queue", "storage"], + queue: ["worker", "function"], + stream: ["worker", "function"], + // A cache may load from a database on a miss (read-through). Linking it is optional: + // an app server linked to both a cache and a database is cache-aside, with the same maths. + cache: ["database", "nosql"], + database: [], + nosql: [], + search: [], + storage: [], +}; + +// ---- property builders --------------------------------------------------- + +const size = (sizeSet: SizeSet, defaultId: string): PropertyDef => ({ + id: "size", + label: "Machine size", + type: "size", + sizeSet, + default: defaultId, + unit: "tier", + group: "Capacity", +}); +const count = (id: string, label: string, unit: string, def: number, min: number, max: number, group: PropertyGroup = "Capacity", help?: string): PropertyDef => ({ + id, label, type: "count", min, max, step: 1, default: def, unit, group, help, +}); +const ratio = (id: string, label: string, def: number, group: PropertyGroup = "Behaviour", help?: string): PropertyDef => ({ + id, label, type: "ratio", min: 0, max: 1, step: 0.05, default: def, unit: "fraction", group, help, +}); +const toggle = (id: string, label: string, def: 0 | 1, group: PropertyGroup, help?: string): PropertyDef => ({ + id, label, type: "toggle", default: def, unit: "on/off", group, help, +}); +const choice = (id: string, label: string, options: string[], def: string, group: PropertyGroup = "Behaviour", help?: string): PropertyDef => ({ + id, label, type: "enum", options, default: def, unit: "option", group, help, +}); +const azs = (def: number, min = 1): PropertyDef => + count("azs", "Zones (separate data centres)", "zones", def, min, 3, "Resilience", "Spreading across zones means one zone going down does not stop the service."); +const scaling = (on: 0 | 1, min: number, max: number, target: number): PropertyDef[] => [ + toggle("autoscale", "Add machines automatically (autoscaling)", on, "Scaling", "Adds or removes machines to stay near the target busyness."), + count("minCount", "Fewest machines", "machines", min, 1, 100, "Scaling"), + count("maxCount", "Most machines", "machines", max, 1, 200, "Scaling"), + ratio("targetUtil", "Aim to stay this busy (target utilisation)", target, "Scaling", "Add machines before this level. Waiting time starts to climb near 70% busy."), +]; + +// ---- the catalog ----------------------------------------------------------- + +type Entry = Omit; + +const ENTRIES: Record = { + // Generic high-level design blocks + client: { label: "Client", family: "hld", role: "client", vendor: "Users", icon: "client", + properties: [count("load", "Traffic sent (offered load)", "req/s", 1000, 1, 10_000_000)] }, + dns: { label: "DNS", family: "hld", role: "dns", vendor: "Resolver", icon: "dns", + managed: { capacity: 1_000_000, pricePerHour: 0.001, pricePerMillion: 0 }, + properties: [count("ttl", "Record TTL", "seconds", 300, 1, 86_400, "Behaviour")] }, + cdn: { label: "CDN", family: "hld", role: "cdn", vendor: "Edge cache", icon: "cdn", + managed: { capacity: 1_000_000, pricePerHour: 0.02, pricePerMillion: 0.75 }, + properties: [ratio("hitRate", "Answered nearby (edge hit rate)", 0.8, "Behaviour", "A hit is answered close to the user. Only misses reach your servers.")] }, + waf: { label: "Firewall", family: "hld", role: "firewall", vendor: "WAF", icon: "firewall", + managed: { capacity: 1_000_000, pricePerHour: 0.007, pricePerMillion: 0.6 }, + properties: [ratio("blockRate", "Blocked share", 0.02, "Behaviour", "Share of traffic dropped as malicious.")] }, + "rate-limiter": { label: "Rate limiter", family: "hld", role: "limiter", vendor: "Token bucket", icon: "limiter", + managed: { capacity: 1_000_000, pricePerHour: 0.01, pricePerMillion: 0 }, + properties: [count("limit", "Limit", "req/s", 5000, 10, 1_000_000, "Behaviour", "Requests above this are rejected, protecting what sits behind it.")] }, + "load-balancer": { label: "Load balancer", family: "hld", role: "balancer", vendor: "L7 LB", icon: "balancer", + properties: [size("generic", "general-small"), count("zones", "Zones (separate data centres)", "zones", 1, 1, 3, "Resilience")] }, + "api-gateway": { label: "API gateway", family: "hld", role: "gateway", vendor: "Gateway", icon: "gateway", + properties: [size("generic", "general-small"), count("count", "Machines (instances)", "machines", 2, 1, 50)] }, + "app-server": { label: "App server", family: "hld", role: "compute", vendor: "Compute", icon: "compute", + properties: [size("generic", "compute-small"), count("count", "Machines (instances)", "machines", 2, 1, 50), ...scaling(0, 2, 10, 0.6), azs(1)] }, + worker: { label: "Worker", family: "hld", role: "worker", vendor: "Consumer", icon: "worker", + properties: [size("generic", "compute-small"), count("count", "Workers", "workers", 2, 1, 100), count("batchSize", "Items saved per trip (batch size)", "events", 1, 1, 1000, "Behaviour", "How many items (clicks, posts, events) go to the store in one trip. Saving many at once turns thousands of writes a second into a few."), ...scaling(0, 1, 20, 0.7)] }, + cache: { label: "Cache", family: "hld", role: "cache", vendor: "Redis", icon: "cache", + properties: [size("generic", "memory-small"), count("count", "Machines (nodes)", "nodes", 1, 1, 20), ratio("hitRate", "Answered by the cache (hit rate)", 0.85, "Behaviour", "A hit means the database is never asked. A miss goes on to the database."), azs(1)] }, + database: { label: "Database", family: "hld", role: "database", vendor: "PostgreSQL", icon: "database", + properties: [ + size("generic", "memory-medium"), + count("replicas", "Read-only copies (read replicas)", "copies", 0, 0, 5, "Capacity", "Extra copies that share the reads. Every write still goes to the main copy (the primary)."), + ratio("readRatio", "Share that only reads", 0.8, "Behaviour", "Reads look data up. Writes change it."), + toggle("multiAz", "Extra copy that takes over (failover standby)", 0, "Resilience", "A standby copy in a second zone takes over if the main copy's zone fails. It doubles the main copy's cost."), + ] }, + nosql: { label: "NoSQL store", family: "hld", role: "nosql", vendor: "Key-value", icon: "nosql", + properties: [size("generic", "memory-medium"), count("count", "Machines (nodes)", "nodes", 3, 1, 30), azs(1)] }, + search: { label: "Search", family: "hld", role: "search", vendor: "Index", icon: "search", + properties: [size("generic", "memory-medium"), count("count", "Machines (nodes)", "nodes", 2, 1, 20), azs(1)] }, + queue: { label: "Queue", family: "hld", role: "queue", vendor: "Broker", icon: "queue", + managed: { capacity: 100_000, pricePerHour: 0.01, pricePerMillion: 0.04 }, + properties: [count("maxInFlight", "Most messages handled at once (max in flight)", "messages", 1000, 1, 1_000_000, "Behaviour")] }, + stream: { label: "Event stream", family: "hld", role: "stream", vendor: "Kafka", icon: "stream", + properties: [count("partitions", "Lanes (partitions)", "lanes", 4, 1, 256, "Capacity", "Each lane takes about 1,000 events a second."), count("retentionHours", "Keep events for (retention)", "hours", 24, 1, 8760, "Behaviour")] }, + "object-storage": { label: "Object storage", family: "hld", role: "storage", vendor: "Blob store", icon: "storage", + managed: { capacity: 1_000_000, pricePerHour: 0.01, pricePerMillion: 0.4 }, + properties: [count("capacityGb", "Capacity", "GB", 100, 1, 1_000_000)] }, + + // AWS services + "aws-route53": { label: "Route 53", family: "aws", role: "dns", vendor: "AWS DNS", icon: "dns", + managed: { capacity: 1_000_000, pricePerHour: 0.0007, pricePerMillion: 0 }, + properties: [choice("routing", "Routing policy", ["simple", "latency", "failover", "weighted"], "simple")] }, + "aws-cloudfront": { label: "CloudFront", family: "aws", role: "cdn", vendor: "AWS CDN", icon: "cdn", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.75 }, + properties: [ratio("hitRate", "Cache hit rate", 0.85), choice("priceClass", "Price class", ["100", "200", "All"], "100")] }, + "aws-waf": { label: "AWS WAF", family: "aws", role: "firewall", vendor: "Web ACL", icon: "firewall", + managed: { capacity: 1_000_000, pricePerHour: 0.007, pricePerMillion: 0.6 }, + properties: [ratio("blockRate", "Blocked share", 0.02), count("rules", "Rules", "rules", 10, 1, 100, "Behaviour")] }, + "aws-alb": { label: "ALB", family: "aws", role: "balancer", vendor: "Application LB", icon: "balancer", + managed: { capacity: 100_000, pricePerHour: 0.0225, pricePerMillion: 0.2 }, + properties: [azs(2, 2), toggle("crossZone", "Cross-zone balancing", 1, "Resilience")] }, + "aws-nlb": { label: "NLB", family: "aws", role: "balancer", vendor: "Network LB", icon: "balancer", + managed: { capacity: 200_000, pricePerHour: 0.0225, pricePerMillion: 0.1 }, + properties: [azs(2, 1)] }, + "aws-api-gateway": { label: "API Gateway", family: "aws", role: "gateway", vendor: "AWS API Gateway", icon: "gateway", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 1 }, + properties: [ + choice("apiType", "API type", ["HTTP", "REST"], "HTTP", "Behaviour", "REST APIs cost about 3.5 times more per request."), + count("limit", "Throttle", "req/s", 10_000, 10, 100_000, "Behaviour", "Account throttle; requests above it get 429 errors."), + ] }, + "aws-ec2-asg": { label: "EC2 Auto Scaling", family: "aws", role: "compute", vendor: "EC2", icon: "compute", + properties: [size("ec2", "m5.large"), count("count", "Desired instances", "instances", 2, 1, 200), ...scaling(1, 2, 10, 0.5), azs(2)] }, + "aws-fargate": { label: "ECS Fargate", family: "aws", role: "compute", vendor: "Containers", icon: "compute", + properties: [size("fargate", "1 vCPU / 2 GB"), count("count", "Tasks", "tasks", 2, 1, 500), ...scaling(1, 2, 20, 0.6), azs(2)] }, + "aws-lambda": { label: "Lambda", family: "aws", role: "function", vendor: "Serverless", icon: "function", + properties: [ + choice("memoryMb", "Memory", ["128", "256", "512", "1024", "2048"], "512", "Capacity", "More memory also means more CPU and a higher GB-second price."), + count("durationMs", "Duration", "ms", 120, 1, 900_000, "Behaviour"), + count("concurrency", "Reserved concurrency", "executions", 1000, 1, 10_000, "Capacity", "Concurrency divided by duration is the most it can serve; beyond that it throttles."), + ] }, + "aws-elasticache": { label: "ElastiCache", family: "aws", role: "cache", vendor: "Redis", icon: "cache", + properties: [size("elasticache", "cache.r6g.large"), count("count", "Shards", "shards", 1, 1, 50), count("replicasPerShard", "Replicas per shard", "replicas", 1, 0, 5, "Resilience"), ratio("hitRate", "Hit rate", 0.85), azs(2)] }, + "aws-rds": { label: "RDS", family: "aws", role: "database", vendor: "Managed SQL", icon: "database", + properties: [ + choice("engine", "Engine", ["PostgreSQL", "MySQL"], "PostgreSQL", "Behaviour"), + size("rds", "db.r5.large"), + count("replicas", "Read replicas", "replicas", 1, 0, 15, "Capacity", "Replicas share the reads; every write still goes to the primary."), + ratio("readRatio", "Read share", 0.8), + toggle("multiAz", "Multi-AZ", 1, "Resilience", "A synchronous standby in another zone. Doubles the primary cost."), + ] }, + "aws-dynamodb": { label: "DynamoDB", family: "aws", role: "nosql", vendor: "Key-value", icon: "nosql", + managed: { capacity: 40_000, pricePerHour: 0, pricePerMillion: 0 }, + properties: [ + choice("capacityMode", "Capacity mode", ["on-demand", "provisioned"], "on-demand", "Capacity", "On-demand bills per request; provisioned bills per hour for the units you reserve."), + count("rcu", "Read units", "RCU", 1000, 1, 100_000, "Capacity"), + count("wcu", "Write units", "WCU", 500, 1, 100_000, "Capacity"), + ratio("readRatio", "Read share", 0.8), + ] }, + "aws-opensearch": { label: "OpenSearch", family: "aws", role: "search", vendor: "Search", icon: "search", + properties: [size("opensearch", "m5.large.search"), count("count", "Data nodes", "nodes", 2, 1, 40), azs(2)] }, + "aws-sqs": { label: "SQS", family: "aws", role: "queue", vendor: "AWS queue", icon: "queue", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.4 }, + properties: [choice("queueType", "Queue type", ["standard", "FIFO"], "standard", "Behaviour", "FIFO keeps order but tops out near 3,000 messages/s with batching.")] }, + "aws-kinesis": { label: "Kinesis", family: "aws", role: "stream", vendor: "Data Streams", icon: "stream", + properties: [count("partitions", "Shards", "shards", 2, 1, 500, "Capacity", "Each shard takes about 1,000 records/s."), count("retentionHours", "Retention", "hours", 24, 24, 8760, "Behaviour")] }, + "aws-s3": { label: "S3", family: "aws", role: "storage", vendor: "Object storage", icon: "storage", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0.4 }, + properties: [choice("storageClass", "Storage class", ["Standard", "Intelligent-Tiering", "Glacier IR"], "Standard")] }, + + // Kubernetes + "k8s-ingress": { label: "Ingress", family: "k8s", role: "balancer", vendor: "ingress-nginx", icon: "balancer", + properties: [size("pod", "500m / 512Mi"), count("count", "Controller replicas", "pods", 2, 1, 20), azs(1)] }, + "k8s-service": { label: "Service", family: "k8s", role: "balancer", vendor: "ClusterIP", icon: "balancer", + managed: { capacity: 1_000_000, pricePerHour: 0, pricePerMillion: 0 }, + properties: [choice("serviceType", "Type", ["ClusterIP", "NodePort", "LoadBalancer"], "ClusterIP", "Behaviour", "A LoadBalancer Service also rents a cloud load balancer.")] }, + "k8s-deployment": { label: "Deployment", family: "k8s", role: "compute", vendor: "Pods", icon: "compute", + properties: [size("pod", "500m / 512Mi"), count("count", "Replicas", "pods", 2, 1, 200), ...scaling(1, 2, 10, 0.6), azs(1)] }, + "k8s-statefulset": { label: "StatefulSet", family: "k8s", role: "database", vendor: "PostgreSQL", icon: "database", + properties: [size("pod", "2 CPU / 4Gi"), count("replicas", "Read replicas", "pods", 0, 0, 5), ratio("readRatio", "Read share", 0.8)] }, + + // Docker + "docker-proxy": { label: "Reverse proxy", family: "docker", role: "balancer", vendor: "Traefik", icon: "balancer", + properties: [size("container", "1 CPU / 1GB"), count("count", "Containers", "containers", 1, 1, 10)] }, + "docker-container": { label: "App container", family: "docker", role: "compute", vendor: "Container", icon: "compute", + properties: [size("container", "1 CPU / 1GB"), count("count", "Replicas", "containers", 1, 1, 20)] }, + "docker-postgres": { label: "Postgres", family: "docker", role: "database", vendor: "postgres:16", icon: "database", + properties: [size("container", "2 CPU / 2GB"), count("replicas", "Read replicas", "containers", 0, 0, 3), ratio("readRatio", "Read share", 0.8)] }, + + // Linux, one host + "linux-nginx": { label: "nginx", family: "linux", role: "balancer", vendor: "Reverse proxy", icon: "balancer", + properties: [size("host", "2 cores / 4GB")] }, + "linux-service": { label: "App service", family: "linux", role: "compute", vendor: "systemd", icon: "compute", + properties: [size("host", "2 cores / 4GB"), count("count", "Hosts", "hosts", 1, 1, 10)] }, + "linux-postgres": { label: "PostgreSQL", family: "linux", role: "database", vendor: "postgresql.service", icon: "database", + properties: [size("host", "4 cores / 8GB"), count("replicas", "Read replicas", "hosts", 0, 0, 3), ratio("readRatio", "Read share", 0.8)] }, +}; + +const COMPONENT_KINDS = Object.keys(ENTRIES) as ComponentKind[]; +const KIND_SET = new Set(COMPONENT_KINDS); + +export function isComponentKind(value: string): value is ComponentKind { + return KIND_SET.has(value); +} + +export function roleOf(kind: ComponentKind): Role { + return ENTRIES[kind].role; +} + +function portsFor(kind: ComponentKind): PortDef[] { + const role = ENTRIES[kind].role; + const inbound = COMPONENT_KINDS.filter((k) => ROLE_NEXT[ENTRIES[k].role].includes(role)); + const outbound = COMPONENT_KINDS.filter((k) => ROLE_NEXT[role].includes(ENTRIES[k].role)); + const ports: PortDef[] = []; + if (inbound.length > 0) ports.push({ id: "in", dir: "in", accepts: inbound }); + if (outbound.length > 0) ports.push({ id: "out", dir: "out", accepts: outbound }); + return ports; +} + +export const COMPONENT_CATALOG: Record = Object.fromEntries( + COMPONENT_KINDS.map((kind) => [kind, { kind, ...ENTRIES[kind], ports: portsFor(kind) }]), +) as Record; + +export function canConnect(from: ComponentKind, to: ComponentKind): boolean { + return ROLE_NEXT[ENTRIES[from].role].includes(ENTRIES[to].role); +} + +export function kindsInFamily(family: Family): ComponentKind[] { + return COMPONENT_KINDS.filter((k) => ENTRIES[k].family === family); +} + +// ---- size catalogs ----------------------------------------------------------- + +const GENERIC_RULE = { general: "~800 req/s per vCPU at a light mix", compute: "~1,200 req/s per vCPU at a CPU-bound mix", memory: "~600 req/s per vCPU; holds a large working set" }; +const tier = (set: SizeSet, id: string, family: SizeTier["family"], vcpu: number, memoryGb: number, pricePerHour: number, capacityRule = GENERIC_RULE[family]): SizeTier => ({ + id, set, family, vcpu, memoryGb, capacityRule, pricePerHour, +}); + +export const SIZE_CATALOG: SizeTier[] = [ + tier("generic", "general-small", "general", 2, 8, 0.1), + tier("generic", "general-medium", "general", 4, 16, 0.2), + tier("generic", "general-large", "general", 8, 32, 0.4), + tier("generic", "general-xlarge", "general", 16, 64, 0.8), + tier("generic", "compute-small", "compute", 2, 4, 0.12), + tier("generic", "compute-medium", "compute", 4, 8, 0.24), + tier("generic", "compute-large", "compute", 8, 16, 0.48), + tier("generic", "compute-xlarge", "compute", 16, 32, 0.96), + tier("generic", "memory-small", "memory", 2, 16, 0.15), + tier("generic", "memory-medium", "memory", 4, 32, 0.3), + tier("generic", "memory-large", "memory", 8, 64, 0.6), + tier("generic", "memory-xlarge", "memory", 16, 128, 1.2), + + tier("ec2", "t3.medium", "general", 2, 4, 0.0416, "burstable; ~800 req/s per vCPU while it has credits"), + tier("ec2", "m5.large", "general", 2, 8, 0.096), + tier("ec2", "m5.xlarge", "general", 4, 16, 0.192), + tier("ec2", "c5.large", "compute", 2, 4, 0.085), + tier("ec2", "c5.xlarge", "compute", 4, 8, 0.17), + tier("ec2", "c5.2xlarge", "compute", 8, 16, 0.34), + tier("ec2", "r5.large", "memory", 2, 16, 0.126), + + tier("fargate", "0.25 vCPU / 0.5 GB", "general", 0.25, 0.5, 0.0123), + tier("fargate", "0.5 vCPU / 1 GB", "general", 0.5, 1, 0.0247), + tier("fargate", "1 vCPU / 2 GB", "general", 1, 2, 0.0494), + tier("fargate", "2 vCPU / 4 GB", "general", 2, 4, 0.0988), + tier("fargate", "4 vCPU / 8 GB", "general", 4, 8, 0.1975), + + tier("rds", "db.t3.medium", "memory", 2, 4, 0.068), + tier("rds", "db.m5.large", "memory", 2, 8, 0.171), + tier("rds", "db.r5.large", "memory", 2, 16, 0.24), + tier("rds", "db.r5.xlarge", "memory", 4, 32, 0.48), + tier("rds", "db.r5.2xlarge", "memory", 8, 64, 0.96), + + tier("elasticache", "cache.t3.small", "memory", 2, 1.37, 0.034, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.m5.large", "memory", 2, 6.38, 0.156, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.r6g.large", "memory", 2, 13.07, 0.206, "~15,000 ops/s per vCPU"), + tier("elasticache", "cache.r6g.xlarge", "memory", 4, 26.32, 0.411, "~15,000 ops/s per vCPU"), + + tier("opensearch", "t3.medium.search", "memory", 2, 4, 0.073, "~300 queries/s per vCPU"), + tier("opensearch", "m5.large.search", "memory", 2, 8, 0.142, "~300 queries/s per vCPU"), + tier("opensearch", "r5.large.search", "memory", 2, 16, 0.186, "~300 queries/s per vCPU"), + + tier("pod", "250m / 256Mi", "general", 0.25, 0.25, 0.01, "CPU request; ~800 req/s per full core"), + tier("pod", "500m / 512Mi", "general", 0.5, 0.5, 0.02, "CPU request; ~800 req/s per full core"), + tier("pod", "1 CPU / 1Gi", "general", 1, 1, 0.04, "CPU request; ~800 req/s per full core"), + tier("pod", "2 CPU / 4Gi", "general", 2, 4, 0.09, "CPU request; ~800 req/s per full core"), + + tier("container", "0.5 CPU / 512MB", "general", 0.5, 0.5, 0.02, "--cpus limit; ~800 req/s per full core"), + tier("container", "1 CPU / 1GB", "general", 1, 1, 0.04, "--cpus limit; ~800 req/s per full core"), + tier("container", "2 CPU / 2GB", "general", 2, 2, 0.08, "--cpus limit; ~800 req/s per full core"), + + tier("host", "1 core / 2GB", "general", 1, 2, 0.02, "~800 req/s per core"), + tier("host", "2 cores / 4GB", "general", 2, 4, 0.04, "~800 req/s per core"), + tier("host", "4 cores / 8GB", "general", 4, 8, 0.08, "~800 req/s per core"), + tier("host", "8 cores / 16GB", "general", 8, 16, 0.16, "~800 req/s per core"), +]; + +export function sizesFor(set: SizeSet): SizeTier[] { + return SIZE_CATALOG.filter((t) => t.set === set); +} diff --git a/server/src/shared/lab/engine/challenge.ts b/server/src/shared/lab/engine/challenge.ts new file mode 100644 index 00000000..55d7e19a --- /dev/null +++ b/server/src/shared/lab/engine/challenge.ts @@ -0,0 +1,290 @@ +// The run behind a visual challenge: pure and server-importable like the model it +// wraps. It takes a board and plays it through the challenge's scenarios (peak +// traffic, then each fault), asks the tiered-architecture model for the numbers in +// every one, and turns them into a pass or fail per check, each with the measured +// value, the target and, when it fails, the reason. +// +// Functional checks are about structure: can a request travel the path the feature +// needs? Non-functional checks are measurements: latency, how much is still served +// when something dies, whether queued work is all counted, and cost. + +import type { Board, BoardNode, ChallengeDef, ChallengeScenario, CheckDef, CheckMetric, Fault, HldLabSpec } from "./hld-types.js"; +import type { ComponentKind, Role } from "./catalog.js"; +import { COMPONENT_CATALOG, roleOf } from "./catalog.js"; +import { runTieredModel, type ModelOptions, type ModelResult, type Targets, type TierLoad } from "./tiered-architecture.js"; + +export const STEADY: ChallengeScenario = { + id: "steady", + title: "Peak traffic", + story: "Everything is healthy and traffic is at its busiest.", + faults: [], +}; + +export interface CheckResult { + id: string; + kind: "functional" | "non-functional"; + label: string; + pass: boolean; + /** What the run found, with its unit. */ + measured: string; + /** What it had to be. */ + target: string; + /** Why it failed and what to look at; absent when it passed. */ + reason?: string; + /** The scenario the number comes from, so the board can replay it. */ + scenario: string; +} + +export interface PhaseReport { + id: string; + title: string; + story: string; + load: number; + /** The board as the scenario left it (fault applied). */ + board: Board; + /** The components the fault took down or thinned out. */ + hit: string[]; + /** False when the fault named a part this design does not have. */ + applicable: boolean; + /** The part the fault names when the design has none: "cache". */ + missing?: string; + result: ModelResult; +} + +export interface ChallengeReport { + phases: PhaseReport[]; + checks: CheckResult[]; + passed: number; + total: number; + allPass: boolean; +} + +const labelOf = (kind: ComponentKind) => COMPONENT_CATALOG[kind].label; +// Lowercases the first letter of a label for use mid-sentence, but leaves acronyms such as CDN alone. +const lower = (text: string) => (/^[A-Z]{2}/.test(text) ? text : text.charAt(0).toLowerCase() + text.slice(1)); +const pct = (n: number) => `${(Math.floor(n * 10000) / 100).toFixed(2)}%`; +const roleLabel = (role: Role) => Object.values(COMPONENT_CATALOG).find((c) => c.role === role)?.label ?? role; +const perSec = (n: number) => `${Math.round(n).toLocaleString("en-US")}/s`; + +function metricText(metric: CheckMetric, v: number): string { + switch (metric) { + case "p99": return `${Math.round(v)} ms`; + case "capacity": return perSec(v); + case "served": return `${(Math.floor(v * 1000) / 10).toFixed(1)}%`; + case "availability": return pct(v); + case "cost": return `$${v.toFixed(2)}/h`; + } +} +const targetText = (metric: CheckMetric, op: "<=" | ">=", v: number) => + `${op === "<=" ? "at most" : "at least"} ${metric === "availability" ? pct(v) : metricText(metric, v)}`; + +// ---- faults ------------------------------------------------------------------- + +function applyFaults(board: Board, faults: Fault[], steady: ModelResult): { board: Board; hit: string[]; applicable: boolean } { + const nodes: BoardNode[] = board.nodes.map((n) => ({ ...n, props: { ...(n.props ?? {}) } })); + const hit: string[] = []; + for (const fault of faults) { + const targets = nodes.filter((n) => roleOf(n.kind) === fault.role); + if (targets.length === 0) continue; + if (fault.type === "down") { + for (const n of targets) { n.props!.down = 1; hit.push(n.id); } + } else { + const first = targets[0]!; + const units = steady.tiers.find((t) => t.id === first.id)?.units ?? 1; + if (units <= 1) first.props!.down = 1; + else { first.props!.autoscale = 0; first.props!.count = units - 1; } + hit.push(first.id); + } + } + return { board: { ...board, nodes }, hit, applicable: hit.length > 0 }; +} + +// ---- functional checks: can a request travel the path? --------------------------- + +function reachFrom(board: Board, starts: string[]): Set { + const next = new Map(); + for (const e of board.edges) next.set(e.from, [...(next.get(e.from) ?? []), e.to]); + const seen = new Set(); + const queue = [...starts]; + while (queue.length > 0) { + const id = queue.shift()!; + for (const to of next.get(id) ?? []) if (!seen.has(to)) { seen.add(to); queue.push(to); } + } + return seen; +} + +/** Walks the roles in order. Returns the labels found so far and the first role that has no way in. */ +export function followChain(board: Board, chain: Role[]): { trail: string[]; missing?: Role } { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + let frontier = board.nodes.filter((n) => roleOf(n.kind) === chain[0] && !n.props?.down).map((n) => n.id); + const trail: string[] = frontier.length > 0 ? [labelOf(byId.get(frontier[0]!)!.kind)] : []; + if (frontier.length === 0) return { trail, missing: chain[0] }; + for (const role of chain.slice(1)) { + const reached = reachFrom(board, frontier); + frontier = [...reached].filter((id) => roleOf(byId.get(id)!.kind) === role && !byId.get(id)!.props?.down); + if (frontier.length === 0) return { trail, missing: role }; + trail.push(labelOf(byId.get(frontier[0]!)!.kind)); + } + return { trail }; +} + +const ROLE_NAME: Partial> = { + client: "a client", compute: "an app server", database: "a database", queue: "a queue", worker: "a worker", cache: "a cache", balancer: "a load balancer", +}; +const roleName = (role: Role) => ROLE_NAME[role] ?? `a ${role}`; + +function pathCheck(def: Extract, board: Board): CheckResult { + const { trail, missing } = followChain(board, def.chain); + if (missing !== undefined && def.inlineIfNo && !board.nodes.some((n) => roleOf(n.kind) === def.inlineIfNo)) { + return { + id: def.id, kind: def.kind, label: def.label, pass: true, scenario: "steady", target: def.target, + measured: `saved during the request (inline), no ${lower(roleLabel(def.inlineIfNo))}`, + }; + } + const pass = missing === undefined; + const last = trail.at(-1); + return { + id: def.id, kind: def.kind, label: def.label, pass, scenario: "steady", target: def.target, + measured: pass ? trail.join(" > ") : trail.length > 0 ? `${trail.join(" > ")} > ?` : "no path", + reason: pass ? undefined : trail.length === 0 + ? `There is no ${missing === "client" ? "client" : roleName(missing!).replace(/^an? /, "")} on the board.` + : `The path stops at ${lower(last!)}: link it to ${roleName(missing!)}.`, + }; +} + +// ---- non-functional checks: measured in a scenario --------------------------------- + +function worstTier(result: ModelResult): TierLoad | undefined { + return [...result.tiers].filter((t) => t.reachable && !t.managed).sort((a, b) => b.utilisation - a.utilisation)[0]; +} +const busy = (t: TierLoad) => `${labelOf(t.kind)} is ${Math.round(t.utilisation * 100)}% busy`; + +function measure(metric: CheckMetric, r: ModelResult, load: number): number { + switch (metric) { + case "p99": return r.p99Ms; + case "capacity": return r.capacityCeiling; + case "served": return load > 0 ? Math.min(1, r.capacityCeiling / load) : 1; + case "availability": return r.availability; + case "cost": return r.costPerHour; + } +} + +function whyMetricFailed(metric: CheckMetric, r: ModelResult, scenario: PhaseReport): string { + const worst = worstTier(r); + const during = scenario.id === "steady" ? "" : ` while ${lower(scenario.title)}`; + if (r.failure) return r.failure; + switch (metric) { + case "p99": { + const slow = [...r.tiers].filter((t) => t.waitMs > 0.5).sort((x, y) => y.waitMs - x.waitMs).slice(0, 2); + return slow.length > 0 + ? `Requests wait in line at ${slow.map((t) => `the ${lower(labelOf(t.kind))} (${Math.round(t.utilisation * 100)}% busy, +${Math.round(t.waitMs)} ms)`).join(" and ")}${during}. Give them more capacity, or take load off them.` + : "The path itself is too slow: fewer hops would help."; + } + case "capacity": + case "served": + return worst ? `${busy(worst)}${during}, so it cannot serve the whole load. Add machines, read-only copies or a cache in front of it.` : "Nothing on the board can serve the load."; + case "availability": { + const role = r.weakest?.role; + return role ? `${roleLabel(role)} is the weak link (${pct(r.weakest!.availability)}): run more than one, or in two zones.` : "Add redundancy."; + } + case "cost": { + const priciest = [...r.tiers].sort((a, b) => b.cost - a.cost)[0]; + return priciest ? `${labelOf(priciest.kind)} costs the most ($${priciest.cost.toFixed(2)}/h). Try a smaller size or fewer machines.` : "Over budget."; + } + } +} + +function metricCheck(def: Extract, phases: Map): CheckResult { + const phase = phases.get(def.scenario) ?? phases.get("steady")!; + const value = measure(def.metric, phase.result, phase.load); + const pass = def.op === "<=" ? value <= def.value : value >= def.value; + return { + id: def.id, kind: def.kind, label: def.label, pass, scenario: phase.id, + measured: metricText(def.metric, value) + (phase.applicable || phase.id === "steady" ? "" : ` (no ${phase.missing} to lose)`), + target: targetText(def.metric, def.op, def.value), + reason: pass ? undefined : whyMetricFailed(def.metric, phase.result, phase), + }; +} + +function drainCheck(def: Extract, steady: PhaseReport, scenarioId: string, inlineClicks: boolean, share = 1): CheckResult { + const { board, result, load } = steady; + const queue = board.nodes.find((n) => roleOf(n.kind) === "queue" && result.tiers.find((t) => t.id === n.id)?.reachable); + const items = def.items ?? "clicks"; + const done = def.done ?? "counted"; + const Items = items.charAt(0).toUpperCase() + items.slice(1); + const target = `no ${items} lost, all ${done} within ${def.maxDrainSeconds} s of the worker coming back`; + const base = { id: def.id, kind: def.kind, label: def.label, scenario: scenarioId, target }; + if (!queue && inlineClicks && !board.nodes.some((n) => roleOf(n.kind) === "queue")) { + return { ...base, pass: true, measured: `no worker to lose: ${items} are saved during the request (inline)` }; + } + if (!queue) { + // With no queue there is no link to read the rate from, so take the queue's share of the stream. + const lost = Math.round(load * share * def.outageSeconds); + return { ...base, pass: false, measured: `${lost.toLocaleString("en-US")} ${items} lost in ${def.outageSeconds} s`, reason: `${Items} have nowhere to wait while the worker is down. Put a queue between the app server and the worker.` }; + } + const workers = board.edges.filter((e) => e.from === queue.id).map((e) => result.tiers.find((t) => t.id === e.to)).filter((t): t is TierLoad => !!t && roleOf(t.kind) === "worker"); + if (workers.length === 0) { + return { ...base, pass: false, measured: `${items} pile up and are never ${done}`, reason: "The queue has no worker. Link the queue to a worker, and the worker to where it saves its work." }; + } + const arriving = board.edges.filter((e) => e.to === queue.id).reduce((sum, e) => sum + (result.edgeFlows[`${e.from}>${e.to}`] ?? 0), 0); + const capacity = workers.reduce((sum, w) => sum + w.capacity, 0); + const spare = capacity - arriving; + const backlog = Math.round(arriving * def.outageSeconds); + if (spare <= 0) { + return { ...base, pass: false, measured: `${backlog.toLocaleString("en-US")} ${items} waiting, never all ${done}`, reason: `Workers handle ${perSec(capacity)} but ${items} arrive at ${perSec(arriving)}: they can never catch up. Add workers or a bigger size.` }; + } + const drain = Math.ceil(backlog / spare); + const pass = drain <= def.maxDrainSeconds; + return { + ...base, pass, measured: `${backlog.toLocaleString("en-US")} ${items} waiting, all ${done} after ${drain} s`, + reason: pass ? undefined : `Workers have only ${perSec(spare)} to spare, so ${backlog.toLocaleString("en-US")} waiting ${items} take ${drain} s. Add workers or a bigger size.`, + }; +} + +// ---- the run ---------------------------------------------------------------------- + +/** Labs with no authored challenge are scored on their targets, as non-functional checks. */ +export function challengeFor(spec: HldLabSpec): ChallengeDef { + if (spec.challenge) return spec.challenge; + const level = spec.levels[0]; + const t = level?.targets ?? {}; + const checks: CheckDef[] = []; + const add = (id: string, label: string, metric: CheckMetric, op: "<=" | ">=", value?: number) => { + if (value != null) checks.push({ type: "metric", id, kind: "non-functional", label, scenario: "steady", metric, op, value }); + }; + add("capacity", "Serves the load", "capacity", ">=", t.rps); + add("p99", "Slowest 1 in 100 requests (p99)", "p99", "<=", t.p99Ms); + add("availability", "Stays up (availability)", "availability", ">=", t.availability); + add("cost", "Cost per hour", "cost", "<=", t.budgetPerHour); + return { peakLoad: level?.load ?? 1000, scenarios: [], checks }; +} + +/** The model run for a lab: the same options the challenge's own scenarios use, so every number agrees. */ +export function runModel(spec: HldLabSpec, board: Board, load: number, targets: Targets = {}): ModelResult { + const options: ModelOptions = { + inlineWrites: Boolean(spec.challenge?.inlineClicks) && !board.nodes.some((n) => roleOf(n.kind) === "queue"), + shares: spec.challenge?.shares, + }; + return runTieredModel(board, load, targets, options); +} + +/** Plays the board through the challenge. `board` must already carry the learner's properties. */ +export function runChallenge(spec: HldLabSpec, board: Board, load: number): ChallengeReport { + const challenge = challengeFor(spec); + const steadyResult = runModel(spec, board, load); + const phases: PhaseReport[] = [{ ...STEADY, load, board, hit: [], applicable: true, result: steadyResult }]; + for (const scenario of challenge.scenarios) { + const { board: faulted, hit, applicable } = applyFaults(board, scenario.faults, steadyResult); + const missing = applicable ? undefined : lower(roleLabel(scenario.faults[0]?.role ?? "compute")); + phases.push({ id: scenario.id, title: scenario.title, story: scenario.story, load, board: faulted, hit, applicable, missing, result: runModel(spec, faulted, load) }); + } + const byId = new Map(phases.map((p) => [p.id, p])); + const steady = phases[0]!; + const checks: CheckResult[] = challenge.checks.map((def) => { + if (def.type === "path") return pathCheck(def, board); + if (def.type === "drain") return drainCheck(def, steady, challenge.scenarios.find((s) => s.faults.some((f) => f.type === "down" && f.role === "worker"))?.id ?? "steady", Boolean(challenge.inlineClicks), challenge.shares?.queue ?? 1); + return metricCheck(def, byId); + }); + const passed = checks.filter((c) => c.pass).length; + return { phases, checks, passed, total: checks.length, allPass: passed === checks.length }; +} diff --git a/server/src/shared/lab/engine/hld-types.ts b/server/src/shared/lab/engine/hld-types.ts new file mode 100644 index 00000000..bcea8aa7 --- /dev/null +++ b/server/src/shared/lab/engine/hld-types.ts @@ -0,0 +1,143 @@ +// The pure data shapes of a high-level design (HLD) lab: the board, the challenge, the +// reference solution and the HLD spec. No UI and no network imports, so the server can +// replay a design with the same types the lab board uses. + +import type { ComponentKind, Role } from "./catalog.js"; + +export type LabFamily = "hld" | "db" | "net"; + +export interface BoardNode { + id: string; + kind: ComponentKind; + x: number; + y: number; + props?: Record; +} + +export interface BoardEdge { + from: string; + to: string; + /** Which dot each end uses (t, r, b, l); the board picks bottom to top when absent. */ + via?: [string, string]; +} + +export interface Board { + nodes: BoardNode[]; + edges: BoardEdge[]; +} + +export interface LabLevel { + id: string; + load: number; + targets: { rps?: number; p99Ms?: number; availability?: number; budgetPerHour?: number }; + event?: string; +} + +// ---- challenge: the checks a visual lab's Run puts the design through ---------- + +/** Something that goes wrong in a scenario. */ +export type Fault = + /** One instance of the first component with this role dies; a fleet of one dies whole. */ + | { type: "lose-instance"; role: Role } + /** Every component with this role goes down. */ + | { type: "down"; role: Role }; + +export interface ChallengeScenario { + id: string; + /** Short name, shown on the run strip: "The cache dies". */ + title: string; + /** One line shown while this phase plays. */ + story: string; + faults: Fault[]; +} + +export type CheckMetric = "p99" | "capacity" | "served" | "availability" | "cost"; + +interface CheckBase { + id: string; + kind: "functional" | "non-functional"; + label: string; +} + +export type CheckDef = + /** A functional check: a request can travel client -> ... -> the next role, in order. */ + | (CheckBase & { + type: "path"; + chain: Role[]; + target: string; + /** A design with no component of this role passes without the chain: the work is done inline instead. */ + inlineIfNo?: Role; + }) + /** A measured check: one number from one scenario against a limit. */ + | (CheckBase & { type: "metric"; scenario: string; metric: CheckMetric; op: "<=" | ">="; value: number }) + /** Work queued while its consumer is down must be fully counted once it is back. */ + | (CheckBase & { + type: "drain"; + outageSeconds: number; + maxDrainSeconds: number; + /** What waits in the queue, plural: "clicks" (the default), "posts", "messages". */ + items?: string; + /** What happens to each item once a worker takes it: "counted" (the default), "delivered", "saved". */ + done?: string; + }); + +export interface ChallengeDef { + /** Requests a second at the busiest moment; every scenario runs at this load. */ + peakLoad: number; + /** + * With no queue on the board, each request writes its click to the database before it + * answers, so counting works but costs a database write per request. + */ + inlineClicks?: boolean; + /** + * The share of requests that send work to parts of a role, for side jobs only some + * requests need: { queue: 0.1 } means 1 request in 10 leaves a job in the queue. + * Each share is above 0 and at most 1; a role with no share gets the whole stream. + */ + shares?: Partial>; + scenarios: ChallengeScenario[]; + checks: CheckDef[]; +} + +// ---- solution: a reference design a learner can open and compare with ---------- + +/** Why one part is in the reference design. */ +export interface SolutionPart { + /** Plain words: what this part does in the design. */ + why: string; + /** Ids of the checks this part helps pass. */ + checks: string[]; + /** What goes wrong without it, with numbers from the model. */ + without: string; +} + +export interface SolutionDef { + /** The reference design. It must pass every check of the lab. */ + board: Board; + /** One or two plain sentences: the idea behind the design. */ + summary: string; + /** Keyed by node id in `board`. */ + parts: Record; +} + +export interface LabBase { + slug: string; + family: LabFamily; + title: string; + purpose: string; + limits: string; + hints: string[]; + referenceSlug?: string; +} + +export interface HldLabSpec extends LabBase { + family: "hld"; + allowedComponents: ComponentKind[]; + startingBoard?: Board; + scenario: string; + levels: LabLevel[]; + /** A visual challenge: functional and non-functional checks and the scenarios that test them. */ + challenge?: ChallengeDef; + /** A reference design the learner can open after pressing Run, and compare with their own. */ + solution?: SolutionDef; +} diff --git a/server/src/shared/lab/engine/tiered-architecture.ts b/server/src/shared/lab/engine/tiered-architecture.ts new file mode 100644 index 00000000..a2527e14 --- /dev/null +++ b/server/src/shared/lab/engine/tiered-architecture.ts @@ -0,0 +1,537 @@ +// The tiered-architecture model: the engine behind the lab board. Pure and +// server-importable (no DOM, no React), so a graded lab can run it on the server. +// +// From a board and an offered load it routes requests down the links, evaluates +// every component by its role and configuration (instance fleets, autoscaling, +// zones, read replicas, managed services billed per request, Lambda concurrency, +// rate limits, queues), and returns utilisation, the capacity ceiling, p50/p99 +// latency with the queueing knee, availability and cost, scored against targets. +// +// Numbers are illustrative. The rules below are stated so a "how this is +// calculated" panel can show them. + +import type { Board, BoardNode } from "./hld-types.js"; +import type { ComponentKind, Role, SizeTier } from "./catalog.js"; +import { COMPONENT_CATALOG, SIZE_CATALOG, roleOf } from "./catalog.js"; + +const PER_VCPU: Record = { general: 800, compute: 1200, memory: 600 }; +/** Roles that serve far more, or far less, per vCPU than a typical app server. */ +const ROLE_RATE: Partial> = { cache: 15_000, search: 300, nosql: 2_000 }; +const NETWORK_MS = 10; +/** Chance a single Availability Zone is up. */ +const AZ_AVAIL = 0.9995; +/** Regional managed services are spread across zones by the provider. */ +const MANAGED_AVAIL = 0.9999; + +const SERVICE_MS: Record = { + client: 0, dns: 1, cdn: 2, firewall: 1, limiter: 1, balancer: 2, gateway: 5, + compute: 20, function: 0, worker: 15, cache: 1, database: 8, nosql: 5, search: 25, + queue: 5, stream: 10, storage: 20, +}; +const SINGLE_AVAIL: Partial> = { + balancer: 0.9995, gateway: 0.9995, compute: 0.99, worker: 0.99, cache: 0.999, + database: 0.999, nosql: 0.9995, search: 0.999, stream: 0.999, +}; + +export interface TierLoad { + id: string; + kind: ComponentKind; + capacity: number; + utilisation: number; + down: boolean; + reachable: boolean; + /** Instances actually running, after autoscaling. */ + units: number; + /** Managed services scale for you; their utilisation is rarely the story. */ + managed: boolean; + /** A short line for the card: autoscaled, throttling, backlog, and so on. */ + note?: string; + /** What this component costs per hour whether or not it is serving. */ + cost: number; + /** Milliseconds a request spends waiting in line here, on top of its service time. Zero off the request path. */ + waitMs: number; + /** For a cache: what it was asked, what it answered itself, and what went on to the database. */ + cacheStats?: { hitRate: number; reads: number; hits: number; misses: number }; +} + +/** One labelled share of the traffic on a link, such as "cache misses" or "click writes". */ +export interface EdgePart { + label: string; + rate: number; +} + +/** Optional rules a lab can switch on for the whole run. */ +export interface ModelOptions { + /** + * Every request an app server serves also writes one row (a click) to the database + * before it answers. Labs turn this on when the board has no queue to carry the clicks. + */ + inlineWrites?: boolean; + /** + * The share of requests that send work to parts of a role, for side jobs that only + * some requests need: { queue: 0.1 } means 1 request in 10 leaves a job in the queue. + * Applied wherever a part of another role sends to that role, so it holds however the + * learner links the board. A role with no share gets the whole stream. + */ + shares?: Partial>; +} + +export interface Targets { + rps?: number; + p99Ms?: number; + availability?: number; + budgetPerHour?: number; +} + +export interface ModelResult { + capacityCeiling: number; + p50Ms: number; + p99Ms: number; + availability: number; + costPerHour: number; + tiers: TierLoad[]; + pass: { rps: boolean; p99: boolean; availability: boolean; budget: boolean }; + allPass: boolean; + /** Why the design is broken, when a component is down or unlinked. */ + failure?: string; + /** Request rate on each live link, keyed "from>to". */ + edgeFlows: Record; + /** What the traffic on a link is made of, where that is worth saying (cache reads, misses, writes). */ + edgeParts: Record; + /** Requests rejected by rate limits and throttles, per second. */ + dropped: number; + /** Requests filtered out by firewalls, per second. */ + blocked: number; + /** How fast queued work piles up because consumers are too slow, per second. */ + backlog: number; + /** The role on the request path with the lowest availability, for "add redundancy here". */ + weakest?: { role: Role; availability: number }; +} + +// ---- reading a node's configuration ------------------------------------------- + +function propOf(node: BoardNode, key: string): number | string | undefined { + const own = node.props?.[key]; + if (own !== undefined) return own; + return COMPONENT_CATALOG[node.kind].properties.find((p) => p.id === key)?.default; +} +function num(node: BoardNode, key: string, fallback: number): number { + const v = propOf(node, key); + return typeof v === "number" ? v : fallback; +} +function str(node: BoardNode, key: string, fallback: string): string { + const v = propOf(node, key); + return typeof v === "string" ? v : fallback; +} +function tierOf(node: BoardNode): SizeTier { + const id = propOf(node, "size"); + return SIZE_CATALOG.find((t) => t.id === id) ?? SIZE_CATALOG[0]; +} +const isDown = (node: BoardNode) => Boolean(node.props?.down); +const rate = (n: number) => Math.round(n).toLocaleString("en-US"); + +/** A fleet of `units` spread over `zones`; it is up while any zone has a live instance. */ +function fleetAvailability(single: number, units: number, zones: number): number { + const n = Math.max(1, Math.round(zones)); + const perZone = Math.max(1, units / n); + const zone = AZ_AVAIL * (1 - Math.pow(1 - single, perZone)); + return 1 - Math.pow(1 - zone, n); +} + +// ---- routing -------------------------------------------------------------------- + +/** Nodes a request can reach from any live client, following the links and skipping down nodes. */ +function reachableFrom(board: Board): Set { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + const next = new Map(); + for (const e of board.edges) next.set(e.from, [...(next.get(e.from) ?? []), e.to]); + const seen = new Set(); + const queue = board.nodes.filter((n) => n.kind === "client" && !isDown(n)).map((n) => n.id); + for (const id of queue) seen.add(id); + while (queue.length > 0) { + const id = queue.shift()!; + for (const to of next.get(id) ?? []) { + const node = byId.get(to); + if (node && !isDown(node) && !seen.has(to)) { + seen.add(to); + queue.push(to); + } + } + } + return seen; +} + +/** Live links between reachable nodes, deduplicated, as parent to children and child to parents. */ +function liveLinks(board: Board, reachable: Set) { + const children = new Map(); + const parents = new Map(); + for (const e of board.edges) { + if (!reachable.has(e.from) || !reachable.has(e.to) || e.from === e.to) continue; + const kids = children.get(e.from) ?? []; + if (kids.includes(e.to)) continue; + children.set(e.from, [...kids, e.to]); + parents.set(e.to, [...(parents.get(e.to) ?? []), e.from]); + } + return { children, parents }; +} + +/** Reachable nodes in topological order (Kahn), so load and latency flow parent before child. */ +function topoOrder(reachable: Set, children: Map, parents: Map): string[] { + const indegree = new Map([...reachable].map((id) => [id, (parents.get(id) ?? []).length])); + const queue = [...reachable].filter((id) => indegree.get(id) === 0); + const order: string[] = []; + while (queue.length > 0) { + const id = queue.shift()!; + order.push(id); + for (const kid of children.get(id) ?? []) { + indegree.set(kid, (indegree.get(kid) ?? 1) - 1); + if (indegree.get(kid) === 0) queue.push(kid); + } + } + return order; +} + +const ASYNC_ROLES = new Set(["queue", "stream"]); + +/** Nodes on the synchronous request path: reachable without passing through a queue or stream. */ +function synchronous(order: string[], byId: Map, children: Map): Set { + const seen = new Set(order.filter((id) => byId.get(id)!.kind === "client")); + const queue = [...seen]; + while (queue.length > 0) { + const id = queue.shift()!; + if (ASYNC_ROLES.has(roleOf(byId.get(id)!.kind))) continue; + for (const kid of children.get(id) ?? []) { + if (!seen.has(kid)) { + seen.add(kid); + queue.push(kid); + } + } + } + return seen; +} + +/** The most a node lets through per second; above it, requests are rejected. */ +function limitOf(node: BoardNode): number | undefined { + if (node.kind === "rate-limiter" || node.kind === "aws-api-gateway") return num(node, "limit", Infinity); + if (node.kind === "aws-lambda") return lambdaCapacity(node); + return undefined; +} +/** Share of what a node serves that continues downstream (CDN misses, traffic a firewall lets in). */ +function passOn(node: BoardNode): number { + const role = roleOf(node.kind); + if (role === "cdn") return 1 - num(node, "hitRate", 0); + if (role === "firewall") return 1 - num(node, "blockRate", 0); + // A cache answers its hits itself; only the misses go on to a database linked behind it. + if (role === "cache") return 1 - num(node, "hitRate", 0); + return 1; +} +function lambdaCapacity(node: BoardNode): number { + return (num(node, "concurrency", 1000) * 1000) / Math.max(1, num(node, "durationMs", 120)); +} + +// ---- evaluating one component ---------------------------------------------------- + +interface Evaluation { + capacity: number; + units: number; + cost: number; + serviceMs: number; + availability: number; + /** Whether requests wait in line as it gets busy (the p99 knee), or are throttled instead. */ + queueing: boolean; + managed: boolean; + note?: string; +} + +function evaluate(node: BoardNode, flow: number, inlineWrites = 0): Evaluation { + const def = COMPONENT_CATALOG[node.kind]; + const role = def.role; + + if (node.kind === "aws-lambda") { + const duration = Math.max(1, num(node, "durationMs", 120)); + const memoryGb = Number(str(node, "memoryMb", "512")) / 1024; + const capacity = lambdaCapacity(node); + const cost = flow * 3600 * (0.2 / 1e6 + (duration / 1000) * memoryGb * 0.0000166667); + const note = flow > capacity ? `throttling ${rate(flow - capacity)}/s` : flow > 0 ? `~${rate(Math.ceil((flow * duration) / 1000))} running at once` : undefined; + return { capacity, units: 1, cost, serviceMs: duration, availability: MANAGED_AVAIL, queueing: false, managed: true, note }; + } + + if (node.kind === "aws-dynamodb") { + const reads = num(node, "readRatio", 0.8); + if (str(node, "capacityMode", "on-demand") === "provisioned") { + const rcu = num(node, "rcu", 1000); + const wcu = num(node, "wcu", 500); + const util = Math.max((flow * reads) / (rcu * 2), (flow * (1 - reads)) / wcu); + return { + capacity: util > 0 ? flow / util : rcu * 2 + wcu, units: 1, cost: rcu * 0.00013 + wcu * 0.00065, + serviceMs: 5, availability: MANAGED_AVAIL, queueing: false, managed: true, + note: util > 1 ? "throttled: raise RCU/WCU or go on-demand" : undefined, + }; + } + return { + capacity: 40_000, units: 1, cost: (flow * 3600 * (reads * 0.25 + (1 - reads) * 1.25)) / 1e6, + serviceMs: 5, availability: MANAGED_AVAIL, queueing: false, managed: true, + }; + } + + if (role === "stream") { + const shards = num(node, "partitions", 2); + const aws = def.family === "aws"; + return { + capacity: shards * 1000, units: shards, cost: shards * 0.015 + (aws ? (flow * 3600 * 0.014) / 1e6 : 0), + serviceMs: SERVICE_MS.stream, availability: aws ? MANAGED_AVAIL : fleetAvailability(0.999, shards, 1), + queueing: false, managed: aws, note: flow > shards * 1000 ? "producers throttled: add shards" : undefined, + }; + } + + if (def.managed) { + let capacity = def.managed.capacity; + let perMillion = def.managed.pricePerMillion; + if (node.kind === "aws-api-gateway" && str(node, "apiType", "HTTP") === "REST") perMillion = 3.5; + if (node.kind === "aws-sqs" && str(node, "queueType", "standard") === "FIFO") capacity = 3000; + const hourly = node.kind === "k8s-service" && str(node, "serviceType", "ClusterIP") === "LoadBalancer" ? 0.0225 : def.managed.pricePerHour; + const limit = limitOf(node); + if (limit != null) capacity = Math.min(capacity, limit); + const hasZones = def.properties.some((p) => p.id === "azs"); + const availability = hasZones ? fleetAvailability(0.99999, 1, num(node, "azs", 2)) : MANAGED_AVAIL; + const note = limit != null && flow > limit ? `rejecting ${rate(flow - limit)}/s` : undefined; + return { + capacity, units: 1, cost: hourly + (flow * 3600 * perMillion) / 1e6, + serviceMs: SERVICE_MS[role] + (node.kind === "aws-api-gateway" ? 5 : 0), + availability, queueing: false, managed: true, note, + }; + } + + // Instance-based: a fleet of servers of one size. + const tier = tierOf(node); + const perUnit = tier.vcpu * (ROLE_RATE[role] ?? PER_VCPU[tier.family]); + const single = SINGLE_AVAIL[role] ?? 0.99; + + if (role === "database") { + const replicas = num(node, "replicas", 0); + const reads = num(node, "readRatio", 0.8); + const multiAz = num(node, "multiAz", 0) > 0; + // Every write goes to the primary; reads spread over the primary and its replicas. + // Inline writes are all writes: they are part of the flow but never reads. + const other = Math.max(0, flow - inlineWrites); + const util = Math.max(other * (1 - reads) + inlineWrites, (other * reads) / (1 + replicas)) / perUnit; + const parts = [replicas > 0 ? `${replicas} read replica${replicas === 1 ? "" : "s"}` : null, multiAz ? "Multi-AZ" : null].filter(Boolean); + return { + capacity: util > 0 ? flow / util : perUnit * (1 + replicas), units: 1 + replicas, + cost: tier.pricePerHour * ((multiAz ? 2 : 1) + replicas), serviceMs: SERVICE_MS.database, + availability: fleetAvailability(single, 1, multiAz ? 2 : 1), queueing: true, managed: false, + note: parts.length > 0 ? parts.join(", ") : undefined, + }; + } + + let units = node.kind === "load-balancer" ? num(node, "zones", 1) : num(node, "count", 1); + let note: string | undefined; + if (num(node, "autoscale", 0) > 0) { + const min = Math.max(1, num(node, "minCount", 1)); + const max = Math.max(min, num(node, "maxCount", 10)); + const target = Math.min(1, Math.max(0.05, num(node, "targetUtil", 0.6))); + units = Math.min(max, Math.max(min, Math.ceil(flow / (perUnit * target) - 1e-9))); + note = units === max && flow / (perUnit * units) > target ? `at max ${max}: raise the max or the size` : `autoscaled to ${units} (${min} to ${max})`; + } + + let cost = tier.pricePerHour * units; + let availabilityUnits = units; + if (node.kind === "aws-elasticache") { + const replicasPerShard = num(node, "replicasPerShard", 1); + cost = tier.pricePerHour * units * (1 + replicasPerShard); + availabilityUnits = 1 + replicasPerShard; + } + const zones = node.kind === "load-balancer" ? units : num(node, "azs", 1); + return { + capacity: perUnit * units, units, cost, serviceMs: SERVICE_MS[role], + availability: fleetAvailability(single, availabilityUnits, zones), queueing: true, managed: false, note, + }; +} + +// ---- the model ------------------------------------------------------------------- + +export function runTieredModel(board: Board, load: number, targets: Targets, options: ModelOptions = {}): ModelResult { + const byId = new Map(board.nodes.map((n) => [n.id, n])); + const reachable = reachableFrom(board); + const { children, parents } = liveLinks(board, reachable); + const order = topoOrder(reachable, children, parents); + const sync = synchronous(order, byId, children); + + // Load enters at the live clients and flows down the links. A node first applies + // its limit (rejecting the excess), then passes on what continues (CDN misses, + // traffic the firewall lets in). Parallel children with the same role share it; + // different roles are different services and each see the whole stream; a + // database or key-value store beside a cache only sees the cache misses. + const incoming = new Map(); + const inlineWrites = new Map(); + const edgeFlows: Record = {}; + const edgeParts: Record = {}; + const addPart = (key: string, label: string, rate: number) => { (edgeParts[key] ??= []).push({ label, rate }); }; + let dropped = 0; + let blocked = 0; + const clients = order.filter((id) => byId.get(id)!.kind === "client"); + for (const id of clients) incoming.set(id, load / clients.length); + for (const id of order) { + const node = byId.get(id)!; + const flowIn = incoming.get(id) ?? 0; + const limit = limitOf(node); + const served = limit != null ? Math.min(flowIn, limit) : flowIn; + dropped += flowIn - served; + const out = served * passOn(node); + if (roleOf(node.kind) === "firewall") blocked += served - out; + + const kids = (children.get(id) ?? []).map((k) => byId.get(k)!); + const cache = kids.find((n) => roleOf(n.kind) === "cache"); + const missRate = cache ? 1 - num(cache, "hitRate", 0) : 1; + // Read-through: a store that the cache itself links to is loaded by the cache on a miss, + // so the app server's own link to it carries no reads (it never counts twice). + const behindCache = new Set(cache ? children.get(cache.id) ?? [] : []); + const byRole = new Map(); + for (const kid of kids) { + if (behindCache.has(kid.id)) continue; + byRole.set(roleOf(kid.kind), [...(byRole.get(roleOf(kid.kind)) ?? []), kid.id]); + } + for (const [role, ids] of byRole) { + const stores = role === "database" || role === "nosql"; + // A worker batches its writes: one trip to the store carries `batchSize` events. + const batch = node.kind === "worker" && stores ? Math.max(1, num(node, "batchSize", 1)) : 1; + // A side job only some requests need (an alert, an index update) carries its share of the stream. + const part = role !== roleOf(node.kind) ? (options.shares?.[role] ?? 1) : 1; + const share = (stores ? (out * missRate) / batch : out) * part; + for (const k of ids) { + const key = `${id}>${k}`; + const rate = share / ids.length; + incoming.set(k, (incoming.get(k) ?? 0) + rate); + edgeFlows[key] = (edgeFlows[key] ?? 0) + rate; + if (part < 1) addPart(key, `${Math.round(part * 1000) / 10}% of requests send work here`, rate); + if (role === "cache") addPart(key, `reads, ${Math.round(num(byId.get(k)!, "hitRate", 0) * 100)}% answered by the cache`, rate); + else if (stores && node.kind === "worker" && batch > 1) addPart(key, `writes, ${batch} per trip`, rate); + else if (stores && cache) addPart(key, "cache misses", rate); + else if (stores && roleOf(node.kind) === "cache") addPart(key, "cache misses", rate); + } + } + if (options.inlineWrites && roleOf(node.kind) === "compute") { + // The click write goes to the store whether the app server reaches it directly or through its cache. + const direct = kids.filter((k) => roleOf(k.kind) === "database"); + const through = (cache ? children.get(cache.id) ?? [] : []).map((k) => byId.get(k)!).filter((k) => roleOf(k.kind) === "database"); + const stores = [...new Map([...direct, ...through].map((k) => [k.id, k])).values()]; + for (const store of stores) { + const writes = out / stores.length; + const key = direct.some((d) => d.id === store.id) ? `${id}>${store.id}` : `${cache!.id}>${store.id}`; + incoming.set(store.id, (incoming.get(store.id) ?? 0) + writes); + inlineWrites.set(store.id, (inlineWrites.get(store.id) ?? 0) + writes); + edgeFlows[key] = (edgeFlows[key] ?? 0) + writes; + addPart(key, direct.some((d) => d.id === store.id) ? "click writes" : "click writes, written directly", writes); + } + } + } + + const evaluations = new Map(); + const tiers: TierLoad[] = []; + let cost = 0; + for (const node of board.nodes) { + if (node.kind === "client") continue; + const down = isDown(node); + const onPath = reachable.has(node.id); + const flow = onPath ? incoming.get(node.id) ?? 0 : 0; + const ev = evaluate(node, flow, inlineWrites.get(node.id) ?? 0); + const capacity = down ? 0 : ev.capacity; + evaluations.set(node.id, ev); + cost += ev.cost; // placed hardware costs money whether or not it is serving + tiers.push({ + id: node.id, kind: node.kind, capacity, utilisation: capacity > 0 ? flow / capacity : 0, + down, reachable: onPath, units: ev.units, managed: ev.managed, note: ev.note, cost: ev.cost, waitMs: 0, + cacheStats: roleOf(node.kind) === "cache" && onPath + ? { hitRate: num(node, "hitRate", 0), reads: flow, hits: flow * num(node, "hitRate", 0), misses: flow * (1 - num(node, "hitRate", 0)) } + : undefined, + }); + } + const tierById = new Map(tiers.map((t) => [t.id, t])); + + // Work behind a queue is asynchronous: slow consumers build a backlog, not slow requests. + let backlog = 0; + for (const id of order) { + const node = byId.get(id)!; + if (!ASYNC_ROLES.has(roleOf(node.kind))) continue; + const consumers = (children.get(id) ?? []).reduce((sum, k) => sum + (tierById.get(k)?.capacity ?? 0), 0); + const behind = Math.max(0, (incoming.get(id) ?? 0) - consumers); + backlog += behind; + const tier = tierById.get(id); + // A consumer that is down is still linked: say so, instead of "no consumers linked". + const linkedButDown = board.edges.some((e) => e.from === id && isDown(byId.get(e.to)!)); + if (tier) tier.note = consumers === 0 ? (linkedButDown ? `consumers down, backlog grows ${rate(behind)}/s` : "no consumers linked") : behind > 0 ? `backlog grows ${rate(behind)}/s` : "consumers keeping up"; + } + + // Capacity, latency and availability of the synchronous request path. + let ceiling = Number.POSITIVE_INFINITY; + const roleAvail = new Map(); + const lat50 = new Map(); + const lat99 = new Map(); + for (const id of order) { + if (!sync.has(id)) continue; + const tier = tierById.get(id); + const ev = evaluations.get(id); + if (tier && ev) { + const flow = incoming.get(id) ?? 0; + if (flow > 0 && tier.capacity > 0) ceiling = Math.min(ceiling, (tier.capacity * load) / flow); + const role = roleOf(tier.kind); + roleAvail.set(role, [...(roleAvail.get(role) ?? []), ev.availability]); + } + const service = ev?.serviceMs ?? 0; + const u = ev?.queueing && tier ? Math.min(tier.utilisation, 0.985) : 0; + const before = (parents.get(id) ?? []).filter((p) => sync.has(p)); + lat50.set(id, service + Math.max(0, ...before.map((p) => lat50.get(p) ?? 0))); + lat99.set(id, service / (1 - u) + Math.max(0, ...before.map((p) => lat99.get(p) ?? 0))); + if (tier) tier.waitMs = service / (1 - u) - service; + } + const p50 = NETWORK_MS + Math.max(0, ...lat50.values()); + const p99 = NETWORK_MS + Math.max(0, ...lat99.values()); + + // Parallel components with the same role back each other up; the roles are in series. + let availability = 1; + let weakest: ModelResult["weakest"]; + for (const [role, parts] of roleAvail) { + const roleUp = 1 - parts.reduce((all, a) => all * (1 - a), 1); + availability *= roleUp; + if (!weakest || roleUp < weakest.availability) weakest = { role, availability: roleUp }; + } + + // A placed database that requests cannot reach means nothing is served. + let failure: string | undefined; + const stores = board.nodes.filter((n) => roleOf(n.kind) === "database" || roleOf(n.kind) === "nosql"); + if (stores.length > 0 && !stores.some((n) => reachable.has(n.id))) { + ceiling = 0; + availability = 0; + const blocker = board.nodes.find((n) => isDown(n) && board.edges.some((e) => e.from === n.id || e.to === n.id)); + failure = blocker + ? `${COMPONENT_CATALOG[blocker.kind].label} is down: requests through it fail.` + : "The database is not linked into the request path."; + } + + if (!Number.isFinite(ceiling)) ceiling = 0; + + const pass = { + rps: targets.rps == null ? true : ceiling >= targets.rps, + p99: targets.p99Ms == null ? true : p99 <= targets.p99Ms, + availability: targets.availability == null ? true : availability >= targets.availability, + budget: targets.budgetPerHour == null ? true : cost <= targets.budgetPerHour, + }; + + return { + capacityCeiling: Math.round(ceiling), + p50Ms: Math.round(p50), + p99Ms: Math.round(p99), + availability, + failure, + edgeFlows, + edgeParts, + dropped, + blocked, + backlog, + weakest, + costPerHour: cost, + tiers, + pass, + allPass: pass.rps && pass.p99 && pass.availability && pass.budget, + }; +} diff --git a/server/tests/unit/shared/games/sysdesign.test.ts b/server/tests/unit/shared/games/sysdesign.test.ts index 4f03acdc..dec67ee3 100644 --- a/server/tests/unit/shared/games/sysdesign.test.ts +++ b/server/tests/unit/shared/games/sysdesign.test.ts @@ -1,117 +1,347 @@ import { describe, expect, it } from "vitest"; import { seededRandom } from "../../../../src/shared/games/daily.js"; -import { sysdesignEngine, simulate, STEPS, SYSDESIGN_POOL, type SysdesignRound } from "../../../../src/shared/games/sysdesign/engine.js"; +import { MAX_EDGES, MAX_NODES, SYSDESIGN_POOL, sysdesignEngine, type SysdesignRound } from "../../../../src/shared/games/sysdesign/engine.js"; +import { COMPONENT_CATALOG, canConnect } from "../../../../src/shared/lab/engine/catalog.js"; +import { runChallenge } from "../../../../src/shared/lab/engine/challenge.js"; +import type { Board } from "../../../../src/shared/lab/engine/hld-types.js"; const engine = sysdesignEngine; -const verify = (round: SysdesignRound, changes: string[]) => engine.verify(round, { changes }); - -function subsets(ids: string[], max: number): string[][] { - const out: string[][] = [[]]; - const walk = (start: number, current: string[]) => { - if (current.length >= max) return; - for (let i = start; i < ids.length; i++) { - const next = [...current, ids[i]!]; - out.push(next); - walk(i + 1, next); - } - }; - walk(0, []); - return out; +const byId = (id: string) => SYSDESIGN_POOL.find((r) => r.id === id)!; +const clone = (value: T): T => JSON.parse(JSON.stringify(value)) as T; + +/** The reference board, edited. The lab sends every property of every part, so fill in the defaults. */ +function design(round: SysdesignRound, edit: (board: Board) => void = () => undefined, from: "solution" | "start" = "solution"): { board: Board } { + const board = clone(from === "solution" ? round.spec.solution!.board : round.spec.startingBoard!); + edit(board); + for (const node of board.nodes) { + const props: Record = {}; + for (const def of COMPONENT_CATALOG[node.kind].properties) props[def.id] = def.default; + node.props = { ...props, ...(node.props ?? {}) }; + } + return { board }; } +const node = (board: Board, id: string) => board.nodes.find((n) => n.id === id)!; describe("sysdesign pool", () => { - it("has at least four scenarios per difficulty and twelve in total, with unique ids", () => { + it("has six incidents, two for each difficulty, with unique ids, titles and slugs", () => { for (const difficulty of ["easy", "medium", "hard"] as const) { - expect(SYSDESIGN_POOL.filter((r) => r.difficulty === difficulty).length).toBeGreaterThanOrEqual(4); + expect(SYSDESIGN_POOL.filter((r) => r.difficulty === difficulty)).toHaveLength(2); } - expect(SYSDESIGN_POOL.length).toBeGreaterThanOrEqual(12); - expect(new Set(SYSDESIGN_POOL.map((r) => r.id)).size).toBe(SYSDESIGN_POOL.length); - expect(new Set(SYSDESIGN_POOL.map((r) => r.title)).size).toBe(SYSDESIGN_POOL.length); + expect(SYSDESIGN_POOL).toHaveLength(6); + expect(new Set(SYSDESIGN_POOL.map((r) => r.id)).size).toBe(6); + expect(new Set(SYSDESIGN_POOL.map((r) => r.title)).size).toBe(6); + expect(new Set(SYSDESIGN_POOL.map((r) => r.spec.slug)).size).toBe(6); }); - it("has well formed data and plain text (no long dashes)", () => { - for (const r of SYSDESIGN_POOL) { - expect(r.traffic).toHaveLength(STEPS); - expect(r.traffic.every((n) => Number.isFinite(n) && n >= 0)).toBe(true); - expect(new Set(r.changes.map((c) => c.id)).size).toBe(r.changes.length); - expect(r.hints.length).toBeGreaterThanOrEqual(3); - expect(r.maxChanges).toBeGreaterThanOrEqual(r.solution.length); - expect(r.maxChanges).toBeLessThanOrEqual(5); - expect(JSON.stringify(r)).not.toMatch(/[–—]/); + it("is plain data that survives JSON, in plain text with no long dashes", () => { + for (const round of SYSDESIGN_POOL) { + const copy = JSON.parse(JSON.stringify(round)) as SysdesignRound; + expect(copy).toEqual(round); + expect(JSON.stringify(round)).not.toMatch(/[\u2013\u2014]/); + expect(engine.verify(copy, design(round)).stars).toBe(3); } }); +}); - it("round data survives JSON, because rounds travel as JSON", () => { - for (const r of SYSDESIGN_POOL) { - const copy = JSON.parse(JSON.stringify(r)) as SysdesignRound; - expect(verify(copy, r.solution)).toEqual(verify(r, r.solution)); +describe.each(SYSDESIGN_POOL.map((r) => [r.id, r] as const))("incident %s", (_id, round) => { + const spec = round.spec; + const challenge = spec.challenge!; + + it("is a well formed AWS lab spec", () => { + expect(spec.family).toBe("hld"); + expect(spec.limits.length).toBeGreaterThan(20); + expect(spec.hints.length).toBeGreaterThanOrEqual(3); + expect(spec.levels).toHaveLength(1); + expect(spec.levels[0]!.load).toBe(challenge.peakLoad); + expect(challenge.checks.some((c) => c.kind === "functional")).toBe(true); + expect(challenge.checks.some((c) => c.kind === "non-functional")).toBe(true); + expect(new Set(challenge.checks.map((c) => c.id)).size).toBe(challenge.checks.length); + for (const kind of [...spec.startingBoard!.nodes, ...spec.solution!.board.nodes].map((n) => n.kind)) expect(spec.allowedComponents).toContain(kind); + // Parts are real AWS parts, except the generic worker, which has no AWS twin. + for (const kind of spec.allowedComponents) expect(["client", "worker"].includes(kind) || COMPONENT_CATALOG[kind].family === "aws").toBe(true); + for (const board of [spec.startingBoard!, spec.solution!.board]) { + const ids = new Set(board.nodes.map((n) => n.id)); + expect(ids.size).toBe(board.nodes.length); + for (const e of board.edges) { + expect(ids.has(e.from) && ids.has(e.to)).toBe(true); + expect(canConnect(board.nodes.find((n) => n.id === e.from)!.kind, board.nodes.find((n) => n.id === e.to)!.kind)).toBe(true); + } } }); -}); -describe.each(SYSDESIGN_POOL.map((r) => [r.id, r] as const))("scenario %s", (_id, round) => { - it("is really an incident: doing nothing fails", () => { - const result = verify(round, []); + it("tells the same numbers in its story as in its checks", () => { + const budget = challenge.checks.find((c) => c.id === "cost" && c.type === "metric"); + expect(budget && budget.type === "metric" ? spec.scenario : "").toContain(`$${(budget as { value: number }).value.toFixed(2)} an hour`); + expect(spec.scenario).toContain(`${challenge.peakLoad.toLocaleString("en-US")} requests a second`); + expect(spec.levels[0]!.targets.budgetPerHour).toBe((budget as { value: number }).value); + }); + + it("explains every part of its reference solution, naming real checks", () => { + const solution = spec.solution!; + const checkIds = new Set(challenge.checks.map((c) => c.id)); + for (const n of solution.board.nodes) { + if (n.kind === "client") continue; + const part = solution.parts[n.id]; + expect(part, `part ${n.id}`).toBeTruthy(); + expect(part!.why.length).toBeGreaterThan(30); + expect(part!.without.length).toBeGreaterThan(30); + for (const c of part!.checks) expect(checkIds.has(c)).toBe(true); + } + for (const id of Object.keys(solution.parts)) expect(solution.board.nodes.some((n) => n.id === id)).toBe(true); + }); + + it("is really an incident: the starting board fails, and says what is wrong", () => { + const start = design(round, () => undefined, "start"); + const report = runChallenge(spec, start.board, challenge.peakLoad); + expect(report.allPass).toBe(false); + expect(report.passed).toBeGreaterThanOrEqual(1); + const result = engine.verify(round, start); expect(result.passed).toBe(false); expect(result.stars).toBe(0); - expect(result.message.length).toBeGreaterThan(10); + expect(result.message).toMatch(/^Not yet: ".+" fails\. Found: .+\. Needed: .+\.$/); }); - it("is solved by its stated solution, with three stars", () => { - expect(round.solution.every((id) => round.changes.some((c) => c.id === id))).toBe(true); - const result = verify(round, round.solution); + it("is solved by its reference solution, which passes every check with three stars", () => { + const report = runChallenge(spec, design(round).board, challenge.peakLoad); + expect(report.checks.filter((c) => !c.pass)).toEqual([]); + const result = engine.verify(round, design(round)); expect(result.passed).toBe(true); expect(result.stars).toBe(3); - expect(result.message).toMatch(/goals met/i); - }); - - it("does not give three stars to a single change when the solution needs several", () => { - if (round.solution.length < 2) return; - for (const change of round.changes) expect(verify(round, [change.id]).stars).toBeLessThan(3); - }); - - it("has a real trap that does not fix the incident and makes something worse", () => { - expect(round.trap).toBeTruthy(); - expect(round.changes.some((c) => c.id === round.trap)).toBe(true); - expect(round.solution).not.toContain(round.trap); - expect(verify(round, [round.trap!]).passed).toBe(false); - const base = simulate(round, []); - const trapped = simulate(round, [round.trap!]); - const worse = trapped.costUsd > base.costUsd || trapped.p95Ms > base.p95Ms || trapped.availability < base.availability; - expect(worse).toBe(true); - // Using the trap never earns three stars, even with the solution. - if (round.solution.length < round.maxChanges) { - expect(verify(round, [...round.solution, round.trap!]).stars).toBeLessThan(3); + expect(result.message).toMatch(/^All \d+ checks pass at \$\d+\.\d\d an hour/); + }); + + it("does not solve it by doing nothing, or with an empty board", () => { + expect(engine.verify(round, { board: { nodes: [], edges: [] } } as never).passed).toBe(false); + expect(engine.verify(round, { board: { nodes: [{ id: "client", kind: "client", x: 0, y: 0, props: {} }], edges: [] } }).passed).toBe(false); + }); + + it("gives the same answer every time", () => { + expect(engine.verify(round, design(round))).toEqual(engine.verify(round, design(round))); + }); +}); + +describe("the reasons are true", () => { + it("easy A: two servers cannot lose one, and the bill needs both a smaller database and fewer servers", () => { + const r = byId("sd-bill-tripled"); + expect(engine.verify(r, design(r, (b) => (node(b, "web").props!.count = 2))).message).toMatch(/one server dies/); + expect(engine.verify(r, design(r, (b) => (node(b, "db").props!.multiAz = 0))).message).toMatch(/availability/i); + }); + + it("easy B: CloudFront fixes the speed but breaks the budget", () => { + const r = byId("sd-launch-slow"); + const cdn = design(r, (b) => { + b.nodes.push({ id: "cdn", kind: "aws-cloudfront", x: 0, y: 0 }); + b.edges = [{ from: "client", to: "cdn" }, { from: "cdn", to: "alb" }, { from: "alb", to: "web" }, { from: "web", to: "db" }]; + b.nodes = b.nodes.filter((n) => n.id !== "cache"); + }); + const result = engine.verify(r, cdn); + expect(result.passed).toBe(false); + expect(result.message).toMatch(/Cost per hour/); + }); + + it("medium A: a cache alone is not enough, the database needs read replicas for when it is flushed", () => { + const r = byId("sd-flash-sale"); + const result = engine.verify(r, design(r, (b) => (node(b, "db").props!.replicas = 0))); + expect(result.passed).toBe(false); + expect(result.message).toMatch(/cache is flushed/i); + }); + + it("medium B: every layer needs two zones", () => { + const r = byId("sd-lost-zone"); + for (const edit of [ + (b: Board) => (node(b, "web").props!.azs = 1), + (b: Board) => (node(b, "cache").props = { ...node(b, "cache").props, azs: 1, replicasPerShard: 0 }), + (b: Board) => (node(b, "db").props!.multiAz = 0), + ]) { + const result = engine.verify(r, design(r, edit)); + expect(result.passed).toBe(false); + expect(result.message).toMatch(/availability/i); + } + }); + + it("hard A: the old oversized fleet blows the budget, and two replicas are not enough", () => { + const r = byId("sd-peak-day"); + const fleet = engine.verify(r, design(r, (b) => Object.assign(node(b, "web").props!, { size: "c5.2xlarge", count: 6 }))); + expect(fleet.passed).toBe(false); + expect(fleet.message).toMatch(/Cost per hour/); + const replicas = engine.verify(r, design(r, (b) => (node(b, "db").props!.replicas = 2))); + expect(replicas.passed).toBe(false); + expect(replicas.message).toMatch(/zone is down/); + }); + + it("hard B: one worker cannot clear the pile in time, and no queue loses orders", () => { + const r = byId("sd-orders-pile"); + const slowWorker = engine.verify(r, design(r, (b) => (node(b, "w").props!.count = 1))); + expect(slowWorker.passed).toBe(false); + expect(slowWorker.message).toMatch(/No order is lost/); + const noQueue = engine.verify(r, design(r, (b) => { + b.nodes = b.nodes.filter((n) => n.id !== "q" && n.id !== "w"); + b.edges = b.edges.filter((e) => ["client", "alb", "web", "db"].includes(e.from) && ["alb", "web", "db"].includes(e.to)); + })); + expect(noQueue.passed).toBe(false); + expect(noQueue.message).toMatch(/order is saved/i); + }); +}); + +describe("stars", () => { + it("gives fewer stars to a design that costs more than the reference, and one star for a heavy one", () => { + const bill = byId("sd-bill-tripled"); + const heavier = engine.verify(bill, design(bill, (b) => (node(b, "web").props!.size = "m5.xlarge"))); + expect(heavier.passed).toBe(true); + expect(heavier.stars).toBe(2); + expect(heavier.message).toMatch(/For 3 stars/); + + const launch = byId("sd-launch-slow"); + const heavy = engine.verify(launch, design(launch, (b) => (node(b, "db").props!.size = "db.r5.2xlarge"))); + expect(heavy.passed).toBe(true); + expect(heavy.stars).toBe(1); + expect(heavy.message).toMatch(/For 2 stars/); + }); + + it("gives three stars to a cheaper design that still passes, but not to one with extra parts", () => { + const bill = byId("sd-bill-tripled"); + const cheaper = engine.verify(bill, design(bill, (b) => (node(b, "db").props!.size = "db.t3.medium"))); + expect(cheaper.stars).toBe(3); + const bloated = engine.verify(bill, design(bill, (b) => { + b.nodes.push({ id: "c1", kind: "aws-elasticache", x: 3, y: 3, props: { size: "cache.t3.small", replicasPerShard: 0 } }); + b.edges.push({ from: "web", to: "c1" }); + b.nodes.push({ id: "c2", kind: "aws-elasticache", x: 4, y: 3, props: { size: "cache.t3.small", replicasPerShard: 0 } }); + b.edges.push({ from: "web", to: "c2" }); + })); + expect(bloated.passed).toBe(true); + expect(bloated.stars).toBeLessThan(3); + }); +}); + +describe("a design that cheats is rejected", () => { + const round = byId("sd-flash-sale"); + + it("rejects typed-in miracle settings", () => { + const hits = engine.verify(round, design(round, (b) => (node(b, "cache").props!.hitRate = 1))); + expect(hits.passed).toBe(false); + expect(hits.message).toMatch(/hit rate/i); + const reads = engine.verify(round, design(round, (b) => { + node(b, "db").props!.readRatio = 1; + node(b, "db").props!.replicas = 0; + })); + expect(reads.passed).toBe(false); + expect(reads.message).toMatch(/traffic/i); + }); + + it("rejects parts the round does not offer", () => { + // CloudFront is a real part in other rounds, but not in this one. + const cdn = engine.verify(round, design(round, (b) => { + b.nodes.push({ id: "cdn", kind: "aws-cloudfront", x: 0, y: 0 }); + b.edges.push({ from: "client", to: "cdn" }); + })); + expect(cdn.passed).toBe(false); + expect(cdn.message).toMatch(/not one of the parts/); + // DynamoDB and Lambda are not in any incident, so the board is not even read. + for (const kind of ["aws-dynamodb", "aws-lambda", "k8s-deployment", "linux-nginx"]) { + const result = engine.verify(round, design(round, (b) => b.nodes.push({ id: "x", kind: kind as never, x: 0, y: 0 }))); + expect(result.passed).toBe(false); } }); - it("explains which goal failed in one plain sentence", () => { - const result = verify(round, []); - expect(result.message).toMatch(/^Goal missed: .+ is .+, the goal is .+\.$/); + it("rejects too many parts, too many links and too many of one kind", () => { + const many = design(round, (b) => { + for (let i = 0; i < MAX_NODES; i++) b.nodes.push({ id: `extra${i}`, kind: "aws-ec2-asg", x: 0, y: 0 }); + }); + expect(engine.parseSubmission(many)).toBeNull(); + expect(engine.verify(round, many).passed).toBe(false); + const three = design(round, (b) => { + for (let i = 0; i < 4; i++) { + b.nodes.push({ id: `w${i}`, kind: "aws-ec2-asg", x: 0, y: 0, props: { size: "c5.large", count: 20 } }); + b.edges.push({ from: "alb", to: `w${i}` }); + } + }); + expect(engine.verify(round, three).passed).toBe(false); + const links = design(round, (b) => { + for (let i = 0; i < MAX_EDGES + 1; i++) b.edges.push({ from: "client", to: "alb" }); + }); + expect(engine.parseSubmission(links)).toBeNull(); }); - it("gives finite numbers and never throws for every allowed set of changes", () => { - for (const ids of subsets(round.changes.map((c) => c.id), round.maxChanges)) { - const sim = simulate(round, ids); - expect(sim.steps).toHaveLength(STEPS); - for (const n of [sim.p95Ms, sim.availability, sim.costUsd, sim.peakAppUtil, sim.peakDbUtil]) expect(Number.isFinite(n)).toBe(true); - expect(sim.availability).toBeGreaterThanOrEqual(0); - expect(sim.availability).toBeLessThanOrEqual(100); - expect(sim.steps.at(-1)!.costToDate).toBe(sim.costUsd); - const result = verify(round, ids); - if (!result.passed) expect(result.stars).toBe(0); + it("rejects a design with two clients, and a design with no client", () => { + const two = design(round, (b) => b.nodes.push({ id: "client2", kind: "client", x: 0, y: 0 })); + expect(engine.verify(round, two).passed).toBe(false); + const none = design(round, (b) => { + b.nodes = b.nodes.filter((n) => n.kind !== "client"); + b.edges = b.edges.filter((e) => e.from !== "client"); + }); + expect(engine.verify(round, none).passed).toBe(false); + }); + + it("does not let a huge fleet buy its way out: the budget check still fails", () => { + const huge = engine.verify(round, design(round, (b) => Object.assign(node(b, "web").props!, { size: "c5.2xlarge", count: 200 }))); + expect(huge.passed).toBe(false); + expect(huge.message).toMatch(/Cost per hour/); + }); +}); + +describe("parseSubmission", () => { + const round = byId("sd-lost-zone"); + + it("accepts every reference and starting board, and keeps the settings", () => { + for (const r of SYSDESIGN_POOL) { + for (const from of ["solution", "start"] as const) { + const parsed = engine.parseSubmission(design(r, () => undefined, from)); + expect(parsed, `${r.id} ${from}`).not.toBeNull(); + expect(parsed!.board.nodes.length).toBe((from === "solution" ? r.spec.solution!.board : r.spec.startingBoard!).nodes.length); + } } }); - it("is deterministic and does not depend on a previous run", () => { - expect(simulate(round, round.solution)).toEqual(simulate(round, round.solution)); + it("fills in missing settings with the catalog defaults, drops link handles, and does not change the input", () => { + const input = { board: { nodes: [{ id: "client", kind: "client" }, { id: "alb", kind: "aws-alb" }], edges: [{ from: "client", to: "alb", via: ["b", "t"] }] } }; + const before = JSON.stringify(input); + const parsed = engine.parseSubmission(input)!; + expect(parsed.board.nodes[1]!.props).toEqual({ azs: 2, crossZone: 1 }); + expect(parsed.board.edges).toEqual([{ from: "client", to: "alb" }]); + expect(JSON.stringify(input)).toBe(before); }); - it("rejects too many changes, repeated changes and unknown changes", () => { - const ids = round.changes.map((c) => c.id); - expect(verify(round, ids.slice(0, round.maxChanges + 1)).passed).toBe(false); - expect(verify(round, [...round.solution, round.solution[0]!]).passed).toBe(false); - expect(verify(round, ["not-a-real-change"]).passed).toBe(false); + it("rejects junk", () => { + const ok = design(round).board; + const withNode = (patch: Record) => ({ board: { ...clone(ok), nodes: [{ ...ok.nodes[1]!, ...patch }, ...ok.nodes.slice(2), ok.nodes[0]!] } }); + const junk: unknown[] = [ + null, undefined, 0, 1, "board", true, [], {}, { board: null }, { board: [] }, { board: {} }, { board: { nodes: [], edges: [] } }, + { board: { nodes: "x", edges: [] } }, { board: { nodes: [], edges: "x" } }, { ...design(round), extra: 1 }, { board: { ...ok, extra: 1 } }, + { board: { nodes: [{ id: "a", kind: "client" }], edges: [{ from: "a", to: "a" }] } }, + { board: { nodes: [{ id: "a", kind: "client" }], edges: [{ from: "a", to: "zzz" }] } }, + { board: { nodes: [{ id: "a", kind: "client" }, { id: "a", kind: "aws-alb" }], edges: [] } }, + { board: { nodes: [{ id: "a", kind: "client" }, { id: "b", kind: "aws-rds" }], edges: [{ from: "a", to: "b" }] } }, + { board: { nodes: [{ id: "a", kind: "client" }, { id: "b", kind: "aws-alb" }], edges: [{ from: "a", to: "b" }, { from: "a", to: "b" }] } }, + withNode({ id: "" }), withNode({ id: "x".repeat(33) }), withNode({ id: "a b" }), withNode({ id: 5 }), withNode({ kind: "nope" }), withNode({ kind: 7 }), + withNode({ x: "1" }), withNode({ x: Number.NaN }), withNode({ y: Infinity }), withNode({ x: 1e9 }), withNode({ extra: true }), withNode({ props: [] }), withNode({ props: "x" }), + withNode({ props: { down: 1 } }), withNode({ props: { notAProp: 1 } }), + ]; + for (const value of junk) expect(engine.parseSubmission(value), JSON.stringify(value)).toBeNull(); + }); + + it("rejects settings outside what the catalog allows", () => { + const bad = (id: string, props: Record) => { + const sub = design(round); + Object.assign(node(sub.board, id).props!, props); + return engine.parseSubmission(sub); + }; + expect(bad("web", { count: 0 })).toBeNull(); + expect(bad("web", { count: 201 })).toBeNull(); + expect(bad("web", { count: 2.5 })).toBeNull(); + expect(bad("web", { count: "3" })).toBeNull(); + expect(bad("web", { count: Number.NaN })).toBeNull(); + expect(bad("web", { size: "m5.huge" })).toBeNull(); + expect(bad("web", { size: 3 })).toBeNull(); + expect(bad("web", { size: "db.r5.large" })).toBeNull(); + expect(bad("web", { azs: 4 })).toBeNull(); + expect(bad("web", { autoscale: 2 })).toBeNull(); + expect(bad("web", { targetUtil: 1.5 })).toBeNull(); + expect(bad("db", { replicas: 16 })).toBeNull(); + expect(bad("db", { replicas: -1 })).toBeNull(); + expect(bad("db", { multiAz: true })).toBeNull(); + expect(bad("db", { engine: "Oracle" })).toBeNull(); + expect(bad("cache", { hitRate: -0.1 })).toBeNull(); + expect(bad("web", { count: 4 })).not.toBeNull(); }); }); @@ -124,63 +354,37 @@ describe("daily rotation", () => { it("changes from day to day and walks the whole pool", () => { const seen = new Set(); - let sameAsPrevious = 0; let previous = ""; for (let d = 1; d <= 8; d++) { const day = `2026-12-0${d}`; const ids = engine.roundsFor(day).map((r) => r.id).join(","); - if (ids === previous) sameAsPrevious++; + expect(ids).not.toBe(previous); previous = ids; engine.roundsFor(day).forEach((r) => seen.add(r.id)); } - expect(sameAsPrevious).toBe(0); expect(seen.size).toBe(SYSDESIGN_POOL.length); }); }); -describe("parseSubmission", () => { - it("accepts a list of unique change ids", () => { - expect(engine.parseSubmission({ changes: [] })).toEqual({ changes: [] }); - expect(engine.parseSubmission({ changes: ["a", "b"] })).toEqual({ changes: ["a", "b"] }); - }); - - it("rejects junk", () => { - const junk: unknown[] = [ - null, undefined, 0, 1, "changes", true, [], ["a"], {}, { changes: "a" }, { changes: null }, { changes: [1] }, - { changes: [null] }, { changes: [""] }, { changes: ["a", "a"] }, { changes: ["x".repeat(65)] }, { changes: Array.from({ length: 9 }, (_, i) => `c${i}`) }, - { changes: ["a"], extra: 1 }, { done: true }, { changes: { 0: "a", length: 1 } }, { changes: [["a"]] }, { changes: [{ id: "a" }] }, - ]; - for (const value of junk) expect(engine.parseSubmission(value)).toBeNull(); - }); -}); - describe("verify never throws", () => { - it("copes with random and broken parsed input", () => { + it("copes with random and broken input", () => { const rand = seededRandom(7); + const kinds = ["client", "aws-alb", "aws-ec2-asg", "aws-rds", "aws-elasticache", "aws-sqs", "worker", "aws-cloudfront", "nope", 3, null]; for (const round of SYSDESIGN_POOL) { - const ids = [...round.changes.map((c) => c.id), "zzz", "", "__proto__", "constructor"]; for (let i = 0; i < 40; i++) { - const count = Math.floor(rand() * 7); - const changes = Array.from({ length: count }, () => ids[Math.floor(rand() * ids.length)]!); - expect(() => engine.verify(round, { changes })).not.toThrow(); + const count = Math.floor(rand() * 8); + const nodes = Array.from({ length: count }, (_, n) => ({ id: `n${n}`, kind: kinds[Math.floor(rand() * kinds.length)], x: 0, y: 0 })); + const edges = Array.from({ length: Math.floor(rand() * 8) }, () => ({ from: `n${Math.floor(rand() * 8)}`, to: `n${Math.floor(rand() * 8)}` })); + expect(() => engine.verify(round, { board: { nodes, edges } } as never)).not.toThrow(); + const result = engine.verify(round, { board: { nodes, edges } } as never); + if (!result.passed) expect(result.stars).toBe(0); + } + for (const junk of [null, undefined, 0, "x", [], {}, { board: null }, { board: { nodes: null, edges: null } }, { board: { nodes: [null], edges: [] } }]) { + expect(() => engine.verify(round, junk as never)).not.toThrow(); + expect(engine.verify(round, junk as never).passed).toBe(false); } - expect(() => engine.verify(round, { changes: [1, null, {}] as unknown as string[] })).not.toThrow(); - expect(() => engine.verify(round, {} as never)).not.toThrow(); - expect(() => engine.verify(round, null as never)).not.toThrow(); + expect(() => engine.verify({ ...round, spec: { ...round.spec, challenge: undefined } }, design(round))).not.toThrow(); + expect(() => engine.verify({ ...round, spec: null } as never, design(round))).not.toThrow(); } }); }); - -describe("stars", () => { - it("gives one star for meeting the goals only, and more for the tighter target and fewer changes", () => { - const logs = SYSDESIGN_POOL.find((r) => r.id === "sd-logs-forever")!; - expect(verify(logs, ["glacier-lifecycle"]).stars).toBe(1); - expect(verify(logs, ["glacier-lifecycle", "compress-logs"]).stars).toBe(3); - const bill = SYSDESIGN_POOL.find((r) => r.id === "sd-bill-tripled")!; - expect(verify(bill, ["rightsize-app", "rightsize-db"]).stars).toBe(1); - expect(verify(bill, bill.solution).stars).toBe(3); - const outage = SYSDESIGN_POOL.find((r) => r.id === "sd-az-outage")!; - // The autoscaling group is extra, so it earns two stars (a fourth change), not three. - expect(verify(outage, [...outage.solution, "autoscaling"]).stars).toBeLessThan(3); - }); -});