cache

package
v0.66.0 Latest Latest
Warning

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

Go to latest
Published: Sep 12, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CallerKindAdmin     = "admin"      // API-key admin: unrestricted
	CallerKindAdminUser = "admin_user" // OAuth admin (server edition): unrestricted
	CallerKindAnonymous = "anonymous"  // unauthenticated /mcp caller (back-compat admin): unrestricted
	CallerKindAgent     = "agent"      // agent token: bounded by AllowedServers/Permissions/ProfilePin
	CallerKindUser      = "user"       // OAuth user (server edition): bounded to its own identity
)

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"
	DefaultTTL       = 2 * time.Hour
	CleanupInterval  = 10 * time.Minute
)

Variables

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).

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 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 unrestricted kinds.
	Principal string `json:"principal,omitempty"`
	// AllowedServers is the agent token's server scope ("*" = every server).
	// nil means unrestricted (admin kinds).
	AllowedServers []string `json:"allowed_servers,omitempty"`
	// Permissions is the agent token's permission tier list. nil means
	// unrestricted (admin 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"`
}

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 is at least as broad as the producing authorization a in every dimension — i.e. whether the reader could have generated the entry itself. That is the read gate for read_cache: a reader never sees a payload it could not have obtained by calling the tool.

Profile scope is compared first and for every kind: a request bounded to a profile (by pin, URL or set_profile) is narrower than an unscoped one, and a scoped reader must currently cover every server the producer's profile exposed — compared as server sets, so a profile that was deleted (stale pin: same name, deny-all scope) or narrowed since the entry was produced no longer reads it.

The anonymous kind is unrestricted for tool calls but is not an identity (auth.AnonymousContext), so it ranks below an authenticated admin: it may read anonymous, agent and user entries, never an authenticated admin's.

func (Authorization) Unrestricted added in v0.66.0

func (a Authorization) Unrestricted() bool

Unrestricted reports whether the caller kind carries no server/permission bound of its own.

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

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. An entry with no recorded producer (persisted before stamping existed, or written through Store by an internal caller) is treated as produced by an unrestricted caller with no identity — readable by any unrestricted kind, never by an agent or user.

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 is readable only by unrestricted callers; 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. GetRecordsAs refuses readers that could not have produced it.

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"`
}

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 by internal callers; those are readable only by
	// unrestricted callers.
	Producer *Authorization `json:"producer,omitempty"`
}

Record represents a cached tool response

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

func (*Record) UnmarshalBinary

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

UnmarshalBinary implements encoding.BinaryUnmarshaler for Record

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