GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
//! Headless JSON-lines server: the control protocol's envelope
//! (`{"id","method","params"}` → `{"id","ok","result"|"error"}`) over a
//! [`Headless`] session, so scripts and agents can keep one editing session
//! open without MCP or the GUI. `photocraft-cli serve` runs it on stdio or a
//! loopback TCP port.
//!
//! Methods (camelCase params):
//! - `engine.execute {command, params?, wait?}` / `engine.commands {filter?}`
//! - `jobs.list` / `jobs.cancel {job?}`: background jobs (#210)
//! - `session.list`, `doc.open {path}`, `doc.new {…file.new params}`,
//!   `doc.place {path, scale?, fit?, center?, index?}` (#2810: the read root is the scope,
//!   the counterpart of the refused ambient `file.placeEmbedded`),
//!   `doc.replaceSmartObject {path, layer?, index?}` (#8061: the same scope for
//!   `layer.smartObjects.replaceContents`),
//!   `doc.exportLayers {dir, format?, prefix?, visibleOnly?, quality?, index?}`,
//!   `doc.exportDataSets {dir, format?, dataSets?, naming?, index?}`,
//!   `doc.importDataSets {path, delimiter?, index?}` (#3216: the same treatment for the export
//!   and CSV half of #2810), `doc.save {path?, format?, quality?, index?}`, `doc.inspect {index?}`,
//!   `doc.render {index?, maxSide?, path?}` (writes a PNG to `path`, else
//!   returns it base64-encoded; adds `warnings` when a renderer fell back), `doc.select {index}`, `doc.close {index?}`
//! - `batch {steps: [{command, params?, wait?} | {method, params?}], stopOnError?}`
//! - `methods`: this list.

use std::io::{BufRead, Write};
use std::net::TcpListener;
use std::path::PathBuf;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, Mutex, PoisonError};
use std::time::{Duration, Instant};

use base64::Engine as _;
use serde_json::{Value, json};

use crate::budgets::{BatchReplyBudget, write_reply};
use crate::security::{
    AUTH_DEADLINE, AuthDeadlineStream, AuthStep, ConnectionLimiter, LineRead, MAX_BATCH_STEPS, MAX_CONNECTIONS, MAX_REQUEST_BYTES, ServerHandshake,
    configure_stream, discard_rest_of_line, read_bounded_line, repeat_auth_reply,
};
use crate::{AutomationError, Headless};

/// Method names served by [`Headless::handle`].
pub const METHODS: &[&str] = &[
    "engine.execute",
    "jobs.list",
    "jobs.cancel",
    "engine.commands",
    "session.list",
    "doc.open",
    "doc.place",
    "doc.replaceSmartObject",
    "doc.new",
    "doc.save",
    "doc.exportLayers",
    "doc.exportDataSets",
    "doc.importDataSets",
    "doc.inspect",
    "doc.render",
    "doc.select",
    "doc.close",
    "batch",
    "methods",
];

/// Adds the structured memory fields (`required`, soft and hard limits and measured capacity)
/// from a typed admission error to a JSON error object, so clients can offer approval.
fn attach_memory_error_details(obj: &mut Value, err: &AutomationError) {
    match err {
        AutomationError::Import(photocraft_io::IoError::PsdApprovalRequired { required, soft_limit, hard_limit, available_ram })
        | AutomationError::Engine(photocraft_engine::EngineError::PsdApprovalRequired { required, soft_limit, hard_limit, available_ram, .. }) => {
            if let Some(m) = obj.as_object_mut() {
                m.insert("required".into(), json!(required));
                m.insert("soft".into(), json!(soft_limit));
                m.insert("softLimit".into(), json!(soft_limit));
                m.insert("hard".into(), json!(hard_limit));
                m.insert("hardLimit".into(), json!(hard_limit));
                if let Some(avail) = available_ram {
                    m.insert("available".into(), json!(avail));
                    m.insert("availableRam".into(), json!(avail));
                }
            }
        }
        AutomationError::Import(photocraft_io::IoError::PsdImportBudget { required, limit, free_memory })
        | AutomationError::Engine(photocraft_engine::EngineError::PsdHardBudget { required, limit, free_memory, .. }) => {
            if let Some(m) = obj.as_object_mut() {
                m.insert("required".into(), json!(required));
                m.insert("hard".into(), json!(limit));
                m.insert("hardLimit".into(), json!(limit));
                if let Some(free) = free_memory {
                    m.insert("available".into(), json!(free));
                    m.insert("availableRam".into(), json!(free));
                }
            }
        }
        _ => {}
    }
}

