shep_core/config/
app.rs

1//! Per-app configuration schema: one sheep's Flockfile entry.
2
3use core::fmt;
4
5use std::collections::BTreeMap;
6
7// use schemars::generate
8use serde::{Deserialize, Serialize};
9
10use crate::values::{MemSize, UpDuration};
11
12/// How a health probe checks a sheep
13// wire format: changing these strings is a breaking change
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
15#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
16#[serde(rename_all = "snake_case")]
17pub enum ProbeKind {
18    /// HTTP GET must return 2xx
19    Http,
20    /// TCP connect must succeed
21    Tcp,
22    /// Command must exit 0
23    Exec,
24}
25
26/// Readiness/liveness probe configuration (spec §7)
27// wire format: changing field names/defaults is a breaking change
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
30#[serde(deny_unknown_fields)]
31pub struct ProbeConfig {
32    /// Probe mechanism
33    pub kind: ProbeKind,
34    /// URL (http), `host:port` (tcp), or command line (exec)
35    pub target: String,
36    /// Time between probes (default 10s)
37    #[serde(default = "default_probe_interval")]
38    pub interval: UpDuration,
39    /// Per-probe timeout (default 5s)
40    #[serde(default = "default_probe_timeout")]
41    pub timeout: UpDuration,
42    /// Consecutive failures before the probe reports unhealthy (default 3)
43    #[serde(default = "default_failure_threshold")]
44    pub failure_threshold: u32,
45}
46
47fn default_probe_interval() -> UpDuration {
48    UpDuration::from_millis(10_000)
49}
50fn default_probe_timeout() -> UpDuration {
51    UpDuration::from_millis(5_000)
52}
53fn default_failure_threshold() -> u32 {
54    3
55}
56
57/// Per-app configuration — one sheep's entry in a Flockfile
58///
59/// Field names are the Flockfile contract (sheep-native; pm2 spellings are
60/// rejected — the importer translates them). Unknown fields are errors so
61/// typos fail loudly at parse time.
62///
63/// # Example
64/// ```
65/// use shep_core::config::AppConfig;
66///
67/// let app: AppConfig = toml::from_str("name = \"web\"\nscript = \"./srv\"").unwrap();
68/// assert!(app.autorestart); // spec default
69/// ```
70// wire format: changing field names/defaults is a breaking change
71#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
72#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
73#[serde(deny_unknown_fields, default)]
74pub struct AppConfig {
75    /// Unique sheep name (required)
76    #[cfg_attr(feature = "schema", schemars(extend("init" = {
77        "example": "my-first-sheep",
78        "group": "process",
79        "blurb": "A convenient and unique name for shep to display"
80    })))]
81    pub name: String,
82    /// Executable or script path (required)
83    #[cfg_attr(feature = "schema", schemars(extend("init" = {
84        "example": "./index.js",
85        "group": "process",
86        "blurb": "The script that shep should use to launch your app"
87    })))]
88    pub script: String,
89    /// Arguments passed to the script
90    #[cfg_attr(feature = "schema", schemars(extend("init" = {
91        "group": "inputs",
92        "blurb": "Arguments passed to the script, as a list"
93    })))]
94    pub args: Vec<String>,
95    /// Working directory (default: daemon's cwd at spawn registration)
96    #[cfg_attr(feature = "schema", schemars(extend("init" = {
97        "example": "/srv/app",
98        "group": "process",
99        "blurb": "Where the process runs. Without it, the daemon's own directory"
100    })))]
101    pub cwd: Option<String>,
102    /// Interpreter override (`"none"` = run script directly)
103    #[cfg_attr(feature = "schema", schemars(extend("init" = {
104        "example": "none",
105        "group": "process",
106        "blurb": "What runs the script. Set it to none to exec the file directly"
107    })))]
108    pub interpreter: Option<String>,
109    /// Environment for the sheep (merged over the daemon's filtered env)
110    #[cfg_attr(feature = "schema", schemars(extend("init" = {
111        "example": "{ NODE_ENV = 'production' }",
112        "group": "inputs",
113        "blurb": "Environment variables for this app, layered over the daemon's own"
114    })))]
115    pub env: BTreeMap<String, String>,
116    /// Instance count ("cluster" = N fork instances; spec §4)
117    #[cfg_attr(feature = "schema", schemars(extend("init" = {
118        "group": "process",
119        "blurb": "How many copies of this app to run"
120    })))]
121    pub instances: u32,
122    /// Restart on unexpected exit
123    #[cfg_attr(feature = "schema", schemars(extend("init" = {
124        "group": "restart",
125        "blurb": "Restarts the process automatically when it exits unexpectedly"
126    })))]
127    pub autorestart: bool,
128    /// Start when the daemon starts / on `shep muster`
129    #[cfg_attr(feature = "schema", schemars(extend("init" = {
130        "group": "restart",
131        "blurb": "Start this app when the daemon starts, and on shep muster"
132    })))]
133    pub autostart: bool,
134    /// Exit codes treated as clean stop (no restart)
135    #[cfg_attr(feature = "schema", schemars(extend("init" = {
136        "group": "restart",
137        "blurb": "Exit codes that mean a clean stop, so shep will not restart"
138    })))]
139    pub stop_exit_codes: Vec<i32>,
140    /// Uptime below this marks an exit as unstable
141    #[cfg_attr(feature = "schema", schemars(extend("init" = {
142        "group": "restart",
143        "blurb": "An exit sooner than this counts as unstable"
144    })))]
145    pub min_uptime: UpDuration,
146    /// Consecutive unstable exits before `errored`
147    #[cfg_attr(feature = "schema", schemars(extend("init" = {
148        "group": "restart",
149        "blurb": "How many unstable exits in a row before shep gives up"
150    })))]
151    pub max_restarts: u32,
152    /// Fixed delay before every restart (alternative to backoff)
153    #[cfg_attr(feature = "schema", schemars(extend("init" = {
154        "example": "3s",
155        "group": "restart",
156        "blurb": "A fixed wait before every restart, instead of growing backoff"
157    })))]
158    pub restart_delay: Option<UpDuration>,
159    /// Initial backoff delay; grows ×1.5 capped at 15s (spec §4)
160    ///
161    /// Defaults to 100ms, not unset. An unstable exit (sooner than
162    /// `min_uptime`) with neither this nor `restart_delay` configured would
163    /// otherwise restart with no delay at all, so an app that can never
164    /// start (a missing dependency, a bad config) would burn its whole
165    /// `max_restarts` budget inside a second, logging the same failure
166    /// dozens of times.
167    ///
168    /// All of the above assumes `restart_delay` is unset. A fixed
169    /// `restart_delay` takes precedence over this field on every exit,
170    /// stable or not, so a stable exit restarts immediately only while
171    /// `restart_delay` stays unset, and setting this field to `"0"`
172    /// disables the backoff without producing an immediate restart if a
173    /// nonzero `restart_delay` is also configured.
174    #[cfg_attr(feature = "schema", schemars(extend("init" = {
175        "example": "5s",
176        "group": "restart",
177        "blurb": "Starting delay between restarts, growing each time it fails again"
178    })))]
179    pub exp_backoff_restart_delay: Option<UpDuration>,
180    /// Stop signal, one of `SIGTERM`/`SIGINT`/`SIGQUIT`/`SIGUSR2` (the `SIG`
181    /// prefix and the case are both optional). Unset means `SIGTERM`.
182    ///
183    /// A `String` rather than a [`KillSignal`](crate::config::KillSignal) so
184    /// the Flockfile schema and this struct's wire form stay plain text;
185    /// `normalize` is what refuses a name outside that set, the same split
186    /// `cron_restart` and the watch globs already use.
187    #[cfg_attr(feature = "schema", schemars(extend("init" = {
188        "example": "SIGTERM",
189        "group": "shutdown",
190        "blurb": "Which signal shep sends first when stopping this app",
191        "suggest": ["SIGTERM", "SIGINT", "SIGQUIT", "SIGUSR2"]
192    })))]
193    pub kill_signal: Option<String>,
194    /// Grace period between stop signal and SIGKILL
195    #[cfg_attr(feature = "schema", schemars(extend("init" = {
196        "group": "shutdown",
197        "blurb": "How long shep waits after the stop signal before SIGKILL"
198    })))]
199    pub kill_timeout: UpDuration,
200    /// Send `{"kind":"shutdown"}` on the shepherd channel instead of a signal
201    #[cfg_attr(feature = "schema", schemars(extend("init" = {
202        "group": "shutdown",
203        "blurb": "Ask the app to stop over the channel instead of signalling it"
204    })))]
205    pub shutdown_with_message: bool,
206    /// Readiness fallback window when no ready signal/probe configured
207    #[cfg_attr(feature = "schema", schemars(extend("init" = {
208        "group": "readiness",
209        "blurb": "How long to wait for readiness when nothing else reports it"
210    })))]
211    pub listen_timeout: UpDuration,
212    /// Drain window for the old instance during reload
213    #[cfg_attr(feature = "schema", schemars(extend("init" = {
214        "group": "shutdown",
215        "blurb": "How long the old instance gets to drain during a reload"
216    })))]
217    pub graceful_timeout: UpDuration,
218    /// How long a triggered action gets to answer on the shepherd channel
219    /// before its row becomes `ActionOutcome::TimedOut`.
220    ///
221    /// Defaults to 3s — comfortably under the 5s an RPC caller gets when it
222    /// sends no deadline of its own (`shep-client`'s `DEFAULT_DEADLINE`,
223    /// mirrored daemon-side as `rpc`'s `DEFAULT_DEADLINE_MS`). The margin
224    /// matters more than the number: push this past that budget and a caller
225    /// using the plain default gives up with `DeadlineExceeded` before the
226    /// daemon's own honest `TimedOut` row ever reaches it. A legitimately
227    /// slow action (a cache flush, say) can still ask for longer, but its
228    /// caller has to ask for a longer deadline in step —
229    /// `Client::request_with_deadline`, the way `shep logs -f` already asks
230    /// for `LOG_PLANE_DEADLINE` rather than the client's default. `normalize`
231    /// refuses a value no caller could ever satisfy, however long a deadline
232    /// it asks for; a value merely above the *default* budget is a caller's
233    /// choice to widen its own deadline, not a config error this crate can
234    /// see.
235    #[cfg_attr(feature = "schema", schemars(extend("init" = {
236        "group": "shutdown",
237        "blurb": "How long a triggered action has to answer before shep gives up"
238    })))]
239    pub action_timeout: UpDuration,
240    /// Memory ceiling — polling enforcer restarts above this
241    #[cfg_attr(feature = "schema", schemars(extend("init" = {
242        "example": "512M",
243        "group": "restart",
244        "blurb": "Restart the app if it climbs above this much memory"
245    })))]
246    pub max_memory: Option<MemSize>,
247    /// Watch files and restart on change
248    #[cfg_attr(feature = "schema", schemars(extend("init" = {
249        "group": "watch",
250        "blurb": "Restart when a file changes"
251    })))]
252    pub watch: bool,
253    /// Watch ignore globs (defaults added daemon-side: dot-entries, node_modules)
254    #[cfg_attr(feature = "schema", schemars(extend("init" = {
255        "group": "watch",
256        "blurb": "Paths watch should skip, on top of dotfiles and node_modules"
257    })))]
258    pub ignore_watch: Vec<String>,
259    /// Watch debounce window (default 500ms, applied daemon-side)
260    #[cfg_attr(feature = "schema", schemars(extend("init" = {
261        "example": "500",
262        "group": "watch",
263        "blurb": "How long to wait after a change before restarting"
264    })))]
265    pub watch_delay: Option<UpDuration>,
266    /// Cron pattern for scheduled restarts (croner dialect)
267    #[cfg_attr(feature = "schema", schemars(extend("init" = {
268        "example": "* * * * *",
269        "group": "cron",
270        "blurb": "Restart on a schedule, written as a cron pattern",
271        "suggest": ["*/5 * * * *", "0 * * * *", "0 0 * * *", "0 0 * * 0"]
272    })))]
273    pub cron_restart: Option<String>,
274    /// Fold (group) this sheep belongs to
275    #[cfg_attr(feature = "schema", schemars(extend("init" = {
276        "example": "backend",
277        "group": "process",
278        "blurb": "A fold to group this app with others, for commands that take one"
279    })))]
280    pub fold: Option<String>,
281    /// Run as this user (unix)
282    #[cfg_attr(feature = "schema", schemars(extend("init" = {
283        "example": "www-data",
284        "group": "process",
285        "blurb": "Run as this user, on unix"
286    })))]
287    pub user: Option<String>,
288    /// Run as this group (unix)
289    #[cfg_attr(feature = "schema", schemars(extend("init" = {
290        "example": "www-data",
291        "group": "process",
292        "blurb": "Run as this group, on unix"
293    })))]
294    pub group: Option<String>,
295    /// Stdout log file (default: `$SHEP_HOME/logs/<name>-<instance>-out.log`; `merge_logs` collapses to `<name>-out.log`)
296    #[cfg_attr(feature = "schema", schemars(extend("init" = {
297        "example": "/var/log/my-first-sheep/out.log",
298        "group": "logging",
299        "blurb": "Where stdout goes. Defaults to a file under $SHEP_HOME/logs"
300    })))]
301    pub out_file: Option<String>,
302    /// Stderr log file (default: `$SHEP_HOME/logs/<name>-<instance>-err.log`; `merge_logs` collapses to `<name>-err.log`)
303    #[cfg_attr(feature = "schema", schemars(extend("init" = {
304        "example": "/var/log/my-first-sheep/err.log",
305        "group": "logging",
306        "blurb": "Where stderr goes. Defaults to a file under $SHEP_HOME/logs"
307    })))]
308    pub err_file: Option<String>,
309    /// Merge instance logs into one file pair
310    #[cfg_attr(feature = "schema", schemars(extend("init" = {
311        "group": "logging",
312        "blurb": "Put every instance's output in one pair of files"
313    })))]
314    pub merge_logs: bool,
315    /// Open the shepherd channel on fd 3 for this app on its own, without
316    /// needing `wait_ready` or `shutdown_with_message` to imply it.
317    ///
318    /// Defaults to `false`: a socketpair plus two pump tasks per sheep is
319    /// real cost weighed against spec §14.11's single-digit-MB idle-RSS
320    /// goal, so a channel is opened only when something asks for one.
321    #[cfg_attr(feature = "schema", schemars(extend("init" = {
322        "group": "inputs",
323        "blurb": "Opens fd 3 so the app can talk to shep directly"
324    })))]
325    pub channel: bool,
326    /// Open a pipe on this sheep's stdin, so `shep whisper` can write to it.
327    ///
328    /// Defaults to `false`, and the default is the decision rather than a
329    /// convenience. Without it a sheep gets `/dev/null` on fd 0, which is what
330    /// every sheep has had until now, and three things argue for keeping it
331    /// that way unless an app asks otherwise:
332    ///
333    /// - Flipping it for the whole flock is a behaviour change to processes
334    ///   nobody asked to change.
335    /// - **Programs detect stdin.** A closed or null fd 0 is how a great many
336    ///   programs decide they are non-interactive — no prompt, no pager, no
337    ///   readline, no colour. Handing them a pipe silently moves them to the
338    ///   other branch.
339    /// - It costs a descriptor and a pump task per sheep for the whole life of
340    ///   the process, against spec §14.11's single-digit-MB idle-RSS goal — the
341    ///   same budget [`Self::channel`]'s own default is protecting.
342    ///
343    /// Unlike `channel`, nothing implies this: `wait_ready` and
344    /// `shutdown_with_message` both need fd 3 and so turn `channel` on for you,
345    /// while nothing in shep needs a sheep's stdin except an operator typing
346    /// `shep whisper`. A sheep without it answers a `no_stdin` row and names
347    /// this field.
348    ///
349    /// The pipe's write end lives as long as the sheep does, so the app sees
350    /// EOF on stdin when the process is on its way out, never before.
351    #[cfg_attr(feature = "schema", schemars(extend("init" = {
352        "group": "inputs",
353        "blurb": "Keeps stdin open so shep whisper can write to the process"
354    })))]
355    pub stdin: bool,
356    /// Expect `{"kind":"ready"}` on the shepherd channel
357    #[cfg_attr(feature = "schema", schemars(extend("init" = {
358        "group": "readiness",
359        "blurb": "Wait for the app to say it is ready on the channel"
360    })))]
361    pub wait_ready: bool,
362    /// Asserts that the app itself sets `SO_REUSEPORT` before it binds —
363    /// shep binds nothing, so it cannot set the option on the app's behalf.
364    /// The child process owns the mechanism (Node ≥22's `reusePort`, Go's
365    /// `net.ListenConfig.Control`, nginx's `reuseport`); shep's contribution
366    /// is permission for the old and new instance to overlap during reload,
367    /// not the socket option itself.
368    ///
369    /// That permission is what the field buys, and it is read by exactly one
370    /// thing: which reload the daemon runs for the app.
371    ///
372    /// - **Unset**, and the app has a `readiness_probe`: reload is SERIAL.
373    ///   The instance being replaced is drained first and its replacement is
374    ///   spawned into the empty slot, so the app is down for the length of
375    ///   the drain. That is the cost of an honest answer — while both
376    ///   instances are up, a probe against an address cannot say which of
377    ///   them answered, and shep would take the outgoing instance's reply as
378    ///   proof the incoming one is ready.
379    /// - **Set**: reload OVERLAPS. The replacement is spawned alongside the
380    ///   instance it replaces and takes over without a gap — if the app really does set
381    ///   `SO_REUSEPORT`. If it does not, the replacement takes `EADDRINUSE`
382    ///   and the reload fails, which is the failure this field exists to keep
383    ///   opt-in.
384    ///
385    /// An app with no `readiness_probe` overlaps either way: with nothing
386    /// probing an address, there is no answer for the wrong instance to give.
387    /// So does one using `wait_ready`, because the shepherd channel a
388    /// replacement reports on is its own — the instance being replaced has no
389    /// way to answer it. Both of those need `SO_REUSEPORT` as much as a
390    /// `reuse_port` app does if they bind an address, since they are overlapped
391    /// too; what this field changes is which apps get overlapped, not what an
392    /// overlap costs.
393    ///
394    /// Setting this on an app that does NOT set the socket option is the one
395    /// way to get it wrong, and shep cannot check it: the option is set
396    /// inside the child, after the fork, on a socket shep never sees.
397    #[cfg_attr(feature = "schema", schemars(extend("init" = {
398        "group": "process",
399        "blurb": "The app sets SO_REUSEPORT itself, so reload may overlap the two instances"
400    })))]
401    pub reuse_port: bool,
402    /// Readiness probe — gates reload's AwaitReady (spec §7)
403    #[cfg_attr(feature = "schema", schemars(extend("init" = {
404        "example": { "kind": "http", "target": "http://127.0.0.1:8080/ready" },
405        "group": "readiness",
406        "blurb": "A health check shep waits on before it treats a reload as finished"
407    })))]
408    pub readiness_probe: Option<ProbeConfig>,
409    /// Liveness probe — failures feed the restart policy (spec §7)
410    #[cfg_attr(feature = "schema", schemars(extend("init" = {
411        "example": { "kind": "http", "target": "http://127.0.0.1:8080/healthz" },
412        "group": "readiness",
413        "blurb": "A health check that triggers a restart when it keeps failing"
414    })))]
415    pub liveness_probe: Option<ProbeConfig>,
416    /// Watch include globs (empty = watch cwd)
417    #[cfg_attr(feature = "schema", schemars(extend("init" = {
418        "group": "watch",
419        "blurb": "Which paths to watch. Empty means the working directory"
420    })))]
421    pub watch_options: Vec<String>,
422    /// Timezone for `cron_restart` (IANA name)
423    #[cfg_attr(feature = "schema", schemars(extend("init" = {
424        "example": "US/Eastern",
425        "group": "cron",
426        "blurb": "Which timezone cron_restart is read in, as an IANA name"
427    })))]
428    pub cron_timezone: Option<String>,
429    /// Removed. Set your own variable to `{{instance}}` in `env` instead.
430    ///
431    /// Kept only so `normalize` can reject it with that instruction: a
432    /// `deny_unknown_fields` serde error would name no replacement. Remove
433    /// in 0.2.
434    #[cfg_attr(feature = "schema", schemars(skip))]
435    pub increment_var: Option<String>,
436}
437
438/// Redacts `env`: only its length is printed.
439impl fmt::Debug for AppConfig {
440    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
441        f.debug_struct("AppConfig")
442            .field("name", &self.name)
443            .field("script", &self.script)
444            .field("env", &format_args!("<{} vars>", self.env.len()))
445            .finish_non_exhaustive()
446    }
447}
448
449impl Default for AppConfig {
450    fn default() -> Self {
451        Self {
452            name: String::new(),
453            script: String::new(),
454            args: Vec::new(),
455            cwd: None,
456            interpreter: None,
457            env: BTreeMap::new(),
458            instances: 1,
459            autorestart: true,
460            autostart: true,
461            stop_exit_codes: Vec::new(),
462            min_uptime: UpDuration::from_millis(1000),
463            max_restarts: 16,
464            restart_delay: None,
465            // Not None: see the field's doc comment. An unstable exit with
466            // no restart policy configured must not restart instantly.
467            exp_backoff_restart_delay: Some(UpDuration::from_millis(100)),
468            kill_signal: None,
469            kill_timeout: UpDuration::from_millis(1600),
470            shutdown_with_message: false,
471            listen_timeout: UpDuration::from_millis(3000),
472            graceful_timeout: UpDuration::from_millis(8000),
473            action_timeout: UpDuration::from_millis(3000),
474            max_memory: None,
475            watch: false,
476            ignore_watch: Vec::new(),
477            watch_delay: None,
478            cron_restart: None,
479            fold: None,
480            user: None,
481            group: None,
482            out_file: None,
483            err_file: None,
484            merge_logs: false,
485            channel: false,
486            stdin: false,
487            wait_ready: false,
488            reuse_port: false,
489            readiness_probe: None,
490            liveness_probe: None,
491            watch_options: Vec::new(),
492            cron_timezone: None,
493            increment_var: None,
494        }
495    }
496}
497
498impl AppConfig {
499    /// A minimal config with spec defaults, the programmatic entry point.
500    #[must_use]
501    pub fn minimal(name: &str, script: &str) -> Self {
502        Self {
503            name: name.to_string(),
504            script: script.to_string(),
505            ..Self::default()
506        }
507    }
508
509    /// The names of the fields whose values differ between `self` and
510    /// `other`, in field-name order.
511    ///
512    /// Names only, never values. The one caller sends this list across the
513    /// wire to be printed at an operator, and [`AppConfig::env`] carries
514    /// secrets, so a differing `env` reports `"env"` and stops there.
515    ///
516    /// Compare configs that have both been through
517    /// [`normalize`](fn@crate::config::normalize). Two configs differing only
518    /// in what normalization would have filled in are not a difference an
519    /// operator can act on, and reporting them would make the caller noisy
520    /// about nothing.
521    ///
522    /// # Example
523    ///
524    /// ```
525    /// use shep_core::config::AppConfig;
526    ///
527    /// let stored = AppConfig::minimal("web", "./srv");
528    /// let mut edited = stored.clone();
529    /// edited.cwd = Some("/srv".to_string());
530    ///
531    /// assert_eq!(stored.drifted_fields(&edited), vec!["cwd".to_string()]);
532    /// assert!(stored.drifted_fields(&stored).is_empty());
533    /// ```
534    #[must_use]
535    pub fn drifted_fields(&self, other: &Self) -> Vec<String> {
536        if self == other {
537            return Vec::new();
538        }
539        // Serde-compared, not field by field: a new field needs no edit here.
540        // Sorted since `serde_json::Map` is a `BTreeMap` only while
541        // `preserve_order` is off crate-wide. An empty result means no
542        // drift, or none could be computed.
543        let (Ok(serde_json::Value::Object(mine)), Ok(serde_json::Value::Object(theirs))) =
544            (serde_json::to_value(self), serde_json::to_value(other))
545        else {
546            return Vec::new();
547        };
548        let mut fields: Vec<String> = mine
549            .iter()
550            .filter(|(key, value)| theirs.get(key.as_str()) != Some(value))
551            .map(|(key, _)| key.clone())
552            .collect();
553        fields.sort_unstable();
554        fields
555    }
556}
557
558#[cfg(test)]
559mod tests {
560    use super::*;
561    use crate::values::{MemSize, UpDuration};
562
563    #[test]
564    fn minimal_config_gets_spec_defaults() {
565        let app = AppConfig::minimal("web", "./server");
566        assert_eq!(app.name, "web");
567        assert_eq!(app.script, "./server");
568        assert!(app.autorestart);
569        assert!(app.autostart);
570        assert_eq!(app.instances, 1);
571        assert_eq!(app.min_uptime, UpDuration::from_millis(1000));
572        assert_eq!(app.max_restarts, 16);
573        assert_eq!(app.kill_timeout, UpDuration::from_millis(1600));
574        assert_eq!(app.listen_timeout, UpDuration::from_millis(3000));
575        assert_eq!(app.graceful_timeout, UpDuration::from_millis(8000));
576        assert_eq!(app.action_timeout, UpDuration::from_millis(3000));
577        assert!(app.max_memory.is_none());
578        assert!(app.fold.is_none());
579        assert!(!app.channel);
580    }
581
582    #[test]
583    fn unstable_restarts_are_throttled_by_default() {
584        let app = AppConfig::minimal("web", "./srv");
585        assert_eq!(
586            app.exp_backoff_restart_delay,
587            Some(UpDuration::from_millis(100))
588        );
589    }
590
591    #[test]
592    fn stdin_is_not_piped_unless_the_app_asks() {
593        let app = AppConfig::minimal("web", "./srv");
594        assert!(!app.stdin);
595        let parsed: AppConfig = toml::from_str("name = \"web\"\nscript = \"./srv\"").unwrap();
596        assert!(!parsed.stdin);
597    }
598
599    #[test]
600    fn the_flockfile_key_is_stdin() {
601        let parsed: AppConfig =
602            toml::from_str("name = \"web\"\nscript = \"./srv\"\nstdin = true").unwrap();
603        assert!(parsed.stdin);
604    }
605
606    #[test]
607    fn toml_round_trip_with_newtypes() {
608        let toml_src = r#"
609name = "worker"
610script = "python3"
611args = ["job.py", "--fast"]
612max_memory = "512M"
613min_uptime = "5s"
614fold = "backend"
615env = { RUST_LOG = "info" }
616"#;
617        let app: AppConfig = toml::from_str(toml_src).unwrap();
618        assert_eq!(app.max_memory, Some("512M".parse::<MemSize>().unwrap()));
619        assert_eq!(app.min_uptime, UpDuration::from_millis(5000));
620        assert_eq!(app.fold.as_deref(), Some("backend"));
621        assert_eq!(app.env.get("RUST_LOG").map(String::as_str), Some("info"));
622        assert_eq!(app.args, vec!["job.py", "--fast"]);
623    }
624
625    #[test]
626    fn unknown_fields_are_rejected() {
627        let err = toml::from_str::<AppConfig>(
628            "name = \"x\"\nscript = \"y\"\nmax_memory_restart = \"1G\"",
629        )
630        .unwrap_err();
631        assert!(err.to_string().contains("max_memory_restart"), "{err}");
632    }
633
634    #[test]
635    fn probe_config_parses_with_defaults() {
636        let src = r#"
637name = "api"
638script = "./api"
639
640[readiness_probe]
641kind = "http"
642target = "http://127.0.0.1:8080/healthz"
643"#;
644        let app: AppConfig = toml::from_str(src).unwrap();
645        let probe = app.readiness_probe.unwrap();
646        assert_eq!(probe.kind, ProbeKind::Http);
647        assert_eq!(probe.target, "http://127.0.0.1:8080/healthz");
648        assert_eq!(probe.interval, UpDuration::from_millis(10_000));
649        assert_eq!(probe.timeout, UpDuration::from_millis(5_000));
650        assert_eq!(probe.failure_threshold, 3);
651        assert!(app.liveness_probe.is_none());
652    }
653
654    #[test]
655    fn debug_redacts_env_values() {
656        // Exact string pinned so a lazy derive(Debug) refactor fails here.
657        let mut app = AppConfig::minimal("web", "./srv");
658        app.env
659            .insert("DATABASE_URL".to_string(), "postgres://secret".to_string());
660        app.env.insert("RUST_LOG".to_string(), "info".to_string());
661        assert_eq!(
662            format!("{app:?}"),
663            "AppConfig { name: \"web\", script: \"./srv\", env: <2 vars>, .. }"
664        );
665    }
666
667    #[test]
668    fn an_unedited_config_has_drifted_in_no_field() {
669        let app = AppConfig::minimal("web", "./srv");
670
671        assert!(app.drifted_fields(&app.clone()).is_empty());
672    }
673
674    #[test]
675    fn drift_names_every_edited_field_and_no_other() {
676        // Two fields, not one, so a comparator that stopped at the first
677        // difference fails here.
678        let stored = AppConfig::minimal("proto-api", "./proto-enum-api");
679        let mut edited = stored.clone();
680        edited.cwd = Some("/srv/pogo-proto-api".to_string());
681        edited.args = vec!["-config".to_string(), "config.toml".to_string()];
682
683        assert_eq!(
684            stored.drifted_fields(&edited),
685            vec!["args".to_string(), "cwd".to_string()]
686        );
687    }
688
689    #[test]
690    fn drift_reports_env_by_name_and_never_by_value() {
691        let stored = AppConfig::minimal("web", "./srv");
692        let mut edited = stored.clone();
693        edited
694            .env
695            .insert("DATABASE_URL".to_string(), "postgres://hunter2".to_string());
696
697        let fields = edited.drifted_fields(&stored);
698
699        assert_eq!(fields, vec!["env".to_string()]);
700        // Names go to an operator; a value never should.
701        assert!(!fields.concat().contains("hunter2"));
702    }
703
704    #[test]
705    fn drift_is_symmetric() {
706        let stored = AppConfig::minimal("web", "./srv");
707        let mut edited = stored.clone();
708        edited.instances = 4;
709
710        assert_eq!(
711            stored.drifted_fields(&edited),
712            edited.drifted_fields(&stored)
713        );
714        assert_eq!(
715            stored.drifted_fields(&edited),
716            vec!["instances".to_string()]
717        );
718    }
719}
shep_core/config/app.rs

shep_core/config/
app.rs
