hakorune/docs/reference/plugin-abi/nyash_abi_v2.md

Nyash Plugin ABI v2 (TypeBox)

Overview
- Purpose: unify plugin invocation via per‑Box TypeBox exports and a simple TLV wire format.
- Design: loader resolves a per‑Box dispatch function once, then calls by `(instance_id, method_id, TLV args) → TLV result`.
- Stability: v2 opts for simplicity over backward compatibility. Migrate plugins to v2; legacy C ABI entry remains available only for bootstrapping during transition.

Error Codes
- 0: OK
- -1: E_SHORT (output buffer too small; two‑phase protocol)
- -2: E_TYPE (invalid type for call)
- -3: E_METHOD (unknown method id)
- -4: E_ARGS (invalid/malformed args)
- -5: E_PLUGIN (internal plugin error/missing TypeBox)
- -8: E_HANDLE (invalid instance handle)

TLV Encoding (version=1)
- Header: 2 bytes `u16` version (1), 2 bytes `u16` argc
- Entries: repeated blocks [tag: u8, reserved: u8=0, size: u16 LE, payload: [size]]
- Tags
  - 1: bool (size=1; 0/1)
  - 2: i32 (size=4; LE)
  - 3: i64 (size=8; LE)
  - 4: f32 (size=4; LE)
  - 5: f64 (size=8; LE)
  - 6: string (UTF‑8)
  - 7: bytes
  - 8: plugin handle (type_id:u32 + instance_id:u32)
  - 9: host handle (u64)

Two‑Phase Result Protocol
- On first call, host may pass `result=NULL` or a small buffer.
- Plugin returns `E_SHORT` and writes required size to `*result_len`.
- Host re‑allocates and retries; on success return 0 and fill result.

TypeBox Export
- Each plugin Box publishes a single symbol: `nyash_typebox_<BoxName>` with C layout:

  struct NyashTypeBoxFfi {
    uint32_t abi_tag;     // 'TYBX' = 0x54594258
    uint16_t version;     // 1
    uint16_t struct_size; // sizeof(NyashTypeBoxFfi)
    const char* name;     // "FileBox\0", etc.
    uint32_t (*resolve)(const char* method_name); // optional
    int32_t  (*invoke_id)(uint32_t instance_id, uint32_t method_id,
                          const uint8_t* args, size_t args_len,
                          uint8_t* out, size_t* out_len);
    uint64_t capabilities; // reserved
  };

Naming Conventions
- Symbol: `nyash_typebox_<Box>` where `<Box>` is the Box type (e.g., `FileBox`, `RegexBox`).
- Methods: prefer lowerCamelCase in resolve names (e.g., `setStatus`, `readBody`, `isMatch`).
- Boxes live in one shared library and are listed under `[libraries."<libname>"].boxes` in `nyash.toml`.

Examples
- RegexBox (methods: birth/compile/isMatch/find/replaceAll/split/fini)
  - resolve → method_id → invoke_id: decode TLV → run regex → encode TLV
  - Export `nyash_typebox_RegexBox` with `resolve` and `invoke_id` pointers.

- Net (Client/Response/Request minimal)
  - ClientBox: `get(url)`, `post(url, body)` → returns Handle(Response)
  - ResponseBox: `setStatus(i32)`, `setHeader(name,value)`, `write(bytes|string)`, `getStatus()`, `readBody()`
  - RequestBox: `path()`, `readBody()`, `respond(Response)`
  - Each Box exports its own TypeBox symbol (e.g., `nyash_typebox_ClientBox`).

nyash.toml Layout
- Declare libraries and per‑Box metadata:

  [libraries]
  [libraries."libnyash_regex_plugin.so"]
  boxes = ["RegexBox"]
  path = "plugins/nyash-regex-plugin/target/release/libnyash_regex_plugin.so"

  [libraries."libnyash_regex_plugin.so".RegexBox]
  type_id = 52
  abi_version = 1
  [libraries."libnyash_regex_plugin.so".RegexBox.methods]
  birth = { method_id = 0 }
  compile = { method_id = 1 }
  isMatch = { method_id = 2 }

Error Handling Patterns
- Two‑phase output (E_SHORT) is mandatory for large or variable results.
- For invalid handles/args, return `-8` / `-4` respectively; host commonly wraps these into `ResultBox` in higher layers.

Invoke Semantics
- Birth: method_id=0, instance_id=0. Returns 4‑byte LE instance_id (not TLV).
- Fini: method_id=UINT32_MAX, instance_id=target. Should release resources and return OK with TLV void or 0‑entry TLV.
- Regular methods: return TLV payloads per method contract.

Host Expectations
- Host looks up per‑Box function from the TypeBox symbol and calls it via a library‑level shim.
- If no TypeBox is exported for a box, the call fails with `E_PLUGIN`.
- Method ids and type ids are configured in `nyash.toml` under `[libraries]`.

Minimal C Header
- See `include/nyash_abi.h` for a ready‑to‑use header and constants.

Notes
- Keep result payloads small; prefer handles (tag=8) for large data and stream APIs.
- Use UTF‑8 strings (tag=6) for human‑readable values; use bytes (tag=7) otherwise.

Method Tables (TLV Contracts)
- RegexBox
  - birth(0): returns `handle` (RegexBox)
  - compile(1): args [string pattern]; returns `OK`
  - isMatch(2): args [string text]; returns [bool]
  - find(3): args [string text]; returns [string match]
  - replaceAll(4): args [string text, string repl]; returns [string]
  - split(5): args [string text, i64 limit?]; returns [string joined by "\n"]
  - fini(MAX): returns `OK`

- Net — Client/Response/Request
  - ClientBox
    - birth(0): returns `handle` (ClientBox)
    - get(1): args [string url]; returns `handle` (ResponseBox)
    - post(2): args [string url, bytes|string body]; returns `handle` (ResponseBox)
    - fini(MAX)
  - ResponseBox
    - birth(0)
    - setStatus(1): args [i32]
    - setHeader(2): args [string name, string value]
    - write(3): args [bytes|string]
    - readBody(4): returns [bytes]
    - getStatus(5): returns [i32]
    - getHeader(6): args [string name]; returns [string]
    - fini(MAX)
  - RequestBox
    - birth(0): returns `handle` (RequestBox)
    - path(1): returns [string]
    - readBody(2): returns [bytes]
    - respond(3): args [handle(ResponseBox)]
    - fini(MAX)

Phase‑12 Alignment & Roadmap
- Alignment: The Phase‑12 “Unified TypeBox ABI” is a superset of this v2 minimal design. It shares the same core shape: per‑Box TypeBox export, method_id dispatch, and TLV arguments/results.
- Current focus (v2 minimal): simplicity and portability for first‑party plugins (Regex/Net/File/Path/Math/Time/Python family). The loader probes `nyash_typebox_<Box>` and calls `invoke_id` with `(instance_id, method_id, TLV)`.
- Forward compatibility: hosts validate `struct_size` and `version`. Future minor extensions can add optional fields to NyashTypeBoxFfi while preserving existing layout. Keep `capabilities=0` for now.
- Planned extensions (Phase‑16/17 candidates):
  - create/destroy function pointers (birth/fini remain for backward safety)
  - get_type_info() style metadata discovery (can be added via a resolved method first)
  - method table slotting and stricter signature IDs for faster dispatch
  - NyValue bridge and BoxHeader/vtable integration for RC/GC cooperation and JIT IC
- Guidance: implementers should target v2 minimal today. When Phase‑12 features land, they will be additive, with migration guides and host shims to keep existing v2 plugins working.