Files
archie/internal/infrastructure/staterpc/error_test.go
T
sam 33751abe4e test(staterpc): verify State Store end-to-end and preserve context error identity (#775)
* test(state-store): real-process smoke + deadline/sentinel error contract

Add end-to-end verification for archie-core-8cda.4.7, the .4.7 State Store
verification stage against docs/prds/state-store-contract.md (rev. 2c):

- Real-process smoke coverage: build ./cmd/archie-state-store, run it against
  a minimal config on loopback, poll the readiness surface, and drive the
  State Store gRPC contract through staterpc.NewClient exactly as a consumer
  does. Covers the combined task/event/capture view, error-sentinel fidelity
  across the wire, the found=false-not-error convention, single-owner SQLite
  (the binary owns the one archie.db file; the consumer never opens a store
  file), per-call deadline behaviour, restart/recovery (SIGTERM + reopen on
  the same db), and the remote capture/mapping/binding surfaces.

- Fix a real deadline-identity gap in unmapError: a cancelled or
  deadline-exceeded context surfaced by gRPC-Go as a *status.Error was
  re-wrapped into a sanitised internal-style error, breaking
  errors.Is(err, context.Canceled/DeadlineExceeded). The agent's deadlineStore
  bounds each Store call with context.WithTimeout and the workflow consumer
  (workflow.go) uses errors.Is(err, context.DeadlineExceeded) to mark a stage
  interrupted rather than failed, so the re-wrap would wrongly park an
  interrupted task. Unmap Canceled/DeadlineExceeded codes back to the standard
  context sentinels.

- Pin the error-mapping contract in staterpc: context-identity preservation,
  sentinel round-trip fidelity for every store sentinel, and the sanitisation
  rule (an Internal error must not leak raw detail or map to a sentinel).

* test(state-store): assert single-owner SQLite composition (daemon/gateway require target)

The single-owner invariant (docs/prds/state-store-contract.md §12 step 7/8) is
that only archie-state-store opens archie.db; the daemon and gateway resolve
their task-store surface from openStateStoreAdapter, which requires
[services.state].target and opens no local store. This test pins that
composition root so a future change cannot silently reintroduce a local
*store.Store in the daemon or gateway path (dual-store ownership).

* test(state-store): skip real-process smoke tests under -short

The smoke tests build and exec the real archie-state-store binary, which is
slow enough that a -short run (e.g. a focused edit loop) should skip them.
task check (go test ./... -count=1) does not use -short, so they still run in
the full gate.

* test(state-store): fix subprocess log race under -race

The smoke test captured the subprocess's stdout/stderr in a strings.Builder
that the os/exec writer goroutine and the test reader goroutine touched
concurrently, racing under -race. Replace it with a mutex-guarded buffer, the
standard pattern for reading a running subprocess's output.

* test(state-store): satisfy lint (noctx, errorlint) on new tests

- exec.Command -> exec.CommandContext, http.Get -> NewRequestWithContext +
  Client.Do, so the subprocess and readiness polling honour the test context
  (noctx).
- errorlint: compare the raw non-status error via errors.Is rather than != on
  a wrapped error.

* docs(deployments): document State Store readiness verification and single-owner invariant

The deployment runbook described how to launch archie-state-store but not how
to verify it is healthy before starting archied. Document the -ready-addr
readiness surface (/healthz, /health/detailed state_db component) and the
single-owner invariant: one task SQLite file owned by archie-state-store, with
archied/archie-gateway never opening archie.db directly (state-store-contract
§12 step 7/8).

* fix(state-store): preserve context deadline/cancel identity in mapError

The symmetric server-side gap to the unmapError fix: if a store query fails
because the caller's context expires mid-call (§6 StoreTimeout), the handler's
mapError folded context.Canceled/DeadlineExceeded into codes.Internal. The
client would receive a sanitised internal error with no deadline identity, so
the agent's workflow consumer (errors.Is(err, context.DeadlineExceeded)) could
not distinguish an interrupted stage from a failed one.

Map a context cancel/deadline error to its matching gRPC code so unmapError
rehydrates it back to the standard context sentinel, completing the §6/§7
round-trip. Pin both directions with TestMapErrorPreservesContextIdentity.
2026-09-07 05:47:36 +10:00

128 lines
5.1 KiB
Go

package staterpc
import (
"context"
"errors"
"strings"
"testing"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
"github.com/samcharles93/archie-core/internal/store"
)
// TestUnmapErrorPreservesContextIdentity pins the §6 deadline contract that
// unmapError must rehydrate a gRPC Canceled / DeadlineExceeded status back to
// the standard context sentinels. The agent's deadlineStore bounds each Store
// call with context.WithTimeout and the workflow consumer checks
// errors.Is(err, context.DeadlineExceeded) to mark a stage interrupted rather
// than failed (workflow.go); if unmapError folded those into a sanitised
// internal error, a merely interrupted stage would be parked as a failure.
func TestUnmapErrorPreservesContextIdentity(t *testing.T) {
tests := []struct {
name string
err error
want error
}{
{name: "cancelled", err: status.Error(codes.Canceled, context.Canceled.Error()), want: context.Canceled},
{name: "deadline exceeded", err: status.Error(codes.DeadlineExceeded, context.DeadlineExceeded.Error()), want: context.DeadlineExceeded},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := unmapError(tt.err)
if !errors.Is(got, tt.want) {
t.Fatalf("unmapError(%q) = %v, want errors.Is(err, %v)", tt.err, got, tt.want)
}
if errors.Is(got, store.ErrStaleTransition) {
t.Fatalf("unmapError(%q) = %v, must not map to a store sentinel", tt.err, got)
}
})
}
}
// TestMapErrorPreservesContextIdentity pins the server side of the same §6
// contract: if the store (or a server handler) returns a context error because
// the caller's ctx expired mid-call, mapError must map it to the matching
// gRPC code rather than sanitising it into codes.Internal. Otherwise the
// client never sees the deadline identity and an interrupted stage is wrongly
// treated as a failure.
func TestMapErrorPreservesContextIdentity(t *testing.T) {
tests := []struct {
name string
err error
want error
}{
{name: "cancelled", err: context.Canceled, want: context.Canceled},
{name: "deadline exceeded", err: context.DeadlineExceeded, want: context.DeadlineExceeded},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
mapped := mapError(tt.err)
if got := unmapError(mapped); !errors.Is(got, tt.want) {
t.Fatalf("mapError/unmapError round-trip for %q = %v, want errors.Is(err, %v)", tt.err, got, tt.want)
}
})
}
}
// TestUnmapErrorSentinelFidelity pins the §7 sentinel rehydration round-trip
// for each store error code, so a consumer's errors.Is(err, store.ErrX) keeps
// working across the wire.
func TestUnmapErrorSentinelFidelity(t *testing.T) {
tests := []struct {
name string
store error
rehyd error
}{
{name: "stale transition", store: store.ErrStaleTransition, rehyd: store.ErrStaleTransition},
{name: "binding not found", store: store.ErrBindingNotFound, rehyd: store.ErrBindingNotFound},
{name: "mapping not found", store: store.ErrMappingNotFound, rehyd: store.ErrMappingNotFound},
{name: "binding overlap", store: store.ErrBindingOverlap, rehyd: store.ErrBindingOverlap},
{name: "binding transition", store: store.ErrBindingTransition, rehyd: store.ErrBindingTransition},
{name: "already dispatched", store: store.ErrAlreadyDispatched, rehyd: store.ErrAlreadyDispatched},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// mapError converts the store sentinel to a gRPC status; unmapError
// must recover the same sentinel. This is the round-trip the wire
// contract guarantees (§7).
mapped := mapError(tt.store)
got := unmapError(mapped)
if !errors.Is(got, tt.rehyd) {
t.Fatalf("round-trip %q -> %q: got %v, want %v", tt.store, mapped, got, tt.rehyd)
}
})
}
}
// TestUnmapErrorDoesNotLeakInternalDetail pins the §7 sanitisation rule: an
// infra/unknown error maps to codes.Internal and must not rehydrate to a store
// sentinel, the public message must not carry the raw wrapped detail (SQL
// paths, provider details), and a non-status error is returned unchanged.
func TestUnmapErrorDoesNotLeakInternalDetail(t *testing.T) {
const detail = "sql: path=/var/lib/archie/archie.db secret=abcdef"
internal := mapError(errors.New(detail))
got := unmapError(internal)
if errors.Is(got, store.ErrStaleTransition) || errors.Is(got, store.ErrBindingNotFound) || errors.Is(got, store.ErrAlreadyDispatched) {
t.Fatalf("unmapError(internal) = %v, must not map to a store sentinel", got)
}
if st, ok := status.FromError(got); !ok || st.Code() != codes.Internal {
t.Fatalf("unmapError(internal) = %v, want a codes.Internal status", got)
}
if strings.Contains(got.Error(), detail) {
t.Fatalf("unmapError leaked raw internal detail: %q", got.Error())
}
// A raw (non-status) error is returned unchanged (not wrapped into a
// status or a store sentinel).
raw := errors.New("transport failure")
got = unmapError(raw)
if errors.Is(got, store.ErrStaleTransition) {
t.Fatalf("unmapError(raw) = %v, must not map to a store sentinel", got)
}
if !errors.Is(got, raw) {
t.Fatalf("unmapError(raw) = %v, want an error chain including the original", got)
}
}