memcache

type ActiveOp interface {
	End(OpResult)
}

type BreakerConfig struct {
	// Enabled turns the circuit breaker on. When false (the zero value) no
	// breaker is created, every operation is always attempted, and the other
	// fields are ignored.
	Enabled bool

	// TripMinRequests is the minimum number of operations that must have been
	// observed within TripWindow before the breaker can trip. Below this
	// volume the failure ratio is statistically meaningless (one failure out
	// of two operations is not an outage), so the breaker stays closed
	// regardless of the ratio.
	// The default is DefaultBreakerTripMinRequests (10).
	TripMinRequests int

	// TripFailureRatio is the fraction of failed operations at which the
	// breaker trips. Each time an operation fails, the breaker looks at the
	// operations observed within TripWindow and opens when at least
	// TripMinRequests were observed and failures/operations reaches this
	// ratio. Must be in (0, 1]: 0.6 means "open when 60% of recent
	// operations failed", 1 means "open only when every recent operation
	// failed".
	// The default is DefaultBreakerTripFailureRatio (0.6).
	TripFailureRatio float64

	// TripWindow is how far back the trip condition looks: the operation and
	// failure counts cover approximately the last TripWindow (a rolling
	// window), so old failures age out and cannot combine with fresh ones to
	// trip the breaker long after a blip.
	// The default is DefaultBreakerTripWindow (10s).
	TripWindow time.Duration

	// OpenDuration is how long the breaker stays open after tripping. While
	// open, every operation to the server fails immediately with
	// ErrBreakerOpen, without dialing or using a connection. When it
	// elapses, the breaker becomes half-open and probes the server.
	// The default is DefaultBreakerOpenDuration (5s).
	OpenDuration time.Duration

	// HalfOpenMaxRequests is the number of operations let through while the
	// breaker is half-open; any further operations fail with ErrBreakerOpen
	// until the probes complete. A single failed probe reopens the breaker
	// for another OpenDuration; once this many probes have succeeded the
	// breaker closes.
	// The default is DefaultBreakerHalfOpenMaxRequests (1).
	HalfOpenMaxRequests int

	// OnStateChange, if set, is called whenever a server's breaker changes
	// state. address is the server's host:port; from and to are the states it
	// moved between (never BreakerDisabled).
	// It is called synchronously from the operation's goroutine while the
	// breaker's internal lock is held: it must return quickly and must not
	// perform memcache operations. Use it for logging and metrics.
	OnStateChange func(address string, from, to BreakerState)
}

type BreakerMetrics struct {
	State                BreakerState
	Requests             int
	TotalSuccesses       int
	TotalFailures        int
	ConsecutiveSuccesses int
	ConsecutiveFailures  int
}

type BreakerState int

type CAS uint64

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

type ClientError = meta.ClientError

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

type ConcatOptions struct {
	CAS          CAS
	CreateOnMiss bool   // create the key when it is absent (memcached's autovivify)
	TTL          TTL    // expiration of the created item; ignored unless CreateOnMiss
	Flags        uint32 // client flags of the created item; ignored unless CreateOnMiss
}

