calog/API.md

# calog script API reference

Every function below is a **native** that calog registers into each engine, so a script in
any language can call it. This reference covers the natives the `calog` runner and its
libraries expose. (For the C embedding API -- `calogCreate`, `calogRegister`, `calogFnInvoke`,
etc. -- see the README and `src/calog.h`.)

## Conventions

- **Calling syntax per engine.** Most engines call a native by its bare name --
  `cryptoUuid()`, `kvSet("k", 1)`. Two differ:
  - **Wren**: `Calog.call("name", [args])`, e.g. `Calog.call("kvSet", ["k", 1])`.
  - **Scheme (s7)**: s-expression form, `(kvSet "k" 1)`.
- **Output & exit** (provided by the `calog` runner): `calogPrint(...)` writes to stdout;
  `calogExit([code])` tears everything down and exits. calog is event-driven, so a script
  must call `calogExit` (or be interrupted) to end -- a finished top level does not exit.
- **Values.** Arguments and results marshal through one canonical type: `nil`, `bool`, `int`,
  `real`, `string`, `list`, and `map` (keyed record). Strings are **binary-safe** (may contain
  embedded NULs) everywhere the underlying library allows it.
- **Signatures.** Every entry is written `name(param: type, ...) -> returnType`, using the
  value types above plus `handle` (an opaque int64 resource handle), `fn` (a function value),
  and `any` (a value of any type). `[x]` marks an optional argument and `...x` a variadic one.
  A signature with no `->` returns `nil`. A return type given as `T | nil` may be `nil` (e.g.
  a lookup miss or end of stream).
- **Handles** (db connections, sockets, ssh sessions, tasks) are opaque int64 values from a
  process-wide table, so a handle can be **passed to another context and used there** -- e.g.
  lent to a function in another script via `calogCall`, which uses it and returns while the
  caller is blocked (a safe synchronous hand-off). What is *not* safe is using one handle from
  two contexts at the same instant, or closing it while another context is mid-operation: at
  most one context may touch a given handle at any moment, and exactly one closes it. (Tasks are
  the exception -- a task is owner-scoped: only its spawner may `taskEval`/`taskClose` it.)
- **Callbacks.** Natives that take a `fn` argument (`psSubscribe`, `timerAfter`, `timerEvery`,
  `calogExport`) accept a first-class function value in every engine. A function value handed
  *to* a script (say, returned by `calogCall`) is invoked directly -- except in my-basic, which
  calls it with `calogInvoke(fn, ...args)`.
- **Availability.** Every library in this reference is compiled into `bin/calog`: crypto,
  json, kv, fs, time, timer, export, pubsub, task, net (TCP / UDP / ENet), db (SQLite /
  PostgreSQL / MySQL), http, and ssh. ssh needs a reachable server; http needs a reachable
  endpoint.

---

## Runner (`calog` binary)

| Function | Description |
|---|---|
| `calogPrint(...values: any)` | Write each argument to stdout, space-separated, with a trailing newline. |
| `calogExit([code: int])` | Tear down the runtime and exit the process with `code` (default `0`). Does not return. |

## crypto

Binary-safe cryptographic primitives over OpenSSL.

| Function | Description |
|---|---|
| `cryptoHashSha256(data: string) -> string` | SHA-256 as a 64-char lowercase hex digest. |
| `cryptoHashSha1(data: string) -> string` | SHA-1 as a 40-char lowercase hex digest. |
| `cryptoHmacSha256(key: string, data: string) -> string` | HMAC-SHA-256 as 64-char lowercase hex. |
| `cryptoRandomBytes(count: int) -> string` | `count` cryptographically-random bytes. |
| `cryptoBase64Encode(data: string) -> string` | Base64-encode. |
| `cryptoBase64Decode(text: string) -> string` | Base64-decode (trailing whitespace tolerated). |
| `cryptoHexEncode(data: string) -> string` | Lowercase hex encode. |
| `cryptoHexDecode(hexText: string) -> string` | Hex decode (case-insensitive). |
| `cryptoUuid() -> string` | A random RFC 4122 version-4 UUID string. |

## db

SQL over SQLite, PostgreSQL, and MySQL/MariaDB. Parameters are always **bound** (never
string-spliced), so queries are injection-safe. Values marshal as: NULL <-> nil, integers/
reals as-is, text and BLOBs as binary-safe strings.

| Function | Description |
|---|---|
| `dbOpen(driver: string, conn: string) -> handle` | Open a connection. `driver` is `"sqlite"`, `"postgres"`, or `"mysql"`. `conn` is a SQLite path or `":memory:"`, a libpq conninfo, or a MySQL `key=value ...` string. |
| `dbExec(handle: handle, sql: string, ...params: any) -> int` | Run a non-query statement with bound params; returns rows affected. |
| `dbQuery(handle: handle, sql: string, ...params: any) -> list` | Run a query; returns a list of `{column: value}` row maps. |
| `dbClose(handle: handle)` | Close the connection. |

