Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Core\Time;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use DateTimeImmutable;
12use DateTimeInterface;
13
14/**
15 * Interface for Network Time Protocol (NTP) Time Synchronization Service.
16 *
17 * Provides clock-drift-aware authoritative timestamps and token expiration checks
18 * using certified atomic time servers (GUM, NIST, Cloudflare).
19 *
20 * @package App\Core\Time
21 */
22interface NtpTimeSyncServiceInterface
23{
24    /**
25     * Returns current authoritative Unix timestamp adjusted by verified NTP clock drift.
26     *
27     * @return int Authoritative Unix timestamp in seconds.
28     */
29    public function getAdjustedTimestamp(): int;
30
31    /**
32     * Returns current authoritative DateTimeImmutable instance adjusted by NTP clock drift.
33     *
34     * @return DateTimeImmutable Authoritative UTC DateTime.
35     */
36    public function getAdjustedDateTime(): DateTimeImmutable;
37
38    /**
39     * Returns current measured clock drift in seconds (positive if server clock is behind NTP).
40     *
41     * @return float Clock drift offset in seconds.
42     */
43    public function getClockDriftSeconds(): float;
44
45    /**
46     * Explicitly queries reference NTP server to measure and cache clock drift.
47     *
48     * @param string|null $host Optional NTP server hostname.
49     * @param int $port NTP port (default 123).
50     * @param int $timeout Socket timeout in seconds.
51     * @return float Measured clock drift in seconds.
52     */
53    public function syncWithNtp(?string $host = null, int $port = 123, int $timeout = 2): float;
54
55    /**
56     * Checks if given expiration time is reached according to authoritative adjusted clock.
57     *
58     * @param DateTimeInterface $expiresAt Target expiration timestamp.
59     * @return bool True if expired, false if still valid.
60     */
61    public function isTokenExpired(DateTimeInterface $expiresAt): bool;
62}