Class NtpTimeSource

java.lang.Object
lol.trq.alts.time.NtpTimeSource
All Implemented Interfaces:
TimeSource

public final class NtpTimeSource extends Object implements TimeSource
A TimeSource corrected against an NTP server.

One clean protocol, one UDP round trip: the offset between the OS clock and the server's is measured and applied, and re-measured on an interval. This is the library's only non-HTTP network shape, and it is deliberately minimal — a single SNTP exchange with the standard four-timestamp offset calculation, not an aggregator over a handful of web time APIs that each answer in a different JSON shape and are slower than the drift they claim to fix.

Its UDP exchange does not go through the runtime's ProxyProvider. NTP is not HTTP, and no proxy route the library knows carries it, so a host that proxies every request still sends this one from its own address to the server named here; see SECURITY.md. A host that must not do that passes its own TimeSource instead.

now() never touches the network. It is the OS clock plus the last measured offset — pure arithmetic — because it is read inside the final spin of a scheduled claim, where a DNS lookup or a socket timeout turns a twenty-millisecond approach into seconds and misses the target. Measurement happens off to the side: a now() that finds the offset due for a re-measure starts one on the executor it was given and returns at once with what it already has. A failed measurement keeps the last good offset (or zero, if none was ever obtained) and is retried on a growing backoff rather than on every call — a claim should fire on a slightly-off clock rather than not at all. A caller that wants the correction in hand before it schedules anything calls sync() first, which does block.

A reply is only believed if it is a server reply to this request: server mode, a real stratum, a set clock, and the request's own random nonce echoed back, so a stray or forged datagram cannot move the clock.

Since:
0.11.0
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a source correcting against pool.ntp.org, re-syncing every 15 minutes.
    NtpTimeSource(Executor executor, String server, int port, Duration resyncInterval)
    Creates a source correcting against a server on a given port — for a host running its own time server somewhere other than the standard port.
    NtpTimeSource(Executor executor, String server, Duration resyncInterval)
    Creates a source correcting against a given server on a given interval.
  • Method Summary

    Modifier and Type
    Method
    Description
    now()
    Returns the OS clock corrected by the last measured offset.
    Returns the correction currently applied to the OS clock.
    boolean
    Measures the offset now, blocking until the exchange finishes or times out, so a caller about to schedule a time-critical claim has the correction in hand before the first now().
    boolean
    Returns whether an offset has ever been measured.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • NtpTimeSource

      public NtpTimeSource(Executor executor)
      Creates a source correcting against pool.ntp.org, re-syncing every 15 minutes.
      Parameters:
      executor - the executor background measurements run on
      Since:
      1.0.0
    • NtpTimeSource

      public NtpTimeSource(Executor executor, String server, Duration resyncInterval)
      Creates a source correcting against a given server on a given interval.
      Parameters:
      executor - the executor background measurements run on
      server - the NTP server hostname
      resyncInterval - how often to re-measure the offset; null or non-positive means 15 minutes
      Since:
      1.0.0
    • NtpTimeSource

      public NtpTimeSource(Executor executor, String server, int port, Duration resyncInterval)
      Creates a source correcting against a server on a given port — for a host running its own time server somewhere other than the standard port.
      Parameters:
      executor - the executor background measurements run on
      server - the NTP server hostname
      port - the UDP port the server answers on
      resyncInterval - how often to re-measure the offset; null or non-positive means 15 minutes
      Since:
      1.0.0
  • Method Details

    • now

      public Instant now()
      Returns the OS clock corrected by the last measured offset. Never blocks and never touches the network: when the offset is due for a re-measure this starts one in the background and returns with the offset it already has, which is zero until the first measurement lands.
      Specified by:
      now in interface TimeSource
      Returns:
      now, corrected by the last known offset
      Since:
      0.11.0
    • sync

      public boolean sync()
      Measures the offset now, blocking until the exchange finishes or times out, so a caller about to schedule a time-critical claim has the correction in hand before the first now().

      Measurements are serialised: a call made while another is in flight waits for it and then measures in turn.

      Returns:
      true if the sync succeeded
      Since:
      0.11.0
    • synced

      public boolean synced()
      Returns whether an offset has ever been measured. Until it has, now() is the uncorrected OS clock.
      Returns:
      true once a measurement has succeeded
      Since:
      0.12.0
    • offset

      public Duration offset()
      Returns the correction currently applied to the OS clock.
      Returns:
      the last measured offset, zero before the first successful measurement
      Since:
      0.12.0