Crate fuzzball 

Encoder and decoder for the Fuzzball terminal protocol.

Fuzzball is a small family of terminal extensions, first implemented in the Mouser terminal. Every message is a DCS string with the private marker = and the family tag Fz:

ESC P = F z <subsystem> <verb> ; <params> [: <payload>] ESC \

This crate has no dependencies and does no I/O. It turns typed values into the exact bytes Mouser emits and parses those bytes back, including partial input:

• message: framing, Params, parse for one message and a streaming Decoder that splits terminal input into Fuzzball messages and other bytes.
• common: capability query and reply, error codes, generic replies.
• keyboard: key events, enable / disable / query commands.
• graphics: upload (with chunking), place, delete, query.
• shell: shell-integration silent actions (advertise, change directory, reply).
• plugins: plugin hello, query, bye and replies.
• passthrough: tmux and GNU screen wrapping.

The wire format is specified in the docs/ directory of the repository.

Parsing key events

use fuzzball::keyboard::{Key, KeyEvent, KeyKind};
use fuzzball::{Decoder, Item};

let mut d = Decoder::new();
d.push(b"x\x1bP=Fzke;t=p,code=KeyA,key=U+0061,te");
assert_eq!(d.next(), Some(Item::Text(b"x".to_vec())));
assert_eq!(d.next(), None); // the rest of the message has not arrived yet
d.push(b"xt=61\x1b\\");
let Some(Item::Message(m)) = d.next() else { panic!() };
let ev = KeyEvent::from_message(&m).unwrap();
assert_eq!(ev.kind, KeyKind::Press);
assert_eq!(ev.key, Some(Key::Char('a')));
assert_eq!(ev.text.as_deref(), Some("a"));

Stability

From 1.0.0 on, the wire format and this API follow semantic versioning: public enums and structs that may grow are #[non_exhaustive].

Re-exports

pub use common::ErrorCode;

pub use common::Reply;

pub use message::Decoder;

pub use message::Item;

pub use message::Message;

pub use message::Params;

pub use message::Parse;

pub use message::parse;

pub use message::parse_with_limit;

Modules

common

Common subsystem (c): capability query and reply, plus error codes and the generic reply shape every subsystem uses (<sub> r).

graphics

Graphics subsystem (g): upload, place, delete, query.

keyboard

Keyboard subsystem (k): key events and the mode commands.

message

Message framing: Message, Params, one-shot parse and the streaming Decoder.

passthrough

Multiplexer passthrough (README §3.2). Use enc=b64 (the default) inside these.

plugins

Plugin subsystem (p): a program in the terminal asks to act as a plugin.

shell

Shell-integration subsystem (s): silent actions such as changing directory without typing cd.

Constants

DEFAULT_MAX_MESSAGE

Default largest message parse and Decoder buffer before giving up.

MAX_CHUNK

Largest payload per message Mouser accepts, in wire bytes (max_chunk).

PREFIX

Bytes every Fuzzball message starts with: ESC P = F z.

ST

String terminator: ESC \.

VERSION

Wire protocol version (v=) this crate speaks.