replication

type AppendEntriesRequest struct {
	Term         uint64          `json:"term"`
	LeaderID     string          `json:"leader_id"`
	LeaderAddr   string          `json:"leader_addr"`
	PrevLogIndex uint64          `json:"prev_log_index"`
	PrevLogTerm  uint64          `json:"prev_log_term"`
	Entries      []*RaftLogEntry `json:"entries"`
	LeaderCommit uint64          `json:"leader_commit"`
	// CodecVersion identifies the wire format generation (TRC-21/TRC-22).
	// 0 (or absent via omitempty) = pre-version frame; 1 = first versioned frame.
	// Rolling-upgrade compat: receivers treat absent/0 as pre-version and accept
	// gracefully; leaders omit the field when any peer is at version 0.
	CodecVersion uint32 `json:"codec_version,omitempty"`
}

type AppendEntriesResponse struct {
	Term          uint64 `json:"term"`
	Success       bool   `json:"success"`
	MatchIndex    uint64 `json:"match_index"`
	ConflictIndex uint64 `json:"conflict_index"`
	ConflictTerm  uint64 `json:"conflict_term"`
	ResponderID   string `json:"responder_id"`
	// CodecVersion echoes the responder's supported codec version so the leader
	// can track peer capabilities for mixed-cluster compat (TRC-22).
	CodecVersion uint32 `json:"codec_version,omitempty"`
}

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

type ClusterMessage struct {
	Type      ClusterMessageType
	NodeID    string
	Timestamp int64
	Signature string
	Payload   []byte
}

type ClusterMessageType uint8

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

type ClusterTransportConfig struct {
	NodeID       string
	BindAddr     string
	DialTimeout  time.Duration
	ReadTimeout  time.Duration
	WriteTimeout time.Duration
	MaxMsgSize   int
	TLSServer    *tls.Config
	TLSClient    *tls.Config
	AuthSecret   []byte
	AuthMaxSkew  time.Duration
}

type Command struct {
	// Type identifies the operation type.
	Type CommandType

	// Data is the serialized operation data.
	Data []byte

	// Timestamp when the command was created.
	Timestamp time.Time

	// RequestID for idempotency/deduplication.
	RequestID string
}

type CommandType uint8

type Config struct {
	// Mode selects the replication mode (default: standalone)
	// Environment: NORNICDB_CLUSTER_MODE
	Mode ReplicationMode

	// NodeID uniquely identifies this node in the cluster.
	// Auto-generated if not set.
	// Environment: NORNICDB_CLUSTER_NODE_ID
	NodeID string

	// BindAddr is the address to bind the replication server.
	// Environment: NORNICDB_CLUSTER_BIND_ADDR
	BindAddr string

	// AdvertiseAddr is the address advertised to other nodes.
	// Defaults to BindAddr if not set.
	// Environment: NORNICDB_CLUSTER_ADVERTISE_ADDR
	AdvertiseAddr string

	// ReplicationSecret is a shared secret used to authenticate cluster messages.
	// When set, nodes must present valid HMAC signatures for replication traffic.
	// Environment: NORNICDB_CLUSTER_REPLICATION_SECRET
	ReplicationSecret string

	// DataDir for replication state (Raft logs, snapshots).
	// Defaults to main database DataDir + "/replication"
	// Environment: NORNICDB_CLUSTER_DATA_DIR
	DataDir string

	// HAStandby holds hot standby configuration.
	HAStandby HAStandbyConfig

	// Raft holds Raft consensus configuration.
	Raft RaftConfig

	// MultiRegion holds multi-region configuration.
	MultiRegion MultiRegionConfig

	// Consistency holds default consistency levels.
	Consistency ConsistencyConfig

	// TLS holds security configuration for encrypted connections.
	TLS TLSConfig
}

type ConnectionHandler func(conn PeerConnection)

type ConsistencyConfig struct {
	// DefaultWriteConsistency for write operations.
	// Environment: NORNICDB_CLUSTER_WRITE_CONSISTENCY
	DefaultWriteConsistency ConsistencyLevel

	// DefaultReadConsistency for read operations.
	// Environment: NORNICDB_CLUSTER_READ_CONSISTENCY
	DefaultReadConsistency ConsistencyLevel
}

type ConsistencyLevel string

