Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(relay): a rate-limited /v1/relay/join is E_JOIN_RATE, not a network failure (R40)

reviewe5cd075c5681
diff --git a/src/core/relay/join-token.test.ts b/src/core/relay/join-token.test.ts
index 228cc1473..0438fd52a 100644
--- a/src/core/relay/join-token.test.ts
+++ b/src/core/relay/join-token.test.ts
@@ -47,10 +47,15 @@ describe('joiner tokens', () => {
expect(await mintJoinToken({ apiBase: 'a', deviceToken: 'x', fetch: fake(403, {}).f })).toEqual({ ok: false, kind: 'revoked' })
})
+ it('join: 429 is a rate limit (R40) — never retried as a network failure, never a token verdict', async () => {
+ const join = (f: typeof fetch) => mintJoinToken({ apiBase: 'a', deviceToken: 'x', fetch: f })
+ expect(await join(fake(429, {}).f)).toEqual({ ok: false, kind: 'rate-limited' })
+ })
+
it('join: any other failure is network, never a token verdict', async () => {
const join = (f: typeof fetch) => mintJoinToken({ apiBase: 'a', deviceToken: 'x', fetch: f })
expect(await join(fake(500, {}).f)).toEqual({ ok: false, kind: 'network' })
- expect(await join(fake(429, {}).f)).toEqual({ ok: false, kind: 'network' })
+ expect(await join(fake(503, {}).f)).toEqual({ ok: false, kind: 'network' })
expect(await join(throwing)).toEqual({ ok: false, kind: 'network' })
expect(await join(fake(200, 'nope').f)).toEqual({ ok: false, kind: 'network' })
expect(await join(fake(200, { pairingToken: 'P' }).f)).toEqual({ ok: false, kind: 'network' })
diff --git a/src/core/relay/join-token.ts b/src/core/relay/join-token.ts
index 39eeb34f7..f6f43a878 100644
--- a/src/core/relay/join-token.ts
+++ b/src/core/relay/join-token.ts
@@ -15,7 +15,7 @@ const TIMEOUT_MS = 8000
export type DeviceMintResult = { ok: true; deviceToken: string } | { ok: false; kind: 'network' | 'refused' | 'rate-limited' }
export type JoinMintResult =
| { ok: true; pairingToken: string; relayEndpoint: string }
- | { ok: false; kind: 'bad-token' | 'revoked' | 'network' }
+ | { ok: false; kind: 'bad-token' | 'revoked' | 'rate-limited' | 'network' }
/** A reply: its status and its parsed JSON body (`null` when the body is not JSON). */
interface Reply { status: number; ok: boolean; body: unknown }
@@ -84,6 +84,9 @@ export async function mintJoinToken(d: {
// Everything else says nothing about the token, so it must not cost a device mint.
if (res.status === 401) return { ok: false, kind: 'bad-token' }
if (res.status === 403) return { ok: false, kind: 'revoked' }
+ // A rate limit is a verdict about WHEN, not a network blip: read as `network`, an unattended
+ // reconnect would ask again every minute for as long as the limit holds (R40).
+ if (res.status === 429) return { ok: false, kind: 'rate-limited' }
if (!res.ok) return { ok: false, kind: 'network' }
const j = res.body as { pairingToken?: unknown; relayEndpoint?: unknown } | null
if (typeof j?.pairingToken !== 'string' || !j.pairingToken || typeof j.relayEndpoint !== 'string' || !j.relayEndpoint) {
diff --git a/src/main/remote/hosted-join.test.ts b/src/main/remote/hosted-join.test.ts
index d32cb6ea7..0f26dde9a 100644
--- a/src/main/remote/hosted-join.test.ts
+++ b/src/main/remote/hosted-join.test.ts
@@ -426,6 +426,16 @@ describe('connectHostedTeam (the relay:client:connect leg for a join code)', ()
expect(x.sessions.size).toBe(0)
})
+ it('R40: a rate-limited /v1/relay/join is E_JOIN_RATE (never retried), and the device token is kept', async () => {
+ const s = setup({ routes: { device: [DEVICE_OK('KEEP')], join: [[429, {}], JOIN_OK] } })
+ const err = await connectHostedTeam(codeText, s.deps, io().io).catch((e: Error) => e)
+ expect(joinErrorCode((err as Error).message)).toBe('E_JOIN_RATE')
+ // A later attempt (a person's, the next day) presents the SAME token: a rate limit costs no mint.
+ await connectHostedTeam(codeText, s.deps, io().io)
+ expect(s.api.count('device')).toBe(1)
+ expect(s.api.calls.filter((c) => c.route === 'join').map((c) => c.body.deviceToken)).toEqual(['KEEP', 'KEEP'])
+ })
+
it('a failed join registers nothing and rejects with the human message', async () => {
const s = setup({ routes: { device: [[429, {}]] } })
const x = io()