cortex/

bootstrap.rs

// Copyright 2015-2025 Deyan Ginev. See the LICENSE
// file at the top-level directory of this distribution.
//
// Licensed under the MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>.
// This file may not be copied, modified, or distributed
// except according to those terms.

//! Self-install and diagnostics: the library logic behind `cortex init` and `cortex doctor`.
//!
//! Kept in the library (not the binary) so the contracts are testable; the `cortex` binary is a
//! thin renderer over these functions.

use std::path::Path;

use diesel::pg::PgConnection;
use diesel::prelude::*;
use rand::RngExt;
use rand::distr::Alphanumeric;
use serde::Serialize;

use crate::config::{CortexConfig, TokenFile, to_persisted_toml};
use crate::migrations;

/// Write `cortex.toml` **atomically**: serialize to a sibling temp file, then `rename` it over the
/// target. `rename` is atomic on a POSIX filesystem, so a crash mid-write leaves the **previous**
/// `cortex.toml` (or none) intact rather than a half-written file the app can't parse — and that
/// `cortex init` would then skip as "already present". `fs::write` truncates any temp orphaned by a
/// prior crash, so the next write starts clean. (Process-crash atomic; power-loss durability would
/// additionally need an `fsync` of the temp + dir, overkill for a setup-time config write.)
pub(crate) fn write_config_atomically(path: impl AsRef<Path>, content: &str) -> Result<(), String> {
  let path = path.as_ref();
  let tmp = path.with_extension("toml.tmp");
  std::fs::write(&tmp, content).map_err(|e| format!("cannot write {}: {e}", tmp.display()))?;
  std::fs::rename(&tmp, path).map_err(|e| format!("cannot publish {}: {e}", path.display()))?;
  Ok(())
}

/// Structured diagnostics — the data contract shared by `cortex doctor` and its agent twin.
#[derive(Debug, Serialize)]
pub struct DoctorReport {
  /// The database accepts a connection and a trivial query.
  pub database_reachable: bool,
  /// The schema is at the latest embedded migration.
  pub migrations_current: bool,
  /// The built-in `init` and `import` services are seeded.
  pub services_seeded: bool,
  /// At least one admin/API token is configured (`auth.rerun_tokens`) — i.e. the deployment is
  /// sign-in-able. **Informational, not part of `ok`**: a freshly-`init`ed box legitimately has
  /// none until `cortex set-admin-token` runs, so this must not make `cortex init` exit
  /// non-zero.
  pub admin_token_configured: bool,
  /// Whether every *blocking* check passed (database + migrations + seeded services).
  pub ok: bool,
}

impl DoctorReport {
  /// Actionable next-step hints for any failing or unconfigured check, in fix-this-first order, so
  /// a stuck operator is told *how* to fix a red check, not merely that it is red. Empty when the
  /// box is healthy and configured. Shared by the `cortex doctor` text output and its JSON twin
  /// (the agent gets the same guidance).
  #[must_use]
  pub fn remediations(&self) -> Vec<String> {
    let mut hints = Vec::new();
    if !self.database_reachable {
      // Until the database is back, the migration / service checks are unknowable — fix this first
      // and re-run, rather than chasing the cascade of `false`s it produces.
      hints.push(
        "database unreachable — check the database URL (`cortex.toml` [database].url, or \
         DATABASE_URL) and that PostgreSQL is running"
          .to_string(),
      );
      return hints;
    }
    if !self.migrations_current {
      hints
        .push("schema out of date — run `cortex init` to apply the pending migrations".to_string());
    }
    // The built-in services are seeded by a migration, so a missing pair *while migrations are
    // current* means they were removed out of band; otherwise `cortex init` (above) restores them,
    // and a separate hint here would be redundant noise.
    if !self.services_seeded && self.migrations_current {
      hints.push(
        "the built-in `init`/`import` services are missing despite current migrations — they were \
         likely deleted; re-create them (originally seeded by migration \
         2017-10-01-204801_services)"
          .to_string(),
      );
    }
    if !self.admin_token_configured {
      hints.push(
        "no admin token configured — run `cortex set-admin-token --generate --owner <you>` to \
         enable sign-in and write actions"
          .to_string(),
      );
    }
    hints
  }
}

