docs: include error handling flow in readme (#116)

* docs(mediator): update mediator readme Signed-off-by: Shailesh Patil <shailesh.patil@iohk.io> * docs(mediator): update mediator readme Signed-off-by: Shailesh Patil <shailesh.patil@iohk.io> * docs(mediator): TODO added for adding report link Signed-off-by: Shailesh Patil <shailesh.patil@iohk.io> * docs(mediator): adding the test report link Signed-off-by: Shailesh Patil <shailesh.patil@iohk.io> * Added CODEOWNER files Signed-off-by: Shailesh Patil <shailesh.patil@iohk.io> * Updated the ReadME and docker compose Signed-off-by: Shailesh Patil <shailesh.patil@iohk.io> * addressed the pr comments Signed-off-by: Shailesh Patil <shailesh.patil@iohk.io> --------- Signed-off-by: Shailesh Patil <shailesh.patil@iohk.io> Co-authored-by: Shailesh Patil <shailesh.patil@iohk.io> Signed-off-by: Shailesh <Patil>
input-output-hk · Apr 30, 2024 · 3924e51 · 3924e51
1 parent c6305d2
commit 3924e51
Show file tree

Hide file tree

Showing 4 changed files with 196 additions and 48 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1,8 @@
+# code
+* @FabioPinheiro @mineme0110
+
+# E2E tests:
+/tests/ @antonbaliasnikov
+
+# Docs:
+*.md @petevielhaber
diff --git a/Mediator-Error_Handling.md b/Mediator-Error_Handling.md
@@ -1,11 +1,7 @@
 # Error Handling
 
-
-More info see https://input-output.atlassian.net/browse/ATL-5236
-
 https://identity.foundation/didcomm-messaging/spec/#problem-reports
 
-
 On each step of all our protocols processing, when something wrong is happening, we need to:
 Goals
 - Update the record to a documented error state
@@ -16,8 +12,6 @@ Goal other: error recover/resilient
 - [optional] Send event that record state changed to error
 - Decide on the policy of re-trying sending errors (one of the proposals is just to send it once, and if a recipient did not get this, then it’s on its own requesting record ID state)
 
-
-
 Note: most errors in Mediator will be synchronous
 
 - Store messages when sending (1w)
@@ -28,31 +22,30 @@ Note: most errors in Mediator will be synchronous
     - [WIP]
   - (sync & async) e.p.crypto.replay - if the message is replay (possible he replay attack).
   - (sync) e.p.req - pickup message before enroling.
-  - [QA] StatusRequest - https://didcomm.org/messagepickup/3.0/status-request
-  - [QA] DeliveryRequest - https://didcomm.org/messagepickup/3.0/delivery-request
+  - [DONE] StatusRequest - https://didcomm.org/messagepickup/3.0/status-request
+  - [DONE] DeliveryRequest - https://didcomm.org/messagepickup/3.0/delivery-request
   - (sync) e.p.me.res.storage - connection MongoBD is not working.
-  - [QA] catch all StorageCollection Error
+  - [DONE] catch all StorageCollection Error
   - (sync) e.p.me.res.storage - business logic MongoBD is not working.
-  - [QA] catch all StorageThrowable
+  - [DONE] catch all StorageThrowable
   - (sync) e.p.did - for any DID method that is not `did.peer`.
   - (sync) e.p.did.malformed - for any DID method malformed.
   - (sync) e.p.msg - for parsing error from the message.
-    - [QA] All parsing errors from the decrypt function
+    - [DONE] All parsing errors from the decrypt function
     - [TODO] parsing for a specific data model of each protocol
   - (sync) e.p.msg.unsupported - for the message type LiveModeChange and all message that is not role of the mediator
-    - [QA] MediateGrant
-    - [QA] MediateDeny
-    - [QA] KeylistResponse
-    - [QA] Status - https://didcomm.org/messagepickup/3.0/status
-    - [TODO] ...
+    - [DONE] MediateGrant
+    - [DONE] MediateDeny
+    - [DONE] KeylistResponse
+    - [DONE] Status - https://didcomm.org/messagepickup/3.0/status
   - LiveModeChange Not Supported 
-    - [QA] "e.m.live-mode-not-supported" - https://didcomm.org/messagepickup/3.0/live-delivery-change
+    - [DONE] "e.m.live-mode-not-supported" - https://didcomm.org/messagepickup/3.0/live-delivery-change
   - (sync) e.p.msg.unsupported - for parsing error due to unsupported version or protocol.
-    - [QA] MissingProtocolExecuter (unsupported protocol it also works fine for unsupported versions)
+    - [DONE] MissingProtocolExecuter (unsupported protocol it also works fine for unsupported versions)
   - (sync & async) e.p.req.not_enroll - Get a Forward message to a DID that is not enrolled.
-    - [QA] Send a Problem Report if the next DID is not enrolled in the Mediator.
+    - [DONE] Send a Problem Report if the next DID is not enrolled in the Mediator.
   - (sync & async) e.p.me - catch all error at the end.
-    - [WIP]
+    - [DONE]
 - Receive a problem report (1w):
 - in case of Warnings Reply `w.p` -> log warnings and escalate to an error `e.p` on the reply
 - in case of Error `e.p` -> log error
@@ -63,3 +56,116 @@ Note: most errors in Mediator will be synchronous
 - [optional] update the protocol with new tokens (2d)
   - `e.p.me.res.storage`
   - `e.p.me.res.not_enroll`
+
+# Problem Reports in Mediator flow
+
+https://didcomm.org/coordinate-mediation/2.0/mediate-request
+
+```mermaid
+stateDiagram-v2
+  classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+  [*] -->Recipient
+ Recipient --> mediation_request_received:mediation request message(1)
+  mediation_request_received --> request_stored :received mediation request message (2)
+  request_stored -->  request_processing:{Mediation request processing} (3)
+  request_processing -->Recipient: Mediation Grant message reply Sync (4)
+  request_processing -->Recipient: Mediation Deny message reply Sync  (4)
+  request_processing -->Recipient: Problem report message reply sync  (4)
+  class request_processing processing
+```
+
+https://didcomm.org/coordinate-mediation/2.0/keylist-update
+```mermaid
+stateDiagram-v2
+  classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  classDef grant fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  mediation_granted -->Recipient
+ Recipient --> Key_list_update_request:key list update request message(1)
+  Key_list_update_request --> request_stored :received Key list update request message (2)
+  request_stored -->  request_processing:{Key list update request processing} (3)
+  request_processing -->Recipient: Key list update Response message reply Sync (4)
+  request_processing -->Recipient: Problem report message reply sync  (4)
+  class request_processing processing
+  class mediation_granted grant
+```
+
+https://didcomm.org/coordinate-mediation/2.0/keylist-query
+```mermaid
+stateDiagram-v2
+  classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  classDef grant fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  mediation_granted -->Recipient
+ Recipient --> Key_list_query_request:key list query request message(1)
+  Key_list_query_request --> request_stored :received Key list query request message (2)
+  request_stored -->  request_processing:{Key list query request processing} (3)
+  request_processing -->Recipient: Key list query Response message reply Sync (4)
+  request_processing -->Recipient: Problem report message reply sync  (4)
+  class request_processing processing
+  class mediation_granted grant
+```
+
+Pickup 3.0 https://didcomm.org/pickup/3.0
+
+https://didcomm.org/messagepickup/3.0/status-request
+```mermaid
+stateDiagram-v2
+  classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  classDef success fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  mediation_granted --> Key_list_updated
+  Key_list_updated -->Recipient
+ Recipient --> status_request:status request message(1)
+  status_request --> request_stored :received status request message (2)
+  request_stored -->  request_processing: status request processing (3)
+  request_processing -->Recipient: status Response message reply Sync (4)
+  request_processing -->Recipient: Problem report message reply sync  (4)
+  class request_processing processing
+  class mediation_granted,Key_list_updated success
+```
+https://didcomm.org/messagepickup/3.0/delivery-request
+```mermaid
+stateDiagram-v2
+  classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  classDef success fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  mediation_granted --> Key_list_updated
+  Key_list_updated -->Recipient
+ Recipient --> Key_list_query_request:Delivery request message(1)
+  Key_list_query_request --> request_stored :received Delivery request message (2)
+  request_stored -->  request_processing:{Delivery request processing} (3)
+  request_processing -->Recipient: Delivery Response message reply Sync (4)
+  request_processing -->Recipient: Problem report message reply sync  (4)
+  class request_processing processing
+  class mediation_granted,Key_list_updated success
+```
+
+https://didcomm.org/messagepickup/3.0/messages-received
+```mermaid
+stateDiagram-v2
+  classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  classDef success fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  mediation_granted --> Key_list_updated
+  Key_list_updated -->Recipient
+ Recipient --> Key_list_query_request:messages-received request message(1)
+  Key_list_query_request --> request_stored :messages-received request message (2)
+  request_stored -->  request_processing:{messages-received request processing} (3)
+  request_processing -->Recipient: messages-received Response message reply Sync (4)
+  request_processing -->Recipient: Problem report message reply sync  (4)
+  class request_processing processing
+  class mediation_granted,Key_list_updated success
+```
+
+
+Sender to Recipient (Sender use the type forward message)
+https://didcomm.org/routing/2.0/forward
+```mermaid
+stateDiagram-v2
+  classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+  [*] --> Sender
+  Sender --> forward_message_request:forward message request(1)
+  forward_message_request --> request_stored :forward request message (2)
+  request_stored -->  request_processing:{forward message request processing} (3)
+  request_processing --> forward_message_stored: message stored (4)
+  request_processing -->Sender: Problem report Signed message reply sync  (4)
+  forward_message_stored --> [*]
+  class request_processing processing
+```
diff --git a/README.md b/README.md
@@ -14,8 +14,21 @@ graph LR
  - **Scala Steward** automates the creation of pull requests for libraries with updated dependencies, saving maintainers time and effort. It can also help ensure that libraries are kept up-to-date, improving their reliability and performance.
 
 
-**More documentation:**
-- [LICENSE](LICENSE) - Apache License, Version 2.0
+# Table of contents:
+- [Mediator Purpose](#Description)
+- [Protocols Supported](#Protocols)
+  - [Mediator Protocol State and Flow](Coordinate-Mediation-Protocol.md)
+- [Pre-reqs](#pre-reqs)
+- [Getting started](#getting-started)
+  - [Docker only](#docker-only)
+- [Configuring the mediator](#configure-the-mediator)
+    - [Mediator identity](#identity)
+    - [Mediator storage](#mediator-storage)
+      - [Mediator-Storage-In-cloud](#mongodb-in-cloud) 
+- [Mediator Deployment](#deploy)
+- [Mediator Test suite](#mediator-tests)
+- [Mediator Error Handling](Mediator-Error_Handling.md#error-handling)  
+- [Mediator protocols state flow with problem reporting](Mediator-Error_Handling.md#problem-reports-in-mediator-flow)
 
 ## Description
 
@@ -53,61 +66,82 @@ The mediator is especially useful when the edge entities are not always online,
 - [TODO] `MediatorCoordination 3.0` - https://didcomm.org/mediator-coordination/3.0
 - [DONE] `Pickup 3` - https://didcomm.org/pickup/3.0 [ with exclusion of When the delivery request  (https://didcomm.org/messagepickup/3.0/delivery-request)  is made, but there are no messages currently available to be sent,  No status message is sent immediately, Instead you can check the the status of message using the status request https://didcomm.org/messagepickup/3.0/status-request]
 - [DONE] `TrustPing 2.0` - https://didcomm.org/trust-ping/2.0/
+- [DONE] `Report Problem 2.0` https://didcomm.org/report-problem/2.0/
 
-## How to run
 
-### server
+# Pre-reqs
 
-**Start the server**:
- - shell> `docker-compose up mongo`
- - sbt> `mediator/reStart`
-### webapp
+To build and run this mediator, locally you will need a few things:
+- Install [Docker](https://docs.docker.com/get-docker/)
+- Install [SBT](https://www.scala-sbt.org/download.html)
 
-The webapp/webpage is atm just to show the QRcode with out of band invitation for the Mediator.
+# Getting started
+This DIDComm Mediator comprises two elements: a backend service and a database.
+The backend service is a JVM application, and the database used is MongoDB.
+The backend service is also a web service with a single-page application that will give the final user an invitation page
 
-**Compile** - sbt> `webapp / Compile / fastOptJS / webpack`
+- Clone the repository
+```
+git clone git@github.com:input-output-hk/atala-prism-mediator.git
+```
+```
+shell> cd atala-prism-mediator
+shell> docker-compose up mongo 
+```
+In another shell from the project root directory `atala-prism-mediator`
+```
+shell> sbt
+sbt> mediator/reStart
+```
+By default mediator will start on port 8080
 
-**Open the webpage for develop** - open> `file:///.../webapp/index-fastopt.html`
+You can open the `http://localhost:8080/` URL in a web browser, and it will show a QR code that serves as an out-of-band invitation for the Mediator.
+
+## How to run mediator as docker image
+# Docker only
+It is possible to run everything with a single command with Docker compose docker-compose.yml
+The latest stable image version is available in the IOHK repositories.
+To build a docker image locally, run NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal.
+```
+shell> cd atala-prism-mediator
+shell> NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal
+shell> MEDIATOR_VERSION=$(sbt "print mediator/version" --error) docker-compose up
+```
 
 ### Configure the Mediator
 
 The default configuration is set up [application.conf](/mediator/src/main/resources/application.conf).
 So in order to configure the mediator for your needs.
 You can either change the default configuration or you can set up environment variables that overrides the defaults:
 
+# identity
 To set up the mediator identity:
 - `KEY_AGREEMENT_D` - is the key agreement private key (MUST be a X25519 OKP key type).
 - `KEY_AGREEMENT_X` - is the key agreement public key (MUST be a X25519 OKP key type).
 - `KEY_AUTHENTICATION_D` - is the key authentication private key (MUST be an Ed25519 OKP key type).
 - `KEY_AUTHENTICATION_X` - is the key authentication public key (MUST be an Ed25519 OKP key type).
 - `SERVICE_ENDPOINT` - is the endpoint of the mediator. Where the mediator will be listening to incoming DID Comm messages.
 
+# mediator-storage
 To set up the mediator storage (MongoDB):
 - `MONGODB_PROTOCOL` - is the protocol type used by mongo.
 - `MONGODB_HOST` - is the endpoint where the MongoDB will be listening.
 - `MONGODB_PORT` - is the endpoint's port where the MongoDB will be listening.
-- `MONGODB_USER` - is the user name used by the Mediator service to connect to the database.
+- `MONGODB_USER` - is the username used by the Mediator service to connect to the database.
 - `MONGODB_PASSWORD` - is the password used by the Mediator service to connect to the database.
 - `MONGODB_DB_NAME` - is the name of the database used by the Mediator.
 
-## Run
-
-This DIDComm Mediator is composed of two elements, a backend service, and a database.
-The backend service is a JVM application and the database used is MongoDB.
-The backend service is also a web service that has a single-page application that will give the final user an invitation page.
-
-### Run localy
-
-Everything can be run with a single command with Docker compose `docker-compose.yml`
+### MongoDB In cloud
 
-First build to docker image with `NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal`.
-The latest stable image version can also be downloaded from the IOHK repositories.
-
-### MongoBD
-
-Docker compose would do that for you but if you are running separately or on the cloud like MongoDB Atlas.
+Using the mongodb from cloud like MongoDB Atlas.
 You will need to create the table and indexes before starting the backend service. See the file `initdb.js`.
 
 ### Deploy
 
 You can easily deploy the image everywhere. We recommend a minimum of 250 mb ram to run the mediator backend service.
+
+# mediator-tests
+https://github.com/input-output-hk/didcomm-v2-mediator-test-suite
+https://input-output-hk.github.io/didcomm-v2-mediator-test-suite/Reports.html
+
+- [LICENSE](LICENSE) - Apache License, Version 2.0
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -14,7 +14,7 @@ services:
       - ./initdb.js:/docker-entrypoint-initdb.d/initdb.js
 
   atalaprism-mediator:
-    image: ghcr.io/input-output-hk/atala-prism-mediator:${MEDIATOR_VERSION:-0.2.0-SNAPSHOT}
+    image: ghcr.io/input-output-hk/atala-prism-mediator:${MEDIATOR_VERSION}
     ports:
       - "8080:8080"
     environment: