Documentation
¶
Index ¶
- Constants
- Variables
- func GenerateKey(toolName string, args map[string]interface{}, timestamp time.Time) string
- func NextUniqueTimestamp() time.Time
- type Authorization
- type Manager
- func (m *Manager) Close()
- func (m *Manager) Get(key string) (*Record, error)
- func (m *Manager) GetRecords(key string, offset, limit int) (*ReadCacheResponse, error)
- func (m *Manager) GetRecordsAs(key string, offset, limit int, reader Authorization) (*ReadCacheResponse, error)
- func (m *Manager) GetStats() *Stats
- func (m *Manager) Invalidate(key string) error
- func (m *Manager) InvalidatePrefix(prefix string) (int, error)
- func (m *Manager) Peek(key string) (*Record, bool)
- func (m *Manager) Refresh(key string) error
- func (m *Manager) Store(key, toolName string, args map[string]interface{}, content, recordPath string, ...) error
- func (m *Manager) StoreAs(key, toolName string, args map[string]interface{}, content, recordPath string, ...) error
- type Meta
- type PathSegment
- type ReadCacheResponse
- type Record
- type Stats
Constants ¶
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.
const ( CacheBucket = "cache" CacheStatsBucket = "cache_stats" DefaultTTL = 2 * time.Hour CleanupInterval = 10 * time.Minute )
Variables ¶
ErrUnauthorizedRead is returned when a reader's authorization could not have produced the entry it asks for (Spec 104 FR-016a).
Functions ¶
func GenerateKey ¶
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
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 ¶
NewManager creates a new cache manager
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) Invalidate ¶ added in v0.35.0
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
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
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
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) MarshalBinary ¶
MarshalBinary implements encoding.BinaryMarshaler for Record
func (*Record) UnmarshalBinary ¶
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 ¶
MarshalBinary implements encoding.BinaryMarshaler for Stats
func (*Stats) UnmarshalBinary ¶
UnmarshalBinary implements encoding.BinaryUnmarshaler for Stats