/// The outcome of `cortex init`.
#[derive(Debug, Serialize)]
pub struct InitOutcome {
  /// Migration versions applied (empty when the database was already current).
  pub migrations_applied: Vec<String>,
  /// Whether a configuration file was scaffolded (because it was missing).
  pub config_created: bool,
}

/// Runs the install diagnostics against the given database URL.
pub fn doctor(database_url: &str) -> DoctorReport {
  // Auth readiness is independent of the database — a token may be configured even if the DB is
  // down.
  let admin_token_configured = !crate::config::config().auth.rerun_tokens.is_empty();
  match PgConnection::establish(database_url) {
    Ok(mut connection) => {
      let database_reachable = diesel::sql_query("SELECT 1")
        .execute(&mut connection)
        .is_ok();
      let migrations_current = !migrations::has_pending_migrations(&mut connection);
      let services_seeded = builtin_services_present(&mut connection);
      DoctorReport {
        database_reachable,
        migrations_current,
        services_seeded,
        admin_token_configured,
        ok: database_reachable && migrations_current && services_seeded,
      }
    },
    Err(_) => DoctorReport {
      database_reachable: false,
      migrations_current: false,
      services_seeded: false,
      admin_token_configured,
      ok: false,
    },
  }
}

/// Minimum PostgreSQL server version CorTeX requires (`180000` = 18.0). The migrations use
/// **PG18-only features** — `uuidv7()` defaults on the external-handle columns and the
/// report-summary materialized-view rollups — so an older server cannot run them. `init`
/// pre-flights this and fails with a clear message instead of a cryptic mid-migration `function
/// "uuidv7" does not exist`.
const MIN_PG_VERSION_NUM: i32 = 180_000;

/// Reads PostgreSQL's `server_version_num` (e.g. `180004` for 18.4); `None` if the probe itself
/// fails (then we let the migration proceed rather than block on a probe error — the migration is
/// the backstop).
fn server_version_num(connection: &mut PgConnection) -> Option<i32> {
  use diesel::dsl::sql;
  use diesel::sql_types::Integer;
  diesel::select(sql::<Integer>("current_setting('server_version_num')::int"))
    .get_result::<i32>(connection)
    .ok()
}

/// Self-migrates the database (embedded migrations) and scaffolds a config file if one is missing.
pub fn init(database_url: &str, config_path: &Path) -> Result<InitOutcome, String> {
  let mut connection = PgConnection::establish(database_url)
    .map_err(|e| format!("cannot connect to database: {e}"))?;
  // Pre-flight the server version: fail fast with a clear message on PostgreSQL < 18 instead of a
  // cryptic mid-migration error. A probe failure (`None`) doesn't block — the migration still runs.
  if let Some(version) = server_version_num(&mut connection)
    && version < MIN_PG_VERSION_NUM
  {
    return Err(format!(
      "CorTeX requires PostgreSQL 18 or newer (the migrations use PG18-only features — `uuidv7()` \
         handle defaults and the report-summary materialized views); this server is {}.{}. Upgrade \
         PostgreSQL and re-run `cortex init`.",
      version / 10000,
      version % 10000
    ));
  }
  let migrations_applied = migrations::run_pending_migrations(&mut connection)
    .map_err(|e| format!("migration failed: {e}"))?;
  let config_created = if config_path.exists() {
    false
  } else {
    let toml = to_persisted_toml(&CortexConfig::default())
      .map_err(|e| format!("cannot serialize config: {e}"))?;
    write_config_atomically(config_path, &toml)?;
    true
  };
  // Scaffold an **empty** JSON token file (`config.json` / `CORTEX_AUTH_FILE`) — the single source
  // of truth for admin/API tokens — if one is missing, so the operator has a discoverable place for
  // `cortex set-admin-token` to fill in. Seeded empty on purpose: never copy the demo
  // `config.example.json` tokens into a live deployment (they are public in the repo).
  let auth_path = crate::config::auth_file_path();
  if !auth_path.exists() {
    let empty = serde_json::to_string_pretty(&TokenFile::default())
      .map_err(|e| format!("cannot serialize token file: {e}"))?;
    write_config_atomically(&auth_path, &empty)?;
  }
  Ok(InitOutcome {
    migrations_applied,
    config_created,
  })
}

