From cb54ab8a261d71deffe8f02ecf392c135790a062 Mon Sep 17 00:00:00 2001 From: Bogdan Mircea Date: Mon, 25 Sep 2023 13:08:21 +0300 Subject: [PATCH] Added 'Glossary' and 'Extending the crate' sections Signed-off-by: Bogdan Mircea --- messages/README.md | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/messages/README.md b/messages/README.md index 3dd690c117..02f84a9aa3 100644 --- a/messages/README.md +++ b/messages/README.md @@ -1,8 +1,15 @@ # messages -The `messages` crate provides data structures representing the various messages used in Aries protocols. This `README` explores the architecture behind the crate and module organization, making implementing new messages/protocols easier. +The `messages` crate provides data structures representing the various messages used in Aries protocols. This `README` explores the architecture behind the crate and module organization to clarify the individual pieces and design decisions within the crate. + +### Glossary +- `message content`: represents the protocol specific set of fields of a message +- `message decorators`: represents the decorator fields of a message not directly linked to the processing of a message within a protocol +- `message family` / `protocol`: represents the name of an Aries protocol, irrespective of its version (the `present-proof` part of `https://didcomm.org/present-proof/1.0/propose-presentation`) +- `message kind`: represents the name of a particular message within a specific protocol (the `propose-presentation` part of `https://didcomm.org/present-proof/1.0/propose-presentation`) +- `message type`: refers to the fully defined type of the message (which can translate to an entire, functional, `@type` field of an Aries message); it is comprised of a `protocol`, `major version`, `minor version` and `message kind`. ### Message structure -All messages, from all protocols and all versions, are part of the parent `AriesMessage` enum. The individual messages from a specific version of a specific protocol are then implemented in a cascade: +All messages, from all protocols and all versions, are part of the parent `AriesMessage` enum. The individual messages from a specific version of a specific protocol are then implemented in a cascade, as follows: - AriesMessage - Connection @@ -55,7 +62,7 @@ As a result, simple `serde` tagged serialization/deserialization is not sufficie We want to take the `@type` field and parse it to determine the exact protocol, version and message to process. The machinery is in place for that to happen through the delayed serialization/deserialization, but the protocol version resolution and all the possible variants for the `@type` field are located within this module and encapsulated in the `Protocol` enum. -Similarly to `AriesMessage`, the `Protocol` enum is represented in a cascading fashion: +Similarly to `AriesMessage`, the `Protocol` enum is represented in a cascading fashion such as: - Protocol - ConnectionType @@ -81,4 +88,21 @@ The relevant submodule then contains the actual definitions of the `content` and ### The `decorators` module Contains data structure for decorators. -Unlike messages and their `@type` field, decorators get their version associated within their name `~thread/1`. Since only major versions are used, swapping a decorators version in a message represents a breaking change and would have to be explicitly defined in the message's content/decorators data structure. No resolution is required. \ No newline at end of file +Unlike messages and their `@type` field, decorators get their version associated within their name `~thread/1`. Since only major versions are used, swapping a decorators version in a message represents a breaking change and would have to be explicitly defined in the message's content/decorators data structure. No resolution is required. + +### Extending the crate +Adding new messages to the crate should be fairly easy to do, even without understanding all the inner workings. The main concepts needed are: +- the `AriesMessage` enum encapsulates all messages +- messages are serialized/deserialized conditionally based on their `@type` field. +- the `@type` field gets deserialized using the `Protocol` enum, through which all +supported protocols can be resolved. +- the `PROTOCOL_REGISTRY` contains entries for all supported protocol versions, which is how minor version resolution is handled + +With that in mind, a crude list of steps for extending the crate would be: +- changes in the `msg_types` module + - adding/extending data types to represent the new protocol / protocol version + - if adding the first version of a new protocol, extend the `Protocol` enum + - add an entry to the `PROTOCOL_REGISTRY` +- changes in the `msg_fields` module + - adding/extending data types to represent the message content and message decorators +- if adding the first version of a new protocol, extend the `AriesMessage` enum \ No newline at end of file