ingest

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Sep 26, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package ingest reads messages from a chat platform and does nothing else with them.

It is deliberately incapable of posting. The provider is constructed read-only, so it carries no Actor at all — not an Actor that refuses, but none — which removes moderation, interactive components and commands along with it. Shadow mode here is a property of the types rather than a flag somebody has to remember to check.

Index

Constants

View Source
const (
	// DefaultTokenEnvVar names the environment variable holding the bot token.
	// The config records the NAME; the secret never lands in a config file.
	//nolint:gosec // G101: this is the NAME of an environment variable, not a
	// credential. Recording the name rather than the value is the entire point.
	DefaultTokenEnvVar = "DISCORD_PHPBOTSCOUT_TOKEN"

	// DefaultHealthHost binds the health listener to loopback. Anything wider
	// is a decision an operator has to make deliberately.
	DefaultHealthHost = "127.0.0.1"

	// DefaultHealthPort is the health listener's port.
	DefaultHealthPort = 8081
)

Defaults for the settings that have a safe one. A credential and an allowlist deliberately do not.

View Source
const (
	// DefaultStateInterval is how often the connection is checked for a lossy
	// reconnect.
	//
	// It is polled rather than driven by traffic because the signal is about
	// the connection, not about messages: a reconnect during a quiet spell is
	// exactly the one nobody would otherwise notice, and waiting for the next
	// message to report it would mean the quietest channels report last.
	DefaultStateInterval = 5 * time.Second

	// DefaultHandlerTimeout bounds one handler call. Generous for a publish,
	// short enough that a stalled handler is visible inside one health
	// interval.
	DefaultHandlerTimeout = 5 * time.Second
)

Defaults for the settings that have a safe one.

Variables

View Source
var (
	// ErrNoGuilds is returned when no guild is configured.
	ErrNoGuilds = errors.NewSentinel("ingest.no_guilds", "ingest: no guild configured")

	// ErrMultipleGuilds is returned when more than one guild is configured.
	// Multi-tenancy is a v1 non-goal; the config is a list so that becomes an
	// additive change rather than a breaking one.
	ErrMultipleGuilds = errors.NewSentinel("ingest.multiple_guilds",
		"ingest: more than one guild configured, which is not supported in v1")

	// ErrNoSpace is returned when a guild carries no identifier.
	ErrNoSpace = errors.NewSentinel("ingest.no_space", "ingest: guild space must not be empty")

	// ErrNoChannels is returned for an empty allowlist. It fails closed: an
	// empty list permits nothing rather than everything.
	ErrNoChannels = errors.NewSentinel("ingest.no_channels", "ingest: channel allowlist must not be empty")

	// ErrWildcardBind is returned when the health listener would bind every
	// interface. Binding all of them and trusting a firewall to be correct is
	// how private services become public ones.
	ErrWildcardBind = errors.NewSentinel("ingest.wildcard_bind",
		"ingest: health host must be an explicit interface, not a wildcard")

	// ErrInvalidPort is returned for a port outside the usable range.
	ErrInvalidPort = errors.NewSentinel("ingest.invalid_port", "ingest: health port must be between 1 and 65535")

	// ErrNoAuth is returned when a guild carries no credential at all.
	ErrNoAuth = errors.NewSentinel("ingest.no_auth", "ingest: no credential configured")

	// ErrAmbiguousAuth is returned when more than one credential mode is set.
	// Picking one silently is the wrong kind of helpful where a secret is
	// concerned.
	ErrAmbiguousAuth = errors.NewSentinel("ingest.ambiguous_auth",
		"ingest: exactly one of auth.env, auth.keychain or auth.value may be set")
)

Configuration errors, as sentinels so a caller can tell a misconfiguration from a platform failure.

View Source
var (
	// ErrLoopStopped is reported when the message loop has exited.
	ErrLoopStopped = errors.NewSentinel("ingest.loop_stopped", "ingest: message loop stopped")

	// ErrNoFeed is returned when a pump is built over nothing.
	ErrNoFeed = errors.NewSentinel("ingest.no_feed", "ingest: no feed to read from")

	// ErrNoHandler is returned when a pump is built with nothing to hand
	// messages to.
	ErrNoHandler = errors.NewSentinel("ingest.no_handler", "ingest: no handler")
)

Pump errors.

Functions

func Needs added in v0.3.0

func Needs() []chatplatform.Need

Needs reports the platform capabilities this package intends to use.

