Skip to content

feat(go): let an operation mark expected source errors - #288

Draft
lan17 wants to merge 2 commits into
mainfrom
feat/go-expected-source-errors
Draft

lan17 wants to merge 2 commits into
mainfrom
feat/go-expected-source-errors

Conversation

@lan17

@lan17 lan17 commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Problem

The Go source path records error{error="fallback", in_fallback="true"} for every source error that a caller still waits for. Go code returns an error for normal outcomes such as not found, where TypeScript and Python sources usually return null or None, which DialCache stores as a value. So in Go a normal "not found" shows as a fallback error, and real source failures hide among normal answers. The maintainer reported this while he added DialCache to a Go service whose source returns a "not found" error for a key that has no value yet. That service must not cache "not found", because the first write for such a key does not invalidate. Refs #287 for the Rust, TypeScript and Python ports.

Change

Public API, Go only. Operation[T] gets one field, ExpectedError func(error) bool.

op := dialcache.Operation[Profile]{
	Identity:      dialcache.Identity{KeyType: "user", UseCase: "profile"},
	ExpectedError: func(err error) bool { return errors.Is(err, ErrNotFound) },
}
  • When the source returns an error and the predicate returns true, the caller gets the same error value, so errors.Is and errors.As still work. DialCache stores nothing in any layer, as today, and the fallback timer still records the duration. Only the fallback error event is skipped.
  • DialCache's own errors always count and never reach the predicate: FallbackTimeoutError (source deadline) and CallbackPanicError (source panic). DialCache returns both unwrapped, so a type check finds them. A source that returns another operation's error of these types unchanged also counts.
  • A nil field, false or a panic in the predicate gives today's behavior. The predicate runs through callSafely, like the recovery predicate, and a panic logs a warning.
  • The predicate runs only where the error event would otherwise be recorded, once per flight. Coalesced followers get the leader's result, and there is still at most one event per flight.
  • Stale recovery keeps its own predicate. An accepted error that stale recovery serves still records no fallback error, so C58's rule that a recovered failure still counts applies to the errors the predicate does not accept. GO-PARITY.md and the Go note in docs/observability.md say so. Shadow validation is unchanged and still reports source_error for any source error.
  • With the field unset nothing changes, so no replay, parity, vector or wire test changed.
  • No design record. The change adds one optional field to one port, leaves how callers construct the cache and call its operations unchanged, and changes no CONTRACTS.md text. The maintainer chose a per-operation, Go-only option with no instance-level setting. The mutant rule fires, because formal/catalogs/mutations.json names go/engine.go (no anchor touches the changed lines), so the tier is Mutations. No docs/upgrading.md note, because nothing changes for existing callers.
  • Docs: go/README.md, docs/languages/go.md with an excerpt, a Go note under Error categories in docs/observability.md, and formal/guides/GO-PARITY.md. Each says that only Go has the option for now.
  • Ledgers, refreshed in the order of formal/catalogs/README.md: source-audit.json for the four edited pages; feature-coverage.json for a new native case, B01.expected-source-errors, with the three new tests, listed under the api and observability features, and TypeScript not applicable (Expected source errors for the Rust, TypeScript and Python ports #287); go-parity.json for the re-pinned go/api.go and go/engine.go hashes, the new expected symbol, the mapping rationale and the B01 binding adaptation.

Ports

Port Status
TypeScript N/A: sources usually return null for not found, which DialCache stores; #287
Go done
Rust N/A: sources return Err for normal outcomes, so the same problem applies; #287
Python N/A: sources usually return None for not found; #287

Validation

Head: d662e80 (merge of main at 995c629 into 2c18aef)

  • make check-go (go vet, gofmt and race tests with coverage) at d662e80: passed.
  • make audit at d662e80: passed.
  • corepack pnpm docs:check and make docs at d662e80: passed.
  • PR CI at d662e80: every check passed, including test, go, typescript, rust, python, wire, quint, differential (1) to (4), Build documentation and Validate PR title.
  • formal-full.yaml in mutations mode, run 44166353511, at d662e80: success (generate, symbolic, TypeScript, Go, Rust and Python parity, and the TypeScript, Go and Rust mutation campaigns).
  • go -C go test -race -count=1 -run TestExpectedError ./ at 2c18aef: passed, 3 tests with 8 subtests: accepting, rejecting, nil and panicking predicates; deadline and panic errors; coalesced followers. The merge did not change the tested files; make check-go ran them again at d662e80.
  • Negative control, run on the uncommitted tree before the first commit: removing the new condition in source, removing the type check, or making expected always false each fails these tests.
  • PR CI at 2c18aef: every check passed.
  • formal-full.yaml in mutations mode, run 44047562498, at 2c18aef: success (generate, symbolic, TypeScript, Go, Rust and Python parity, and the TypeScript, Go and Rust mutation campaigns). The merge of main changed Go source, so it does not cover d662e80.

Not run: locally, make integration-go and make integration-wire need Docker. check-ts, check-rust and check-python were not run locally, because those ports are unchanged. CI ran all of them.

Follow-ups

Operation.ExpectedError reports whether an error that the source
returned is a normal outcome, such as not found. For an accepted error
the caller still gets the same error and nothing is cached, and the
fallback timer still records, but DialCache records no fallback error
event. The source deadline and panic errors never reach the predicate,
and a nil, false or panicking predicate keeps today's behavior. Stale
recovery and coalescing are unchanged. Go only for now; #287 tracks
the other ports.
@codecov-commenter

codecov-commenter commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.80%. Comparing base (995c629) to head (d662e80).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #288      +/-   ##
==========================================
+ Coverage   94.79%   94.80%   +0.01%     
==========================================
  Files          84       84              
  Lines       13199    13208       +9     
  Branches      805      805              
==========================================
+ Hits        12512    12522      +10     
+ Misses        621      620       -1     
  Partials       66       66              
Flag Coverage Δ
go 94.08% <100.00%> (+0.06%) ⬆️
python 93.60% <ø> (ø)
rust 94.78% <ø> (ø)
typescript 97.21% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Resolve the ledger conflicts with the Prometheus bucket option (#286):
take main's source-audit.json and go-parity.json, apply the expected
error mapping again, and refresh both in the catalog README's order.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants