daemon

Documentation

Overview

Package daemon implements the BubbleFish Nexus gateway daemon. It wires together the WAL, queue, idempotency store, destination adapter, HTTP server, authentication middleware, request handlers, Prometheus metrics, hot reload watcher, and 3-stage graceful shutdown.

Lifecycle:

New()   — validates dependencies, wires components, initialises metrics
Start() — opens WAL and destination, starts HTTP server, runs forever
Stop()  — 3-stage budgeted shutdown: HTTP → queue drain → WAL close

All state is held in struct fields. There are no package-level variables.

Index

• type Daemon
  • func New(cfg *config.Config, logger *slog.Logger) *Daemon
  • func (d *Daemon) BuildAdminRouter() http.Handler
  • func (d *Daemon) RequestShutdown()
  • func (d *Daemon) Search(ctx context.Context, params mcp.SearchParams) (mcp.SearchResult, error)
  • func (d *Daemon) ShutdownRequested() <-chan struct{}
  • func (d *Daemon) Start() error
  • func (d *Daemon) Status(_ context.Context) (mcp.StatusResult, error)
  • func (d *Daemon) Stop() error
  • func (d *Daemon) Stopped() <-chan struct{}
  • func (d *Daemon) Write(ctx context.Context, params mcp.WriteParams) (mcp.WriteResult, error)
• type DashboardAuditProvider
  • func NewDashboardAuditProvider(d *Daemon) *DashboardAuditProvider
  • func (p *DashboardAuditProvider) AuditStats() web.AuditStatsInfo
  • func (p *DashboardAuditProvider) InteractionsByActor(actorID string, limit int) []web.AuditRecordInfo
  • func (p *DashboardAuditProvider) PolicyDenials(limit int) []web.AuditRecordInfo
  • func (p *DashboardAuditProvider) RecentInteractions(limit int) []web.AuditRecordInfo
• type DashboardSecurityProvider
  • func NewDashboardSecurityProvider(d *Daemon) *DashboardSecurityProvider
  • func (p *DashboardSecurityProvider) AuthFailures(limit int) []web.AuthFailureInfo
  • func (p *DashboardSecurityProvider) LintFindings() []web.LintFinding
  • func (p *DashboardSecurityProvider) SourcePolicies() []web.SourcePolicyInfo

Types

type Daemon

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

Daemon is the central BubbleFish Nexus gateway daemon. All state is held in struct fields; there are no package-level variables.

func New

func New(cfg *config.Config, logger *slog.Logger) *Daemon

New creates a Daemon from the loaded configuration. It does NOT open any files or start any goroutines — call Start() for that.

Panics if cfg or logger are nil.

func (*Daemon) BuildAdminRouter

func (d *Daemon) BuildAdminRouter() http.Handler

BuildAdminRouter creates a chi router with all admin API routes and their auth middleware. This is used both by the daemon's data-plane router and by the web dashboard server (port 8081) to serve admin endpoints on the same origin as the dashboard HTML.

func (*Daemon) RequestShutdown

func (d *Daemon) RequestShutdown()

RequestShutdown signals that the daemon should begin graceful shutdown. Safe to call multiple times; only the first close has any effect.

func (*Daemon) Search

func (d *Daemon) Search(ctx context.Context, params mcp.SearchParams) (mcp.SearchResult, error)

Search executes the 6-stage retrieval cascade and returns matching records, identical to handleQuery but called directly without HTTP overhead.

Reference: Tech Spec Section 3.4, Section 14.3.

func (*Daemon) ShutdownRequested

func (d *Daemon) ShutdownRequested() <-chan struct{}

ShutdownRequested returns a channel that is closed when an API-initiated shutdown has been requested (via POST /api/shutdown). The start command selects on this alongside OS signals.

func (*Daemon) Start

func (d *Daemon) Start() error

