go

module
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Jul 24, 2026 License: MIT

README

anyhook (Go)

A Go port of anyhook, a runtime-agnostic webhook delivery engine: fan-out, Standard Webhooks signing, jittered-backoff retry, per-endpoint circuit-breaking, and dead-lettering, behind a small set of injected ports (interfaces) so the delivery logic never touches a broker or database SDK directly.

This is a faithful behavioral port of the TypeScript implementation under packages/ (@anyhook/core, @anyhook/signing, @anyhook/testing); the TypeScript code remains the source of truth. This Go module ships at M1 parity: the core delivery engine, SSRF policy, Standard Webhooks signing, and the in-memory testing harness. The AWS runtime adapters (DynamoDB StateStore, SQS/SNS Transport, EventBridge Scheduler) are a separate, later track and are not part of this module yet.

  • Module path: github.com/sns45/anyhook/go
  • Go: 1.23+
  • Version: 0.1.0 (M1 parity: core + signing + testing)

Install

go get github.com/sns45/anyhook/go@latest

core has zero runtime dependencies beyond the standard library (mirrors the TS @anyhook/core "zero-runtime-dep" goal, G1); signing and testing are also standard-library only.

Layout

go/
  core/      ports (interfaces), domain types, retry/jitter/circuit/outcome
             policy, SSRF URL policy, fan-out, id/idempotency-key derivation,
             DeliverOnce, and the Engine (Send + ProcessMessage)
  signing/   Standard Webhooks HMAC-SHA256 sign/verify, secret generation,
             golden-file wire-format tests, interop vector test
  testing/   in-memory Transport/StateStore/Scheduler, a controllable Clock,
             a seeded Rng, a scriptable MockReceiver, and a RunDeliveries
             harness that drives the in-memory delivery loop to quiescence

Quick start

package main

import (
	"context"
	"encoding/json"
	"log"

	"github.com/sns45/anyhook/go/core"
	"github.com/sns45/anyhook/go/signing"
	anyhooktesting "github.com/sns45/anyhook/go/testing"
)

