swarm-controller: serve swarm-wide service quick links (hyperhive#3289)

New `services.hyperhive.swarm.controller.links` option (listOf {label,
icon, url}, same shape as the per-agent hyperhive.dashboardLinks) plus
a new GET /api/links route serving it, same pattern as the existing
hives/GET /api/hives.

Rather than one central hardcoded list, each service's own module
contributes its own entry when actually enabled on the controller's
host: swarm-authelia.nix, hive-matrix.nix (gated on gui.enable too,
since / on that vhost only serves fluffychat then) and
hive-forge/default.nix (gated on behindGateway) each push one entry,
the same list-merge idiom services.hyperhive.gateway.localNames
already uses. swarm-ui.nix contributes a static entry for its own
same-origin swagger docs. Adding a future service's link is a nix-only
change to that service's own module.

Verified: cargo build/clippy/test -p swarm-controller clean, a
throwaway nixosSystem eval confirms all 4 entries merge correctly into
SWARM_CONTROLLER_LINKS, nix build .#swarm-controller succeeds.

swarm-controller/src/main.rs

@@ -65,6 +65,7 @@ fn socket_path() -> PathBuf {
     tags(
         (name = "health", description = "liveness probe"),
         (name = "hives", description = "the swarm's hive directory"),
+        (name = "links", description = "swarm service quick links"),
     )
 )]
 struct ApiDoc;
@@ -97,6 +98,9 @@ struct AppState {
     /// Loaded once at startup (`load_hives`); never mutated, so an
     /// `Arc` clone per request is the whole synchronization story.
     hives: Arc<Vec<HiveEntry>>,
+    /// Loaded once at startup (`load_links`); same synchronization story
+    /// as `hives`.
+    links: Arc<Vec<ServiceLink>>,
 }
 
 /// Env var the controller's NixOS module sets from
@@ -136,6 +140,58 @@ async fn get_hives(State(state): State<AppState>) -> Json<Vec<HiveEntry>> {
     Json((*state.hives).clone())
 }
 
+/// One quick link to a swarm-wide service (authelia, matrix, forge, this
+/// daemon's own swagger UI, …). Deliberately generic rather than named
+/// fields per service: each service's own nix module contributes its own
+/// entry to `services.hyperhive.swarm.controller.links` (same list-merge
+/// idiom `services.hyperhive.gateway.localNames` already uses), so adding
+/// a new one is a nix-only change — no new field here, no swarm-ui change.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
+struct ServiceLink {
+    label: String,
+    /// Emoji or short glyph. Empty string, not `Option`, when a
+    /// contributing module has none — one fewer null-vs-absent case for
+    /// the frontend to handle, and every real contributor sets one today.
+    icon: String,
+    url: String,
+}
+
+/// Env var the controller's NixOS module sets from the merged
+/// `services.hyperhive.swarm.controller.links` list, JSON-encoded — same
+/// shape/rationale as [`HIVES_ENV`]. Consumed by `GET /api/links`.
+const LINKS_ENV: &str = "SWARM_CONTROLLER_LINKS";
+
+/// Parses [`LINKS_ENV`] into the swarm's service-link list. Same
+/// fall-back-to-empty rationale as `load_hives`: a daemon that can't yet
+/// see this config should still serve `/health` rather than fail startup.
+fn load_links() -> Vec<ServiceLink> {
+    let Some(raw) = std::env::var_os(LINKS_ENV) else {
+        return Vec::new();
+    };
+    match serde_json::from_str(&raw.to_string_lossy()) {
+        Ok(links) => links,
+        Err(e) => {
+            tracing::warn!(error = %e, env = LINKS_ENV, "failed to parse service links, serving an empty list");
+            Vec::new()
+        }
+    }
+}
+
+/// Quick links to swarm-wide services (authelia, matrix, forge, this
+/// daemon's own swagger UI, …), as contributed by each service's own nix
+/// module. Empty when nothing was configured to contribute — a caller
+/// renders 0 links the same way it renders any other count, no special
+/// "not configured" case.
+#[utoipa::path(
+    get,
+    path = "/api/links",
+    responses((status = 200, description = "swarm service quick links", body = Vec<ServiceLink>)),
+    tag = "links"
+)]
+async fn get_links(State(state): State<AppState>) -> Json<Vec<ServiceLink>> {
+    Json((*state.links).clone())
+}
+
 #[tokio::main]
 async fn main() -> Result<()> {
     tracing_subscriber::fmt()
@@ -176,11 +232,13 @@ async fn main() -> Result<()> {
 
     let state = AppState {
         hives: Arc::new(load_hives()),
+        links: Arc::new(load_links()),
     };
 
     let (router, api) = OpenApiRouter::<AppState>::with_openapi(ApiDoc::openapi())
         .routes(routes!(health))
         .routes(routes!(get_hives))
+        .routes(routes!(get_links))
         .split_for_parts();
     // Just the JSON, not the UI — Swagger UI itself is nginx-hosted from
     // the nix store (see the module doc comment above). `api` is
@@ -199,7 +257,9 @@ async fn main() -> Result<()> {
 
 #[cfg(test)]
 mod tests {
-    use super::{DEFAULT_SOCKET, HIVES_ENV, HiveEntry, load_hives};
+    use super::{
+        DEFAULT_SOCKET, HIVES_ENV, HiveEntry, LINKS_ENV, ServiceLink, load_hives, load_links,
+    };
     use std::path::Path;
 
     /// The socket must not share a directory with anything else, because
@@ -277,4 +337,49 @@ mod tests {
             std::env::remove_var(HIVES_ENV);
         }
     }
+
+    /// Same three-state coverage as `load_hives_covers_missing_malformed_and_valid`,
+    /// same reason for one test rather than three (a shared process env var).
+    ///
+    /// SAFETY: single-threaded mutation of a process env var no other test
+    /// in this crate reads; restored (removed) before returning.
+    #[test]
+    fn load_links_covers_missing_malformed_and_valid() {
+        unsafe {
+            std::env::remove_var(LINKS_ENV);
+        }
+        assert_eq!(
+            load_links(),
+            Vec::<ServiceLink>::new(),
+            "unset env var is an empty list, not a startup failure"
+        );
+
+        unsafe {
+            std::env::set_var(LINKS_ENV, "not json");
+        }
+        assert_eq!(
+            load_links(),
+            Vec::<ServiceLink>::new(),
+            "unparseable env var falls back to empty rather than panicking"
+        );
+
+        unsafe {
+            std::env::set_var(
+                LINKS_ENV,
+                r#"[{"label":"Authelia","icon":"🔑","url":"https://auth.example.com/"}]"#,
+            );
+        }
+        assert_eq!(
+            load_links(),
+            vec![ServiceLink {
+                label: "Authelia".to_string(),
+                icon: "🔑".to_string(),
+                url: "https://auth.example.com/".to_string(),
+            }]
+        );
+
+        unsafe {
+            std::env::remove_var(LINKS_ENV);
+        }
+    }
 }