kiss

type ChannelStat struct {
	RxFrames uint64
	TxFrames uint64
}

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

type ClientConfig struct {
	// InterfaceID is the KissInterface DB row ID. Used to tag ingress
	// frames (TNC mode) with ingress.KissTnc(InterfaceID).
	InterfaceID uint32
	// Name identifies the interface in logs and metrics.
	Name string
	// RemoteHost / RemotePort are the dial target.
	RemoteHost string
	RemotePort uint16
	// ChannelMap mirrors the server side — the per-port → channel
	// translation applied to inbound frames. Outbound TX uses the
	// reverse mapping (first port whose value equals the target
	// channel, default 0).
	ChannelMap map[uint8]uint32
	// ReconnectInitMs / ReconnectMaxMs size the backoff schedule. Both
	// must be > 0; the manager normalizes zero to sensible defaults
	// before calling.
	ReconnectInitMs uint32
	ReconnectMaxMs  uint32
	// Dialer is the net.Dialer used for every dial. nil → default
	// Dialer with a 10s connect timeout. Tests inject a custom dialer
	// to point at net.Pipe endpoints.
	Dialer *net.Dialer
	// DialFunc, when non-nil, replaces the net.Dialer. Used by tests
	// that don't have a real listener (e.g. net.Pipe harnesses).
	DialFunc func(ctx context.Context, network, addr string) (net.Conn, error)
	// Sink receives parsed AX.25 frames for TX (modem mode). Typically
	// *txgovernor.Governor.
	Sink txgovernor.TxSink
	// Logger is optional.
	Logger *slog.Logger
	// Mode selects RX routing — identical semantics to the server
	// path. Modem-mode Clients submit inbound frames to Sink; TNC-mode
	// Clients forward via RxIngress.
	Mode Mode
	// AllowTxFromGovernor mirrors the server-side knob: when true AND
	// Mode==ModeTnc, the manager wires a per-instance tx queue.
	AllowTxFromGovernor bool
	// TncIngressRateHz / TncIngressBurst size the TNC-mode rate
	// limiter on inbound frames. Zero disables rate limiting.
	TncIngressRateHz uint32
	TncIngressBurst  uint32
	// RxIngress is the TNC-mode inbound sink. Mirrors server.go.
	RxIngress func(rf *pb.ReceivedFrame, src ingress.Source)
	// GateTxToIs: when true and Mode == ModeModem, the dispatcher fires
	// OnClientTxAccepted after every KISS frame Sink.Submit accepted.
	// Meaningless when Mode == ModeTnc (the RX fanout there already
	// feeds the iGate). Default false.
	GateTxToIs bool
	// OnClientTxAccepted, when non-nil and GateTxToIs is true, is
	// invoked from the ModeModem branch of dispatchDataFrame AFTER
	// Sink.Submit returns nil. Wiring uses it to offer the parsed
	// APRS packet to the iGate's RF→IS gate. The hook MUST be
	// non-blocking — it runs on the client's read goroutine.
	OnClientTxAccepted func(ctx context.Context, channel uint32, f *ax25.Frame)
	// Clock is the rate-limiter's time source. nil → wall time.
	Clock Clock
	// OnFrameIngress is invoked for every successfully-decoded data
	// frame (observation hook).
	OnFrameIngress func(mode Mode)
	// OnDecodeError is invoked per ax.25 decode failure.
	OnDecodeError func()
	// OnReload is invoked on every state transition so the wiring
	// layer can nudge the txbackend dispatcher to rebuild. Optional.
	OnReload func()
}

type Clock interface {
	Now() time.Time
}

type Decoder struct {

	// Max payload size; frames larger than this return an error.
	MaxFrame int
	// contains filtered or unexported fields
}

type Frame struct {
	Port    uint8  // 0..15
	Command byte   // low nibble of the type byte
	Data    []byte // unescaped payload
}

type InstanceQueue interface {
	Enqueue(frame []byte, frameID uint64) error
	Depth() int32
}

type InterfaceStatus struct {
	// State is the lifecycle state. One of the State* constants above.
	State string
	// LastError is the most recent non-nil error from the transport, if
	// any. Cleared on successful (re)connection. Empty in Phase 1.
	LastError string
	// RetryAtUnixMs is the wall-clock time (Unix milliseconds) at which
	// the supervisor plans to retry a failed dial. Zero when not in
	// backoff or not applicable. Phase 4 fills this in.
	RetryAtUnixMs int64
	// PeerAddr is the dialed or accepted peer address, if known. Phase 4
	// populates this for tcp-client. Empty in Phase 1.
	PeerAddr string
	// ConnectedSince is the Unix millisecond timestamp when the current
	// session became live. Zero when not connected. Phase 4.
	ConnectedSince int64
	// ReconnectCount is the cumulative number of reconnect attempts the
	// supervisor has made since process start. Phase 4.
	ReconnectCount uint64
	// BackoffSeconds is the current backoff duration in seconds, used
	// by the UI to render a countdown. Zero when not in backoff. Phase 4.
	BackoffSeconds uint32
}

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

