Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/languages/go.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,22 @@ and `errors.As` for native error handling. `FallbackTimeoutError` reports a
source deadline; callback panics become `CallbackPanicError`. `Invalidate`
returns maintenance errors, including `ErrNoRemote` without an adapter.

A Go source often returns an error for a normal outcome, such as not found, and
DialCache records each source error as a `fallback` error. Set
`Operation.ExpectedError` to mark the errors that are not failures. The caller
still gets the error unchanged and nothing is cached; only the `fallback` error
is skipped, and the fallback duration is still recorded. `FallbackTimeoutError`
and `CallbackPanicError` always count, and so does an error when the predicate
panics. To cache a not-found answer, return it as a value instead. The other
languages have no such option yet. Excerpt:

```go
op := dialcache.Operation[Profile]{
Identity: dialcache.Identity{KeyType: "user", UseCase: "profile"},
ExpectedError: func(err error) bool { return errors.Is(err, ErrNotFound) },
}
```

## Identity and values

`Identity` holds normalized strings and ordered argument pairs. Use
Expand Down
9 changes: 9 additions & 0 deletions docs/observability.md
Original file line number Diff line number Diff line change
Expand Up @@ -681,6 +681,15 @@ native error type or message:

DialCache defines these values itself, so they are identical for every adapter.

<LanguageContent language="go">

A source error that `Operation.ExpectedError` accepts, such as not found, records
no `fallback` error, even when stale recovery serves a value. The fallback timer
still records the wait. A source deadline or panic always records `fallback`.
The other languages have no such option yet.

</LanguageContent>

