How the timer keeps running after a refresh

The timer that Untimer replaces was a browser tab. It worked well until you touched it. Refresh the page and the session was gone. Leave the page and come back, and the session was gone. Open it on a phone, and the phone put the tab to sleep and the countdown stopped. The founder used that timer every day for years and lived with all three problems.

The cause was where the time lived. That timer kept “seconds remaining” in the memory of the page and counted it down in a loop. That is the obvious way to build a timer, and it breaks easily. Page memory disappears. Loops in background tabs get slowed down. The computer’s clock moves when the person changes it, when the operating system syncs it, or when a laptop lid closes for an hour.

Untimer is built the other way round. A session keeps running when you refresh the page, close the tab, put the laptop to sleep or open Untimer on another device. The server stores the session as an end time, and every screen works out the time left from that end time.

The server stores an end time

When you let go of the hourglass, the server writes down one fact: this session ends at a particular instant, such as 10:25:00 and some milliseconds in the server’s own time. It writes a few other facts beside it: when the session started, what it is for if you named a task, and how long it was planned to be. Then it stops. The server holds a moment and leaves the counting alone.

Every screen that shows the countdown does the same small sum. It takes the end time, subtracts the time now and shows the answer as minutes and seconds. It repeats that sum on every repaint and throws the answer away each time. After a refresh the page asks the server what is happening, is told the end time and draws the time left. This is why a refresh leaves the session where it was.

The clock comes from the server

If the screen used your computer’s clock, a clock that runs a minute fast would show a session a minute short, and a clock that jumped during a sync would make the sand lurch. So every answer from the server includes the server’s own time, and the app anchors to that. It notes the server’s time together with the browser’s elapsed time counter at the moment the answer arrives. From then on it measures elapsed time from that counter, which your machine leaves alone. The wall clock can be wrong by an hour and the sand is still right.

When a laptop wakes from sleep the counter is stale, so the app asks again. It also asks again when the tab becomes visible, when the window gets focus and when the network comes back. Each of those is one small request, and each one sets the clock again. Using the app keeps the clock right.

One session at a time

Only one session can run per account, and a unique rule on the database table enforces it. If a phone and a laptop both start a session at the same moment, exactly one wins, and the other device is told what is already running and shows that session. Two devices stay in agreement about which session is live, because the database has room for one answer. A session you start on one device appears on your other devices within a few seconds.

Every change you make carries a small random ticket as well. If your connection drops halfway through pressing Reset and the request is sent again, the server recognises the ticket and applies the reset once. Sending the same request twice is safe.

Sessions that end while Untimer is closed

What happens when a session reaches zero and every screen is away? The tab is closed, the laptop is shut and the phone is in a bag. The end time is already written down, so the session can finish on its own. The next time anything asks the server anything, the server first looks for sessions whose end time has passed and records them as complete, ended at the moment they were due. A session that finished at 10:25 while you were in a meeting is recorded as finished at 10:25 when you open Untimer at 14:00. The history comes out right with every device asleep.

The completion is the server’s to write. When the sand runs out on screen, the app asks the server to confirm, and the server hands back the record it just wrote. The message box at the end of a session reads from that record.

The bell

The sound at the end is one more place a timer usually counts. The obvious way is to check every second whether it is time to ring. In a tab hidden behind your work, browsers slow those checks to once a second, and after a few minutes to once a minute. A bell that rings a minute late cannot be trusted.

So Untimer places the bell. The browser’s audio system keeps its own clock, and that clock keeps going in a hidden tab. When a session starts, the bell is placed on that clock at the exact moment the session ends and then left alone. Stopping the session takes it back, and Reset places it again for the new end time. When the moment arrives it sounds, whatever the tab is doing.

A browser allows sound only after you have touched the page, so after a refresh in the middle of a session the bell is placed once you click or press a key. After that it is exact. Settings has a switch for a browser notification when the session ends, which covers a page you have not touched since the refresh.

The tab title

While a session runs, the browser tab title shows the whole minutes left, such as 24 min. You can read the time from another tab.

History and totals

Ten years of sessions keep the app just as quick. Every screen reads a page at a time instead of the whole history. The days list in Insights loads one page at a time, the other panels read daily totals that the server updates when each session ends, and the server checks milestones at the same moment. The timer the founder replaced did the opposite, and it got slower every month.

What this gives you

Start a session at your desk and open Untimer on your phone, and the phone shows the same sand at the same place. Refresh the page a hundred times and the session carries on. Close the tab and open it an hour later, and the session is there, completed at the minute it was due. The session carries on when the laptop sleeps and when the computer’s clock is wrong.

All of this happens out of sight, so you can stop thinking about the timer and think about something else.