dio_server_clock
Tamper-resistant server time for Dio apps. Reads the HTTP Date header from responses you already make and anchors it to a monotonic clock, so device time and timezone changes have no effect.
- No extra requests and no backend changes
- Ignores the device clock and timezone once synced
- Corrects for network delay and skips cached responses
- Pure Dart: works in Flutter, CLI and server apps, on Dio 4 and 5
Why
DateTime.now() trusts a clock and a timezone the user controls. If the phone's time is off, changed by hand, or set to another timezone, any time-based decision in the app (market hours, offer windows, cut-off times) is wrong.
How it works
Every HTTP response carries a Date header. The HTTP standard (RFC 9110) requires servers with a clock to send it, and web servers and CDNs (Nginx, Apache, CloudFront, Cloudflare) add it on their own, including on 401 and 500 responses. It is always UTC, with one-second resolution.
flowchart LR
A["Response arrives<br/>Date header + round trip"] --> B["Filter the sample<br/>allowed path, not cached, fast enough"]
B --> C["Set the anchor<br/>server time + round trip / 2<br/>monotonic stopwatch restarts"]
C --> D["Read the time<br/>anchor + stopwatch elapsed"]
The stopwatch reads the OS monotonic clock, which ignores device time and timezone changes, so the time stays correct between samples. The most precise sample (shortest round trip) is kept, and refreshed after five minutes.
Quick start
dependencies:
dio_server_clock: ^0.1.0
import 'package:dio_server_clock/dio_server_clock.dart';
final serverClock = ServerClock(); // one per backend, app-wide
dio.interceptors.add(ServerClockInterceptor(serverClock)); // add it last
serverClock.now; // server time, UTC
serverClock.nowIn(const Duration(hours: 5, minutes: 30)); // fields at UTC+5:30
serverClock.isSynced; // false until the first sample
Before the first accepted sample, now falls back to the device clock. Check isSynced where that matters.
Choosing which requests to sample
Sample authenticated, user-specific responses, which CDNs don't cache (Cache-Control: private or no-store). Avoid static files and public cacheable endpoints: a cached copy carries an old Date.
ServerClockInterceptor(
serverClock,
pathPrefixes: const ['/api/v1/user/', '/api/v1/orders'],
include: (options) => options.method == 'GET', // optional, combined with pathPrefixes
);
Login is a good first sample: it is never cached and happens before any screen that needs the time.
Cached responses
A response is skipped when its headers show it came from a cache:
| Header | Treated as cached when |
|---|---|
Age |
Greater than 0 (Age: 0 alone is not a hit) |
Cache-Status (RFC 9211) |
Any member has the hit parameter |
X-Cache |
CloudFront Hit / RefreshHit, Fastly or Varnish HIT, Squid TCP_*_HIT |
CF-Cache-Status |
Cloudflare HIT, STALE, UPDATING, REVALIDATED |
304 Not Modified responses are skipped too. isCacheHit(headers) is exported if you need the same check.
Local caching interceptors
Add ServerClockInterceptor after any caching interceptor. A cache that answers in its onRequest (like dio_cache_plus) never reaches it, and dio_cache_plus 2.1.0+ also marks hits with Cache-Status and Age, which are detected. For a cache that marks responses another way, pass isFromCache:
ServerClockInterceptor(
serverClock,
isFromCache: (response) => response.extra['fromMyCache'] == true,
);
Interceptor order
The round trip is measured from this interceptor's onRequest to its onResponse. Adding it last keeps slow request work in other interceptors (token refresh, reading secure storage) out of the measurement.
Lifecycle (Flutter)
The monotonic clock can pause while the device is in deep sleep, so after a long sleep now can be behind until the next response. Call invalidate() when the app resumes so the next response replaces the anchor:
@override
void didChangeAppLifecycleState(AppLifecycleState state) {
if (state == AppLifecycleState.resumed) serverClock.invalidate();
}
The anchor lives in memory only. A new process starts unsynced; nothing is saved to disk, because a stored offset would be wrong after a reboot.
Accuracy
About ±1 second. uncertainty gives the worst-case error of the current anchor: half the round trip plus half a second for the Date header's resolution. onAnchor emits a ClockSample each time the anchor changes, with deviceSkew (server minus device) for logging or a "your device time is off" banner.
This is for client-side decisions. It is not a security boundary: anyone who can rewrite responses (for example a proxy on a rooted device) can change the Date header. Enforce anything that matters on the server.
Fixed offsets
nowIn(offset) returns a DateTime whose fields (hour, minute, weekday) are the wall-clock time at that offset. It is still flagged UTC, so read or format its fields, but never store it, send it, or call toLocal() on it. Store and send now.millisecondsSinceEpoch instead.
Example: checking market hours in India Standard Time.
bool isMarketOpen(ServerClock serverClock) {
final t = serverClock.nowIn(const Duration(hours: 5, minutes: 30));
if (t.weekday == DateTime.saturday || t.weekday == DateTime.sunday) {
return false;
}
final minutes = t.hour * 60 + t.minute;
return minutes >= 9 * 60 + 15 && minutes < 15 * 60 + 30;
}
Fixed offsets don't handle daylight saving time; for regions that use it, convert now with a timezone database.
Web
Browsers hide the Date header on cross-origin requests. The server must send Access-Control-Expose-Headers: Date. Android, iOS and desktop are unaffected.
Configuration
| Parameter | Default | Meaning |
|---|---|---|
maxRoundTrip |
2 s | Slower samples are ignored once synced |
maxRoundTripBeforeSync |
10 s | Looser limit before the first sample and after invalidate() |
maxAnchorAge |
5 min | After this, a less precise sample may replace the anchor |
FAQ
Why not NTP? NTP needs UDP access to a time server, which some networks block, and it gives the time of a third party rather than your server. This package needs nothing beyond the requests you already make.
Several backends? Create one ServerClock and interceptor per Dio instance.
Can I feed samples myself? Yes: addHttpDate(header, roundTrip) or addSample(serverTime, roundTrip, resolution: ...).
Libraries
- dio_server_clock
- Tamper-resistant server time for Dio apps.