fumi/core/shim/smolmail_rns.h

/*
 * C ABI between fumi (Rust) and the microReticulum client shim.
 *
 * All calls block the caller; the shim owns the Reticulum loop thread and
 * every callback fires on that thread. link_id and destination_hash are
 * always 16 bytes. No client Reticulum identity is created or loaded anywhere
 * (upstream spec sec 13.8): a server MUST NOT require identification, and a
 * durable client handle is exactly what the wire format withholds.
 */
#ifndef SMOLMAIL_RNS_H
#define SMOLMAIL_RNS_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Implemented in smolmail_rns.cpp, called from src/rns/ffi.rs.
 * udp_forward_host may be NULL: with no forward target the interface sends
 * to the source address of the last datagram received, which a client that
 * only listens cannot use -- a client speaks first, so the forward target
 * should point at the server's UDP interface.
 * Returns 0 on success, negative on failure. */
int smolmail_rns_start(const char *storage_dir,
                       const char *udp_listen_host, uint16_t udp_listen_port,
                       const char *udp_forward_host, uint16_t udp_forward_port);

/* Requests a path if none is known and waits for it (upstream spec sec
 * 13.3), recalls the identity, builds the OUT/SINGLE smolmail.server
 * destination, opens the link and waits for ACTIVE. Returns the 16-byte
 * link id, which the caller's AUTH and REGISTER bind values are derived
 * from (upstream spec sec 13.6).
 * Returns 0 on success, negative on failure. */
int smolmail_rns_connect(const uint8_t *destination_hash, uint32_t timeout_ms,
                         uint8_t *link_id_out);

/* request is `op u8 || body`, the response `status u8 || payload`
 * (upstream spec sec 13.5). A CLI has one request in flight at a time, so
 * the shim keeps a single response slot rather than a map.
 * Returns 0 on success and writes the response length to *out_len;
 * negative on failure: no link (-1), send failure (-2), timeout or closed
 * link (-3), failed transfer (-4), malformed response (-5), response larger
 * than cap (-6). These are local errors and MUST NOT be reported as status
 * codes (upstream spec sec 13.5). */
int smolmail_rns_request(const uint8_t *request, size_t request_len,
                         uint32_t timeout_ms, uint8_t *out, size_t cap,
                         size_t *out_len);

/* Tears the link down rather than leave it on keepalives, which run for
 * minutes (upstream spec sec 13.10). */
void smolmail_rns_close(void);

/* Stops the Reticulum stack: halts and joins the loop thread, tears the link
 * down, deregisters and stops the UDP interface, and releases the
 * Reticulum instance. The loop thread must be joined before the process (or
 * embedding host) tears down statics, or it keeps calling into Reticulum
 * while their destructors run. A no-op when the stack is not running.
 * The stack can be started again afterwards. */
void smolmail_rns_stop(void);

#ifdef __cplusplus
}
#endif

#endif /* SMOLMAIL_RNS_H */