websub

WebSub

The WebSub and PubSubHubbub 0.4 toolkit Go deserves. Subscriber, publisher, hub. Plugs into any router. Built by daily users of WebSub.

go get github.com/Jazzmoon/websub

Why this one

• No dependencies. The core module imports nothing outside the standard library. Routers and storage backends are separate modules, so you pull in only what you use.
• Every HTTP type is an http.Handler. It mounts on net/http, chi, and gorilla/mux with no glue at all. Adapters for gin, echo, and fiber are separate modules for the frameworks that need one.
• Both specs, one API. WebSub by default, PubSubHubbub 0.4 behind WithMode. The differences live in one file rather than two code paths.
• Documented. Every exported symbol has a doc comment, with the spec section linked wherever the behavior is not obvious.

Subscriber

package main

import (
 "context"
 "log"
 "net/http"

 "github.com/Jazzmoon/websub"
)

func main() {
 sub, err := websub.NewSubscriber("https://example.com/websub/")
 if err != nil {
  log.Fatal(err)
 }

 sub.OnNotify(func(s *websub.Subscription, contentType string, body []byte) {
  log.Printf("%s published %d bytes of %s", s.Topic, len(body), contentType)
 })

 // Each subscription gets its own callback below this prefix, so mount
 // the handler on the prefix rather than an exact path.
 http.Handle("/websub/", sub)
 go http.ListenAndServe(":8080", nil)

 // Discovers the topic's hub from its Link headers, then subscribes.
 pending, err := sub.Subscribe(context.Background(), "https://example.org/feed",
  websub.WithSecret("a-random-secret"))
 if err != nil {
  log.Fatal(err)
 }

 // The hub verifies out of band by calling back. Await waits for that.
 active, err := sub.Await(context.Background(), pending)
 if err != nil {
  log.Fatal(err)
 }
 log.Printf("subscribed to %s until %s", active.Topic, active.ExpiresAt)

 select {}
}

When a secret is set, OnNotify runs only for content whose X-Hub-Signature verifies. Anything else is dropped and logged.

Publisher

A publisher does not serve content itself. It tells subscribers where your hub is, and tells the hub when your content changed.

pub, err := websub.NewPublisher("https://example.com",
 websub.WithHubs("https://hub.example.com/"))

// Middleware attaches the discovery headers to whatever already serves the
// topic, so a subscriber can find the hub.
http.Handle("/feed", pub.Middleware("/feed", feedHandler))

// An empty body is a ping: the hub fetches the topic itself.
err = pub.Publish(ctx, "/feed", "", nil)

// Or hand the hub the content directly, for a topic it cannot reach.
err = pub.Publish(ctx, "/feed", "application/atom+xml", body)

Hub

hub, err := websub.NewHub("https://example.com/hub")

// Only this hub knows which topics it is willing to serve.
hub.AddValidator(func(sub *websub.HubSubscription) (bool, string) {
 if !strings.HasPrefix(sub.Topic, "https://example.com/") {
  return false, "this hub only serves example.com"
 }
 return true, ""
})

http.Handle("/hub", hub)

The hub verifies every subscription out of band, clamps leases to bounds you set, signs deliveries, retries failures with backoff, and drops expired subscriptions. AddSniffer gives you a copy of everything published, for archiving or metrics. Shutdown waits for in-flight verification and delivery.

Routers

chi and gorilla/mux accept http.Handler natively, so there is no adapter package to install for them. gin, echo, and fiber each get a thin wrapper module, and each replays the full conformance suite below through its own wrapper rather than trusting the translation by inspection.

Storage

The hub keeps subscription state in a SubscriptionStore. The built-in implementation is in memory, which is right for development and wrong for anything that has to survive a restart:

hub, err := websub.NewHub("https://example.com/hub", websub.WithStore(store))

Durable backends are separate modules, each validated against the same storage/storetest conformance suite so switching between them is a one line change:

store, err := websubredis.Open(ctx, "redis://localhost:6379/0")
// or: websubpostgres.Open(ctx, os.Getenv("DATABASE_URL"))
// or: websubsqlite.Open(ctx, "file:websub.db")

hub, err := websub.NewHub("https://example.com/hub", websub.WithStore(store))

Spec conformance

Every box below is a case in tests/conformance, run against both WebSub and PubSubHubbub 0.4. It is written to be replayed through a wrapped handler too, which is how the gin, echo, and fiber adapters are held to the same standard rather than trusted by inspection.

Subscriber cases

• Discovery from Link headers, HTML <link>, Atom, and RSS, in that priority order, including multiple hubs, combined rel values, and relative URLs resolved against the URL discovery finished at
• hub.topic is the self URL found during discovery, not the URL the request started at
• Subscription parameters: hub.callback, hub.mode, hub.topic, hub.lease_seconds, hub.secret, with the 200 byte secret limit
• Verification of intent, echoing hub.challenge with a safe media type
• 404 for a verification request naming an unrecognized topic, mode, or callback
• The lease the hub grants wins over the lease requested
• Unsubscribe round trip
• Denial notification, with hub.reason surfaced as an error
• X-Hub-Signature over SHA-1, SHA-256, SHA-384, SHA-512
• Unsigned or mismatched content dropped locally, still acknowledged with a 2xx so the hub does not retry it
• Leases renewed before they lapse, reusing the same callback so the hub overrides the subscription rather than adding a second one

Publisher cases

• Advertises one rel=self and at least one rel=hub, discoverable by a real subscriber
• Both publishing methods: ping, and posting content directly
• hub.url and hub.topic both sent, for hubs that read either name
• Trailing slash topic URLs stay distinct
• Every advertised hub is notified, and one failing does not stop the others

Hub cases

• 202 for a valid subscription request, 4xx for a malformed one
• Verification of intent with hub.mode, hub.topic, hub.challenge, and hub.lease_seconds; nothing is stored unless the subscriber confirms
• Requested leases clamped to the hub's bounds; no perpetual leases under WebSub, permitted under 0.4
• Re-subscribing overrides the previous subscription rather than duplicating it
• Content distribution carries rel=hub and rel=self Link headers and the topic's own content type
• X-Hub-Signature generated for subscriptions with a secret
• Validators deny with a reason, delivered as a denial notification
• Expired subscriptions are neither delivered to nor kept
• Both accepted publishing methods

Testing your own code

websubtest runs a real in-process hub and publisher, so code that subscribes to or publishes topics can be tested against the actual protocol instead of a mock:

func TestMySubscriber(t *testing.T) {
 hub := websubtest.NewHub(t)
 topic := websubtest.NewPublisher(t, hub, "application/atom+xml", "<feed/>")

 sub, err := websub.NewSubscriber(callbackURL)
 // ... mount sub, then:
 active, err := sub.Subscribe(ctx, topic.URL())

 topic.SetContent("application/atom+xml", "<feed>updated</feed>")
 hub.Publish(t, topic.URL())
}

go get github.com/Jazzmoon/websub/websubtest

Examples

Runnable programs for every role and router are in examples, each a self-contained main.go.

Packages

Every module below is tagged and versioned independently of core.

See releasing.md for how tags and changelogs work across the modules.

Documentation

Guides and design notes are at websub.jazzmoon.ca. API reference is on pkg.go.dev. Every exported symbol has a doc comment, with the spec section linked wherever the behavior is not obvious.

Contributing

See CONTRIBUTING.md.

Security issues go through SECURITY.md, not the public issue tracker.

License

Apache-2.0. See LICENSE.