fn bad(msg: impl Into<String>) -> AutomationError {
    AutomationError::BadRequest(msg.into())
}

/// The optional `index` param: missing or null means the active document; anything else must be a
/// non-negative integer (never silently fall back to the active document, which `doc.close` would close).
fn index_of(p: &Value) -> Result<Option<usize>, AutomationError> {
    match p.get("index") {
        None | Some(Value::Null) => Ok(None),
        Some(v) => v.as_u64().and_then(|i| usize::try_from(i).ok()).map(Some).ok_or_else(|| bad("`index` must be a non-negative integer")),
    }
}

fn str_of<'a>(p: &'a Value, k: &str) -> Option<&'a str> {
    p.get(k).and_then(Value::as_str)
}

impl Headless {
    /// Dispatch one request. Unknown methods and bad params are errors, never panics.
    pub fn handle(&mut self, method: &str, params: Value) -> Result<Value, AutomationError> {
        self.sync_jobs();
        let p = if params.is_null() { json!({}) } else { params };
        match method {
            "engine.execute" => {
                let id = str_of(&p, "command").ok_or_else(|| bad("engine.execute needs `command`"))?;
                if METHODS.contains(&id) && photocraft_engine::commands::find(id).is_none() {
                    return Err(bad(photocraft_engine::command_hints::protocol_method_as_command(id)));
                }
                let wait = p.get("wait").and_then(Value::as_bool).unwrap_or(true);
                self.command_start(id, p.get("params").cloned().unwrap_or(Value::Null), wait)
            }
            // Background jobs (#210): list (applying any that finished) and cancel.
            "jobs.list" => self.command_start("jobs.list", json!({}), true),
            "jobs.cancel" => self.command_start("jobs.cancel", p, true),
            "engine.commands" => {
                let all = self.command_list();
                Ok(match str_of(&p, "filter").map(str::to_lowercase) {
                    None => all,
                    Some(n) => {
                        Value::Array(all.as_array().into_iter().flatten().filter(|c| photocraft_engine::commands::list_entry_matches(c, &n)).cloned().collect())
                    }
                })
            }
            "session.list" => Ok(self.session_list()),
            "doc.open" => {
                let path = str_of(&p, "path").ok_or_else(|| bad("doc.open needs `path`"))?;
                let approve = match p.get("approveHighMemory") {
                    None | Some(Value::Null) => false,
                    Some(Value::Bool(b)) => *b,
                    Some(_) => return Err(bad("`approveHighMemory` must be a boolean")),
                };
                self.open_with_approval(&PathBuf::from(path), approve)
            }
            "doc.place" => {
                let path = str_of(&p, "path").ok_or_else(|| bad("doc.place needs `path`"))?;
                if p.get("approveHighMemory").is_some_and(|v| !v.is_boolean()) {
                    return Err(bad("`approveHighMemory` must be a boolean"));
                }
                let mut opts = p.as_object().cloned().unwrap_or_default();
                opts.remove("path");
                opts.remove("index");
                self.place(index_of(&p)?, path, &Value::Object(opts))
            }
            "doc.replaceSmartObject" => {
                let path = str_of(&p, "path").ok_or_else(|| bad("doc.replaceSmartObject needs `path`"))?;
                let mut opts = p.as_object().cloned().unwrap_or_default();
                opts.remove("path");
                opts.remove("index");
                self.replace_smart_object(index_of(&p)?, path, &Value::Object(opts))
            }
            "doc.new" => self.command_run("file.new", p),
            "doc.save" => {
                let tga_bits = photocraft_engine::file_cmds::tga_bits_param(&p, "doc.save").map_err(|e| bad(e.to_string()))?;
                let pdf_spot_plates = photocraft_engine::file_cmds::pdf_spot_plates_param(&p, "doc.save").map_err(|e| bad(e.to_string()))?;
                let mut opts = photocraft_io::ExportOptions {
                    tiff_layers: p.get("tiffLayers").and_then(Value::as_bool).unwrap_or(false),
                    tga_bits,
                    pdf_spot_plates,
                    pcraft_full_composite: photocraft_engine::file_cmds::pcraft_full_composite_param(&p, "doc.save")
                        .map_err(|e| bad(e.to_string()))?
                        .unwrap_or(false),
                    ..Default::default()
                };
                opts.encode.dpx_bits = photocraft_engine::file_cmds::dpx_bits_param(&p, "doc.save").map_err(|e| bad(e.to_string()))?;
                opts.encode.dds = photocraft_engine::file_cmds::dds_param(&p, "doc.save").map_err(|e| bad(e.to_string()))?.unwrap_or_default();
                if let Some(c) = photocraft_engine::file_cmds::tiff_compression_param(&p, "doc.save").map_err(|e| bad(e.to_string()))? {
                    opts.encode.tiff_compression = c;
                }
                let tiff_bool = |key| photocraft_engine::file_cmds::tiff_bool_param(&p, key, "doc.save").map_err(|e| bad(e.to_string()));
                opts.tiff_transparency = tiff_bool("tiffTransparency")?;
                opts.encode.tiff_pyramid = tiff_bool("tiffPyramid")?.unwrap_or(false);
                if let Some(maximize) = photocraft_engine::file_cmds::maximize_compatibility_param(&p, "doc.save").map_err(|e| bad(e.to_string()))? {
                    opts.psd_maximize_compatibility = maximize;
                }
                match p.get("quality") {
                    None | Some(Value::Null) => {}
                    Some(v) => {
                        // Like the CLI's `--quality`: never ignore or clamp a bad value.
                        let q = v
                            .as_u64()
                            .filter(|q| (1..=100).contains(q))
                            .and_then(|q| u8::try_from(q).ok())
                            .ok_or_else(|| bad(format!("`quality` must be a whole number from 1 to 100, got {v}")))?;
                        opts.encode.jpeg_quality = q;
                        opts.encode.webp_quality = q;
                        opts.encode.webp_lossless = false;
                    }
                }
                let path = str_of(&p, "path").map(PathBuf::from);
                self.save(index_of(&p)?, path.as_deref(), str_of(&p, "format"), &opts)
            }
            "doc.exportLayers" | "doc.exportDataSets" => {
                let dir = str_of(&p, "dir").ok_or_else(|| bad(format!("{method} needs `dir`")))?;
                let mut opts = p.as_object().cloned().unwrap_or_default();
                opts.remove("dir");
                opts.remove("index");
                let opts = Value::Object(opts);
                if method == "doc.exportLayers" { self.export_layers(index_of(&p)?, dir, &opts) } else { self.export_data_sets(index_of(&p)?, dir, &opts) }
            }
            "doc.importDataSets" => {
                let path = str_of(&p, "path").ok_or_else(|| bad("doc.importDataSets needs `path`"))?;
                let mut opts = p.as_object().cloned().unwrap_or_default();
                opts.remove("path");
                opts.remove("index");
                self.import_data_sets(index_of(&p)?, path, &Value::Object(opts))
            }
            "doc.inspect" => self.inspect(index_of(&p)?),
            "doc.render" => {
                let max = match p.get("maxSide") {
                    None => 1024,
                    Some(value) => {
                        value.as_u64().and_then(|value| u32::try_from(value).ok()).ok_or_else(|| bad("maxSide must be an unsigned 32-bit integer"))?
                    }
                };
                let png = self.render_png(index_of(&p)?, max)?;
                // A GPU to CPU fallback is reported with this reply, not on the next save.
                let warnings = self.drain_diagnostics();
                let mut reply = match str_of(&p, "path") {
                    Some(path) => {
                        self.write_render(&PathBuf::from(path), &png)?;
                        json!({"path": path, "bytes": png.len()})
                    }
                    None => json!({
                        "mime": "image/png",
                        "base64": base64::engine::general_purpose::STANDARD.encode(&png),
                    }),
                };
                if !warnings.is_empty()
                    && let Some(object) = reply.as_object_mut()
                {
                    object.insert("warnings".into(), json!(warnings));
                }
                Ok(reply)
            }
            "doc.select" => {
                let i = index_of(&p)?.ok_or_else(|| bad("doc.select needs `index`"))?;
                self.select(i)
            }
            "doc.close" => self.close(index_of(&p)?),
            "batch" => self.batch(&p),
            "methods" => Ok(json!(METHODS)),
            other => Err(bad(format!("{} (try `methods`)", photocraft_engine::command_hints::unknown_method(other, METHODS)))),
        }
    }

    /// Run `steps` in order. Each step is `{command, params?, wait?}` (an engine command) or
    /// `{method, params?}` (any [`METHODS`] entry). Stops at the first error unless
    /// `stopOnError` is false; the reply lists every step's result.
    pub fn batch(&mut self, p: &Value) -> Result<Value, AutomationError> {
        self.batch_with_budget(p, BatchReplyBudget::default())
    }

    /// [`Headless::batch`] with a caller's reply budget (MCP charges escaped sizes, see
    /// [`BatchReplyBudget::escaped`]). Steps stop once the budget runs out.
    pub fn batch_with_budget(&mut self, p: &Value, mut reply_budget: BatchReplyBudget) -> Result<Value, AutomationError> {
        let steps = p.get("steps").and_then(Value::as_array).ok_or_else(|| bad("batch needs `steps`"))?;
        if steps.len() > MAX_BATCH_STEPS {
            return Err(bad(format!("batch contains {} steps; maximum is {MAX_BATCH_STEPS}", steps.len())));
        }
        let stop = p.get("stopOnError").and_then(Value::as_bool).unwrap_or(true);
        let mut results = Vec::with_capacity(steps.len());
        let mut failed = 0usize;
        for (i, s) in steps.iter().enumerate() {
            let params = s.get("params").cloned().unwrap_or(Value::Null);
            let r = if let Some(c) = str_of(s, "command") {
                // Like `engine.execute`: `wait: false` starts a long command as a background job.
                let wait = s.get("wait").and_then(Value::as_bool).unwrap_or(true);
                self.command_start(c, params, wait)
            } else if let Some(m) = str_of(s, "method") {
                if m == "batch" { Err(bad("nested batch")) } else { self.handle(m, params) }
            } else {
                Err(bad(format!("step {i} needs `command` or `method`")))
            };
            let was_error = r.is_err();
            let result = match r {
                Ok(v) => json!({"ok": true, "result": v}),
                Err(e) => {
                    let mut obj = json!({"ok": false, "error": e.to_string()});
                    attach_memory_error_details(&mut obj, &e);
                    obj
                }
            };
            if let Err(error) = reply_budget.charge(&result) {
                failed += 1;
                results.push(json!({"ok": false, "error": format!("batch response budget exceeded; current step may have completed: {error}")}));
                break;
            }
            results.push(result);
            if was_error {
                failed += 1;
                if stop {
                    break;
                }
            }
        }
        Ok(json!({"completed": results.len() - failed, "failed": failed, "results": results}))
    }
}

