knaxuslearn · build · ship

Roadmaps / JavaScript / The milestone project

Read first

The milestone project

Scenario. A chat app lets users paste links. The link preview service fetches each page and returns its title, description and image, cached for 10 minutes. Peak load is 200 requests a second with 20% cache misses, so about 40 outbound fetches a second. Some hosts are slow, some are hostile. Targets: p99 under 400 ms for cache hits; at most 64 outbound requests in flight and 4 per host; at most 256 MB of memory (RSS, the memory the operating system has given the process); event-loop delay p99 at or under 50 ms; no request to a private address. The service is assumed to run on one small instance (1 vCPU, 512 MB), so every limit has a reason in the numbers.

PhaseCheckpointDone when
1Fetch corefetchPreview(url, { signal }) runs with a global limit of 64, a per-host limit of 4 and a 5 s timeout from AbortSignal.timeout. Against a local fake server with 500 URLs on 50 hosts, where 10% of hosts hang, a counter in the test records that in-flight requests never pass the limits. A client abort closes the socket within 100 ms (the fake server sees the close). Event-loop delay p99 from monitorEventLoopDelay stays at or under 50 ms. A seeded 200 ms synchronous loop inside a promise callback fails the build through the delay check.
2Streams and workersThe body is read as a stream with a 2 MB cap and a limit of 3 redirects. An endless response from the fake server is cut at 2 MB, and 100 of them grow RSS by under 50 MB. Parsing runs in a pool of 2 worker threads (fresher: on the main thread behind the same interface), and at 40 requests a second event-loop delay p99 stays at or under 50 ms. The package loads from an ES module, a CommonJS file and a bundler in a three-way test matrix. A redirect loop and a gzip bomb (a small file that expands past the cap) are both rejected.
3Browser and memoryA page lists 5,000 previews. The slowest interaction (typing in a filter box) measures 200 ms or less in DevTools with 4x CPU throttling, across 20 runs. A seeded leak (a listener added on every render) is found by comparing two heap snapshots and then fixed. The server runs a 1-hour soak at 40 fetches a second, and its RSS after warm-up stays within 10% of its 10-minute value.
4Hardened and shippedTwelve seeded attacks are blocked or neutralised: loopback, a private range, the link-local cloud metadata address, a hostname that resolves to a private address, a redirect to a private address, a resolver stub that changes its answer between check and connect (DNS rebinding), credentials in the URL, a non-HTTP scheme, a 10 MB header, __proto__ in a JSON option, a regular expression that backtracks without end, and a script tag in a title. npm ci installs from the lockfile, npm audit signatures passes and CI runs the tests. A 10-minute run at 200 requests a second meets every target. On SIGTERM the service drains in-flight work within 10 s.
WWork version (Staff and Principal)On a real service: measure a baseline (event-loop delay and p99), make one change that removes a stall, leak or unsafe fetch, and measure again. Pass: a target agreed in writing beforehand is met, or the worst stall falls at least 5 times on the same load. The ADR is signed by a named stakeholder, scored by someone other than you, and a recheck is booked three months later. Level 4 also needs evidence that another team used your checklist and recorded a finding with it. Timebox: six weeks alongside Phases 3 and 4.

Evidence to hand in. A repository whose README opens with the problem and the numbers above; one ADR (architecture decision record) per decision, each naming a rejected option; raw measurement output and a test report; a one-page design doc; a diagram of the request path. Skeletons: Checkpoint 1 is one table (run, URLs, hung hosts, max in flight, abort time, event-loop delay p99) plus the failing seeded-stall run. Checkpoint 3 is two heap snapshot summaries (retained size and retainer path) and the throttled interaction timings. Checkpoint 4 is a 12-row attack table (attack, expected result, actual result, log line).

LevelWhat you build and hand in
FresherCore scope: single process, constant limits, the four checkpoints, ADRs 1 to 4.
SeniorAdds the worker pool, a load test in CI, per-host fairness and a seeded-fault suite, plus ADRs 5 and 6.
StaffAdds written decisions with numbers: service level objective, alert thresholds, runbook, cost of the instance, and a Node upgrade policy (Week 16).
PrincipalAdds a safe-fetch design for a company with many services, a review checklist other teams reuse, and a measured outcome from the work version.

Do this at work. A solo lab is not promotion evidence. Take a real Node service that has stalled, leaked memory or fetches user-supplied URLs, and run Checkpoint W on it. Start with a baseline: event-loop delay, p99 and RSS over a week. Make one change. Measure again. A promotion committee accepts the real decision and who made it, the named stakeholder who relied on it, before and after numbers, and a result checked again three months later.

Solo version. With no real service, use a named open-source Node project that fetches or proxies requests: read its code, write a one-page review of how it bounds concurrency and size, and ask a peer or mentor to check your measurements. Replay a recorded request file instead of live traffic.

Laptop scale. The whole project runs on a laptop against fake local servers. Nothing needs cloud spend. If you want a real deployment, one small instance is optional and its cost goes in the memo.

Honest sizing. A first bounded fetcher takes an experienced engineer a day or two, but the checkpoint adds cancellation tests, a delay monitor and a seeded fault. Phase 2 has the heaviest load for a fresher (streams and workers together), so use the extra fresher week there.

Worked reference: what a "3 Proven" hand-in for Checkpoint 1 looks like

The numbers are illustrative. The shape (without limits, in-flight work and delay grow with the hung hosts) is what you should expect. Hand in your own measurements.

500 URLs, 50 hosts, 10% hungUnbounded Promise.allGlobal limit only (64)Global 64 and per host 4
Max in flight5006464
Max in flight to one host1064 (one hung host fills the pool)4
Healthy URLs finished in 10 s410 of 450190 of 450450 of 450
Event-loop delay p9995 ms22 ms21 ms

ADR-2 excerpt: Limit per host and globally, with a queue per host. The size comes from Little's law (requests in flight equal arrival rate times time in system). At 40 fetches a second, 5% hung hosts holding a socket for the full 5 s timeout give 40 x 0.05 x 5 = 10 in flight, and healthy fetches at about 0.2 s give 8. Normal load is about 18 in flight, so 64 leaves 3.5 times headroom. A global limit alone lets one hung host take all 64 slots, so the per-host limit is 4. Rejected: a library-provided pool, because we need the queue per host and a counter we can assert in tests. Revisit if the 5 s timeout or the 20% miss rate changes.