## export

Share a function by name across contexts and engines.

| Function | Description |
|---|---|
| `calogExport(name: string, fn: fn)` | Publish function `fn` under a global `name`. |
| `calogUnexport(name: string)` | Remove an exported name. |
| `calogCall(name: string, ...args: any) -> any` | Call an exported function by name -- works in **every** engine. (An export is also reachable by its bare name -- `exportedFn(args)` -- on Lua/JS/Squirrel/s7, on Ruby at top level (via `method_missing`), and on my-basic case-insensitively (it uppercases identifiers); Wren and Berry always need `calogCall`.) |

## fs

POSIX filesystem access. A failed operation raises a catchable script error carrying
`strerror(errno)`.

| Function | Description |
|---|---|
| `fsRead(path: string) -> string` | Read a whole file (binary-safe). |
| `fsWrite(path: string, data: string)` | Create/truncate and write `data`. |
| `fsAppend(path: string, data: string)` | Create if absent, append at the end. |
| `fsExists(path: string) -> bool` | Whether the path exists. |
| `fsRemove(path: string)` | Unlink a file. |
| `fsMkdir(path: string)` | Create one directory level (existing dir is OK). |
| `fsList(path: string) -> list` | Entry name strings, excluding `.` and `..`. |
| `fsStat(path: string) -> map \| nil` | `{size, isDir, isFile, mtime}`, or nil if the path is absent. |

## http

Minimal HTTP/1.1 client over `http://` and `https://`. Each call is its own connection
(`Connection: close`). 3xx redirects are followed (up to 16, to break loops). `https://`
verifies the server certificate against the system CA store by default.

| Function | Description |
|---|---|
| `httpGet(url: string) -> map` | GET a URL, following redirects. Returns `{status, body, headers}` (headers keyed by lowercased name). |
| `httpRequest(opts: map) -> map` | `opts` is `{method (default "GET"), url, headers (map), body, insecure (bool), maxRedirects (int, default 16; 0 = don't follow)}`. `insecure=true` skips TLS verification. Returns `{status, body, headers}`. |

## json

| Function | Description |
|---|---|
| `jsonParse(text: string) -> any` | Parse JSON: object -> map, array -> list, number -> int or real, string, true/false, null -> nil. |
| `jsonStringify(value: any) -> string` | Serialize a value to compact JSON text. |

## kv

A process-wide, thread-safe store shared by every context and engine. Holds **data only** (a
function value is rejected). Keys are binary-safe.

| Function | Description |
|---|---|
| `kvSet(key: string, value: any)` | Store a deep copy of `value` under `key` (replaces any existing). |
| `kvGet(key: string) -> any \| nil` | A deep copy of the stored value, or nil if absent. |
| `kvHas(key: string) -> bool` | Whether the key is present. |
| `kvDelete(key: string)` | Remove the key (no error if absent). |
| `kvKeys() -> list` | A list of the stored keys (strings). |

## net

Three first-class transports -- **TCP**, **UDP**, and **ENet** (reliable/ordered delivery
over UDP) -- all always available. Payloads are binary-safe strings. Blocking calls
(`tcpAccept`/`tcpRecv`/`udpRecvFrom`/`enetService`) stall only the calling context's thread.

TCP and UDP:

| Function | Description |
|---|---|
| `tcpConnect(host: string, port: int) -> handle` | Connect to a TCP server. |
| `tcpListen(port: int) -> handle` | Listen on a TCP port. |
| `tcpAccept(handle: handle) -> handle` | Block for a client; returns a connection handle. |
| `tcpSend(handle: handle, data: string) -> int` | Send all of `data`; returns bytes sent. |
| `tcpRecv(handle: handle, maxBytes: int) -> string \| nil` | Read up to `maxBytes`; nil at end of stream. |
| `tcpClose(handle: handle)` | Close a socket. |
| `udpOpen(port: int) -> handle` | Open a UDP socket (`port` 0 = ephemeral). |
| `udpSendTo(handle: handle, host: string, port: int, data: string) -> int` | Send a datagram; returns bytes sent. |
| `udpRecvFrom(handle: handle, maxBytes: int) -> map` | Receive one datagram: `{data, host, port}`. |
| `udpClose(handle: handle)` | Close a UDP socket. |

ENet (reliable UDP -- ordered, reliable channels over UDP):

| Function | Description |
|---|---|
| `enetHost(port: int, maxPeers: int) -> handle` | Create an ENet host. |
| `enetConnect(hostHandle: handle, host: string, port: int, channels: int) -> handle` | Initiate a connection to a peer; returns a peer handle. |
| `enetService(hostHandle: handle, timeoutMs: int) -> map` | Poll for one event within `timeoutMs`. Returns `{type, ...}` where `type` is `"none"`, `"connect"`, `"receive"` (with `peer`, `channel`, `data`), or `"disconnect"`. |
| `enetSend(peerHandle: handle, channel: int, data: string, reliable: bool)` | Queue a packet on a channel. |
| `enetDisconnect(peerHandle: handle)` | Begin disconnecting a peer. |
| `enetClose(hostHandle: handle)` | Destroy an ENet host. |

## pubsub

Deliver a message to every subscriber of a topic, across contexts and engines. Delivery is
synchronous; each subscriber runs on its own context's thread and gets a deep copy of the
message. Keep publish graphs acyclic.

| Function | Description |
|---|---|
| `psSubscribe(topic: string, fn: fn) -> int` | Register `fn` to receive messages published on `topic`; returns a subscription id. |
| `psUnsubscribe(id: int)` | Drop the subscription with that id. |
| `psPublish(topic: string, msg: any) -> int` | Deliver a copy of `msg` to every subscriber; returns how many were invoked. |

## ssh

SSH/SFTP over libssh2. Requires a reachable SSH server. Payloads are binary-safe. A connection
handle can be passed to and used by another context (see Handles above), but a libssh2 session
is **not thread-safe**: never operate on one handle from two contexts at once -- calog does not
serialize it for you.

| Function | Description |
|---|---|
| `sshConnect(host: string[, port: int]) -> handle` | Connect (port defaults to 22). |
| `sshAuthPassword(handle: handle, user: string, password: string) -> bool` | Password authentication. |
| `sshAuthKey(handle: handle, user: string, privateKeyPath: string[, publicKeyPath: string, passphrase: string]) -> bool` | Public-key authentication. |
| `sshExec(handle: handle, command: string) -> map` | Run a remote command: `{stdout, stderr, exitCode}`. |
| `sshClose(handle: handle)` | Close the session. |
| `sftpGet(handle: handle, remotePath: string) -> string` | Read a remote file whole (binary-safe). |
| `sftpPut(handle: handle, remotePath: string, data: string)` | Create/truncate a remote file (mode 0644). |
| `sftpList(handle: handle, path: string) -> list` | `[{name, size, isDir}, ...]`. |
| `sftpStat(handle: handle, path: string) -> map \| nil` | `{size, isDir}`, or nil if the path is missing. |
| `sftpRemove(handle: handle, path: string)` | Remove a remote file. |
| `sftpMkdir(handle: handle, path: string)` | Create a remote directory (mode 0755). |

## task

Launch and manage other calog script contexts. Tasks are fire-and-forget: a spawned context
runs on its own thread; results come back through host natives or the shared kv/pubsub. A
task is owned by the context that spawned it, and only that owner may `taskEval`/`taskClose`.
`taskClose` is cooperative -- a task busy in a pure loop must poll `taskActive()` and break
out, or the close blocks until the task next returns to the runtime.

| Function | Description |
|---|---|
| `taskSpawn(engine: string, code: string) -> handle` | Run a code string on a named engine (`"lua"`, `"js"`, `"squirrel"`, `"mybasic"`, `"berry"`, `"s7"`, `"wren"`, `"mruby"`). |
| `taskLoad(baseName: string) -> handle` | Launch a script *file* (engine chosen by extension). |
| `taskEval(handle: handle, code: string)` | Feed more code into a running task (runs on its thread). |
| `taskClose(handle: handle)` | Ask a task to stop (cooperative: sets its shutdown flag, then waits for its thread to exit). |
| `taskActive() -> bool` | Called *inside a task*: `false` once its owner has asked it to stop. A long loop polls this -- `while taskActive() do ... end` -- so `taskClose` need not block. |
| `taskActive(handle: handle) -> bool` | Called *in the owner*: whether the task spawned under `handle` is still open. |
| `taskExit()` | Called *inside a task*: retire this task's **own** context. Deferred -- the current code finishes normally, then the context stops and the runtime reaps it (no owner action needed). |
| `taskSelf() -> int` | The calling script's own context id. |
| `taskCount() -> int` | Number of tasks this library currently holds open. |

## time

| Function | Description |
|---|---|
| `timeNow() -> real` | Wall-clock epoch seconds, fractional (CLOCK_REALTIME). |
| `timeMonotonic() -> real` | Seconds from an unspecified origin (CLOCK_MONOTONIC); use for intervals. |
| `timeSleep(ms: int)` | Block the calling context for `ms` milliseconds. |

## timer

One background thread drives every timer; each callback runs on the context that created the
timer.

| Function | Description |
|---|---|
| `timerAfter(ms: int, fn: fn) -> int` | Fire `fn` once, `ms` milliseconds from now; returns a timer id. |
| `timerEvery(ms: int, fn: fn) -> int` | Fire `fn` every `ms` milliseconds; returns a timer id. |
| `timerCancel(id: int)` | Stop a pending or repeating timer. |