taskfast-cli 0.22.0

`taskfast` CLI: worker + poster hot-loop operations, JSON-envelope output.
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
// SPDX-License-Identifier: MIT
//! Unified local state and secret persistence for `.taskfast/` directory.
//!
//! Encapsulates path resolution, directory permissions (0700 on Unix for `.taskfast`),
//! automatic `.gitignore` provisioning, atomic file writes with 0600 permissions from
//! creation, and an ephemeral adapter for test execution with `/dev/null`.

use std::collections::VecDeque;
use std::fs;
use std::io::{self, Write};
use std::path::{Path, PathBuf};

use crate::config::DEFAULT_CONFIG_PATH;

/// Typed assets managed within the local `.taskfast/` state directory.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum StateAsset {
    /// CLI configuration (`config.json`).
    Config,
    /// Event stream pagination cursor (`events.cursor`).
    EventsCursor,
    /// Deduplication cache for received event IDs (`events.seen`).
    EventsSeen,
    /// Pending submission fee retry transaction hashes (`fee_retries.json`).
    FeeRetries,
}

impl StateAsset {
    /// Return the standard file name for this state asset.
    pub const fn filename(self) -> &'static str {
        match self {
            Self::Config => "config.json",
            Self::EventsCursor => "events.cursor",
            Self::EventsSeen => "events.seen",
            Self::FeeRetries => "fee_retries.json",
        }
    }
}

/// Unified state store for `.taskfast/` local files.
#[derive(Debug, Clone)]
pub struct StateStore {
    root_dir: Option<PathBuf>,
}

impl StateStore {
    /// Construct a store from a config path.
    ///
    /// When `config_path` is `/dev/null` or within `/dev/`, creates an ephemeral
    /// store that never touches the filesystem. Otherwise, creates a disk-backed
    /// store rooted at the parent directory of `config_path`.
    pub fn from_config_path(config_path: &Path) -> Self {
        if config_path == Path::new("/dev/null") || config_path.parent() == Some(Path::new("/dev"))
        {
            return Self::ephemeral();
        }

        let root_dir = config_path
            .parent()
            .filter(|p| !p.as_os_str().is_empty())
            .unwrap_or_else(|| Path::new("."))
            .to_path_buf();

        Self {
            root_dir: Some(root_dir),
        }
    }

    /// Construct an ephemeral store with no on-disk persistence.
    pub fn ephemeral() -> Self {
        Self { root_dir: None }
    }

    /// Return true if this store is ephemeral (no on-disk persistence).
    pub fn is_ephemeral(&self) -> bool {
        self.root_dir.is_none()
    }

    /// Return the root directory if disk-backed.
    pub fn root_dir(&self) -> Option<&Path> {
        self.root_dir.as_deref()
    }

    /// Return the resolved path on disk for a state asset, or None if ephemeral.
    pub fn path_for(&self, asset: StateAsset) -> Option<PathBuf> {
        self.root_dir.as_ref().map(|dir| dir.join(asset.filename()))
    }

    /// Ensure the root directory exists with 0700 permissions and automatic `.gitignore`.
    pub fn ensure_dir(&self) -> io::Result<()> {
        if let Some(dir) = &self.root_dir {
            Self::ensure_dir_path(dir)?;
        }
        Ok(())
    }

    /// Ensure a directory exists. When the directory is named `.taskfast`, tightens
    /// permissions to 0700 on Unix and provisions `.gitignore`.
    pub fn ensure_dir_path(dir: &Path) -> io::Result<()> {
        if dir.as_os_str().is_empty() || dir == Path::new(".") {
            return Ok(());
        }
        fs::create_dir_all(dir)?;

        let is_taskfast_dir = Path::new(DEFAULT_CONFIG_PATH)
            .parent()
            .and_then(Path::file_name)
            .is_some_and(|expected| dir.file_name() == Some(expected));

        if is_taskfast_dir {
            #[cfg(unix)]
            {
                use std::os::unix::fs::PermissionsExt;
                fs::set_permissions(dir, fs::Permissions::from_mode(0o700))?;
            }
            ensure_dir_gitignore(dir);
        }
        Ok(())
    }

