isb_daemon/daemon/

apps.rs

//! The app tools (`project_*`, `environment_*`, `app_*`) and the public
//! webhook route, over [`crate::app::Apps`].

use std::time::Duration;

mod delete;
pub(crate) mod manifest;

pub(super) use delete::{KEEP_MONITORS, delete_tools, empty_org, stack_targets};

use serde::Deserialize;
use serde_json::{Value, json};

use super::{args, caller_name, obj};
use crate::app::deploy::Trigger;
use crate::app::{App, AppSpec, Apps, EnvValue};
use crate::error::{Error, Result};
use crate::org::OrgId;
use crate::server::{Caller, Registry, Tool};

/// Where an app's webhook is served.
pub fn webhook_path(org: &OrgId, app: &str) -> String {
    format!("/api/v1/webhooks/{org}/{app}")
}

fn org_of(a: &Value) -> Result<OrgId> {
    super::arg_org(a)
}

pub(super) fn trigger(c: &Caller) -> Trigger {
    // The CLI on the host; a superadmin over HTTP is an API call.
    if c.is_local() {
        Trigger::Manual
    } else {
        Trigger::Api
    }
}

/// An app as the tools show it: its settings, where it runs, and its
/// environment as a map with secret references (never values).
pub fn app_json(org: &OrgId, a: &App) -> Value {
    let mut v = serde_json::to_value(&a.spec).unwrap_or_default();
    let stack = a.spec.stack().unwrap_or_default();
    let vars: serde_json::Map<String, Value> = a
        .spec
        .env
        .vars()
        .map(|(k, v)| {
            (
                k.to_string(),
                match v {
                    EnvValue::Plain(s) => json!(s),
                    EnvValue::Secret { secret } => json!({"secret": secret}),
                },
            )
        })
        .collect();
    let o = v.as_object_mut().expect("an app is an object");
    o.insert("env_vars".into(), Value::Object(vars));
    o.insert("stack".into(), json!(stack));
    o.insert(
        "service_name".into(),
        json!(format!("{}.{stack}", a.spec.name)),
    );
    o.insert("current_deployment".into(), json!(a.current));
    o.insert("created_at".into(), json!(a.created_at));
    o.insert("updated_at".into(), json!(a.updated_at));
    o.insert("webhook".into(), json!(webhook_path(org, &a.spec.name)));
    o.insert(
        "domains_served".into(),
        json!(crate::app::compose_takes_domains()),
    );
    if let crate::app::Source::Database(db) = &a.spec.source {
        o.insert(
            "connection".into(),
            crate::app::database::connection(&a.spec, db, org, None),
        );
    }
    v
}

/// What `app_create` and `app_update` answer with when the app has domains
/// and the server runs without an ingress.
pub const NO_INGRESS_WARNING: &str = "This server has no ingress, so domains aren't served. A platform admin starts isb serve with --ingress-https (or a Cloudflare Tunnel for the org).";

/// Add `ingress_enabled` to an app as the tools show it, and return the
/// warning when its domains will not be served.
pub(super) fn note_ingress(app: &mut Value, ingress: bool) -> Option<&'static str> {
    let has_domains = app
        .get("domains")
        .and_then(Value::as_array)
        .is_some_and(|d| !d.is_empty());
    if let Some(o) = app.as_object_mut() {
        o.insert("ingress_enabled".into(), json!(ingress));
    }
    (!ingress && has_domains).then_some(NO_INGRESS_WARNING)
}

/// What the app's service is doing now (`state`, and `message` when it is
/// failing: "image ... not found", say), or `None` before its first deploy.
fn service_status(ap: &Apps, org: &OrgId, app: &App) -> Option<Value> {
    let stack = app.spec.stack().ok()?;
    let st = ap
        .controller()
        .status(&crate::stack::qualified(org, &stack))
        .ok()?;
    let s = st
        .services
        .into_iter()
        .find(|s| s.service == app.spec.name)?;
    let mut v = json!({"state": s.state, "replicas": s.replicas, "healthy": s.healthy});
    if let Some(m) = s.message {
        v["message"] = json!(m);
    }
    Some(v)
}

