hyperhive/swarm-wire/src/builder.rs

//! The swarm builder's requests: the subjects swarm-controller sends a build,
//! an archetype evaluation and a meta-flake lock on, and what travels each way.
//!
//! Three crates name these: the controller sends the requests, the builder
//! answers them, and the auth-callout responder grants the subjects to each.

use std::time::Duration;

use serde::{Deserialize, Serialize};

/// The subject every build goes to. The controller is its one publisher and
/// the builder its one subscriber; the builder answers on the request's reply
/// subject.
pub const SUBJECT: &str = "$SWARM.builder.build";

/// The queue group the builder subscribes in, so a second instance shares the
/// requests instead of running each one twice.
pub const QUEUE_GROUP: &str = "builder";

/// The longest one build may take before the builder stops it and answers
/// with a timeout.
pub const BUILD_DEADLINE: Duration = Duration::from_hours(1);

/// How long the controller waits for the reply, and the queue lets the
/// builder answer: the build at its deadline, plus a minute the builder spends
/// on a request's wait for the build slot, the forge token read before the
/// build and the reply's trip back.
pub const REPLY_DEADLINE: Duration = Duration::from_mins(61);

/// One build: an agent's config repo at one commit, on the builder's own
/// agent base.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BuildAgent {
    /// The agent, which is also its config repo's name.
    pub agent: String,
    /// The commit to build.
    pub rev: String,
    /// The PR the commit is the head of; its `refs/pull/<pr>/head` is the ref
    /// the builder fetches the commit through.
    pub pr: u64,
}

/// The builder's answer to one [`BuildAgent`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "kebab-case")]
pub enum Reply {
    /// The config built; `out_path` is the system closure's store path.
    Built { out_path: String },
    /// The build did not finish: the last lines `nix` printed, or why the
    /// builder could not start it.
    Failed { error_tail: String },
}

/// The subject an archetype evaluation goes to: the controller asks, the
/// builder evaluates the `meta` of every `hyperhiveArchetypes` entry of its own
/// hyperhive source and answers on the request's reply subject.
pub const ARCHETYPES_SUBJECT: &str = "$SWARM.builder.archetypes";

/// The longest one archetype evaluation may take, and how long the controller
/// waits for its reply.
pub const ARCHETYPES_DEADLINE: Duration = Duration::from_mins(2);

/// One archetype evaluation. No field yet: the builder evaluates the hyperhive
/// source it was deployed with.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct EvalArchetypes {}

/// The builder's answer to one [`EvalArchetypes`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "kebab-case")]
pub enum ArchetypesReply {
    /// `source` is the flake evaluated; `archetypes` maps each archetype's
    /// name to its `meta`, as `nix eval --json` printed it and unchecked.
    Evaluated {
        source: String,
        archetypes: serde_json::Map<String, serde_json::Value>,
    },
    /// The evaluation did not finish: the last lines `nix` printed, or why the
    /// builder could not start it.
    Failed { error_tail: String },
}

/// The subject a swarm meta-flake lock goes to, with the same one publisher and
/// one subscriber as [`SUBJECT`].
pub const LOCK_SUBJECT: &str = "$SWARM.builder.lock-meta";

/// The longest one lock may take. A lock fetches every input's source and
/// builds nothing.
pub const LOCK_DEADLINE: Duration = Duration::from_mins(10);

/// How long the controller waits for a lock's reply: the lock at its deadline,
/// plus a minute for the rest.
pub const LOCK_REPLY_DEADLINE: Duration = Duration::from_mins(11);

/// One lock: the swarm meta flake's `flake.nix`, locked on its own in a scratch
/// directory. The builder writes nothing anywhere else and commits nothing; the
/// controller commits the returned lock beside the flake.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LockMeta {
    /// The rendered `flake.nix`.
    pub flake_nix: String,
}

/// The builder's answer to one [`LockMeta`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "kebab-case")]
pub enum LockReply {
    /// The flake locked; `flake_lock` is the `flake.lock` `nix` wrote.
    Locked { flake_lock: String },
    /// The lock did not finish: the last lines `nix` printed, or why the
    /// builder could not start it.
    Failed { error_tail: String },
}

