daemonapi

type ConnReadWriter interface {
	Read(p []byte) (int, error)
	Write(p []byte) (int, error)
	Close() error
}

type Connection interface {
	// Info returns an endpoint snapshot. The returned struct is a
	// value copy, so plugins may hold it across goroutines.
	Info() ConnectionInfo
}

type ConnectionInfo struct {
	LocalAddr  protocol.Addr
	LocalPort  uint16
	RemoteAddr protocol.Addr
	RemotePort uint16
}

type Daemon interface {

	// Start brings the daemon online. Returns when the listeners are
	// bound and the daemon is ready to accept traffic, or with an
	// error if any step of bootstrap fails.
	Start() error

	// Stop drains in-flight work and tears down the daemon. Idempotent;
	// safe to call from a signal handler.
	Stop() error

	// NodeID returns this daemon's stable 32-bit node ID. 0 when the
	// identity has not been loaded yet.
	NodeID() uint32

	// Identity returns the daemon's Ed25519 keypair holder. Returns
	// nil when the daemon was started without an identity file
	// (in-memory tests).
	Identity() *crypto.Identity

	// IdentityPath returns the on-disk path to the identity file.
	// Empty when running in-memory.
	IdentityPath() string

	// Sign signs the message with the local Ed25519 private key.
	// Returns nil when no identity is loaded.
	Sign(msg []byte) []byte

	// AdminToken returns the local admin token used to authenticate
	// privileged registry RPCs. Empty when not configured.
	AdminToken() string

	// TrustAutoApprove reports whether the daemon was started with
	// the auto-approve flag set. Plugins gating user-visible decisions
	// on this flag (handshake auto-accept) read it once at Init.
	TrustAutoApprove() bool

	// Addr returns the daemon's pilot-network address. Stable for
	// the life of the daemon process.
	Addr() protocol.Addr

	// DialConnection opens an outbound stream to (dstAddr, dstPort)
	// and returns an opaque Connection handle. The handle is passed
	// back to SendData, CloseConnection, NewConnReadWriter, etc.
	DialConnection(dstAddr protocol.Addr, dstPort uint16) (Connection, error)

	// DialConnectionContext is DialConnection with a deadline. The
	// context's Done channel cancels the dial.
	DialConnectionContext(ctx context.Context, dstAddr protocol.Addr, dstPort uint16) (Connection, error)

	// SendData writes the byte slice to the stream connection.
	// Blocks until the data is queued for transmission.
	SendData(conn Connection, data []byte) error

	// SendDatagram sends an unconnected (UDP-shaped) payload to
	// (dstAddr, dstPort). Best-effort, no retransmission.
	SendDatagram(dstAddr protocol.Addr, dstPort uint16, data []byte) error

	// CloseConnection tears down the connection. Idempotent.
	CloseConnection(conn Connection)

	// NewConnReadWriter wraps a stream Connection as a net.Conn-style
	// adapter. Plugins that need read/write semantics use this; the
	// daemon retains ownership of the underlying connection state.
	NewConnReadWriter(conn Connection) ConnReadWriter

	// Ports returns the daemon's port allocator. Opaque to most
	// plugins; usually handed off to other plugins (e.g. handshake)
	// that bind well-known ports through it.
	Ports() PortAllocator

	// Tunnels returns the daemon's tunnel registry. Opaque to most
	// plugins.
	Tunnels() TunnelRegistry

	// RegistryClient returns the L8 registry-side-channel client.
	// nil when the daemon is running without a registry connection.
	RegistryClient() *registry.Client

	// RegConnListNodes is the privileged list_nodes RPC, used by the
	// policy plugin to enumerate per-network members.
	RegConnListNodes(netID uint16, token string) (map[string]any, error)

	// SetMemberTags updates the local node's per-network tag list
	// via the registry.
	SetMemberTags(netID uint16, tags []string)

	// PublishEvent is the bus.Publish wrapper, exposed at top level
	// because plugins commonly publish without holding a Bus reference.
	PublishEvent(topic string, payload map[string]any)

	// Bus returns the in-process event bus for plugins that subscribe.
	Bus() EventBus

	// GetTrustChecker returns the currently-registered trust checker
	// (typically the trustedagents plugin). Returns nil when no
	// checker is wired.
	GetTrustChecker() TrustChecker

	// RegisterTrustChecker installs the given checker as the daemon's
	// trust authority. Called once at startup by the trustedagents
	// plugin via the runtime adapter.
	RegisterTrustChecker(tc TrustChecker)

	// HandshakeService returns the currently-registered handshake
	// service. Returns nil when no handshake plugin is wired (tests
	// that bypass plugins).
	HandshakeService() HandshakeService

	// RegisterHandshakeService installs the handshake plugin's
	// service. Called once at startup via the runtime adapter.
	RegisterHandshakeService(svc HandshakeService)

	// TrustedPeers proxies through to HandshakeService().TrustedPeers().
	// Returns nil when no handshake plugin is wired.
	TrustedPeers() []HandshakeTrustRecord

	// HandshakeRevokeTrust proxies through to HandshakeService().RevokeTrust.
	HandshakeRevokeTrust(nodeID uint32) error

	// HandshakeSendRequest proxies through to HandshakeService().SendRequest.
	HandshakeSendRequest(nodeID uint32, reason string) error

	// RegisterPolicyManager installs the policy plugin's manager.
	RegisterPolicyManager(pm PolicyManager)

	// SetWebhookURL hot-swaps the active webhook URL on the registered
	// webhook plugin. No-op when no plugin is registered.
	SetWebhookURL(url string)

	// RegisterWebhookManager installs the webhook plugin's manager.
	RegisterWebhookManager(wm WebhookManager)
}

