Grilling: result mapping and error semantics #7

New Issue

2026-10-03T16:22:29Z

haylan commented

2026-10-03 16:22:29 +00:00

Map: #1

Question

Both research tickets and the config surface are settled. Decide how the plugin maps a fastCRW response to opencode results and how it reports failures: parsing both data[] and data.results shapes, snippet/description to content, the time field, empty results, success:false and each error_code (e.g. 429, 503 search_disabled), non-JSON bodies, network errors, abort via signal, and what error messages the user sees. Fallback to built-ins is off (fastCRW is the only provider).

Map: #1 ## Question Both research tickets and the config surface are settled. Decide how the plugin maps a fastCRW response to opencode results and how it reports failures: parsing both `data[]` and `data.results` shapes, `snippet`/`description` to `content`, the `time` field, empty results, `success:false` and each `error_code` (e.g. 429, 503 `search_disabled`), non-JSON bodies, network errors, abort via `signal`, and what error messages the user sees. Fallback to built-ins is off (fastCRW is the only provider).

haylan added the wayfinder:grilling label 2026-10-03 16:22:29 +00:00

haylan self-assigned this 2026-10-03 16:46:04 +00:00

haylan commented

2026-10-03 16:46:05 +00:00

Resolved with the user (all recommendations accepted).

Parsing: accept data as an array or data.results as an array; any other shape throws "unexpected response shape".
Mapping: { url, title, content: snippet || description || "", time: {} }. time always {} (inner shape unverified); publishedDate not mapped.
Empty/malformed: empty list returns [], not an error. Entries without a string url are dropped; missing title falls back to url. No warnings logged.
API errors: throw Error("fastCRW <status> <error_code>: <error>"); HTTP 200 with success:false handled the same (status 200). Fixed hints only for 401 ("check apiKey or CRW_API_KEY") and 503 search_disabled ("the server has no search backend configured"). The token never appears in any message.
Non-JSON: throw fastCRW <status>: non-JSON response plus the first 200 chars of the body.
Network errors: throw fastCRW: cannot reach <baseURL> with the original error as cause.
Abort: an abort via opencode's signal is rethrown untouched.
Timeout/retries: fixed internal 30 s timeout combined with opencode's signal via AbortSignal.any; not configurable. No retries; a 429 keeps its status in the message so opencode's cooldown logic can see it (verify in the runtime checks).
Long queries: sent as-is; the server's 400 invalid_request flows through the error path.

Resolved with the user (all recommendations accepted). - **Parsing:** accept `data` as an array or `data.results` as an array; any other shape throws "unexpected response shape". - **Mapping:** `{ url, title, content: snippet || description || "", time: {} }`. `time` always `{}` (inner shape unverified); `publishedDate` not mapped. - **Empty/malformed:** empty list returns `[]`, not an error. Entries without a string `url` are dropped; missing `title` falls back to `url`. No warnings logged. - **API errors:** throw `Error("fastCRW <status> <error_code>: <error>")`; HTTP 200 with `success:false` handled the same (status 200). Fixed hints only for 401 ("check apiKey or CRW_API_KEY") and 503 `search_disabled` ("the server has no search backend configured"). The token never appears in any message. - **Non-JSON:** throw `fastCRW <status>: non-JSON response` plus the first 200 chars of the body. - **Network errors:** throw `fastCRW: cannot reach <baseURL>` with the original error as `cause`. - **Abort:** an abort via opencode's `signal` is rethrown untouched. - **Timeout/retries:** fixed internal 30 s timeout combined with opencode's `signal` via `AbortSignal.any`; not configurable. No retries; a 429 keeps its status in the message so opencode's cooldown logic can see it (verify in the runtime checks). - **Long queries:** sent as-is; the server's 400 `invalid_request` flows through the error path.

haylan closed this issue

2026-10-03 16:46:08 +00:00

haylan referenced this issue

2026-10-03 16:46:10 +00:00

Wayfinder map: fastCRW websearch plugin for opencode v2 #1

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: haylan/fastcrw-opencode-websearch#7