Skip to main content

coven_database/
claim.rs

1//! Durable identity and exact attempted bytes for one sequence claim (§5.1).
2
3use crate::internal_schema::WRITE_DEVICE_SQL;
4use crate::sqlite::StoreSql;
5use crate::{
6    write_encoding::{counter, damaged},
7    DbError, OperationId,
8};
9use coven_format::path::ObjectPath;
10use coven_foundation::id_source::DeviceId;
11use sqlive::rusqlite::params;
12use std::io::Read;
13
14/// The original work carried by a claim. Every slot kind shares one counter.
15#[derive(Clone, Debug, PartialEq, Eq)]
16pub enum ClaimWork {
17    /// The queued originals through this write number, inclusive.
18    Writes(u64),
19    /// An admin, key-copy or snapshot-announcement step of an operation.
20    Operation(OperationId),
21}
22
23/// A create-once request, persisted before the provider is called.
24pub struct ClaimAttempt<R> {
25    /// The exact path bound by the sealed envelope.
26    pub path: ObjectPath,
27    /// The complete sealed bytes, reused for an uncertain request.
28    pub bytes: R,
29}
30
31/// Settlement of the most recent attempt.
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub enum ClaimSettlement {
34    /// No authoritative read has settled the request.
35    Unknown,
36    /// The slot is still absent above the floor; resend its exact bytes.
37    Retry,
38    /// Other bytes occupy the slot, or the floor snapshot excludes this claim.
39    NotLanded,
40    /// Exact bytes or the floor snapshot establish publication.
41    Landed,
42    /// Authenticated claim evidence belongs to another copy of this device id.
43    DeviceIdInUse,
44}
45
46/// A claim retains every attempt, including attempts that lost contention.
47#[derive(Clone, Debug, PartialEq, Eq)]
48pub struct Claim {
49    /// The installation that reserved this number.
50    pub device: DeviceId,
51    /// One monotonically increasing number across every slot kind.
52    pub number: u64,
53    /// The queue batch or journal operation which owns it.
54    pub work: ClaimWork,
55    /// Attempts in their durable order; only the last can be outstanding.
56    pub attempts: Vec<ObjectPath>,
57    /// What authoritative storage reads established about the last attempt.
58    pub settlement: ClaimSettlement,
59}
60
61/// Authenticated observations supplied by the sync reader.
62pub enum ClaimRead {
63    /// The create succeeded and the subsequent authenticated floor still keeps
64    /// the attempted slot. No reread of our own ciphertext is required.
65    Created,
66    /// A slot at or above the checked floor. Absence permits exact retry.
67    Kept(Option<Box<dyn Read + Send>>),
68    /// A snapshot whose coverage includes the attempted slot below the floor.
69    Compacted {
70        /// The floor's first kept slot.
71        first: u64,
72        /// The authenticated snapshot's coverage.
73        covers: u64,
74        /// This device's last included claim in that snapshot.
75        last_claim: u64,
76        /// Digest paired with that number; absent exactly when it is zero.
77        digest: Option<[u8; 32]>,
78    },
79}
80
81fn settlement(text: String) -> sqlive::rusqlite::Result<ClaimSettlement> {
82    match text.as_str() {
83        "unknown" => Ok(ClaimSettlement::Unknown),
84        "retry" => Ok(ClaimSettlement::Retry),
85        "not-landed" => Ok(ClaimSettlement::NotLanded),
86        "landed" => Ok(ClaimSettlement::Landed),
87        "device-id-in-use" => Ok(ClaimSettlement::DeviceIdInUse),
88        _ => Err(damaged(4, sqlive::rusqlite::types::Type::Text)),
89    }
90}
91
92fn metadata(db: &StoreSql) -> Result<Option<Claim>, DbError> {
93    Ok(db.query("SELECT device,number,through,operation,settlement FROM _coven_claim_journal WHERE singleton=1", [], |r| {
94        let work = match (r.get::<_,Option<Vec<u8>>>(2)?, r.get::<_,Option<i64>>(3)?) {
95            (Some(n),None) => ClaimWork::Writes(counter(n)?),
96            (None,Some(id)) => ClaimWork::Operation(OperationId(id)),
97            _ => return Err(damaged(2, sqlive::rusqlite::types::Type::Blob)),
98        };
99        Ok(Claim { device:r.get::<_, DeviceId>(0)?, number:counter(r.get(1)?)?, work,
100            attempts:Vec::new(), settlement:settlement(r.get(4)?)? })
101    }).map(|mut rows| rows.pop())?)
102}
103
104pub(crate) fn current(db: &StoreSql) -> Result<Option<Claim>, DbError> {
105    metadata(db)?.map(|mut claim| {
106        claim.attempts = db.query("SELECT path FROM _coven_claim_attempts WHERE device=?1 AND number=?2 ORDER BY attempt",
107            params![claim.device,claim.number.to_be_bytes().as_slice()], |r| {
108                let path:String=r.get(0)?;
109                ObjectPath::parse(&path).map_err(|e|crate::write_encoding::decode_failure(0,sqlive::rusqlite::types::Type::Text,e))
110            })?;
111        Ok(claim)
112    }).transpose()
113}
114
115pub(crate) fn reserved(db: &StoreSql, device: DeviceId) -> Result<u64, DbError> {
116    let previous: Option<Vec<u8>> = db.query_row(
117        "SELECT (SELECT number FROM _coven_claim_counters WHERE device=?1)",
118        [device],
119        |r| r.get(0),
120    )?;
121    Ok(previous.map(counter).transpose()?.unwrap_or(0))
122}
123
124pub(crate) fn begin<R: Read>(
125    db: &StoreSql,
126    device: DeviceId,
127    work: ClaimWork,
128    number: u64,
129    prepared: crate::claim_preparation::PreparedClaim<R>,
130) -> Result<Claim, DbError> {
131    if metadata(db)?.is_some() {
132        return Err(DbError::ClaimPending);
133    }
134    // Concurrent callers may have committed another claim while this one sealed.
135    if reserved(db, device)?.checked_add(1) != Some(number) {
136        return Err(DbError::ClaimPending);
137    }
138    let (through, operation) = match work {
139        ClaimWork::Writes(through) => (Some(through.to_be_bytes().to_vec()), None),
140        ClaimWork::Operation(operation) => (None, Some(operation.0)),
141    };
142    db.execute("INSERT INTO _coven_claim_counters(device,number) VALUES(?1,?2) ON CONFLICT(device) DO UPDATE SET number=excluded.number",
143        params![device,number.to_be_bytes().as_slice()])?;
144    db.execute("INSERT INTO _coven_claim_journal(device,number,through,operation,settlement,singleton) VALUES(?1,?2,?3,?4,'unknown',1)",
145        params![device,number.to_be_bytes().as_slice(),through,operation])?;
146    let path = prepared.attempt.path.clone();
147    append(db, device, number, prepared)?;
148    if let ClaimWork::Writes(through) = work {
149        db.execute(
150            "INSERT INTO _coven_upload_claims(device,number,claim)
151             SELECT device,number,?1 FROM _coven_uploads WHERE device=?2 AND number<=?3
152             ON CONFLICT(device,number) DO UPDATE SET claim=excluded.claim",
153            params![number.to_be_bytes().as_slice(), device, through.to_be_bytes().as_slice()],
154        )?;
155    }
156    Ok(Claim { device, number, work, attempts: vec![path], settlement: ClaimSettlement::Unknown })
157}
158
159fn append(
160    db: &StoreSql,
161    device: DeviceId,
162    number: u64,
163    prepared: crate::claim_preparation::PreparedClaim<impl Read>,
164) -> Result<(), DbError> {
165    let crate::claim_preparation::PreparedClaim { mut attempt, digest, size } = prepared;
166    let ordinal: i64 = db.query_row("SELECT coalesce(max(attempt),0)+1 FROM _coven_claim_attempts WHERE device=?1 AND number=?2",
167        params![device,number.to_be_bytes()], |r|r.get(0))?;
168    db.execute(
169        "INSERT INTO _coven_claim_attempts(device,number,attempt,path) VALUES(?1,?2,?3,?4)",
170        params![device, number.to_be_bytes(), ordinal, attempt.path.as_str()],
171    )?;
172    for chunk in 0i64.. {
173        let bytes = read_chunk(&mut attempt.bytes)?;
174        if bytes.is_empty() {
175            break;
176        }
177        db.execute("INSERT INTO _coven_claim_chunks(device,number,attempt,chunk,bytes) VALUES(?1,?2,?3,?4,?5)",
178            params![device,number.to_be_bytes(),ordinal,chunk,bytes])?;
179    }
180    db.execute(
181        "UPDATE _coven_claim_attempts SET digest=?4,size=?5 WHERE device=?1 AND number=?2 AND attempt=?3",
182        params![
183            device,
184            number.to_be_bytes(),
185            ordinal,
186            digest.as_bytes(),
187            size.to_be_bytes()
188        ],
189    )?;
190    Ok(())
191}
192
193/// The next chunk of a claim's ciphertext stream: up to one chunk's bytes,
194/// none at its end.
195pub(crate) fn read_chunk(bytes: &mut dyn Read) -> Result<Vec<u8>, DbError> {
196    let mut chunk = Vec::new();
197    bytes
198        .take(coven_format::chunks::CHUNK_SIZE as u64)
199        .read_to_end(&mut chunk)
200        .map_err(DbError::ClaimRead)?;
201    Ok(chunk)
202}
203
204/// Bounded reads of the current attempt's durable ciphertext.
205pub struct ClaimBytes<'a> {
206    db: &'a StoreSql,
207    device: DeviceId,
208    number: u64,
209    attempt: i64,
210    chunk: i64,
211    ended: bool,
212}
213
214impl Iterator for ClaimBytes<'_> {
215    type Item = Result<Vec<u8>, DbError>;
216
217    fn next(&mut self) -> Option<Self::Item> {
218        if self.ended {
219            return None;
220        }
221        let bytes = self.db.query_row("SELECT (SELECT bytes FROM _coven_claim_chunks WHERE device=?1 AND number=?2 AND attempt=?3 AND chunk=?4)",
222            params![self.device,self.number.to_be_bytes(),self.attempt,self.chunk], |r|r.get::<_,Option<Vec<u8>>>(0));
223        match bytes {
224            Ok(Some(bytes)) => {
225                self.chunk += 1;
226                Some(Ok(bytes))
227            }
228            Ok(None) => {
229                self.ended = true;
230                None
231            }
232            Err(error) => {
233                self.ended = true;
234                Some(Err(error.into()))
235            }
236        }
237    }
238}
239
240pub(crate) fn read_attempt<T, E: From<DbError>>(
241    db: &StoreSql,
242    consume: impl FnOnce(ClaimBytes<'_>) -> Result<T, E>,
243) -> Result<T, E> {
244    let claim = metadata(db)?.ok_or(DbError::NoClaim)?;
245    let attempt = db
246        .query_row(
247            "SELECT max(attempt) FROM _coven_claim_attempts WHERE device=?1 AND number=?2",
248            params![claim.device, claim.number.to_be_bytes()],
249            |r| r.get(0),
250        )
251        .map_err(DbError::from)?;
252    consume(ClaimBytes {
253        db,
254        device: claim.device,
255        number: claim.number,
256        attempt,
257        chunk: 0,
258        ended: false,
259    })
260}
261
262fn equal(db: &StoreSql, mut received: Box<dyn Read + Send>) -> Result<bool, DbError> {
263    read_attempt(db, |mut saved| {
264        let mut equal = true;
265        loop {
266            let incoming = read_chunk(&mut received)?;
267            let stored = saved.next().transpose()?;
268            if incoming.is_empty() && stored.is_none() {
269                return Ok(equal);
270            }
271            equal &= stored.as_deref() == Some(incoming.as_slice());
272        }
273    })
274}
275
276pub(crate) fn retry(
277    db: &StoreSql,
278    attempt: crate::claim_preparation::PreparedClaim<impl Read>,
279) -> Result<(), DbError> {
280    let claim = metadata(db)?.ok_or(DbError::NoClaim)?;
281    if claim.settlement != ClaimSettlement::NotLanded {
282        return Err(DbError::ClaimUnsettled);
283    }
284    append(db, claim.device, claim.number, attempt)?;
285    db.execute("UPDATE _coven_claim_journal SET settlement='unknown' WHERE singleton=1", [])?;
286    Ok(())
287}
288
289pub(crate) fn settle(db: &StoreSql, read: ClaimRead) -> Result<ClaimSettlement, DbError> {
290    let claim = current(db)?.ok_or(DbError::NoClaim)?;
291    if matches!(
292        claim.settlement,
293        ClaimSettlement::Landed | ClaimSettlement::NotLanded | ClaimSettlement::DeviceIdInUse
294    ) {
295        return Ok(claim.settlement);
296    }
297    let attempt = claim.attempts.last().expect("a journal starts with its first attempt");
298    let (result, name) = match read {
299        ClaimRead::Created => (ClaimSettlement::Landed, "landed"),
300        ClaimRead::Kept(Some(bytes)) => {
301            if equal(db, bytes)? {
302                (ClaimSettlement::Landed, "landed")
303            } else {
304                (ClaimSettlement::NotLanded, "not-landed")
305            }
306        }
307        ClaimRead::Kept(None) => (ClaimSettlement::Retry, "retry"),
308        ClaimRead::Compacted { first, covers, last_claim, digest } => {
309            let slot = attempt.slot_number().ok_or(DbError::InvalidClaimCoverage)?;
310            if first <= slot.get() || covers < first - 1 {
311                return Err(DbError::InvalidClaimCoverage);
312            }
313            if last_claim < claim.number {
314                (ClaimSettlement::NotLanded, "not-landed")
315            } else if last_claim > claim.number {
316                (ClaimSettlement::DeviceIdInUse, "device-id-in-use")
317            } else {
318                let attempted_digest: Vec<u8> = db.query_row(
319                    "SELECT digest FROM _coven_claim_attempts WHERE device=?1 AND number=?2 ORDER BY attempt DESC LIMIT 1",
320                    params![claim.device, claim.number.to_be_bytes()],
321                    |r| r.get(0),
322                )?;
323                if digest.as_ref().map(|value| value.as_slice())
324                    == Some(attempted_digest.as_slice())
325                {
326                    (ClaimSettlement::Landed, "landed")
327                } else {
328                    (ClaimSettlement::DeviceIdInUse, "device-id-in-use")
329                }
330            }
331        }
332    };
333    db.execute("UPDATE _coven_claim_journal SET settlement=?1 WHERE singleton=1", [name])?;
334    Ok(result)
335}
336
337/// The operation whose open claim the applied slots record as landed,
338/// whatever its settlement says, with the slot its last attempt claimed:
339/// this device's last recorded claim has its number and that attempt's
340/// digest. An unsettled claim of a slot applied since, or compacted under a
341/// loaded floor, is one (§5.1).
342pub(crate) fn landed_operation(
343    db: &StoreSql,
344) -> Result<Option<(OperationId, coven_merge::Slot)>, DbError> {
345    let Some(claim) = metadata(db)? else {
346        return Ok(None);
347    };
348    let ClaimWork::Operation(id) = claim.work else {
349        return Ok(None);
350    };
351    let found = db.query(
352        "SELECT a.path FROM _coven_claim_attempts AS a
353         JOIN _coven_last_claims AS c ON c.device=a.device AND c.number=a.number
354             AND c.digest=a.digest
355         WHERE a.device=?1 AND a.number=?2
356             AND a.attempt=(SELECT max(attempt) FROM _coven_claim_attempts
357                 WHERE device=?1 AND number=?2)",
358        params![claim.device, claim.number.to_be_bytes()],
359        |r| r.get::<_, String>(0),
360    )?;
361    let Some(path) = found.into_iter().next() else {
362        return Ok(None);
363    };
364    let path = ObjectPath::parse(&path).map_err(|e| {
365        crate::write_encoding::decode_failure(0, sqlive::rusqlite::types::Type::Text, e)
366    })?;
367    Ok(Some((id, path.slot_number().ok_or(DbError::InvalidClaimCoverage)?)))
368}
369
370/// Whether the open claim is the operation `id`'s.
371pub(crate) fn held_by(db: &StoreSql, id: OperationId) -> Result<bool, DbError> {
372    Ok(metadata(db)?.is_some_and(|claim| claim.work == ClaimWork::Operation(id)))
373}
374
375/// End the open claim, settled or not, of an operation that ends without
376/// it: this device has stopped for good, and no attempt of it can count.
377pub(crate) fn drop_operation(db: &StoreSql, id: OperationId) -> Result<(), DbError> {
378    if held_by(db, id)? {
379        db.execute("DELETE FROM _coven_claim_journal WHERE singleton=1", [])?;
380    }
381    Ok(())
382}
383
384/// Finish only a settled attempt. The owning operation controls whether a lost
385/// claim is abandoned or retried; a landed batch removes its original queue rows.
386pub(crate) fn finish(db: &StoreSql) -> Result<(), DbError> {
387    let claim = metadata(db)?.ok_or(DbError::NoClaim)?;
388    let mut writes_landed = false;
389    match claim.settlement {
390        ClaimSettlement::Unknown | ClaimSettlement::Retry => return Err(DbError::ClaimUnsettled),
391        ClaimSettlement::Landed if matches!(claim.work, ClaimWork::Writes(_)) => {
392            // A write still queued keeps its entry, with no slot; a landed
393            // one's entry may be forgotten (§16.7).
394            let unconsumed: bool = db.query_row(
395                &format!("SELECT EXISTS(SELECT 1 FROM _coven_upload_claims u JOIN _coven_writes w ON {WRITE_DEVICE_SQL}=u.device AND w.number=u.number WHERE u.device=?1 AND u.claim=?2 AND w.slot IS NULL)"),
396                params![claim.device, claim.number.to_be_bytes()],
397                |r| r.get(0),
398            )?;
399            if unconsumed {
400                return Err(DbError::ClaimUnsettled);
401            }
402            crate::reset_bytes::landed(db, claim.device, claim.number)?;
403            crate::upload::forget_claimed(db, claim.device, claim.number)?;
404            writes_landed = true;
405        }
406        _ => (),
407    }
408    db.execute("DELETE FROM _coven_claim_journal WHERE singleton=1", [])?;
409    if writes_landed {
410        db.give_back_free_pages()?;
411    }
412    Ok(())
413}
414
415/// Path evidence distinguishes contention from an unattempted use of this id.
416#[cfg(any(test, feature = "test-utils"))]
417pub(crate) fn attempted(db: &StoreSql, path: &ObjectPath) -> Result<bool, DbError> {
418    Ok(db.query_row(
419        "SELECT EXISTS(SELECT 1 FROM _coven_claim_attempts WHERE path=?1)",
420        [path.as_str()],
421        |r| r.get(0),
422    )?)
423}
424
425pub(crate) fn attempted_digest(
426    db: &StoreSql,
427    number: u64,
428    path: &ObjectPath,
429    digest: &[u8; 32],
430) -> Result<bool, DbError> {
431    Ok(db.query_row("SELECT EXISTS(SELECT 1 FROM _coven_claim_attempts WHERE number=?1 AND path=?2 AND digest=?3)",
432        params![number.to_be_bytes(), path.as_str(), digest], |r| r.get(0))?)
433}
434
435/// Durable transfer state for the current attempt's exact sealed bytes.
436pub struct ClaimUpload {
437    /// The complete ciphertext length.
438    pub size: u64,
439    /// Opaque provider session retained after each confirmed part.
440    pub session: Option<Vec<u8>>,
441}
442
443pub(crate) fn upload(db: &StoreSql) -> Result<ClaimUpload, DbError> {
444    let claim = metadata(db)?.ok_or(DbError::NoClaim)?;
445    Ok(db.query_row("SELECT size,session FROM _coven_claim_attempts WHERE device=?1 AND number=?2 ORDER BY attempt DESC LIMIT 1",
446        params![claim.device, claim.number.to_be_bytes()], |row| Ok(ClaimUpload {size: counter(row.get(0)?)?, session: row.get(1)?}))?)
447}
448
449pub(crate) fn save_upload(db: &StoreSql, session: Vec<u8>) -> Result<(), DbError> {
450    let claim = metadata(db)?.ok_or(DbError::NoClaim)?;
451    db.execute("UPDATE _coven_claim_attempts SET session=?3 WHERE device=?1 AND number=?2 AND attempt=(SELECT max(attempt) FROM _coven_claim_attempts WHERE device=?1 AND number=?2)",
452        params![claim.device, claim.number.to_be_bytes(), session])?;
453    Ok(())
454}
455
456pub(crate) fn range(db: &StoreSql, offset: u64, length: usize) -> Result<Vec<u8>, DbError> {
457    if length == 0 {
458        return Ok(Vec::new());
459    }
460    let claim = metadata(db)?.ok_or(DbError::NoClaim)?;
461    let chunk_size = coven_format::chunks::CHUNK_SIZE as u64;
462    let end = offset.checked_add(length as u64).ok_or(DbError::DamagedDatabase)?;
463    let pieces = db.query("SELECT chunk,bytes FROM _coven_claim_chunks WHERE device=?1 AND number=?2 AND attempt=(SELECT max(attempt) FROM _coven_claim_attempts WHERE device=?1 AND number=?2) AND chunk>=?3 AND chunk<=?4 ORDER BY chunk",
464        params![claim.device, claim.number.to_be_bytes(), (offset / chunk_size) as i64, ((end-1) / chunk_size) as i64],
465        |row| Ok((row.get::<_,i64>(0)? as u64, row.get::<_,Vec<u8>>(1)?)))?;
466    let mut bytes = Vec::with_capacity(length);
467    for (index, piece) in pieces {
468        let start = offset.saturating_sub(index * chunk_size) as usize;
469        let last = (end - index * chunk_size).min(piece.len() as u64) as usize;
470        bytes.extend_from_slice(piece.get(start..last).ok_or(DbError::DamagedDatabase)?);
471    }
472    if bytes.len() != length {
473        return Err(DbError::DamagedDatabase);
474    }
475    Ok(bytes)
476}
477
478#[cfg(test)]
479#[path = "claim_tests.rs"]
480pub(crate) mod tests;