network

type ApplyFunc func(Frame) error

type ApplyKey [48]byte

type Archive interface {
	Append(ctx context.Context, shardID string, seq uint64, frame []byte) error
	Range(ctx context.Context, shardID string, fromSeq, toSeq uint64) (iter.Seq2[Frame, error], error)
	Close() error
}

type ArchiveConfig struct {
	// URL is the backend destination: s3://bucket/prefix or
	// gs://bucket/prefix. Prefix is optional; if absent, objects land
	// at the bucket root.
	URL string

	// SegmentTargetBytes is the size at which an in-memory segment
	// flushes. Defaults to 8 MiB.
	SegmentTargetBytes int

	// FlushInterval is the max time a partial segment may linger in
	// memory before being flushed. Defaults to 10 s.
	FlushInterval time.Duration

	// RetryDeadline bounds transient retry attempts for a single
	// segment flush. Defaults to 5 minutes. After it elapses, the
	// segment is retained for the next flush cycle (never dropped).
	RetryDeadline time.Duration

	// SigningKey is the Ed25519 private key used to sign every segment
	// we write. Production callers MUST inject a KMS-held key; when
	// unset (tests, dev), the archive writer auto-generates a transient
	// key — fine in-process, useless across restarts.
	SigningKey ed25519.PrivateKey

	// TrustedSegmentKeys are Ed25519 public keys whose segments the
	// reader accepts. The local SigningKey's public half is always
	// trusted; additional keys cover rotation (PITR against archives
	// written under a now-retired key).
	TrustedSegmentKeys []ed25519.PublicKey

	// BacklogMaxBytes caps the per-shard in-memory backlog of encoded
	// segments waiting to upload. Once exceeded, the oldest segments
	// are dropped (counted on IncDrops). Zero = unbounded (dev only);
	// production callers MUST set this to a sane ceiling.
	BacklogMaxBytes int

	// BacklogMaxSegments caps the per-shard backlog by segment count.
	// Either limit firing triggers the drop path. Zero = unbounded.
	BacklogMaxSegments int
}

type ArchiveMetrics struct {
	// SetLagBytes reports the total size of buffered, not-yet-flushed
	// frames across all shards. Surfaced as base_archive_lag_bytes.
	SetLagBytes func(bytes int64)
	// IncFailures increments a failures counter whenever a segment
	// exhausts its retry deadline. The segment is re-buffered unless
	// the backlog cap is exceeded.
	IncFailures func()
	// IncDrops increments a drop counter whenever the backlog cap
	// sheds the oldest segment. Liveness-over-durability — operators
	// should page on this.
	IncDrops func()
}

type Config struct {
	// Enabled is true iff BASE_NETWORK=quasar.
	Enabled bool

	// ShardKey names the identity carried by requests (JWT claim or header).
	// Required when Enabled.
	ShardKey string

	// Replication is the number of members holding each shard. 1 = standalone
	// DAG (durability via archive), 2 = pair, 3+ = Byzantine-safe quorum.
	Replication int

	// Peers is the static seed list. In k8s these are pod-ordinal DNS names
	// emitted by the operator; in compose they are static service names.
	// host:port form, p2p port not HTTP port.
	Peers []string

	// NodeID is the local member identity. Defaults to $HOSTNAME; overridable
	// via BASE_NODE_ID for tests and compose.
	NodeID string

	// Role is "validator" (default) or "archive". Archive nodes don't vote;
	// they subscribe to finalized frames and append to cold storage.
	Role NodeRole

	// Archive is the cold-storage URL or "off". s3://bucket/prefix,
	// gs://bucket/prefix, file://path (dev), off.
	Archive string

	// ListenHTTP is the Base HTTP listen address. Used only for the
	// /-/base/members endpoint by the Gateway; main HTTP comes from core.
	ListenHTTP string

	// ListenP2P is the Quasar peer-to-peer port.
	ListenP2P string

	// TLS is the mTLS config for the Quasar p2p transport (R5). When
	// unset the transport runs without authentication — only acceptable
	// in single-node dev and tests. Production callers inject certs via
	// the KMS plugin (base/plugins/kms) or the operator-emitted dev CA.
	// See transport_tls.go for the pinning rules.
	TLS *TLSConfig
}

type Envelope struct {
	ShardID string
	Frame   Frame
}

type Frame struct {
	ShardID   string
	Seq       uint64
	PrevSeq   uint64
	Timestamp int64
	Salt      [16]byte
	Payload   []byte
	Cksm      [32]byte
	Bytes     []byte
}

type HookRegisterer interface {
	RegisterCommitHook(func() int32)
}