/// Answer one request line. Malformed JSON gets an error reply with `id: null`.
pub fn respond(h: &Mutex<Headless>, line: &str) -> Value {
    let req: Value = match serde_json::from_str(line) {
        Ok(v) => v,
        Err(e) => return json!({"id": null, "ok": false, "error": format!("bad JSON: {e}")}),
    };
    let id = req.get("id").cloned().unwrap_or(Value::Null);
    let Some(method) = req.get("method").and_then(Value::as_str) else {
        return json!({"id": id, "ok": false, "error": "missing `method`"});
    };
    let params = req.get("params").cloned().unwrap_or(Value::Null);
    // Last-resort guard (AGENTS.md, Never crash): a command that panics answers this request
    // with an error instead of taking down the connection (or the whole stdio server). Edits
    // run on a copy of the document (`Session::edit`), so the session stays consistent and a
    // poisoned lock is safe to keep using, the same as the MCP server does.
    let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| h.lock().unwrap_or_else(PoisonError::into_inner).handle(method, params)))
        .unwrap_or_else(|_| Err(AutomationError::Other(format!("internal error: `{method}` panicked"))));
    // A renderer whose diagnostics panic must not lose the reply either.
    let diagnostics =
        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| h.lock().unwrap_or_else(PoisonError::into_inner).drain_diagnostics())).unwrap_or_default();
    for diagnostic in diagnostics {
        // A broken stderr pipe must not panic the server before it writes the reply.
        let _ = writeln!(std::io::stderr(), "warning: {diagnostic}");
    }
    match r {
        Ok(v) => json!({"id": id, "ok": true, "result": v}),
        Err(e) => {
            let mut obj = json!({"id": id, "ok": false, "error": e.to_string()});
            attach_memory_error_details(&mut obj, &e);
            obj
        }
    }
}

