Skip to content

Test that FodId keeps the byte layout, the payload version and its constructor out of reach - #157

Merged
jwrosewell merged 1 commit into
rcfrom
test/did-surface
Nov 15, 2026
Merged

jwrosewell merged 1 commit into
rcfrom
test/did-surface

Conversation

@jwrosewell

@jwrosewell jwrosewell commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Tests only. Three rules of the 51Did specification limit what FodId offers a caller, and the Java package meets all three, but no test would fail if a later change broke one of them. This adds those tests. It is the follow-up that #141 names under What remains.

What the specification says

did-specification/README.md lines 33 to 35:

Application code MUST NOT read the layout by hand, and the packages therefore keep the offsets and lengths out of their public surface.

package-surface.md lines 53 to 57:

A package MUST refuse a Payload whose version it does not know, reporting it the way it reports one it cannot read and naming the version it found, as set out in Identifier layout. The version belongs to the refusal and MUST NOT appear as a member of the identifier, because a caller has nothing to decide with it.

identifier-layout.md lines 42 and 43:

The Envelope is signed, so a 51Did package MUST create instances only by reading bytes that are already a complete Envelope.

What the code does today

At rc de74c8c8, every offset and length constant in FodId is package-private (lines 110 to 168), the payload version is read by a private method (payloadVersionOf) and reaches a caller only in the message of a refused read, FodId is final, its one constructor is private (lines 181 to 192), and the public static readers that give a FodId each take one encoded Envelope (fromBase64, fromByteArray, fromOwid). The only public version accessor, getVersion, gives the Envelope's own version, a com.swancommunity.owid.Version.

The tests

FodIdSurfaceTests in pipeline.did, commit e4d094a1, reads FodId by reflection.

  • layout_OffsetsAndLengths_AreNotPublic finds no field of FodId that is public or protected.
  • payloadVersion_IsNotAMemberOfTheIdentifier finds no public or protected method whose name holds "version" and which gives anything other than the Envelope's Version.
  • instances_AreMadeOnlyByReadingAnEnvelope checks that FodId is final, that every constructor is private, and that every public static method giving a FodId takes one String, byte[] or Owid.

They pass on rc by design, so the red run breaks the three rules on purpose. Red 43673233766 ran the tests with FodId's HEADER_LENGTH made public, a public getPayloadVersion added and the constructor made public, plus a throwaway workflow, Java 17. Exactly the three new tests failed, with "FodId fields a caller can reach expected:<[]> but was:<[HEADER_LENGTH]>", "FodId methods that give a version other than the Envelope's expected:<[]> but was:<[getPayloadVersion]>" and the private constructor assertion, while FodIdTests (47) and FodIdParseTests (38) passed. Green 43673225548 ran the head plus the same workflow, and FodIdSurfaceTests passed 3 of 3, FodIdTests 47 of 47 and FodIdParseTests 38 of 38.

Full build

Run 43674223762 built e4d094a merged with rc (2eebbff) on nine configurations, Ubuntu x64 with Java 8, 11, 17 and 21, Ubuntu arm64 with Java 17, and Windows with Java 8, 11, 17 and 21, and every job passed. FodIdSurfaceTests passed 3 of 3 in all nine jobs. Each of its ten Setting 'PullRequestSha' lines names e4d094a, and its Configure job printed "Left out 6 macOS entries".

macOS was left out of this draft's full build under the 9 November decision. The rc head is built with macOS before it merges into main.

What it releases

Nothing. The change is a test under src/test, which the release plan leaves out (ci/README.md), so no package is released for it.

Base branch

rc at de74c8c. A trial merge of the head with rc at 30e8df6 is clean.

…ctor out of reach

The 51Did specification keeps the offsets and lengths out of a package's
public surface (did-specification/README.md lines 33 to 35), keeps the
payload version off the identifier (package-surface.md lines 55 and 56),
and has a package make an instance only by reading a complete Envelope
(identifier-layout.md lines 42 and 43). FodId meets all three, and these
tests fail if a later change makes a layout constant, a payload version
accessor or the constructor reachable.
@jwrosewell
jwrosewell marked this pull request as ready for review November 15, 2026 09:31
@jwrosewell
jwrosewell merged commit 50e63e4 into rc Nov 15, 2026
4 checks passed
@jwrosewell
jwrosewell deleted the test/did-surface branch November 15, 2026 09:31
@jwrosewell jwrosewell mentioned this pull request Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant