batpak 0.8.2

Event sourcing with causal graphs and caller-defined gates. Sync API, no async runtime.
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

// justifies: INV-TEST-PANIC-AS-ASSERTION; this lock-behavior harness uses panic! as assertion style for precise lock-mode drift.
#![allow(clippy::panic)]
//! Store directory locking surface.
//! PROVES: INV-JOURNAL-SINGLE-LIVE-OWNER.
//! Harness pattern: State-Machine Harness (open/hold/reject/release lane).
//!
//! PROVES: mutable and read-only opens both hold an exclusive lifetime lock
//! under the exclusive-only ownership contract, and open attempts fail before
//! cold-start work when the requested mode cannot be acquired.
//! CATCHES: mutable/reopen races that allow two writers, read-only opens that
//! ignore a live mutable owner, or lock guards dropped before the Store handle.
//! SEEDED: not random; deterministic tempdir-based lock choreography.

use batpak::event::kind::EventKindError;
use batpak::store::{ReadOnly, Store, StoreConfig, StoreError, StoreLockMode};
use std::path::Path;
use std::process::Command;
use std::time::{Duration, Instant};
use tempfile::TempDir;

fn match_locked(err: StoreError, path: &std::path::Path, mode: StoreLockMode) {
    let expected_path = std::fs::canonicalize(path).expect("canonical tempdir path");
    let StoreError::StoreLocked {
        path: actual_path,
        mode: actual_mode,
    } = err
    else {
        panic!("expected StoreLocked, got {err:?}");
    };
    assert_eq!(actual_path, expected_path);
    assert_eq!(actual_mode, mode);
}

fn wait_for_path(path: &Path, label: &str) {
    let deadline = Instant::now() + Duration::from_secs(10);
    while Instant::now() < deadline {
        if path.exists() {
            return;
        }
        std::thread::sleep(Duration::from_millis(25));
    }
    panic!("{label} did not appear at {}", path.display());
}

fn wait_for_mutable_open_after_release(config: &StoreConfig, path: &Path, label: &str) -> Store {
    let deadline = Instant::now() + Duration::from_secs(2);
    let expected_path = std::fs::canonicalize(path).expect("canonical tempdir path");
    let mut last_err = None;
    while Instant::now() < deadline {
        match Store::open(config.clone()) {
            Ok(store) => return store,
            Err(StoreError::StoreLocked {
                path: actual_path,
                mode,
            }) => {
                assert_eq!(actual_path, expected_path);
                assert_eq!(mode, StoreLockMode::Mutable);
                last_err = Some(StoreError::StoreLocked {
                    path: actual_path,
                    mode,
                });
                std::thread::sleep(Duration::from_millis(25));
            }
            Err(err) => panic!("{label}: unexpected error while waiting for lock release: {err:?}"),
        }
    }
    panic!(
        "{label}: lock did not clear before deadline: {:?}",
        last_err.expect("lock retry loop should record the last StoreLocked error")
    );
}

fn wait_for_read_only_open_after_release(
    config: &StoreConfig,
    path: &Path,
    label: &str,
) -> Store<ReadOnly> {
    let deadline = Instant::now() + Duration::from_secs(2);
    let expected_path = std::fs::canonicalize(path).expect("canonical tempdir path");
    let mut last_err = None;
    while Instant::now() < deadline {
        match Store::<ReadOnly>::open_read_only(config.clone()) {
            Ok(store) => return store,
            Err(StoreError::StoreLocked {
                path: actual_path,
                mode,
            }) => {
                assert_eq!(actual_path, expected_path);
                assert_eq!(mode, StoreLockMode::ReadOnly);
                last_err = Some(StoreError::StoreLocked {
                    path: actual_path,
                    mode,
                });
                std::thread::sleep(Duration::from_millis(25));
            }
            Err(err) => panic!("{label}: unexpected error while waiting for lock release: {err:?}"),
        }
    }
    panic!(
        "{label}: lock did not clear before deadline: {:?}",
        last_err.expect("lock retry loop should record the last StoreLocked error")
    );
}

