serverconn

type AckState = mailboxconn.AckState

type ArkVersionGetInfoClient interface {
	// GetInfo returns the operator's info, including its Ark protocol
	// version selection and policies.
	GetInfo(ctx context.Context, in *arkrpc.GetInfoRequest,
		opts ...grpc.CallOption) (*arkrpc.GetInfoResponse, error)
}

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

type ConnectorConfig struct {
	// Edge is the gRPC client for the remote mailbox edge service,
	// providing Send, Pull, and AckUpTo operations.
	Edge mailboxpb.MailboxServiceClient

	// LocalMailboxID is this client's mailbox identifier. Inbound
	// envelopes are pulled from this mailbox, and it is set as the
	// sender on outbound envelopes.
	LocalMailboxID string

	// RemoteMailboxID is the remote server's mailbox identifier. Outbound
	// envelopes are addressed to this mailbox.
	RemoteMailboxID string

	// MailboxProtocolVersion is the immutable mailbox transport version
	// stamped on every outbound envelope. It defines envelope framing and
	// delivery semantics and is a stable code constant
	// (mailboxpb.MailboxProtocolVersionV1), not a negotiated value.
	MailboxProtocolVersion uint32

	// ArkProtocolVersion is the immutable Ark protocol version negotiated
	// through the direct GetInfo bootstrap RPC and bound to this runtime
	// for its lifetime. It is stamped on every outbound envelope and
	// validated on every inbound envelope. Runtime construction rejects a
	// zero value: a runtime must always carry an explicit Ark version.
	ArkProtocolVersion uint32

	// Dispatchers maps (service, method) pairs to envelope dispatchers.
	// The ingress loop uses this table to route KIND_REQUEST and
	// KIND_EVENT envelopes to the correct local actor via ServiceKey.
	Dispatchers map[mailboxrpc.ServiceMethod]EnvelopeDispatcher

	// NonTxRoutes marks the subset of Dispatchers whose closure serves an
	// inbound KIND_REQUEST end to end -- it runs the local handler and
	// then puts the KIND_RESPONSE envelope back on the wire with
	// Edge.Send -- instead of enqueuing into a local durable mailbox.
	// Those dispatchers block on a network round trip, so the ingress
	// loop runs them BEFORE it opens the folded write transaction. A
	// marked route left unmarked would hold the database writer across
	// that round trip: on SQLite, which production opens with
	// _txlock=immediate, that is the single global writer lock and every
	// other writer in the process stalls behind it; on Postgres, where
	// db.BaseDB.BeginTx pins SERIALIZABLE, it is a multi-second SSI
	// conflict window and a source of 40001 aborts.
	//
	// Marking is opt-in because an EnvelopeDispatcher is an opaque
	// closure: only the wiring layer knows whether a given route
	// terminates in a durable enqueue or in blocking IO. A route is only
	// hoisted out of the transaction when it is listed here AND the
	// envelope is a KIND_REQUEST, so a durable event or response route
	// can never be hoisted by accident. Any new route whose dispatcher
	// performs IO rather than a durable enqueue MUST be listed here.
	//
	// The mark only ever errs in one direction. Leaving a route out costs
	// the stall described above, which is what the code did before this
	// field existed. Marking a route whose dispatcher is actually a
	// durable Tell is the expensive mistake: the enqueue would commit on
	// its own ahead of the cursor, and because the ingress path
	// propagates no outbox ID, the re-pull after a crash in that window
	// enqueues a second copy under a fresh UUIDv7 that
	// EnqueueMailboxMessage's ON CONFLICT (id) DO NOTHING cannot
	// collapse. That turns exactly-once local delivery into a duplicate
	// the receiving actor never sees coming, which is why the mark and
	// the dispatcher are registered together.
	NonTxRoutes RouteSet

	// Store is the delivery store used by both the durable actor runtime
	// (for inbox persistence) and checkpoint persistence (for ack
	// watermark state). This is the single durability source of truth.
	Store actor.DeliveryStore

	// Codec handles TLV serialization of ServerConnMsg types for the
	// durable actor mailbox.
	Codec *actor.MessageCodec

	// EgressWorkers is how many concurrent worker loops drain the durable
	// egress mailbox. Values <= 1 keep the historical single-sender
	// behavior; values greater than 1 run a competing-consumer pool so
	// independent outbound sends (e.g. from the round and out-of-round
	// actors) proceed in parallel instead of serializing behind one
	// in-flight Edge.Send. Per-session ordering is preserved because each
	// SendClientEventRequest carries the inner message's CorrelationKey,
	// which the durable mailbox claims in per-key FIFO order. The single
	// ingress puller is unaffected -- only the egress sender fans out.
	EgressWorkers int

	// DurableUnaryBuilder constructs proof-gated unary request bodies for
	// transport-native durable unary messages such as indexer script-scope
	// queries. When nil, those message types are rejected.
	DurableUnaryBuilder DurableUnaryRequestBuilder

	// Log is an optional logger for this connector instance.
	Log fn.Option[btclog.Logger]

	// OnIncompatible is an optional callback invoked exactly once when the
	// connector transitions to a terminal incompatible state after the
	// first permanent version error. It receives the typed status error so
	// the caller can surface structured compatibility details. It must not
	// block; the connector invokes it inline on the transition.
	OnIncompatible func(*mailboxconn.StatusError)

	// PullMaxEnvelopes bounds the number of envelopes returned per Pull
	// call.
	PullMaxEnvelopes uint32

	// PullWaitTimeout is the long-poll timeout for Pull calls. The remote
	// edge will hold the connection open for this duration before
	// returning an empty response.
	PullWaitTimeout time.Duration

	// RetryBaseDelay is the base delay for exponential backoff on
	// transient failures (pull, ack, dispatch).
	RetryBaseDelay time.Duration

	// RetryMaxDelay caps the exponential backoff delay.
	RetryMaxDelay time.Duration

	// ResponseWaiterTTL bounds how long a response waiter (or buffered
	// early response) is retained before stale cleanup.
	ResponseWaiterTTL time.Duration

	// MaxInFlightUnary caps how many unary RPCs this client may have
	// outstanding against the remote mailbox at once. A non-positive value
	// selects DefaultMaxInFlightUnary.
	//
	// What it counts is live UnaryFacade waiters in the response registry,
	// so it bounds the live unary path and nothing else. The durable
	// egress paths (SendUnaryRequest, SendRPCRequest) do not register an
	// in-memory waiter and are not gated here, which is deliberate: their
	// responses fall through to durable route dispatch when no waiter is
	// left, so an abandoned one is redelivered rather than discarded, and
	// it is the discarding that this cap exists to bound.
	//
	// The mailbox protocol has no cancel envelope, so a caller that gives
	// up on its deadline cannot recall the request: the operator runs it
	// to completion and delivers a response with no waiter left to receive
	// it. Capping the outstanding set is the only client-side bound on how
	// much of that abandoned work one client can queue. Exceeding it fails
	// the send locally with ResourceExhausted, which is the same fast-fail
	// signal a shedding operator sends, so callers back off on it without
	// needing to know where it came from.
	//
	// The cap is per connector rather than per subsystem, so it is shared
	// by every unary caller in the daemon. One subsystem that saturates it
	// therefore fails unrelated unary RPCs daemon-wide until its requests
	// drain. That is the intent: the resource being protected is the
	// operator's queue, which is also shared, and a per-subsystem cap
	// would let N subsystems each queue their own N without any of them
	// noticing. The cost is that the loudest caller can starve the quiet
	// ones, which is why the default sits well above any legitimate burst.
	MaxInFlightUnary int

	// HeartbeatInterval is the interval between heartbeat sends to
	// the server. A zero or negative value uses
	// DefaultHeartbeatInterval (30 s). The server's staleness
	// threshold should be at least 2× this interval.
	HeartbeatInterval time.Duration

	// AuthSignature is the Schnorr signature proving the client
	// holds the private key for its pubkey-derived mailbox ID.
	// When non-nil, it is serialized as hex and included as the
	// x-mailbox-auth-sig header on every outbound envelope. The
	// server verifies this signature during client registration.
	AuthSignature *schnorr.Signature

	// TLSBindSignature is the Schnorr signature binding the
	// client's secp256k1 mailbox identity to the SPKI bytes of
	// the TLS leaf certificate this connector dialed with. When
	// non-nil, it is serialized as hex and included as the
	// x-mailbox-tls-bind-sig header on every outbound envelope.
	// The server uses this on first-contact Send to verify the
	// TLS leaf it observes is the one the verified identity
	// signed over, closing the registration-time replay window
	// described in issue #448.
	TLSBindSignature *schnorr.Signature
	// contains filtered or unexported fields
}

