randogoth/bunshin
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

feat: harden the RNS carrier: idle-link reaper, refusal logging, patched microReticulum fork

Browse source
This commit is contained in:
randogoth 2026-09-29 10:27:44 +03:00
parent 07f064460f
commit 8ea6865e7e
6 changed files with 110 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -55,7 +55,7 @@ bunshin rns-keygen --key server.rns.key
bunshin serve --rns --key server.key --rns-key server.rns.key --db mail.db --rns-udp 0.0.0.0:4242
```
`rns-keygen` writes the 64-byte Reticulum identity and prints the destination hash; publish `smol+rns://<user>@<hash>` as the server's address. RNS-specific limits (`--rns-max-envelope`, `--rns-fetch-budget`, `--rns-max-links`, `--rns-rate-link-requests`, `--rns-rate-link-bytes`) default to mesh-friendly 32 KiB caps; the UDP interface is the one supported transport interface so far. See [RNS.md](RNS.md).
`rns-keygen` writes the 64-byte Reticulum identity and prints the destination hash; publish `smol+rns://<user>@<hash>` as the server's address. RNS-specific limits (`--rns-max-envelope`, `--rns-fetch-budget`, `--rns-max-links`, `--rns-rate-link-requests`, `--rns-rate-link-bytes`) default to mesh-friendly 32 KiB caps; `--rns-link-idle` (default 300 s) reaps links whose client went silent, since nothing else times a link out; the UDP interface is the one supported transport interface so far. See [RNS.md](RNS.md).
## Building

6
RNS.md
View file

@ -126,6 +126,7 @@ One process serves both carriers: shared `Store`, shared config, one systemd uni
| `--rns-max-links` | 100 | concurrent links — refused past the cap |
| `--rns-rate-link-requests` | 60 | per link per minute |
| `--rns-rate-link-bytes` | 1048576 | per link per minute, via `ByteRateLimiter` |
| `--rns-link-idle` | 300 | seconds of silence before a link is reaped; 0 disables the reaper |
| `--rns-udp` | `127.0.0.1:4242` | UDP interface to listen on, host[:port] |
| `--rns-udp-forward` | unset | optional forward target; without it the interface replies to the last datagram's source |
@ -144,8 +145,9 @@ The per-link request limiter reuses `RateLimiter` keyed by the link hex. The per
## 9. Remaining open items
1. Cross-transport envelope size: per-transport caps are enforced; a 768 KiB TCP envelope is still delivered whole to an RNS FETCH. Operators should apply the smaller cap mailbox-wide when in doubt (upstream spec 13.7).
2. Interfaces beyond UDP (RNS-compatible TCP hub/client, I2P): microReticulum ships none; the UDP interface is the first supported one.
3. The reference `test_interop/run_request_response.sh` harness was not rerun against the shim; its PlatformIO build step is unavailable here. The equivalent interop was exercised directly against `smolmail_rns.py` (§10.6).
2. Upstream `microReticulum` deadlock: a client dying mid-resource-transfer wedges the single transport loop forever — `Resource::request_next` sends its `RESOURCE_REQ` through `Transport::outbound` from inside the `jobs()` resource tick, and `outbound` busy-waits on `_jobs_running`, a flag `jobs()` itself holds. No announces, no new links, mesh dead until restart. The vendored source is a local fork carrying the fix (same-thread reentrant calls skip the cycle wait); the equivalent report is filed upstream.
3. Interfaces beyond UDP (RNS-compatible TCP hub/client, I2P): microReticulum ships none; the UDP interface is the first supported one.
4. The reference `test_interop/run_request_response.sh` harness was not rerun against the shim; its PlatformIO build step is unavailable here. The equivalent interop was exercised directly against `smolmail_rns.py` (§10.6).
Formerly open items resolved during implementation: raw identity bytes exist (`load_private_key`); the shim ABI and run-loop drive pattern are §7.1/§7.2; `ALLOW_ALL` matches the reference; announcing at startup + every 2 h, unconditional even when invite-only (the invite gates REGISTER, not the link); the interface question is §7.4.

4
THIRD_PARTY_NOTICES.md
View file