#[cfg(test)]
mod tests {
    use serde_json::json;

    use super::*;

    #[test]
    fn the_build_request_serializes_as_pinned() {
        let req = BuildAgent {
            agent: "atlas".to_owned(),
            rev: "abc".to_owned(),
            pr: 7,
        };
        let value = serde_json::to_value(&req).expect("encodes");
        assert_eq!(value, json!({"agent": "atlas", "rev": "abc", "pr": 7}));
        assert_eq!(
            serde_json::from_value::<BuildAgent>(value).expect("decodes"),
            req
        );
    }

    #[test]
    fn the_reply_serializes_as_pinned() {
        for (reply, wire) in [
            (
                Reply::Built {
                    out_path: "/nix/store/x".to_owned(),
                },
                json!({"state": "built", "out_path": "/nix/store/x"}),
            ),
            (
                Reply::Failed {
                    error_tail: "e".to_owned(),
                },
                json!({"state": "failed", "error_tail": "e"}),
            ),
        ] {
            assert_eq!(serde_json::to_value(&reply).expect("encodes"), wire);
            assert_eq!(
                serde_json::from_value::<Reply>(wire).expect("decodes"),
                reply
            );
        }
    }

    #[test]
    fn the_archetypes_request_and_reply_serialize_as_pinned() {
        let req = EvalArchetypes::default();
        let value = serde_json::to_value(&req).expect("encodes");
        assert_eq!(value, json!({}));
        assert_eq!(
            serde_json::from_value::<EvalArchetypes>(value).expect("decodes"),
            req
        );

        let mut archetypes = serde_json::Map::new();
        archetypes.insert("coder".to_owned(), json!({"description": "d"}));
        for (reply, wire) in [
            (
                ArchetypesReply::Evaluated {
                    source: "/nix/store/h".to_owned(),
                    archetypes,
                },
                json!({
                    "state": "evaluated",
                    "source": "/nix/store/h",
                    "archetypes": {"coder": {"description": "d"}},
                }),
            ),
            (
                ArchetypesReply::Failed {
                    error_tail: "e".to_owned(),
                },
                json!({"state": "failed", "error_tail": "e"}),
            ),
        ] {
            assert_eq!(serde_json::to_value(&reply).expect("encodes"), wire);
            assert_eq!(
                serde_json::from_value::<ArchetypesReply>(wire).expect("decodes"),
                reply
            );
        }
    }

    #[test]
    fn the_subjects_are_pinned() {
        assert_eq!(SUBJECT, "$SWARM.builder.build");
        assert_eq!(ARCHETYPES_SUBJECT, "$SWARM.builder.archetypes");
        assert_eq!(LOCK_SUBJECT, "$SWARM.builder.lock-meta");
        assert_eq!(QUEUE_GROUP, "builder");
    }

    #[test]
    fn the_reply_deadline_outlasts_the_build() {
        assert!(REPLY_DEADLINE > BUILD_DEADLINE);
    }

    #[test]
    fn the_lock_reply_deadline_outlasts_the_lock() {
        assert!(LOCK_REPLY_DEADLINE > LOCK_DEADLINE);
    }

    #[test]
    fn the_lock_request_and_reply_serialize_as_pinned() {
        let req = LockMeta {
            flake_nix: "{ }".to_owned(),
        };
        let value = serde_json::to_value(&req).expect("encodes");
        assert_eq!(value, json!({"flake_nix": "{ }"}));
        assert_eq!(
            serde_json::from_value::<LockMeta>(value).expect("decodes"),
            req
        );
        for (reply, wire) in [
            (
                LockReply::Locked {
                    flake_lock: "{}".to_owned(),
                },
                json!({"state": "locked", "flake_lock": "{}"}),
            ),
            (
                LockReply::Failed {
                    error_tail: "e".to_owned(),
                },
                json!({"state": "failed", "error_tail": "e"}),
            ),
        ] {
            assert_eq!(serde_json::to_value(&reply).expect("encodes"), wire);
            assert_eq!(
                serde_json::from_value::<LockReply>(wire).expect("decodes"),
                reply
            );
        }
    }
}