@nofendian17/opencode-relay-plugin 2.0.1 → 2.0.5

package/README.md

@@ -1,10 +1,16 @@
 # @nofendian17/opencode-relay-plugin (v2)
 
-Route OpenCode **v2** Zen traffic (`https://opencode.ai/zen/*`) through your
-relay endpoint(s), ported from the v1 `relay.js`
-(`@opencode-ai/plugin` → `@opencode/plugin`).
+Route OpenCode **v2** opencode.ai traffic through your relay endpoint(s),
+ported from the v1 `relay.js` (`@opencode-ai/plugin` → `@opencode/plugin`).
 
-Only Zen requests are relayed; other providers already point at direct
+## Scope
+
+Matched by **origin** (`https://opencode.ai`), not by path prefix. This covers
+`/zen/*`, `/inference/*`, and any future path on the same origin. (Before
+v2.0.4 the match was prefix-based on `/zen/*`, so `/inference/*` traffic
+silently went direct — same rate-limit symptom, no relay in the log.)
+
+Only opencode.ai requests are relayed; other providers already point at direct
 gateways and are left untouched (no rewrite, no forced retries).
 
 V1 patched `provider.options.fetch` + `globalThis.fetch`. V2 providers no longer expose `fetch`,
@@ -16,7 +22,7 @@ so this plugin uses the documented v2 interception points:
 - `ctx.session.hook("retry")` — relay network errors never reach `http.response`, so force a
   retry (next attempt picks the next relay); after the pool is exhausted the next attempt goes direct
 - `ctx.session.hook("experimental.ws.handshake")` — no-op (relay is HTTP-only, kept direct)
-- `globalThis.fetch` patch — only for out-of-session `https://opencode.ai/zen/*` traffic (v1 parity)
+- `globalThis.fetch` patch — only for out-of-session `https://opencode.ai/*` traffic (v1 parity)
 - `ctx.provider.transform` — re-enable the built-in `opencode` (Zen) provider if disabled
 
 Reference: https://opencode.ai/v2/docs/plugins/ + migration guide
@@ -59,17 +65,21 @@ Local file (auto-discovered):
 | Option | Env fallback | Description |
 | --- | --- | --- |
 | `url: string \| string[]` | `RELAY_URL` (comma-separated) | Relay endpoint(s), `http(s)` only. Invalid entries are skipped with a warning log; if none remain valid the plugin disables itself. |
-| `debug: boolean` | `RELAY_DEBUG=1` | Verbose per-request logging. When on, log lines are also appended to `/tmp/opencode-relay.log` (plugin `console.log` is not forwarded to opencode logs). |
+| `debug: boolean` | `RELAY_DEBUG=1` | Verbose per-request logging. When on, log lines are also appended to `/tmp/opencode-relay.log` (plugin `console.log` is not forwarded to opencode logs). Override the path with `RELAY_DEBUG_LOG` (used by tests for isolation). |
 
 ## Relay protocol (unchanged from v1)
 
 - `<relay-url>` with original method/body/headers plus:
-  - `x-relay-target: https://api.anthropic.com` (origin)
-  - `x-relay-path: /v1/messages?foo=bar` (path + query)
+  - `x-relay-target: https://opencode.ai` (origin)
+  - `x-relay-path: /inference/v1/chat/completions` (path + query)
 - Relay returns the provider response verbatim (status/body/headers).
 - `429` or `>= 500` → try next relay → fall back to direct.
 - Network error → try next relay → fall back to direct.
 
+Retry accounting: attempts `1..N` (pool size) each try the next relay in
+round-robin order; attempt `N+1` goes direct once (per-session flag, consumed
+by the next `http.request`), then the pool is used again.
+
 ## Security
 
 The relay terminates TLS and sees everything it forwards: request bodies and
@@ -79,10 +89,19 @@ access logs as secret-bearing.
 
 ## Verify
 
-1. `RELAY_DEBUG=1` + set `url` to a local echo server, run a prompt, confirm
+1. Set `debug: true` + `url` to a local echo server, run a prompt, confirm
    `x-relay-target` / `x-relay-path` headers arrive.
-2. Stop the relay → request still succeeds via direct fallback (check `[relay] fallback to direct` log).
+2. Stop the relay → request still succeeds via direct fallback (check
+   `[relay] relay fallback to direct` in `/tmp/opencode-relay.log`).
 3. Unset `url`/`RELAY_URL` → `[relay] disabled` log, traffic goes direct.
+4. Confirm scope: a request to `https://opencode.ai/inference/...` must show
+   `via relay` in the log. If the log only shows
+   `direct fallback (all relays failed previously)` with an
+   `https://opencode.ai/...` URL and zero `via relay` lines, the request never
+   entered the pool — check the origin match in `index.ts`.
+
+Note: the debug file is the shared `/tmp/opencode-relay.log`; concurrent
+opencode processes append to the same file.
 
 ## V1 vs V2 notes
 

package/index.ts

