The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* The gateway in its own process, as the core sees it (docs/design/2026-10-06-core-boundary-next.md, step
* 10, R2; the process's side is gateway/gatewayProcess.ts). The relay, the E2EE sessions and every key
* live there; the core keeps what it must read in line, as the gateway last said it, and sends what it has
* for remote clients in the clear, over the service link only the master's token opens.
*
* - What the core reads synchronously is kept here from the gateway's notices: whether the backend link
* is up, and the remote clients it holds a session with (the socket keeps their roles and labels).
* - What the core has for a remote client goes to the gateway as it is, never held: a frame the gateway
* is not there to seal is a frame no remote client could have got. While the gateway reads nothing
* (hung), what would pile up on the socket to it is dropped at GATEWAY_BUFFER_LIMIT and said once a
* minute; the master kills a hung gateway soon after.
* - The gateway gone (crashed, killed, restarting) is the relay gone: every remote client with it, the
* link down, no device watching. A window working on another machine through it is closed, and opens
* again on its own. The windows on this computer and the agents never notice.
* - Each time the gateway connects it is told everything it starts from (`start`): it builds its relay
* afresh, as a core's restart did when the relay ran in the core.
*/
import { RelayConnectError } from '../lib/relayFrames.js'
import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS } from '../lib/gatewayWire.js'
import { decodeTerminalLocal, encodeTerminalLocal } from '../lib/terminalBinary.js'
import { answerAccountQuery } from './accountQueries.js'
import { guestMachineList, withStaleMarker } from '../lib/machineListReply.js'
import type { GatewayMachines } from './api.js'
import { LANE_OFF } from './api.js'
import type {
BackendNotice, GatewayEvents, LocalWindows, GatewayOps, GatewayPort, GatewayRefusal, GatewayStatus, HttpAnswer, LaneSeal,
RemoteClient, RemoteRole, RemoteTransport, TabFrame, TabKey, TabRelay, WindowRelay, WindowRelaySession, WindowRelaySink,
} from './api.js'
import { askTabKey } from '../lib/tabKeyWire.js'
import { askTabRelay, tabFrameOf } from '../lib/tabRelayWire.js'
import { ON_DEMAND_START_MS, type ServiceFrame } from './serviceLinks.js'
export interface GatewayLinkDeps {
/** The core's side of what the gateway tells it (BackendSocket's `fromGateway`). */
events: GatewayEvents
/** The service link to the gateway (core/serviceLinks.ts, for `gateway`). */
notify(frame: ServiceFrame): boolean
notifyBinary(bytes: Uint8Array): boolean
buffered(): number
call(type: string, payload: Record<string, unknown>, waitMs?: number): Promise<Record<string, unknown>>
/** What the gateway starts from each time it connects: this machine's ids, whether it is signed in. */
start(): Record<string, unknown>
/** The account's tokens (`core.account`): the gateway asks for one each time it dials, and holds none. */
tokens: { accessToken(opts?: { force?: boolean; failedToken?: string }): Promise<string> }
/** A read of the backend's REST API under the account's session (the core's proxy). */
backend(method: 'GET', path: string): Promise<HttpAnswer>
/** The last machine list reported by the gateway, for the models service's presence labels. */
machines?(state: GatewayMachines): void
/** Ask the master for the gateway's process (harnessd/coreLink.ts `want`): it runs on demand (core/gatewayWake.ts). */
want?(): void
/** How long what waits for the gateway's first start waits (core/serviceLinks.ts `ON_DEMAND_START_MS`). */
startWaitMs?: number
newId?: () => string
now?: () => number
log?: (line: string) => void
}
/** Bytes waiting on the socket to the gateway past which a frame for remote clients is dropped. A hung
* gateway reads nothing for up to its heartbeat deadline (30 s); every event and terminal byte for
* remote clients would wait in the core's memory meanwhile. */
export const GATEWAY_BUFFER_LIMIT = 16 * 1024 * 1024
/** Optional counters yield long before relay traffic does. Never queue measurements for a restart. */
export const GATEWAY_USAGE_BUFFER_LIMIT = 64 * 1024
/** How long a pairing may take: the code is typed on one screen and checked over the relay, round by round. */
export const PAIR_WAIT_MS = 120_000
/** The close a window on another machine gets when the gateway it went through is gone: try again shortly. */
export const WINDOW_GATEWAY_GONE = 1013
/** The most a window's E2EE requests and sessions to open wait for the gateway's first start; the oldest go. */
export const OWED_MAX = 256
/** How long the fleet's lane waits on the gateway to seal or open a frame. The frames behind it wait too,
* in order; a gateway that has not answered in this long is hung, and the master ends it soon after. */
export const LANE_WAIT_MS = 5_000
/** How long a shared tab's relay call waits on the gateway: a send there answers within 8 s of being asked
* (gateway/tabRelay.ts `TAB_RELAY_SEND_DEADLINE_MS`: the relay admitting its socket, then its turn within the rate),
* so the gateway's answer is the one the core gives, and a frame answered false here is never sent there. */
export const TAB_RELAY_WAIT_MS = 10_000
const UNAVAILABLE: HttpAnswer = { status: 503, body: { error: 'GATEWAY_UNAVAILABLE' } }
interface Window {
sink: WindowRelaySink
onClosed: (code: number, reason: string) => void
opening: { resolve: (session: WindowRelaySession) => void; reject: (error: Error) => void } | null
}
const text = (value: unknown): string => (typeof value === 'string' ? value : '')
const record = (value: unknown): Record<string, unknown> =>
(value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {})
export function createGatewayLink(deps: GatewayLinkDeps) {
const { events } = deps
const log = deps.log ?? ((line: string) => console.warn(line))
const now = deps.now ?? Date.now
let counter = 0
const newId = deps.newId ?? (() => `window-${++counter}`)
/** The gateway's process is connected to this core. */
let up = false
/** It has connected in this core's life. Before that it runs on demand: what needs it asks for it, once, and
* what a window asked of it meanwhile (an E2EE request, a session to another machine) waits for it, in order,
* to be told after its `start`. Gone again later it is the master's to restart, and nothing waits. */
let seen = false
let asked = false
const owed: Array<Record<string, unknown>> = []
let owedTimer: ReturnType<typeof setTimeout> | null = null
/** The backend link, as the gateway last said. */
let linkUp = false
// What the gateway is told again whenever it connects.
let requestsOpen = true
let dial: 'connect' | 'local' | null = null
let localClients: LocalWindows = { desktop: 0, tui: 0 }
let wifiService = false
let reachable: string[] | null = null
let machines: GatewayMachines | null = null
/** The remote clients the gateway registered, to forget each when it goes. */
const clients = new Set<string>()
const windows = new Map<string, Window>()
const localRequests = new Map<string, { fail(): void; finish(): void }>()
let droppedSaidAt = -Infinity
let droppedUnsaid = 0
const send = (kind: string, payload: Record<string, unknown> = {}): boolean =>
up && deps.notify({ type: 'service_event', payload: { ...payload, kind } })
/** A frame for remote clients: dropped rather than held while the gateway reads nothing. */
const fits = (): boolean => {
if (deps.buffered() <= GATEWAY_BUFFER_LIMIT) return true
const at = now()
if (at - droppedSaidAt < 60_000) droppedUnsaid++
else {
log(`[gateway] it is not reading: frames for remote clients dropped${droppedUnsaid ? ` · ${droppedUnsaid} more since` : ''}`)
droppedSaidAt = at
droppedUnsaid = 0
}
return false
}
const bulk = (kind: string, payload: Record<string, unknown>): boolean => up && fits() && send(kind, payload)
const reachableClient = (connId: string): boolean => up && clients.has(connId)
const need = (): void => {
if (up || seen || asked) return
asked = true
deps.want?.()
}
const localKey = (connId: string, type: unknown, requestId: unknown): string | null =>
requestId === undefined ? null : JSON.stringify([connId, type, requestId])
const refuseLocal = (connId: string, frame: Record<string, unknown>): void => {
const requestId = record(frame.payload).requestId
if (requestId !== undefined) events.toLocal(connId, {
type: `${frame.type}_result`, payload: { requestId, error: 'SERVICE_UNAVAILABLE', service: 'gateway', retryable: true },
})
}
/** Chaos testing killed the gateway between a local request and its reply. The core must answer for a
* lost link, including in-flight requests; the window's longer deadline is not a service fallback.
* Bound both the wait and the number held, and never replay a pairing or revocation after a restart. */
const forwardLocal = (connId: string, frame: Record<string, unknown>): void => {
const key = localKey(connId, `${frame.type}_result`, record(frame.payload).requestId)
if (key !== null) {
if (localRequests.has(key)) return
if (localRequests.size >= OWED_MAX) { refuseLocal(connId, frame); return }
const finish = (): void => { clearTimeout(timer); localRequests.delete(key) }
const fail = (): void => { finish(); refuseLocal(connId, frame) }
const timer = setTimeout(fail, frame.type === 'phone_pair' || frame.type === 'device_e2ee_pair' ? PAIR_WAIT_MS : LANE_WAIT_MS)
timer.unref?.()
localRequests.set(key, { fail, finish })
}
if (!send('localFrame', { connId, frame }) && key !== null) localRequests.get(key)!.fail()
}
/** What waits for the first start gives up explicitly: no late pairing or window open after refusal. */
const giveUp = (item: Record<string, unknown>): void => {
if (item.kind === 'windowOpen') closeWindow(text(item.id), WINDOW_GATEWAY_GONE, 'the relay did not start')
else refuseLocal(text(item.connId), record(item.frame))
}
const owe = (kind: string, payload: Record<string, unknown>): void => {
owed.push({ ...payload, kind })
if (owed.length > OWED_MAX) giveUp(owed.shift()!)
need()
owedTimer ??= setTimeout(() => { owedTimer = null; for (const item of owed.splice(0)) giveUp(item) }, deps.startWaitMs ?? ON_DEMAND_START_MS)
owedTimer.unref?.()
}
const port: GatewayPort = {
usageLaunch: (signal) => { if (deps.buffered() < GATEWAY_USAGE_BUFFER_LIMIT) send('usageLaunch', { signal }) },
usageCounter: (metric) => { if (deps.buffered() < GATEWAY_USAGE_BUFFER_LIMIT) send('usageCounter', { metric }) },
connect: () => { dial = 'connect'; need(); send('connect') },
serveThisComputerOnly: () => { dial = 'local'; send('thisComputerOnly') },
holdRequests: () => { requestsOpen = false; send('hold') },
openRequests: () => { requestsOpen = true; send('open') },
connected: () => up && linkUp,
broadcast: (frame, guest) => { bulk('broadcast', guest ? { frame, guest } : { frame }) },
commander: (frame) => { bulk('commander', { frame }) },
user: (frame) => { send('user', { frame }) },
reply: (connId, type, requestId, payload) => { send('reply', { connId, type, requestId, payload }) },
target: (connId, type, payload) => up && linkUp && clients.has(connId) && bulk('target', { connId, type, payload }),
terminal: (connId, type, payload) => reachableClient(connId) && bulk('terminal', { connId, type, payload }),
terminalBinary: (connId, clear) => {
if (!reachableClient(connId) || !fits()) return false
const local = encodeTerminalLocal(clear)
const bytes = local && encodeGatewayBinary(GatewayBinary.remote, connId, local)
return !!bytes && deps.notifyBinary(bytes)
},
observer: (connId, type, payload) => up && linkUp && send('observer', { connId, type, payload }),
windowOpened: (surface) => { send('windowOpened', { surface }) },
localClients: (windows) => { localClients = windows; send('localClients', { windows }) },
local: async (connId, frame) => { if (up || seen) forwardLocal(connId, frame); else owe('localFrame', { connId, frame }) },
device: (connId, type, payload) => reachableClient(connId) && send('device', { connId, type, payload }),
deviceClient: (connId, identity) => { send('deviceClient', { connId, identity }) },
stop: async () => { send('stop') },
}
const http = async (type: string, payload: Record<string, unknown> = {}, waitMs?: number): Promise<HttpAnswer> => {
const answer = await deps.call(type, payload, waitMs)
if (typeof answer.status !== 'number') return UNAVAILABLE
// A busy answer's Retry-After (gateway/accountHttp.ts), which the daemon passes on to the Desktop's reports.
const retry = answer.retryAfterMs
return { status: answer.status, body: record(answer.body),
...(typeof retry === 'number' && Number.isFinite(retry) && retry >= 0 ? { retryAfterMs: retry } : {}) }
}
/**
* The fleet's lane's sessions, in the gateway (gateway/lane.ts). Every one of them is a call, the lane's
* drop too, so the gateway takes them in the order the lane made them. A gateway that is not there
* starts no session and seals nothing: the lane hears `lost`, never its frame back as it was.
*/
const lane = (op: string, payload: Record<string, unknown> = {}) => deps.call(GATEWAY_CALLS.lane, { ...payload, op }, LANE_WAIT_MS)
const laneOps: LaneSeal = {
hello: async (machineId, peerPub) => {
const answer = await lane('hello', { machineId, peerPub })
if (answer.frame && typeof answer.frame === 'object') return record(answer.frame)
throw new Error('the gateway could not start an E2EE session: it is not running')
},
welcome: async (machineId, payload) => (await lane('welcome', { machineId, payload })).ok === true,
rekey: async (machineId, payload) => { await lane('rekey', { machineId, payload }) },
seal: async (machineId, frame) => {
const answer = await lane('seal', { machineId, frame })
return answer.frame && typeof answer.frame === 'object' ? { frame: record(answer.frame) } : { lost: true }
},
open: async (machineId, frame) => {
const answer = await lane('open', { machineId, frame })
if (answer.frame && typeof answer.frame === 'object') return { frame: record(answer.frame) }
if (answer.unknownEpoch === true) return { unknownEpoch: true }
return answer.unreadable === true ? { unreadable: true } : { lost: true }
},
drop: (machineId) => { void lane('drop', { machineId }) },
}
/** Share's owner's key, held by the gateway (gateway/observerKey.ts): each a call; none while it is away. */
const ownerKey = async (payload: Record<string, unknown>): Promise<string> => {
const answer = await deps.call(GATEWAY_CALLS.observerKey, payload, LANE_WAIT_MS)
if (typeof answer.key === 'string') return answer.key
// Its process down, or its gateway not started yet: no key to sign with.
throw new Error(typeof answer.error === 'string' && !answer.error.startsWith('SERVICE_') ? answer.error : 'the gateway holds no key just now: it is not running')
}
/** Shared tabs' keys, held by the gateway (gateway/tabKey.ts): one call a method, the drop too, so the gateway takes
* them in the order Agent Messages made them. While it is away: no signature, no session, nothing sealed. */
const tabKeyOps: TabKey = askTabKey((payload) => deps.call(GATEWAY_CALLS.tabKey, payload, LANE_WAIT_MS))
/** Shared tabs' relay, whose sockets the gateway holds (gateway/tabRelay.ts): one call a method. While it is away,
* nothing is opened or sent; what the sockets hear comes back as `tabFrame` notices. */
const tabRelayOps: TabRelay = askTabRelay((payload) => deps.call(GATEWAY_CALLS.tabRelay, payload, TAB_RELAY_WAIT_MS))
const ops: GatewayOps = {
backend: (method, path, body) => http(GATEWAY_CALLS.backend, { method, path, ...(body === undefined ? {} : { body }) }, 25_000),
machines: async (fallback = false) => {
const state = deps.start()
const requestedOwner = text(record(state.account).machineId)
if (!requestedOwner) {
const body = guestMachineList(text(state.computerId), text(state.machineName), text(state.hostname))
deps.machines?.({ owner: null, body, fetchedAt: now() })
return { status: 200, body }
}
const answer = await http(GATEWAY_CALLS.machines, { fallback }, 25_000)
const currentOwner = text(record(deps.start().account).machineId)
if (requestedOwner !== currentOwner) return { status: 409, body: { success: false, error: { code: 'ACCOUNT_CHANGED', message: 'The account changed. Refresh and try again.' } } }
if (answer.status === 401 || answer.status === 403) machines = null
const owner = currentOwner
// A crashed gateway costs the network, not the app's last known roster. Never cross accounts or
// hide a real sign-out with rows cached for an earlier session.
if (fallback && answer.status >= 500 && owner && machines?.owner === owner && machines.body) {
return { status: 200, body: withStaleMarker(machines.body, machines.fetchedAt) }
}
return answer
},
mintGridName: async () => {
const answer = await deps.call(GATEWAY_CALLS.mintGridName, {}, 15_000)
if (typeof answer.error === 'string') throw new Error(answer.error)
return typeof answer.name === 'string' ? answer.name : null
},
status: async (): Promise<GatewayStatus> => {
// Never started, it has no pairing under way and nothing to say; `/api/status` is asked far too often to
// start it for.
if (!up && !seen) return { fingerprint: null, pairs: [], pending: null }
const answer = await deps.call(GATEWAY_CALLS.status, {}, 2_000)
return {
fingerprint: typeof answer.fingerprint === 'string' ? answer.fingerprint : null,
pairs: Array.isArray(answer.pairs) ? answer.pairs as Array<Record<string, unknown>> : [],
pending: answer.pending && typeof answer.pending === 'object' ? answer.pending as Record<string, unknown> : null,
}
},
pair: (code) => http(GATEWAY_CALLS.pair, { code }, PAIR_WAIT_MS),
listPairs: () => http(GATEWAY_CALLS.listPairs),
revoke: (id) => http(GATEWAY_CALLS.revoke, { id }),
revokeAll: () => http(GATEWAY_CALLS.revokeAll),
setRemotePassword: (password) => http(GATEWAY_CALLS.setRemotePassword, { password }),
clearRemotePassword: () => http(GATEWAY_CALLS.clearRemotePassword),
remotePasswordStatus: () => http(GATEWAY_CALLS.remotePasswordStatus),
trustLinkedPeer: (peer) => http(GATEWAY_CALLS.trustLinkedPeer, { peer }),
groupList: () => http(GATEWAY_CALLS.groupList),
groupSync: () => http(GATEWAY_CALLS.groupSync),
groupRemove: (selector) => http(GATEWAY_CALLS.groupRemove, { selector }),
devicesList: () => http(GATEWAY_CALLS.devicesList),
devicesRemove: (pub) => http(GATEWAY_CALLS.devicesRemove, { pub }),
devicesHistory: () => http(GATEWAY_CALLS.devicesHistory),
devicesDismiss: (body) => http(GATEWAY_CALLS.devicesDismiss, { body }),
devicesRebaseline: (confirm, head) => http(GATEWAY_CALLS.devicesRebaseline, { confirm, ...(head ? { head } : {}) }),
wifi: async (request) => {
const answer = await deps.call(GATEWAY_CALLS.wifi, request, request.op === 'pair' ? PAIR_WAIT_MS : undefined)
if (answer.result && typeof answer.result === 'object') return { result: answer.result as Record<string, unknown> }
const refused = record(answer.refused)
const why: GatewayRefusal = typeof refused.code === 'string'
? { code: refused.code, message: text(refused.message) }
: { code: 'UNAVAILABLE', message: 'The Wi-Fi device link is not reachable on this computer right now. Try again.' }
return { refused: why }
},
wifiService: (on) => { wifiService = on; if (on) need(); send('wifiService', { on }) },
revokeIdentity: (identity) => { send('revokeIdentity', { identity }) },
account: (next) => {
if (machines && machines.owner !== next.machineId) {
machines = null
deps.machines?.({ owner: next.machineId, body: null, fetchedAt: now() })
}
send('account', { account: next })
},
reachable: (machineIds) => { reachable = machineIds; send('reachable', { machineIds }) },
lane: laneOps,
observerKey: {
publicKey: () => ownerKey({ op: 'public' }),
signWelcome: (machineId, shareId, peer, ephemeral) => ownerKey({ op: 'sign', machineId, shareId, peer, ephemeral }),
},
tabKey: tabKeyOps,
tabRelay: tabRelayOps,
// The account's connected services, sealed and opened by the gateway (lib/e2ee/connectorVault.ts).
connectorVault: {
seal: async (plaintext) => {
const answer = await deps.call(GATEWAY_CALLS.connectorVault, { op: 'seal', plaintext }, LANE_WAIT_MS)
if (answer.envelope && typeof answer.envelope === 'object') return record(answer.envelope)
throw new Error(typeof answer.error === 'string' && !answer.error.startsWith('SERVICE_') ? answer.error : 'the gateway holds no key just now: it is not running')
},
open: async (envelope) => {
const answer = await deps.call(GATEWAY_CALLS.connectorVault, { op: 'open', envelope }, LANE_WAIT_MS)
return typeof answer.plaintext === 'string' ? { plaintext: answer.plaintext, complete: answer.complete === true } : null
},
},
// Machines shared across accounts, pinned and trusted by the gateway (gateway/sharedTrust.ts).
sharedTrust: async (desired) => {
const answer = await deps.call(GATEWAY_CALLS.sharedTrust, { ...desired }, LANE_WAIT_MS)
if (typeof answer.pins === 'number' && typeof answer.keys === 'number') return { pins: answer.pins, keys: answer.keys }
throw new Error(typeof answer.error === 'string' && !answer.error.startsWith('SERVICE_') ? answer.error : 'the gateway is not running')
},
}
/** A window's session through the gateway: to another of the owner's machines, or to a harness shared
* with this account (`share`). */
const openWindow = (open: Record<string, unknown>, sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
new Promise((resolve, reject) => {
if (!up && seen) { reject(new RelayConnectError('the relay is restarting', WINDOW_GATEWAY_GONE)); return }
const id = newId()
windows.set(id, { sink, onClosed, opening: { resolve, reject } })
if (up) send('windowOpen', { ...open, id })
else owe('windowOpen', { ...open, id })
})
const open = (isolated: boolean) => (machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>,
sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
openWindow({ machineId, autonomousEnv, frame: selectFrame, isolated }, sink, onClosed)
const sessionOf = (id: string): WindowRelaySession => ({
send: async (frame) => { send('windowSend', { id, frame }) },
sendBinary: async (clear) => {
const local = encodeTerminalLocal(clear)
const bytes = local && encodeGatewayBinary(GatewayBinary.window, id, local)
if (bytes && up) deps.notifyBinary(bytes)
},
detach: () => { if (windows.delete(id)) send('windowDetach', { id }) },
})
const windowRelay: WindowRelay = {
acquire: open(false),
acquireIsolated: open(true),
invalidate: (machineId) => { send('windowInvalidate', { machineId, isolated: false }) },
invalidateIsolated: (machineId) => { send('windowInvalidate', { machineId, isolated: true }) },
acquireShare: (machineId, shareId, sink, onClosed) => openWindow({ machineId, share: shareId }, sink, onClosed),
}
/** A window's connection ended, from the gateway's side or because the gateway went. */
const closeWindow = (id: string, code: number, reason: string): void => {
const window = windows.get(id)
if (!window) return
windows.delete(id)
if (window.opening) window.opening.reject(new RelayConnectError(reason, code))
else window.onClosed(code, reason)
}
/** What the gateway tells the core (`service_notice`): trusted as the gateway's, the master's token
* having opened the link, but read as data, never thrown on. */
const notice = (payload: Record<string, unknown>): void => {
const connId = text(payload.connId)
switch (payload.kind) {
case 'frame':
void events.frame(connId, record(payload.frame), payload.transport === 'p2p' ? 'p2p' : 'relay' as RemoteTransport,
payload.role === 'web' ? 'web' : 'device' as RemoteRole)
return
case 'client': {
const client = payload.client ? record(payload.client) as unknown as RemoteClient : null
if (client) clients.add(connId)
else clients.delete(connId)
events.client(connId, client)
return
}
case 'disconnected':
clients.delete(connId)
void events.disconnected(connId)
return
case 'observer':
void events.observer(connId, text(payload.type), record(payload.payload))
return
case 'toLocal': {
const frame = record(payload.frame)
const key = localKey(connId, frame.type, record(frame.payload).requestId)
if (key !== null) localRequests.get(key)?.finish()
events.toLocal(connId, frame)
return
}
case 'status':
linkUp = payload.connected === true
events.status(linkUp)
return
case 'linkDown':
events.linkDown()
return
case 'commanders':
events.commanders(Number(payload.count) || 0, typeof payload.active === 'number' ? payload.active : null, payload.recheck === true)
return
case 'commanderJoined':
events.commanderJoined()
return
case 'meta':
events.meta(record(payload.meta) as { name?: string | null; gridName?: string | null })
return
case 'notice':
events.notice(record(payload.notice) as unknown as BackendNotice)
return
case 'machines': {
const owner = text(payload.owner) || null
if (owner !== (text(record(deps.start().account).machineId) || null)) return
const body = payload.body && typeof payload.body === 'object' && !Array.isArray(payload.body) ? record(payload.body) : null
machines = { owner, body,
fetchedAt: typeof payload.fetchedAt === 'number' && Number.isFinite(payload.fetchedAt) && Math.abs(payload.fetchedAt) <= 8.64e15 ? payload.fetchedAt : now() }
deps.machines?.(machines)
return
}
case 'revoked':
events.revoked()
return
case 'busy':
events.busy()
return
case 'device':
void events.device(connId, record(payload.frame), payload.opened ? record(payload.opened) : null)
return
case 'deviceRevoked':
events.deviceRevoked(text(payload.identity))
return
case 'toWindows':
events.toWindows(record(payload.frame))
return
case 'tabFrame': {
const event = tabFrameOf(payload.event)
if (event) events.tabFrame(event)
return
}
case 'windowOpened': {
const window = windows.get(text(payload.id))
if (!window?.opening) return
const { resolve } = window.opening
window.opening = null
resolve(sessionOf(text(payload.id)))
return
}
case 'windowFailed':
case 'windowClosed':
closeWindow(text(payload.id), typeof payload.code === 'number' ? payload.code : 1011, text(payload.reason) || 'relay failed')
return
case 'windowFrame':
windows.get(text(payload.id))?.sink.sendFrame(record(payload.frame))
return
default:
log(`[gateway] an unknown notice from the gateway was ignored: ${JSON.stringify(String(payload.kind)).slice(0, 80)}`)
}
}
const binary = (raw: Uint8Array): void => {
const decoded = decodeGatewayBinary(raw)
if (!decoded) return
if (decoded.kind === GatewayBinary.window) { windows.get(decoded.id)?.sink.sendBinary(decoded.bytes); return }
const clear = decodeTerminalLocal(decoded.bytes)
if (clear) void events.binary(decoded.id, clear)
}
/**
* What the gateway asks the core (`service_query`): a token to dial with, the device key log's reads of
* the backend, and the harnesses shared with this account (the Share relay finds a share among them
* before it dials). Nothing else: the gateway is the relay, and the core's own REST reads are not its to
* make. A refused token comes back as the session's own error, so the gateway can tell a session that
* is over (stop for good) from one that could not be refreshed just now (try again).
*/
const answer = async (query: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> => {
// The gateway is the lane's seal, never a lane of its own: it is answered tokens, and no lane step.
if (query === 'access_token') return (await answerAccountQuery({ accessToken: (options) => deps.tokens.accessToken(options), lane: LANE_OFF }, query, payload))!
if (query === 'backend' && payload.method === 'GET' && (text(payload.path).startsWith('/api/device-keys') || payload.path === '/api/harness-shares')) {
return { ...await deps.backend('GET', text(payload.path)) }
}
return { error: 'UNKNOWN_QUERY' }
}
return {
port,
ops,
windowRelay,
notice,
binary,
answer,
/** The core is stopping: the gateway closes its link to the backend (its process is the master's to end). */
stop: (): Promise<void> => port.stop(),
/** The gateway's process connected: it starts from everything it is told here, each time. */
connected(): void {
// A gateway that connects again without the core having seen it go (its link replaced) started afresh
// all the same: what the core kept of the last one goes first.
if (up) this.disconnected()
up = true
seen = true
// The account as the core reads it now (`start`), which is never older than the last one it said.
send('start', { requestsOpen, dial, localClients, wifiService, reachable, ...deps.start() })
// Then what waited for its first start, in the order it came.
if (owedTimer) clearTimeout(owedTimer)
owedTimer = null
for (const { kind, ...payload } of owed.splice(0)) {
if (kind === 'localFrame') forwardLocal(text(payload.connId), record(payload.frame))
else send(text(kind), payload)
}
},
/** The gateway's process went: the relay with it, as far as everything in the core is concerned. */
disconnected(): void {
up = false
for (const request of localRequests.values()) request.fail()
for (const id of [...windows.keys()]) closeWindow(id, WINDOW_GATEWAY_GONE, 'the relay restarted')
// Each remote client's connection ended with it: what it had open here goes (its terminals, its
// viewers, the Wi-Fi device service's hold on it).
for (const connId of [...clients]) { clients.delete(connId); void events.disconnected(connId) }
events.linkDown()
events.commanders(0, null)
if (linkUp) { linkUp = false; events.status(false) }
},
}
}
export type GatewayLink = ReturnType<typeof createGatewayLink>
/** The lane's sessions as the core hands them to its services (`core.account.lane`): read from the gateway
* each time, because the core's API is built before the gateway is started. */
export function laneOf(gateway: () => LaneSeal): LaneSeal {
return {
hello: (machineId, peerPub) => gateway().hello(machineId, peerPub),
welcome: (machineId, payload) => gateway().welcome(machineId, payload),
rekey: (machineId, payload) => gateway().rekey(machineId, payload),
seal: (machineId, frame) => gateway().seal(machineId, frame),
open: (machineId, frame) => gateway().open(machineId, frame),
drop: (machineId) => gateway().drop(machineId),
}
}
/**
* Shared tabs' relay as the core hands it to its services (`core.account.tabRelay`): read from the gateway each time, as
* the lane is (`laneOf`). The core keeps which tabs were opened and not closed since (`opened`), because the sockets
* and the service that wants them can each go without the other noticing:
* - The gateway alone restarting drops every socket without a word to Agent Messages, which would hear nothing more
* from its tabs until its next refresh: as the gateway connects again, every tab opened is opened again
* (`connected`). Its first connection opens nothing: every open went to it then.
* - A tab the relay closed for good (`closed`: 4403, 4409) is the service's to open again or not (messages/sharedTabs.ts).
* - Agent Messages out of the core's process going leaves the gateway holding sockets nobody listens to: they are
* closed (`closeOpened`), and the process opens them again as it starts.
*/
export function tabRelayOf(gateway: () => TabRelay): TabRelay & { heard(event: TabFrame): void; connected(): void; closeOpened(): void } {
const opened = new Set<string>()
let connectedBefore = false
return {
open: (sharedTabId) => { opened.add(sharedTabId); return gateway().open(sharedTabId) },
send: (sharedTabId, to, payload) => gateway().send(sharedTabId, to, payload),
close: (sharedTabId) => { opened.delete(sharedTabId); gateway().close(sharedTabId) },
/** What a tab's relay said (`GatewayEvents.tabFrame`): a close is the tab no longer open. */
heard: (event) => { if (event.closed) opened.delete(event.sharedTabId) },
/** The gateway's process connected: after its first time, it holds none of the sockets it had. */
connected: () => {
if (connectedBefore) for (const sharedTabId of opened) void gateway().open(sharedTabId)
connectedBefore = true
},
/** Agent Messages out of the core's process went: no one listens to its tabs' sockets until it is back. */
closeOpened: () => {
for (const sharedTabId of [...opened]) { opened.delete(sharedTabId); gateway().close(sharedTabId) }
},
}
}
/** Shared tabs' keys as the core hands them to its services (`core.account.tabKey`): read from the gateway each
* time, as the lane is (`laneOf`). */
export function tabKeyOf(gateway: () => TabKey): TabKey {
return {
publicKey: () => gateway().publicKey(),
signRoster: (sharedTabId, version, body) => gateway().signRoster(sharedTabId, version, body),
signKeyChange: (sharedTabId, nextPub) => gateway().signKeyChange(sharedTabId, nextPub),
hello: (link) => gateway().hello(link),
welcome: (link, payload) => gateway().welcome(link, payload),
accept: (link, hello) => gateway().accept(link, hello),
seal: (link, frame) => gateway().seal(link, frame),
open: (link, frame) => gateway().open(link, frame),
drop: (link) => gateway().drop(link),
}
}