Source: src/wxd/web/spec.md

Spec

Working list for wxd. This page is src/wxd/web/spec.md. Edit that file and refresh. The boxes are disabled. They are not an editor.

Run locally, markdown, the stylesheet, and the page script are read on each request. A change to Python still needs a process restart. On mobs.ws the board, Cities, Reference, and Spec are a static build made at deploy time and served by the proxy, so a page change does not restart the feed.

Version 1 collects the stations on the Cities page from the US government observation feeds, NOAA model grids, and the public D-ATIS mirror, on one WebSocket. The product is that socket. A caller subscribes and the decoded reports arrive. Polling the public sources, decoding them, and keeping the latest value are this process's job. metar.ws (reference)/ is background on another product. This file is the list we keep current.

Built

• NOAA Aviation Weather Center METAR cache, polled every 1.5 seconds from :15 to :00 past each minute and every 5 seconds otherwise. The stations on the Cities page. Raw report kept. expected_time is the next routine observation minute. A report first decoded after the opening fill carries ingest_age_s (receipt minus observation time, whole seconds) and poll_lag_ms when the cache time is present. The fill itself does not. A correction keeps those first values.
• NCEP MADIS HF-METAR, classic NetCDF, on hf.<icao>. The same station list. No invented raw text.
• NWS Climatological Report (Daily), polled about every 45 seconds from api.weather.gov, on cli.<icao>. Whole degrees Fahrenheit, the climate date printed on the report, and the raw product text. The cached value is the newest issuance. When that is a preliminary, the newest full-day report is kept beside it, including across a restart. Love Field (KDAL) has no CLI location in that API. Downtown Los Angeles (KCQT) is not collected.
• One WebSocket at /v1/ws. Subscribe by station. Cached replay, then live diffs.
• Access tokens, approved 29 October 2026. The socket, GET /v1/latest, GET /v1/latency, and GET /v1/history need a token: Authorization: Bearer, ?token=, or the board's cookie. A bad token gets HTTP 401 before the upgrade, a token without the scope 403. The token file lives outside the repo and holds SHA-256 digests with a label. The log names the label, never the token. The pages, GET /v1/status, and GET /v1/stations stay public. No accounts.
• GET /v1/latest returns the current value of every channel as JSON, in the publication shape plus age_s. feed and station filter it. GET /v1/latency gives p50 and p90 per station and feed over 24 hours.
• The board asks for a token, keeps it in the browser, and shows no data without one.
• Per-token limits, approved 29 October 2026: 5 sockets at once, 60 GET /v1/latest and 30 GET /v1/history per minute. Over a limit is HTTP 429 with Retry-After. GET /v1/status is not limited.
• Releases, approved 29 October 2026. The server runs a tagged commit from its own release directory, keeps the last five, and rolls back with one command. GET /v1/status reports that release as version.
• Static pages, approved 29 October 2026. The board, Cities, Reference, Spec, the stylesheet, and the page script are built to files (python -m wxd.webbuild) and served by Caddy. Feeds and History stay on the feed process because they show its memory. The pages deploy and roll back without restarting the feed.
• Dedup and revision. A new receipt time or cache time is not a new report.
• The first successful poll of each feed fills memory quietly, then subscribers get that snapshot with cached: true. A newly arrived or changed product carries cached: false. This is the flag the project started with, as on metar.ws. The protocol 1 names fresh and snapshot are still sent beside it until clients have moved.
• Socket additions, 30 October 2026 (v0.6.0), from the rs-pm client's feedback. Still protocol 1, and every change was a new field. The ack and the text ping carry server_time. Every publication carries sent_at, stamped when it is written to that socket. Every broadcast carries a global seq, and the ack names the run with boot_id. A subscribe with since_seq replays missed publications from a bounded buffer and says full, partial, or none. "snapshot":false skips the snapshot. A slow client gets a backpressure warning at 500 queued, before the close at 1000.
• Protocol 2, 30 October 2026 (v0.7.0), the rest of the rs-pm feedback. Snapshot frames say cached: true again. Every event has report_id, correction, supersedes, and source_time, and the minute, climate, and D-ATIS feeds are measured like the official one. Times are UTC with milliseconds, and clock fields are null rather than left out. subscribed lists the stations each name covers and each feed's cadence. Feed health is pushed as status frames. A request id comes back as ref. One keepalive timer per socket, and a socket that stops answering pings is closed. "mode":"latest" coalesces a slow client's queue. 503 is JSON with Retry-After. Tokens have read-only scopes and rotate with an overlap. The Reference page lists what a protocol 1 client must change.
• Board, cities, feeds, history, reference, and this spec, on the same port as the socket.
• Last poll on the board: live flag, station count, HTTP status, new events, elapsed time, cache age.
• A failed poll stays on the board and on Feeds for 30 minutes after the feed recovers. The note names the climate stations or the minute file, or says the poll failed. A minute file that is not published yet is not a failure.
• History of reports this process has decoded, in memory for 48 hours, at GET /v1/history and /history. A restart clears it. This is not a backfill.
• Station catalog at GET /v1/stations and on the Cities page. Latitude, longitude, and elevation are the Aviation Weather Center station values read on 26 October 2026. Weather events do not repeat them.
• MADIS data descriptors. A minute value is omitted when the flag is X, Q, B, or I. Passed flags and Z stay. The flag character is not copied onto the event.
• The board can add a city from that catalog. It still opens only the stations on screen. Typing a four-character id still works.
• FAA D-ATIS text on atis.<icao>, polled every 5 seconds from :45 to :05 past each hour and every 15 seconds otherwise from the public mirror at atis.info. This process is not a SWIM client. raw is the original bulletin, not a rebuilt METAR. A new event is a new observation time or a new weather sentence. An information-letter or runway-only change is not a new event. Central Park (KNYC) has no D-ATIS. The bulletin does not settle the temperature contracts.
• HRRR, NBM, and GFS 2 m temperature on hrrr.<icao>, nbm.<icao>, and gfs.<icao>, polled about every 30 minutes from NOAA NOMADS. The poll reads the GRIB index and fetches that message by byte range. The event keeps the nearest cell and a local-day high and low. Hours are every 3 through 48. day_complete stays false until the samples span the local day with no gap over 6 hours. A partial day is still published. These forecasts do not settle the temperature contracts.

