shep-daemon 0.25.2

The supervision engine behind shep: process spawning, restart policy, the log plane, watch and cron restarts, and the RPC server
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
//! Reading and writing a dog's own `[<name>]` section of `dogs.toml`.
//!
//! A dog asks for this over the socket rather than getting it in its
//! environment: `SHEP_HOME` and `SHEP_DOG_NAME` are the only two variables
//! [`super::dog_app`] sets, because the environment is readable from the
//! process table and inherited by every child.

use std::path::Path;

use shep_core::config::DogsConfig;

use super::spec::DogError;

/// `path`, a `dogs.toml`, read as UTF-8 text: `None` when the file is not
/// there, which is the shape of a home that has never had a dog configured
/// and also the shape of a section nobody has written yet.
///
/// The one place the two readers of this file map a missing file to an
/// empty result; any other failure to read is [`DogError::Io`] for both.
fn read_dogs_toml(path: &Path) -> Result<Option<String>, DogError> {
    match std::fs::read_to_string(path) {
        Ok(source) => Ok(Some(source)),
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(err) => Err(DogError::Io(err)),
    }
}

/// The `[<name>]` section of `path`, a `dogs.toml`, as the operator wrote it:
/// a document in its own right, headers rebased off `name`, no header of its own.
///
/// Reads the file on every call, so one reader can never be stale and
/// `shep disable X && shep enable X` re-reads an edited section. A missing
/// file, or one with no such section, is `Ok(String::new())`.
///
/// The operator's own bytes, not a re-render: rendering a parsed table drops
/// the comments inside a section and sorts its keys.
///
/// # Errors
/// - [`DogError::Config`] if the file is not valid `dogs.toml` or its section
///   will not render back. [`DogError::Io`] if it could not be read.
pub fn dog_section(path: &Path, name: &str) -> Result<String, DogError> {
    // A missing file returns before the parse below, which would otherwise
    // be handed nothing to parse.
    let Some(source) = read_dogs_toml(path)? else {
        return Ok(String::new());
    };
    // Through shep-core's own type, so a broken `dogs.toml` is one named error
    // and not a second parser's opinion of the same file.
    let config =
        DogsConfig::load(Some(&source)).map_err(|err| DogError::Config(err.to_string()))?;
    let Some(table) = config.dog.get(name) else {
        return Ok(String::new());
    };
    // Cannot fail: the stricter parse above already read the same bytes.
    let doc: toml_edit::DocumentMut = source
        .parse()
        .map_err(|err: toml_edit::TomlError| DogError::Config(err.to_string()))?;
    match doc.get(name) {
        Some(toml_edit::Item::Table(spanned)) => {
            // Re-rooted, not `to_string`ed in place. A table renders its own
            // key-values and leaves its child tables to the document, which
            // writes their headers by their path from the root, so a section
            // read out of `[bark]` would arrive missing or misnamed.
            let mut section = spanned.clone();
            // The root of a document takes no header, and the decor here is
            // the `[bark]` line's own: a comment above it belongs to the
            // table rather than to the body, and `set_dog_section` carries
            // it across on the write instead.
            section.set_implicit(true);
            *section.decor_mut() = toml_edit::Decor::default();
            let mut out = toml_edit::DocumentMut::new();
            *out.as_table_mut() = section;
            Ok(out.to_string())
        }
        // An inline table, `bark = { poll = "60s" }`, is a valid entry
        // whose span is `{ ... }`, which is not a section body and is not
        // something the pane could write back. Rendered, as every section
        // was before: there is no comment to lose inside one line.
        _ => toml::to_string(table).map_err(|err| DogError::Config(err.to_string())),
    }
}

