Skip to main content

datumesh_http/
config.rs

1//! The mesh's configuration: [`Config`], from code or from the environment
2//! ([`Config::from_env`]).
3//!
4//! Secrets never come from here directly: the signing key and the API keys are read from
5//! files that must have mode 0600 ([`read_secret_file`]).
6
7use std::collections::BTreeMap;
8use std::fmt;
9use std::path::Path;
10use std::time::Duration;
11
12use datumesh_core::json::{self, Value};
13use datumesh_core::lexical;
14
15use crate::apikeys::ApiKeys;
16
17/// The default wall-clock budget of a request before it is answered `pending` (SPEC 5.5).
18pub const DEFAULT_BUDGET: Duration = Duration::from_secs(1);
19/// The default size of the blocking pool, which is the concurrency limit of evaluation and
20/// store access (see the crate documentation for why).
21pub const DEFAULT_POOL_SIZE: usize = 32;
22/// The default bound on a `POST /cells` batch.
23pub const DEFAULT_BATCH_MAX: usize = 1000;
24/// The default number of members in one JSON page of `GET /slice`.
25pub const DEFAULT_SLICE_PAGE: usize = 1000;
26/// The bound on a JSON page of `GET /slice` (`limit=`).
27pub const MAX_SLICE_PAGE: usize = 10_000;
28/// The bound on the members of a slice served (SPEC 10.1: a manifest has at most 1,048,576).
29pub const MAX_SLICE_MEMBERS: usize = 1_048_576;
30
31/// Rate limits (token buckets), per minute. Refused requests are answered `rate_limited`
32/// with `retry_after_seconds` and `Retry-After`; nothing is ever queued.
33#[non_exhaustive]
34#[derive(Clone, Debug, PartialEq, Eq)]
35pub struct RateLimits {
36    /// Whether limits apply at all (default true).
37    pub enabled: bool,
38    /// Requests per minute per client IP without an API key (default 60).
39    pub per_ip: u32,
40    /// The burst per IP: the bucket's capacity (default 120).
41    pub ip_burst: u32,
42    /// Requests per minute per API key, unless the key's own line says otherwise (default
43    /// 600; the burst is the same number).
44    pub per_key: u32,
45    /// `POST /verify` per minute per IP, with or without a key (default 60; burst the same).
46    pub verify_per_ip: u32,
47    /// `POST /x/calc` per minute per IP, with or without a key (default 30; burst the same). Its
48    /// own bucket, taken after the per-IP limit (Build 2 Part 3, `calc`).
49    pub calc_per_ip: u32,
50    /// Cells per request token in a `POST /cells` batch (default 50: a batch of 1,000 cells
51    /// counts as 20 requests).
52    pub batch_cells_per_token: u32,
53    /// `/series` pages per minute per IP, besides the per-IP limit (`DATUMESH_RATE_SERIES_PER_IP`,
54    /// default 30; burst the same), so that a crawler that misses the cache cannot load the mesh.
55    pub series_per_ip: u32,
56    /// `POST /x/keys` per minute per IP, besides the per-IP limit (`DATUMESH_RATE_KEYS_PER_IP`, default 5;
57    /// burst the same). Every `POST` counts, whatever its outcome (QUESTIONS-build2 D39).
58    pub keys_per_ip: u32,
59}
60
61impl Default for RateLimits {
62    fn default() -> Self {
63        RateLimits {
64            enabled: true,
65            per_ip: 60,
66            ip_burst: 120,
67            per_key: 600,
68            verify_per_ip: 60,
69            calc_per_ip: 30,
70            batch_cells_per_token: 50,
71            series_per_ip: 30,
72            keys_per_ip: 5,
73        }
74    }
75}
76
77/// Cache lifetimes. Content-addressed objects (descriptors, receipts, manifests, blobs) never
78/// expire: their bytes are fixed by their hash.
79#[non_exhaustive]
80#[derive(Clone, Debug, PartialEq, Eq)]
81pub struct Ttls {
82    /// A foreign host's key document (default 300 s). A receipt signed with a key id the
83    /// cached document lacks refetches it at once (at most every `key_refetch`).
84    pub key_doc: Duration,
85    /// The shortest interval between two fetches of one host's key document (default 10 s).
86    pub key_refetch: Duration,
87    /// A foreign host's mesh document (default 300 s).
88    pub mesh_doc: Duration,
89    /// How long a foreign name's binding, confirmed with its mesh, stands for requests
90    /// without an asof or with a later one (default 60 s).
91    pub binding: Duration,
92    /// How long a foreign cell's latest version, confirmed with its mesh, stands for requests
93    /// without an asof or with a later one (default 60 s).
94    pub current: Duration,
95    /// `max-age` of answers to requests without an asof (default 10 s).
96    pub latest_max_age: Duration,
97    /// How long a completed job's result is kept after it is first served, and after it
98    /// completes when it is never served, while the mesh runs (default and minimum 300 s, SPEC 5.5).
99    pub job: Duration,
100}
101
102impl Default for Ttls {
103    fn default() -> Self {
104        Ttls {
105            key_doc: Duration::from_secs(300),
106            key_refetch: Duration::from_secs(10),
107            mesh_doc: Duration::from_secs(300),
108            binding: Duration::from_secs(60),
109            current: Duration::from_secs(60),
110            latest_max_age: Duration::from_secs(10),
111            job: Duration::from_secs(300),
112        }
113    }
114}
115
116/// What a function's cells need (the licence and payment stubs of step 1.4).
117#[non_exhaustive]
118#[derive(Clone, Debug, PartialEq, Eq)]
119pub enum Rule {
120    /// Only these principals (API key owners) may receive the function's cells; anyone
121    /// else is answered `unlicensed`.
122    Principals(Vec<String>),
123    /// The function's cells are sold: `payment_required` with this quote (a stub until
124    /// prepaid balances, 3.3).
125    Price {
126        /// The amount (SPEC 3.1, greater than zero).
127        amount: String,
128        /// A currency code of `units.md`.
129        currency: String,
130    },
131}
132
133/// Per-function rules, by fully qualified function name. Functions without one are free.
134#[non_exhaustive]
135#[derive(Clone, Debug, Default, PartialEq, Eq)]
136pub struct Policy {
137    /// The rules.
138    pub rules: BTreeMap<String, Rule>,
139}
140
141impl Policy {
142    /// The rule of a function, if any.
143    pub fn rule(&self, fn_name: &str) -> Option<&Rule> {
144        self.rules.get(fn_name)
145    }
146
147    /// From JSON: `{"<function>": {"principals": ["..."]} | {"price": {"amount", "currency"}}}`.
148    pub fn from_json(bytes: &[u8]) -> Result<Policy, ConfigError> {
149        let v = json::parse(bytes).map_err(|e| ConfigError::new("policy", e.to_string()))?;
150        let mut rules = BTreeMap::new();
151        for (name, r) in v.as_object().ok_or_else(|| ConfigError::new("policy", "not an object"))? {
152            lexical::check_function_name(name, "$").map_err(|e| ConfigError::new("policy", e.to_string()))?;
153            let rule = if let Some(Value::Array(ps)) = r.get("principals") {
154                Rule::Principals(
155                    ps.iter()
156                        .map(|p| p.as_str().map(str::to_string).ok_or_else(|| ConfigError::new("policy", "principal")))
157                        .collect::<Result<_, _>>()?,
158                )
159            } else if let Some(p) = r.get("price") {
160                let amount =
161                    p.get("amount").and_then(Value::as_str).ok_or_else(|| ConfigError::new("policy", "amount"))?;
162                let currency =
163                    p.get("currency").and_then(Value::as_str).ok_or_else(|| ConfigError::new("policy", "currency"))?;
164                lexical::check_number(amount, "$").map_err(|e| ConfigError::new("policy", e.to_string()))?;
165                if amount.starts_with('-') || amount == "0" || !lexical::is_currency(currency) {
166                    return Err(ConfigError::new("policy", format!("price of {name}")));
167                }
168                Rule::Price { amount: amount.to_string(), currency: currency.to_string() }
169            } else {
170                return Err(ConfigError::new("policy", format!("rule of {name}")));
171            };
172            rules.insert(name.clone(), rule);
173        }
174        Ok(Policy { rules })
175    }
176}
177
178/// The mesh's configuration.
179#[non_exhaustive]
180#[derive(Clone, Debug)]
181pub struct Config {
182    /// The DNS name the mesh signs as (`computed_by`) and serves on: `https://<host>/...`
183    /// (e.g. `mesh-test.datumesh.com`), unless [`Config::base_url`] says otherwise.
184    pub host: String,
185    /// Where the mesh is served when not at `https://<host>`, e.g. `http://127.0.0.1:8787`
186    /// for a mesh on this machine (default: none): the base of every URL in the mesh
187    /// document (`bindings` and the endpoints, [`crate::Mesh::mesh_document`]). `https://`
188    /// with any host; `http://` only when the mesh's `host` is unrooted (its last label is
189    /// `invalid`, SPEC 2.5, e.g. `local.invalid`) and only with `127.0.0.1`, `[::1]` or
190    /// `localhost`; an optional port; no path, query, fragment or trailing slash
191    /// ([`check_base_url`]; [`crate::MeshBuilder::build`] refuses another with
192    /// [`crate::BuildError::BaseUrl`]).
193    ///
194    /// An `http://` mesh document is for local use only: it is not valid under spec-0.4.3
195    /// (9.6 wants `https://` URLs on the host), and core 0.3.6's `resolve_mesh` refuses it.
196    /// spec-0.4.4 will allow exactly this: for an unrooted host, mesh-document URLs and
197    /// `poll` may be `http://` on a loopback address only (`127.0.0.1`, `[::1]`,
198    /// `localhost`); rooted hosts stay `https://`-only. datumesh-core 0.3.8 will accept it.
199    /// The key document and `host` do not change, nor do the URLs in envelopes and headers
200    /// (a `pending` envelope's `poll`, a page's `next`, the `canonical` link), which stay
201    /// [`Config::origin`]: SPEC 5.5 makes `poll` an `https://` URL, and a client maps
202    /// `https://<host>/` onto where it reaches the mesh (its peers).
203    pub base_url: Option<String>,
204    /// The hosts whose names this mesh owns (default: `host`). A name under any other host
205    /// is resolved across meshes.
206    pub namespaces: Vec<String>,
207    /// The wall-clock budget of a request before it is answered `pending` (default 1 s).
208    pub budget: Duration,
209    /// The blocking pool's size: the concurrency limit (default 32).
210    pub pool_size: usize,
211    /// The most cells in one `POST /cells` (default 1,000).
212    pub batch_max: usize,
213    /// Whether each held test is a signed cell (trust `primary`) `<host>/test_case(function_hash, case)` (E5:
214    /// `DATUMESH_TEST_CELLS=1`, mesh-test). Off on production: no test cells until named.
215    pub test_cells: bool,
216    /// The default JSON page of `GET /slice` (default 1,000; at most 10,000 with `limit=`).
217    pub slice_page: usize,
218    /// The most members one slice read serves (default 1,048,576).
219    pub slice_max: usize,
220    /// The depth of `GET /explain` by default (default 4; at most 16 with `depth=`).
221    pub explain_depth: usize,
222    /// The most jobs held at once, running or done (default 10,000).
223    pub max_jobs: usize,
224    /// Rate limits.
225    pub rate: RateLimits,
226    /// Cache lifetimes.
227    pub ttl: Ttls,
228    /// Take the client IP from the last `X-Forwarded-For` entry (behind Caddy) instead of
229    /// the peer address (default false).
230    pub trust_proxy: bool,
231    /// Resolve names under hosts this mesh does not own (default true).
232    pub cross_mesh: bool,
233    /// When set, the only other hosts whose names are resolved across meshes; names under
234    /// any other host are not served (`not_covered`). Default: every host.
235    pub cross_mesh_hosts: Option<Vec<String>>,
236    /// Origins to use instead of `https://<host>` for some hosts, e.g. `mesh-b.example` ->
237    /// `http://127.0.0.1:8081` (tests and private networks only; the default is none).
238    pub peers: BTreeMap<String, String>,
239    /// The time limit of one request to another mesh (default 10 s; SPEC 9.3's bound).
240    pub peer_timeout: Duration,
241    /// Short names of the call syntax: `@alias` -> fully qualified name.
242    pub aliases: BTreeMap<String, String>,
243    /// Licence and payment rules.
244    pub policy: Policy,
245    /// Descriptions of the functions `GET /find` searches (name -> description).
246    pub catalog: BTreeMap<String, String>,
247    /// The embedding service's base URL (`DATUMESH_EMBED_URL`, e.g. `http://embed:8080`): vector
248    /// `find` is on when it is set and the store has vectors (default none). Since 0.4.0.
249    pub embed_url: Option<String>,
250    /// API keys (`Authorization: Bearer dm_...`).
251    pub api_keys: ApiKeys,
252    /// The hosts that may publish with `POST /bundles` besides the mesh's own namespaces
253    /// (`DATUMESH_PUBLISH_DOMAINS`; Build 2 Part 4, D11). Default: none.
254    pub publish_domains: PublishDomains,
255    /// Where the operator's log of `POST /bundles` goes (`DATUMESH_LOG_DIR`, the file
256    /// `bundles.log` in it); default none, no log.
257    pub log_dir: Option<std::path::PathBuf>,
258    /// The series with month or year pages (`DATUMESH_SERIES_FILE`, Build 2 Part 6); none: no pages.
259    pub(crate) series: Vec<crate::series::SeriesPage>,
260    /// Whether a key of a publisher can be registered for a namespace of its own: `DATUMESH_KEY_NAMES=1`
261    /// turns `GET /x/keys/challenge` and `POST /x/keys` on (QUESTIONS-build2 D39). Default off; any other
262    /// value is off too.
263    pub key_names: bool,
264    /// How long a registration challenge is valid (`DATUMESH_KEY_CHALLENGE_TTL_SECS`; default 300 s).
265    pub key_challenge_ttl: Duration,
266    /// The address the takeover page names for a source that wants to take over (`DATUMESH_CONTACT`,
267    /// D40). Default none: the page names no address.
268    pub contact: Option<String>,
269    /// How long the first build of the series overview waits after start (`DATUMESH_SERIES_FIRST_BUILD_DELAY_SECS`;
270    /// default 0). Until that build is done the sitemap and the index answer `503`.
271    pub series_first_build_delay: Duration,
272    /// How often the series overview is rebuilt (`DATUMESH_SERIES_REFRESH_SECS`; default 300 s, at least 1 s).
273    pub series_refresh: Duration,
274    /// How long the first build of the object index (`describe` of an object id) waits after start
275    /// (`DATUMESH_INDEX_FIRST_BUILD_DELAY_SECS`; default 0). Until it is built, such a request is `503`.
276    pub index_first_build_delay: Duration,
277    /// How long the first build of the `find` summary and the empty query waits after start
278    /// (`DATUMESH_FIND_FIRST_BUILD_DELAY_SECS`; default 0). Until it is built, those requests are `503`.
279    pub find_first_build_delay: Duration,
280    /// How often the value counts of the catalogue are refreshed (`DATUMESH_VALUE_COUNTS_SECS`; default 3600 s,
281    /// at least 1 s; and once at start).
282    pub value_counts_refresh: Duration,
283    /// The most distinct values a string key takes from the cells of a function before it is open
284    /// (`DATUMESH_DICTIONARY_MAX`; default 1000, at least 1; CONTRACT-0.4.9 H7).
285    pub dictionary_max: usize,
286}
287
288/// Which hosts may publish with `POST /bundles` (`DATUMESH_PUBLISH_DOMAINS`): the mesh's own
289/// namespaces always; then none (the default), named hosts, or any host with a valid key
290/// document (`*`).
291#[non_exhaustive]
292#[derive(Clone, Debug, PartialEq, Eq, Default)]
293pub enum PublishDomains {
294    /// The mesh's own namespaces only.
295    #[default]
296    Own,
297    /// These hosts, besides the mesh's own namespaces.
298    Hosts(Vec<String>),
299    /// Any host whose key document the mesh can check.
300    Any,
301}
302
303impl PublishDomains {
304    /// Parses the variable's value: empty is `Own`, `*` is `Any`, else a comma-separated list of
305    /// hosts (spaces allowed).
306    pub fn parse(v: &str) -> Result<PublishDomains, ConfigError> {
307        let v = v.trim();
308        if v.is_empty() {
309            return Ok(PublishDomains::Own);
310        }
311        if v == "*" {
312            return Ok(PublishDomains::Any);
313        }
314        let mut hosts = Vec::new();
315        for h in v.split(',').map(str::trim).filter(|h| !h.is_empty()) {
316            lexical::check_dns_name(h, "$").map_err(|e| ConfigError::new("DATUMESH_PUBLISH_DOMAINS", e.to_string()))?;
317            hosts.push(h.to_string());
318        }
319        Ok(if hosts.is_empty() { PublishDomains::Own } else { PublishDomains::Hosts(hosts) })
320    }
321
322    /// Whether a bundle of `host` (not one of the mesh's own namespaces) may be published.
323    pub fn allows(&self, host: &str) -> bool {
324        match self {
325            PublishDomains::Own => false,
326            PublishDomains::Hosts(h) => h.iter().any(|x| x == host),
327            PublishDomains::Any => true,
328        }
329    }
330}
331
332impl Config {
333    /// The defaults for a mesh signing as `host`.
334    pub fn new(host: impl Into<String>) -> Config {
335        let host = host.into();
336        Config {
337            namespaces: vec![host.clone()],
338            host,
339            base_url: None,
340            budget: DEFAULT_BUDGET,
341            pool_size: DEFAULT_POOL_SIZE,
342            batch_max: DEFAULT_BATCH_MAX,
343            test_cells: false,
344            slice_page: DEFAULT_SLICE_PAGE,
345            slice_max: MAX_SLICE_MEMBERS,
346            explain_depth: 4,
347            max_jobs: 10_000,
348            rate: RateLimits::default(),
349            ttl: Ttls::default(),
350            trust_proxy: false,
351            cross_mesh: true,
352            cross_mesh_hosts: None,
353            peers: BTreeMap::new(),
354            peer_timeout: Duration::from_secs(10),
355            aliases: BTreeMap::new(),
356            policy: Policy::default(),
357            catalog: BTreeMap::new(),
358            embed_url: None,
359            api_keys: ApiKeys::default(),
360            publish_domains: PublishDomains::Own,
361            key_names: false,
362            key_challenge_ttl: Duration::from_secs(300),
363            contact: None,
364            series_first_build_delay: Duration::ZERO,
365            series_refresh: Duration::from_secs(300),
366            index_first_build_delay: Duration::ZERO,
367            find_first_build_delay: Duration::ZERO,
368            value_counts_refresh: Duration::from_secs(3600),
369            dictionary_max: 1000,
370            log_dir: None,
371            series: Vec::new(),
372        }
373    }
374
375    /// The configuration with this base URL ([`Config::base_url`]); it is checked when the
376    /// mesh is built.
377    pub fn with_base_url(mut self, url: impl Into<String>) -> Config {
378        self.base_url = Some(url.into());
379        self
380    }
381
382    /// The configuration from the environment (`DATUMESH_*`; the README lists them). The
383    /// files named (`DATUMESH_API_KEYS_FILE`, and the others) are read here; the API keys
384    /// file must have mode 0600.
385    pub fn from_env() -> Result<Config, ConfigError> {
386        Config::from_vars(|k| std::env::var(k).ok())
387    }
388
389    /// The configuration from variables `get` answers, as [`Config::from_env`] reads them.
390    pub fn from_vars(get: impl Fn(&str) -> Option<String>) -> Result<Config, ConfigError> {
391        let host = get("DATUMESH_HOST").ok_or_else(|| ConfigError::new("DATUMESH_HOST", "not set"))?;
392        let mut c = Config::new(host);
393        if let Some(v) = get("DATUMESH_BASE_URL").filter(|v| !v.is_empty()) {
394            c.base_url = Some(v);
395        }
396        if let Some(v) = get("DATUMESH_NAMESPACES") {
397            c.namespaces = v.split(',').map(|s| s.trim().to_string()).filter(|s| !s.is_empty()).collect();
398        }
399        let ms = |k: &str, d: Duration| -> Result<Duration, ConfigError> {
400            match get(k) {
401                Some(v) => v.parse::<u64>().map(Duration::from_millis).map_err(|e| ConfigError::new(k, e.to_string())),
402                None => Ok(d),
403            }
404        };
405        let secs = |k: &str, d: Duration| -> Result<Duration, ConfigError> {
406            match get(k) {
407                Some(v) => v.parse::<u64>().map(Duration::from_secs).map_err(|e| ConfigError::new(k, e.to_string())),
408                None => Ok(d),
409            }
410        };
411        let num = |k: &str, d: usize| -> Result<usize, ConfigError> {
412            match get(k) {
413                Some(v) => v.parse::<usize>().map_err(|e| ConfigError::new(k, e.to_string())),
414                None => Ok(d),
415            }
416        };
417        let flag = |k: &str, d: bool| -> Result<bool, ConfigError> {
418            match get(k).as_deref() {
419                None => Ok(d),
420                Some("1" | "true" | "yes") => Ok(true),
421                Some("0" | "false" | "no") => Ok(false),
422                Some(v) => Err(ConfigError::new(k, format!("not a boolean: {v}"))),
423            }
424        };
425        c.budget = ms("DATUMESH_BUDGET_MS", c.budget)?;
426        c.pool_size = num("DATUMESH_POOL_SIZE", c.pool_size)?;
427        c.batch_max = num("DATUMESH_BATCH_MAX", c.batch_max)?;
428        c.test_cells = flag("DATUMESH_TEST_CELLS", c.test_cells)?;
429        c.slice_page = num("DATUMESH_SLICE_PAGE", c.slice_page)?;
430        c.slice_max = num("DATUMESH_SLICE_MAX", c.slice_max)?;
431        c.explain_depth = num("DATUMESH_EXPLAIN_DEPTH", c.explain_depth)?;
432        c.max_jobs = num("DATUMESH_MAX_JOBS", c.max_jobs)?;
433        c.trust_proxy = flag("DATUMESH_TRUST_PROXY", c.trust_proxy)?;
434        c.cross_mesh = flag("DATUMESH_CROSS_MESH", c.cross_mesh)?;
435        c.rate.enabled = flag("DATUMESH_RATE_LIMITS", c.rate.enabled)?;
436        c.rate.per_ip = num("DATUMESH_RATE_PER_IP", c.rate.per_ip as usize)? as u32;
437        c.rate.ip_burst = num("DATUMESH_RATE_IP_BURST", c.rate.ip_burst as usize)? as u32;
438        c.rate.per_key = num("DATUMESH_RATE_PER_KEY", c.rate.per_key as usize)? as u32;
439        c.rate.verify_per_ip = num("DATUMESH_RATE_VERIFY_PER_IP", c.rate.verify_per_ip as usize)? as u32;
440        c.rate.series_per_ip = num("DATUMESH_RATE_SERIES_PER_IP", c.rate.series_per_ip as usize)? as u32;
441        c.rate.calc_per_ip = num("DATUMESH_RATE_CALC_PER_IP", c.rate.calc_per_ip as usize)? as u32;
442        c.rate.keys_per_ip = num("DATUMESH_RATE_KEYS_PER_IP", c.rate.keys_per_ip as usize)? as u32;
443        // Off unless exactly `1` (an empty or other value is off too, not an error).
444        c.key_names = get("DATUMESH_KEY_NAMES").as_deref() == Some("1");
445        c.key_challenge_ttl = secs("DATUMESH_KEY_CHALLENGE_TTL_SECS", c.key_challenge_ttl)?;
446        c.contact = get("DATUMESH_CONTACT").map(|v| v.trim().to_string()).filter(|v| !v.is_empty());
447        c.series_first_build_delay = secs("DATUMESH_SERIES_FIRST_BUILD_DELAY_SECS", c.series_first_build_delay)?;
448        c.series_refresh = secs("DATUMESH_SERIES_REFRESH_SECS", c.series_refresh)?;
449        c.index_first_build_delay = secs("DATUMESH_INDEX_FIRST_BUILD_DELAY_SECS", c.index_first_build_delay)?;
450        c.find_first_build_delay = secs("DATUMESH_FIND_FIRST_BUILD_DELAY_SECS", c.find_first_build_delay)?;
451        c.value_counts_refresh = secs("DATUMESH_VALUE_COUNTS_SECS", c.value_counts_refresh)?;
452        c.dictionary_max = num("DATUMESH_DICTIONARY_MAX", c.dictionary_max)?;
453        c.ttl.key_doc = secs("DATUMESH_TTL_KEY_DOC", c.ttl.key_doc)?;
454        c.ttl.mesh_doc = secs("DATUMESH_TTL_MESH_DOC", c.ttl.mesh_doc)?;
455        c.ttl.binding = secs("DATUMESH_TTL_BINDING", c.ttl.binding)?;
456        c.ttl.current = secs("DATUMESH_TTL_CURRENT", c.ttl.current)?;
457        c.ttl.latest_max_age = secs("DATUMESH_LATEST_MAX_AGE", c.ttl.latest_max_age)?;
458        c.ttl.job = secs("DATUMESH_JOB_TTL", c.ttl.job)?;
459        c.peer_timeout = ms("DATUMESH_PEER_TIMEOUT_MS", c.peer_timeout)?;
460        if let Some(v) = get("DATUMESH_CROSS_MESH_HOSTS") {
461            c.cross_mesh_hosts = Some(v.split(',').map(|s| s.trim().to_string()).filter(|s| !s.is_empty()).collect());
462        }
463        if let Some(v) = get("DATUMESH_PEERS") {
464            for pair in v.split(',').map(str::trim).filter(|s| !s.is_empty()) {
465                let (h, o) =
466                    pair.split_once('=').ok_or_else(|| ConfigError::new("DATUMESH_PEERS", "host=origin pairs"))?;
467                c.peers.insert(h.trim().to_string(), o.trim().trim_end_matches('/').to_string());
468            }
469        }
470        if let Some(p) = get("DATUMESH_ALIASES_FILE") {
471            c.aliases = string_map(&read_file(&p)?, "DATUMESH_ALIASES_FILE")?;
472        }
473        if let Some(p) = get("DATUMESH_CATALOG_FILE") {
474            c.catalog = string_map(&read_file(&p)?, "DATUMESH_CATALOG_FILE")?;
475        }
476        if let Some(v) = get("DATUMESH_EMBED_URL").filter(|v| !v.trim().is_empty()) {
477            c.embed_url = Some(v.trim().trim_end_matches('/').to_string());
478        }
479        if let Some(p) = get("DATUMESH_POLICY_FILE") {
480            c.policy = Policy::from_json(&read_file(&p)?)?;
481        }
482        if let Some(p) = get("DATUMESH_API_KEYS_FILE") {
483            c.api_keys = ApiKeys::parse(&read_secret_file(Path::new(&p))?)?;
484        }
485        c.publish_domains = PublishDomains::parse(&get("DATUMESH_PUBLISH_DOMAINS").unwrap_or_default())?;
486        if let Some(p) = get("DATUMESH_SERIES_FILE").filter(|p| !p.trim().is_empty()) {
487            c.series = crate::series::parse(&read_file(&p)?)?;
488        }
489        if let Some(d) = get("DATUMESH_LOG_DIR").filter(|d| !d.trim().is_empty()) {
490            c.log_dir = Some(std::path::PathBuf::from(d));
491        }
492        c.check()?;
493        Ok(c)
494    }
495
496    /// Checks the configuration: names are DNS names and function names, the base URL is
497    /// one ([`check_base_url`]), numbers in range.
498    pub fn check(&self) -> Result<(), ConfigError> {
499        lexical::check_dns_name(&self.host, "$").map_err(|e| ConfigError::new("host", e.to_string()))?;
500        if self.series_refresh < Duration::from_secs(1) {
501            return Err(ConfigError::new("DATUMESH_SERIES_REFRESH_SECS", "at least 1 second"));
502        }
503        if self.value_counts_refresh < Duration::from_secs(1) {
504            return Err(ConfigError::new("DATUMESH_VALUE_COUNTS_SECS", "at least 1 second"));
505        }
506        if self.dictionary_max == 0 {
507            return Err(ConfigError::new("DATUMESH_DICTIONARY_MAX", "at least 1"));
508        }
509        if let Some(c) = &self.contact {
510            if c.chars().any(|ch| ch.is_whitespace() || ch.is_control()) {
511                return Err(ConfigError::new("DATUMESH_CONTACT", "an address without spaces"));
512            }
513        }
514        if let Some(u) = &self.base_url {
515            check_base_url(&self.host, u).map_err(|e| ConfigError::new("base URL", format!("{u}: {e}")))?;
516        }
517        for h in &self.namespaces {
518            lexical::check_dns_name(h, "$").map_err(|e| ConfigError::new("namespaces", e.to_string()))?;
519        }
520        for (h, o) in &self.peers {
521            lexical::check_dns_name(h, "$").map_err(|e| ConfigError::new("peers", e.to_string()))?;
522            if !(o.starts_with("http://") || o.starts_with("https://")) {
523                return Err(ConfigError::new("peers", format!("{o}: not an http(s) origin")));
524            }
525        }
526        for (a, n) in &self.aliases {
527            lexical::check_function_name(n, "$").map_err(|e| ConfigError::new("aliases", format!("{a}: {e}")))?;
528        }
529        if self.pool_size == 0 || self.batch_max == 0 || self.slice_page == 0 || self.slice_max == 0 {
530            return Err(ConfigError::new("sizes", "the pool, batch and slice bounds must be positive"));
531        }
532        if self.ttl.job < Duration::from_secs(300) {
533            return Err(ConfigError::new("job TTL", "at least 300 s (SPEC 5.5)"));
534        }
535        if self.budget.is_zero() {
536            return Err(ConfigError::new("budget", "must be positive"));
537        }
538        Ok(())
539    }
540
541    /// Whether this mesh owns the names under `host`.
542    pub fn owns(&self, host: &str) -> bool {
543        self.namespaces.iter().any(|h| h == host)
544    }
545
546    /// `https://<host>`: where this mesh is served, the base of the URLs in its envelopes.
547    pub fn origin(&self) -> String {
548        format!("https://{}", self.host)
549    }
550
551    /// The base of the URLs in the mesh document: the base URL when set, else
552    /// [`Config::origin`].
553    pub fn mesh_document_base(&self) -> String {
554        self.base_url.clone().unwrap_or_else(|| self.origin())
555    }
556}
557
558/// Why a base URL ([`Config::base_url`]) is refused.
559#[non_exhaustive]
560#[derive(Clone, Copy, Debug, PartialEq, Eq)]
561pub enum BaseUrlError {
562    /// Neither `https://` nor `http://` (lower case).
563    Scheme,
564    /// `http://` for a mesh whose host is rooted (not under `.invalid`, SPEC 2.5): rooted
565    /// hosts are served over `https://` only, whatever the base URL's host.
566    HttpRootedHost,
567    /// `http://` (for an unrooted host) with a host other than `127.0.0.1`, `[::1]` and
568    /// `localhost`.
569    HttpNotLoopback,
570    /// No host, userinfo, or a host that is neither a DNS name (lower case), an IPv4 address
571    /// nor an IPv6 address in brackets.
572    Host,
573    /// A port that is not a decimal number from 1 to 65535 (`:` with nothing after it too).
574    Port,
575    /// A path after the host and port.
576    Path,
577    /// A slash alone after the host and port.
578    TrailingSlash,
579    /// A query.
580    Query,
581    /// A fragment.
582    Fragment,
583}
584
585impl fmt::Display for BaseUrlError {
586    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
587        f.write_str(match self {
588            BaseUrlError::Scheme => "not an https:// or http:// URL",
589            BaseUrlError::HttpRootedHost => "http:// is for an unrooted host (under .invalid) only",
590            BaseUrlError::HttpNotLoopback => "http:// is for 127.0.0.1, [::1] and localhost only",
591            BaseUrlError::Host => "not a host name, IPv4 address or bracketed IPv6 address",
592            BaseUrlError::Port => "not a port from 1 to 65535",
593            BaseUrlError::Path => "a path (the base URL is a scheme, a host and a port)",
594            BaseUrlError::TrailingSlash => "a trailing slash",
595            BaseUrlError::Query => "a query",
596            BaseUrlError::Fragment => "a fragment",
597        })
598    }
599}
600
601impl std::error::Error for BaseUrlError {}
602
603/// Checks a base URL ([`Config::base_url`]) for a mesh signing as `host`: `https://` with any
604/// host, or, when `host` is unrooted ([`is_unrooted`]), `http://` with `127.0.0.1`, `[::1]`
605/// or `localhost`; then an optional `:<port>` (1 to 65535) and nothing else: no path, query,
606/// fragment, trailing slash or userinfo. The form is checked first, then the scheme's rule:
607/// `http://` for a rooted host is [`BaseUrlError::HttpRootedHost`] before anything about the
608/// URL's host.
609pub fn check_base_url(host: &str, url: &str) -> Result<(), BaseUrlError> {
610    let mesh_host = host;
611    let (http, rest) = if let Some(r) = url.strip_prefix("https://") {
612        (false, r)
613    } else if let Some(r) = url.strip_prefix("http://") {
614        (true, r)
615    } else {
616        return Err(BaseUrlError::Scheme);
617    };
618    if rest.contains('#') {
619        return Err(BaseUrlError::Fragment);
620    }
621    if rest.contains('?') {
622        return Err(BaseUrlError::Query);
623    }
624    let (authority, path) = rest.split_at(rest.find('/').unwrap_or(rest.len()));
625    match path {
626        "" => {}
627        "/" => return Err(BaseUrlError::TrailingSlash),
628        _ => return Err(BaseUrlError::Path),
629    }
630    if authority.contains('@') {
631        return Err(BaseUrlError::Host);
632    }
633    let (host, port) = if let Some(r) = authority.strip_prefix('[') {
634        let (inside, after) = r.split_once(']').ok_or(BaseUrlError::Host)?;
635        inside.parse::<std::net::Ipv6Addr>().map_err(|_| BaseUrlError::Host)?;
636        let port = match after {
637            "" => None,
638            p => Some(p.strip_prefix(':').ok_or(BaseUrlError::Host)?),
639        };
640        (&authority[..inside.len() + 2], port)
641    } else {
642        let (host, port) = match authority.split_once(':') {
643            Some((h, p)) => (h, Some(p)),
644            None => (authority, None),
645        };
646        if host.parse::<std::net::Ipv4Addr>().is_err() && !is_dns_name(host) {
647            return Err(BaseUrlError::Host);
648        }
649        (host, port)
650    };
651    if let Some(p) = port {
652        let ok = !p.is_empty() && p.len() <= 5 && p.bytes().all(|b| b.is_ascii_digit());
653        if !ok || !(1..=65535).contains(&p.parse::<u32>().unwrap_or(0)) {
654            return Err(BaseUrlError::Port);
655        }
656    }
657    if http && !is_unrooted(mesh_host) {
658        return Err(BaseUrlError::HttpRootedHost);
659    }
660    if http && !matches!(host, "127.0.0.1" | "[::1]" | "localhost") {
661        return Err(BaseUrlError::HttpNotLoopback);
662    }
663    Ok(())
664}
665
666/// Whether a host is unrooted (SPEC 2.5, spec-0.4.3): its last label is `invalid`
667/// (`local.invalid`, `agent-7.local.invalid`). Every other host is rooted.
668pub fn is_unrooted(host: &str) -> bool {
669    host.rsplit('.').next() == Some("invalid")
670}
671
672/// A DNS name in lower case: labels of 1 to 63 of `a-z`, `0-9` and `-`, not starting or
673/// ending with `-`, at most 253 characters.
674fn is_dns_name(h: &str) -> bool {
675    !h.is_empty()
676        && h.len() <= 253
677        && h.split('.').all(|l| {
678            !l.is_empty()
679                && l.len() <= 63
680                && !l.starts_with('-')
681                && !l.ends_with('-')
682                && l.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
683        })
684}
685
686fn string_map(bytes: &[u8], what: &str) -> Result<BTreeMap<String, String>, ConfigError> {
687    let v = json::parse(bytes).map_err(|e| ConfigError::new(what, e.to_string()))?;
688    let mut out = BTreeMap::new();
689    for (k, x) in v.as_object().ok_or_else(|| ConfigError::new(what, "not an object"))? {
690        let s = x.as_str().ok_or_else(|| ConfigError::new(what, format!("{k}: not a string")))?;
691        out.insert(k.clone(), s.to_string());
692    }
693    Ok(out)
694}
695
696fn read_file(path: &str) -> Result<Vec<u8>, ConfigError> {
697    std::fs::read(path).map_err(|e| ConfigError::new(path, e.to_string()))
698}
699
700/// Reads a file holding a secret, refusing it unless only its owner may read or write it
701/// (mode 0600 or stricter, on Unix).
702pub fn read_secret_file(path: &Path) -> Result<Vec<u8>, ConfigError> {
703    let what = path.display().to_string();
704    let meta = std::fs::metadata(path).map_err(|e| ConfigError::new(&what, e.to_string()))?;
705    #[cfg(unix)]
706    {
707        use std::os::unix::fs::PermissionsExt;
708        let mode = meta.permissions().mode() & 0o777;
709        if mode & 0o077 != 0 {
710            return Err(ConfigError::new(&what, format!("mode {mode:o}: a secret file must be 0600")));
711        }
712    }
713    #[cfg(not(unix))]
714    let _ = meta;
715    std::fs::read(path).map_err(|e| ConfigError::new(&what, e.to_string()))
716}
717
718/// A configuration error: what and why.
719#[derive(Clone, Debug, PartialEq, Eq)]
720pub struct ConfigError {
721    what: String,
722    detail: String,
723}
724
725impl ConfigError {
726    pub(crate) fn new(what: &str, detail: impl Into<String>) -> ConfigError {
727        ConfigError { what: what.to_string(), detail: detail.into() }
728    }
729}
730
731impl fmt::Display for ConfigError {
732    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
733        write!(f, "configuration: {}: {}", self.what, self.detail)
734    }
735}
736
737impl std::error::Error for ConfigError {}