type CorrelationID = mailboxconn.CorrelationID

type DispatcherMap = map[mailboxrpc.ServiceMethod]EnvelopeDispatcher

type DurableUnaryQuery interface {
	ServerConnMsg

	// BuildBody constructs the proto request body and returns stable
	// identity bytes for deterministic ID derivation.
	BuildBody(ctx context.Context, builder DurableUnaryRequestBuilder) (
		body *anypb.Any, stableBytes []byte, err error)

	// QueryCorrelationID returns the correlation ID for response routing.
	QueryCorrelationID() string

	// QueryMsgID returns the caller-provided msg ID (empty = auto-derive).
	QueryMsgID() string

	// QueryIdempotencyKey returns the caller-provided idempotency key
	// (empty = auto-derive).
	QueryIdempotencyKey() string

	// ServiceMethod returns the mailbox route for this query.
	ServiceMethod() mailboxrpc.ServiceMethod
}

type DurableUnaryRequestBuilder interface {
	// BuildListOORRecipientEventsByScriptRequest builds the
	// ListOORRecipientEventsByScript unary request for the given taproot
	// output script and monotonic cursor.
	BuildListOORRecipientEventsByScriptRequest(ctx context.Context,
		pkScript []byte, afterEventID uint64,
		limit uint32) (proto.Message, error)

	// BuildListVTXOsByScriptsRequest builds the ListVTXOsByScripts unary
	// request for the given taproot output scripts and cursor.
	BuildListVTXOsByScriptsRequest(ctx context.Context, pkScripts [][]byte,
		afterCursor []byte, limit uint32) (proto.Message, error)
}

