network

package
v0.14.1 Latest Latest
Warning

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

 Go to latest Published: Sep 12, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxRequestBodyBytes = 1 << 20

MaxRequestBodyBytes is the HTTP adapter's JSON decoding limit. Replicated mutations have the smaller quepaxa.MaxReplicatedValueBytes consensus limit.

Variables

View Source 
var (
	ErrNotReady              = errors.New("node is not ready")
	ErrRequestConflict       = errors.New("request ID conflict")
	ErrInvalidRequest        = errors.New("invalid request")
	ErrOverloaded            = errors.New("mutation queue overloaded")
	ErrDurabilityUnavailable = errors.New("object-store durability unavailable")
	ErrCommitUnknown         = errors.New("commit outcome unknown")
	ErrGraphResourceLimit    = errors.New("graph resource limit exceeded")
	ErrReadVersionMismatch   = errors.New("read version mismatch")
)

Functions

func ValidateExecuteRequest added in v0.8.1 

func ValidateExecuteRequest(req ExecuteRequest) error

ValidateExecuteRequest applies the same mutation contract and encoded-size check as Execute without submitting the command.

func VerifyRecoveryProbe added in v0.14.0 

func VerifyRecoveryProbe(p RecoveryProbe, nonce, token string) bool

Types

type CommitUnknownError 

type CommitUnknownError struct {
	Slot             quepaxa.Slot
	RequestID        string
	RetryThroughSlot uint64
	Cause            error
}

CommitUnknownError means a mutation may commit despite the failed call. Retrying the same request ID resolves the outcome without duplicating it.

func (*CommitUnknownError) Error 

func (e *CommitUnknownError) Error() string

func (*CommitUnknownError) Unwrap 

func (e *CommitUnknownError) Unwrap() []error

type DecisionsResponse 

type DecisionsResponse struct {
	ClusterID  types.ClusterID        `json:"cluster_id"`
	ProposerID quepaxa.NodeID         `json:"proposer_id"`
	ConfigID   uint                   `json:"config_id"`
	Tip        quepaxa.Slot           `json:"tip"`
	Decisions  []quepaxa.DecidedValue `json:"decisions"`
}

type ErrorResponse added in v0.9.1 

type ErrorResponse struct {
	Code             string `json:"code"`
	Error            string `json:"error"`
	RequestID        string `json:"request_id,omitempty"`
	Slot             uint64 `json:"slot,omitempty"`
	RetryThroughSlot uint64 `json:"retry_through_slot,omitempty"`
}

ErrorResponse is the stable JSON error envelope returned by the HTTP adapter.

type ExecuteRequest 

type ExecuteRequest struct {
	RequestID string `json:"request_id"`
	SQL       string `json:"sql,omitempty"`
	Args      []any  `json:"args,omitempty"`
	// WantRows requests bounded rows from a replicated mutation.
	WantRows   bool                 `json:"want_rows,omitempty"`
	RequireOne bool                 `json:"require_one,omitempty"`
	Statements []types.SQLStatement `json:"statements,omitempty"`
}

ExecuteRequest is the request body for execute.

type ExecuteResponse 

type ExecuteResponse struct {
	types.MutationReceipt
	Statements []types.SQLStatementResult `json:"statements,omitempty"`
}

ExecuteResponse contains the bounded aggregate receipt and requested rows.

type GraphExecuteResponse 

type GraphExecuteResponse struct {
	types.MutationReceipt
}

type GraphQueryRequest 

type GraphQueryRequest struct {
	Cypher      string         `json:"cypher"`
	Args        map[string]any `json:"args,omitempty"`
	Consistency string         `json:"consistency,omitempty"`
}

type GraphReachableRequest added in v0.10.0 

type GraphReachableRequest = types.GraphReachableRequest

type GraphReachableResult added in v0.10.0 

type GraphReachableResult = types.GraphReachableResult

type GraphStreamOffsetRequest 

type GraphStreamOffsetRequest struct {
	RequestID   string `json:"request_id,omitempty"`
	Stream      string `json:"stream"`
	Consumer    string `json:"consumer"`
	Sequence    uint64 `json:"sequence,omitempty"`
	Consistency string `json:"consistency,omitempty"`
}

type GraphStreamOffsetResponse 

type GraphStreamOffsetResponse struct {
	Sequence     uint64 `json:"sequence"`
	Found        bool   `json:"found"`
	AppliedSlot  uint64 `json:"applied_slot"`
	ConsensusTip uint64 `json:"consensus_tip"`
}

type GraphStreamReadRequest 

