wastebin-mcp-go/docs/adr/005-error-model.md
opencode-agent[bot] 124b5628f5
fix: typed error model with data and legacy sentinel compatibility (#240)
* Typed error refactor done; verify passes.

Co-authored-by: xlionjuan <[email protected]>

* All 6 items done; verify passes.

Co-authored-by: xlionjuan <[email protected]>

* Review: narrow error-model claims, fix Unwrap coverage, docs sync

* All findings fixed; verify passes, tests added, docs synced.

Co-authored-by: xlionjuan <[email protected]>

* Both changes done; verify + diff check pass.

Co-authored-by: xlionjuan <[email protected]>

* Docs contract fixed; verify passes clean.

Co-authored-by: xlionjuan <[email protected]>

* All 3 findings fixed; verify passes, fixture shrunk 44→26.

Co-authored-by: xlionjuan <[email protected]>

* docs contract: cover parseErrorDocRows guardrails and fix fixture scope claim

Add TestParseErrorDocRows_Behavior, table-driven tests proving that a
same-named row outside the handler-error section is ignored, a duplicate
inside the section fails closed with errDocDuplicateRow, and extraction
stops at the next heading.

Correct the fixture scope description in errorDocCases and
TestDocsMCPTools_ErrorRows: some cases deliberately duplicate rows already
pinned verbatim by exact-output unit tests to exercise placeholder
normalization, rather than claiming those rows are not duplicated.

---------

Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>
Co-authored-by: xlionjuan <[email protected]>
2026-08-04 00:39:12 +08:00

119 lines
5.6 KiB
Markdown

# ADR 005: Typed Error Model with Unified Wording
**Status:** Accepted
**Last updated:** 2026-08-02
**Supersedes:** Issue #208 (docs drift) — absorbed into this ADR.
## Context
`docs/MCP_TOOLS.md` documented error messages that drifted from the actual
runtime output. Root cause: error messages were assembled piecemeal.
`internal/wastebin/errors.go` provided sentinel constants, while five wrapping
sites (`checkContentSize`, `readFileContent`, `validateFilePath`,
`normalizeExtension`, `translateHTTPError`) appended dynamic suffixes with
ad-hoc `fmt.Errorf` calls. Documentation had to hand-copy every combination, so
drift was inevitable.
The sibling project `searxng-mcp-go` solves this with typed errors
(`ValidationError`, `SearXNGError`, `HTMLResponseError`): the output format is
produced centrally by each type's `Error()` method, and contract tests pin the
exact strings.
## Decision
### Typed errors for data-carrying errors
Errors that carry **structured, programmatically-relevant** data (size and
limit, extension, HTTP status, sandbox path, blocked component/prefix, the
underlying OS error) are represented by typed errors so that `errors.As` can
extract that data. Each typed error wraps the legacy sentinel it replaces and
implements `Unwrap()` and `Is()`, so existing `errors.Is(err, errSentinel)`
assertions keep working through the chain. `PathNotFoundError` and
`PathPermissionError` additionally join the underlying OS error into `Unwrap()`
(`errors.Join(sentinel, underlying)`), preserving `errors.Is(err,
os.ErrNotExist)` / `errors.Is(err, os.ErrPermission)` matching that callers
relied on before the refactor. Errors that carry no data remain sentinel errors
used with `errors.Is`.
Dynamic data that is **purely diagnostic** — response-body snippets, response
path details, expiration values, redirect endpoints — is not given its own
type. It is appended at the wrapping site with a `fmt.Errorf("%w: <value>",
sentinel)` suffix. The static `"<problem>; <next-step guidance>"` portion is
still produced centrally by the sentinel (or the typed error's `Error()`
method); only the value itself is assembled per call site, and the docs tables
describe it with `<placeholder>` markers.
| Type | Fields | Replaces |
|---|---|---|
| `ContentTooLargeError` | `Size`, `Limit` | `errContentTooLarge` + wrapping sites |
| `InvalidExtensionError` | `Ext` | `errInvalidExtension` + `normalizeExtension` |
| `PathNotFoundError` | `Underlying` | `errPathNotFound` + `validateFilePath` |
| `PathPermissionError` | `Underlying` | `errPathPermissionDenied` + `validateFilePath` |
| `SandboxNoMatchError` | `Path` | `errSandboxTranslationNoMatch` + `readFileContent` |
| `BlockedComponentError` | `Component` | `errBuiltinBlockedComponent` + wrapping sites |
| `BlockedPrefixError` | `Prefix` | `errBuiltinBlockedPrefix` + `stageBuiltinBlocked` |
| `HTTPError` | `StatusCode`, `Body` | `translateHTTPError` branches (403/413/422/unknown) |
### Unified wording — BREAKING
Every handler (create_paste pipeline) error message follows the
`"<problem>; <next-step guidance>"` convention, with dynamic values appended as
`: <value>`. This change added guidance to every family that previously
carried none: HTTP 403, HTTP 422, unknown HTTP status, redirects,
response-too-large, the path and file-mode sentinels (`errPathTraversal`,
`errBuiltinBlockedPrefix`, `errBuiltinBlockedComponent`, `errUserBlockedPath`,
`errFileNotText`, `errFileReadDisabled`), response validation
(`errInvalidWastebinResponse` and its parse failures), expiration errors,
hostname resolution, HTTP request failures (`HTTP request failed`, `failed to
create HTTP request`), and Wastebin response read/parse failures. Consumers
that match on exact error strings must update.
### No error codes
Error codes are intentionally out of scope for this change. They can be added
additively later by giving each typed error a `Code` field without changing the
wording convention.
### One-shot migration
The migration happens in a single change. No intermediate mixed-wording state
exists: every wrapping site produces either a typed error or a sentinel that
already follows the unified format.
### Contract tests
Each typed error's `Error()` output is pinned to the exact string in
`internal/wastebin/errors_test.go` (mirroring searxng's
`TestMCPErrors_InvalidInputs` approach). Documentation describes the message
shape with `<placeholder>` markers instead of claiming exact strings.
## Consequences
**Positive:**
- The static wording for each error family is produced centrally — by the
sentinel or the typed error's `Error()` method — so wording drift is confined
to the diagnostic values that the docs tables describe with `<placeholder>`
markers.
- `errors.Is` assertions against the legacy sentinels keep working through the
typed errors' `Unwrap()`/`Is()`.
- Errors that previously gave no next-step guidance now tell the agent what to
do.
- Docs describe a convention plus placeholders, so a wording tweak no longer
requires a documentation rewrite.
**Negative:**
- Breaking change for consumers matching on exact error strings (HTTP unknown
status, content-size wording, and messages that gained guidance).
- Two sources of truth for wording — the `Error()` methods and the docs tables —
still exist, but contract tests pin the code side and the docs tables use
placeholders.
## Related documents
- `internal/wastebin/errors.go` — sentinels and typed errors
- `internal/wastebin/errors_test.go` — contract tests pinning `Error()` output
- `docs/MCP_TOOLS.md` — error section rewritten as convention + placeholders
- `docs/adr/002-path-validation.md` — updated stage error wording
- `CONTEXT.md` — error handling summary