type Config struct {
	// MaxConnsPerServer is the maximum number of connections the client opens
	// to a single server. It is therefore also the number of operations that
	// can be in flight to that server at once: past it, callers wait for a
	// connection to come back.
	//
	// That wait is bounded only by the caller's context (see the Timeouts
	// section in the package documentation), so a pool sized below peak
	// concurrency plus deadline-less contexts queues waiters without shedding.
	// Size it against peak per-server concurrency, and pass contexts with
	// deadlines.
	// The default is DefaultMaxConnsPerServer (10).
	MaxConnsPerServer int

	// MaxConnLifetime is the maximum duration a connection can be reused.
	// Enforced when a connection is checked out of the pool, when it is
	// returned after an operation, and by the maintenance loop for idle
	// connections.
	//
	// Useful values are seconds to minutes. Below a second, connections are
	// recycled faster than they are useful and most operations pay a fresh
	// dial — which collapses throughput when the dial includes a TLS
	// handshake.
	// The default is no limit.
	MaxConnLifetime time.Duration

	// MaxConnIdleTime is the maximum duration a connection can be idle before
	// being closed. Enforced when a connection is checked out of the pool and
	// by the maintenance loop.
	//
	// Note that checkout-time enforcement needs traffic to act: a pool that
	// receives no operations at all only shrinks when the background
	// maintenance loop prunes it. That loop always runs; see
	// MaintenanceInterval for how its period affects how promptly this happens.
	//
	// Set it below MaxConnLifetime, or it never fires: the lifetime limit
	// always preempts it.
	// The default is no limit.
	MaxConnIdleTime time.Duration

	// MaintenanceInterval is how often the background maintenance loop runs.
	// The loop always runs; this only tunes its period.
	// The default is DefaultMaintenanceInterval (30s).
	//
	// Each pass, for every pool:
	//
	//   - pings idle connections and closes any that are broken or past
	//     MaxConnLifetime/MaxConnIdleTime, so limits are enforced even on a pool
	//     no operations are flowing through (checkout/return also enforce them,
	//     but that needs traffic to act);
	//   - reaps the pool of any server absent from the server set for
	//     reapAfterMissedPasses consecutive passes, so a client against a
	//     dynamic server set (e.g. Kubernetes endpoints) does not accumulate a
	//     pool — with its idle connections and its circuit breaker — for every
	//     address it ever routed to.
	//
	// The interval is the resolution of this maintenance, not a deadline, so a
	// longer period trades promptness for a bit less background work: an idle
	// connection a server or middlebox dropped is not noticed until the next
	// pass (or the next operation routed to it); a connection past its
	// lifetime/idle limit on an otherwise idle pool is pruned that much later;
	// and a departed server's pool — its connections and breaker — survives up
	// to reapAfterMissedPasses of these intervals before being reclaimed. Pick
	// the period against how fast your server set churns and how long you can
	// tolerate a dropped idle connection lingering; the default is a good
	// starting point. A period long enough to matter against a churning set
	// (minutes) lets departed pools pile up in the meantime, so prefer the
	// default there rather than disabling maintenance by stretching the period.
	MaintenanceInterval time.Duration

	// IdleConnCheckAfter controls the on-acquire liveness check: when a
	// connection that has been idle at least this long is checked out of the
	// pool, it is verified with a cheap non-blocking probe and transparently
	// replaced if the server, a load balancer, or a middlebox closed it while
	// it sat idle. This keeps a rolling restart or an idle-timed-out flow from
	// surfacing as a burst of failed operations on the next request.
	//
	// Freshly established and actively cycling connections (idle less than the
	// threshold) are trusted without a syscall, so the hot path is unaffected.
	// The probe cannot see through TLS, so TLS connections are always trusted
	// and rely on the next operation to detect a dead peer.
	//
	// The default is DefaultIdleConnCheckAfter (1s); a negative value disables
	// the check.
	IdleConnCheckAfter time.Duration

	// OperationTimeout bounds the read/write of a single memcache operation.
	// It acts as an upper bound on every operation: the effective deadline is
	// the earlier of the context deadline and now+OperationTimeout. A context
	// deadline sooner than OperationTimeout still wins; a later one (or a
	// context with no deadline) is capped at OperationTimeout. This ensures a
	// long-lived context (e.g. a request- or job-scoped one) cannot leave an
	// operation unbounded, so a hung-but-connected server fails fast instead of
	// stalling the client.
	//
	// OperationTimeout bounds socket I/O only. It does not bound waiting for a
	// connection from a saturated pool: that wait is bounded solely by the
	// caller's context, so pass contexts with deadlines (see the Timeouts
	// section in the package documentation).
	//
	// The cap cannot be disabled, so the client is never left unbounded by a
	// configuration mistake. Set a large explicit value for operations that
	// legitimately need a long budget; 100ms-1s suits most latency
	// requirements.
	//
	// With Breaker enabled, OperationTimeout must be the binding deadline for
	// a hung server's timeouts to be attributed to that server and open its
	// breaker; callers whose own deadline is at or below it own the timeout
	// instead. See BreakerConfig.
	// The default is DefaultOperationTimeout (1s).
	OperationTimeout time.Duration

	// DialTimeout bounds establishing a new connection, including the TCP
	// handshake and the TLS handshake if applicable. Set it higher than
	// OperationTimeout when TLS connections take longer to establish.
	// The default is the resolved OperationTimeout, so the dial is always
	// bounded.
	DialTimeout time.Duration

	// Dialer is used to create new connections. If nil, a default
	// net.Dialer is used.
	//
	// To connect over TLS (memcached running with --enable-ssl), set a
	// *tls.Dialer, which satisfies this interface:
	//
	//	Dialer: &tls.Dialer{Config: &tls.Config{RootCAs: pool}}
	//
	// A single *tls.Dialer serves a whole multi-server set: crypto/tls
	// derives ServerName from each dial address when Config.ServerName is
	// empty, so every server is verified against its own hostname. To tune
	// the underlying TCP connection (timeouts, keep-alive) as well, set
	// tls.Dialer.NetDialer. For per-server TLS settings, supply a Dialer that
	// selects its config based on the address.
	Dialer Dialer

	// ServerSelector picks which server to use for a key.
	// It receives the key and current server set and returns the selected server.
	// The default implementation uses Rendezvous Hash for membership-stable selection.
	ServerSelector ServerSelector

	// Breaker configures the circuit breaker guarding each server: when a
	// server's recent failure ratio trips it, operations to that server fail
	// fast with ErrBreakerOpen instead of tying up connections. Disabled
	// unless Breaker.Enabled is true. See BreakerConfig for the policy knobs
	// and their defaults.
	Breaker BreakerConfig

	// Observer is notified around each operation for tracing and metrics.
	// If nil, no observation is performed. See the otelmemcache subpackage for
	// a ready-made OpenTelemetry adapter.
	Observer Observer
}