type Membership interface {
	// Members returns the current sorted member list. Includes self.
	// Never nil; a singleton returns a 1-element slice.
	Members() []NodeID

	// Watch returns a channel that emits the member list on every
	// change. The first value is delivered immediately on subscribe.
	// The channel closes when ctx is cancelled.
	Watch(ctx context.Context) <-chan []NodeID

	// Close releases any resources. Safe to call multiple times.
	Close() error
}

type Metrics struct {
	Shards           prometheus.Counter
	ActiveShards     prometheus.Gauge
	WALLagBytes      prometheus.Gauge
	HotShards        prometheus.Gauge
	LeaseContentions prometheus.Counter
	ArchiveLagBytes  prometheus.Gauge
	// ArchiveFailures counts segment flushes that exhausted their
	// retry deadline. Incremented once per failure regardless of
	// re-buffer outcome.
	ArchiveFailures prometheus.Counter
	// ArchiveDrops counts segments shed by the per-shard backlog cap
	// (R6). Under a healthy backend this stays at zero; non-zero is a
	// pageable condition — we're losing archive frames to keep the pod
	// alive.
	ArchiveDrops prometheus.Counter

	FramesSubmitted prometheus.Counter
	FramesIngested  prometheus.Counter
	FramesFinalized prometheus.Counter
	FramesDuplicate prometheus.Counter
	FramesInvalid   prometheus.Counter
	// FramesRejectedShardMismatch counts frames dropped because the
	// Envelope's routed shard disagreed with the Frame's internal
	// shardID (R1 probe). Under healthy operation this stays at zero.
	FramesRejectedShardMismatch prometheus.Counter
	// FramesRejectedSeqGap counts frames whose height != prevHeight+1
	// (R2). The apply path never bumps localSeq from these.
	FramesRejectedSeqGap prometheus.Counter

	ApplyErrors   prometheus.Counter
	WALHookErrors prometheus.Counter
	WALBytes      prometheus.Counter

	// MembershipSize is the live member count as reported by the
	// Membership watcher. Dashboards alert on unexpected drops
	// (scale-down events show up here before the transport notices).
	MembershipSize prometheus.Gauge
}

type Network interface {
	Enabled() bool

	Start(ctx context.Context) error
	Stop(ctx context.Context) error

	// InstallWALHook wires the commit hook on a raw SQLite driver connection
	// for the given shard. The hook captures the committed frame, signs it,
	// and submits it to the shard's Quasar engine. Apply-on-finalize is
	// idempotent by (salt, cksm).
	InstallWALHook(rawConn any, shardID string) error

	// WriterFor returns the current writer endpoint for shardID and whether
	// it is the local pod. Gateway uses this for request routing.
	WriterFor(shardID string) (endpoint string, local bool)

	// MembersFor returns all replica endpoints for shardID.
	MembersFor(shardID string) []string

	// Metrics exposes the Prom collectors. Callers register via their own
	// registry; we never touch the global default.
	Metrics() *Metrics
}

type NodeID string

type NodeRole string

type Resolver interface {
	LookupHost(ctx context.Context, host string) ([]string, error)
}

type Shard struct {
	ID        string
	Members   []NodeID
	Threshold int
	// contains filtered or unexported fields
}

type TLSConfig struct {
	// CACerts are the PEM-encoded CA certificates the transport trusts
	// for peer certs. Supplied by the operator from the Base-network
	// Secret (KMS-issued) or the self-signed dev CA.
	CACerts []byte

	// ServerCert / ServerKey are the local pod's TLS identity. Both
	// PEM-encoded. Production: issued by KMS; dev: self-signed.
	ServerCert []byte
	ServerKey  []byte

	// ClientCert / ClientKey are optional — when the transport opens
	// outbound connections it presents these. Typically the same as
	// the server cert (pod identity is one cert per pod).
	ClientCert []byte
	ClientKey  []byte

	// AllowedSANs is the SAN allowlist: the pod DNS names from
	// BASE_PEERS. Any peer cert whose DNSNames slice does not include
	// one of these is rejected. Empty slice + non-nil CACerts = "trust
	// any cert chained to CA" (dev-only fallback).
	AllowedSANs []string
}

type Transport interface {
	// Start begins delivering inbound envelopes to recv. It must be
	// idempotent-on-stop (Stop may be called after Start errors).
	Start(ctx context.Context, recv func(Envelope)) error

	// Publish fans out env to every peer in the local node's router view.
	// Best-effort: peers discover missed frames via Quasar's DAG sync on
	// reconnect. Implementations should not block for slow peers.
	Publish(env Envelope) error

	// Stop releases transport resources. Safe to call multiple times.
	Stop(ctx context.Context) error
}