/// Put the image check's warning and the ingress one in a tool's answer.
pub(super) fn warn(out: &mut Value, image: Option<String>, ingress: Option<&str>) {
    let all: Vec<String> = image.into_iter().chain(ingress.map(String::from)).collect();
    if !all.is_empty() {
        out["warning"] = json!(all.join("\n"));
    }
}

/// Check the image an update's patch would leave the app with, when it
/// changes. A patch that does not make valid settings is left to `update`
/// to refuse.
fn check_patched_image(
    ap: &Apps,
    org: &OrgId,
    name: &str,
    patch: &Value,
) -> Result<Option<String>> {
    let cur = ap.get(org, name)?;
    let mut v = serde_json::to_value(&cur.spec)?;
    crate::app::merge_patch(&mut v, patch);
    match serde_json::from_value::<AppSpec>(v) {
        Ok(next) => ap.check_image(Some(&cur.spec), &next),
        Err(_) => Ok(None),
    }
}

const APP_PROPS: &str = r#"{
  "source": {"type": "object", "description": "Exactly one of {\"image\": IMAGE} or {\"git\": {\"url\", \"ref\" (branch, tag or SHA; default main), \"subdir\", \"auth\": {\"token_secret\": NAME, \"username\"} | {\"ssh_key_secret\": NAME}, \"submodules\": false}}. IMAGE always carries its registry's prefix: Docker Hub is docker:NAME[:TAG] or docker:OWNER/NAME[:TAG] (docker:nginx:1.27, docker:traefik/whoami; never docker:traefik:whoami, which is the tag whoami of the image traefik), then ghcr:OWNER/NAME[:TAG], quay:OWNER/NAME[:TAG], oci:HOST/PATH[:TAG], registry:APP[:TAG] for the org's own builds; a name with no prefix is an image already on the host. A registry image is looked up when saved: one the registry does not have is refused, one that cannot be checked (offline, private) is saved with a warning."},
  "build": {"type": "object", "description": "Git sources only: {\"builder\": {\"type\": \"railpack\" | \"nixpacks\" | \"dockerfile\" (path, target) | \"buildpacks\" (builder)}, \"args\": {K: V}, \"untrusted\": true (build in a VM)}."},
  "env": {"description": ".env text, or a map {KEY: \"value\" | {\"secret\": NAME}}. A secret is an org secret, delivered as the variable."},
  "domains": {"type": "array", "items": {"type": "object"}, "description": "[{host, path?, port?, https?, redirect?}] for the ingress; port defaults to the app's port."},
  "volumes": {"type": "array", "items": {"type": "string"}, "description": "Named volumes, NAME:/path[:ro]. No host paths."},
  "ports": {"type": "array", "items": {"type": "string"}, "description": "Published host ports, compose syntax (127.0.0.1:8080:80), load-balanced over healthy replicas."},
  "replicas": {"type": "integer", "minimum": 0, "maximum": 100},
  "port": {"type": "integer", "minimum": 1, "maximum": 65535, "description": "The port the app listens on."},
  "healthcheck": {"type": "object", "description": "A compose healthcheck: {test, interval, timeout, retries, start_period}."},
  "command": {"description": "argv (a list) or a command line."},
  "previews": {"type": "object", "description": "Preview deployments per pull request (git sources): {enabled, branches (base branches; default the app's ref), max (default 3), env (.env text or {KEY: value | {secret: NAME}}), inherit_env (default false), domain (auto | *.suffix), port, replicas (default 1), resources, ttl (e.g. 7d), forks (default false; fork PRs build in a VM and get only fork_secrets), fork_secrets [NAME], status {token_secret, kind: github | gitea, api_url}}. See preview_list."},
  "files": {"type": "array", "items": {"type": "object"}, "description": "[{path, secret, mode?}]: an org secret's value as a file at an absolute path (config files, certificates)."},
  "user": {"type": "string", "description": "The user the app runs as; numeric (uid[:gid]) on an OCI image."},
  "working_dir": {"type": "string"},
  "secret_on_change": {"type": "string", "enum": ["roll", "restart", "none"], "description": "What a new version of a secret the app uses (env or files) does to its replicas: roll (default; a rolling update), restart (each replica's app restarted in place with the new value, one at a time, waiting until healthy) or none (files updated, replicas reported stale until they next start)."}
}"#;

