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 Option
- type Replicator
- func (r *Replicator) Apply(ctx context.Context, payload []byte) error
- func (r *Replicator) Close()
- 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 DefaultSendTimeout = 10 * time.Second
DefaultSendTimeout bounds one send once it is detached from the caller's context, so a peer that hangs does not hold a goroutine until Replicator.Close. Override with WithSendTimeout.
const (
// ReplicatePath is the HTTP path the replication server serves and the transport posts to.
ReplicatePath = "/internal/replicate"
)
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 Option ¶ added in v0.45.0
type Option func(*Replicator)
Option configures a Replicator.
func WithSendTimeout ¶ added in v0.45.0
WithSendTimeout bounds how long one detached send may run. Since a send no longer ends with the caller's context, this — not the write deadline — is what caps a quorum wait against a slow peer, so it must exceed the slowest acceptable peer round-trip. Zero or negative ⇒ DefaultSendTimeout.
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, opts ...Option) *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) Close ¶ added in v0.45.0
func (r *Replicator) Close()
Close cancels every in-flight send and waits for them to return. Replicate must not be called after Close.
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.
ctx bounds the wait, not the sends: each send carries ctx's values (trace, logger) but not its cancellation, and ends on its own timeout or at Replicator.Close — so a straggler is still delivered after the caller has answered its client.
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