Skip to content

io7m-com/verdant

Repository files navigation

verdant

Maven Central Maven Central (snapshot) Codecov Java Version

com.io7m.verdant

JVM Platform Status
OpenJDK (Temurin) Current Linux Build (OpenJDK (Temurin) Current, Linux)
OpenJDK (Temurin) LTS Linux Build (OpenJDK (Temurin) LTS, Linux)
OpenJDK (Temurin) Current Windows Build (OpenJDK (Temurin) Current, Windows)
OpenJDK (Temurin) LTS Windows Build (OpenJDK (Temurin) LTS, Windows)

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.