fn app_props() -> Value {
    let mut p: Value = serde_json::from_str(APP_PROPS).expect("APP_PROPS is JSON");
    p["resources"] = crate::app::resources_schema();
    p
}

/// app_create's properties: the app's, plus where it goes.
fn create_props() -> Value {
    let mut create_props = app_props();
    create_props["name"] = json!({"type": "string", "description": "[a-z0-9-], unique in the org; the service name in its stack."});
    create_props["project"] = json!({"type": "string"});
    create_props["environment"] = json!({"type": "string", "description": "Default production."});
    create_props["deploy"] =
        json!({"type": "boolean", "description": "Queue a deploy right away."});
    create_props
}

/// app_update's properties.
fn update_props() -> Value {
    let mut update_props = app_props();
    update_props["name"] = json!({"type": "string"});
    update_props["deploy"] =
        json!({"type": "boolean", "description": "Queue a deploy after the change."});
    update_props
}

/// The properties of the tools that can wait for a deployment.
fn wait_props() -> Value {
    json!({
        "name": {"type": "string"},
        "wait": {"type": "boolean", "description": "Wait until the deployment finishes (default false)."},
        "timeout": {"type": "string", "description": "How long wait may take, e.g. 10m (default 15m)."}
    })
}

/// app_rollback's properties.
fn rb_props() -> Value {
    let mut rb_props = wait_props();
    rb_props["deployment"] = json!({"type": "integer", "minimum": 1, "description": "The deployment to go back to (default: the last successful one before the current)."});
    rb_props
}

/// The MCP annotations the tools below share.
struct Ann {
    ro: Value,
    write: Value,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Named {
    name: String,
    #[serde(default)]
    #[allow(dead_code)]
    org: Option<String>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct EnvArgs {
    project: String,
    #[serde(default)]
    name: Option<String>,
    #[serde(default)]
    #[allow(dead_code)]
    org: Option<String>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct DeployArgs {
    name: String,
    #[serde(default)]
    deployment: Option<u64>,
    #[serde(default)]
    wait: bool,
    #[serde(default)]
    timeout: Option<String>,
    #[serde(default)]
    #[allow(dead_code)]
    org: Option<String>,
}

fn finish(ap: &Apps, org: &OrgId, a: &DeployArgs, id: u64) -> Result<Value> {
    let d = if a.wait {
        let t = match &a.timeout {
            Some(t) => crate::flex::parse_duration(t).map_err(Error::invalid)?,
            None => Duration::from_secs(900),
        };
        ap.wait(org, &a.name, id, t)?
    } else {
        ap.deployment(org, &a.name, id)?
    };
    Ok(json!({"deployment": d.summary()}))
}

pub fn register(r: &mut Registry, apps: Apps, ingress: bool) -> Result<()> {
    let ann = Ann {
        ro: json!({"readOnlyHint": true, "openWorldHint": false}),
        write: json!({"destructiveHint": false, "openWorldHint": false}),
    };

    project_create_tool(r, &apps, &ann)?;
    project_list_tool(r, &apps, &ann)?;

    environment_create_tool(r, &apps, &ann)?;
    environment_list_tool(r, &apps, &ann)?;

    app_create_tool(r, &apps, &ann, ingress)?;
    app_get_tool(r, &apps, &ann, ingress)?;
    app_list_tool(r, &apps, &ann, ingress)?;
    app_update_tool(r, &apps, &ann, ingress)?;

    app_deploy_tool(r, &apps, &ann)?;
    app_rollback_tool(r, &apps, &ann)?;
    app_deployments_tool(r, &apps, &ann)?;
    app_deployment_log_tool(r, &apps, &ann)?;
    app_env_get_tool(r, &apps, &ann)?;
    app_env_set_tool(r, &apps, &ann)?;
    app_webhook_tool(r, &apps, &ann)?;
    app_deploy_key_tool(r, &apps, &ann)?;
    manifest::register(r, apps, ingress)
}

fn project_create_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "project_create",
        "Create a project",
        "Create a project in an org: a group of environments (default: production), each of which runs its apps as one stack named <project>-<env>.",
        obj(
            json!({
                "name": {"type": "string"},
                "description": {"type": "string"},
                "environments": {"type": "array", "items": {"type": "string"}, "description": "Default [production]."}
            }),
            &["name"]
        ),
        ann.write,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            #[derive(Deserialize)]
            #[serde(deny_unknown_fields)]
            struct A {
                name: String,
                #[serde(default)]
                description: String,
                #[serde(default)]
                environments: Vec<String>,
                #[serde(default)]
                #[allow(dead_code)]
                org: Option<String>,
            }
            let org = org_of(&a)?;
            let a: A = args(a)?;
            Ok(json!(ap.project_create(
                &org,
                &a.name,
                &a.description,
                &a.environments
            )?))
        }
    );
    Ok(())
}

