primarylease

type Authority ¶

type Authority struct {
	// contains filtered or unexported fields
}

Authority issues signed certificates only after an external LeaseStore CAS makes the handoff durable. It has no HTTP listener, peer authentication or membership logic; those are deployment concerns around the store.

func NewAuthority(options AuthorityOptions) (*Authority, error)

func (authority *Authority) Grant(ctx context.Context, request GrantRequest) (Grant, error)

func (authority *Authority) Revoke(ctx context.Context, databaseID [16]byte, epoch uint64) (LeaseRecord, error)

func (authority *Authority) Stats() AuthorityStats

type AuthorityOptions ¶

type AuthorityOptions struct {
	Store         LeaseStore
	PrivateKey    ed25519.PrivateKey
	LeaseDuration time.Duration
	MaxClockSkew  time.Duration
	Clock         func() time.Time
	CASRetries    int
}

AuthorityOptions configures a controller-side certificate issuer. MaxClockSkew is the maximum absolute offset allowed between a primary and the controller. A new owner cannot receive a currently valid certificate until the preceding certificate's expiry plus this window.

type AuthorityStats ¶

type AuthorityStats struct {
	GrantAttempts              uint64
	Granted                    uint64
	HandoffWaits               uint64
	PromotionAttempts          uint64
	PromotionReadinessRejected uint64
	SequenceRejected           uint64
	StoreFailures              uint64
	CASConflicts               uint64
	RevokeAttempts             uint64
	Revoked                    uint64
}

AuthorityStats is a fixed-cardinality, identity-free process snapshot for a controller issuer. It deliberately excludes database IDs, owners, epochs, certificates, endpoints and error details. Read it from a sampler rather than from a controller request hot path.

type Certificate ¶

type Certificate struct {
	DatabaseID     [16]byte
	Owner          string
	Epoch          uint64
	CommitSequence uint64
	NotBefore      time.Time
	NotAfter       time.Time
}

Certificate is a controller-issued, signed authority to accept writes for a bounded time. CommitSequence is the source position at which the authority was issued; the first accepted write must advance beyond it. Epoch must grow monotonically in the controller, but the guard treats it as opaque ordering data because it cannot contact the controller in the write path.

func Parse(encoded string, publicKey ed25519.PublicKey) (Certificate, error)

func (certificate Certificate) String() string

type DurableConsumerPromotionReadiness ¶

type DurableConsumerPromotionReadiness struct {
	Source       *meldbase.DB
	ConsumerName string
	Buffer       int
}

DurableConsumerPromotionReadiness is a first-party readiness check for a single-writer follower. It verifies that the source's authenticated named durable database consumer has durably acknowledged exactly the candidate follower's local token, and that the source has not advanced beyond it.

Authority runs readiness only after the old lease's skew-safe handoff point. The deployment must still ensure that the source used that lease guard and that ConsumerName is bound by its replication transport to this follower's trusted identity. It deliberately stays closed if the source is unavailable, history state is missing or either position differs.

func (readiness DurableConsumerPromotionReadiness) VerifyFollowerPromotion(ctx context.Context, request meldbase.FollowerPromotionRequest, record LeaseRecord, exists bool) error

type FileStore ¶

type FileStore struct {
	// contains filtered or unexported fields
}

FileStore is one durable, single-member LeaseStore rooted in a trusted existing directory. It is suitable as the local state of one independently operated quorum member, not as a quorum or leader-election service by itself. Each database identity has a separate atomically replaced record.

The directory must be on storage appropriate for the controller's durability contract. FileStore writes use a per-record advisory flock, durable temporary file, atomic rename and directory fsync. A checksum makes torn, malformed or substituted record data fail closed.

func NewFileStore(directory string) (*FileStore, error)

func (store *FileStore) CompareAndSwapPrimaryLease(ctx context.Context, databaseID [16]byte, previous *LeaseRecord, next LeaseRecord) (bool, error)

func (store *FileStore) LoadPrimaryLease(ctx context.Context, databaseID [16]byte) (LeaseRecord, bool, error)

func (store *FileStore) String() string

type Grant ¶

type Grant struct {
	Certificate string
	Record      LeaseRecord
	RetryAfter  time.Time
}

Grant is the controller response for a primary or follower-promotion request. RetryAfter is set only with ErrLeaseActive.

type GrantRequest ¶

type GrantRequest struct {
	DatabaseID     [16]byte
	Owner          string
	CommitSequence uint64
}

GrantRequest identifies the owner and exact source position the controller is asked to certify. Owner must derive from authenticated controller-side identity, never an application request.

type Guard ¶

type Guard struct {
	// contains filtered or unexported fields
}

