Crate escouade_plugin_protocol

Expand description

§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.