Skip to content

A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.

feat(plugins): run installed plugins as programs of their own

RoversX472fa44a2646
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 789ca5c2..710d6fbb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -85,7 +85,7 @@ directories:
| `thinkterm-gui` | `wezterm-gui/` | The terminal itself |
| `thinkterm-mux-server` | `wezterm-mux-server/` | The multiplexer server |
| `thinkterm` | `wezterm/` | The CLI |
-| `thinkterm-plugin-server` | `thinkterm-plugin-server/` | Runs the plugins (Snippets so far) apart from the mux; started when first needed |
+| `thinkterm-plugin-server` | `thinkterm-plugin-server/` | Runs the plugins (Snippets built in, installed ones as processes of their own) apart from the mux; started when first needed |
`wezterm/` also builds a `wezterm` binary. That is a deliberate compatibility
shim, not a leftover — the environment variables ThinkTerm sets promise that a
diff --git a/Cargo.lock b/Cargo.lock
index 0236b5cb..8e547461 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -8589,16 +8589,40 @@ dependencies = [
"wezterm-uds",
]
+[[package]]
+name = "thinkterm-plugin-example"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "base64 0.22.1",
+ "serde_json",
+ "thinkterm-plugin-sdk",
+ "uuid",
+]
+
+[[package]]
+name = "thinkterm-plugin-sdk"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "serde",
+ "serde_json",
+ "thinkterm-plugin-channel",
+]
+
[[package]]
name = "thinkterm-plugin-server"
version = "0.1.0"
dependencies = [
"anyhow",
"log",
+ "serde",
"serde_json",
"tempfile",
"thinkterm-plugin-channel",
+ "thinkterm-plugin-sdk",
"thinkterm-snippets",
+ "toml 0.8.23",
"wezterm-uds",
]
@@ -10212,6 +10236,7 @@ dependencies = [
"termwiz-funcs",
"textwrap",
"thinkterm-file-index",
+ "thinkterm-plugin-channel",
"thinkterm-proto",
"thinkterm-tui",
"thinkterm-update",
diff --git a/Cargo.toml b/Cargo.toml
index 12ae119e..e84a7d41 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -15,6 +15,8 @@ members = [
"thinkterm-render",
"thinkterm-mobile",
"thinkterm-plugin-channel",
+ "thinkterm-plugin-example",
+ "thinkterm-plugin-sdk",
"thinkterm-plugin-server",
"thinkterm-session",
"thinkterm-snippets",
@@ -182,6 +184,7 @@ thinkterm-font-core = { path = "thinkterm-font-core" }
thinkterm-font-web = { path = "thinkterm-font-web" }
thinkterm-i18n = { path = "thinkterm-i18n" }
thinkterm-plugin-channel = { path = "thinkterm-plugin-channel", default-features = false }
+thinkterm-plugin-sdk = { path = "thinkterm-plugin-sdk" }
thinkterm-proto = { path = "thinkterm-proto" }
thinkterm-render = { path = "thinkterm-render" }
thinkterm-session = { path = "thinkterm-session" }
diff --git a/docs/thinkterm/plugins.md b/docs/thinkterm/plugins.md
new file mode 100644
index 00000000..a953f2f7
--- /dev/null
+++ b/docs/thinkterm/plugins.md
@@ -0,0 +1,304 @@
+# Plugins
+
+**Status:** Version 1. A plugin provides data and functions: it answers
+calls, and tells the clients that watch it when something changed. A
+plugin's interface belongs in the sidebar, and installed plugins have none
+there yet. The desktop and the browser list them in Settings › Sidebar &
+Plugins, under the panels, and show nothing else of them; a plugin cannot
+show anything on its own. `thinkterm plugin call` calls one from the
+command line.
+
+Snippets is a built-in plugin that provides a panel: its switch is that
+panel's, among the panels in Settings › Sidebar & Plugins, and its row in
+the plugin list says which panel it provides.
+
+A plugin runs in `thinkterm-plugin-server`, a small process separate from
+the GUI and the mux. The desktop, a browser and the `thinkterm` command line
+are all clients of that process, and none of them holds a plugin's data or
+logic. Snippets is the first plugin. It is built into the server and uses the
+same interface as an installed plugin.
+
+```
+ desktop ─────────────────────────┐
+ browser ── mux (PluginFrame) ────┼──► thinkterm-plugin-server ──► built-in plugins (in process)
+ thinkterm plugin … ──────────────┘ │
+ └──► installed plugins (one process each, stdio)
+```
+
+- The mux only carries a browser's frames to the server. It does not read
+ them, and it keeps no plugin state.
+- A client starts the server when it first needs a plugin. The server exits
+ 30 seconds after the last client disconnects, and stops its plugin
+ processes when it does.
+- One server runs per user on each machine, and per build profile: a debug
+ build never talks to a release build's server.
+- The desktop and the command line use the server on their own machine. A
+ browser uses the one on the machine whose mux served its page. On a
+ headless host that is the server the server packages install there, with
+ that host's own snippets and plugins.
+
+## Installing a plugin
+
+A plugin is a directory that holds a `plugin.toml` and the program it runs.
+Put the directory under the plugins directory:
+
+| System | Plugins directory |
+|---------|---------------------------------------------------|
+| macOS | `~/Library/Application Support/ThinkTerm/plugins` |
+| Linux | `~/.local/share/ThinkTerm/plugins` |
+| Windows | `%APPDATA%\ThinkTerm\plugins` |
+
+`thinkterm plugin dir` prints the directory. There is no install step and no
+restart. ThinkTerm finds a new plugin the next time it looks: when Settings ›
+Sidebar opens, or when you run `thinkterm plugin list`. Deleting the
+directory uninstalls the plugin.
+
+A plugin's directory can be a symbolic link. That is the easiest way to work
+on one: link your source directory in, and rebuild. ThinkTerm restarts the
+plugin the next time it is used after its program changes.
+
+## `plugin.toml`
+
+```toml
+id = "text-tools" # required: a-z, 0-9 and "-", at most 64 characters
+name = "Text Tools" # required
+version = "0.1.0" # required; shown, not compared
+description = "Decodes text, and makes UUIDs."
+api = 1 # required: the plugin API version it speaks
+
+# Optional. The systems it runs on: "macos", "linux", "windows". Default: all.
+platforms = ["macos", "linux", "windows"]
+
+[run]
+# Found beside plugin.toml first, then on PATH. On Windows, ".exe" is
+# tried too.
+program = "thinkterm-plugin-example"
+args = []
+
+# Optional overrides for one system: [run.macos], [run.linux], [run.windows].
+[run.windows]
+program = "thinkterm-plugin-example.exe"
+
+# Optional translations, by language tag ("zh-CN") or language ("zh").
+[locales.zh-CN]
+name = "文本工具"
+description = "解码文字,生成 UUID。"
+```
+
+The id `plugins` is reserved, and an installed plugin cannot use a built-in
+plugin's id. If two installed plugins share an id, the one whose directory
+sorts first is used, and the other is shown as invalid.
+
+## What a plugin can do
+
+- **Calls.** A client can send the plugin any JSON value and receive any JSON
+ value back. This is how Snippets serves its panel.
+ `thinkterm plugin call <id> <json>` sends a call from the command line.
+- **Events.** During a call, a plugin can make the caller a watcher and send
+ events to its watchers. Snippets uses this to tell every panel on show that
+ the snippets changed.
+
+That is all. A plugin has no commands and sends no notifications: nothing of
+a plugin shows outside the sidebar.
+
+## The protocol
+
+ThinkTerm starts an installed plugin's program when the plugin is first
+needed. It talks to the program over standard input and output. Each message
+is one line of JSON, UTF-8, ending in `\n`, and no longer than 16 MiB.
+Anything the program writes to standard error goes to the plugin server's log
+(`plugins-log` in the runtime directory), a line at a time under the plugin's
+id. Past 4 MiB from all plugins together, the rest is dropped until the server
+starts again.
+
+The program starts with these environment variables, in its own directory:
+
+| Variable | Value |
+|-------------------------|----------------------------------------------------|
+| `THINKTERM_PLUGIN_ID` | its id |
+| `THINKTERM_PLUGIN_DIR` | its directory |
+| `THINKTERM_PLUGIN_DATA` | a directory for its own files, created before start |
+| `THINKTERM_PLUGIN_API` | `1` |
+
+`WEZTERM_PANE` and `WEZTERM_UNIX_SOCKET` are not passed on: the pane or mux
+the plugin server happened to be started from says nothing about a plugin.
+
+The program's first line must be:
+
+```json
+{"type":"ready","api":1}
+```
+
+ThinkTerm then sends it:
+
+```json
+{"type":"call","id":1,"body":{"op":"decode","text":"aGk="}}
+{"type":"call","id":2,"body":{"op":"frobnicate"}}
+{"type":"stop"}
+```
+
+The program answers each `call` by its `id`, in any order:
+
+```json
+{"type":"ok","id":1,"body":{"kind":"Base64","text":"hi"}}
+{"type":"error","id":2,"message":"unknown op"}
+```
+
+An answer may add `"watch": true` to make the caller a watcher. The program
+can also send an event at any time:
+
+```json
+{"type":"event","body":{"event":"changed"}}
+```
+
+After `stop`, standard input closes. The program must exit then, or when
+standard input closes for any other reason. A program that is still running
+2 seconds later is killed. No new program starts under the same id until the
+old one is gone, since the two would share the data directory; calls made
+meanwhile wait for it. ThinkTerm ignores lines it cannot read and message
+types it does not know, and so should the program.
+
+## Rust SDK
+
+`thinkterm-plugin-sdk` implements the protocol. A plugin implements `Plugin`
+and hands it to `run`:
+
+```rust
+use serde_json::{json, Value};
+use thinkterm_plugin_sdk::{Cx, Plugin};
+
+struct Hello;
+
+impl Plugin for Hello {
+ fn call(&mut self, body: Value, _cx: &mut Cx) -> anyhow::Result<Value> {
+ match body["op"].as_str() {
+ Some("greet") => Ok(json!("hello")),
+ _ => anyhow::bail!("no such call"),
+ }
+ }
+}
+
+fn main() -> std::io::Result<()> {
+ thinkterm_plugin_sdk::run(Hello)
+}
+```
+
+- `run` returns when ThinkTerm stops the plugin, so `main` can clean up.
+ Standard output belongs to the protocol: print with `eprintln!`.
+- `run_with` passes the plugin an `Emitter`, which can send events from
+ other threads.
+- Snippets implements the same trait. It runs inside the server, and it can
+ also run out of process: `thinkterm-plugin-server --serve-plugin snippets`.
+ The server's tests use that to exercise the protocol end to end.
+
+`thinkterm-plugin-example` is a complete plugin: a manifest and two calls.
+To install it and try it:
+
+```sh
+cargo build --release -p thinkterm-plugin-example
+dir="$(thinkterm plugin dir)/text-tools"
+mkdir -p "$dir"
+cp thinkterm-plugin-example/plugin.toml target/release/thinkterm-plugin-example "$dir/"
+thinkterm plugin list
+thinkterm plugin call text-tools '{"op":"decode","text":"aGk="}'
+```
+
+## Lifecycle
+
+Each plugin has a state. Clients show it, and the plugin list in Settings ›
+Sidebar shows the reason for a failed state.
+
+| State | Meaning | Leaves it when |
+|---------------|------------------------------------------------------------|-------------------------------------------------|
+| `off` | Turned off | turned on |
+| `idle` | On, and not running. Built-in plugins are always `idle`. | it is used |
+| `starting` | The program started and has not said `ready` yet | `ready`, exit, or 10 seconds pass |
+| `running` | Ready, and answering | exit, turned off, reload, or the server exits |
+| `crashed` | Exited unexpectedly; the reason is kept | it is used again, which restarts it |
+| `failed` | Crashed 3 times within a minute, or cannot be started | reload, turned off and on, or its files change |
+| `invalid` | `plugin.toml` cannot be used; the reason is kept | the manifest is fixed |
+| `unsupported` | `platforms` does not include this system | the manifest changes |
+
+Nothing starts a plugin except a client that uses it: a call from the
+command line, or a panel on show. Calls that are waiting when a plugin
+stops are answered with an error. Nothing is retried on the plugin's behalf.
+
+## Reload
+
+| What | How it happens |
+|------------------------------|--------------------------------------------------------------------------------|
+| Find new and removed plugins | Each `list`: opening Settings › Sidebar & Plugins, `thinkterm plugin list` |
+| A changed `plugin.toml` | Read again at the next `list` or use. A running plugin is stopped first. |
+| A rebuilt program | Checked before each use. A running plugin is stopped and started again. |
+| One plugin, by hand | `thinkterm plugin reload <id>`: stop, read again, and clear `crashed`/`failed` |
+| Everything, by hand | Reload in Settings › Sidebar & Plugins, or `thinkterm plugin reload` |
+| The on/off switches | `plugins.json` is read again when another server changes it |
+| A newer ThinkTerm | Its clients replace the older server, and the older server stops its plugins |
+
+A client reconnects after the server restarts, and then asks for everything
+it shows again: the plugin list, a panel's rows, and so on. A client never
+treats what it last saw as current once the connection is gone.
+
+## State
+
+| What | Where | Owner |
+|-----------------------------|----------------------------------------|--------------------------------|
+| On/off switches | `<data>/plugins.json` | the plugin server |
+| A plugin's own files | `<data>/plugin-data/<id>/` | that plugin |
+| Snippets | `<data>/snippets.json` | the Snippets plugin |
+| Plugin list, states, calls | memory | the plugin server |
+| What a client shows | memory, per window or page | that client |
+
+`<data>` is the parent of the plugins directory. A plugin that is not listed
+in `plugins.json` is on. Turning a plugin off is written there, and the entry
+stays when the plugin is removed, so reinstalling it keeps it off.
+
+### What a client keeps
+
+Every client follows the same rules. The desktop keeps one connection for all
+of its windows, and a browser page keeps one through the mux.
+
+- **The plugin list** is asked for when the client connects, and again when
+ the server says it changed. Only one request is in flight at a time, and
+ changes that arrive meanwhile are folded into one more request. The last
+ list stays on show while a new one is on its way.
+- **A switch** shows the new position while the change is on its way. It
+ goes back if the server refuses, and the reason is shown.
+- **A call** waits up to 10 seconds for its answer.
+- **When the connection is lost**, a client shows that plugins are
+ unavailable, and asks again once it reconnects.
+- **The desktop** remembers whether Snippets was on the last time it heard,
+ so the right sidebar does not flicker at startup. The server's answer wins
+ when it arrives.
+
+## Command line
+
+```
+thinkterm plugin list plugins and their states
+thinkterm plugin enable <id>
+thinkterm plugin disable <id>
+thinkterm plugin reload [<id>]
+thinkterm plugin call <id> <json>
+thinkterm plugin dir where plugins are installed
+```
+
+## Security
+
+A plugin is a program you installed, and it runs as you, with your
+permissions. `platforms` in the manifest only decides where it runs; it does
+not restrict what it can do. ThinkTerm shows nothing for a plugin, but that
+does not stop the program itself from, say, showing a system notification or
+running `thinkterm cli`: only a sandbox would. ThinkTerm never starts a
+plugin on its own: it runs only when a client uses it. Nothing downloads or
+installs plugins for you.
+
+## Limits
+
+| Limit | Value |
+|------------------------------------------|------------|
+| Message size, either direction | 16 MiB |
+| Calls waiting on one plugin | 64 |
+| Time to say `ready` | 10 seconds |
+| Time to exit after `stop` | 2 seconds |
+| Crashes before `failed` | 3 in 60 s |
+| Standard error logged, all plugins | 4 MiB |
diff --git a/thinkterm-plugin-channel/src/client.rs b/thinkterm-plugin-channel/src/client.rs
index 0292b0f3..069cdf8c 100644
--- a/thinkterm-plugin-channel/src/client.rs
+++ b/thinkterm-plugin-channel/src/client.rs
@@ -266,14 +266,20 @@ pub const CALL_TIMEOUT: Duration = Duration::from_secs(10);
/// Dropping the session ends it.
pub struct Session {
jobs: Sender<Job>,
+ call_timeout: Duration,
+}
+
+/// A call on its way: to which plugin, what, how long it may wait for its
+/// answer, and whom to tell.
+struct Call {
+ plugin: String,
+ body: Value,
+ wait: Duration,
+ reply: Reply,
}
enum Job {
- Call {
- plugin: String,
- body: Value,
- reply: Reply,
- },
+ Call(Call),
/// What the host sent over connection number `.0`.
Heard(u64, io::Result<FromHost>),
Stop,
@@ -306,20 +312,33 @@ impl Session {
let readers = jobs.clone();
std::thread::Builder::new()
.name("plugin-session".into())
- .spawn(move || serve_session(host, call_timeout, queue, readers, notice))?;
- Ok(Self { jobs })
+ .spawn(move || serve_session(host, queue, readers, notice))?;
+ Ok(Self { jobs, call_timeout })
}
/// Asks `plugin`. `reply` is called with the answer on the session's
/// thread, or with why there is none.
pub fn call(&self, plugin: &str, body: Value, reply: impl FnOnce(Answer) + Send + 'static) {
- let job = Job::Call {
+ self.call_within(plugin, body, self.call_timeout, reply)
+ }
+
+ /// Asks `plugin`, waiting `wait` for the answer: for a call that is
+ /// known to take long.
+ pub fn call_within(
+ &self,
+ plugin: &str,
+ body: Value,
+ wait: Duration,
+ reply: impl FnOnce(Answer) + Send + 'static,
+ ) {
+ let job = Job::Call(Call {
plugin: plugin.to_string(),
body,
+ wait,
reply: Box::new(reply),
- };
- if let Err(mpsc::SendError(Job::Call { reply, .. })) = self.jobs.send(job) {
- reply(Err("the plugin session has ended".into()));
+ });
+ if let Err(mpsc::SendError(Job::Call(call))) = self.jobs.send(job) {
+ (call.reply)(Err("the plugin session has ended".into()));
}
}
}
@@ -330,13 +349,18 @@ impl Drop for Session {
}
}
-/// The calls sent and not yet answered: when each gives up, and whom to
-/// tell.
-type Waiting = HashMap<u64, (Instant, Reply)>;
+/// A call sent and not yet answered: when it gives up, how long that was,
+/// and whom to tell.
+struct Waiter {
+ deadline: Instant,
+ wait: Duration,
+ reply: Reply,
+}
+
+type Waiting = HashMap<u64, Waiter>;
fn serve_session(
host: Host,
- call_timeout: Duration,
queue: Receiver<Job>,
readers: Sender<Job>,
mut notice: impl FnMut(Notice),
@@ -345,7 +369,7 @@ fn serve_session(
let mut generation = 0u64;
let mut retry = SESSION_RETRY_FIRST;
// Calls made while there was no connection, sent on the next one.
- let mut queued: Vec<(String, Value, Reply)> = Vec::new();
+ let mut queued: Vec<Call> = Vec::new();
loop {
let connected = host.connect().and_then(|connection| {
let reader = connection.try_clone()?;
@@ -355,8 +379,8 @@ fn serve_session(
Ok(handles) => handles,
Err(err) => {
let why = format!("{err:#}");
- for (_, _, reply) in queued.drain(..) {
- reply(Err(why.clone()));
+ for call in queued.drain(..) {
+ (call.reply)(Err(why.clone()));
}
notice(Notice::Trouble(why));
if !pause(&queue, retry, &mut queued) {
@@ -390,27 +414,20 @@ fn serve_session(
let mut waiting = Waiting::new();
let mut alive = true;
- for (plugin, body, reply) in queued.drain(..) {
+ for call in queued.drain(..) {
if alive {
- let deadline = Instant::now() + call_timeout;
- alive = send_call(
- &mut connection,
- &mut next_id,
- &mut waiting,
- (plugin, body, reply),
- deadline,
- );
+ alive = send_call(&mut connection, &mut next_id, &mut waiting, call);
} else {
- reply(Err("the plugin host went away".into()));
+ (call.reply)(Err("the plugin host went away".into()));
}
}
while alive {
- let job = match waiting.values().map(|(deadline, _)| *deadline).min() {
+ let job = match waiting.values().map(|waiter| waiter.deadline).min() {
Some(deadline) => {
match queue.recv_timeout(deadline.saturating_duration_since(Instant::now())) {
Ok(job) => Ok(job),
Err(RecvTimeoutError::Timeout) => {
- give_up_overdue(&mut waiting, call_timeout);
+ give_up_overdue(&mut waiting);
continue;
}
Err(RecvTimeoutError::Disconnected) => Err(()),
@@ -419,30 +436,19 @@ fn serve_session(
None => queue.recv().map_err(drop),
};
match job {
- Ok(Job::Call {
- plugin,
- body,
- reply,
- }) => {
- let deadline = Instant::now() + call_timeout;
- alive = send_call(
- &mut connection,
- &mut next_id,
- &mut waiting,
- (plugin, body, reply),
- deadline,
- )
+ Ok(Job::Call(call)) => {
+ alive = send_call(&mut connection, &mut next_id, &mut waiting, call)
}
Ok(Job::Heard(from, _)) if from != generation => {}
Ok(Job::Heard(_, Ok(FromHost::Ok { id, body }))) => {
retry = SESSION_RETRY_FIRST;
- if let Some((_, reply)) = waiting.remove(&id) {
- reply(Ok(body));
+ if let Some(waiter) = waiting.remove(&id) {
+ (waiter.reply)(Ok(body));
}
}
Ok(Job::Heard(_, Ok(FromHost::Error { id, message }))) => {
- if let Some((_, reply)) = waiting.remove(&id) {
- reply(Err(message));
+ if let Some(waiter) = waiting.remove(&id) {
+ (waiter.reply)(Err(message));
}
}
Ok(Job::Heard(_, Ok(FromHost::Event { plugin, body }))) => {
@@ -452,16 +458,16 @@ fn serve_session(
Ok(Job::Heard(_, Err(_))) => alive = false,
Ok(Job::Stop) | Err(()) => {
connection.shutdown();
- for (_, (_, reply)) in waiting.drain() {
- reply(Err("the plugin session has ended".into()));
+ for (_, waiter) in waiting.drain() {
+ (waiter.reply)(Err("the plugin session has ended".into()));
}
return;
}
}
}
connection.shutdown();
- for (_, (_, reply)) in waiting.drain() {
- reply(Err("the plugin host went away".into()));
+ for (_, waiter) in waiting.drain() {
+ (waiter.reply)(Err("the plugin host went away".into()));
}
// A host that answered reset this; one that keeps failing is asked
// less and less often.
@@ -472,28 +478,32 @@ fn serve_session(
}
}
-/// Sends a call, to be answered through `reply` by `deadline`. False when
-/// the host has gone, which `reply` is told.
+/// Sends a call, to be answered through its reply once its wait is up at
+/// the latest. False when the host has gone, which the reply is told.
fn send_call(
connection: &mut Connection,
next_id: &mut u64,
waiting: &mut Waiting,
- (plugin, body, reply): (String, Value, Reply),
- deadline: Instant,
+ call: Call,
) -> bool {
*next_id += 1;
- let call = ToHost::Call {
+ let message = ToHost::Call {
id: *next_id,
- plugin,
- body,
+ plugin: call.plugin,
+ body: call.body,
};
- match connection.send(&call) {
+ match connection.send(&message) {
Ok(()) => {
- waiting.insert(*next_id, (deadline, reply));
+ let waiter = Waiter {
+ deadline: Instant::now() + call.wait,
+ wait: call.wait,
+ reply: call.reply,
+ };
+ waiting.insert(*next_id, waiter);
true
}
Err(err) => {
- reply(Err(format!("the plugin host went away: {err}")));
+ (call.reply)(Err(format!("the plugin host went away: {err}")));
false
}
}
@@ -501,17 +511,18 @@ fn send_call(
/// Tells the calls whose time is up that no answer is coming. One that
/// arrives later finds nobody waiting and is dropped.
-fn give_up_overdue(waiting: &mut Waiting, call_timeout: Duration) {
+fn give_up_overdue(waiting: &mut Waiting) {
let now = Instant::now();
let overdue: Vec<u64> = waiting
.iter()
- .filter(|(_, (deadline, _))| *deadline <= now)
+ .filter(|(_, waiter)| waiter.deadline <= now)
.map(|(id, _)| *id)
.collect();
for id in overdue {
- if let Some((_, reply)) = waiting.remove(&id) {
- reply(Err(format!(
- "the plugin host did not answer within {call_timeout:?}"
+ if let Some(waiter) = waiting.remove(&id) {
+ (waiter.reply)(Err(format!(
+ "the plugin host did not answer within {:?}",
+ waiter.wait
)));
}
}
@@ -520,7 +531,7 @@ fn give_up_overdue(waiting: &mut Waiting, call_timeout: Duration) {
/// Waits `delay` before the next attempt, keeping the calls made meanwhile;
/// a call cuts the wait short, since someone is waiting on it. False when
/// the session was ended.
-fn pause(queue: &Receiver<Job>, delay: Duration, queued: &mut Vec<(String, Value, Reply)>) -> bool {
+fn pause(queue: &Receiver<Job>, delay: Duration, queued: &mut Vec<Call>) -> bool {
let until = Instant::now() + delay;
loop {
let left = until.saturating_duration_since(Instant::now());
@@ -528,12 +539,8 @@ fn pause(queue: &Receiver<Job>, delay: Duration, queued: &mut Vec<(String, Value
return true;
}
match queue.recv_timeout(left) {
- Ok(Job::Call {
- plugin,
- body,
- reply,
- }) => {
- queued.push((plugin, body, reply));
+ Ok(Job::Call(call)) => {
+ queued.push(call);
return true;
}
Ok(Job::Heard(..)) => {}
diff --git a/thinkterm-plugin-channel/src/lib.rs b/thinkterm-plugin-channel/src/lib.rs
index a34dc68c..57727f49 100644
--- a/thinkterm-plugin-channel/src/lib.rs
+++ b/thinkterm-plugin-channel/src/lib.rs
@@ -13,10 +13,12 @@
//!
//! A frame is a little-endian `u32` length and that many bytes of JSON: a
//! [`wire::ToHost`] one way, a [`wire::FromHost`] the other. What a call's
-//! body means is up to the plugin it names.
+//! body means is up to the plugin it names; the host's own API, the list of
+//! plugins and their commands, is [`registry`].
#[cfg(feature = "native")]
pub mod client;
#[cfg(feature = "native")]
pub mod paths;
+pub mod registry;
pub mod wire;
diff --git a/thinkterm-plugin-channel/src/paths.rs b/thinkterm-plugin-channel/src/paths.rs
index 1e773d5a..cf235841 100644
--- a/thinkterm-plugin-channel/src/paths.rs
+++ b/thinkterm-plugin-channel/src/paths.rs
@@ -1,7 +1,7 @@
//! Where the plugin host lives on this machine. Every client works these
//! out the same way, so they all find the one host.
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
/// The directory the mux keeps its own socket in (config's `RUNTIME_DIR`),
/// worked out the same way without loading config: the host is a small
@@ -21,6 +21,16 @@ pub fn data_dir() -> PathBuf {
.join("ThinkTerm")
}
+/// Where the host looks for installed plugins, one directory each.
+pub fn plugins_dir() -> PathBuf {
+ plugins_dir_in(&data_dir())
+}
+
+/// The plugins directory of a host keeping its data in `data_dir`.
+pub fn plugins_dir_in(data_dir: &Path) -> PathBuf {
+ data_dir.join("plugins")
+}
+
fn home_dir() -> PathBuf {
dirs_next::home_dir().unwrap_or_default()
}
diff --git a/thinkterm-plugin-channel/src/registry.rs b/thinkterm-plugin-channel/src/registry.rs
new file mode 100644
index 00000000..25e36d65
--- /dev/null
+++ b/thinkterm-plugin-channel/src/registry.rs
@@ -0,0 +1,170 @@
+//! The plugin host's own API: the plugins it knows, turning them on and
+//! off, and reloading them. It is called as the plugin named [`PLUGIN`],
+//! and its events go to every client that asked for the list.
+
+use serde::{Deserialize, Serialize};
+
+/// The name calls address and events carry.
+pub const PLUGIN: &str = "plugins";
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "op", rename_all = "snake_case")]
+pub enum Request {
+ /// Every plugin, in the order a list shows them, with names in
+ /// `locale` where the plugin has them. Answered with `Vec<Info>`. The
+ /// caller is told of every change after it, and asks again.
+ List {
+ #[serde(default)]
+ locale: String,
+ },
+ /// Turn a plugin on or off. Answered with `null`; the change is
+ /// announced.
+ SetEnabled { id: String, enabled: bool },
+ /// Stop a plugin, read its manifest again and forget that it failed;
+ /// every installed plugin when `id` is absent, looking for new and
+ /// removed ones too. Answered with `null`; the change is announced.
+ Reload {
+ #[serde(default)]
+ id: Option<String>,
+ },
+}
+
+/// One plugin as a list shows it.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Info {
+ pub id: String,
+ pub name: String,
+ #[serde(default)]
+ pub description: String,
+ /// Empty for a built-in plugin, which is as new as the host.
+ #[serde(default)]
+ pub version: String,
+ #[serde(default)]
+ pub builtin: bool,
+ /// Where an installed plugin lives.
+ #[serde(default)]
+ pub dir: Option<String>,
+ pub enabled: bool,
+ pub state: State,
+}
+
+impl Info {
+ /// Whether it can be used: on, and not broken past using.
+ pub fn usable(&self) -> bool {
+ self.enabled && self.state.usable()
+ }
+}
+
+/// Where a plugin is in its life. A built-in plugin is `Off` or `Idle`:
+/// it runs inside the host and is never started or stopped.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum State {
+ /// Turned off.
+ Off,
+ /// On, and not running: started when something uses it.
+ Idle,
+ /// Its program started and has not said it is ready.
+ Starting,
+ Running,
+ /// Its program ended without being asked to; using the plugin starts it
+ /// again.
+ Crashed {
+ reason: String,
+ },
+ /// It crashed too often, or cannot be started. It stays so until it is
+ /// reloaded or its files change.
+ Failed {
+ reason: String,
+ },
+ /// Its manifest cannot be used.
+ Invalid {
+ reason: String,
+ },
+ /// It does not run on this system.
+ Unsupported {
+ reason: String,
+ },
+}
+
+impl State {
+ /// Whether using the plugin can work: it is not broken past using.
+ pub fn usable(&self) -> bool {
+ !matches!(
+ self,
+ Self::Off | Self::Failed { .. } | Self::Invalid { .. } | Self::Unsupported { .. }
+ )
+ }
+
+ /// Why it is not working, when it is not.
+ pub fn reason(&self) -> Option<&str> {
+ match self {
+ Self::Crashed { reason }
+ | Self::Failed { reason }
+ | Self::Invalid { reason }
+ | Self::Unsupported { reason } => Some(reason),
+ Self::Off | Self::Idle | Self::Starting | Self::Running => None,
+ }
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "event", rename_all = "snake_case")]
+pub enum Event {
+ /// Plugins came or went, were turned on or off, or changed state: a
+ /// list on show is to be asked for again.
+ Changed,
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::{json, to_value};
+
+ #[test]
+ fn requests_states_and_events_are_tagged_json() {
+ assert_eq!(
+ serde_json::from_value::<Request>(json!({"op": "list"})).unwrap(),
+ Request::List {
+ locale: String::new()
+ }
+ );
+ assert_eq!(
+ serde_json::from_value::<Request>(json!({"op": "reload"})).unwrap(),
+ Request::Reload { id: None }
+ );
+ assert!(serde_json::from_value::<Request>(json!({"op": "run"})).is_err());
+ assert_eq!(
+ to_value(State::Crashed {
+ reason: "exit status 1".into()
+ })
+ .unwrap(),
+ json!({"kind": "crashed", "reason": "exit status 1"})
+ );
+ assert_eq!(to_value(State::Idle).unwrap(), json!({"kind": "idle"}));
+ assert_eq!(
+ to_value(Event::Changed).unwrap(),
+ json!({"event": "changed"})
+ );
+ }
+
+ #[test]
+ fn a_plugin_is_usable_while_on_and_not_broken() {
+ let mut info = Info {
+ id: "a".into(),
+ name: "A".into(),
+ description: String::new(),
+ version: String::new(),
+ builtin: false,
+ dir: None,
+ enabled: true,
+ state: State::Idle,
+ };
+ assert!(info.usable());
+ info.state = State::Failed {
+ reason: "no".into(),
+ };
+ assert!(!info.usable());
+ assert_eq!(info.state.reason(), Some("no"));
+ }
+}
diff --git a/thinkterm-plugin-channel/src/wire.rs b/thinkterm-plugin-channel/src/wire.rs
index 41fa2d63..e2d3820f 100644
--- a/thinkterm-plugin-channel/src/wire.rs
+++ b/thinkterm-plugin-channel/src/wire.rs
@@ -4,10 +4,12 @@ use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::io::{self, Read, Write};
-/// The version of this format. A client that finds a host speaking an
-/// older one asks it to quit and starts its own; one that finds a newer
-/// host leaves it alone.
-pub const PROTOCOL: u32 = 1;
+/// The version of this format and of what the host answers. A client that
+/// finds a host speaking an older one asks it to quit and starts its own;
+/// one that finds a newer host leaves it alone. 2 added the host's own API
+/// (`registry`) and installed plugins; 3 took commands and notifications
+/// out of it.
+pub const PROTOCOL: u32 = 3;
/// The largest frame either side sends or accepts, so a confused peer
/// cannot have the other allocate without bound. A thousand scripts of
diff --git a/thinkterm-plugin-example/Cargo.toml b/thinkterm-plugin-example/Cargo.toml
new file mode 100644
index 00000000..92d6b0d3
--- /dev/null
+++ b/thinkterm-plugin-example/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "thinkterm-plugin-example"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+# An example ThinkTerm plugin, to copy and change. Its dependencies name
+# their versions rather than the workspace's, so the directory builds on
+# its own once the SDK path below points at a checkout of ThinkTerm.
+
+[dependencies]
+anyhow = "1.0"
+base64 = { version = "0.22", default-features = false, features = ["std"] }
+serde_json = "1.0"
+thinkterm-plugin-sdk = { path = "../thinkterm-plugin-sdk" }
+uuid = { version = "1.13", features = ["v4"] }
diff --git a/thinkterm-plugin-example/plugin.toml b/thinkterm-plugin-example/plugin.toml
new file mode 100644
index 00000000..bc487c6d
--- /dev/null
+++ b/thinkterm-plugin-example/plugin.toml
@@ -0,0 +1,29 @@
+# The manifest ThinkTerm reads to find this plugin and its program.
+# docs/thinkterm/plugins.md describes every key.
+id = "text-tools"
+name = "Text Tools"
+version = "0.1.0"
+description = "Decodes text, and makes UUIDs."
+api = 1
+
+[run]
+program = "thinkterm-plugin-example"
+
+[run.windows]
+program = "thinkterm-plugin-example.exe"
+
+[locales.zh-CN]
+name = "文本工具"
+description = "解码文字,生成 UUID。"
+
+[locales.ja-JP]
+name = "テキストツール"
+description = "テキストをデコードし、UUID を作ります。"
+
+[locales.de-DE]
+name = "Textwerkzeuge"
+description = "Dekodiert Text und erzeugt UUIDs."
+
+[locales.fr-FR]
+name = "Outils de texte"
+description = "Décode du texte et crée des UUID."
diff --git a/thinkterm-plugin-example/src/main.rs b/thinkterm-plugin-example/src/main.rs
new file mode 100644
index 00000000..c90e8d39
--- /dev/null
+++ b/thinkterm-plugin-example/src/main.rs
@@ -0,0 +1,250 @@
+//! An example ThinkTerm plugin: two calls, in one small program. To make
+//! one of your own, copy this directory, change the id in plugin.toml and
+//! the name in Cargo.toml, and change what the calls do.
+//! docs/thinkterm/plugins.md says how to install it.
+//!
+//! - `{"op": "decode", "text": "…"}` answers with what the text decodes
+//! to, or `null`:
+//! `thinkterm plugin call text-tools '{"op":"decode","text":"aGk="}'`.
+//! - `{"op": "uuid"}` answers with a new UUID.
+
+use anyhow::{bail, Context as _};
+use base64::alphabet;
+use base64::engine::general_purpose::{GeneralPurpose, GeneralPurposeConfig};
+use base64::engine::DecodePaddingMode;
+use base64::Engine as _;
+use serde_json::{json, Value};
+use thinkterm_plugin_sdk::{Cx, Plugin};
+
+struct TextTools;
+
+impl Plugin for TextTools {
+ fn call(&mut self, body: Value, _cx: &mut Cx) -> anyhow::Result<Value> {
+ match body["op"].as_str() {
+ Some("decode") => {
+ let text = body["text"]
+ .as_str()
+ .context("\"decode\" needs a \"text\"")?;
+ Ok(match decode(text.trim()) {
+ Some(decoded) => json!({"kind": decoded.kind, "text": decoded.text}),
+ None => Value::Null,
+ })
+ }
+ Some("uuid") => Ok(json!(uuid::Uuid::new_v4().to_string())),
+ _ => bail!("unknown op; this plugin knows \"decode\" and \"uuid\""),
+ }
+ }
+}
+
+fn main() -> std::io::Result<()> {
+ thinkterm_plugin_sdk::run(TextTools)
+}
+
+#[derive(Debug, PartialEq)]
+struct Decoded {
+ kind: &'static str,
+ text: String,
+}
+
+/// What `text` decodes to, trying a JWT, a Unix time, URL encoding and
+/// Base64 in that order.
+fn decode(text: &str) -> Option<Decoded> {
+ if text.is_empty() {
+ return None;
+ }
+ jwt(text)
+ .or_else(|| unix_time(text))
+ .or_else(|| percent(text))
+ .or_else(|| base64_text(text))
+}
+
+/// Base64 in either alphabet, padded or not.
+fn base64_bytes(text: &str) -> Option<Vec<u8>> {
+ let config =
+ GeneralPurposeConfig::new().with_decode_padding_mode(DecodePaddingMode::Indifferent);
+ GeneralPurpose::new(&alphabet::STANDARD, config)
+ .decode(text)
+ .or_else(|_| GeneralPurpose::new(&alphabet::URL_SAFE, config).decode(text))
+ .ok()
+}
+
+/// A JSON Web Token: its header and payload, the signature left out.
+fn jwt(text: &str) -> Option<Decoded> {
+ let mut parts = text.split('.');
+ let (header, payload, _signature) = (parts.next()?, parts.next()?, parts.next()?);
+ if parts.next().is_some() {
+ return None;
+ }
+ let object = |part: &str| {
+ serde_json::from_slice::<Value>(&base64_bytes(part)?)
+ .ok()
+ .filter(Value::is_object)
+ };
+ let pretty = |value: &Value| serde_json::to_string_pretty(value).unwrap_or_default();
+ Some(Decoded {
+ kind: "JWT",
+ text: format!(
+ "{}\n{}",
+ pretty(&object(header)?),
+ pretty(&object(payload)?)
+ ),
+ })
+}
+
+/// Seconds (ten digits) or milliseconds (thirteen) since 1970, as a date.
+fn unix_time(text: &str) -> Option<Decoded> {
+ if !text.bytes().all(|byte| byte.is_ascii_digit()) {
+ return None;
+ }
+ let seconds: i64 = match text.len() {
+ 10 => text.parse().ok()?,
+ 13 => text.parse::<i64>().ok()? / 1000,
+ _ => return None,
+ };
+ let (days, time) = (seconds.div_euclid(86_400), seconds.rem_euclid(86_400));
+ let (year, month, day) = civil_from_days(days);
+ Some(Decoded {
+ kind: "Unix time",
+ text: format!(
+ "{year:04}-{month:02}-{day:02} {:02}:{:02}:{:02} UTC",
+ time / 3600,
+ time / 60 % 60,
+ time % 60
+ ),
+ })
+}
+
+/// The date `days` after 1970-01-01, by Howard Hinnant's `civil_from_days`.
+fn civil_from_days(days: i64) -> (i64, u32, u32) {
+ let z = days + 719_468;
+ let era = z.div_euclid(146_097);
+ let day_of_era = z.rem_euclid(146_097);
+ let year_of_era =
+ (day_of_era - day_of_era / 1460 + day_of_era / 36_524 - day_of_era / 146_096) / 365;
+ let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
+ let shifted_month = (5 * day_of_year + 2) / 153;
+ let day = (day_of_year - (153 * shifted_month + 2) / 5 + 1) as u32;
+ let month = if shifted_month < 10 {
+ shifted_month + 3
+ } else {
+ shifted_month - 9
+ } as u32;
+ (year_of_era + era * 400 + i64::from(month <= 2), month, day)
+}
+
+/// Text with `%XX` escapes in it, unescaped.
+fn percent(text: &str) -> Option<Decoded> {
+ let bytes = text.as_bytes();
+ let mut out = Vec::with_capacity(bytes.len());
+ let mut escaped = false;
+ let mut at = 0;
+ while at < bytes.len() {
+ let hex = bytes
+ .get(at + 1..at + 3)
+ .filter(|digits| bytes[at] == b'%' && digits.iter().all(u8::is_ascii_hexdigit));
+ match hex {
+ Some(digits) => {
+ let digits = std::str::from_utf8(digits).ok()?;
+ out.push(u8::from_str_radix(digits, 16).ok()?);
+ escaped = true;
+ at += 3;
+ }
+ None => {
+ out.push(bytes[at]);
+ at += 1;
+ }
+ }
+ }
+ if !escaped {
+ return None;
+ }
+ Some(Decoded {
+ kind: "URL encoding",
+ text: String::from_utf8(out).ok()?,
+ })
+}
+
+/// Base64 that decodes to readable text.
+fn base64_text(text: &str) -> Option<Decoded> {
+ let compact: String = text.split_ascii_whitespace().collect();
+ if compact.len() < 4 {
+ return None;
+ }
+ let decoded = String::from_utf8(base64_bytes(&compact)?).ok()?;
+ if decoded
+ .chars()
+ .any(|c| c.is_control() && !matches!(c, '\n' | '\r' | '\t'))
+ {
+ return None;
+ }
+ Some(Decoded {
+ kind: "Base64",
+ text: decoded,
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+
+ fn decoded(text: &str) -> (&'static str, String) {
+ let found = decode(text).unwrap_or_else(|| panic!("{text:?} did not decode"));
+ (found.kind, found.text)
+ }
+
+ #[test]
+ fn each_kind_decodes() {
+ assert_eq!(
+ decoded("aGVsbG8gd29ybGQ="),
+ ("Base64", "hello world".into())
+ );
+ assert_eq!(decoded("aGVsbG8gd29ybGQ"), ("Base64", "hello world".into()));
+ assert_eq!(decoded("a%20b%2Fc"), ("URL encoding", "a b/c".into()));
+ assert_eq!(
+ decoded("1700000000"),
+ ("Unix time", "2023-11-14 22:13:20 UTC".into())
+ );
+ assert_eq!(
+ decoded("1700000000123"),
+ ("Unix time", "2023-11-14 22:13:20 UTC".into())
+ );
+ let token = format!(
+ "{}.{}.signature",
+ URL_SAFE_NO_PAD.encode(r#"{"alg":"HS256"}"#),
+ URL_SAFE_NO_PAD.encode(r#"{"sub":"example"}"#)
+ );
+ let (kind, text) = decoded(&token);
+ assert_eq!(kind, "JWT");
+ assert!(text.contains("\"alg\": \"HS256\"") && text.contains("\"sub\": \"example\""));
+ }
+
+ #[test]
+ fn what_is_not_encoded_is_not_decoded() {
+ for text in ["", "test", "hello world", "12345", "100%", "%zz", "a.b.c"] {
+ assert_eq!(decode(text), None, "{text:?}");
+ }
+ }
+
+ #[test]
+ fn the_calls() {
+ let mut plugin = TextTools;
+ let mut cx = Cx::new();
+ assert_eq!(
+ plugin
+ .call(json!({"op": "decode", "text": " aGk= \n"}), &mut cx)
+ .unwrap(),
+ json!({"kind": "Base64", "text": "hi"})
+ );
+ assert_eq!(
+ plugin
+ .call(json!({"op": "decode", "text": ""}), &mut cx)
+ .unwrap(),
+ Value::Null
+ );
+ let made = plugin.call(json!({"op": "uuid"}), &mut cx).unwrap();
+ let made = uuid::Uuid::parse_str(made.as_str().unwrap()).unwrap();
+ assert_eq!(made.get_version_num(), 4);
+ assert!(plugin.call(json!({"op": "nope"}), &mut cx).is_err());
+ }
+}
diff --git a/thinkterm-plugin-sdk/Cargo.toml b/thinkterm-plugin-sdk/Cargo.toml
new file mode 100644
index 00000000..733a6520
--- /dev/null
+++ b/thinkterm-plugin-sdk/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "thinkterm-plugin-sdk"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+# What a ThinkTerm plugin is written with: the Plugin trait, and the loop
+# that speaks the plugin protocol over standard input and output. Kept to
+# serde and anyhow, so a plugin that uses it stays small.
+
+[dependencies]
+anyhow.workspace = true
+serde = { workspace = true, features = ["derive", "std"] }
+serde_json.workspace = true
+thinkterm-plugin-channel.workspace = true
diff --git a/thinkterm-plugin-sdk/src/lib.rs b/thinkterm-plugin-sdk/src/lib.rs
new file mode 100644
index 00000000..0c1757a7
--- /dev/null
+++ b/thinkterm-plugin-sdk/src/lib.rs
@@ -0,0 +1,293 @@
+//! Writing a ThinkTerm plugin.
+//!
+//! A plugin is a program that ThinkTerm starts when the plugin is first
+//! used, and talks to over the program's standard input and output (see
+//! [`protocol`], and docs/thinkterm/plugins.md for the manifest that goes
+//! with it). Implement [`Plugin`] and hand it to [`run`]:
+//!
+//! ```no_run
+//! use serde_json::{json, Value};
+//! use thinkterm_plugin_sdk::{Cx, Plugin};
+//!
+//! struct Hello;
+//!
+//! impl Plugin for Hello {
+//! fn call(&mut self, body: Value, _cx: &mut Cx) -> anyhow::Result<Value> {
+//! match body["op"].as_str() {
+//! Some("greet") => Ok(json!("hello")),
+//! _ => anyhow::bail!("no such call"),
+//! }
+//! }
+//! }
+//!
+//! fn main() -> std::io::Result<()> {
+//! thinkterm_plugin_sdk::run(Hello)
+//! }
+//! ```
+//!
+//! The plugins built into ThinkTerm implement the same trait, and run
+//! inside the plugin host instead of in a program of their own.
+
+pub mod protocol;
+
+use anyhow::anyhow;
+use protocol::{FromPlugin, ToPlugin};
+use serde_json::Value;
+use std::io::{self, BufRead};
+use std::panic::AssertUnwindSafe;
+use std::path::PathBuf;
+
+pub trait Plugin: Send {
+ /// Answers a client's call: any JSON, as the plugin defines it. The
+ /// default takes no calls.
+ fn call(&mut self, body: Value, cx: &mut Cx) -> anyhow::Result<Value> {
+ let _ = (body, cx);
+ anyhow::bail!("this plugin takes no calls")
+ }
+}
+
+/// A plugin chosen at run time, among several.
+impl<P: Plugin + ?Sized> Plugin for Box<P> {
+ fn call(&mut self, body: Value, cx: &mut Cx) -> anyhow::Result<Value> {
+ (**self).call(body, cx)
+ }
+}
+
+/// What a call does besides answering, all of it sent once the answer is.
+#[derive(Debug, Default)]
+pub struct Cx {
+ watch: bool,
+ events: Vec<Value>,
+}
+
+impl Cx {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// The caller is sent this plugin's events from now on: a client that
+ /// listed something, to hear when it changes.
+ pub fn watch(&mut self) {
+ self.watch = true;
+ }
+
+ /// Sends `event` to every client watching this plugin, the caller
+ /// included.
+ pub fn emit(&mut self, event: Value) {
+ self.events.push(event);
+ }
+
+ /// What was asked for, for whatever runs the plugin to carry out.
+ pub fn finish(self) -> Effects {
+ Effects {
+ watch: self.watch,
+ events: self.events,
+ }
+ }
+}
+
+#[derive(Debug, Default, PartialEq)]
+pub struct Effects {
+ pub watch: bool,
+ pub events: Vec<Value>,
+}
+
+/// Sends events from outside a call: from a thread the plugin keeps to
+/// watch something, say.
+#[derive(Debug, Clone)]
+pub struct Emitter {
+ _private: (),
+}
+
+impl Emitter {
+ pub fn emit(&self, event: Value) -> io::Result<()> {
+ send(&FromPlugin::Event { body: event })
+ }
+}
+
+fn send(message: &FromPlugin) -> io::Result<()> {
+ protocol::write_message(&mut io::stdout().lock(), message)
+}
+
+/// The directory ThinkTerm made for the plugin to keep its files in.
+pub fn data_dir() -> Option<PathBuf> {
+ std::env::var_os("THINKTERM_PLUGIN_DATA").map(PathBuf::from)
+}
+
+/// Serves `plugin` over standard input and output until ThinkTerm asks it
+/// to stop or closes its input, which is when the program is to exit.
+/// Standard output belongs to the protocol: print with `eprintln!`, which
+/// goes to ThinkTerm's plugin log.
+pub fn run(plugin: impl Plugin) -> io::Result<()> {
+ run_with(|_| plugin)
+}
+
+/// [`run`], for a plugin that sends events of its own accord: `make` is
+/// handed what sends them.
+pub fn run_with<P: Plugin>(make: impl FnOnce(Emitter) -> P) -> io::Result<()> {
+ let mut plugin = make(Emitter { _private: () });
+ send(&FromPlugin::Ready { api: protocol::API })?;
+ serve(&mut plugin, &mut io::stdin().lock(), &mut |message| {
+ send(message)
+ })
+}
+
+/// Answers what `input` asks until it ends or says stop.
+fn serve<P: Plugin>(
+ plugin: &mut P,
+ input: &mut impl BufRead,
+ out: &mut impl FnMut(&FromPlugin) -> io::Result<()>,
+) -> io::Result<()> {
+ let mut line = Vec::new();
+ while protocol::read_line(input, &mut line)? {
+ if line.iter().all(u8::is_ascii_whitespace) {
+ continue;
+ }
+ let message: ToPlugin = match serde_json::from_slice(&line) {
+ Ok(message) => message,
+ Err(err) => {
+ // One from a newer ThinkTerm, say. Its caller is told when
+ // it has one; anything else is let be.
+ let id = serde_json::from_slice::<Value>(&line)
+ .ok()
+ .and_then(|message| message.get("id")?.as_u64());
+ if let Some(id) = id {
+ out(&FromPlugin::Error {
+ id,
+ message: format!("not a message this plugin knows: {err}"),
+ })?;
+ }
+ continue;
+ }
+ };
+ match message {
+ ToPlugin::Call { id, body } => {
+ let mut cx = Cx::new();
+ let answer = guard(|| plugin.call(body, &mut cx));
+ answer_with(out, id, answer, cx)?;
+ }
+ ToPlugin::Stop => break,
+ }
+ }
+ Ok(())
+}
+
+/// A plugin that panics answers with an error and goes on serving; the
+/// panic itself is on standard error, in the log.
+fn guard<T>(work: impl FnOnce() -> anyhow::Result<T>) -> anyhow::Result<T> {
+ match std::panic::catch_unwind(AssertUnwindSafe(work)) {
+ Ok(result) => result,
+ Err(panic) => {
+ let why = panic
+ .downcast_ref::<&str>()
+ .map(|why| why.to_string())
+ .or_else(|| panic.downcast_ref::<String>().cloned())
+ .unwrap_or_default();
+ Err(anyhow!("the plugin panicked: {why}"))
+ }
+ }
+}
+
+fn answer_with(
+ out: &mut impl FnMut(&FromPlugin) -> io::Result<()>,
+ id: u64,
+ answer: anyhow::Result<Value>,
+ cx: Cx,
+) -> io::Result<()> {
+ let effects = cx.finish();
+ match answer {
+ Ok(body) => out(&FromPlugin::Ok {
+ id,
+ body,
+ watch: effects.watch,
+ })?,
+ Err(err) => out(&FromPlugin::Error {
+ id,
+ message: format!("{err:#}"),
+ })?,
+ }
+ for body in effects.events {
+ out(&FromPlugin::Event { body })?;
+ }
+ Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::json;
+
+ /// Counts calls, and lists as a watcher.
+ #[derive(Default)]
+ struct Counter {
+ calls: u64,
+ }
+
+ impl Plugin for Counter {
+ fn call(&mut self, body: Value, cx: &mut Cx) -> anyhow::Result<Value> {
+ match body["op"].as_str() {
+ Some("add") => {
+ self.calls += 1;
+ cx.emit(json!({"event": "changed"}));
+ Ok(json!(self.calls))
+ }
+ Some("get") => {
+ cx.watch();
+ Ok(json!(self.calls))
+ }
+ Some("boom") => panic!("boom"),
+ _ => anyhow::bail!("unknown op"),
+ }
+ }
+ }
+
+ fn serve_lines(input: &str) -> Vec<Value> {
+ let mut plugin = Counter::default();
+ let mut sent = Vec::new();
+ serve(&mut plugin, &mut input.as_bytes(), &mut |message| {
+ sent.push(serde_json::to_value(message).unwrap());
+ Ok(())
+ })
+ .unwrap();
+ sent
+ }
+
+ #[test]
+ fn calls_are_answered_by_id_with_their_events_after() {
+ let sent = serve_lines(concat!(
+ "{\"type\":\"call\",\"id\":1,\"body\":{\"op\":\"get\"}}\n",
+ "\n",
+ "{\"type\":\"call\",\"id\":2,\"body\":{\"op\":\"add\"}}\n",
+ "{\"type\":\"call\",\"id\":3,\"body\":{\"op\":\"nope\"}}\n",
+ ));
+ assert_eq!(
+ sent,
+ [
+ json!({"type": "ok", "id": 1, "body": 0, "watch": true}),
+ json!({"type": "ok", "id": 2, "body": 1}),
+ json!({"type": "event", "body": {"event": "changed"}}),
+ json!({"type": "error", "id": 3, "message": "unknown op"}),
+ ]
+ );
+ }
+
+ #[test]
+ fn it_stops_when_told_and_outlives_a_panic_and_the_unknown() {
+ let sent = serve_lines(concat!(
+ "{\"type\":\"call\",\"id\":1,\"body\":{\"op\":\"boom\"}}\n",
+ "{\"type\":\"command\",\"id\":2,\"command\":\"decode\"}\n",
+ "{\"type\":\"frobnicate\"}\n",
+ "not json\n",
+ "{\"type\":\"stop\"}\n",
+ "{\"type\":\"call\",\"id\":3,\"body\":{\"op\":\"get\"}}\n",
+ ));
+ assert_eq!(sent.len(), 2, "{sent:?}");
+ assert_eq!(sent[0]["id"], 1);
+ assert!(sent[0]["message"]
+ .as_str()
+ .unwrap()
+ .contains("panicked: boom"));
+ assert_eq!(sent[1]["type"], "error");
+ assert_eq!(sent[1]["id"], 2);
+ }
+}
diff --git a/thinkterm-plugin-sdk/src/protocol.rs b/thinkterm-plugin-sdk/src/protocol.rs
new file mode 100644
index 00000000..59d26195
--- /dev/null
+++ b/thinkterm-plugin-sdk/src/protocol.rs
@@ -0,0 +1,160 @@
+//! The plugin protocol: what ThinkTerm and a plugin's program say to each
+//! other over the program's standard input and output. Each message is one
+//! line of JSON. docs/thinkterm/plugins.md describes it for plugins written
+//! in any language.
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::io::{self, BufRead, Read, Write};
+
+/// The version of this protocol: a manifest's `api`, which the program's
+/// `ready` repeats.
+pub const API: u32 = 1;
+
+/// The longest line either side sends or accepts, so that neither can make
+/// the other hold an input without bound. The same as a client's frame.
+pub const MAX_LINE: usize = thinkterm_plugin_channel::wire::MAX_FRAME;
+
+/// What ThinkTerm sends a plugin.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ToPlugin {
+ /// A client's call. Answered by an `ok` or an `error` with the same id.
+ Call {
+ id: u64,
+ #[serde(default)]
+ body: Value,
+ },
+ /// Exit now. Standard input closes after it.
+ Stop,
+}
+
+/// What a plugin sends ThinkTerm.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum FromPlugin {
+ /// The first line: the program is ready, and speaks this protocol.
+ Ready {
+ api: u32,
+ },
+ Ok {
+ id: u64,
+ #[serde(default)]
+ body: Value,
+ /// The caller is sent the plugin's events from now on.
+ #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+ watch: bool,
+ },
+ Error {
+ id: u64,
+ message: String,
+ },
+ /// For every client watching the plugin.
+ Event {
+ body: Value,
+ },
+}
+
+/// Writes `message` as one line, in a single write, so lines written from
+/// two threads never mix.
+pub fn write_message(to: &mut impl Write, message: &impl Serialize) -> io::Result<()> {
+ let mut line = serde_json::to_vec(message)?;
+ line.push(b'\n');
+ to.write_all(&line)?;
+ to.flush()
+}
+
+/// Reads one line into `line`, without its ending; false at the end of the
+/// input. A line longer than [`MAX_LINE`] is an error: what follows it
+/// cannot be told apart from it.
+pub fn read_line(from: &mut impl BufRead, line: &mut Vec<u8>) -> io::Result<bool> {
+ line.clear();
+ let read = Read::take(&mut *from, MAX_LINE as u64 + 1).read_until(b'\n', line)?;
+ if read == 0 {
+ return Ok(false);
+ }
+ if line.last() == Some(&b'\n') {
+ line.pop();
+ if line.last() == Some(&b'\r') {
+ line.pop();
+ }
+ } else if line.len() > MAX_LINE {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidData,
+ format!("a plugin message is limited to {MAX_LINE} bytes"),
+ ));
+ }
+ Ok(true)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::{json, to_value};
+
+ #[test]
+ fn messages_are_json_tagged_by_type() {
+ assert_eq!(
+ to_value(FromPlugin::Ready { api: API }).unwrap(),
+ json!({"type": "ready", "api": 1})
+ );
+ assert_eq!(
+ to_value(FromPlugin::Ok {
+ id: 1,
+ body: json!("hi"),
+ watch: false
+ })
+ .unwrap(),
+ json!({"type": "ok", "id": 1, "body": "hi"})
+ );
+ let ok: FromPlugin = serde_json::from_value(json!({"type": "ok", "id": 2})).unwrap();
+ assert_eq!(
+ ok,
+ FromPlugin::Ok {
+ id: 2,
+ body: Value::Null,
+ watch: false
+ }
+ );
+ let call: ToPlugin =
+ serde_json::from_value(json!({"type": "call", "id": 3, "body": {"op": "uuid"}}))
+ .unwrap();
+ assert_eq!(
+ call,
+ ToPlugin::Call {
+ id: 3,
+ body: json!({"op": "uuid"})
+ }
+ );
+ assert_eq!(to_value(ToPlugin::Stop).unwrap(), json!({"type": "stop"}));
+ // What a plugin can no longer send is not a message.
+ assert!(
+ serde_json::from_value::<FromPlugin>(json!({"type": "notify", "title": "x"})).is_err()
+ );
+ }
+
+ #[test]
+ fn lines_round_trip_and_refuse_what_is_too_long() {
+ let mut wire = Vec::new();
+ write_message(&mut wire, &FromPlugin::Ready { api: API }).unwrap();
+ wire.extend_from_slice(b"{\"type\":\"stop\"}\r\n");
+ wire.extend_from_slice(b"last");
+ let mut from = wire.as_slice();
+ let mut line = Vec::new();
+ assert!(read_line(&mut from, &mut line).unwrap());
+ assert_eq!(line, br#"{"type":"ready","api":1}"#);
+ assert!(read_line(&mut from, &mut line).unwrap());
+ assert_eq!(line, br#"{"type":"stop"}"#);
+ assert!(read_line(&mut from, &mut line).unwrap());
+ assert_eq!(line, b"last", "a last line may lack its ending");
+ assert!(!read_line(&mut from, &mut line).unwrap());
+
+ let huge = vec![b'x'; MAX_LINE + 1];
+ let err = read_line(&mut huge.as_slice(), &mut line).unwrap_err();
+ assert_eq!(err.kind(), io::ErrorKind::InvalidData);
+ let mut fits = vec![b'x'; MAX_LINE];
+ fits.push(b'\n');
+ assert!(read_line(&mut fits.as_slice(), &mut line).unwrap());
+ assert_eq!(line.len(), MAX_LINE);
+ }
+}
diff --git a/thinkterm-plugin-server/Cargo.toml b/thinkterm-plugin-server/Cargo.toml
index 15419159..88671d0e 100644
--- a/thinkterm-plugin-server/Cargo.toml
+++ b/thinkterm-plugin-server/Cargo.toml
@@ -14,10 +14,11 @@ path = "src/main.rs"
[dependencies]
anyhow.workspace = true
log.workspace = true
+serde = { workspace = true, features = ["derive", "std"] }
serde_json.workspace = true
+tempfile.workspace = true
thinkterm-plugin-channel = { workspace = true, features = ["native"] }
+thinkterm-plugin-sdk.workspace = true
thinkterm-snippets = { workspace = true, features = ["native"] }
+toml.workspace = true
wezterm-uds.workspace = true
-
-[dev-dependencies]
-tempfile.workspace = true
diff --git a/thinkterm-plugin-server/src/builtins.rs b/thinkterm-plugin-server/src/builtins.rs
new file mode 100644
index 00000000..ed086415
--- /dev/null
+++ b/thinkterm-plugin-server/src/builtins.rs
@@ -0,0 +1,36 @@
+//! The plugins built into the host.
+
+use crate::manifest::Manifest;
+use crate::registry::Builtin;
+use std::path::Path;
+use thinkterm_plugin_sdk::Plugin;
+
+/// Every built-in plugin, keeping its files in `data_dir`, in the order a
+/// list shows them.
+pub fn all(data_dir: &Path) -> Vec<Builtin> {
+ vec![Builtin {
+ manifest: Manifest::parse(include_str!("snippets.toml"), true)
+ .expect("the snippets manifest reads"),
+ plugin: Box::new(crate::snippets::Snippets::new(
+ data_dir.join("snippets.json"),
+ )),
+ }]
+}
+
+/// The built-in plugin `id` alone, to serve out of process.
+pub fn one(id: &str, data_dir: &Path) -> Option<Box<dyn Plugin>> {
+ all(data_dir)
+ .into_iter()
+ .find(|builtin| builtin.manifest.id == id)
+ .map(|builtin| builtin.plugin)
+}
+
+#[cfg(test)]
+mod tests {
+ #[test]
+ fn every_manifest_reads() {
+ let builtins = super::all(std::path::Path::new("/nonexistent"));
+ assert_eq!(builtins[0].manifest.id, "snippets");
+ assert_eq!(builtins[0].manifest.localized("zh-CN").name, "片段");
+ }
+}
diff --git a/thinkterm-plugin-server/src/host.rs b/thinkterm-plugin-server/src/host.rs
index 65bb3dd8..4aea28e6 100644
--- a/thinkterm-plugin-server/src/host.rs
+++ b/thinkterm-plugin-server/src/host.rs
@@ -3,16 +3,28 @@
//! Each client has a thread reading its calls and one writing what it is
//! sent, from a queue of its own: a client that stops reading loses its
//! connection instead of holding up everyone else's events.
+//!
+//! A call to a built-in plugin is answered on the caller's thread with the
+//! host locked. One to an installed plugin is handed to its program, and
+//! answered when the program answers, on the thread that reads it: a slow
+//! plugin holds up its own callers and nobody else. Calls addressed to
+//! [`api::PLUGIN`] are the host's own: the list of plugins, their switches,
+//! and reloading them.
+use crate::process::{Listener, Waiter};
+use crate::registry::{Fallout, Lookup, Message, Registry};
use serde_json::Value;
use std::collections::{HashMap, HashSet};
use std::fs;
use std::net::Shutdown;
use std::path::PathBuf;
use std::sync::mpsc::{sync_channel, SyncSender, TrySendError};
-use std::sync::{Arc, Mutex, MutexGuard};
+use std::sync::{Arc, Mutex, MutexGuard, Weak};
use std::time::{Duration, Instant};
+use thinkterm_plugin_channel::registry as api;
use thinkterm_plugin_channel::wire::{read_frame, write_frame, FromHost, ToHost, PROTOCOL};
+use thinkterm_plugin_sdk::protocol::{FromPlugin, ToPlugin};
+use thinkterm_plugin_sdk::Cx;
use wezterm_uds::UnixStream;
/// Frames that may wait for one client. A client this far behind is not
@@ -22,32 +34,16 @@ const QUEUE: usize = 256;
/// no use for megabytes of stack each.
const STACK: usize = 256 * 1024;
-/// A plugin as the host runs it.
-pub trait Plugin: Send {
- fn name(&self) -> &'static str;
-
- /// Answers `body`, a call from a client. The plugin may make the caller
- /// one of its watchers and leave events for all of them in `outcome`.
- fn call(&mut self, body: Value, outcome: &mut Outcome) -> anyhow::Result<Value>;
-}
-
-#[derive(Default)]
-pub struct Outcome {
- /// The caller is sent this plugin's events from now on.
- pub watch: bool,
- /// Sent to every watcher, the caller included, after the answer.
- pub events: Vec<Value>,
-}
-
struct Client {
outbox: SyncSender<Vec<u8>>,
/// Shut down to drop a client whose writer may be stuck in a write.
socket: UnixStream,
- watching: HashSet<&'static str>,
+ /// The plugins whose events it is sent; [`api::PLUGIN`] for the list's.
+ watching: HashSet<String>,
}
struct State {
- plugins: Vec<Box<dyn Plugin>>,
+ registry: Registry,
clients: HashMap<u64, Client>,
next_client: u64,
/// When the last client left, or the host started; `None` while anyone
@@ -59,22 +55,61 @@ pub struct Host {
state: Mutex<State>,
socket: PathBuf,
idle: Duration,
+ /// Itself, for what it starts from a program's threads to report to.
+ me: Weak<Host>,
+}
+
+/// What handling something leaves to send, in the order it goes out: the
+/// answers, then the plugins' events, then what the list's watchers hear.
+#[derive(Default)]
+struct Out {
+ answers: Vec<(u64, Vec<u8>)>,
+ /// Clients that start watching a plugin, before its events go out.
+ watch: Vec<(u64, String)>,
+ events: Vec<(String, Value)>,
+ changed: bool,
+ /// Not told of the change: it asked for the list, and has it.
+ fresh: Option<u64>,
+}
+
+impl Out {
+ fn answer(&mut self, client: u64, id: u64, answer: Result<Value, String>) {
+ let frame = match answer {
+ Ok(body) => FromHost::Ok { id, body },
+ Err(message) => FromHost::Error { id, message },
+ };
+ self.answers.push((client, frame.encode()));
+ }
+
+ fn fallout(&mut self, fallout: Fallout) {
+ for (waiter, why) in fallout.unanswered {
+ self.answer(waiter.client, waiter.id, Err(why));
+ }
+ self.changed |= fallout.changed;
+ }
}
impl Host {
- pub fn new(socket: PathBuf, idle: Duration, plugins: Vec<Box<dyn Plugin>>) -> Arc<Self> {
- Arc::new(Self {
+ pub fn new(socket: PathBuf, idle: Duration, registry: Registry) -> Arc<Self> {
+ Arc::new_cyclic(|me| Self {
state: Mutex::new(State {
- plugins,
+ registry,
clients: HashMap::new(),
next_client: 1,
idle_since: Some(Instant::now()),
}),
socket,
idle,
+ me: me.clone(),
})
}
+ /// Itself as what a program's threads report to.
+ fn listener(&self) -> Option<Arc<dyn Listener>> {
+ let me = self.me.upgrade()?;
+ Some(me)
+ }
+
fn state(&self) -> MutexGuard<'_, State> {
// A plugin that panicked mid-call leaves its own data as it was;
// the table of clients is updated only here, between calls.
@@ -139,7 +174,7 @@ impl Host {
}
}
- fn serve(&self, client: u64, mut stream: UnixStream) {
+ fn serve(self: &Arc<Self>, client: u64, mut stream: UnixStream) {
loop {
let frame = match read_frame(&mut stream) {
Ok(frame) => frame,
@@ -160,58 +195,123 @@ impl Host {
}
}
- fn call(&self, client: u64, id: u64, plugin: &str, body: Value) {
+ fn call(self: &Arc<Self>, client: u64, id: u64, plugin: &str, body: Value) {
let mut state = self.state();
- let state = &mut *state;
- let mut outcome = Outcome::default();
- let (name, answer) = match state.plugins.iter_mut().find(|p| p.name() == plugin) {
- Some(found) => (found.name(), found.call(body, &mut outcome)),
- None => {
- let answer = FromHost::Error {
- id,
- message: format!("there is no plugin named {plugin:?}"),
- };
- deliver(&mut state.clients, client, answer.encode());
- return;
+ let mut out = Out::default();
+ if plugin == api::PLUGIN {
+ self.manage(&mut state, client, id, body, &mut out);
+ } else {
+ self.ask(&mut state, client, id, plugin, body, &mut out);
+ }
+ send(&mut state, out);
+ }
+
+ /// A call to the host itself.
+ fn manage(
+ self: &Arc<Self>,
+ state: &mut State,
+ client: u64,
+ id: u64,
+ body: Value,
+ out: &mut Out,
+ ) {
+ let request = match serde_json::from_value::<api::Request>(body) {
+ Ok(request) => request,
+ Err(err) => {
+ let why = format!("not a request the plugin host knows: {err}");
+ return out.answer(client, id, Err(why));
}
};
- let answer = match answer {
- Ok(body) => FromHost::Ok { id, body },
- Err(err) => FromHost::Error {
- id,
- message: format!("{err:#}"),
- },
- };
- if outcome.watch {
- if let Some(caller) = state.clients.get_mut(&client) {
- caller.watching.insert(name);
+ let mut fallout = Fallout::default();
+ let answer = match request {
+ api::Request::List { locale } => {
+ state.registry.scan(&mut fallout);
+ out.watch.push((client, api::PLUGIN.to_string()));
+ out.fresh = Some(client);
+ Ok(serde_json::to_value(state.registry.list(&locale))
+ .expect("a plugin list always serialises"))
}
- }
- deliver(&mut state.clients, client, answer.encode());
- for body in outcome.events {
- let frame = FromHost::Event {
- plugin: name.to_string(),
- body,
+ api::Request::SetEnabled {
+ id: plugin,
+ enabled,
+ } => state
+ .registry
+ .set_enabled(&plugin, enabled, &mut fallout)
+ .map(|()| Value::Null),
+ api::Request::Reload { id: plugin } => state
+ .registry
+ .reload(plugin.as_deref(), &mut fallout)
+ .map(|()| Value::Null),
+ };
+ out.answer(client, id, answer);
+ out.fallout(fallout);
+ }
+
+ /// A call for the plugin `plugin`.
+ fn ask(
+ self: &Arc<Self>,
+ state: &mut State,
+ client: u64,
+ id: u64,
+ plugin: &str,
+ body: Value,
+ out: &mut Out,
+ ) {
+ let mut fallout = Fallout::default();
+ let found = state.registry.find(plugin, &mut fallout);
+ out.fallout(fallout);
+ match found {
+ Lookup::Missing => out.answer(
+ client,
+ id,
+ Err(format!("there is no plugin named {plugin:?}")),
+ ),
+ Lookup::Builtin(index) => {
+ let enabled = state.registry.enabled(plugin);
+ let builtin = state.registry.builtin(index);
+ if !enabled {
+ let why = format!("{} is turned off", builtin.manifest.name);
+ return out.answer(client, id, Err(why));
+ }
+ let mut cx = Cx::new();
+ let answer = builtin.plugin.call(body, &mut cx);
+ let effects = cx.finish();
+ if effects.watch && answer.is_ok() {
+ out.watch.push((client, plugin.to_string()));
+ }
+ out.answer(client, id, answer.map_err(|err| format!("{err:#}")));
+ out.events.extend(
+ effects
+ .events
+ .into_iter()
+ .map(|event| (plugin.to_string(), event)),
+ );
}
- .encode();
- let watchers: Vec<u64> = state
- .clients
- .iter()
- .filter(|(_, watcher)| watcher.watching.contains(name))
- .map(|(id, _)| *id)
- .collect();
- for watcher in watchers {
- deliver(&mut state.clients, watcher, frame.clone());
+ Lookup::Installed(index) => {
+ let listener: Arc<dyn Listener> = Arc::clone(self) as Arc<dyn Listener>;
+ let mut fallout = Fallout::default();
+ let message: Message = Box::new(move |asked| ToPlugin::Call { id: asked, body });
+ let asked = state.registry.ask(
+ plugin,
+ index,
+ Waiter { client, id },
+ message,
+ &listener,
+ &mut fallout,
+ );
+ if let Err(why) = asked {
+ out.answer(client, id, Err(why));
+ }
+ out.fallout(fallout);
}
}
- if state.clients.is_empty() {
- state.idle_since.get_or_insert_with(Instant::now);
- }
}
fn leave(&self, client: u64) {
let mut state = self.state();
state.clients.remove(&client);
+ // Nobody is left to answer: its calls free the plugins' slots.
+ state.registry.forget_client(client);
if state.clients.is_empty() {
state.idle_since.get_or_insert_with(Instant::now);
}
@@ -246,15 +346,130 @@ impl Host {
}
/// Removes the socket, so the next client starts a new host rather
- /// than finding a dead one, and exits. Every change is on disk by the
- /// time it is answered, and holding the table means no call is under
- /// way, so there is nothing left to save.
- fn exit(&self, _held: MutexGuard<'_, State>) -> ! {
+ /// than finding a dead one, stops the plugins' programs and exits.
+ /// Every change is on disk by the time it is answered, and holding the
+ /// table means no call is under way, so there is nothing left to save.
+ fn exit(&self, mut held: MutexGuard<'_, State>) -> ! {
let _ = fs::remove_file(&self.socket);
+ held.registry.shut_down();
std::process::exit(0);
}
}
+impl Listener for Host {
+ fn said(&self, plugin: &str, generation: u64, message: FromPlugin) {
+ let mut state = self.state();
+ let mut out = Out::default();
+ let mut fallout = Fallout::default();
+ let running = state.registry.process(plugin, generation).is_some();
+ match message {
+ FromPlugin::Ready { api } => {
+ state.registry.ready(plugin, generation, api, &mut fallout)
+ }
+ FromPlugin::Ok { id, body, watch } => {
+ let waiter = state
+ .registry
+ .process(plugin, generation)
+ .and_then(|process| process.answered(id));
+ if let Some(waiter) = waiter {
+ if watch {
+ out.watch.push((waiter.client, plugin.to_string()));
+ }
+ out.answer(waiter.client, waiter.id, Ok(body));
+ }
+ }
+ FromPlugin::Error { id, message } => {
+ let waiter = state
+ .registry
+ .process(plugin, generation)
+ .and_then(|process| process.answered(id));
+ if let Some(waiter) = waiter {
+ out.answer(waiter.client, waiter.id, Err(message));
+ }
+ }
+ FromPlugin::Event { body } if running => out.events.push((plugin.to_string(), body)),
+ FromPlugin::Event { .. } => {}
+ }
+ out.fallout(fallout);
+ send(&mut state, out);
+ }
+
+ fn ended(&self, plugin: &str, generation: u64, why: String) {
+ let Some(listener) = self.listener() else {
+ return;
+ };
+ let mut state = self.state();
+ let mut fallout = Fallout::default();
+ state
+ .registry
+ .ended(plugin, generation, why, &listener, &mut fallout);
+ let mut out = Out::default();
+ out.fallout(fallout);
+ send(&mut state, out);
+ }
+
+ fn late(&self, plugin: &str, generation: u64) {
+ let mut state = self.state();
+ let mut fallout = Fallout::default();
+ state.registry.late(plugin, generation, &mut fallout);
+ let mut out = Out::default();
+ out.fallout(fallout);
+ send(&mut state, out);
+ }
+}
+
+/// Sends what `out` holds.
+fn send(state: &mut State, out: Out) {
+ for (client, plugin) in out.watch {
+ if let Some(watcher) = state.clients.get_mut(&client) {
+ watcher.watching.insert(plugin);
+ }
+ }
+ for (client, frame) in out.answers {
+ deliver(&mut state.clients, client, frame);
+ }
+ for (plugin, body) in out.events {
+ let frame = FromHost::Event {
+ plugin: plugin.clone(),
+ body,
+ }
+ .encode();
+ tell_watchers(&mut state.clients, &plugin, None, frame);
+ }
+ if out.changed {
+ let frame = registry_event(&api::Event::Changed);
+ tell_watchers(&mut state.clients, api::PLUGIN, out.fresh, frame);
+ }
+ if state.clients.is_empty() {
+ state.idle_since.get_or_insert_with(Instant::now);
+ }
+}
+
+fn registry_event(event: &api::Event) -> Vec<u8> {
+ FromHost::Event {
+ plugin: api::PLUGIN.to_string(),
+ body: serde_json::to_value(event).expect("an event always serialises"),
+ }
+ .encode()
+}
+
+/// Queues `frame` for every client watching `plugin` but `except`.
+fn tell_watchers(
+ clients: &mut HashMap<u64, Client>,
+ plugin: &str,
+ except: Option<u64>,
+ frame: Vec<u8>,
+) {
+ let watchers: Vec<u64> = clients
+ .iter()
+ .filter(|(id, watcher)| Some(**id) != except && watcher.watching.contains(plugin))
+ .map(|(id, _)| *id)
+ .collect();
+ for watcher in watchers {
+ deliver(clients, watcher, frame.clone());
+ }
+}
+
/// Queues `frame` for `client`; one that is not keeping up is dropped,
/// which closes its queue and so its connection.
fn deliver(clients: &mut HashMap<u64, Client>, client: u64, frame: Vec<u8>) {
diff --git a/thinkterm-plugin-server/src/main.rs b/thinkterm-plugin-server/src/main.rs
index 8fce0d74..c4a9b85b 100644
--- a/thinkterm-plugin-server/src/main.rs
+++ b/thinkterm-plugin-server/src/main.rs
@@ -4,12 +4,22 @@
//! the socket (see thinkterm-plugin-channel); it exits by itself once nothing has
//! been connected for a while. One runs at a time: it holds a lock for as
//! long as it runs, and a second one gives way.
+//!
+//! The plugins built into it run inside it. An installed plugin runs as a
+//! program of its own, which the host starts when the plugin is first used
+//! and stops when it exits (see registry and docs/thinkterm/plugins.md).
// Started in the background, never from a console: no window of its own.
#![cfg_attr(windows, windows_subsystem = "windows")]
+mod builtins;
mod host;
+mod manifest;
+mod process;
+mod registry;
mod snippets;
+mod stamp;
+mod switches;
use anyhow::Context;
use std::fs::{self, File, OpenOptions, TryLockError};
@@ -24,12 +34,18 @@ const IDLE_EXIT: Duration = Duration::from_secs(30);
/// How long a host waits for the lock before leaving it to the one that
/// holds it: long enough for a host that was asked to quit to be gone.
const LOCK_WAIT: Duration = Duration::from_secs(3);
+/// How long an installed plugin's program has to say it is ready.
+const READY_WITHIN: Duration = Duration::from_secs(10);
struct Args {
socket: PathBuf,
lock: PathBuf,
data_dir: PathBuf,
idle: Duration,
+ ready_within: Duration,
+ /// Serve this built-in plugin over standard input and output, as an
+ /// installed plugin's program does, instead of being the host.
+ serve_plugin: Option<String>,
}
fn parse_args() -> Result<Args, String> {
@@ -38,6 +54,15 @@ fn parse_args() -> Result<Args, String> {
lock: paths::lock(),
data_dir: paths::data_dir(),
idle: IDLE_EXIT,
+ ready_within: READY_WITHIN,
+ serve_plugin: None,
+ };
+ let seconds = |name: &str, value: &std::ffi::OsStr| {
+ value
+ .to_str()
+ .and_then(|secs| secs.parse().ok())
+ .map(Duration::from_secs)
+ .ok_or_else(|| format!("{name} needs a number of seconds"))
};
let mut given = std::env::args_os().skip(1);
while let Some(arg) = given.next() {
@@ -49,13 +74,9 @@ fn parse_args() -> Result<Args, String> {
"--socket" => args.socket = value.into(),
"--lock" => args.lock = value.into(),
"--data-dir" => args.data_dir = value.into(),
- "--idle-secs" => {
- let secs = value
- .to_str()
- .and_then(|secs| secs.parse().ok())
- .ok_or_else(|| format!("{name} needs a number of seconds"))?;
- args.idle = Duration::from_secs(secs);
- }
+ "--idle-secs" => args.idle = seconds(&name, &value)?,
+ "--ready-secs" => args.ready_within = seconds(&name, &value)?,
+ "--serve-plugin" => args.serve_plugin = Some(value.to_string_lossy().into_owned()),
_ => return Err(format!("unknown argument {name}")),
}
}
@@ -102,6 +123,17 @@ fn main() {
std::process::exit(2);
}
};
+ if let Some(id) = &args.serve_plugin {
+ let Some(plugin) = builtins::one(id, &args.data_dir) else {
+ eprintln!("thinkterm-plugin-server: there is no built-in plugin {id:?}");
+ std::process::exit(2);
+ };
+ if let Err(err) = thinkterm_plugin_sdk::run(plugin) {
+ log::error!("serving {id}: {err}");
+ std::process::exit(1);
+ }
+ return;
+ }
if let Err(err) = run(args) {
log::error!("{err:#}");
std::process::exit(1);
@@ -125,10 +157,12 @@ fn run(args: Args) -> anyhow::Result<()> {
make_private(&args.socket);
log::info!("listening at {}", args.socket.display());
- let plugins: Vec<Box<dyn host::Plugin>> = vec![Box::new(snippets::Snippets::new(
- args.data_dir.join("snippets.json"),
- ))];
- let host = host::Host::new(args.socket, args.idle, plugins);
+ let registry = registry::Registry::new(
+ &args.data_dir,
+ builtins::all(&args.data_dir),
+ args.ready_within,
+ );
+ let host = host::Host::new(args.socket, args.idle, registry);
host.exit_when_idle();
for stream in listener.incoming() {
match stream {
diff --git a/thinkterm-plugin-server/src/manifest.rs b/thinkterm-plugin-server/src/manifest.rs
new file mode 100644
index 00000000..5f428a6d
--- /dev/null
+++ b/thinkterm-plugin-server/src/manifest.rs
@@ -0,0 +1,405 @@
+//! A plugin's manifest, `plugin.toml`: who the plugin is, and the program
+//! it runs. docs/thinkterm/plugins.md describes it.
+//! A built-in plugin has one too, without the program.
+
+use serde::Deserialize;
+use std::collections::BTreeMap;
+use std::io::ErrorKind;
+use std::path::{Path, PathBuf};
+use thinkterm_plugin_channel::registry;
+use thinkterm_plugin_sdk::protocol::API;
+
+pub const FILE: &str = "plugin.toml";
+/// The longest id: it names a directory, a switch, and every event.
+const ID_LIMIT: usize = 64;
+/// A file this long is not a manifest.
+const SIZE_LIMIT: u64 = 256 * 1024;
+
+#[derive(Debug, Deserialize)]
+struct Raw {
+ id: String,
+ name: String,
+ #[serde(default)]
+ version: String,
+ #[serde(default)]
+ description: String,
+ api: u32,
+ #[serde(default)]
+ platforms: Vec<String>,
+ #[serde(default)]
+ run: Option<RawRun>,
+ #[serde(default)]
+ locales: BTreeMap<String, RawLocale>,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct RawRun {
+ #[serde(default)]
+ program: Option<String>,
+ #[serde(default)]
+ args: Option<Vec<String>>,
+ #[serde(default)]
+ macos: Option<Box<RawRun>>,
+ #[serde(default)]
+ linux: Option<Box<RawRun>>,
+ #[serde(default)]
+ windows: Option<Box<RawRun>>,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct RawLocale {
+ #[serde(default)]
+ name: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct Manifest {
+ pub id: String,
+ pub name: String,
+ pub version: String,
+ pub description: String,
+ pub platforms: Vec<String>,
+ /// The program for this system, and its arguments. None for a built-in
+ /// plugin, and for one that does not run on this system.
+ run: Option<(String, Vec<String>)>,
+ /// By language tag, lowercased.
+ locales: BTreeMap<String, Locale>,
+}
+
+#[derive(Debug, Clone, Default, PartialEq)]
+struct Locale {
+ name: Option<String>,
+ description: Option<String>,
+}
+
+/// A plugin's name and description in one language.
+pub struct Localized<'a> {
+ pub name: &'a str,
+ pub description: &'a str,
+}
+
+/// Whether `id` can name a plugin: a-z, 0-9 and "-", starting with a letter
+/// or digit.
+pub fn valid_id(id: &str) -> bool {
+ !id.is_empty()
+ && id.len() <= ID_LIMIT
+ && !id.starts_with('-')
+ && id
+ .bytes()
+ .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
+}
+
+fn id_rule() -> String {
+ format!("a-z, 0-9 and \"-\", at most {ID_LIMIT} characters")
+}
+
+impl Manifest {
+ /// The manifest in an installed plugin's directory.
+ pub fn load(dir: &Path) -> Result<Self, String> {
+ let path = dir.join(FILE);
+ let meta = std::fs::metadata(&path).map_err(|err| match err.kind() {
+ ErrorKind::NotFound => format!("there is no {FILE}"),
+ _ => format!("{FILE}: {err}"),
+ })?;
+ if meta.len() > SIZE_LIMIT {
+ return Err(format!("{FILE} is larger than {SIZE_LIMIT} bytes"));
+ }
+ let text = std::fs::read_to_string(&path).map_err(|err| format!("{FILE}: {err}"))?;
+ Self::parse(&text, false)
+ }
+
+ /// A manifest's text. A built-in plugin's names no program.
+ pub fn parse(text: &str, builtin: bool) -> Result<Self, String> {
+ let raw: Raw = toml::from_str(text).map_err(|err| {
+ let line = err.span().map(|span| {
+ let before = &text.as_bytes()[..span.start.min(text.len())];
+ before.iter().filter(|byte| **byte == b'\n').count() + 1
+ });
+ match line {
+ Some(line) => format!("{FILE}, line {line}: {}", err.message()),
+ None => format!("{FILE}: {}", err.message()),
+ }
+ })?;
+ if !valid_id(&raw.id) {
+ return Err(format!("the id {:?} is not {}", raw.id, id_rule()));
+ }
+ if raw.id == registry::PLUGIN {
+ return Err(format!("the id {:?} is ThinkTerm's own", raw.id));
+ }
+ if raw.name.trim().is_empty() {
+ return Err("the name is empty".into());
+ }
+ if raw.api > API {
+ return Err(format!(
+ "it needs a newer ThinkTerm: it speaks plugin API {}, this one speaks {API}",
+ raw.api
+ ));
+ }
+ if raw.api == 0 {
+ return Err(format!("api must be {API}"));
+ }
+ let platforms: Vec<String> = raw
+ .platforms
+ .iter()
+ .map(|platform| platform.to_ascii_lowercase())
+ .collect();
+ let supported = supports(&platforms);
+ let run = match (builtin, raw.run) {
+ (true, None) => None,
+ (true, Some(_)) => return Err("a built-in plugin runs no program".into()),
+ (false, None) => return Err("there is no [run] section".into()),
+ (false, Some(_)) if !supported => None,
+ (false, Some(run)) => Some(run.for_this_system()?),
+ };
+ if !builtin && raw.version.trim().is_empty() {
+ return Err("the version is empty".into());
+ }
+ let locales = raw
+ .locales
+ .into_iter()
+ .map(|(tag, locale)| {
+ let locale = Locale {
+ name: locale.name.filter(|name| !name.trim().is_empty()),
+ description: locale.description,
+ };
+ (tag.to_ascii_lowercase(), locale)
+ })
+ .collect();
+ Ok(Self {
+ id: raw.id,
+ name: raw.name,
+ version: raw.version,
+ description: raw.description,
+ platforms,
+ run,
+ locales,
+ })
+ }
+
+ /// Whether it runs on this system.
+ pub fn supported(&self) -> bool {
+ supports(&self.platforms)
+ }
+
+ /// Its name and description in `locale`, where it has them: the tag
+ /// itself (`zh-CN`), else its language (`zh`), else another tag of the
+ /// same language.
+ pub fn localized(&self, locale: &str) -> Localized<'_> {
+ let found = self.locale_for(locale);
+ Localized {
+ name: found
+ .and_then(|found| found.name.as_deref())
+ .unwrap_or(&self.name),
+ description: found
+ .and_then(|found| found.description.as_deref())
+ .unwrap_or(&self.description),
+ }
+ }
+
+ fn locale_for(&self, tag: &str) -> Option<&Locale> {
+ let tag = tag.to_ascii_lowercase();
+ let language = tag
+ .split(['-', '_'])
+ .next()
+ .filter(|lang| !lang.is_empty())?;
+ self.locales
+ .get(&tag)
+ .or_else(|| self.locales.get(language))
+ .or_else(|| {
+ self.locales
+ .iter()
+ .find(|(key, _)| key.split(['-', '_']).next() == Some(language))
+ .map(|(_, found)| found)
+ })
+ }
+
+ /// The program to start for the plugin in `dir`, and its arguments: the
+ /// file beside the manifest when there is one, else, for a bare name, a
+ /// program on PATH.
+ pub fn program(&self, dir: &Path) -> Result<(PathBuf, Vec<String>), String> {
+ let Some((program, args)) = &self.run else {
+ return Err("it runs no program on this system".into());
+ };
+ let named = Path::new(program);
+ let found = if named.is_absolute() {
+ existing(named)
+ } else {
+ existing(&dir.join(named)).or_else(|| {
+ // A bare name, such as an interpreter.
+ (named.components().count() == 1)
+ .then(|| on_path(named))
+ .flatten()
+ })
+ };
+ match found {
+ Some(found) => Ok((found, args.clone())),
+ None => Err(format!("cannot find its program {program:?}")),
+ }
+ }
+}
+
+fn supports(platforms: &[String]) -> bool {
+ platforms.is_empty() || platforms.iter().any(|os| os == std::env::consts::OS)
+}
+
+impl RawRun {
+ /// The program and arguments for this system: its own section's, where
+ /// it has one, over the shared ones.
+ fn for_this_system(self) -> Result<(String, Vec<String>), String> {
+ let own = match std::env::consts::OS {
+ "macos" => self.macos,
+ "linux" => self.linux,
+ "windows" => self.windows,
+ _ => None,
+ };
+ let (program, args) = match own {
+ Some(own) => (own.program.or(self.program), own.args.or(self.args)),
+ None => (self.program, self.args),
+ };
+ let program = program
+ .filter(|program| !program.trim().is_empty())
+ .ok_or_else(|| format!("[run] names no program for {}", std::env::consts::OS))?;
+ Ok((program, args.unwrap_or_default()))
+ }
+}
+
+/// `path`, if it is a file; on Windows, with ".exe" added when that is.
+fn existing(path: &Path) -> Option<PathBuf> {
+ if path.is_file() {
+ return Some(path.to_path_buf());
+ }
+ if cfg!(windows) && path.extension().is_none() {
+ let exe = path.with_extension("exe");
+ if exe.is_file() {
+ return Some(exe);
+ }
+ }
+ None
+}
+
+fn on_path(name: &Path) -> Option<PathBuf> {
+ let path = std::env::var_os("PATH")?;
+ std::env::split_paths(&path).find_map(|dir| existing(&dir.join(name)))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const EXAMPLE: &str = r#"
+ id = "text-tools"
+ name = "Text Tools"
+ version = "0.1.0"
+ description = "Decodes things."
+ api = 1
+
+ [run]
+ program = "tool"
+ args = ["--stdio"]
+
+ [run.windows]
+ program = "tool.exe"
+
+ [locales.zh-CN]
+ name = "文本工具"
+
+ [locales.ja]
+ description = "デコード"
+ "#;
+
+ #[test]
+ fn a_manifest_reads_and_localizes() {
+ let manifest = Manifest::parse(EXAMPLE, false).unwrap();
+ assert_eq!(manifest.id, "text-tools");
+ let (program, args) = manifest.run.clone().unwrap();
+ assert_eq!(program, if cfg!(windows) { "tool.exe" } else { "tool" });
+ assert_eq!(args, ["--stdio"]);
+ assert!(manifest.supported());
+
+ let chinese = manifest.localized("zh-CN");
+ assert_eq!(chinese.name, "文本工具");
+ assert_eq!(chinese.description, "Decodes things.");
+ assert_eq!(manifest.localized("zh").name, "文本工具", "same language");
+ assert_eq!(manifest.localized("ja-JP").description, "デコード");
+ assert_eq!(manifest.localized("").name, "Text Tools");
+ assert_eq!(manifest.localized("de-DE").name, "Text Tools");
+ }
+
+ #[test]
+ fn what_a_manifest_must_not_be() {
+ let broken = |from: &str, to: &str| {
+ let text = EXAMPLE.replacen(from, to, 1);
+ Manifest::parse(&text, false).unwrap_err()
+ };
+ assert!(broken("text-tools", "Text Tools").contains("is not a-z"));
+ assert!(broken("text-tools", "plugins").contains("ThinkTerm's own"));
+ assert!(broken("api = 1", "api = 2").contains("newer ThinkTerm"));
+ assert!(broken("api = 1", "api = 0").contains("api must be"));
+ assert!(broken("version = \"0.1.0\"", "").contains("version"));
+ let unreadable = broken("[run]", "[run");
+ assert!(unreadable.starts_with("plugin.toml, line "), "{unreadable}");
+ assert!(Manifest::parse(EXAMPLE, true)
+ .unwrap_err()
+ .contains("runs no program"));
+ }
+
+ #[test]
+ fn an_error_says_the_line_it_is_on() {
+ // The second id starts its line.
+ let twice = Manifest::parse("id = \"a\"\nid = \"b\"\n", false).unwrap_err();
+ assert!(twice.starts_with("plugin.toml, line 2:"), "{twice}");
+ let first = Manifest::parse("id = \n", false).unwrap_err();
+ assert!(first.starts_with("plugin.toml, line 1:"), "{first}");
+ }
+
+ #[test]
+ fn a_plugin_for_another_system_needs_no_program_here() {
+ let elsewhere = if cfg!(windows) { "linux" } else { "windows" };
+ let text = format!(
+ "id = \"a\"\nname = \"A\"\nversion = \"1\"\napi = 1\nplatforms = [\"{elsewhere}\"]\n[run.{elsewhere}]\nprogram = \"a\"\n"
+ );
+ let manifest = Manifest::parse(&text, false).unwrap();
+ assert!(!manifest.supported());
+ assert!(manifest.program(Path::new(".")).is_err());
+ }
+
+ #[test]
+ fn the_program_is_found_beside_the_manifest_or_on_path() {
+ let dir = tempfile::tempdir().unwrap();
+ let manifest = Manifest::parse(EXAMPLE, false).unwrap();
+ assert!(manifest
+ .program(dir.path())
+ .unwrap_err()
+ .contains("cannot find"));
+ let name = if cfg!(windows) { "tool.exe" } else { "tool" };
+ std::fs::write(dir.path().join(name), "").unwrap();
+ let (found, _) = manifest.program(dir.path()).unwrap();
+ assert_eq!(found, dir.path().join(name));
+
+ let interpreter = if cfg!(windows) { "cmd" } else { "sh" };
+ let text = EXAMPLE
+ .replace(
+ "program = \"tool\"",
+ &format!("program = \"{interpreter}\""),
+ )
+ .replace(
+ "program = \"tool.exe\"",
+ &format!("program = \"{interpreter}\""),
+ );
+ let manifest = Manifest::parse(&text, false).unwrap();
+ let (found, _) = manifest.program(dir.path()).unwrap();
+ assert!(found.is_absolute(), "{found:?} is from PATH");
+ }
+
+ #[test]
+ fn ids() {
+ for id in ["a", "text-tools", "x2"] {
+ assert!(valid_id(id), "{id}");
+ }
+ for id in ["", "-a", "A", "a_b", "a b", &"a".repeat(65)] {
+ assert!(!valid_id(id), "{id}");
+ }
+ }
+}
diff --git a/thinkterm-plugin-server/src/process.rs b/thinkterm-plugin-server/src/process.rs
new file mode 100644
index 00000000..e6bfca81
--- /dev/null
+++ b/thinkterm-plugin-server/src/process.rs
@@ -0,0 +1,520 @@
+//! An installed plugin's program while it runs: the threads that carry its
+//! input and output, the calls it has not answered, and how it is stopped.
+//!
+//! Its input is written from a queue of its own, like a client's: a program
+//! that stops reading fills the queue, not the host's lock. What it says is
+//! read on a thread that hands every message to the host, and that reaps
+//! the program once its output ends.
+//!
+//! A program told to stop is [`Exiting`] until it is gone, and the host
+//! starts no other run of the plugin meanwhile: one writing its files on
+//! the way out would write over what a new run had already saved.
+
+use crate::stamp::Stamp;
+use std::collections::HashMap;
+use std::io::{BufRead, BufReader, Read, Write};
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, ExitStatus, Stdio};
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::mpsc::{sync_channel, SyncSender, TrySendError};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+use thinkterm_plugin_sdk::protocol::{self, FromPlugin, ToPlugin, API};
+
+/// Messages that may wait for one program. A program this far behind is
+/// not reading.
+const QUEUE: usize = 256;
+/// Calls one program may have unanswered.
+pub const PENDING_LIMIT: usize = 64;
+/// How long a call waits for its answer here. Longer than any client waits
+/// (`CALL_TIMEOUT`), so a call is only let go once whoever made it has given
+/// up: a plugin that never answers does not keep its slots.
+pub const PENDING_EXPIRY: Duration = Duration::from_secs(70);
+/// How long a program has to exit once asked to, or once its output ends.
+pub const STOP_GRACE: Duration = Duration::from_secs(2);
+/// Lines that are not messages logged for one program; a program that
+/// prints its debugging to standard output would fill the log otherwise.
+const NOISE_LOGGED: usize = 5;
+/// What the programs' standard error may put in the host's log between
+/// them while it runs. Past it, what they write is dropped: a program
+/// printing in a loop does not fill the disk. The log is cut back when the
+/// host next starts.
+const ERRORS_LOGGED: usize = 4 * 1024 * 1024;
+/// The longest stretch of standard error logged as one line.
+const ERROR_LINE: u64 = 4096;
+/// What is left of [`ERRORS_LOGGED`].
+static ERRORS_LEFT: AtomicUsize = AtomicUsize::new(ERRORS_LOGGED);
+const STACK: usize = 256 * 1024;
+
+/// What the host hears about a program, on the program's own threads.
+pub trait Listener: Send + Sync + 'static {
+ /// It said something.
+ fn said(&self, id: &str, generation: u64, message: FromPlugin);
+ /// It has exited, for `why`: its output ended, or it was told to stop
+ /// and is gone. Told once or twice for one run; the second time finds
+ /// nothing left to do.
+ fn ended(&self, id: &str, generation: u64, why: String);
+ /// Its time to say it is ready is up.
+ fn late(&self, id: &str, generation: u64);
+}
+
+/// Who is waiting for an answer: a client, and its own id for the call.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Waiter {
+ pub client: u64,
+ pub id: u64,
+}
+
+/// What starting a program takes.
+pub struct Start<'a> {
+ pub id: &'a str,
+ /// Tells this run of the program from any other.
+ pub generation: u64,
+ pub program: &'a Path,
+ pub args: &'a [String],
+ pub dir: &'a Path,
+ pub data_dir: &'a Path,
+ pub ready_within: Duration,
+}
+
+pub struct Process {
+ id: String,
+ pub generation: u64,
+ child: Arc<Mutex<Child>>,
+ outbox: SyncSender<Vec<u8>>,
+ /// The calls it has not answered, and when each was made.
+ pending: HashMap<u64, (Waiter, Instant)>,
+ next_id: u64,
+ /// It said it is ready.
+ pub ready: bool,
+ /// The program file, and how it was when started: a program rebuilt
+ /// since is started again.
+ pub program: PathBuf,
+ pub program_stamp: Option<Stamp>,
+ listener: Arc<dyn Listener>,
+}
+
+/// A program told to stop, until it is gone.
+pub struct Exiting {
+ /// The id it ran as, which names its data directory.
+ pub id: String,
+ pub generation: u64,
+ child: Arc<Mutex<Child>>,
+}
+
+impl Exiting {
+ /// Whether it has exited, whatever has or has not been told of it.
+ pub fn gone(&self) -> bool {
+ exited(&self.child)
+ }
+}
+
+/// Why a call was not handed to the program.
+pub enum Refused {
+ /// Too many of its calls are unanswered.
+ Busy(String),
+ /// It is not reading what it is sent, or its input is closed: it is not
+ /// going to answer anything.
+ Gone(String),
+}
+
+impl Process {
+ pub fn start(
+ start: Start<'_>,
+ program_stamp: Option<Stamp>,
+ listener: Arc<dyn Listener>,
+ ) -> Result<Self, String> {
+ create_private_dir(start.data_dir)
+ .map_err(|err| format!("cannot make {}: {err}", start.data_dir.display()))?;
+ let mut command = Command::new(start.program);
+ command
+ .args(start.args)
+ .current_dir(start.dir)
+ .env("THINKTERM_PLUGIN_ID", start.id)
+ .env("THINKTERM_PLUGIN_DIR", start.dir)
+ .env("THINKTERM_PLUGIN_DATA", start.data_dir)
+ .env("THINKTERM_PLUGIN_API", API.to_string())
+ .stdin(Stdio::piped())
+ .stdout(Stdio::piped())
+ // Into the host's log, a line at a time and within an allowance.
+ .stderr(Stdio::piped())
+ // Which pane and which mux its `thinkterm cli` reaches is for the
+ // context to say, not for whoever happened to start the host:
+ // without these it finds the desktop by itself, and the mux
+ // server with `--prefer-mux`.
+ .env_remove("WEZTERM_PANE")
+ .env_remove("WEZTERM_UNIX_SOCKET");
+ #[cfg(windows)]
+ {
+ // The host has no console; a console program would open one.
+ use std::os::windows::process::CommandExt;
+ const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+ command.creation_flags(CREATE_NO_WINDOW);
+ }
+ let mut child = command
+ .spawn()
+ .map_err(|err| format!("cannot start {}: {err}", start.program.display()))?;
+ log::info!(
+ "started plugin {} ({}), pid {}",
+ start.id,
+ start.program.display(),
+ child.id()
+ );
+ let (Some(mut input), Some(output), Some(errors)) =
+ (child.stdin.take(), child.stdout.take(), child.stderr.take())
+ else {
+ let _ = child.kill();
+ let _ = child.wait();
+ return Err("its input and output were not piped".into());
+ };
+ let child = Arc::new(Mutex::new(child));
+ let (outbox, queued) = sync_channel::<Vec<u8>>(QUEUE);
+
+ let writing = std::thread::Builder::new()
+ .name(format!("plugin-{}-in", start.id))
+ .stack_size(STACK)
+ .spawn(move || {
+ for line in queued {
+ if input.write_all(&line).and_then(|()| input.flush()).is_err() {
+ break;
+ }
+ }
+ // Dropping the input closes it: the program's cue to exit.
+ });
+
+ let reading = {
+ let id = start.id.to_string();
+ let generation = start.generation;
+ let child = Arc::clone(&child);
+ let listener = Arc::clone(&listener);
+ std::thread::Builder::new()
+ .name(format!("plugin-{id}-out"))
+ .stack_size(STACK)
+ .spawn(move || {
+ let mut output = BufReader::new(output);
+ let mut line = Vec::new();
+ let mut noise = 0;
+ let why = loop {
+ match protocol::read_line(&mut output, &mut line) {
+ Ok(true) => {}
+ Ok(false) => break None,
+ Err(err) => break Some(format!("{err}")),
+ }
+ match serde_json::from_slice::<FromPlugin>(&line) {
+ Ok(message) => listener.said(&id, generation, message),
+ Err(err) if noise < NOISE_LOGGED => {
+ noise += 1;
+ log::warn!("plugin {id} wrote a line that is not a message: {err}");
+ }
+ Err(_) => {}
+ }
+ };
+ let exit = reap(&child);
+ let why = match why {
+ Some(broken) => format!("{broken}; {exit}"),
+ None => exit,
+ };
+ listener.ended(&id, generation, why);
+ })
+ };
+
+ let watching = {
+ let id = start.id.to_string();
+ let generation = start.generation;
+ let ready_within = start.ready_within;
+ let listener = Arc::clone(&listener);
+ std::thread::Builder::new()
+ .name(format!("plugin-{id}-start"))
+ .stack_size(STACK)
+ .spawn(move || {
+ std::thread::sleep(ready_within);
+ listener.late(&id, generation);
+ })
+ };
+
+ let logging = {
+ let id = start.id.to_string();
+ std::thread::Builder::new()
+ .name(format!("plugin-{id}-err"))
+ .stack_size(STACK)
+ .spawn(move || {
+ log_errors(errors, &ERRORS_LEFT, |line| {
+ log::info!("plugin {id}: {line}")
+ });
+ })
+ };
+
+ if let Err(err) = writing.and(reading).and(watching).and(logging) {
+ kill(&child);
+ return Err(format!("cannot start the threads for it: {err}"));
+ }
+ Ok(Self {
+ id: start.id.to_string(),
+ generation: start.generation,
+ child,
+ outbox,
+ pending: HashMap::new(),
+ next_id: 0,
+ ready: false,
+ program: start.program.to_path_buf(),
+ program_stamp,
+ listener,
+ })
+ }
+
+ /// Sends a call or a command, made by `message` from the id it is
+ /// given; `waiter` is answered when the program answers it.
+ pub fn ask(
+ &mut self,
+ waiter: Waiter,
+ message: impl FnOnce(u64) -> ToPlugin,
+ ) -> Result<(), Refused> {
+ if self.pending.len() >= PENDING_LIMIT {
+ return Err(Refused::Busy(format!(
+ "it has {PENDING_LIMIT} calls unanswered already"
+ )));
+ }
+ self.next_id += 1;
+ let mut line = Vec::new();
+ protocol::write_message(&mut line, &message(self.next_id))
+ .map_err(|err| Refused::Busy(format!("{err}")))?;
+ match self.outbox.try_send(line) {
+ Ok(()) => {}
+ Err(TrySendError::Full(_)) => {
+ return Err(Refused::Gone("it is not reading what it is sent".into()))
+ }
+ Err(TrySendError::Disconnected(_)) => {
+ return Err(Refused::Gone("its input is closed".into()))
+ }
+ }
+ self.pending.insert(self.next_id, (waiter, Instant::now()));
+ Ok(())
+ }
+
+ /// The client waiting for the answer to `id`, now that it came.
+ pub fn answered(&mut self, id: u64) -> Option<Waiter> {
+ self.pending.remove(&id).map(|(waiter, _)| waiter)
+ }
+
+ /// Lets go of the calls made longer than [`PENDING_EXPIRY`] ago: whoever
+ /// made them stopped waiting long since. Hands them back.
+ pub fn expire(&mut self) -> Vec<Waiter> {
+ let mut expired = Vec::new();
+ self.pending.retain(|_, (waiter, made)| {
+ let keep = made.elapsed() < PENDING_EXPIRY;
+ if !keep {
+ expired.push(*waiter);
+ }
+ keep
+ });
+ expired
+ }
+
+ /// Lets go of the calls `client` made: it has gone, and nobody is left
+ /// to answer. The program may still answer them, into nothing.
+ pub fn forget_client(&mut self, client: u64) {
+ self.pending
+ .retain(|_, (waiter, _)| waiter.client != client);
+ }
+
+ /// Asks the program to exit, and kills it if it has not within
+ /// [`STOP_GRACE`]; the host is told once it is gone. Hands back the
+ /// calls it will not answer, and the program until it is gone.
+ pub fn stop(self) -> (Vec<Waiter>, Exiting) {
+ let Self {
+ id,
+ generation,
+ child,
+ outbox,
+ pending,
+ listener,
+ ..
+ } = self;
+ let mut line = Vec::new();
+ if protocol::write_message(&mut line, &ToPlugin::Stop).is_ok() {
+ let _ = outbox.try_send(line);
+ }
+ // The writer closes the program's input once the queue is done.
+ drop(outbox);
+ let exiting = Exiting {
+ id: id.clone(),
+ generation,
+ child: Arc::clone(&child),
+ };
+ let stopper = std::thread::Builder::new()
+ .name("plugin-stop".into())
+ .stack_size(STACK)
+ .spawn({
+ let child = Arc::clone(&child);
+ move || {
+ let why = reap(&child);
+ listener.ended(&id, generation, why);
+ }
+ });
+ if stopper.is_err() {
+ // Gone at once, then; its reader tells the host.
+ kill(&child);
+ }
+ let waiters = pending.into_values().map(|(waiter, _)| waiter).collect();
+ (waiters, exiting)
+ }
+
+ /// Kills the program at once: it failed to start, or stopped reading.
+ /// Hands back the calls it will not answer.
+ pub fn kill(self) -> Vec<Waiter> {
+ kill(&self.child);
+ self.pending
+ .into_values()
+ .map(|(waiter, _)| waiter)
+ .collect()
+ }
+}
+
+/// Stops every program at once, for the host to exit: asks each running
+/// one to exit, gives them and the ones already exiting `grace` between
+/// them, and kills whatever is left.
+pub fn stop_all(processes: Vec<Process>, exiting: Vec<Exiting>, grace: Duration) {
+ let mut running: Vec<Arc<Mutex<Child>>> = processes
+ .into_iter()
+ .map(|process| {
+ let Process { child, outbox, .. } = process;
+ let mut line = Vec::new();
+ if protocol::write_message(&mut line, &ToPlugin::Stop).is_ok() {
+ let _ = outbox.try_send(line);
+ }
+ // Closing the queue closes the program's input once it is sent.
+ drop(outbox);
+ child
+ })
+ .chain(exiting.into_iter().map(|exiting| exiting.child))
+ .collect();
+ let deadline = Instant::now() + grace;
+ while !running.is_empty() && Instant::now() < deadline {
+ running.retain(|child| !exited(child));
+ std::thread::sleep(Duration::from_millis(10));
+ }
+ for child in &running {
+ kill(child);
+ }
+}
+
+/// Whether the program has exited, reaping it if so. Never waits: nothing
+/// holds a program's lock while it dies.
+fn exited(child: &Mutex<Child>) -> bool {
+ child
+ .lock()
+ .map(|mut child| !matches!(child.try_wait(), Ok(None)))
+ .unwrap_or(true)
+}
+
+/// Waits for the program to exit, killing it if it has not within
+/// [`STOP_GRACE`], and says how it ended -- once it is gone, so that no
+/// other run starts while it can still write.
+fn reap(child: &Mutex<Child>) -> String {
+ let deadline = Instant::now() + STOP_GRACE;
+ loop {
+ let waited = child.lock().map(|mut child| child.try_wait());
+ match waited {
+ Ok(Ok(Some(status))) => return describe(status),
+ Ok(Ok(None)) if Instant::now() < deadline => {
+ std::thread::sleep(Duration::from_millis(10));
+ }
+ Ok(Ok(None)) => {
+ kill(child);
+ // Stuck in the system, it dies when the system lets it.
+ while !exited(child) {
+ std::thread::sleep(Duration::from_millis(50));
+ }
+ return "it did not exit, and was killed".into();
+ }
+ Ok(Err(err)) => return format!("waiting for it: {err}"),
+ Err(_) => return "it ended".into(),
+ }
+ }
+}
+
+/// Kills the program without waiting for it: the caller may hold the
+/// host's lock. Whoever reads its output reaps it.
+fn kill(child: &Mutex<Child>) {
+ if let Ok(mut child) = child.lock() {
+ let _ = child.kill();
+ }
+}
+
+/// Hands what a program writes to its standard error to `log`, a line at a
+/// time, while `left` allows. Past that the rest is read and dropped, said
+/// once: a program is never held up writing it.
+fn log_errors(from: impl Read, left: &AtomicUsize, mut log: impl FnMut(&str)) {
+ let mut from = BufReader::new(from);
+ let mut line = Vec::new();
+ let mut dropping = false;
+ loop {
+ line.clear();
+ match Read::take(&mut from, ERROR_LINE).read_until(b'\n', &mut line) {
+ Ok(0) | Err(_) => return,
+ Ok(_) => {}
+ }
+ let allowed = left
+ .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |left| {
+ left.checked_sub(line.len())
+ })
+ .is_ok();
+ if allowed {
+ let text = String::from_utf8_lossy(&line);
+ let text = text.trim_end();
+ if !text.is_empty() {
+ log(text);
+ }
+ } else if !dropping {
+ dropping = true;
+ log(&format!(
+ "plugins wrote {ERRORS_LOGGED} bytes to standard error; \
+ the rest is dropped until the plugin server starts again"
+ ));
+ }
+ }
+}
+
+fn describe(status: ExitStatus) -> String {
+ match status.code() {
+ Some(code) => format!("it exited with status {code}"),
+ None => format!("it ended: {status}"),
+ }
+}
+
+fn create_private_dir(dir: &Path) -> std::io::Result<()> {
+ let mut builder = std::fs::DirBuilder::new();
+ builder.recursive(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::DirBuilderExt;
+ builder.mode(0o700);
+ }
+ builder.create(dir)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn standard_error_is_logged_by_the_line_within_its_allowance() {
+ let written = b"first\n\nsecond line\nthird\nfourth\n".to_vec();
+ // Room for the first three lines, the empty one among them.
+ let left = AtomicUsize::new(6 + 1 + 12);
+ let mut logged = Vec::new();
+ log_errors(&written[..], &left, |line| logged.push(line.to_string()));
+ assert_eq!(logged.len(), 3, "{logged:?}");
+ assert_eq!(logged[..2], ["first", "second line"]);
+ assert!(logged[2].contains("dropped"), "{logged:?}");
+ }
+
+ #[test]
+ fn a_line_without_end_is_logged_in_pieces() {
+ let written = vec![b'x'; ERROR_LINE as usize + 10];
+ let left = AtomicUsize::new(usize::MAX);
+ let mut logged = Vec::new();
+ log_errors(&written[..], &left, |line| logged.push(line.len()));
+ assert_eq!(logged, [ERROR_LINE as usize, 10]);
+ }
+}
diff --git a/thinkterm-plugin-server/src/registry.rs b/thinkterm-plugin-server/src/registry.rs
new file mode 100644
index 00000000..71062055
--- /dev/null
+++ b/thinkterm-plugin-server/src/registry.rs
@@ -0,0 +1,909 @@
+//! The plugins the host knows: the ones built into it, and the ones
+//! installed in the plugins directory, each with its switch and, while an
+//! installed one runs, its program.
+//!
+//! The directory is looked at again whenever the list is asked for, and a
+//! plugin's manifest and program whenever it is used, so installing,
+//! removing, editing and rebuilding a plugin need no restart. Nothing
+//! starts a plugin's program but a client using the plugin, and no program
+//! starts while one that ran under the same id -- from whichever directory
+//! -- is still on its way out: they share a data directory, and calls made
+//! meanwhile wait for it to be gone.
+
+use crate::manifest::{self, Manifest};
+use crate::process::{self, Exiting, Listener, Process, Refused, Start, Waiter};
+use crate::stamp::{stamp, Stamp};
+use crate::switches::{self, Switches};
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+use thinkterm_plugin_channel::registry::{Info, State};
+use thinkterm_plugin_sdk::protocol::{ToPlugin, API};
+use thinkterm_plugin_sdk::Plugin;
+
+/// Crashes within [`CRASH_WINDOW`] that mark a plugin failed.
+const CRASH_LIMIT: usize = 3;
+const CRASH_WINDOW: Duration = Duration::from_secs(60);
+/// Directories looked at in the plugins directory; one with more than this
+/// is not a plugins directory someone keeps by hand.
+const DIR_LIMIT: usize = 256;
+/// How long the programs still running when the host exits have to exit.
+const EXIT_GRACE: Duration = Duration::from_secs(1);
+
+/// A plugin built into the host, which runs inside it.
+pub struct Builtin {
+ pub manifest: Manifest,
+ pub plugin: Box<dyn Plugin>,
+}
+
+/// A call or a command for a program, made from the id it is sent with.
+pub type Message = Box<dyn FnOnce(u64) -> ToPlugin + Send>;
+
+/// A call waiting for the plugin's last program to be gone.
+struct Queued {
+ waiter: Waiter,
+ message: Message,
+}
+
+/// What starting an installed plugin's program takes, once it may start.
+struct Launch {
+ id: String,
+ program: Result<(PathBuf, Vec<String>), String>,
+ program_stamp: Option<Stamp>,
+}
+
+struct Installed {
+ dir: PathBuf,
+ /// What a plugin whose manifest does not read is known by.
+ dir_name: String,
+ manifest: Result<Manifest, String>,
+ manifest_stamp: Option<Stamp>,
+ /// Why it is not used although its manifest reads: another plugin has
+ /// its id.
+ shadowed: Option<String>,
+ run: Run,
+ /// When it crashed within the last [`CRASH_WINDOW`], oldest first.
+ crashes: Vec<Instant>,
+ /// Its programs told to stop and not gone yet. While any that ran under
+ /// an id is, no program of that id starts, here or in another
+ /// directory.
+ exiting: Vec<Exiting>,
+ /// The calls waiting for such a program to be gone.
+ queued: Vec<Queued>,
+}
+
+enum Run {
+ Idle,
+ Running(Process),
+ Crashed(String),
+ /// It stays so until it is reloaded, turned off and on, or its manifest
+ /// or program changes from how they were when it failed.
+ Failed {
+ reason: String,
+ manifest: Option<Stamp>,
+ program: Option<Stamp>,
+ },
+}
+
+impl Installed {
+ fn new(dir_name: String, dir: PathBuf) -> Self {
+ let mut installed = Self {
+ dir,
+ dir_name,
+ manifest: Err(String::new()),
+ manifest_stamp: None,
+ shadowed: None,
+ run: Run::Idle,
+ crashes: Vec::new(),
+ exiting: Vec::new(),
+ queued: Vec::new(),
+ };
+ installed.read_manifest();
+ installed
+ }
+
+ fn read_manifest(&mut self) {
+ self.manifest_stamp = stamp(&self.dir.join(manifest::FILE));
+ self.manifest = Manifest::load(&self.dir);
+ if let Err(reason) = &self.manifest {
+ log::warn!("plugin in {}: {reason}", self.dir.display());
+ }
+ }
+
+ /// Its id, when its manifest reads.
+ fn id(&self) -> Option<&str> {
+ self.manifest
+ .as_ref()
+ .ok()
+ .map(|manifest| manifest.id.as_str())
+ }
+
+ /// Whether calls addressed to `id` are this plugin's.
+ fn answers_to(&self, id: &str) -> bool {
+ self.shadowed.is_none() && self.id() == Some(id)
+ }
+
+ /// Stops its program, if it runs, handing its unanswered calls to
+ /// `fallout` with `why`. The program is exiting until it is gone.
+ fn stop(&mut self, why: &str, fallout: &mut Fallout) {
+ if let Run::Running(process) = std::mem::replace(&mut self.run, Run::Idle) {
+ log::info!("stopping plugin {}: {why}", self.dir_name);
+ let (waiters, exiting) = process.stop();
+ fallout.lost(waiters, why);
+ self.exiting.push(exiting);
+ }
+ }
+
+ /// Stops it, answers the calls waiting to reach it, and forgets that it
+ /// crashed or failed.
+ fn reset(&mut self, why: &str, fallout: &mut Fallout) {
+ self.stop(why, fallout);
+ let queued = std::mem::take(&mut self.queued);
+ fallout.lost(queued.into_iter().map(|call| call.waiter).collect(), why);
+ self.run = Run::Idle;
+ self.crashes.clear();
+ }
+}
+
+/// What an operation leaves for the host to tell the clients.
+#[derive(Default)]
+pub struct Fallout {
+ /// Calls that will not be answered, and why.
+ pub unanswered: Vec<(Waiter, String)>,
+ /// The list changed: whoever shows it is to be told.
+ pub changed: bool,
+}
+
+impl Fallout {
+ fn lost(&mut self, waiters: Vec<Waiter>, why: &str) {
+ self.unanswered
+ .extend(waiters.into_iter().map(|waiter| (waiter, why.to_string())));
+ self.changed = true;
+ }
+}
+
+/// Which plugin a call is for.
+pub enum Lookup {
+ Builtin(usize),
+ Installed(usize),
+ Missing,
+}
+
+pub struct Registry {
+ plugins_dir: PathBuf,
+ /// Where each installed plugin gets a directory of its own.
+ plugin_data: PathBuf,
+ switches: Switches,
+ builtins: Vec<Builtin>,
+ installed: Vec<Installed>,
+ /// Counts program starts, so what a program's threads report is never
+ /// taken for another run's.
+ generation: u64,
+ ready_within: Duration,
+}
+
+impl Registry {
+ pub fn new(data_dir: &Path, builtins: Vec<Builtin>, ready_within: Duration) -> Self {
+ let mut registry = Self {
+ plugins_dir: thinkterm_plugin_channel::paths::plugins_dir_in(data_dir),
+ plugin_data: data_dir.join("plugin-data"),
+ switches: Switches::load(data_dir.join(switches::FILE)),
+ builtins,
+ installed: Vec::new(),
+ generation: 0,
+ ready_within,
+ };
+ // Nobody is connected yet to be told what it found.
+ registry.scan(&mut Fallout::default());
+ registry
+ }
+
+ /// Looks at the plugins directory and the switches again: plugins added
+ /// or removed, manifests changed, switches moved by another host.
+ pub fn scan(&mut self, fallout: &mut Fallout) {
+ self.follow_switches(fallout);
+ let found = self.read_dir();
+ let before = self.installed.len();
+ let mut removed = false;
+ self.installed.retain_mut(|installed| {
+ let kept = found.iter().any(|(name, _)| *name == installed.dir_name);
+ if !kept {
+ installed.reset("it was removed", fallout);
+ log::info!("plugin {} was removed", installed.dir_name);
+ removed = true;
+ }
+ kept
+ });
+ for (name, dir) in found {
+ match self
+ .installed
+ .iter()
+ .position(|installed| installed.dir_name == name)
+ {
+ Some(index) => self.refresh_manifest(index, fallout),
+ None => {
+ log::info!("found plugin {}", dir.display());
+ self.installed.push(Installed::new(name, dir));
+ }
+ }
+ }
+ if removed || self.installed.len() != before {
+ fallout.changed = true;
+ }
+ self.installed.sort_by(|a, b| a.dir_name.cmp(&b.dir_name));
+ self.resolve_ids(fallout);
+ }
+
+ /// The plugin directories, by name: not hidden, at most [`DIR_LIMIT`].
+ /// Takes in the switches another host moved -- a debug build's, say:
+ /// a plugin turned off there stops here too.
+ fn follow_switches(&mut self, fallout: &mut Fallout) {
+ if !self.switches.refresh() {
+ return;
+ }
+ fallout.changed = true;
+ for installed in &mut self.installed {
+ let off = installed.id().is_some_and(|id| !self.switches.enabled(id));
+ if off {
+ installed.reset("it was turned off", fallout);
+ }
+ }
+ }
+
+ fn read_dir(&self) -> Vec<(String, PathBuf)> {
+ let Ok(entries) = std::fs::read_dir(&self.plugins_dir) else {
+ return Vec::new();
+ };
+ let mut found: Vec<(String, PathBuf)> = entries
+ .filter_map(Result::ok)
+ .filter_map(|entry| {
+ let name = entry.file_name().into_string().ok()?;
+ let dir = entry.path();
+ // A link to a directory counts: that is how one works on a
+ // plugin in place.
+ (!name.starts_with('.') && dir.is_dir()).then_some((name, dir))
+ })
+ .take(DIR_LIMIT)
+ .collect();
+ found.sort();
+ found
+ }
+
+ /// Reads a plugin's manifest again if it changed on disk; a plugin
+ /// whose manifest changed is stopped, and forgets that it failed.
+ fn refresh_manifest(&mut self, index: usize, fallout: &mut Fallout) {
+ let installed = &mut self.installed[index];
+ if stamp(&installed.dir.join(manifest::FILE)) == installed.manifest_stamp {
+ return;
+ }
+ installed.reset("its manifest changed", fallout);
+ installed.read_manifest();
+ fallout.changed = true;
+ self.resolve_ids(fallout);
+ }
+
+ /// Settles which plugin answers to an id two of them claim: a built-in
+ /// plugin, else the one whose directory sorts first. The others are
+ /// stopped and shown as invalid.
+ fn resolve_ids(&mut self, fallout: &mut Fallout) {
+ let builtin_ids: Vec<String> = self
+ .builtins
+ .iter()
+ .map(|builtin| builtin.manifest.id.clone())
+ .collect();
+ let mut claimed: Vec<(String, String)> = Vec::new();
+ for installed in &mut self.installed {
+ let Some(id) = installed.id().map(str::to_string) else {
+ installed.shadowed = None;
+ continue;
+ };
+ let shadowed = if builtin_ids.contains(&id) {
+ Some(format!("the id {id:?} belongs to a built-in plugin"))
+ } else if let Some((_, first)) = claimed.iter().find(|(known, _)| *known == id) {
+ Some(format!("{first} has the same id, {id:?}"))
+ } else {
+ claimed.push((id, installed.dir_name.clone()));
+ None
+ };
+ if shadowed.is_some() && installed.shadowed.is_none() {
+ installed.reset("another plugin has its id", fallout);
+ fallout.changed = true;
+ }
+ installed.shadowed = shadowed;
+ }
+ }
+
+ /// Every plugin, as a list shows them: the built-in ones first, then
+ /// the installed ones by name.
+ pub fn list(&self, locale: &str) -> Vec<Info> {
+ let mut list: Vec<Info> = self
+ .builtins
+ .iter()
+ .map(|builtin| self.builtin_info(builtin, locale))
+ .collect();
+ let mut installed: Vec<Info> = self
+ .installed
+ .iter()
+ .map(|installed| self.installed_info(installed, locale))
+ .collect();
+ installed.sort_by(|a, b| {
+ a.name
+ .to_lowercase()
+ .cmp(&b.name.to_lowercase())
+ .then_with(|| a.id.cmp(&b.id))
+ });
+ list.extend(installed);
+ list
+ }
+
+ fn builtin_info(&self, builtin: &Builtin, locale: &str) -> Info {
+ let manifest = &builtin.manifest;
+ let enabled = self.switches.enabled(&manifest.id);
+ let localized = manifest.localized(locale);
+ Info {
+ id: manifest.id.clone(),
+ name: localized.name.to_string(),
+ description: localized.description.to_string(),
+ version: String::new(),
+ builtin: true,
+ dir: None,
+ enabled,
+ state: if enabled { State::Idle } else { State::Off },
+ }
+ }
+
+ fn installed_info(&self, installed: &Installed, locale: &str) -> Info {
+ let dir = Some(installed.dir.display().to_string());
+ let manifest = match &installed.manifest {
+ Ok(manifest) => manifest,
+ Err(reason) => {
+ return Info {
+ id: installed.dir_name.clone(),
+ name: installed.dir_name.clone(),
+ description: String::new(),
+ version: String::new(),
+ builtin: false,
+ dir,
+ enabled: self.switches.enabled(&installed.dir_name),
+ state: State::Invalid {
+ reason: reason.clone(),
+ },
+ }
+ }
+ };
+ let enabled = self.switches.enabled(&manifest.id);
+ let state = if let Some(reason) = &installed.shadowed {
+ State::Invalid {
+ reason: reason.clone(),
+ }
+ } else if !manifest.supported() {
+ State::Unsupported {
+ reason: format!(
+ "it runs on {}, not {}",
+ manifest.platforms.join(", "),
+ std::env::consts::OS
+ ),
+ }
+ } else if !enabled {
+ State::Off
+ } else {
+ match &installed.run {
+ Run::Idle if !installed.queued.is_empty() => State::Starting,
+ Run::Idle => State::Idle,
+ Run::Running(process) if process.ready => State::Running,
+ Run::Running(_) => State::Starting,
+ Run::Crashed(reason) => State::Crashed {
+ reason: reason.clone(),
+ },
+ Run::Failed { reason, .. } => State::Failed {
+ reason: reason.clone(),
+ },
+ }
+ };
+ let localized = manifest.localized(locale);
+ Info {
+ id: manifest.id.clone(),
+ name: localized.name.to_string(),
+ description: localized.description.to_string(),
+ version: manifest.version.clone(),
+ builtin: false,
+ dir,
+ enabled,
+ state,
+ }
+ }
+
+ /// Which plugin answers to `id`, looking at the plugins directory
+ /// again when none does: it may have been installed since.
+ pub fn find(&mut self, id: &str, fallout: &mut Fallout) -> Lookup {
+ match self.lookup(id) {
+ Lookup::Missing => {
+ self.scan(fallout);
+ self.lookup(id)
+ }
+ found => found,
+ }
+ }
+
+ /// Which plugin answers to `id`.
+ pub fn lookup(&self, id: &str) -> Lookup {
+ if let Some(index) = self
+ .builtins
+ .iter()
+ .position(|builtin| builtin.manifest.id == id)
+ {
+ return Lookup::Builtin(index);
+ }
+ match self
+ .installed
+ .iter()
+ .position(|installed| installed.answers_to(id))
+ {
+ Some(index) => Lookup::Installed(index),
+ None => Lookup::Missing,
+ }
+ }
+
+ pub fn builtin(&mut self, index: usize) -> &mut Builtin {
+ &mut self.builtins[index]
+ }
+
+ pub fn enabled(&self, id: &str) -> bool {
+ self.switches.enabled(id)
+ }
+
+ pub fn set_enabled(
+ &mut self,
+ id: &str,
+ enabled: bool,
+ fallout: &mut Fallout,
+ ) -> Result<(), String> {
+ let known = self
+ .builtins
+ .iter()
+ .any(|builtin| builtin.manifest.id == id)
+ || self
+ .installed
+ .iter()
+ .any(|installed| installed.id() == Some(id));
+ if !known {
+ return Err(format!("there is no plugin {id:?}"));
+ }
+ // The file is written over what it says now, so what another host
+ // changed in it is acted on first, not just carried along.
+ self.follow_switches(fallout);
+ let moved = self
+ .switches
+ .set(id, enabled)
+ .map_err(|err| format!("cannot save the switch: {err:#}"))?;
+ if !moved {
+ return Ok(());
+ }
+ log::info!("plugin {id} turned {}", if enabled { "on" } else { "off" });
+ fallout.changed = true;
+ for installed in &mut self.installed {
+ if installed.id() == Some(id) {
+ installed.reset(
+ if enabled {
+ "it was turned on"
+ } else {
+ "it was turned off"
+ },
+ fallout,
+ );
+ }
+ }
+ Ok(())
+ }
+
+ /// Stops a plugin, reads its manifest again and forgets that it failed:
+ /// every installed plugin when `id` is `None`, after looking for new and
+ /// removed ones.
+ pub fn reload(&mut self, id: Option<&str>, fallout: &mut Fallout) -> Result<(), String> {
+ fallout.changed = true;
+ let Some(id) = id else {
+ self.scan(fallout);
+ for installed in &mut self.installed {
+ installed.reset("it was reloaded", fallout);
+ }
+ return Ok(());
+ };
+ if self
+ .builtins
+ .iter()
+ .any(|builtin| builtin.manifest.id == id)
+ {
+ // Nothing to reload: it is as new as the host.
+ return Ok(());
+ }
+ let index = self
+ .installed
+ .iter()
+ .position(|installed| installed.id() == Some(id) || installed.dir_name == id)
+ .ok_or_else(|| format!("there is no plugin {id:?}"))?;
+ let installed = &mut self.installed[index];
+ installed.reset("it was reloaded", fallout);
+ installed.read_manifest();
+ self.resolve_ids(fallout);
+ Ok(())
+ }
+
+ /// Hands a call or a command made for `id` to the installed plugin at
+ /// `index`, found answering to it: to its program, started if it is not
+ /// running, and started again if it was rebuilt since. While a program
+ /// that ran under the id is still exiting, the call waits for it to be
+ /// gone. An error is why it cannot reach the plugin at all; one met on
+ /// the way is the call's answer, in `fallout`.
+ pub fn ask(
+ &mut self,
+ id: &str,
+ index: usize,
+ waiter: Waiter,
+ message: Message,
+ listener: &Arc<dyn Listener>,
+ fallout: &mut Fallout,
+ ) -> Result<(), String> {
+ let launch = self.launchable(index, fallout)?;
+ // Its manifest, read again, may name another id now: the call is
+ // not for that plugin.
+ if launch.id != id {
+ return Err(format!("there is no plugin named {id:?}"));
+ }
+ let installed = &mut self.installed[index];
+ if let Run::Running(process) = &installed.run {
+ if stamp(&process.program) != process.program_stamp {
+ installed.stop("its program changed, and it is started again", fallout);
+ }
+ }
+ let call = Queued { waiter, message };
+ if self.still_exiting(id) {
+ let installed = &mut self.installed[index];
+ if installed.queued.len() >= process::PENDING_LIMIT {
+ return Err(format!(
+ "it has {} calls waiting already",
+ process::PENDING_LIMIT
+ ));
+ }
+ installed.queued.push(call);
+ fallout.changed = true;
+ return Ok(());
+ }
+ let mut calls = std::mem::take(&mut self.installed[index].queued);
+ calls.push(call);
+ self.deliver(index, launch, calls, listener, fallout);
+ Ok(())
+ }
+
+ /// Whether a program that ran under `id` is still on its way out, from
+ /// whichever directory: a new one would share its data directory.
+ fn still_exiting(&mut self, id: &str) -> bool {
+ let mut exiting = false;
+ for installed in &mut self.installed {
+ // Gone without word reaching here counts as gone.
+ installed.exiting.retain(|exiting| !exiting.gone());
+ exiting |= installed.exiting.iter().any(|exiting| exiting.id == id);
+ }
+ exiting
+ }
+
+ /// Sends the calls that waited for programs on their way out, for each
+ /// plugin whose id has none left.
+ fn send_queued(&mut self, listener: &Arc<dyn Listener>, fallout: &mut Fallout) {
+ for index in 0..self.installed.len() {
+ if self.installed[index].queued.is_empty() {
+ continue;
+ }
+ // A manifest read again here answers the calls it no longer
+ // takes: the plugin is reset.
+ let launch = match self.launchable(index, fallout) {
+ Ok(launch) => launch,
+ Err(why) => {
+ let calls = std::mem::take(&mut self.installed[index].queued);
+ fallout.lost(calls.into_iter().map(|call| call.waiter).collect(), &why);
+ continue;
+ }
+ };
+ if self.still_exiting(&launch.id) {
+ continue;
+ }
+ let calls = std::mem::take(&mut self.installed[index].queued);
+ if !calls.is_empty() {
+ self.deliver(index, launch, calls, listener, fallout);
+ }
+ }
+ }
+
+ /// Whether the installed plugin at `index` may run now, reading its
+ /// manifest again if it changed, and what starting it takes.
+ fn launchable(&mut self, index: usize, fallout: &mut Fallout) -> Result<Launch, String> {
+ self.refresh_manifest(index, fallout);
+ let installed = &self.installed[index];
+ let manifest = installed.manifest.as_ref().map_err(Clone::clone)?;
+ if let Some(reason) = &installed.shadowed {
+ return Err(reason.clone());
+ }
+ if !manifest.supported() {
+ return Err(format!("{} does not run on this system", manifest.name));
+ }
+ if !self.switches.enabled(&manifest.id) {
+ return Err(format!("{} is turned off", manifest.name));
+ }
+ let id = manifest.id.clone();
+ let program = manifest.program(&installed.dir);
+ let program_stamp = program.as_ref().ok().and_then(|(path, _)| stamp(path));
+
+ let installed = &mut self.installed[index];
+ if let Run::Failed {
+ reason,
+ manifest: manifest_then,
+ program: program_then,
+ } = &installed.run
+ {
+ if *manifest_then == installed.manifest_stamp && *program_then == program_stamp {
+ return Err(reason.clone());
+ }
+ // Something changed since: worth another try.
+ installed.run = Run::Idle;
+ installed.crashes.clear();
+ fallout.changed = true;
+ }
+ Ok(Launch {
+ id,
+ program,
+ program_stamp,
+ })
+ }
+
+ /// Sends `calls` to the program of the installed plugin at `index`,
+ /// starting it first if it is not running.
+ fn deliver(
+ &mut self,
+ index: usize,
+ launch: Launch,
+ calls: Vec<Queued>,
+ listener: &Arc<dyn Listener>,
+ fallout: &mut Fallout,
+ ) {
+ if !matches!(self.installed[index].run, Run::Running(_)) {
+ if let Err(why) = self.start(index, launch, listener, fallout) {
+ fallout.lost(calls.into_iter().map(|call| call.waiter).collect(), &why);
+ return;
+ }
+ }
+ let Run::Running(process) = &mut self.installed[index].run else {
+ unreachable!("just started");
+ };
+ let expired = process.expire();
+ fallout.lost(expired, "the plugin did not answer in time");
+ let mut gone = None;
+ let mut calls = calls.into_iter();
+ for call in calls.by_ref() {
+ match process.ask(call.waiter, call.message) {
+ Ok(()) => {}
+ Err(Refused::Busy(why)) => fallout.unanswered.push((call.waiter, why)),
+ Err(Refused::Gone(why)) => {
+ fallout.unanswered.push((call.waiter, why.clone()));
+ gone = Some((process.generation, why));
+ break;
+ }
+ }
+ }
+ if let Some((generation, why)) = gone {
+ let rest: Vec<Waiter> = calls.map(|call| call.waiter).collect();
+ fallout.lost(rest, &why);
+ // It is not coming back to answer anything: a crash.
+ if let Ok(id) = self.installed[index]
+ .manifest
+ .as_ref()
+ .map(|m| m.id.clone())
+ {
+ self.gave_up(&id, generation, why, false, fallout);
+ }
+ }
+ }
+
+ /// Starts the program of the installed plugin at `index`.
+ fn start(
+ &mut self,
+ index: usize,
+ launch: Launch,
+ listener: &Arc<dyn Listener>,
+ fallout: &mut Fallout,
+ ) -> Result<(), String> {
+ let Launch {
+ id,
+ program,
+ program_stamp,
+ } = launch;
+ let installed = &mut self.installed[index];
+ fallout.changed = true;
+ let (path, args) = match program {
+ Ok(found) => found,
+ Err(reason) => {
+ installed.run = Run::Failed {
+ reason: reason.clone(),
+ manifest: installed.manifest_stamp,
+ program: None,
+ };
+ return Err(reason);
+ }
+ };
+ self.generation += 1;
+ let data_dir = self.plugin_data.join(&id);
+ let start = Start {
+ id: &id,
+ generation: self.generation,
+ program: &path,
+ args: &args,
+ dir: &installed.dir,
+ data_dir: &data_dir,
+ ready_within: self.ready_within,
+ };
+ match Process::start(start, program_stamp, Arc::clone(listener)) {
+ Ok(process) => {
+ installed.run = Run::Running(process);
+ Ok(())
+ }
+ Err(reason) => {
+ log::warn!("plugin {id}: {reason}");
+ installed.run = Run::Failed {
+ reason: reason.clone(),
+ manifest: installed.manifest_stamp,
+ program: program_stamp,
+ };
+ Err(reason)
+ }
+ }
+ }
+
+ /// Lets go of what `client` asked that is still waiting: it has gone.
+ pub fn forget_client(&mut self, client: u64) {
+ for installed in &mut self.installed {
+ installed.queued.retain(|call| call.waiter.client != client);
+ if let Run::Running(process) = &mut installed.run {
+ process.forget_client(client);
+ }
+ }
+ }
+
+ /// The program of plugin `id` in its run number `generation`, if that
+ /// run is the one going on.
+ pub fn process(&mut self, id: &str, generation: u64) -> Option<&mut Process> {
+ self.installed
+ .iter_mut()
+ .filter(|installed| installed.answers_to(id))
+ .find_map(|installed| match &mut installed.run {
+ Run::Running(process) if process.generation == generation => Some(process),
+ _ => None,
+ })
+ }
+
+ /// The run's program said it is ready, speaking plugin API `api`.
+ pub fn ready(&mut self, id: &str, generation: u64, api: u32, fallout: &mut Fallout) {
+ let Some(process) = self.process(id, generation) else {
+ return;
+ };
+ process.ready = true;
+ fallout.changed = true;
+ if api == API {
+ return;
+ }
+ self.gave_up(
+ id,
+ generation,
+ format!("it speaks plugin API {api}; this ThinkTerm speaks {API}"),
+ true,
+ fallout,
+ );
+ }
+
+ /// The run's program has exited. One told to stop is gone at last: the
+ /// calls that waited for it go to a new program. Any other ended
+ /// without being asked to.
+ pub fn ended(
+ &mut self,
+ id: &str,
+ generation: u64,
+ why: String,
+ listener: &Arc<dyn Listener>,
+ fallout: &mut Fallout,
+ ) {
+ // Runs are numbered across every plugin, so an exiting one is found
+ // by its number: its plugin may answer to another id by now.
+ let exited = self.installed.iter().position(|installed| {
+ installed
+ .exiting
+ .iter()
+ .any(|exiting| exiting.generation == generation)
+ });
+ if let Some(index) = exited {
+ self.installed[index]
+ .exiting
+ .retain(|exiting| exiting.generation != generation);
+ } else {
+ let ready = self
+ .process(id, generation)
+ .is_some_and(|process| process.ready);
+ let why = if ready {
+ why
+ } else {
+ format!("before it was ready, {why}")
+ };
+ self.gave_up(id, generation, why, false, fallout);
+ }
+ // Calls may wait for this run, or for one already found gone before
+ // word of it came.
+ self.send_queued(listener, fallout);
+ }
+
+ /// The run's program has not said it is ready in time.
+ pub fn late(&mut self, id: &str, generation: u64, fallout: &mut Fallout) {
+ let ready = self
+ .process(id, generation)
+ .is_some_and(|process| process.ready);
+ if !ready {
+ let why = format!("it did not say it was ready within {:?}", self.ready_within);
+ self.gave_up(id, generation, why, false, fallout);
+ }
+ }
+
+ /// Ends the run for `why`: its calls go unanswered, and it counts as a
+ /// crash -- or, with `for_good`, as a failure at once.
+ fn gave_up(
+ &mut self,
+ id: &str,
+ generation: u64,
+ why: String,
+ for_good: bool,
+ fallout: &mut Fallout,
+ ) {
+ let Some(installed) = self.installed.iter_mut().find(|installed| {
+ installed.answers_to(id)
+ && matches!(&installed.run, Run::Running(process) if process.generation == generation)
+ }) else {
+ return;
+ };
+ let Run::Running(process) = std::mem::replace(&mut installed.run, Run::Idle) else {
+ return;
+ };
+ let program = stamp(&process.program);
+ log::warn!("plugin {id} stopped: {why}");
+ fallout.lost(process.kill(), &format!("the plugin stopped: {why}"));
+
+ let now = Instant::now();
+ installed
+ .crashes
+ .retain(|crashed| now.duration_since(*crashed) < CRASH_WINDOW);
+ installed.crashes.push(now);
+ let too_often = installed.crashes.len() >= CRASH_LIMIT;
+ installed.run = if for_good || too_often {
+ let reason = if too_often {
+ format!("it stopped {CRASH_LIMIT} times within a minute; last, {why}")
+ } else {
+ why
+ };
+ Run::Failed {
+ reason,
+ manifest: installed.manifest_stamp,
+ program,
+ }
+ } else {
+ Run::Crashed(why)
+ };
+ }
+
+ /// Stops every program, for the host to exit.
+ pub fn shut_down(&mut self) {
+ let mut running = Vec::new();
+ let mut exiting = Vec::new();
+ for installed in &mut self.installed {
+ if let Run::Running(process) = std::mem::replace(&mut installed.run, Run::Idle) {
+ running.push(process);
+ }
+ exiting.append(&mut installed.exiting);
+ }
+ if !running.is_empty() || !exiting.is_empty() {
+ process::stop_all(running, exiting, EXIT_GRACE);
+ }
+ }
+}
diff --git a/thinkterm-plugin-server/src/snippets.rs b/thinkterm-plugin-server/src/snippets.rs
index b9f908cc..e61eca1e 100644
--- a/thinkterm-plugin-server/src/snippets.rs
+++ b/thinkterm-plugin-server/src/snippets.rs
@@ -1,12 +1,16 @@
//! The snippets plugin: the one copy of the user's snippets, the file it is
//! kept in, and everything done with it. Clients show what it answers.
+//!
+//! It is written against thinkterm-plugin-sdk like any installed plugin,
+//! and runs inside the host (or out of it, with `--serve-plugin snippets`).
-use crate::host::{Outcome, Plugin};
+use crate::stamp::{stamp, Stamp};
use anyhow::Context;
use serde_json::Value;
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
use std::time::{SystemTime, UNIX_EPOCH};
-use thinkterm_snippets::wire::{Event, Request, Row, Saved, Snippet, PLUGIN};
+use thinkterm_plugin_sdk::{Cx, Plugin};
+use thinkterm_snippets::wire::{Event, Request, Row, Saved, Snippet};
use thinkterm_snippets::{file, SnippetRecord, SnippetStore};
pub struct Snippets {
@@ -18,20 +22,6 @@ pub struct Snippets {
seen: Option<Stamp>,
}
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-struct Stamp {
- len: u64,
- modified: Option<SystemTime>,
-}
-
-fn stamp(path: &Path) -> Option<Stamp> {
- let meta = std::fs::metadata(path).ok()?;
- Some(Stamp {
- len: meta.len(),
- modified: meta.modified().ok(),
- })
-}
-
fn now_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
@@ -64,13 +54,13 @@ impl Snippets {
/// the file changed behind this host's back, which is a change for
/// every client too. A file that does not read is an error, never an
/// empty store: an empty one would be written over it by the next save.
- fn current(&mut self, outcome: &mut Outcome) -> anyhow::Result<&mut SnippetStore> {
+ fn current(&mut self, cx: &mut Cx) -> anyhow::Result<&mut SnippetStore> {
let now = stamp(&self.path);
if self.store.is_none() || now != self.seen {
let store = file::load(&self.path)?;
if self.store.is_some() {
log::info!("{} changed on disk; reloaded it", self.path.display());
- outcome.events.push(changed());
+ cx.emit(changed());
}
self.store = Some(store);
self.seen = now;
@@ -79,32 +69,28 @@ impl Snippets {
}
/// Keeps `next` once it is on disk, and tells the clients.
- fn commit(&mut self, next: SnippetStore, outcome: &mut Outcome) -> anyhow::Result<()> {
+ fn commit(&mut self, next: SnippetStore, cx: &mut Cx) -> anyhow::Result<()> {
file::save(&self.path, &next)?;
self.store = Some(next);
self.seen = stamp(&self.path);
- outcome.events.push(changed());
+ cx.emit(changed());
Ok(())
}
}
impl Plugin for Snippets {
- fn name(&self) -> &'static str {
- PLUGIN
- }
-
- fn call(&mut self, body: Value, outcome: &mut Outcome) -> anyhow::Result<Value> {
+ fn call(&mut self, body: Value, cx: &mut Cx) -> anyhow::Result<Value> {
let request: Request =
serde_json::from_value(body).context("not a request the snippets plugin knows")?;
let answer = match request {
Request::List { query } => {
- let store = self.current(outcome)?;
+ let store = self.current(cx)?;
let rows: Vec<Row> = store.matching(&query).map(row).collect();
- outcome.watch = true;
+ cx.watch();
serde_json::to_value(rows)?
}
Request::Get { id } => {
- let store = self.current(outcome)?;
+ let store = self.current(cx)?;
let snippet = store.get(&id).map(|snippet| Snippet {
id: snippet.id.clone(),
title: snippet.title.clone(),
@@ -113,7 +99,7 @@ impl Plugin for Snippets {
serde_json::to_value(snippet)?
}
Request::Text { id, run } => {
- let store = self.current(outcome)?;
+ let store = self.current(cx)?;
let text = store.get(&id).and_then(|snippet| {
if run {
thinkterm_snippets::run_text(&snippet.body)
@@ -130,7 +116,7 @@ impl Plugin for Snippets {
}
// Saved before it is kept, so a change that did not reach
// the disk is neither kept nor announced.
- let mut next = self.current(outcome)?.clone();
+ let mut next = self.current(cx)?.clone();
let now = now_ms();
let saved = match id {
None => {
@@ -142,14 +128,14 @@ impl Plugin for Snippets {
None => return Ok(serde_json::to_value(Saved::Gone)?),
},
};
- self.commit(next, outcome)?;
+ self.commit(next, cx)?;
serde_json::to_value(Saved::Saved { id: saved })?
}
Request::Delete { id } => {
- let mut next = self.current(outcome)?.clone();
+ let mut next = self.current(cx)?.clone();
let deleted = next.delete(&id, now_ms());
if deleted {
- self.commit(next, outcome)?;
+ self.commit(next, cx)?;
}
Value::Bool(deleted)
}
@@ -162,23 +148,31 @@ impl Plugin for Snippets {
mod tests {
use super::*;
use serde_json::json;
+ use thinkterm_plugin_sdk::Effects;
- fn ask(plugin: &mut Snippets, request: Request) -> (Value, Outcome) {
- let mut outcome = Outcome::default();
+ fn ask(plugin: &mut Snippets, request: Request) -> (Value, Effects) {
+ let mut cx = Cx::new();
let answer = plugin
- .call(serde_json::to_value(request).unwrap(), &mut outcome)
+ .call(serde_json::to_value(request).unwrap(), &mut cx)
.unwrap();
- (answer, outcome)
+ (answer, cx.finish())
+ }
+
+ /// Calls the plugin with raw JSON.
+ fn call(plugin: &mut Snippets, body: Value) -> anyhow::Result<(Value, Effects)> {
+ let mut cx = Cx::new();
+ let answer = plugin.call(body, &mut cx)?;
+ Ok((answer, cx.finish()))
}
fn list(plugin: &mut Snippets, query: &str) -> Vec<Row> {
- let (answer, outcome) = ask(
+ let (answer, effects) = ask(
plugin,
Request::List {
query: query.into(),
},
);
- assert!(outcome.watch, "a list is followed");
+ assert!(effects.watch, "a list is followed");
serde_json::from_value(answer).unwrap()
}
@@ -204,17 +198,15 @@ mod tests {
let mut plugin = plugin_in(&dir);
assert!(list(&mut plugin, "").is_empty());
- let mut outcome = Outcome::default();
- let answer = plugin
- .call(
- json!({"op": "save", "title": "", "body": " git status \n"}),
- &mut outcome,
- )
- .unwrap();
+ let (answer, effects) = call(
+ &mut plugin,
+ json!({"op": "save", "title": "", "body": " git status \n"}),
+ )
+ .unwrap();
let Saved::Saved { id } = serde_json::from_value(answer).unwrap() else {
panic!("not saved");
};
- assert_eq!(outcome.events, [changed()]);
+ assert_eq!(effects.events, [changed()]);
assert!(id.starts_with("snippet-"));
let rows = list(&mut plugin, "");
assert_eq!(
@@ -251,12 +243,12 @@ mod tests {
("Fetch", "git fetch")
);
- let (answer, outcome) = ask(&mut plugin, Request::Delete { id: id.clone() });
+ let (answer, effects) = ask(&mut plugin, Request::Delete { id: id.clone() });
assert_eq!(answer, json!(true));
- assert_eq!(outcome.events, [changed()]);
- let (answer, outcome) = ask(&mut plugin, Request::Delete { id: id.clone() });
+ assert_eq!(effects.events, [changed()]);
+ let (answer, effects) = ask(&mut plugin, Request::Delete { id: id.clone() });
assert_eq!(answer, json!(false));
- assert!(outcome.events.is_empty(), "nothing changed");
+ assert!(effects.events.is_empty(), "nothing changed");
assert_eq!(save(&mut plugin, Some(&id), "", "git fetch"), Saved::Gone);
let (answer, _) = ask(&mut plugin, Request::Get { id });
assert_eq!(answer, Value::Null);
@@ -311,16 +303,13 @@ mod tests {
restored.create("b".into(), "", "pwd --physical".into(), 2);
file::save(&path, &restored).unwrap();
- let mut outcome = Outcome::default();
- let answer = plugin
- .call(json!({"op": "list", "query": ""}), &mut outcome)
- .unwrap();
+ let (answer, effects) = call(&mut plugin, json!({"op": "list", "query": ""})).unwrap();
let rows: Vec<Row> = serde_json::from_value(answer).unwrap();
assert_eq!(
rows.iter().map(|r| r.id.as_str()).collect::<Vec<_>>(),
["b"]
);
- assert_eq!(outcome.events, [changed()]);
+ assert_eq!(effects.events, [changed()]);
}
#[test]
@@ -329,16 +318,12 @@ mod tests {
let path = dir.path().join("snippets.json");
std::fs::write(&path, "not json").unwrap();
let mut plugin = plugin_in(&dir);
- let mut outcome = Outcome::default();
- assert!(plugin
- .call(json!({"op": "list", "query": ""}), &mut outcome)
- .is_err());
- assert!(plugin
- .call(
- json!({"op": "save", "title": "", "body": "ls"}),
- &mut outcome
- )
- .is_err());
+ assert!(call(&mut plugin, json!({"op": "list", "query": ""})).is_err());
+ assert!(call(
+ &mut plugin,
+ json!({"op": "save", "title": "", "body": "ls"})
+ )
+ .is_err());
assert_eq!(std::fs::read_to_string(&path).unwrap(), "not json");
}
@@ -346,9 +331,6 @@ mod tests {
fn an_unknown_request_is_an_error() {
let dir = tempfile::tempdir().unwrap();
let mut plugin = plugin_in(&dir);
- let mut outcome = Outcome::default();
- assert!(plugin
- .call(json!({"op": "frobnicate"}), &mut outcome)
- .is_err());
+ assert!(call(&mut plugin, json!({"op": "frobnicate"})).is_err());
}
}
diff --git a/thinkterm-plugin-server/src/snippets.toml b/thinkterm-plugin-server/src/snippets.toml
new file mode 100644
index 00000000..8165ccee
--- /dev/null
+++ b/thinkterm-plugin-server/src/snippets.toml
@@ -0,0 +1,24 @@
+# The Snippets plugin's manifest: an installed plugin's, less the program,
+# which is the host itself. Clients take its name and description from
+# here, in the user's language, like any plugin's.
+id = "snippets"
+name = "Snippets"
+description = "Saved commands and text you can paste into a pane."
+api = 1
+clients = ["desktop", "web"]
+
+[locales.zh-CN]
+name = "片段"
+description = "保存的命令和文本,可以粘贴到面板中。"
+
+[locales.ja-JP]
+name = "スニペット"
+description = "保存したコマンドやテキストを、ペインに貼り付けられます。"
+
+[locales.de-DE]
+name = "Snippets"
+description = "Gespeicherte Befehle und Texte, die Sie in ein Pane einfügen können."
+
+[locales.fr-FR]
+name = "Extraits"
+description = "Commandes et textes enregistrés, à coller dans un panneau."
diff --git a/thinkterm-plugin-server/src/stamp.rs b/thinkterm-plugin-server/src/stamp.rs
new file mode 100644
index 00000000..7ab99f85
--- /dev/null
+++ b/thinkterm-plugin-server/src/stamp.rs
@@ -0,0 +1,22 @@
+//! Telling that a file changed without reading it: its length and the time
+//! it was last written. What the host keeps (the snippets, the switches)
+//! and what it runs (manifests, programs) are compared by stamp before use,
+//! so a change made from outside is picked up without watching for it.
+
+use std::path::Path;
+use std::time::SystemTime;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Stamp {
+ len: u64,
+ modified: Option<SystemTime>,
+}
+
+/// The file's stamp; `None` when there is no such file.
+pub fn stamp(path: &Path) -> Option<Stamp> {
+ let meta = std::fs::metadata(path).ok()?;
+ Some(Stamp {
+ len: meta.len(),
+ modified: meta.modified().ok(),
+ })
+}
diff --git a/thinkterm-plugin-server/src/switches.rs b/thinkterm-plugin-server/src/switches.rs
new file mode 100644
index 00000000..ada35393
--- /dev/null
+++ b/thinkterm-plugin-server/src/switches.rs
@@ -0,0 +1,130 @@
+//! Which plugins are turned off: `plugins.json` in the data directory. A
+//! plugin that is not in it is on. A switch stays when its plugin is
+//! removed, so a plugin installed again comes back as it was left.
+
+use crate::stamp::{stamp, Stamp};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::io::Write;
+use std::path::PathBuf;
+
+pub const FILE: &str = "plugins.json";
+
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+struct Stored {
+ #[serde(default)]
+ plugins: BTreeMap<String, Switch>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+struct Switch {
+ enabled: bool,
+}
+
+pub struct Switches {
+ path: PathBuf,
+ stored: Stored,
+ /// The file as last read or written, to notice another host's change.
+ seen: Option<Stamp>,
+}
+
+impl Switches {
+ pub fn load(path: PathBuf) -> Self {
+ let mut switches = Self {
+ path,
+ stored: Stored::default(),
+ seen: None,
+ };
+ switches.read();
+ switches
+ }
+
+ /// Reads the file again. One that does not read leaves every plugin on
+ /// until a switch is changed, which writes it anew.
+ fn read(&mut self) {
+ self.seen = stamp(&self.path);
+ self.stored = match std::fs::read(&self.path) {
+ Ok(bytes) => serde_json::from_slice(&bytes).unwrap_or_else(|err| {
+ log::warn!("{} does not read: {err}", self.path.display());
+ Stored::default()
+ }),
+ Err(_) => Stored::default(),
+ };
+ }
+
+ /// Picks up a change made by another host -- a debug build's, say.
+ /// True when a switch moved.
+ pub fn refresh(&mut self) -> bool {
+ if stamp(&self.path) == self.seen {
+ return false;
+ }
+ let before = self.stored.clone();
+ self.read();
+ self.stored != before
+ }
+
+ pub fn enabled(&self, id: &str) -> bool {
+ self.stored
+ .plugins
+ .get(id)
+ .map_or(true, |switch| switch.enabled)
+ }
+
+ /// Turns a plugin on or off, on disk before it counts. The file is
+ /// written over as last read: [`refresh`](Self::refresh) first, and act
+ /// on what another host moved. False when it already was.
+ pub fn set(&mut self, id: &str, enabled: bool) -> anyhow::Result<bool> {
+ if self.enabled(id) == enabled {
+ return Ok(false);
+ }
+ let mut next = self.stored.clone();
+ next.plugins.insert(id.to_string(), Switch { enabled });
+ let dir = self
+ .path
+ .parent()
+ .ok_or_else(|| anyhow::anyhow!("{} has no directory", self.path.display()))?;
+ std::fs::create_dir_all(dir)?;
+ let mut file = tempfile::NamedTempFile::new_in(dir)?;
+ file.write_all(&serde_json::to_vec_pretty(&next)?)?;
+ file.as_file().sync_all()?;
+ file.persist(&self.path)?;
+ self.stored = next;
+ self.seen = stamp(&self.path);
+ Ok(true)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn a_switch_is_kept_on_disk_and_read_back() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join(FILE);
+ let mut switches = Switches::load(path.clone());
+ assert!(switches.enabled("a"), "on unless turned off");
+ assert!(switches.set("a", false).unwrap());
+ assert!(!switches.set("a", false).unwrap(), "already off");
+ assert!(!switches.enabled("a"));
+ assert!(!Switches::load(path.clone()).enabled("a"));
+
+ // Another host turns it back on.
+ let mut other = Switches::load(path.clone());
+ assert!(other.set("a", true).unwrap());
+ assert!(switches.refresh());
+ assert!(switches.enabled("a"));
+ assert!(!switches.refresh(), "nothing new");
+ }
+
+ #[test]
+ fn a_file_that_does_not_read_leaves_everything_on() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join(FILE);
+ std::fs::write(&path, "not json").unwrap();
+ let mut switches = Switches::load(path.clone());
+ assert!(switches.enabled("a"));
+ switches.set("a", false).unwrap();
+ assert!(!Switches::load(path).enabled("a"));
+ }
+}
diff --git a/thinkterm-plugin-server/tests/common/mod.rs b/thinkterm-plugin-server/tests/common/mod.rs
new file mode 100644
index 00000000..6ee0ef79
--- /dev/null
+++ b/thinkterm-plugin-server/tests/common/mod.rs
@@ -0,0 +1,79 @@
+//! What the host's tests share: a host of their own in a temporary
+//! directory, started by the client library or by hand.
+
+#![allow(dead_code)]
+
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command};
+use std::sync::mpsc;
+use std::time::{Duration, Instant};
+use thinkterm_plugin_channel::client::{Host, Notice, Session};
+use thinkterm_plugin_channel::wire::ToHost;
+
+pub const WAIT: Duration = Duration::from_secs(10);
+
+pub fn host_in(dir: &Path) -> Host {
+ Host {
+ socket: dir.join("sock"),
+ lock: dir.join("lock"),
+ data_dir: dir.join("data"),
+ log: dir.join("log"),
+ program: PathBuf::from(env!("CARGO_BIN_EXE_thinkterm-plugin-server")),
+ }
+}
+
+/// A host started by hand, with arguments the client library does not pass.
+pub fn spawn(host: &Host, extra: &[&str]) -> Child {
+ spawn_with_env(host, extra, &[])
+}
+
+/// [`spawn`], with variables in the host's environment.
+pub fn spawn_with_env(host: &Host, extra: &[&str], env: &[(&str, &str)]) -> Child {
+ Command::new(&host.program)
+ .arg("--socket")
+ .arg(&host.socket)
+ .arg("--lock")
+ .arg(&host.lock)
+ .arg("--data-dir")
+ .arg(&host.data_dir)
+ .args(extra)
+ .envs(env.iter().copied())
+ .spawn()
+ .unwrap()
+}
+
+/// Leaves no host running after the test.
+pub fn stop(host: &Host) {
+ if let Ok(mut connection) = host.connect() {
+ let _ = connection.send(&ToHost::Quit);
+ }
+}
+
+pub fn wait_until(what: &str, mut done: impl FnMut() -> bool) {
+ let deadline = Instant::now() + WAIT;
+ while !done() {
+ assert!(Instant::now() < deadline, "timed out waiting for {what}");
+ std::thread::sleep(Duration::from_millis(20));
+ }
+}
+
+/// A session, and the notices it gives.
+pub fn session(host: &Host) -> (Session, mpsc::Receiver<Notice>) {
+ let (tx, rx) = mpsc::channel();
+ let session = Session::start(host.clone(), move |notice| {
+ let _ = tx.send(notice);
+ })
+ .unwrap();
+ (session, rx)
+}
+
+pub fn next_notice(notices: &mpsc::Receiver<Notice>, wanted: impl Fn(&Notice) -> bool) -> Notice {
+ let deadline = Instant::now() + WAIT;
+ loop {
+ let left = deadline.saturating_duration_since(Instant::now());
+ let notice = notices.recv_timeout(left).expect("a notice");
+ if wanted(&notice) {
+ return notice;
+ }
+ }
+}
diff --git a/thinkterm-plugin-server/tests/host.rs b/thinkterm-plugin-server/tests/host.rs
index 307814ed..1d04e06b 100644
--- a/thinkterm-plugin-server/tests/host.rs
+++ b/thinkterm-plugin-server/tests/host.rs
@@ -1,56 +1,16 @@
//! The host as its clients see it: a real process, started by the client
//! library, on a socket in a directory of the test's own.
+mod common;
+
+use common::{host_in, next_notice, session, spawn, stop, wait_until, WAIT};
use serde_json::{json, Value};
-use std::path::{Path, PathBuf};
-use std::process::{Child, Command};
use std::sync::mpsc;
use std::time::{Duration, Instant};
use thinkterm_plugin_channel::client::{Answer, Connection, Host, Notice, Session};
use thinkterm_plugin_channel::wire::{read_frame, write_frame, FromHost, ToHost, PROTOCOL};
use thinkterm_snippets::wire::{Event, Request, Row, Saved, PLUGIN};
-const WAIT: Duration = Duration::from_secs(10);
-
-fn host_in(dir: &Path) -> Host {
- Host {
- socket: dir.join("sock"),
- lock: dir.join("lock"),
- data_dir: dir.join("data"),
- log: dir.join("log"),
- program: PathBuf::from(env!("CARGO_BIN_EXE_thinkterm-plugin-server")),
- }
-}
-
-/// A host started by hand, with arguments the client library does not pass.
-fn spawn(host: &Host, extra: &[&str]) -> Child {
- Command::new(&host.program)
- .arg("--socket")
- .arg(&host.socket)
- .arg("--lock")
- .arg(&host.lock)
- .arg("--data-dir")
- .arg(&host.data_dir)
- .args(extra)
- .spawn()
- .unwrap()
-}
-
-/// Leaves no host running after the test.
-fn stop(host: &Host) {
- if let Ok(mut connection) = host.connect() {
- let _ = connection.send(&ToHost::Quit);
- }
-}
-
-fn wait_until(what: &str, mut done: impl FnMut() -> bool) {
- let deadline = Instant::now() + WAIT;
- while !done() {
- assert!(Instant::now() < deadline, "timed out waiting for {what}");
- std::thread::sleep(Duration::from_millis(20));
- }
-}
-
fn call(connection: &mut Connection, id: u64, request: Request) {
connection
.send(&ToHost::Call {
@@ -250,16 +210,6 @@ fn a_host_from_a_newer_build_is_left_alone() {
assert!(host.socket.exists());
}
-/// A session, and the notices it gives.
-fn session(host: &Host) -> (Session, mpsc::Receiver<Notice>) {
- let (tx, rx) = mpsc::channel();
- let session = Session::start(host.clone(), move |notice| {
- let _ = tx.send(notice);
- })
- .unwrap();
- (session, rx)
-}
-
fn ask(session: &Session, request: Request) -> Answer {
let (tx, rx) = mpsc::channel();
session.call(
@@ -272,17 +222,6 @@ fn ask(session: &Session, request: Request) -> Answer {
rx.recv_timeout(WAIT).expect("every call is answered")
}
-fn next_notice(notices: &mpsc::Receiver<Notice>, wanted: impl Fn(&Notice) -> bool) -> Notice {
- let deadline = Instant::now() + WAIT;
- loop {
- let left = deadline.saturating_duration_since(Instant::now());
- let notice = notices.recv_timeout(left).expect("a notice");
- if wanted(&notice) {
- return notice;
- }
- }
-}
-
#[test]
fn a_session_follows_the_host_across_a_restart() {
let dir = tempfile::tempdir().unwrap();
diff --git a/thinkterm-plugin-server/tests/plugins.rs b/thinkterm-plugin-server/tests/plugins.rs
new file mode 100644
index 00000000..47d201c2
--- /dev/null
+++ b/thinkterm-plugin-server/tests/plugins.rs
@@ -0,0 +1,704 @@
+//! Installed plugins as clients see them: found in the plugins directory,
+//! started as programs of their own, turned off and on, reloaded, and given
+//! up on when they misbehave.
+
+mod common;
+
+use common::{host_in, next_notice, session, spawn, spawn_with_env, stop, wait_until, WAIT};
+use serde_json::{json, Value};
+use std::path::PathBuf;
+use std::sync::mpsc;
+use std::time::Duration;
+use thinkterm_plugin_channel::client::{Answer, Host, Notice, Session};
+use thinkterm_plugin_channel::registry::{self as api, Info, State};
+use thinkterm_plugin_channel::wire::{FromHost, ToHost};
+
+fn call(session: &Session, plugin: &str, body: Value) -> Answer {
+ let (tx, rx) = mpsc::channel();
+ session.call(plugin, body, move |answer| {
+ let _ = tx.send(answer);
+ });
+ rx.recv_timeout(WAIT).expect("every call is answered")
+}
+
+fn manage(session: &Session, request: api::Request) -> Answer {
+ call(session, api::PLUGIN, serde_json::to_value(request).unwrap())
+}
+
+fn list(session: &Session) -> Vec<Info> {
+ let listed = manage(
+ session,
+ api::Request::List {
+ locale: "zh-CN".into(),
+ },
+ );
+ serde_json::from_value(listed.unwrap()).unwrap()
+}
+
+fn info(session: &Session, id: &str) -> Info {
+ list(session)
+ .into_iter()
+ .find(|info| info.id == id)
+ .unwrap_or_else(|| panic!("{id} is not listed"))
+}
+
+fn ids(listed: &[Info]) -> Vec<&str> {
+ listed.iter().map(|info| info.id.as_str()).collect()
+}
+
+fn set_enabled(session: &Session, id: &str, enabled: bool) -> Answer {
+ manage(
+ session,
+ api::Request::SetEnabled {
+ id: id.into(),
+ enabled,
+ },
+ )
+}
+
+/// Installs a plugin: a directory `name` in the host's plugins directory,
+/// holding `manifest`.
+fn install(host: &Host, name: &str, manifest: &str) -> PathBuf {
+ let dir = host.data_dir.join("plugins").join(name);
+ std::fs::create_dir_all(&dir).unwrap();
+ std::fs::write(dir.join("plugin.toml"), manifest).unwrap();
+ dir
+}
+
+/// Snippets installed again under another id, as a program of its own:
+/// the host's own program serving it over standard input and output.
+fn snippets_copy(host: &Host) -> String {
+ format!(
+ r#"
+id = "snippets-copy"
+name = "Snippets, out of process"
+version = "1.0"
+api = 1
+
+[run]
+program = '{}'
+args = ["--serve-plugin", "snippets", "--data-dir", '{}']
+
+[locales.zh-CN]
+name = "片段副本"
+"#,
+ host.program.display(),
+ host.data_dir.join("copy").display()
+ )
+}
+
+fn is_event_of(plugin: &str) -> impl Fn(&Notice) -> bool + '_ {
+ move |notice| matches!(notice, Notice::Event { plugin: from, .. } if from == plugin)
+}
+
+#[test]
+fn an_installed_plugin_runs_as_a_program_of_its_own() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install(&host, "copy", &snippets_copy(&host));
+ let (session, notices) = session(&host);
+
+ let listed = list(&session);
+ assert_eq!(ids(&listed), ["snippets", "snippets-copy"]);
+ assert!(listed[0].builtin);
+ assert_eq!(listed[0].name, "片段", "in the language asked for");
+ assert_eq!(listed[1].name, "片段副本");
+ assert_eq!(listed[1].version, "1.0");
+ assert_eq!(listed[1].state, State::Idle, "nothing started it yet");
+
+ let rows = call(
+ &session,
+ "snippets-copy",
+ json!({"op": "list", "query": ""}),
+ );
+ assert_eq!(rows, Ok(json!([])));
+ assert_eq!(info(&session, "snippets-copy").state, State::Running);
+ let saved = call(
+ &session,
+ "snippets-copy",
+ json!({"op": "save", "title": "", "body": "make"}),
+ )
+ .unwrap();
+ assert_eq!(saved["outcome"], "saved");
+ // The list made this session a watcher, and the save tells it.
+ let Notice::Event { body, .. } = next_notice(&notices, is_event_of("snippets-copy")) else {
+ unreachable!()
+ };
+ assert_eq!(body, json!({"event": "changed"}));
+ // Its files are where it was told to keep them, apart from the
+ // built-in plugin's.
+ assert!(host.data_dir.join("copy/snippets.json").exists());
+ assert!(!host.data_dir.join("snippets.json").exists());
+ drop(session);
+ stop(&host);
+}
+
+#[test]
+fn a_plugin_turned_off_stops_and_refuses_calls_until_turned_on() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install(&host, "copy", &snippets_copy(&host));
+ let (session, _notices) = session(&host);
+ let query = json!({"op": "list", "query": ""});
+ call(&session, "snippets-copy", query.clone()).unwrap();
+
+ assert_eq!(
+ set_enabled(&session, "snippets-copy", false),
+ Ok(Value::Null)
+ );
+ let off = info(&session, "snippets-copy");
+ assert_eq!((off.enabled, off.state), (false, State::Off));
+ let why = call(&session, "snippets-copy", query.clone()).unwrap_err();
+ assert!(why.contains("turned off"), "{why}");
+ let kept = std::fs::read_to_string(host.data_dir.join("plugins.json")).unwrap();
+ assert!(kept.contains("snippets-copy"), "{kept}");
+
+ assert_eq!(
+ set_enabled(&session, "snippets-copy", true),
+ Ok(Value::Null)
+ );
+ assert_eq!(
+ call(&session, "snippets-copy", query.clone()),
+ Ok(json!([]))
+ );
+ assert_eq!(info(&session, "snippets-copy").state, State::Running);
+
+ // A built-in plugin has a switch too.
+ set_enabled(&session, "snippets", false).unwrap();
+ let why = call(&session, "snippets", query.clone()).unwrap_err();
+ assert!(why.contains("Snippets is turned off"), "{why}");
+ set_enabled(&session, "snippets", true).unwrap();
+ assert_eq!(call(&session, "snippets", query), Ok(json!([])));
+
+ let why = set_enabled(&session, "nothing", false).unwrap_err();
+ assert!(why.contains("no plugin"), "{why}");
+ drop(session);
+ stop(&host);
+}
+
+#[test]
+fn plugins_come_and_go_with_their_directories() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ let (watcher, watcher_notices) = session(&host);
+ assert_eq!(ids(&list(&watcher)), ["snippets"]);
+
+ let (session, _notices) = session(&host);
+ let installed = install(&host, "copy", &snippets_copy(&host));
+ assert_eq!(ids(&list(&session)), ["snippets", "snippets-copy"]);
+ // The other client showing the list hears that it changed.
+ next_notice(&watcher_notices, is_event_of(api::PLUGIN));
+
+ call(
+ &session,
+ "snippets-copy",
+ json!({"op": "list", "query": ""}),
+ )
+ .unwrap();
+ std::fs::remove_dir_all(&installed).unwrap();
+ assert_eq!(ids(&list(&session)), ["snippets"]);
+ let why = call(
+ &session,
+ "snippets-copy",
+ json!({"op": "list", "query": ""}),
+ )
+ .unwrap_err();
+ assert!(why.contains("no plugin named"), "{why}");
+ drop((watcher, session));
+ stop(&host);
+}
+
+#[test]
+fn a_manifest_that_cannot_be_used_is_listed_with_why() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ let copy = snippets_copy(&host);
+ install(&host, "copy", &copy);
+ let broken = install(&host, "broken", "id = \n");
+ install(&host, "twin", &copy);
+ install(
+ &host,
+ "clash",
+ &copy.replace("\"snippets-copy\"", "\"snippets\""),
+ );
+ install(&host, "future", &copy.replace("api = 1", "api = 2"));
+ std::fs::create_dir_all(host.data_dir.join("plugins/empty")).unwrap();
+ let (session, _notices) = session(&host);
+
+ let reason = |id: &str| match info(&session, id).state {
+ State::Invalid { reason } => reason,
+ other => panic!("{id} is {other:?}"),
+ };
+ assert!(
+ reason("broken").starts_with("plugin.toml, line 1"),
+ "{}",
+ reason("broken")
+ );
+ assert!(reason("empty").contains("no plugin.toml"));
+ assert!(reason("future").contains("newer ThinkTerm"));
+ let listed = list(&session);
+ let twins: Vec<&Info> = listed
+ .iter()
+ .filter(|info| info.id == "snippets-copy")
+ .collect();
+ assert_eq!(twins.len(), 2);
+ assert_eq!(
+ twins
+ .iter()
+ .filter(|info| info.state == State::Idle)
+ .count(),
+ 1
+ );
+ let shadowed = listed
+ .iter()
+ .filter_map(|info| info.state.reason())
+ .any(|why| why.contains("copy has the same id"));
+ assert!(shadowed, "{listed:?}");
+ let clash = listed
+ .iter()
+ .filter_map(|info| info.state.reason())
+ .any(|why| why.contains("belongs to a built-in plugin"));
+ assert!(clash, "{listed:?}");
+ // The built-in plugin still answers to its id.
+ assert_eq!(
+ call(&session, "snippets", json!({"op": "list", "query": ""})),
+ Ok(json!([]))
+ );
+
+ std::fs::write(
+ broken.join("plugin.toml"),
+ copy.replace("snippets-copy", "mended"),
+ )
+ .unwrap();
+ assert_eq!(info(&session, "mended").state, State::Idle);
+ drop(session);
+ stop(&host);
+}
+
+#[test]
+fn plugins_have_no_commands_to_run() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ let (session, _notices) = session(&host);
+ let run = json!({"op": "run", "plugin": "snippets", "command": "frobnicate"});
+ let why = call(&session, api::PLUGIN, run).unwrap_err();
+ assert!(why.contains("not a request the plugin host knows"), "{why}");
+ drop(session);
+ stop(&host);
+}
+
+#[test]
+fn reloading_stops_a_plugin_and_the_next_call_starts_it() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install(&host, "copy", &snippets_copy(&host));
+ let (session, _notices) = session(&host);
+ let query = json!({"op": "list", "query": ""});
+ call(&session, "snippets-copy", query.clone()).unwrap();
+ assert_eq!(info(&session, "snippets-copy").state, State::Running);
+
+ let reload = |id: Option<&str>| {
+ manage(
+ &session,
+ api::Request::Reload {
+ id: id.map(str::to_string),
+ },
+ )
+ };
+ assert_eq!(reload(Some("snippets-copy")), Ok(Value::Null));
+ assert_eq!(info(&session, "snippets-copy").state, State::Idle);
+ call(&session, "snippets-copy", query.clone()).unwrap();
+ assert_eq!(reload(None), Ok(Value::Null));
+ assert_eq!(info(&session, "snippets-copy").state, State::Idle);
+ assert_eq!(reload(Some("snippets")), Ok(Value::Null), "nothing to do");
+ assert!(reload(Some("nothing")).is_err());
+ drop(session);
+ stop(&host);
+}
+
+/// Plugins written as shell scripts, for the ways a program can misbehave.
+#[cfg(unix)]
+mod scripts {
+ use super::*;
+ use std::os::unix::fs::PermissionsExt;
+
+ /// Says it is ready; answers a call with its pid; exits with status 3
+ /// when a call says "crash", and never answers one that says "hang".
+ const WELL_BEHAVED: &str = r#"#!/bin/sh
+printf '%s\n' '{"type":"ready","api":1}'
+while IFS= read -r line; do
+ id=$(printf '%s' "$line" | sed -n 's/^{"type":"[a-z]*","id":\([0-9]*\).*/\1/p')
+ case "$line" in
+ *'"type":"stop"'*) exit 0 ;;
+ *'"crash"'*) exit 3 ;;
+ *'"hang"'*) ;;
+ *) printf '{"type":"ok","id":%s,"body":%s}\n' "$id" "$$" ;;
+ esac
+done
+"#;
+
+ const MANIFEST: &str = r#"
+id = "shell"
+name = "Shell"
+version = "1"
+api = 1
+
+[run]
+program = "plugin.sh"
+"#;
+
+ fn install_script(host: &Host, script: &str) -> PathBuf {
+ install_script_in(host, "shell", script)
+ }
+
+ /// The same plugin, id "shell", installed in directory `name`.
+ fn install_script_in(host: &Host, name: &str, script: &str) -> PathBuf {
+ let dir = install(host, name, MANIFEST);
+ let program = dir.join("plugin.sh");
+ std::fs::write(&program, script).unwrap();
+ std::fs::set_permissions(&program, std::fs::Permissions::from_mode(0o755)).unwrap();
+ program
+ }
+
+ fn pid(answer: Answer) -> u64 {
+ answer.unwrap().as_u64().expect("a pid")
+ }
+
+ #[test]
+ fn a_plugin_that_keeps_stopping_is_given_up_on() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(&host, WELL_BEHAVED);
+ let (session, _notices) = session(&host);
+ let first = pid(call(&session, "shell", json!({"op": "pid"})));
+
+ for round in 1..=3 {
+ let why = call(&session, "shell", json!({"op": "crash"})).unwrap_err();
+ assert!(why.contains("exited with status 3"), "{why}");
+ let state = info(&session, "shell").state;
+ match round {
+ 3 => assert!(matches!(state, State::Failed { .. }), "{state:?}"),
+ _ => {
+ assert!(matches!(state, State::Crashed { .. }), "{state:?}");
+ // Using it again starts it again.
+ assert_ne!(pid(call(&session, "shell", json!({"op": "pid"}))), first);
+ }
+ }
+ }
+ let why = call(&session, "shell", json!({"op": "pid"})).unwrap_err();
+ assert!(why.contains("3 times within a minute"), "{why}");
+
+ manage(
+ &session,
+ api::Request::Reload {
+ id: Some("shell".into()),
+ },
+ )
+ .unwrap();
+ assert_eq!(info(&session, "shell").state, State::Idle);
+ pid(call(&session, "shell", json!({"op": "pid"})));
+ drop(session);
+ stop(&host);
+ }
+
+ #[test]
+ fn a_plugin_that_never_says_it_is_ready_is_given_up_on() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(&host, "#!/bin/sh\nexec sleep 30\n");
+ let mut child = spawn(&host, &["--ready-secs", "1"]);
+ wait_until("the host to listen", || host.socket.exists());
+ let (session, _notices) = session(&host);
+ let why = call(&session, "shell", json!({"op": "pid"})).unwrap_err();
+ assert!(why.contains("did not say it was ready within 1s"), "{why}");
+ assert!(matches!(
+ info(&session, "shell").state,
+ State::Crashed { .. }
+ ));
+ drop(session);
+ stop(&host);
+ wait_until("the host to quit", || child.try_wait().unwrap().is_some());
+ }
+
+ #[test]
+ fn a_notification_a_plugin_sends_reaches_nobody() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(
+ &host,
+ r#"#!/bin/sh
+printf '%s\n' '{"type":"ready","api":1}'
+while IFS= read -r line; do
+ id=$(printf '%s' "$line" | sed -n 's/^{"type":"[a-z]*","id":\([0-9]*\).*/\1/p')
+ case "$line" in
+ *'"type":"stop"'*) exit 0 ;;
+ *) printf '%s\n' '{"type":"notify","title":"Look","body":"here"}'
+ printf '{"type":"ok","id":%s,"body":%s}\n' "$id" "$$" ;;
+ esac
+done
+"#,
+ );
+ let (session, notices) = session_listing(&host);
+ pid(call(&session, "shell", json!({"op": "pid"})));
+ // A list's change comes after the answer; a notification never does.
+ std::thread::sleep(Duration::from_millis(500));
+ while let Ok(notice) = notices.try_recv() {
+ if let Notice::Event { body, .. } = notice {
+ assert_ne!(body["event"], "notify", "a notification reached a client");
+ }
+ }
+ drop(session);
+ stop(&host);
+ }
+
+ /// A session that has asked for the list, and so hears what it is told.
+ fn session_listing(host: &Host) -> (Session, mpsc::Receiver<Notice>) {
+ let (session, notices) = session(host);
+ list(&session);
+ (session, notices)
+ }
+
+ /// Saves its pid when a call says "save", and again on its way out, a
+ /// second after it is told to stop: a plugin writing what it holds.
+ const SLOW_TO_STOP: &str = r#"#!/bin/sh
+printf '%s\n' '{"type":"ready","api":1}'
+while IFS= read -r line; do
+ id=$(printf '%s' "$line" | sed -n 's/^{"type":"[a-z]*","id":\([0-9]*\).*/\1/p')
+ case "$line" in
+ *'"type":"stop"'*) break ;;
+ *'"save"'*) printf '%s' "$$" > "$THINKTERM_PLUGIN_DATA/state"
+ printf '{"type":"ok","id":%s,"body":%s}\n' "$id" "$$" ;;
+ *) printf '{"type":"ok","id":%s,"body":%s}\n' "$id" "$$" ;;
+ esac
+done
+sleep 1
+printf '%s' "$$" > "$THINKTERM_PLUGIN_DATA/state"
+"#;
+
+ #[test]
+ fn a_reloaded_plugin_starts_again_only_once_its_last_run_is_gone() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(&host, SLOW_TO_STOP);
+ let state = host.data_dir.join("plugin-data/shell/state");
+ let (session, _notices) = session(&host);
+ let first = pid(call(&session, "shell", json!({"op": "save"})));
+
+ manage(
+ &session,
+ api::Request::Reload {
+ id: Some("shell".into()),
+ },
+ )
+ .unwrap();
+ // Made at once, while the first run is still saving on its way out:
+ // it waits for that run to be gone.
+ let second = pid(call(&session, "shell", json!({"op": "save"})));
+ assert_ne!(second, first);
+ std::thread::sleep(Duration::from_millis(1500));
+ let saved: u64 = std::fs::read_to_string(&state).unwrap().parse().unwrap();
+ assert_eq!(saved, second, "the first run wrote over the second");
+ drop(session);
+ stop(&host);
+ }
+
+ #[test]
+ fn a_plugin_taking_over_an_id_starts_only_once_the_old_run_is_gone() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(&host, SLOW_TO_STOP);
+ let state = host.data_dir.join("plugin-data/shell/state");
+ let (session, _notices) = session(&host);
+ let first = pid(call(&session, "shell", json!({"op": "save"})));
+
+ // A copy whose directory sorts first claims the id. The one that
+ // ran under it is stopped, and saves on its way out into the data
+ // directory the two share.
+ install_script_in(&host, "a-shell", SLOW_TO_STOP);
+ list(&session);
+ let second = pid(call(&session, "shell", json!({"op": "save"})));
+ assert_ne!(second, first);
+ std::thread::sleep(Duration::from_millis(1500));
+ let saved: u64 = std::fs::read_to_string(&state).unwrap().parse().unwrap();
+ assert_eq!(saved, second, "the old run wrote over the new one");
+ drop(session);
+ stop(&host);
+ }
+
+ #[test]
+ fn a_plugin_whose_id_changes_answers_to_the_new_one_only() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ let program = install_script(&host, SLOW_TO_STOP);
+ let (session, _notices) = session(&host);
+ let first = pid(call(&session, "shell", json!({"op": "pid"})));
+
+ let renamed = MANIFEST.replace(r#"id = "shell""#, r#"id = "renamed""#);
+ std::fs::write(program.with_file_name("plugin.toml"), renamed).unwrap();
+ // Made for the old id as the manifest changes: not the renamed
+ // plugin's to answer.
+ let why = call(&session, "shell", json!({"op": "pid"})).unwrap_err();
+ assert!(why.contains("no plugin named"), "{why}");
+ // The old run is on its way out under the old id; the new id has
+ // nothing to wait for.
+ let second = pid(call(&session, "renamed", json!({"op": "pid"})));
+ assert_ne!(second, first);
+ drop(session);
+ stop(&host);
+ }
+
+ #[test]
+ fn a_plugin_another_host_turned_off_stops_here_as_a_switch_is_set() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(&host, WELL_BEHAVED);
+ let (session, _notices) = session(&host);
+ let running = pid(call(&session, "shell", json!({"op": "pid"})));
+
+ // Another host -- a debug build's -- turns it off in the file they
+ // share; then a switch is set here.
+ std::fs::write(
+ host.data_dir.join("plugins.json"),
+ r#"{"plugins":{"shell":{"enabled":false}}}"#,
+ )
+ .unwrap();
+ set_enabled(&session, "snippets", false).unwrap();
+ wait_until("the plugin turned off elsewhere to stop", || {
+ !alive(running)
+ });
+ assert_eq!(info(&session, "shell").state, State::Off);
+ drop(session);
+ stop(&host);
+ }
+
+ fn alive(pid: u64) -> bool {
+ std::process::Command::new("kill")
+ .args(["-0", &pid.to_string()])
+ .stderr(std::process::Stdio::null())
+ .status()
+ .is_ok_and(|status| status.success())
+ }
+
+ #[test]
+ fn a_program_is_not_given_the_pane_the_host_was_started_from() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(
+ &host,
+ r#"#!/bin/sh
+printf '%s\n' '{"type":"ready","api":1}'
+while IFS= read -r line; do
+ id=$(printf '%s' "$line" | sed -n 's/^{"type":"[a-z]*","id":\([0-9]*\).*/\1/p')
+ case "$line" in
+ *'"type":"stop"'*) exit 0 ;;
+ *) printf '{"type":"ok","id":%s,"body":"%s %s"}\n' "$id" "${WEZTERM_PANE-none}" "${WEZTERM_UNIX_SOCKET-none}" ;;
+ esac
+done
+"#,
+ );
+ // Started by a command run in a pane, the host has the pane's.
+ let mut child = spawn_with_env(
+ &host,
+ &[],
+ &[
+ ("WEZTERM_PANE", "7"),
+ ("WEZTERM_UNIX_SOCKET", "/tmp/elsewhere"),
+ ],
+ );
+ wait_until("the host to listen", || host.socket.exists());
+ let (session, _notices) = session(&host);
+ let seen = call(&session, "shell", json!({"op": "env"})).unwrap();
+ assert_eq!(seen, json!("none none"));
+ drop(session);
+ stop(&host);
+ wait_until("the host to quit", || child.try_wait().unwrap().is_some());
+ }
+
+ #[test]
+ fn what_a_program_writes_to_standard_error_is_logged_under_its_id() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(
+ &host,
+ r#"#!/bin/sh
+printf '%s\n' '{"type":"ready","api":1}'
+while IFS= read -r line; do
+ id=$(printf '%s' "$line" | sed -n 's/^{"type":"[a-z]*","id":\([0-9]*\).*/\1/p')
+ case "$line" in
+ *'"type":"stop"'*) exit 0 ;;
+ *) printf 'looking at call %s\n' "$id" >&2
+ printf '{"type":"ok","id":%s,"body":null}\n' "$id" ;;
+ esac
+done
+"#,
+ );
+ let (session, _notices) = session(&host);
+ call(&session, "shell", json!({"op": "look"})).unwrap();
+ wait_until("the line in the host's log", || {
+ std::fs::read_to_string(&host.log)
+ .unwrap_or_default()
+ .contains("plugin shell: looking at call 1")
+ });
+ drop(session);
+ stop(&host);
+ }
+
+ #[test]
+ fn calls_left_by_a_client_that_went_do_not_keep_the_plugin_busy() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ install_script(&host, WELL_BEHAVED);
+ let mut gone = host.connect().unwrap();
+ let limit = 64;
+ for id in 1..=limit + 1 {
+ gone.send(&ToHost::Call {
+ id,
+ plugin: "shell".into(),
+ body: json!({"op": "hang"}),
+ })
+ .unwrap();
+ }
+ // The call past the limit is refused, so the limit is reached.
+ let (tx, rx) = mpsc::channel();
+ let mut reader = gone.try_clone().unwrap();
+ std::thread::spawn(move || {
+ while let Ok(message) = reader.recv() {
+ if let FromHost::Error { id, message } = message {
+ let _ = tx.send((id, message));
+ return;
+ }
+ }
+ });
+ let (id, why) = rx
+ .recv_timeout(WAIT)
+ .expect("the call past the limit is refused");
+ assert_eq!(id, limit + 1);
+ assert!(why.contains("unanswered already"), "{why}");
+ gone.shutdown();
+ drop(gone);
+
+ let (session, _notices) = session(&host);
+ wait_until("the plugin to take calls again", || {
+ call(&session, "shell", json!({"op": "pid"})).is_ok()
+ });
+ drop(session);
+ stop(&host);
+ }
+
+ #[test]
+ fn a_rebuilt_program_is_started_again() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_in(dir.path());
+ let program = install_script(&host, WELL_BEHAVED);
+ let (session, _notices) = session(&host);
+ let first = pid(call(&session, "shell", json!({"op": "pid"})));
+ assert_eq!(pid(call(&session, "shell", json!({"op": "pid"}))), first);
+
+ std::fs::write(&program, format!("{WELL_BEHAVED}# rebuilt\n")).unwrap();
+ let second = pid(call(&session, "shell", json!({"op": "pid"})));
+ assert_ne!(second, first);
+ assert_eq!(info(&session, "shell").state, State::Running);
+ drop(session);
+ stop(&host);
+ }
+}