@ -1,6 +1,6 @@
# Third-Party Notices
bunshin incorporates the third-party components listed below. Components are grouped by license, each with the copyright notice that applies to it, followed by the full license text. A component listed under several licenses is multi-licensed under those options; any one of them may be chosen. All components are redistributed unmodified from their published sources.
bunshin incorporates the third-party components listed below. Components are grouped by license, each with the copyright notice that applies to it, followed by the full license text. A component listed under several licenses is multi-licensed under those options; any one of them may be chosen. Components are redistributed from their published sources, except where a bullet notes a local patch; all other components are unmodified.
The Rust crates listed are all crates resolved by `Cargo.lock`, including transitive dependencies, which are statically linked into the bunshin binary.
The SQLite C library is bundled in source form by the `libsqlite3-sys` crate and is public domain (see the final section).
@ -102,7 +102,7 @@ The libraries marked "vendored source" are pinned nix flake inputs; each is iden
- zerocopy-derive 0.8.59 - Copyright 2023 The Fuchsia Authors
- zeroize 1.9.0 - Copyright (c) 2018-2026 The RustCrypto Project Developers
- zeroize_derive 1.5.0 - Copyright (c) 2019-2026 The RustCrypto Project Developers
- microReticulum (vendored source, https://github.com/attermann/microReticulum, rev 40fa628809d5)
- microReticulum (vendored source, https://github.com/attermann/microReticulum, rev 40fa628809d5; patched locally — same-thread reentrant calls skip the Transport::outbound/inbound jobs-cycle wait, fixing a transport-loop deadlock, see RNS.md §9)
- microStore (vendored source, https://github.com/attermann/microStore, rev 0f28567fe00a)
```

20
flake.lock generated
View file

@ -21,18 +21,18 @@
"microReticulum": {
"flake": false,
"locked": {
"lastModified": 1784575896,
"narHash": "sha256-cqo+BJ3tsmw4fD+SL0D3X9FKCgf+n0VQng2pSIuyK/8=",
"owner": "attermann",
"repo": "microReticulum",
"rev": "40fa628809d57140180c1c833559ab96fec992c1",
"type": "github"
"lastModified": 1790668417,
"narHash": "sha256-BrOkpepwcCfB7o9TOYOQ3SnZfwHVx3WyUTJsIGwAdLk=",
"ref": "fix/outbound-reentrancy-deadlock",
"rev": "03be60051d40e556933101289c0203d9f3308b62",
"revCount": 226,
"type": "git",
"url": "file:///mnt/data/Projects/code/microReticulum"
},
"original": {
"owner": "attermann",
"repo": "microReticulum",
"rev": "40fa628809d57140180c1c833559ab96fec992c1",
"type": "github"
"ref": "fix/outbound-reentrancy-deadlock",
"type": "git",
"url": "file:///mnt/data/Projects/code/microReticulum"
}
},
"nixpkgs": {

17
flake.nix
View file

@ -9,8 +9,13 @@
# so every microReticulum FetchContent dependency is vendored as its own
# flake input and handed over via RNS_<DEP>_SOURCE_DIR. microReticulum
# is pinned at the commit RNS.md sec 5 verified against.
# Local fork of attermann/microReticulum at rev 40fa628809d5 plus a
# local patch: Transport::outbound/inbound skip their jobs-cycle wait
# for same-thread reentrant calls, which otherwise deadlock the single
# transport loop when a stalled resource tick sends a RESOURCE_REQ
# from inside jobs() (see RNS.md sec 9).
microReticulum = {
url = "github:attermann/microReticulum/40fa628809d57140180c1c833559ab96fec992c1";
url = "git+file:///mnt/data/Projects/code/microReticulum?ref=fix/outbound-reentrancy-deadlock";
flake = false;
};
rns-arduinojson = {
@ -272,6 +277,15 @@
description = "Max request bytes per minute, per link.";
};
linkIdleSecs = mkOption {
type = types.ints.unsigned;
default = 300;
description = ''
Seconds after which an idle RNS link is reaped, freeing
its session and link slot; 0 disables the reaper.
'';
};
udpListenPort = mkOption {
type = types.port;
default = 4242;
@ -337,6 +351,7 @@
--rns-max-links ${toString cfg.rns.maxLinks}
--rns-rate-link-requests ${toString cfg.rns.rateLinkRequests}
--rns-rate-link-bytes ${toString cfg.rns.rateLinkBytes}
--rns-link-idle ${toString cfg.rns.linkIdleSecs}
--rns-udp 0.0.0.0:${toString cfg.rns.udpListenPort}
)
''}

77
src/rns.rs
View file

@ -12,6 +12,7 @@
use std::collections::{HashMap, HashSet};
use std::ffi::CString;
use std::sync::{Mutex, OnceLock};
use std::time::{Duration, Instant};
use crate::bind::TransportBindValues;
use crate::proto::{AUTH_FULL_TOKENS, INTERNAL_ERROR, MALFORMED, RATE_LIMITED, TOO_LARGE};
@ -59,6 +60,7 @@ pub struct RnsArgs {
pub udp_listen_port: u16,
pub udp_forward_host: Option<String>,
pub udp_forward_port: u16,
pub link_idle_secs: u64,
pub max_tokens: u16,
pub main_quota: i64,
pub requests_quota: i64,
@ -71,6 +73,10 @@ struct RnsState {
destination: [u8; 16],
sessions: Mutex<HashMap<[u8; 16], Session<'static>>>,
links: Mutex<HashSet<[u8; 16]>>,
/// Last-seen instant per link, the reaper's clock. Updated before the
/// limiters so a client still sending — even one being refused — counts
/// as alive; only a silent link is reapable.
last_activity: Mutex<HashMap<[u8; 16], Instant>>,
request_limiter: RateLimiter,
byte_limiter: ByteRateLimiter,
max_links: usize,
@ -117,6 +123,7 @@ pub fn start(args: RnsArgs) -> anyhow::Result<String> {
destination,
sessions: Mutex::new(HashMap::new()),
links: Mutex::new(HashSet::new()),
last_activity: Mutex::new(HashMap::new()),
request_limiter: RateLimiter::new(args.rate_link_requests),
byte_limiter: ByteRateLimiter::new(args.rate_link_bytes),
max_links: args.max_links,
@ -124,6 +131,13 @@ pub fn start(args: RnsArgs) -> anyhow::Result<String> {
};
STATE.get_or_init(|| state);
// microReticulum never times a link out and the shim has no server-side
// close, so a client that dies mid-link would hold its Store handle and
// maxLinks slot forever; 0 keeps the old never-expire behavior.
if args.link_idle_secs > 0 {
std::thread::spawn(move || reap_loop(Duration::from_secs(args.link_idle_secs)));
}
let storage_dir = CString::new(args.storage_dir).unwrap();
let listen_host = CString::new(args.udp_listen_host).unwrap();
let forward_host = args.udp_forward_host.map(|h| CString::new(h).unwrap());
@ -185,6 +199,9 @@ fn handle_request(request: &[u8], link_id: &[u8; 16]) -> Vec<u8> {
// an AUTH carrying a full token set, whichever is larger.
let max_request = (state.config.max_envelope + 34)
.max(AUTH_FULL_TOKENS + 32 * state.config.max_tokens as usize);
// Any request, even one about to be refused, proves the link is alive.
state.last_activity.lock().unwrap().insert(*link_id, Instant::now());
if request.len() > max_request {
log::warn!(
"request of {} bytes over {} byte cap",
@ -194,6 +211,9 @@ fn handle_request(request: &[u8], link_id: &[u8; 16]) -> Vec<u8> {
return response(TOO_LARGE);
}
if !state.request_limiter.allow(&link) || !state.byte_limiter.allow(&link, request.len()) {
// Pre-dispatch refusals never reach the session metrics, so they get
// their own line or the journal undercounts a spinning client.
log::debug!("link {link} rate limited: request refused");
return response(RATE_LIMITED);
}
@ -264,6 +284,45 @@ extern "C" fn smolmail_rns_take_response(out: *mut u8, cap: usize) -> usize {
}
}
/// Links whose last activity is at least `idle` old, with their age.
fn expired_links(
last_activity: &HashMap<[u8; 16], Instant>,
now: Instant,
idle: Duration,
) -> Vec<([u8; 16], Duration)> {
last_activity
.iter()
.filter(|(_, seen)| now.duration_since(**seen) >= idle)
.map(|(id, seen)| (*id, now.duration_since(*seen)))
.collect()
}
/// Evicts links that have gone silent: microReticulum never times a link
/// out and the shim has no server-side close, so a client that dies
/// mid-link would otherwise hold its Store handle and maxLinks slot
/// forever. A reaped link that somehow speaks again is treated as a fresh
/// session (unauthenticated until the next AUTH), which is safe.
fn reap_loop(idle: Duration) {
let interval = (idle / 4).clamp(Duration::from_secs(1), Duration::from_secs(60));
loop {
std::thread::sleep(interval);
let Some(state) = STATE.get() else {
return;
};
let expired = expired_links(&state.last_activity.lock().unwrap(), Instant::now(), idle);
for (link, age) in expired {
state.links.lock().unwrap().remove(&link);
state.sessions.lock().unwrap().remove(&link);
state.last_activity.lock().unwrap().remove(&link);
log::debug!(
"link {} reaped after {:?} idle",
data_encoding::HEXLOWER.encode(&link),
age
);
}
}
}
#[no_mangle]
extern "C" fn smolmail_rns_on_link_opened(link_id: *const u8) -> i32 {
let Some(state) = STATE.get() else {
@ -280,6 +339,9 @@ extern "C" fn smolmail_rns_on_link_opened(link_id: *const u8) -> i32 {
return 1;
}
links.insert(link);
if let Some(state) = STATE.get() {
state.last_activity.lock().unwrap().insert(link, Instant::now());
}
log::debug!("link {} opened ({} open)", data_encoding::HEXLOWER.encode(&link), links.len());
0
}
@ -290,6 +352,7 @@ extern "C" fn smolmail_rns_on_link_closed(link_id: *const u8) {
let link: [u8; 16] = unsafe { std::slice::from_raw_parts(link_id, 16).try_into().unwrap() };
state.links.lock().unwrap().remove(&link);
state.sessions.lock().unwrap().remove(&link);
state.last_activity.lock().unwrap().remove(&link);
log::debug!("link {} closed", data_encoding::HEXLOWER.encode(&link));
}
}
@ -311,4 +374,18 @@ mod tests {
"799855f4955f1b09fd20a13cd84f4e71"
);
}
#[test]
fn expired_links_selects_only_silent_ones() {
let mut last_activity = HashMap::new();
let now = Instant::now();
let idle = Duration::from_secs(300);
last_activity.insert([1u8; 16], now - Duration::from_secs(301)); // silent
last_activity.insert([2u8; 16], now - Duration::from_secs(299)); // active
last_activity.insert([3u8; 16], now); // just seen
let expired = expired_links(&last_activity, now, idle);
assert_eq!(expired.len(), 1);
assert_eq!(expired[0].0, [1u8; 16]);
assert!(expired[0].1 >= idle);
}
}