// 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