-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.in
67 lines (52 loc) · 2.19 KB
/
README.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
## verdant
The `verdant` package provides a binary protocol for advertising HTTP endpoint
protocol versions.
### Features
* Written in pure Java 17.
* [OSGi](https://www.osgi.org/) ready.
* [JPMS](https://en.wikipedia.org/wiki/Java_Platform_Module_System) 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](https://www.github.com/io7m-com/cedarbridge)
specification language using the canonical binary encoding. Briefly: All values
are delivered in [big endian](https://en.wikipedia.org/wiki/Endianness)
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](https://en.wikipedia.org/wiki/Universally_unique_identifier)
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.