type EdgePayload struct {
	ID            string
	StartNode     string
	EndNode       string
	Type          string
	Properties    map[string]any
	CreatedAt     int64
	Confidence    float64
	AutoGenerated bool
}

type FenceRequest struct {
	Reason    string
	RequestID string
}

type FenceResponse struct {
	Fenced bool
}

type HAStandbyConfig struct {
	// Role is "primary" or "standby".
	// Environment: NORNICDB_CLUSTER_HA_ROLE
	Role string

	// PeerAddr is the address of the other node.
	// Environment: NORNICDB_CLUSTER_HA_PEER_ADDR
	PeerAddr string

	// SyncMode controls replication synchronization.
	// Environment: NORNICDB_CLUSTER_HA_SYNC_MODE
	SyncMode SyncMode

	// HeartbeatInterval is how often to send heartbeats.
	// Environment: NORNICDB_CLUSTER_HA_HEARTBEAT_MS (in milliseconds)
	HeartbeatInterval time.Duration

	// FailoverTimeout is how long to wait before triggering failover.
	// Environment: NORNICDB_CLUSTER_HA_FAILOVER_TIMEOUT
	FailoverTimeout time.Duration

	// AutoFailover enables automatic failover on primary failure.
	// Environment: NORNICDB_CLUSTER_HA_AUTO_FAILOVER
	AutoFailover bool

	// WALBatchSize is max entries per WAL batch.
	// Environment: NORNICDB_CLUSTER_HA_WAL_BATCH_SIZE
	WALBatchSize int

	// WALBatchTimeout is max time to wait for batch fill.
	// Environment: NORNICDB_CLUSTER_HA_WAL_BATCH_TIMEOUT
	WALBatchTimeout time.Duration

	// ReconnectInterval is how often to retry connection to peer.
	// Environment: NORNICDB_CLUSTER_HA_RECONNECT_INTERVAL
	ReconnectInterval time.Duration

	// MaxReconnectBackoff is maximum backoff for reconnection.
	// Environment: NORNICDB_CLUSTER_HA_MAX_RECONNECT_BACKOFF
	MaxReconnectBackoff time.Duration
}

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

type HealthStatus struct {
	// Mode is the replication mode.
	Mode ReplicationMode `json:"mode"`

	// NodeID is this node's identifier.
	NodeID string `json:"node_id"`

	// Role is the current role (leader, follower, standby, etc.).
	Role string `json:"role"`

	// IsLeader indicates if this node accepts writes.
	IsLeader bool `json:"is_leader"`

	// LeaderID is the current leader's ID (if known).
	LeaderID string `json:"leader_id,omitempty"`

	// LeaderAddr is the current leader's address.
	LeaderAddr string `json:"leader_addr,omitempty"`

	// State is the current state (ready, initializing, etc.).
	State string `json:"state"`

	// Healthy indicates overall health.
	Healthy bool `json:"healthy"`

	// ReplicationLag is the lag behind leader (for followers).
	ReplicationLag time.Duration `json:"replication_lag,omitempty"`

	// LastContact is the last successful contact with leader/peer.
	LastContact time.Time `json:"last_contact,omitempty"`

	// Peers contains status of peer nodes.
	Peers []PeerStatus `json:"peers,omitempty"`

	// Region is the region ID (for multi-region).
	Region string `json:"region,omitempty"`

	// CommitIndex is the last committed log index (for Raft).
	CommitIndex uint64 `json:"commit_index,omitempty"`

	// AppliedIndex is the last applied log index.
	AppliedIndex uint64 `json:"applied_index,omitempty"`

	// Term is the current Raft term.
	Term uint64 `json:"term,omitempty"`
}

type HeartbeatRequest struct {
	NodeID      string
	Role        string
	WALPosition uint64
	Timestamp   int64
}

type HeartbeatResponse struct {
	NodeID      string
	Role        string
	WALPosition uint64
	Lag         int64
}

type MessageHandler func(ctx context.Context, nodeID string, msg *ClusterMessage) (*ClusterMessage, error)

type MetricsAware interface {
	// SetReplicatorMetrics injects the observability bag + peer tracker.
	// Idempotent. Calling with nil disables observation (defensive).
	SetReplicatorMetrics(bag *observability.ReplicationMetrics, tracker *PeerTracker)
}