Next

Nothing is queued ahead of the later phase.

Later phase

Still outside this ingest loop. The note is in metar.ws (reference)/notes-for-our-engine.md.

• Historical backfill.
• Accounts and billing. Tokens are issued by hand until then.

Hold these

• flt_cat is copied from NOAA.
• HF-METAR has no raw. The NetCDF rawMessage is not a METAR.
• 10+ visibility stays a limit. It does not become an exact metre value.
• The board opens obs.<id>, hf.<id>, cli.<id>, atis.<id>, hrrr.<id>, nbm.<id>, and gfs.<id> for the stations on screen. A station with no climate product or no D-ATIS is not subscribed for that feed. Model channels are always subscribed. obs.*, hf.*, cli.*, atis.*, hrrr.*, nbm.*, and gfs.* are separate subscriptions.
• Latitude, longitude, and elevation live on the station catalog, not on the weather event.
• This product is a weather feed. It is not a prediction-market site, and it is not advertised as one. Traders may be among the people who use it. The Cities list still names the markets that picked these stations, so a reader can see which public number each market uses.
• Sources stay the ones already wired: the Aviation Weather Center METAR cache, NCEP MADIS, the NWS daily climate report, NOAA NOMADS for HRRR, NBM, and GFS, and the public D-ATIS mirror. New source families wait until they are asked for.
• The feed collects the stations in src/wxd/cities.py. The Cities page and the board's starting list both read that file. Checked 26 October 2026. polymarket.com has a daily high and a daily low at LaGuardia (KLGA), O'Hare (KORD), Atlanta (KATL), Miami (KMIA), Hobby (KHOU), Austin (KAUS), Love Field (KDAL), Denver (KDEN), Sea-Tac (KSEA), San Francisco (KSFO), and Los Angeles (KLAX). Polymarket US has a daily high at Central Park (KNYC), Midway (KMDW), Philadelphia (KPHL), Los Angeles (KLAX), Miami (KMIA), and San Francisco (KSFO), and a daily low at Central Park and Midway. Those Polymarket US markets settle on the NWS Climatological Report (Daily), which is the Climate column. polymarket.com still settles on the routine METAR temperature remark, which is the Official column. The board columns are that METAR, the minute observations, the climate report, and the D-ATIS bulletin. A forecast strip under those columns shows HRRR, NBM, and GFS. The D-ATIS column is not a settlement number. A model temperature is not a settlement number. A saved list that matches an older default exactly is replaced with this list. Any other saved list stays as the reader left it.