@@ -1,14 +1,16 @@
 import { Plugin } from "@opencode/plugin"
 import { appendFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
 
 interface RelayOptions {
   url?: string | string[]
   debug?: boolean
 }
 
-const DEBUG_LOG = "/tmp/opencode-relay.log"
+const DEBUG_LOG = join(tmpdir(), "opencode-relay.log")
 
-const ZEN_PREFIX = "https://opencode.ai/zen/"
+const OPENCODE_ORIGIN = "https://opencode.ai"
 
 type Logger = (message: string, extra?: Record<string, unknown>) => void
 
@@ -59,50 +61,78 @@ function withDuplex(init: RequestInit, bodyBuf: ArrayBuffer | undefined): Reques
   return bodyBuf ? ({ ...init, duplex: "half" } as RequestInit) : init
 }
 
-// Returns true if the signal was aborted and the caller should return early.
-async function failoverToDirect(
-  event: { response: Response },
+interface RelayPoolResult {
+  response?: Response
+  lastError?: unknown
+  aborted: boolean
+}
+
+/**
+ * Try each relay in the pool starting from `start`, up to `count` attempts.
+ * Shared by both failover paths (session hooks + global fetch patch).
+ */
+async function tryRelayPool(
   relays: readonly string[],
   start: number,
-  orig: { origin: string; path: string },
+  count: number,
   method: string,
-  headers: Headers,
+  baseHeaders: Headers,
+  orig: { origin: string; path: string },
   bodyBuf: ArrayBuffer | undefined,
   signal: AbortSignal | undefined,
   directFetch: typeof fetch,
   log: Logger,
-  emit: Logger,
-): Promise<boolean> {
-  let lastStatus = event.response.status
-  // Try the other relays in the pool (the first was already tried in http.request).
-  for (let i = 1; i < relays.length; i++) {
-    if (signal?.aborted) return true
+): Promise<RelayPoolResult> {
+  let lastError: unknown
+  for (let i = 0; i < count; i++) {
+    if (signal?.aborted) return { aborted: true }
     const relay = relays[(start + i) % relays.length]
-    const h = new Headers(headers)
-    h.set("x-relay-target", orig.origin)
-    h.set("x-relay-path", orig.path)
-    log(`retry ${method} ${orig.origin} via next relay`, { relay, prevStatus: lastStatus })
+    const headers = new Headers(baseHeaders)
+    headers.set("x-relay-target", orig.origin)
+    headers.set("x-relay-path", orig.path)
+    log(`retry ${method} ${orig.origin} via relay`, { relay, attempt: i + 1 })
     try {
-      const res = await directFetch(relay, withDuplex({ method, headers: h, body: bodyBuf, signal }, bodyBuf))
-      if (!isRelayFailureStatus(res.status)) {
-        event.response = res
-        return false
-      }
-      lastStatus = res.status
+      const res = await directFetch(relay, withDuplex({ method, headers, body: bodyBuf, signal }, bodyBuf))
+      if (!isRelayFailureStatus(res.status)) return { response: res, aborted: false }
+      lastError = new Error(`relay responded ${res.status}`)
       try {
         await res.body?.cancel()
       } catch {
         // ignore
       }
     } catch (e) {
-      if (signal?.aborted) return true
-      log("relay retry network error", { relay, error: String(e) })
-      continue
+      if (signal?.aborted) return { aborted: true }
+      lastError = e
+      log("relay network error", { relay, error: String(e) })
     }
   }
+  return { lastError, aborted: false }
+}
+
+// Returns true if the signal was aborted and the caller should return early.
+async function failoverToDirect(
+  event: { response: Response },
+  relays: readonly string[],
+  start: number,
+  orig: { origin: string; path: string },
+  method: string,
+  headers: Headers,
+  bodyBuf: ArrayBuffer | undefined,
+  signal: AbortSignal | undefined,
+  directFetch: typeof fetch,
+  log: Logger,
+  emit: Logger,
+): Promise<boolean> {
+  // Try the other relays in the pool (the first was already tried in http.request).
+  const result = await tryRelayPool(relays, start + 1, relays.length - 1, method, headers, orig, bodyBuf, signal, directFetch, log)
+  if (result.aborted) return true
+  if (result.response) {
+    event.response = result.response
+    return false
+  }
 
   // All relays failed -> direct fallback (v1 parity).
-  emit("relay fallback to direct", { target: orig.origin, path: orig.path, status: lastStatus })
+  emit("relay fallback to direct", { target: orig.origin, path: orig.path, status: event.response.status })
   if (signal?.aborted) return true
   try {
     event.response = await directFetch(orig.origin + orig.path, withDuplex({ method, headers, body: bodyBuf, signal }, bodyBuf))
@@ -119,7 +149,7 @@ type RelayFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Resp
  * `x-relay-target` / `x-relay-path` (original method preserved),
  * round-robin across the pool, fail over on 429/5xx + network errors,
  * fall back to direct.
- * Used for out-of-session traffic (global fetch patch for Zen).
+ * Used for out-of-session traffic (global fetch patch for opencode.ai).
  */
 function createRelayFetch(
   relays: readonly string[],
@@ -154,35 +184,15 @@ function createRelayFetch(
       }
     }
 
-    const start = pickIndex()
-    let lastError: unknown
-    for (let attempt = 0; attempt < relays.length; attempt++) {
-      const relay = relays[(start + attempt) % relays.length]
-      const headers = new Headers(originalHeaders)
-      headers.set("x-relay-target", url.origin)
-      headers.set("x-relay-path", relayPath(url))
-      if (debug) log(`${method} ${url.origin}${url.pathname}`, { relay, attempt: attempt + 1 })
-
-      try {
-        const res = await direct(relay, withDuplex({ method, headers, body: bodyBuf, signal }, bodyBuf))
-        if (!isRelayFailureStatus(res.status)) return res
-        lastError = new Error(`relay responded ${res.status}`)
-        // Consume/cancel relay error body so the socket can be reused.
-        try {
-          await res.body?.cancel()
-        } catch {
-          // ignore
-        }
-      } catch (e) {
-        if (signal.aborted) throw e
-        lastError = e
-      }
-    }
+    const orig = { origin: url.origin, path: relayPath(url) }
+    const result = await tryRelayPool(relays, pickIndex(), relays.length, method, originalHeaders, orig, bodyBuf, signal, direct, log)
+    if (result.aborted) throw new Error("The operation was aborted")
+    if (result.response) return result.response
 
     emit("relay fallback to direct", {
       target: url.origin,
       path: url.pathname,
-      error: String(lastError),
+      error: String(result.lastError),
     })
     return direct(url.href, withDuplex({ method, headers: originalHeaders, body: bodyBuf, signal }, bodyBuf))
   }
@@ -209,8 +219,11 @@ export default Plugin.define({
     const debug = parsed.debug
     const prefix = "[relay]"
     // console output from v2 plugins is not forwarded to opencode logs,
-    // so when debug is on, mirror everything to a file in /tmp as well.
+    // so when debug is on, mirror everything to a file as well.
+    // RELAY_DEBUG_LOG overrides the path (tests use an isolated file so a
+    // live opencode process appending to the default never interferes).
     // Async fire-and-forget: logging never breaks requests.
+    const debugLogFile = process.env.RELAY_DEBUG_LOG ?? DEBUG_LOG
     let warnedLogFile = false
     const fileLog: Logger | undefined = debug
       ? (message, extra) => {
@@ -218,10 +231,10 @@ export default Plugin.define({
             `${new Date().toISOString()} ${prefix} ${message}` +
             (extra ? ` ${JSON.stringify(extra)}` : "") +
             "\n"
-          appendFile(DEBUG_LOG, line).catch((e: unknown) => {
+          appendFile(debugLogFile, line).catch((e: unknown) => {
             if (!warnedLogFile) {
               warnedLogFile = true
-              console.log(prefix, "debug log write failed", DEBUG_LOG, String(e))
+              console.log(prefix, "debug log write failed", debugLogFile, String(e))
             }
           })
         }
@@ -270,15 +283,15 @@ export default Plugin.define({
     const relayOrigins = buildRelayOrigins(relays)
     const relayFetch = createRelayFetch(relays, pickIndex, directFetch, debug, log, emit)
 
-    // --- Global fetch patch for out-of-session Zen traffic (v1 parity) ---
+    // --- Global fetch patch for out-of-session opencode.ai traffic (v1 parity) ---
     // Session model traffic is covered by hooks below; this covers anything
-    // else that calls fetch("https://opencode.ai/zen/...") directly.
+    // else that calls fetch("https://opencode.ai/...") directly.
     if (!g[PATCH_MARKER]) {
       g[PATCH_MARKER] = originalForPatch
       globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
         const urlStr =
           typeof input === "string" ? input : input instanceof URL ? input.href : input.url
-        if (typeof urlStr === "string" && urlStr.startsWith(ZEN_PREFIX)) {
+        if (typeof urlStr === "string" && urlStr.startsWith(OPENCODE_ORIGIN)) {
           try {
             if (!relayOrigins.has(new URL(urlStr).origin)) return relayFetch(input, init)
           } catch {
@@ -337,9 +350,10 @@ export default Plugin.define({
       // Avoid relaying the relay itself (loop).
       if (relayOrigins.has(url.origin)) return
 
-      // Scope: only the Zen endpoint goes through the relay. Other
+      // Scope: only opencode.ai endpoints go through the relay (zen,
+      // inference, and any future path on the same origin). Other
       // providers already point at direct gateways and are left untouched.
-      if (!url.href.startsWith(ZEN_PREFIX)) return
+      if (url.origin !== OPENCODE_ORIGIN) return
 
       // Buffer body (streams are one-shot).
       let bodyBuf: ArrayBuffer | undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nofendian17/opencode-relay-plugin",
-  "version": "2.0.1",
+  "version": "2.0.5",
   "description": "Route OpenCode v2 Zen (opencode.ai) traffic through relay endpoint(s) with round-robin, failover, and direct fallback. Other providers are left untouched.",
   "type": "module",
   "main": "./index.ts",
@@ -26,7 +26,7 @@
     "@opencode/plugin": "^2"
   },
   "devDependencies": {
-    "@opencode/plugin": "^2.0.24",
+    "@opencode/plugin": "^2.0.28",
     "@types/node": "^26.6.4",
     "typescript": "^5.9.3"
   }