/// Replaces `name`'s table in `path`, a `dogs.toml`, with `section` and writes
/// the file back owner-only, under the lock the CLI's writers of it hold.
///
/// `dogs.toml` is hand-editable on purpose, so this reads, modifies and
/// writes the document it read rather than rendering a parsed map back out:
/// every table other than `name`'s comes through byte for byte, comments
/// included. The write is staged in a sibling file created owner-only,
/// `fsync`ed, then `rename`d over `path` so a crash leaves the whole file
/// or none of it.
///
/// # Errors
/// - [`DogError::Io`]: the lock, the read, the staging file, the `fsync` or
///   the rename. [`DogError::Config`]: `section` or `path` is not valid TOML.
pub fn set_dog_section(path: &Path, name: &str, section: &str) -> Result<(), DogError> {
    use std::io::Write as _;

    use toml_edit::{DocumentMut, Item};

    // Held across the read, the splice and the rename, and dropped on the
    // way out. Two writers that read before either wrote would lose one of
    // the two sections whichever way the renames raced. This function takes
    // no other lock, so it cannot hold `dogs.toml` and wait on `shep.toml`.
    let _lock = shep_core::config_lock::ConfigLock::acquire(path).map_err(DogError::Io)?;

    // A missing file is the ordinary first write: a home that has never had
    // a dog configured has no `dogs.toml` at all.
    let existing = read_dogs_toml(path)?.unwrap_or_default();
    let mut doc: DocumentMut = existing.parse().map_err(|err: toml_edit::TomlError| {
        DogError::Config(format!("dogs.toml does not parse: {err}"))
    })?;
    let incoming: DocumentMut = section.parse().map_err(|err: toml_edit::TomlError| {
        DogError::Config(format!("[{name}] does not parse: {err}"))
    })?;

    // `set_implicit(false)`, or a section emptied down to nothing takes the
    // dog's table with it. A document's root table is implicit, and an
    // implicit table with no keys of its own renders no header at all. The
    // emptied case is where an operator lands by deleting the last key.
    let mut table = incoming.as_table().clone();
    table.set_implicit(false);
    // A comment above `[name]`, and anything trailing the header itself, are
    // decor on the table rather than text inside it: `dog_section` hands the
    // caller the body and cannot carry them, and replacing the item wholesale
    // would drop both.
    if let Some(Item::Table(existing)) = doc.get(name) {
        *table.decor_mut() = existing.decor().clone();
    }
    doc[name] = Item::Table(table);

    let rendered = doc.to_string();
    DogsConfig::load(Some(&rendered))
        .map_err(|err| DogError::Config(format!("[{name}] would not load: {err}")))?;

    let parent = path.parent().unwrap_or_else(|| Path::new("."));
    let mut tmp = shep_core::config_lock::create_config_file(parent).map_err(DogError::Io)?;
    tmp.write_all(rendered.as_bytes()).map_err(DogError::Io)?;
    shep_core::atomic_file::publish(tmp, path).map_err(DogError::Io)
}

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

    #[test]
    fn a_section_written_with_sub_tables_reaches_the_dog_as_its_own_document() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        let source = "# above the header\n[bark]\n# above poll\npoll = \"5s\"\n\n[bark.sinks.local]\nkind = \"json\"\nurl = \"https://example.invalid/h\"\n\n[[bark.rules]]\non = \"event\"\nkinds = [\"exit\"]\nsinks = [\"local\"]\n\n[otel]\nendpoint = \"https://collector.invalid\"\n";
        std::fs::write(&path, source).unwrap();

        let section = dog_section(&path, "bark").unwrap();
        let parsed: toml::Table = section.parse().unwrap();

        // The dog parses the section as its own root, so every sub-table has
        // to arrive rebased off the section name.
        assert!(parsed.contains_key("sinks"), "{section}");
        assert!(parsed.contains_key("rules"), "{section}");
        assert_eq!(
            parsed["sinks"]["local"]["kind"].as_str(),
            Some("json"),
            "{section}"
        );
        assert_eq!(
            parsed["rules"].as_array().map(Vec::len),
            Some(1),
            "{section}"
        );
        // The operator's own comment between keys survives the re-rooting,
        // which is the reason this reads a span rather than re-rendering.
        assert!(section.contains("# above poll"), "{section}");
        // The header's own decor is `set_dog_section`'s to carry, not this.
        assert!(!section.contains("# above the header"), "{section}");
        // A second dog is nobody else's business.
        assert!(!section.contains("otel"), "{section}");
    }

    #[test]
    fn a_sub_table_section_survives_a_read_and_a_write_back() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        std::fs::write(
            &path,
            "# keep me\n[bark]\npoll = \"5s\"\n\n[bark.sinks.local]\nkind = \"json\"\nurl = \"https://example.invalid/h\"\n",
        )
        .unwrap();

        let section = dog_section(&path, "bark").unwrap();
        set_dog_section(&path, "bark", &section).unwrap();

        let after = std::fs::read_to_string(&path).unwrap();
        let reloaded: toml::Table = after.parse().unwrap();
        assert_eq!(
            reloaded["bark"]["sinks"]["local"]["url"].as_str(),
            Some("https://example.invalid/h"),
            "{after}"
        );
        assert!(after.contains("# keep me"), "{after}");
        assert_eq!(dog_section(&path, "bark").unwrap(), section, "{after}");
    }

    #[test]
    fn a_dogs_section_comes_back_as_its_own_table_and_nothing_else() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        std::fs::write(
            &path,
            "[bark]\ndebounce = \"30s\"\n\n[metrics]\nport = 9615\n",
        )
        .unwrap();

        let bark = dog_section(&path, "bark").unwrap();
        assert!(bark.contains("debounce"));
        assert!(
            !bark.contains("9615"),
            "one dog never sees another's config"
        );
        // Round-trips as TOML, the contract the dog parses under.
        let parsed: toml::Table = toml::from_str(&bark).unwrap();
        assert_eq!(parsed["debounce"].as_str(), Some("30s"));

        assert_eq!(dog_section(&path, "absent").unwrap(), "");
        assert_eq!(
            dog_section(&dir.path().join("gone.toml"), "bark").unwrap(),
            ""
        );
    }

    #[test]
    fn a_section_reaches_the_wire_exactly_as_it_did_from_shep_toml() {
        let dir = tempfile::tempdir().expect("tempdir");
        let path = dir.path().join("dogs.toml");
        std::fs::write(&path, "[bark]\ndebounce = \"30s\"\n").expect("write");

        // Pinned as a string: the dog-facing contract is the exact text.
        assert_eq!(
            dog_section(&path, "bark").expect("section"),
            "debounce = \"30s\"\n"
        );
    }

    #[test]
    fn a_dog_with_no_section_still_gets_an_empty_string() {
        let dir = tempfile::tempdir().expect("tempdir");
        let path = dir.path().join("dogs.toml");
        std::fs::write(&path, "[bark]\ndebounce = \"30s\"\n").expect("write");

        assert_eq!(dog_section(&path, "metrics").expect("section"), "");
    }

    /// A comment above another dog's table, or that dog's own keys, would
    /// not survive a regenerate-from-map write. `dogs.toml` is
    /// hand-editable on purpose, so an operator's file coming back
    /// rewritten would be the bug.
    #[test]
    fn set_dog_section_replaces_one_table_and_leaves_the_rest_untouched() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        std::fs::write(
            &path,
            "# top comment\n[metrics]\nbind = \"127.0.0.1:9100\"\n\n[bark]\npoll = \"60s\"\n",
        )
        .unwrap();

        set_dog_section(&path, "bark", "poll = \"30s\"\nhistory_bytes = 4096\n").unwrap();

        let text = std::fs::read_to_string(&path).unwrap();
        assert!(text.starts_with("# top comment"), "{text}");
        assert!(text.contains("bind = \"127.0.0.1:9100\""), "{text}");
        assert!(text.contains("poll = \"30s\""), "{text}");
        assert!(!text.contains("poll = \"60s\""), "{text}");
        let parsed = DogsConfig::load(Some(&text)).unwrap();
        assert_eq!(parsed.dog["bark"]["history_bytes"].as_integer(), Some(4096));
    }

    /// The sibling test above pins a comment outside the edited table,
    /// which the write side preserves on its own; a comment inside it, and
    /// the order of the keys around it, survive only if the section the
    /// pane was handed was the raw span. `toml::map::Map` is a `BTreeMap`
    /// without `preserve_order`, so a re-render alphabetises as well as
    /// stripping. A comment above the header is the third case, decor on
    /// the table itself, which only the write side can carry.
    #[test]
    fn a_pane_round_trip_keeps_the_comments_and_the_key_order() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        std::fs::write(
            &path,
            "# what bark is for\n[bark]\n# why bark polls slowly\npoll = \"60s\"\nzz_last = 1\naa_first = 2\n",
        )
        .unwrap();

        let section = dog_section(&path, "bark").unwrap();
        assert!(section.contains("# why bark polls slowly"), "{section}");
        assert!(
            section.find("zz_last") < section.find("aa_first"),
            "the keys come back in the operator\'s order: {section}"
        );

        // What the pane does: write back what it was handed, one value
        // changed.
        set_dog_section(&path, "bark", &section.replace("60s", "30s")).unwrap();

        let text = std::fs::read_to_string(&path).unwrap();
        assert!(text.contains("# why bark polls slowly"), "{text}");
        assert!(
            text.contains("# what bark is for"),
            "the header's own comment lives on the table, not inside it: {text}"
        );
        assert!(text.contains("poll = \"30s\""), "{text}");
        assert!(
            text.find("zz_last") < text.find("aa_first"),
            "the write keeps the order the read handed it: {text}"
        );
    }

    /// A `dogs.toml` that is there but cannot be read (a directory sitting
    /// at the path) is an I/O error for both readers, not the empty result
    /// a missing file gets: the two cases must not collapse into one.
    #[test]
    fn a_dogs_toml_that_cannot_be_read_is_an_io_error_for_both_functions() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        std::fs::create_dir(&path).unwrap();

        let read = dog_section(&path, "bark").unwrap_err();
        assert!(matches!(read, DogError::Io(_)), "{read}");

        let write = set_dog_section(&path, "bark", "poll = \"30s\"\n").unwrap_err();
        assert!(matches!(write, DogError::Io(_)), "{write}");
    }

    /// A home that has never had a dog configured has no `dogs.toml` at
    /// all, the ordinary case for the first section anyone writes.
    #[test]
    fn set_dog_section_creates_the_file_when_there_is_none() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");

        set_dog_section(&path, "bark", "poll = \"30s\"\n").unwrap();

        let parsed = DogsConfig::load(Some(&std::fs::read_to_string(&path).unwrap())).unwrap();
        assert!(parsed.dog.contains_key("bark"));
    }

    /// A section this daemon cannot read back must never reach disk: the
    /// file it lands in is the one every dog is served from, so one bad
    /// section would take the rest of the kennel down with it.
    #[test]
    fn set_dog_section_refuses_text_that_is_not_a_table_and_writes_nothing() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        std::fs::write(&path, "[bark]\npoll = \"60s\"\n").unwrap();

        let err = set_dog_section(&path, "bark", "this is = = not toml").unwrap_err();

        assert!(err.to_string().contains("bark"), "{err}");
        assert_eq!(
            std::fs::read_to_string(&path).unwrap(),
            "[bark]\npoll = \"60s\"\n"
        );
    }

    /// This section parses fine on its own and the spliced document is
    /// valid TOML; what it is not is a valid `DogsConfig`, since the file
    /// it lands in has a top-level scalar. The daemon serves every dog
    /// from one `DogsConfig::load` of this file, so a write that leaves it
    /// unloadable takes the whole kennel down, not just this dog.
    #[test]
    fn set_dog_section_refuses_a_result_the_daemon_could_not_read_back() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        std::fs::write(&path, "port = 9100\n[bark]\npoll = \"60s\"\n").unwrap();

        let err = set_dog_section(&path, "bark", "poll = \"30s\"\n").unwrap_err();

        assert!(err.to_string().contains("bark"), "{err}");
        assert_eq!(
            std::fs::read_to_string(&path).unwrap(),
            "port = 9100\n[bark]\npoll = \"60s\"\n"
        );
    }

    /// A root table is implicit, and an implicit table with no keys of its
    /// own renders no header at all, so an operator who cleared a section
    /// in the pane would find `[bark]` gone from a file they are invited
    /// to hand-edit, and `shep describe` with it.
    #[test]
    fn set_dog_section_leaves_the_table_behind_when_the_section_is_emptied() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");
        std::fs::write(&path, "[bark]\npoll = \"60s\"\n").unwrap();

        set_dog_section(&path, "bark", "").unwrap();

        let text = std::fs::read_to_string(&path).unwrap();
        assert!(text.contains("[bark]"), "{text}");
        let parsed = DogsConfig::load(Some(&text)).unwrap();
        assert!(parsed.dog["bark"].is_empty(), "{text}");
    }

    /// `docs/dogs.md` tells an operator to paste a webhook URL here, a
    /// bearer token in a path. The CLI's own writer creates the file
    /// `0600`; a second writer at `0644` would be the downgrade.
    #[cfg(unix)]
    #[test]
    fn set_dog_section_writes_owner_only() {
        use std::os::unix::fs::PermissionsExt as _;

        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("dogs.toml");

        set_dog_section(&path, "bark", "poll = \"30s\"\n").unwrap();

        assert_eq!(
            std::fs::metadata(&path).unwrap().permissions().mode() & 0o777,
            0o600
        );
    }
}