shep-client 0.2.3

Async client for the shep daemon: typed requests, event subscriptions, and starting a shepherd that is not running yet
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
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
//! The dog side of the probe contract: one call a dog makes as its first
//! line, which answers every question shep asks its binary.
//!
//! A dog is a plugin process the shepherd supervises. Before shep adopts one,
//! and again whenever it needs the dog's config schema, it spawns the binary
//! with a flag and reads what comes back. [`probe`] answers both flags, so
//! neither the answer's format nor the flag names are ever typed by a dog
//! author:
//!
//! ```no_run
//! # #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
//! # #[derive(shep_client::dogs::DogConfig)]
//! # struct MyDogConfig {}
//! fn main() {
//!     shep_client::dogs::probe::<MyDogConfig>(
//!         env!("CARGO_PKG_NAME"),
//!         env!("CARGO_PKG_VERSION"),
//!     );
//!     // ...normal startup, reached only when this run is not a probe.
//! }
//! ```
//!
//! `name` and `version` are arguments rather than `env!` calls in this
//! crate, since `env!` expands where it is written and would report
//! `shep-client`'s own version instead of the dog's.
//!
//! Answering is optional: with the `schema` feature off, [`probe`] still
//! answers the version flag, and the schema flag exits without printing,
//! which shep reads as a dog with no schema and refuses nothing for.

use std::io::Write as _;

pub use shep_core::dogs::SECRET_KEY;
use shep_core::dogs::{SCHEMA_FLAG, SHEP_PROTOCOL_KEY, VERSION_FLAG};
/// The derive that implements [`DogConfig`], re-exported so a dog takes one
/// dependency rather than two.
///
/// Its own documentation carries the rules: which shapes accept
/// `#[shep(secret)]`, which refuse it, and what the expansion looks like.
pub use shep_macros::DogConfig;

/// What a dog's config type tells shep about itself: which of its fields are
/// credentials, and the schema extension key that says so.
///
/// Derive it, and mark each credential field with `#[shep(secret)]`; do not
/// write this impl by hand, since a mistyped [`SECRET_KEY`] compiles,
/// validates, marks nothing, and paints a credential on screen.
pub trait DogConfig {
    /// The schema extension key a marked field carries. Always
    /// [`SECRET_KEY`]; it is an associated const so the derive can name it
    /// through this crate rather than reaching into `shep_core`.
    const SECRET_KEY: &'static str;

    /// The Rust identifiers of the fields marked `#[shep(secret)]`, deduped.
    /// A name repeated across the variants of an enum appears once, because
    /// this is a list of names to look for rather than places to look.
    const SECRET_FIELDS: &'static [&'static str];
}

/// A field marked `#[shep(secret)]` that names no property of the config
/// type's own schema, so the marker had nothing to land on.
///
/// A like-named property under `$defs` does not count: it's a different
/// type's field, and letting it answer for this one is how a renamed
/// credential ships unmarked.
///
/// `Debug` is derived: the field it names is an identifier from the dog's
/// own source, never a credential's value.
#[cfg(feature = "schema")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SecretFieldMissing {
    /// The Rust identifier that was marked and could not be found.
    pub field: &'static str,
}

#[cfg(feature = "schema")]
impl core::fmt::Display for SecretFieldMissing {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(
            f,
            "the field `{}` is marked `#[shep(secret)]` but this type's own \
             schema has no property of that name, so the credential would go \
             out unmarked. A `#[serde(rename)]` on the field, or a \
             `rename_all_fields` on the type, renames the property and leaves \
             the mark with nothing to land on.",
            self.field
        )
    }
}

#[cfg(feature = "schema")]
impl core::error::Error for SecretFieldMissing {}