Start opens the WAL, opens the destination, replays pending WAL entries, starts the queue workers, starts the hot reload watcher, and starts the HTTP server. It blocks until the HTTP server returns (i.e. until Stop is called or the listener fails).

Start is not safe to call concurrently. Call it once per Daemon.

func (*Daemon) Status

func (d *Daemon) Status(_ context.Context) (mcp.StatusResult, error)

Status returns the current daemon health and queue state.

Reference: Tech Spec Section 14.3.

func (*Daemon) Stop

func (d *Daemon) Stop() error

Stop gracefully shuts down the daemon in three budgeted stages. It is safe to call multiple times; only the first call has any effect (sync.Once).

Shutdown stages (reference: Tech Spec Section 14.2):

Stage 1 (stageTimeout): Stop accepting new HTTP requests.
Stage 2 (stageTimeout): Drain queue workers.
Stage 3 (stageTimeout): Stop reload watcher + close WAL + close destination.

Total budget = drain_timeout_seconds (default 30s). Each stage gets 1/3.

func (*Daemon) Stopped

func (d *Daemon) Stopped() <-chan struct{}

Stopped returns a channel that is closed when the daemon has fully stopped.

func (*Daemon) Write

func (d *Daemon) Write(ctx context.Context, params mcp.WriteParams) (mcp.WriteResult, error)

Write persists content through the WAL → queue → destination pipeline, identical to handleWrite but called directly without HTTP overhead.

It respects the same ordering contract as handleWrite:

1. Source lookup
2. Policy gate
3. Build TranslatedPayload
4. WAL append
5. Queue enqueue

Reference: Tech Spec Section 3.2, Section 14.3.

type DashboardAuditProvider

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

DashboardAuditProvider adapts Daemon to the web.AuditProvider interface. All methods are safe for concurrent use (they use the AuditReader which creates a new file handle per query).

Reference: Tech Spec Addendum Section A2.7.

func NewDashboardAuditProvider

func NewDashboardAuditProvider(d *Daemon) *DashboardAuditProvider

NewDashboardAuditProvider creates an AuditProvider backed by the given Daemon.

func (*DashboardAuditProvider) AuditStats

func (p *DashboardAuditProvider) AuditStats() web.AuditStatsInfo

AuditStats returns summary statistics for the interaction log.

func (*DashboardAuditProvider) InteractionsByActor

func (p *DashboardAuditProvider) InteractionsByActor(actorID string, limit int) []web.AuditRecordInfo

InteractionsByActor returns interaction records for a specific actor.

func (*DashboardAuditProvider) PolicyDenials

func (p *DashboardAuditProvider) PolicyDenials(limit int) []web.AuditRecordInfo

PolicyDenials returns interaction records with denied or filtered decisions.

func (*DashboardAuditProvider) RecentInteractions

func (p *DashboardAuditProvider) RecentInteractions(limit int) []web.AuditRecordInfo

RecentInteractions returns the most recent interaction records.

type DashboardSecurityProvider

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

DashboardSecurityProvider adapts Daemon to the web.SecurityProvider interface. All methods are safe for concurrent use (they use the daemon's RWMutex and the securitylog's internal mutex).

Reference: Tech Spec Section 13.2 — Security Tab.

func NewDashboardSecurityProvider

func NewDashboardSecurityProvider(d *Daemon) *DashboardSecurityProvider

NewDashboardSecurityProvider creates a SecurityProvider backed by the given Daemon.

func (*DashboardSecurityProvider) AuthFailures

func (p *DashboardSecurityProvider) AuthFailures(limit int) []web.AuthFailureInfo

AuthFailures returns the last N auth failure events.

func (*DashboardSecurityProvider) LintFindings

func (p *DashboardSecurityProvider) LintFindings() []web.LintFinding

LintFindings runs config lint and returns the findings.

func (*DashboardSecurityProvider) SourcePolicies

func (p *DashboardSecurityProvider) SourcePolicies() []web.SourcePolicyInfo

SourcePolicies returns a read-only summary of all source policies.