type GraphStreamReadRequest struct {
	Stream        string `json:"stream,omitempty"`
	AfterSequence uint64 `json:"after_sequence,omitempty"`
	Limit         uint   `json:"limit,omitempty"`
	WaitMS        uint32 `json:"wait_ms,omitempty"`
	Consistency   string `json:"consistency,omitempty"`
}

type GraphStreamReadResponse 

type GraphStreamReadResponse struct {
	Records      []types.GraphStreamRecord `json:"records"`
	AppliedSlot  uint64                    `json:"applied_slot"`
	ConsensusTip uint64                    `json:"consensus_tip"`
}

type GraphStreamTrimRequest 

type GraphStreamTrimRequest struct {
	RequestID       string `json:"request_id"`
	Stream          string `json:"stream"`
	ThroughSequence uint64 `json:"through_sequence"`
}

type KVGetRequest 

type KVGetRequest struct{ Key, Consistency string }

type KVGetResponse 

type KVGetResponse struct {
	Found        bool   `json:"found"`
	Value        []byte `json:"value,omitempty"`
	AppliedSlot  uint64 `json:"applied_slot"`
	ConsensusTip uint64 `json:"consensus_tip"`
}

type KVMutationRequest 

type KVMutationRequest struct {
	RequestID      string `json:"request_id"`
	Key            string `json:"key"`
	Value          []byte `json:"value,omitempty"`
	Expected       []byte `json:"expected,omitempty"`
	ExpectedExists bool   `json:"expected_exists,omitempty"`
	TTLMS          int64  `json:"ttl_ms,omitempty"`
}

type KVMutationResponse 

type KVMutationResponse struct {
	types.MutationReceipt
}

type MembershipChange added in v0.14.0 

type MembershipChange struct {
	OperationID       string           `json:"operation_id"`
	ClusterID         string           `json:"cluster_id"`
	ExpectedConfigID  uint             `json:"expected_config_id"`
	ExpectedAbortSlot quepaxa.Slot     `json:"expected_abort_slot,omitempty"`
	Remove            quepaxa.NodeID   `json:"remove,omitempty"`
	Add               *quepaxa.Member  `json:"add,omitempty"`
	Fence             *MembershipFence `json:"fence,omitempty"`
}

MembershipChange identifies one immutable operation against one configuration. Fence attests external exclusion of the removed incarnation, including its storage writers and replacement scheduling; deleting a Pod alone is not a fence.

type MembershipFence added in v0.14.0 

type MembershipFence struct {
	NodeID      quepaxa.NodeID `json:"node_id"`
	WALIdentity string         `json:"wal_identity"`
	WorkloadUID string         `json:"workload_uid"`
	Confirmed   bool           `json:"confirmed"`
	Evidence    string         `json:"evidence"`
}

type MembershipStatus added in v0.14.0 

type MembershipStatus struct {
	NodeID      quepaxa.NodeID   `json:"node_id"`
	ClusterID   string           `json:"cluster_id"`
	ConfigID    uint             `json:"config_id"`
	Voters      []quepaxa.NodeID `json:"voters"`
	WALIdentity string           `json:"wal_identity"`
	Voting      bool             `json:"voting"`
	Pending     bool             `json:"pending"`
	AbortSlot   quepaxa.Slot     `json:"abort_slot,omitempty"`
}

MembershipStatus contains no peer credentials. WALIdentity identifies this process's persistent incarnation; it is not evidence that another is fenced.

type MigrationRequest added in v0.9.1 

type MigrationRequest struct {
	RequestID  string
	Version    int64
	Name       string
	Checksum   string
	Statements []types.SQLStatement
}

MigrationRequest is the in-process engine command used by DB.Migrate.

type PeerIdentity added in v0.9.1 

type PeerIdentity struct {
	ID        quepaxa.NodeID
	PeerURL   string
	PublicKey [ed25519.PublicKeySize]byte
}

PeerIdentity is the token-free endpoint and pinned TLS identity of a voter.

func NewPeerIdentity added in v0.9.1 

func NewPeerIdentity(clusterID types.ClusterID, member quepaxa.Member) (PeerIdentity, error)

NewPeerIdentity derives the public identity a learner may retain.

type PeerServer 

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

PeerServer owns the private QUIC listener. Public HTTP remains a separate adapter.

func StartLearnerPeerServer added in v0.13.0 

func StartLearnerPeerServer(ctx context.Context, addr string, server *Server, voters []quepaxa.Member, token string, learner quepaxa.Member) (*PeerServer, error)

