Documentation
¶
Overview ¶
Package replay owns storage-neutral replay detection contracts and invariants.
Replay detection is explicit local policy. This package does not modify DKIM2 verification results or turn local replay disposition into protocol conformance.
Index ¶
- Constants
- func FirstSeenValue(nonce Nonce) (string, error)
- func IsTypedError(err error) bool
- func NewError(code ErrorCode) error
- func PreflightContext(ctx context.Context) (result error)
- func PropagationPendingValue(leaseExpiry time.Time, nonce Nonce) (string, error)
- func UseStorageKey(key Key, use func(string) error) (resultErr error)
- func ValidateCheckOutcome(check Check, err error) error
- type Check
- type Clock
- type ClockFunc
- type Deriver
- func (d *Deriver) Close(ctx context.Context) (resultErr error)
- func (d *Deriver) Derive(ctx context.Context, identity Identity) (Key, error)
- func (d *Deriver) DerivePropagation(ctx context.Context, identity Identity) (Key, error)
- func (Deriver) Format(state fmt.State, _ rune)
- func (Deriver) GoString() string
- func (Deriver) String() string
- type DisabledStore
- func (s *DisabledStore) CheckAndRemember(ctx context.Context, _ Key, _ Retention) (Check, error)
- func (s *DisabledStore) Close(ctx context.Context) (resultErr error)
- func (s *DisabledStore) CommitPropagation(ctx context.Context, _ Key) (PropagationCommit, error)
- func (DisabledStore) Format(state fmt.State, _ rune)
- func (DisabledStore) GoString() string
- func (DisabledStore) MarshalJSON() ([]byte, error)
- func (DisabledStore) MarshalText() ([]byte, error)
- func (s *DisabledStore) ReservePropagation(ctx context.Context, _ Key, _ Retention, _ Lease) (PropagationReservation, error)
- func (s *DisabledStore) State() StoreState
- func (DisabledStore) String() string
- type Error
- type ErrorCode
- type Identity
- type IdentitySetdeprecated
- func (s IdentitySet) Eligible() bool
- func (s IdentitySet) Exploded() bool
- func (IdentitySet) Format(state fmt.State, _ rune)
- func (IdentitySet) GoString() string
- func (s IdentitySet) Identity(index int) (Identity, error)
- func (s IdentitySet) Len() int
- func (IdentitySet) String() string
- func (s IdentitySet) Valid() bool
- type IdentitySource
- type Key
- type Lease
- type Limits
- type ManagedStore
- type MemoryConfig
- type MemoryStore
- func (s *MemoryStore) CheckAndRemember(ctx context.Context, key Key, retention Retention) (check Check, resultErr error)
- func (s *MemoryStore) Close(ctx context.Context) (resultErr error)
- func (s *MemoryStore) CommitPropagation(ctx context.Context, key Key) (commit PropagationCommit, resultErr error)
- func (MemoryStore) Format(state fmt.State, _ rune)
- func (MemoryStore) GoString() string
- func (MemoryStore) MarshalJSON() ([]byte, error)
- func (MemoryStore) MarshalText() ([]byte, error)
- func (s *MemoryStore) ReservePropagation(ctx context.Context, key Key, retention Retention, lease Lease) (reservation PropagationReservation, resultErr error)
- func (s *MemoryStore) State() StoreState
- func (MemoryStore) String() string
- type Nonce
- type PropagationCommit
- type PropagationReservation
- type PropagationState
- type PropagationStore
- type Retention
- type Store
- type StoreState
Constants ¶
const ( // KeyAlgorithm identifies the frozen HMAC replay-key algorithm. KeyAlgorithm = "dkim2-replay-hmac-sha256-v2" // StoredValue is the legacy nonce-free first-seen marker written by // earlier providers; ParseFirstSeenValue still accepts it as a foreign // record. New writes use FirstSeenValue. StoredValue = "v1" )
const ( // PropagationKeyDomainLabel is the distinct HMAC domain-separation frame // label for delivery-status propagation coordinates. PropagationKeyDomainLabel = "dkim2-replay-propagation-v1" // PropagationCommittedValue is the exact stored value of a committed coordinate. PropagationCommittedValue = "committed" // PropagationPendingPrefix starts the stored value of a pending coordinate; // the suffix is the lease expiry in Unix milliseconds. PropagationPendingPrefix = "pending:" )
const ( // FirstSeenValuePrefix starts the nonce-bearing stored value of a first-seen record. FirstSeenValuePrefix = "v2:" // NonceHexLength is the exact lowercase hexadecimal length of one stored nonce. NonceHexLength = 2 * nonceByteLength )
const (
// DraftIdentifier is the exact behavior baseline bound into replay identities.
DraftIdentifier = "draft-ietf-dkim-dkim2-spec-09"
)
Variables ¶
This section is empty.
Functions ¶
func FirstSeenValue ¶
FirstSeenValue renders the nonce-bearing first-seen value "v2:<nonce>". An invalid nonce is rejected so no provider can write an unidentifiable record.
func IsTypedError ¶
IsTypedError reports whether err is one direct member of the closed taxonomy.
func PreflightContext ¶
PreflightContext maps a context state before any mutation boundary.
func PropagationPendingValue ¶
PropagationPendingValue renders the nonce-bearing pending value "pending:<unixms>:<16 lowercase hex nonce>". The expiry must be a positive Unix millisecond instant within the closed digit bound and the nonce must be valid, so every rendered value parses back through ParsePropagationValue.
func UseStorageKey ¶
UseStorageKey authorizes one synchronous pre-dispatch callback for a protected key.
func ValidateCheckOutcome ¶
ValidateCheckOutcome verifies one result/error pair without traversing raw errors.
Types ¶
type Check ¶
type Check uint8
Check identifies one successful replay-store outcome.
const ( // CheckFirstSeen means the identity was atomically retained for the first time. CheckFirstSeen Check = iota + 1 // CheckReplayed means the identity already existed without retention extension. CheckReplayed // CheckDisabled means explicit local policy selected no replay storage. CheckDisabled )
func (Check) MarshalJSON ¶
MarshalJSON emits only a known replay-check value.
func (Check) MarshalText ¶
MarshalText emits only a known replay-check value.
type Deriver ¶
type Deriver struct {
// contains filtered or unexported fields
}
Deriver owns one cloned deployment-local HMAC secret and its lifecycle.
func NewDeriver ¶
NewDeriver validates and clones one exact replay-key secret and epoch.
func (*Deriver) Close ¶
Close rejects new derives, drains admitted work, and clears the owned secret.
func (*Deriver) DerivePropagation ¶
DerivePropagation produces the delivery-status propagation storage key of one sealed identity. It shares the secret, epoch, and storage-key shape with Derive but uses the distinct propagation domain-separation frame, so a propagation coordinate never collides with the ordinary first-seen record of the same message.
type DisabledStore ¶
type DisabledStore struct {
// contains filtered or unexported fields
}
DisabledStore is an explicit no-storage replay provider.
func NewDisabledStore ¶
func NewDisabledStore() *DisabledStore
NewDisabledStore constructs one explicit disabled replay provider.
func (*DisabledStore) CheckAndRemember ¶
CheckAndRemember returns disabled without inspecting key or retention.
func (*DisabledStore) Close ¶
func (s *DisabledStore) Close(ctx context.Context) (resultErr error)
Close atomically closes the disabled provider and is idempotent.
func (*DisabledStore) CommitPropagation ¶
func (s *DisabledStore) CommitPropagation(ctx context.Context, _ Key) (PropagationCommit, error)
CommitPropagation returns disabled without inspecting the key.
func (DisabledStore) Format ¶
func (DisabledStore) Format(state fmt.State, _ rune)
Format prevents every formatting verb from exposing provider state.
func (DisabledStore) GoString ¶
func (DisabledStore) GoString() string
GoString returns a constant representation without lifecycle detail.
func (DisabledStore) MarshalJSON ¶
func (DisabledStore) MarshalJSON() ([]byte, error)
MarshalJSON rejects serialization of disabled-provider state.
func (DisabledStore) MarshalText ¶
func (DisabledStore) MarshalText() ([]byte, error)
MarshalText rejects serialization of disabled-provider state.
func (*DisabledStore) ReservePropagation ¶
func (s *DisabledStore) ReservePropagation(ctx context.Context, _ Key, _ Retention, _ Lease) (PropagationReservation, error)
ReservePropagation returns disabled without inspecting key, retention, or lease.
func (*DisabledStore) State ¶
func (s *DisabledStore) State() StoreState
State returns one bounded lock-free lifecycle snapshot.
func (DisabledStore) String ¶
func (DisabledStore) String() string
String returns a constant representation without lifecycle detail.
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is one typed content-free replay failure.
func (*Error) MarshalJSON ¶
MarshalJSON emits only the stable replay failure class.
func (*Error) MarshalText ¶
MarshalText emits only the stable replay failure class.
type ErrorCode ¶
type ErrorCode string
ErrorCode identifies one stable replay failure class.
const ( // ErrorCodeInvalidRequest classifies invalid input or a missing required value. ErrorCodeInvalidRequest ErrorCode = "invalid_request" // ErrorCodeMisconfigured classifies incomplete or unsafe construction. ErrorCodeMisconfigured ErrorCode = "misconfigured" // ErrorCodeLimitExceeded classifies a hard bounded-resource refusal. ErrorCodeLimitExceeded ErrorCode = "limit_exceeded" ErrorCodeUnavailable ErrorCode = "unavailable" // ErrorCodeIndeterminate classifies a write that may have crossed mutation dispatch. ErrorCodeIndeterminate ErrorCode = "indeterminate" // ErrorCodeInconsistent classifies an authoritative contradictory backend outcome. ErrorCodeInconsistent ErrorCode = "inconsistent" // ErrorCodeCancelled classifies pre-dispatch caller cancellation. ErrorCodeCancelled ErrorCode = "cancelled" // ErrorCodeDeadlineExceeded classifies a pre-dispatch elapsed caller deadline. ErrorCodeDeadlineExceeded ErrorCode = "deadline_exceeded" // ErrorCodeClosed classifies work rejected after close begins. ErrorCodeClosed ErrorCode = "closed" // ErrorCodeInternalInvariant classifies impossible in-process state. ErrorCodeInternalInvariant ErrorCode = "internal_invariant" )
func ErrorCodeOf ¶
ErrorCodeOf returns the stable code for one direct replay failure.
func (ErrorCode) MarshalJSON ¶
MarshalJSON emits only a known replay error code.
func (ErrorCode) MarshalText ¶
MarshalText emits only a known replay error code.
type Identity ¶
type Identity struct {
// contains filtered or unexported fields
}
Identity is one immutable message-wide authenticated replay identity.
func (Identity) Format ¶
Format prevents every formatting verb from exposing authenticated digest bytes.
func (Identity) GoString ¶
GoString returns a constant representation without authenticated digest bytes.
type IdentitySet
deprecated
type IdentitySet struct {
// contains filtered or unexported fields
}
IdentitySet is an immutable compatibility wrapper around the single message identity.
Deprecated: Draft-09 replay equality is message-wide. New code should use Identity.
func NewIdentitySet ¶
func NewIdentitySet(source IdentitySource) (set IdentitySet, resultErr error)
NewIdentitySet constructs one identity from a sealed trusted-boundary source.
func (IdentitySet) Eligible ¶
func (s IdentitySet) Eligible() bool
Eligible reports whether local replay policy counts this message. Messages authenticated only by the originator's i=1 signature are direct deliveries, not intermediary re-sends (Draft-09 Section 15.1), and are not counted. The identity remains valid for DSN propagation coordinates.
func (IdentitySet) Exploded ¶
func (s IdentitySet) Exploded() bool
Exploded returns the authenticated complete-chain OR fact for a valid set.
func (IdentitySet) Format ¶
func (IdentitySet) Format(state fmt.State, _ rune)
Format prevents every formatting verb from exposing authenticated digest bytes.
func (IdentitySet) GoString ¶
func (IdentitySet) GoString() string
GoString returns a constant representation without authenticated digest bytes.
func (IdentitySet) Identity ¶
func (s IdentitySet) Identity(index int) (Identity, error)
Identity returns the immutable message-wide identity at index zero.
func (IdentitySet) Len ¶
func (s IdentitySet) Len() int
Len returns one for a valid Draft-09 message identity.
func (IdentitySet) String ¶
func (IdentitySet) String() string
String returns a constant representation without authenticated digest bytes.
func (IdentitySet) Valid ¶
func (s IdentitySet) Valid() bool
Valid reports whether the set contains the single message-wide identity.
type IdentitySource ¶
IdentitySource exposes only sealed fixed replay facts at the trusted root bridge.
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key is an opaque replay-storage capability.
Identity construction and key derivation own the nonzero representation. The zero value is intentionally invalid for enabled stores.
func (Key) MarshalJSON ¶
MarshalJSON rejects serialization of a protected replay key.
func (Key) MarshalText ¶
MarshalText rejects serialization of a protected replay key.
type Lease ¶
type Lease struct {
// contains filtered or unexported fields
}
Lease is an immutable validated whole-millisecond pending lease.
type Limits ¶
type Limits struct {
MaxEntries int
MaxWaiters int
PruneBudget int
MaxInFlight int
MaxAdmissionWaiters int
}
Limits contains reusable hard-bounded replay provider resources.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns the frozen restrictive provider defaults.
func ResolveLimits ¶
ResolveLimits applies per-field defaults and validates every hard bound.
type ManagedStore ¶
type ManagedStore interface {
Store
State() StoreState
Close(context.Context) error
}
ManagedStore adds bounded lifecycle control to a replay store.
type MemoryConfig ¶
MemoryConfig contains the bounded resources and required injected clock.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is a deterministic bounded heap-expiring replay provider.
func NewMemoryStore ¶
func NewMemoryStore(config MemoryConfig) (*MemoryStore, error)
NewMemoryStore validates and constructs one bounded memory replay provider.
func (*MemoryStore) CheckAndRemember ¶
func (s *MemoryStore) CheckAndRemember( ctx context.Context, key Key, retention Retention, ) (check Check, resultErr error)
CheckAndRemember atomically classifies and retains one protected replay key.
func (*MemoryStore) Close ¶
func (s *MemoryStore) Close(ctx context.Context) (resultErr error)
Close publishes closing, drains admitted work, and clears retained state once.
func (*MemoryStore) CommitPropagation ¶
func (s *MemoryStore) CommitPropagation(ctx context.Context, key Key) (commit PropagationCommit, resultErr error)
CommitPropagation moves one pending propagation coordinate to committed by compare-and-set. A committed coordinate stays committed; an absent or expired coordinate is unknown.
func (MemoryStore) Format ¶
func (MemoryStore) Format(state fmt.State, _ rune)
Format prevents every formatting verb from exposing retained replay data.
func (MemoryStore) GoString ¶
func (MemoryStore) GoString() string
GoString returns a constant representation without keys or provider state.
func (MemoryStore) MarshalJSON ¶
func (MemoryStore) MarshalJSON() ([]byte, error)
MarshalJSON rejects serialization of memory-provider state.
func (MemoryStore) MarshalText ¶
func (MemoryStore) MarshalText() ([]byte, error)
MarshalText rejects serialization of memory-provider state.
func (*MemoryStore) ReservePropagation ¶
func (s *MemoryStore) ReservePropagation( ctx context.Context, key Key, retention Retention, lease Lease, ) (reservation PropagationReservation, resultErr error)
ReservePropagation atomically inserts or refreshes one pending propagation coordinate. A live lease is reported as pending, a committed coordinate as committed, and an absent coordinate or an expired lease becomes pending with a fresh lease and a fresh retention.
func (*MemoryStore) State ¶
func (s *MemoryStore) State() StoreState
State returns one bounded lock-free lifecycle snapshot.
func (MemoryStore) String ¶
func (MemoryStore) String() string
String returns a constant representation without keys or provider state.
type Nonce ¶
type Nonce struct {
// contains filtered or unexported fields
}
Nonce is one random 64-bit write identity that a networked provider embeds in the value of one logical write. Because the value is fixed for every client-level attempt of that write, a retried attempt that observes its own value proves its own earlier commit instead of reporting a foreign record. The zero value is invalid and never rendered.
func NewNonce ¶
NewNonce reads exactly one nonce from random, or from crypto/rand when random is nil. A short read, a read error, or an all-zero nonce fails closed as an internal invariant without exposing source detail.
func ParseFirstSeenValue ¶
ParseFirstSeenValue decodes one stored first-seen value. It accepts the nonce-bearing form "v2:<16 lowercase hex>" and the legacy nonce-free StoredValue "v1" written by earlier providers; legacy reports true for the latter and a zero nonce. Every other string reports ok false.
func (Nonce) MarshalJSON ¶
MarshalJSON rejects serialization of nonce bytes.
func (Nonce) MarshalText ¶
MarshalText rejects serialization of nonce bytes.
type PropagationCommit ¶
type PropagationCommit uint8
PropagationCommit identifies one successful commit outcome.
const ( // PropagationCommitted means the coordinate is committed, whether by this call or before. PropagationCommitted PropagationCommit = iota + 1 // PropagationCommitUnresolved means the token resolves to no pending or // committed coordinate within retention; it formats as "unresolved" and is // the outcome the daemon answers with 409. The plain "unknown" marker is // reserved for values outside the closed vocabulary. PropagationCommitUnresolved // PropagationCommitDisabled means explicit local policy selected no replay storage. PropagationCommitDisabled )
func (PropagationCommit) Format ¶
func (c PropagationCommit) Format(state fmt.State, _ rune)
Format prevents unknown numeric values from reaching formatting output.
func (PropagationCommit) GoString ¶
func (c PropagationCommit) GoString() string
GoString returns the stable commit representation.
func (PropagationCommit) Known ¶
func (c PropagationCommit) Known() bool
Known reports whether the commit belongs to the closed vocabulary.
func (PropagationCommit) String ¶
func (c PropagationCommit) String() string
String returns the stable commit value or a constant unknown marker.
type PropagationReservation ¶
type PropagationReservation uint8
PropagationReservation identifies one successful reservation outcome.
const ( // PropagationReserved means the coordinate was absent or its lease had expired and is now pending. PropagationReserved PropagationReservation = iota + 1 // PropagationPending means another attempt holds a live lease. PropagationPending // PropagationAlreadyCommitted means the coordinate was committed within retention. PropagationAlreadyCommitted // PropagationReservationDisabled means explicit local policy selected no replay storage. PropagationReservationDisabled )
func (PropagationReservation) Format ¶
func (r PropagationReservation) Format(state fmt.State, _ rune)
Format prevents unknown numeric values from reaching formatting output.
func (PropagationReservation) GoString ¶
func (r PropagationReservation) GoString() string
GoString returns the stable reservation representation.
func (PropagationReservation) Known ¶
func (r PropagationReservation) Known() bool
Known reports whether the reservation belongs to the closed vocabulary.
func (PropagationReservation) String ¶
func (r PropagationReservation) String() string
String returns the stable reservation value or a constant unknown marker.
type PropagationState ¶
type PropagationState string
PropagationState is the closed stored state of one propagation coordinate.
const ( // PropagationStatePending reports a reserved coordinate whose attempt has not committed. PropagationStatePending PropagationState = "pending" // PropagationStateCommitted reports a coordinate whose propagated report was accepted. PropagationStateCommitted PropagationState = "committed" )
func ParsePropagationValue ¶
func ParsePropagationValue(value string) (PropagationState, time.Time, bool)
ParsePropagationValue decodes one stored propagation value. It accepts "committed", the nonce-bearing pending form "pending:<unixms>:<16 lowercase hex nonce>", and the legacy pending form "pending:<unixms>" written by earlier providers. It reports the closed state, the lease expiry for pending values, and false for every string outside the closed grammar.
func (PropagationState) Known ¶
func (s PropagationState) Known() bool
Known reports whether the state belongs to the closed vocabulary.
type PropagationStore ¶
type PropagationStore interface {
ReservePropagation(context.Context, Key, Retention, Lease) (PropagationReservation, error)
CommitPropagation(context.Context, Key) (PropagationCommit, error)
}
PropagationStore reserves and commits delivery-status propagation coordinates in two phases. ReservePropagation inserts a pending record with a lease if the coordinate is absent or its pending lease has expired, reports a live lease as pending, and reports a committed record as committed. CommitPropagation moves a pending record to committed by compare-and-set, is idempotent for committed records, and reports an absent or expired record as unknown. Ordinary first-seen records are never touched.
type Retention ¶
type Retention struct {
// contains filtered or unexported fields
}
Retention is an immutable validated whole-millisecond retention period.
func DefaultRetention ¶
func DefaultRetention() Retention
DefaultRetention returns the frozen fourteen-day default.
func NewRetention ¶
NewRetention validates and constructs one replay retention period.
func (Retention) Duration ¶
Duration returns the exact validated duration or zero for an invalid value.
func (Retention) Milliseconds ¶
Milliseconds returns the signed Redis-protocol PX value or zero for an invalid value.
type StoreState ¶
type StoreState uint8
StoreState identifies one bounded replay-store lifecycle state.
const ( // StoreReady permits enabled storage operations. StoreReady StoreState = iota + 1 // StoreDegraded reports a fail-closed enabled provider impairment. StoreDegraded // StoreDisabled reports an explicitly selected disabled provider. StoreDisabled // StoreClosing rejects new operations while admitted work drains. StoreClosing // StoreClosed rejects all later operations. StoreClosed )
func (StoreState) Format ¶
func (s StoreState) Format(state fmt.State, _ rune)
Format prevents unknown numeric values from reaching formatting output.
func (StoreState) GoString ¶
func (s StoreState) GoString() string
GoString returns the stable store-state representation.
func (StoreState) Known ¶
func (s StoreState) Known() bool
Known reports whether the state belongs to the closed lifecycle vocabulary.
func (StoreState) MarshalJSON ¶
func (s StoreState) MarshalJSON() ([]byte, error)
MarshalJSON emits only a known replay-store state.
func (StoreState) MarshalText ¶
func (s StoreState) MarshalText() ([]byte, error)
MarshalText emits only a known replay-store state.
func (StoreState) String ¶
func (s StoreState) String() string
String returns the stable state value or a constant unknown marker.