zwire_host/
lib.rs

1//! `zwire-host` — one small self-contained binary that exposes the local
2//! machine to any app over a JSON message protocol.
3//!
4//! Originally the Chrome native-messaging host for the [`zwire`] HUD, it is now a
5//! **universal local endpoint**: system stats, a namespaced key/value store, a
6//! filesystem crawler, subprocess exec, clipboard/notify/open, and multiplexed
7//! PTY terminals — reachable from a browser extension *and* from tmux, emacs,
8//! desktop apps, plugins, and any language.
9//!
10//! # Transports
11//! * **Native messaging** (default): `u32`-length-prefixed JSON on stdio, for
12//!   Chrome. Just run the binary with no recognised subcommand.
13//! * **Socket daemon**: `zwire-host serve` listens on a Unix socket speaking
14//!   newline-delimited JSON — the lingua franca every tool already has.
15//! * **Client**: `zwire-host call '{"cmd":"hostinfo"}'` sends one request and
16//!   prints the reply frames.
17//!
18//! Both transports feed the same [`session::Session`] dispatcher, so every
19//! capability is reachable from every client.
20//!
21//! [`zwire`]: https://github.com/MenkeTechnologies/zwire
22pub mod api;
23pub mod bus;
24pub mod exec;
25pub mod fsops;
26pub mod jobs;
27pub mod osops;
28pub mod peer;
29#[cfg(feature = "sysinfo-caps")]
30pub mod procs;
31pub mod proto;
32#[cfg(feature = "pty")]
33pub mod pty;
34pub mod session;
35pub mod store;
36#[cfg(feature = "sysinfo-caps")]
37pub mod sysmon;
38pub mod transport;
39pub mod watch;
40
41// Re-export the handful of types a dependent binary needs to embed the host.
42// This lets sibling hosts (e.g. `zpwrchrome-host`) pull this crate in and reuse
43// the dispatcher + transports directly:
44//
45// ```no_run
46// // in another crate's main.rs, with `zwire-host` as a dependency:
47// fn main() {
48//     // zero-config: full native-messaging + `serve`/`call` behaviour
49//     zwire_host::run(std::env::args().skip(1).collect());
50// }
51// ```
52//
53// Or drive the dispatcher yourself over any transport:
54//
55// ```no_run
56// use zwire_host::{Peer, Session};
57// let out = Peer::ndjson(Box::new(std::io::stdout()));
58// let mut sess = Session::new();
59// sess.handle(&out, &serde_json::json!({"cmd": "hostinfo"}));
60// ```
61pub use proto::{Framing, Out, Peer};
62pub use session::{caps, Session};
63
64use std::io::Read;
65use std::path::PathBuf;
66
67/// Crate version, surfaced in `hello`/`hostinfo` replies.
68pub const VERSION: &str = env!("CARGO_PKG_VERSION");
69
70/// Where the socket daemon listens by default. `$ZWIRE_HOST_SOCK` overrides on
71/// every platform. Otherwise:
72///   * Windows — a per-user named pipe `\\.\pipe\zwire-host-<user>`.
73///   * Unix — `$XDG_RUNTIME_DIR/zwire-host.sock`, else `~/.zwire/host.sock`.
74///
75/// On Windows the returned path's *leaf* is used as the pipe's namespaced name;
76/// the directory portion is ignored.
77pub fn default_socket() -> PathBuf {
78    if let Ok(p) = std::env::var("ZWIRE_HOST_SOCK") {
79        return PathBuf::from(p);
80    }
81    #[cfg(windows)]
82    {
83        let user = std::env::var("USERNAME").unwrap_or_else(|_| "user".into());
84        let safe: String = user
85            .chars()
86            .filter(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_'))
87            .collect();
88        let name = if safe.is_empty() { "user".into() } else { safe };
89        PathBuf::from(format!("zwire-host-{name}"))
90    }
91    #[cfg(not(windows))]
92    {
93        if let Ok(rt) = std::env::var("XDG_RUNTIME_DIR") {
94            if !rt.is_empty() {
95                return PathBuf::from(rt).join("zwire-host.sock");
96            }
97        }
98        store::app_dir("zwire").join("host.sock")
99    }
100}
101
102const USAGE: &str = "\
103zwire-host — universal local host (system stats · fs · exec · pty · kv · os)
104
105USAGE:
106    zwire-host                     native-messaging mode on stdio (Chrome default)
107    zwire-host serve               run the NDJSON socket daemon
108    zwire-host call '<json>'       send one request to the daemon, print reply
109    zwire-host call                ...reading the request JSON from stdin
110    zwire-host call --stream '...'  keep printing frames (sysinfo/pty streams)
111    zwire-host version | help
112
113OPTIONS:
114    --socket <path>   override the socket path (default: $ZWIRE_HOST_SOCK or
115                      $XDG_RUNTIME_DIR/zwire-host.sock or ~/.zwire/host.sock)
116    --stream, -f      relay every reply frame instead of just the first
117    --tcp <addr>      (serve) also listen for peers/remote clients on TCP
118    --token <tok>     (serve) shared secret required of inbound TCP ($ZWIRE_HOST_TOKEN)
119    --name <name>     (serve) this host's advertised peer name (default: hostname)
120    --peer <addr>     (serve) dial a peer and keep it linked; repeatable
121
122Examples:
123    zwire-host serve &
124    zwire-host call '{\"cmd\":\"hostinfo\"}'
125    zwire-host call '{\"cmd\":\"fs_walk\",\"path\":\"~/src\",\"ext\":\"rs\"}'
126    echo '{\"cmd\":\"exec\",\"program\":\"git\",\"args\":[\"status\"]}' | zwire-host call
127    zwire-host call --stream '{\"cmd\":\"sysinfo_start\"}'
128    zwire-host serve --tcp 0.0.0.0:7420 --token SECRET --peer other.local:7420
129";
130
131/// Entry point: interpret `args` (everything after `argv[0]`) and run the chosen
132/// transport. Any unrecognised first token falls through to native-messaging
133/// mode, because Chrome launches the host with extension-origin arguments we
134/// must ignore.
135pub fn run(args: Vec<String>) {
136    // Pull optional flags out of the arg list.
137    let mut socket = default_socket();
138    let mut follow = false;
139    let mut tcp: Option<String> = None;
140    let mut token: Option<String> = None;
141    let mut name: Option<String> = None;
142    let mut peers: Vec<String> = Vec::new();
143    let mut positional: Vec<String> = Vec::new();
144    let mut it = args.into_iter();
145    while let Some(a) = it.next() {
146        match a.as_str() {
147            "--socket" | "-s" => {
148                if let Some(p) = it.next() {
149                    socket = PathBuf::from(p);
150                }
151            }
152            "--stream" | "--follow" | "-f" => follow = true,
153            "--tcp" => tcp = it.next(),
154            "--token" => token = it.next(),
155            "--name" => name = it.next(),
156            "--peer" => {
157                if let Some(p) = it.next() {
158                    peers.push(p);
159                }
160            }
161            _ => positional.push(a),
162        }
163    }
164
165    match positional.first().map(String::as_str) {
166        Some("serve") => transport::serve(transport::ServeConfig {
167            socket,
168            tcp,
169            token,
170            name,
171            peers,
172        }),
173        Some("call") => {
174            let rest = positional[1..].join(" ");
175            let request = if rest.trim().is_empty() {
176                let mut s = String::new();
177                let _ = std::io::stdin().read_to_string(&mut s);
178                s
179            } else {
180                rest
181            };
182            transport::call(&socket, &request, follow);
183        }
184        Some("version") | Some("--version") | Some("-V") => {
185            println!("zwire-host {VERSION}");
186        }
187        Some("help") | Some("--help") | Some("-h") => {
188            print!("{USAGE}");
189        }
190        // `stdio`, no args, or Chrome's origin argument → native messaging.
191        _ => transport::stdio(),
192    }
193}
zwire_host/lib.rs

zwire_host/
lib.rs
