serve

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source
const (
	BusServiceName     = "messaging"
	BusHealthCheckName = "messaging-subscriptions"
)

BusServiceName is the bus's name in the controller. The health check takes a different one: a Controller enforces uniqueness only in the health-check map, so a collision is silently accepted and the report carries two entries under one name (0019 D7).

View Source
const (
	RespondSubscriberName  = "respond"
	FeedbackSubscriberName = "feedback"
)

Subscription names. There is no log subscriber: a line per message would keep what people wrote outside the policy's retention (spec 0028).

View Source
const DiscordServiceName = "discord"

DiscordServiceName is the transport's name in the controller, which is also how the health endpoints and the exhaustion poll refer to it.

View Source
const MinRefreshInterval = session.MinRefreshInterval

MinRefreshInterval is the shortest accepted refresh interval.

View Source
const StalenessHealthCheckName = "index-staleness"

StalenessHealthCheckName names the stale-source count on /healthz.

Variables

View Source
var (
	// ErrGaveUp is returned by Run when a required service fails for good: it
	// exhausts its restarts, fails to start with no restart policy, or dies
	// after a clean start. The process exits non-zero so an orchestrator and a
	// bare process converge on replacing it (0018 OQ9).
	ErrGaveUp = errors.NewSentinel("serve.gave_up", "serve: a required service gave up")
)

Errors the daemon can end on.

View Source
var ErrNoSubscribers = errors.NewSentinel("serve.no_subscribers",
	"serve: the message bus has no subscribers")

ErrNoSubscribers refuses a bus nothing would consume from. go/messaging accepts one since v0.2.1, for publish-only processes; serve is not one.

Functions

func NewBus added in v0.5.0

func NewBus(log *slog.Logger, respond, feedback Handler) (*messaging.Bus, error)

NewBus builds the bus the gateway publishes onto, with the answering path subscribed to messages and feedback to votes (spec 0027). A nil handler declares no subscription; the bus refuses to be built with none.

func NewBusWithMode added in v0.5.0

func NewBusWithMode(log *slog.Logger, respond, feedback Handler, mode messaging.DeliveryMode) (*messaging.Bus, error)

NewBusWithMode is NewBus with the delivery mode exposed, so a test can prove D16 by asking for one this backend refuses.

Not a knob. AtMostOnce is D5, and the design stays inside core NATS's intersection deliberately so that reaching a broker stays the wiring change the spike measured rather than a redesign.

func NewCmdServe

func NewCmdServe(props *props.Props) *setup.Command

func Purger added in v0.6.0

func Purger(ctx context.Context, log *slog.Logger, db *store.DB) (*respond.Purger, error)

Purger builds the scheduled question purge over the store the answering path records into, so the retention the policy publishes is enforced rather than promised (0010 D5a).

func Recovering added in v0.5.0

func Recovering(log *slog.Logger, name string, probe func() error) func() (err error)

Recovering wraps a probe so a panic inside it is a failed probe rather than a crashed supervisor: the controller calls Status bare (services.go:145).

func Refresher

func Refresher(sess *session.Session, p *props.Props, log *slog.Logger, interval time.Duration) *indexer.Service

Refresher builds the scheduled index refresher.

It goes through the same session the `index` commands open, so the scheduled and manual routes run one code path and cannot drift into disagreeing about what is indexed or where the index lives.

A failure here fails startup, deliberately. Building the provider makes no network call, so it can only fail on a configuration an operator can fix in seconds — and this project already refuses a bad configuration before anything binds or connects. A forge that is merely unreachable is a different thing: it surfaces later as a failed refresh, and is degraded rather than fatal.

func ReloadGuilds added in v0.10.1

func ReloadGuilds(log *slog.Logger, target GuildReloader) func(config.Observed) error

ReloadGuilds is the observer WatchGuilds registers. A change that does not validate is refused whole, so the running configuration stays, and the log says why. It never returns an error: the refusal is reported here, where its reason is known.

func Responder added in v0.5.0

func Responder(
	ctx context.Context, log *slog.Logger, cfg Config, db *store.DB,
	asker respond.Asker, posterFor PosterFunc, extra ...respond.Option,
) (*respond.Service, error)

Responder builds the answering path over an answerer: the recorder and threads over the store, one Poster per configured guild, and the budget if one is configured (0018 D6, 0019 D19).

The answerer is a parameter because building it needs a model provider and its credentials, and everything else here is testable without one.

