notify

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package notify is the egress client for switchboard's outbound message ingress (v0.5 W4.5) — the half of unattended monitoring that speaks. A monitoring cycle that found something needs to say so in a chat channel where there is no inbound message to reply to, and switchboard's `--ingress-addr` surface is exactly that door:

POST  /v1/messages  {"conversation","text"}        → 200 {"conversation","id"}
PATCH /v1/messages  {"conversation","id","text"}   → 204
PATCH /v1/messages  {"conversation","id","append"} → 204, or 200 {"conversation","id"}

What this package is not

It is not a chat library and it holds no opinion about what a message should say. It has no notion of a finding, a transition, or a severity; the text is the caller's, and every method here is one HTTP request. Rendering belongs to whoever is writing the sentence (for a monitoring cycle that is the model), and the platform belongs to switchboard — an instance bridges the one platform it was started with, which is why there is no platform field on the wire.

It is also not durable. There is no queue, no retry loop and no spool: a failed post is reported to the caller, which for a monitoring cycle is the right answer, because the next cycle is a fresher sample and re-sending a stale assessment is worse than dropping it. Stdlib only, so the slim-embed dependency gate (scripts/check-slim-deps.sh) is unaffected.

The two answers that are not failures

Both come from append, and a client that treats them as errors is broken in a way that only shows up in production:

  • 409 "no remembered text for this message" — the ingress remembers the bodies it posted in memory, bounded and lost on restart, so an append can outlive the memory of what it is appending to. A restart, another replica, or a message posted from elsewhere all land here. The answer is ErrSendFullText, and the caller resends the whole message with Replace. 501 on an append means the same thing permanently (the platform cannot even tell when a message is full), and maps to the same sentinel for the same reason.

  • 200 with a ref, instead of 204 — the append would have overflowed the platform's single-message limit, so switchboard posted a continuation in the same thread and handed back its ref. Append returns that ref, and a caller that keeps appending to the old one will 409 forever afterwards.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrSendFullText says the append could not be applied and the
	// whole message must be sent instead (409, or 501 on an append).
	// It is a routine outcome, not a fault: see the package doc.
	ErrSendFullText = errors.New("notify: send the full text")

	// ErrEditUnsupported says the platform cannot edit messages at all
	// (501 on a replace). A caller that wanted to refine a message in
	// place has to post a new one.
	ErrEditUnsupported = errors.New("notify: this platform cannot edit messages")

	// ErrNoSuchMessage says the conversation or message is gone (404) —
	// a channel that was archived, a message somebody deleted.
	ErrNoSuchMessage = errors.New("notify: no such conversation or message")

	// ErrDenied covers the two configuration failures worth telling
	// apart from a transport blip: a bad bearer token (401) and a
	// conversation outside the ingress allowlist (403). Retrying either
	// is pointless until a human changes something.
	ErrDenied = errors.New("notify: refused")
)

Sentinels a caller acts on. Everything else is an *Error with a status, which a caller can inspect but is not expected to branch on.

Functions

This section is empty.

Types

type Client

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

Client posts to one switchboard ingress. Safe for concurrent use; it holds no per-message state, because the thing worth remembering between calls — which message a timeline is currently appending to — belongs to whoever is keeping the timeline.

func New

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

New validates the config and builds a client.

func (*Client) Append

func (c *Client) Append(ctx context.Context, ref Ref, line, idem string) (Ref, error)

Append adds a line to a message and returns the ref to address from now on — the same one, or the continuation switchboard rolled over into. A caller that ignores the returned ref will 409 on every subsequent append, which is the failure this signature exists to make hard.

ErrSendFullText means the append could not be applied and the caller should Replace with the full text it holds.

func (*Client) Endpoint

func (c *Client) Endpoint() string

Endpoint is the URL this client posts to, for the log line that says where a monitor is talking.

func (*Client) Post

func (c *Client) Post(ctx context.Context, conversation, text, idem string) (Ref, error)

Post sends a new message and returns its ref.

idem is the caller's replay key (the Idempotency-Key header), empty for none. A monitoring cycle should always set one: a post that timed out client-side may well have landed, and the retry that follows would otherwise double-post the same assessment.

func (*Client) Replace

func (c *Client) Replace(ctx context.Context, ref Ref, text, idem string) error

Replace rewrites a message's whole body. It is both the refinement verb — an assessment that took minutes edits the message it posted rather than littering the channel — and the fallback an append's ErrSendFullText asks for.

type Config

type Config struct {
	// BaseURL is switchboard's ingress. Either the bare origin
	// ("http://switchboard.agent-triage.svc.cluster.local:8080") or the
	// full endpoint; the route is appended when the URL carries no path.
	BaseURL string

	// Token is the bearer token the ingress requires. It is
	// deliberately not the daemon's own token — different direction,
	// different trust — and cmd/mast refuses to start if the two match.
	Token string

	// HTTP substitutes the transport (tests, proxies, custom TLS). When
	// nil a client with Timeout is built.
	HTTP *http.Client

	// Timeout bounds one request when HTTP is nil. Zero means
	// defaultTimeout.
	Timeout time.Duration
}

Config constructs a Client.

type Error

type Error struct {
	Status int
	Msg    string
	// Sentinel is the errors.Is target for this status, or nil.
	Sentinel error
}

Error is a non-2xx answer from the ingress. Msg is the ingress's own error text when it sent one, which is worth surfacing: it says whether a 403 was the allowlist or the chat platform's own refusal.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Ref

type Ref struct {
	Conversation string `json:"conversation"`
	ID           string `json:"id"`
}

Ref addresses one posted message. It is exactly what the ingress hands back, and exactly what a later edit or append must present.

func (Ref) Zero

func (r Ref) Zero() bool

Zero reports whether the ref names nothing — no message posted yet, or a timeline that was closed.

Jump to

Keyboard shortcuts

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