type ManagerConfig struct {
	Sink   txgovernor.TxSink
	Logger *slog.Logger
	// OnDecodeError, if non-nil, is installed on every Server the
	// Manager starts. A shared counter across all KISS interfaces is
	// intentional: the metric is about "kiss frames that failed
	// ax25 decoding" at the system level, not per-interface.
	OnDecodeError func()
	// OnFrameIngress, if non-nil, is invoked for every KISS data frame
	// that successfully AX.25-decodes at any managed server, with the
	// server's interface ID and its configured Mode. Observation hook
	// used by Phase 5 of the KISS modem/TNC plan to drive the
	// graywolf_kiss_ingress_frames_total counter.
	OnFrameIngress func(ifaceID uint32, mode Mode)
	// OnBroadcastSuppressed, if non-nil, is invoked once per recipient
	// skipped by BroadcastFromChannel's self-loop guard (the
	// originating TNC-mode interface). Phase 5 uses this to drive the
	// graywolf_kiss_broadcast_suppressed_total counter.
	OnBroadcastSuppressed func(recipientID uint32)
	// RxIngress, if non-nil, is installed on every Server started in
	// ModeTnc. The wiring layer wraps this with a non-blocking send
	// into the shared modem-RX fanout channel. Callers may set it
	// later via SetRxIngress; configs started before it is set run
	// without TNC routing (frames are dropped with a warning).
	RxIngress func(rf *pb.ReceivedFrame, src ingress.Source)
	// OnClientTxAccepted, if non-nil, is installed on every Server /
	// Client / Serial launched by this Manager. The Manager wraps it
	// with the per-interface DB row ID so the wiring layer can route
	// the gated submission through one shared App method without each
	// transport having to know its own ID. The wrapped hook only
	// fires inside the Server/Client dispatch path when the
	// per-interface GateTxToIs flag is set.
	OnClientTxAccepted func(ctx context.Context, ifaceID, channel uint32, f *ax25.Frame)
	// Clock is the rate-limiter time source installed on every Server.
	// nil selects wall time; tests inject a fake clock.
	Clock Clock
	// OnTxQueueDepth is an optional per-instance gauge reporter.
	// Invoked on every enqueue / drain with the updated depth so the
	// wiring layer can surface graywolf_kiss_instance_tx_queue_depth.
	OnTxQueueDepth func(ifaceID uint32, depth int32)
	// OnTxQueueDrop is an optional counter incrementer invoked when a
	// per-instance tx enqueue fails ("busy" | "down").
	OnTxQueueDrop func(ifaceID uint32, reason string)
	// OnClientStateChange, if non-nil, is invoked on every state
	// transition of a tcp-client supervisor. The wiring layer uses
	// this to surface the Phase 4 kiss_client metrics (connected
	// gauge, backoff_seconds gauge) without having to wire a
	// dedicated per-start callback from every notifyKissManager
	// path. name is the interface display name; st is the live
	// status snapshot.
	OnClientStateChange func(ifaceID uint32, name string, st InterfaceStatus)
	// OnClientReconnect fires exactly once per successful dial on a
	// tcp-client supervisor. Wired to the Phase 4
	// graywolf_kiss_client_reconnects_total counter.
	OnClientReconnect func(ifaceID uint32)
	// OnSerialStateChange / OnSerialReconnect mirror the client hooks
	// for serial supervisors. Parallel hooks (D7 option A); a
	// follow-up may collapse both behind transport-neutral
	// OnSupervisor* (tracked Out-of-scope in the spec).
	OnSerialStateChange func(ifaceID uint32, name string, st InterfaceStatus)
	OnSerialReconnect   func(ifaceID uint32)
}

type Mode string

type OpenFunc = func(device string, baud uint32) (io.ReadWriteCloser, error)

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

