Import packages/protocol/src/transport-upgrade.ts

This commit is contained in:
QQ 2026-11-17 08:52:24 +08:00
parent 38d3a9e3fe
commit 0aaa91e54b
1 changed files with 182 additions and 0 deletions

View File

@ -0,0 +1,182 @@
import { z } from 'zod'
export const TRANSPORT_UPGRADE_CAPABILITY = 'remote.transport.upgrade.v1' as const
export const UPGRADE_SEQUENCE_HEADER_BYTES = 12
export const MAX_REORDER_BUFFERED_FRAMES = 256
export const MAX_REORDER_BUFFERED_BYTES = 4 * 1024 * 1024
export const DEFAULT_REORDER_GAP_TIMEOUT_MS = 5_000
export const DEFAULT_PREVIOUS_LEG_DRAIN_MS = 3_000
const UPGRADE_SEQ_MAGIC = [0x44, 0x53, 0x48, 0x55] as const // 'DSHU'
export const transportUpgradeCandidateSchema = z.object({
candidate: z.string().max(4096).optional(),
sdpMid: z.string().max(128).nullable().optional(),
sdpMLineIndex: z.number().int().min(0).max(64).nullable().optional(),
usernameFragment: z.string().max(256).nullable().optional(),
}).strict()
export const transportUpgradeOfferSchema = z.object({
attemptId: z.string().min(1).max(64),
sdp: z.string().min(1).max(128 * 1024),
}).strict()
export const transportUpgradeIceSchema = z.object({
attemptId: z.string().min(1).max(64),
candidate: transportUpgradeCandidateSchema,
}).strict()
export const transportUpgradeActivateSchema = z.object({
attemptId: z.string().min(1).max(64),
transport: z.enum(['lan', 'p2p', 'turn']).optional(),
previousLegEndCounter: z.number().int().min(0).optional(),
}).strict()
export const transportUpgradeDrainSchema = z.object({
attemptId: z.string().min(1).max(64),
previousLegEndCounter: z.number().int().min(0),
}).strict()
export const transportUpgradeAbortSchema = z.object({
attemptId: z.string().min(1).max(64).optional(),
}).strict()
export type TransportTier = 'Relay' | 'TURN' | 'P2P' | 'LAN'
export function transportTierRank(mode: TransportTier | undefined): number {
switch (mode) {
case 'LAN': return 3
case 'P2P': return 2
case 'TURN': return 1
default: return 0
}
}
export function wireFromTransportTier(mode: 'LAN' | 'P2P' | 'TURN'): 'lan' | 'p2p' | 'turn' {
return mode === 'LAN' ? 'lan' : mode === 'P2P' ? 'p2p' : 'turn'
}
export function wrapUpgradedTransportFrame(counter: number, ciphertext: Uint8Array): Uint8Array {
if (!Number.isSafeInteger(counter) || counter < 0) {
throw new Error('Upgraded transport counter must be a non-negative safe integer.')
}
const out = new Uint8Array(UPGRADE_SEQUENCE_HEADER_BYTES + ciphertext.byteLength)
out.set(UPGRADE_SEQ_MAGIC, 0)
const view = new DataView(out.buffer, out.byteOffset, UPGRADE_SEQUENCE_HEADER_BYTES)
view.setBigUint64(4, BigInt(counter), false)
out.set(ciphertext, UPGRADE_SEQUENCE_HEADER_BYTES)
return out
}
export function unwrapUpgradedTransportFrame(frame: Uint8Array): { counter: number; ciphertext: Uint8Array } {
if (
frame.byteLength < UPGRADE_SEQUENCE_HEADER_BYTES
|| frame[0] !== UPGRADE_SEQ_MAGIC[0]
|| frame[1] !== UPGRADE_SEQ_MAGIC[1]
|| frame[2] !== UPGRADE_SEQ_MAGIC[2]
|| frame[3] !== UPGRADE_SEQ_MAGIC[3]
) {
throw new Error('Invalid upgraded transport frame header.')
}
const view = new DataView(frame.buffer, frame.byteOffset, UPGRADE_SEQUENCE_HEADER_BYTES)
const rawCounter = view.getBigUint64(4, false)
if (rawCounter > BigInt(Number.MAX_SAFE_INTEGER)) {
throw new Error('Upgraded transport frame counter overflowed.')
}
return {
counter: Number(rawCounter),
ciphertext: frame.subarray(UPGRADE_SEQUENCE_HEADER_BYTES),
}
}
/**
* Bounded out-of-order ciphertext reorder buffer for cross-leg Noise switchovers.
* Enforces strict frame count, byte budget, and gap deadline limits.
*/
export class SequencedCiphertextReorderBuffer {
private readonly pending = new Map<number, Uint8Array>()
private bufferedBytes = 0
private gapTimer?: ReturnType<typeof setTimeout>
private gapCounter?: number
constructor(
private readonly options: {
maxFrames?: number
maxBytes?: number
gapTimeoutMs?: number
onGapTimeout: (missingCounter: number) => void
},
) {}
get size(): number { return this.pending.size }
get bytes(): number { return this.bufferedBytes }
push(counter: number, expectedCounter: number, ciphertext: Uint8Array): void {
if (!Number.isSafeInteger(counter) || counter <= expectedCounter) {
throw new Error('Ciphertext counter is duplicated or out of order.')
}
if (this.pending.has(counter)) {
throw new Error('Duplicate buffered ciphertext counter.')
}
const maxFrames = this.options.maxFrames ?? MAX_REORDER_BUFFERED_FRAMES
const maxBytes = this.options.maxBytes ?? MAX_REORDER_BUFFERED_BYTES
if (this.pending.size >= maxFrames || this.bufferedBytes + ciphertext.byteLength > maxBytes) {
throw new Error('Cross-transport reorder buffer exceeded its limit.')
}
const copy = new Uint8Array(ciphertext)
this.pending.set(counter, copy)
this.bufferedBytes += copy.byteLength
this.armGapTimer(expectedCounter)
}
takeNext(expectedCounter: number): Uint8Array | undefined {
const hit = this.pending.get(expectedCounter)
if (hit === undefined) {
if (this.pending.size === 0) this.clearGapTimer()
else this.armGapTimer(expectedCounter)
return undefined
}
this.pending.delete(expectedCounter)
this.bufferedBytes -= hit.byteLength
if (this.pending.size === 0) this.clearGapTimer()
else this.armGapTimer(expectedCounter + 1)
return hit
}
onExpectedAdvanced(nextExpectedCounter: number): void {
if (this.pending.size === 0) {
this.clearGapTimer()
return
}
this.armGapTimer(nextExpectedCounter)
}
clear(): void {
this.clearGapTimer()
this.pending.clear()
this.bufferedBytes = 0
}
private armGapTimer(expectedCounter: number): void {
if (this.gapCounter === expectedCounter && this.gapTimer !== undefined) return
this.clearGapTimer()
this.gapCounter = expectedCounter
const timeoutMs = this.options.gapTimeoutMs ?? DEFAULT_REORDER_GAP_TIMEOUT_MS
this.gapTimer = setTimeout(() => {
this.gapTimer = undefined
if (this.pending.size > 0) {
this.options.onGapTimeout(expectedCounter)
}
}, timeoutMs)
;(this.gapTimer as { unref?: () => void }).unref?.()
}
private clearGapTimer(): void {
if (this.gapTimer !== undefined) {
clearTimeout(this.gapTimer)
this.gapTimer = undefined
}
this.gapCounter = undefined
}
}