Skip to content

Commit 0e8741c

Browse files
committed
feat(rust): keyset cursor pagination for v2.session.list
PR #20 (Caminho A): complete v2.session.list with real cursor pagination, faithful to the TS keyset semantics (session.ts). - opencode-db: SessionListQuery gains `anchor: Option<ListAnchor>` + `directory` filter; SessionStore::list implements the keyset boundary on (time_created, id), flips order + reverses results for a `Previous` anchor, in both SqlxSessionStore and MemorySessionStore. New ListAnchor/ListDirection types. - opencode-server: the handler emits `previous`/`next` cursors (from the first/ last row, preserving filters+order) and follows an inbound `cursor`; default limit 50. Cursor codec is base64url(serde_json) — a Rust-native opaque token (not byte-interchangeable with TS across a mid-pagination rollback; documented). Undecodable cursor → 400 InvalidCursorError (the other arm of the golden 400 union). Added the `base64` crate (zero-dep, MIT/Apache). Verified: build/clippy -D warnings/fmt/test (db 22, server 25) and openapi-diff all green. Cursor round-trip covered end-to-end (page → next → previous) plus a DB-level keyset test for both store impls. https://claude.ai/code/session_017Lo2jkGdTgRvsPG6tcwEqz
1 parent 399f8e6 commit 0e8741c

7 files changed

Lines changed: 420 additions & 31 deletions

File tree

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
6161
clap = { version = "4", features = ["derive", "env"] }
6262
async-trait = "0.1"
6363
ulid = "1"
64+
# base64url for the opaque keyset pagination cursor (zero-dependency, MIT/Apache).
65+
base64 = "0.22"
6466
jsonc-parser = { version = "0.26", features = ["serde"] }
6567
# Search/glob — the ripgrep libraries (identical ignore/match semantics to ripgrep.ts).
6668
ignore = "0.4"