type Event struct {
	Topic   string
	NodeID  uint32
	Time    time.Time
	Payload map[string]any
}

type EventBus interface {
	// Publish emits the topic + payload to every subscriber whose
	// pattern matches the topic. Non-blocking; events may be dropped
	// on per-subscriber backpressure.
	Publish(topic string, payload map[string]any)

	// Subscribe registers a pattern-matching subscriber and returns
	// the receive channel plus a cancellation closure. Calling the
	// closure stops delivery and drains the buffer.
	Subscribe(pattern string) (<-chan Event, func())
}

type Factory func() Plugin

type HandshakePendingRecord struct {
	NodeID        uint32
	PublicKey     string
	Justification string
	ReceivedAt    time.Time
}

type HandshakeService interface {
	IsTrusted(nodeID uint32) bool
	TrustedPeers() []HandshakeTrustRecord
	PendingRequests() []HandshakePendingRecord
	PendingCount() int
	SendRequest(peerNodeID uint32, justification string) error
	ApproveHandshake(peerNodeID uint32) error
	RejectHandshake(peerNodeID uint32, reason string) error
	RevokeTrust(peerNodeID uint32) error

	// WaitForTrust blocks until the peer transitions to trusted, or
	// the timeout elapses. Returns true if trust was granted in
	// time. Wired through the daemon so callers (typically pilotctl
	// before a first send to a trusted-list peer) can block
	// bidirectional operations on trust establishment instead of
	// racing the data send against the handshake reply.
	WaitForTrust(peerNodeID uint32, timeout time.Duration) bool

	// ProcessRelayedRequest / ProcessRelayedApproval /
	// ProcessRelayedRejection are invoked from the daemon's relay
	// poller after parsing the registry-inbox payload.
	ProcessRelayedRequest(fromNodeID uint32, justification string)
	ProcessRelayedApproval(fromNodeID uint32)
	ProcessRelayedRejection(fromNodeID uint32)

	// Stop drains background RPCs and stops the replay reaper.
	Stop()
}

