Documentation
¶
Overview ¶
Package conformance is the suite every messaging.Backend must pass.
It is what makes the backend contract real rather than asserted, and it is the only thing that will catch a second backend quietly meaning something different by "shed" or "bounded". Both shipped backends run it, and when a third arrives the suite is what it is held to: any test it cannot pass is a place the abstraction was wrong rather than a place to add an exception.
What a suite like this is most likely to miss ¶
Everything above is about a backend doing its job. A mutation audit of an earlier version found that a conforming backend could still return a constant zero Depth, declare three overflow policies and implement one, ignore the group name entirely so every competing subscriber shared one pool, replace least-loaded routing with "always the first", and leak every subscription on Stop. Each of those passed ten green cases.
So the suite now makes a backend DO what it declares, and asserts the numbers move rather than merely existing. A capability that lies is worse than one that is absent: absent is handled by degrading at construction, and a lie is a caller who checked, believed the answer, and got something else.
What it deliberately does not assert ¶
Which member of a competing group receives a message, that the split between members is even, or that a degraded member is routed around. A spike measured NATS giving 10/10, 11/9 and 12/8 on identical input, and losing a wedged member's whole share while a healthy member idled. Asserting any of those would encode one backend's behaviour as the contract.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run executes the whole suite against a backend that does not survive a restart.
A backend declaring SurvivesRestart must be run through RunDurable instead, and Run refuses it: a declared capability the suite cannot exercise is a promise nobody keeps, which is exactly what this suite exists to prevent.
Types ¶
type Binder ¶
type Binder interface {
// OpenUnbound builds a backend bound to a stream that does NOT exist, and
// returns the name it will fail to find.
OpenUnbound(t *testing.T) (messaging.Backend, string)
}
Binder is implemented by a fixture whose backend binds to a stream that must already exist (0005 D9). A backend whose storage is its own — a directory, a table — has nothing to bind and does not implement it.
type Durable ¶
type Durable interface {
// Open builds a backend over the fixture's storage. Every call returns a
// fresh backend; the storage is shared.
Open(t *testing.T) messaging.Backend
// Restart stops the storage and starts it again, keeping its contents.
// Every backend from a previous Open is invalid afterwards. For a broker
// this restarts the process; for a file-backed store it may do nothing
// beyond invalidating open handles, because files persist on their own.
//
// For a managed service the fixture cannot restart — SQS is one — Restart
// restarts everything the fixture can, every client and backend, and the
// fixture's documentation says so. The reasoning above holds for storage a
// fixture owns; a service's durability across its own restarts is the
// vendor's claim, and what the rows prove there is that a CONSUMER's
// restart loses no message and no attempt count, which is the claim a
// consumer can act on (0007 D13).
Restart(t *testing.T)
}
Durable is what a backend declaring SurvivesRestart gives the suite: a way to build a backend over storage the fixture controls, and to restart that storage between two backends.
Why a fixture rather than a Restart on the backend ¶
The suite's New builds an independent backend on every call, which is right for every row that does not involve a restart and useless for the two that do: "messages survive a restart" is a question about the STORAGE — a broker process, a directory, a database — not about the adapter that talks to it. Restarting the adapter while the storage keeps running proves only that reconnection works, which another row already covers. So the fixture owns the storage: it creates it, it builds backends over it, it bounces it, and it tears it down (issue 3).
type Foreign ¶ added in v0.9.0
type Foreign interface {
// SendUnreadable sends one message of kind where the source subscribed
// with spec reads, and reports whether it could: a backend reading one
// format has no Ambiguous message.
SendUnreadable(t *testing.T, spec messaging.SourceSpec, kind UnreadableKind) bool
}
Foreign is implemented by a fixture that can put a message where a source reads, as a producer outside the bus would (0015 D8).
The bus's own Publish cannot write a message nobody can read, so only the fixture, which knows its broker and the formats its backend reads, can. A suite run without one skips the unreadable-message row, which is how a backend that cannot carry such a message opts out.
type Granular ¶
type Granular interface {
// LeaseGranularity is the smallest AckWait the backend can honour.
LeaseGranularity() time.Duration
}
Granular is implemented by a fixture whose backend keeps its lease in units coarser than a millisecond — SQS's visibility timeout is whole seconds — so the lease row's timings scale rather than asking for what cannot exist.
type Immutable ¶
type Immutable interface {
// ImmutableFields names the fields of Pattern, StartAt, MaxDeliver and
// AckWait that the backend refuses to see changed on reopen.
ImmutableFields() []string
}
Immutable is implemented by a fixture whose backend can refuse only some of the identity's fields on reopen. A log-shaped backend holds the whole identity and refuses all four; a queue-shaped one holds a queue, and its pattern is the operator's binding, its StartAt does not exist, and its AckWait is the adapter's own (0007 D10, 0008 D10, 0009 D10). A fixture that does not implement it is held to all four.
type Killable ¶ added in v0.2.0
type Killable interface {
// Kill takes the link out from under the source subscribed with this spec.
// It returns once the broker has acted, so the row does not race it.
Kill(t *testing.T, spec messaging.SourceSpec)
}
Killable is implemented by a fixture that can take a source's transport away from it, the way an operator or a broker would: cancelling a consumer, deleting a queue, dropping a connection (0010 D7).
It is the fixture's job rather than the backend's, because killing a link is an operator's act and the fixture is the operator everywhere else in this suite. A suite run without one skips the row, which is how a backend with no link to lose opts out.
type New ¶
New constructs a fresh, unstarted backend. The suite calls it once per test, because a suite that shares one backend between tests is measuring the leftovers of the previous one.
type Option ¶ added in v0.2.0
type Option func(*options)
Option configures a suite run.
func WithForeign ¶ added in v0.9.0
WithForeign supplies the seam for the unreadable-message row (0015 D8). Without it that row is skipped, and every other row is unaffected.
func WithKillable ¶ added in v0.2.0
WithKillable supplies the seam for the link-death row (0010 D7). Without it that row is skipped, and every other row is unaffected.
func WithSlowPublishes ¶ added in v0.8.0
func WithSlowPublishes() Option
WithSlowPublishes is for a backend whose every publish waits on its broker's durable write, such as Artemis. The two volume rows then publish less, still four times the bound, so a slow runner stays inside the package timeout (0008 D15).
type UnreadableKind ¶ added in v0.9.0
type UnreadableKind int
UnreadableKind is the way a message fails envelope.Read.
const ( // Unclaimed is a message no format the backend reads claims. Unclaimed UnreadableKind = iota // Ambiguous is a message two of them claim. Ambiguous // Malformed is a message one of them claims and cannot decode. Malformed )
func (UnreadableKind) String ¶ added in v0.9.0
func (k UnreadableKind) String() string