func main() {
	ctx := context.Background()
	clock := anyhooktesting.NewTestClock(0)
	transport := anyhooktesting.NewMemoryTransport()
	scheduler := anyhooktesting.NewMemoryScheduler(transport, clock)
	state := anyhooktesting.NewMemoryStateStore(clock)
	receiver := anyhooktesting.NewMockReceiver(clock)
	receiver.Default = anyhooktesting.ReceiverOK()

	engine := core.NewEngine(core.EngineOptions{
		Transport: transport,
		State:     state,
		Scheduler: scheduler,
		HTTP:      receiver,
		Signer:    signing.CoreSigner{}, // Standard Webhooks signing, from package signing
		Clock:     clock,
		Rng:       anyhooktesting.SeededRng(1),
	})
	if err := engine.Start(ctx); err != nil {
		log.Fatal(err)
	}

	res, err := state.CreateEndpoint(ctx, core.CreateEndpointInput{
		Tenant: "acme", URL: "https://example.com/hook", EventTypes: []string{"order.*"},
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("endpoint %s created, secret %s", res.Endpoint.EndpointID, res.Secret)

	receipt, err := engine.Send(ctx, core.SendEvent{
		Tenant: "acme", Type: "order.created", Payload: json.RawMessage(`{"orderId":"1"}`),
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("accepted %s, fanned out to %d message(s)", receipt.EventID, receipt.MessageCount)

	// Drive the in-memory delivery loop to quiescence (real deployments run a
	// worker off Engine.Start instead).
	if err := anyhooktesting.RunDeliveries(ctx, anyhooktesting.RunOptions{
		Transport: transport, Scheduler: scheduler, Clock: clock,
	}); err != nil {
		log.Fatal(err)
	}
}

A production deployment swaps testing's in-memory ports for durable adapters implementing core.Transport, core.StateStore, and core.Scheduler (e.g. the AWS track's SQS/SNS, DynamoDB, and EventBridge adapters) — the Engine and DeliverOnce code never changes.

Package overview

core
  • Ports: Clock, Rng, HTTPClient, URLPolicy, WebhookSigner, Transport, Scheduler, StateStore — every adapter dependency is injected; core imports no broker/crypto SDK.
  • Types: SendEvent, Receipt, Endpoint, CircuitState / CircuitRecord, Message / MessageStatus, Attempt / DlqReason.
  • Policy: DefaultScheduleMs (5s, 30s, 2m, 10m, 30m, 1h, 3h, 6h), NextDelayMs (full jitter over [0, base), (0, false) once the schedule is exhausted), ClassifyOutcome (2xx delivered; 3xx and non-429 4xx permanent; 429/5xx/timeout/network retryable), and the circuit-breaker state machine (InitialCircuit, OnFailure, OnSuccess, CanAttempt, ToHalfOpen; default threshold 5, cooldown 30s).
  • Fan-out: Subscribes (exact / * / prefix.*), Fanout, DeriveIdempotencyKey, NewID.
  • SSRF: DefaultURLPolicy blocks non-http(s) schemes and loopback/private/link-local targets, including obfuscated IPv4 (decimal/octal/hex) and full-form IPv6 loopback/unspecified literals.
  • Delivery: DeliverOnce (one signed POST + outcome classification) and Engine (Send — durable accept, never blocks on delivery; ProcessMessage — circuit gate, deliver, classify, retry/DLQ/circuit update).
signing

Standard Webhooks (https://www.standardwebhooks.com) HMAC-SHA256 signing: Sign, Signer (multi-secret, space-joined webhook-signature for zero-downtime rotation), Verify (±300s tolerance, timing-safe compare), GenerateSecret/ParseSecret. Sign/Verify are byte-for-byte compatible with the official standardwebhooks libraries — see the interop vector test in signing/sign_test.go.

testing

In-memory MemoryTransport, MemoryStateStore (tenant-scoped, so no query can ever leak across tenants), MemoryScheduler; a controllable TestClock and a seeded SeededRng; a scriptable MockReceiver (ReceiverOK, ReceiverFailThenOK(n), ReceiverPermanent(status), ReceiverTimeout, ReceiverNetwork, ReceiverSlow(ms)); and RunDeliveries, which drains the transport and advances the scheduler/clock in lockstep until the system is quiescent.

Naming note: the package is named testing to mirror the TS @anyhook/testing package and this module's sibling anyq/go layout. A file that needs both the standard library testing package and this one must import this package under an alias, e.g. anyhooktesting "github.com/sns45/anyhook/go/testing" (see go/testing/integration_test.go for the pattern).

Differences from the TypeScript design (idiomatic Go)

  • Errors, not exceptions. Engine.Send / ProcessMessage and every StateStore/Transport/Scheduler method return error; HTTPClient, URLPolicy, and WebhookSigner stay infallible (no error return), mirroring the TS ports, which never reject for these three.
  • context.Context everywhere on I/O-shaped ports, in place of any implicit cancellation.
  • AttemptStatus is an int with two negative sentinels (StatusTimeout = -1, StatusNetwork = -2) standing in for the TS union type number | 'timeout' | 'network' (Go has no built-in union type; real HTTP status codes are always non-negative).
  • json.RawMessage payloads. SendEvent.Payload and Message.Payload are json.RawMessage rather than any, so the wire body used for HMAC signing and idempotency-key derivation is byte-for-byte deterministic — the same design choice anyq's Go port makes for message bodies. Callers holding a Go value marshal it first: json.Marshal(v). DeriveIdempotencyKey builds the idempotency key from tenant + " " + type + " " + string(payload) rather than re-marshaling a Go value (Go's encoding/json sorts map keys, which V8's JSON.stringify does not — matching the TS byte-for-byte here isn't possible in general, and isn't required: no cross-language vector depends on it).
  • signing.Verify returns raw bytes, not any. The TS verify() returns JSON.parse()'d unknown; Verify returns the validated raw body bytes so the caller json.Unmarshals into its own type — more idiomatic Go.
  • Response snippets are byte-sliced, not UTF-16-code-unit-sliced. DeliverOnce's RespSnippet truncates with Go's byte-indexed string slicing; the TS .slice(0, limit) truncates by UTF-16 code unit. Both truncate at the same count, but a truncation that lands mid-multibyte UTF-8 character can differ from a truncation landing mid-surrogate-pair — an edge case only reachable with non-ASCII response bodies right at the 512-byte snippet boundary.
  • No optional/default parameters. Go has none; EngineOptions, URLPolicyOptions, DeliverPorts, etc. use zero-value defaults (0/nil/"" means "unset, apply the default") instead of the TS = defaultValue parameter syntax.
  • Portal/HTTP router deferred. The TS packages/core/src/portal/* (a framework-agnostic Request -> Response router plus EndpointApi / DeliveryApi wrappers around StateStore) is out of scope for this M1 Go port; core.StateStore already exposes every operation those wrappers need, so adding a Go router later is additive, not a breaking change.

Testing

cd go
go test ./...                          # unit + integration tests, no network
go test -race ./...                    # same, with the race detector
go test ./signing/... -run TestGolden -update   # regenerate signing/testdata/*.golden after an intentional wire-format change

Notable coverage:

  • Signing interop vector (signing/sign_test.go): Sign reproduces an exact signature generated by the official-compatible TS signer, proving byte-identical wire compatibility with the standardwebhooks ecosystem.
  • Golden wire-format files (signing/golden_test.go, signing/testdata/*.golden): lock down the full Standard Webhooks header set for a few fixed inputs; the -update flag is a deliberate anyhook addition on top of the TS test suite (which has no golden-file harness).
  • Message-level isolation (G3) and cross-tenant no-leak (G7) (testing/integration_test.go): a healthy and a permanently-failing endpoint fed by the same event must resolve completely independently, and no tenant's state is ever visible under another tenant's key.
  • MockReceiver matrix (testing/integration_test.go): ok → delivered in 1 attempt; failThenOk(1) → delivered in 2; permanent(404) → dead permanent_4xx in 1 attempt; timeout → dead exhausted_retries after the full retry schedule.
  • SSRF hardening (core/urlpolicy_test.go): obfuscated IPv4 (decimal/octal/hex) and full-form IPv6 loopback/unspecified literals are refused, not just the plain dotted-decimal/compressed forms.

Versioning & release tags

This module lives in the go/ subdirectory of a polyglot repo, so its semver tags are prefixed with the subdirectory: go/v0.1.0. go get github.com/sns45/anyhook/go@v0.1.0 resolves it transparently, because the module path ends in /go.

Directories

Path Synopsis
Package aws is the AWS-native Lambda/SQS/DynamoDB runtime for anyhook: it implements the go/core ports (core.Transport, core.StateStore, core.Scheduler, core.HTTPClient) against aws-sdk-go-v2 directly, and wires Lambda handler factories for the ingest, delivery, and retry-sweeper entrypoints.
Package aws is the AWS-native Lambda/SQS/DynamoDB runtime for anyhook: it implements the go/core ports (core.Transport, core.StateStore, core.Scheduler, core.HTTPClient) against aws-sdk-go-v2 directly, and wires Lambda handler factories for the ingest, delivery, and retry-sweeper entrypoints.
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.
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.
Package signing implements Standard Webhooks (https://www.standardwebhooks.com) HMAC-SHA256 signature generation and verification.
Package signing implements Standard Webhooks (https://www.standardwebhooks.com) HMAC-SHA256 signature generation and verification.
Package testing provides in-memory port implementations and deterministic test helpers for exercising the anyhook core Engine without real infrastructure: a controllable Clock, a seeded Rng, an in-memory Transport / StateStore / Scheduler, a scriptable mock HTTP receiver, and a harness that drives the in-memory delivery loop to quiescence.
Package testing provides in-memory port implementations and deterministic test helpers for exercising the anyhook core Engine without real infrastructure: a controllable Clock, a seeded Rng, an in-memory Transport / StateStore / Scheduler, a scriptable mock HTTP receiver, and a harness that drives the in-memory delivery loop to quiescence.

Jump to

Keyboard shortcuts

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