verify

package
v0.20.2 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package verify is the relay's self-verification harness: it drives real messages through real Slack and asserts that each inbound path behaved as designed.

Why this exists

Every inbound path had a verification story except one. `app_mention` carries an absolute guard — a bot-authored mention is dropped, no exceptions, because the relay replies as the same bot and a bot-triggerable mention is an unbounded reply→trigger→reply loop. The consequence was that no automated check could ever exercise `app_mention`, and a real bug (the mention flag lost across the slackproto→handler boundary) survived to release because only a human typing in Slack could find it.

The way out is not to weaken the guard, and not to add a test-only door past it. It is to post as a *human*: `chat.postMessage` with a user token (`xoxp-`) produces a message with no `bot_id` and a real human `user`, so it clears the guard the same way a person does, over the same websocket, through Slack's own servers. Nothing here bypasses anything — that is the entire point, and it is why the checks are worth trusting.

How a check asserts

Both halves, always:

  • the ingest journal (internal/journal) record for the exact ts it posted, which says what the relay decided and why; and
  • the actual Slack thread state via conversations.replies.

The journal half is load-bearing for the negative checks. "The bot must NOT answer this" asserted by silence alone is unfalsifiable — it passes just as happily when the relay is down, misconfigured, or still booting. Waiting for the *drop record* for that specific ts turns it into positive evidence that the relay saw the message and deliberately declined it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultJournalArgv

func DefaultJournalArgv(unit, since string) []string

DefaultJournalArgv reads the systemd user unit's log from the point the harness started. `-o cat` strips journald's own prefix, though journal.Parse tolerates it either way.

func ParseRecords

func ParseRecords(b []byte) []journal.Record

ParseRecords extracts every ingest record from a log stream.

func PollWaiter

func PollWaiter(interval, timeout time.Duration) func(context.Context, func(context.Context) (bool, error)) error

PollWaiter returns a Wait function that re-evaluates cond every interval until it holds or timeout elapses.

func Summarise

func Summarise(results []Result) (string, bool)

Summarise renders the results as one line per check plus a verdict, and reports whether every check that ran passed.

Types

type CommandSource

type CommandSource struct {
	Argv []string
	// Timeout bounds a single read. It is deliberately INDEPENDENT of
	// the caller's context deadline: the harness polls this inside a
	// wait budget, and if the read inherited that budget then the last
	// poll before the budget expired would have its journalctl killed
	// mid-flight and report "context deadline exceeded" — a symptom of
	// the wait ending, dressed up as the cause. That is not
	// hypothetical: it cost a real operator a wrong diagnosis, sending
	// them after a slow journald when the actual cause (a refusal) was
	// sitting in the journal the whole time. A read is either fast or
	// genuinely broken; either way it must say which. 0 = 30s.
	Timeout time.Duration
}

CommandSource reads the relay's ingest journal by running a command and parsing its output — in production `journalctl --user -u slack-acp`, but any command that emits the relay's log lines works (a file cat, an ssh into the deployment host, a container log).

It re-runs the command on every call rather than tailing: the harness polls, the window is bounded by --since, and a re-read is far simpler to reason about than a long-lived pipe that can stall.

func NewCommandSource

func NewCommandSource(argv []string) (*CommandSource, error)

NewCommandSource builds a Source from an argv.

func NewShellSource

func NewShellSource(cmdline string) (*CommandSource, error)

NewShellSource builds a Source from a shell command line. Splitting an operator-supplied string on whitespace would mangle the quoting that any realistic override needs (`ssh host journalctl --since "10 min ago"`), so the string is handed to the shell verbatim.

func (*CommandSource) Records

func (c *CommandSource) Records(ctx context.Context) ([]journal.Record, error)

Records runs the command and parses every ingest record from its output. Non-record lines are ignored, so the command may emit the relay's ordinary logging too.

type Config

type Config struct {
	// Bot is authenticated with the xoxb- token: it posts the
	// bot-authored checks and performs cleanup of the relay's replies.
	Bot Slack
	// User is authenticated with an xoxp- user token and posts every
	// human-authored check. Nil disables those checks (they report
	// SKIP with the reason) — the harness never silently substitutes
	// the bot token, because a bot-authored post cannot exercise the
	// app_mention guard and pretending otherwise is the exact failure
	// mode this package exists to avoid.
	User Slack
	// Journal reads the relay's ingest decisions.
	Journal Source

	PublicChannel  string
	PrivateChannel string

	// Outage, when set, enables the catch-up checks: it stops the
	// relay, the harness posts while it is down, and it starts it again.
	// Nil SKIPs them.
	Outage Outage

	// SelfDriveSentinel enables the self-drive check when non-empty.
	SelfDriveSentinel string

	// Interject enables the mid-turn interject check; set it when the
	// relay runs with interject.enabled.
	Interject bool

	// Nonce disambiguates this run's messages from any other run's.
	// Generated per-run when empty.
	Nonce string

	// Wait blocks until cond returns true, or fails. Injected so tests
	// need no wall clock; nil installs PollWaiter(200ms, 90s).
	Wait func(ctx context.Context, cond func(context.Context) (bool, error)) error

	// Now supplies the nonce timestamp; nil uses time.Now.
	Now func() time.Time
}