fn project_list_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "project_list",
        "List projects",
        "An org's projects, each with its environments and, in each, its apps and its compose stacks (`compose`: name, services and `deployed_at`, unix seconds) and `conflicts`: a compose service that does not get the environment's name `<service>.<project>-<env>` because `winner` (a stack; `<project>-<env>` for an app) holds it.",
        obj(json!({}), &[]),
        ann.ro,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let apps = ap.list(&org)?;
            let projects: Vec<Value> = ap
                .project_list(&org)?
                .into_iter()
                .map(|p| {
                    let envs: Vec<Value> = p
                        .environments
                        .iter()
                        .map(|e| {
                            let names: Vec<&str> = apps
                                .iter()
                                .filter(|x| x.spec.project == p.name && &x.spec.environment == e)
                                .map(|x| x.spec.name.as_str())
                                .collect();
                            let ec = ap.environment_compose(&org, &p.name, e);
                            let compose: Vec<Value> = ec
                                .stacks
                                .iter()
                                .map(|(s, svcs)| {
                                    let at = ap
                                        .controller()
                                        .definition(&crate::stack::qualified(&org, s))
                                        .ok()
                                        .map(|d| d.deployed_at);
                                    json!({"name": s, "services": svcs, "deployed_at": at})
                                })
                                .collect();
                            json!({
                                "name": e,
                                "stack": format!("{}-{e}", p.name),
                                "apps": names,
                                "compose": compose,
                                "conflicts": ec.conflicts,
                            })
                        })
                        .collect();
                    json!({"name": p.name, "description": p.description, "created_at": p.created_at, "environments": envs})
                })
                .collect();
            Ok(json!({"projects": projects}))
        }
    );
    Ok(())
}

fn environment_create_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "environment_create",
        "Create an environment",
        "Add an environment (staging, preview, ...) to a project. Its apps run as the stack <project>-<name>.",
        obj(
            json!({"project": {"type": "string"}, "name": {"type": "string"}}),
            &["project", "name"]
        ),
        ann.write,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let a: EnvArgs = args(a)?;
            let name = a.name.ok_or_else(|| Error::invalid("name is required"))?;
            Ok(json!(ap.environment_create(&org, &a.project, &name)?))
        }
    );
    Ok(())
}

fn environment_list_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "environment_list",
        "List environments",
        "A project's environments.",
        obj(json!({"project": {"type": "string"}}), &["project"]),
        ann.ro,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let a: EnvArgs = args(a)?;
            let p = ap.project_get(&org, &a.project)?;
            Ok(json!({"environments": p.environments}))
        }
    );
    Ok(())
}

fn app_create_tool(r: &mut Registry, apps: &Apps, ann: &Ann, ingress: bool) -> Result<()> {
    tool!(
        r,
        apps,
        "app_create",
        "Create an app",
        "Create an application in a project's environment: an image or a git source (built by a builder), plus its env, domains, volumes, ports, replicas, port, health check, resources and command. Returns the app and its webhook secret (POST <webhook> with it to deploy). Nothing runs until app_deploy (or deploy=true).",
        obj(create_props(), &["name", "project", "source"]),
        ann.write,
        move |ap: &Apps, mut a: Value, c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let deploy = a.get("deploy").and_then(Value::as_bool).unwrap_or(false);
            if let Some(o) = a.as_object_mut() {
                o.remove("org");
                o.remove("deploy");
            }
            let spec: AppSpec = args(a)?;
            let image = ap.check_image(None, &spec)?;
            let (app, secret) = ap.create(&org, spec)?;
            let mut aj = app_json(&org, &app);
            let ingress = note_ingress(&mut aj, ingress);
            let mut out = json!({"app": aj, "webhook_secret": secret});
            warn(&mut out, image, ingress);
            if deploy {
                let d = ap.deploy(&org, &app.spec.name, trigger(c), &caller_name(c), None)?;
                out["deployment"] = d.summary();
            }
            Ok(out)
        }
    );
    Ok(())
}

