Package notify
Go module github.com/bide-ai/bide; all packages.
github.com/bide-ai/bide/notify · pkg.go.dev · Stability: core
Package notify ships bide's webhook notifier: a signed HTTPS POST of a structured notification, and the receiver-side Verify that checks one.
Constants
const HeaderDelivery = "Bide-Delivery",const HeaderTimestamp = "Bide-Timestamp",const HeaderSignature = "Bide-Signature": Header names of a webhook request.const DefaultTimeout = 10 * time.Second,const MaxRequests = 3: Defaults of a Webhook.const DefaultTolerance = 5 * time.Minute: DefaultTolerance is how far a request's timestamp may be from the receiver's clock before Verify rejects it, when the caller passes a tolerance of zero.const Schema = "bide.notification.v1": Schema is the value of the payload's "schema" field.
Variables
var ErrNoSignature,var ErrBadTimestamp,var ErrStale,var ErrBadSignature,var ErrNoSecrets,var ErrShortSecret,var ErrBodyTooLarge,var ErrDeliveryID: Verification errors.var ErrorText: ErrorText allows the typed error's text ("error") in the payload.
Functions
func CheckSecret(secret string) error: CheckSecret reports whether this process can use secret as a webhook signing secret: it returns ErrShortSecret for a non-empty secret shorter than 14 bytes under strict FIPS enforcement (GODEBUG=fips140=only), and nil otherwise.func SPKIHash(c *x509.Certificate) string: SPKIHash returns the hex SHA-256 of a certificate's SubjectPublicKeyInfo: the value WithServerPin takes, and the value recorded as the client certificate in a delivery's audit record.func Sign(secrets []string, ts int64, body []byte) string: Sign returns the Bide-Signature header value for body sent at ts: one "v1=<hex>" entry per secret, space separated, where each is HMAC-SHA256(secret, ts + "." + body).func Verify(r *http.Request, secrets []string, tolerance time.Duration) error: Verify checks a request from a bide webhook in one call, for use in a receiver.func VerifyBody(timestamp, signature string, body []byte, secrets []string, tolerance time.Duration, now time.Time) error: VerifyBody is Verify over parts the caller already holds, such as a stored body and its headers when checking a delivery later as evidence.
type Abort
type Abort struct {
Reason string `json:"reason"`
}Abort is the detail of a run_aborted event; Reason is a code from a closed set, not text.
type Approval
type Approval struct {
ToolUseID string `json:"tool_use_id"`
Tool string `json:"tool"`
Policy Policy `json:"policy"`
Approvers []string `json:"approvers"`
Approved int `json:"approved"`
Excluded []string `json:"excluded,omitempty"`
Reask string `json:"reask,omitempty"`
Why []agent.GateReason `json:"why,omitempty"`
Args json.RawMessage `json:"args,omitempty"`
}Approval is the detail of an approval_pending event: who may decide and how many must.
type Clears
type Clears struct {
ID string `json:"id"`
Key string `json:"key"`
Kind string `json:"kind"`
}Clears is the detail of a resolved notification, the all-clear: the event that stopped being current.
type Escalates
type Escalates struct {
ID string `json:"id"`
Key string `json:"key"`
Kind string `json:"kind"`
Level int `json:"level"`
}Escalates is the detail of an escalated notification.
type Failing
type Failing struct {
Cause string `json:"cause"`
}Failing is the detail of a recovery_failing event; Cause is a class, not text.
type Field
type Field struct {
// contains filtered or unexported fields
}A Field is a payload field that is left out unless named in WithFields.
Constructors and functions
func Args(tools ...string) Field: Args allows the arguments of an approval-pending call ("approval.args") for the named tools only.
type Halt
type Halt struct {
Cause string `json:"cause"`
AttemptedAt *time.Time `json:"attempted_at"`
}Halt is the detail of an outcome_unknown event.
type Option
type Option func(*Webhook) errorAn Option configures NewWebhook.
Constructors and functions
func WithClientCert(certFile, keyFile string) Option: WithClientCert presents a client certificate for mutual TLS, read from PEM files.func WithClientCertPEM(certPEM, keyPEM []byte) Option: WithClientCertPEM is WithClientCert for a pair held in memory, such as one read from the environment.func WithFields(fs ...Field) Option: WithFields allows payload fields that are left out by default.func WithOnError(f func(error)) Option: WithOnError sets where non-fatal problems are reported, such as a client certificate that failed to reload (the last good pair stays in use).func WithProxy(f func(*http.Request) (*url.URL, error)) Option: WithProxy sets how the webhook reaches the receiver through a proxy (nil means directly).func WithRequestsPerCall(n int) Option: WithRequestsPerCall sets how many requests one Notify call may make, with backoff of 1 s then 2 s between them (default 1, at most MaxRequests).func WithSecrets(current, previous string) Option: WithSecrets sets the signing secrets.func WithServerCA(file string) Option: WithServerCA verifies the receiver against the CA certificates in a PEM file instead of the system roots.func WithServerCAPEM(pem []byte) Option: WithServerCAPEM is WithServerCA for a bundle held in memory.func WithServerPin(pins ...string) Option: WithServerPin pins the receiver's key: after normal certificate verification, the handshake fails unless a certificate in the verified chain has a SubjectPublicKeyInfo whose SHA-256 is one of the pins (64 hex characters or base64; see SPKIHash).func WithTimeout(d time.Duration) Option: WithTimeout sets the timeout of each request (default 10 seconds).func WithViewDB(path string) Option: WithViewDB names the SQLite journal file the deployment's runs are in, so the payload's view.command is a command that runs:bide view -db <path> -run <id>.func WithViewURL(base string) Option: WithViewURL sets the base URL of the deployment's run viewer; the payload's view.url is then base + "/" + run ID, escaped.
type Payload
type Payload struct {
Schema string `json:"schema"`
ID string `json:"id"`
Key string `json:"key"`
Kind string `json:"kind"`
RunID string `json:"run_id"`
EventAt *time.Time `json:"event_at"`
ObservedAt *time.Time `json:"observed_at"`
DeadlineAt *time.Time `json:"deadline_at"`
Attempt int `json:"attempt"`
Summary string `json:"summary"`
Step *Step `json:"step"`
Halt *Halt `json:"halt"`
Principal *Principal `json:"principal"`
Approval *Approval `json:"approval"`
Abort *Abort `json:"abort"`
Failing *Failing `json:"failing"`
Stop *Stop `json:"stop"`
Clears *Clears `json:"clears"`
Escalates *Escalates `json:"escalates"`
Receiver string `json:"receiver,omitempty"`
Reason string `json:"reason,omitempty"`
View View `json:"view"`
Error string `json:"error,omitempty"`
}Payload is the JSON body of a webhook request, schema bide.notification.v1.
type PermanentError
type PermanentError struct{ Status int }PermanentError is returned for a response that retrying inside the round cannot fix: any 4xx other than 429, or a redirect.
Methods
func (e *PermanentError) Error() string: Error names the status only: no URL, no body.func (e *PermanentError) Unwrap() error: Unwrap makes errors.Is(err, agent.ErrNotifyPermanent) true.
type Policy
type Policy struct {
Need int `json:"need"`
Of int `json:"of"`
}Policy is the gate's k of n.
type Principal
type Principal struct {
OnBehalfOf string `json:"on_behalf_of"`
AuthorityRef string `json:"authority_ref"`
}Principal is the party the run acts for.
type ProbeResult
type ProbeResult struct {
Status int
TLS bool
Handshake bool
HandshakeErr error
HandshakeTime time.Duration
TLSVersion string
Auth *agent.NotifyAuth
Requests int
Elapsed time.Duration
}ProbeResult is what one delivery looked like from the sender's side, for a tool that tests a receiver (bide notify test).
type Step
type Step struct {
OpKind string `json:"op_kind"`
OpID string `json:"op_id"`
Tool string `json:"tool,omitempty"`
}Step names the operation an event is about.
type Stop
type Stop struct {
ID string `json:"id"`
Scope string `json:"scope"`
Name string `json:"name,omitempty"`
Reason string `json:"reason"`
By string `json:"by"`
Host string `json:"host,omitempty"`
Mode string `json:"mode"`
Signed bool `json:"signed"`
Compensation string `json:"compensation"`
LiftedBy []string `json:"lifted_by,omitempty"`
}Stop is the detail of a stop_set or stop_lifted event.
type View
type View struct {
Command string `json:"command"`
URL *string `json:"url"`
}View points at where to look.
type Webhook
type Webhook struct {
// contains filtered or unexported fields
}A Webhook delivers notifications as signed HTTPS POSTs.
Constructors and functions
func NewWebhook(rawURL string, opts ...Option) (*Webhook, error): NewWebhook returns a Webhook that posts to rawURL.
Methods
func (w *Webhook) Notify(ctx context.Context, n agent.Notification) error: Notify delivers n as one signed POST, retrying inside the round (see MaxRequests).func (w *Webhook) Probe(ctx context.Context, n agent.Notification) (ProbeResult, error): Probe delivers n exactly as Notify does (the same payload, signature, TLS options and request rules) and reports how the delivery went, without the audit acknowledgement Notify makes.