Config wires a Runner.

type Message

type Message struct {
	TS      string
	User    string
	BotID   string
	SubType string
	Text    string
}

Message is the subset of a Slack message the harness reasons about.

type Outage added in v0.17.0

type Outage interface {
	Stop(ctx context.Context) error
	Start(ctx context.Context) error
}

Outage takes the relay down and brings it back, so the catch-up can be exercised against real Slack: only a message posted while the relay is NOT connected proves the catch-up, and nothing short of stopping it makes Slack withhold an event.

func NewShellOutage added in v0.17.0

func NewShellOutage(stop, start string) (Outage, error)

NewShellOutage builds an Outage from two command lines. Both empty means none (the check SKIPs); exactly one is a configuration error, because a relay stopped and never started is worse than no check.

type Result

type Result struct {
	Name    string
	Status  Status
	Detail  string
	Records []journal.Record
}

Result is one check's outcome plus the evidence behind it.

type Runner

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

Runner executes the checks.

func New

func New(cfg Config) (*Runner, error)

New constructs a Runner, filling in defaults.

func (*Runner) Nonce

func (r *Runner) Nonce() string

Nonce returns the marker embedded in every message this run posts.

func (*Runner) Run

func (r *Runner) Run(ctx context.Context) ([]Result, error)

Run executes every check in order and returns one Result each. Cleanup runs unconditionally before returning, including on error.

type ShellOutage added in v0.17.0

type ShellOutage struct {
	StopCmd, StartCmd string
}

ShellOutage runs operator-supplied shell command lines, e.g. `systemctl --user stop slack-acp` / `systemctl --user start slack-acp`, or the same over ssh.

func (ShellOutage) Start added in v0.17.0

func (o ShellOutage) Start(ctx context.Context) error

Start runs the start command.

func (ShellOutage) Stop added in v0.17.0

func (o ShellOutage) Stop(ctx context.Context) error

Stop runs the stop command.

type Slack

type Slack interface {
	// AuthTest returns the user id the token authenticates as.
	AuthTest(ctx context.Context) (string, error)
	// Post publishes a message, returning its ts. threadTS may be empty
	// for a top-level post.
	Post(ctx context.Context, channel, threadTS, text string) (string, error)
	// Update edits a message in place.
	Update(ctx context.Context, channel, ts, text string) error
	// Delete removes a message. Slack only permits deleting messages
	// authored by the calling token.
	Delete(ctx context.Context, channel, ts string) error
	// Replies returns the messages of a thread, parent first.
	Replies(ctx context.Context, channel, threadTS string) ([]Message, error)
	// OpenDM returns the IM channel id for a conversation with userID.
	OpenDM(ctx context.Context, userID string) (string, error)
	// React adds the named emoji reaction to a message.
	React(ctx context.Context, channel, ts, name string) error
	// Upload shares a small text file into channel with comment as its
	// message text, returning the file id.
	Upload(ctx context.Context, channel, name, content, comment string) (string, error)
	// FileShareTS returns the ts of the message that shared fileID in
	// channel, or "" while Slack has not recorded the share yet.
	FileShareTS(ctx context.Context, fileID, channel string) (string, error)
	// DeleteFile removes an uploaded file.
	DeleteFile(ctx context.Context, fileID string) error
}

Slack is the Web API surface the harness needs. Two implementations are wired at runtime — one bound to the bot token, one to the user token — because *which token posts* is the whole experiment.

func NewSlack

func NewSlack(token string) Slack

NewSlack wraps a token in the Slack interface. Pass an xoxb- token for the bot client and an xoxp- user token for the human client. The token is never logged, and never appears in argv — it is read from the environment by the caller.

SLACK_API_BASE redirects the Web API, matching slackproto's behaviour, so the harness can be exercised against a fake server.

type Source

type Source interface {
	Records(ctx context.Context) ([]journal.Record, error)
}

Source yields the relay's ingest-journal records. The live implementation shells out to journalctl; tests supply a fixture.

type Status

type Status string

Status is the outcome of one named check.

const (
	StatusPass Status = "PASS"
	StatusFail Status = "FAIL"
	StatusSkip Status = "SKIP"
)

Check outcomes. Skip is a first-class result, not a soft pass: a check that could not run (no user token, no sentinel configured) must be visibly absent from the evidence, never quietly green.

Jump to

Keyboard shortcuts

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