cache

Documentation

Index

• func CacheMiddleware(c Cache, tiers *TierClassifier, cfg *config.CacheConfig) func(http.Handler) http.Handler
• func ContextWithRequestID(ctx context.Context, id string) context.Context
• func ExtractResourcePrefix(path string) string
• func GenerateCacheKey(merchantKey, method, path, query, customSuffix string) string
• func InvalidateOnMutation(c Cache, merchantKey, method, path string)
• func RequestIDFromContext(ctx context.Context) string
• func SortQueryParams(query string) string
• type Cache
• type CacheStats
• type CacheTier
• type CachedResponse
• type MemoryCache
  • func NewMemoryCache(maxBytes int64) *MemoryCache
  • func (mc *MemoryCache) Close() error
  • func (mc *MemoryCache) Delete(_ context.Context, key string) error
  • func (mc *MemoryCache) DeleteByPrefix(_ context.Context, prefix string) error
  • func (mc *MemoryCache) Get(_ context.Context, key string) (*CachedResponse, error)
  • func (mc *MemoryCache) Set(_ context.Context, key string, resp *CachedResponse, ttl time.Duration) error
  • func (mc *MemoryCache) Stats() CacheStats
• type PIIChecker
• type TierClassifier
  • func NewTierClassifier(piiChecker PIIChecker) *TierClassifier
  • func (tc *TierClassifier) Classify(method, path string, r *http.Request) TierConfig
• type TierConfig

Functions

func CacheMiddleware

func CacheMiddleware(c Cache, tiers *TierClassifier, cfg *config.CacheConfig) func(http.Handler) http.Handler

CacheMiddleware returns a middleware that caches GET responses by merchant+endpoint. It also caches POST responses for batch-cacheable endpoints (e.g. pricing batches, fee estimates) using order-independent body hashing. Cache hits skip all downstream handlers (including rate limiting).

func ContextWithRequestID

func ContextWithRequestID(ctx context.Context, id string) context.Context

ContextWithRequestID stores a request ID in the context.

func ExtractResourcePrefix

func ExtractResourcePrefix(path string) string

ExtractResourcePrefix strips the trailing path segment (assumed to be an ID) to find the broader cacheable resource path. "/listings/2021-08-01/items/SELLER/SKU123" → "/listings/2021-08-01/items/SELLER" "/orders/v0/orders/123-456-789" → "/orders/v0/orders" "/orders/v0/orders" → "/orders/v0/orders" (no trailing ID to strip)

func GenerateCacheKey

func GenerateCacheKey(merchantKey, method, path, query, customSuffix string) string

GenerateCacheKey creates a deterministic, human-readable cache key. Format: "merchantKey:method:path?sortedQuery[:customSuffix]" Keys are NOT hashed - this allows prefix-based invalidation via DeleteByPrefix. Query parameters are sorted alphabetically so "A=1&B=2" == "B=2&A=1".

func InvalidateOnMutation

func InvalidateOnMutation(c Cache, merchantKey, method, path string)

InvalidateOnMutation invalidates cached entries when a write operation occurs. Uses prefix-based invalidation: strips the trailing ID segment from the path and deletes all cache entries whose key starts with "merchantKey:GET:" + resourcePrefix. Also invalidates batch-cached listing offer elements when a listing SKU is mutated.

func RequestIDFromContext

func RequestIDFromContext(ctx context.Context) string

RequestIDFromContext retrieves the request ID stored by the logging middleware.

func SortQueryParams

func SortQueryParams(query string) string

SortQueryParams sorts query parameters alphabetically for deterministic keys.

Types

type Cache

type Cache interface {
	Get(ctx context.Context, key string) (*CachedResponse, error)
	Set(ctx context.Context, key string, resp *CachedResponse, ttl time.Duration) error
	Delete(ctx context.Context, key string) error
	DeleteByPrefix(ctx context.Context, prefix string) error
	Stats() CacheStats
	Close() error
}

Cache is the interface for response caching backends. Phase 3 provides MemoryCache; Redis/Badger can implement this later.

type CacheStats

type CacheStats struct {
	Hits       int64
	Misses     int64
	Evictions  int64
	BytesUsed  int64
	EntryCount int64
}

CacheStats holds cache hit/miss/eviction counters.

type CacheTier

type CacheTier int

CacheTier represents the caching aggressiveness for an endpoint.

const (
	CacheTierAggressive CacheTier = 1 // 6-24 hours (catalog, definitions)
	CacheTierModerate   CacheTier = 2 // 5-30 minutes (reports, inventory, listings)
	CacheTierShort      CacheTier = 3 // 30-120 seconds (orders, pricing)
	CacheTierNever      CacheTier = 4 // No caching (feeds, notifications, mutations)
)

type CachedResponse

type CachedResponse struct {
	StatusCode      int
	Headers         http.Header
	Body            []byte
	CachedAt        time.Time
	TTL             time.Duration
	SourceRequestID string // ID of the request that generated this cached response
}

CachedResponse holds a cached HTTP response.

type MemoryCache

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

MemoryCache is an in-memory LRU cache with background expiration.

func NewMemoryCache

func NewMemoryCache(maxBytes int64) *MemoryCache

NewMemoryCache creates an in-memory cache with LRU eviction. maxBytes sets the memory limit; use 0 for unlimited (not recommended).

func (*MemoryCache) Close

func (mc *MemoryCache) Close() error

func (*MemoryCache) Delete

func (mc *MemoryCache) Delete(_ context.Context, key string) error

func (*MemoryCache) DeleteByPrefix

func (mc *MemoryCache) DeleteByPrefix(_ context.Context, prefix string) error

func (*MemoryCache) Get

func (mc *MemoryCache) Get(_ context.Context, key string) (*CachedResponse, error)

func (*MemoryCache) Set

func (mc *MemoryCache) Set(_ context.Context, key string, resp *CachedResponse, ttl time.Duration) error

func (*MemoryCache) Stats

func (mc *MemoryCache) Stats() CacheStats

type PIIChecker

type PIIChecker func(r *http.Request) bool

PIIChecker returns true if the request involves PII data. In Phase 3 this is nil (no PII checking). Phase 4 provides the real implementation.

type TierClassifier

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

TierClassifier maps endpoint patterns to cache tiers.

func NewTierClassifier

func NewTierClassifier(piiChecker PIIChecker) *TierClassifier

NewTierClassifier creates a classifier with default SP-API tier patterns. piiChecker may be nil (Phase 3 default - no PII checking).

func (*TierClassifier) Classify

func (tc *TierClassifier) Classify(method, path string, r *http.Request) TierConfig

Classify determines the cache tier for a given request. Non-GET methods are CacheTierNever unless the endpoint is batch-cacheable. If piiChecker returns true, returns CacheTierNever with Reason "PII_EXCLUDED".

type TierConfig

type TierConfig struct {
	Tier           CacheTier
	DefaultTTL     time.Duration
	Reason         string // e.g. "PII_EXCLUDED"  -  empty for normal classification
	BatchCacheable bool   // true for POST batch endpoints (per-element caching)
	PostCacheable  bool   // true for single POST endpoints (body-hash caching)
}

TierConfig holds the resolved tier and TTL for a request.