cache

package
v0.70.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 3, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CallerKindAdmin     = "admin"      // API-key admin: administrator
	CallerKindAdminUser = "admin_user" // OAuth admin (server edition): administrator
	CallerKindAnonymous = "anonymous"  // unauthenticated /mcp caller (back-compat admin): administrator-shaped
	CallerKindAgent     = "agent"      // agent token: bounded by AllowedServers/Permissions/ProfilePin
	CallerKindUser      = "user"       // OAuth user (server edition): bounded to its own identity
	// CallerKindInternal marks an entry the proxy wrote for ITSELF — the
	// registry search cache and the repository guesser cache. No request
	// produces such an entry, so no read_cache caller can redeem it, the
	// administrator included (Spec 105 FR-002, SC-005 named exception). Its
	// legitimate readers are the ungated Peek/Get paths of its writers.
	CallerKindInternal = "internal"
)

Caller kinds recorded on a cache entry. They mirror the auth context types the MCP layer hands out; the cache package keeps its own copy so it does not depend on internal/auth.

View Source
const (
	CacheBucket      = "cache"
	CacheStatsBucket = "cache_stats"
	// CacheSnapshotBucket holds each distinct producer authorization snapshot
	// ONCE, keyed by the digest its records' frame headers carry, for
	// ADMINISTRATOR DIAGNOSTICS only: no read path consults it — the gate
	// decides on the header alone (research D16). Written in the same
	// transaction as the record that first references it; unreferenced
	// snapshots are dropped by the cleanup sweep.
	CacheSnapshotBucket = "cache_snapshots"
	DefaultTTL          = 2 * time.Hour
	CleanupInterval     = 10 * time.Minute
)
View Source
const RecordVersion uint8 = 1

RecordVersion is the provenance schema current binaries stamp on every record they write. Bump it only when the meaning of Producer changes in a way older readers must not trust — a bump makes every existing entry legacy.

Variables

View Source
var (
	// ErrKeyNotFound: no entry under the key (or nothing left after an
	// invalidation).
	ErrKeyNotFound = errors.New("cache key not found")
	// ErrKeyExpired: the entry had passed its TTL. The ungated Get evicts it;
	// the gated read refuses it like a miss and leaves it to the cleanup
	// sweep (see getGuarded).
	ErrKeyExpired = errors.New("cache key expired")
)

Read outcomes a caller can act on with errors.Is. The messages are part of the agent-facing contract: the read_cache banner and its consumers key on "cache key not found", and the non-disclosing refusal for scoped callers (Spec 105 FR-001) reuses ErrKeyNotFound verbatim.

View Source
var ErrEntryUnreadable = errors.New("cache entry is unreadable and has been invalidated")

ErrEntryUnreadable is returned by a gated read to a reader the header ADMITTED whose entry then proved unreadable: a body this binary cannot decode, or one that disagrees with the header it sits behind. It is not an ErrUnauthorizedRead — the reader was entitled to the entry, and what it learns (its own entry is corrupt) discloses nothing about another subject — and it is not a miss: the refusal shape is decided on the fixed header only, so an admitted reader never receives it (codex round 6). The entry has been invalidated by the time the caller sees the error.

View Source
var ErrForwardedMismatch = fmt.Errorf("%w: entry was produced for a different set of forwarded client headers", ErrUnauthorizedRead)

ErrForwardedMismatch is the ErrUnauthorizedRead the read_cache handler returns when an entry was produced by a call that forwarded client headers (Spec 112 FR-017) and the redeeming request's forwarded set for the same upstream differs or is absent. errors.Is(err, ErrUnauthorizedRead) holds, so scoped callers get the same non-disclosing not-found body.

View Source
var ErrInternalEntry = fmt.Errorf("%w: entry is internal to the proxy", ErrUnauthorizedRead)

ErrInternalEntry is the ErrUnauthorizedRead a gated read returns for an internal (registry/guesser) entry. The entry is kept: its keys are guessable, and evicting on refusal would let any caller purge what the proxy's own readers depend on. errors.Is(err, ErrUnauthorizedRead) holds.

View Source
var ErrLegacyProvenance = fmt.Errorf("%w: entry predates provenance stamping and has been invalidated", ErrUnauthorizedRead)

