txgovernor

type ChannelTiming ¶

type ChannelTiming struct {
	SlotTime time.Duration // defaults to 100 ms
	Persist  uint8         // 0..255, default 63
	FullDup  bool          // skip CSMA entirely
}

ChannelTiming holds the CSMA parameters for one radio channel. Values mirror the tx_timing SQLite row (ms units). TX delay and tail live in ConfigurePtt (hot-reloaded by the bridge) and are not duplicated here.

type Config ¶

type Config struct {
	// Sender is the downstream TransmitFrame consumer. Required.
	Sender Sender
	// DcdEvents is an optional channel of per-channel DCD state changes
	// from modembridge. If nil, CSMA falls back to "always clear".
	DcdEvents <-chan *pb.DcdChange
	// Rate1MinLimit and Rate5MinLimit cap the number of frames transmitted
	// per channel in the last 1 and 5 minutes. Zero = unlimited.
	Rate1MinLimit int
	Rate5MinLimit int
	// DedupWindow is the suppression window for identical frames. Default
	// 30s if zero.
	DedupWindow time.Duration
	// QueueCapacity caps the total pending queue. Default 256.
	QueueCapacity int
	// Channels maps channel number to timing parameters. Missing channels
	// use defaults.
	Channels map[uint32]ChannelTiming
	// Logger is optional.
	Logger *slog.Logger
	// RandSource allows tests to inject a deterministic random source for
	// p-persist decisions. Defaults to time-seeded rand.
	RandSource *rand.Rand
}

Config is the Governor's static configuration.

type Governor ¶

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

Governor is the centralized TX scheduler.

func New(cfg Config) *Governor

func (g *Governor) AddTxHook(h TxHook) (id uint64, unregister func())

func (g *Governor) QueueLen() int

func (g *Governor) Run(ctx context.Context) error

func (g *Governor) SetChannelTiming(channel uint32, t ChannelTiming)

func (g *Governor) SetSkipCSMA(fn func(channel uint32) bool)

func (g *Governor) Stats() Stats

func (g *Governor) Submit(ctx context.Context, channel uint32, frame *ax25.Frame, src SubmitSource) error

type Sender ¶

type Sender func(*pb.TransmitFrame) error

Sender transmits one frame to the Rust modem. In production this is modembridge.Bridge.SendTransmitFrame; in tests, a fake.

type Stats ¶

type Stats struct {
	Enqueued     uint64
	Sent         uint64
	Deduped      uint64
	RateLimited  uint64
	QueueDropped uint64
}

Stats exposes counters for metrics.

type SubmitSource ¶

type SubmitSource struct {
	Kind      string // "kiss" | "agw" | "beacon" | "digipeater" | "igate"
	Detail    string
	Priority  int
	SkipDedup bool // bypass dedup window (e.g. operator-triggered send-now)
}

SubmitSource describes the origin of a TX request for logging, dedup scoping, and metrics.

type TxHook ¶

type TxHook func(channel uint32, frame *ax25.Frame, source SubmitSource)

TxHook is invoked after a frame has been successfully submitted to the downstream Sender. It runs inline in the governor's worker goroutine, so implementations MUST be fast and non-blocking (packetlog record, counter bumps, channel send with default, etc). A blocking hook stalls the governor's send loop for every registered consumer.

Multiple hooks may be registered concurrently via AddTxHook; they are invoked in registration order on each successful send.

type TxHookRegistry ¶

type TxHookRegistry interface {
	AddTxHook(h TxHook) (id uint64, unregister func())
}

TxHookRegistry is the narrow hook-registration interface. Callers that only need to register/unregister a TxHook should depend on this interface rather than the concrete *Governor so tests can inject a fake. The returned unregister closure is idempotent.

type TxSink ¶

type TxSink interface {
	Submit(ctx context.Context, channel uint32, frame *ax25.Frame, src SubmitSource) error
}

TxSink is implemented by anything that accepts AX.25 frames for transmit scheduling. The canonical implementation is *Governor; callers that need only to submit frames should depend on this interface rather than the concrete type so tests can inject a fake without reaching for a package-local interface copy.

Every production call site funnels through txgovernor.Governor. Previously each caller (kiss, agw, beacon, igate) declared its own TxSink + SubmitSource types duplicating this signature, which meant a change to the governor's Submit contract could silently drift away from the duplicates until a compile error finally surfaced in the adapter layer. Depending on this type eliminates that risk.