type MultiRegionConfig struct {
	// RegionID identifies this region.
	// Environment: NORNICDB_CLUSTER_REGION_ID
	RegionID string

	// LocalCluster is the local Raft cluster configuration.
	LocalCluster RaftConfig

	// RemoteRegions are other regions to replicate to.
	// Environment: NORNICDB_CLUSTER_REMOTE_REGIONS (format: "region:host:port,...")
	RemoteRegions []RemoteRegionConfig

	// CrossRegionSyncMode controls cross-region replication mode.
	// Environment: NORNICDB_CLUSTER_CROSS_REGION_MODE
	CrossRegionSyncMode SyncMode

	// CrossRegionBatchSize is entries per cross-region batch.
	// Environment: NORNICDB_CLUSTER_CROSS_REGION_BATCH_SIZE
	CrossRegionBatchSize int

	// CrossRegionBatchTimeout is max time to wait for batch fill.
	// Environment: NORNICDB_CLUSTER_CROSS_REGION_BATCH_TIMEOUT
	CrossRegionBatchTimeout time.Duration

	// ConflictStrategy handles write conflicts between regions.
	// Environment: NORNICDB_CLUSTER_CONFLICT_STRATEGY
	ConflictStrategy string // "last_write_wins", "manual"
}

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

type NodePayload struct {
	ID              string
	Labels          []string
	Properties      map[string]any
	NamedEmbeddings map[string][]float32
	ChunkEmbeddings [][]float32
	CreatedAtUnixNs int64
	UpdatedAtUnixNs int64
}

type PeerConfig struct {
	// ID is the unique identifier for this peer.
	ID string

	// Addr is the network address (host:port).
	Addr string
}

type PeerConnection interface {
	// SendWALBatch sends a batch of WAL entries to the peer.
	SendWALBatch(ctx context.Context, entries []*WALEntry) (*WALBatchResponse, error)

	// SendHeartbeat sends a heartbeat to the peer.
	SendHeartbeat(ctx context.Context, req *HeartbeatRequest) (*HeartbeatResponse, error)

	// SendFence sends a fence request to prevent split-brain.
	SendFence(ctx context.Context, req *FenceRequest) (*FenceResponse, error)

	// SendPromote notifies the peer to prepare for promotion.
	SendPromote(ctx context.Context, req *PromoteRequest) (*PromoteResponse, error)

	// SendRaftVote sends a Raft vote request and returns the response.
	SendRaftVote(ctx context.Context, req *RaftVoteRequest) (*RaftVoteResponse, error)

	// SendRaftAppendEntries sends Raft append entries and returns the response.
	SendRaftAppendEntries(ctx context.Context, req *RaftAppendEntriesRequest) (*RaftAppendEntriesResponse, error)

	// Close closes the connection.
	Close() error

	// IsConnected returns true if the connection is active.
	IsConnected() bool
}

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

type PeerStatus struct {
	// ID is the peer's identifier.
	ID string `json:"id"`

	// Address is the peer's network address.
	Address string `json:"address"`

	// Healthy indicates if the peer is reachable.
	Healthy bool `json:"healthy"`

	// Lag is the replication lag for this peer.
	Lag uint64 `json:"lag,omitempty"`

	// LastContact is the last successful contact with this peer.
	LastContact time.Time `json:"last_contact,omitempty"`

	// State is the peer's current state.
	State string `json:"state,omitempty"`
}

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

type PromoteRequest struct {
	Reason string
}

type PromoteResponse struct {
	Ready bool
}

type RaftAppendEntriesRequest struct {
	Term         uint64          `json:"term"`
	LeaderID     string          `json:"leader_id"`
	LeaderAddr   string          `json:"leader_addr"`
	PrevLogIndex uint64          `json:"prev_log_index"`
	PrevLogTerm  uint64          `json:"prev_log_term"`
	Entries      []*RaftLogEntry `json:"entries"`
	LeaderCommit uint64          `json:"leader_commit"`
	CodecVersion uint32          `json:"codec_version,omitempty"`
}

type RaftAppendEntriesResponse struct {
	Term          uint64 `json:"term"`
	Success       bool   `json:"success"`
	MatchIndex    uint64 `json:"match_index"`
	ConflictIndex uint64 `json:"conflict_index,omitempty"`
	ConflictTerm  uint64 `json:"conflict_term,omitempty"`
	ResponderID   string `json:"responder_id"`
	CodecVersion  uint32 `json:"codec_version,omitempty"`
}

