Documentation
¶
Overview ¶
Package webhooks sends signed events to endpoints that owners register.
Index ¶
- Constants
- Variables
- func NewClient(allowPrivate bool) *http.Client
- func NewLiveClient(allowPrivate func() bool) *http.Client
- func RegisterRoutes(api huma.API, pool *pgxpool.Pool, store *Store, notifier *Notifier, ...)
- func Sign(secret string, timestamp int64, body []byte) string
- func SignatureHeader(timestamp int64, body []byte, secrets ...string) string
- func ValidateURL(ctx context.Context, raw string, allowPrivate bool) error
- type Attempt
- type Delivery
- type DeliveryArgs
- type DeliveryWorker
- type Endpoint
- type Envelope
- type JobInserter
- type Notifier
- func (n *Notifier) Redeliver(ctx context.Context, pool beginner, deliveryID string) (bool, error)
- func (n *Notifier) SendTest(ctx context.Context, pool beginner, endpointID string) error
- func (n *Notifier) SetChanged(ctx context.Context, tx pgx.Tx, setID string) error
- func (n *Notifier) SkillChanged(ctx context.Context, tx pgx.Tx, skillName string) error
- func (n *Notifier) SubmissionDecided(ctx context.Context, tx pgx.Tx, sub *submissions.Submission) error
- func (n *Notifier) VersionReleased(ctx context.Context, tx pgx.Tx, ev skill.ReleaseEvent) error
- type SetChangedData
- type Store
- func (s *Store) Deliveries(ctx context.Context, endpointID string, limit int) ([]Delivery, error)
- func (s *Store) Get(ctx context.Context, id string) (*Endpoint, error)
- func (s *Store) List(ctx context.Context) ([]Endpoint, error)
- func (s *Store) Rotate(ctx context.Context, id, secret string, window time.Duration) (*Endpoint, error)
- type SubmissionData
- type VersionData
- type WebhookEndpointWithSecret
Constants ¶
const ( HeaderEventID = "X-Skael-Event-Id" HeaderEventType = "X-Skael-Event-Type" HeaderTimestamp = "X-Skael-Timestamp" HeaderSignature = "X-Skael-Signature" )
The headers each delivery carries.
const ( EventVersionPublished = "skill.version.published" EventVersionApproved = "skill.version.approved" EventSetChanged = "set.changed" EventSubmissionDone = "submission.decided" )
The event types.
Variables ¶
var ErrRefusedAddress = errors.New("refused address")
ErrRefusedAddress reports an address a delivery may not reach.
var EventTypes = []string{EventVersionPublished, EventVersionApproved, EventSetChanged, EventSubmissionDone}
EventTypes lists what an endpoint can subscribe to.
Functions ¶
func NewClient ¶
NewClient returns the HTTP client for deliveries. The control function runs on the resolved IP of every connection, including each redirect, so DNS rebinding and a redirect to a metadata service both fail at dial.
func NewLiveClient ¶ added in v0.19.0
NewLiveClient is NewClient with the address rule read on every dial and redirect.
func RegisterRoutes ¶
func RegisterRoutes(api huma.API, pool *pgxpool.Pool, store *Store, notifier *Notifier, allowPrivate func() bool)
RegisterRoutes wires endpoint management. Only instance owners and admins reach it, because an endpoint receives data about every matching skill.
func SignatureHeader ¶
SignatureHeader signs with each live secret, so a consumer holding the old secret still verifies during a rotation window.
Types ¶
type Attempt ¶
type Attempt struct {
ResponseCode *int `json:"response_code"`
Error string `json:"error,omitempty"`
Succeeded bool `json:"succeeded"`
CreatedAt time.Time `json:"created_at"`
}
Attempt is one try at a delivery.
type Delivery ¶
type Delivery struct {
ID string `json:"id"`
EventID string `json:"event_id"`
EventType string `json:"event_type"`
State string `json:"state"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Attempts []Attempt `json:"attempts"`
}
Delivery is one event for one endpoint, with every attempt.
type DeliveryArgs ¶
type DeliveryArgs struct {
DeliveryID string `json:"delivery_id"`
}
DeliveryArgs holds an id and nothing else. River UI shows arguments to admins, and a payload or a secret must not appear there.
func (DeliveryArgs) InsertOpts ¶
func (DeliveryArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type DeliveryWorker ¶
type DeliveryWorker struct {
river.WorkerDefaults[DeliveryArgs]
// contains filtered or unexported fields
}
DeliveryWorker sends one attempt of one delivery.
func NewDeliveryWorker ¶
func NewDeliveryWorker(store *Store, allowPrivate func() bool) *DeliveryWorker
NewDeliveryWorker constructs the worker.
func (*DeliveryWorker) NextRetry ¶
func (w *DeliveryWorker) NextRetry(job *river.Job[DeliveryArgs]) time.Time
NextRetry doubles from one minute up to maxBackoff.
func (*DeliveryWorker) Timeout ¶
func (w *DeliveryWorker) Timeout(*river.Job[DeliveryArgs]) time.Duration
Timeout bounds one attempt beyond the HTTP client's own limit.
func (*DeliveryWorker) Work ¶
func (w *DeliveryWorker) Work(ctx context.Context, job *river.Job[DeliveryArgs]) error
Work sends the event. Returning an error makes River retry, and the state becomes failed only on the attempt River will not repeat.
type Endpoint ¶
type Endpoint struct {
ID string `json:"id"`
Name string `json:"name"`
URL string `json:"url"`
EventTypes []string `json:"event_types"`
SetIDs []string `json:"set_ids"`
Enabled bool `json:"enabled"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
PreviousExpiresAt *time.Time `json:"previous_secret_expires_at,omitempty"`
// contains filtered or unexported fields
}
Endpoint is a registered receiver. Its secrets never leave through this type.
type Envelope ¶
type Envelope struct {
ID string `json:"id"`
Type string `json:"type"`
Time time.Time `json:"time"`
Data any `json:"data"`
}
Envelope is the JSON body of every delivery.
type JobInserter ¶
type JobInserter interface {
InsertTx(ctx context.Context, tx pgx.Tx, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
}
JobInserter is the part of the River client that enqueues in a transaction.
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier turns a change into events inside the transaction that made the change, so a crash cannot lose an event and a rollback cannot invent one.
func NewNotifier ¶
func NewNotifier(inserter JobInserter, setStore *sets.Store) *Notifier
NewNotifier constructs a Notifier.
func (*Notifier) SendTest ¶
SendTest emits a test event to one endpoint, and redeliver re-enqueues with the same event id: both run in their own transaction.
func (*Notifier) SetChanged ¶
SetChanged implements sets.ChangeNotifier. It emits only when the set's resolution id differs, so an unrelated release and an unchanged pin are quiet.
func (*Notifier) SkillChanged ¶
SkillChanged implements skill.ChangeNotifier: it rechecks each set that names the skill or one of its aliases, and each set whose pattern matches it.
func (*Notifier) SubmissionDecided ¶
func (n *Notifier) SubmissionDecided(ctx context.Context, tx pgx.Tx, sub *submissions.Submission) error
SubmissionDecided implements submissions.ChangeNotifier.
func (*Notifier) VersionReleased ¶
VersionReleased implements skill.ChangeNotifier. A publish the gate holds never reaches it, so a held version has no event.
type SetChangedData ¶
type SetChangedData struct {
SetID string `json:"set_id"`
Set string `json:"set"`
ResolutionID string `json:"resolution_id"`
Complete bool `json:"complete"`
Skills []sets.ResolvedEntry `json:"skills"`
}
SetChangedData is the data of set.changed. It holds no skill content, so a webhook cannot go around a set-limited key.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists endpoints and the delivery log.
func (*Store) Deliveries ¶
Deliveries lists an endpoint's newest deliveries with their attempts.
type SubmissionData ¶
type SubmissionData struct {
SubmissionID string `json:"submission_id"`
Skill string `json:"skill"`
State string `json:"state"`
Consumer string `json:"consumer"`
Version *int `json:"version,omitempty"`
}
SubmissionData is the data of submission.decided. A rejection's reason stays behind the API, which checks who reads it.
type VersionData ¶
type VersionData struct {
Skill string `json:"skill"`
Version int `json:"version"`
SHA256 string `json:"sha256"`
}
VersionData is the data of the skill version events.
type WebhookEndpointWithSecret ¶
WebhookEndpointWithSecret returns the secret once, at create and at rotate.