dio_server_clock 0.2.0
dio_server_clock: ^0.2.0 copied to clipboard
Tamper-resistant server time for Dio apps. Reads the HTTP Date header from responses you already make and anchors it to a monotonic clock.
Changelog #
All notable changes to dio_server_clock will be documented in this file.
0.2.0 2026-Nov-01 #
Breaking release: the clock now gives a valid time or no time.
Breaking #
nowandnowInreturnDateTime?: null before the first accepted response, afterreset(), and afterinvalidate()where sleep isn't counted. They no longer fall back to the device clockisSynced,deviceSkewanduncertaintyfollownow: false or null whenevernowis nullmaxAnchorAgeis removed; the newest acceptable response now winsinvalidate()clears the time where the clock may pause in deep sleep (web, Windows); on Android, iOS, macOS and Linux it keeps the timeonAnchorfires for every accepted responseServerClockInterceptor:pathPrefixesis replaced byallow, whose path entries match at/boundaries (/api/userno longer matches/api/users)ServerClockInterceptor:isFromCacheis replaced bycacheVerdictServerClockInterceptor: the clock is now the optional namedserverClock:argument, defaulting toServerClock.instance
Added #
- The time runs on the platform boot clock, which keeps counting through deep sleep:
CLOCK_BOOTTIMEon Android and Linux,CLOCK_MONOTONICon iOS and macOS, throughdart:ffi. Web, Windows and any failure fall back toStopwatch.countsSleepreports which is in use tolerance(default 5 s): a response more than this ahead replaces a stale time at once; one more than this behind (a cached copy) is ignored, unless three in a row agree, meaning the server's clock moved backonSyncChanged: aStream<bool>that fires when the time is gained or lostServerClock.instance: a shared clock thatServerClockInterceptor()feeds by default, so most apps don't create or pass a clock.dispose()does nothing on itallowanddenyonServerClockInterceptor: lists of paths (/api/v1/user, any host), base URLs (https://api.example.com) or URLs with a path. Deny wins; invalid entries throwArgumentErrorwhen the interceptor is createdcacheVerdictonServerClockInterceptor, returning aCacheVerdict:cachedskips a response,freshsamples it despite the default cache check,useDefaultleaves it to the default check- The example is now a Flutter test app for Android and iOS, with a deep-sleep check
Migration from 0.1.0 #
- Handle null wherever you read the time:
final now = ServerClock.instance.now; if (now == null) { /* unknown: show "syncing…" */ }. Don't replace null withDateTime.now()in decisions - Remove
maxAnchorAge:fromServerClock(...) pathPrefixes: ['/api/v1/']becomesallow: ['/api/v1']. Note the/boundary: a prefix that relied on partial matches (/api/userfor/api/users) needs each path listedServerClockInterceptor(myClock)becomesServerClockInterceptor(serverClock: myClock), orServerClockInterceptor()withServerClock.instancein place of your clockisFromCache: (r) => condbecomescacheVerdict: (r) => cond ? CacheVerdict.cached : CacheVerdict.useDefault- Keep calling
invalidate()on app resume
0.1.0 2026-Oct-31 #
Added #
ServerClock: server time anchored to a monotonic stopwatch, withnow,nowIn,isSynced,deviceSkew,uncertainty,onAnchor,invalidateandresetServerClockInterceptor: samples the HTTPDateheader from Dio responses, including error responses, withpathPrefixes,includeandisFromCachefiltersisCacheHit: detects cached responses fromAge,Cache-Status(RFC 9211),X-CacheandCF-Cache-Statusheaders- Supports Dio 4 and 5; pure Dart, no Flutter dependency