ErrLegacyProvenance is the ErrUnauthorizedRead a gated read returns for an entry with absent, legacy or unrecognised provenance (Spec 105 FR-002). The entry has been invalidated by the time the caller sees it. errors.Is(err, ErrUnauthorizedRead) holds.

View Source
var ErrUnauthorizedRead = errors.New("cache entry was produced under an authorization this request does not hold")

ErrUnauthorizedRead is returned when a reader's authorization could not have produced the entry it asks for (Spec 104 FR-016a), and for the entries no request could have produced: legacy provenance and internal entries (Spec 105 FR-002). The handler surfaces one non-disclosing body for scoped callers.

Functions

func GenerateKey

func GenerateKey(toolName string, args map[string]interface{}, timestamp time.Time) string

GenerateKey generates a cache key from tool name, arguments, and timestamp.

The timestamp is mixed in at nanosecond granularity. The truncator calls this with time.Now() once per truncated payload; a single upstream result can carry multiple oversized TextContent blocks, and recursive read_cache truncation can mint several keys in quick succession. At second granularity any of those that landed in the same wall-clock second collided on one key, so a later Store silently overwrote an earlier payload and the earlier banner resolved to the wrong data. GenerateKey is a PURE function of its inputs (asserted by TestGenerateKey); callers that need per-call uniqueness must supply distinct timestamps — see NextUniqueTimestamp.

func IsKnownCallerKind added in v0.68.0

func IsKnownCallerKind(kind string) bool

IsKnownCallerKind reports whether kind is one this binary stamps and gates on. A record carrying any other kind has provenance this binary does not recognise (see Record.HasCurrentProvenance).

func NextUniqueTimestamp added in v0.51.0

func NextUniqueTimestamp() time.Time

NextUniqueTimestamp returns a strictly increasing timestamp for cache-key generation. time.Now() alone is not collision-safe: Windows wall-clock resolution is ~0.5-15.6ms, so two truncated blocks in the same tick got identical UnixNano readings and therefore identical keys (flaked TestForwardContentResult_MultipleTextBlocksDistinctKeys on windows-latest). A process-wide atomic high-water mark bumps same-tick readings by 1ns each, preserving GenerateKey's purity while guaranteeing distinct inputs.

Types

type Authorization added in v0.66.0

type Authorization struct {
	CallerKind string `json:"caller_kind"`
	// Principal identifies the caller within its kind: agent name for agent
	// tokens, user id for OAuth users. Empty for administrator kinds.
	Principal string `json:"principal,omitempty"`
	// AllowedServers is the agent token's server scope ("*" = every server).
	// nil means unrestricted for administrator kinds; for an agent it is an
	// empty grant, which the dispatch gates (auth.CanAccessServer) and the
	// read gate alike treat as deny-all.
	AllowedServers []string `json:"allowed_servers,omitempty"`
	// Permissions is the agent token's permission tier list. nil means
	// unrestricted (administrator kinds).
	Permissions []string `json:"permissions,omitempty"`
	// ProfilePin is the agent token's pinned profile ("" = unpinned).
	ProfilePin string `json:"profile_pin,omitempty"`
	// Profile is the effective profile the request was bounded to (token pin >
	// URL profile > session set_profile), "" when unscoped.
	Profile string `json:"profile,omitempty"`
	// ProfileScoped is true when a profile bounded the request. It is kept
	// separate from ProfileServers because a deny-all scope (an empty profile,
	// or the scope a stale pin resolves to) is scoped with NO servers, which
	// omitempty could not tell apart from unscoped.
	ProfileScoped bool `json:"profile_scoped,omitempty"`
	// ProfileServers is the effective server set of that profile at the time
	// of the request. The read gate compares server sets, not names: deleting
	// or narrowing a profile must revoke cached access, and a stale pin keeps
	// its name while resolving to deny-all.
	ProfileServers []string `json:"profile_servers,omitempty"`
	// PolicyFingerprint is the effective profile's Spec 108 tool-policy
	// fingerprint (profile.CompiledPolicy.Fingerprint, hex-encoded), set only
	// when ProfileScoped and the profile has a compiled policy. Editing a
	// profile's policy (tier cap, allow/deny, classify, unannotated handling,
	// code execution, management tools, switchable_to) changes this without
	// necessarily changing ProfileServers, so a page cached under the old
	// policy is refused after the edit even though the server-scope dimension
	// is unchanged (FR-027).
	PolicyFingerprint string `json:"policy_fingerprint,omitempty"`
	// ToolTierGeneration is the Supervisor-wide counter (runtime/supervisor.
	// Supervisor.ToolTierGeneration) bumped whenever any server's discovered
	// tool set is republished — and therefore whenever any tool's effective
	// annotations may have changed, or a tool appeared/disappeared — set only
	// when ProfileScoped. A page cached while a tool was classified read and
	// later re-listed with a destructive hint is refused by the next
	// read_cache once this has moved, with no config edit at all (FR-027).
	ToolTierGeneration uint64 `json:"tool_tier_generation,omitempty"`
}