Guard implements meldbase.PrimaryWriteFence and meldbase.FollowerPromotionFenceBinder. Install is used for an already elected primary; follower promotion binds the certificate returned by the external promotion authority automatically.

func NewGuard(publicKey ed25519.PublicKey, options GuardOptions) (*Guard, error)

business writes until Install or follower promotion binds a certificate.

func (guard *Guard) BindFollowerPromotion(ctx context.Context, fence meldbase.FollowerPromotionFence) error

func (guard *Guard) Install(encoded string) error

func (guard *Guard) LeaseStatus() GuardLeaseStatus

func (guard *Guard) Revoke()

func (guard *Guard) ValidatePrimaryWrite(request meldbase.PrimaryWriteFenceRequest) error

type GuardLeaseStatus ¶

type GuardLeaseStatus struct {
	Installed      bool
	Epoch          uint64
	CommitSequence uint64
	NotBefore      time.Time
	NotAfter       time.Time
}

GuardLeaseStatus is a fixed local snapshot for a renewal supervisor. It contains no certificate text or owner identity. Installed does not imply the lease is still time-valid; callers evaluate NotAfter against their own trusted local clock.

type GuardOptions ¶

type GuardOptions struct {
	Owner            string
	MaxLeaseDuration time.Duration
	Clock            func() time.Time
}

GuardOptions configures a local primary write guard. Owner is a stable, controller-defined process identity; it is not supplied by an untrusted client. Clock is intended for deterministic tests; production callers leave it nil.

type LeaseRecord ¶

type LeaseRecord struct {
	DatabaseID     [16]byte
	Owner          string
	Epoch          uint64
	CommitSequence uint64
	NotAfter       time.Time
	Revoked        bool
}

LeaseRecord is the controller's durable compare-and-swap state for one database. It is deliberately distinct from a rollback anchor: Owner/Epoch move forward and a lease may expire, while a rollback anchor is a permanent lower bound on recoverable history.

type LeaseStore ¶

type LeaseStore interface {
	LoadPrimaryLease(context.Context, [16]byte) (LeaseRecord, bool, error)
	CompareAndSwapPrimaryLease(context.Context, [16]byte, *LeaseRecord, LeaseRecord) (bool, error)
}

LeaseStore is the minimal durable CAS required by Authority. Implement it with a quorum-backed transactional store in production. Load and CompareAndSwap must be linearizable for a database identity; a local file or MemoryStore is useful only for deterministic development/testing.

previous is nil only when the record is expected not to exist. A false swap result is a concurrent state change, not a successful no-op.

type MemoryStore ¶

type MemoryStore struct {
	// contains filtered or unexported fields
}

MemoryStore is a linearizable in-process LeaseStore for tests and local deterministic demos. It must not be used as a production quorum store.

func NewMemoryStore() *MemoryStore

func (store *MemoryStore) CompareAndSwapPrimaryLease(ctx context.Context, databaseID [16]byte, previous *LeaseRecord, next LeaseRecord) (bool, error)

func (store *MemoryStore) LoadPrimaryLease(ctx context.Context, databaseID [16]byte) (LeaseRecord, bool, error)

type PrimaryOptions ¶

type PrimaryOptions struct {
	OpenOptions     meldbase.OpenOptions
	PublicKey       ed25519.PublicKey
	GuardOptions    GuardOptions
	RenewalClient   RenewalClient
	RequestTimeout  time.Duration
	RetryInterval   time.Duration
	KeepLeaseOnStop bool
}

PrimaryOptions assembles one primary with the exact Guard instance that its Renewer will update. OpenOptions remains available for storage settings, but PrimaryWriteFence and Follower are owned by this constructor and must be left unset/false.

type PrimaryRuntime ¶

type PrimaryRuntime struct {
	DB      *meldbase.DB
	Guard   *Guard
	Renewer *Renewer
}

PrimaryRuntime owns the safely wired primary components. The database starts closed to writes because Guard starts without a certificate; call Renew once explicitly or Run under a long-lived supervisor before serving mutations.

func OpenPrimary(path string, options PrimaryOptions) (*PrimaryRuntime, error)

func (runtime *PrimaryRuntime) Close() error

func (runtime *PrimaryRuntime) Renew(ctx context.Context) error

func (runtime *PrimaryRuntime) Run(ctx context.Context) error

type PromotionAuthority ¶

type PromotionAuthority struct {
	Authority *Authority
	Owner     string
	Readiness PromotionReadiness
}

PromotionAuthority adapts a controller Authority to meldbase.FollowerPromotionAuthority. Construct it with the authenticated target process owner identity; it never accepts that identity from a replication frame.

