Version: v0.7.0

API de SSH

Los helpers para conexión SSH, ejecución remota y transferencia de archivos están disponibles bajo ptool.ssh y p.ssh.

ptool.ssh.connect

ptool.ssh.connect(target_or_options) prepara un manejador de conexión SSH respaldado por el comando ssh del sistema y devuelve un objeto Connection.

ssh debe estar disponible en PATH.

Argumentos:

target_or_options (string|table, obligatorio):
- Cuando se proporciona una cadena, se trata como un destino SSH.
- Cuando se proporciona una tabla, actualmente admite:
  - target (string, opcional): Cadena de destino SSH, como "[email protected]" o "[email protected]:2222".
  - host (string, opcional): Nombre de host o dirección IP.
  - user (string, opcional): Nombre de usuario SSH. Por defecto usa $USER, o "root" si $USER no está disponible.
  - port (integer, opcional): Puerto SSH. Por defecto es 22.
  - auth (table, opcional): Configuración de autenticación.
  - host_key (table, opcional): Configuración de verificación de clave de host.
  - connect_timeout_ms (integer, opcional): Timeout en milisegundos. Por defecto es 10000.
  - keepalive_interval_ms (integer, opcional): Intervalo de keepalive en milisegundos.

Ejemplos de cadenas de destino admitidas:

local a = ptool.ssh.connect("[email protected]")
local b = ptool.ssh.connect("[email protected]:2222")
local c = ptool.ssh.connect("[2001:db8::10]:2222")

Campos de auth:

private_key_file (string, opcional): Ruta a un archivo de clave privada.
private_key_passphrase (string, opcional): Frase de contraseña de la clave privada. Actualmente no es compatible.
password (string, opcional): Autenticación basada en contraseña. Actualmente no es compatible.

Comportamiento de autenticación:

Si se proporciona auth.private_key_file, ptool invoca ssh con esa clave mediante -i y también establece IdentitiesOnly=yes.
Si se proporciona auth.private_key_passphrase o auth.password, ptool.ssh.connect(...) falla porque esta API no pasa esos secretos al comando ssh del sistema.
En caso contrario, la autenticación se delega a la configuración local de OpenSSH, incluidas opciones y mecanismos como IdentityFile, ProxyJump, ProxyCommand, ssh-agent y certificados.
Las rutas de clave relativas se resuelven desde el directorio de runtime actual de ptool, por lo que siguen ptool.cd(...).
~ y ~/... se expanden en las rutas de clave.

Campos de host_key:

verify (string, opcional): Modo de verificación de la clave de host. Valores admitidos:
- "known_hosts": Verifica contra un archivo known_hosts (predeterminado).
- "ignore": Omite la verificación de la clave de host.
known_hosts_file (string, opcional): Ruta a un archivo known_hosts. Solo se usa cuando verify = "known_hosts".

Comportamiento de clave de host:

Si verify = "ignore", ptool invoca ssh con StrictHostKeyChecking=no y UserKnownHostsFile=/dev/null.
Si verify = "known_hosts" y se proporciona known_hosts_file, ptool invoca ssh con StrictHostKeyChecking=yes y ese UserKnownHostsFile.
Si verify = "known_hosts" y se omite known_hosts_file, o si host_key se omite por completo, el manejo de la clave de host se delega a la configuración local de OpenSSH y a sus valores predeterminados.
Las rutas relativas de known_hosts_file se resuelven desde el directorio de runtime actual de ptool.
~ y ~/... se expanden en known_hosts_file.
Cuando known_hosts_file se proporciona explícitamente, reemplaza el valor predeterminado de UserKnownHostsFile que usa el comando ssh local para esta conexión.

Ejemplo:

local ssh = ptool.ssh.connect({
  host = "example.com",
  user = "deploy",
  port = 22,
  auth = {
    private_key_file = "~/.ssh/id_ed25519",
  },
  host_key = {
    verify = "known_hosts",
  },
})

Connection

Connection representa un manejador de conexión respaldado por OpenSSH devuelto por ptool.ssh.connect().

Está implementado como un userdata de Lua.

Campos y métodos:

Campos:
- conn.host (string)
- conn.user (string)
- conn.port (integer)
- conn.target (string)
Métodos:
- conn:run(...) -> table
- conn:run_capture(...) -> table
- conn:http_request(options) -> Response
- conn:path(path) -> RemotePath
- conn:exists(path) -> boolean
- conn:is_file(path) -> boolean
- conn:is_dir(path) -> boolean
- conn:upload(local_path, remote_path[, options]) -> table
- conn:download(remote_path, local_path[, options]) -> table
- conn:close() -> nil

run