/// Serve JSON lines from `r` to `w` until EOF. Blank lines are ignored. An over-long or non-UTF-8
/// line gets an error reply and is skipped; the session (and its open documents) keeps serving.
pub fn serve_lines(h: &Mutex<Headless>, mut r: impl BufRead, mut w: impl Write) -> std::io::Result<()> {
    let mut line = String::new();
    loop {
        let (reply, unread_rest) = match read_bounded_line(&mut r, &mut line) {
            Ok(LineRead::Eof) => return Ok(()),
            Ok(LineRead::TooLong) => (json!({"id": null, "ok": false, "error": format!("request exceeds {MAX_REQUEST_BYTES} bytes")}), !line.ends_with('\n')),
            Err(e) if e.kind() == std::io::ErrorKind::InvalidData => (json!({"id": null, "ok": false, "error": "request is not valid UTF-8"}), false),
            Err(e) => return Err(e),
            Ok(LineRead::Line) if line.trim().is_empty() => continue,
            Ok(LineRead::Line) => (respond(h, &line), false),
        };
        write_reply(&mut w, &reply)?;
        w.flush()?;
        if unread_rest {
            discard_rest_of_line(&mut r)?;
        }
    }
}

/// Serve one connection. It must complete `auth` within `auth_deadline` of connecting, however
/// much it sends meanwhile (#4965); after that only the idle timeout applies.
fn serve_tcp_connection(h: &Mutex<Headless>, stream: std::net::TcpStream, token: &str, auth_deadline: std::time::Duration) -> std::io::Result<()> {
    configure_stream(&stream)?;
    let read = stream.try_clone()?;
    let mut reader = std::io::BufReader::new(AuthDeadlineStream::new(read, auth_deadline));
    let mut out = stream;
    let mut line = String::new();
    let mut handshake = ServerHandshake::new();
    let mut authenticated = false;
    loop {
        match read_bounded_line(&mut reader, &mut line)? {
            LineRead::Eof => return Ok(()),
            LineRead::TooLong => {
                let reply = json!({
                    "id": null,
                    "ok": false,
                    "error": format!("request exceeds {MAX_REQUEST_BYTES} bytes"),
                });
                write_reply(&mut out, &reply)?;
                out.flush()?;
                return Ok(());
            }
            LineRead::Line if line.trim().is_empty() => continue,
            LineRead::Line => {}
        }
        let (reply, step) = if authenticated {
            (repeat_auth_reply(&line).unwrap_or_else(|| respond(h, &line)), AuthStep::Authenticated)
        } else {
            let (reply, step) = handshake.reply(&line, token);
            if step == AuthStep::Authenticated {
                authenticated = true;
                reader.get_mut().authenticated()?;
            }
            (reply, step)
        };
        write_reply(&mut out, &reply)?;
        out.flush()?;
        if step == AuthStep::Rejected {
            return Ok(());
        }
    }
}

