feat: allow no-ctx ffi procs

Author: gmelodie

CHANGELOG.md

@@ -20,12 +20,26 @@ All notable changes to this project are documented in this file.
   where `-install_name` requires `-dynamiclib`.
 
 ### Added
+- **`{.ffiStatic.}`**: exports a context-independent proc. It takes no library
+  param, and its wrapper takes no `ctx`, so a host can call a stateless utility
+  (key generation, parsing, a version string) without constructing the library
+  — previously the only way to expose one was an `{.ffi.}` method, forcing the
+  caller to build and tear down an instance just to reach it
+  ([#134](https://github.com/logos-messaging/nim-ffi/issues/134)). Wired for
+  both the `cbor` and `c` ABIs and all four backends: the C header emits
+  `<lib>_static_<proc>(...)` (`<lib>_ctx_<proc>` is the method form and
+  `<lib>_<proc>` the raw symbol), while C++ and Rust emit an associated function
+  on the ctx type taking the `timeout` a method reads from its ctx. Handlers run
+  on the library's *static context*, created on the first such call and alive for
+  the rest of the process, so the first call starts a thread pair that is never
+  torn down. An `{.ffiHandle.}` parameter or return is rejected at macro time: a
+  handle belongs to the context that created it, which a static proc cannot reach.
 - `{.ffiEvent.}` no longer requires an explicit wire-name string: when omitted
   it is derived from the proc name via `camelToSnakeCase`
   (`onPeerConnected` → `on_peer_connected`), matching how `{.ffi.}` derives its
   C export symbol. Pass a string literal only to override it.
-- FFI annotations (`{.ffi.}`, `{.ffiCtor.}`, `{.ffiDtor.}`, `{.ffiEvent.}`,
-  `{.ffiHandle.}`, `{.ffiRaw.}`) that expand after `genBindings()` now produce a
+- FFI annotations (`{.ffi.}`, `{.ffiStatic.}`, `{.ffiCtor.}`, `{.ffiDtor.}`,
+  `{.ffiEvent.}`, `{.ffiHandle.}`, `{.ffiRaw.}`) that expand after `genBindings()` now produce a
   loud compile error instead of being silently dropped from the generated
   bindings.
 - **C binding generator** (`-d:targetLang=c`): emits a header-only C binding

README.md

@@ -19,7 +19,7 @@ requires "https://github.com/logos-messaging/nim-ffi >= 0.2.0"
 
 - You **declare a library** once with `declareLibrary(name, LibType)`.
 - You **annotate procs and types** with pragmas (`{.ffi.}`, `{.ffiCtor.}`,
-  `{.ffiDtor.}`, `{.ffiEvent.}`).
+  `{.ffiDtor.}`, `{.ffiStatic.}`, `{.ffiEvent.}`).
 - You **call `genBindings()` last**, which emits the foreign bindings.
 
 By default, every request/response crosses the boundary as a single CBOR blob
@@ -78,6 +78,7 @@ The generated C export names are the snake_case form of the proc names, e.g.
 | `declareLibrary(name, LibType[, defaultABIFormat])` | call | Registers the library, its state type, and the default wire format. Must run before any annotation. |
 | `{.ffi.}` on a `type` | `object` | Registers the type for binding generation; it serializes via the library's ABI format (CBOR by default). |
 | `{.ffi.}` on a `proc` | proc | Exposes a method. First param is the library value, then typed params; returns `Future[Result[T, string]]`. |
+| `{.ffiStatic.}` | proc | Exposes a context-independent proc: no library param, and its wrapper takes no ctx — see below. |
 | `{.ffiCtor.}` | proc | The constructor. Returns `Future[Result[LibType, string]]`; creates the FFI context. |
 | `{.ffiDtor.}` | proc | The destructor. Exactly one param `(x: LibType)`; tears the context down. |
 | `{.ffiEvent[: "wire_name"].}` | proc (empty body) | A library-initiated callback. Call the proc from any `{.ffi.}` handler to fire it. The wire name is optional — see below. |
@@ -91,6 +92,44 @@ Every `{.ffi.}` / `{.ffiCtor.}` proc must have an explicit
 `return ok(...)` without awaiting). The `Result`'s error string is delivered to
 the foreign caller as the failure message.
 
