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 ¶
- func DefaultJournalArgv(unit, since string) []string
- func ParseRecords(b []byte) []journal.Record
- func PollWaiter(interval, timeout time.Duration) func(context.Context, func(context.Context) (bool, error)) error
- func Summarise(results []Result) (string, bool)
- type CommandSource
- type Config
- type Message
- type Outage
- type Result
- type Runner
- type ShellOutage
- type Slack
- type Source
- type Status
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultJournalArgv ¶
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 ¶
ParseRecords extracts every ingest record from a log stream.
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.
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 Outage ¶ added in v0.17.0
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
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 Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner executes the checks.
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.
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)
// 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 ¶
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 ¶
Source yields the relay's ingest-journal records. The live implementation shells out to journalctl; tests supply a fixture.