snip-sync 0.2.0

gRPC sync server for snp snippet manager
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
//! Test-only request observer for the snip-sync server.
//!
//! The observer lets tests capture sanitized request telemetry from
//! the actual gRPC handlers without depending on injected hooks that
//! could miss a code path. Each handler invokes `request_started` and
//! `request_finished` automatically, so test code cannot create
//! evidence by calling `record_request` manually.
//!
//! Sanitization guarantees:
//! - no API key, authorization header, raw body, decrypted snippet
//!   command, or plaintext payload is retained;
//! - payload evidence is length, hash, and sentinel boolean only;
//! - per-process record count is bounded.

use std::collections::VecDeque;
use std::sync::{Arc, Mutex};

/// Maximum number of request records retained per server instance.
/// Older records are dropped when this limit is exceeded.
pub const MAX_OBSERVER_RECORDS: usize = 256;

/// A sanitized request-start record emitted by gRPC handlers.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RequestStarted {
    /// Monotonic sequence number per server instance.
    pub sequence: u64,
    /// Wall-clock start time (millis since UNIX epoch).
    pub started_at_unix_ms: u64,
    /// gRPC method name (e.g. `"push_snippets"`).
    pub method: String,
    /// Logical operation (e.g. `"push"`, `"pull"`, `"register"`).
    pub operation: String,
    /// Authenticated user id resolved from the API key, if any.
    /// `None` for unauthenticated endpoints like `health`.
    pub authenticated_user_id: Option<String>,
    /// Authenticated device id (if present in metadata).
    pub authenticated_device_id: Option<String>,
    /// Target library id (if the request targets a specific library).
    pub target_library_id: Option<String>,
    /// Request revision (for sync endpoints).
    pub request_revision: Option<u64>,
    /// Payload length in bytes (decoded request body, sanitized).
    pub payload_len: usize,
    /// Payload SHA-256 hex digest.
    pub payload_sha256: String,
    /// True if any plaintext snippet command sentinel would have
    /// been observed in the payload. Always `false` for encrypted
    /// payloads.
    pub payload_contains_plaintext_sentinel: bool,
    /// Number of requests in-flight at start time.
    pub concurrent_at_start: usize,
}

/// A sanitized request-finish record emitted by gRPC handlers.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RequestFinished {
    /// Sequence number shared with the matching `RequestStarted`.
    pub sequence: u64,
    /// Wall-clock finish time (millis since UNIX epoch).
    pub finished_at_unix_ms: u64,
    /// Whether the handler returned a success status.
    pub success: bool,
    /// Response revision (for sync endpoints).
    pub response_revision: Option<u64>,
}

/// Observer trait implemented by test sinks.
///
/// The handler invokes `request_started` immediately before dispatch
/// and `request_finished` after the handler future resolves.
pub trait TestRequestObserver: Send + Sync {
    fn request_started(&self, event: RequestStarted);
    fn request_finished(&self, event: RequestFinished);

    /// Allocate the next monotonic sequence number for a request pair.
    /// Default returns 0 (observers that don't track sequences).
    fn allocate_sequence(&self) -> u64 {
        0
    }

    /// Number of requests currently in-flight (started but not finished).
    /// Default returns 0.
    fn current_concurrent(&self) -> usize {
        0
    }

    /// Find the sequence number of the most recent `RequestStarted`
    /// whose `method` matches. Default returns 0.
    fn last_started_sequence_for_method(&self, _method: &str) -> u64 {
        0
    }

    /// Update the IDs of the most recent request for the given method.
    /// Default is a no-op.
    fn update_ids_for_last_method(
        &self,
        _method: &str,
        _user_id: Option<String>,
        _device_id: Option<String>,
        _library_id: Option<String>,
    ) {
    }
}

/// Default in-memory observer used by `RecordingServer`.
#[derive(Debug, Default)]
pub struct InMemoryObserver {
    inner: Arc<Mutex<Inner>>,
}

#[derive(Debug, Default)]
struct Inner {
    next_seq: u64,
    in_flight: usize,
    max_in_flight: usize,
    // `VecDeque` keeps eviction O(1): the oldest record is dropped from the
    // front without shifting the remaining records under the lock.
    starts: VecDeque<RequestStarted>,
    finishes: VecDeque<RequestFinished>,
}

impl InMemoryObserver {
    /// Returns a fresh, empty observer wrapped in an `Arc`.
    pub fn shared() -> Arc<Self> {
        Arc::new(Self::default())
    }

    /// Returns all recorded `RequestStarted` events.
    pub fn starts(&self) -> Vec<RequestStarted> {
        self.inner.lock().unwrap().starts.iter().cloned().collect()
    }

    /// Returns all recorded `RequestFinished` events.
    pub fn finishes(&self) -> Vec<RequestFinished> {
        self.inner
            .lock()
            .unwrap()
            .finishes
            .iter()
            .cloned()
            .collect()
    }