type HandshakeTrustRecord struct {
	NodeID     uint32
	PublicKey  string
	ApprovedAt time.Time
	Mutual     bool
	Network    uint16
}

type Listener interface {
	// Accept blocks until an inbound Connection lands on the
	// listener or the listener is closed. ok=false signals close
	// (no further Connections will arrive).
	Accept() (conn Connection, ok bool)

	// Port returns the bound port. Stable for the listener's lifetime.
	Port() uint16

	// Close releases the port and stops accepting new Connections.
	Close() error
}

type Plugin interface {
	// Name returns the registration key of this plugin. Must be
	// stable across releases of the plugin; the daemon engine may
	// use it for keyed lookups, persistence, and operator-facing
	// status output.
	Name() string

	// Init wires the plugin to a running daemon engine. The plugin
	// retains the Daemon for the rest of its lifetime. Init returns
	// an error if the plugin cannot bootstrap; the daemon aborts
	// startup on any plugin Init failure.
	Init(d Daemon) error

	// Shutdown stops the plugin's background work and drains any
	// in-flight requests. The Daemon passed to Init is still valid
	// during Shutdown — plugins may use it for last-mile work — but
	// the daemon engine will not accept new traffic. Shutdown should
	// honor the context's deadline; the daemon will not wait
	// indefinitely on a stuck plugin.
	Shutdown(ctx context.Context) error
}

type PolicyEventType = string

type PolicyManager interface {
	Start(netID uint16, policyJSON []byte) (PolicyRunner, error)
	Stop(netID uint16)
	Get(netID uint16) PolicyRunner
	All() []PolicyRunner
	StopAll()
	LoadPersisted() error
}

type PolicyRunner interface {
	NetworkID() uint16
	HasMember(peerNodeID uint32) bool

	// EvaluatePortGate takes a string event-type ("connect", "dial",
	// "datagram", ...). The plugin's EventType is a type alias to
	// coreapi.PolicyEventType which is itself a type alias to string,
	// so plugin signatures match this exactly.
	EvaluatePortGate(
		eventType string,
		port uint16,
		peerNodeID uint32,
		payloadSize int,
		direction string,
		localTags, nodeInfoTags []string,
	) bool

	EvaluateActions(eventType string, ctx map[string]any)
	Status() map[string]any
	PeerList() []map[string]interface{}
	ForceCycle() map[string]any
	ReconcileNow()
	PolicyJSON() ([]byte, error)
	Stop()
}

type PortAllocator interface {
	// Bind takes ownership of the given port and returns a Listener
	// that will receive Connections targeting it. Returns an error
	// if the port is already bound.
	Bind(port uint16) (Listener, error)

	// Unbind releases the port. The Listener returned by Bind also
	// stops accepting (its Accept loop returns ok=false). Idempotent;
	// unbinding an unbound port is a no-op.
	Unbind(port uint16)
}

type TrustChecker interface {
	IsTrusted(nodeID uint32) (string, bool)
}

type TunnelRegistry interface {
	// RemovePeer tears down the encrypted tunnel for the given peer.
	// All per-peer state (session keys, retransmit queues, routing
	// entries) is dropped. Safe to call when no tunnel exists.
	RemovePeer(nodeID uint32)
}

type VersionInfo struct {
	// Version is the semver of the running daemon, e.g. "v1.10.5".
	Version string
	// Commit is the git SHA the daemon was built from. Empty in dev builds.
	Commit string
	// BuildTime is the UTC timestamp the daemon binary was assembled.
	BuildTime string
}

type WebhookManager interface {
	// SetURL hot-swaps the active webhook URL. Empty URL disables
	// delivery (no-op until set again).
	SetURL(url string)

	// Stats returns dispatcher counters for daemon Info. All-zero
	// when no client is configured (nil-safe at the plugin level).
	Stats() WebhookStats
}

type WebhookStats struct {
	Dropped      uint64
	CircuitSkips uint64
}