tombstonegc

package
v1.0.21 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 30, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package tombstonegc coordinates safe, automatic tombstone collection. It deliberately does not provide membership discovery, authentication, or persistence; applications must supply an authoritative membership view and authenticate acknowledgement messages before passing them to Coordinator.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidMembership = errors.New("tombstonegc: invalid membership")
	ErrInvalidGroup      = errors.New("tombstonegc: invalid replication group")
	ErrGroupMismatch     = errors.New("tombstonegc: acknowledgement replication group mismatch")
	ErrUnknownMember     = errors.New("tombstonegc: acknowledgement from unknown member")
	ErrStaleMembership   = errors.New("tombstonegc: acknowledgement membership epoch is stale")
	ErrInvalidTag        = errors.New("tombstonegc: invalid tombstone tag")
	ErrNilTarget         = errors.New("tombstonegc: nil tombstone target")
)
View Source 
var (
	// ErrMembershipGroupMismatch means an installed membership belongs to a
	// different replication group than the coordinator.
	ErrMembershipGroupMismatch = errors.New("tombstonegc: membership replication group mismatch")
	// ErrMembershipRollback means an installed membership would move the
	// coordinator to an earlier or conflicting membership epoch.
	ErrMembershipRollback = errors.New("tombstonegc: membership epoch rollback")
)

Functions

This section is empty.

Types

type AcknowledgementStats added in v1.0.8 

type AcknowledgementStats struct {
	GroupID string
	Epoch   uint64
	Members int
	Tags    int
	Entries int
}

AcknowledgementStats is a point-in-time summary for setting application GC policy. Entries counts unique member/tag acknowledgements; Tags counts the tags with at least one retained acknowledgement.

type Coordinator 

type Coordinator[T comparable] struct {
	// contains filtered or unexported fields
}

Coordinator collects exact tombstone acknowledgements for one replicated target. Its state is deliberately fail-closed: a restart or membership replacement clears acknowledgements and can delay collection, but cannot make a tombstone eligible prematurely.

Removing a member is only safe after the application has retired it from the replication protocol. A removed member that later reconnects must bootstrap from a snapshot created after the compaction it missed.

func NewCoordinator 

func NewCoordinator[T comparable](groupID string, members []string) (*Coordinator[T], error)

NewCoordinator creates a coordinator for groupID with the initial active membership. groupID must uniquely name this replication group and be included in authenticated acknowledgement messages. At least one unique, non-blank member is required.

func NewCoordinatorAtMembership added in v1.0.8 

func NewCoordinatorAtMembership[T comparable](membership Membership) (*Coordinator[T], error)

NewCoordinatorAtMembership creates a coordinator at an externally assigned, persisted membership epoch. Callers must authenticate and durably record the membership view before constructing the coordinator. Unlike NewCoordinator, this constructor does not invent epoch 1 after a process restart.

func (*Coordinator[T]) Acknowledge 

func (c *Coordinator[T]) Acknowledge(groupID, member string, epoch uint64, tombstones []crdt.Tag) error

Acknowledge records the exact tombstones present at one member under the supplied group ID and membership epoch. Repeated reports are idempotently unioned.

func (*Coordinator[T]) AcknowledgeAndCompact 

func (c *Coordinator[T]) AcknowledgeAndCompact(groupID, member string, epoch uint64, tombstones []crdt.Tag, target *set.ORSet[T]) (int, error)

AcknowledgeAndCompact records one exact acknowledgement and immediately removes from target only tombstones acknowledged by every current member. It is the normal receive-path operation for automatic collection.

func (*Coordinator[T]) AcknowledgeAndCompactTarget added in v1.0.10 

func (c *Coordinator[T]) AcknowledgeAndCompactTarget(groupID, member string, epoch uint64, tombstones []crdt.Tag, target TombstoneTarget) (int, error)

AcknowledgeAndCompactTarget records one exact acknowledgement and immediately removes from target only tombstones acknowledged by every current member. It reuses the same fail-closed membership epoch as OR-Set collection, but it cannot prove that a post-compaction checkpoint was persisted or that old deltas were retired; callers must do both before accepting compaction.

func (*Coordinator[T]) AcknowledgeSetAndCompact 

func (c *Coordinator[T]) AcknowledgeSetAndCompact(groupID, member string, epoch uint64, acknowledged *set.ORSet[T], target *set.ORSet[T]) (int, error)

AcknowledgeSetAndCompact is AcknowledgeAndCompact for a member's complete current OR-Set state. The state must be a verified representation received from that member, not an inferred frontier.

func (*Coordinator[T]) AcknowledgementStats added in v1.0.8 

func (c *Coordinator[T]) AcknowledgementStats() AcknowledgementStats

AcknowledgementStats returns counts suitable for monitoring acknowledgement memory and deciding when to persist a post-compaction snapshot and prune records. It returns an empty value for a nil coordinator.

func (*Coordinator[T]) InstallMembership added in v1.0.8 

func (c *Coordinator[T]) InstallMembership(membership Membership) error

InstallMembership installs an already authenticated, authoritative membership view. It accepts only a strictly newer epoch for the same group and clears all receipt state, so a receipt from an old view can never make a tombstone eligible for collection. Replaying the currently installed view is idempotent when its member set is identical.

func (*Coordinator[T]) Membership 

func (c *Coordinator[T]) Membership() Membership

Membership returns a sorted, immutable copy of the active membership view.

func (*Coordinator[T]) PruneAcknowledgements added in v1.0.8 

func (c *Coordinator[T]) PruneAcknowledgements(groupID string, epoch uint64, tags []crdt.Tag) (int, error)

PruneAcknowledgements removes retained acknowledgement proofs for tags in the current membership epoch. Call it only after the local compacted target has been durably snapshotted. Pruning is fail-closed: it can delay a later compaction until members report again, but it cannot make a tag eligible.

A Coordinator shared by multiple local targets must not prune a tag until every target that relies on this Coordinator has compacted it or can safely wait for another full acknowledgement cycle. The return value is the number of member/tag acknowledgement records removed.

func (*Coordinator[T]) ReplaceMembership 

func (c *Coordinator[T]) ReplaceMembership(members []string) (Membership, error)

ReplaceMembership installs an authoritative new membership view. It clears all collected acknowledgements and increments the epoch, so reports from an earlier view cannot make any tombstone eligible for collection.

type Membership 

type Membership struct {
	GroupID string
	Epoch   uint64
	Members []string
}

Membership is an immutable view of the active replicas that must acknowledge a tombstone before it can be removed.

type TombstoneTarget added in v1.0.10 

type TombstoneTarget interface {
	TombstoneTags() []crdt.Tag
	CompactTombstones([]crdt.Tag) (int, error)
}

TombstoneTarget is a CRDT whose tombstones can be enumerated and compacted. Coordinator only establishes exact acknowledgement eligibility; targets must enforce their own structural compaction rules.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.