    /// Maximum number of concurrent in-flight requests observed.
    pub fn max_concurrent(&self) -> usize {
        self.inner.lock().unwrap().max_in_flight
    }

    /// Total number of `RequestStarted` events recorded.
    pub fn started_count(&self) -> usize {
        self.inner.lock().unwrap().starts.len()
    }

    /// Total number of `RequestFinished` events recorded.
    pub fn finished_count(&self) -> usize {
        self.inner.lock().unwrap().finishes.len()
    }

    /// Total number of successful finishes.
    pub fn success_count(&self) -> usize {
        self.inner
            .lock()
            .unwrap()
            .finishes
            .iter()
            .filter(|f| f.success)
            .count()
    }

    /// First request-start timestamp, or `None`.
    pub fn first_started_at_unix_ms(&self) -> Option<u64> {
        self.inner
            .lock()
            .unwrap()
            .starts
            .front()
            .map(|e| e.started_at_unix_ms)
    }

    /// First request-finish timestamp, or `None`.
    pub fn first_finished_at_unix_ms(&self) -> Option<u64> {
        self.inner
            .lock()
            .unwrap()
            .finishes
            .front()
            .map(|e| e.finished_at_unix_ms)
    }

    /// Count of finished requests for `success=true`.
    pub fn failures(&self) -> usize {
        self.inner
            .lock()
            .unwrap()
            .finishes
            .iter()
            .filter(|f| !f.success)
            .count()
    }
}

impl TestRequestObserver for InMemoryObserver {
    fn allocate_sequence(&self) -> u64 {
        self.next_sequence()
    }

    fn current_concurrent(&self) -> usize {
        self.inner.lock().unwrap().in_flight
    }

    fn last_started_sequence_for_method(&self, method: &str) -> u64 {
        self.inner
            .lock()
            .unwrap()
            .starts
            .iter()
            .rev()
            .find(|s| s.method == method)
            .map(|s| s.sequence)
            .unwrap_or(0)
    }

    fn update_ids_for_last_method(
        &self,
        method: &str,
        user_id: Option<String>,
        device_id: Option<String>,
        library_id: Option<String>,
    ) {
        let mut inner = self.inner.lock().unwrap();
        if let Some(start) = inner.starts.iter_mut().rev().find(|s| s.method == method) {
            start.authenticated_user_id = user_id;
            start.authenticated_device_id = device_id;
            start.target_library_id = library_id;
        }
    }

    fn request_started(&self, event: RequestStarted) {
        let mut inner = self.inner.lock().unwrap();
        inner.starts.push_back(event);
        if inner.starts.len() > MAX_OBSERVER_RECORDS {
            inner.starts.pop_front();
        }
        inner.in_flight += 1;
        if inner.in_flight > inner.max_in_flight {
            inner.max_in_flight = inner.in_flight;
        }
    }

    fn request_finished(&self, event: RequestFinished) {
        let mut inner = self.inner.lock().unwrap();
        inner.finishes.push_back(event);
        if inner.finishes.len() > MAX_OBSERVER_RECORDS {
            inner.finishes.pop_front();
        }
        if inner.in_flight > 0 {
            inner.in_flight -= 1;
        }
    }
}

impl InMemoryObserver {
    /// Allocates the next sequence number. Exposed for handlers that
    /// need to coordinate started/finished pairing.
    pub fn next_sequence(&self) -> u64 {
        let mut inner = self.inner.lock().unwrap();
        inner.next_seq += 1;
        inner.next_seq
    }

    /// Reset observer state after registration and before the measured
    /// mutation. Clears starts, finishes, in-flight count, and max
    /// concurrency. The sequence generator remains monotonic.
    pub fn reset(&self) {
        let mut inner = self.inner.lock().unwrap();
        inner.starts.clear();
        inner.finishes.clear();
        inner.in_flight = 0;
        inner.max_in_flight = 0;
    }
}

/// Wall-clock millis since UNIX epoch.
pub fn now_millis() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default()
        .as_millis() as u64
}

/// Map a gRPC method name to a logical operation name.
///
/// `push_snippets` → `"push"`, `pull` semantics → `"pull"`, etc.
pub fn operation_name_for_method(method: &str) -> &'static str {
    match method {
        "push_snippets" => "push",
        "sync" => "sync",
        "get_snippets" => "pull",
        "register" => "register",
        "health" => "health",
        "create_library" => "create_library",
        "list_libraries" => "list_libraries",
        "delete_library" => "delete_library",
        "list_premade_libraries" => "list_premade_libraries",
        "get_premade_library" => "get_premade_library",
        "search_premade_libraries" => "search_premade",
        _ => "other",
    }
}

