feat(kanban): recover from missing sync history

req: sync/007\nreq: sync/020

examples/kanban/src/main.rs

@@ -40,6 +40,7 @@ struct SyncStore(PathBuf);
 struct SyncState {
     next_sequence: u64,
     acknowledgements: BTreeMap<CommandId, SyncAcknowledgement>,
+    retained_after: u64,
     reconnects: BTreeMap<String, u64>,
     transient_failure_limit: u8,
     transient_failures: BTreeMap<CommandId, u8>,
@@ -76,6 +77,21 @@ struct SyncAcknowledgement {
     status: &'static str,
 }
 
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SyncSnapshot {
+    schema_version: u8,
+    server_sequence: u64,
+    cards: Vec<SnapshotCard>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SnapshotCard {
+    id: u64,
+    column: &'static str,
+}
+
 #[derive(Debug)]
 enum SyncRejection {
     BadRequest(&'static str),
@@ -294,6 +310,10 @@ async fn main() {
             next_sequence: 1,
             ..SyncState::default()
         });
+    sync.retained_after = std::env::var("HEMX_KANBAN_RETAINED_AFTER")
+        .ok()
+        .and_then(|value| value.parse::<u64>().ok())
+        .unwrap_or_default();
     sync.transient_failure_limit = std::env::var("HEMX_KANBAN_SYNC_FAILURES")
         .ok()
         .and_then(|value| value.parse::<u8>().ok())
@@ -321,6 +341,7 @@ async fn main() {
         .route("/sync.js", get(sync_js))
         .route("/sync/commands", post(sync_command))
         .route("/sync/acknowledgements", get(sync_acknowledgements))
+        .route("/sync/snapshot", get(sync_snapshot))
         .route(runtime_js_path(), get(runtime))
         .with_state(state);
 
@@ -474,6 +495,32 @@ async fn sync_command(
     Ok(Json(acknowledgement))
 }
 
+// req: sync/007 req: sync/020
+async fn sync_snapshot(State(state): State<Arc<AppState>>) -> Json<SyncSnapshot> {
+    let board = state.board.lock().unwrap();
+    let sync = state.sync.lock().unwrap();
+    let cards = board
+        .cards
+        .iter()
+        .map(|card| SnapshotCard {
+            id: card.id,
+            column: column_name(card.column),
+        })
+        .collect();
+    Json(SyncSnapshot {
+        schema_version: 1,
+        server_sequence: sync.next_sequence.saturating_sub(1),
+        cards,
+    })
+}
+
+fn column_name(column: usize) -> &'static str {
+    ["todo", "doing", "done"]
+        .get(column)
+        .copied()
+        .unwrap_or("todo")
+}
+
 // req: sync/005 req: sync/006 req: sync/007 req: sync/013
 async fn sync_acknowledgements(
     State(state): State<Arc<AppState>>,
@@ -502,18 +549,42 @@ async fn sync_acknowledgements(
             .keep_alive(KeepAlive::default());
         }
     }
-    let events = sync
+    let first_available = sync
         .acknowledgements
         .values()
-        .filter(|acknowledgement| acknowledgement.server_sequence > after)
-        .map(|acknowledgement| {
-            Ok(Event::default()
-                .id(acknowledgement.server_sequence.to_string())
-                .event("acknowledgement")
-                .json_data(acknowledgement)
-                .expect("serializable acknowledgement"))
-        })
-        .collect::<Vec<Result<Event, Infallible>>>();
+        .filter(|acknowledgement| acknowledgement.server_sequence > sync.retained_after)
+        .map(|acknowledgement| acknowledgement.server_sequence)
+        .min();
+    let latest = sync.next_sequence.saturating_sub(1);
+    let history_missing = after < latest
+        && first_available.is_none_or(|first_sequence| after.saturating_add(1) < first_sequence);
+    let events = if history_missing {
+        vec![Ok(Event::default()
+            .id(latest.to_string())
+            .event("snapshot-required")
+            .json_data(serde_json::json!({
+                "after": after,
+                "firstAvailable": first_available,
+                "latest": latest,
+                "snapshotUrl": "/sync/snapshot",
+            }))
+            .expect("serializable missing history event"))]
+    } else {
+        sync.acknowledgements
+            .values()
+            .filter(|acknowledgement| {
+                acknowledgement.server_sequence > after
+                    && acknowledgement.server_sequence > sync.retained_after
+            })
+            .map(|acknowledgement| {
+                Ok(Event::default()
+                    .id(acknowledgement.server_sequence.to_string())
+                    .event("acknowledgement")
+                    .json_data(acknowledgement)
+                    .expect("serializable acknowledgement"))
+            })
+            .collect::<Vec<Result<Event, Infallible>>>()
+    };
     Sse::new(stream::iter(events).boxed()).keep_alive(KeepAlive::default())
 }