@godspeedai/cognate-provider-wire 0.8.0 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/src/EGM.md +36 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@godspeedai/cognate-provider-wire",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.1",
|
|
4
4
|
"description": "Shared SSE and HTTP error boundary for fetch model adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -22,6 +22,6 @@
|
|
|
22
22
|
".": "./src/index.ts"
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
|
-
"@godspeedai/cognate-capabilities": "^0.
|
|
25
|
+
"@godspeedai/cognate-capabilities": "^0.9.1"
|
|
26
26
|
}
|
|
27
27
|
}
|
package/src/EGM.md
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# provider-wire / src — HTTP and SSE boundary over injected fetch
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
`src/index.ts` is the only module. It defines an injectable `HttpFetch` type, composes caller signals with an optional timeout, classifies upstream HTTP statuses into `ModelProviderError` kinds, posts JSON bodies, and parses Server-Sent Events from a `Response` body with incremental UTF-8 decoding. Callers supply both the URL and the fetch implementation, so the module owns protocol framing and error typing rather than transport selection.
|
|
6
|
+
|
|
7
|
+
## Interface
|
|
8
|
+
|
|
9
|
+
- `HttpFetch` — `(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>` `[packages/provider-wire/src/index.ts:HttpFetch]`
|
|
10
|
+
- `requestSignal(signal?, timeoutMs?)` — returns the caller signal, or its combination with an abort-on-timeout signal `[packages/provider-wire/src/index.ts:requestSignal]`
|
|
11
|
+
- `httpError(status)` — maps a status to a `ModelProviderError` `[packages/provider-wire/src/index.ts:httpError]`
|
|
12
|
+
- `sendJson(url, body, headers, fetchFn, signal?)` — POSTs JSON and returns the successful `Response` `[packages/provider-wire/src/index.ts:sendJson]`
|
|
13
|
+
- `SSEEvent` — `{ event: string; data: string }` `[packages/provider-wire/src/index.ts:SSEEvent]`
|
|
14
|
+
- `readSSE(response, signal?)` — async generator of parsed frames `[packages/provider-wire/src/index.ts:readSSE]`
|
|
15
|
+
|
|
16
|
+
## Invariants
|
|
17
|
+
|
|
18
|
+
- Status mapping is fixed: `401`/`403` to `unauthorized`, `429` to `rate_limited`, other `4xx` to `invalid_request`, everything else to `unavailable` `[packages/provider-wire/src/index.ts:httpError]`
|
|
19
|
+
- The upstream error message is deliberately discarded; the error text is only `model upstream HTTP <status>` so tokens or user payload cannot leak `[packages/provider-wire/src/index.ts:httpError]`
|
|
20
|
+
- A thrown fetch is `cancelled` when the signal is aborted, otherwise `unavailable` `[packages/provider-wire/src/index.ts:sendJson]`
|
|
21
|
+
- `sendJson` merges `content-type: application/json` under the caller headers, so a caller header wins `[packages/provider-wire/src/index.ts:sendJson]`
|
|
22
|
+
- A response body without a stream fails as `malformed_response` with `missing event stream` `[packages/provider-wire/src/index.ts:readSSE]`
|
|
23
|
+
- Frames are split on `\r?\n\r?\n`; only `event:` and `data:` lines are read, multiple `data:` lines join with `\n`, and a frame with no `data:` line is skipped `[packages/provider-wire/src/index.ts:decode]`
|
|
24
|
+
- A trailing frame without a blank-line terminator is still emitted when the stream ends `[packages/provider-wire/src/index.ts:readSSE]`
|
|
25
|
+
- Mid-stream failure is `cancelled` when the signal aborted and `unavailable` otherwise, because callers may retry the latter `[packages/provider-wire/src/index.ts:readSSE]`
|
|
26
|
+
- The reader lock is released in a `finally`, so an aborted consumer does not strand the body `[packages/provider-wire/src/index.ts:readSSE]`
|
|
27
|
+
|
|
28
|
+
## Side Effects
|
|
29
|
+
|
|
30
|
+
- Issues the network request through the caller's `fetchFn` only, with no ambient global fetch lookup `[packages/provider-wire/src/index.ts:sendJson]`
|
|
31
|
+
- Creates timers via `AbortSignal.timeout(timeoutMs)` only when the caller passes a timeout `[packages/provider-wire/src/index.ts:requestSignal]`
|
|
32
|
+
- Holds the response body stream and its reader until the generator completes `[packages/provider-wire/src/index.ts:readSSE]`
|
|
33
|
+
|
|
34
|
+
## Verification
|
|
35
|
+
|
|
36
|
+
- Run: `cd packages/provider-wire && bun test`
|