Canonical API name: ptool.ssh.Connection:run.

conn:run(...) ejecuta un comando remoto a través de la conexión SSH actual.

Se admiten las siguientes formas de llamada:

conn:run("hostname")
conn:run("echo", "hello world")
conn:run("echo", {"hello", "world"})
conn:run("hostname", { stdout = "capture" })
conn:run("echo", {"hello", "world"}, { stdout = "capture" })
conn:run({ cmd = "git", args = {"rev-parse", "HEAD"} })

Reglas de argumentos:

conn:run(cmdline): cmdline se envía como la cadena de comando remoto.
conn:run(cmd, argsline): cmd se trata como el comando, y argsline se divide usando reglas de estilo shell (shlex).
conn:run(cmd, args): cmd es una cadena y args es un arreglo de cadenas. Los argumentos se escapan para shell antes de la ejecución remota.
conn:run(cmdline, options): options sobrescribe esta invocación.
conn:run(cmd, args, options): options sobrescribe esta invocación.
conn:run(options): options es una tabla.
Cuando el segundo argumento es una tabla: si es un arreglo (claves enteras consecutivas 1..n), se trata como args; en caso contrario se trata como options.

Cuando se usa conn:run(options), options actualmente admite:

cmd (string, obligatorio): Nombre del comando o ruta del ejecutable.
args (string[], opcional): Lista de argumentos.
cwd (string, opcional): Directorio de trabajo remoto. Se aplica anteponiendo cd ... && al comando shell remoto generado.
env (table, opcional): Variables de entorno remotas, donde claves y valores son cadenas. Se aplica anteponiendo export ... && al comando shell remoto generado.
stdin (string, optional): String sent to the remote process stdin.
trim (boolean, optional): Whether to trim leading and trailing whitespace from captured stdout and captured stderr before returning them. This only affects streams set to "capture". Defaults to false.
echo (boolean, optional): Whether to echo the remote command before execution. Defaults to true.
check (boolean, optional): Whether to raise an error immediately when the exit status is not 0. Defaults to false.
stdout (string, optional): Stdout handling strategy. Supported values:
- "inherit": Hereda el terminal actual (predeterminado).
- "capture": Capture into res.stdout.
- "null": Descarta la salida.
stderr (string, optional): Stderr handling strategy. Supported values:
- "inherit": Hereda el terminal actual (predeterminado).
- "capture": Capture into res.stderr.
- "null": Descarta la salida.

Cuando se usan las formas abreviadas, la tabla options solo admite:

stdin (string, optional): String sent to the remote process stdin.
trim (boolean, optional): Whether to trim leading and trailing whitespace from captured stdout and captured stderr before returning them. This only affects streams set to "capture". Defaults to false.
echo (boolean, optional): Whether to echo the remote command before execution. Defaults to true.
check (boolean, optional): Whether to raise an error immediately when the exit status is not 0. Defaults to false.
stdout (string, optional): Stdout handling strategy. Supported values:
- "inherit": Hereda el terminal actual (predeterminado).
- "capture": Capture into res.stdout.
- "null": Descarta la salida.
stderr (string, optional): Stderr handling strategy. Supported values:
- "inherit": Hereda el terminal actual (predeterminado).
- "capture": Capture into res.stderr.
- "null": Descarta la salida.

Reglas del valor de retorno:

Siempre se devuelve una tabla con los siguientes campos:
- ok (boolean): Si el código de salida remoto es 0.
- code (integer|nil): Código de salida remoto. Si el proceso remoto termina por señal, este valor es nil.
- target (string): Cadena de destino SSH con el formato user@host:port.
- stdout (string, opcional): Presente cuando stdout = "capture".
- stderr (string, opcional): Presente cuando stderr = "capture".
- assert_ok(self) (function): Lanza un error cuando ok = false.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")

local res = ssh:run("uname -a", { stdout = "capture" })
print(res.target)
print(res.stdout)
local res2 = ssh:run({
  cmd = "git",
  args = {"rev-parse", "HEAD"},
  cwd = "/srv/app",
  env = {
    FOO = "bar",
  },
  trim = true,
  stdout = "capture",
  check = true,
})

print(res2.stdout)

run_capture

Canonical API name: ptool.ssh.Connection:run_capture.

conn:run_capture(...) ejecuta un comando remoto a través de la conexión SSH actual.

Acepta las mismas formas de llamada, reglas de argumentos, reglas del valor de retorno y opciones que conn:run(...).

La única diferencia es el manejo predeterminado de flujos:

stdout usa "capture" por defecto.
stderr usa "capture" por defecto.

trim todavía tiene como valor predeterminado false y aún puede anular cualquiera de estos campos explícitamente en options.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")

