Lutra/crates/engine/src/cmd/deploy_remote.rs
danny 7601ce12f6 D2: engine commands for the remote browser, compare and sync; save before upload
deploy.browse, readRemote, writeRemote, renameRemote, mkdirRemote,
deleteRemote (confirm: true required), compare, sync (confirmDelete
required for deletions). deploy.upload saves dirty buffers under its
paths first (saveFirst, default true) without queueing uploads on save.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 19:50:00 +01:00

413 lines
13 KiB
Rust

//! Remote browser, compare and sync commands (C9 D2). They share the job
//! slot of [`super::deploy`]: each runs as a pending outcome on a
//! `lutra-deploy` thread, one at a time.
//!
//! **Browser paths** are relative to the server's root folder with `/`
//! (`""` is the root); absolute paths and `..` are `invalid_params`.
//!
//! **Nothing is deleted on the server without an explicit confirmation:**
//! `deploy.deleteRemote` needs `confirm: true`, and `deploy.sync` needs
//! `confirmDelete: true` whenever its `delete` list is not empty. Without
//! it they fail with `invalid_params` before connecting.
use serde::Deserialize;
use serde_json::Value;
use super::deploy::{Work, relative_paths, start};
use super::params::parse;
use crate::{Command, CommandSpec, EngineError, Outcome, Registry, State};
use lutra_deploy::browse::Target;
/// Longest text `deploy.writeRemote` accepts.
const MAX_WRITE: usize = 4 * 1024 * 1024;
/// Registers the remote `deploy.*` commands.
///
/// # Errors
/// [`EngineError::Internal`] if an id is taken.
pub fn register(registry: &mut Registry) -> Result<(), EngineError> {
registry.register(Box::new(Browse))?;
registry.register(Box::new(ReadRemote))?;
registry.register(Box::new(WriteRemote))?;
registry.register(Box::new(RenameRemote))?;
registry.register(Box::new(MkdirRemote))?;
registry.register(Box::new(DeleteRemote))?;
registry.register(Box::new(Compare))?;
registry.register(Box::new(Sync))?;
Ok(())
}
/// Ids of this module's commands.
#[cfg(test)]
pub(crate) const COMMAND_IDS: &[&str] = &[
"deploy.browse",
"deploy.compare",
"deploy.deleteRemote",
"deploy.mkdirRemote",
"deploy.readRemote",
"deploy.renameRemote",
"deploy.sync",
"deploy.writeRemote",
];
/// Whether a job may start: a project and a free slot.
fn idle(state: &State) -> bool {
state.has_project() && state.deploy_idle()
}
/// Params naming a browser path.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct PathParams {
/// The browser path.
#[serde(default)]
path: String,
/// The server's id; the default server when absent.
#[serde(default)]
id: Option<String>,
}
/// `deploy.browse`.
struct Browse;
impl Command for Browse {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "deploy.browse",
label: "Deployment: List Server Folder",
menu_path: None,
default_shortcut: None,
params: "{ path?: folder relative to the server's root (\"\" for the root), id?: server id }; returns { path, entries: [{ name, isDir, size? }] } folders first",
}
}
fn enabled(&self, state: &State) -> bool {
idle(state)
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let p: PathParams = parse(self.spec().id, params)?;
start(state, self.spec().id, p.id.as_deref(), Work::Browse(p.path))
}
}
/// Params of `deploy.readRemote`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
struct ReadParams {
/// A project-relative path, mapped to the server.
#[serde(default)]
path: Option<String>,
/// A browser path, relative to the server's root.
#[serde(default)]
remote_path: Option<String>,
/// The server's id; the default server when absent.
#[serde(default)]
id: Option<String>,
}
/// `deploy.readRemote`.
struct ReadRemote;
impl Command for ReadRemote {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "deploy.readRemote",
label: "Deployment: Read Server File",
menu_path: None,
default_shortcut: None,
params: "{ path: project-relative file (mapped) | remotePath: file relative to the server's root, id?: server id }; returns { text: string|null (null when missing), binary, tooLarge } (at most 4 MiB)",
}
}
fn enabled(&self, state: &State) -> bool {
idle(state)
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: ReadParams = parse(command, params)?;
let target = match (p.path, p.remote_path) {
(Some(path), None) => {
let rel = relative_paths(state, command, &[path])?;
Target::Mapped(rel.into_iter().next().unwrap_or_default())
}
(None, Some(remote)) => Target::Browser(remote),
_ => {
return Err(EngineError::invalid_params(
command,
"give exactly one of path and remotePath",
));
}
};
start(state, command, p.id.as_deref(), Work::Read(target))
}
}
/// Params of `deploy.writeRemote`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
struct WriteParams {
/// The browser path of the file.
remote_path: String,
/// Its new text.
text: String,
/// The server's id; the default server when absent.
#[serde(default)]
id: Option<String>,
}
/// `deploy.writeRemote`.
struct WriteRemote;
impl Command for WriteRemote {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "deploy.writeRemote",
label: "Deployment: Save Server File",
menu_path: None,
default_shortcut: None,
params: "{ remotePath: file relative to the server's root, text: at most 4 MiB, id?: server id }; writes the file on the server (creating its folder); returns {}",
}
}
fn enabled(&self, state: &State) -> bool {
idle(state)
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: WriteParams = parse(command, params)?;
if p.text.len() > MAX_WRITE || p.remote_path.trim().is_empty() {
return Err(EngineError::invalid_params(
command,
"remotePath must name a file and text may hold at most 4 MiB",
));
}
start(
state,
command,
p.id.as_deref(),
Work::Write(p.remote_path, p.text),
)
}
}
/// Params of `deploy.renameRemote`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct RenameParams {
/// The browser path to rename.
from: String,
/// Its new browser path.
to: String,
/// The server's id; the default server when absent.
#[serde(default)]
id: Option<String>,
}
/// `deploy.renameRemote`.
struct RenameRemote;
impl Command for RenameRemote {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "deploy.renameRemote",
label: "Deployment: Rename on Server",
menu_path: None,
default_shortcut: None,
params: "{ from, to: paths relative to the server's root, id?: server id }; returns {}",
}
}
fn enabled(&self, state: &State) -> bool {
idle(state)
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: RenameParams = parse(command, params)?;
if p.from.trim().is_empty() || p.to.trim().is_empty() {
return Err(EngineError::invalid_params(
command,
"from and to must name paths",
));
}
start(state, command, p.id.as_deref(), Work::Rename(p.from, p.to))
}
}
/// `deploy.mkdirRemote`.
struct MkdirRemote;
impl Command for MkdirRemote {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "deploy.mkdirRemote",
label: "Deployment: New Folder on Server",
menu_path: None,
default_shortcut: None,
params: "{ path: new folder relative to the server's root, id?: server id }; creates it and its parents; returns {}",
}
}
fn enabled(&self, state: &State) -> bool {
idle(state)
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: PathParams = parse(command, params)?;
if p.path.trim().is_empty() {
return Err(EngineError::invalid_params(
command,
"path must name the new folder",
));
}
start(state, command, p.id.as_deref(), Work::Mkdir(p.path))
}
}
/// Params of `deploy.deleteRemote`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct DeleteParams {
/// The browser path to delete.
path: String,
/// The user confirmed the deletion.
#[serde(default)]
confirm: bool,
/// The server's id; the default server when absent.
#[serde(default)]
id: Option<String>,
}
/// `deploy.deleteRemote`.
struct DeleteRemote;
impl Command for DeleteRemote {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "deploy.deleteRemote",
label: "Deployment: Delete on Server",
menu_path: None,
default_shortcut: None,
params: "{ path: file or folder relative to the server's root (never the root), confirm: true (required: the user agreed), id?: server id }; a folder goes with everything inside; returns { deleted: count }",
}
}
fn enabled(&self, state: &State) -> bool {
idle(state)
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: DeleteParams = parse(command, params)?;
if !p.confirm {
return Err(EngineError::invalid_params(
command,
"deleting on the server needs confirm: true after the user agreed",
));
}
start(state, command, p.id.as_deref(), Work::Delete(p.path))
}
}
/// Params of `deploy.compare`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct CompareParams {
/// Project-relative files or folders; `""` is the whole project.
paths: Vec<String>,
/// The server's id; the default server when absent.
#[serde(default)]
id: Option<String>,
}
/// `deploy.compare`.
struct Compare;
impl Command for Compare {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "deploy.compare",
label: "Deployment: Compare with Server",
menu_path: None,
default_shortcut: None,
params: "{ paths: [project-relative file or folder, \"\" for the whole project], id?: server id }; returns { differences: [{ path, status: localOnly|remoteOnly|different, localSize?, remoteSize? }] } sorted by path; equal files are left out",
}
}
fn enabled(&self, state: &State) -> bool {
idle(state)
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: CompareParams = parse(command, params)?;
let paths = relative_paths(state, command, &p.paths)?;
start(state, command, p.id.as_deref(), Work::Compare(paths))
}
}
/// Params of `deploy.sync`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
struct SyncParams {
/// Project-relative files to upload.
#[serde(default)]
upload: Vec<String>,
/// Project-relative files to delete on the server.
#[serde(default)]
delete: Vec<String>,
/// The user confirmed the deletions.
#[serde(default)]
confirm_delete: bool,
/// The server's id; the default server when absent.
#[serde(default)]
id: Option<String>,
}
/// `deploy.sync`.
struct Sync;
impl Command for Sync {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "deploy.sync",
label: "Deployment: Sync with Server",
menu_path: None,
default_shortcut: None,
params: "{ upload?: [project-relative files], delete?: [project-relative files to delete on the server], confirmDelete: true (required when delete is not empty), id?: server id }; returns { files, bytes, skipped, failed, deleted }",
}
}
fn enabled(&self, state: &State) -> bool {
idle(state)
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: SyncParams = parse(command, params)?;
if !p.delete.is_empty() && !p.confirm_delete {
return Err(EngineError::invalid_params(
command,
"deleting on the server needs confirmDelete: true after the user agreed",
));
}
if p.upload.is_empty() && p.delete.is_empty() {
return Err(EngineError::invalid_params(command, "nothing to sync"));
}
let upload = if p.upload.is_empty() {
Vec::new()
} else {
relative_paths(state, command, &p.upload)?
};
let delete = if p.delete.is_empty() {
Vec::new()
} else {
relative_paths(state, command, &p.delete)?
};
start(state, command, p.id.as_deref(), Work::Sync(upload, delete))
}
}