Shadow mode is the default (0010 D6): the answer is composed and recorded, and nothing is posted, except in a server whose post_answers is set (0025).

func Run added in v0.5.0

func Run(ctx context.Context, d Deps) error

Run registers the services and runs the controller until the context ends or a required service gives up.

func RunServe

func RunServe(ctx context.Context, p *props.Props, _ *ServeOptions, _ []string) error

RunServe runs the daemon until the context is cancelled.

The command owns wiring and nothing else: configuration in, services registered, controller started, shutdown awaited. Every decision worth testing lives in pkg/transport and pkg/ingest, where it can be exercised against a fake rather than a live gateway.

func ServerAskers added in v0.11.0

func ServerAskers(
	ctx context.Context, guilds []ingest.GuildConfig, db *store.DB, shared chat.ChatClient, clientFor ClientFunc,
) ([]respond.Option, error)

ServerAskers gives each server with its own corpus or AI settings its own answering service (spec 0029 D5, D7, D9). A server with neither uses the process-wide asker, so it gets no option here. A server that keeps the process-wide provider and model shares its client.

func StalenessHealthCheck added in v0.14.0

func StalenessHealthCheck(refresher *indexer.Service) controls.HealthCheck

StalenessHealthCheck reports how many sources are stale. Degraded, never unhealthy: a stale index still answers, with a caveat (spec 0033 D7, OQ3).

func WatchGuilds added in v0.10.1

func WatchGuilds(store *config.Store, log *slog.Logger, target GuildReloader)

WatchGuilds hands each configuration change made while serve runs to target (issue 13). The store's watch is started by go-tool-base for every command.

Types

type ClientFunc added in v0.11.0

type ClientFunc func(ctx context.Context, provider, model string) (chat.ChatClient, error)

ClientFunc builds a chat client for a provider and model, each empty for the process-wide ai.* value. ask.NewClientFor is the production one.

type Config

type Config struct {
	ingest.Config

	Transport transport.Config
	Index     IndexConfig
	Respond   RespondConfig
}

Config is everything the daemon needs.

The ingest configuration is embedded rather than named, so the guilds and health sections keep reading as they did before the index arrived.

func ConfigFromStore

func ConfigFromStore(store *config.Store) (Config, error)

ConfigFromStore reads the configuration from the live store.

func LoadConfig

func LoadConfig(r io.Reader) (Config, error)

LoadConfig reads, defaults and validates the configuration.

Validation happens here rather than at first use so a misconfiguration is reported before anything connects or binds. An operator should see "the allowlist is empty", not a connection error three layers downstream of it.

type Deps added in v0.5.0

type Deps struct {
	Config Config
	Log    *slog.Logger

	// Discord is the transport to supervise. Built from Config by RunServe.
	Discord *transport.Transport

	// Bus carries messages from the gateway to its subscribers, or nil for
	// none. Nil is for tests that exercise the transport alone.
	Bus *messaging.Bus

	// Refresher is the index refresher, or nil for none.
	Refresher *indexer.Service

	// Purger enforces question retention, or nil for none.
	Purger *respond.Purger

	// Health is nil to skip the health listener (tests that do not want a
	// port), otherwise the listener settings.
	Health *ingest.HealthConfig
}

Deps is what Run needs, separated from how RunServe obtains it so a test and the swap scenario can inject a fake client, a fake transport or no refresher at all.

type GuildReloader added in v0.10.1

type GuildReloader interface {
	Reload(cfg ingest.Config)
}

GuildReloader takes a changed configuration. The transport is one: it applies what can change live and warns about what cannot.

type Handler added in v0.5.0

type Handler = func(context.Context, messaging.Delivery) error

Handler is a bus subscription's handler.

type IndexConfig

type IndexConfig struct {
	// RefreshInterval is how often the corpus is re-read.
	RefreshInterval time.Duration
}

IndexConfig is the resolved index configuration.

Deliberately does not carry index.path. That key has one reader — session.DBPath — shared with the `index` commands, and a second reader here would be the drift this whole wiring exists to avoid: `serve` refreshing one database while `index status` reports another.

type PosterFunc added in v0.5.0

type PosterFunc func(space comms.ID) (*transport.Poster, error)

PosterFunc hands out the write path for a space. transport.Transport.Poster is the one serve uses; a func so Responder can be built against a fake.

type RespondConfig added in v0.5.0

type RespondConfig struct {
	ThreadWindow time.Duration
	AnswerBudget int
}

RespondConfig is the resolved respond section.

type ServeOptions

type ServeOptions struct{}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL