Skip to content
Open
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
4 changes: 2 additions & 2 deletions docs/peer-interviews.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ Only session members may export a saved transcript or audio; each member reads
their own AI suggestions. Either member can delete the shared saved transcript
or stop/delete shared audio. Deleting audio stops its writer before unlinking
files. This does not stop the previously agreed temporary AI processing and
suggestions; terminate the session to stop the interview. A downloaded copy
suggestions; cancel the session to stop the interview. A downloaded copy
cannot be recalled by deleting the server copy. A withdrawal made before capture
starts is recorded, and the observer then declines to record that audio.

Expand Down Expand Up @@ -289,7 +289,7 @@ actual transcripts or audio to a public issue.
completion, confirm 24-hour expiry blocks reads and cleanup removes files.
9. Opt out of availability and expire a heartbeat; confirm the roster and
pending requests disappear. Abandon a confirmed availability proposal and
verify ten-minute cleanup. Terminate an active session and confirm LiveKit
verify ten-minute cleanup. Cancel an active session and confirm LiveKit
room deletion.
10. Allow a short round and hard deadline to expire with no polling; confirm
final capture and settlement continue even while room deletion is stalled.
Expand Down
44 changes: 14 additions & 30 deletions docs/recording-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -442,10 +442,13 @@ made the distinction necessary:

### Ending

Normal end is `POST /api/interviews/{id}/end` or the LiveKit `room_finished`
webhook, whichever arrives first. Neither is optional: a browser can be closed
and a webhook can be lost. Both move the recording to `finalizing`, and
`finalizing` may become itself, so the second one to arrive changes nothing.
Normal end is the LiveKit `room_finished` webhook, which moves the recording to
`finalizing`. `finalizing` may become itself, so a repeated delivery changes
nothing. The browser sends no end of its own. The file arrives with the
`egress_ended` that Egress sends, which also completes the recording if
`room_finished` was lost. If `egress_ended` is lost, whether or not
`room_finished` arrived, the row is left to the sweeper below, which fails it as
`abandoned` once the bound for its state has passed.

Consent withdrawal is not a normal end. The recording is not finished, it is
abandoned: it goes to `failed` with reason `consent_withdrawn` and the file it
Expand Down Expand Up @@ -742,38 +745,19 @@ allocated the number the caller is told.

### The snapshot

`GET /api/interviews/{id}/snapshot`, signed in, answering
`{"seq", "quotaExceeded", "events": [...]}`.

Nothing is stored to produce it and there is no cadence to configure. The four
replaceable kinds already are the snapshot: the newest event of each is the
whole state of that kind, so a snapshot is the replay with the superseded frames
dropped, computed at the read. A periodic snapshot written to a second table
would be a copy that can disagree with the events it was made from.

A late join is therefore the snapshot plus everything after `seq`, concatenated.
The ceiling and the rows under it are read in one transaction, so a writer
landing between two statements cannot put an event in the snapshot that the
caller is about to ask for again.

| Answer | When |
|---|---|
| `200` | the snapshot, and the `seq` to carry on from |
| `404 recording_not_found` | no such interview, not this account's, consent withdrawn, or this server records nothing |
| `410 replay_expired` | past the retention deadline, whether or not the sweeper has run |
| `410 recording_deleted` | the recording is a tombstone |

`410` rather than `404` for the last two: the account owns the interview and is
owed the difference between "never yours" and "not any more".

Authorization is the account that owns the interview, and nothing else. There is
no separate verified-identity gate here, because a replay is scoped by account
row rather than by handle: a self-declared account is its own row and sees its
own interviews. The verified-identity gate lives where identity decides who
receives a file, which is the start of a recording, not the read of a replay.

An interview whose recording never started still has a replay and it is readable.
Expiry and deletion are read from the recording when there is one.
`GET /api/recordings/{id}/events` and the template's replay read, both below,
serve it, answering `{"seq", "quotaExceeded", "events": [...]}`;
`quotaExceeded` says the replay stopped growing at its quota, so its tail is
missing. The ceiling and the rows under it are read in one transaction, so a
writer landing between two statements cannot put an event in the snapshot that
the caller is about to ask for again.