fn helper_command(data_dir: &Path, ready: &Path, release: &Path) -> Command {
    let current = std::env::current_exe().expect("current test binary");
    let example_name = format!("store_lock_helper{}", std::env::consts::EXE_SUFFIX);
    let example = current
        .parent()
        .and_then(Path::parent)
        .expect("test binary lives under target profile")
        .join("examples")
        .join(example_name);
    let mut cmd = if example.exists() {
        Command::new(example)
    } else {
        let mut cargo = Command::new(std::env::var("CARGO").unwrap_or_else(|_| "cargo".into()));
        cargo
            .arg("run")
            .arg("--quiet")
            .arg("--example")
            .arg("store_lock_helper")
            .arg("--manifest-path")
            .arg(Path::new(env!("CARGO_MANIFEST_DIR")).join("Cargo.toml"))
            .arg("--");
        cargo
    };
    cmd.env("BATPAK_LOCK_HELPER_DATA_DIR", data_dir)
        .env("BATPAK_LOCK_HELPER_READY", ready)
        .env("BATPAK_LOCK_HELPER_RELEASE", release);
    cmd
}

#[test]
fn mutable_open_holds_exclusive_lock_and_blocks_read_only_until_drop() {
    let dir = TempDir::new().expect("temp dir");
    let config = StoreConfig::new(dir.path());
    let store = Store::open(config.clone()).expect("open mutable store");

    let err = match Store::open(config.clone()) {
        Ok(_) => panic!("mutable open must not succeed while another mutable store holds the lock"),
        Err(err) => err,
    };
    match_locked(err, dir.path(), StoreLockMode::Mutable);

    let err = match Store::<ReadOnly>::open_read_only(config.clone()) {
        Ok(_) => panic!("read-only open must not succeed while mutable store holds exclusive lock"),
        Err(err) => err,
    };
    match_locked(err, dir.path(), StoreLockMode::ReadOnly);

    drop(store);

    let reopened =
        wait_for_read_only_open_after_release(&config, dir.path(), "read-only open after drop");
    let _ = reopened.query(&batpak::coordinate::Region::all());
}

#[test]
fn read_only_open_is_also_exclusive_under_ownership_contract() {
    let dir = TempDir::new().expect("temp dir");
    let config = StoreConfig::new(dir.path());

    let ro = Store::<ReadOnly>::open_read_only(config.clone()).expect("open read-only store");

    let err = match Store::<ReadOnly>::open_read_only(config.clone()) {
        Ok(_) => panic!("second read-only open must not succeed while first read-only store holds the exclusive lock"),
        Err(err) => err,
    };
    match_locked(err, dir.path(), StoreLockMode::ReadOnly);

    let err = match Store::open(config.clone()) {
        Ok(_) => {
            panic!("mutable open must not succeed while read-only store holds the exclusive lock")
        }
        Err(err) => err,
    };
    match_locked(err, dir.path(), StoreLockMode::Mutable);

    drop(ro);

    let store = wait_for_mutable_open_after_release(
        &config,
        dir.path(),
        "mutable open after read-only release",
    );
    let _ = store.diagnostics();
}

#[test]
fn subprocess_mutable_owner_blocks_other_processes() {
    let dir = TempDir::new().expect("temp dir");
    let ready = dir.path().join("ready");
    let release = dir.path().join("release");
    let config = StoreConfig::new(dir.path());

    let mut child = helper_command(dir.path(), &ready, &release)
        .spawn()
        .expect("spawn lock helper");

    wait_for_path(&ready, "helper ready file");

    let err = match Store::open(config.clone()) {
        Ok(_) => panic!("second mutable open must fail while helper owns the lock"),
        Err(err) => err,
    };
    match_locked(err, dir.path(), StoreLockMode::Mutable);

    let err = match Store::<ReadOnly>::open_read_only(config) {
        Ok(_) => panic!("read-only open must fail while helper owns the lock"),
        Err(err) => err,
    };
    match_locked(err, dir.path(), StoreLockMode::ReadOnly);

    std::fs::write(&release, b"release").expect("release helper");
    // Intentional: child process wait follows the release signal; helper exit
    // is the test assertion.
    let status = child.wait().expect("wait on helper");
    assert!(
        status.success(),
        "helper process must exit successfully: {status}"
    );
}

#[test]
fn event_kind_error_pub_surface_has_a_real_test_witness() {
    let err = EventKindError::ReservedSystemCategory;
    let display = err.to_string();
    assert!(
        display.contains("reserved"),
        "public EventKindError witness should remain a real path-position test use"
    );
}