Files
orca/cloud/apps/relay-edge/src/env.ts
Neil cc7d19e932 relay edge: host-sent keepalive answered without waking the object (#40010)
Desktops advertise client-keepalive-v1; the edge offers it after the hello-ack and
auto-responds to a fixed keepalive frame, so idle hosts need no 25 s ping alarm
(each setAlarm is a billed row write). Silent keepalive hosts are probed with one
relay ping before a phone is refused, closed at once where the host is leaving.
Shipped desktops and cells see nothing new. Kill switch CLIENT_KEEPALIVE=0.
2026-11-08 15:03:20 -08:00

126 lines
6.3 KiB
TypeScript

import type { HostRelay } from './host-relay'
import type { SpliceRelay } from './splice-relay'
export type Env = {
HOST_RELAY: DurableObjectNamespace<HostRelay>
SPLICE_RELAY: DurableObjectNamespace<SpliceRelay>
// Pooled connection to the relay's Postgres (credentials, invites, devices, assignments).
HYPERDRIVE?: Hyperdrive
// 'postgres' (MVP and production) or 'spike' (no database: stub credentials, no epoch check).
EDGE_BACKEND?: string
// The cell id directors write into relay_assignments for hosts placed on the edge.
EDGE_CELL_ID?: string
// Relay JWTs: verified against the auth service's JWKS (fetched, cached per isolate, served
// stale for up to 30 min if auth is unreachable; a cold isolate falls back to the colo's last
// good set in the Cache API for up to 24 h, jwks-persist.ts). RELAY_JWKS (inline set) is for local tests and
// the spike only.
RELAY_JWKS_URL?: string
RELAY_JWKS?: string
RELAY_AUTH_ISSUER?: string
RELAY_JWT_AUDIENCE: string
PING_INTERVAL_MS: string
SILENCE_TIMEOUT_MS: string
ORPHAN_GRACE_MS: string
// '0' stops offering the host-sent keepalive (host-relay-control.ts) and pings every control from
// the alarm again, including controls that took the offer earlier. Default: offered.
CLIENT_KEEPALIVE?: string
// Object backend: store cleanup cadence (default 24 h) and how long an object keeps the data of
// a host that moved away before wiping it (default 30 days). Tests shorten both.
SWEEP_INTERVAL_MS?: string
LEFT_RETENTION_MS?: string
// Flood guard per splice direction: close 4429 if more than this many bytes reach a peer that
// has sent nothing within the window. 0 disables (default; it cut healthy readers in the spike).
SPLICE_SILENT_BYTES_MAX?: string
SPLICE_SILENT_WINDOW_MS?: string
// Spike backend only: comma-separated `<kind>:<relayDeviceId>:<sha256 b64url>` accepted tokens.
SPIKE_RESUME_TOKEN_HASHES?: string
// Spike/test only: /__spike/abort* reset routes.
SPIKE_ADMIN?: string
// Spike/test only: /__spike/info and /__spike/host/<id> debug endpoints (colo, version).
SPIKE_DEBUG?: string
// Version label baked in per deploy (--var EDGE_VERSION:<tag>), reported by metrics and debug.
EDGE_VERSION?: string
METRICS?: AnalyticsEngineDataset
// Per-source limit on unauthenticated phone and host data upgrades (Rate Limiting binding).
PREAUTH_LIMITER?: RateLimit
// Phase 2 admin calls: the director's edge admin key (secret, not its lease key) and its public URL (iss).
ADMIN_SIGNING_KEY?: string
ADMIN_ISSUER?: string
// Key rotation (admin.ts): a second accepted key while the director moves to it. >= 32 chars.
ADMIN_SIGNING_KEY_NEXT?: string
// '1': admin tokens without a `jti` are refused (401). Default off while the director adopts jti.
ADMIN_REQUIRE_JTI?: string
// Optional second signer for `erase` only (the account erasure job): it can never push.
ERASE_SIGNING_KEY?: string
ERASE_SIGNING_KEY_NEXT?: string
ERASE_ISSUER?: string
}
export type EdgeClaims = {
userId: string
profileId: string
organizationId: string
relayHostId: string
exp: number
}
export type EdgeConfig = {
backend: 'object' | 'postgres' | 'spike'
cellId: string
pingIntervalMs: number
silenceTimeoutMs: number
orphanGraceMs: number
sweepIntervalMs: number
leftRetentionMs: number
clientKeepalive: boolean
}
const configs = new WeakMap<object, EdgeConfig>()
function positiveInt(name: string, value: string | undefined): number {
const parsed = Number(value)
if (!Number.isSafeInteger(parsed) || parsed <= 0) { throw new Error(`relay_edge_config_${name}`) }
return parsed
}
// Validated once per isolate. A misconfigured deploy fails every request loudly (500) rather than
// running with a silently wrong backend: the spike backend skips credential and epoch checks.
export function edgeConfig(env: Env): EdgeConfig {
const cached = configs.get(env)
if (cached) { return cached }
const backend = env.EDGE_BACKEND ?? 'postgres'
if (backend !== 'object' && backend !== 'postgres' && backend !== 'spike') { throw new Error('relay_edge_config_backend') }
// Phase 2: assignments arrive only through signed director pushes.
if (backend === 'object' && (!env.ADMIN_SIGNING_KEY || env.ADMIN_SIGNING_KEY.length < 32 || !env.ADMIN_ISSUER)) {
throw new Error('relay_edge_config_admin')
}
// A rotation key, once set, must be as strong as the primary ('' counts as cleared).
if (env.ADMIN_SIGNING_KEY_NEXT && env.ADMIN_SIGNING_KEY_NEXT.length < 32) { throw new Error('relay_edge_config_admin_next') }
if (env.ERASE_SIGNING_KEY_NEXT && env.ERASE_SIGNING_KEY_NEXT.length < 32) { throw new Error('relay_edge_config_erase_next') }
if (backend === 'postgres' && !env.HYPERDRIVE) { throw new Error('relay_edge_config_hyperdrive') }
if (backend === 'spike' && env.SPIKE_DEBUG !== '1' && env.SPIKE_ADMIN !== '1') {
throw new Error('relay_edge_config_spike_backend_outside_spike')
}
// The abort routes reset objects (drop every socket); only the spike backend may turn them on.
if (env.SPIKE_ADMIN === '1' && backend !== 'spike') { throw new Error('relay_edge_config_spike_admin_outside_spike') }
if (!env.RELAY_JWKS_URL && !env.RELAY_JWKS) { throw new Error('relay_edge_config_jwks') }
if (env.RELAY_JWKS_URL && !env.RELAY_AUTH_ISSUER) { throw new Error('relay_edge_config_issuer') }
if (!env.RELAY_JWT_AUDIENCE) { throw new Error('relay_edge_config_audience') }
const config: EdgeConfig = {
backend,
cellId: env.EDGE_CELL_ID || 'edge',
pingIntervalMs: positiveInt('ping_interval', env.PING_INTERVAL_MS),
silenceTimeoutMs: positiveInt('silence_timeout', env.SILENCE_TIMEOUT_MS),
orphanGraceMs: positiveInt('orphan_grace', env.ORPHAN_GRACE_MS),
sweepIntervalMs: positiveInt('sweep_interval', env.SWEEP_INTERVAL_MS ?? String(24 * 60 * 60 * 1000)),
leftRetentionMs: positiveInt('left_retention', env.LEFT_RETENTION_MS ?? String(30 * 24 * 60 * 60 * 1000)),
clientKeepalive: env.CLIENT_KEEPALIVE !== '0'
}
// The offer carries the ping interval, which the contract bounds to 1..60 s.
config.clientKeepalive &&= config.pingIntervalMs >= 1_000 && config.pingIntervalMs <= 60_000
// Shipped desktops close a control that is silent for 75 s; a ping must arrive well inside it.
if (config.pingIntervalMs >= config.silenceTimeoutMs) { throw new Error('relay_edge_config_ping_interval') }
configs.set(env, config)
return config
}