ticket-monitoring/docs/design-notes.md

Design notes

Why this is built the way it is, and what broke along the way. Useful if you're forking it, or writing something similar against a different site.

Two sites are supported. Each lives in src/providers/ and exposes the same two functions, check() and extract(), returning sessions in one normalized shape. Everything above that layer, including the alert state machine, has no idea which site a session came from.

District: the API

District's movie pages are server-rendered Next.js, but showtimes load client-side from:

GET /gw/consumer/movies/v5/movie
      ?version=3&site_id=1&channel=mweb&child_site_id=1&platform=district
      &movieCode=<frmtid>&city_key=<city>&content_id=<id>
      &date=YYYY-MM-DD&latitude=<lat>&longitude=<lng>&cinemaOrderLogic=3

Findings that shaped the design:

• x-guest-token is generated client-side. It looks like a session token but isn't server-issued — the browser builds <epoch_ms>_<18 digits>_<11 random chars> per request, and any value of that shape is accepted. No login, no cookies.
• Latitude and longitude are mandatory. Without them the API returns 400 Mandatory search params are missing, even though results are city-wide.
• 204 vs 200 is the signal. A date that isn't open for booking returns 204 No Content; an open date returns the full session list. That status flip is the entire trigger, which keeps the check to a single cheap request.
• showTime is UTC without a zone suffix. Local time is applied via TZ_OFFSET_MINUTES.
• meta.showDates only exists in a 200 body. Because the target date returns an empty 204 while closed, the daily heartbeat makes one extra call for today purely to report how far ahead bookings currently run. That probe is best-effort and never counts as a failure.

BookMyShow: the API

GET /api/movies-data/v5/showtimes-by-event/primary-dynamic
      ?etCodes=<ET code>&dateCode=YYYYMMDD&regionCode=AHD
      &isDesktop=true&xLocationShared=false&memberId=&lsId=&subCode=
      &appCode=WEB&refEventCode=<ET code>[&language=hindi]

Sent with x-region-code, x-region-slug, x-latitude, x-longitude, x-app-code: WEB and an x-bms-id that, like District's guest token, the web client makes up locally.

• Cloudflare blocks on TLS fingerprint, not IP or headers. curl and Node's fetch both get 403 with a byte-perfect copy of the browser's headers, and no cf_clearance cookie is involved, so there is nothing to copy across. A proxy does not help either, since the block happens during the TLS handshake. impit performs the request with a real Chrome fingerprint and returns 200. It ships prebuilt binaries for linux x64 and arm64 in both gnu and musl flavours, which is what keeps the Alpine image and the arm64 build working.
• There is no 204. A date that is not on sale answers 200 with a short body containing only header, additionalData and addOnWidgets. The tell is that data.showtimeWidgets is absent, so "closed" is a property of the payload rather than the status code.
• A past or invalid date returns 400, which counts as a failure rather than "closed". That is deliberate: it means something is wrong with the configuration, and you should hear about it.
• Sessions are buried in generic UI widgets. Venue cards sit several layers down inside showtimeWidgets, so the parser walks the tree looking for type: "venue-card" instead of indexing through fixed positions, which would break the moment BMS reorders its layout.
• Seat detail lives in a bottom sheet. Each showtime carries a customGestureCTA describing the panel shown on double-tap, and that is the only place per-tier prices appear. BMS reports availability as words (AVAILABLE, FILLING FAST, ALMOST FULL) and never as exact counts, unlike District, so the normalized session leaves avail and total null and alert lines omit the seat figures for this site.
• Times are already local, so unlike District's UTC timestamps they are passed through as-is.

Alert state machine

decideProvider() in src/monitor.js is pure: state in, { baseState, alerts } out. That makes every edge case testable without network or clock mocking, and it's where the interesting rules live.

• Publish before persist. Each alert carries its own statePatch, merged only after that alert's push succeeds. A failed notification retries on the next tick instead of being silently recorded as delivered.
• Dedupe by session id, not a boolean. Shows added after the first alert still notify you.
• Dedupe does not outlive the listing. Cinemas publish early, pull the shows and re-list them, often under the same session ids, and this really happened with the Endgame release. A show missing for three consecutive successful checks is forgotten, so its return alerts again. Three rather than one, so a single flaky response can't cause a duplicate max-priority push, and failed checks don't count, since an outage says nothing about whether a show exists. If the whole date goes dark after opening, a separate notice says the shows were withdrawn. The re-arm itself lives in the base state, not in that notice's patch, so it happens even if the notice fails to deliver.
• dateOpenAlerted rides an alert patch, never the base state. Otherwise a failed push followed by sessions disappearing could swallow the only notification you'd ever get.
• Open-but-empty counts as closed, defending against a 200 with no sessions.
• Failures are capped at the threshold, so a long outage stops writing state entirely.
• State is written only when it actually changed. Originally this ran on Cloudflare KV with a 1,000 writes/day free limit against 1,440 daily ticks, which forced the discipline; it's still the right behaviour on a filesystem.
• State is namespaced per site. Each provider gets its own dedupe map, failure counter and BROKEN flag under state.providers.<key>, so the same session id can alert once per site and a site going down never marks the other as broken. Retirement and the daily heartbeat are the only tick-level decisions, and they live in decideGlobal().

The guiding rule throughout: degrade toward duplicate notifications, never toward silence. Every failure path, whether it is unreadable state, a failed push or a failed write, errs that way.

What broke in production

Both failures were about where the traffic came from, not the code.

1. Akamai started returning 403 to the cloud host after ~2 days. The first version ran as a Cloudflare Worker on a 1-minute cron. It worked, alerted correctly in a fire drill, then hard- blocked — while the same requests from a home connection kept working. Datacenter IP ranges get flagged; residential ones didn't. The monitor's own BROKEN alert is what surfaced this, which is the strongest argument for having it.
2. ntfy.sh returned 429 to that same class of IP. Push delivery failed from cloud egress even with an account token, because rate limits are per visitor IP and shared cloud IPs are already spent. Self-hosting ntfy fixed it immediately.

The fix for both: run it from a residential connection, or route only the site checks through a SOCKS5 proxy (PROXY_URL) and use your own ntfy server. Notifications deliberately stay direct so the alerting path has no dependency on the proxy.

Cloudflare Workers cannot do this. fetch() there has no proxy option, and the raw-TCP escape hatch (connect() from cloudflare:sockets) can't help: startTls() validates the certificate against the host you dialed, with no SNI override, so you can't form a TLS session for a third-party origin through a proxy. That's why the project ended up as a plain Node process in Docker rather than a serverless function.