iris/ai-app
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Condense the documentation and thin the server's comments

Browse Source 
The markdown had accumulated a lot that was stale rather than wrong.
PLAN.md still described pi as the llama.cpp harness, a refcounted
LlamaServerManager, and a providers-by-hosts cross-product, all of which
were superseded or never built; it also carried a second copy of the HTTP
table that routes.rs owns. EXPLORER.md and TRANSCRIPT_CACHE.md held
implementation checklists for work that has since landed. AGENTS.md
restated most of PLAN.md's design instead of being the working-notes
layer it says it is. 3225 lines of markdown to 2180, with the stale
sections gone rather than reworded.

On the server, comments explaining what the code already says are out and
the ones recording a constraint, a measurement or an incident are kept but
cut to a few lines each: 5504 comment lines to 4586.

Four doc comments in session/mod.rs, and one each in process.rs and
usage.rs, had drifted onto the item above the one they describe --
functions were reordered without them, so `stop_session`'s doc sat on
`set_session_cwd`, `stat_of`'s on `struct Stat`, and `UsageMonitor`'s on
`type Cached`. Each is back on its own item.

routes.rs's module table also claimed later phases would add `/hosts`,
which setups replaced.

cargo test (127 passed), clippy --all-targets and fmt are clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
irisandClaude Opus 5 committed 2026-09-04 15:45:43 -04:00
1 parent e3e02d55f7
commit 79682f03a7
24 files changed
+4572 -6821
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