+### Context-independent procs
+
+A `{.ffi.}` proc is a method: it takes the library value and its wrapper takes a
+`ctx`, so the host must construct the library to call it. A stateless utility
+shouldn't have to pay for that. Annotate it `{.ffiStatic.}` instead — drop the
+library param, and the ctx disappears from the generated wrapper:
+
+```nim
+proc counterParse*(text: string): Future[Result[BumpRequest, string]] {.ffiStatic.} =
+  return ok(BumpRequest(by: text.parseInt()))
+```
+
+```c
+/* {.ffi.} method              */ counter_ctx_bump(ctx, &req, on_reply, ud);
+/* {.ffiStatic.} — no ctx      */ counter_static_parse(text, on_reply, ud);
+```
+
+The wrapper is `<lib>_static_<proc>` rather than `<lib>_<proc>` for the same
+reason a method's is `<lib>_ctx_<proc>`: `<lib>_<proc>` is the raw symbol the
+dylib exports. In C++ and Rust a static is an associated function on the ctx
+type (`EchoCtx::lib_version()`), so it takes the `timeout` a method reads from
+its ctx.
+
+The handler still runs on an FFI thread — the library's **static context**,
+created on the first `{.ffiStatic.}` call and alive for the rest of the process.
+So the first such call starts a thread pair that is never torn down (there is no
+ctx whose destructor could own them). It has no `myLib`, which is why a static
+proc cannot take the library value.
+
+Two things cannot cross a `{.ffiStatic.}` proc, and the macro rejects both: an
+`{.ffiHandle.}` parameter and an `{.ffiHandle.}` return. A handle is registered
+in the context that created it, and a static proc has no access to the caller's.
+
+Under `abi = c` a static replies with a `string` or an `{.ffi.}` object type. A
+scalar return is wired only for an all-scalar `{.ffi.}` method, which rides the
+[CBOR-free fast path](#abi-format) — that path resolves the library value
+through the ctx, which a static proc doesn't have.
+
 ### The result callback contract
 
 Each request carries a result callback. It receives one of these status codes

examples/echo/c_abi_bindings/echo.h

@@ -32,9 +32,17 @@ typedef struct {
 typedef struct {
     ShoutRequest req;
 } EchoShoutReq;
+typedef struct {
+    uint8_t _placeholder; /* C forbids empty structs */
+} EchoLibVersionReq;
+typedef struct {
+    ShoutRequest req;
+} EchoShoutAnonReq;
 
 typedef void (*EchoShoutReplyFn)(int err_code, const ShoutResponse* reply, const char* err_msg, void* user_data);
 typedef void (*EchoVersionReplyFn)(int err_code, const char* reply, const char* err_msg, void* user_data);
+typedef void (*EchoLibVersionReplyFn)(int err_code, const char* reply, const char* err_msg, void* user_data);
+typedef void (*EchoShoutAnonReplyFn)(int err_code, const ShoutResponse* reply, const char* err_msg, void* user_data);
 
 typedef void (*EchoCreateRawFn)(int err_code, const char* ctx_addr, const char* err_msg, void* user_data);
 /* Raw reply of a scalar-fast-path export: `msg`/`len` are bytes (a string
@@ -61,6 +69,8 @@ extern "C" {
 void* echo_create(const EchoCreateCtorReq* req, EchoCreateRawFn on_created, void* user_data);
 int echo_shout(void* ctx, EchoShoutReplyFn on_reply, void* user_data, const EchoShoutReq* req);
 int echo_version(void* ctx, EchoScalarRawFn callback, void* user_data);
+int echo_lib_version(EchoLibVersionReplyFn on_reply, void* user_data, const EchoLibVersionReq* req);
+int echo_shout_anon(EchoShoutAnonReplyFn on_reply, void* user_data, const EchoShoutAnonReq* req);
 int echo_destroy(void* ctx);
 
 #ifdef __cplusplus
@@ -165,4 +175,17 @@ static inline int echo_ctx_version(const EchoCtx* ctx, EchoVersionReplyFn on_rep
     return echo_version(ctx->ptr, echo_version_scalar_reply, box);
 }
 
+static inline int echo_static_lib_version(EchoLibVersionReplyFn on_reply, void* user_data) {
+    EchoLibVersionReq ffi_req;
+    memset(&ffi_req, 0, sizeof(ffi_req));
+    return echo_lib_version(on_reply, user_data, &ffi_req);
+}
+
+static inline int echo_static_shout_anon(const ShoutRequest* req, EchoShoutAnonReplyFn on_reply, void* user_data) {
+    EchoShoutAnonReq ffi_req;
+    memset(&ffi_req, 0, sizeof(ffi_req));
+    ffi_req.req = *req;
+    return echo_shout_anon(on_reply, user_data, &ffi_req);
+}
+
 #endif /* NIM_FFI_LIB_ECHO_C_ABI_H_INCLUDED */

examples/echo/c_bindings/echo.h

@@ -25,6 +25,12 @@ typedef struct {
 typedef struct {
     char _nimffi_empty; /* C forbids empty structs */
 } EchoVersionReq;
+typedef struct {
+    char _nimffi_empty; /* C forbids empty structs */
+} EchoLibVersionReq;
+typedef struct {
+    ShoutRequest req;
+} EchoShoutAnonReq;
 
 static inline CborError echo_enc_EchoConfig(
         CborEncoder* e, const EchoConfig* v) {
@@ -185,6 +191,47 @@ static inline CborError echo_dec_EchoVersionReq(
     (void)out;
     return cbor_value_advance(it);
 }
+static inline CborError echo_enc_EchoLibVersionReq(
+        CborEncoder* e, const EchoLibVersionReq* v) {
+    (void)v;
+    CborEncoder m;
+    CborError err = cbor_encoder_create_map(e, &m, 0);
+    if (err) return err;
+    return cbor_encoder_close_container(e, &m);
+}
+static inline CborError echo_dec_EchoLibVersionReq(
+        CborValue* it, EchoLibVersionReq* out) {
+    if (!cbor_value_is_map(it)) return CborErrorImproperValue;
+    (void)out;
+    return cbor_value_advance(it);
+}
+static inline CborError echo_enc_EchoShoutAnonReq(
+        CborEncoder* e, const EchoShoutAnonReq* v) {
+    CborEncoder m;
+    CborError err = cbor_encoder_create_map(e, &m, 1);
+    if (err) return err;
+    err = cbor_encode_text_stringz(&m, "req");
+    if (err) return err;
+    err = echo_enc_ShoutRequest(&m, &v->req);
+    if (err) return err;
+    return cbor_encoder_close_container(e, &m);
+}
+static inline CborError echo_dec_EchoShoutAnonReq(
+        CborValue* it, EchoShoutAnonReq* out) {
+    if (!cbor_value_is_map(it)) return CborErrorImproperValue;
+    CborValue field;
+    CborError err;
+    err = cbor_value_map_find_value(it, "req", &field);
+    if (err) return err;
+    if (!cbor_value_is_valid(&field)) return CborErrorImproperValue;
+    err = echo_dec_ShoutRequest(&field, &out->req);
+    if (err) return err;
+    return cbor_value_advance(it);
+}
+static inline void echo_free_EchoShoutAnonReq(EchoShoutAnonReq* v) {
+    if (!v) return;
+    echo_free_ShoutRequest(&v->req);
+}
 
 /* ============================================================ */
 /* C ABI declarations (symbols exported by the Nim dylib)       */
@@ -196,6 +243,8 @@ extern "C" {
 void* echo_create(const uint8_t* req_cbor, size_t req_cbor_len, FFICallback callback, void* user_data);
 int echo_shout(void* ctx, FFICallback callback, void* user_data, const uint8_t* req_cbor, size_t req_cbor_len);
 int echo_version(void* ctx, FFICallback callback, void* user_data, const uint8_t* req_cbor, size_t req_cbor_len);
+int echo_lib_version(FFICallback callback, void* user_data, const uint8_t* req_cbor, size_t req_cbor_len);
+int echo_shout_anon(FFICallback callback, void* user_data, const uint8_t* req_cbor, size_t req_cbor_len);
 int echo_destroy(void* ctx);
 uint64_t echo_add_event_listener(void* ctx, const char* event_name, FFICallback callback, void* user_data);
 int echo_remove_event_listener(void* ctx, uint64_t listener_id);
@@ -208,6 +257,8 @@ int echo_remove_event_listener(void* ctx, uint64_t listener_id);
 static inline CborError echo_encv_EchoCreateCtorReq(CborEncoder* e, const void* v) { return echo_enc_EchoCreateCtorReq(e, (const EchoCreateCtorReq*)v); }
 static inline CborError echo_encv_EchoShoutReq(CborEncoder* e, const void* v) { return echo_enc_EchoShoutReq(e, (const EchoShoutReq*)v); }
 static inline CborError echo_encv_EchoVersionReq(CborEncoder* e, const void* v) { return echo_enc_EchoVersionReq(e, (const EchoVersionReq*)v); }
+static inline CborError echo_encv_EchoLibVersionReq(CborEncoder* e, const void* v) { return echo_enc_EchoLibVersionReq(e, (const EchoLibVersionReq*)v); }
+static inline CborError echo_encv_EchoShoutAnonReq(CborEncoder* e, const void* v) { return echo_enc_EchoShoutAnonReq(e, (const EchoShoutAnonReq*)v); }
 static inline CborError echo_decv_ShoutResponse(CborValue* it, void* v) { return echo_dec_ShoutResponse(it, (ShoutResponse*)v); }
 static inline CborError echo_decv_Str(CborValue* it, void* v) { return nimffi_dec_str(it, (NimFfiStr*)v); }
 
@@ -418,4 +469,127 @@ static inline int echo_ctx_version(const EchoCtx* ctx, EchoVersionReplyFn on_rep
     return 0;
 }
 
+typedef void (*EchoLibVersionReplyFn)(int err_code, const NimFfiStr* reply, const char* err_msg, void* user_data);
+typedef struct { EchoLibVersionReplyFn fn; void* user_data; } EchoLibVersionCallBox;
+static void echo_lib_version_reply_trampoline(int ret, const char* msg, size_t len, void* ud) {
+    EchoLibVersionCallBox* box = (EchoLibVersionCallBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
+    if (!box->fn) {
+        free(box);
+        return;
+    }
+    if (ret != 0) {
+        char* em = nimffi_dup_cstr_n(msg ? msg : "", msg ? len : 0);
+        box->fn(ret, NULL, em ? em : "FFI call failed", box->user_data);
+        free(em);
+        free(box);
+        return;
+    }
+    char* err = NULL;
+    NimFfiStr out;
+    memset(&out, 0, sizeof(out));
+    int dec = nimffi_decode_from_buf(echo_decv_Str, (const uint8_t*)msg, len, &out, &err);
+    if (dec != 0) {
+        box->fn(-1, NULL, err ? err : "decode failed", box->user_data);
+        free(err);
+        nimffi_free_str(&out);
+        free(box);
+        return;
+    }
+    box->fn(NIMFFI_RET_OK, &out, NULL, box->user_data);
+    nimffi_free_str(&out);
+    free(box);
+}
+static inline int echo_static_lib_version(EchoLibVersionReplyFn on_reply, void* user_data) {
+    EchoLibVersionReq ffi_req;
+    memset(&ffi_req, 0, sizeof(ffi_req));
+    uint8_t* req_buf = NULL;
+    size_t req_len = 0;
+    char* err = NULL;
+    if (nimffi_encode_to_buf(echo_encv_EchoLibVersionReq, &ffi_req, &req_buf, &req_len, &err) != 0) {
+        if (on_reply) on_reply(-1, NULL, err ? err : "encode failed", user_data);
+        free(err);
+        return -1;
+    }
+    EchoLibVersionCallBox* box = (EchoLibVersionCallBox*)malloc(sizeof(EchoLibVersionCallBox));
+    if (!box) {
+        free(req_buf);
+        if (on_reply) on_reply(-1, NULL, "out of memory", user_data);
+        return -1;
+    }
+    box->fn = on_reply;
+    box->user_data = user_data;
+    int ret = echo_lib_version(echo_lib_version_reply_trampoline, box, req_buf, req_len);
+    free(req_buf);
+    if (ret == NIMFFI_RET_MISSING_CALLBACK) {
+        if (on_reply) on_reply(-1, NULL, "RET_MISSING_CALLBACK (internal error)", user_data);
+        free(box);
+        return -1;
+    }
+    return 0;
+}
+
+typedef void (*EchoShoutAnonReplyFn)(int err_code, const ShoutResponse* reply, const char* err_msg, void* user_data);
+typedef struct { EchoShoutAnonReplyFn fn; void* user_data; } EchoShoutAnonCallBox;
+static void echo_shout_anon_reply_trampoline(int ret, const char* msg, size_t len, void* ud) {
+    EchoShoutAnonCallBox* box = (EchoShoutAnonCallBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
+    if (!box->fn) {
+        free(box);
+        return;
+    }
+    if (ret != 0) {
+        char* em = nimffi_dup_cstr_n(msg ? msg : "", msg ? len : 0);
+        box->fn(ret, NULL, em ? em : "FFI call failed", box->user_data);
+        free(em);
+        free(box);
+        return;
+    }
+    char* err = NULL;
+    ShoutResponse out;
+    memset(&out, 0, sizeof(out));
+    int dec = nimffi_decode_from_buf(echo_decv_ShoutResponse, (const uint8_t*)msg, len, &out, &err);
+    if (dec != 0) {
+        box->fn(-1, NULL, err ? err : "decode failed", box->user_data);
+        free(err);
+        echo_free_ShoutResponse(&out);
+        free(box);
+        return;
+    }
+    box->fn(NIMFFI_RET_OK, &out, NULL, box->user_data);
+    echo_free_ShoutResponse(&out);
+    free(box);
+}
+static inline int echo_static_shout_anon(const ShoutRequest* req, EchoShoutAnonReplyFn on_reply, void* user_data) {
+    EchoShoutAnonReq ffi_req;
+    memset(&ffi_req, 0, sizeof(ffi_req));
+    ffi_req.req = *req;
+    uint8_t* req_buf = NULL;
+    size_t req_len = 0;
+    char* err = NULL;
+    if (nimffi_encode_to_buf(echo_encv_EchoShoutAnonReq, &ffi_req, &req_buf, &req_len, &err) != 0) {
+        if (on_reply) on_reply(-1, NULL, err ? err : "encode failed", user_data);
+        free(err);
+        return -1;
+    }
+    EchoShoutAnonCallBox* box = (EchoShoutAnonCallBox*)malloc(sizeof(EchoShoutAnonCallBox));
+    if (!box) {
+        free(req_buf);
+        if (on_reply) on_reply(-1, NULL, "out of memory", user_data);
+        return -1;
+    }
+    box->fn = on_reply;
+    box->user_data = user_data;
+    int ret = echo_shout_anon(echo_shout_anon_reply_trampoline, box, req_buf, req_len);
+    free(req_buf);
+    if (ret == NIMFFI_RET_MISSING_CALLBACK) {
+        if (on_reply) on_reply(-1, NULL, "RET_MISSING_CALLBACK (internal error)", user_data);
+        free(box);
+        return -1;
+    }
+    return 0;
+}
+
 #endif /* NIM_FFI_LIB_ECHO_H_INCLUDED */