Documentation
¶
Overview ¶
Package replica defines the transport-independent boundary around one framed CRDT replication group.
It deliberately does not open connections, authenticate peers, retain an operation log, or compact CRDT tombstones. Its job is narrower: make the agreement required before a transport exchanges frames explicit, keep a contiguous per-actor delivery frontier, and prevent an acknowledgement from being emitted before a checkpoint has been durably installed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidManifest = errors.New("replica: invalid manifest") ErrManifestMismatch = errors.New("replica: manifest mismatch") ErrProtocolMismatch = errors.New("replica: protocol mismatch") ErrInvalidDot = errors.New("replica: invalid dot") ErrFrontierGap = errors.New("replica: non-contiguous frontier advance") ErrInvalidCheckpoint = errors.New("replica: invalid checkpoint") ErrNilValidator = errors.New("replica: nil state validator") ErrNilStore = errors.New("replica: nil checkpoint store") ErrNotInstalled = errors.New("replica: checkpoint is not installed") ErrCheckpointChanged = errors.New("replica: a different checkpoint is already installed") ErrInvalidChange = errors.New("replica: invalid change") ErrDotConflict = errors.New("replica: conflicting payload for one dot") ErrPendingLimit = errors.New("replica: pending change limit exceeded") ErrNilApply = errors.New("replica: nil delta apply function") )
Functions ¶
This section is empty.
Types ¶
type Acknowledgement ¶
type Acknowledgement struct {
GroupID string
Epoch uint64
CheckpointID [sha256.Size]byte
Frontier Frontier
}
Acknowledgement proves that one installed checkpoint was durably recorded. It is intentionally not a tombstone-GC acknowledgement: eligibility to compact a tombstone remains type-specific, especially for RGA and trees.
type ApplyDelta ¶
ApplyDelta applies one already validated canonical delta frame. It must leave the concrete CRDT unchanged on an error. Inbox advances its frontier only after this function succeeds.
type Change ¶
type Change struct {
Dot Dot
// contains filtered or unexported fields
}
Change binds exactly one canonical delta frame to a persistently assigned dot. The dot is a delivery/accounting identity, not a replacement for the CRDT's own mutation tags inside the delta payload.
func NewChange ¶
NewChange validates that delta belongs to manifest's exact delta protocol and returns a copy. It does not decode the CRDT-specific payload; that work remains the concrete ApplyDelta implementation's responsibility. It accepts only stable protocols; use NewChangeWithPolicy for an explicit experimental protocol opt-in.
func NewChangeWithPolicy ¶ added in v1.0.6
func NewChangeWithPolicy(manifest Manifest, dot Dot, delta []byte, policy crdt.ProtocolPolicy) (Change, error)
NewChangeWithPolicy validates one change under policy. Experimental protocols require an explicit AllowExperimental policy at this use boundary.
type Checkpoint ¶
type Checkpoint struct {
// contains filtered or unexported fields
}
Checkpoint is a validated, immutable recovery boundary for one replication group. HLC-backed CRDTs include their local clock state so the local replica cannot reuse an earlier tag after restoring the checkpoint.
func NewCheckpoint ¶
func NewCheckpoint(manifest Manifest, state []byte, frontier Frontier, clockState clock.State, validator StateValidator) (Checkpoint, error)
NewCheckpoint validates the manifest/frame agreement and invokes validator before a checkpoint may be persisted. For HLC-backed protocols, clockState must be valid; for non-HLC protocols it must be the zero value. It accepts only stable protocols; use NewCheckpointWithPolicy for an explicit experimental protocol opt-in.
func NewCheckpointWithPolicy ¶ added in v1.0.6
func NewCheckpointWithPolicy(manifest Manifest, state []byte, frontier Frontier, clockState clock.State, validator StateValidator, policy crdt.ProtocolPolicy) (Checkpoint, error)
NewCheckpointWithPolicy validates a checkpoint under policy. Experimental protocols require an explicit AllowExperimental policy at this use boundary.
func (Checkpoint) ClockState ¶
func (c Checkpoint) ClockState() (clock.State, bool)
ClockState reports the HLC state included in c.
func (Checkpoint) Frontier ¶
func (c Checkpoint) Frontier() Frontier
Frontier returns a copy of the durable delivery frontier.
func (Checkpoint) ID ¶
func (c Checkpoint) ID() [sha256.Size]byte
ID is a stable digest over all checkpoint meaning, including epoch, protocol semantics, state bytes, frontier, and HLC state.
func (Checkpoint) Manifest ¶
func (c Checkpoint) Manifest() Manifest
Manifest returns the checkpoint's manifest by value.
func (Checkpoint) State ¶
func (c Checkpoint) State() []byte
State returns a copy of the canonical concrete state frame.
type CheckpointStore ¶
type CheckpointStore interface {
SaveCheckpoint(Checkpoint) error
}
CheckpointStore atomically records the state frame, HLC state (when any), frontier, checkpoint ID, and epoch. Its success result is the durability boundary used by Session before it emits an acknowledgement.
type Delivery ¶
Delivery describes the result of receiving one change. Buffered reports an out-of-order change retained for its missing per-actor prefix; Applied lists every dot installed by this call, including any now-unblocked buffered changes. Duplicate reports that this call did not retain or install its change because the dot was already known.
type Dot ¶
Dot is a persistently assigned, per-group operation sequence number. It is deliberately not an HLC tag: an HLC timestamp is ordered, but is not proof that every earlier timestamped mutation was received. A Frontier advances only over contiguous dots and is therefore safe for missing-update queries.
type Frontier ¶
type Frontier struct {
// contains filtered or unexported fields
}
Frontier records the greatest contiguous dot durably installed for each actor. Its internals are private so callers cannot create a false prefix by mutating a returned map.
func NewFrontier ¶
NewFrontier returns an immutable-by-convention frontier from contiguous sequence values. Zero entries are rejected because absence already denotes counter zero.
func (Frontier) Advance ¶
Advance returns a frontier that includes dot. Duplicates are idempotent; receiving a future dot before its predecessor is rejected instead of making the frontier claim knowledge it cannot prove.
type Inbox ¶
type Inbox struct {
// contains filtered or unexported fields
}
Inbox is a bounded, transport-independent receiver for one manifest. It accepts duplicate and out-of-order deliveries, but its frontier advances only across contiguous persisted actor counters. Applications must persist the concrete CRDT state and the resulting frontier atomically before using it as a recovery/checkpoint boundary.
func NewInbox ¶
func NewInbox(manifest Manifest, frontier Frontier, maxPending, maxBytes int, apply ApplyDelta) (*Inbox, error)
NewInbox creates a bounded receiver. maxPending and maxBytes cover only deferred out-of-order frames; immediately applicable frames are bounded by encoding.DefaultLimits and the concrete CRDT decoder. It accepts only stable protocols; use NewInboxWithPolicy for an explicit experimental protocol opt-in.
func NewInboxWithPolicy ¶ added in v1.0.6
func NewInboxWithPolicy(manifest Manifest, frontier Frontier, maxPending, maxBytes int, apply ApplyDelta, policy crdt.ProtocolPolicy) (*Inbox, error)
NewInboxWithPolicy creates a bounded receiver under policy. Experimental protocols require an explicit AllowExperimental policy at this use boundary.
type Manifest ¶
Manifest is the authenticated agreement for one CRDT replication group. GroupID and SchemaID are application-defined stable names. A group carries one concrete CRDT protocol; applications that replicate multiple objects create multiple manifests rather than treating unrelated frames as one atomic document.
func NewManifest ¶
func NewManifest(groupID, schemaID string, epoch uint64, protocol Protocol, policy crdt.ProtocolPolicy) (Manifest, error)
NewManifest validates an immutable-by-convention manifest. policy is checked here so a caller cannot accidentally construct a group for a reserved, unknown, or disabled experimental frame type.
func (Manifest) Compatible ¶
Compatible reports whether local and remote describe the same replication group and exact CRDT semantics. It intentionally rejects a semantic-version mismatch rather than guessing that two versions can read one another.
type Protocol ¶
Protocol identifies exactly one framed CRDT protocol in a replication group. SemanticsVersion is independent of encoding.FormatVersion: changing conflict semantics, snapshot meaning, or tombstone lifecycle requires a new semantic version (and, when frame compatibility is broken, new type IDs).
CodecID is the schema/element codec identifier carried by every frame in this group. It may be empty for CRDTs whose canonical frames have no codec.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session binds a manifest to an optional checkpoint. It is safe for concurrent callers. A session permits only one checkpoint ID: a rebase must create a new epoch/manifest instead of silently replacing a recovery base.
func NewSession ¶
NewSession creates a checkpoint session for one stable-protocol manifest. Use NewSessionWithPolicy for an explicit experimental protocol opt-in.
func NewSessionWithPolicy ¶ added in v1.0.6
func NewSessionWithPolicy(manifest Manifest, policy crdt.ProtocolPolicy) (*Session, error)
NewSessionWithPolicy creates a checkpoint session under policy. Experimental protocols require an explicit AllowExperimental policy at this use boundary.
func (*Session) Acknowledge ¶
func (s *Session) Acknowledge() (Acknowledgement, error)
Acknowledge returns a proof of durable checkpoint installation. The returned frontier is a copy and cannot mutate Session state.
func (*Session) Install ¶
func (s *Session) Install(checkpoint Checkpoint, store CheckpointStore) error
Install persists checkpoint before publishing it to the session. If storage fails, the session remains unable to acknowledge the checkpoint.
type StateValidator ¶
StateValidator must perform concrete CRDT validation of one complete state frame. A frame-envelope checksum is not sufficient evidence that a snapshot is recoverable. Validators receive owned bytes, and a panic is treated as a rejected checkpoint.
Source Files