harald/zeroclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3

perf(build): gate Matrix channel for faster iteration

Browse source
This commit is contained in:
Chummy 2026-02-19 21:01:26 +08:00
parent 87dcda638c
commit 05404c6e7a
9 changed files with 135 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

44
Cargo.lock generated
View file

@ -408,7 +408,7 @@ dependencies = [
"sha1",
"sync_wrapper",
"tokio",
"tokio-tungstenite 0.28.0",
"tokio-tungstenite",
"tower",
"tower-layer",
"tower-service",
@ -6004,9 +6004,9 @@ dependencies = [
[[package]]
name = "tokio-tungstenite"
version = "0.24.0"
version = "0.28.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "edc5f74e248dc973e0dbb7b74c7e0d6fcc301c694ff50049504004ef4d0cdcd9"
checksum = "d25a406cddcc431a75d3d9afc6a7c0f7428d4891dd973e4d54c56b46127bf857"
dependencies = [
"futures-util",
"log",
@ -6014,22 +6014,10 @@ dependencies = [
"rustls-pki-types",
"tokio",
"tokio-rustls",
"tungstenite 0.24.0",
"tungstenite",
"webpki-roots 0.26.11",
]
[[package]]
name = "tokio-tungstenite"
version = "0.28.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d25a406cddcc431a75d3d9afc6a7c0f7428d4891dd973e4d54c56b46127bf857"
dependencies = [
"futures-util",
"log",
"tokio",
"tungstenite 0.28.0",
]
[[package]]
name = "tokio-util"
version = "0.7.18"
@ -6333,26 +6321,6 @@ version = "0.25.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31"
[[package]]
name = "tungstenite"
version = "0.24.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "18e5b8366ee7a95b16d32197d0b2604b43a0be89dc5fac9f8e96ccafbaedda8a"
dependencies = [
"byteorder",
"bytes",
"data-encoding",
"http 1.4.0",
"httparse",
"log",
"rand 0.8.5",
"rustls",
"rustls-pki-types",
"sha1",
"thiserror 1.0.69",
"utf-8",
]
[[package]]
name = "tungstenite"
version = "0.28.0"
@ -6365,6 +6333,8 @@ dependencies = [
"httparse",
"log",
"rand 0.9.2",
"rustls",
"rustls-pki-types",
"sha1",
"thiserror 2.0.18",
"utf-8",
@ -7747,7 +7717,7 @@ dependencies = [
"tokio-rustls",
"tokio-serial",
"tokio-stream",
"tokio-tungstenite 0.24.0",
"tokio-tungstenite",
"tokio-util",
"toml 1.0.1+spec-1.1.0",
"tower",

9
Cargo.toml
View file

@ -26,7 +26,7 @@ tokio-util = { version = "0.7", default-features = false }
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "blocking", "multipart", "stream", "socks"] }
# Matrix client + E2EE decryption
matrix-sdk = { version = "0.16", default-features = false, features = ["e2e-encryption", "rustls-tls", "markdown"] }
matrix-sdk = { version = "0.16", optional = true, default-features = false, features = ["e2e-encryption", "rustls-tls", "markdown"] }
# Serialization
serde = { version = "1.0", default-features = false, features = ["derive"] }
@ -103,8 +103,8 @@ console = "0.16"
# Hardware discovery (device path globbing)
glob = "0.3"
# Discord WebSocket gateway
tokio-tungstenite = { version = "0.24", features = ["rustls-tls-webpki-roots"] }
# WebSocket client channels (Discord/Lark/DingTalk)
tokio-tungstenite = { version = "0.28", features = ["rustls-tls-webpki-roots"] }
futures-util = { version = "0.3", default-features = false, features = ["sink"] }
futures = "0.3"
regex = "1.10"
@ -158,8 +158,9 @@ rppal = { version = "0.22", optional = true }
landlock = { version = "0.4", optional = true }
[features]
default = ["hardware"]
default = ["hardware", "channel-matrix"]
hardware = ["nusb", "tokio-serial"]
channel-matrix = ["dep:matrix-sdk"]
peripheral-rpi = ["rppal"]
# Browser backend feature alias used by cfg(feature = "browser-native")
browser-native = ["dep:fantoccini"]

19
docs/channels-reference.md
View file

@ -69,6 +69,25 @@ Operational notes:
## Channel Matrix
### Build Feature Toggle (`channel-matrix`)
Matrix support is controlled at compile time by the `channel-matrix` Cargo feature.
- Default builds include Matrix support (`default = ["hardware", "channel-matrix"]`).
- For faster local iteration when Matrix is not needed:
```bash
cargo check --no-default-features --features hardware
```
- To explicitly enable Matrix support in custom feature sets:
```bash
cargo check --no-default-features --features hardware,channel-matrix
```
If `[channels_config.matrix]` is present but the binary was built without `channel-matrix`, `zeroclaw channel list`, `zeroclaw channel doctor`, and `zeroclaw channel start` will log that Matrix is intentionally skipped for this build.
---
## 2. Delivery Modes at a Glance

47
docs/troubleshooting.md
View file

@ -2,7 +2,7 @@
This guide focuses on common setup/runtime failures and fast resolution paths.
Last verified: **February 18, 2026**.
Last verified: **February 19, 2026**.
## Installation / Bootstrap
@ -32,6 +32,51 @@ Fix:
./bootstrap.sh --install-system-deps
```
### Build is very slow or appears stuck
Symptoms:
- `cargo check` / `cargo build` appears stuck at `Checking zeroclaw` for a long time
- repeated `Blocking waiting for file lock on package cache` or `build directory`
Why this happens in ZeroClaw:
- Matrix E2EE stack (`matrix-sdk`, `ruma`, `vodozemac`) is large and expensive to type-check.
- TLS + crypto native build scripts (`aws-lc-sys`, `ring`) add noticeable compile time.
- `rusqlite` with bundled SQLite compiles C code locally.
- Running multiple cargo jobs/worktrees in parallel causes lock contention.
Fast checks:
```bash
cargo check --timings
cargo tree -d
```
The timing report is written to `target/cargo-timings/cargo-timing.html`.
Faster local iteration (when Matrix channel is not needed):
```bash
cargo check --no-default-features --features hardware
```
This skips `channel-matrix` and can significantly reduce compile time.
To build with Matrix support explicitly enabled:
```bash
cargo check --no-default-features --features hardware,channel-matrix
```
Lock-contention mitigation:
```bash
pgrep -af "cargo (check|build|test)|cargo check|cargo build|cargo test"
```
Stop unrelated cargo jobs before running your own build.
### `zeroclaw` command not found after install
Symptom:

6
src/channels/dingtalk.rs
View file

@ -169,7 +169,7 @@ impl Channel for DingTalkChannel {
_ => continue,
};
let frame: serde_json::Value = match serde_json::from_str(&msg) {
let frame: serde_json::Value = match serde_json::from_str(msg.as_ref()) {
Ok(v) => v,
Err(_) => continue,
};
@ -195,7 +195,7 @@ impl Channel for DingTalkChannel {
"data": "",
});
if let Err(e) = write.send(Message::Text(pong.to_string())).await {
if let Err(e) = write.send(Message::Text(pong.to_string().into())).await {
tracing::warn!("DingTalk: failed to send pong: {e}");
break;
}
@ -262,7 +262,7 @@ impl Channel for DingTalkChannel {
"message": "OK",
"data": "",
});
let _ = write.send(Message::Text(ack.to_string())).await;
let _ = write.send(Message::Text(ack.to_string().into())).await;
let channel_msg = ChannelMessage {
id: Uuid::new_v4().to_string(),

10
src/channels/discord.rs
View file

@ -272,7 +272,9 @@ impl Channel for DiscordChannel {
}
}
});
write.send(Message::Text(identify.to_string())).await?;
write
.send(Message::Text(identify.to_string().into()))
.await?;
tracing::info!("Discord: connected and identified");
@ -301,7 +303,7 @@ impl Channel for DiscordChannel {
_ = hb_rx.recv() => {
let d = if sequence >= 0 { json!(sequence) } else { json!(null) };
let hb = json!({"op": 1, "d": d});
if write.send(Message::Text(hb.to_string())).await.is_err() {
if write.send(Message::Text(hb.to_string().into())).await.is_err() {
break;
}
}
@ -312,7 +314,7 @@ impl Channel for DiscordChannel {
_ => continue,
};
let event: serde_json::Value = match serde_json::from_str(&msg) {
let event: serde_json::Value = match serde_json::from_str(msg.as_ref()) {
Ok(e) => e,
Err(_) => continue,
};
@ -329,7 +331,7 @@ impl Channel for DiscordChannel {
1 => {
let d = if sequence >= 0 { json!(sequence) } else { json!(null) };
let hb = json!({"op": 1, "d": d});
if write.send(Message::Text(hb.to_string())).await.is_err() {
if write.send(Message::Text(hb.to_string().into())).await.is_err() {
break;
}
continue;

14
src/channels/lark.rs
View file

@ -288,7 +288,7 @@ impl LarkChannel {
payload: None,
};
if write
.send(WsMsg::Binary(initial_ping.encode_to_vec()))
.send(WsMsg::Binary(initial_ping.encode_to_vec().into()))
.await
.is_err()
{
@ -309,7 +309,7 @@ impl LarkChannel {
headers: vec![PbHeader { key: "type".into(), value: "ping".into() }],
payload: None,
};
if write.send(WsMsg::Binary(ping.encode_to_vec())).await.is_err() {
if write.send(WsMsg::Binary(ping.encode_to_vec().into())).await.is_err() {
tracing::warn!("Lark: ping failed, reconnecting");
break;
}
@ -378,7 +378,7 @@ impl LarkChannel {
let mut ack = frame.clone();
ack.payload = Some(br#"{"code":200,"headers":{},"data":[]}"#.to_vec());
ack.headers.push(PbHeader { key: "biz_rt".into(), value: "0".into() });
let _ = write.send(WsMsg::Binary(ack.encode_to_vec())).await;
let _ = write.send(WsMsg::Binary(ack.encode_to_vec().into())).await;
}
// Fragment reassembly
@ -917,9 +917,11 @@ mod tests {
#[test]
fn lark_ws_activity_refreshes_heartbeat_watchdog() {
assert!(should_refresh_last_recv(&WsMsg::Binary(vec![1, 2, 3])));
assert!(should_refresh_last_recv(&WsMsg::Ping(vec![9, 9])));
assert!(should_refresh_last_recv(&WsMsg::Pong(vec![8, 8])));
assert!(should_refresh_last_recv(&WsMsg::Binary(
vec![1, 2, 3].into()
)));
assert!(should_refresh_last_recv(&WsMsg::Ping(vec![9, 9].into())));
assert!(should_refresh_last_recv(&WsMsg::Pong(vec![8, 8].into())));
}
#[test]

28
src/channels/mod.rs
View file

@ -6,6 +6,7 @@ pub mod imessage;
pub mod irc;
pub mod lark;
pub mod linq;
#[cfg(feature = "channel-matrix")]
pub mod matrix;
pub mod mattermost;
pub mod qq;
@ -27,6 +28,7 @@ pub use imessage::IMessageChannel;
pub use irc::IrcChannel;
pub use lark::LarkChannel;
pub use linq::LinqChannel;
#[cfg(feature = "channel-matrix")]
pub use matrix::MatrixChannel;
pub use mattermost::MattermostChannel;
pub use qq::QQChannel;
@ -1389,7 +1391,10 @@ pub async fn handle_command(command: crate::ChannelCommands, config: &Config) ->
("Mattermost", config.channels_config.mattermost.is_some()),
("Webhook", config.channels_config.webhook.is_some()),
("iMessage", config.channels_config.imessage.is_some()),
("Matrix", config.channels_config.matrix.is_some()),
(
"Matrix",
cfg!(feature = "channel-matrix") && config.channels_config.matrix.is_some(),
),
("Signal", config.channels_config.signal.is_some()),
("WhatsApp", config.channels_config.whatsapp.is_some()),
("Linq", config.channels_config.linq.is_some()),
@ -1401,6 +1406,11 @@ pub async fn handle_command(command: crate::ChannelCommands, config: &Config) ->
] {
println!(" {} {name}", if configured { "✅" } else { "❌" });
}
if !cfg!(feature = "channel-matrix") {
println!(
" ℹ️ Matrix channel support is disabled in this build (enable `channel-matrix`)."
);
}
println!("\nTo start channels: zeroclaw channel start");
println!("To check health: zeroclaw channel doctor");
println!("To configure: zeroclaw onboard");
@ -1489,6 +1499,7 @@ pub async fn doctor_channels(config: Config) -> Result<()> {
));
}
#[cfg(feature = "channel-matrix")]
if let Some(ref mx) = config.channels_config.matrix {
channels.push((
"Matrix",
@ -1503,6 +1514,13 @@ pub async fn doctor_channels(config: Config) -> Result<()> {
));
}
#[cfg(not(feature = "channel-matrix"))]
if config.channels_config.matrix.is_some() {
tracing::warn!(
"Matrix channel is configured but this build was compiled without `channel-matrix`; skipping Matrix health check."
);
}
if let Some(ref sig) = config.channels_config.signal {
channels.push((
"Signal",
@ -1864,6 +1882,7 @@ pub async fn start_channels(config: Config) -> Result<()> {
channels.push(Arc::new(IMessageChannel::new(im.allowed_contacts.clone())));
}
#[cfg(feature = "channel-matrix")]
if let Some(ref mx) = config.channels_config.matrix {
channels.push(Arc::new(MatrixChannel::new_with_session_hint(
mx.homeserver.clone(),
@ -1875,6 +1894,13 @@ pub async fn start_channels(config: Config) -> Result<()> {
)));
}
#[cfg(not(feature = "channel-matrix"))]
if config.channels_config.matrix.is_some() {
tracing::warn!(
"Matrix channel is configured but this build was compiled without `channel-matrix`; skipping Matrix runtime startup."
);
}
if let Some(ref sig) = config.channels_config.signal {
channels.push(Arc::new(SignalChannel::new(
sig.http_url.clone(),

18
src/channels/qq.rs
View file

@ -263,7 +263,9 @@ impl Channel for QQChannel {
}
}
});
write.send(Message::Text(identify.to_string())).await?;
write
.send(Message::Text(identify.to_string().into()))
.await?;
tracing::info!("QQ: connected and identified");
@ -287,7 +289,11 @@ impl Channel for QQChannel {
_ = hb_rx.recv() => {
let d = if sequence >= 0 { json!(sequence) } else { json!(null) };
let hb = json!({"op": 1, "d": d});
if write.send(Message::Text(hb.to_string())).await.is_err() {
if write
.send(Message::Text(hb.to_string().into()))
.await
.is_err()
{
break;
}
}
@ -298,7 +304,7 @@ impl Channel for QQChannel {
_ => continue,
};
let event: serde_json::Value = match serde_json::from_str(&msg) {
let event: serde_json::Value = match serde_json::from_str(msg.as_ref()) {
Ok(e) => e,
Err(_) => continue,
};
@ -315,7 +321,11 @@ impl Channel for QQChannel {
1 => {
let d = if sequence >= 0 { json!(sequence) } else { json!(null) };
let hb = json!({"op": 1, "d": d});
if write.send(Message::Text(hb.to_string())).await.is_err() {
if write
.send(Message::Text(hb.to_string().into()))
.await
.is_err()
{
break;
}
continue;