Reading messages and nothing else. The list is what the transport negotiates its privileges from — on Discord these become gateway intents, sent once at identify and unchangeable without reconnecting — so leaving a capability out is how the bot stops being granted it rather than merely declining to use it. NeedMemberLookup is absent deliberately: nothing here looks a member up, and asking for it would request the privileged GUILD_MEMBERS intent for a capability no code path reaches.

A function rather than a package-level slice, so a caller cannot append to the set every service shares.

Types

type AuthConfig

type AuthConfig struct {
	// Env names an environment variable holding the token. The recommended
	// default, and the only mode permitted under CI.
	Env string `mapstructure:"env" yaml:"env" json:"env"`

	// Keychain references an OS keychain entry as "service/account".
	Keychain string `mapstructure:"keychain" yaml:"keychain" json:"keychain"`

	// Value is a literal token. Supported for throwaway environments and
	// refused under CI.
	Value string `mapstructure:"value" yaml:"value" json:"value"`
}

AuthConfig records how the bot token is stored, following the estate's three-mode convention. Exactly one field is set.

The config never holds the secret in env or keychain mode — only a name or a reference — which is what keeps a token out of a file that gets committed by accident.

func (AuthConfig) Mode

func (a AuthConfig) Mode() (credentials.Mode, error)

Mode reports which credential mode is configured, and whether exactly one is.

type Config

type Config struct {
	// Guilds is a list carrying exactly one entry in v1.
	//
	// The list shape is deliberate. A provider is scoped to one space at
	// construction, so supporting several is N providers and N services rather
	// than a contract change — but that is only cheap if the configuration did
	// not have to break to express it. A list with one element costs nothing
	// now; migrating every operator's config later does not.
	Guilds []GuildConfig `mapstructure:"guilds" yaml:"guilds" json:"guilds"`

	Health HealthConfig `mapstructure:"health" yaml:"health" json:"health"`
}

Config is the ingest service's configuration.

func (Config) Validate

func (c Config) Validate() error

Validate reports whether the configuration can start a bot that does what the operator meant.

It is strict on purpose. Every check here catches a configuration that would otherwise start successfully and behave wrongly in a way nobody would notice — reading no channels, reading the wrong server, or listening where it should not.

func (Config) WithDefaults

func (c Config) WithDefaults() Config

WithDefaults returns a copy with the safe defaults applied, leaving anything the operator set alone.

type Feed added in v0.5.0

type Feed interface {
	Messages() <-chan chatplatform.Message
	State() chatplatform.ConnState
}

Feed is what the pump reads. It is the two methods of a chatplatform.Reader the pump has a use for: the transport owns Connect and Close (0018 D8), so the pump cannot reach either, and it cannot reach an Actor because nothing here has a type that carries one (0018 D2).

type GuildConfig

type GuildConfig struct {
	// Space is the guild, workspace or network identifier.
	//
	// It is not how the bot discovers where it is — the gateway supplies that.
	// It is an authorisation boundary: an invite link can be shared, and this
	// is what stops an unintended server becoming one the bot serves.
	Space chatplatform.ID `mapstructure:"space" yaml:"space" json:"space"`

	// Channels is the allowlist. Empty permits nothing.
	Channels []chatplatform.ID `mapstructure:"channels" yaml:"channels" json:"channels"`

	// Auth carries the credential, in whichever mode the operator chose.
	Auth AuthConfig `mapstructure:"auth" yaml:"auth" json:"auth"`

	// PostAnswers lets the bot post its answers in this space. Off, the
	// default, keeps the space read-only by construction (spec 0025).
	PostAnswers bool `mapstructure:"post_answers" yaml:"post_answers" json:"post_answers"`
}

GuildConfig is one platform space and the channels the bot may read in it.

type Handler added in v0.5.0

type Handler func(ctx context.Context, space chatplatform.ID, msg chatplatform.Message)

Handler receives each permitted message.

The context carries a deadline of the pump's handler timeout, and the contract is that the handler returns when it ends. The pump calls it synchronously and cannot end it from outside: a handler that ignores its context stalls the pump, which readiness then reports (0018 D8d). The space is passed beside the message because neither Message nor Ref carries one.

func LogHandler added in v0.5.0

func LogHandler(log *slog.Logger) Handler

LogHandler is the composition slice's handler: it logs the message and does nothing else (0018 D6). Content is redacted at this boundary, because it is untrusted input from a public server.

type HealthConfig