fn app_get_tool(r: &mut Registry, apps: &Apps, ann: &Ann, ingress: bool) -> Result<()> {
    tool!(
        r,
        apps,
        "app_get",
        "Get an app",
        "An app's settings, stack, service name, current deployment and webhook path, and what its service is doing now: status {state (converged, updating, failing, ...), replicas, healthy, message (why it is failing, e.g. image ... not found)}. Secrets in its env show as {secret: NAME}, never values.",
        obj(json!({"name": {"type": "string"}}), &["name"]),
        ann.ro,
        move |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let a: Named = args(a)?;
            let app = ap.get(&org, &a.name)?;
            let mut v = app_json(&org, &app);
            note_ingress(&mut v, ingress);
            if let Some(st) = service_status(ap, &org, &app) {
                v["status"] = st;
            }
            Ok(v)
        }
    );
    Ok(())
}

fn app_list_tool(r: &mut Registry, apps: &Apps, ann: &Ann, ingress: bool) -> Result<()> {
    tool!(
        r,
        apps,
        "app_list",
        "List apps",
        "An org's apps, optionally only one project's (and environment's).",
        obj(
            json!({"project": {"type": "string"}, "environment": {"type": "string"}}),
            &[]
        ),
        ann.ro,
        move |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            #[derive(Deserialize)]
            #[serde(deny_unknown_fields)]
            struct A {
                project: Option<String>,
                environment: Option<String>,
                #[serde(default)]
                #[allow(dead_code)]
                org: Option<String>,
            }
            let org = org_of(&a)?;
            let a: A = args(a)?;
            let apps: Vec<Value> = ap
                .list(&org)?
                .into_iter()
                .filter(|x| a.project.as_ref().is_none_or(|p| *p == x.spec.project))
                .filter(|x| {
                    a.environment
                        .as_ref()
                        .is_none_or(|e| *e == x.spec.environment)
                })
                .map(|x| {
                    let mut v = app_json(&org, &x);
                    note_ingress(&mut v, ingress);
                    v
                })
                .collect();
            Ok(json!({"apps": apps}))
        }
    );
    Ok(())
}

fn app_update_tool(r: &mut Registry, apps: &Apps, ann: &Ann, ingress: bool) -> Result<()> {
    tool!(
        r,
        apps,
        "app_update",
        "Update an app",
        "Change an app's settings: the fields given replace the current ones (a JSON merge patch: null clears a setting; objects merge). Name, project and environment are fixed. Takes effect at the next deploy (deploy=true queues one).",
        obj(update_props(), &["name"]),
        ann.write,
        move |ap: &Apps, mut a: Value, c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let deploy = a.get("deploy").and_then(Value::as_bool).unwrap_or(false);
            let name = a
                .get("name")
                .and_then(Value::as_str)
                .ok_or_else(|| Error::invalid("name is required"))?
                .to_string();
            if let Some(o) = a.as_object_mut() {
                o.remove("org");
                o.remove("deploy");
                o.remove("name");
            }
            let image = match a.get("source") {
                Some(_) => check_patched_image(ap, &org, &name, &a)?,
                None => None,
            };
            let app = ap.update(&org, &name, &a)?;
            let mut aj = app_json(&org, &app);
            let ingress = note_ingress(&mut aj, ingress);
            let mut out = json!({"app": aj});
            warn(&mut out, image, ingress);
            if deploy {
                let d = ap.deploy(&org, &name, trigger(c), &caller_name(c), None)?;
                out["deployment"] = d.summary();
            }
            Ok(out)
        }
    );
    Ok(())
}