/// Headless TCP daemons with no clients should eventually release their listening port (#3682).
const TCP_IDLE_TIMEOUT: Duration = Duration::from_secs(30 * 60);

/// Serve authenticated JSON lines on a loopback TCP address with one shared session.
/// Refuses non-loopback addresses, caps connections and request bytes, and closes the listener
/// after an idle period with no connections. Active clients are never evicted by this timer.
pub fn serve_tcp(addr: &str, h: Arc<Mutex<Headless>>, token: String, ready: impl FnOnce(std::net::SocketAddr)) -> Result<(), AutomationError> {
    serve_tcp_until_idle(addr, h, token, ready, TCP_IDLE_TIMEOUT)
}

fn serve_tcp_until_idle(
    addr: &str,
    h: Arc<Mutex<Headless>>,
    token: String,
    ready: impl FnOnce(std::net::SocketAddr),
    idle: Duration,
) -> Result<(), AutomationError> {
    let listener = TcpListener::bind(addr).map_err(|e| AutomationError::Io(format!("bind {addr}: {e}")))?;
    let local = listener.local_addr().map_err(|e| AutomationError::Io(e.to_string()))?;
    if !local.ip().is_loopback() {
        return Err(bad(format!("{addr} is not a loopback address")));
    }
    listener.set_nonblocking(true).map_err(|e| AutomationError::Io(e.to_string()))?;
    ready(local);
    let limiter = ConnectionLimiter::new(MAX_CONNECTIONS);
    let token = Arc::new(token);
    let active = Arc::new(AtomicUsize::new(0));
    let mut last_active = Instant::now();
    loop {
        match listener.accept() {
            Ok((mut stream, _)) => {
                last_active = Instant::now();
                let Some(permit) = limiter.try_acquire() else {
                    let _ = configure_stream(&stream);
                    let _ = writeln!(stream, "{}", json!({"id": null, "ok": false, "error": "connection limit reached"}));
                    continue;
                };
                // The listener is nonblocking; individual requests still use blocking socket I/O.
                let _ = stream.set_nonblocking(false);
                let h = h.clone();
                let token = Arc::clone(&token);
                let active = Arc::clone(&active);
                active.fetch_add(1, Ordering::AcqRel);
                std::thread::spawn(move || {
                    let _permit = permit;
                    let _ = serve_tcp_connection(&h, stream, &token, AUTH_DEADLINE);
                    active.fetch_sub(1, Ordering::AcqRel);
                });
            }
            Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
                if active.load(Ordering::Acquire) != 0 {
                    last_active = Instant::now();
                } else if last_active.elapsed() >= idle {
                    return Ok(());
                }
                std::thread::sleep(Duration::from_millis(100));
            }
            Err(e) if matches!(e.kind(), std::io::ErrorKind::Interrupted | std::io::ErrorKind::ConnectionAborted) => {}
            Err(e) => return Err(AutomationError::Io(e.to_string())),
        }
    }
}

#[cfg(test)]
mod tests;