func (authority PromotionAuthority) AuthorizeFollowerPromotion(ctx context.Context, request meldbase.FollowerPromotionRequest) (meldbase.FollowerPromotionFence, error)

type PromotionReadiness ¶

type PromotionReadiness interface {
	VerifyFollowerPromotion(context.Context, meldbase.FollowerPromotionRequest, LeaseRecord, bool) error
}

PromotionReadiness proves that a specific follower position is eligible for promotion against the controller state observed by the same Authority CAS attempt. A production implementation normally verifies durable replication receipt/ack evidence and any required application recovery policy. Owner and epoch fencing alone cannot prove that an asynchronous follower contains all writes from the former primary.

type PromotionReadinessFunc ¶

type PromotionReadinessFunc func(context.Context, meldbase.FollowerPromotionRequest, LeaseRecord, bool) error

PromotionReadinessFunc adapts a function to PromotionReadiness.

func (function PromotionReadinessFunc) VerifyFollowerPromotion(ctx context.Context, request meldbase.FollowerPromotionRequest, record LeaseRecord, exists bool) error

type QuorumReplica ¶

type QuorumReplica struct {
	MemberID string
	Store    LeaseStore
}

QuorumReplica binds one independent, statically identified controller member to a local LeaseStore adapter. Store typically represents an authenticated HTTPS/mTLS RPC client. MemberID must be stable configuration, not a value supplied by a request or endpoint response.

type QuorumStats ¶

type QuorumStats struct {
	Replicas         uint64
	Quorum           uint64
	Loads            uint64
	CompareAndSwaps  uint64
	EndpointFailures uint64
	QuorumFailures   uint64
	Conflicts        uint64
}

QuorumStats is a fixed, identity-free operational snapshot. It intentionally omits endpoint and database identities.

type QuorumStore ¶

type QuorumStore struct {
	// contains filtered or unexported fields
}

QuorumStore turns independent linearizable member stores into a fail-closed LeaseStore. A successful CAS is persisted on a strict majority. Reads accept only a record (or absence) held identically by a strict majority; they never choose a maximum from crossed or partial histories.

This is the quorum layer, not a membership/election system. Deployments must still use separately operated failure domains and an authenticated adapter for every replica.

func NewQuorumStore(replicas []QuorumReplica) (*QuorumStore, error)

func (store *QuorumStore) CompareAndSwapPrimaryLease(ctx context.Context, databaseID [16]byte, previous *LeaseRecord, next LeaseRecord) (bool, error)

func (store *QuorumStore) LoadPrimaryLease(ctx context.Context, databaseID [16]byte) (LeaseRecord, bool, error)

func (store *QuorumStore) Stats() QuorumStats

func (store *QuorumStore) String() string

type RenewalClient ¶

type RenewalClient interface {
	Grant(context.Context, [16]byte, uint64) (Grant, error)
}

RenewalClient is the narrow control-plane dependency used by Renewer. The supplied authorityhttp.Client implements it. Owner authentication stays in that transport and is never an argument to a renewal request.

type Renewer ¶

type Renewer struct {
	// contains filtered or unexported fields
}

Renewer performs controller I/O outside the database writer. It is not a leader-election, replication-ack or promotion mechanism: its commit sequence snapshot is a controller checkpoint and cannot establish follower completeness after a source failure.

func NewRenewer(options RenewerOptions) (*Renewer, error)

func (renewer *Renewer) Renew(ctx context.Context) error

func (renewer *Renewer) Run(ctx context.Context) error

func (renewer *Renewer) Stats() RenewerStats

type RenewerOptions ¶

type RenewerOptions struct {
	DB              *meldbase.DB
	Guard           *Guard
	Client          RenewalClient
	RequestTimeout  time.Duration
	RetryInterval   time.Duration
	KeepLeaseOnStop bool
	Clock           func() time.Time
}

RenewerOptions configures a single-primary renewal agent. DB must be the same database that was opened with Guard as its PrimaryWriteFence. The API cannot infer that pointer equality across the Meldbase boundary, so this deployment wiring is explicit and checked at least for a configured fence.

KeepLeaseOnStop is deliberately false by default: Run revokes the local guard when its supervisory context ends, so a stopped supervisor cannot leave a process writable until natural certificate expiry. Set it only when another supervisor takes over with the same process and guard lifecycle.

type RenewerStats ¶

type RenewerStats struct {
	Attempts            uint64
	Succeeded           uint64
	Failed              uint64
	InstallFailed       uint64
	ConsecutiveFailures uint64
	Running             bool
}

RenewerStats is a fixed-cardinality, identity-free supervisor snapshot. It intentionally contains no certificate, endpoint, owner or database ID.