/// The outcome of `cortex set-admin-token`.
#[derive(Debug, Serialize)]
pub struct SetTokenOutcome {
  /// The owner the token now maps to.
  pub owner: String,
  /// `true` if the token already existed (its owner was updated) rather than added.
  pub replaced: bool,
  /// How many tokens are configured after the write.
  pub token_count: usize,
}

/// Generates a fresh random admin/API token: 32 URL-safe alphanumeric characters (~190 bits). Used
/// by `cortex set-admin-token --generate`. The token is a plaintext bearer credential (the
/// lightweight scheme — see `docs/archive/AAA_DESIGN.md`); hashing-at-rest is a documented later
/// step.
pub fn generate_token() -> String {
  rand::rng()
    .sample_iter(&Alphanumeric)
    .take(32)
    .map(char::from)
    .collect()
}

/// Sets (or updates) an admin/API token in the JSON token file at `auth_path` (`config.json` /
/// `CORTEX_AUTH_FILE`) — the **single source of truth** for `rerun_tokens` — **merging** into the
/// existing file so other tokens are preserved. The library logic behind `cortex set-admin-token`.
///
/// If the file is missing it is created with just this token (an empty `rerun_tokens` map
/// otherwise). There is no `cortex.toml [auth]` layering anymore, so a written token takes effect
/// immediately (the frontend re-reads this file on every gated request). Mapping the token to a
/// per-person `owner` is what gives the audit log its actor (`docs/archive/AAA_DESIGN.md`).
pub fn set_admin_token(
  auth_path: &Path,
  token: &str,
  owner: &str,
) -> Result<SetTokenOutcome, String> {
  if token.is_empty() {
    return Err("refusing to set an empty token".to_string());
  }
  // Read the existing token file (empty map when none exists yet), merge, write back as JSON.
  let mut file: TokenFile = match std::fs::read_to_string(auth_path) {
    Ok(text) => serde_json::from_str(&text)
      .map_err(|e| format!("cannot parse {}: {e}", auth_path.display()))?,
    Err(_) => TokenFile::default(),
  };
  let replaced = file
    .rerun_tokens
    .insert(token.to_string(), owner.to_string())
    .is_some();
  let token_count = file.rerun_tokens.len();
  let serialized =
    serde_json::to_string_pretty(&file).map_err(|e| format!("cannot serialize token file: {e}"))?;
  write_config_atomically(auth_path, &serialized)?;
  Ok(SetTokenOutcome {
    owner: owner.to_string(),
    replaced,
    token_count,
  })
}

/// The outcome of `cortex revoke-token`.
#[derive(Debug, Serialize)]
pub struct RevokeTokenOutcome {
  /// How many tokens this call removed (`0` if none matched).
  pub revoked: usize,
  /// How many tokens remain configured afterward.
  pub token_count: usize,
}

