kellnr_settings/
docs.rs

1use provcfg::{ClapArgs, Configurable};
2use serde::{Deserialize, Serialize};
3use utoipa::ToSchema;
4
5#[derive(Debug, Deserialize, Serialize, Eq, PartialEq, Clone, Configurable, ClapArgs, ToSchema)]
6#[serde(default)]
7#[configurable(clap_prefix = "docs")]
8pub struct Docs {
9    /// Enable documentation hosting
10    ///
11    /// Building docs runs the build scripts and proc macros of every
12    /// published crate on the Kellnr host. See `build_wrapper` before
13    /// enabling this for publishers you do not fully trust.
14    pub enabled: bool,
15
16    /// Max docs size in MB
17    pub max_size: usize,
18
19    /// Max duration of a single rustdoc build in seconds (0 = unlimited).
20    /// Builds that take longer are killed and the crate is skipped.
21    pub build_timeout_seconds: u64,
22
23    /// Command prefix (comma-separated) for the rustdoc build process.
24    ///
25    /// Building docs compiles the published crate, which runs its build
26    /// scripts and proc macros. Kellnr runs every build in a child process
27    /// with a cleared environment, so no `KELLNR_*` settings or secrets are
28    /// passed on. Cargo's own `CARGO_*` variables are kept, so a registry
29    /// token in `CARGO_REGISTRIES_<NAME>_TOKEN` is visible to build scripts
30    /// and should belong to a dedicated read-only user.
31    /// The build still runs as the Kellnr user: it can read every
32    /// file Kellnr can read (for example the config file or the `SQLite`
33    /// database, e.g. via `include_str!`) and it has network access. Kellnr
34    /// only publishes the files rustdoc generates, but the build can write
35    /// such content into the generated docs of the crate. Only enable docs
36    /// for crates you trust, or set a wrapper that confines the build, e.g.
37    /// with bubblewrap:
38    /// `["bwrap", "--ro-bind", "/", "/", "--tmpfs", "<data_dir>",
39    /// "--bind", "<data_dir>/doc_queue", "<data_dir>/doc_queue",
40    /// "--bind", "<cargo_home>", "<cargo_home>", "--tmpfs", "/etc/kellnr",
41    /// "--dev", "/dev", "--proc", "/proc", "--tmpfs", "/tmp",
42    /// "--unshare-pid", "--die-with-parent", "--"]`.
43    /// The wrapper is followed by the Kellnr binary and its arguments.
44    #[configurable(env_list)]
45    #[arg(value_delimiter = ',')]
46    pub build_wrapper: Vec<String>,
47}
48
49impl Default for Docs {
50    fn default() -> Self {
51        Self {
52            enabled: false,
53            max_size: 100,
54            build_timeout_seconds: 1800,
55            build_wrapper: Vec::new(),
56        }
57    }
58}
59
60impl Docs {
61    /// `max_size` in bytes.
62    pub fn max_bytes(&self) -> usize {
63        crate::registry::mb_to_bytes(self.max_size)
64    }
65}
kellnr_settings/docs.rs

kellnr_settings/
docs.rs
