cja/

eyes_manifest.rs

//! Boot-time app manifest emission to Eyes.
//!
//! Telemetry shows what *happened*; the manifest tells Eyes what the app's
//! *shape* is — every registered job type, every cron entry with its schedule,
//! and the build version. Apps send one manifest at process start via
//! [`send_boot_manifest`]; each stored manifest doubles as a boot/deploy
//! marker on the Eyes server.
//!
//! Emission is fire-and-forget: it spawns a background task, logs a warning
//! on failure, and never blocks or crashes app boot. When Eyes is not
//! configured (`EYES_ORG_ID`/`EYES_APP_ID` unset — the same variables
//! [`crate::setup::setup_tracing`] uses), it's a debug-logged no-op.
//!
//! # Intended call site
//!
//! Call once at boot, *after* constructing your job/cron registries (they
//! don't exist yet when `setup_tracing` runs, which is why this is a separate
//! explicit call):
//!
//! ```rust,ignore
//! async fn run() -> cja::Result<()> {
//!     let _eyes_handle = setup_tracing("my-app")?;
//!     let app_state = AppState::from_env().await?;
//!     let cron_registry = cron_registry(); // your CronRegistry setup
//!
//!     cja::eyes_manifest::send_boot_manifest::<Jobs, AppState>(
//!         Some(env!("CARGO_PKG_VERSION")),
//!         option_env!("VERGEN_GIT_SHA"),
//!         Some(&cron_registry),
//!     );
//!
//!     // ... spawn server/job/cron workers as usual
//! }
//! ```
//!
//! `app_version` and `git_sha` are explicit parameters: as a library, cja
//! cannot read your crate's compile-time env, so source them at the app call
//! site (e.g. `env!("CARGO_PKG_VERSION")` and `option_env!("VERGEN_GIT_SHA")`
//! if you use [vergen](https://docs.rs/vergen), matching what
//! [`crate::setup::setup_sentry`] uses for release detection). Pass `None` if
//! you don't have them.

use crate::app_state::AppState;
use crate::jobs::registry::JobRegistry;

pub use eyes_subscriber::{
    AppManifest, CronEntry, ExpectedProcessRole, HttpMethod, HttpMonitor, ManifestError,
};

/// Build an [`AppManifest`] from a job registry and (optionally) a cron registry.
///
/// Job names come from [`JobRegistry::job_names`] (generated by
/// `impl_job_registry!`). Cron schedule strings come from
/// [`crate::cron::CronRegistry::entries`]: the `Duration` `Debug` form for
/// interval schedules (e.g. `"300s"`) and the original expression for cron
/// expression schedules.
///
/// Most apps should call [`send_boot_manifest`] instead; this is exposed for
/// callers that want to inspect or customize the manifest before sending it
/// with [`send_manifest`] (e.g. attaching a `base_url` and [`HttpMonitor`]
/// declarations).
#[cfg(feature = "cron")]
#[must_use]
pub fn build_boot_manifest<J, S>(
    app_version: Option<&str>,
    git_sha: Option<&str>,
    cron_registry: Option<&crate::cron::CronRegistry<S>>,
) -> AppManifest
where
    J: JobRegistry<S>,
    S: AppState,
{
    let mut manifest = AppManifest::default()
        .jobs(J::job_names().iter().map(ToString::to_string).collect())
        .crons(
            cron_registry
                .map(|registry| {
                    registry
                        .entries()
                        .into_iter()
                        .map(|(name, schedule)| CronEntry {
                            name: name.to_string(),
                            schedule,
                        })
                        .collect()
                })
                .unwrap_or_default(),
        );
    if let Some(app_version) = app_version {
        manifest = manifest.app_version(app_version);
    }
    if let Some(git_sha) = git_sha {
        manifest = manifest.git_sha(git_sha);
    }
    manifest
}

/// Build an [`AppManifest`] from a job registry (no cron support compiled in).
#[cfg(not(feature = "cron"))]
#[must_use]
pub fn build_boot_manifest<J, S>(app_version: Option<&str>, git_sha: Option<&str>) -> AppManifest
where
    J: JobRegistry<S>,
    S: AppState,
{
    let mut manifest =
        AppManifest::default().jobs(J::job_names().iter().map(ToString::to_string).collect());
    if let Some(app_version) = app_version {
        manifest = manifest.app_version(app_version);
    }
    if let Some(git_sha) = git_sha {
        manifest = manifest.git_sha(git_sha);
    }
    manifest
}

/// Send this app's boot manifest to Eyes, fire-and-forget.
///
/// Builds an [`AppManifest`] (see [`build_boot_manifest`]) and spawns a
/// background task that POSTs it using the `EYES_URL`/`EYES_ORG_ID`/
/// `EYES_APP_ID` environment variables — the same configuration
/// [`crate::setup::setup_tracing`] uses for the Eyes tracing layer.
///
/// This never blocks or fails app boot:
///
/// - If `EYES_ORG_ID` or `EYES_APP_ID` is unset, it's a debug-logged no-op.
/// - If called outside a Tokio runtime, it logs a warning and does nothing.
/// - If the send fails, the spawned task logs a warning.
///
/// See the [module docs](self) for the intended call site and how to source
/// `app_version`/`git_sha`.
#[cfg(feature = "cron")]
pub fn send_boot_manifest<J, S>(
    app_version: Option<&str>,
    git_sha: Option<&str>,
    cron_registry: Option<&crate::cron::CronRegistry<S>>,
) where
    J: JobRegistry<S>,
    S: AppState,
{
    spawn_send(build_boot_manifest::<J, S>(
        app_version,
        git_sha,
        cron_registry,
    ));
}

