Crate escouade_plugin_kit 

escouade-plugin-kit

What the Rust plugins of Escouade share, so that a plugin is nothing but its client. The same source compiles in process and for wasm32-wasip1, without tokio or reqwest in the second case.

• serve: the loop of a plugin. Calls answer as they end, several at once, and the plugin can ask Escouade for its secrets and its settings while it answers (Cx).
• hosts: the service of code hosts and of the Kanban’s sources, and of their account. A plugin gives its kinds (ForgeKind, SourceKind); the account, its token, one client per account, the typed errors and the budget of calls are here.
• forge: the contract of a code host’s client.
• errors, text: an HTTP error and what it says, the criteria of a ticket’s description.
• http: the calls, and http::reqwest, a plugin’s client. It is reqwest in process and, in a module, the part of reqwest plugins use, over net/fetch.
• time: sleep and timeout, on tokio in process and on the host’s timers in a module.
• i18n: the language of the interface, as initialize says it.

use escouade_plugin_kit::forge::BoxFuture;
use escouade_plugin_kit::serve::{self, Cx, Plugin, Refusal};
use serde_json::Value;

struct Example;

impl Plugin for Example {
    fn call<'a>(&'a self, _cx: &'a Cx, method: &'a str, _params: Value) -> BoxFuture<'a, Result<Value, Refusal>> {
        Box::pin(async move { Err(Refusal::not_found(method)) })
    }
}

pub fn run() -> i32 {
    serve::run("example", Example)
}

escouade_plugin_kit::protocol::module!(run);

The reference of the plugins: https://escouade.dev/en/docs/plugins/api. The code is in Escouade’s repository. This crate is under the MIT licence; the app is under GPL-3.0-or-later.

Re-exports

pub use escouade_plugin_protocol as protocol;

Modules

errors

The errors of a service that the core tells apart: an HTTP error (401 says « reconnect the account »), a refusal that asking again would not change. They cross the protocol as codes (escouade_plugin_protocol::code) and come back as these very types in the core (plugins::adapters), so that a client in a plugin and one in the core fail alike.

forge

The contract of a code host’s client (docs/PLUGINS.md §4.5): what a plugin’s client does for one account, and what the core’s adapter of a plugin (ProcessForge) and the hosts still in the core do the same way. A call a host cannot do says Unsupported, which crosses the protocol as « no such method » (-32601).

hosts

The service of the code hosts and of the Kanban’s sources, for every plugin that serves some (docs/PLUGINS.md §4.4, §4.5): GitHub today, GitLab, Bitbucket, Gitea and Azure DevOps after it. A plugin gives its kinds — a ForgeKind for each host it serves, a SourceKind for each source — and Hosts answers the core’s adapters (ProcessForge, ProcessTicketSource) for them:

http

The calls of a plugin to its service: the HTTP client as Escouade’s network settings make it, and a call whose failure says what the service said (HttpError).

i18n

The language of the interface, in which a plugin of the first hand writes what the user reads (an error, a state’s name): French or English, as Escouade’s. A plugin is told it by initialize (a module has no environment, docs/PLUGINS.md §8.4.8); a process reads it from ESCOUADE_LANG (fr, en) before that. The core sets it as its own changes (set_ui).

serve

The loop of a plugin (docs/PLUGINS.md §3, PLG-2), asynchronous: JSON-RPC 2.0, one message a line. Each request is answered when it ends, several at once (a slow call does not hold back the others); a batch is answered as a batch. While it answers, the plugin may ask Escouade (Cx::request: its secrets, its settings) and write to its journal (Cx::log). initialize and shutdown are answered here.

text

The acceptance criteria of a ticket’s description, as every source reads them.

time

A plugin’s timers, whatever the target: tokio’s in process; in a module, the host’s (timer/set, timer/fired, docs/PLUGINS.md §8.4.5), a task waiting for its timer as it waits for any line.

Macros

tr

A text in the interface’s language.

tr_in

A text in lang: tr_in!(lang, "français {x}", "English {x}").