Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import { describe, expect, it } from 'vitest'
import {
MessageType,
HEADER_LENGTH,
FrameDecoder,
encodeHandshakeFrame,
parseHandshakeMessage,
type DecodedFrame
} from './protocol'
describe('handshake framing', () => {
it('round-trips an orca-relay-handshake envelope through the existing framing', () => {
const sent = encodeHandshakeFrame({
type: 'orca-relay-handshake',
version: '0.1.0+deadbeef'
})
expect(sent[0]).toBe(MessageType.Handshake)
expect(sent.length).toBeGreaterThan(HEADER_LENGTH)
const frames: DecodedFrame[] = []
const decoder = new FrameDecoder((f) => frames.push(f))
decoder.feed(sent)
expect(frames).toHaveLength(1)
expect(frames[0].type).toBe(MessageType.Handshake)
const msg = parseHandshakeMessage(frames[0].payload)
expect(msg).toEqual({ type: 'orca-relay-handshake', version: '0.1.0+deadbeef' })
})
it('round-trips an orca-relay-handshake-ok reply', () => {
const sent = encodeHandshakeFrame({
type: 'orca-relay-handshake-ok',
version: '0.1.0+deadbeef'
})
const frames: DecodedFrame[] = []
const decoder = new FrameDecoder((f) => frames.push(f))
decoder.feed(sent)
const msg = parseHandshakeMessage(frames[0].payload)
expect(msg).toEqual({ type: 'orca-relay-handshake-ok', version: '0.1.0+deadbeef' })
})
it('round-trips an orca-relay-handshake-mismatch reply', () => {
const sent = encodeHandshakeFrame({
type: 'orca-relay-handshake-mismatch',
expected: '0.1.0+aaa',
got: '0.1.0+bbb'
})
const frames: DecodedFrame[] = []
const decoder = new FrameDecoder((f) => frames.push(f))
decoder.feed(sent)
const msg = parseHandshakeMessage(frames[0].payload)
expect(msg).toEqual({
type: 'orca-relay-handshake-mismatch',
expected: '0.1.0+aaa',
got: '0.1.0+bbb'
})
})
it('rejects payloads with unknown type', () => {
const bogus = Buffer.from(JSON.stringify({ type: 'orca-something-else', version: 'x' }))
expect(() => parseHandshakeMessage(bogus)).toThrow(/Unknown handshake type/)
})
// Hostile JSON can make String(type) throw and hide the intended refusal diagnostic.
it('still names the refusal when the peer type cannot be stringified', () => {
const hostile = Buffer.from(JSON.stringify({ type: { toString: 1 } }))
expect(() => parseHandshakeMessage(hostile)).toThrow(/Unknown handshake type: object/)
})
// Validate versions before pre-auth readers interpolate them into diagnostics.
it('rejects a version that is not a string on both arms that carry one', () => {
for (const type of ['orca-relay-handshake', 'orca-relay-handshake-ok']) {
for (const version of [{ toString: 1 }, 7, null, undefined, ['0.1.0']]) {
const payload = Buffer.from(JSON.stringify({ type, version }))
expect(
() => parseHandshakeMessage(payload),
`${type} version=${JSON.stringify(version)}`
).toThrow(/Handshake field version is not a string/)
}
}
})
it('rejects a mismatch reply whose expected or got is not a string', () => {
const type = 'orca-relay-handshake-mismatch'
expect(() =>
parseHandshakeMessage(Buffer.from(JSON.stringify({ type, expected: {}, got: 'b' })))
).toThrow(/Handshake field expected is not a string/)
expect(() =>
parseHandshakeMessage(Buffer.from(JSON.stringify({ type, expected: 'a', got: 1 })))
).toThrow(/Handshake field got is not a string/)
})
it('rejects payloads that are not objects', () => {
for (const payload of ['null', '"orca-relay-handshake"', '42']) {
expect(() => parseHandshakeMessage(Buffer.from(payload)), payload).toThrow(
/Handshake payload is not an object/
)
}
})
// Validate optional credentials at the parser so future readers cannot encounter a hostile non-string.
it('rejects a present endpointCredential that is not a string', () => {
for (const endpointCredential of [{ toString: 1 }, 7, null, ['secret'], true]) {
const payload = Buffer.from(
JSON.stringify({ type: 'orca-relay-handshake', version: '0.1.0', endpointCredential })
)
expect(
() => parseHandshakeMessage(payload),
`endpointCredential=${JSON.stringify(endpointCredential)}`
).toThrow(/Handshake field endpointCredential is not a string/)
}
})
// Missing credentials are valid for unauthenticated endpoints; preserve absence.
it('still accepts a handshake with no endpointCredential, and one with a string', () => {
const bare = Buffer.from(JSON.stringify({ type: 'orca-relay-handshake', version: '0.1.0' }))
expect(parseHandshakeMessage(bare)).toEqual({ type: 'orca-relay-handshake', version: '0.1.0' })
const withCredential = Buffer.from(
JSON.stringify({ type: 'orca-relay-handshake', version: '0.1.0', endpointCredential: 'sec' })
)
expect(parseHandshakeMessage(withCredential)).toEqual({
type: 'orca-relay-handshake',
version: '0.1.0',
endpointCredential: 'sec'
})
})
it('still accepts a credential-mismatch reply, which carries no fields', () => {
const payload = Buffer.from(
JSON.stringify({ type: 'orca-relay-handshake-credential-mismatch' })
)
expect(parseHandshakeMessage(payload)).toEqual({
type: 'orca-relay-handshake-credential-mismatch'
})
})
it('carries the optional informational runtime on handshake-ok', () => {
const runtime = { kind: 'pinned-node', version: '24.21.0' }
const payload = Buffer.from(
JSON.stringify({ type: 'orca-relay-handshake-ok', version: '0.1.0', runtime })
)
expect(parseHandshakeMessage(payload)).toEqual({
type: 'orca-relay-handshake-ok',
version: '0.1.0',
runtime
})
})
it.each([['pinned-node'], [{ kind: 1, version: '24' }], [null]])(
'refuses a present-but-malformed runtime %j',
(runtime) => {
const payload = Buffer.from(
JSON.stringify({ type: 'orca-relay-handshake-ok', version: '0.1.0', runtime })
)
expect(() => parseHandshakeMessage(payload)).toThrow('runtime')
}
)
it('handshake frames use a distinct MessageType from Regular and KeepAlive', () => {
expect(MessageType.Handshake).not.toBe(MessageType.Regular)
expect(MessageType.Handshake).not.toBe(MessageType.KeepAlive)
})
})