local res = ssh:run_capture("uname -a", { trim = true })
print(res.stdout)

local res2 = ssh:run_capture({
  cmd = "sh",
  args = {"-c", "printf 'out'; printf 'err' >&2"},
  cwd = "/srv/app",
})
print(res2.stdout)
print(res2.stderr)

local res3 = ssh:run_capture("echo hello", {
  stderr = "inherit",
})
print(res3.stdout)

http_request

Canonical API name: ptool.ssh.Connection:http_request.

conn:http_request(options) envía una solicitud HTTP desde el host SSH remoto y devuelve el mismo tipo de objeto Response que ptool.http.request(...).

options admite los mismos campos y las mismas reglas de validación que ptool.http.request(options).

Esto es útil cuando solo se puede acceder al endpoint de destino desde el host remoto, por ejemplo, un servicio vinculado a 127.0.0.1, una dirección de VPC privada o un endpoint de metadatos.

Notas:

La solicitud se ejecuta en el host remoto, por lo que la resolución DNS, el acceso de red saliente, la configuración de proxy, la confianza TLS y las reglas del firewall provienen de ese host y no de la máquina local.
El host remoto debe tener curl disponible en PATH.
Los cuerpos de solicitud se envían al proceso remoto curl a través de SSH.
Los encabezados y el cuerpo de la respuesta se transmiten de vuelta por SSH y luego se consumen mediante los métodos normales de Response documentados en la API HTTP.
basic_auth y bearer_token siguen siendo mutuamente excluyentes.
fail_on_http_error, el manejo de redirecciones, el manejo de tiempos de espera y el almacenamiento en caché del cuerpo de la respuesta se comportan igual que en ptool.http.request(...).

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")

local resp = ssh:http_request({
  url = "http://127.0.0.1:8080/health",
  headers = {
    accept = "application/json",
  },
  timeout_ms = 5000,
  fail_on_http_error = true,
})

local data = resp:json()
print(resp.status)
print(data.status)

path

Canonical API name: ptool.ssh.Connection:path.

conn:path(path) crea un objeto RemotePath reutilizable vinculado a la conexión SSH actual.

path (string, obligatorio): La ruta remota.
Devuelve: Un objeto RemotePath que puede pasarse a conn:upload(...), conn:download(...) y ptool.fs.copy(...).

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")
local remote_release = ssh:path("/srv/app/releases/current.tar.gz")

ssh:download(remote_release, "./tmp/current.tar.gz")

exists

Canonical API name: ptool.ssh.Connection:exists.

conn:exists(path) comprueba si existe una ruta remota.

path (string|remote path, required): The remote path to check. It can be a string or a value created by conn:path(...).
Returns: true when the remote path exists, otherwise false.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")

print(ssh:exists("/srv/app"))
print(ssh:path("/srv/app/releases/current.tar.gz"):exists())

is_file

Canonical API name: ptool.ssh.Connection:is_file.

conn:is_file(path) comprueba si una ruta remota existe y es un archivo regular.

path (string|remote path, required): The remote path to check. It can be a string or a value created by conn:path(...).
Returns: true when the remote path is a file, otherwise false.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")
local remote_tarball = ssh:path("/srv/app/releases/current.tar.gz")

if ssh:is_file(remote_tarball) then
  print("release tarball exists")
end

is_dir

Canonical API name: ptool.ssh.Connection:is_dir.

conn:is_dir(path) comprueba si una ruta remota existe y es un directorio.

path (string|remote path, required): The remote path to check. It can be a string or a value created by conn:path(...).
Returns: true when the remote path is a directory, otherwise false.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")
local releases = ssh:path("/srv/app/releases")

if releases:is_dir() then
  print("releases directory is ready")
end

upload

Canonical API name: ptool.ssh.Connection:upload.

conn:upload(local_path, remote_path[, options]) sube un archivo o directorio local al host remoto.

local_path (string, obligatorio): El archivo o directorio local que se va a subir.
remote_path (string|remote path, obligatorio): La ruta de destino en el host remoto. Puede ser una cadena o un valor creado por conn:path(...).
options (table, optional): Transfer options.
Returns: A table with the following fields:
- bytes (integer): El número de bytes de archivos regulares subidos. Cuando se sube un directorio, es la suma de los tamaños de los archivos subidos.
- from (string): La ruta local de origen.
- to (string): La ruta remota de destino.

Supported transfer options:

parents (boolean, opcional): Crea el directorio padre de remote_path antes de subir. Por defecto es false.
overwrite (boolean, optional): Whether an existing destination file may be replaced. Defaults to true.
echo (boolean, optional): Whether to print the transfer before executing it. Defaults to false.