type EnvelopeDispatcher func(
	ctx context.Context, env *mailboxpb.Envelope,
) error

type EnvelopeRouteConfig[M actor.Message, R any] struct {
	// Service is the fully-qualified protobuf service name.
	Service string

	// Method is the protobuf method name.
	Method string

	// NewEvent must return a fresh zero-value proto.Message for
	// the expected request or response type.
	NewEvent func() proto.Message

	// Key is the ServiceKey for the target actor.
	Key actor.ServiceKey[M, R]

	// Adapt converts the deserialized proto and envelope metadata into the
	// actor message type M. Return ErrEnvelopeHandled when the envelope was
	// intentionally consumed without actor delivery.
	Adapt func(*mailboxpb.Envelope, proto.Message) (M, error)

	// ResolveKey optionally maps an adapted message to a more specific
	// service key (e.g. a per-session durable mailbox). When the resolved
	// key has a live registration, the message is told straight to that
	// actor, skipping the static Key hop; otherwise dispatch falls back to
	// Key, which owns admission for actors that do not exist yet. Return
	// false to always use Key for this message.
	ResolveKey func(M) (actor.ServiceKey[M, R], bool)
}

type EventRouteConfig[M actor.Message, R any] struct {
	// Service is the fully-qualified protobuf service name that appears
	// in the inbound envelope's RPC metadata
	// (e.g., "hellotest.v1.RoundService").
	Service string

	// Method is the protobuf method name (e.g., "RoundStarted").
	Method string

	// NewEvent must return a fresh zero-value proto.Message for the
	// expected event type. It is called once per delivered envelope to
	// provide the unmarshal target.
	NewEvent func() proto.Message

	// Key is the ServiceKey for the target durable actor. The router
	// calls key.Ref(system).Tell(ctx, msg) for each dispatched event,
	// which persists the message to the actor's durable mailbox before
	// returning nil.
	Key actor.ServiceKey[M, R]

	// Adapt converts the deserialized proto.Message to the actor message
	// type M. Return an error to reject envelopes whose body cannot be
	// converted.
	Adapt func(proto.Message) (M, error)

	// ResolveKey optionally maps an adapted message to a more specific
	// service key (e.g. a per-session durable mailbox). When the resolved
	// key has a live registration, the message is told straight to that
	// actor, skipping the static Key hop; otherwise dispatch falls back to
	// Key, which owns admission for actors that do not exist yet. Return
	// false to always use Key for this message.
	ResolveKey func(M) (actor.ServiceKey[M, R], bool)
}

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

type IdempotencyKey = mailboxconn.IdempotencyKey

type InboundActorMessage interface {
	actor.Message
	InboundServerMessage
}

type InboundEventRouteConfig[M InboundActorMessage, R any] struct {
	// Service is the fully-qualified protobuf service name
	// (e.g., "hellotest.v1.HelloService").
	Service string

	// Method is the protobuf method name (e.g., "HelloStarted").
	Method string

	// Key is the ServiceKey for the target durable actor.
	Key actor.ServiceKey[M, R]

	// NewEvent must return a fresh zero-value proto.Message for the
	// expected event type.
	NewEvent func() proto.Message

	// NewMsg must return a non-nil zero-value M. FromProto is called
	// on the returned value to populate it from the deserialized event.
	NewMsg func() M
}