    /// Atomic file write: writes to sibling `.tmp`, 0600 on Unix from creation, flushes, renames.
    ///
    /// Cleans up the temporary file if write or rename fails. Does not chmod the parent directory.
    pub fn atomic_write_file(path: &Path, contents: &[u8]) -> io::Result<()> {
        if let Some(parent) = path.parent() {
            if !parent.as_os_str().is_empty() {
                fs::create_dir_all(parent)?;
            }
        }

        let tmp_name = format!(
            "{}.tmp.{}",
            path.file_name().and_then(|n| n.to_str()).unwrap_or("file"),
            uuid::Uuid::new_v4().simple()
        );
        let tmp = path.with_file_name(tmp_name);

        let write_res = (|| -> io::Result<()> {
            #[cfg(unix)]
            let create = {
                use std::os::unix::fs::OpenOptionsExt;
                fs::OpenOptions::new()
                    .write(true)
                    .create(true)
                    .truncate(true)
                    .mode(0o600)
                    .open(&tmp)
            };
            #[cfg(not(unix))]
            let create = fs::File::create(&tmp);

            let mut f = create?;
            f.write_all(contents)?;
            f.flush()?;
            drop(f);
            fs::rename(&tmp, path)?;
            Ok(())
        })();

        if write_res.is_err() {
            let _ = fs::remove_file(&tmp);
        }
        write_res
    }

    /// Read the pagination cursor if present and non-empty.
    pub fn read_cursor(&self) -> Option<String> {
        let path = self.path_for(StateAsset::EventsCursor)?;
        let raw = fs::read_to_string(path).ok()?;
        let trimmed = raw.trim().to_string();
        if trimmed.is_empty() {
            None
        } else {
            Some(trimmed)
        }
    }

    /// Write pagination cursor. A `None` cursor leaves the existing cursor untouched.
    pub fn write_cursor(&self, next_cursor: Option<&str>) -> io::Result<()> {
        let Some(payload) = next_cursor else {
            return Ok(());
        };
        let Some(path) = self.path_for(StateAsset::EventsCursor) else {
            return Ok(());
        };
        Self::atomic_write_file(&path, payload.as_bytes())
    }

    /// Load seen event IDs from `events.seen`.
    pub fn load_seen_lines(&self) -> io::Result<Vec<String>> {
        let Some(path) = self.path_for(StateAsset::EventsSeen) else {
            return Ok(Vec::new());
        };
        match fs::read_to_string(path) {
            Ok(raw) => Ok(raw
                .lines()
                .filter(|l| !l.is_empty())
                .map(str::to_string)
                .collect()),
            Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(Vec::new()),
            Err(e) => Err(e),
        }
    }

    /// Append a single seen ID to `events.seen`.
    pub fn append_seen_line(&self, id: &str) -> io::Result<()> {
        let Some(path) = self.path_for(StateAsset::EventsSeen) else {
            return Ok(());
        };

        let open_append = || {
            #[cfg(unix)]
            {
                use std::os::unix::fs::OpenOptionsExt;
                fs::OpenOptions::new()
                    .create(true)
                    .append(true)
                    .mode(0o600)
                    .open(&path)
            }
            #[cfg(not(unix))]
            {
                fs::OpenOptions::new().create(true).append(true).open(&path)
            }
        };

        let mut f = match open_append() {
            Ok(file) => file,
            Err(e) if e.kind() == io::ErrorKind::NotFound => {
                self.ensure_dir()?;
                open_append()?
            }
            Err(e) => return Err(e),
        };

        writeln!(f, "{id}")?;
        Ok(())
    }

    /// Rewrite `events.seen` with the given IDs, separated by newlines.
    pub fn rewrite_seen_lines(&self, ids: &VecDeque<String>) -> io::Result<()> {
        let Some(path) = self.path_for(StateAsset::EventsSeen) else {
            return Ok(());
        };
        let mut body = String::new();
        for id in ids {
            body.push_str(id);
            body.push('\n');
        }
        Self::atomic_write_file(&path, body.as_bytes())
    }

    /// Read any pending fee retry transaction hash for `task_id`.
    pub fn get_pending_fee_retry(&self, task_id: &uuid::Uuid) -> Option<String> {
        let path = self.path_for(StateAsset::FeeRetries)?;
        let raw = fs::read_to_string(path).ok()?;
        let map: std::collections::HashMap<String, String> = serde_json::from_str(&raw).ok()?;
        map.get(&task_id.to_string()).cloned()
    }

    /// Record a pending fee retry transaction hash for `task_id`.
    pub fn record_pending_fee_retry(&self, task_id: &uuid::Uuid, tx_hash: &str) -> io::Result<()> {
        let Some(path) = self.path_for(StateAsset::FeeRetries) else {
            return Ok(());
        };
        let mut map: std::collections::HashMap<String, String> = if path.exists() {
            fs::read_to_string(&path)
                .ok()
                .and_then(|raw| serde_json::from_str(&raw).ok())
                .unwrap_or_default()
        } else {
            std::collections::HashMap::new()
        };
        map.insert(task_id.to_string(), tx_hash.to_string());
        let body = serde_json::to_vec_pretty(&map)
            .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
        Self::atomic_write_file(&path, &body)
    }