‎RUST_MIGRATION.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,8 @@ cargo-dist · cargo-deny. **Out of scope:** tree-sitter (TUI-only).
7777
- ✅ **Migration-journal verification** (PR #17, "TS migrates / Rust verifies"): boot health check reads the `migration` journal (+ **read-only** `__drizzle_migrations` bridge) and diffs against `EXPECTED_MIGRATIONS` (mirrors `migration.gen.ts`). Behind+journal-present → fatal with a clear message; ahead/no-journal → warn (policy documented in [`MIGRATION_POLICY.md`](./MIGRATION_POLICY.md), owner-approved).
7878
- ✅ **Session-store tables** (PR #17): `session_input` (event-sourced steering inbox) + `session_context_epoch` (per-session baseline/agent) models + repositories in `opencode-db`, DDL mirroring the final TS schema.
7979
- ✅ **First session read-route cutover** (PR #18): `GET /api/session/{sessionID}` (`v2.session.get`, group `session`) → `SessionV2Info`, served natively by reading the shared **`session` projection table** via a `SessionStore` wired through `AppContext`. **Finding:** the V2 read routes read projection tables (the projector folds events into them on the *write* path), not the event log per request — so a faithful Rust read is a `SELECT`, not an event fold. `session.status` is **not** cuttable yet (it reads per-process in-memory runner state, which lives in TS until Phase 4). Contract enforced by `openapi-diff` (now collapses `anyOf[X,X]` and drops the `{type:null}` member utoipa adds for `Option<$ref>`); seam-gated (`OPENCODE_RUST_ROUTES=session`, off by default). A separate test exercises `event_store.read()` against externally (TS-)written event rows.
80-
- ✅ **Session list cutover** (PR #19): `GET /api/session` (`v2.session.list`, group `session`) → `SessionsResponse` (`{ data: SessionV2Info[], cursor }`), same `SessionStore` with `limit`/`order`/`search`/`project`/`workspace` filters. Opaque keyset cursors are a follow-up (the `cursor` object is returned empty; its fields are optional in the contract). Contract-enforced (`/api/session`); the 400 union (`anyOf[InvalidCursorError, InvalidRequestError]`) reuses the dedup-collapsing normalizer.
80+
- ✅ **Session list cutover** (PR #19): `GET /api/session` (`v2.session.list`, group `session`) → `SessionsResponse` (`{ data: SessionV2Info[], cursor }`), same `SessionStore` with `limit`/`order`/`search`/`project`/`workspace`/`directory` filters. Contract-enforced (`/api/session`); the 400 union (`anyOf[InvalidCursorError, InvalidRequestError]`) reuses the dedup-collapsing normalizer.
81+
- ✅ **Keyset cursor pagination** (PR #20): `v2.session.list` now returns real `previous`/`next` cursors and follows an inbound `cursor`. Faithful TS keyset semantics (`session.ts`): anchor `(time_created, id)`, order-flip + result-reverse for `previous`, default limit 50; an undecodable cursor → 400 `InvalidCursorError`. The cursor token is a Rust-native `base64url(JSON)` (opaque per the contract; not byte-interchangeable with TS cursors across a mid-pagination rollback — documented). Added the `base64` crate.
8182
- ⬜ Channels (`watch`/`async-broadcast`), SSE `/event`
8283
- ⬜ Cutover: `agent`, `project`, `project-copy`, `credential`, `model`, `provider`, then `event`
8384

‎crates/opencode-db/src/lib.rs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ pub use opencode_events::{EventInput, StoredEvent};
2424

2525
pub use migration::{MigrationReport, EXPECTED_MIGRATIONS};
2626
pub use session::{
27-
MemorySessionStore, SessionContextEpoch, SessionContextEpochRepo, SessionInput,
28-
SessionInputRepo, SessionListQuery, SessionRecord, SessionStore, SqlxSessionStore,
29-
SESSION_CONTEXT_EPOCH_DDL, SESSION_INPUT_DDL,
27+
ListAnchor, ListDirection, MemorySessionStore, SessionContextEpoch, SessionContextEpochRepo,
28+
SessionInput, SessionInputRepo, SessionListQuery, SessionRecord, SessionStore,
29+
SqlxSessionStore, SESSION_CONTEXT_EPOCH_DDL, SESSION_INPUT_DDL,
3030
};
3131

3232
/// Database / event-store errors.

‎crates/opencode-db/src/session.rs‎

Lines changed: 215 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -276,20 +276,68 @@ const SESSION_RECORD_COLS: &str = "id, project_id, parent_id, agent, model, cost
276276
tokens_output, tokens_reasoning, tokens_cache_read, tokens_cache_write, title, directory, \
277277
workspace_id, path, time_created, time_updated, time_archived";
278278

279+
/// Pagination direction within a keyset cursor.
280+
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
281+
#[serde(rename_all = "lowercase")]
282+
pub enum ListDirection {
283+
/// The page after the anchor (default).
284+
#[default]
285+
Next,
286+
/// The page before the anchor.
287+
Previous,
288+
}
289+
290+
/// A keyset pagination anchor: the `(time_created, id)` position to page from, plus the direction.
291+
/// Mirrors the TS `ListAnchor` (`session.ts`).
292+
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
293+
pub struct ListAnchor {
294+
/// Anchor session id (the `id` tiebreaker).
295+
pub id: String,
296+
/// Anchor `time_created` (ms).
297+
pub time: i64,
298+
/// Page before or after the anchor.
299+
pub direction: ListDirection,
300+
}
301+
279302
/// Filters/ordering for [`SessionStore::list`]. All filters are optional (`None` = no filter).
280303
#[derive(Debug, Clone, Default)]
281304
pub struct SessionListQuery {
282305
/// Max rows to return (`None` = no limit).
283306
pub limit: Option<i64>,
284307
/// Order by `time_created` (then `id`) descending — most-recent first — when `true`; ascending
285-
/// otherwise.
308+
/// otherwise. (The requested order; for a `Previous` anchor the query is flipped internally.)
286309
pub descending: bool,
287310
/// ASCII-case-insensitive substring match on `title`.
288311
pub search: Option<String>,
289312
/// Restrict to a project id.
290313
pub project: Option<String>,
291314
/// Restrict to a workspace id.
292315
pub workspace: Option<String>,
316+
/// Restrict to a directory.
317+
pub directory: Option<String>,
318+
/// Keyset anchor for cursor pagination (`None` = first page).
319+
pub anchor: Option<ListAnchor>,
320+
}
321+
322+
impl SessionListQuery {
323+
/// Whether this query pages *before* its anchor.
324+
fn is_previous(&self) -> bool {
325+
matches!(
326+
self.anchor.as_ref().map(|a| a.direction),
327+
Some(ListDirection::Previous)
328+
)
329+
}
330+
331+
/// The effective sort order applied to the SQL/in-memory query: a `Previous` anchor flips the
332+
/// requested order (then results are reversed back), so the page is the rows immediately before
333+
/// the anchor in the requested order.
334+
fn effective_descending(&self) -> bool {
335+
if self.is_previous() {
336+
!self.descending
337+
} else {
338+
self.descending
339+
}
340+
}
293341
}
294342

295343
/// Read-only store over the `session` projection table.
@@ -357,9 +405,13 @@ impl SessionStore for SqlxSessionStore {
357405
}
358406

359407
async fn list(&self, query: &SessionListQuery) -> Result<Vec<SessionRecord>, DbError> {
408+
let descending = query.effective_descending();
360409
// Build the filter clause dynamically, then bind in the same order.
361410
let mut sql = format!("SELECT {SESSION_RECORD_COLS} FROM session");
362411
let mut conds: Vec<&str> = Vec::new();
412+
if query.directory.is_some() {
413+
conds.push("directory = ?");
414+
}
363415
if query.project.is_some() {
364416
conds.push("project_id = ?");
365417
}
@@ -369,11 +421,19 @@ impl SessionStore for SqlxSessionStore {
369421
if query.search.is_some() {
370422
conds.push("title LIKE ?");
371423
}
424+
if query.anchor.is_some() {
425+
// Keyset boundary on `(time_created, id)` relative to the anchor.
426+
conds.push(if descending {
427+
"(time_created < ? OR (time_created = ? AND id < ?))"
428+
} else {
429+
"(time_created > ? OR (time_created = ? AND id > ?))"
430+
});
431+
}
372432
if !conds.is_empty() {
373433
sql.push_str(" WHERE ");
374434
sql.push_str(&conds.join(" AND "));
375435
}
376-
sql.push_str(if query.descending {
436+
sql.push_str(if descending {
377437
" ORDER BY time_created DESC, id DESC"
378438
} else {
379439
" ORDER BY time_created ASC, id ASC"
@@ -383,6 +443,9 @@ impl SessionStore for SqlxSessionStore {
383443
}
384444

385445
let mut q = sqlx::query(&sql);
446+
if let Some(d) = &query.directory {
447+
q = q.bind(d);
448+
}
386449
if let Some(p) = &query.project {
387450
q = q.bind(p);
388451
}
@@ -392,12 +455,20 @@ impl SessionStore for SqlxSessionStore {
392455
if let Some(s) = &query.search {
393456
q = q.bind(format!("%{s}%"));
394457
}
458+
if let Some(a) = &query.anchor {
459+
q = q.bind(a.time).bind(a.time).bind(&a.id);
460+
}
395461
if let Some(l) = query.limit {
396462
q = q.bind(l);
397463
}
398464

399465
let rows = q.fetch_all(&self.pool).await?;
400-
rows.iter().map(record_from_row).collect()
466+
let mut records: Vec<SessionRecord> =
467+
rows.iter().map(record_from_row).collect::<Result<_, _>>()?;
468+
if query.is_previous() {
469+
records.reverse();
470+
}
471+
Ok(records)
401472
}
402473
}
403474

@@ -434,12 +505,14 @@ impl SessionStore for MemorySessionStore {
434505
}
435506

436507
async fn list(&self, query: &SessionListQuery) -> Result<Vec<SessionRecord>, DbError> {
508+
let descending = query.effective_descending();
437509
let search = query.search.as_ref().map(|s| s.to_lowercase());
438510
let mut rows: Vec<SessionRecord> = self
439511
.rows
440512
.lock()
441513
.expect("session store mutex poisoned")
442514
.values()
515+
.filter(|r| query.directory.as_ref().is_none_or(|d| &r.directory == d))
443516
.filter(|r| query.project.as_ref().is_none_or(|p| &r.project_id == p))
444517
.filter(|r| {
445518
query
@@ -454,13 +527,26 @@ impl SessionStore for MemorySessionStore {
454527
})
455528
.cloned()
456529
.collect();
530+
// Keyset boundary relative to the anchor, in the effective order.
531+
if let Some(a) = &query.anchor {
532+
rows.retain(|r| {
533+
if descending {
534+
(r.time_created, r.id.as_str()) < (a.time, a.id.as_str())
535+
} else {
536+
(r.time_created, r.id.as_str()) > (a.time, a.id.as_str())
537+
}
538+
});
539+
}
457540
rows.sort_by(|a, b| (a.time_created, &a.id).cmp(&(b.time_created, &b.id)));
458-
if query.descending {
541+
if descending {
459542
rows.reverse();
460543
}
461544
if let Some(limit) = query.limit {
462545
rows.truncate(limit.max(0) as usize);
463546
}
547+
if query.is_previous() {
548+
rows.reverse();
549+
}
464550
Ok(rows)
465551
}
466552
}
@@ -778,4 +864,129 @@ mod tests {
778864
};
779865
assert_eq!(ids(store.list(&search).await.unwrap()), ["ses_a", "ses_c"]);
780866
}
867+
868+
#[tokio::test]
869+
async fn sqlx_session_store_keyset_pagination() {
870+
let dir = tempfile::tempdir().unwrap();
871+
let db = Database::connect(dir.path().join("sessions.db"))
872+
.await
873+
.unwrap();
874+
sqlx::query(SESSION_PROJECTION_DDL)
875+
.execute(db.pool())
876+
.await
877+
.unwrap();
878+
for i in 1..=5 {
879+
sqlx::query(
880+
"INSERT INTO session (id, project_id, title, directory, time_created, time_updated) \
881+
VALUES (?, 'prj_1', 'S', '/r', ?, ?)",
882+
)
883+
.bind(format!("ses_{i}"))
884+
.bind(i * 100)
885+
.bind(i * 100)
886+
.execute(db.pool())
887+
.await
888+
.unwrap();
889+
}
890+
let store = SqlxSessionStore::new(db.pool().clone());
891+
let ids = |rs: &[SessionRecord]| rs.iter().map(|r| r.id.clone()).collect::<Vec<_>>();
892+
893+
// Page 1: newest first, two per page.
894+
let page1 = store
895+
.list(&SessionListQuery {
896+
descending: true,
897+
limit: Some(2),
898+
..Default::default()
899+
})
900+
.await
901+
.unwrap();
902+
assert_eq!(ids(&page1), ["ses_5", "ses_4"]);
903+
904+
// Page 2: anchored "next" from the last row of page 1.
905+
let last = page1.last().unwrap();
906+
let page2 = store
907+
.list(&SessionListQuery {
908+
descending: true,
909+
limit: Some(2),
910+
anchor: Some(ListAnchor {
911+
id: last.id.clone(),
912+
time: last.time_created,
913+
direction: ListDirection::Next,
914+
}),
915+
..Default::default()
916+
})
917+
.await
918+
.unwrap();
919+
assert_eq!(ids(&page2), ["ses_3", "ses_2"]);
920+
921+
// "previous" from the first row of page 2 returns page 1's rows in the requested (desc) order.
922+
let first2 = page2.first().unwrap();
923+
let prev = store
924+
.list(&SessionListQuery {
925+
descending: true,
926+
limit: Some(2),
927+
anchor: Some(ListAnchor {
928+
id: first2.id.clone(),
929+
time: first2.time_created,
930+
direction: ListDirection::Previous,
931+
}),
932+
..Default::default()
933+
})
934+
.await
935+
.unwrap();
936+
assert_eq!(ids(&prev), ["ses_5", "ses_4"]);
937+
}
938+
939+
#[tokio::test]
940+
async fn memory_session_store_keyset_matches_sqlx() {
941+
let store = MemorySessionStore::new();
942+
for i in 1..=5 {
943+
let mut r = SessionRecord {
944+
id: format!("ses_{i}"),
945+
project_id: "prj_1".into(),
946+
parent_id: None,
947+
agent: None,
948+
model: None,
949+
cost: 0.0,
950+
tokens_input: 0,
951+
tokens_output: 0,
952+
tokens_reasoning: 0,
953+
tokens_cache_read: 0,
954+
tokens_cache_write: 0,
955+
title: "S".into(),
956+
directory: "/r".into(),
957+
workspace_id: None,
958+
path: None,
959+
time_created: 0,
960+
time_updated: 0,
961+
time_archived: None,
962+
};
963+
r.time_created = i * 100;
964+
store.insert(r);
965+
}
966+
let ids = |rs: &[SessionRecord]| rs.iter().map(|r| r.id.clone()).collect::<Vec<_>>();
967+
let page1 = store
968+
.list(&SessionListQuery {
969+
descending: true,
970+
limit: Some(2),
971+
..Default::default()
972+
})
973+
.await
974+
.unwrap();
975+
assert_eq!(ids(&page1), ["ses_5", "ses_4"]);
976+
let last = page1.last().unwrap();
977+
let page2 = store
978+
.list(&SessionListQuery {
979+
descending: true,
980+
limit: Some(2),
981+
anchor: Some(ListAnchor {
982+
id: last.id.clone(),
983+
time: last.time_created,
984+
direction: ListDirection::Next,
985+
}),
986+
..Default::default()
987+
})
988+
.await
989+
.unwrap();
990+
assert_eq!(ids(&page2), ["ses_3", "ses_2"]);
991+
}
781992
}

‎crates/opencode-server/Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ tower-http.workspace = true
1919
reqwest.workspace = true
2020
serde.workspace = true
2121
serde_json.workspace = true
22+
base64.workspace = true
2223
utoipa.workspace = true
2324
tracing.workspace = true
2425
anyhow.workspace = true

0 commit comments

Comments
 (0)