wire/command/
tuning.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4// Copyright (c) 2026 2youg1 and the sprawling contributors
5
6//! What a person settles about one endpoint besides its address.
7//!
8//! Six values that are entered on one form and read together by every
9//! call that endpoint carries: what to call it, how long it may take,
10//! how many times a failed request is made again, how long a streamed
11//! answer may run, the headers it adds, and the body fields it writes.
12//! They travel as one value because a form that sent them separately
13//! would let a probe and the attachment behind it disagree about what
14//! they are talking to.
15//!
16//! **Every figure is optional, and absent means the city's own.** A
17//! zero is a deadline no request can meet and a retry count nobody
18//! meant, so the wire has no way to spell one by accident.
19//!
20//! An override's value travels as the text a person typed. What that
21//! text means as JSON is `gateway`'s answer, because `gateway` is what
22//! writes it into a request body; this crate carries the bytes and
23//! decides nothing about them.
24
25use kernel::Proxying;
26use serde::{Deserialize, Serialize};
27
28/// One header every request to this endpoint carries.
29///
30/// The value may be a `secret:realm/name` reference, which the vault
31/// redeems at the moment the header is written; anything else is sent
32/// as it stands. Plaintext credentials never reach this type — the
33/// enrolment door is the only way a secret enters the city.
34#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
35#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
36pub struct HeaderPair {
37    pub name: String,
38    pub value: String,
39}
40
41/// One field written into every request body this endpoint receives.
42///
43/// `pointer` is a JSON pointer (`/temperature`, `/reasoning/effort`),
44/// and missing object segments along it are created. `value` is the
45/// text a person typed, never a parsed number: a float in a frame is a
46/// float in the record that frame produces, and this city keeps floats
47/// out of its ledger.
48#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
49#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
50pub struct BodyOverride {
51    pub pointer: String,
52    pub value: String,
53}
54
55/// Everything a person settles about one endpoint beyond its address.
56///
57/// `Default` is "nothing was settled", which is what a form that never
58/// opened its advanced section means, and what every caller that has no
59/// opinion sends.
60#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
61#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
62pub struct EndpointTuning {
63    /// What to call this endpoint on screen. Absent means the id it was
64    /// filed under, which is what a person who named it once meant.
65    pub label: Option<String>,
66    /// How long one request to this endpoint may take.
67    pub timeout_ms: Option<u64>,
68    /// How many times a request that failed for a reason worth retrying
69    /// is made again. Zero is a legal answer and means "once, then
70    /// report".
71    pub request_max_retries: Option<u32>,
72    /// How long a streamed answer may go **without a byte arriving**
73    /// before the city gives up on it. An idle bound rather than a
74    /// deadline on the whole answer, which is how the transport
75    /// applies it: a model that keeps writing is never cut off for
76    /// writing a long answer, and one that stops mid-answer is given
77    /// up on this long after its last byte.
78    pub stream_idle_timeout_ms: Option<u64>,
79    pub headers: Vec<HeaderPair>,
80    pub overrides: Vec<BodyOverride>,
81    /// Which of this endpoint's calls go through the machine's proxy.
82    /// Absent is the city's own rule, which keeps a call to an address
83    /// on this machine off the proxy; the other two settings exist
84    /// because that rule is right about the common machine and wrong
85    /// about some real ones.
86    pub proxying: Option<Proxying>,
87    /// How many calls to this endpoint may be in flight at once. Absent
88    /// and zero both mean nobody settled it, and the city takes the
89    /// default for this kind of connection.
90    pub max_in_flight: Option<u32>,
91}
wire/command/tuning.rs

wire/command/
tuning.rs
