Crates.io | pact |
lib.rs | pact |
version | 0.2.0 |
source | src |
created_at | 2023-10-16 00:26:24.549874 |
updated_at | 2024-03-15 17:25:46.116717 |
description | Compact and streamable data format that works anywhere--from web apps to robots. |
homepage | https://gitlab.com/alicorn/pub/alicorn |
repository | https://gitlab.com/alicorn/pub/alicorn |
max_upload_size | |
id | 1004207 |
size | 89,101 |
Compact and streamable data format that works anywhere--from web apps to robots.
Pacts describe the structure of related types of data, each containing one or more fields. Pact data can encode to and decode from raw binary data streams, which means pacts are extra-helpful for making distributed or embedded apps that speak different languages or rely on low-level networking.
Note: For those familiar with other data interchange formats, pacts have a lot in common with things like the
proto
schemas used bygRPC
and thecapnp
schemas used by Cap'n Proto.
Each data type in a pact can have the following kinds of fields:
8
to 64
bits
(u8
, u16
, u32
, and u64
).8
to 64
bits
(i8
, i16
, i32
, and i64
).32
to 64
bits
(f32
and f64
).bool
).string
).For information on how pact data is coded to and
from binary data, refer to the codec
docs.
Pacts are made with TOML:
## An example pact.
pact = 'MyGreeter'
## Data type in this pact
## named "Request".
[data.1. Request]
message = 'string'
## Another data type in this
## pact named "Response".
[data.2. Response]
message = 'string'
## This field of a Response is a
## list of strings, instead of just
## a single string, because it is
## surrounded by `[]`.
friends = ['string']
## This field of a Response is a
## copy of the request that the
## response is for, showing how
## we can nest other data types
## within data types.
request = 'Request'
This example describes a MyGreeter
pact with two
kinds of data: Request
and Response
. Both of
these data contain a message
string, while the
Response
data contains a list of strings called
friends
and a copy of the original Request
.
Every data description starts with a number called
an Ordinal. Ordinals uniquely identify the different
kinds of data in the same pact. The first data described
by a pact always has ordinal 1
, and each additional
data type in the same pact has an ordinal that is one
higher than the previous data.
Comments that start with ##
and come immediately
before the pact
name, a data
name, or a field
name, will be parsed as documentation for the item
they precede.
The easiest way to get started with TOML pacts
in your own projects is via the
pact-derive
crate.
Yes! Pact data is designed to evolve as a system's needs change:
If a system receives data of a new type it doesn't support, or containing new fields it doesn't support, the new information will be gracefully ignored.
Conversely, if a system receives data that's missing newly-added fields, the missing fields will be gracefully populated with default values.
Copyright 2024 Alicorn Systems, Inc.
Licensed under the GNU Affero General Public License version 3, as published by the Free Software Foundation. Refer to the license file for more information.
If you have any questions, please reach out to [hello@alicorn.systems
].