/// Revokes admin/API token(s) from the JSON token file at `auth_path` (`config.json` /
/// `CORTEX_AUTH_FILE`) — the inverse of [`set_admin_token`]. Removes either a specific `token` or
/// **every** token mapped to `owner` (the caller supplies exactly one). Merges into the existing
/// file (other tokens are preserved) and writes atomically; rewrites only when something actually
/// changed. The library logic behind `cortex revoke-token`. A revoked token stops working
/// immediately — the frontend re-reads this file on every gated request.
pub fn revoke_admin_token(
  auth_path: &Path,
  token: Option<&str>,
  owner: Option<&str>,
) -> Result<RevokeTokenOutcome, String> {
  let mut file: TokenFile = match std::fs::read_to_string(auth_path) {
    Ok(text) => serde_json::from_str(&text)
      .map_err(|e| format!("cannot parse {}: {e}", auth_path.display()))?,
    Err(_) => {
      return Err(format!(
        "no token file at {} — nothing to revoke",
        auth_path.display()
      ));
    },
  };
  let revoked = match (token, owner) {
    (Some(tok), _) => usize::from(file.rerun_tokens.remove(tok).is_some()),
    (None, Some(own)) => {
      let matching: Vec<String> = file
        .rerun_tokens
        .iter()
        .filter(|(_, value)| value.as_str() == own)
        .map(|(key, _)| key.clone())
        .collect();
      for key in &matching {
        file.rerun_tokens.remove(key);
      }
      matching.len()
    },
    (None, None) => return Err("specify a token to revoke, or --owner <name>".to_string()),
  };
  let token_count = file.rerun_tokens.len();
  if revoked > 0 {
    let serialized = serde_json::to_string_pretty(&file)
      .map_err(|e| format!("cannot serialize token file: {e}"))?;
    write_config_atomically(auth_path, &serialized)?;
  }
  Ok(RevokeTokenOutcome {
    revoked,
    token_count,
  })
}

/// Operator guidance for tuning the PostgreSQL **server** (`shared_buffers`, `work_mem`, …),
/// printed by `cortex tune-db` and at the end of `cortex init`. Per the owner decision (see
/// `docs/DB_TUNING.md`), `cortex` does **not** reimplement the pgtune heuristic — it points at the
/// upstream service and pre-fills the host's RAM / cores so the operator's inputs are ready. The
/// per-table autovacuum is
/// already automatic (a migration); this is the host-sized server config (see `docs/DB_TUNING.md`).
pub fn db_tuning_guidance() -> String {
  format!(
    "PostgreSQL server tuning is recommended but not automated.\n\
     CorTeX is a \"Mixed\" workload (OLTP task/log writes + DW bulk-loads + reporting); the stock\n\
     defaults (shared_buffers=128MB, work_mem=4MB) are far too small for a real corpus.\n\n\
     1. Generate a config at https://pgtune.leopard.in.ua/ with these inputs:\n\
     \x20    DB Type = mixed   OS = linux   DB Version = <your PG major>\n\
     \x20    Total RAM = {ram}   CPUs = {cores}   Connections = 300   Storage = nvme (or ssd)\n\
     2. Apply the ALTER SYSTEM block it prints, then restart PostgreSQL.\n\
     \x20  (build note: keep wal_compression=lz4 / io_method=io_uring only if your build supports them.)\n\n\
     A verified example block (256 GB / 64 cores / nvme) is in docs/DB_TUNING.md.",
    ram = total_ram_hint(),
    cores = core_hint(),
  )
}

/// Best-effort host RAM for the tuning guidance (Linux `/proc/meminfo`), or a placeholder.
fn total_ram_hint() -> String {
  std::fs::read_to_string("/proc/meminfo")
    .ok()
    .and_then(|meminfo| {
      meminfo
        .lines()
        .find(|line| line.starts_with("MemTotal"))
        .and_then(|line| line.split_whitespace().nth(1))
        .and_then(|kb| kb.parse::<u64>().ok())
    })
    .map(|kb| format!("{} GB", kb / 1024 / 1024))
    .unwrap_or_else(|| "<your host RAM>".to_string())
}

/// Best-effort CPU hint for the tuning guidance (logical count, with a physical-cores reminder).
fn core_hint() -> String {
  std::thread::available_parallelism()
    .map(|logical| {
      format!("{logical} (use *physical* cores — often half this on hyperthreaded CPUs)")
    })
    .unwrap_or_else(|_| "<physical cores>".to_string())
}

/// Whether the built-in `init` and `import` services are present in the database.
fn builtin_services_present(connection: &mut PgConnection) -> bool {
  use crate::schema::services::dsl::{name, services};
  let count: i64 = services
    .filter(name.eq_any(["init", "import"]))
    .count()
    .get_result(connection)
    .unwrap_or(0);
  count >= 2
}