Skip to content

Caveats Gotchas

Jump to bottom
Kaushik Gopal edited this page Feb 25, 2023 · 8 revisions

⚠️ TrueTime is changing and this part of the wiki needs to be updated.

Notes/tips:

  • Each initialize call makes an SNTP network request. TrueTime needs to be initialized only once ever, per device boot. Use TrueTime's withSharedPreferencesCache or withCustomizedCache option to make use of this feature and avoid repeated network request calls.
  • Preferable use dependency injection (like Dagger) and create a TrueTime @Singleton object
  • You can read up on Wikipedia the differences between SNTP and NTP.
  • TrueTime is also available for iOS/Swift

Troubleshooting/Exception handling:

InvalidNtpServerResponseException

When you execute the TrueTime initialization, you are very highly likely to get an InvalidNtpServerResponseException because of root delay violation or root dispersion violation the first time. This is an expected occurrence as per the NTP Spec and needs to be handled.

Why does this happen?

The NTP protocol works on UDP:

It has no handshaking dialogues, and thus exposes the user's program to any unreliability of the underlying network and so there is no guarantee of delivery, ordering, or duplicate protection

UDP is suitable for purposes where error checking and correction is either not necessary or is performed in the application, avoiding the overhead of such processing at the network interface level. Time-sensitive applications often use UDP because dropping packets is preferable to waiting for delayed packets, which may not be an option in a real-time system

(Wikipedia's page, emphasis our own)

This means it is highly plausible that we get faulty data packets. These are caught by the library and surfaced to the api consumer as an InvalidNtpServerResponseException. See this portion of the code for the various checks that we guard against.

These guards are extremely important to guarantee accurate time and cannot be avoided.

How do I handle or protect against this in my application?

It's pretty simple:

  • keep retrying the request, until you get a successful one. Yes it does happen eventually :)
  • Try picking a better NTP pool server. In our experience time.apple.com has worked best

Or if you want the library to just handle that, use the Rx-ified version of the library (note the -rx suffix):

implementation 'com.github.instacart.truetime-android:library-extension-rx:<release-version>'

With TrueTimeRx, we go the whole nine yards and implement the complete NTP Spec (we resolve the DNS for the provided NTP host to single IP addresses, shoot multiple requests to that single IP, guard against the above mentioned checks, retry every single failed request, filter the best response and persist that to disk). If you don't use TrueTimeRx, you don't get these benefits.

We welcome PRs for folks who wish to replicate the functionality in the vanilla TrueTime version. We don't have plans of re-implementing that functionality atm in the vanilla/simple version of TrueTime.

Do also note, if TrueTime fails to initialize (because of the above exception being thrown), then an IllegalStateException is thrown if you try to request an actual date via TrueTime.now().

Clock drift and the need for Re-syncing

Every clock tick (nanosecond) in your phone is controlled by the quality of the quartz crystal in the phone's CPU.

If the quality of that quartz crystal is good, then it keeps time better. If it isn't that good, there's a chance again that there's a clock drift. This means that even if you get the TrueTime NTP call to successfully run through once, that isn't enough for the perpetuity of time.

TrueTime basically gets the offset from the "true" time; at that instant. Clock drifts is a real problem and so that means, over time, it's definitely going to go out of sync again with the "true" time. This is a physical limitation of the oscillator crystal in CPUs which help keep time.

To solve for this problem, you will have to rerun the TrueTime.init call at regular/frequent intervals so you resynchronize with the true time. At Instacart, we use a simple Flowable.interval to re-spawn an Android service, which in turn runs the TrueTimeRx.initializeNtp call.

Sample (pseudo)code:

  // inside MyApplication class
  override fun onCreate() { 

     // ...
     runTrueTimeSyncerInBackground(this)
     // ...
  }
 
  /**
   * This should be run only once.
   * calling this method again will exponentially increase calling rates
   */
  fun runTrueTimeSyncerInBackground(app: ISApplication): Disposable {
      return Flowable.interval(0L, 5, TimeUnit.MINUTES)
              .filter { !app.isOffline }
              .filter { !app.isInBackground }
              .doOnNext { app.startService(Intent(app, TrueTimeSyncService::class.java)) }
              .subscribeOn(Schedulers.io())
              .subscribe(
                    { Timber.d("TrueTime Syncer called") },
                    { Timber.w(it, "Error when running TrueTime Syncer") }
              )
  }

Here's what the TrueTimeSyncService looks like:

/**
 * Background Android Service object that sends the request to initialize TrueTime
 *
 * Calling the start service multiple times should not have any negative effect
 * as we filter these out if a current job is already running
 *
 */
class ISTrueTimeSyncService : Service() {

      private var jobCurrentlyRunning = false

      // ...

      override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
          // ^ Warning: By default executed on main thread
          
          if (jobCurrentlyRunning) return Service.START_STICKY

          Single
                .fromCallable {
                    jobCurrentlyRunning = true
                    Timber.d("Running TrueTime init now")
                }
                .flatMap<LongArray> {
                    TrueTimeRx.initializeNtp("time.google.com")
                }
                .doFinally { jobCurrentlyRunning = false }
                .subscribeOn(Schedulers.io())
                .subscribe(
                        { Timber.v("TrueTime was initialized at ${it!!.contentToString()}") },
                        { Timber.v("TrueTime init fail ${it}")  }
                )

        return Service.START_STICKY
    }
    
    // ...
}

What is a good interval to keep re-initing TrueTime?

In experiments conducted as part of the paper - An Analysis of Time Drift in Hand-Held Recording Devices results show that:

The time drift was between 3 ppm (Asus Nexus 7 2012 Wi-Fi) and 270 ppm (Samsung Galaxy SII ).

            270s               1s               1s     
270ppm =  -----------   =  -----------   =  -----------
          1_000_000 s        3_703 s          61_7 mts

A rough extrapolation of this would mean that if you want to keep the accuracy within 1 second, then you need to be re-initing TrueTime approximately every 1 hour.

(source: #90)

Clone this wiki locally