StartLearnerPeerServer gives an unpromoted learner its own token-bound TLS identity. The learner is not admitted as a voter until its core applies the reconfiguration, so its token cannot authenticate voting RPCs meanwhile.

func StartPeerServer 

func StartPeerServer(ctx context.Context, addr string, server *Server, members []quepaxa.Member, token string) (*PeerServer, error)

func StartPeerServerOnTransport added in v0.13.0 

func StartPeerServerOnTransport(ctx context.Context, transport *quic.Transport, server *Server, members []quepaxa.Member, token string) (*PeerServer, error)

StartPeerServerOnTransport serves on an already-bound QUIC transport. The caller owns the transport and its UDP socket; closing this PeerServer leaves them available for a subsequent listener without releasing the port.

func (*PeerServer) Addr 

func (s *PeerServer) Addr() string

func (*PeerServer) Close 

func (s *PeerServer) Close() error

type QueryRequest 

type QueryRequest struct {
	SQL         string `json:"sql"`
	Args        []any  `json:"args,omitempty"`
	Consistency string `json:"consistency,omitempty"`
}

QueryRequest is the request body for query.

type QueryResponse 

type QueryResponse struct {
	Columns      []string        `json:"columns"`
	Rows         [][]interface{} `json:"rows"`
	AppliedSlot  uint64          `json:"applied_slot"`
	ConsensusTip uint64          `json:"consensus_tip"`
}

QueryResponse is the response body for query.

type ReadAdmissionLimits added in v0.11.0 

type ReadAdmissionLimits struct {
	MaxConcurrent int
	MaxLongPoll   int
}

ReadAdmissionLimits bounds concurrent read work in one Server. Long-poll stream reads additionally use MaxLongPoll so they leave capacity for normal queries. Configure the limits before exposing the Server.

type RecoveryProbe added in v0.14.0 

type RecoveryProbe struct {
	Excluded string              `json:"excluded,omitempty"`
	Nonce    string              `json:"nonce"`
	Status   VoterRecoveryStatus `json:"status"`
	MAC      string              `json:"mac"`
}

RecoveryProbe binds a fresh challenge to the real ReadIndex-backed status. It is not a fencing proof and a timeout is not evidence of process death.

type ReplicaStatus added in v0.9.1 

type ReplicaStatus struct {
	Mode        string    `json:"mode"`
	AppliedSlot uint64    `json:"applied_slot"`
	SourceTip   uint64    `json:"source_tip"`
	LagSlots    uint64    `json:"lag_slots"`
	Source      string    `json:"source"`
	LastSync    time.Time `json:"last_sync"`
	LastError   string    `json:"last_error,omitempty"`
}

ReplicaStatus is the observable catch-up state of a non-voting replica.

type RequestStatusRequest 

type RequestStatusRequest struct {
	Kind      string `json:"kind"`
	RequestID string `json:"request_id"`
}

type RequestStatusResponse 

type RequestStatusResponse struct {
	State   string                 `json:"state"`
	Tip     uint64                 `json:"tip"`
	Receipt *types.MutationReceipt `json:"receipt,omitempty"`
}

type Server 

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

Server is the HTTP server for client API.

func NewServer 

func NewServer(core *quepaxa.Core, material *materializer.Materializer, cluster types.ClusterID, writable bool, transport *Transport, ready ...func() bool) *Server

NewServer creates a new HTTP server.

func (*Server) AbortMembership added in v0.14.0 

func (s *Server) AbortMembership(ctx context.Context, change MembershipChange) error

AbortMembership terminates a pending addition under its original voter quorum. OperationID, ClusterID, ExpectedConfigID and ExpectedAbortSlot suffice; callers need not retain the failed learner's credentials to abort its recorded operation.

func (*Server) ChangeMembership added in v0.14.0 

func (s *Server) ChangeMembership(ctx context.Context, change MembershipChange) error

ChangeMembership joins the server lifecycle so shutdown cannot close its WAL while a management operation is still using it.

func (*Server) Close 

func (s *Server) Close()

Close stops background request batching.

func (*Server) Execute 

func (s *Server) Execute(ctx context.Context, req ExecuteRequest) (ExecuteResponse, error)

Execute applies one SQL statement or an atomic statements transaction.

func (*Server) ExecuteReturning added in v0.9.1 

func (s *Server) ExecuteReturning(ctx context.Context, req ExecuteRequest) (ExecuteResponse, error)

ExecuteReturning executes one replicated mutation and returns its bounded rows.

func (*Server) ExecuteReturningOne added in v0.9.1 

