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

5.6 KiB

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.
  • 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