type ConnPoolMetrics struct {
	// Lifetime counters
	AcquireCount        int64         // Total acquire attempts
	AcquireWaitCount    int64         // Acquires that had to wait
	AcquireWaitDuration time.Duration // Total time spent waiting to acquire
	CreatedConns        int64         // Total connections created
	DestroyedConns      int64         // Total connections destroyed
	AcquireErrors       int64         // Failed acquire attempts

	// Current state gauges
	TotalConns  int // Total connections in pool (active + idle)
	IdleConns   int // Idle connections available
	ActiveConns int // Connections currently in use
}

type Connection struct {
	Reader *bufio.Reader
	Writer *bufio.Writer
	// contains filtered or unexported fields
}

type ConnectionError = meta.ConnectionError

type Counter struct {
	Key   string
	Value uint64
	CAS   CAS

	// Status is StatusApplied when the counter was read (or created), or the
	// condition that stopped it: StatusNotFound (miss without Create) or
	// StatusCASMismatch. Value is only set on StatusApplied — a CAS mismatch
	// leaves the key in place but returns nothing about it.
	Status Status
}

type CounterOptions struct {
	TTL     TTL
	CAS     CAS
	Create  bool   // create the key when it is absent, seeded with Initial
	Initial uint64 // value of the created key; ignored unless Create
}

type DeleteOptions struct {
	CAS CAS // require the item's CAS to match; zero: delete unconditionally
}

type Dialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

type Executor interface {
	Execute(ctx context.Context, req *meta.Request, fn ResponseFunc) error
	ExecuteBatch(ctx context.Context, reqs []*meta.Request) ([]*meta.Response, error)
}

type GenericError = meta.GenericError

type GetOptions struct {
	TTL TTL // non-zero: touch-on-read, updating the item's expiration (get-and-touch)
}

type InvalidRequestError = meta.InvalidRequestError

type Item struct {
	Key   string
	Value []byte
	Flags uint32 // client flags stored alongside the value
	CAS   CAS    // compare-and-swap token

	// Status is StatusApplied when the key was found and StatusNotFound when
	// it was not; Value, Flags and CAS are only set on a hit. Test it with
	// Status.OK(), as on every other result type.
	Status Status
}

type Observer interface {
	StartOp(ctx context.Context, info OpInfo) (context.Context, ActiveOp)
}