func (s *Server) ExecuteReturningOne(ctx context.Context, req ExecuteRequest) (ExecuteResponse, error)

ExecuteReturningOne commits only when exactly one row is returned.

func (*Server) GraphChanges 

func (s *Server) GraphChanges(ctx context.Context, request GraphStreamReadRequest) (GraphStreamReadResponse, error)

func (*Server) GraphExecute 

func (s *Server) GraphExecute(ctx context.Context, command types.GraphCommand) (GraphExecuteResponse, error)

func (*Server) GraphQuery 

func (s *Server) GraphQuery(ctx context.Context, request GraphQueryRequest) (types.GraphCommandResult, error)

func (*Server) GraphReachable added in v0.10.0 

func (s *Server) GraphReachable(ctx context.Context, request GraphReachableRequest) (GraphReachableResult, error)

func (*Server) GraphStreamOffset 

func (s *Server) GraphStreamOffset(ctx context.Context, request GraphStreamOffsetRequest) (GraphStreamOffsetResponse, error)

func (*Server) GraphStreamRead 

func (s *Server) GraphStreamRead(ctx context.Context, request GraphStreamReadRequest) (GraphStreamReadResponse, error)

func (*Server) KVCAS 

func (s *Server) KVCAS(ctx context.Context, req KVMutationRequest) (KVMutationResponse, error)

func (*Server) KVDelete 

func (s *Server) KVDelete(ctx context.Context, req KVMutationRequest) (KVMutationResponse, error)

func (*Server) KVGet 

func (s *Server) KVGet(ctx context.Context, req KVGetRequest) (KVGetResponse, error)

func (*Server) KVMutate 

func (s *Server) KVMutate(ctx context.Context, operation string, req KVMutationRequest) (KVMutationResponse, error)

func (*Server) KVPut 

func (s *Server) KVPut(ctx context.Context, req KVMutationRequest) (KVMutationResponse, error)

func (*Server) MembershipStatus added in v0.14.0 

func (s *Server) MembershipStatus() (MembershipStatus, error)

MembershipStatus is an observational snapshot, never a fencing authorization.

func (*Server) Migrate added in v0.9.1 

func (s *Server) Migrate(ctx context.Context, req MigrationRequest) (ExecuteResponse, error)

Migrate applies one engine-owned migration atomically with its ledger row.

func (*Server) NotificationDrops 

func (s *Server) NotificationDrops() uint64

func (*Server) NotifyPublish 

func (s *Server) NotifyPublish(ctx context.Context, req types.NotifyCommand) (types.MutationReceipt, error)

func (*Server) NotifySubscribe 

func (s *Server) NotifySubscribe(topic string) (<-chan []byte, func(), error)

func (*Server) ProposeControl 

func (s *Server) ProposeControl(ctx context.Context, value []byte) (quepaxa.Slot, error)

ProposeControl commits an internal read barrier through the normal bounded proposal lifecycle.

func (*Server) Query 

func (s *Server) Query(ctx context.Context, req QueryRequest) (QueryResponse, error)

Query reads SQL locally or after a linearizable consensus barrier.

func (*Server) Quiesce 

func (s *Server) Quiesce(ctx context.Context) (func(), error)

Quiesce drains proposals and excludes decision application while a certified checkpoint replaces local consensus and materialized state.

func (*Server) RequestStatus 

func (s *Server) RequestStatus(ctx context.Context, req RequestStatusRequest) (RequestStatusResponse, error)

func (*Server) ServeHTTP 

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

func (*Server) SetCheckpointPrepare 

func (s *Server) SetCheckpointPrepare(prepare func(context.Context, quepaxa.NodeID, quepaxa.CheckpointSeal) error)

func (*Server) SetCompactedHandler 

func (s *Server) SetCompactedHandler(handler func())

SetCompactedHandler installs the recovery trigger used when a peer has compacted history this node still needs.

func (*Server) SetDurabilityBarrier 

func (s *Server) SetDurabilityBarrier(barrier func(context.Context, quepaxa.Slot) error)

SetDurabilityBarrier installs the mutation ACK barrier before the server is exposed.

func (*Server) SetGraphStreamOffset 

func (s *Server) SetGraphStreamOffset(ctx context.Context, request GraphStreamOffsetRequest) error

func (*Server) SetMembershipAbort added in v0.14.0 

func (s *Server) SetMembershipAbort(abort func(context.Context, MembershipChange) error)

func (*Server) SetMembershipChange added in v0.14.0 

func (s *Server) SetMembershipChange(change func(context.Context, MembershipChange) error)

