idempotency

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

type Record struct {
	// Key is the idempotency key (already validated).
	Key string

	// Fingerprint is the request fingerprint.
	Fingerprint RequestFingerprint

	// State is the current lifecycle state.
	State RecordState

	// ResponseStatus is the HTTP status of the completed response.
	// Valid only when State == StateCompleted.
	ResponseStatus int

	// ResponseHeaders are the non-sensitive response headers to replay.
	// Sensitive headers (Set-Cookie, Authorization) should be filtered
	// by the application before storage.
	ResponseHeaders http.Header

	// ResponseBody is the response body to replay.
	// Valid only when State == StateCompleted.
	ResponseBody []byte

	// CreatedAt is when the record was created.
	CreatedAt time.Time

	// ExpiresAt is when the record should be evicted.
	ExpiresAt time.Time
}

type RecordState int

type RequestFingerprint struct {
	// Method is the HTTP method (uppercase).
	Method string

	// Path is the request path (including query string).
	Path string

	// BodyHash is the SHA-256 hash of the request body (hex-encoded).
	BodyHash string
}

type Store interface {
	// Reserve attempts to create an in-progress record for the given
	// key and fingerprint. If a record already exists:
	//   - If it is in-progress, return the existing record and
	//     ErrConflict.
	//   - If it is completed, return the existing record and
	//     ErrReplayAvailable.
	//   - If it is expired, the implementation should evict it and
	//     allow the reservation.
	//   - If the fingerprint does not match, return
	//     ErrFingerprintMismatch.
	Reserve(key string, fingerprint RequestFingerprint, ttl time.Duration) (existing *Record, err error)

	// Complete marks an in-progress record as completed with the
	// given response. The response headers and body are stored for
	// replay. Sensitive headers must be filtered by the caller before
	// storage.
	Complete(key string, status int, headers http.Header, body []byte) error

	// Fail marks an in-progress record as failed. The record may be
	// retried by the client with the same key.
	Fail(key string) error

	// Get retrieves the record for the given key. Returns nil, nil if
	// the key does not exist.
	Get(key string) (*Record, error)
}