weir

type BreakerConfig struct {
	Window         time.Duration // 0: 10s (10 buckets)
	MinRequests    int           // 0: 20
	FailureRatio   float64       // 0: 0.5; (0, 1]
	OpenFor        time.Duration // 0: 5s
	MaxOpenFor     time.Duration // 0: max(60s, OpenFor); at least OpenFor
	HalfOpenProbes int           // 0: 1
	CountStatus500 bool
	Disable        bool
}

type BreakerState uint8

type BypassConfig struct {
	Cookies               []string
	Headers               []string      // canonicalized
	ReportStrippedCookies time.Duration // FR-OBS-5; 0: 5m; negative disables
}

type CacheGroupsConfig struct{ Ignore bool }

type CacheInfo struct {
	Hit       bool          // answered without contacting the origin for this request
	Fwd       FwdReason     // why the request went forward; FwdNone when Hit
	Stale     StaleReason   // non-zero when a stale response was served
	FwdStatus int           // origin status when Fwd != FwdNone (304 on revalidation)
	Stored    bool          // the forwarded response was stored
	Collapsed bool          // this request waited on another request's flight
	TTL       time.Duration // remaining freshness at send time; negative when stale
	Detail    string        // implementation detail for Cache-Status, e.g. "negative"
}

type ClientConfig struct{ HonorRevalidation bool }

type CoalesceConfig struct {
	LeaderMaxAge    time.Duration // 0: min(10s, Timeouts.Origin); at most Timeouts.Origin
	FollowerMaxWait time.Duration // 0: min(10s, Timeouts.Origin); at most Timeouts.Origin
	HitForMissTTL   time.Duration // 0: 30s
}

type Config struct {
	Store         store.Store // nil: memory store sized per FR-MEM-1
	Key           KeyConfig
	Forward       ForwardConfig
	Bypass        BypassConfig
	Storable      StorableConfig
	Freshness     FreshnessConfig
	Coalesce      CoalesceConfig
	Limiter       LimiterConfig
	Breaker       BreakerConfig
	Negative      NegativeConfig
	MissRate      MissRateConfig
	CacheGroups   CacheGroupsConfig
	Client        ClientConfig
	Timeouts      TimeoutsConfig
	Warm          WarmConfig
	Limits        LimitsConfig
	CacheStatus   string // Cache-Status member name (FR-SRV-9); "": "Weir"
	NoCacheStatus bool   // omit the Cache-Status header (T-27)
	Observer      Observer
	Logger        *slog.Logger   // nil: discard
	Rand          func() float64 // [0, 1); safe for concurrent use; nil: rand.Float64
}

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

type EngineStats struct {
	Inflight     int          // origin fetches holding limiter slots
	Queued       int          // fetches waiting for a slot
	BreakerState BreakerState // BreakerClosed, BreakerHalfOpen or BreakerOpen
	StoreBytes   int64        // -1 when the store does not implement store.Sizer
}

type Event struct {
	Kind      EventKind
	Time      time.Time
	Partition string        // truncated to 256 bytes; empty for engine-wide events; never a metric label
	Duration  time.Duration // fetch, wait, or open duration where relevant
	Status    int
	Reason    string    // fixed vocabulary per kind, safe as a metric label
	Info      CacheInfo // for EvRequest
}

type EventKind uint8

type ForwardConfig struct {
	Mode           ForwardMode
	Allow          []string // canonicalized; added to the trace headers
	NoTraceHeaders bool     // D29: do not forward traceparent, tracestate, X-Request-Id
}

type ForwardMode uint8

type FreshnessConfig struct {
	Jitter                      float64 // 0: 0.10 unless NoJitter; [0, 0.5]
	NoJitter                    bool
	JitterMinLifetime           time.Duration // 0: 10s
	EarlyRefreshBeta            float64       // 0: 1.0
	NoEarlyRefresh              bool
	HeuristicFraction           float64       // 0: 0.1
	HeuristicMax                time.Duration // 0: 1h
	DefaultTTL                  time.Duration // 0: none
	DefaultStaleWhileRevalidate time.Duration // 0: none
	DefaultStaleIfError         time.Duration // 0: none
	Keep                        time.Duration // 0: 5m; only entries with a validator
}