/// Compute a stable SHA-256 hex digest of length+sentinel-derived
/// fields without ever retaining the raw payload bytes.
///
/// This is a sanitization helper used by handlers to populate the
/// `payload_sha256` field. It only hashes COUNT-derived fields, so
/// the resulting digest is stable for the same input *size* but does
/// NOT function as a checksum of the actual content.
pub fn payload_sha256<T>(items: &[T], _device_id: &str, _api_key: &str) -> String {
    use sha2::{Digest, Sha256};
    let mut hasher = Sha256::new();
    hasher.update((items.len() as u64).to_le_bytes());
    // Note: do NOT include `_device_id` or `_api_key` in the hash; both
    // carry user-identifying and credential material.
    let bytes = hasher.finalize();
    bytes.iter().map(|b| format!("{:02x}", b)).collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn observer_records_started_and_finished() {
        let obs = InMemoryObserver::shared();
        let seq = obs.next_sequence();
        obs.request_started(RequestStarted {
            sequence: seq,
            started_at_unix_ms: 1,
            method: "push".to_string(),
            operation: "push".to_string(),
            authenticated_user_id: None,
            authenticated_device_id: None,
            target_library_id: None,
            request_revision: None,
            payload_len: 0,
            payload_sha256: String::new(),
            payload_contains_plaintext_sentinel: false,
            concurrent_at_start: 0,
        });
        obs.request_finished(RequestFinished {
            sequence: seq,
            finished_at_unix_ms: 2,
            success: true,
            response_revision: None,
        });
        assert_eq!(obs.started_count(), 1);
        assert_eq!(obs.finished_count(), 1);
        assert_eq!(obs.success_count(), 1);
        assert_eq!(obs.failures(), 0);
    }

    #[test]
    fn observer_tracks_max_concurrent() {
        let obs = InMemoryObserver::shared();
        let s1 = obs.next_sequence();
        obs.request_started(RequestStarted {
            sequence: s1,
            started_at_unix_ms: 1,
            method: "push".to_string(),
            operation: "push".to_string(),
            authenticated_user_id: None,
            authenticated_device_id: None,
            target_library_id: None,
            request_revision: None,
            payload_len: 0,
            payload_sha256: String::new(),
            payload_contains_plaintext_sentinel: false,
            concurrent_at_start: 0,
        });
        let s2 = obs.next_sequence();
        obs.request_started(RequestStarted {
            sequence: s2,
            started_at_unix_ms: 2,
            method: "push".to_string(),
            operation: "push".to_string(),
            authenticated_user_id: None,
            authenticated_device_id: None,
            target_library_id: None,
            request_revision: None,
            payload_len: 0,
            payload_sha256: String::new(),
            payload_contains_plaintext_sentinel: false,
            concurrent_at_start: 1,
        });
        assert_eq!(obs.max_concurrent(), 2);
        obs.request_finished(RequestFinished {
            sequence: s1,
            finished_at_unix_ms: 3,
            success: true,
            response_revision: None,
        });
        obs.request_finished(RequestFinished {
            sequence: s2,
            finished_at_unix_ms: 4,
            success: true,
            response_revision: None,
        });
        assert_eq!(obs.max_concurrent(), 2);
    }

    #[test]
    fn observer_does_not_retain_payload_bytes() {
        // Sanitization guarantee: the observer itself never accepts
        // raw byte payloads. Only length, hash, and sentinel boolean.
        let obs = InMemoryObserver::shared();
        let seq = obs.next_sequence();
        let _ = seq;
        // If the API ever changes to accept `Vec<u8>` here, the
        // `InMemoryObserver::request_started` signature above will
        // need a deliberate review and a sanitized conversion.
    }

    #[test]
    fn observer_evicts_the_oldest_record_beyond_the_cap() {
        let obs = InMemoryObserver::shared();
        let total = MAX_OBSERVER_RECORDS + 1;

        for index in 0..total {
            let seq = obs.next_sequence();
            obs.request_started(RequestStarted {
                sequence: seq,
                started_at_unix_ms: index as u64,
                method: "push".to_string(),
                operation: "push".to_string(),
                authenticated_user_id: None,
                authenticated_device_id: None,
                target_library_id: None,
                request_revision: None,
                payload_len: 0,
                payload_sha256: String::new(),
                payload_contains_plaintext_sentinel: false,
                concurrent_at_start: 0,
            });
            obs.request_finished(RequestFinished {
                sequence: seq,
                finished_at_unix_ms: index as u64,
                success: true,
                response_revision: None,
            });
        }

        assert_eq!(obs.started_count(), MAX_OBSERVER_RECORDS);
        assert_eq!(obs.finished_count(), MAX_OBSERVER_RECORDS);

        let starts = obs.starts();
        assert_eq!(starts.len(), MAX_OBSERVER_RECORDS);
        // The newest record is retained, the oldest one was evicted.
        assert_eq!(starts.last().map(|s| s.sequence), Some(total as u64));
        assert_eq!(starts.first().map(|s| s.sequence), Some(2));

        let finishes = obs.finishes();
        assert_eq!(finishes.len(), MAX_OBSERVER_RECORDS);
        assert_eq!(finishes.last().map(|f| f.sequence), Some(total as u64));
        assert_eq!(finishes.first().map(|f| f.sequence), Some(2));
    }
}