type RaftConfig struct {
	// ClusterID identifies the Raft cluster.
	// Environment: NORNICDB_CLUSTER_RAFT_CLUSTER_ID
	ClusterID string

	// Bootstrap initializes a new cluster (only on first node).
	// Environment: NORNICDB_CLUSTER_RAFT_BOOTSTRAP
	Bootstrap bool

	// Peers is the initial set of peer addresses.
	// Format: "node-id:addr,node-id:addr"
	// Environment: NORNICDB_CLUSTER_RAFT_PEERS
	Peers []PeerConfig

	// ElectionTimeout is the time before starting an election.
	// Environment: NORNICDB_CLUSTER_RAFT_ELECTION_TIMEOUT
	ElectionTimeout time.Duration

	// HeartbeatTimeout is the interval for leader heartbeats.
	// Environment: NORNICDB_CLUSTER_RAFT_HEARTBEAT_TIMEOUT
	HeartbeatTimeout time.Duration

	// LeaderLeaseTimeout is how long a leader maintains its lease.
	// Environment: NORNICDB_CLUSTER_RAFT_LEADER_LEASE_TIMEOUT
	LeaderLeaseTimeout time.Duration

	// SnapshotInterval is seconds between automatic snapshots.
	// Environment: NORNICDB_CLUSTER_RAFT_SNAPSHOT_INTERVAL
	SnapshotInterval int

	// SnapshotThreshold is log entries before triggering snapshot.
	// Environment: NORNICDB_CLUSTER_RAFT_SNAPSHOT_THRESHOLD
	SnapshotThreshold uint64

	// TrailingLogs is entries to retain after snapshot.
	// Environment: NORNICDB_CLUSTER_RAFT_TRAILING_LOGS
	TrailingLogs uint64

	// MaxAppendEntries is max entries per AppendEntries RPC.
	// Environment: NORNICDB_CLUSTER_RAFT_MAX_APPEND_ENTRIES
	MaxAppendEntries uint64

	// CommitTimeout is max time to wait for commit.
	// Environment: NORNICDB_CLUSTER_RAFT_COMMIT_TIMEOUT
	CommitTimeout time.Duration

	// MaxInflightLogs is max in-flight log entries for replication.
	// Environment: NORNICDB_CLUSTER_RAFT_MAX_INFLIGHT_LOGS
	MaxInflightLogs int

	// SnapshotRetain is number of snapshots to retain.
	// Environment: NORNICDB_CLUSTER_RAFT_SNAPSHOT_RETAIN
	SnapshotRetain int
}

type RaftLogEntry struct {
	Index   uint64   `json:"index"`
	Term    uint64   `json:"term"`
	Command *Command `json:"command"`
}

type RaftRPCMessage struct {
	Type    RaftRPCType `json:"type"`
	Payload []byte      `json:"payload"`
}

type RaftRPCType uint8

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

type RaftState int

type RaftVoteRequest struct {
	Term         uint64 `json:"term"`
	CandidateID  string `json:"candidate_id"`
	LastLogIndex uint64 `json:"last_log_index"`
	LastLogTerm  uint64 `json:"last_log_term"`
}

type RaftVoteResponse struct {
	Term        uint64 `json:"term"`
	VoteGranted bool   `json:"vote_granted"`
	VoterID     string `json:"voter_id"`
}

type RemoteRegionConfig struct {
	// RegionID identifies the remote region.
	RegionID string

	// Addrs are coordinator addresses for the remote region.
	Addrs []string

	// Priority for failover (lower = higher priority).
	Priority int
}

type ReplicatedEngine struct {
	storage.Engine
	// contains filtered or unexported fields
}

type ReplicationMode string