### The template's replay read

Expand Down Expand Up @@ -1523,7 +1507,7 @@ new reads and future ready transitions, then waits for the observer to close
its writer and unlinks saved and partial files. A late capture finish cannot
resurrect the record. Already downloaded copies cannot be recalled. Deleting
saved audio does not cancel the separately agreed temporary AI transcription
and end-only suggestions; session termination stops the interview.
and end-only suggestions; cancelling the session stops the interview.

Transcripts are separately selectable and withdrawable. When not selected,
raw text exists only in bounded observer memory until the same session's
Expand Down
13 changes: 3 additions & 10 deletions src/accounts/peer/rounds.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,21 +28,14 @@ pub(super) fn action(
}
if matches!(
action,
"ready" | "start" | "advance" | "finish" | "terminate" | "cancel" | "invite"
"ready" | "start" | "advance" | "finish" | "cancel" | "invite"
) && let Err(e) = version(s, body)
{
return Ok(Err(e));
}
let result = match action {
"cancel" | "terminate" => {
s.close_partial(
if action == "cancel" {
"cancelled"
} else {
"finalizing"
},
now,
);
"cancel" => {
s.close_partial("cancelled", now);
c.execute("DELETE FROM peer_active_users WHERE session_id=?1", [&s.id])?;
Ok(())
}
Expand Down
6 changes: 4 additions & 2 deletions src/recording/replay.rs
Original file line number Diff line number Diff line change
Expand Up @@ -689,8 +689,10 @@ fn replay_view(
return Ok(SnapshotView::NoInterview);
}

// No recording row is not a refusal: an interview whose recording never
// started still has a replay, and it is this account's to read.
// No recording row is not a refusal, only nothing to check expiry or
// deletion against. The history events route and the template's replay
// read find the recording first, so through them the row is always
// there.
let recording: Option<(String, Option<i64>, i64)> = transaction
.query_row(
"
Expand Down
4 changes: 2 additions & 2 deletions src/recording/store.rs
Original file line number Diff line number Diff line change
Expand Up @@ -309,8 +309,8 @@ pub fn transition_within(
}

// Somebody else moved it first, so the state to report is theirs and
// not the one that was asked for. Reporting `next` here told `/end`
// that a recording was `finalizing` when it had already failed.
// not the one that was asked for. Reporting `next` here told the stop
// path that a recording was `finalizing` when it had already failed.
let actual: String = connection.query_row(
"SELECT state FROM recordings WHERE id = ?1",
[recording_id],
Expand Down
15 changes: 8 additions & 7 deletions src/recording/sweeper.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,11 @@ use super::{
/// Moves the row and then stops the provider, in that order.
///
/// The order matters and is not obvious. Calling the provider first meant two
/// callers racing on one recording, `/end` and a `room_finished` webhook say,
/// both sent a stop, and a process that died between a successful stop and the
/// write left a row that stayed active forever. Moving first makes the row the
/// record of intent, and only the caller that moved it talks to the provider.
/// callers racing on one recording, a `room_finished` webhook and the sweeper
/// say, both sent a stop, and a process that died between a successful stop and
/// the write left a row that stayed active forever. Moving first makes the row
/// the record of intent, and only the caller that moved it talks to the
/// provider.
///
/// A failed stop leaves the row where it was moved to and the job still
/// running, which the sweeper finds once the row goes stale. That is the cost
Expand Down Expand Up @@ -132,9 +133,9 @@ pub async fn start_and_record_egress(

if stored {
// A stop can land while the provider is still answering: consent
// withdrawn, the room finished, the candidate closed the tab. The row
// keeps the id whatever state it is in, and this is where a job that
// outlived its recording gets stopped.
// withdrawn or the room finished. The row keeps the id whatever state
// it is in, and this is where a job that outlived its recording gets
// stopped.
settle_new_egress(accounts, recorder, &recording.id, &egress_id).await;
} else {
// Either the row already names another job, from the other caller
Expand Down
80 changes: 4 additions & 76 deletions src/web/interviews.rs
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
//! The interview record itself: creating one, ending it, the consent that
//! gates recording, the replay events it accumulates, and the reports written
//! The interview record itself: creating one, the consent that gates
//! recording, the replay events it accumulates, and the reports written
//! against it.

use std::time::Instant;

use axum::body::Body;
use axum::extract::{Path as UriPath, State};
use axum::http::{Request, StatusCode};
use axum::response::{IntoResponse, Response};
use axum::response::Response;
use serde_json::{Value, json};

use crate::accounts::{
Expand All @@ -17,12 +17,8 @@ use crate::accounts::{
use crate::current_epoch_seconds_i64;

use super::auth::Owner;
use super::recordings::finish_recording;
use super::token::{read_body_or_refuse, read_body_with};
use super::{
AppState, MAX_BODY_BYTES, MAX_REPORT_BYTES, json_response, rate_limited_response,
replay_response,
};
use super::{AppState, MAX_BODY_BYTES, MAX_REPORT_BYTES, json_response, rate_limited_response};

/// What one account posting replay events may spend in a window.
///
Expand Down Expand Up @@ -221,43 +217,6 @@ pub(crate) async fn create_interview_handler(
}
}

/// The interview is over.
///
/// One of the two ways a recording stops normally, and neither is optional: the
/// browser can be closed and the `room_finished` webhook can be lost, so the
/// pipeline has to survive either arriving alone and both arriving in any
/// order.
pub(crate) async fn end_interview_handler(
State(state): State<AppState>,
UriPath(interview_id): UriPath<String>,
Owner { accounts, user }: Owner,
) -> Response {
let Some(recorder) = state.recorder.clone() else {
return StatusCode::NO_CONTENT.into_response();
};
let found = {
let accounts = std::sync::Arc::clone(&accounts);
let interview_id = interview_id.clone();
blocking(move || {
crate::recording::recording_for_interview(&accounts, &interview_id, user.id)
})
.await
};
match found {
// Nothing recorded, so there is nothing to stop. Not a 404: the
// interview ending is the candidate's news either way.
Ok(None) => StatusCode::NO_CONTENT.into_response(),
Ok(Some(recording)) => finish_recording(&accounts, &recorder, &recording).await,
Err(error) => {
eprintln!("could not read a recording while ending an interview: {error}");
json_response(
StatusCode::INTERNAL_SERVER_ERROR,
json!({ "error": "Could not end the interview." }),
)
}
}
}

/// The replay, arriving one batch at a time.
///
/// Authenticated and owner-scoped like everything else about an interview, and
Expand Down Expand Up @@ -381,34 +340,3 @@ pub(crate) async fn replay_events_handler(
}
}
}

/// Where a late join starts.
///
/// The snapshot is the replay with the superseded frames dropped, and `seq` is
/// where the caller carries on from. Nothing is stored to produce it and there
/// is no cadence to configure.
pub(crate) async fn replay_snapshot_handler(
State(state): State<AppState>,
UriPath(interview_id): UriPath<String>,
Owner { accounts, user }: Owner,
) -> Response {
let missing = || {
json_response(
StatusCode::NOT_FOUND,
json!({ "code": "recording_not_found", "error": "No replay for that interview." }),
)
};
if state.recorder.is_none() {
return missing();
}
let now = current_epoch_seconds_i64();
let view =
blocking(move || crate::recording::replay_snapshot(&accounts, &interview_id, user.id, now))
.await;

// Gone rather than not-found on an expired or deleted replay: this account
// owns the interview and is owed the difference between "never yours" and
// "not any more". That distinction, and the two sentences carrying it, are
// `replay_response`'s, shared with the two recording routes.
replay_response(view, missing, "could not read a replay snapshot")
}
26 changes: 13 additions & 13 deletions src/web/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -578,12 +578,7 @@ pub(crate) fn web_router(
"/api/interviews/{id}/recording",
post(start_recording_handler).get(recording_status_handler),
)
.route("/api/interviews/{id}/end", post(end_interview_handler))
.route("/api/interviews/{id}/events", post(replay_events_handler))
.route(
"/api/interviews/{id}/snapshot",
get(replay_snapshot_handler),
)
.route(
crate::recording::WEBHOOK_ROUTE,
post(recording_webhook_handler),
Expand Down Expand Up @@ -1099,20 +1094,21 @@ fn forwarded_client(headers: &header::HeaderMap, peer: SocketAddr, hops: u32) ->
.unwrap_or_else(|| peer.ip())
}

/// One answer for every replay read, so the three routes that take one cannot
/// drift apart.
/// One answer for every replay read, so the history events route and the
/// template's replay read cannot drift apart.
///
/// They differ in two things and this takes both: what "no such replay" means
/// to the caller, which is a recording id to one route and a room to another,
/// and the sentence a read error is logged under. Everything else was written
/// out three times, including the two `410` bodies, and those are the retention
/// promise: a copy that said something slightly different would be a third
/// answer to a question the product gives one answer to. `gone_response` below
/// exists for the same reason on the route ahead of this one.
/// out three times before the fold, including the two `410` bodies, and those
/// are the retention promise: a copy that said something slightly different
/// would be a second answer to a question the product gives one answer to.
/// `recordings::gone_response` exists for the same reason on the route ahead of
/// this one.
///
/// A function pointer rather than a closure, because none of the three captures
/// A function pointer rather than a closure, because no route captures
/// anything: what a route answers here is a constant, and a signature that
/// allowed a captured one would be inviting a fourth thing to differ.
/// allowed a captured one would be inviting another thing to differ.
pub(crate) fn replay_response(
view: rusqlite::Result<crate::recording::SnapshotView>,
missing: fn() -> Response,
Expand Down Expand Up @@ -1162,3 +1158,7 @@ fn replay_body(snapshot: &crate::recording::Snapshot) -> Value {
.collect::<Vec<_>>(),
})
}

#[cfg(test)]
#[path = "../../tests/unit/web.rs"]
mod tests;
2 changes: 1 addition & 1 deletion src/web/recordings/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,7 @@ pub(crate) async fn recording_status_handler(
/// Asks the provider to stop and moves the row to `finalizing`.
///
/// Idempotent by way of the transition table: `finalizing` may become itself,
/// so the second of the two normal-end paths to arrive changes nothing.
/// so a second `room_finished` delivery changes nothing.
pub(crate) async fn finish_recording(
accounts: &Arc<Accounts>,
recorder: &crate::recording::Recorder,
Expand Down
9 changes: 4 additions & 5 deletions tests/recording.rs
Original file line number Diff line number Diff line change
Expand Up @@ -918,11 +918,10 @@ pub(crate) mod lifecycle {
vec!["EG_live@interview-abc12345".to_string()]
);

// The other normal-end path arriving second changes nothing, which is
// what lets a browser close and a webhook be lost independently. The
// provider is not asked again either: only the caller that moved the
// row talks to it, so `/end` racing a `room_finished` webhook sends one
// stop rather than two.
// A second stop arriving changes nothing, as when a `room_finished`
// webhook is delivered twice. The provider is not asked again either:
// only the caller that moved the row talks to it, so two deliveries
// send one stop rather than two.
let recording = recording_by_id(&accounts, "rec-1").unwrap().unwrap();
let again = codetrial::recording::stop_recording(
&accounts,
Expand Down
2 changes: 1 addition & 1 deletion tests/unit/accounts/peer/retention.rs
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ fn rounds_snapshots_feedback_and_invites_go_with_their_session() {
}

#[test]
fn a_terminated_session_and_its_paired_lobby_entry_are_pruned() {
fn a_finalizing_session_and_its_paired_lobby_entry_are_pruned() {
let a = fixture();
let now = 100 * DAY;
let old = session(&a, 1, now - RETENTION_SECONDS - 1, "finalizing");
Expand Down
Loading
Loading