mirror of
https://github.com/xlionjuan/wastebin-mcp-go.git
synced 2026-11-17 04:17:54 +00:00
* 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]>
119 lines
5.6 KiB
Markdown
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
|