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    /// Explicit ordered accounts; absence leaves the existing accounts intact.
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub accounts: Option<Vec<kernel::event::record::ProviderAccount>>,
66    /// What to call this endpoint on screen. Absent means the id it was
67    /// filed under, which is what a person who named it once meant.
68    pub label: Option<String>,
69    /// How long one request to this endpoint may take.
70    pub timeout_ms: Option<u64>,
71    /// How many times a request that failed for a reason worth retrying
72    /// is made again. Zero is a legal answer and means "once, then
73    /// report".
74    pub request_max_retries: Option<u32>,
75    /// How long a streamed answer may go **without a byte arriving**
76    /// before the city gives up on it. An idle bound rather than a
77    /// deadline on the whole answer, which is how the transport
78    /// applies it: a model that keeps writing is never cut off for
79    /// writing a long answer, and one that stops mid-answer is given
80    /// up on this long after its last byte.
81    pub stream_idle_timeout_ms: Option<u64>,
82    pub headers: Vec<HeaderPair>,
83    pub overrides: Vec<BodyOverride>,
84    /// Which of this endpoint's calls go through the machine's proxy.
85    /// Absent is the city's own rule, which keeps a call to an address
86    /// on this machine off the proxy; the other two settings exist
87    /// because that rule is right about the common machine and wrong
88    /// about some real ones.
89    pub proxying: Option<Proxying>,
90    /// How many calls to this endpoint may be in flight at once. Absent
91    /// and zero both mean nobody settled it, and the city takes the
92    /// default for this kind of connection.
93    pub max_in_flight: Option<u32>,
94    /// How many more times one account is asked the same request before
95    /// the next account takes it. Absent means the city's own figure,
96    /// which the configuration query reads back; read only where the
97    /// endpoint lists two accounts or more.
98    #[serde(default, skip_serializing_if = "Option::is_none")]
99    pub account_retries: Option<kernel::account_recovery::AccountRetries>,
100}
wire/command/tuning.rs

wire/command/
tuning.rs