type SerialConfig struct {
	Name                string
	Device              string
	BaudRate            uint32
	Mode                Mode
	ChannelMap          map[uint8]uint32
	ReconnectInitMs     uint32
	ReconnectMaxMs      uint32
	Logger              *slog.Logger
	TncIngressRateHz    uint32
	TncIngressBurst     uint32
	AllowTxFromGovernor bool
	// GateTxToIs mirrors ServerConfig.GateTxToIs for the wrapping
	// Server constructed in StartSerial. Only meaningful when Mode ==
	// ModeModem; the field is read unconditionally and the server's
	// dispatch path enforces the mode gate.
	GateTxToIs bool
	// OnReload fires on every state transition so the wiring layer can
	// rebuild the tx backend. Mirrors ClientConfig.OnReload.
	OnReload func()
	// OpenFunc, when non-nil, replaces the go.bug.st/serial open. Tests
	// inject a fake returning an in-memory pipe. Mirrors
	// ClientConfig.DialFunc (client.go:131).
	OpenFunc func(device string, baud uint32) (io.ReadWriteCloser, error)
}

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

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

type ServerConfig struct {
	// InterfaceID is the KissInterface DB row ID. Used to tag inbound
	// frames with ingress.KissTnc(InterfaceID) when Mode == ModeTnc and
	// to suppress self-echo on the broadcast fanout. Zero is acceptable
	// for unit tests that don't exercise the RX fanout; production
	// startup and hot reload both populate it.
	InterfaceID uint32
	// Name identifies the interface in logs and metrics.
	Name string
	// ListenAddr is a "host:port" TCP address. For serial/bluetooth use a
	// different constructor (ServeTransport).
	ListenAddr string
	// ChannelMap translates KISS port numbers (0..15) to graywolf radio
	// channels. A missing entry defaults to channel 1.
	ChannelMap map[uint8]uint32
	// Sink receives parsed AX.25 frames for transmission. Typically
	// *txgovernor.Governor in production.
	Sink txgovernor.TxSink
	// Logger is optional.
	Logger *slog.Logger
	// OnClientChange is invoked with the new active-client count whenever
	// a client connects or disconnects. Optional.
	OnClientChange func(active int)
	// OnDecodeError is invoked for every KISS data frame whose payload
	// failed AX.25 decoding. Optional; nil is a no-op. A single counter
	// with no labels is used on purpose: per-client address would
	// explode cardinality on a server with churning clients.
	OnDecodeError func()
	// OnFrameIngress is invoked for every KISS data frame that
	// successfully AX.25-decodes, in both Modem and TNC modes, before
	// dispatch. Observation hook; nil is a no-op. The Mode argument
	// mirrors the server's configured routing so the subscriber can
	// label a single counter covering both modes.
	OnFrameIngress func(mode Mode)
	// Broadcast, when false, disables BroadcastFromChannel fan-out (the
	// interface is TX-only from the KISS client's perspective). Default
	// true — kiss_interfaces.broadcast in the configstore drives this.
	Broadcast bool
	// Mode selects the inbound-frame routing policy. Empty is treated as
	// ModeModem for backwards compatibility with callers that predate
	// the field.
	Mode Mode
	// TncIngressRateHz and TncIngressBurst configure the per-interface
	// token-bucket ingress cap applied in ModeTnc. Zero (either field)
	// disables rate limiting — every frame is allowed.
	TncIngressRateHz uint32
	TncIngressBurst  uint32
	// RxIngress, when non-nil and Mode == ModeTnc, receives every inbound
	// KISS data frame that survives the rate limiter and the per-interface
	// queue. Phase 3 wires this to the shared modem-RX fanout in
	// pkg/app/wiring.go. nil in ModeModem — that path submits to Sink
	// instead, preserving byte-for-byte existing behavior.
	RxIngress func(rf *pb.ReceivedFrame, src ingress.Source)
	// Clock is the rate-limiter's time source. nil selects wall time.
	// Tests inject a fake clock to exercise burst/refill determinism.
	Clock Clock
	// AllowTxFromGovernor mirrors KissInterface.AllowTxFromGovernor. When
	// true AND Mode == ModeTnc, the manager wires a per-instance tx
	// queue used by Manager.TransmitOnChannel to fan governor-scheduled
	// frames out to this interface. Informational on the server itself
	// (the server does not consult it directly); the manager reads it
	// to decide whether to construct the queue.
	AllowTxFromGovernor bool
	// GateTxToIs: when true and Mode == ModeModem, the dispatcher fires
	// OnClientTxAccepted after every KISS frame Sink.Submit accepted.
	// Meaningless when Mode == ModeTnc (the RX fanout there already
	// feeds the iGate). Default false.
	GateTxToIs bool
	// OnClientTxAccepted, when non-nil and GateTxToIs is true, is
	// invoked from the ModeModem branch of dispatchDataFrame AFTER
	// Sink.Submit returns nil. Wiring uses it to offer the parsed
	// APRS packet to the iGate's RF→IS gate. The hook MUST be
	// non-blocking — it runs on the per-connection read goroutine.
	OnClientTxAccepted func(ctx context.Context, channel uint32, f *ax25.Frame)
}