Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions src/client/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -724,6 +724,11 @@ pub struct SyncContentRequest {
/// `GET /v1/jobs/{id}` — an index job's progress. `completed_at` is the
/// terminal signal (set once the worker finishes, success or fail);
/// `error` is set only on failure.
///
/// The server embeds nothing itself: docstore derives the chunks and the
/// embeddings of the staged snapshot. `files_embedded` counts the files that
/// docstore reports ready, so it grows while docstore derives, not while the
/// client uploads. The job completes after the code graph of the snapshot.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct JobStatus {
Expand All @@ -735,10 +740,21 @@ pub struct JobStatus {
#[serde(default)]
pub files_deleted: i64,
pub files_failed: i64,
/// The chunk count of the copy's published snapshot. Set when docstore
/// completed the derivations of the job.
#[serde(default)]
pub chunk_count: Option<i64>,
#[serde(default)]
pub error: Option<String>,
/// The worker stage: `Deriving` while docstore derives the staged files,
/// `Graph` while the published snapshot waits for its code graph. Absent
/// from a server older than these stages.
#[serde(default)]
pub current_stage: Option<String>,
/// Files per second: the latest sample while docstore derives, then the
/// average of the job.
#[serde(default)]
pub operations_per_second: Option<f64>,
/// Set once the worker picks the job up (i.e. it's running).
#[serde(default)]
pub started_at: Option<String>,
Expand Down
40 changes: 32 additions & 8 deletions src/commands/index.rs
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,18 @@ fn poll_interval(elapsed: std::time::Duration) -> std::time::Duration {
}
}

/// The phase that the heartbeat names. Docstore derives the staged files while
/// the server reports `Deriving`; their count grows only then. In `Graph` the
/// files are searchable and the job waits for the code graph of the snapshot.
fn phase(job: &api::JobStatus) -> &'static str {
match job.current_stage.as_deref() {
Some("Graph") => "building graph",
Some("Paused") => "paused",
_ if job.started_at.is_some() => "embedding",
_ => "queued",
}
}

/// Poll the index job until the worker finishes embedding, reporting the
/// outcome. The job runs server-side regardless of whether we keep waiting, so
/// a timeout here isn't a failure — just stop watching.
Expand All @@ -161,6 +173,7 @@ async fn wait_for_job(client: &Client, job_id: &str) -> Result<()> {
embedded = job.files_embedded,
failed = job.files_failed,
chunks = job.chunk_count.unwrap_or(0),
files_per_sec = job.operations_per_second.unwrap_or(0.0),
"indexed",
);
return Ok(());
Expand All @@ -169,26 +182,24 @@ async fn wait_for_job(client: &Client, job_id: &str) -> Result<()> {
info!(
%job_id,
secs = JOB_WAIT.as_secs(),
"still embedding; continues server-side — check back with search",
"still {}; continues server-side — check back with search",
phase(&job),
);
return Ok(());
}

let now = std::time::Instant::now();
if now >= next_progress {
let progress = JobProgress::from(&job);
let phase = if job.started_at.is_some() {
"embedding"
} else {
"queued"
};
info!(
%job_id,
elapsed_secs = start.elapsed().as_secs(),
embedded = progress.embedded,
deleted = progress.deleted,
failed = progress.failed,
"{phase}: {}/{} processed",
files_per_sec = job.operations_per_second.unwrap_or(0.0),
"{}: {}/{} processed",
phase(&job),
progress.processed,
progress.total,
);
Expand All @@ -201,7 +212,7 @@ async fn wait_for_job(client: &Client, job_id: &str) -> Result<()> {

#[cfg(test)]
mod tests {
use super::{JobProgress, api, poll_interval, terminal_result};
use super::{JobProgress, api, phase, poll_interval, terminal_result};

#[test]
fn polling_is_responsive_for_fast_jobs_then_backs_off() {
Expand All @@ -228,6 +239,8 @@ mod tests {
files_failed: failed,
chunk_count: Some(21),
error: error.map(str::to_owned),
current_stage: Some("Deriving".into()),
operations_per_second: Some(1.5),
started_at: Some("2026-07-14T00:00:00Z".into()),
completed_at: completed.then(|| "2026-07-14T00:01:00Z".into()),
}
Expand All @@ -238,6 +251,17 @@ mod tests {
assert!(!terminal_result("job-1", &job(false, 0, None)).unwrap());
}

#[test]
fn heartbeat_names_the_native_stage_of_the_job() {
let mut deriving = job(false, 0, None);
assert_eq!(phase(&deriving), "embedding");
deriving.current_stage = Some("Graph".into());
assert_eq!(phase(&deriving), "building graph");
deriving.current_stage = None;
deriving.started_at = None;
assert_eq!(phase(&deriving), "queued");
}

#[test]
fn completed_worker_error_fails_the_command_as_embedding() {
let error = terminal_result("job-2", &job(true, 12, Some("store unavailable")))
Expand Down
2 changes: 2 additions & 0 deletions src/engine/coordinator/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -747,6 +747,8 @@ fn job(completed: bool, failed: i64, error: Option<&str>) -> api::JobStatus {
files_failed: failed,
chunk_count: completed.then_some(12),
error: error.map(str::to_string),
current_stage: None,
operations_per_second: None,
started_at: Some("2026-07-31T00:00:00Z".into()),
completed_at: completed.then(|| "2026-07-31T00:00:01Z".into()),
}
Expand Down
2 changes: 2 additions & 0 deletions src/query/render.rs
Original file line number Diff line number Diff line change
Expand Up @@ -740,6 +740,8 @@ mod tests {
files_failed: 3,
chunk_count: None,
error: None,
current_stage: None,
operations_per_second: None,
started_at: Some("2026-07-14T00:00:00Z".into()),
completed_at: None,
};
Expand Down
Loading