type HealthConfig struct {
	// Host is the interface to bind. Explicit by requirement; wildcards are
	// rejected rather than defaulted.
	Host string `mapstructure:"host" yaml:"host" json:"host"`
	Port int    `mapstructure:"port" yaml:"port" json:"port"`
}

HealthConfig configures the health listener.

type Option

type Option func(*Pump)

Option configures a Pump.

func WithClock added in v0.5.0

func WithClock(now func() time.Time) Option

WithClock overrides the clock the hand-over age is measured with.

func WithHandlerTimeout added in v0.5.0

func WithHandlerTimeout(d time.Duration) Option

WithHandlerTimeout bounds each handler call.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets the logger.

func WithStateInterval

func WithStateInterval(d time.Duration) Option

WithStateInterval sets how often the connection state is polled for a reconnect that lost events.

type Pump added in v0.5.0

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

Pump reads one space's feed and hands each permitted message to a Handler.

It is the seam between the socket and whatever works the message (0018 D8d). It holds no platform handle it could close and no Actor it could post through; the transport that built it owns both.

func New

func New(
	space chatplatform.ID, channels []chatplatform.ID, feed Feed, h Handler, opts ...Option,
) (*Pump, error)

New builds a pump for one space.

func (*Pump) CheckReconnectLoss added in v0.5.0

func (p *Pump) CheckReconnectLoss()

CheckReconnectLoss reports a resume that re-identified, exactly once per occurrence.

This is the failure that produces no error and no crash: the bot reconnects, looks healthy, and has silently missed every message sent during the gap. For a support bot those are questions nobody will ever answer. Exported so a readiness probe can poll it during a quiet spell as well as the watcher.

func (*Pump) Detach added in v0.5.0

func (p *Pump) Detach()

Detach drops the feed. The transport calls it once the reader is closed: Run already holds the channel, so the drain continues, and the pump no longer references the reader or, through it, the client.

func (*Pump) Done added in v0.5.0

func (p *Pump) Done() <-chan struct{}

Done is closed when Run has returned.

func (*Pump) HandlerPanics added in v0.5.0

func (p *Pump) HandlerPanics() int64

HandlerPanics counts handler calls that panicked and were recovered.

func (*Pump) HandlerTimeouts added in v0.5.0

func (p *Pump) HandlerTimeouts() int64

HandlerTimeouts counts handler calls that ran past their deadline.

func (*Pump) Ingested added in v0.5.0

func (p *Pump) Ingested() int64

Ingested counts messages accepted from allowlisted channels.

func (*Pump) Outstanding added in v0.5.0

func (p *Pump) Outstanding() time.Duration

Outstanding reports how long the hand-over in progress has been running, or zero when there is none. A value past the handler timeout means a handler has ignored its deadline.

func (*Pump) ReconnectLosses added in v0.5.0

func (p *Pump) ReconnectLosses() int64

ReconnectLosses counts resumes that re-identified and therefore dropped the events buffered during the gap.

func (*Pump) Rejected added in v0.5.0

func (p *Pump) Rejected() int64

Rejected counts messages discarded for being outside the allowlist. It carries no labels by design.

func (*Pump) Reload added in v0.5.0

func (p *Pump) Reload(cfg GuildConfig)

Reload applies a changed configuration.

The allowlist is applied. Identity is not: a changed space or credential needs a restart (R-OPS-5a), and is warned about by name so an ignored change is never a silent one. Applying it live would mean tearing down a working session on a config write, so a mistyped credential would take the bot off the platform at a time nobody chose.

func (*Pump) Run added in v0.5.0

func (p *Pump) Run(ctx context.Context)

Run consumes the feed until it closes, then returns.

It never selects on ctx. The feed closes when the transport closes the reader, and everything already buffered is still readable after that (0018 OQ3), so ranging to the close is what drains the tail; cancellation would drop it. The context is used only as the value-carrying parent of each handler call, stripped of its cancellation.

func (*Pump) Running added in v0.5.0

func (p *Pump) Running() bool

Running reports whether the loop is still consuming.

func (*Pump) SetChannels added in v0.5.0

func (p *Pump) SetChannels(ids []chatplatform.ID)

SetChannels replaces the allowlist. Pure filtering, so it applies to the next message with no session involved (R-OPS-5).

func (*Pump) Space added in v0.5.0

func (p *Pump) Space() chatplatform.ID

Space is the space this pump reads.

func (*Pump) Watch added in v0.5.0

func (p *Pump) Watch(ctx context.Context)

Watch polls the connection for a reconnect that lost events until ctx ends.

Jump to

Keyboard shortcuts

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