verdant

verdant

The verdant package provides a binary protocol for advertising HTTP endpoint protocol versions.

Features

• Written in pure Java 17.
• OSGi ready.
• JPMS ready.
• ISC license.
• High-coverage automated test suite.

Description

verdant is a trivial protocol for announcing a set of protocols exposed by a set of HTTP endpoints.

A client connecting to a root endpoint reads a binary structure delivered with the content type application/verdant+cedarbridge.

The protocol is specified using the cedarbridge specification language using the canonical binary encoding. Briefly: All values are delivered in big endian byte order. Strings are encoded as a 32-bit unsigned integer representing the number of bytes the string data requires, followed by the UTF-8 encoded bytes of the string. Lists are encoded as a 32-bit unsigned integer representing the number of list elements, followed by the elements of the list.

The structure consists of a sequence of messages, with the first message being a fixed-size version header VContainerVersion specifying the version of the verdant protocol. The one and only defined version, at the time of writing, is version 1.

[record VContainerVersion
  [field version IntegerUnsigned32]
]

In version 1 of the protocol, this message will immediately be followed by a V1ProtocolsSupported message.

[record VProtocolId
  [field msb IntegerUnsigned64]
  [field lsb IntegerUnsigned64]
]

[record VProtocolSupported
  [field id VProtocolId]
  [field versionMajor IntegerUnsigned32]
  [field versionMinor IntegerUnsigned32]
  [field endpointPath String]
]

[record V1ProtocolsSupported
  [field supported [List VProtocolSupported]]
]

Each element of type VProtocolSupported specifies a protocol uniquely identified with a UUID and a major and minor version. Clients can then navigate to the associated endpoint path (relative to the current URL) and can expect to converse using whatever protocol was specified.