Skip to content

Commit

Permalink
update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@walotta
walotta committed May 19, 2023
1 parent ae3a0c0 commit 05bbac1
Showing 1 changed file with 45 additions and 41 deletions.
86 changes: 45 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# colink-playbook-dev
# CoLink Playbook Dev

You can use this module to quickly set up a protocol of CoLink with just a few lines in the TOML file.
This module can be used to quickly set up a CoLink protocol with just a few lines in the TOML file.

## Run a protocol by playbook
## Running a Protocol by Playbook

1. Download the release binary of your system from GitHub.

Expand All @@ -18,11 +18,11 @@ You can use this module to quickly set up a protocol of CoLink with just a few l
cargo build --release
```

2. Get your *colink-server address* and the *user's jwt* who wants to run the protocol as `<addr>` and `<jwt>`, which can refer to [rust sdk](https://github.com/CoLearn-Dev/colink-sdk-rust-dev).
2. Get your *colink-server address* and the *user's jwt* who wants to run the protocol as `<addr>` and `<jwt>`, which can be referred to in the [Rust SDK](https://github.com/CoLearn-Dev/colink-sdk-rust-dev).
3. Define your new protocol in the TOML file ( `colink.toml` by default), and get the path of your protocol as `<config_path>`.
3. Define your new protocol in a config file (`colink.toml` by default) in TOML format, and get the path of your TOML file as `<config_path>`.
4. [Optional] If your TOML file is not `colink.toml`, you need to set the env variable `COLINK_PLAYBOOK_CONFIG = <config_path>`.
4. [Optional] If your TOML file name is not `colink.toml`, you need to set the env variable `COLINK_PLAYBOOK_CONFIG = <config_path>`.
5. Run your protocol
Expand All @@ -32,10 +32,12 @@ You can use this module to quickly set up a protocol of CoLink with just a few l
## Format of `TOML` file
You can define your protocol like this: (you need to replace all the field as `<...>`)
* You can define your protocol like the example below (you need to replace all the fields as `<...>`).
* The playbook will run each step in order for each role.
```toml
[<your_po_pkg_name>]
[<your_po_pkg_name>] # po stands for protocol
workdir = <your po working path>
name = <your po name>
Expand All @@ -44,7 +46,7 @@ You can define your protocol like this: (you need to replace all the field as `<
max_num = <int> # [optional] Limit the number of users with this role in this protocol
min_num = <int> # [optional] as previous
[<your_po_pkg_name>.roles.<your_role_name_0>.playbook]
workdir = <your role working path> # [optional] If not defined, will set the protocol working path as role path
workdir = <your role working path> # [optional] If not defined, the protocol working path will be set as the role path
[[<your_po_pkg_name>.roles.<your_role_name_0>.playbook.steps]]
# write actions here
Expand All @@ -53,20 +55,21 @@ You can define your protocol like this: (you need to replace all the field as `<
# write actions here
[<your_po_pkg_name>.roles.<your_role_name_1>]
#define your other role action here
# define your other role action here
[<your_po_pkg_name>.roles.<your_role_name_2>]
#define your other role action here
# define your other role action here
```
## Template string
### Template String
* Templating will activate in all `path`, `variable name`, and `entry name` fields.
* The template string is a string with the format `{{...}}`. The content in the `{{...}}` will be replaced by the dynamic values. Currently, we support two dynamic values: `task_id` and `user_id` (refer to [rust sdk](https://github.com/CoLearn-Dev/colink-sdk-rust-dev)).
* The template string is a string with the format `{{...}}`. The content in the `{{...}}` will be replaced by the dynamic values. Currently, we support two dynamic values: `task_id` and `user_id` (refer to the [Rust SDK](https://github.com/CoLearn-Dev/colink-sdk-rust-dev)).
* templating will activate in all `path`, `variable name` and `entry name` fields.
* templating supports the rust-style slices.
* format example:
* Templating supports the Rust-style slices.
* Format example:
```
"{{task_id}}"
Expand All @@ -75,31 +78,33 @@ You can define your protocol like this: (you need to replace all the field as `<
"{{task_id[2..5]}}"
```
the slices will be `[a,b)` for `{{task_id[a..b]}}`
The slices will be `[a,b)` for `{{task_id[a..b]}}`
## Supported action
### Supported Action
* run action with condition
* Run action with condition
you can use this statement to add a run condition for any step
You can use this statement to add a run condition for any step
```toml
if = "a bash command" # example: `grep -q '0' xx.txt`
[[xxx.steps]]
if = "a bash command" # example: `grep -q '0' xx.txt`
# other steps
```
this action will run the bash command and get its exit code. If return `0`, will run this step, otherwise, this step will be skipped.
This action will run the bash command and get its exit code. If it returns `0`, the step will run, otherwise, this step will be skipped.
* sub-process
* Sub-process
* start the sub-process:
* Start the sub-process:
```toml
[[xxx.steps]]
step_name = "your sub-process name" #cannot start with `__`
process = "your command here"
```
* force kill the sub-process
* Force kill the sub-process
```toml
[[xxx.steps]]
Expand All @@ -110,7 +115,7 @@ You can define your protocol like this: (you need to replace all the field as `<
check_exit_code = <i32> # [optional] set this field to check the exit code of process (notice that if this process is killed, the exit code is 9)
```

* join the sub-process
* Join the sub-process

```toml
[[xxx.steps]]
Expand All @@ -121,13 +126,13 @@ You can define your protocol like this: (you need to replace all the field as `<
check_exit_code = <i32> # [optional] set this field to check the exit code of process
```

* other supported format
* Other supported format

```toml
[[xxx.steps]]
step_name = "your sub-process name"
process = "your command here"
process_wait = "sub-process name of the one to join" # can also be replace with `process_kill`
process_wait = "sub-process name of the one to join" # can also be replaced with `process_kill`
stdout_file = "your file name"
stderr_file = "your file name"
exit_code = "your file name"
Expand All @@ -137,12 +142,12 @@ You can define your protocol like this: (you need to replace all the field as `<
* Notes:

* `step_name` **cannot** start with `__`
* Besides the existing env variables, the subprocess will also get `COLINK_CORE_ADDR` and `COLINK_JWT` , which stand for the *server address* and *user jwt*.
* Besides the existing env variables, we will set two new variables named `COLINK_CORE_ADDR` and `COLINK_JWT` in the process, which stand for the *server address* and *user jwt*.
* If the exit code subprocess is not `0` (or not `9` after calling the *kill* action), the `wait` and `kill` action will throw an exception.

* variable transfer through CoLink
* Variable Transfer through CoLink

* send variable
* Send variable

```toml
[[xxx.steps]]
Expand All @@ -152,9 +157,9 @@ You can define your protocol like this: (you need to replace all the field as `<
index = 0 # [optional] not set for all ones
```

* receive variable
* Receive variable

this action will block the action until receiving the required variable
This action will block the action until receiving the required variable

```toml
[[xxx.steps]]
Expand All @@ -164,40 +169,40 @@ You can define your protocol like this: (you need to replace all the field as `<
index = 0 # [necessary] the index of the roles matched in participants
```

* entry actions of CoLink
* Entry Actions of CoLink

* create entry
* Create entry

```toml
[[xxx.steps]]
create_entry = "name of your entry"
file = "file of the content of entry"
```

* update entry
* Update entry

```toml
[[xxx.steps]]
update_entry = "name of the entry to update"
file = "file of the content of entry"
```

* read entry
* Read entry

```toml
[[xxx.steps]]
read_entry = "name of the entry to read"
file = "file to store the content of entry"
```

* delete entry
* Delete entry

```toml
[[xxx.steps]]
delete_entry = "name of the entry to delete"
```

* read_or_wait entry
* Read or Wait Entry

```toml
[[xxx.steps]]
Expand All @@ -207,5 +212,4 @@ You can define your protocol like this: (you need to replace all the field as `<

## Example

* There is an example that uses `playbook` to run `unifed-fedtree`, you can find it [here](https://github.com/walotta/colink-unifed-fedtree-playbook).

* An example that uses `playbook` to run `unifed-fedtree` can be found [here](https://github.com/walotta/colink-unifed-fedtree-playbook).

0 comments on commit 05bbac1

Please sign in to comment.