// 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.
// A connection handle belongs to the context that created it: using one from another context
// fails (calogErrArgE) rather than racing. The SFTP subsystem is opened lazily on the first
// sftp* call and cached on the connection. Handles are NOT reference-counted; closing one
// while another context is mid-operation is undefined (use-after-free). 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