Crate escouade_plugin_protocol 

escouade-plugin-protocol

The protocol Escouade speaks to its plugins: JSON-RPC 2.0, one message a line. This crate holds what both sides share: the version, the methods, the messages of the handshake and of the extension points.

A plugin that answers at once, a state machine, needs nothing else, and the same source compiles in process and for wasm32-wasip1:

use escouade_plugin_protocol::{turn, Refusal};
use serde_json::{json, Value};

pub fn run() -> i32 {
    turn::run("example", json!({}), |method, _params: Value| {
        Err(Refusal::not_found(method))
    })
}

escouade_plugin_protocol::module!(run);

turn also gives what std cannot give a module: turn::instance_id() in place of std::process::id(), and turn::read_file() in place of std::fs.

A plugin whose calls wait on the network will rather take escouade-plugin-kit.

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.

Internals

The protocol Escouade speaks to its plugins (docs/PLUGINS.md §3, schemas/plugin-protocol-1.json): JSON-RPC 2.0, one message a line, on the plugin’s input and output. This crate holds what both sides share: the version, the names of the methods every plugin answers, the messages of the handshake, and serve, the loop a plugin written in Rust runs (escouade-plugins, the program of the plugins the app gives, INT-4).

Modules

code

The codes of a refusal (JSON-RPC’s own).

engine

The contract of a harness in process (INT-9, docs/PLUGINS.md §4.5 and §4.6): what the core and the plugin of a harness say to each other. The core launches the harness itself, from the description the plugin gives (engine/launch), after it checked it (the fence of private projects, read-only, the token of Escouade’s server never among the arguments, the files written in the agent’s own folder only). What the harness says comes to the plugin in batches of raw lines (agent/frames), which it translates into normalized items and effects (Item) that the core applies to the agent. What the plugin has to write to the harness comes back in its answers (writes), and the core writes it on the harness’s input. The PTY of a terminal view never goes through the plugin: only its launch (terminal/launch) and its hooks (terminal/hook), both ways.

forge

The data of the code hosts (docs/PLUGINS.md §4.5): what a host’s pull requests, checks, reviews and deployments are, as the core and the plugins that serve a host (forge/*) both know them. They travel as JSON, in camelCase; a plugin written in another language writes the same.

method

The methods Escouade calls on every plugin.

tickets

The data of the Kanban’s sources (docs/PLUGINS.md §4.5, tickets/*) as a plugin writes it: containers, states, tickets and their pages. The core reads them into its own types, which name the source by an id it interns (Service); here it is the string the data holds (github, gitlab…), the rest is the same JSON.

turn

A plugin in Rust on both targets (docs/PLUGINS.md §8.3): in process natively, a WASM reactor on wasm32-wasip1, with the same source.

Macros

module

Exports the turn of a plugin, run being what it runs at its start: escouade_plugin_protocol::module!(run);. A module’s first turn calls it; it keeps the plugin (turn::run, escouade_plugin_kit::serve::run), and every turn then runs on what came. Natively, it is nothing: escouade-plugins calls run.

Structs

Greeting

What Escouade said of itself at initialize, kept by greeted: what a process reads from its environment, a module has no other way to get (docs/PLUGINS.md §8.4.8).

Hello

What Escouade says first (initialize).

Named

Output

The output of a plugin that answers later, or says something without being asked: a line at a time, from any thread.

Refusal

A refusal: its code and its message.

Reply

How a request is answered, now or later; dropped, it is not (a notification has nothing to answer).

Request

A request or a notification, read from a line.

Version

Constants

PROTOCOL

The major version of the protocol, which escouade.api of a manifest and protocolVersion of the handshake name.

Functions

answer

The answer to a request: its result, or its refusal.

greeted

Keeps what the params of initialize say of Escouade (serve, the kit’s loop). Only the first counts: a process, or an instance, is told once.

greeting

What Escouade said at initialize: none before it. For the language of a plugin of the kit, see its i18n.

initialized

What the plugin answers to initialize: the version of the protocol it speaks (Escouade refuses any other) and what it can do.

json_line

The JSON value of a harness’s line. A harness written in JavaScript escapes a lone half of a UTF-16 pair (\ud83c), which JSON allows and serde refuses: the output of a tool that read a binary file was lost whole (ESC-290). Such a half is read as � (�).

serve

The loop of a plugin: reads a line at a time from input, answers the requests on output, calls handler for each method but the two of the handshake it answers itself (initialize with capabilities, shutdown, after which it returns). A line that is no request is answered with a parse error. Returns when input ends or after shutdown.

serve_later

serve for a plugin whose answers may wait (an HTTP client): handler answers by its Reply, from wherever it wants, and goes back to reading at once, so that a long call does not hold the others.