Directory behavior:

Cuando local_path es un archivo, el comportamiento no cambia.
Cuando local_path es un directorio y remote_path no existe, remote_path se convierte en la raíz del directorio de destino.
Cuando local_path es un directorio y remote_path ya existe como directorio, el directorio de origen se crea dentro de él usando el basename del directorio de origen.
overwrite = false rejects an already-existing destination directory for the final directory root.
Las subidas de directorios requieren que tar esté disponible en el host remoto.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")
local remote_tarball = ssh:path("/srv/app/releases/current.tar.gz")

local res = ssh:upload("./dist/app.tar.gz", remote_tarball, {
  parents = true,
  overwrite = true,
  echo = true,
})

print(res.bytes)
print(res.to)

Directory example:

local ssh = ptool.ssh.connect("[email protected]")

local res = ssh:upload("./dist/assets", "/srv/app/releases", {
  parents = true,
  overwrite = true,
  echo = true,
})

print(res.bytes)
print(res.to) -- [email protected]:22:/srv/app/releases

download

Canonical API name: ptool.ssh.Connection:download.

conn:download(remote_path, local_path[, options]) descarga un archivo o directorio remoto a una ruta local.

remote_path (string|remote path, obligatorio): La ruta de origen en el host remoto. Puede ser una cadena o un valor creado por conn:path(...).
local_path (string, obligatorio): La ruta de destino local.
options (table, optional): Transfer options.
Returns: A table with the following fields:
- bytes (integer): El número de bytes de archivos regulares descargados. Cuando se descarga un directorio, es la suma de los tamaños de los archivos descargados.
- from (string): La ruta remota de origen.
- to (string): La ruta local de destino.

Supported transfer options:

parents (boolean, opcional): Crea el directorio padre de local_path antes de descargar. Por defecto es false.
overwrite (boolean, optional): Whether an existing destination file may be replaced. Defaults to true.
echo (boolean, optional): Whether to print the transfer before executing it. Defaults to false.

Directory behavior:

Cuando remote_path es un archivo, el comportamiento no cambia.
Cuando remote_path es un directorio y local_path no existe, local_path se convierte en la raíz del directorio de destino.
Cuando remote_path es un directorio y local_path ya existe como directorio, el directorio remoto de origen se crea dentro de él usando el basename del directorio remoto.
overwrite = false rejects an already-existing destination directory for the final directory root.
Las descargas de directorios requieren que tar esté disponible en el host remoto.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")

local res = ssh:download("/srv/app/logs/app.log", "./tmp/app.log", {
  parents = true,
  overwrite = false,
  echo = true,
})

print(res.bytes)
print(res.from)

Directory example:

local ssh = ptool.ssh.connect("[email protected]")

local res = ssh:download("/srv/app/releases/assets", "./tmp/releases", {
  parents = true,
  overwrite = true,
  echo = true,
})

print(res.bytes)
print(res.from)

close

Canonical API name: ptool.ssh.Connection:close.

conn:close() cierra el manejador de conexión SSH.

Comportamiento:

Después de cerrarla, la conexión ya no puede usarse.
Cerrar una conexión que ya está cerrada está permitido y no tiene efecto.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")
ssh:close()

RemotePath

RemotePath representa una ruta remota vinculada a un Connection y devuelta por conn:path(path).

Está implementado como un userdata de Lua.

Métodos:

remote:exists() -> boolean
remote:is_file() -> boolean
remote:is_dir() -> boolean

exists

remote:exists() comprueba si existe la ruta remota.

Returns: true when the remote path exists, otherwise false.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")
local remote_release = ssh:path("/srv/app/releases/current.tar.gz")

print(remote_release:exists())

is_file

remote:is_file() comprueba si la ruta remota existe y es un archivo regular.

Returns: true when the remote path is a file, otherwise false.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")
local remote_tarball = ssh:path("/srv/app/releases/current.tar.gz")

if remote_tarball:is_file() then
  print("release tarball exists")
end

is_dir

remote:is_dir() comprueba si la ruta remota existe y es un directorio.

Returns: true when the remote path is a directory, otherwise false.

Ejemplo:

local ssh = ptool.ssh.connect("[email protected]")
local releases = ssh:path("/srv/app/releases")

if releases:is_dir() then
  print("releases directory is ready")
end

ptool.ssh.connect​

Connection​

run​

run_capture​

http_request​

path​

exists​

is_file​

is_dir​

upload​

download​

close​

RemotePath​

exists​

is_file​

is_dir​

ptool.ssh.connect

Connection

run

run_capture

http_request

path

exists

is_file

is_dir

upload

download

close

RemotePath

exists

is_file

is_dir