    /// Clear any pending fee retry transaction hash for `task_id`.
    pub fn clear_pending_fee_retry(&self, task_id: &uuid::Uuid) -> io::Result<()> {
        let Some(path) = self.path_for(StateAsset::FeeRetries) else {
            return Ok(());
        };
        if !path.exists() {
            return Ok(());
        }
        let raw = fs::read_to_string(&path)?;
        let mut map: std::collections::HashMap<String, String> =
            serde_json::from_str(&raw).unwrap_or_default();
        if map.remove(&task_id.to_string()).is_some() {
            let body = serde_json::to_vec_pretty(&map)
                .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
            Self::atomic_write_file(&path, &body)?;
        }
        Ok(())
    }
}

fn ensure_dir_gitignore(dir: &Path) {
    let gitignore = dir.join(".gitignore");
    match fs::OpenOptions::new()
        .write(true)
        .create_new(true)
        .open(&gitignore)
    {
        Ok(mut f) => {
            if let Err(e) = f.write_all(b"*\n") {
                tracing::warn!(path = %gitignore.display(), error = %e, "could not write .taskfast/.gitignore");
            }
        }
        Err(e) if e.kind() == io::ErrorKind::AlreadyExists => {}
        Err(e) => {
            tracing::warn!(path = %gitignore.display(), error = %e, "could not create .taskfast/.gitignore");
        }
    }
}

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

    #[test]
    fn ephemeral_mode_skips_disk() {
        let store = StateStore::from_config_path(Path::new("/dev/null"));
        assert!(store.is_ephemeral());
        assert_eq!(store.root_dir(), None);
        assert_eq!(store.path_for(StateAsset::Config), None);

        assert!(store.write_cursor(Some("cur1")).is_ok());
        assert_eq!(store.read_cursor(), None);
    }

    #[test]
    fn disk_mode_creates_0700_dir_and_gitignore() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join(".taskfast").join("config.json");
        let store = StateStore::from_config_path(&config_path);
        assert!(!store.is_ephemeral());

        store.ensure_dir().unwrap();
        let root = store.root_dir().unwrap();
        assert!(root.exists());

        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mode = fs::metadata(root).unwrap().permissions().mode() & 0o777;
            assert_eq!(mode, 0o700, "directory mode must be 0700");
        }

        let gitignore = root.join(".gitignore");
        assert!(
            gitignore.exists(),
            ".gitignore must be created for .taskfast"
        );
        let content = fs::read_to_string(gitignore).unwrap();
        assert_eq!(content, "*\n");
    }

    #[test]
    fn atomic_write_file_sets_0600_from_creation_without_chmod_parent() {
        let tmp = TempDir::new().unwrap();
        let parent = tmp.path().join("sub");
        let target = parent.join("secret.file");
        StateStore::atomic_write_file(&target, b"secret-data").unwrap();

        assert_eq!(fs::read(&target).unwrap(), b"secret-data");
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let file_mode = fs::metadata(&target).unwrap().permissions().mode() & 0o777;
            assert_eq!(file_mode, 0o600, "file mode must be 0600");

            // Parent directory must not be chmod'd to 0700 when writing arbitrary file
            let parent_mode = fs::metadata(&parent).unwrap().permissions().mode() & 0o777;
            assert_ne!(parent_mode, 0o700, "parent directory must not be 0700");
        }
    }

    #[test]
    fn cursor_and_seen_roundtrip() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.json");
        let store = StateStore::from_config_path(&config_path);

        assert_eq!(store.read_cursor(), None);
        store.write_cursor(Some("c1")).unwrap();
        assert_eq!(store.read_cursor(), Some("c1".into()));
        store.write_cursor(None).unwrap();
        assert_eq!(store.read_cursor(), Some("c1".into()));

        assert!(store.load_seen_lines().unwrap().is_empty());
        store.append_seen_line("evt_1").unwrap();
        store.append_seen_line("evt_2").unwrap();
        assert_eq!(store.load_seen_lines().unwrap(), vec!["evt_1", "evt_2"]);

        let mut queue = std::collections::VecDeque::new();
        queue.push_back("evt_3".to_string());
        store.rewrite_seen_lines(&queue).unwrap();
        assert_eq!(store.load_seen_lines().unwrap(), vec!["evt_3"]);
    }

    #[test]
    fn pending_fee_retry_roundtrip() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.json");
        let store = StateStore::from_config_path(&config_path);
        let task_id = uuid::Uuid::new_v4();

        assert_eq!(store.get_pending_fee_retry(&task_id), None);
        store
            .record_pending_fee_retry(&task_id, "0xabcdef123456")
            .unwrap();
        assert_eq!(
            store.get_pending_fee_retry(&task_id),
            Some("0xabcdef123456".into())
        );

        store.clear_pending_fee_retry(&task_id).unwrap();
        assert_eq!(store.get_pending_fee_retry(&task_id), None);
    }
}