1use std::path::PathBuf;
7use std::sync::atomic::{AtomicUsize, Ordering};
8use std::sync::{Arc, Mutex, MutexGuard};
9use std::time::Duration;
10
11use axum::Json;
12use axum::body::{Body, Bytes};
13use axum::extract::{Request, State};
14use axum::http::request::Parts;
15use axum::http::{HeaderValue, Method, StatusCode, header};
16use axum::middleware::Next;
17use axum::response::{IntoResponse, Response};
18use second_brain_core::redact::redact;
19use serde_json::{Value, json};
20use tokio::sync::Notify;
21
22use crate::AppState;
23use crate::write_queue::{self, Entry};
24
25pub const REPLAY_HEADER: &str = "x-second-brain-replay";
27pub const QUEUED_REASON: &str = "store maintenance is running; the write is saved when it finishes";
28const RETRY_AFTER_SECS: u64 = 300;
29const MAX_QUEUED_BODY: usize = 8 * 1024 * 1024;
30
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32enum Mode {
33 Open,
34 Closed,
35 Draining,
37}
38
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40enum Class {
41 Read,
42 Queueable(&'static str),
44 Refused,
46}
47
48pub struct WriteGate {
49 queue_dir: Option<PathBuf>,
50 mode: Mutex<Mode>,
51 in_flight: AtomicUsize,
52 maintenance: Mutex<()>,
53 reopened: Notify,
54}
55
56impl Default for WriteGate {
57 fn default() -> Self {
58 Self::with_queue(None)
59 }
60}
61
62pub struct WriteSlot<'a>(&'a WriteGate);
63
64impl Drop for WriteSlot<'_> {
65 fn drop(&mut self) {
66 self.0.in_flight.fetch_sub(1, Ordering::SeqCst);
67 }
68}
69
70pub struct Closed<'a> {
73 gate: &'a WriteGate,
74 _serial: MutexGuard<'a, ()>,
75}
76
77impl Drop for Closed<'_> {
78 fn drop(&mut self) {
79 *self.gate.mode() = Mode::Draining;
80 self.gate.reopened.notify_one();
81 }
82}
83
84enum Admission<'a> {
85 Live(WriteSlot<'a>),
86 Queue,
87 Busy,
88}
89
90impl WriteGate {
91 pub fn new(queue_dir: PathBuf) -> Self {
92 Self::with_queue(Some(queue_dir))
93 }
94
95 fn with_queue(queue_dir: Option<PathBuf>) -> Self {
96 Self {
97 queue_dir,
98 mode: Mutex::new(Mode::Open),
99 in_flight: AtomicUsize::new(0),
100 maintenance: Mutex::new(()),
101 reopened: Notify::new(),
102 }
103 }
104
105 pub fn is_closed(&self) -> bool {
106 *self.mode() == Mode::Closed
107 }
108
109 pub fn try_enter(&self) -> Option<WriteSlot<'_>> {
112 match self.admit(Class::Refused, true) {
113 Admission::Live(slot) => Some(slot),
114 Admission::Queue | Admission::Busy => None,
115 }
116 }
117
118 pub fn close(&self) -> Closed<'_> {
121 let serial = match self.maintenance.lock() {
122 Ok(g) => g,
123 Err(poisoned) => poisoned.into_inner(),
124 };
125 *self.mode() = Mode::Closed;
126 while self.in_flight.load(Ordering::SeqCst) > 0 {
127 std::thread::sleep(Duration::from_millis(20));
128 }
129 Closed {
130 gate: self,
131 _serial: serial,
132 }
133 }
134
135 pub async fn reopened(&self) {
137 self.reopened.notified().await;
138 }
139
140 pub fn open_when_drained(&self, queue_empty: impl FnOnce() -> bool) {
143 let mut mode = self.mode();
144 if *mode == Mode::Draining && queue_empty() {
145 *mode = Mode::Open;
146 }
147 }
148
149 fn admit(&self, class: Class, replay: bool) -> Admission<'_> {
150 let mode = self.mode();
151 let admission = match (*mode, class) {
152 (Mode::Open, _) => Admission::Live(WriteSlot(self)),
153 (Mode::Closed, Class::Queueable(_)) if !replay => Admission::Queue,
154 (Mode::Closed, _) => Admission::Busy,
155 (Mode::Draining, Class::Queueable(_)) if !replay => Admission::Queue,
156 (Mode::Draining, _) => Admission::Live(WriteSlot(self)),
157 };
158 if matches!(admission, Admission::Live(_)) {
159 self.in_flight.fetch_add(1, Ordering::SeqCst);
160 }
161 admission
162 }
163
164 fn enqueue(&self, entry: &Entry) -> anyhow::Result<bool> {
166 let mode = self.mode();
167 if *mode == Mode::Open {
168 return Ok(false);
169 }
170 let Some(dir) = &self.queue_dir else {
171 anyhow::bail!("this daemon has no write queue");
172 };
173 write_queue::push(dir, entry)?;
174 Ok(true)
175 }
176
177 fn mode(&self) -> MutexGuard<'_, Mode> {
178 match self.mode.lock() {
179 Ok(g) => g,
180 Err(poisoned) => poisoned.into_inner(),
181 }
182 }
183}
184
185fn classify(method: &Method, path: &str) -> Class {
188 if method == Method::GET || method == Method::HEAD {
189 return Class::Read;
190 }
191 match (method.as_str(), path) {
192 (
193 "POST",
194 "/v1/recall"
195 | "/v1/context"
196 | "/v1/daily/memories"
197 | "/v1/sync/export"
198 | "/v1/maintenance/vacuum",
199 ) => Class::Read,
200 ("POST", "/v1/remember") => Class::Queueable("remember"),
201 ("POST", "/v1/associate") => Class::Queueable("associate"),
202 ("POST", "/v1/ingest") => Class::Queueable("ingest"),
203 ("DELETE", p) if p.starts_with("/v1/memory/") => Class::Queueable("forget"),
204 _ => Class::Refused,
205 }
206}
207
208pub async fn hold_writes(State(state): State<Arc<AppState>>, req: Request, next: Next) -> Response {
209 let class = classify(req.method(), req.uri().path());
210 if class == Class::Read {
211 return next.run(req).await;
212 }
213 let replay = req.headers().contains_key(REPLAY_HEADER);
214 let mut req = req;
215 loop {
216 match state.gate.admit(class, replay) {
217 Admission::Live(slot) => {
218 let response = next.run(req).await;
219 drop(slot);
220 return response;
221 }
222 Admission::Busy => return busy(),
223 Admission::Queue => {}
224 }
225 let Class::Queueable(tool) = class else {
226 return busy();
227 };
228 let (parts, body) = req.into_parts();
229 let bytes = match axum::body::to_bytes(body, MAX_QUEUED_BODY).await {
230 Ok(b) => b,
231 Err(e) => return error(StatusCode::PAYLOAD_TOO_LARGE, &format!("{e}")),
232 };
233 let entry = match queued_entry(tool, &parts, &bytes) {
234 Ok(entry) => entry,
235 Err(e) => return error(StatusCode::BAD_REQUEST, &e),
236 };
237 let saved = {
238 let (state, entry) = (state.clone(), entry.clone());
239 tokio::task::spawn_blocking(move || state.gate.enqueue(&entry)).await
240 };
241 match saved {
242 Ok(Ok(true)) => return queued(&entry),
243 Ok(Ok(false)) => req = Request::from_parts(parts, Body::from(bytes)),
244 Ok(Err(e)) => {
245 tracing::warn!("cannot queue a {tool} during store maintenance: {e:#}");
246 return busy();
247 }
248 Err(e) => {
249 tracing::warn!("queueing a {tool} during store maintenance failed: {e}");
250 return busy();
251 }
252 }
253 }
254}
255
256fn queued_entry(tool: &str, parts: &Parts, bytes: &Bytes) -> Result<Entry, String> {
260 let mut body: Option<Value> = if bytes.is_empty() {
261 None
262 } else {
263 Some(serde_json::from_slice(bytes).map_err(|e| format!("invalid JSON body: {e}"))?)
264 };
265 if tool == "remember" {
266 let Some(Value::Object(fields)) = body.as_mut() else {
267 return Err("a remember needs a JSON object body".to_string());
268 };
269 if !fields.get("id").is_some_and(Value::is_string) {
270 fields.insert(
271 "id".to_string(),
272 Value::String(uuid::Uuid::new_v4().to_string()),
273 );
274 }
275 }
276 if let Some(body) = body.as_mut() {
277 redact_strings(body);
278 }
279 Ok(Entry {
280 tool: tool.to_string(),
281 method: parts.method.to_string(),
282 path: parts.uri.path().to_string(),
283 query: parts.uri.query().map(redact_query),
284 body,
285 })
286}
287
288fn redact_strings(value: &mut Value) {
289 match value {
290 Value::String(s) => *s = redact(s).text,
291 Value::Array(items) => items.iter_mut().for_each(redact_strings),
292 Value::Object(fields) => fields.values_mut().for_each(redact_strings),
293 _ => {}
294 }
295}
296
297fn redact_query(query: &str) -> String {
298 let Ok(mut url) = reqwest::Url::parse(&format!("http://queue/?{query}")) else {
299 return redact(query).text;
300 };
301 let pairs: Vec<(String, String)> = url
302 .query_pairs()
303 .map(|(k, v)| (k.into_owned(), redact(&v).text))
304 .collect();
305 url.query_pairs_mut().clear().extend_pairs(pairs);
306 url.query().unwrap_or_default().to_string()
307}
308
309fn queued(entry: &Entry) -> Response {
310 let mut reply = json!({ "queued": true, "reason": QUEUED_REASON });
311 if entry.tool == "remember"
312 && let Some(id) = entry.body.as_ref().and_then(|b| b["id"].as_str())
313 {
314 reply["id"] = Value::String(id.to_string());
315 }
316 (StatusCode::ACCEPTED, Json(reply)).into_response()
317}
318
319fn busy() -> Response {
320 let mut response = error(
321 StatusCode::SERVICE_UNAVAILABLE,
322 "store maintenance is running; retry later",
323 );
324 response
325 .headers_mut()
326 .insert(header::RETRY_AFTER, HeaderValue::from(RETRY_AFTER_SECS));
327 response
328}
329
330fn error(status: StatusCode, message: &str) -> Response {
331 (status, Json(json!({ "error": message }))).into_response()
332}
333
334#[cfg(test)]
335mod tests {
336 use super::*;
337
338 #[test]
339 fn writes_are_told_apart_from_reads() {
340 let post = Method::POST;
341 assert_eq!(classify(&Method::GET, "/v1/redaction"), Class::Read);
342 assert_eq!(classify(&post, "/v1/recall"), Class::Read);
343 assert_eq!(classify(&post, "/v1/maintenance/vacuum"), Class::Read);
344 assert_eq!(
345 classify(&post, "/v1/remember"),
346 Class::Queueable("remember")
347 );
348 assert_eq!(
349 classify(&Method::DELETE, "/v1/memory/x"),
350 Class::Queueable("forget")
351 );
352 assert_eq!(classify(&post, "/v1/sync/import"), Class::Refused);
353 assert_eq!(classify(&post, "/v1/some-new-route"), Class::Refused);
354 }
355
356 #[test]
357 fn a_queued_write_holds_no_secret() {
358 let token = ["gh", "p_"].concat() + "Qq7k3Jd9XwL2pVb8NzR4tYc6MhF1sGa5UeT0";
359 let remember = axum::http::Request::builder()
360 .method("POST")
361 .uri("/v1/remember")
362 .body(())
363 .unwrap()
364 .into_parts()
365 .0;
366 let body = json!({"content": format!("deploy with {token}"), "tags": [token.clone()]});
367 let entry = queued_entry("remember", &remember, &Bytes::from(body.to_string())).unwrap();
368 let forget = axum::http::Request::builder()
369 .method("DELETE")
370 .uri(format!("/v1/memory/x?hard=false&reason=leaked%20{token}"))
371 .body(())
372 .unwrap()
373 .into_parts()
374 .0;
375 let forget = queued_entry("forget", &forget, &Bytes::new()).unwrap();
376 let saved =
377 serde_json::to_string(&entry).unwrap() + &serde_json::to_string(&forget).unwrap();
378 assert!(!saved.contains(&token), "{saved}");
379 assert!(saved.contains("[REDACTED:github_token]"));
380 assert!(entry.body.unwrap()["id"].is_string());
381 assert!(forget.query.unwrap().starts_with("hard=false&reason="));
382 }
383
384 #[test]
385 fn closing_waits_for_writes_in_flight() {
386 let gate = Arc::new(WriteGate::default());
387 let slot_gate = gate.clone();
388 let (entered, wait) = std::sync::mpsc::channel();
389 let writer = std::thread::spawn(move || {
390 let _slot = slot_gate.try_enter().unwrap();
391 entered.send(()).unwrap();
392 std::thread::sleep(Duration::from_millis(200));
393 });
394 wait.recv().unwrap();
395 let started = std::time::Instant::now();
396 let closed = gate.close();
397 assert!(started.elapsed() >= Duration::from_millis(100));
398 assert!(gate.try_enter().is_none());
399 writer.join().unwrap();
400 drop(closed);
401 assert!(gate.try_enter().is_some());
402 }
403
404 #[test]
405 fn after_maintenance_writes_queue_until_the_queue_drains() {
406 let gate = WriteGate::default();
407 drop(gate.close());
408 assert!(matches!(
409 gate.admit(Class::Queueable("remember"), false),
410 Admission::Queue
411 ));
412 assert!(matches!(
413 gate.admit(Class::Queueable("remember"), true),
414 Admission::Live(_)
415 ));
416 gate.open_when_drained(|| false);
417 assert!(matches!(
418 gate.admit(Class::Queueable("remember"), false),
419 Admission::Queue
420 ));
421 gate.open_when_drained(|| true);
422 assert!(matches!(
423 gate.admit(Class::Queueable("remember"), false),
424 Admission::Live(_)
425 ));
426 }
427}