/// The JSON Schema a dog answers the schema flag with: what `schemars`
/// generates for `T`, with every `#[shep(secret)]` field of `T` carrying
/// [`SECRET_KEY`]. Public so a dog or test can render the marks without
/// spawning itself.
///
/// # Errors
///
/// [`SecretFieldMissing`] when a marked name matches no property of `T`'s
/// own representation.
#[cfg(feature = "schema")]
pub fn config_schema<T: DogConfig + schemars::JsonSchema>()
-> Result<schemars::Schema, SecretFieldMissing> {
    let mut schema = schemars::SchemaGenerator::default().into_root_schema_for::<T>();
    let mut found: Vec<&'static str> = Vec::new();
    // `None` only for a schema that is the bare `true` or `false`, which has
    // no property to mark and so leaves every marked name unfound below.
    if let Some(root) = schema.as_object_mut() {
        mark_secrets_in_object(root, T::SECRET_FIELDS, T::SECRET_KEY, &mut found);
    }
    for field in T::SECRET_FIELDS {
        if !found.contains(field) {
            return Err(SecretFieldMissing { field });
        }
    }
    Ok(schema)
}

/// Where `schemars` puts the schema of every OTHER named type the root
/// mentions, and the one keyword [`mark_secrets_in_object`] refuses to walk.
#[cfg(feature = "schema")]
const DEFS: &str = "$defs";