type InboundServerMessage interface {
	// FromProto populates the receiver from a server-pushed proto message.
	// It is called by the EventRouter dispatch closure after the envelope
	// body has been unmarshaled into the expected proto type. Return an
	// error to reject events whose proto fields cannot be converted.
	FromProto(proto.Message) error
}

type MailboxAuthSigner func(context.Context, string) (string, error)

type RouteSet = map[mailboxrpc.ServiceMethod]struct{}

type Runtime struct {
	*actor.DurableActor[ServerConnMsg, ServerConnResp]
	// contains filtered or unexported fields
}

type SendClientEventRequest struct {
	actor.BaseMessage

	// Message is the client FSM outbox message to send to the server.
	// It must implement the ServerMessage interface which provides the
	// ToProto() method for conversion to protobuf.
	Message ServerMessage

	// MsgID uniquely identifies this send attempt. When this request is
	// durably persisted and later retried, the same MsgID is reused.
	MsgID string

	// IdempotencyKey identifies the semantic operation for remote dedupe.
	// Retries of the same persisted request must reuse this key.
	IdempotencyKey string

	// Service is the fully-qualified protobuf service name for mailbox
	// routing (e.g. "round.v1.RoundService"). Populated from
	// ServerMessage.ServiceMethod() at send time, persisted in TLV for
	// crash-safe replay.
	Service string

	// Method is the RPC method name for mailbox routing (e.g.
	// "JoinRound"). Populated from ServerMessage.ServiceMethod() at
	// send time, persisted in TLV for crash-safe replay.
	Method string
	// contains filtered or unexported fields
}

type SendClientEventResponse struct {
	actor.BaseMessage

	// Success indicates whether the send operation succeeded.
	Success bool

	// Error contains the error message if the send failed.
	Error string
}

type SendListOORRecipientEventsByScriptRequest struct {
	actor.BaseMessage

	// PkScript is the taproot output script to query.
	PkScript []byte

	// AfterEventID is the exclusive lower bound for the recipient-event
	// stream cursor.
	AfterEventID uint64

	// Limit is the maximum number of recipient events to return.
	Limit uint32

	// CorrelationID links this request to the eventual KIND_RESPONSE.
	CorrelationID string

	// MsgID uniquely identifies this send attempt. Retries of the same
	// persisted request must reuse this ID.
	MsgID string

	// IdempotencyKey identifies the semantic operation for remote dedupe.
	IdempotencyKey string
}

type SendListVTXOsByScriptsRequest struct {
	actor.BaseMessage

	// PkScripts are the taproot output scripts to query.
	PkScripts [][]byte

	// AfterCursor is the exclusive lower bound for the VTXO query cursor.
	AfterCursor []byte

	// Limit is the maximum number of VTXOs to return.
	Limit uint32

	// CorrelationID links this request to the eventual KIND_RESPONSE.
	CorrelationID string

	// MsgID uniquely identifies this send attempt. Retries of the same
	// persisted request must reuse this ID.
	MsgID string

	// IdempotencyKey identifies the semantic operation for remote dedupe.
	IdempotencyKey string
}

type SendRPCRequest struct {
	actor.BaseMessage

	// Envelope is the pre-built mailbox envelope ready for sending.
	Envelope *mailboxpb.Envelope
}

type SendRPCResponse struct {
	actor.BaseMessage

	// Success indicates whether the send operation succeeded.
	Success bool

	// Error contains the error message if the send failed.
	Error string
}

type SendUnaryRequest struct {
	actor.BaseMessage

	// Body is the request payload wrapped as Any.
	Body *anypb.Any

	// MsgID uniquely identifies this send attempt. Retries of the same
	// persisted request must reuse this ID.
	MsgID string

	// IdempotencyKey identifies the semantic operation for remote dedupe.
	IdempotencyKey string

	// Service is the fully-qualified protobuf service name.
	Service string

	// Method is the RPC method name.
	Method string

	// CorrelationID links this request to the eventual KIND_RESPONSE.
	CorrelationID string
}

type ServerConnMsg interface {
	actor.TLVMessage
	// contains filtered or unexported methods
}

type ServerConnResp interface {
	actor.Message
	// contains filtered or unexported methods
}

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

type ServerMessage interface {
	// ToProto converts the message to a protobuf message that can be
	// sent over gRPC. An error is returned if serialization of any
	// embedded field (e.g. signatures, transactions) fails.
	ToProto() fn.Result[proto.Message]

	// ServiceMethod returns the fully-qualified protobuf service and
	// method names used for mailbox envelope routing (e.g.
	// Service: "round.v1.RoundService", Method: "JoinRound").
	ServiceMethod() mailboxrpc.ServiceMethod
}

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