/// Send this app's boot manifest to Eyes, fire-and-forget (no cron support
/// compiled in). See the `cron`-enabled variant for behavior details.
#[cfg(not(feature = "cron"))]
pub fn send_boot_manifest<J, S>(app_version: Option<&str>, git_sha: Option<&str>)
where
    J: JobRegistry<S>,
    S: AppState,
{
    spawn_send(build_boot_manifest::<J, S>(app_version, git_sha));
}

/// Send a caller-built manifest to Eyes, fire-and-forget.
///
/// Like [`send_boot_manifest`], but for apps that need declarations the
/// registries can't express. Build the base manifest with
/// [`build_boot_manifest`], attach the extra declarations with the
/// [`AppManifest`] builder methods, then send:
///
/// ```rust,ignore
/// let manifest = cja::eyes_manifest::build_boot_manifest::<Jobs, AppState>(
///     Some(env!("CARGO_PKG_VERSION")),
///     option_env!("VERGEN_GIT_SHA"),
///     Some(&cron_registry),
/// )
/// .base_url("https://arena.battlesnake.com")
/// .monitors(vec![HttpMonitor::new("health", "/health")]);
/// cja::eyes_manifest::send_manifest(manifest);
/// ```
///
/// Same guarantees as [`send_boot_manifest`]: never blocks or fails app boot,
/// debug-logged no-op when `EYES_ORG_ID`/`EYES_APP_ID` are unset.
pub fn send_manifest(manifest: AppManifest) {
    spawn_send(manifest);
}

fn spawn_send(manifest: AppManifest) {
    if std::env::var("EYES_ORG_ID").is_err() || std::env::var("EYES_APP_ID").is_err() {
        tracing::debug!("Skipping Eyes boot manifest: EYES_ORG_ID and/or EYES_APP_ID not set");
        return;
    }

    match tokio::runtime::Handle::try_current() {
        Ok(handle) => {
            handle.spawn(async move {
                if let Err(error) = eyes_subscriber::send_manifest_from_env(&manifest).await {
                    tracing::warn!(%error, "Failed to send Eyes boot manifest");
                }
            });
        }
        Err(_) => {
            tracing::warn!("Skipping Eyes boot manifest: no Tokio runtime available");
        }
    }
}

#[cfg(all(test, feature = "cron"))]
mod test {
    use std::time::Duration;

    use super::*;
    use crate::cron::CronRegistry;
    use crate::impl_job_registry;
    use crate::jobs::Job;
    use crate::server::cookies::CookieKey;

    #[derive(Clone)]
    struct TestAppState {
        db: sqlx::PgPool,
        cookie_key: CookieKey,
    }

    impl AppState for TestAppState {
        fn db(&self) -> &sqlx::PgPool {
            &self.db
        }

        fn version(&self) -> &'static str {
            "test"
        }

        fn cookie_key(&self) -> &CookieKey {
            &self.cookie_key
        }
    }

    #[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
    struct ManifestJobA;

    #[async_trait::async_trait]
    impl Job<TestAppState> for ManifestJobA {
        const NAME: &'static str = "ManifestJobA";

        async fn run(&self, _app_state: TestAppState) -> color_eyre::Result<()> {
            Ok(())
        }
    }

    #[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
    struct ManifestJobB;

    #[async_trait::async_trait]
    impl Job<TestAppState> for ManifestJobB {
        const NAME: &'static str = "ManifestJobB";

        async fn run(&self, _app_state: TestAppState) -> color_eyre::Result<()> {
            Ok(())
        }
    }

    impl_job_registry!(TestAppState, ManifestJobA, ManifestJobB);

    #[test]
    fn test_build_boot_manifest_populates_jobs_and_crons() {
        let mut cron_registry: CronRegistry<TestAppState> = CronRegistry::new();
        cron_registry.register_job(ManifestJobA, None, Duration::from_mins(5));
        cron_registry
            .register_job_with_cron(ManifestJobB, None, "0 0 9 * * * *")
            .unwrap();

        let manifest = build_boot_manifest::<Jobs, TestAppState>(
            Some("1.2.3"),
            Some("abc123"),
            Some(&cron_registry),
        );

        assert_eq!(manifest.app_version.as_deref(), Some("1.2.3"));
        assert_eq!(manifest.git_sha.as_deref(), Some("abc123"));
        assert_eq!(manifest.jobs, vec!["ManifestJobA", "ManifestJobB"]);
        assert_eq!(
            manifest.crons,
            vec![
                CronEntry {
                    name: "ManifestJobA".to_string(),
                    schedule: "300s".to_string(),
                },
                CronEntry {
                    name: "ManifestJobB".to_string(),
                    schedule: "0 0 9 * * * *".to_string(),
                },
            ]
        );
    }

    #[test]
    fn test_build_boot_manifest_without_cron_registry() {
        let manifest = build_boot_manifest::<Jobs, TestAppState>(None, None, None);

        assert_eq!(manifest.app_version, None);
        assert_eq!(manifest.git_sha, None);
        assert_eq!(manifest.jobs, vec!["ManifestJobA", "ManifestJobB"]);
        assert!(manifest.crons.is_empty());
    }
}