Documentation
¶
Overview ¶
Package replica is the L0 write-replication layer: it fans an opaque write payload out to the ring-owners of a key and returns once a write **quorum** has durably applied it, so the unflushed head survives the loss of a minority of replicas (DESIGN.md §11; RF=3, quorum (RF/2)+1=2). The storage library owns the node-to-node transport (see Transport and the HTTP implementation in this package) rather than delegating it to the embedder.
The replicator is decoupled from the ring and membership: the caller resolves a key to its owners' [Target]s (network addresses), and a target equal to the local node is applied in process instead of sent over the wire.
Index ¶
- Constants
- Variables
- type ApplyFunc
- type Replicator
- func (r *Replicator) Apply(ctx context.Context, payload []byte) error
- func (r *Replicator) Handler() http.Handler
- func (r *Replicator) Replicate(ctx context.Context, targets []Target, payload []byte) error
- func (r *Replicator) ReplicateQuorum(ctx context.Context, targets []Target, payload []byte, quorum int) error
- type Target
- type Transport
Constants ¶
const ReplicatePath = "/internal/replicate"
ReplicatePath is the HTTP path the replication server serves and the transport posts to.
Variables ¶
var ErrNoTargets = errors.New("replica: no targets")
ErrNoTargets is returned by Replicator.Replicate when no replica targets are given.
Functions ¶
This section is empty.
Types ¶
type ApplyFunc ¶
ApplyFunc applies a replicated write to the local store (decoding the payload). It is what a Target equal to the local node runs in process, and what the receiving side of the transport runs for a remote write.
type Replicator ¶
type Replicator struct {
// contains filtered or unexported fields
}
Replicator fans writes out to replica targets and enforces write quorum.
func New ¶
func New(self string, transport Transport, apply ApplyFunc) *Replicator
New returns a replicator for the local node at self, using transport for remote sends and apply for local (and, on the receiving side, remote) application.
func (*Replicator) Apply ¶
func (r *Replicator) Apply(ctx context.Context, payload []byte) error
Apply applies a payload locally — the entry point the transport's receiving side calls for an inbound replicated write.
func (*Replicator) Handler ¶
func (r *Replicator) Handler() http.Handler
Handler returns the HTTP handler that receives replicated writes and applies them via the replicator. Mount it on the node's internal server at ReplicatePath:
mux.Handle(replica.ReplicatePath, rp.Handler())
func (*Replicator) Replicate ¶
Replicate sends payload to every target (the local one applied in process, the rest over the transport) and returns nil as soon as a quorum — (len(targets)/2)+1 — has acked. It returns early with an error once enough targets have failed that quorum is unreachable. The non-quorum targets still receive the write (best-effort) so all replicas converge; only the wait is quorum-bounded.
func (*Replicator) ReplicateQuorum ¶ added in v0.2.0
func (r *Replicator) ReplicateQuorum(ctx context.Context, targets []Target, payload []byte, quorum int) error
ReplicateQuorum is Replicator.Replicate with an explicit required-ack count, for callers that compute quorum themselves — e.g. a shard primary that has already applied locally and needs only (RF/2) more acks from its secondaries. A quorum ≤ 0 returns immediately (the caller's own copy suffices); a quorum exceeding len(targets) can never be met.
type Target ¶
type Target struct {
Addr string
}
Target is one replica destination: a node's network address.
type Transport ¶
Transport sends a replicated write payload to a peer node at addr and returns when the peer has applied it (ack) or an error if it did not. Implementations must be safe for concurrent use. The HTTP implementation is NewHTTPTransport.
func NewHTTPTransport ¶
NewHTTPTransport returns a Transport that POSTs payloads to peers at http://{addr}{ReplicatePath}. A nil client uses http.DefaultClient; pass one with a timeout in production.
Source Files