Authorization is the authorization a cache entry was produced under, and the authorization a read_cache request presents. A cache key is a hash, not a credential: without this record a narrower token on the same MCP session could page a payload a broader token generated.

func (Authorization) CouldHaveProduced added in v0.66.0

func (a Authorization) CouldHaveProduced(reader Authorization) bool

CouldHaveProduced reports whether reader may redeem an entry produced under a: it is admits over the facts a stored header carries for a, so the predicate and the gated door (Manager.GetRecordsAs) return one verdict. See admits for the ordering.

func (Authorization) DenyAll added in v0.68.0

func (a Authorization) DenyAll() bool

DenyAll reports whether a SCOPED snapshot could have authorized no tool call at all: an empty server grant (deny-all on every dispatch gate — an agent or user AuthContext with no AllowedServers reaches nothing), or a binding to an empty effective profile (an empty profile, or the scope a stale pin resolves to). As a producer snapshot it could not have authorized the entry it is stamped on, so no scoped reader qualifies for it however broad; as a reader it could not have produced ANY entry, its own deny-all-stamped one included. Administrator kinds are never deny-all here: the read gate admits them on kind alone. The frame header records this bit so the gated read can refuse a scoped reader without loading the snapshot.

func (Authorization) IsAdministrator added in v0.68.0

func (a Authorization) IsAdministrator() bool

IsAdministrator reports whether the caller kind is an administrator kind: the API-key admin, the OAuth admin of the server edition, and the administrator-shaped anonymous /mcp caller. The name is deliberately about KIND, not reach — an administrator request can still be bounded to a profile, and the read gate ignores that binding (Spec 105 FR-001, D5).

func (Authorization) IsScoped added in v0.68.0

func (a Authorization) IsScoped() bool

IsScoped reports whether the caller kind is bounded by the dispatch gates — auth.CanAccessServer, HasPermission and the effective profile — rather than admitted as an administrator: agent tokens and server-edition OAuth users. A user is allowlist-scoped exactly like an agent at every dispatch gate (call_tool_*, direct dispatch, retrieve_tools/describe_tool visibility, set_profile), so the read gate bounds it the same way (codex round 4).

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager handles cached tool responses

func NewManager

func NewManager(db *bbolt.DB, logger *zap.Logger) (*Manager, error)

NewManager creates a new cache manager

func (*Manager) Close

func (m *Manager) Close()

Close stops the cache manager

func (*Manager) Get

func (m *Manager) Get(key string) (*Record, error)

Get retrieves a cached tool response without a read gate. It is the read path of the proxy's own writers (the repository guesser); credentialed requests go through GetRecordsAs.

func (*Manager) GetRecords

func (m *Manager) GetRecords(key string, offset, limit int) (*ReadCacheResponse, error)

GetRecords retrieves paginated records from a cached response without a read gate. Callers serving a credentialed request use GetRecordsAs.

func (*Manager) GetRecordsAs added in v0.66.0

func (m *Manager) GetRecordsAs(key string, offset, limit int, reader Authorization) (*ReadCacheResponse, error)

GetRecordsAs retrieves paginated records from a cached response, refusing with ErrUnauthorizedRead when reader could not have produced the entry (Spec 104 FR-016a). The gate runs on every page.

Two classes of entry are refused for EVERY caller kind, administrators included (Spec 105 FR-002):

  • legacy provenance (no producer, no version, or a version this binary does not recognise — every entry persisted before stamping existed): refused with ErrLegacyProvenance and durably invalidated by the refusal;
  • internal entries (CallerKindInternal — the registry and guesser caches): refused with ErrInternalEntry WITHOUT eviction, since their keys are guessable and their writers' ungated readers depend on them.