fn app_deploy_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "app_deploy",
        "Deploy an app",
        "Deploy an app's current settings: pull (an image source, pinned to its digest) or fetch and build (a git source), then roll its service in its environment's stack; other apps there are untouched. One deploy runs at a time per app; a new one waits behind it and replaces any other waiting one. Returns the deployment record; follow it with app_deployment_log or the events feed.",
        obj(wait_props(), &["name"]),
        ann.write,
        |ap: &Apps, a: Value, c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let a: DeployArgs = args(a)?;
            let d = ap.deploy(&org, &a.name, trigger(c), &caller_name(c), None)?;
            finish(ap, &org, &a, d.id)
        }
    );
    Ok(())
}

fn app_rollback_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "app_rollback",
        "Roll back an app",
        "Redeploy a previous successful deployment's image (by digest when known) and settings, without building. The app's saved settings are not changed, so the next deploy applies them again.",
        obj(rb_props(), &["name"]),
        ann.write,
        |ap: &Apps, a: Value, c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let a: DeployArgs = args(a)?;
            let d = ap.rollback(&org, &a.name, a.deployment, trigger(c), &caller_name(c))?;
            finish(ap, &org, &a, d.id)
        }
    );
    Ok(())
}

fn app_deployments_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "app_deployments",
        "List an app's deployments",
        "An app's deployments, newest first: trigger, status (queued, building, deploying, done, failed, superseded), commit, image and digest, timestamps.",
        obj(
            json!({"name": {"type": "string"}, "limit": {"type": "integer", "minimum": 1, "maximum": 100}}),
            &["name"]
        ),
        ann.ro,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            #[derive(Deserialize)]
            #[serde(deny_unknown_fields)]
            struct A {
                name: String,
                limit: Option<usize>,
                #[serde(default)]
                #[allow(dead_code)]
                org: Option<String>,
            }
            let org = org_of(&a)?;
            let a: A = args(a)?;
            let app = ap.get(&org, &a.name)?;
            let ds: Vec<Value> = ap
                .deployments(&org, &a.name)?
                .into_iter()
                .take(a.limit.unwrap_or(20))
                .map(|d| d.summary())
                .collect();
            Ok(json!({"current": app.current, "deployments": ds}))
        }
    );
    Ok(())
}

fn app_deployment_log_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "app_deployment_log",
        "A deployment's log",
        "A deployment's log (git, build and rollout lines) from byte `offset`. Returns the text, the offset to ask from next, whether the deployment has finished, and its record (status, image, commit, timings; read before the text, so a finished record means the text is complete): poll until done. The same lines stream on the events feed as level `log`.",
        obj(
            json!({
                "name": {"type": "string"},
                "deployment": {"type": "integer", "minimum": 1},
                "offset": {"type": "integer", "minimum": 0}
            }),
            &["name", "deployment"]
        ),
        ann.ro,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            #[derive(Deserialize)]
            #[serde(deny_unknown_fields)]
            struct A {
                name: String,
                deployment: u64,
                #[serde(default)]
                offset: u64,
                #[serde(default)]
                #[allow(dead_code)]
                org: Option<String>,
            }
            let org = org_of(&a)?;
            let a: A = args(a)?;
            let (log, next, d) = ap.log_and_record(&org, &a.name, a.deployment, a.offset)?;
            Ok(json!({
                "log": log,
                "offset": next,
                "finished": d.status.finished(),
                "status": d.status,
                "deployment": d.summary(),
            }))
        }
    );
    Ok(())
}

fn app_env_get_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "app_env_get",
        "Get an app's environment",
        "An app's environment as .env text (KEY=value lines, comments kept). Secret references read KEY=${{secret.NAME}}; their values are never shown.",
        obj(json!({"name": {"type": "string"}}), &["name"]),
        ann.ro,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let a: Named = args(a)?;
            Ok(json!({"env": ap.env_get(&org, &a.name)?}))
        }
    );
    Ok(())
}