A valid explicit invalidation without a configured remote adapter is still an
invalidation attempt: it emits the invalidation count and `error="invalidation"`
then returns the native missing-remote error. Invalid buffer inputs fail before
Expand Down
41 changes: 40 additions & 1 deletion formal/catalogs/feature-coverage.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
"B01.static-policy-validation",
"B01.policy-leaf-omission",
"B01.capacity-validation",
"B01.expected-source-errors",
"B01.renamed-and-removed-options"
],
"assumptions": []
Expand Down Expand Up @@ -562,7 +563,8 @@
"X01.datadog-schema-mode",
"X01.datadog-validation-privacy",
"X01.shadow-log-resource-bounds",
"X01.coalescing-inspection"
"X01.coalescing-inspection",
"B01.expected-source-errors"
],
"assumptions": [
"E03"
Expand Down Expand Up @@ -906,6 +908,43 @@
"adaptation": "Both bindings reject an explicit zero shadow capacity; in Go WithShadowCapacity(0) returns ErrInvalidOption. Go distinguishes an omitted local capacity, which keeps the default of 10,000, from WithLocalCapacity(0), which disables storage while retaining coalescing.",
"gaps": []
},
{
"id": "B01.expected-source-errors",
"rule": "Operation.ExpectedError marks errors a source returns for normal outcomes: an accepted error reaches the caller unchanged, is cached in no layer and records no fallback error event, while the fallback timer, stale recovery and coalescing are unchanged; the source deadline and panic errors always count.",
"contracts": [
"B01"
],
"relatedContracts": [
"C27",
"C58"
],
"typescript": [],
"go": [
{
"test": "TestExpectedErrorRecordsNoFallbackError",
"path": "go/expected_error_test.go",
"scope": "Accepting, rejecting, nil and panicking predicates over request, local and remote layers: the source error reaches the caller and the predicate unchanged, nothing is cached or written, the fallback timer records every call and only an accepted error skips the fallback error event; a panicking predicate logs a warning.",
"sha256": "413453de509fc916ff6d370040dc84d2d4c7158efb7df9369cf7e9f181b20602"
},
{
"test": "TestExpectedErrorAlwaysCountsDeadlinesAndPanics",
"path": "go/expected_error_test.go",
"scope": "A source deadline and a source panic return FallbackTimeoutError and CallbackPanicError, record one fallback error and never call a predicate that accepts every error.",
"sha256": "413453de509fc916ff6d370040dc84d2d4c7158efb7df9369cf7e9f181b20602"
},
{
"test": "TestExpectedErrorReachesCoalescedFollowers",
"path": "go/expected_error_test.go",
"scope": "A leader and two coalesced followers get the same source error from one source call; the predicate runs once, and the flight records one fallback error only when the predicate rejects the error.",
"sha256": "413453de509fc916ff6d370040dc84d2d4c7158efb7df9369cf7e9f181b20602"
}
],
"adaptation": "Go sources return errors for normal outcomes such as not found, where TypeScript sources usually return null, which DialCache stores; the predicate keeps those errors out of the fallback error count without caching them.",
"gaps": [],
"notApplicable": {
"typescript": "TypeScript has no expected-error option yet (#287); its sources usually return null for a normal miss, which DialCache stores as a value."
}
},
{
"id": "B02.native-context-propagation",
"rule": "Enable/disable nesting restores the prior scope after return and failure, and concurrent native flows do not leak enablement.",
Expand Down
40 changes: 21 additions & 19 deletions formal/catalogs/go-parity.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
"semanticCasesSha256": "380273598e1d956a3f9fce270cc84424b342e456139b279bd56576bd3b837f65",
"executionSha256": "eaf117c3e8630013cc8df0524f84af440c470f42e8711ab4dd07b931161c784f",
"sourceAuditDispositionsSha256": "942eab018ae0d8fa189ff16c322f6d9b3301aadc7c46d00b311018728c62f34e",
"featureCoverageSha256": "7bfe01e9ed074fc4661e6db2d3397341f7f691f476e2358e4af082c8117570de",
"featureCoverageSha256": "3ad445174431b89164b9a9bbfef0adbeb7ff7e0ca6675b7c8b904392da02084a",
"coverageWitnessesSha256": "745cebececddbfa97912621ada94072d648e8e60e8b3eb013b91eefd16f352a1",
"profilesSha256": "888a522f8ad97862ebcb0b5fe363ec7bec60367fa42c60e1623141814b1991b3"
},
Expand Down Expand Up @@ -3328,13 +3328,14 @@
"nativeBindingAdaptations": [
{
"id": "B01",
"rationale": "One Go package exposes one non-generic Cache with generic Cached[T]/GetOrLoad[T] functions, a typed Operation[T] with a typed Codec and comparator, a time.Duration Policy with a typed or JSON-shaped runtime overlay, functional options and sentinel errors. Enable returns a scoped context and its close function, with callback helpers for the TypeScript shape; New returns ErrInvalidOption instead of panicking, operation validation returns errors, and functional options distinguish an omitted setting from an explicit zero or empty value. TypeScript entry-point/typechecking tests remain language-specific; observable validation and failure consequences still require Go tests.",
"rationale": "One Go package exposes one non-generic Cache with generic Cached[T]/GetOrLoad[T] functions, a typed Operation[T] with a typed Codec and comparator, a time.Duration Policy with a typed or JSON-shaped runtime overlay, functional options and sentinel errors. Enable returns a scoped context and its close function, with callback helpers for the TypeScript shape; New returns ErrInvalidOption instead of panicking, operation validation returns errors, and functional options distinguish an omitted setting from an explicit zero or empty value. TypeScript entry-point/typechecking tests remain language-specific; observable validation and failure consequences still require Go tests. Operation.ExpectedError is a Go-only option that keeps errors a source returns for normal outcomes out of the fallback error event.",
"references": [
"go/README.md",
"go/api.go",
"go/bindings.go",
"go/internal/testsuite/bindings_test.go",
"go/api_boundary_test.go"
"go/api_boundary_test.go",
"go/expected_error_test.go"
]
},
{
Expand Down Expand Up @@ -3396,7 +3397,7 @@
],
"mappingReview": {
"status": "reviewed-mapping-not-execution",
"rationale": "Static configuration and callback contracts map to typed time.Duration Policy, functional Option constructors and Operation[T]. ParsePolicy exposes the seconds-based JSON input; pointer leaves and functional options preserve omission versus explicit false/zero. ResolvePolicy applies the sparse overlay and validated feature defaults. The shadow.mismatchLogging leaves map to ShadowPolicy.MismatchLogging with a typed MismatchDiffLevel, and the logMismatches shorthand stays a *bool that expands to them.",
"rationale": "Static configuration and callback contracts map to typed time.Duration Policy, functional Option constructors and Operation[T]. ParsePolicy exposes the seconds-based JSON input; pointer leaves and functional options preserve omission versus explicit false/zero. ResolvePolicy applies the sparse overlay and validated feature defaults. The shadow.mismatchLogging leaves map to ShadowPolicy.MismatchLogging with a typed MismatchDiffLevel, and the logMismatches shorthand stays a *bool that expands to them. Operation.ExpectedError is a Go-only field: Go sources return errors for normal outcomes such as not found, where TypeScript sources return a null that DialCache stores.",
"nativeAdaptations": [
"B01",
"B02"
Expand Down Expand Up @@ -3425,7 +3426,7 @@
"RecoveryPredicate",
"MismatchEntry"
],
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d"
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d"
}
]
}
Expand Down Expand Up @@ -3511,7 +3512,7 @@
],
"mappingReview": {
"status": "reviewed-mapping-not-execution",
"rationale": "The public orchestration is divided into Cache lifecycle, Cached registration, GetOrLoad execution, source/read deadlines and detached shadow work. GetOrLoad snapshots inputs before awaiting policy; singleFlight owns leaders/followers. Go contexts, generics, returned errors and recovered callback panics replace TypeScript overloads, promises and exceptions; default diagnostic logging lives in an internal package, while public logger callbacks and inspection remain root-package bindings. The warning's leaves come from the invocation's ResolvedShadow, Operation.MismatchDiff replaces the built-in walk, and warnShadowMismatch emits one shadowMismatchLogging event; a Warn panic is the Go logger_error. Each caller waits on its own context: a leader runs the shared flight on a context its own cancellation does not end, followers stop waiting when their own context ends, the source context carries the source deadline, and detached shadow work runs on a context that ends with its job.",
"rationale": "The public orchestration is divided into Cache lifecycle, Cached registration, GetOrLoad execution, source/read deadlines and detached shadow work. GetOrLoad snapshots inputs before awaiting policy; singleFlight owns leaders/followers. Go contexts, generics, returned errors and recovered callback panics replace TypeScript overloads, promises and exceptions; default diagnostic logging lives in an internal package, while public logger callbacks and inspection remain root-package bindings. The warning's leaves come from the invocation's ResolvedShadow, Operation.MismatchDiff replaces the built-in walk, and warnShadowMismatch emits one shadowMismatchLogging event; a Warn panic is the Go logger_error. Each caller waits on its own context: a leader runs the shared flight on a context its own cancellation does not end, followers stop waiting when their own context ends, the source context carries the source deadline, and detached shadow work runs on a context that ends with its job. source records no fallback error event for an error that Operation.ExpectedError accepts; the caller still gets the error and nothing is cached, and the deadline and panic errors never reach the predicate.",
"nativeAdaptations": [
"B01",
"B02",
Expand Down Expand Up @@ -3547,11 +3548,12 @@
"singleFlight",
"shared",
"source",
"expected",
"readServing",
"putRemote",
"recover"
],
"sha256": "7872cc5aa3eada704c89f1e11ddd5ee619ebb5533f5aed95cf74f228bea0f3f9"
"sha256": "cbb35e38195a6506e766f27695127e7de1c0e8b446f8086f9322df3911015548"
},
{
"path": "go/deadline.go",
Expand All @@ -3578,7 +3580,7 @@
"Operation",
"Event"
],
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d"
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d"
},
{
"path": "go/internal/logging/logging.go",
Expand Down Expand Up @@ -3613,7 +3615,7 @@
"CallbackPanicError",
"ErrNoRemote"
],
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d"
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d"
},
{
"path": "go/redis_adapter.go",
Expand Down Expand Up @@ -3652,7 +3654,7 @@
"Codec",
"Remote"
],
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d"
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d"
},
{
"path": "go/bindings.go",
Expand Down Expand Up @@ -3722,7 +3724,7 @@
"remoteValue",
"localResult"
],
"sha256": "7872cc5aa3eada704c89f1e11ddd5ee619ebb5533f5aed95cf74f228bea0f3f9"
"sha256": "cbb35e38195a6506e766f27695127e7de1c0e8b446f8086f9322df3911015548"
}
]
}
Expand Down Expand Up @@ -3790,7 +3792,7 @@
"TimerClock",
"DeferredExecutor"
],
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d"
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d"
}
]
}
Expand Down Expand Up @@ -3874,11 +3876,11 @@
"putLocal",
"shared"
],
"sha256": "7872cc5aa3eada704c89f1e11ddd5ee619ebb5533f5aed95cf74f228bea0f3f9"
"sha256": "cbb35e38195a6506e766f27695127e7de1c0e8b446f8086f9322df3911015548"
},
{
"path": "go/api.go",
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d",
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d",
"symbols": [
"systemClock",
"newSystemClock"
Expand Down Expand Up @@ -3944,7 +3946,7 @@
"canRecover",
"recover"
],
"sha256": "7872cc5aa3eada704c89f1e11ddd5ee619ebb5533f5aed95cf74f228bea0f3f9"
"sha256": "cbb35e38195a6506e766f27695127e7de1c0e8b446f8086f9322df3911015548"
},
{
"path": "go/shadow.go",
Expand Down Expand Up @@ -4241,7 +4243,7 @@
"Option",
"Logger"
],
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d"
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d"
},
{
"path": "go/metrics.go",
Expand All @@ -4260,7 +4262,7 @@
"errorEvent",
"duration"
],
"sha256": "7872cc5aa3eada704c89f1e11ddd5ee619ebb5533f5aed95cf74f228bea0f3f9"
"sha256": "cbb35e38195a6506e766f27695127e7de1c0e8b446f8086f9322df3911015548"
},
{
"path": "go/shadow.go",
Expand Down Expand Up @@ -4354,7 +4356,7 @@
"Remote",
"ReadBudget"
],
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d"
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d"
},
{
"path": "go/protocol.go",
Expand Down Expand Up @@ -4430,7 +4432,7 @@
"Codec",
"ContextCodec"
],
"sha256": "45ae467fbcef94cb47ebb9e9912f06c81ee03529ad63a108e91db017cd3a1f7d"
"sha256": "bb3080c11fbdff95e379bdca68484ed4bd755fe7d8e080e1394026bfda4f028d"
},
{
"path": "go/codec.go",
Expand Down
8 changes: 4 additions & 4 deletions formal/catalogs/source-audit.json
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@
},
{
"path": "docs/languages/go.md",
"sha256": "68b3b6822ee4aa51bdc8b39bd81ae8d5ffd3193fbcad7bac8b46e72cb6be3dda",
"sha256": "0a3c089446b3ed433db2b6c72a969b3b3147a963c77d67380d161d67e2609761",
"entries": [
{"title":"Go integration","contracts":["B01"]},
{"title":"Installation and runtime","contracts":["B01","B02"]},
Expand Down Expand Up @@ -235,7 +235,7 @@
},
{
"path": "docs/observability.md",
"sha256": "230f8597110bad4d6327f03d31cb4e045bd26a5b7036cfbc6314add50eae18d2",
"sha256": "2ecbb37cd8f7d4631a778ecc7ffe61e26e6c128fe97f83a4bf48429950a032d0",
"entries": [
{"title":"Observability","contracts":["C30","X01"]},
{"title":"Reading the signals","contracts":["C58"]},
Expand Down Expand Up @@ -1507,7 +1507,7 @@
},
{
"path": "formal/guides/GO-PARITY.md",
"sha256": "c245fd24071f3503447c0f5a43a984a36a447672a261d741a1af83b8c1f17771",
"sha256": "5fe0d41296892a60a4501a7f56533d388dbaf981cf37dc9a484c48dd2d67b1c9",
"entries": [
{"title":"Go parity acceptance"},
{"title":"Required evidence"},
Expand Down Expand Up @@ -1800,7 +1800,7 @@
},
{
"path": "go/README.md",
"sha256": "01224a60c2a05dabdf150351e03115445b69d936f538d17014c94a562e734a86",
"sha256": "8b505722059780c040604bdf73a776747df1d3a463ad27b74f6d9ba6fe3dc457",
"entries": [
{"title":"DialCache for Go"},
{"title":"Use"},
Expand Down
11 changes: 11 additions & 0 deletions formal/guides/GO-PARITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,17 @@ bindings have focused native tests and share the generated policy and shadow
replay evidence above. The ledger and feature inventory distinguish each
portable case's Quint evidence from its additional native binding requirements.

`Operation.ExpectedError` is a Go-only binding option. Go sources return errors
for normal outcomes such as not found, where TypeScript and Python sources
usually return a value that DialCache stores. An error the predicate accepts
still reaches the caller unchanged and is not stored, but it records no
`fallback` error event, even when stale recovery serves; C58's rule that a
recovered failure still counts applies to the errors it does not accept. The
fallback duration, stale recovery and coalescing are unchanged, and the source
deadline and panic errors never reach the predicate. With the field unset the
shared replay evidence applies unchanged; native tests in
[`expected_error_test.go`](../../go/expected_error_test.go) cover the option.

`MetricsAdapter.ObserveEvent` accepts backend-neutral diagnostics.
`FailureIsolatedObserver` and `FailureIsolatedLogger` prevent exporter errors
or panics from replacing cache/source results. Confirmed-mismatch warning fields
Expand Down
6 changes: 6 additions & 0 deletions go/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,12 @@ Source/codec/provider/comparator panics become `CallbackPanicError`; telemetry
panics are ignored. Cache plumbing fails open while explicit maintenance errors
are returned. Applications still own cancellation of the source context.

DialCache records every source error as a `fallback` error, including one that
reports a normal outcome such as not found. Set `Operation.ExpectedError` to
mark those errors: the caller still gets the error and nothing is cached, but no
`fallback` error is recorded. A source deadline or panic always counts. Only Go
has this option for now.

`WithClock` separates wall time from elapsed time. The default clock preserves
fractional milliseconds through `PreciseClock.ElapsedTime`. Custom clocks can
implement that optional interface; existing `ElapsedMS`-only clocks retain their
Expand Down
Loading
Loading