Every refusal is decided on the record's fixed header. A reader the header admits whose entry then proves unreadable (undecodable body, or one that disagrees with the header) gets ErrEntryUnreadable — not an ErrUnauthorizedRead — and the entry is invalidated.

func (*Manager) GetStats

func (m *Manager) GetStats() *Stats

GetStats returns current cache statistics

func (*Manager) Invalidate added in v0.35.0

func (m *Manager) Invalidate(key string) error

Invalidate removes a single cache entry, forcing the next access to miss. It is a no-op (nil error) if the key is absent. Used by the registry refresh path (FR-007) to drop cached server lists on demand.

func (*Manager) InvalidatePrefix added in v0.35.0

func (m *Manager) InvalidatePrefix(prefix string) (int, error)

InvalidatePrefix removes every cache entry whose key starts with prefix and returns how many were deleted. Registry caches are keyed by a stable prefix (e.g. "registry-servers:<id>:") so a single refresh can drop all variants of a registry's cached results regardless of tag/query/limit (FR-007).

func (*Manager) Peek added in v0.35.0

func (m *Manager) Peek(key string) (*Record, bool)

Peek returns a cached record WITHOUT evicting it or mutating access stats, even when the entry has expired. Unlike Get (which deletes expired entries and is the read path for fresh data), Peek lets the registry layer serve a stale value while still flagging its age — callers derive freshness from time.Since(record.CreatedAt) and record.IsExpired() (FR-007). The boolean is false only when the key is absent.

func (*Manager) Refresh added in v0.35.0

func (m *Manager) Refresh(key string) error

Refresh forces the next access to re-fetch by invalidating the cached entry. The cache manager has no knowledge of the upstream source, so "refresh" is a lazy operation: it drops the stale value and the caller re-populates it on the next Store. Provided alongside Invalidate to match the data model (FR-007).

func (*Manager) Store

func (m *Manager) Store(key, toolName string, args map[string]interface{}, content, recordPath string, totalRecords int) error

Store saves a tool response to cache with no producer authorization. Such an entry has legacy provenance (Spec 105 FR-002): the gated read refuses it for every caller and invalidates it. It exists for the ungated readers and for tests that seed pre-feature records; production callers stamp the producer via StoreAs.

func (*Manager) StoreAs added in v0.66.0

func (m *Manager) StoreAs(key, toolName string, args map[string]interface{}, content, recordPath string, totalRecords int, producer Authorization) error

StoreAs saves a tool response to cache stamped with the authorization it was produced under and the current RecordVersion. GetRecordsAs refuses readers that could not have produced it.

func (*Manager) StoreAsForwarded added in v0.70.0

func (m *Manager) StoreAsForwarded(key, toolName string, args map[string]interface{}, content, recordPath string, totalRecords int, producer Authorization, forwardedDigest, forwardedServer string) error

StoreAsForwarded is StoreAs for a result produced by a call that forwarded client headers (Spec 112 FR-017): the entry additionally carries forwardedDigest (Digest of the forwarded set) and forwardedServer (the upstream it went to). Empty digest is equivalent to StoreAs.

type Meta

type Meta struct {
	Key          string `json:"key"`
	TotalRecords int    `json:"total_records"`
	Limit        int    `json:"limit"`
	Offset       int    `json:"offset"`
	TotalSize    int    `json:"total_size"`
	RecordPath   string `json:"record_path,omitempty"`
}

Meta represents metadata about the cached response

type PathSegment

type PathSegment struct {
	Type  string // "object", "array", or "parsed"
	Key   string // for object access
	Index int    // for array access
}

PathSegment represents a segment of a JSON path

type ReadCacheResponse

type ReadCacheResponse struct {
	Records []interface{} `json:"records"`
	Meta    Meta          `json:"meta"`
	// Producer is the authorization snapshot the paged entry was produced
	// under. It never reaches the wire: the read_cache handler carries it to
	// the store of a recursively re-truncated page so provenance stays
	// monotone down the chain — a child page is stamped with its PARENT's
	// snapshot, never with the (possibly broader) redeemer's (Spec 105
	// FR-001).
	Producer *Authorization `json:"-"`
	// ForwardedDigest / ForwardedServer carry the entry's Spec 112 FR-017 fact
	// to the handler, which enforces it and copies it to a re-cached child
	// page. They never reach the wire.
	ForwardedDigest string `json:"-"`
	ForwardedServer string `json:"-"`
}

