radicle/radicle-ci-broker
1
0
Fork 0
mirror of https://seed.radicle.dev/rad:zwTxygwuz5LDGBq255RA2CbNGrz8.git synced 2026-10-18 19:30:29 +08:00
Code Issues Packages Projects Releases Wiki Activity

doc: generate sample adapter messages with code

Browse Source 
This removes the need to update them manually. Now they'll always be
up to date.

Signed-off-by: Lars Wirzenius <liw@liw.fi>
This commit is contained in:
Lars Wirzenius
2024-11-13 09:47:26 +02:00
parent 7ddb877a15
commit b199175ac0
6 changed files with 73 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -1,3 +1,4 @@
*.svg
*.html
/target
doc/messages.md
doc/Makefile
+4 -1
View File
@@ -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 $@
doc/architecture.md
-179
View File
@@ -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
doc/architecture.subplot
+1
View File
@@ -4,5 +4,6 @@ authors:
- The Radicle Project
markdowns:
- architecture.md
- messages.md
classes:
- json
doc/messages.sh
Executable
+39
View File
@@ -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
doc/messages.txt
+28
View File
@@ -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