Documentation
¶
Overview ¶
Package core is the runtime-agnostic anyhook delivery engine: fan-out, signing (via an injected port), delivery, jittered-backoff retry, per-endpoint circuit-breaking, and dead-lettering. It mirrors packages/core/src in the TypeScript implementation, which remains the source of truth for behavior.
Every adapter dependency (durable storage, message transport, scheduling, outbound HTTP, webhook signing, SSRF policy, clock, randomness) is expressed as a port (interface) in this file; core itself imports no broker or crypto SDKs, matching the TS "zero-runtime-dep" goal (G1).
Index ¶
- Constants
- Variables
- func CapacityFor(rateLimitPerSec float64) float64
- func DeriveIdempotencyKey(e SendEvent) string
- func FullJitter(baseMs int64, rng Rng) int64
- func NewID(prefix string, rng Rng) string
- func NextDelayMs(cfg RetryConfig, attemptNo int, rng Rng, retryAfterMs *int64) (int64, bool)
- func Subscribes(endpoint Endpoint, eventType string) bool
- type Attempt
- type AttemptOutcome
- type AttemptStatus
- type CircuitConfig
- type CircuitGate
- type CircuitRecord
- type CircuitState
- type Clock
- type CreateEndpointInput
- type CreateEndpointResult
- type DeliverPorts
- type DeliveryQuery
- type DeliveryResult
- type DeliveryRow
- type DlqEntry
- type DlqReason
- type Endpoint
- type Engine
- type EngineOptions
- type EventRecordResult
- type HTTPClient
- type HTTPResult
- type Message
- type MessageStatus
- type Outcome
- type RateBucket
- type Receipt
- type RetryConfig
- type Rng
- type Scheduler
- type SendEvent
- type StateStore
- type Telemetry
- type Transport
- type URLCheckResult
- type URLPolicy
- type URLPolicyOptions
- type UpdateEndpointPatch
- type WebhookSigner
Constants ¶
const DefaultCooldownMs int64 = 30_000
DefaultCooldownMs is the default circuit-breaker cooldown before an open circuit transitions to half-open.
const DefaultFailureThreshold = 5
DefaultFailureThreshold: open the circuit after 5 consecutive failed messages.
const DefaultIDLength = 20
DefaultIDLength is the number of random characters NewID generates after the prefix.
const DefaultMaxPayloadBytes int64 = 256 * 1024
DefaultMaxPayloadBytes caps the JSON-encoded event payload size.
const DefaultTimeoutMs int64 = 15_000
DefaultTimeoutMs is the default per-delivery HTTP timeout.
const RetryAfterCapMs int64 = 21_600_000
RetryAfterCapMs caps a receiver-supplied Retry-After so it cannot push delivery out arbitrarily far. 6h, the largest schedule step.
const Version = "0.1.0"
Version is the anyhook Go module version. It tracks the TypeScript package numbering; this Go port ships at M1 parity (core delivery engine + signing + testing harness), matching the TS packages/core, packages/signing, and packages/testing behavior.
Variables ¶
var DefaultRetryConfig = RetryConfig{ScheduleMs: DefaultScheduleMs}
DefaultRetryConfig is the default RetryConfig using DefaultScheduleMs.
var DefaultScheduleMs = []int64{
5_000, 30_000, 120_000, 600_000, 1_800_000, 3_600_000, 10_800_000, 21_600_000,
}
DefaultScheduleMs is the default backoff schedule: ~5s, 30s, 2m, 10m, 30m, 1h, 3h, 6h (8 attempts, ~12h total) then DLQ.
Functions ¶
func CapacityFor ¶
CapacityFor returns the bucket capacity (max burst) for a given rate: up to ~1s worth of tokens, minimum 1. Mirrors TS capacityFor (packages/core/src/policy/ratelimit.ts).
func DeriveIdempotencyKey ¶
DeriveIdempotencyKey derives a stable idempotency key from the event when the producer omits one. Same (tenant, type, payload) -> same key; any difference -> a different key.
func FullJitter ¶
FullJitter returns a uniform random delay in [0, baseMs). Avoids thundering herds when a receiver recovers.
func NewID ¶
NewID generates a prefixed id (e.g. "msg_9f3k..."). Entropy comes from the injected Rng (deterministic in tests).
func NextDelayMs ¶
NextDelayMs returns the delay (ms) before the given 0-based attempt, and true, or (0, false) when the schedule is exhausted (caller should DLQ).
When retryAfterMs is non-nil (429/503 Retry-After), it wins but is capped by RetryAfterCapMs. Otherwise full jitter is applied over [0, base) for that attempt's base delay.
func Subscribes ¶
Subscribes reports whether an endpoint subscribes to an event type. Supports exact match, the "*" wildcard, and dot-prefixed wildcards such as "payment.*" (matches "payment.succeeded").
Types ¶
type Attempt ¶
type Attempt struct {
MessageID string
EndpointID string
Tenant string
EventType string
// AttemptNo is the 0-based attempt index.
AttemptNo int
Status AttemptStatus
LatencyMs int64
// RespSnippet is a truncated response body snippet (secrets/configured fields redacted).
RespSnippet string
Ts int64
Outcome AttemptOutcome
}
Attempt is one HTTP POST try for a message. Append-only in the delivery log. Mirrors TS Attempt (packages/core/src/types/attempt.ts).
type AttemptOutcome ¶
type AttemptOutcome string
AttemptOutcome is the terminal classification recorded against an Attempt (distinct from Outcome, which classifies a single transport result before it's known whether a retry follows).
const ( AttemptDelivered AttemptOutcome = "delivered" AttemptRetried AttemptOutcome = "retried" AttemptDead AttemptOutcome = "dead" )
type AttemptStatus ¶
type AttemptStatus int
AttemptStatus is a delivery attempt's transport status: either a real HTTP status code (>= 100) or one of the non-numeric sentinels below.
TS models this as `number | 'timeout' | 'network'`; Go has no built-in union type, so negative sentinel values stand in for the two non-numeric cases (real HTTP status codes are always non-negative).
const ( // StatusTimeout indicates the request exceeded its deadline. StatusTimeout AttemptStatus = -1 // StatusNetwork indicates a network-level failure (e.g. connection refused, DNS, SSRF refusal). StatusNetwork AttemptStatus = -2 )
func (AttemptStatus) IsCode ¶
func (s AttemptStatus) IsCode() bool
IsCode reports whether s represents a real HTTP status code (as opposed to the timeout/network sentinels).
func (AttemptStatus) String ¶
func (s AttemptStatus) String() string
String renders "timeout", "network", or the decimal status code.
type CircuitConfig ¶
type CircuitConfig struct {
// FailureThreshold: consecutive failed messages before the circuit opens (default 5).
FailureThreshold int
// CooldownMs: cooldown before an open circuit transitions to half-open.
CooldownMs int64
}
CircuitConfig is circuit-breaker tuning. Engine-level in M1 (per-endpoint override is a post-v1 option, matching TS).
type CircuitGate ¶
CircuitGate is the result of CanAttempt.
func CanAttempt ¶
func CanAttempt(rec CircuitRecord, now int64) CircuitGate
CanAttempt reports whether a delivery may be attempted now:
- closed -> allowed (not a probe)
- open -> allowed only once the cooldown elapsed, as a single probe (caller then calls ToHalfOpen)
- half-open -> allowed as the single probe
type CircuitRecord ¶
type CircuitRecord struct {
State CircuitState
ConsecutiveFailures int
// OpenedAt is the epoch-ms the circuit opened; non-nil only while State == CircuitOpen.
OpenedAt *int64
CooldownMs int64
}
CircuitRecord is the per-endpoint circuit-breaker state persisted in the durable StateStore. Mirrors TS CircuitRecord.
func InitialCircuit ¶
func InitialCircuit(cooldownMs int64) CircuitRecord
InitialCircuit returns a fresh, closed circuit with the given cooldown.
func OnFailure ¶
func OnFailure(rec CircuitRecord, now int64, threshold int) CircuitRecord
OnFailure applies a delivery failure. A failure in half-open re-opens immediately and resets the cooldown clock. Otherwise it increments the consecutive-failure count and opens once it reaches threshold.
func OnSuccess ¶
func OnSuccess(rec CircuitRecord) CircuitRecord
OnSuccess applies a delivery success: reset to closed.
func ToHalfOpen ¶
func ToHalfOpen(rec CircuitRecord) CircuitRecord
ToHalfOpen transitions an open circuit whose cooldown elapsed into half-open.
type CircuitState ¶
type CircuitState string
CircuitState is the per-endpoint circuit-breaker state.
const ( CircuitClosed CircuitState = "closed" CircuitOpen CircuitState = "open" CircuitHalfOpen CircuitState = "half-open" )
type Clock ¶
type Clock interface {
Now() int64
}
Clock is a monotonic-ish wall clock (epoch ms). Injected for deterministic tests.
type CreateEndpointInput ¶
type CreateEndpointInput struct {
Tenant string
URL string
EventTypes []string
Description string
RateLimit *float64
}
CreateEndpointInput is the input to StateStore.CreateEndpoint.
type CreateEndpointResult ¶
CreateEndpointResult is returned by StateStore.CreateEndpoint. The secret is returned once, matching the TS "secret returned only at creation" contract (G10).
type DeliverPorts ¶
type DeliverPorts struct {
HTTP HTTPClient
Signer WebhookSigner
URLPolicy URLPolicy
Clock Clock
TimeoutMs int64
// SnippetLimit caps the response snippet stored in the delivery log. 0 means the default (512).
SnippetLimit int
}
DeliverPorts are the ports DeliverOnce needs.
type DeliveryQuery ¶
type DeliveryQuery struct {
Tenant string
EndpointID string
EventType string
Status MessageStatus
Before *int64
After *int64
Limit int
}
DeliveryQuery is the query shape for the delivery-log surface. Zero values mean "unset" for every optional field (Status == "", Before/After == nil, Limit == 0).
type DeliveryResult ¶
type DeliveryResult struct {
Status AttemptStatus
Outcome Outcome
LatencyMs int64
RespSnippet string
// RetryAfterMs is the parsed, capped Retry-After in ms (429/503 only), when present.
RetryAfterMs *int64
// BlockedBySSRF is true when the target was refused by the URL policy (SSRF), before any POST.
BlockedBySSRF bool
}
DeliveryResult is the outcome of one DeliverOnce call.
func DeliverOnce ¶
func DeliverOnce(ctx context.Context, m Message, endpoint Endpoint, p DeliverPorts) DeliveryResult
DeliverOnce performs ONE delivery POST for a message. Assumes the caller already checked the circuit. Signs the body (Standard Webhooks; "webhook-id" = the stable messageId so retries dedupe), enforces the URL policy first (SSRF -> permanent), and classifies the transport outcome.
type DeliveryRow ¶
DeliveryRow pairs a message with its full attempt history.
type DlqReason ¶
type DlqReason string
DlqReason is a machine-readable reason a message landed in the DLQ.
const ( // ReasonExhaustedRetries: retry schedule ran out. ReasonExhaustedRetries DlqReason = "exhausted_retries" // ReasonPermanent4xx: receiver returned a non-retryable 4xx/3xx. ReasonPermanent4xx DlqReason = "permanent_4xx" // ReasonBlockedSSRF: target refused by the URL/SSRF policy (never delivered). ReasonBlockedSSRF DlqReason = "blocked_ssrf" // ReasonEndpointGone: endpoint was deleted/disabled after the message was enqueued. ReasonEndpointGone DlqReason = "endpoint_gone" // ReasonCircuitOpenExpired is reserved for a future "parked past max retention" path (not emitted in M1). ReasonCircuitOpenExpired DlqReason = "circuit_open_expired" )
type Endpoint ¶
type Endpoint struct {
EndpointID string
Tenant string
URL string
// EventTypes is the set of subscribed event types; an event fans out to
// endpoints subscribed to its type (see Subscribes).
EventTypes []string
Description string
Disabled bool
// RateLimit is an optional per-endpoint delivery rate limit
// (deliveries/sec). Nil means unset (no limit configured).
RateLimit *float64
CreatedAt int64
// Secrets holds the endpoint's active signing secret(s). Secrets[0] is
// primary; a second entry exists during a rotation window.
Secrets []string
}
Endpoint is a customer-registered delivery destination, scoped to a tenant. Mirrors TS Endpoint (packages/core/src/types/endpoint.ts).
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the runtime-agnostic webhook delivery engine. Producers call Send; the engine fans out, signs, delivers, retries with jittered backoff, circuit-breaks dead endpoints, and dead-letters exhausted messages. All durable state lives behind the injected ports (G1/G2).
func NewEngine ¶
func NewEngine(opts EngineOptions) *Engine
NewEngine builds an Engine from EngineOptions, applying defaults for every unset optional field.
func (*Engine) ProcessMessage ¶
ProcessMessage delivers one message once, then advances its independent retry/circuit/DLQ state. Called by the transport subscription (a worker) -- one message can never affect another (G3).
type EngineOptions ¶
type EngineOptions struct {
Transport Transport
State StateStore
Scheduler Scheduler
HTTP HTTPClient
// Signer is injected so package core stays zero-runtime-dep (G1); build
// one from package signing's CoreSigner.
Signer WebhookSigner
// Telemetry is an optional observability sink (§11); nil -> NoopTelemetry.
Telemetry Telemetry
URLPolicy URLPolicy // nil -> DefaultURLPolicy(URLPolicyOptions{})
Clock Clock // nil -> wall clock
Rng Rng // nil -> math/rand-backed
Retry *RetryConfig
Circuit *CircuitConfig
MaxPayloadBytes int64 // 0 -> DefaultMaxPayloadBytes
TimeoutMs int64 // 0 -> DefaultTimeoutMs
}
EngineOptions configures a new Engine.
type EventRecordResult ¶
type EventRecordResult struct {
// IsNew is false if the (tenant, idemKey) pair was already accepted.
IsNew bool
EventID string
MessageCount int
}
EventRecordResult is returned by StateStore.RecordEvent.
type HTTPClient ¶
type HTTPClient interface {
Post(ctx context.Context, url string, body string, headers map[string]string, timeoutMs int64) HTTPResult
}
HTTPClient is the outbound HTTP capability. Adapters enforce SSRF/redirect policy at connection time and translate transport failures into HTTPResult{Status: StatusTimeout | StatusNetwork} rather than returning a Go error — this mirrors the TS port, whose `post()` never rejects.
type HTTPResult ¶
type HTTPResult struct {
Status AttemptStatus
Body string
Headers map[string]string
}
HTTPResult is the result of a single delivery POST. Headers uses lowercased keys so the engine can honor Retry-After. Status is either a real HTTP status code or one of the AttemptStatus sentinels (StatusTimeout, StatusNetwork).
type Message ¶
type Message struct {
MessageID string
Tenant string
EndpointID string
EventID string
EventType string
Payload json.RawMessage
// AttemptNo is the 0-based attempt index into the retry schedule.
AttemptNo int
Status MessageStatus
// NextAttemptAt is the epoch-ms of the next scheduled attempt, set when
// Status == StatusRetrying.
NextAttemptAt *int64
CreatedAt int64
}
Message is one (event x endpoint) delivery obligation. Fan-out turns one event into N messages, each with INDEPENDENT retry/circuit state (the key isolation invariant, G3). Mirrors TS Message (packages/core/src/types/message.ts).
type MessageStatus ¶
type MessageStatus string
MessageStatus is the delivery status for one message.
const ( // StatusPending: accepted, not yet attempted. StatusPending MessageStatus = "pending" // StatusDelivering: attempt in flight. StatusDelivering MessageStatus = "delivering" // StatusDelivered: received a 2xx. StatusDelivered MessageStatus = "delivered" // StatusRetrying: transient failure, scheduled for a future attempt. StatusRetrying MessageStatus = "retrying" // StatusBlocked: endpoint circuit is open; parked, not counted as an attempt. StatusBlocked MessageStatus = "blocked" // StatusDead: moved to the DLQ (exhausted or permanent failure). StatusDead MessageStatus = "dead" )
type Outcome ¶
type Outcome string
Outcome is the classification of a single delivery attempt's transport status.
func ClassifyOutcome ¶
func ClassifyOutcome(status AttemptStatus) Outcome
ClassifyOutcome classifies a delivery attempt's transport status:
- 2xx -> delivered
- 3xx -> permanent (redirects are not followed; a redirect on a webhook target is misconfiguration)
- 429 -> retryable
- other 4xx -> permanent (the receiver rejected it; retrying won't help)
- 5xx -> retryable
- timeout / network -> retryable
- <200 (unexpected) -> retryable
type RateBucket ¶
type RateBucket struct {
// Tokens is the available delivery tokens (fractional).
Tokens float64
// LastRefillMs is the epoch-ms the bucket was last refilled.
LastRefillMs int64
}
RateBucket is per-endpoint token-bucket rate-limit state persisted in the durable StateStore. Mirrors TS RateBucket (packages/core/src/types/endpoint.ts).
func ConsumeToken ¶
func ConsumeToken(bucket RateBucket, rateLimitPerSec float64, now int64) (allowed bool, next RateBucket, retryAfterMs int64)
ConsumeToken refills bucket for elapsed time, then tries to consume one delivery token. When empty, it returns allowed=false with retryAfterMs set to the time until the next token is available -- the caller throttles by rescheduling the message (never dropping it). rateLimitPerSec is deliveries/second. Mirrors TS consumeToken.
func InitialBucket ¶
func InitialBucket(rateLimitPerSec float64, now int64) RateBucket
InitialBucket returns a fresh, full bucket for an endpoint's rate limit.
type Receipt ¶
type Receipt struct {
EventID string
// Accepted is always true for a successfully returned Receipt; Send
// returns an error instead of a false value on failure (idiomatic Go, in
// place of the TS `accepted: true` literal type).
Accepted bool
// MessageCount is the number of matched endpoints at acceptance time. 0 is
// valid and not an error.
MessageCount int
}
Receipt is returned by Engine.Send once the event is durably accepted. It never blocks on delivery (G5).
type RetryConfig ¶
type RetryConfig struct {
ScheduleMs []int64
}
RetryConfig is the retry backoff configuration. Base delays in ms; full jitter is applied per attempt (see NextDelayMs). Length of ScheduleMs is the max attempts before DLQ.
type Rng ¶
type Rng interface {
Next() float64
}
Rng is a uniform random source in [0, 1). Injected so jitter/ids are deterministic in tests.
type Scheduler ¶
Scheduler owns "attempt this message again at time T" (the state store is the schedule).
type SendEvent ¶
type SendEvent struct {
// Type is the dot-namespaced event type, e.g. "payment.succeeded". Required.
Type string
// Tenant is the isolation scope (the producer's customer). Required.
Tenant string
// Payload is the JSON-serializable event payload. Required.
//
// Represented as json.RawMessage (raw bytes of an already-encoded JSON
// document) rather than `any`, so the wire body used for HMAC signing and
// idempotency-key derivation is byte-for-byte deterministic — the same
// design anyq's Go port uses for message bodies. Callers that hold a Go
// value should json.Marshal it first: `json.Marshal(v)`.
Payload json.RawMessage
// IdempotencyKey is optional; auto-derived from the event when empty (see
// DeriveIdempotencyKey).
IdempotencyKey string
// Metadata carries optional, non-signed routing hints.
Metadata map[string]string
}
SendEvent is a single business occurrence submitted by a producer via Engine.Send. Mirrors TS SendEvent (packages/core/src/types/event.ts).
type StateStore ¶
type StateStore interface {
// RecordEvent implements idempotency: returns IsNew == false if the
// (tenant, idemKey) was already accepted.
RecordEvent(ctx context.Context, tenant, eventID, idemKey string) (EventRecordResult, error)
// FinalizeEvent persists the acceptance result for an idempotency key so
// replays of Send return the same receipt.
FinalizeEvent(ctx context.Context, tenant, idemKey, eventID string, messageCount int) error
CreateEndpoint(ctx context.Context, in CreateEndpointInput) (CreateEndpointResult, error)
// GetEndpoint returns (nil, nil) when the endpoint does not exist for this tenant.
GetEndpoint(ctx context.Context, tenant, endpointID string) (*Endpoint, error)
ListEndpoints(ctx context.Context, tenant string) ([]Endpoint, error)
MatchEndpoints(ctx context.Context, tenant, eventType string) ([]Endpoint, error)
UpdateEndpoint(ctx context.Context, tenant, endpointID string, patch UpdateEndpointPatch) (Endpoint, error)
RotateSecret(ctx context.Context, tenant, endpointID string) (string, error)
DeleteEndpoint(ctx context.Context, tenant, endpointID string) error
PutMessage(ctx context.Context, m Message) error
// GetMessage returns (nil, nil) when the message does not exist for this tenant.
GetMessage(ctx context.Context, tenant, messageID string) (*Message, error)
AppendAttempt(ctx context.Context, a Attempt) error
ListDeliveries(ctx context.Context, q DeliveryQuery) ([]DeliveryRow, error)
GetCircuit(ctx context.Context, tenant, endpointID string) (CircuitRecord, error)
PutCircuit(ctx context.Context, tenant, endpointID string, rec CircuitRecord) error
// GetRateBucket returns the per-endpoint rate-limit token bucket (§10).
// Returns (nil, nil) when never set; the caller seeds a full bucket via
// InitialBucket.
GetRateBucket(ctx context.Context, tenant, endpointID string) (*RateBucket, error)
PutRateBucket(ctx context.Context, tenant, endpointID string, bucket RateBucket) error
AddToDlq(ctx context.Context, m Message, reason DlqReason) error
ListDlq(ctx context.Context, tenant, endpointID string) ([]DlqEntry, error)
}
StateStore is the durable state axis: idempotency, endpoints, messages, attempts, circuit state, DLQ. Every method is tenant-scoped (G7).
type Telemetry ¶
type Telemetry interface {
RecordAttempt(attempt Attempt)
}
Telemetry is an optional observability sink (§11). Called once per delivery attempt with its full record; a backend can emit the attempt as a span and increment delivered/retried/dead counters from Attempt.Outcome. Kept behind this interface so package core never hard-depends on an OpenTelemetry SDK.
var NoopTelemetry Telemetry = noopTelemetry{}
NoopTelemetry is the no-op telemetry sink (the default when none is injected).
type Transport ¶
type Transport interface {
// Send durably enqueues a message for delivery. Returns at durable
// acceptance (G5).
Send(ctx context.Context, m Message) error
// Subscribe registers the delivery handler (the engine's ProcessMessage).
Subscribe(ctx context.Context, handler func(ctx context.Context, m Message) error) error
}
Transport is the durable-buffering axis (anyq). anyhook composes a transport here; endpoint retry state NEVER lives in the transport (G2).
type URLCheckResult ¶
URLCheckResult is the result of a URLPolicy check.
type URLPolicy ¶
type URLPolicy interface {
Check(ctx context.Context, url string) URLCheckResult
}
URLPolicy is the SSRF/scheme policy applied before delivery.
func DefaultURLPolicy ¶
func DefaultURLPolicy(opts URLPolicyOptions) URLPolicy
DefaultURLPolicy is the default deny-list SSRF policy. Refuses non-http(s) schemes and private/loopback/link-local literal-IP targets, including obfuscated IPv4 (decimal/octal/hex) and full-form IPv6 loopback/unspecified forms. Public hostnames are allowed.
KNOWN LIMITATION (accepted, not delegated): this is a static hostname/literal-IP check. A public hostname that resolves to a private IP (DNS rebinding) is NOT caught -- net/http exposes no pre-dial hook here, so adapters cannot fully close this either. Operators on shared infra needing that guarantee must run anyhook behind egress network controls.
type URLPolicyOptions ¶
type URLPolicyOptions struct {
// AllowHTTP allows plain http: targets. Nil means true (the default);
// set a pointer to false to require https.
AllowHTTP *bool
// ExtraDeny lists extra hostnames/IPs to always deny (exact, case-insensitive).
ExtraDeny []string
}
URLPolicyOptions configures DefaultURLPolicy.
type UpdateEndpointPatch ¶
UpdateEndpointPatch is a partial update to an Endpoint. A nil field means "leave unchanged"; EventTypes uses a pointer-to-slice for the same reason (a non-nil pointer to an empty slice means "clear the subscriptions").
type WebhookSigner ¶
type WebhookSigner interface {
Sign(secrets []string, id string, payload string, timestampMs int64) map[string]string
}
WebhookSigner is the Standard Webhooks signing capability, injected so package core stays zero-runtime-dep (G1); package signing provides a structurally-compatible implementation. secrets is the endpoint's active signing secret(s) (more than one during a rotation window).