Skip to content

CLAUDE.md

Latest commit

 

History

History
54 lines (38 loc) · 2.8 KB

CLAUDE.md

File metadata and controls

54 lines (38 loc) · 2.8 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Run all tests
go test ./...

# Run a single test
go test -run TestMarshalUnmarshalPropagatedError .

# Regenerate code after modifying InternalState constants or PropagatedError/ErrorSource structs
go generate ./...

Architecture

This is a single-package Go library (github.com/redsift/go-errs, package errs) that provides a structured error type for use across redsift services.

Core type: PropagatedError

PropagatedError (defined in errors.go) is the central error type. It carries:

  • Id — a unique error instance ID (generated via github.com/redsift/go-foodfans)
  • Code — an InternalState enum value identifying the error category
  • Title, Detail, Link, Source — human-readable and structured context
  • Status — HTTP status code (not serialized)
  • cause — unexported wrapped error (accessible via Unwrap())

InternalState enum

InternalState (defined in lookups.go) is an iota-based int enum of error codes. Each constant is a coffee-drink name (e.g. Espresso, Latte, Cappuccino). These values are stable integers used in serialization — order matters, never reorder or remove existing constants.

Generated files

Several files are auto-generated and must not be edited manually:

  • errors_gen.go / errors_gen_test.go — msgpack serialization for PropagatedError and ErrorSource (generated by msgp)
  • lookups_gen.go / lookups_gen_test.go — msgpack serialization for InternalState
  • internalstate_string.go — String() method for InternalState (generated by stringer)
  • internalstate_jsonenums.go — JSON marshal/unmarshal for InternalState (generated by jsonenums)

Run go generate ./... after any change to InternalState constants or the PropagatedError/ErrorSource struct fields tagged with msg:.

Key helpers

  • WrapWithCode(code, err) — wraps an existing error as a PropagatedError with a specific InternalState
  • Wrap(err) — wraps using Unknown code
  • WrapAsParameterError, WrapAsConfigIssue, WrapAsAssert — convenience wrappers for common codes
  • RetryWithIncrementAndFlag(err) — inspects a PropagatedError to determine retry behavior; specific codes (Turkish, Mocha, Guillermo, Espresso, Kopitubruk, Macchiato) have defined retry semantics
  • IsCode(err, code) — checks if an error has a specific InternalState
  • Errorf(format, args...) — like fmt.Errorf but propagates PropagatedError identity when an error arg is a *PropagatedError
  • PostProcessJsonError(data, err) — enriches JSON parse errors with source location context
  • NotYetImplemented(feature) — returns a lightweight nyiError (not a PropagatedError)