spexcode 0.5.1 → 0.5.3

package/spec-cli/src/client.ts

@@ -1,4 +1,7 @@
 import { apiBase, assertProjectMatch, resolveSession, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
+import { readSync, writeSync } from 'node:fs'
+import { maintenanceBrokerDescriptors, type Capability, type LeaseOwner, type MaintenanceState } from './session-maintenance.js'
+import { processStartToken } from './process-identity.js'
 
 export class BackendError extends Error {
   constructor(message: string, readonly status?: number) {
@@ -10,6 +13,8 @@ export class BackendError extends Error {
 // the ONE seam where "no backend" becomes loud. A network failure (nothing listening at the resolved base)
 // is the only thing thrown; an HTTP Response of any status is returned for the caller to interpret.
 async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
+  if (maintenanceBrokerDescriptors() && init?.method && !['GET', 'HEAD'].includes(init.method.toUpperCase()))
+    throw new BackendError('maintenance_capability_missing: the operator broker admits only its exact stop/resume plan')
   const base = await apiBase()
   try {
     return await fetch(`${base}${path}`, init)
@@ -23,17 +28,127 @@ async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
 const guarded = (verb: string) => assertProjectMatch(`spex ${verb}`)
 const post = (body: unknown): RequestInit => ({ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
 const seg = (id: string) => encodeURIComponent(id)
+type BrokerRequest = { op: string; sessionId?: string; force?: boolean }
+type BrokerOutcome = 'committed' | 'refused' | 'indeterminate'
+type BrokerResponse = { ok: boolean; outcome?: BrokerOutcome; status?: number; body?: any; code?: string; error?: string }
+function brokerRequest(request: BrokerRequest): BrokerResponse | null {
+  const fds = maintenanceBrokerDescriptors()
+  if (!fds) return null
+  const startToken = processStartToken(process.pid)
+  if (!startToken) throw new BackendError(`maintenance broker cannot identify client PID ${process.pid}`)
+  const id = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+  const frame = `${JSON.stringify({ v: 1, id, ...request, client: { pid: process.pid, startToken } })}\n`
+  if (Buffer.byteLength(frame) > 4_096) throw new BackendError('maintenance broker request exceeded PIPE_BUF')
+  const token = Buffer.alloc(1)
+  let ownsTurn = false
+  try {
+    if (readSync(fds.turn, token, 0, 1, null) !== 1 || token[0] !== 1)
+      throw new BackendError('maintenance broker turn token was unavailable or invalid')
+    ownsTurn = true
+    if (writeSync(fds.request, frame) !== Buffer.byteLength(frame)) throw new BackendError('maintenance broker request write was incomplete')
+    let line = ''
+    const byte = Buffer.alloc(1)
+    while (!line.endsWith('\n')) {
+      const count = readSync(fds.response, byte, 0, 1, null)
+      if (count === 0) throw new BackendError('maintenance broker closed before replying')
+      line += byte.toString('utf8', 0, count)
+      if (line.length > 64 * 1024) throw new BackendError('maintenance broker response exceeded its bound')
+    }
+    const response = JSON.parse(line) as BrokerResponse & { id?: string }
+    if (response.id !== id) throw new BackendError('maintenance broker response identity mismatch')
+    return response
+  } finally {
+    if (ownsTurn) {
+      try { writeSync(fds.turn, token) } catch { /* broker shutdown owns the failure */ }
+    }
+  }
+}
+const brokerMutation = (request: BrokerRequest): BrokerResponse | null => brokerRequest(request)
+
+export type MaintenanceLeaseResponse = { token: string; epoch: number; state: 'draining' | 'active'; owner: LeaseOwner; capabilities?: Capability[] }
+export async function clientMaintenanceAcquire(capabilities: Capability[], ttlMs: number, waitMs: number): Promise<{ status: number; lease: MaintenanceLeaseResponse }> {
+  await guarded('session maintain')
+  const r = await apiFetch('/api/session-maintenance/acquire', post({ capabilities, ttlMs, waitMs }))
+  const lease = await r.json().catch(() => ({})) as MaintenanceLeaseResponse & { error?: string }
+  if (r.status !== 201 && r.status !== 202) throw new BackendError(`backend refused maintenance acquire (${r.status}): ${lease.error || 'invalid response'}`, r.status)
+  return { status: r.status, lease }
+}
+export async function clientMaintenanceStatus(): Promise<MaintenanceState> {
+  const r = await apiFetch('/api/session-maintenance')
+  if (!r.ok) throw new BackendError(`backend refused maintenance status (${r.status})`, r.status)
+  return await r.json() as MaintenanceState
+}
+const maintenanceHeaders = (token: string): Record<string, string> => ({
+  'content-type': 'application/json',
+  'x-spexcode-session-maintenance': token,
+})
+export async function clientMaintenanceHeartbeat(token: string, epoch: number, ttlMs: number): Promise<MaintenanceState> {
+  const r = await apiFetch('/api/session-maintenance/heartbeat', { method: 'POST', headers: maintenanceHeaders(token), body: JSON.stringify({ epoch, ttlMs }) })
+  if (!r.ok) throw new BackendError(`backend refused maintenance heartbeat (${r.status}): ${await r.text()}`, r.status)
+  return await r.json() as MaintenanceState
+}
+export async function clientMaintenanceRelease(token: string, epoch: number): Promise<void> {
+  const r = await apiFetch('/api/session-maintenance/release', { method: 'POST', headers: maintenanceHeaders(token), body: JSON.stringify({ epoch }) })
+  if (!r.ok) throw new BackendError(`backend refused maintenance release (${r.status}): ${await r.text()}`, r.status)
+}
+export async function clientMaintenanceOperation(
+  token: string,
+  request: { op: 'stop' | 'resume'; sessionId: string; force?: boolean },
+  options: { signal?: AbortSignal; timeoutMs?: number } = {},
+): Promise<BrokerResponse> {
+  const path = `/api/sessions/${seg(request.sessionId)}/${request.op}`
+  const controller = new AbortController()
+  const abort = () => controller.abort(options.signal?.reason)
+  if (options.signal?.aborted) abort()
+  else options.signal?.addEventListener('abort', abort, { once: true })
+  const timer = setTimeout(() => controller.abort(new Error('maintenance operation timed out')), options.timeoutMs ?? 5_000)
+  timer.unref()
+  try {
+    const r = await apiFetch(path, {
+      method: 'POST', headers: maintenanceHeaders(token), signal: controller.signal,
+      body: JSON.stringify(request.op === 'resume' ? { force: request.force === true } : {}),
+    })
+    let body: any
+    try { body = await r.json() } catch {
+      return { ok: false, outcome: 'indeterminate', status: r.status, code: 'maintenance_response_malformed', error: 'maintenance operation returned malformed JSON' }
+    }
+    const committed = r.ok && body?.ok === true
+    const refused = (r.status >= 400 && r.status < 500 && (body?.ok === false || typeof body?.code === 'string'))
+      || (r.ok && body?.ok === false && body?.refused === true)
+    const outcome: BrokerOutcome = committed ? 'committed' : refused ? 'refused' : 'indeterminate'
+    const code = typeof body?.code === 'string' ? body.code
+      : refused ? 'session_operation_refused'
+        : committed ? undefined : 'maintenance_operation_indeterminate'
+    return {
+      ok: committed,
+      outcome,
+      status: r.status,
+      body,
+      ...(code ? { code } : {}),
+      ...(!committed ? { error: body?.error || `status ${r.status}` } : {}),
+    }
+  } finally {
+    clearTimeout(timer)
+    options.signal?.removeEventListener('abort', abort)
+  }
+}
 
 // GET /api/sessions — the board, used by `spex session ls`, and by `spex session watch`/`wait` as their poll source.
-export async function clientListSessions(): Promise<Session[]> {
-  const r = await apiFetch('/api/sessions')
+export async function clientListSessions(includeArchived = false): Promise<Session[]> {
+  const r = await apiFetch(includeArchived ? '/api/sessions?all=1' : '/api/sessions')
   if (!r.ok) throw new BackendError(`backend error ${r.status} listing sessions`, r.status)
   return await r.json() as Session[]
 }
 
+export async function clientResources(): Promise<import('./host-resources.js').ResourceReport> {
+  const r = await apiFetch('/api/resources')
+  if (!r.ok) throw new BackendError(`backend error ${r.status} loading resources: ${await r.text()}`, r.status)
+  return await r.json() as import('./host-resources.js').ResourceReport
+}
+
 // resolve a selector (full id, id-prefix, node, or branch) against the live board, then call with the full id.
-export async function resolveClientSession(selector: string): Promise<Resolved> {
-  return resolveSession(selector, await clientListSessions())
+export async function resolveClientSession(selector: string, includeArchived = true): Promise<Resolved> {
+  return resolveSession(selector, await clientListSessions(includeArchived))
 }
 
 // GET /api/sessions/:id/capture — the live pane as text. The discriminated result keeps the three failure
@@ -49,6 +164,8 @@ export async function clientCapture(id: string): Promise<CaptureResult> {
 // socket, socket-only + fail-loud; a non-accepted prompt comes back ok:false / HTTP 502).
 export async function clientSend(id: string, text: string, from?: string): Promise<DispatchResult> {
   await guarded('session send')
+  const brokered = brokerMutation({ op: 'send', sessionId: id })
+  if (brokered) return brokered.ok ? brokered.body as DispatchResult : { ok: false, error: brokered.code || brokered.error || 'maintenance_active' }
   // `from` = the sending agent's own session id; the backend logs the comms edge ([[comms-edge]]) only when
   // it's present (an agent send), so a human-shell send stays unrecorded.
   const r = await apiFetch(`/api/sessions/${seg(id)}/input`, post({ kind: 'text', text, ...(from ? { from } : {}) }))
@@ -104,7 +221,7 @@ export async function clientEvals(id: string): Promise<EvalsResult> {
     }
     if (!changed) return { ok: true, model: { ...first!, id, items } }
   }
-  throw new BackendError(`session eval pages changed while reading ${id}; retry the command`)
+  throw new BackendError(`session eval pages changed while fetching ${id}; retry the command`)
 }
 
 // POST /api/sessions/:id/merge — the cockpit's merge DISPATCH (200 {dispatched:true} / 409 {reason}).
@@ -120,6 +237,11 @@ export async function clientMerge(id: string): Promise<{ dispatched: boolean; re
 // carries a non-error advisory.
 export async function clientResume(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean; info?: string }> {
   await guarded('session resume')
+  const brokered = brokerMutation({ op: 'resume', sessionId: id, force })
+  if (brokered) {
+    if (!brokered.ok) throw new BackendError(brokered.code || brokered.error || 'maintenance_active', brokered.status)
+    return brokered.body
+  }
   const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({ force }))
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }))
 }
@@ -128,7 +250,13 @@ export async function clientResume(id: string, force = false): Promise<{ ok: boo
 // resumable). Distinct from close. {ok:false} = no such session.
 export async function clientStop(id: string): Promise<boolean> {
   await guarded('session stop')
+  const brokered = brokerMutation({ op: 'stop', sessionId: id })
+  if (brokered) {
+    if (!brokered.ok) throw new BackendError(brokered.code || brokered.error || 'maintenance_active', brokered.status)
+    return !!brokered.body?.ok
+  }
   const r = await apiFetch(`/api/sessions/${seg(id)}/stop`, post({}))
+  if (!r.ok) throw new BackendError(`backend refused to stop ${id}: ${await r.text()}`, r.status)
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
@@ -144,6 +272,16 @@ export async function clientInterrupt(id: string): Promise<DispatchResult> {
 export async function clientClose(id: string): Promise<boolean> {
   await guarded('session close')
   const r = await apiFetch(`/api/sessions/${seg(id)}/close`, post({}))
+  if (!r.ok) throw new BackendError(`backend refused to close ${id}: ${await r.text()}`, r.status)
+  return !!(await r.json().catch(() => ({ ok: false })))?.ok
+}
+
+// POST /api/sessions/:id/archive — cold-archive the session ([[archive]]). The legacy on=false spelling is a
+// signpost to the same resume transition; it never performs a record-only unarchive.
+export async function clientArchive(id: string, on = true): Promise<boolean> {
+  await guarded(on ? 'session archive' : 'session unarchive')
+  const r = await apiFetch(`/api/sessions/${seg(id)}/archive`, post({ on }))
+  if (!r.ok) throw new BackendError(`backend refused to ${on ? 'archive' : 'unarchive'} ${id}: ${await r.text()}`, r.status)
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 

package/spec-cli/src/gateway-hub.ts

@@ -30,6 +30,7 @@ import { installConnectionReaper } from './reaper.js'
 import { spexcodeHome, encodeProject } from './layout.js'
 import { readEndpointRecord } from './host.js'
 import { readGatewayIdentity, type ResolvedIdentity } from './project-identity.js'
+import { proxyHttp } from './gateway.js'
 
 export type HubProject = { id: string; identity: ResolvedIdentity; url: string; port: number; gated: boolean }
 // @@@ extension seam - the hub stays the ONE routing+authorization server; a host-level caller
@@ -351,10 +352,5 @@ function proxyTo(req: http.IncomingMessage, res: http.ServerResponse, upstreamPo
   const headers: http.OutgoingHttpHeaders = { ...req.headers }
   const kept = stripGatewayCookies(req.headers.cookie)
   if (kept) headers.cookie = kept; else delete headers.cookie
-  const up = http.request({ host: '127.0.0.1', port: upstreamPort, path, method: req.method, headers }, (upRes) => {
-    res.writeHead(upRes.statusCode || 502, upRes.headers)
-    upRes.pipe(res)
-  })
-  up.on('error', () => { if (!res.headersSent) res.writeHead(502, { 'Content-Type': 'text/plain' }); res.end('project backend unreachable') })
-  req.pipe(up)
+  proxyHttp(req, res, upstreamPort, path, headers)
 }

package/spec-cli/src/gateway.ts

@@ -227,19 +227,104 @@ const wantsGzip = (req: http.IncomingMessage) => /\bgzip\b/.test(String(req.head
 
 // reverse-proxy an /api request to the loopback supervisor (which forwards to the live child) —
 // stream-gzipping compressible bodies (measured: the board JSON rides down at under a third).
-// `path` overrides the upstream path (the host gateway strips its /p/:projectId prefix); default = as-is.
-// Exported: the host gateway ([[host-gateway]]) proxies per-project traffic through this same function.
-export function proxyHttp(req: http.IncomingMessage, res: http.ServerResponse, upstreamPort: number, path?: string) {
-  const up = http.request({ host: '127.0.0.1', port: upstreamPort, path: path ?? req.url, method: req.method, headers: req.headers }, (upRes) => {
-    const type = String(upRes.headers['content-type'] || '')
-    const skip = !wantsGzip(req) || upRes.headers['content-encoding'] || !COMPRESSIBLE.test(type) || type.startsWith('text/event-stream')
-    if (skip) { res.writeHead(upRes.statusCode || 502, upRes.headers); upRes.pipe(res); return }
-    const headers = { ...upRes.headers, 'content-encoding': 'gzip', vary: 'Accept-Encoding' }
+// `path` and `headers` optionally override routing inputs (the host gateway strips its /p/:projectId
+// prefix and gateway cookies); transport ownership stays here once. Defaults pass the request through.
+export function proxyHttp(req: http.IncomingMessage, res: http.ServerResponse, upstreamPort: number, path?: string, headers: http.OutgoingHttpHeaders = req.headers) {
+  let upstreamResponse: http.IncomingMessage | null = null
+  let transform: ReturnType<typeof createGzip> | null = null
+  let settled = false
+
+  const removeDownstreamListeners = () => {
+    req.off('aborted', abortFromDownstream)
+    req.off('error', abortFromDownstream)
+    req.off('end', onRequestEnd)
+    req.off('close', onRequestClose)
+    res.off('error', abortFromDownstream)
+    res.off('close', onResponseClose)
+    res.off('finish', onResponseFinish)
+  }
+  const destroyUpstream = () => {
+    req.unpipe(up)
+    if (upstreamResponse && transform) {
+      upstreamResponse.unpipe(transform)
+      transform.unpipe(res)
+      transform.destroy()
+    } else if (upstreamResponse) {
+      upstreamResponse.unpipe(res)
+    }
+    upstreamResponse?.destroy()
+    up.destroy()
+  }
+  const settle = () => {
+    if (settled) return
+    settled = true
+    removeDownstreamListeners()
+  }
+  const onResponseFinish = () => {
+    if (settled) return
+    if (req.complete) { settle(); return }
+    // An upstream may reject a body before the client finishes sending it. The response is valid, but the
+    // upload leg is over: sever it upstream and drain the downstream body so the flushed response and
+    // keep-alive socket are not turned into a reset. Request abort ownership stays until end/close.
+    req.unpipe(up)
+    upstreamResponse?.destroy()
+    up.socket?.destroy()
+    up.destroy()
+    if (!req.destroyed) req.resume()
+  }
+  const abortFromDownstream = () => {
+    if (settled) return
+    settled = true
+    removeDownstreamListeners()
+    destroyUpstream()
+  }
+  const onRequestClose = () => {
+    if (!req.complete) abortFromDownstream()
+    else if (res.writableFinished) settle()
+  }
+  const onRequestEnd = () => { if (res.writableFinished) settle() }
+  const onResponseClose = () => {
+    if (!res.writableFinished) abortFromDownstream()
+  }
+  const failFromUpstream = () => {
+    if (settled) return
+    settled = true
+    removeDownstreamListeners()
+    destroyUpstream()
+    if (res.destroyed) return
+    if (!res.headersSent) { res.writeHead(502); res.end('upstream unreachable') }
+    else res.destroy()
+  }
+
+  const up = http.request({ host: '127.0.0.1', port: upstreamPort, path: path ?? req.url, method: req.method, headers }, (received) => {
+    if (settled || res.destroyed) { received.destroy(); up.destroy(); return }
+    upstreamResponse = received
+    received.once('aborted', failFromUpstream)
+    received.once('error', failFromUpstream)
+    received.once('close', () => { if (!received.complete) failFromUpstream() })
+
+    const type = String(received.headers['content-type'] || '')
+    const skip = !wantsGzip(req) || received.headers['content-encoding'] || !COMPRESSIBLE.test(type) || type.startsWith('text/event-stream')
+    if (skip) {
+      res.writeHead(received.statusCode || 502, received.headers)
+      received.pipe(res)
+      return
+    }
+    const headers = { ...received.headers, 'content-encoding': 'gzip', vary: 'Accept-Encoding' }
     delete headers['content-length']   // streamed; the encoded length isn't knowable up front
-    res.writeHead(upRes.statusCode || 502, headers)
-    upRes.pipe(createGzip()).pipe(res)
+    res.writeHead(received.statusCode || 502, headers)
+    transform = createGzip()
+    transform.once('error', failFromUpstream)
+    received.pipe(transform).pipe(res)
   })
-  up.on('error', () => { if (!res.headersSent) res.writeHead(502); res.end('upstream unreachable') })
+  up.once('error', failFromUpstream)
+  req.once('aborted', abortFromDownstream)
+  req.once('error', abortFromDownstream)
+  req.once('end', onRequestEnd)
+  req.once('close', onRequestClose)
+  res.once('error', abortFromDownstream)
+  res.once('close', onResponseClose)
+  res.once('finish', onResponseFinish)
   req.pipe(up)
 }