also looking at this
feat: add shared-clock scoped vehicle simulation sessions
#98
42 files
+2764
-127
| @@ -0,0 +1,62 @@ | ||
| 1 | import { authorityPolicy } from '../authority/supervisor' | |
| 2 | ||
| 3 | export interface VehicleLinkScope { vehicleId: string, bootId: number, sessionId: number } | |
| 4 | export type VehicleLinkSource = 'primary' | 'backup' | |
| 5 | interface Packet extends VehicleLinkScope { sourceId: VehicleLinkSource, sequence: number, capturedAtMs: number, receivedAtMs: number, clockUncertaintyMs: number, connected: boolean } | |
| 6 | const fields = ['vehicleId', 'bootId', 'sessionId', 'sourceId', 'sequence', 'capturedAtMs', 'receivedAtMs', 'clockUncertaintyMs', 'connected'] | |
| 7 | function captureData(input: unknown, keys: string[]): Record<string, unknown> | null { | |
| 8 | if (!input || typeof input !== 'object' || Object.getPrototypeOf(input) !== Object.prototype || Reflect.ownKeys(input).length !== keys.length) return null | |
| 9 | const captured: Record<string, unknown> = {} | |
| 10 | for (const key of keys) { | |
| 11 | const d = Object.getOwnPropertyDescriptor(input, key) | |
| 12 | if (!d || !d.enumerable || !Object.hasOwn(d, 'value')) return null | |
| 13 | captured[key] = d.value | |
| 14 | } | |
| 15 | return captured | |
| 16 | } | |
| 17 | ||
| 18 | /** Two captured sources for one authority owner. Scope labels are not authentication. */ | |
| 19 | export function createRedundantVehicleLinks(input: VehicleLinkScope) { | |
| 20 | const data = captureData(input, ['vehicleId', 'bootId', 'sessionId']) | |
| 21 | if (!data || typeof data.vehicleId !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(data.vehicleId) || typeof data.bootId !== 'number' || !Number.isSafeInteger(data.bootId) || data.bootId < 1 || typeof data.sessionId !== 'number' || !Number.isSafeInteger(data.sessionId) || data.sessionId < 1) throw new TypeError('Invalid vehicle link scope') | |
| 22 | const scope = { vehicleId: data.vehicleId, bootId: data.bootId, sessionId: data.sessionId }, packets = new Map<VehicleLinkSource, Packet>() | |
| 23 | let lastNow = -1, seenHealthy = false, latchedLoss = false | |
| 24 | function clock(nowMs: number) { | |
| 25 | if (!Number.isSafeInteger(nowMs) || nowMs < 0 || nowMs < lastNow) throw new RangeError('Invalid vehicle link clock') | |
| 26 | lastNow = nowMs | |
| 27 | } | |
| 28 | function fresh(packet: Packet, nowMs: number) { | |
| 29 | return packet.connected && nowMs - packet.capturedAtMs + packet.clockUncertaintyMs <= authorityPolicy.linkAgeMs | |
| 30 | } | |
| 31 | function checkLoss(nowMs: number) { | |
| 32 | if (seenHealthy && ![...packets.values()].some(packet => fresh(packet, nowMs))) latchedLoss = true | |
| 33 | } | |
| 34 | return { | |
| 35 | ingest(input: unknown, nowMs: number): boolean { | |
| 36 | clock(nowMs) | |
| 37 | checkLoss(nowMs) | |
| 38 | const captured = captureData(input, fields) | |
| 39 | if (latchedLoss || !captured) return false | |
| 40 | if (captured.vehicleId !== scope.vehicleId || captured.bootId !== scope.bootId || captured.sessionId !== scope.sessionId || !['primary', 'backup'].includes(captured.sourceId as string) | |
| 41 | || typeof captured.connected !== 'boolean' || !['sequence', 'capturedAtMs', 'receivedAtMs', 'clockUncertaintyMs'].every(key => Number.isSafeInteger(captured[key]) && Number(captured[key]) >= 0)) return false | |
| 42 | const packet = captured as unknown as Packet, previous = packets.get(packet.sourceId) | |
| 43 | if (packet.sequence < 1 || packet.clockUncertaintyMs > 10 || packet.capturedAtMs < packet.clockUncertaintyMs || packet.capturedAtMs + packet.clockUncertaintyMs > packet.receivedAtMs || packet.receivedAtMs > nowMs | |
| 44 | || nowMs - packet.capturedAtMs + packet.clockUncertaintyMs > authorityPolicy.linkAgeMs || previous && (packet.sequence <= previous.sequence || packet.capturedAtMs <= previous.capturedAtMs || packet.receivedAtMs < previous.receivedAtMs)) return false | |
| 45 | packets.set(packet.sourceId, { ...packet }) | |
| 46 | if (packet.connected) seenHealthy = true | |
| 47 | return true | |
| 48 | }, | |
| 49 | snapshot(nowMs: number) { | |
| 50 | clock(nowMs) | |
| 51 | checkLoss(nowMs) | |
| 52 | const candidates = (['primary', 'backup'] as const).filter(id => { const packet = packets.get(id); return packet && fresh(packet, nowMs) }) | |
| 53 | if (candidates.length) seenHealthy = true | |
| 54 | else if (seenHealthy) latchedLoss = true | |
| 55 | const selectedSource = latchedLoss ? null : candidates[0] ?? null, selected = selectedSource ? packets.get(selectedSource)! : null | |
| 56 | return { evidence: 'scoped-captured-link-selection' as const, scope: { ...scope }, observedAtMs: nowMs, selectedSource, latchedLoss, | |
| 57 | authority: { capturedAtMs: selected ? selected.capturedAtMs - selected.clockUncertaintyMs : 0, connected: selected !== null }, | |
| 58 | sources: (['primary', 'backup'] as const).map(sourceId => { const packet = packets.get(sourceId); return { sourceId, sequence: packet?.sequence ?? null, capturedAtMs: packet?.capturedAtMs ?? null, receivedAtMs: packet?.receivedAtMs ?? null, clockUncertaintyMs: packet?.clockUncertaintyMs ?? null, connected: packet ? fresh(packet, nowMs) : false } }), | |
| 59 | identityAuthenticated: false as const, physicalFlightEnabled: false as const } | |
| 60 | }, | |
| 61 | } | |
| 62 | } | |