func (*Server) SetMembershipToken added in v0.14.0 

func (s *Server) SetMembershipToken(token string)

SetMembershipToken configures management authentication before serving.

func (*Server) SetObjectStoreStats 

func (s *Server) SetObjectStoreStats(stats func() (map[string]uint64, bool))

func (*Server) SetReadAdmissionLimits added in v0.11.0 

func (s *Server) SetReadAdmissionLimits(limits ReadAdmissionLimits) error

SetReadAdmissionLimits replaces admission limits for subsequently started reads. It is intended for setup before the Server is exposed.

func (*Server) SetRecoveryArchive added in v0.13.0 

func (s *Server) SetRecoveryArchive(token string, archive func(context.Context) error)

SetRecoveryArchive installs the authenticated operation that publishes the local certified suffix to shared archive storage before destructive recovery.

func (*Server) SetReplicaStatus added in v0.9.1 

func (s *Server) SetReplicaStatus(status func() ReplicaStatus)

func (*Server) SetVoterRecoveryStatus added in v0.13.0 

func (s *Server) SetVoterRecoveryStatus(status func(context.Context) VoterRecoveryStatus)

SetVoterRecoveryStatus installs the voter-only recovery status source.

func (*Server) TrimGraphStream 

func (s *Server) TrimGraphStream(ctx context.Context, request GraphStreamTrimRequest) error

type Transport 

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

Transport sends private peer RPCs over persistent raw QUIC connections.

func NewLearnerTransport added in v0.9.1 

func NewLearnerTransport(clusterID types.ClusterID, localID quepaxa.NodeID, configID uint, peers []PeerIdentity, token string) *Transport

NewLearnerTransport creates a read-only transport without retaining voter tokens.

func NewTransport 

func NewTransport(clusterID types.ClusterID, localID quepaxa.NodeID, config *quepaxa.Cluster, token string) *Transport

func (*Transport) BindCore added in v0.13.0 

func (t *Transport) BindCore(core clusterResolver)

BindCore makes requests resolve the immutable configuration for their slot. It is called once during startup before peer RPCs begin.

func (*Transport) Close 

func (t *Transport) Close() error

func (*Transport) FetchDecisions 

func (t *Transport) FetchDecisions(ctx context.Context, source quepaxa.NodeID, from quepaxa.Slot, limit int) (DecisionsResponse, error)

func (*Transport) FetchValue 

func (t *Transport) FetchValue(ctx context.Context, from quepaxa.NodeID, hash quepaxa.ValueHash) ([]byte, error)

func (*Transport) PrepareCheckpoint 

func (t *Transport) PrepareCheckpoint(ctx context.Context, seal quepaxa.CheckpointSeal) error

PrepareCheckpoint waits for a durable verified quorum before the small seal value enters normal consensus.

func (*Transport) ReadTip 

func (t *Transport) ReadTip(ctx context.Context, to quepaxa.NodeID) (quepaxa.Slot, error)

func (*Transport) SendDecision 

func (t *Transport) SendDecision(ctx context.Context, decision quepaxa.Decision) error

func (*Transport) SendRecord 

func (t *Transport) SendRecord(ctx context.Context, to quepaxa.NodeID, request quepaxa.RecordRequest) (quepaxa.Summary, error)

func (*Transport) StageValue 

func (t *Transport) StageValue(ctx context.Context, to quepaxa.NodeID, hash quepaxa.ValueHash, value []byte) error

func (*Transport) VerifyLearner added in v0.13.0 

func (t *Transport) VerifyLearner(ctx context.Context, learner quepaxa.Member, through quepaxa.Slot, prefix quepaxa.ValueHash) error

VerifyLearner asks the candidate's own QUIC endpoint to prove that its WAL durably contains the exact certified prefix. It is an admission check only; it neither copies data nor changes membership.

type VoterRecoveryStatus added in v0.13.0 

type VoterRecoveryStatus struct {
	NodeID       string `json:"node_id"`
	ClusterID    string `json:"cluster_id"`
	Durability   string `json:"durability"`
	Ready        bool   `json:"ready"`
	Quorum       bool   `json:"quorum"`
	CertifiedTip uint64 `json:"certified_tip"`
	AppliedTip   uint64 `json:"applied_tip"`
	ArchiveTip   uint64 `json:"archive_tip"`
}

VoterRecoveryStatus reports the read-only facts an operator needs to assess voter recovery. It does not grant recovery or fencing authority.

Source Files

View all Source files

Directories

Path Synopsis

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.