Documentation
¶
Overview ¶
Package events implements the docs/reference/webhooks.md outbound-webhook surface: HMAC delivery signing, the per-attempt delivery worker (re-signing on every retry), the storage contract for registered webhooks, and the ref.RefStore decorator that turns won non-ephemeral CAS ref flips into `push` events (docs/explanation/domain-model.md invariant 7).
The package deliberately owns only the eventing seam: durable queueing (internal/jobs) and webhook persistence (internal/meta) plug in through the narrow interfaces declared here; wiring them together is the serve command's job.
Index ¶
- Constants
- Variables
- func BaseRepoID(repoKey string) string
- func EphemeralUpdate(repoKey, refName string) bool
- func Sign(secret string, ts int64, body []byte) string
- type Deliverer
- type Delivery
- type MetaWebhookStore
- func (s MetaWebhookStore) CreateWebhook(ctx context.Context, org, url, secret string) (Webhook, error)
- func (s MetaWebhookStore) DeleteWebhook(ctx context.Context, org, id string) error
- func (s MetaWebhookStore) GetWebhook(ctx context.Context, id string) (Webhook, error)
- func (s MetaWebhookStore) ListWebhooks(ctx context.Context, org string) ([]Webhook, error)
- type PushPayload
- type RefStore
- type RefStoreOptions
- type RepoSource
- type RepositoryRef
- type TargetGuard
- type Webhook
- type WebhookLister
- type WebhookLookup
- type WebhookStore
Constants ¶
const ( // HeaderEvent carries the event type on every delivery. HeaderEvent = "X-Pierre-Event" // HeaderSignature carries the `t=<unix>,sha256=<hex>` HMAC signature. HeaderSignature = "X-Pierre-Signature" // UserAgent is the fixed delivery User-Agent. UserAgent = "Pierre-Webhook/1.0" // EventPush fires on any persistent-namespace ref update (API commits, // merges, branch/tag/notes writes, git push). EventPush = "push" // Sync lifecycle events (emitted by the upstream-sync worker). EventSyncStarted = "repo.sync.started" EventSyncSucceeded = "repo.sync.succeeded" EventSyncFailed = "repo.sync.failed" // Outbound push-upstream run events (open.storage extension, issue // #354; emitted by the upstream-sync worker's push lane). EventPushUpstreamStarted = "repo.push_upstream.started" EventPushUpstreamSucceeded = "repo.push_upstream.succeeded" EventPushUpstreamFailed = "repo.push_upstream.failed" )
Delivery headers and event names (docs/reference/webhooks.md "Delivery headers").
Variables ¶
var ErrTargetDenied = errors.New("target denied by egress policy")
ErrTargetDenied marks dial-time policy denials (as opposed to ordinary resolution/connect failures) so callers routing OTHER traffic through the guard — the outbound push egress proxy (issue #90) — can classify a refused destination as a configuration error rather than weather.
var ErrWebhookGone = errors.New("webhook no longer exists")
ErrWebhookGone marks a delivery whose webhook was deleted between enqueue and attempt: terminal, never retried, dropped silently (the registration is gone, so nobody is listening).
Functions ¶
func BaseRepoID ¶
BaseRepoID strips the optional `+ephemeral`/`+import` namespace suffix from a storage key (same shape githttp.BaseRepo handles for URL path elements), yielding the RepoID that keys repo metadata.
func EphemeralUpdate ¶
EphemeralUpdate reports whether a CASRef targets the ephemeral namespace on either write surface: the git surface keys ephemeral pushes by the `<RepoID>+ephemeral` storage key (plain ref names), the API surface uses the bare RepoID with `refs/namespaces/ephemeral/`-prefixed ref names.
func Sign ¶
Sign computes the docs/reference/webhooks.md delivery signature header value for one attempt: hex(HMAC-SHA256(secret, "<ts>." + body)) rendered as "t=<ts>,sha256=<hex>". Receivers reject timestamps older than ~300s, so callers must sign with the send-time timestamp on EVERY attempt (re-signing on retry); Deliverer.Attempt does exactly that.
Types ¶
type Deliverer ¶
type Deliverer struct {
Webhooks WebhookLookup // required
// Client posts deliveries; defaults to the TargetGuard-enforcing
// client (issue #53): private-range targets denied at dial time,
// redirects refused. Only tests override this — production wiring
// must keep the guard and steer it through AllowPrivate.
Client *http.Client
// AllowPrivate selects the guard's private-range escape hatch
// (OPENSTORAGE_WEBHOOK_ALLOW_PRIVATE) when Client is nil. Redirects
// are refused either way.
AllowPrivate bool
// Now supplies the signing timestamp; defaults to time.Now.
Now func() time.Time
// MaxAttempts bounds Deliver's retry loop (default 10, then discard).
MaxAttempts int
// Backoff returns the sleep before retrying after the given 1-based
// failed attempt; defaults to 1s<<(attempt-1) capped at 64s.
Backoff func(attempt int) time.Duration
// Logger records drops and retries; defaults to slog.Default().
Logger *slog.Logger
}
Deliverer is the webhook delivery worker (docs/reference/webhooks.md). Both queue backends share it: River workers call Attempt once per job attempt (River owns backoff/attempt accounting), the in-process local-mode queue calls Deliver which loops attempts with backoff itself. Every attempt reloads the webhook and signs with the current time, so retries always carry a fresh signature (receivers reject signatures older than ~300s).
func (*Deliverer) Attempt ¶
Attempt performs exactly one delivery attempt: reload the webhook, sign the payload with the current time, POST it with the docs/reference/webhooks.md headers. A non-2xx status or transport error returns an error (the caller retries); ErrWebhookGone (wrapped) is terminal.
func (*Deliverer) Deliver ¶
Deliver runs Attempt with backoff until success, a terminal drop (webhook deleted), MaxAttempts exhaustion (delivery discarded, per the docs/reference/webhooks.md at-least-once + bounded-retries guidance), or ctx cancellation. Used by the in-process local-mode queue; River jobs use Attempt directly.
type Delivery ¶
type Delivery struct {
WebhookID string
Event string // EventPush, EventSync*
Payload []byte // JSON body as sent on the wire
}
Delivery is one queued webhook delivery: the payload is the fully rendered JSON body, frozen at enqueue time; only the signature is recomputed per attempt. Queue implementations (internal/jobs) persist exactly these three fields.
type MetaWebhookStore ¶
type MetaWebhookStore struct{ Store meta.EventingStore }
MetaWebhookStore adapts the durable meta.EventingStore webhook rows to this package's WebhookStore contract (type translation only — meta's sentinel errors, notably meta.ErrNotFound, already match what consumers here and in the CRUD handlers expect, so errors pass through untouched).
func (MetaWebhookStore) CreateWebhook ¶
func (MetaWebhookStore) DeleteWebhook ¶
func (s MetaWebhookStore) DeleteWebhook(ctx context.Context, org, id string) error
func (MetaWebhookStore) GetWebhook ¶
func (MetaWebhookStore) ListWebhooks ¶
type PushPayload ¶
type PushPayload struct {
Type string `json:"type"` // always EventPush (issue #367)
Repository RepositoryRef `json:"repository"`
Ref string `json:"ref"`
Before string `json:"before"` // 40 zeros for ref creation
After string `json:"after"` // 40 zeros for ref deletion
CustomerID string `json:"customer_id"`
Org string `json:"org"` // same value as CustomerID (issue #367)
PushedAt string `json:"pushed_at"` // RFC 3339 UTC
}
PushPayload is the docs/reference/webhooks.md `push` event body. Every field is sent non-empty — vendor SDKs reject payloads with any empty field.
func NewPushPayload ¶
func NewPushPayload(org string, repo meta.Repo, refName, before, after string, pushedAt time.Time) PushPayload
NewPushPayload builds the push body for one won CAS. before/after come straight from CASRef's old/new, which already use ref.ZeroSHA for create/delete — exactly the docs/reference/webhooks.md wire convention. customer_id and org are both the owning org's name — the same string the JWT `iss` claim carries (docs/reference/webhooks.md; vendor SDKs compare it against iss). Upstream defines org as that iss and deprecates customer_id; the served-org gate accepts only this iss.
type RefStore ¶
type RefStore struct {
ref.RefStore // inner store; every method except CASRef delegates
// contains filtered or unexported fields
}
RefStore decorates a ref.RefStore so every won CASRef on a persistent (non-ephemeral) ref emits one `push` event per registered webhook and pokes the sync seam — the single choke point covering both write surfaces (API handlers and the git receive-pack update hook), which both flow their ref flips through CASRef. Emission happens strictly AFTER the CAS commits and never fails the update: enqueue errors are logged and swallowed (docs/reference/webhooks.md "emit after the ref update commits"). The optional BeforeCAS step runs before the CAS and can refuse it.
func NewRefStore ¶
func NewRefStore(inner ref.RefStore, opts RefStoreOptions) *RefStore
NewRefStore wraps inner with push-event emission per opts. inner is additionally wrapped in ref.IdempotentCAS, so an ambiguous CAS outcome whose update actually committed is reconciled to a win BELOW this decorator — the push event for it is emitted, not silently dropped.
func (*RefStore) CASRef ¶
CASRef runs BeforeCAS, delegates to the inner store and, on a won update outside the ephemeral namespace, emits the push event + sync poke. Emission uses a cancellation-detached context: the CAS already committed, so a client hanging up mid-response must not lose the event. The inner store is ref.IdempotentCAS-wrapped (see NewRefStore), so a returned error or lost CAS here is already reconciled — skipping emission on it is safe.
type RefStoreOptions ¶
type RefStoreOptions struct {
// Org is the org name owning every repo this store serves (single-org
// self-host mode, same value the serve config / hook env carries).
Org string
// Repos resolves RepoIDs to repo rows (meta.Store satisfies this).
Repos RepoSource
// Webhooks lists the org's registered delivery endpoints.
Webhooks WebhookLister
// EnqueueDelivery hands one delivery to the jobs queue. Adapters wrap
// jobs.Queue.EnqueueWebhookDelivery; failures are logged, never
// propagated (the ref flip already committed).
EnqueueDelivery func(ctx context.Context, d Delivery) error
// EnqueueSync, when non-nil, is invoked once per won non-ephemeral ref
// update with the base RepoID (docs/explanation/domain-model.md invariant 11: pushes to a repo
// with an upstream schedule a sync). Implementations decide whether a
// sync is actually due — upstream row present AND no run currently in
// progress (which also prevents the sync worker's own loopback pushes
// from re-triggering themselves) — and enqueue accordingly.
EnqueueSync func(ctx context.Context, repoID string) error
// BeforeCAS, when non-nil, runs before every non-ephemeral CASRef and
// CASRefGen with the base RepoID. An error refuses the update: the
// inner CAS never runs. The git hook on the local schedule records the
// push's forward intent here (ADR-50), so no accepted write can lose
// it to a crash after the CAS.
BeforeCAS func(ctx context.Context, repoID string) error
// HeldBeforeCAS is BeforeCAS for a writer that holds the ref until its
// CAS returns: it also gets the ref name, and on success returns a
// release, which runs once, right after the inner CAS, also when the
// inner CAS panics. Serve's REST writes on
// the local schedule hold the ref and record the forward intent here
// (ADR-50).
HeldBeforeCAS func(ctx context.Context, repoID, refName string) (release func(), err error)
// Now supplies pushed_at; defaults to time.Now.
Now func() time.Time
// Logger records emission failures; defaults to slog.Default().
Logger *slog.Logger
}
RefStoreOptions configures NewRefStore. Org, Repos, Webhooks, and EnqueueDelivery are required; the rest default sensibly.
type RepoSource ¶
type RepoSource interface {
GetRepoByID(ctx context.Context, org, repoID string) (meta.Repo, error)
}
RepoSource resolves a live repo row by RepoID for payload construction (repository.url, customer_id). meta.Store satisfies it as-is.
type RepositoryRef ¶
type RepositoryRef struct {
ID string `json:"id"`
URL string `json:"url"`
RepoName string `json:"repo_name"`
}
RepositoryRef is the `repository` object embedded in event payloads. RepoName carries the same value as URL: upstream deprecated url in favour of repo_name (issue #367), and both stay on the wire.
type TargetGuard ¶
type TargetGuard struct {
// AllowPrivate admits loopback/private/link-local/ULA delivery targets
// (OPENSTORAGE_WEBHOOK_ALLOW_PRIVATE) for genuinely internal
// deployments. Cloud metadata and addresses that can never be a
// legitimate receiver (unspecified, multicast, broadcast) stay denied,
// and redirects stay refused: the escape hatch relaxes only the private
// receiver classes, not the rest of the policy.
AllowPrivate bool
// LookupNetIP resolves a hostname to candidate addresses; nil uses
// net.DefaultResolver. Tests inject it to simulate DNS rebinding.
LookupNetIP func(ctx context.Context, host string) ([]netip.Addr, error)
// contains filtered or unexported fields
}
TargetGuard decides which network addresses webhook traffic may reach (issue #53). Webhook URLs are attacker-controlled data — any org-level repo:write token can register one — so without a guard, deliveries are a blind-SSRF path from the replicas into loopback, RFC 1918, link-local, and cloud-metadata endpoints.
The zero value is the production default: private-range targets are denied and hostnames resolve through net.DefaultResolver. Enforcement is layered per the issue-#53 triage:
- Registration time (CheckRegistration): fast-feedback courtesy only. Acceptance is NOT a delivery guarantee — DNS can change between registration and delivery.
- Dial time (NewClient): authoritative. The client's dialer re-resolves and vets EVERY candidate address at connect time, then dials only the vetted literals, closing the DNS-rebinding TOCTOU window that URL-time validation leaves open.
func (TargetGuard) CheckHost ¶
func (g TargetGuard) CheckHost(ctx context.Context, host string) error
CheckHost is CheckRegistration's generic twin for non-webhook egress registrations (sync base_repo upstream_host, issue #139): host is a bare hostname or IP literal, already stripped of scheme/port/path by the caller's own shape validation. Same layered semantics — reject denied literals or currently-denied DNS answers as fast feedback, fail OPEN on resolution errors, and never treat acceptance as a promise: the dial-time guard (the sync worker's vetting proxy) is authoritative.
func (TargetGuard) CheckRegistration ¶
func (g TargetGuard) CheckRegistration(ctx context.Context, rawURL string) error
CheckRegistration is the registration-time courtesy check: it rejects URLs whose host is a denied IP literal or currently resolves to a denied address, giving operators fast feedback at POST /webhooks instead of a dead registration that silently never delivers.
It deliberately fails OPEN on resolution errors: registration acceptance is NOT a delivery-reachability promise (the resolver may be partitioned, or the record may change later either way). Dial-time enforcement in NewClient is authoritative.
func (TargetGuard) DialContext ¶
DialContext is the authoritative enforcement point: resolve, vet every candidate, then dial only the vetted literals — handing the hostname to a re-resolving dialer here would reopen the rebinding window vetHost just closed. Exported for the outbound push egress proxy (issue #90), which applies the same dial-time policy to `git push` traffic; policy denials wrap ErrTargetDenied.
func (TargetGuard) NewClient ¶
func (g TargetGuard) NewClient() *http.Client
NewClient builds the delivery client every webhook POST must go through: a 30s overall timeout (a receiver that never responds must not wedge a delivery worker), NO redirect following, and the guarded dialer.
Redirects are refused unconditionally — legitimate webhook receivers answer at their registered URL, and following a redirect would hand the receiver a fresh, unvetted target. A redirect response is therefore a delivery failure with the standard retry semantics.
The transport intentionally ignores HTTP(S)_PROXY: validating the proxy socket would not validate the URL target the proxy later connects to. Operators that require proxy egress must enforce the same destination policy at that proxy rather than bypass this direct-dial guard.
type Webhook ¶
type Webhook struct {
ID string // server-generated "wh_<hex>"
OrgID int64
URL string
Secret string
CreatedAt time.Time // UTC
}
Webhook is one registered delivery endpoint. Secret is the HMAC signing key, stored plaintext because every delivery signs with it (ADR: at-rest secret encryption is out of scope for phase 5). Never log Secret.
type WebhookLister ¶
WebhookLister returns the org's registered webhooks (fan-out targets for one event). Org-scoped by org name, following the meta.Store convention.
type WebhookLookup ¶
WebhookLookup resolves one webhook by ID at delivery time, so every attempt sees the current URL/secret and deliveries for deleted webhooks are dropped. Implementations return meta.ErrNotFound (possibly wrapped) when the webhook no longer exists.
type WebhookStore ¶
type WebhookStore interface {
// CreateWebhook inserts a webhook with a server-generated ID.
CreateWebhook(ctx context.Context, org, url, secret string) (Webhook, error)
// ListWebhooks returns the org's webhooks in registration order.
ListWebhooks(ctx context.Context, org string) ([]Webhook, error)
// GetWebhook returns the webhook with the given ID regardless of org
// (delivery jobs carry only the ID); meta.ErrNotFound when absent.
GetWebhook(ctx context.Context, id string) (Webhook, error)
// DeleteWebhook removes the org's webhook; meta.ErrNotFound when the
// org is unknown or the ID does not belong to it.
DeleteWebhook(ctx context.Context, org, id string) error
}
WebhookStore is the full persistence contract behind the webhook CRUD surface (internal/api/handlers_webhooks.go) and the delivery/fan-out paths. internal/meta implements it on both backends; org-scoped methods key by org name and return meta.ErrNotFound for unknown orgs/IDs, mirroring the frozen meta.Store conventions.