b199175 doc: generate sample adapter messages with code — radicle-ci-broker

Radicle CI broker

doc: generate sample adapter messages with code

Lars Wirzenius committed 1 year ago

commit b199175ac0e98d8d9a8219f0092861a977bf8638
parent 7ddb877a1540e7a2144bca8449bd4a1c57b05293

6 files changed +73 -180

modified .gitignore

@@ -1,3 +1,4 @@

 *.svg
 *.html
 /target
 doc/messages.md
 \ No newline at end of file

modified doc/Makefile

@@ -19,7 +19,10 @@ all: architecture.html userguide.html

 publish: all
 	bash publish.sh
 architecture.html: architecture.subplot architecture.md Makefile
 architecture.html: architecture.subplot architecture.md Makefile messages.md
 messages.md: messages.sh messages.txt
 	./messages.sh > messages.md
 userguide.html: userguide.subplot userguide.md Makefile
 	subplot docgen $< --output $@

modified doc/architecture.md

@@ -166,185 +166,6 @@ they are used to on other forges, we want the broker to pass on

 whatever information it already has from the node events to the
 adapters, so they can pass it on to external CI systems, as appropriate.
 # Request and response messages
 Note: the JSON objects below are formatted on multiple lines to make
 them easier to read. The actual wire format is one line per message.
 Run the `broker-messages` binary to get actual examples produced by
 code.
 ~~~{.sh .numberLines}
 $ cargo run -q --bin broker-messages
 Trigger request:
 {"request":"trigger","event_type":"push","version":<PROTOCOL_VERSION>,repository":{"id":"rad:zwTxygwuz5LDGBq255RA2CbNGrz8","name":"radicle-ci-broker","description":"Radicle CI broker","private":false,"default_branch":"main","delegates":["did:key:z6MkgEMYod7Hxfy9qCvDv5hYHkZ4ciWmLFgfvm3Wn1b2w2FV"]},"pusher":{"id":"did:key:z6MkgEMYod7Hxfy9qCvDv5hYHkZ4ciWmLFgfvm3Wn1b2w2FV","alias":"liw"},"before":"b4fb1e347be7db19f0859717062f94116b5bec9f","after":"b4fb1e347be7db19f0859717062f94116b5bec9f","branch":"patches/8d8232ddcb217fa1402eec4d955e227ef3bb5881","commits":[]}
 Triggered response:
 {"response":"triggered","run_id":{"id":"any-string-works-as-run-id"}}
 Successful response:
 {"response":"finished","result":"success"}
 Failure response:
 {"response":"finished","result":"failure"}
 ~~~
 ## Push Event Request
 An example request that the broker sends looks like this:
 ~~~{.json .numberLines}
 {
     "request": "trigger",
     "event_type": "push",
     "version":<PROTOCOL_VERSION>,
     "pusher": {
         "id": "did:key:z6MkltRpzcq2ybm13yQpyre58JUeMvZY6toxoZVpLZ8YabRa",
         "alias": "node_alias"
     },
     "before": "<BEFORE_COMMIT>",
     "after": "<AFTER_COMMIT>",
     "branch": "<BRANCH_NAME>",
     "commits": [
         "<SOME_OTHER_COMMIT_BEING_PUSHED>",
         "<AFTER_COMMIT>"
     ],
     "repository": {
         "id": "<RID>",
         "name": "heartwood",
         "description": "Radicle is a sovereign peer-to-peer network for
         code collaboration, built on top of Git.",
         "private": false,
         "default_branch": "main",
         "delegates": [
           "did:key:z6MkltRpzcq2ybm13yQpyre58JUeMvZY6toxoZVpLZ8YabRa",
           "did:key:z6MkltRpzcq2ybm13yQpyre58JUeMvZY6toxoZVpLZ8YabRb"
         ]
     }
 }
 ~~~
 where:
   - `<PROTOCOL_VERSION>` is the version of the protocol messages that broker exchanges
   - `<RID>` is the repository ID, in its `rad:` URN format,
   - `<BRANCH_NAME>` is the branch name where the push occurred,
   - `<AFTER_COMMIT>` is the commit id of the last commit being pushed,
   - `<BEFORE_COMMIT>` is the commit id of the **parent** of the first
      commit being pushed (i.e. ` <SOME_OTHER_COMMIT_BEING_PUSHED>`),
      (the SHA checksum).
 The `request` fields allows us to extend this in the future.
 ## Patch Event Request
 An example request that the broker sends looks like this:
 ~~~{.json .numberLines}
 {
     "request": "trigger",
     "event_type": "patch",
     "version":<PROTOCOL_VERSION>
     "action": "created|updated",
     "patch": {
         "id": "<PATCH_ID>",
         "author": {
             "id": "did:key:z6MkltRpzcq2ybm13yQpyre58JUeMvZY6toxoZVpLZ8YabRa",
             "alias": "node_alias"
         },
         "title": "Add description in README",
         "state": {
             "status": "Open",
             "conflicts": [
                 {
                     "revision_id": "string",
                     "oid": "string"
                 }
             ]
         },
         "before": "<BEFORE_COMMIT>",
         "after": "<AFTER_COMMIT>",
         "commits": [
             "<SOME_OTHER_COMMIT_BEING_PUSHED>",
             "<AFTER_COMMIT>"
         ],
         "target": "delegates",
         "labels": [
             "small",
             "goodFirstIssue",
             "enhancement",
             "bug"
         ],
         "assignees": [
             "did:key:z6MkltRpzcq2ybm13yQpyre58JUeMvZY6toxoZVpLZ8YabRa"
         ],
         "revisions": [
             {
                 "id": "41aafe22200464bf905b143d4233f7f1fa4a9123",
                 "author": {
                     "id": "did:key:z6MkltRpzcq2ybm13yQpyre58JUeMvZY6toxoZVpLZ8YabRa",
                     "alias": "my_alias"
                 },
                 "description": "The revision description",
                 "base": "193ed2f675ac6b0d1ab79ed65057c8a56a4fab23",
                 "oid": "f0f5d38ffa8d54a7cc737fc4e75ab1e2e178eaa1",
                 "timestamp": 1699437445
             }
         ]
     },
     "repository": {
         "id": "<RID>",
         "name": "heartwood",
         "description": "Radicle is a sovereign peer-to-peer network for
         code collaboration, built on top of Git.",
         "private": false,
         "default_branch": "main",
         "delegates": [
           "did:key:z6MkltRpzcq2ybm13yQpyre58JUeMvZY6toxoZVpLZ8YabRa",
           "did:key:z6MkltRpzcq2ybm13yQpyre58JUeMvZY6toxoZVpLZ8YabRb"
         ]
     }
 }
 ~~~
 where:
   - `<PROTOCOL_VERSION>` is the version of the protocol messages that broker exchanges
   - `<RID>` is the repository ID, in its `rad:` URN format,
   - `<AFTER_COMMIT>` is the commit id of the last commit being pushed,
   - `<BEFORE_COMMIT>` is the commit id of the **parent** of the first
     commit being pushed (i.e. ` <SOME_OTHER_COMMIT_BEING_PUSHED>`),
     (the SHA checksum).
 The `request` fields allows us to extend this in the future.
 ## Responses
 The first response from the adapter looks like this:
 ~~~{.json .numberLines}
 {
     "response": "triggered",
     "run_id": "<RUNID>"
 }
 ~~~
 where `<RUNID>` is the id of the run that has been triggered.
 The second response from the adapter looks like this:
 ~~~{.json .numberLines}
 {
     "response": "finished",
     "result": "<STATUS>"
 }
 ~~~
 where `<STATUS>` is either the string `success` or `failure`. Note
 that the run id is not repeated as the context makes this clear: the
 response comes from the same process, via the same stdout pipe, as the
 previous message.
 # Report generation
 The CI broker has an SQLite database file for persistent storage of

modified doc/architecture.subplot

@@ -4,5 +4,6 @@ authors:

   - The Radicle Project
 markdowns:
   - architecture.md
   - messages.md
 classes:
   - json

added doc/messages.sh

@@ -0,0 +1,39 @@

 #!/bin/bash
 set -euo pipefail
 message() {
 	echo "~~~json"
 	cargo run -q --bin cibtool -- message "$@" | jq .
 	echo "~~~"
 }
 while read -r line; do
 	case "$line" in
 	@PUSH)
 		message --kind=push
 		;;
 	@PATCH)
 		message --kind=patch
 		;;
 	@TRIGGERED)
 		message --kind=triggered
 		;;
 	@TRIGGEREDURL)
 		message --kind=triggered --info-url=https://ci.example.com/runid/log.html
 		;;
 	@SUCCESS)
 		message --kind=success
 		;;
 	@FAILURE)
 		message --kind=failure
 		;;
 	@*)
 		echo "Unknown directive: $line" 1>&2
 		a exit 1
 		;;
 	*)
 		echo "$line"
 		;;
 	esac
 done <messages.txt

added doc/messages.txt

@@ -0,0 +1,28 @@

 # Sample messages to and from CI adapter
 Note: the JSON objects below are formatted on multiple lines to make
 them easier to read. The actual wire format is one line per message.
 ## Trigger on branch create or update
 @PUSH
 ## Trigger on patch create or update
 @PATCH
 ## Response when run has started
 @TRIGGERED
 ## Response when run has started, with info URL
 @TRIGGEREDURL
 ## Response on successful finish
 @SUCCESS
 ## Response on failure finish
 @FAILURE