server/src/session/pending.rs
+37 -47
View File
@@ -1,20 +1,18 @@
//! What is being done to a machine's Claude Code sessions right now.
//!
//! Importing and deleting used to be whatever the phone was in the middle
//! of: the request was the work, so leaving the screen cancelled it and
//! coming back showed no sign it had ever started. Sessions half-imported
//! that way are the expensive kind of missing -- the row is back in the
//! list looking untouched, and taking it again is the second `--resume` the
//! whole import path exists to prevent.
//! Importing and deleting used to be whatever the phone was in the middle of:
//! the request was the work, so leaving the screen cancelled it and coming back
//! showed no sign it had ever started. Sessions half-imported that way are the
//! expensive kind of missing -- the row is back in the list looking untouched,
//! and taking it again is the second `--resume` the import path exists to
//! prevent.
//!
//! So the work runs here, on the server, and this is the record of it. The
//! phone reads that record two ways, and needs both: every row of `GET
//! /setups/{id}/importable` carries what is happening to it, which is what
//! a phone that was asleep, out of range, or freshly opened has to go on;
//! and [`Registry::subscribe`] is the live stream, which is what makes a
//! screen somebody is looking at change by itself. Neither is sufficient
//! alone -- a broadcast has no memory, and a listing is only true when it
//! was fetched.
//! phone reads that record two ways and needs both: every row of the importable
//! listing carries what is happening to it, which is what a phone that was
//! asleep has to go on; and [`Registry::subscribe`] is the live stream, which is
//! what makes a screen change by itself. A broadcast has no memory, and a
//! listing is only true when it was fetched.
use std::collections::HashMap;
use std::sync::{Arc, Mutex};
@@ -31,8 +29,8 @@ pub enum Operation {
}
impl Operation {
/// The word a row shows while this runs. Fixed here rather than in the
/// app so the two ends cannot disagree about what a state is called.
/// The word a row shows while this runs. Fixed here rather than in the app
/// so the two ends cannot disagree about what a state is called.
pub fn label(self) -> &'static str {
match self {
Self::Importing => "importing",
@@ -43,11 +41,9 @@ impl Operation {
/// One change to what is in flight, as it goes out on the stream.
///
/// The three states are every way an operation ends, including the two that
/// are easy to leave out: it can still be running, it can have finished,
/// and it can have failed. There is deliberately no "unknown" -- this is
/// the server's own work, so not knowing would be a bug rather than a
/// state.
/// The three states are every way an operation ends, including the two easy to
/// leave out: still running, finished, and failed. There is deliberately no
/// "unknown" -- this is the server's own work, so not knowing would be a bug.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase", tag = "state")]
pub enum Change {
@@ -68,9 +64,8 @@ pub enum Change {
}
impl Change {
/// Which machine this is about, so a stream scoped to one can drop the
/// rest. Every variant carries it; matching here rather than at the
/// filter keeps that fact in one place.
/// Which machine this is about, so a stream scoped to one can drop the rest.
/// Every variant carries it; matching here keeps that fact in one place.
pub fn setup(&self) -> &str {
match self {
Self::Started { setup, .. }
@@ -84,11 +79,10 @@ impl Change {
#[derive(Debug)]
pub struct Registry {
running: Mutex<HashMap<(String, String), Operation>>,
/// Kept after the operation ends, because a phone that was not looking
/// when it failed has no other way to find out. Replaced when the next
/// operation on that session starts, and dropped by [`Registry::prune`]
/// when the session is no longer on the machine -- an error about a
/// transcript that is gone has nothing left to be about.
/// Kept after the operation ends, because a phone that was not looking when
/// it failed has no other way to find out. Replaced when the next operation
/// on that session starts, and dropped by [`Registry::prune`] when the
/// session is no longer on the machine.
failures: Mutex<HashMap<(String, String), String>>,
changes: broadcast::Sender<Change>,
}
@@ -98,8 +92,8 @@ impl Default for Registry {
Self {
running: Mutex::new(HashMap::new()),
failures: Mutex::new(HashMap::new()),
// Enough that a phone watching one screen cannot lag behind a
// batch of any size somebody would start by hand.
// Enough that a phone watching one screen cannot lag behind a batch
// of any size somebody would start by hand.
changes: broadcast::channel(256).0,
}
}
@@ -109,10 +103,9 @@ impl Registry {
/// Marks an operation as running and announces it.
///
/// The returned guard is how it stops being marked: settle it with
/// [`InFlight::succeeded`] or [`InFlight::failed`], or drop it and it
/// reports a failure. Dropping without settling means the task was
/// cancelled or panicked, and a row stuck on "importing" for ever is a
/// worse answer than one that says it did not finish.
/// [`InFlight::succeeded`] or [`InFlight::failed`], or drop it and it reports
/// a failure. Dropping without settling means the task was cancelled or
/// panicked, and a row stuck on "importing" for ever is a worse answer.
pub fn begin(self: &Arc<Self>, setup: &str, session: &str, operation: Operation) -> InFlight {
let key = (setup.to_string(), session.to_string());
self.running.lock().unwrap().insert(key.clone(), operation);
@@ -141,11 +134,8 @@ impl Registry {
self.failures.lock().unwrap().get(&key).cloned()
}
/// Forgets failures against sessions the machine no longer has.
///
/// Called from the listing, which is the only place that knows what is
/// still there. A deleted session's failure would otherwise outlive
/// everything it referred to.
/// Forgets failures against sessions the machine no longer has. Called from
/// the listing, which is the only place that knows what is still there.
pub fn prune(&self, setup: &str, present: &[String]) {
self.failures
.lock()
@@ -155,8 +145,8 @@ impl Registry {
});
}
/// Every change as it happens. See the module note on why this is not
/// the only way the phone finds out.
/// Every change as it happens. See the module note on why this is not the
/// only way the phone finds out.
pub fn subscribe(&self) -> broadcast::Receiver<Change> {
self.changes.subscribe()
}
@@ -229,8 +219,8 @@ mod tests {
assert!(matches!(changes.try_recv(), Ok(Change::Finished { .. })));
}
/// A failure outlives the operation, because the phone that needs it may
/// not have been listening when it happened.
/// A failure outlives the operation, because the phone that needs it may not
/// have been listening when it happened.
#[test]
fn a_failure_is_kept_until_something_replaces_or_prunes_it() {
let registry = Arc::new(Registry::default());
@@ -256,8 +246,8 @@ mod tests {
assert!(registry.failure("local", "abc").is_none());
}
/// Trying again clears the last failure, so a row cannot show an error
/// from before the attempt somebody is currently watching.
/// Trying again clears the last failure, so a row cannot show an error from
/// before the attempt somebody is currently watching.
#[test]
fn starting_again_clears_the_previous_failure() {
let registry = Arc::new(Registry::default());
@@ -270,8 +260,8 @@ mod tests {
second.succeeded();
}
/// A task that is cancelled or panics must not leave a row saying
/// something is still happening to it.
/// A task that is cancelled or panics must not leave a row saying something
/// is still happening to it.
#[test]
fn dropping_an_unsettled_operation_reports_a_failure() {
let registry = Arc::new(Registry::default());