Add server-side cursor windows for large file spaces #22

New Issue

zemion · 2026-07-09T16:23:19+02:00

zemion commented

2026-07-09 16:23:19 +02:00

The files module already uses GET /api/v1/files/delta for full-space file/folder reloads, and the current WebUI organizes the result client-side. This is correct for small and medium spaces, but large document spaces will eventually need server-side windows and cursor-safe row deltas.

Scope:

Keep the existing full-space delta endpoint for compatibility.
Add optional server-side window parameters for file/folder lists when spaces become too large to materialize fully in the browser.
Use opaque keyset cursors for sorted windows, including owner, path prefix, campaign scope, sort, filter/search, and page size in the cursor fingerprint.
Return tombstones for files/folders leaving the active window when safe; otherwise fall back to a full window snapshot.
Update FilesPage and ManagedFileChooser only when the backend window endpoint exists and the UI switches away from full-space materialization.
Add tests for move/rename across path prefixes, folder delete tombstones, and cursor mismatch rejection.

Related platform work: govoplan-core#222.

The files module already uses `GET /api/v1/files/delta` for full-space file/folder reloads, and the current WebUI organizes the result client-side. This is correct for small and medium spaces, but large document spaces will eventually need server-side windows and cursor-safe row deltas. Scope: - Keep the existing full-space delta endpoint for compatibility. - Add optional server-side window parameters for file/folder lists when spaces become too large to materialize fully in the browser. - Use opaque keyset cursors for sorted windows, including owner, path prefix, campaign scope, sort, filter/search, and page size in the cursor fingerprint. - Return tombstones for files/folders leaving the active window when safe; otherwise fall back to a full window snapshot. - Update `FilesPage` and `ManagedFileChooser` only when the backend window endpoint exists and the UI switches away from full-space materialization. - Add tests for move/rename across path prefixes, folder delete tombstones, and cursor mismatch rejection. Related platform work: govoplan-core#222.

zemion commented

2026-07-09 17:06:25 +02:00

Partial implementation landed; keeping this open for the remaining UI/window-delta rollout.

Done now:

Added optional keyset cursor windows to GET /api/v1/files and GET /api/v1/files/folders while preserving existing full-list compatibility.
Cursor fingerprints include actor/tenant scope, owner/campaign/path inputs, fixed sort, and page size.
Added response cursor / next_cursor fields and WebUI/core capability types.
Added smoke coverage for file and folder cursor continuation and cursor mismatch rejection.

Still open:

Switch FilesPage / ManagedFileChooser away from full-space materialization where appropriate.
Add active-window tombstone/full-window fallback semantics on top of the windowed list contract when the UI starts using it for large spaces.

Verification: test_files_and_folders_support_cursor_windows passes.

Partial implementation landed; keeping this open for the remaining UI/window-delta rollout. Done now: - Added optional keyset cursor windows to `GET /api/v1/files` and `GET /api/v1/files/folders` while preserving existing full-list compatibility. - Cursor fingerprints include actor/tenant scope, owner/campaign/path inputs, fixed sort, and page size. - Added response `cursor` / `next_cursor` fields and WebUI/core capability types. - Added smoke coverage for file and folder cursor continuation and cursor mismatch rejection. Still open: - Switch `FilesPage` / `ManagedFileChooser` away from full-space materialization where appropriate. - Add active-window tombstone/full-window fallback semantics on top of the windowed list contract when the UI starts using it for large spaces. Verification: `test_files_and_folders_support_cursor_windows` passes.

zemion commented

2026-07-09 17:22:03 +02:00

Codex State: done

Summary

Backend file and folder list windows now expose a sequence watermark for large-space snapshot hydration.
FilesPage and ManagedFileChooser now use keyset-window snapshots followed by delta replay instead of first-loading full-space materialized deltas.
Active path-window tombstones are covered for move-out and recursive folder-delete cases.

Changed Files

src/govoplan_files/backend/router.py
src/govoplan_files/backend/schemas.py
webui/src/api/files.ts
webui/src/features/files/FilesPage.tsx
webui/src/features/files/components/ManagedFileChooser.tsx
tests/test_api_smoke.py

Verification

.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_files_delta_tracks_uploads_folders_and_delete_tombstones tests.test_api_smoke.ApiSmokeTests.test_files_and_folders_support_cursor_windows tests.test_api_smoke.ApiSmokeTests.test_files_delta_reports_active_window_tombstones_for_moves_and_folder_deletes
npm run build (govoplan-core/webui)

## Codex State: done ### Summary - Backend file and folder list windows now expose a sequence watermark for large-space snapshot hydration. - FilesPage and ManagedFileChooser now use keyset-window snapshots followed by delta replay instead of first-loading full-space materialized deltas. - Active path-window tombstones are covered for move-out and recursive folder-delete cases. ### Changed Files - `src/govoplan_files/backend/router.py` - `src/govoplan_files/backend/schemas.py` - `webui/src/api/files.ts` - `webui/src/features/files/FilesPage.tsx` - `webui/src/features/files/components/ManagedFileChooser.tsx` - `tests/test_api_smoke.py` ### Verification - `.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_files_delta_tracks_uploads_folders_and_delete_tombstones tests.test_api_smoke.ApiSmokeTests.test_files_and_folders_support_cursor_windows tests.test_api_smoke.ApiSmokeTests.test_files_delta_reports_active_window_tombstones_for_moves_and_folder_deletes` - `npm run build (govoplan-core/webui)`

zemion closed this issue

2026-07-09 17:22:06 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: add-ideas/govoplan-files#22