The storage seam and the project-format seam each ship an executable conformance
suite: an outside implementer subclasses a contract, runs it, and a green suite
means the implementation is correct. The warehouse adapter seam, which has the
most implementations by a wide margin, has none. What it has instead is a
per-connector test file that each new connector copies and adapts, plus a block
in the safety suite.
That worked at three connectors and is showing its age at seven. Concretely: the
shared expectations are real but unwritten, so they are discovered by reading
another adapter and are easy to miss. Recent examples, each found by hand rather
than by a contract: profile_estimate must accept an include_blobs keyword
because a caller always passes it; a batched probe must degrade to an empty
result rather than self-escalate past its ceiling; table_metadata must supply
an exact row count where list_objects may supply an estimate; every billed
statement must carry a server-side cap derived from the remaining budget.
A contract in the shipped style would let a new connector, in-tree or out, assert
those in one subclass. It would also make the read-only and cost-gate families
enforceable at the seam rather than restated per connector.
Two things to settle before writing it, and they are the interesting part:
- Which members are mandatory. A large slice of the adapter surface is
probed with getattr and degrades gracefully when absent, which is deliberate
and should stay. The contract has to distinguish "required" from "optional but
must behave this way if present", or it will force implementations of things
that were designed to be skippable.
- How to exercise it without a live warehouse. The storage contract runs
against in-memory implementations. An adapter contract needs the implementer
to supply a fake, which is a real cost to impose, so the contract should be
worth more than the fake costs.
Marking help wanted rather than good first issue: the design question above
is the work, and getting it wrong produces a contract people route around.
The storage seam and the project-format seam each ship an executable conformance
suite: an outside implementer subclasses a contract, runs it, and a green suite
means the implementation is correct. The warehouse adapter seam, which has the
most implementations by a wide margin, has none. What it has instead is a
per-connector test file that each new connector copies and adapts, plus a block
in the safety suite.
That worked at three connectors and is showing its age at seven. Concretely: the
shared expectations are real but unwritten, so they are discovered by reading
another adapter and are easy to miss. Recent examples, each found by hand rather
than by a contract:
profile_estimatemust accept aninclude_blobskeywordbecause a caller always passes it; a batched probe must degrade to an empty
result rather than self-escalate past its ceiling;
table_metadatamust supplyan exact row count where
list_objectsmay supply an estimate; every billedstatement must carry a server-side cap derived from the remaining budget.
A contract in the shipped style would let a new connector, in-tree or out, assert
those in one subclass. It would also make the read-only and cost-gate families
enforceable at the seam rather than restated per connector.
Two things to settle before writing it, and they are the interesting part:
probed with
getattrand degrades gracefully when absent, which is deliberateand should stay. The contract has to distinguish "required" from "optional but
must behave this way if present", or it will force implementations of things
that were designed to be skippable.
against in-memory implementations. An adapter contract needs the implementer
to supply a fake, which is a real cost to impose, so the contract should be
worth more than the fake costs.
Marking
help wantedrather thangood first issue: the design question aboveis the work, and getting it wrong produces a contract people route around.