Files
deepseek-harness/packages/api/gateway/src/client/stream-client.ts
T

475 lines
16 KiB
TypeScript

import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
/** Browser owner for the Gateway multiplexed Remote stream socket. */
import {
parseRemoteStreamServerMessage,
REMOTE_STREAM_MUX_PATH,
type RemoteStreamClientMessage,
type RemoteStreamServerMessage,
} from '../stream-protocol.ts'
import { Deque } from '@deepseek-ai/dsh-deque'
import { randomUUID } from '@deepseek-ai/dsh-util-crypto'
/** Physical Remote stream socket failure that may be retried by a domain transport. */
export class RemoteStreamCarrierError extends Error {
/**
* @param message - physical carrier failure description.
* @param options - optional causal error.
*/
constructor(message: string, options?: ErrorOptions) {
super(message, options)
this.name = 'RemoteStreamCarrierError'
}
}
interface SocketWaiter {
readonly revision: number
resolve(socket: WebSocket): void
reject(error: unknown): void
}
interface UplinkPump {
/** Settles once the pump has stopped sending. */
readonly done: Promise<void>
/** Interrupt the pump, including a read blocked on the caller's iterator, and release the iterator. */
stop(): void
}
/** One open logical stream: its downlink frames and, once the `open` frame is out, its uplink pump. */
interface LogicalStream {
readonly inbox: StreamInbox
pump: UplinkPump | undefined
}
const UPLINK_DONE: IteratorReturnResult<undefined> = { value: undefined, done: true }
/**
* Keep one physical WebSocket and share it among independently cancellable
* Remote streams. A carrier that supplies an in-process stream opener never
* starts one.
*/
export class RemoteStreamMuxClient {
private socket: WebSocket | undefined
private cancelCandidate: ((error: Error) => void) | undefined
private keepAlive: Promise<void> | undefined
private revision = 0
private readonly streams = new Map<string, LogicalStream>()
private readonly waiters = new Set<SocketWaiter>()
private running = false
private disposed = false
/** Ensure a physical attempt exists, following the current attempt once if needed. */
start(): void {
if (this.disposed) return
this.running = true
if (this.socket?.readyState === WebSocket.OPEN) return
const pending = this.keepAlive
if (pending === undefined) this.maintain()
else void pending.then(() => { this.maintain() })
}
/** Cancel the current socket or retry wait and start a fresh attempt immediately. */
reconnect(): void {
if (!this.running || this.disposed) return
const failure = new RemoteStreamCarrierError('api gateway: Remote stream reconnect requested')
const pending = this.keepAlive
this.revision++
this.cancelCandidate?.(failure)
const socket = this.socket
if (socket !== undefined) {
this.socket = undefined
this.failAll(failure)
socket.close(4000, 'reconnect requested')
}
if (pending === undefined) this.maintain()
else void pending.then(() => { this.maintain() })
}
/**
* Open one logical stream on the persistent physical connection.
* If no physical attempt is active, opening waits for Connection to request
* one or for the signal to abort.
* @param endpoint - Typert Remote stream endpoint.
* @param payload - endpoint request encoded on the wire.
* @param signal - cancellation for this logical stream.
* @param uplink - the Client's items: each is sent as an `item` frame, its end as `end`; its `return()`
* runs when the stream finishes, and its failure cancels the stream and fails the downlink.
* @returns Host items until completion, cancellation, or failure.
*/
async *open(
endpoint: string,
payload: unknown,
signal: AbortSignal,
uplink?: AsyncIterable<unknown>,
): AsyncGenerator {
signal.throwIfAborted()
const streamId = randomUUID()
const inbox = new StreamInbox()
const stream: LogicalStream = { inbox, pump: undefined }
let carrier: WebSocket | undefined
let opened = false
let terminal = false
const abort = (): void => { inbox.fail(signal.reason) }
signal.addEventListener('abort', abort, { once: true })
try {
const socket = await this.waitForSocket(signal)
signal.throwIfAborted()
carrier = socket
this.streams.set(streamId, stream)
this.send(socket, { type: 'open', streamId, endpoint, payload })
opened = true
if (uplink !== undefined) stream.pump = this.pumpUplink(socket, streamId, uplink, signal, inbox)
while (true) {
const frame = await inbox.next()
signal.throwIfAborted()
if (frame.type === 'item') {
yield frame.value
continue
}
terminal = true
if (frame.type === 'error') {
throw new RemoteError(frame.error.code as never, frame.error.message, frame.error.details as never)
}
return
}
} finally {
signal.removeEventListener('abort', abort)
this.streams.delete(streamId)
stream.pump?.stop()
if (opened && !terminal && carrier?.readyState === WebSocket.OPEN) {
this.send(carrier, { type: 'cancel', streamId })
}
// The old generation's pump has stopped before a supervisor reopens the next one.
if (stream.pump !== undefined) await stream.pump.done
}
}
/**
* Send the caller's uplink items on this generation's socket. `stop()`
* interrupts a pump blocked on `uplink.next()` and releases the iterator: a
* handle's queue closes at once, so `send()` throws from then on, and any
* other iterator's `return()` is invoked without being awaited because a
* generator blocked in `next()` only completes it once it yields.
*/
private pumpUplink(
socket: WebSocket,
streamId: string,
uplink: AsyncIterable<unknown>,
signal: AbortSignal,
inbox: StreamInbox,
): UplinkPump {
const stopped = Promise.withResolvers<IteratorReturnResult<undefined>>()
const interruption: IteratorReturnResult<undefined> = { value: undefined, done: true }
const uplinkIterator = uplink[Symbol.asyncIterator]()
const state = { stopping: false, exhausted: false, released: false }
const release = (): void => {
if (state.released || state.exhausted) return
state.released = true
if (uplink instanceof ClientUplinkQueue) uplink.close()
void Promise.resolve().then(() => uplinkIterator.return?.()).catch(() => undefined)
}
const done = (async (): Promise<void> => {
try {
while (true) {
const next = await Promise.race([uplinkIterator.next(), stopped.promise])
if (state.stopping || next === interruption || signal.aborted || this.socket !== socket) return
if (next.done === true) {
state.exhausted = true
break
}
this.send(socket, { type: 'item', streamId, value: next.value })
}
this.send(socket, { type: 'end', streamId })
} catch (error) {
inbox.fail(error)
} finally {
release()
}
})()
return {
done,
stop: () => {
if (state.stopping) return
state.stopping = true
stopped.resolve(interruption)
release()
},
}
}
/**
* Permanently stop the carrier, close the physical socket, and fail every
* active logical stream.
* @returns once the active connection attempt has stopped.
*/
async close(): Promise<void> {
if (!this.disposed) {
this.disposed = true
this.running = false
const error = new Error('api gateway: Remote stream client disposed')
this.failAll(error)
for (const waiter of [...this.waiters]) waiter.reject(error)
this.cancelCandidate?.(error)
const socket = this.socket
this.socket = undefined
socket?.close(1000, 'disposed')
}
await this.keepAlive
}
private connect(): Promise<WebSocket> {
const socket = new WebSocket(remoteStreamUrl())
const connecting = new Promise<WebSocket>((resolve, reject) => {
let settled = false
const rejectCandidate = (error: Error): void => {
settled = true
socket.removeEventListener('open', opened)
socket.removeEventListener('error', failed)
socket.removeEventListener('message', received)
socket.removeEventListener('close', closed)
this.cancelCandidate = undefined
socket.close()
reject(error)
}
const opened = (): void => {
settled = true
this.cancelCandidate = undefined
this.socket = socket
for (const waiter of [...this.waiters]) waiter.resolve(socket)
resolve(socket)
}
const failed = (): void => {
if (!settled) {
rejectCandidate(new RemoteStreamCarrierError(
'api gateway: Remote stream WebSocket failed to open',
))
return
}
const error = new RemoteStreamCarrierError('api gateway: Remote stream WebSocket failed')
this.lost(socket, error)
socket.close()
}
const closed = (): void => {
if (!settled) {
rejectCandidate(new RemoteStreamCarrierError(
'api gateway: Remote stream WebSocket closed before opening',
))
return
}
this.lost(socket)
}
const received = (event: MessageEvent): void => { this.receive(socket, event.data) }
this.cancelCandidate = rejectCandidate
socket.addEventListener('open', opened, { once: true })
socket.addEventListener('error', failed, { once: true })
socket.addEventListener('message', received)
socket.addEventListener('close', closed, { once: true })
})
return connecting
}
private waitForSocket(signal: AbortSignal): Promise<WebSocket> {
signal.throwIfAborted()
if (this.socket?.readyState === WebSocket.OPEN) return Promise.resolve(this.socket)
if (this.disposed) return Promise.reject(new Error('api gateway: Remote stream client disposed'))
if (!this.running) return Promise.reject(new Error('api gateway: Remote stream client not started'))
return new Promise((resolve, reject) => {
const aborted = (): void => { waiter.reject(signal.reason) }
const cleanup = (): void => {
this.waiters.delete(waiter)
signal.removeEventListener('abort', aborted)
}
const waiter: SocketWaiter = {
revision: this.revision,
resolve: (socket) => {
cleanup()
resolve(socket)
},
reject: (error) => {
cleanup()
// AbortSignal.reason belongs to the caller and may intentionally be a non-Error sentinel.
// oxlint-disable-next-line typescript/prefer-promise-reject-errors
reject(error)
},
}
this.waiters.add(waiter)
signal.addEventListener('abort', aborted, { once: true })
})
}
private receive(socket: WebSocket, data: unknown): void {
if (socket !== this.socket) return
try {
if (typeof data !== 'string') throw new Error('api gateway: Remote stream WebSocket requires text messages')
const frame = parseRemoteStreamServerMessage(data)
const stream = this.streams.get(frame.streamId)
if (stream === undefined) return
stream.inbox.push(frame)
// A terminal frame ends the uplink now, not on the consumer's next read.
if (frame.type !== 'item') stream.pump?.stop()
} catch (error) {
const failure = new RemoteStreamCarrierError('api gateway: invalid Remote stream frame', { cause: error })
this.failAll(failure)
this.lost(socket, failure)
socket.close(4002, 'invalid Remote stream frame')
}
}
private lost(
socket: WebSocket,
error: RemoteStreamCarrierError = new RemoteStreamCarrierError(
'api gateway: Remote stream WebSocket closed',
),
): void {
if (this.socket !== socket) return
this.socket = undefined
this.failAll(error)
}
private maintain(): void {
if (!this.running || this.disposed) return
if (this.socket?.readyState === WebSocket.OPEN || this.keepAlive !== undefined) return
const revision = this.revision
const task = this.connect().then(
() => undefined,
(error: unknown) => {
if (!this.running) return
for (const waiter of [...this.waiters]) {
if (waiter.revision <= revision) waiter.reject(error)
}
},
)
this.keepAlive = task
void task.then(() => {
this.keepAlive = undefined
})
}
private failAll(error: unknown): void {
for (const stream of this.streams.values()) {
stream.inbox.fail(error)
stream.pump?.stop()
}
}
private send(socket: WebSocket, message: RemoteStreamClientMessage): void {
socket.send(JSON.stringify(message))
}
}
class StreamInbox {
private readonly frames = new Deque<RemoteStreamServerMessage>()
private wake: (() => void) | undefined
private failure: Error | undefined
push(frame: RemoteStreamServerMessage): void {
if (this.failure !== undefined) return
this.frames.pushBack(frame)
this.wake?.()
this.wake = undefined
}
fail(error: unknown): void {
if (this.failure !== undefined) return
this.failure = error instanceof Error ? error : new Error(String(error), { cause: error })
this.frames.clear()
this.wake?.()
this.wake = undefined
}
async next(): Promise<RemoteStreamServerMessage> {
while (this.frames.size === 0) {
if (this.failure !== undefined) throw this.failure
await new Promise<void>((resolve) => { this.wake = resolve })
}
return this.frames.popFront() as RemoteStreamServerMessage
}
}
/**
* Uplink items a stream handle queues for its carrier: the mux pump or the
* in-process Host decoder iterates it as the stream's uplink. `end()` is the
* Client half-close; `close()` marks the stream terminated, after which
* `push()` throws. One consumer reads it, one read at a time.
*/
export class ClientUplinkQueue implements AsyncIterable<unknown>, AsyncIterator<unknown> {
private readonly items = new Deque<unknown>()
private ended = false
private closed = false
private wake: (() => void) | undefined
/** @param endpoint - canonical Remote endpoint named by failures. */
constructor(private readonly endpoint: string) {}
/**
* Queue one item for the carrier.
* @param item - item the Host validates against the method's uplink codec.
* @throws {Error} after `end()` or once the stream has terminated.
*/
push(item: unknown): void {
if (this.closed) throw new Error(`client api: ${this.endpoint} stream has terminated`)
if (this.ended) throw new Error(`client api: ${this.endpoint} uplink was ended`)
this.items.pushBack(item)
this.signal()
}
/** Half-close: the carrier reads the queued items, then `end`. Idempotent; ignored after termination. */
end(): void {
if (this.ended || this.closed) return
this.ended = true
this.signal()
}
/** The carrier stopped reading: the logical stream terminated or was disposed. Idempotent. */
close(): void {
if (this.closed) return
this.closed = true
this.items.clear()
this.signal()
}
[Symbol.asyncIterator](): AsyncIterator<unknown> {
return this
}
/**
* Take the next queued item, waiting for one; ends after `end()` or `close()`.
* @returns the next item, or the end of the uplink.
* @throws {Error} when a read is already pending.
*/
async next(): Promise<IteratorResult<unknown>> {
while (true) {
if (this.closed) return UPLINK_DONE
if (this.items.size > 0) return { value: this.items.popFront(), done: false }
if (this.ended) return UPLINK_DONE
if (this.wake !== undefined) throw new Error(`client api: ${this.endpoint} uplink has one pending read`)
await new Promise<void>((resolve) => { this.wake = resolve })
}
}
/**
* The carrier is done with the uplink: close it.
* @returns the end of the uplink.
*/
return(): Promise<IteratorResult<unknown>> {
this.close()
return Promise.resolve(UPLINK_DONE)
}
private signal(): void {
const wake = this.wake
this.wake = undefined
wake?.()
}
}
function remoteStreamUrl(): string {
// The mux route is registered absolute; a page resolves its document-relative
// form against its own document base. A shell-owned Host on another origin
// supplies that base through the transport.
const globals = globalThis as { __DSH_TRANSPORT__?: { streamBaseUrl?: string } }
const url = new URL(REMOTE_STREAM_MUX_PATH.slice(1), globals.__DSH_TRANSPORT__?.streamBaseUrl ?? document.baseURI)
url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
return url.href
}