@hypersoniclabs/helix-sdk 0.1.1 → 0.1.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +954 -2
- package/dist/action-surface.d.ts +182 -0
- package/dist/action-surface.js +1032 -0
- package/dist/action-surface.js.map +1 -0
- package/dist/camera.d.ts +78 -0
- package/dist/camera.js +640 -0
- package/dist/camera.js.map +1 -0
- package/dist/dev-shell/criteria.d.ts +46 -0
- package/dist/dev-shell/criteria.js +98 -0
- package/dist/dev-shell/criteria.js.map +1 -0
- package/dist/dev-shell/index.d.ts +189 -0
- package/dist/dev-shell/index.js +287 -0
- package/dist/dev-shell/index.js.map +1 -0
- package/dist/dev-shell/keys.d.ts +14 -0
- package/dist/dev-shell/keys.js +78 -0
- package/dist/dev-shell/keys.js.map +1 -0
- package/dist/dev-shell/simulator.d.ts +436 -0
- package/dist/dev-shell/simulator.js +1634 -0
- package/dist/dev-shell/simulator.js.map +1 -0
- package/dist/dev-shell/state.d.ts +148 -0
- package/dist/dev-shell/state.js +196 -0
- package/dist/dev-shell/state.js.map +1 -0
- package/dist/device-definition-resolver.d.ts +34 -0
- package/dist/device-definition-resolver.js +172 -0
- package/dist/device-definition-resolver.js.map +1 -0
- package/dist/device-trial.d.ts +3 -0
- package/dist/device-trial.js +132 -0
- package/dist/device-trial.js.map +1 -0
- package/dist/devices.d.ts +228 -0
- package/dist/devices.js +198 -0
- package/dist/devices.js.map +1 -0
- package/dist/dreamerAudio.d.ts +126 -0
- package/dist/dreamerAudio.js +135 -0
- package/dist/dreamerAudio.js.map +1 -0
- package/dist/generated/runtime-contract.d.ts +15529 -0
- package/dist/generated/runtime-contract.js +20470 -0
- package/dist/generated/runtime-contract.js.map +1 -0
- package/dist/index.d.ts +364 -3
- package/dist/index.js +1954 -13
- package/dist/index.js.map +1 -1
- package/dist/interaction-mode.d.ts +172 -0
- package/dist/interaction-mode.js +553 -0
- package/dist/interaction-mode.js.map +1 -0
- package/dist/internal/avatar-pose.d.ts +25 -0
- package/dist/internal/avatar-pose.js +46 -0
- package/dist/internal/avatar-pose.js.map +1 -0
- package/dist/internal/keyed-collection.d.ts +2 -0
- package/dist/internal/keyed-collection.js +12 -0
- package/dist/internal/keyed-collection.js.map +1 -0
- package/dist/internal/vehicle-detach-action.d.ts +2 -0
- package/dist/internal/vehicle-detach-action.js +6 -0
- package/dist/internal/vehicle-detach-action.js.map +1 -0
- package/dist/matchmaking.d.ts +433 -0
- package/dist/matchmaking.js +1487 -0
- package/dist/matchmaking.js.map +1 -0
- package/dist/materials.d.ts +122 -0
- package/dist/materials.js +217 -0
- package/dist/materials.js.map +1 -0
- package/dist/multiplayer-accessors.d.ts +100 -0
- package/dist/multiplayer-accessors.js +200 -0
- package/dist/multiplayer-accessors.js.map +1 -0
- package/dist/multiplayer-contract/avatar-pose.d.ts +112 -0
- package/dist/multiplayer-contract/avatar-pose.js +250 -0
- package/dist/multiplayer-contract/avatar-pose.js.map +1 -0
- package/dist/multiplayer-contract/credential.d.ts +80 -0
- package/dist/multiplayer-contract/credential.js +5 -0
- package/dist/multiplayer-contract/credential.js.map +1 -0
- package/dist/multiplayer-contract/final-rest.d.ts +66 -0
- package/dist/multiplayer-contract/final-rest.js +38 -0
- package/dist/multiplayer-contract/final-rest.js.map +1 -0
- package/dist/multiplayer-contract/index.d.ts +20 -0
- package/dist/multiplayer-contract/index.js +41 -0
- package/dist/multiplayer-contract/index.js.map +1 -0
- package/dist/multiplayer-contract/messages.d.ts +731 -0
- package/dist/multiplayer-contract/messages.js +237 -0
- package/dist/multiplayer-contract/messages.js.map +1 -0
- package/dist/multiplayer-contract/room.d.ts +177 -0
- package/dist/multiplayer-contract/room.js +17 -0
- package/dist/multiplayer-contract/room.js.map +1 -0
- package/dist/multiplayer-contract/state.d.ts +241 -0
- package/dist/multiplayer-contract/state.js +15 -0
- package/dist/multiplayer-contract/state.js.map +1 -0
- package/dist/multiplayer-final-rest.d.ts +32 -0
- package/dist/multiplayer-final-rest.js +217 -0
- package/dist/multiplayer-final-rest.js.map +1 -0
- package/dist/multiplayer.d.ts +624 -0
- package/dist/multiplayer.js +2503 -0
- package/dist/multiplayer.js.map +1 -0
- package/dist/package.json +3 -0
- package/dist/protocol.d.ts +859 -1
- package/dist/protocol.js +117 -5
- package/dist/protocol.js.map +1 -1
- package/dist/runtime-contract/index.d.ts +15 -0
- package/dist/runtime-contract/index.js +12 -0
- package/dist/runtime-contract/index.js.map +1 -0
- package/dist/server-clock.d.ts +25 -0
- package/dist/server-clock.js +88 -0
- package/dist/server-clock.js.map +1 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/dist/universal-vehicles.d.ts +111 -0
- package/dist/universal-vehicles.js +2 -0
- package/dist/universal-vehicles.js.map +1 -0
- package/dist/vault.d.ts +562 -0
- package/dist/vault.js +365 -0
- package/dist/vault.js.map +1 -0
- package/dist/vehicle-specialty-placement.d.ts +28 -0
- package/dist/vehicle-specialty-placement.js +154 -0
- package/dist/vehicle-specialty-placement.js.map +1 -0
- package/dist/vehicle-specialty-transport.d.ts +78 -0
- package/dist/vehicle-specialty-transport.js +183 -0
- package/dist/vehicle-specialty-transport.js.map +1 -0
- package/dist/voice.d.ts +229 -0
- package/dist/voice.js +1348 -0
- package/dist/voice.js.map +1 -0
- package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
- package/generated/runtime-contract/known-answer.json +20471 -0
- package/generated/runtime-contract/known-answer.schema.json +630 -0
- package/generated/runtime-contract/runtime-contract.schema.json +607 -0
- package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
- package/package.json +44 -5
package/dist/protocol.js
CHANGED
|
@@ -1,13 +1,125 @@
|
|
|
1
1
|
// postMessage protocol between a world (sandboxed iframe) and the HELIX shell
|
|
2
2
|
// (the play page, or a local `helix dev` shell). This file IS the wire contract
|
|
3
|
-
// —
|
|
4
|
-
|
|
3
|
+
// — version any breaking change.
|
|
4
|
+
//
|
|
5
|
+
// SYNC OBLIGATION: the shell takes no dependency on this package, so
|
|
6
|
+
// helixgame.com/lib/iwp/protocol.ts hand-mirrors these shapes AND gates them at
|
|
7
|
+
// runtime (isWorldMessage). A type added here that isn't added there is a
|
|
8
|
+
// message the shell silently drops — widen both in lockstep.
|
|
9
|
+
//
|
|
10
|
+
// v2 is additive on two fronts: (1) debug — helix:init gained `debug`, and helix:log
|
|
11
|
+
// carries world logs to the shell when debug is on; (2) the shell-mediated platform
|
|
12
|
+
// API (wallet / marketplace / inventory) on a generic request/response envelope plus
|
|
13
|
+
// push events. The world SDK is a thin wrapper: it posts a request, the shell (which
|
|
14
|
+
// holds the player's session and renders the purchase popup) settles with the backend
|
|
15
|
+
// and posts the result.
|
|
16
|
+
export const PROTOCOL_VERSION = 2;
|
|
17
|
+
/** Additive, versioned presentation intent carried on `helix:init`. */
|
|
18
|
+
export const RUNTIME_FIDELITY_VERSION = 1;
|
|
19
|
+
export const RUNTIME_FIDELITY_VISUAL_TIERS = [
|
|
20
|
+
'auto',
|
|
21
|
+
'minimal',
|
|
22
|
+
'low',
|
|
23
|
+
'medium',
|
|
24
|
+
'high',
|
|
25
|
+
'ultra',
|
|
26
|
+
];
|
|
27
|
+
export const RUNTIME_FIDELITY_RENDER_SCALES = ['1.5', '1', '0.77', '0.59'];
|
|
28
|
+
export const RUNTIME_PROFILE_QUALITIES = ['minimum', 'balanced', 'high', 'ultra'];
|
|
29
|
+
/**
|
|
30
|
+
* Validate untrusted handshake data and copy it into SDK-owned launch state.
|
|
31
|
+
* Unknown versions, unexpected fields, or invalid members fail closed to null;
|
|
32
|
+
* consumers then use their engine's backward-compatible Auto policy.
|
|
33
|
+
*/
|
|
34
|
+
export function normalizeRuntimeFidelityIntent(value) {
|
|
35
|
+
if (!value || typeof value !== 'object')
|
|
36
|
+
return null;
|
|
37
|
+
const candidate = value;
|
|
38
|
+
if (Object.keys(candidate).length !== 4 ||
|
|
39
|
+
candidate.version !== RUNTIME_FIDELITY_VERSION ||
|
|
40
|
+
!RUNTIME_FIDELITY_VISUAL_TIERS.includes(candidate.requestedVisualTier) ||
|
|
41
|
+
!(candidate.renderScaleOverride === null ||
|
|
42
|
+
RUNTIME_FIDELITY_RENDER_SCALES.includes(candidate.renderScaleOverride)) ||
|
|
43
|
+
!(candidate.runtimeProfileQuality === null ||
|
|
44
|
+
RUNTIME_PROFILE_QUALITIES.includes(candidate.runtimeProfileQuality))) {
|
|
45
|
+
return null;
|
|
46
|
+
}
|
|
47
|
+
return {
|
|
48
|
+
version: RUNTIME_FIDELITY_VERSION,
|
|
49
|
+
requestedVisualTier: candidate.requestedVisualTier,
|
|
50
|
+
renderScaleOverride: candidate.renderScaleOverride,
|
|
51
|
+
runtimeProfileQuality: candidate.runtimeProfileQuality,
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
export const PURCHASE_STATUS_MEANING = {
|
|
55
|
+
Pending: { money: 'unknown', ownsAfter: false },
|
|
56
|
+
Granted: { money: 'charged', ownsAfter: true },
|
|
57
|
+
Claimed: { money: 'not-charged', ownsAfter: true },
|
|
58
|
+
AlreadyOwned: { money: 'not-charged', ownsAfter: true },
|
|
59
|
+
InsufficientFunds: { money: 'not-charged', ownsAfter: false },
|
|
60
|
+
MaxPerUserReached: { money: 'not-charged', ownsAfter: false },
|
|
61
|
+
ProductInactive: { money: 'not-charged', ownsAfter: false },
|
|
62
|
+
ProductNotFound: { money: 'not-charged', ownsAfter: false },
|
|
63
|
+
NotInWorld: { money: 'not-charged', ownsAfter: false },
|
|
64
|
+
Unauthorized: { money: 'not-charged', ownsAfter: false },
|
|
65
|
+
RateLimited: { money: 'not-charged', ownsAfter: false },
|
|
66
|
+
// The shell can fabricate Cancelled AFTER an attempted charge (Timeout -> Retry -> Cancel wipes the
|
|
67
|
+
// modal's memory that a POST happened), so not-charged cannot be certified; retaining the key turns
|
|
68
|
+
// that ambiguity into an idempotent replay instead of a fresh key that can double-charge.
|
|
69
|
+
Cancelled: { money: 'unknown', ownsAfter: false },
|
|
70
|
+
Failed: { money: 'not-charged', ownsAfter: false },
|
|
71
|
+
Timeout: { money: 'unknown', ownsAfter: false },
|
|
72
|
+
// Fabricated by the READ path for a row that may merely not be visible yet (the purchase POST can
|
|
73
|
+
// still be queued behind the per-user lock) — the popup's poll already treats it as non-terminal.
|
|
74
|
+
NotFound: { money: 'unknown', ownsAfter: false },
|
|
75
|
+
PriceChanged: { money: 'not-charged', ownsAfter: false },
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* The lens buttons, in the exact order HELIX OS renders them.
|
|
79
|
+
*
|
|
80
|
+
* These are PRESETS, not the zoom domain: effective zoom is CONTINUOUS between
|
|
81
|
+
* the first and last entry, and a preset is only where a tap lands. A runtime
|
|
82
|
+
* that clamps to these five is wrong.
|
|
83
|
+
*/
|
|
84
|
+
export const CAMERA_LENS_PRESETS = [0.5, 1, 2, 3, 5];
|
|
85
|
+
// XR document events. The world document is shared by the SDK and the engine's XR module
|
|
86
|
+
// (humanoid-character); they are different bundles and never import each other, so these two
|
|
87
|
+
// events are the whole seam: the engine reports its immersive-session state and the SDK forwards
|
|
88
|
+
// it to the shell as `helix:xr-session`; the SDK mirrors Helix.prompts.set/clear back so the engine
|
|
89
|
+
// can draw the interaction prompt in-scene while the shell's DOM overlay cannot be seen.
|
|
90
|
+
// Both are STICKY, as in the engine's touchSignals.ts: the last detail is also recorded on the
|
|
91
|
+
// document, so a listener that attaches late starts from the current state.
|
|
92
|
+
// SYNC OBLIGATION: the engine's XR module declares the same names and detail shapes; the shell
|
|
93
|
+
// mirrors only the `helix:xr-session` WorldToShellMessage member below.
|
|
94
|
+
/**
|
|
95
|
+
* Dispatched by the ENGINE XR module on every session state change; the SDK forwards it to the shell.
|
|
96
|
+
* detail: { state: 'unsupported'|'idle'|'entering'|'active'|'exiting'; reason?: string; source: 'humanoid-character' }
|
|
97
|
+
* Sticky store: document.__helixXrSession = { state, reason }
|
|
98
|
+
*/
|
|
99
|
+
export const XR_SESSION_EVENT = 'helix:xr-session';
|
|
100
|
+
/**
|
|
101
|
+
* Dispatched by the SDK when Helix.prompts.set/clear is called; the engine XR module draws it in-scene.
|
|
102
|
+
* detail: { prompt: { id: string; label: string; state?: 'default'|'available'|'locked'|'busy' } | null; source: 'helix-sdk' }
|
|
103
|
+
* Sticky store: document.__helixInteractionPrompt = detail
|
|
104
|
+
*/
|
|
105
|
+
export const XR_INTERACTION_PROMPT_EVENT = 'helix:interaction-prompt';
|
|
106
|
+
const SHELL_MESSAGE_TYPES = new Set([
|
|
107
|
+
'helix:init',
|
|
108
|
+
'helix:session',
|
|
109
|
+
'helix:login-result',
|
|
110
|
+
'helix:response',
|
|
111
|
+
'helix:event',
|
|
112
|
+
'helix:voice-settings',
|
|
113
|
+
'helix:voice-ptt',
|
|
114
|
+
'helix:device-state',
|
|
115
|
+
'helix:camera-state',
|
|
116
|
+
'helix:leave',
|
|
117
|
+
'helix:distribution-capability-request',
|
|
118
|
+
]);
|
|
5
119
|
export function isShellMessage(data) {
|
|
6
120
|
return (typeof data === 'object' &&
|
|
7
121
|
data !== null &&
|
|
8
122
|
typeof data.type === 'string' &&
|
|
9
|
-
(data.type
|
|
10
|
-
data.type === 'helix:session' ||
|
|
11
|
-
data.type === 'helix:login-result'));
|
|
123
|
+
SHELL_MESSAGE_TYPES.has(data.type));
|
|
12
124
|
}
|
|
13
125
|
//# sourceMappingURL=protocol.js.map
|
package/dist/protocol.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,
|
|
1
|
+
{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { HELIX_RUNTIME_CONTRACT, RUNTIME_CONTRACT_DIGEST, RUNTIME_METHOD_INDEX } from '../generated/runtime-contract.js';
|
|
2
|
+
export { HELIX_RUNTIME_CONTRACT, RUNTIME_CONTRACT_DIGEST, RUNTIME_METHOD_INDEX, };
|
|
3
|
+
export type HelixRuntimeContract = typeof HELIX_RUNTIME_CONTRACT;
|
|
4
|
+
export type RuntimeNamespace = keyof HelixRuntimeContract['namespaces'];
|
|
5
|
+
export type RuntimeAuthorityProfile = keyof HelixRuntimeContract['authorityProfiles'];
|
|
6
|
+
export type RuntimeCapability = keyof HelixRuntimeContract['capabilities'];
|
|
7
|
+
export type RuntimeMethodName = keyof typeof RUNTIME_METHOD_INDEX;
|
|
8
|
+
export type RuntimeMethodContract = (typeof RUNTIME_METHOD_INDEX)[RuntimeMethodName];
|
|
9
|
+
/**
|
|
10
|
+
* Returns the generated policy record for a public runtime SDK method.
|
|
11
|
+
*
|
|
12
|
+
* Runtime implementations use this metadata for capability discovery and
|
|
13
|
+
* binding generation; it does not execute or proxy the method itself.
|
|
14
|
+
*/
|
|
15
|
+
export declare function getRuntimeMethod<Name extends RuntimeMethodName>(name: Name): (typeof RUNTIME_METHOD_INDEX)[Name];
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { HELIX_RUNTIME_CONTRACT, RUNTIME_CONTRACT_DIGEST, RUNTIME_METHOD_INDEX, } from '../generated/runtime-contract.js';
|
|
2
|
+
export { HELIX_RUNTIME_CONTRACT, RUNTIME_CONTRACT_DIGEST, RUNTIME_METHOD_INDEX, };
|
|
3
|
+
/**
|
|
4
|
+
* Returns the generated policy record for a public runtime SDK method.
|
|
5
|
+
*
|
|
6
|
+
* Runtime implementations use this metadata for capability discovery and
|
|
7
|
+
* binding generation; it does not execute or proxy the method itself.
|
|
8
|
+
*/
|
|
9
|
+
export function getRuntimeMethod(name) {
|
|
10
|
+
return RUNTIME_METHOD_INDEX[name];
|
|
11
|
+
}
|
|
12
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime-contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,CAAC;AASF;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAU;IAEV,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC"}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/** How many recent samples each source keeps. */
|
|
2
|
+
export declare const SERVER_CLOCK_WINDOW = 9;
|
|
3
|
+
/** Samples this close to the median agree with it. Wider than the `Date` header's 1 s resolution plus latency. */
|
|
4
|
+
export declare const SERVER_CLOCK_AGREEMENT_MS = 2000;
|
|
5
|
+
export type ServerClockSource = 'room' | 'http';
|
|
6
|
+
export declare class ServerClock {
|
|
7
|
+
private readonly deviceNow;
|
|
8
|
+
private readonly windows;
|
|
9
|
+
private readonly lastHeard;
|
|
10
|
+
private heard;
|
|
11
|
+
constructor(deviceNow?: () => number);
|
|
12
|
+
/** A server timestamp (epoch ms) received at `receivedAt` (device epoch ms; default: now). Anything unusable is ignored. */
|
|
13
|
+
observe(serverMs: unknown, source: ServerClockSource, receivedAt?: number): void;
|
|
14
|
+
/**
|
|
15
|
+
* An HTTP `Date` header value (null when the browser did not expose it). The header is truncated to the
|
|
16
|
+
* second, so the middle of that second is taken.
|
|
17
|
+
*/
|
|
18
|
+
observeHttpDate(header: string | null | undefined, receivedAt?: number): void;
|
|
19
|
+
/** Server time minus device time, in ms, or null when no source is trusted yet. */
|
|
20
|
+
offsetMs(): number | null;
|
|
21
|
+
/** The platform's time now (epoch ms): the device clock corrected by the trusted offset, or the device clock alone. */
|
|
22
|
+
now(): number;
|
|
23
|
+
/** Whether `expiresAt` (epoch ms) has passed by the platform's clock. An unreadable expiry (NaN) never has. */
|
|
24
|
+
hasPassed(expiresAt: number): boolean;
|
|
25
|
+
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
// The platform's clock, as far as this page has seen it. Internal: not exported from the package root.
|
|
2
|
+
//
|
|
3
|
+
// A match's room ticket and a party invite carry `expiresAt` in the PLATFORM's time. Judging that against
|
|
4
|
+
// `Date.now()` trusts the device clock, and a device clock running fast by more than a ticket's life never
|
|
5
|
+
// sees a match at all (its opponents start a player short); one running slow hands the world tickets that
|
|
6
|
+
// are long dead. So every expiry judgement in Helix.matchmaking / Helix.party goes through `now()` here.
|
|
7
|
+
//
|
|
8
|
+
// What the SDK learns the platform's time from, without any extra request:
|
|
9
|
+
// - `room` every room's state is stamped with the room server's wall clock (`RoomState.serverTimeMs`, set
|
|
10
|
+
// each tick). Sampled on each state patch while a room is joined.
|
|
11
|
+
// - `http` the `Date` header of a platform API answer (matchmaking and party calls). A cross-origin page can
|
|
12
|
+
// read it only when the API lists it in `Access-Control-Expose-Headers`; until then the browser
|
|
13
|
+
// hides it and this source stays empty. One-second resolution.
|
|
14
|
+
//
|
|
15
|
+
// A sample is kept as an OFFSET (server time minus device time at receipt), so a page that slept, or a room
|
|
16
|
+
// that was left minutes ago, still answers correctly: the offset between two wall clocks does not drift by
|
|
17
|
+
// any amount that matters here. Both sources stamp the time before it travels to the device, so the estimate
|
|
18
|
+
// runs a little behind the platform, never ahead: it errs toward "not expired yet", and the platform has the
|
|
19
|
+
// last word at redeem either way.
|
|
20
|
+
//
|
|
21
|
+
// TRUST IS BOUNDED. Each source keeps its last SERVER_CLOCK_WINDOW samples. The estimate is their median, and
|
|
22
|
+
// it is used only while a strict majority of the window agrees with it (within SERVER_CLOCK_AGREEMENT_MS).
|
|
23
|
+
// So one wild answer — a cached response's stale `Date`, a proxy's own clock — cannot move it, and a single
|
|
24
|
+
// sample is never trusted alone. A genuine change (the device clock was corrected) is followed once most of
|
|
25
|
+
// the window has seen it. When both sources are trusted, the one heard from MOST RECENTLY decides: a room left
|
|
26
|
+
// long ago keeps its samples (they are still the best estimate when nothing newer exists), but it cannot
|
|
27
|
+
// overrule the platform's answers that keep arriving while the player queues. With no trusted estimate from
|
|
28
|
+
// either source the device clock is used, which is exactly the behaviour before this existed.
|
|
29
|
+
/** How many recent samples each source keeps. */
|
|
30
|
+
export const SERVER_CLOCK_WINDOW = 9;
|
|
31
|
+
/** Samples this close to the median agree with it. Wider than the `Date` header's 1 s resolution plus latency. */
|
|
32
|
+
export const SERVER_CLOCK_AGREEMENT_MS = 2_000;
|
|
33
|
+
export class ServerClock {
|
|
34
|
+
deviceNow;
|
|
35
|
+
windows = { room: [], http: [] };
|
|
36
|
+
// The order in which each source was last heard from (a counter, so no clock is needed to compare them).
|
|
37
|
+
lastHeard = { room: 0, http: 0 };
|
|
38
|
+
heard = 0;
|
|
39
|
+
constructor(deviceNow = () => Date.now()) {
|
|
40
|
+
this.deviceNow = deviceNow;
|
|
41
|
+
}
|
|
42
|
+
/** A server timestamp (epoch ms) received at `receivedAt` (device epoch ms; default: now). Anything unusable is ignored. */
|
|
43
|
+
observe(serverMs, source, receivedAt = this.deviceNow()) {
|
|
44
|
+
if (typeof serverMs !== 'number' || !Number.isFinite(serverMs) || serverMs <= 0 || !Number.isFinite(receivedAt))
|
|
45
|
+
return;
|
|
46
|
+
const window = this.windows[source];
|
|
47
|
+
window.push(serverMs - receivedAt);
|
|
48
|
+
if (window.length > SERVER_CLOCK_WINDOW)
|
|
49
|
+
window.shift();
|
|
50
|
+
this.lastHeard[source] = ++this.heard;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* An HTTP `Date` header value (null when the browser did not expose it). The header is truncated to the
|
|
54
|
+
* second, so the middle of that second is taken.
|
|
55
|
+
*/
|
|
56
|
+
observeHttpDate(header, receivedAt = this.deviceNow()) {
|
|
57
|
+
if (typeof header !== 'string' || header.length === 0)
|
|
58
|
+
return;
|
|
59
|
+
const parsed = Date.parse(header);
|
|
60
|
+
if (Number.isFinite(parsed))
|
|
61
|
+
this.observe(parsed + 500, 'http', receivedAt);
|
|
62
|
+
}
|
|
63
|
+
/** Server time minus device time, in ms, or null when no source is trusted yet. */
|
|
64
|
+
offsetMs() {
|
|
65
|
+
const room = trustedOffset(this.windows.room);
|
|
66
|
+
const http = trustedOffset(this.windows.http);
|
|
67
|
+
if (room === null || http === null)
|
|
68
|
+
return room ?? http;
|
|
69
|
+
return this.lastHeard.room > this.lastHeard.http ? room : http;
|
|
70
|
+
}
|
|
71
|
+
/** The platform's time now (epoch ms): the device clock corrected by the trusted offset, or the device clock alone. */
|
|
72
|
+
now() {
|
|
73
|
+
return this.deviceNow() + (this.offsetMs() ?? 0);
|
|
74
|
+
}
|
|
75
|
+
/** Whether `expiresAt` (epoch ms) has passed by the platform's clock. An unreadable expiry (NaN) never has. */
|
|
76
|
+
hasPassed(expiresAt) {
|
|
77
|
+
return Number.isFinite(expiresAt) && expiresAt <= this.now();
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
function trustedOffset(window) {
|
|
81
|
+
if (window.length < 2)
|
|
82
|
+
return null;
|
|
83
|
+
const sorted = [...window].sort((a, b) => a - b);
|
|
84
|
+
const median = sorted[(sorted.length - 1) >> 1];
|
|
85
|
+
const agreeing = sorted.filter((offset) => Math.abs(offset - median) <= SERVER_CLOCK_AGREEMENT_MS).length;
|
|
86
|
+
return agreeing * 2 > sorted.length ? median : null;
|
|
87
|
+
}
|
|
88
|
+
//# sourceMappingURL=server-clock.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server-clock.js","sourceRoot":"","sources":["../src/server-clock.ts"],"names":[],"mappings":"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"}
|