ReadCacheResponse represents the response structure for read_cache tool

type Record

type Record struct {
	Key          string                 `json:"key"`
	ToolName     string                 `json:"tool_name"`
	Args         map[string]interface{} `json:"args"`
	Timestamp    time.Time              `json:"timestamp"`
	FullContent  string                 `json:"full_content"`
	RecordPath   string                 `json:"record_path,omitempty"`   // JSON path to records array
	TotalRecords int                    `json:"total_records,omitempty"` // Total number of records
	TotalSize    int                    `json:"total_size"`              // Full response size in characters
	ExpiresAt    time.Time              `json:"expires_at"`
	AccessCount  int                    `json:"access_count"`
	LastAccessed time.Time              `json:"last_accessed"`
	CreatedAt    time.Time              `json:"created_at"`
	// Producer is the authorization the entry was produced under (Spec 104
	// FR-016a). nil on entries persisted before stamping existed or written
	// through Store; together with Version it decides the entry's provenance
	// class (see HasCurrentProvenance).
	Producer *Authorization `json:"producer,omitempty"`
	// Version is the provenance schema the entry was written under (Spec 105
	// FR-002). 0/absent marks a record persisted before this field existed;
	// any value other than RecordVersion is provenance this binary does not
	// recognise. Both are legacy: refused for every caller and invalidated on
	// the first gated read.
	Version uint8 `json:"version,omitempty"`
	// ForwardedDigest is the Spec 112 FR-017 fact: the per-process HMAC of the
	// client headers forwarded on the call that produced this entry, and
	// ForwardedServer the upstream they were forwarded to. Empty when the call
	// forwarded nothing. It lives in the body only (not the frame header): the
	// authorization gate is unchanged, and the read_cache handler admits the
	// entry only to a request whose digest for the same server is equal. The
	// digest is never logged or returned.
	ForwardedDigest string `json:"forwarded_digest,omitempty"`
	ForwardedServer string `json:"forwarded_server,omitempty"`
}

Record represents a cached tool response

func (*Record) HasCurrentProvenance added in v0.68.0

func (c *Record) HasCurrentProvenance() bool

HasCurrentProvenance reports whether the record carries a producer stamp written under the current provenance schema. Anything else — no producer, no version, a version this binary does not know, a caller kind it does not know — is legacy provenance (Spec 105 FR-002): the gated read refuses it for every caller kind and invalidates it. The kind is checked structurally rather than trusting the version alone: a later binary that adds a kind without bumping RecordVersion, followed by a rollback, must not leave an entry the administrator gate would wave through (it accepts any non-internal kind for an administrator reader).

func (*Record) IsExpired

func (c *Record) IsExpired() bool

IsExpired checks if the cache record has expired

func (*Record) MarshalBinary

func (c *Record) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler for Record: the fixed frame header (derived from the record) followed by the record as JSON. There is no size bound: the header is fixed-size and names the producer by digest, so any authorization the proxy can mint fits (codex round 4). The diagnostic snapshot is persisted by the store path (Manager.storeRecord) in the same transaction — see marshalFrame.

func (*Record) UnmarshalBinary

func (c *Record) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler for Record. It accepts both the framed layout and the bare JSON a pre-frame binary wrote. The body carries every field; the header, when present, must AGREE with it — exactly, on every field it carries — or the value is corrupt. The gated read admits a reader on the header alone, so a header that promised a narrower producer, a later expiry or another size than the body it fronts would hand that reader a body the header never authorized (codex round 3, finding 1). No binary of this repository writes such a value (MarshalBinary derives the header from the record), so it is refused like any other undecodable frame: errRecordFrameMismatch, and the record is left zero — a caller never sees the body.

type Stats

type Stats struct {
	TotalEntries   int `json:"total_entries"`
	TotalSizeBytes int `json:"total_size_bytes"`
	HitCount       int `json:"hit_count"`
	MissCount      int `json:"miss_count"`
	EvictedCount   int `json:"evicted_count"`
	CleanupCount   int `json:"cleanup_count"`
}

Stats represents cache statistics

func (*Stats) MarshalBinary

func (s *Stats) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler for Stats

func (*Stats) UnmarshalBinary

func (s *Stats) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler for Stats

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL