No. 11 devlog
Midnight Is Harder Than You Think
The hardest question this site answers is what day it is.
A daily game promises that everyone gets the same puzzle on the same day, and a new one tomorrow. But today depends on where you are standing, and the people playing are not all standing in one place. The passages for engineers below are marked, and the story holds without them.
The first answer: ask the device
Every browser already knows the date where it is sitting, and reading it takes almost no code. This site shipped with exactly that and kept it for its first sixteen months.
The cost is that the puzzle stops being a shared event. A player in Sydney gets the new puzzle most of a day before a player in Los Angeles, so at any moment the two are on different puzzles. That is fine until they talk to each other, which is what the site is for. A score arrives for a puzzle you have not been handed yet. A friend mentions an answer to a day you are still working on.
There is a second problem underneath. A day that comes from the device is whatever the device says, and a device can be told it is tomorrow from a settings screen. So the gate that hands out puzzles never takes the browser's word for the date. It works out today itself, and takes only one thing from the browser: which date is being asked about.
One day, one puzzle, everywhere
What I run instead is one day for the whole site, pinned to the clock in New York. Midnight there is the rollover for everyone, wherever they are. For most players, that is an hour they did not choose.
| City | January | July |
|---|---|---|
| Los Angelesthe evening before | 9:00 pm | 9:00 pm |
| New York | midnight | midnight |
| London | 5:00 am | 5:00 am |
| Berlin | 6:00 am | 6:00 am |
| Delhi | 10:30 am | 9:30 am |
| Tokyo | 2:00 pm | 1:00 pm |
| Sydney | 4:00 pm | 2:00 pm |
What one shared day buys on the building side:
- One cached copy per date. Everyone asks for the same file and gets the same bytes, so a copy can sit in a data center near them. A per-player day makes every response personal, and a personal response cannot be shared.
- A puzzle's number is arithmetic. The "#142" on a game's card is worked out from the date and that game's first day, and nothing else. No counter increments anywhere, so nothing can fall out of step.
- The free window means one thing. "The last fourteen days" are the same fourteen days for you as for the friend you are chasing.
- Streaks are not a geography puzzle. A played day is filed under the puzzle's date, which does not care where you were standing.
The one thing the site never says is the zone. The copy used to promise "midnight ET" on one page and "midnight EST" one click away, and EST is wrong for most of the year. I took the zone out of the player-facing copy and left it at "midnight". The mechanics did not change, and the promise stopped being wrong.
Two steps
Today is worked out in two moves, and keeping them apart is what makes it work. First, ask the platform for the calendar date in New York right now. Browsers and operating systems carry the world's timezone rules, daylight saving included, and update them when governments change their minds. The answer is a year, a month, and a day, with no clock time and no offset.
Second, every shift after that is plain arithmetic in UTC, the one reference clock that never springs forward. Yesterday is that date minus one. The oldest free day is that date minus thirteen.
For the builders: where the timezone stops
Step one returns a calendar date, and step two never sees a timezone again.
Dates travel as plain YYYY-MM-DD strings from there, which
sort as text in the same order they sort as time, so "is this date in the
future" is a string comparison.
The split exists because of the code it replaced, which I wrote myself and which looked reasonable at the time. It asked the device how far it was from UTC, moved the timestamp by that much, shifted the day, and read the answer back out. The offset it measured before the shift is not always the offset that applies after it, and nothing downstream could tell.
every day of the year
Today itself never moved
It returned the device's own date: wrong in the way the first section is about, but wrong the same way every time.
the day after each clock change
Yesterday came back off by one
For exactly one hour.
the thirteen days after that
The oldest free day came back off by one too
That same hour again, on every one of them.
None of it ever surfaced as an error. A different date simply came back.
Four places midnight bites
A tab left open across the rollover. A page opened at 11:58pm is still that page at 12:02am, showing yesterday. Each game works out its date once, when it loads, and files that day's progress under it. So each game page checks, when it loads, whether its date is still right, and reloads itself if not. That is a blunt fix, and it is the right one.
The check only runs when a page loads, so a tab left untouched through midnight keeps yesterday's board until something reloads it.
Pages built before today existed. Most of this site is Built once, when I deploy, and then served as flat files., this post included. A page that worked out "today" while being built on a Tuesday would still say Tuesday on Friday. So today is only ever read once a page reaches a browser. The game pages build their heading and description ahead of time and leave the board, and its date, to the browser.
The edge of the free window. The newest fourteen days are free to replay, and today counts as one of them: today plus thirteen behind it. Written the other way round it is off by one, which either locks a day early or hands out a fifteenth free day forever. Neither announces itself, so there is a test on each side of the line.
For the builders: two refusals, and the one account that gets tomorrow
The two refusals differ on purpose. A locked archive day comes back as "this exists and you cannot have it", a future day as "there is nothing here", because confirming that tomorrow's puzzle exists is already a small spoiler. In HTTP terms, 403 and 404. The one account that can open a future day is mine, which is how I play each puzzle before anyone else.
Two codebases that have to agree. The puzzles are made by Python on my Mac. The site is TypeScript at the edge. Both have to mean the same thing by "today", and each asks its own timezone database. They agree because the zone's name is spelled out on each side by hand, and names that have to match by hand eventually do not.
If they ever disagree, the card and the game header could show different numbers for the same puzzle. Or the site could ask for a date the pipeline never made, and the player lands on a practice game instead of the day's puzzle. Puzzles are made about ninety days ahead, so a one-day disagreement could sit unnoticed for a quarter, which is the part I like least.
Four rules for the next one
If you are building a daily anything, these would have saved me the rewrite.
- Pick one zone and write it down. Any zone, decided once, in a file that says why. The choice matters much less than making the same choice in every corner of the system.
- Make the day a value. Only the code that works out today looks at a clock. Everything downstream takes a date as an argument: access takes today and the requested date, the puzzle number takes a date and a start date, a streak takes the played dates and today. Functions of dates are easy to test.
- Keep the arithmetic in UTC. Once a date has no time and no offset, adding a day is adding a day. My bug came from doing that arithmetic somewhere an offset could still reach it.
- Let the clock be passed in. The resolver takes an optional "now": production passes nothing and gets the real clock, and tests pass an instant. So there is a test that half past three in the morning UTC on the first of July is still the thirtieth of June in New York, and a winter one that crosses a year. Neither waits until midnight.