47 lines
No EOL
2.8 KiB
C
47 lines
No EOL
2.8 KiB
C
// calogSsh.h -- calog SSH/SFTP library (built on libssh2).
|
|
//
|
|
// Registers inline natives that a script of any engine can call:
|
|
// sshConnect(host[, port]) -> handle (port defaults to 22)
|
|
// sshAuthPassword(handle, user, password) -> bool
|
|
// sshAuthKey(handle, user, privateKeyPath[, publicKeyPath, passphrase]) -> bool
|
|
// sshExec(handle, command) -> { stdout, stderr, exitCode }
|
|
// sshClose(handle)
|
|
// sftpGet(handle, remotePath) -> data (whole file, binary-safe)
|
|
// sftpPut(handle, remotePath, data) (create|truncate, mode 0644)
|
|
// sftpList(handle, path) -> [ { name, size, isDir }, ... ]
|
|
// sftpStat(handle, path) -> { size, isDir } (nil if the path is missing)
|
|
// sftpRemove(handle, path)
|
|
// sftpMkdir(handle, path) (mode 0755)
|
|
// Payloads are binary-safe strings. The blocking natives are INLINE, so they stall only the
|
|
// calling script's context thread, not the host. Sessions are put in libssh2 blocking mode.
|
|
//
|
|
// THREADING / cross-context use. A connection handle is a plain process-wide value (an opaque
|
|
// int64) with no owning context, so it can be PASSED to another script and used there -- e.g.
|
|
// lent to a function in another context via calogCall, which uses it and returns while the
|
|
// caller is blocked. That synchronous lend is SAFE: only one context ever touches the session
|
|
// at a time, and the handle stays with the lender. What is NOT safe is CONCURRENT use of one
|
|
// handle: two contexts operating on it at the same instant (a libssh2 session is NOT thread-safe
|
|
// -- concurrent use corrupts session state), a borrowed handle stashed and later used from a
|
|
// timer/pubsub callback while the owner also uses it, or closing a handle while another context
|
|
// is mid-operation on it (use-after-free). The rule is: at most one context uses a given handle
|
|
// at any instant, and exactly one context closes it. calog does NOT serialize this for you.
|
|
//
|
|
// The SFTP subsystem is opened lazily on the first sftp* call and cached on the connection.
|
|
// Handles are NOT reference-counted. Hostname resolution uses getaddrinfo (works in dynamic
|
|
// builds; a fully-static glibc build cannot resolve names -- connect by IP, or link musl).
|
|
|
|
#ifndef CALOG_SSH_H
|
|
#define CALOG_SSH_H
|
|
|
|
#include "calog.h"
|
|
|
|
// Register the SSH natives on a runtime. Idempotent across runtimes (they share a
|
|
// process-wide connection registry and a single libssh2_init). Returns calogOkE or an error.
|
|
int32_t calogSshRegister(CalogT *calog);
|
|
|
|
// Close any still-open connections, free the process-wide registry, and call libssh2_exit
|
|
// when the last runtime unregisters. Call it AFTER the runtime is torn down (calogDestroy),
|
|
// since it invalidates the natives' state.
|
|
void calogSshShutdown(void);
|
|
|
|
#endif |