idempotency

type Begun struct {
	// State is what Begin found.
	State State
	// Fingerprint is the fingerprint recorded by whoever began the key. Set
	// for Replay and InFlight, so a reused key can be compared.
	Fingerprint string
	// Response is set for Replay. It is a copy the caller may keep.
	Response *Response
	// Token is set for Acquired. Pass it to Complete or Release.
	Token Token
	// Done is closed when the holder completes or releases the key, or when
	// the store sweeps the holder's lapsed claim. Set for InFlight by stores
	// that can signal; nil means poll Begin again. A store is not required to
	// close Done at the instant a lease expires, only at its next sweep, so a
	// waiter must bound its wait by the lease and Begin again when that runs
	// out.
	Done <-chan struct{}
}

type ConflictMode int

type Key struct {
	// Principal is who made the request. Two principals never share a stored
	// response, even when they send the same key value.
	Principal string
	// Scope is where the key applies. The HTTP middleware uses "METHOD /path";
	// the dashboard contract uses its own constant.
	Scope string
	// Value is the client-supplied Idempotency-Key.
	Value string
}

type MemoryOption func(*MemoryStore)

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

type Option func(*config)

type PrincipalFunc func(ctx router.Context) string

type Response struct {
	// Status is the HTTP status the handler wrote.
	Status int
	// Header holds the headers the handler set, not the ones outer middleware
	// set before it ran.
	Header http.Header
	// Body is the response body.
	Body []byte
	// Fingerprint identifies the request that produced this response, so a
	// reused key with a different request can be refused.
	Fingerprint string
	// StoredAt is when the response was stored.
	StoredAt time.Time
	// ExpiresAt is when the store may forget the response. Zero never expires.
	ExpiresAt time.Time
}

type State int

type Store interface {
	// Begin claims key for a new request, or reports why it cannot. lease
	// bounds how long a claim survives a holder that never finishes; a lease of
	// zero or less means DefaultLease. An Acquired result carries the Token the
	// holder must present when it finishes.
	Begin(ctx context.Context, key Key, fingerprint string, lease time.Duration) (Begun, error)
	// Complete stores resp for key and ends the claim held under token. When
	// resp has no Fingerprint it takes the one the claim was begun with. A
	// token that does not match the current claim returns ErrNotHolder and
	// stores nothing. The zero token completes a key that nobody has claimed,
	// storing resp without a prior Begin; it cannot finish a live claim.
	Complete(ctx context.Context, key Key, token Token, resp Response) error
	// Release ends the claim held under token without storing anything, so the
	// key can be used again. A token that does not match the current claim
	// returns ErrNotHolder and changes nothing. Releasing a key that is gone is
	// a no-op.
	Release(ctx context.Context, key Key, token Token) error
}

type Token uint64