Documentation on WebSub

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Architecture#

Modules#

This is a multi-module repository. Each module is versioned and released on its own, so nothing you do not use ends up in your build.

(repo root)      github.com/Jazzmoon/websub             the protocol, no third party imports
  tests/                                                black box test suite
  tests/conformance/                                    the spec cases, importable by anyone
adapter/gin/     github.com/Jazzmoon/websub/adapter/gin
adapter/echo/    github.com/Jazzmoon/websub/adapter/echo
adapter/fiber/   github.com/Jazzmoon/websub/adapter/fiber
storage/redis/   github.com/Jazzmoon/websub/storage/redis
storage/postgres/
storage/sqlite/
storage/storetest/                                      the shared backend suite
websubtest/      github.com/Jazzmoon/websub/websubtest  in-process hub for your own tests

The protocol implementation lives at the repository root rather than in a named subdirectory, because Go requires a module’s go.mod to physically sit wherever its declared path implies; github.com/Jazzmoon/websub is the bare repo path, so its go.mod has to be the repo root’s go.mod. Every other module here follows the more familiar pattern, where the subdirectory name is also the path suffix.

Design decisions

Mon, 01 Jan 0001 00:00:00 +0000

Design decisions#

Decisions that could reasonably have gone the other way, and why they went this way. If you are about to propose a change to one of these, this is the argument you are arguing against.

Principles#

Core has zero third party dependencies. Only the standard library. Anything pulling in an external module goes in its own module.
Every HTTP facing type implements http.Handler. This is what makes every router adapter possible.
WebSub is the default, PubSubHubbub 0.4 is opt in. The differences live in one table in mode.go, never forked into parallel code paths.
Every exported symbol has a doc comment. Comments explain what is not obvious. A comment restating the line below it is noise; one explaining why the spec demands something is not.

One package, not three#

The three roles share Subscription, Mode, Discovery, Sign, Verify, SubscriptionStore, and every option. Splitting into websub/subscriber, websub/hub, and websub/publisher would mean either a base package that all three import anyway, which is indirection rather than separation, or duplicating WithMode, WithLogger, and WithHTTPClient three times.

Specification notes

Mon, 01 Jan 0001 00:00:00 +0000

Specification notes#

This library implements two specifications that mostly agree:

WebSub, a W3C Recommendation, the default
PubSubHubbub 0.4, its predecessor, behind WithMode(websub.ModePuSH04)

The public API is identical either way. Every difference is a field in the table in mode.go and is looked up rather than branched on at a call site, so the deltas stay auditable against the spec text in one place.

Where they differ#

Behavior	WebSub	PubSubHubbub 0.4
Lease duration	Required. Hubs must enforce expiration and must not issue perpetual leases	Optional. An omitted lease means the subscription never expires
Discovery	`Link` header, then HTML `<link>`, then Atom, then RSS, as a required ordered chain	`Link` header primarily, the rest best effort
Verification	Asynchronous GET challenge, always	Same mechanism, but synchronous verification is tolerated in some deployments

Two of those have visible consequences:

Conformance suite

Mon, 01 Jan 0001 00:00:00 +0000

Conformance suite#

tests/conformance holds the spec cases as an importable package rather than as test files, so anything can replay them.

The core module runs them with no router in between.
Each adapter module runs the same cases through its own wrapper.
An adapter this repo does not ship can import the package and do the same.

Running it#

go test ./tests -run TestConformance -v

Through a specific adapter:

cd adapter/fiber && go test ./... -race -v

How it is put together#

Cases are values, not functions scattered across files:

Writing an adapter

Mon, 01 Jan 0001 00:00:00 +0000

Writing an adapter#

An adapter’s whole job is turning an http.Handler into whatever handler type a framework wants. It contains no protocol logic, and it never should. If you find yourself parsing a hub. parameter in an adapter, the fix belongs in core.

Do you need one at all#

If your router accepts an http.Handler, no. chi, gorilla/mux, and net/http’s own ServeMux all do:

r.Handle("/websub/*", subscriber)                  // chi
r.PathPrefix("/websub/").Handler(subscriber)       // gorilla/mux
mux.Handle("/websub/", subscriber)                 // net/http

No adapter package exists for these, and none will. Publishing empty modules would imply they were needed.

Writing a storage backend

Mon, 01 Jan 0001 00:00:00 +0000

Writing a storage backend#

A hub keeps subscription state behind SubscriptionStore. The default is in memory, which is right for development and single process hubs and wrong for anything that has to survive a restart.

type SubscriptionStore interface {
	Save(ctx context.Context, sub Subscription) error
	Get(ctx context.Context, topic, callback string) (Subscription, error)
	Delete(ctx context.Context, topic, callback string) error
	ListByTopic(ctx context.Context, topic string) ([]Subscription, error)
	Topics(ctx context.Context) ([]string, error)
	ListExpiring(ctx context.Context, before time.Time) ([]Subscription, error)
}

Switching is one line:

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

The contract#

A subscription is identified by the pair (topic, callback). Nothing else is a key, and the pair is not unique on either half alone: one subscriber may hold subscriptions to many topics, and one topic may have many subscribers.

Releasing

Mon, 01 Jan 0001 00:00:00 +0000

Releasing#

This repository holds several Go modules. Each is tagged and released on its own, which is what lets a project depend on adapter/gin without pulling in fasthttp, and on core without pulling in anything at all.

Tags#

Go derives a module’s version from a tag whose prefix is the module’s path relative to the repository root:

Module	Tag
`core`	`v1.2.3`
`adapter/gin`	`adapter/gin/v1.2.3`
`storage/redis`	`storage/redis/v1.2.3`
`websubtest`	`websubtest/v1.2.3`

The core module is the repository root: its go.mod declares github.com/Jazzmoon/websub, the bare repo import path, so its files live directly at the repo root rather than in a named subdirectory (Go requires the two to match), and its tags carry no prefix as a result. Every other module’s go.mod lives in a subdirectory matching its own path suffix.