aboutsummaryrefslogtreecommitdiffstats
path: root/src/config
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 22:25:31 +0000
committertv <tv@krebsco.de>2026-11-16 23:32:50 +0100
commitc77f4a88dfd0f4ed423951da6535244aea4a0fa1 (patch)
treea50e0fae72f2cb2184cfa4c143e077c8c6866bfe /src/config
parent023bc8ca4e571b6eb2095b8f1f34ea4363452db9 (diff)
node: votes it casts by itself, for its party
A node may vote and propose for its party by itself, by its operator's rules (`docs/federation.md`, Votes a node casts by itself; `federation::vote`): * `--store-vote-key`: the party's key it signs with, an OpenSSH private key file, one the party's version names, kept on the node; * `--store-vote-record`: its party's one record of its votes, which it votes by, written before each vote is sent, begun where there is none on the version current then; * `--store-follow`, `--store-follow-any`: the parties it follows, by default only on a version that only moves to a checkpoint; * `--store-propose-events`, `--store-propose-every`: when it proposes a checkpoint, once it holds so many events beyond its checkpoint, or so long after its store moved there; * `--store-held-for` (10 minutes): how long it holds an event before it holds it for a while, for the heads it proposes and the voters' rule. Its store keeps when, by the node's own clock, it took each event, and when it moved to its checkpoint. Whenever the worker reads the store, the node decides what to sign (`Holding::act`), records it, writes the record, offers it to its store, and puts it into the document (`held::write`). A vote by hand through the node, by the record and the voters' rule, is `Holding::vote_by_hand`.
Diffstat (limited to 'src/config')
-rw-r--r--src/config/mod.rs147
1 files changed, 147 insertions, 0 deletions
diff --git a/src/config/mod.rs b/src/config/mod.rs
index 762e9a4..7889d7c 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -248,6 +248,62 @@ pub(crate) const OPTIONS: &[OptionSpec] = &[
None,
"With store-root or store-id: parties among whose members, with those of its own party, this node keeps some of its neighbours, by the graph among those alone (docs/store.md, Members): so that a party listing many nodes can't be all of them.",
),
+ #[cfg(feature = "federation")]
+ option(
+ "store-vote-key",
+ Kind::Text,
+ "PATH",
+ None,
+ "With store-root or store-id: this node votes and proposes for its party by itself, by the rules below (docs/federation.md, Votes a node casts by itself), signing with this key, an OpenSSH private key file, unencrypted, one its party's version names, kept on this node: one stolen here votes for the party. Its party then votes by hand only through this node (POST /admin/events/vote), which keeps its one record (store-vote-record).",
+ ),
+ #[cfg(feature = "federation")]
+ option(
+ "store-vote-record",
+ Kind::Text,
+ "PATH",
+ None,
+ "With store-vote-key, which needs it: its party's one record of its votes, which the node votes by, written before each vote is sent; begun, where there is none, on the version current then, on which it casts nothing.",
+ ),
+ #[cfg(feature = "federation")]
+ option(
+ "store-follow",
+ Kind::List,
+ "NAME,[NAME...]",
+ None,
+ "With store-vote-key: parties it follows, voting `true` on a proposal where one of them did, `false` where one did; by default only on a version that only moves to a checkpoint.",
+ ),
+ #[cfg(feature = "federation")]
+ option(
+ "store-follow-any",
+ Kind::Flag,
+ "BOOL",
+ Some("false"),
+ "With store-follow: follow on any version, not only on one that only moves to a checkpoint. It hands those parties the node's vote, its `false` among it.",
+ ),
+ #[cfg(feature = "federation")]
+ option(
+ "store-propose-events",
+ Kind::Integer,
+ "COUNT",
+ None,
+ "With store-vote-key: propose a version that only moves to a checkpoint once it holds this many events beyond its checkpoint, at the heads of what it held for a while (store-held-for), where nothing that can still pass is proposed on the current version; it backs what it proposes.",
+ ),
+ #[cfg(feature = "federation")]
+ option(
+ "store-propose-every",
+ Kind::Duration,
+ "DURATION",
+ None,
+ "With store-vote-key: propose a checkpoint, as store-propose-events, once this long passed by its own clock since its store moved to its checkpoint, or started there.",
+ ),
+ #[cfg(feature = "federation")]
+ option(
+ "store-held-for",
+ Kind::Duration,
+ "DURATION",
+ Some("10m"),
+ "With store-vote-key: how long it holds an event before it holds it for a while: it proposes a checkpoint at the heads of such, and backs none whose heads leave out one it held for a while before it was proposed.",
+ ),
option(
"strict-keys",
Kind::List,
@@ -692,6 +748,31 @@ pub(crate) struct Settings {
#[cfg(feature = "federation")]
#[serde(default)]
pub(crate) store_neighbour_parties: Vec<String>,
+ #[cfg(feature = "federation")]
+ pub(crate) store_vote_key: Option<PathBuf>,
+ #[cfg(feature = "federation")]
+ pub(crate) store_vote_record: Option<PathBuf>,
+ #[cfg(feature = "federation")]
+ #[serde(default)]
+ pub(crate) store_follow: Vec<String>,
+ #[cfg(feature = "federation")]
+ #[serde(default)]
+ pub(crate) store_follow_any: bool,
+ #[cfg(feature = "federation")]
+ pub(crate) store_propose_events: Option<usize>,
+ #[cfg(feature = "federation")]
+ #[serde(
+ default,
+ deserialize_with = "crate::units::optional_duration",
+ serialize_with = "crate::units::serialize_optional_duration"
+ )]
+ pub(crate) store_propose_every: Option<Duration>,
+ #[cfg(feature = "federation")]
+ #[serde(
+ default = "default_store_held_for",
+ with = "crate::units::duration_option"
+ )]
+ pub(crate) store_held_for: Duration,
#[serde(default)]
pub(crate) strict_keys: Vec<String>,
@@ -883,6 +964,10 @@ fn default_token_lifetime() -> Duration {
fn default_session_lifetime() -> Duration {
Duration::from_secs(7 * 24 * 3600)
}
+#[cfg(feature = "federation")]
+fn default_store_held_for() -> Duration {
+ Duration::from_secs(10 * 60)
+}
fn default_challenge_lifetime() -> Duration {
Duration::from_secs(5 * 60)
}
@@ -1171,6 +1256,7 @@ impl Settings {
"store-neighbour-parties",
!self.store_neighbour_parties.is_empty(),
),
+ ("store-vote-key", self.store_vote_key.is_some()),
];
let set: Vec<&str> = of_a_store
.iter()
@@ -1203,6 +1289,44 @@ impl Settings {
{
bail!("store-neighbour-parties: {party:?} isn't a party's name");
}
+ // Voting by itself: its key, its party's record, and rules only with them.
+ let voting = [
+ ("store-vote-record", self.store_vote_record.is_some()),
+ ("store-follow", !self.store_follow.is_empty()),
+ ("store-follow-any", self.store_follow_any),
+ ("store-propose-events", self.store_propose_events.is_some()),
+ ("store-propose-every", self.store_propose_every.is_some()),
+ ];
+ match (&self.store_vote_key, &self.store_vote_record) {
+ (Some(_), None) => {
+ bail!("store-vote-key: set store-vote-record, its party's one record of its votes")
+ }
+ (None, _) => {
+ let set: Vec<&str> = voting
+ .iter()
+ .filter(|(_, set)| *set)
+ .map(|(name, _)| *name)
+ .collect();
+ if !set.is_empty() {
+ bail!(
+ "{} {} of a node voting by itself: set store-vote-key",
+ set.join(", "),
+ if set.len() == 1 { "is" } else { "are" }
+ );
+ }
+ }
+ (Some(_), Some(_)) => {}
+ }
+ if self.store_follow_any && self.store_follow.is_empty() {
+ bail!("store-follow-any follows on any version: set store-follow, whom");
+ }
+ if let Some(party) = self
+ .store_follow
+ .iter()
+ .find(|party| !crate::federation::version::is_party(party))
+ {
+ bail!("store-follow: {party:?} isn't a party's name");
+ }
let first_change = [
("genesis", self.genesis),
("bootstrap-users", !self.bootstrap_users.is_empty()),
@@ -1282,6 +1406,8 @@ impl Settings {
"store-neighbour-parties",
!self.store_neighbour_parties.is_empty(),
),
+ #[cfg(feature = "federation")]
+ ("store-vote-key", self.store_vote_key.is_some()),
("alias", self.alias.is_some()),
("dashboard-url", self.dashboard_url.is_some()),
("debug-api", self.debug_api),
@@ -2390,6 +2516,27 @@ mod tests {
.is_err()
);
assert!(checked(json!({ "store-neighbour-parties": ["lass"] })).is_err());
+ let voting = |more: JsonValue| {
+ let mut values = json!({ "store-id": id, "store-party": "tv" });
+ for (name, value) in more.as_object().unwrap() {
+ values[name] = value.clone();
+ }
+ checked(values)
+ };
+ assert!(
+ voting(
+ json!({ "store-vote-key": "k", "store-vote-record": "r", "store-follow": ["lass"] })
+ )
+ .is_ok()
+ );
+ assert!(voting(json!({ "store-vote-key": "k" })).is_err());
+ assert!(voting(json!({ "store-follow": ["lass"] })).is_err());
+ assert!(
+ voting(
+ json!({ "store-vote-key": "k", "store-vote-record": "r", "store-follow-any": true })
+ )
+ .is_err()
+ );
assert!(
checked(json!({ "store-id": id, "store-root": "root.json", "store-party": "tv" }))
.is_err()