type OpError struct {
	// Op is the operation that failed, as one of the Op* constants
	// ("get", "set", "batch", ...).
	Op string

	// Key is the cache key, when the operation targets a single key.
	//
	// The key is deliberately NOT part of the Error() message: keys often
	// carry user identifiers (PII) that don't belong in logs, and embedding
	// them would give error messages unbounded cardinality. Read this field
	// explicitly (via errors.AsType) when the key is wanted.
	Key string

	// Address is the host:port of the server the operation was routed to.
	Address string

	// Err is the underlying cause: a connection or timeout error,
	// ErrBreakerOpen, a meta protocol error, etc.
	Err error
}

type OpInfo struct {
	// Op is the operation, one of the Op* constants ("get", "set", "touch",
	// ...) and the same vocabulary as OpError.Op. It names what the caller
	// asked for, not the wire command carrying it, so a Touch is not reported
	// as a get and an Add is not reported as a set.
	Op       string
	Address  string // resolved server address ("" if not yet known)
	Key      string // single-op key ("" for batch/stats)
	Requests int    // number of pipelined requests for a batch; 0 otherwise
}

type OpResult struct {
	// Status is the operation's outcome, the same value the caller receives:
	// StatusApplied, StatusNotFound, StatusExists or StatusCASMismatch. It is
	// the zero Status when there is no single outcome to report: the operation
	// failed, or it is a batch, a stats or a flush_all.
	Status Status

	// Code is the raw status the server replied ("HD", "EN", "NS", ...), empty
	// when no response was decoded. Status is what that code meant for this
	// operation — the same NS is StatusExists after an add and StatusNotFound
	// after a replace — so prefer Status and read Code only to report the wire
	// verbatim.
	Code string

	Err error
}

type ParseError = meta.ParseError

type PoolMetrics struct {
	Address string
	Conns   ConnPoolMetrics
	Breaker BreakerMetrics
}

type Querier interface {
	Get(ctx context.Context, key string, opts ...GetOptions) (Item, error)
	Set(ctx context.Context, key string, value []byte, opts ...StoreOptions) (StoreResult, error)
	Add(ctx context.Context, key string, value []byte, opts ...StoreOptions) (StoreResult, error)
	Replace(ctx context.Context, key string, value []byte, opts ...StoreOptions) (StoreResult, error)
	Append(ctx context.Context, key string, value []byte, opts ...ConcatOptions) (StoreResult, error)
	Prepend(ctx context.Context, key string, value []byte, opts ...ConcatOptions) (StoreResult, error)
	Touch(ctx context.Context, key string, ttl TTL) (Status, error)
	Delete(ctx context.Context, key string, opts ...DeleteOptions) (Status, error)
	Increment(ctx context.Context, key string, delta uint64, opts ...CounterOptions) (Counter, error)
	Decrement(ctx context.Context, key string, delta uint64, opts ...CounterOptions) (Counter, error)
	MultiGet(ctx context.Context, keys []string, opts ...GetOptions) ([]Item, error)
	MultiSet(ctx context.Context, items []SetItem) ([]StoreResult, error)
	MultiDelete(ctx context.Context, keys []string) ([]Status, error)
}

type ResponseFunc func(*meta.Response)

type Server struct {
	Address string
}

type ServerError = meta.ServerError

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

type ServerSelector func(key string, servers []Server) Server

type ServerStats struct {
	Address string            // Server address
	Stats   map[string]string // Server statistics (name -> value)
	Error   error             // Error if stats request failed
}

type Servers interface {
	// List returns the current set of servers, read-only. The client calls it
	// on every operation and hands the slice straight to the ServerSelector,
	// so neither may modify it: an implementation is free to return its own
	// backing array, shared with every concurrent caller, and StaticServers
	// does exactly that.
	List() []Server
}

type SetItem struct {
	Key     string
	Value   []byte
	Options StoreOptions
}

type StatsExecutor interface {
	ExecuteStats(ctx context.Context, args ...string) (map[string]string, error)
}

type Status int

type StoreOptions struct {
	TTL   TTL
	Flags uint32 // client flags stored with the item; zero: none
	CAS   CAS    // require the item's CAS to match; zero: store unconditionally
}

type StoreResult struct {
	// Status is StatusApplied when the value was stored, or the condition
	// that stopped it: StatusExists (add on an existing key), StatusNotFound
	// (replace, append or prepend on a missing key) or StatusCASMismatch.
	Status Status

	CAS CAS
}

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