kcode-pending-object-store 0.1.1

Durable checksummed pending-object sidecar storage
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

# API

`kcode-pending-object-store` manages checksummed pending-object sidecars in a
caller-owned directory.

```rust
use kcode_pending_object_store::PendingObjectStore;

let store = PendingObjectStore::new(
    "./data/sessions",
    "session-42",
    "0.2.1",
)?;

store.install(
    0,
    "notes.txt",
    "text/plain",
    b"durable bytes",
)?;

let object = store.read(0)?;
assert_eq!(object.file_name, "notes.txt");
assert_eq!(object.media_type, "text/plain");
assert_eq!(object.bytes, b"durable bytes");
# Ok::<(), anyhow::Error>(())
```

Construction has no filesystem effect. The namespace must contain one to 255
ASCII alphanumeric, `-`, or `_` bytes. The format ID must be nonempty and fit
the format's little-endian `u16` byte length.

## Operations

- `install` writes a synchronized same-directory temporary file, atomically
  renames it to the final filename, and synchronizes the directory. The
  directory must already exist. Installation rejects empty filename or media
  type metadata and never overwrites an existing final file. It removes only
  the exact stale temporary file for the requested position.
- `read` opens only the canonical final filename. It verifies the magic,
  configured format ID, declared lengths, UTF-8 and nonempty metadata, exact
  file length, and SHA-256 checksum before returning a
  `StoredPendingObject`.
- `verify_all` reads every supplied position and performs no cleanup.
- `reconcile` removes recognized temporary files and recognized unreferenced
  final files, synchronizes the directory if anything was removed, and then
  verifies every referenced position.
- `delete_all` removes every recognized temporary or final file for the
  namespace and synchronizes the directory before returning success.

Canonical names are
`<namespace>-<canonical-u64>.pending-object` and
`<namespace>-<canonical-u64>.pending-object.tmp`. Recognition rejects leading
zeroes except for position `0`; malformed and similarly prefixed names are
left untouched.

## Binary compatibility

Files use magic `KSPENDING01\n`, followed by little-endian lengths for the
format ID (`u16`), filename (`u32`), media type (`u32`), and object (`u64`).
The next 32 bytes are SHA-256 of the object bytes. The variable data is the
format ID, UTF-8 filename, UTF-8 media type, and object bytes, in that order.

The format is byte-for-byte compatible with pending-object sidecars from
`kcode-session-log` when constructed with that crate's session ID and format
version.

## Boundary

The crate does not create directories, assign positions, coordinate
concurrent writers, or define application lifecycle. Callers must ensure the
directory exists before mutation and prevent unsupported concurrent
modification.