/// Writes `key` into every property named in `secrets` that belongs to the
/// root type's own representation, and records which names were reached.
///
/// Walks the whole node, not just `properties`: a tagged enum's variants
/// live under `oneOf`/`anyOf`, or nested under a content property, so only
/// a struct has properties at the top level. Stops at [`DEFS`], so a
/// like-named property of another type is never marked or counted as found.
/// A recursive root's `$ref: "#"` is a string, so the walk skips it as a leaf.
///
/// Marks by name, so two variants sharing a field name are both marked
/// even if only one carried the attribute. A non-object property schema is
/// left unmarked, surfacing as [`SecretFieldMissing`] rather than a silent miss.
#[cfg(feature = "schema")]
fn mark_secrets_in_object(
    map: &mut serde_json::Map<String, serde_json::Value>,
    secrets: &[&'static str],
    key: &str,
    found: &mut Vec<&'static str>,
) {
    if let Some(serde_json::Value::Object(properties)) = map.get_mut("properties") {
        for name in secrets {
            if let Some(serde_json::Value::Object(property)) = properties.get_mut(*name) {
                property.insert(key.to_owned(), serde_json::Value::Bool(true));
                if !found.contains(name) {
                    found.push(name);
                }
            }
        }
    }
    for (keyword, value) in map.iter_mut() {
        if keyword == DEFS {
            continue;
        }
        mark_secrets(value, secrets, key, found);
    }
}

/// [`mark_secrets_in_object`] for a node that may be any JSON value: an
/// object is marked, an array is descended (a `oneOf` is one), and anything
/// else is a leaf.
#[cfg(feature = "schema")]
fn mark_secrets(
    node: &mut serde_json::Value,
    secrets: &[&'static str],
    key: &str,
    found: &mut Vec<&'static str>,
) {
    match node {
        serde_json::Value::Object(map) => mark_secrets_in_object(map, secrets, key, found),
        serde_json::Value::Array(items) => {
            for item in items {
                mark_secrets(item, secrets, key, found);
            }
        }
        _ => {}
    }
}

/// Answers shep's probes, and returns when this run is not a probe, so a
/// dog calls it as the first line of `main`.
///
/// `name` and `version` are ordinarily `env!("CARGO_PKG_NAME")` and
/// `env!("CARGO_PKG_VERSION")`; only the version is read by shep.
///
/// # Exits
///
/// Ends the process with [`process::exit`](std::process::exit) before
/// `main` opens anything: status 0 for an answer given, 1 when
/// [`SecretFieldMissing`] makes the schema unpublishable (printed to
/// stderr first).
#[cfg(feature = "schema")]
pub fn probe<T: DogConfig + schemars::JsonSchema>(name: &str, version: &str) {
    match first_argument().as_deref() {
        Some(VERSION_FLAG) => answer(&version_answer(name, version)),
        Some(SCHEMA_FLAG) => match schema_answer::<T>() {
            Ok(json) => answer(&json),
            Err(err) => {
                eprintln!("{err}");
                std::process::exit(1);
            }
        },
        _ => (),
    }
}

/// Answers shep's probes, and returns when this run is not a probe, so a
/// dog calls it as the first line of `main`.
///
/// `name` and `version` are ordinarily `env!("CARGO_PKG_NAME")` and
/// `env!("CARGO_PKG_VERSION")`; only the version is read by shep. With the
/// `schema` feature off, the schema flag exits without printing, so shep
/// records a dog with no schema instead of waiting out a timeout.
///
/// # Exits
///
/// Ends the process with [`process::exit`](std::process::exit), status 0,
/// before `main` opens anything.
#[cfg(not(feature = "schema"))]
pub fn probe<T: DogConfig>(name: &str, version: &str) {
    match first_argument().as_deref() {
        Some(VERSION_FLAG) => answer(&version_answer(name, version)),
        Some(SCHEMA_FLAG) => std::process::exit(0),
        _ => (),
    }
}

/// The argument shep spawns a probe with, which is the only one it passes.
///
/// Only the first: `docs/dogs.md` publishes that contract, and a dog's
/// own arguments are its business.
fn first_argument() -> Option<String> {
    std::env::args().nth(1)
}

/// Prints an answer and ends the process.
///
/// The explicit flush matters: [`std::process::exit`] runs no destructor,
/// so nothing else would push a partial buffer out.
fn answer(text: &str) -> ! {
    let mut stdout = std::io::stdout();
    // A write to a closed stdout is not something a dog can do anything
    // about, and shep reads it as silence, which is a legal answer.
    let _ = write!(stdout, "{text}");
    let _ = stdout.flush();
    std::process::exit(0);
}

/// The `--version` answer, whole, ending in a newline.
///
/// Split out from [`probe`] so the format can be tested against
/// [`shep_core::dogs::parse_version_answer`], the code that reads it.
fn version_answer(name: &str, version: &str) -> String {
    format!(
        "{name} {version}\n{SHEP_PROTOCOL_KEY}: {}\n",
        crate::PROTOCOL_VERSION
    )
}

/// The `--schema` answer, whole, ending in a newline.
///
/// # Errors
///
/// [`SecretFieldMissing`], straight from [`config_schema`].
#[cfg(feature = "schema")]
fn schema_answer<T: DogConfig + schemars::JsonSchema>() -> Result<String, SecretFieldMissing> {
    let schema = config_schema::<T>()?;
    // The same expectation shep-core's own schema printer holds: a schemars
    // `Schema` is a `serde_json::Value` already, so serializing it cannot
    // meet a type serde_json has no representation for.
    let json = serde_json::to_string_pretty(&schema).expect("a schemars Schema always serializes");
    Ok(format!("{json}\n"))
}

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

    /// The two ends of the grammar: what a dog prints and what shep reads.
    /// Pinned as a round trip rather than as a string, because the format is
    /// only ever interesting to the parser.
    #[test]
    fn the_version_answer_parses_with_the_shepherds_own_parser() {
        let answer = version_answer("shep-otel", "0.1.3");
        let parsed = shep_core::dogs::parse_version_answer(&answer)
            .expect("the answer shep's own parser cannot read is the bug this pins");

        assert_eq!(parsed.version, "0.1.3");
        assert_eq!(parsed.protocol, Some(crate::PROTOCOL_VERSION));
    }

    /// Everything the `schema` feature gates, gated the same way: with the
    /// feature off there is no `config_schema` to name here either.
    #[cfg(feature = "schema")]
    mod schema {
        use super::*;

        #[derive(schemars::JsonSchema, DogConfig)]
        #[allow(dead_code, reason = "read by the generated schema, not by Rust")]
        struct Webhook {
            #[shep(secret)]
            url: String,
            channel: String,
        }

        #[derive(schemars::JsonSchema, DogConfig)]
        #[serde(tag = "kind", rename_all = "snake_case")]
        #[allow(dead_code, reason = "read by the generated schema, not by Rust")]
        enum Sink {
            Discord {
                #[shep(secret)]
                url: String,
                quiet: bool,
            },
            Slack {
                #[shep(secret)]
                url: String,
            },
        }

        #[derive(schemars::JsonSchema, DogConfig)]
        #[allow(dead_code, reason = "read by the generated schema, not by Rust")]
        struct Renamed {
            #[shep(secret)]
            #[serde(rename = "webhook_url")]
            url: String,
        }

        /// A type the root only mentions, so `schemars` hoists it into `$defs`.
        /// Its `token` is an ordinary string, and it is named to collide with
        /// the credential the two roots below mark.
        #[derive(schemars::JsonSchema)]
        #[allow(dead_code, reason = "read by the generated schema, not by Rust")]
        struct Inner {
            token: String,
        }

        #[derive(schemars::JsonSchema, DogConfig)]
        #[allow(dead_code, reason = "read by the generated schema, not by Rust")]
        struct Outer {
            #[shep(secret)]
            token: String,
            inner: Inner,
        }

        #[derive(schemars::JsonSchema, DogConfig)]
        #[allow(dead_code, reason = "read by the generated schema, not by Rust")]
        struct RenamedOuter {
            #[shep(secret)]
            #[serde(rename = "api_token")]
            token: String,
            inner: Inner,
        }

        /// Both halves in one test on purpose: an implementation that marked
        /// every property would pass a test that only checked the marked one.
        #[test]
        fn a_secret_field_carries_the_marker_and_a_plain_one_does_not() {
            let schema = config_schema::<Webhook>().expect("`url` is a real property");
            let props = schema
                .as_value()
                .get("properties")
                .expect("a derived struct schema has properties");

            assert_eq!(
                props.get("url").and_then(|url| url.get(SECRET_KEY)),
                Some(&serde_json::Value::Bool(true)),
                "the marked field carries the marker"
            );
            assert_eq!(
                props.get("channel").and_then(|it| it.get(SECRET_KEY)),
                None,
                "the unmarked field carries nothing"
            );
        }

        /// A tagged enum has no top-level `properties` at all: it is a `oneOf` of
        /// one object per variant. Marking code that reads only the top level
        /// finds nothing, marks nothing, and says nothing.
        #[test]
        fn a_marker_reaches_every_variant_of_a_tagged_enum_and_no_plain_field() {
            let schema =
                config_schema::<Sink>().expect("`url` is a real property in both variants");
            let variants = schema
                .as_value()
                .get("oneOf")
                .and_then(|it| it.as_array())
                .expect("a tagged enum is a oneOf");
            assert_eq!(variants.len(), 2);

            for variant in variants {
                let props = variant
                    .get("properties")
                    .expect("each variant carries its own properties");
                assert_eq!(
                    props.get("url").and_then(|url| url.get(SECRET_KEY)),
                    Some(&serde_json::Value::Bool(true)),
                    "every occurrence of the marked name is marked"
                );
                assert_eq!(
                    props.get("quiet").and_then(|it| it.get(SECRET_KEY)),
                    None,
                    "a plain field in the same variant carries nothing"
                );
            }
        }

        #[test]
        fn a_renamed_secret_field_is_an_error_rather_than_a_silent_pass() {
            assert_eq!(
                config_schema::<Renamed>(),
                Err(SecretFieldMissing { field: "url" })
            );
        }

        /// A mark names a field of the type shep asked about, so a like-named
        /// property of some other type the root merely mentions is not that
        /// field and must come out plain. `Rule::sinks` is the live case: it
        /// lists sink NAMES, one level under a `BarkConfig::sinks` that really
        /// does hold credentials.
        #[test]
        fn a_like_named_property_of_a_nested_type_is_left_plain() {
            let schema = config_schema::<Outer>().expect("`token` is a real property of the root");
            let schema = schema.as_value();

            assert_eq!(
                schema.pointer("/properties/token/x-shep-secret"),
                Some(&serde_json::Value::Bool(true)),
                "the root's own marked field carries the marker"
            );
            assert_eq!(
                schema.pointer("/$defs/Inner/properties/token/x-shep-secret"),
                None,
                "a stranger that shares the name is not the marked field"
            );
        }

        /// The same reach, pointing the other way: a `$defs` entry that happens
        /// to carry the pre-rename name would satisfy the missing-field check on
        /// behalf of a credential that shipped unmarked.
        #[test]
        fn a_renamed_secret_field_is_an_error_even_when_a_nested_type_has_the_old_name() {
            assert_eq!(
                config_schema::<RenamedOuter>(),
                Err(SecretFieldMissing { field: "token" })
            );
        }
    }
}