type Replicator interface {
	// Start initializes and starts the replicator.
	// This should be called after the storage engine is ready.
	Start(ctx context.Context) error

	// Apply applies a write command to the cluster.
	// Returns ErrNotLeader if this node cannot accept writes.
	// The command is replicated according to the replication mode.
	Apply(cmd *Command, timeout time.Duration) error

	// ApplyBatch applies multiple commands atomically.
	ApplyBatch(cmds []*Command, timeout time.Duration) error

	// IsLeader returns true if this node can accept writes.
	// For standalone mode, this always returns true.
	// For HA standby, this returns true only on primary.
	// For Raft, this returns true only on the Raft leader.
	IsLeader() bool

	// LeaderAddr returns the address of the current leader.
	// Returns empty string if unknown or in standalone mode.
	LeaderAddr() string

	// LeaderID returns the ID of the current leader.
	LeaderID() string

	// Health returns the current health status of the replicator.
	Health() *HealthStatus

	// WaitForLeader blocks until a leader is elected or context is cancelled.
	WaitForLeader(ctx context.Context) error

	// Shutdown gracefully shuts down the replicator.
	// This should be called before closing the storage engine.
	Shutdown() error

	// Mode returns the current replication mode.
	Mode() ReplicationMode

	// NodeID returns this node's unique identifier.
	NodeID() string
}

type SnapshotReader interface {
	Read(p []byte) (n int, err error)
}

type SnapshotWriter interface {
	Write(p []byte) (n int, err error)
}

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

type Storage interface {
	// ApplyCommand applies a replicated command to storage.
	ApplyCommand(cmd *Command) error

	// GetWALPosition returns the current WAL position.
	GetWALPosition() (uint64, error)

	// GetWALEntries returns WAL entries starting from the given position.
	GetWALEntries(fromPosition uint64, maxEntries int) ([]*WALEntry, error)

	// WriteSnapshot writes a full snapshot to the given writer.
	WriteSnapshot(w SnapshotWriter) error

	// RestoreSnapshot restores state from a snapshot.
	RestoreSnapshot(r SnapshotReader) error
}

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

type SyncMode string

type TLSConfig struct {
	// Enabled enables TLS for all replication connections.
	// STRONGLY RECOMMENDED for production.
	// Environment: NORNICDB_CLUSTER_TLS_ENABLED
	Enabled bool

	// CertFile is path to the server certificate (PEM format).
	// Environment: NORNICDB_CLUSTER_TLS_CERT_FILE
	CertFile string

	// KeyFile is path to the server private key (PEM format).
	// Environment: NORNICDB_CLUSTER_TLS_KEY_FILE
	KeyFile string

	// CAFile is path to the CA certificate for client verification (mTLS).
	// If set, client certificates will be required and verified.
	// Environment: NORNICDB_CLUSTER_TLS_CA_FILE
	CAFile string

	// VerifyClient requires client certificate verification (mTLS).
	// Should be true in production for mutual authentication.
	// Environment: NORNICDB_CLUSTER_TLS_VERIFY_CLIENT
	VerifyClient bool

	// InsecureSkipVerify skips server certificate verification.
	// WARNING: Only use for testing. Never in production!
	// Environment: NORNICDB_CLUSTER_TLS_INSECURE_SKIP_VERIFY
	InsecureSkipVerify bool

	// ServerName is the expected server name for certificate verification.
	// Environment: NORNICDB_CLUSTER_TLS_SERVER_NAME
	ServerName string

	// MinVersion is the minimum TLS version (default: TLS 1.2).
	// Environment: NORNICDB_CLUSTER_TLS_MIN_VERSION
	MinVersion string // "1.2" or "1.3"

	// CipherSuites restricts allowed cipher suites (optional).
	// Leave empty to use secure defaults.
	// Environment: NORNICDB_CLUSTER_TLS_CIPHER_SUITES
	CipherSuites []string
}

type Transport interface {
	// Connect establishes a connection to a peer.
	Connect(ctx context.Context, addr string) (PeerConnection, error)

	// Listen starts accepting connections from peers.
	Listen(ctx context.Context, addr string, handler ConnectionHandler) error

	// Close shuts down the transport.
	Close() error
}

type VoteRequest struct {
	Term         uint64 `json:"term"`
	CandidateID  string `json:"candidate_id"`
	LastLogIndex uint64 `json:"last_log_index"`
	LastLogTerm  uint64 `json:"last_log_term"`
}

type VoteResponse struct {
	Term        uint64 `json:"term"`
	VoteGranted bool   `json:"vote_granted"`
	VoterID     string `json:"voter_id"`
}

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

type WALBatchResponse struct {
	AckedPosition    uint64
	ReceivedPosition uint64
}

type WALEntry struct {
	// Position is the unique, monotonically increasing position.
	Position uint64

	// Timestamp when the entry was created.
	Timestamp int64

	// Command is the replicated command.
	Command *Command
}

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