fn app_env_set_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "app_env_set",
        "Set an app's environment",
        "Replace an app's environment with .env text: KEY=value lines (quotes and # comments as in docker compose; comments are kept), KEY=${{secret.NAME}} for an org secret. Takes effect at the next deploy (deploy=true queues one).",
        obj(
            json!({
                "name": {"type": "string"},
                "env": {"type": "string", "description": "The .env text."},
                "deploy": {"type": "boolean"}
            }),
            &["name", "env"]
        ),
        ann.write,
        |ap: &Apps, a: Value, c: &Caller| -> Result<Value> {
            #[derive(Deserialize)]
            #[serde(deny_unknown_fields)]
            struct A {
                name: String,
                env: String,
                #[serde(default)]
                deploy: bool,
                #[serde(default)]
                #[allow(dead_code)]
                org: Option<String>,
            }
            let org = org_of(&a)?;
            let a: A = args(a)?;
            let app = ap.env_set(&org, &a.name, &a.env)?;
            let mut out = json!({"env": app.spec.env.render()});
            if a.deploy {
                let d = ap.deploy(&org, &a.name, trigger(c), &caller_name(c), None)?;
                out["deployment"] = d.summary();
            }
            Ok(out)
        }
    );
    Ok(())
}

fn app_webhook_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "app_webhook",
        "An app's webhook",
        "The app's webhook path and secret, to configure in GitHub (application/json, the secret), Gitea/Forgejo (the secret), GitLab (secret token) or any caller (?token=<secret>). rotate=true makes a new secret first.",
        obj(
            json!({"name": {"type": "string"}, "rotate": {"type": "boolean"}}),
            &["name"]
        ),
        ann.write,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            #[derive(Deserialize)]
            #[serde(deny_unknown_fields)]
            struct A {
                name: String,
                #[serde(default)]
                rotate: bool,
                #[serde(default)]
                #[allow(dead_code)]
                org: Option<String>,
            }
            let org = org_of(&a)?;
            let a: A = args(a)?;
            let secret = ap.webhook_secret(&org, &a.name, a.rotate)?;
            Ok(json!({"path": webhook_path(&org, &a.name), "secret": secret}))
        }
    );
    Ok(())
}

fn app_deploy_key_tool(r: &mut Registry, apps: &Apps, ann: &Ann) -> Result<()> {
    tool!(
        r,
        apps,
        "app_deploy_key",
        "Make a deploy key",
        "Generate an ed25519 deploy key for a git app with an SSH URL: the private key is stored as the org secret app.<name>.deploy-key and becomes the app's credential; the public key is returned to add to the repository's deploy keys (read-only).",
        obj(json!({"name": {"type": "string"}}), &["name"]),
        ann.write,
        |ap: &Apps, a: Value, _c: &Caller| -> Result<Value> {
            let org = org_of(&a)?;
            let a: Named = args(a)?;
            Ok(json!({"public_key": ap.deploy_key(&org, &a.name)?}))
        }
    );
    Ok(())
}

/// `POST /api/v1/webhooks/<org>/<app>`: served without a session; the
/// request's signature or token is its only credential.
pub fn webhook_routes(apps: Apps) -> crate::server::Routes {
    use crate::server::http::Response;
    std::sync::Arc::new(move |req: &crate::server::http::Request| {
        let rest = req.path.strip_prefix("/api/v1/webhooks/")?;
        let (org, app) = rest.split_once('/')?;
        if app.contains('/') {
            return Some(Response::text(404, "not found"));
        }
        if req.method != "POST" {
            return Some(Response::text(405, "method not allowed").header("Allow", "POST"));
        }
        let token = req.query.as_deref().and_then(|q| {
            q.split('&')
                .find_map(|kv| kv.strip_prefix("token="))
                .map(String::from)
        });
        let header = |n: &str| req.header(n).map(String::from);
        let (status, body) = apps.webhook(org, app, &header, token.as_deref(), &req.body);
        if status == 401 {
            eprintln!(
                "isb serve: webhook {org}/{app}: refused a request from {:?}",
                req.peer
            );
        }
        Some(Response::json(status, &body).header("Cache-Control", "no-store"))
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn warns_about_domains_only_without_an_ingress() {
        let with = json!({"domains": [{"host": "auto"}]});
        let mut a = with.clone();
        assert_eq!(note_ingress(&mut a, false), Some(NO_INGRESS_WARNING));
        assert_eq!(a["ingress_enabled"], json!(false));
        let mut a = with;
        assert_eq!(note_ingress(&mut a, true), None);
        assert_eq!(a["ingress_enabled"], json!(true));
        // No domains, nothing to warn about.
        let mut none = json!({"domains": []});
        assert_eq!(note_ingress(&mut none, false), None);
        let mut absent = json!({});
        assert_eq!(note_ingress(&mut absent, false), None);
    }
}