docs(abi): align v2 with Phase‑12 blueprint; add roadmap/forward‑compat notes and Phase‑15 status pointer
This commit is contained in:
Selfhosting Dev
@ -1,5 +1,7 @@
|
||||
# Phase 12: Nyashコード共有エコシステム - Everything is Box の実現
|
||||
|
||||
> Status note (Phase‑15): このフォルダは「統一TypeBox ABI」の長期設計（青写真）です。現在の main 実装は最小の v2 ABI に収束しており、実用重視で段階導入中です。現行仕様は `docs/reference/plugin-abi/nyash_abi_v2.md` を参照してください。Phase‑12 の要素（create/destroy、型メタ、NyValue、vtable/RC/GC）は前方互換を維持しつつ段階追加予定です。
|
||||
|
||||
## 🌟 最新ブレイクスルー (2025-09-02) - 統一TypeBox ABI誕生！
|
||||
|
||||
### 🚨 究極の発見：ユーザー定義Boxもプラグインに！
|
||||
|
||||
113
docs/reference/plugin-abi/nyash_abi_v2.md
Normal file
113
docs/reference/plugin-abi/nyash_abi_v2.md
Normal file
@ -0,0 +1,113 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
66
include/nyash_abi.h
Normal file
66
include/nyash_abi.h
Normal file
@ -0,0 +1,66 @@
|
||||
// Nyash Plugin ABI v2 — TypeBox header (minimal)
|
||||
// Notes:
|
||||
// - This is the minimal, production-friendly subset used in Phase‑15.
|
||||
// - Forward compatibility: hosts validate struct_size and version; fields may
|
||||
// be extended in future minor revisions without breaking existing plugins.
|
||||
// - See docs/reference/plugin-abi/nyash_abi_v2.md for the spec and roadmap.
|
||||
#ifndef NYASH_ABI_V2_H
|
||||
#define NYASH_ABI_V2_H
|
||||
|
||||
#include <stdint.h>
|
||||
#include <stddef.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
// Magic and version
|
||||
#define NYASH_TYPEBOX_ABI_TAG 0x54594258u /* 'TYBX' */
|
||||
#define NYASH_ABI_VERSION 1u
|
||||
|
||||
// Error codes
|
||||
#define NYB_OK 0
|
||||
#define NYB_E_SHORT -1
|
||||
#define NYB_E_TYPE -2
|
||||
#define NYB_E_METHOD -3
|
||||
#define NYB_E_ARGS -4
|
||||
#define NYB_E_PLUGIN -5
|
||||
#define NYB_E_HANDLE -8
|
||||
|
||||
// TLV tags (version=1)
|
||||
#define NYTLV_BOOL 1
|
||||
#define NYTLV_I32 2
|
||||
#define NYTLV_I64 3
|
||||
#define NYTLV_F32 4
|
||||
#define NYTLV_F64 5
|
||||
#define NYTLV_STRING 6
|
||||
#define NYTLV_BYTES 7
|
||||
#define NYTLV_HANDLE 8 /* type_id:u32 + instance_id:u32 */
|
||||
#define NYTLV_HOST 9 /* host handle: u64 */
|
||||
|
||||
typedef int32_t (*ny_invoke_id_fn)(
|
||||
uint32_t instance_id,
|
||||
uint32_t method_id,
|
||||
const uint8_t* args,
|
||||
size_t args_len,
|
||||
uint8_t* out,
|
||||
size_t* out_len
|
||||
);
|
||||
|
||||
typedef uint32_t (*ny_resolve_fn)(const char* method_name);
|
||||
|
||||
typedef struct NyashTypeBoxFfi {
|
||||
uint32_t abi_tag;
|
||||
uint16_t version;
|
||||
uint16_t struct_size;
|
||||
const char* name; /* C string with trailing NUL */
|
||||
ny_resolve_fn resolve; /* optional */
|
||||
ny_invoke_id_fn invoke_id; /* required */
|
||||
uint64_t capabilities; /* reserved, set 0 */
|
||||
} NyashTypeBoxFfi;
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* NYASH_ABI_V2_H */
|
||||
Reference in New Issue
Block a user