type FwdReason uint8

type KeyConfig struct {
	QueryDrop      []string // exact names or "prefix*"
	QueryKeep      []string // allowlist; empty means keep all
	QuerySort      bool
	NormalizePath  bool
	Headers        []string // canonicalized with http.CanonicalHeaderKey
	Cookies        []string // order is the forwarded order
	Vary           VaryMode
	VaryAllow      []string // canonicalized; required for sensitive Vary names
	MaxVaryHeaders int      // 0: 8
	MaxVariants    int      // 0: 8
	AcceptEncoding []string // empty: ["gzip"]; lowercased
}

type LimiterConfig struct {
	MaxConcurrent     int           // 0: 64
	MaxQueue          int           // 0: 1024
	MaxQueueWait      time.Duration // 0: 2s
	MaxPerPartition   int           // 0: 16; clamped to MaxConcurrent
	ReserveForeground int           // 0: MaxConcurrent/4, at least 1 when MaxConcurrent >= 2
	MaxPerHost        int           // 0: off (M14)
	MaxUpload         int           // D25; 0: MaxConcurrent/4, at least 1
}

type LimitsConfig struct {
	MaxPathBytes        int // 0: 8192
	MaxQueryBytes       int // 0: 8192
	MaxQueryParams      int // 0: 256
	MaxKeyedHeaderBytes int // 0: 1024
	MaxGroups           int // 0: 32
	MaxGroupBytes       int // 0: 128
}

type MissRateConfig struct {
	Window    time.Duration // 0: 10s
	TopK      int           // 0: 64
	MinMisses int           // 0: 500
	MinRatio  float64       // 0: 0.9
	Throttle  bool
	Disable   bool
}

type Mode uint8

type NegativeConfig struct {
	TTL     time.Duration // 0: 2s
	Disable bool
}

type Observer interface{ Observe(Event) }

type Origin interface {
	Fetch(ctx context.Context, req *Request) (*Response, error)
}

type OriginError struct {
	Err error
}

type OriginFunc func(ctx context.Context, req *Request) (*Response, error)

type Purge struct {
	Mode   PurgeMode // PurgeSoft (zero value) or PurgeHard
	All    bool
	URLs   []string // absolute http(s) URLs; parsed and rewritten exactly like requests
	Origin string   // "scheme://host[:port]"; required when Groups is non-empty
	Groups []string
	Eager  bool // M15: with PurgeHard, also delete matching records now (store.Scrubber)
}

type PurgeMode uint8

type Request struct {
	Method   string        // exactly as received; methods are case-sensitive
	Scheme   string        // "http" or "https"
	Host     string        // authority (host[:port]) the client addressed
	Path     string        // origin-form path, still percent-encoded, as received
	RawQuery string        // query without the leading '?', as received
	Header   http.Header   // never mutated by Weir
	Body     io.ReadCloser // nil for GET and HEAD; passed through for other methods
}

type RequestError struct {
	Reason string
}

type Response struct {
	StatusCode int
	Header     http.Header
	Body       io.ReadCloser // never nil on responses returned by Serve
	Cache      CacheInfo     // set by Serve; ignored on responses returned by an Origin
}

type RetryError struct {
	Err   error         // ErrShed or ErrCircuitOpen
	After time.Duration // RetryAfter rounds it up to whole seconds
}

type StaleReason uint8

type StorableConfig struct {
	Statuses       []int // nil: default set; never 206, 304, 500, 502, 503, 504
	MaxObjectBytes int64 // 0: 1 MiB, body plus headers
	StripSetCookie bool
	StreamTypes    []string // Content-Type media types streamed like text/event-stream (FR-STR-1)
}

type TimeoutsConfig struct {
	Origin     time.Duration // 0: 30s
	Background time.Duration // 0: 30s; background refresh and Warm (FR-TMO-1)
	Store      time.Duration // 0: 50ms (remote stores only)
	StreamIdle time.Duration // 0: 60s (D26)
}

type VaryMode uint8

type WarmConfig struct{ Concurrency int } // 0: min(4, MaxConcurrent-ReserveForeground); at most that

type WarmStats struct{ Fetched, Skipped, NotStored, Failed int }