3654abb · hypercore-kb

Changed files (2) +222 -0

.claude/skills/hrpc-c/SKILL.md +110 -0

…	…	@@ -0,0 +1,110 @@
	1	---
	2	name: hrpc-c
	3	description: Generate typed, sans-io C RPC from an HRPC schema — encoders, decoders and a dispatcher over the bare-rpc wire, built on librpc + libcompact and reusing hyperschema-c structs. Read before hand-rolling any local-socket or daemon protocol in C. Keywords: hrpc-c, RPC, C, sans-io, librpc, libcompact, hyperschema-c, bare-rpc, dispatcher, unary, event, stream, duplex, daemon, UDS, codegen.
	4	---
	5
	6	# hrpc-c
	7
	8	A JS BUILD-TIME TOOL THAT EMITS C. Node runs the generator; the output links
	9	`librpc` + `libcompact` and needs no JavaScript at runtime. That is what makes
	10	it usable in a pure-C/C++ daemon.
	11
	12	⚠ Verified 2026-09-10 against UPSTREAM `02253b8` (2026-08-29) — README via the
	13	GitHub API, generated shapes read from `lib/codegen.js` in the clone. **The KB
	14	clone `holepunchto/repos/tier-new/hrpc-c` is at `90e9902` (2026-08-10)**; the
	15	three commits since are CI plus *"Compare against the descriptor instead of
	16	re-deriving the payload rule"*. Re-check before trusting details not marked as
	17	read from upstream.
	18
	19	## Sans-io is the point
	20
	21	From the README: *"the generated code is pure functions: it never owns a socket,
	22	an event loop, or stream state. You call the typed encoders to produce frames,
	23	hand inbound frames to the dispatcher, and do the actual I/O and stream lifecycle
	24	yourself."*
	25
	26	So it composes with whatever carries bytes — a Unix socket, a Protomux channel, a
	27	pipe. It does not impose a transport.
	28
	29	## Why it matters to us
	30
	31	The generic swarm daemon design (`blender-bridge/docs/P2P_BRIDGE_SPEC.md`, and
	32	the `swarmd` sketch) hand-rolled a UDS protocol: length-prefixed frames, a
	33	hand-written type/id header, hand-written compact-encoding. **hrpc-c generates
	34	exactly that**, typed, from a schema, with streaming shapes included — and
	35	`libcompact` already is the C codec we hand-wrote as
	36	`hyperswarm-peer/src/compact_encoding.h`.
	37
	38	⚠ It speaks the bare-rpc wire protocol. That is a protocol, not a runtime
	39	dependency: a C program can speak it to another C program with no Bare anywhere.
	40
	41	## Usage
	42
	43	`CHRPC` extends the JS `hrpc` builder:
	44
	45	```js
	46	const CHyperschema = require('hyperschema-c')
	47	const CHRPC = require('hrpc-c')
	48
	49	const schema = CHyperschema.from('./spec')
	50	const greeter = schema.namespace('greeter')
	51	greeter.register({ name: 'hello-request', fields: [{ name: 'id', type: 'uint', required: true }] })
	52	greeter.register({ name: 'hello-response', fields: [{ name: 'greeting', type: 'uint', required: true }] })
	53
	54	const hrpc = new CHRPC(schema, './spec')
	55	hrpc.namespace('greeter').register({
	56	name: 'hello',
	57	request: { name: '@greeter/hello-request', stream: false },
	58	response: { name: '@greeter/hello-response', stream: false }
	59	})
	60
	61	CHyperschema.toDisk(schema)
	62	CHRPC.toDisk(hrpc)
	63	```
	64
	65	`toDisk` writes five files: `hrpc.json` (the schema), `hrpc.h` (shared,
	66	schema-independent runtime types and enums), `<target>.h` / `<target>.c`, and a
	67	`CMakeLists.txt`. `<target>` is the namespaces joined by `_` plus `_hrpc`.
	68	`toCode(opts)` returns `{ shared, header, source }` as strings instead.
	69
	70	The generated `CMakeLists.txt` expects the consumer to provide `compact`, `rpc`
	71	and the schema target (default `<namespaces>_schema`, override with
	72	`opts.schemaTarget`).
	73
	74	## The five handler kinds
	75
	76	Chosen by the request/response shape. Command ids are the global, append-only ids
	77	from the schema; identifiers are namespaced `<ns>_...`.
	78
	79	\| kind \| shape \| you get \|
	80	\|---\|---\|---\|
	81	\| unary \| request + response, neither streaming \| `<ns>_encode_<name>`, `_error`, `_decode_<name>_response`, and `int (<ns>_on_<name>)(void ctx, const <req>_t , <res>_t , hrpc_error_t *)` \|
	82	\| event \| `request.send: true`, no response \| fire-and-forget encoder (id 0) + `void (on)(void ctx, const <req>_t *)` \|
	83	\| response-stream \| `response.stream: true` \| request encoder, server `_open`/`_chunk`/`_end`/`_error`, client `_stream_open` echo, `_decode_<name>_chunk`, `int (*on)(ctx, req, uint64_t stream_id)` \|
	84	\| request-stream \| `request.stream: true` \| client `_open`/`_chunk`/`_end`, server echo + chunk decode, one unary-style reply, `int (*on)(ctx, uint64_t stream_id)` \|
	85	\| duplex \| both streaming \| the union of both, fully `request_`/`response_` qualified \|
	86
	87	## ⛔ Memory rules — the two that will bite
	88
	89	Both from the README, and both are the opposite of what a careless reader assumes:
	90
	91	- *Every `_encode_` heap-allocates `out`. THE CALLER FREES IT.** The generated
	92	code mallocs the frame (`codegen.js:374-384`) and hands over ownership.
	93	- Decoded views point INTO the inbound frame buffer. `hrpc_error_t` strings
	94	and chunk payloads are borrowed, not copied — anything kept past the read loop
	95	must be copied out first, or it dangles the moment the buffer is reused.
	96
	97	## Dependencies
	98
	99	- [[libcompact]] — the C compact-encoding runtime (ABI-identical to the JS codec)
	100	- `librpc` — the C RPC codec, "low-level RPC codec implemented in C for wide
	101	language support"
	102	- [[hyperschema-c]] — supplies the struct codecs the RPC layer carries
	103
	104	## Related
	105
	106	- [[hyperschema-c]] — generate the structs first; hrpc-c layers on top
	107	- [[hrpc]] — the JS builder `CHRPC` extends
	108	- `bare-linux` — a C host embedding Bare and talking to it over this wire. ⚠ That
	109	route is a SHIM, not a library: the P2P half is JavaScript on a Bare worklet.
	110	hrpc-c itself needs no JS at runtime; bare-kit does.

.claude/skills/hyperschema-c/SKILL.md +112 -0

…	…	@@ -0,0 +1,112 @@
	1	---
	2	name: hyperschema-c
	3	description: Generate C struct codecs from a Hyperschema — the JS tool that emits preencode/encode/decode C on top of libcompact, so a C program speaks the same wire as the JS stack without hand-writing message codecs. Read before hand-porting any compact-encoded message to C. Keywords: hyperschema-c, codegen, C, libcompact, compact_state_t, preencode, encode, decode, schema, wire, dht_messages, versioned, tagged union.
	4	---
	5
	6	# hyperschema-c
	7
	8	A JS BUILD-TIME TOOL THAT EMITS C. Node runs the generator; the output is plain
	9	C that links `libcompact` and needs no JavaScript at runtime. That distinction is
	10	the whole reason it fits a pure-C/C++ daemon.
	11
	12	⚠ Verified 2026-09-10 against UPSTREAM `ccae70b` (2026-08-29) via the GitHub
	13	API and by reading `lib/codegen.js` in the local clone. **The KB clone
	14	`holepunchto/repos/tier-new/hyperschema-c` is at `727039f` (2026-06-04) — about
	15	three months stale.** Re-check before trusting anything here that is not marked
	16	as read from upstream. (Reading a stale clone as current is what put a whole
	17	parity audit on hyperdht 6.29.0 while upstream was at 6.34.0 — see
	18	[[hrpc-c]] and hyperswarm-peer `docs/PARITY-hyperswarm.md` §2.)
	19
	20	## Why it matters to us
	21
	22	Our `hyperswarm-peer/src/dht_messages.h` is a hand-written codec for the
	23	HyperDHT wire. Upstream is moving the other way: hyperdht 6.34.0 pulled in
	24	`hyperdht-address`, which uses hyperschema, and `libhc`'s own commits read
	25	"generate manifest encoding via hyperschema-c". So their encodings are becoming
	26	a GENERATED artifact from a shared schema while ours are typed by hand.
	27
	28	Generating ours from the same schemas would make tracking upstream mechanical
	29	instead of an audit. Not done — recorded as an open question in
	30	`PARITY-hyperswarm.md` §6.3.
	31
	32	## Usage
	33
	34	```js
	35	const CHyperschema = require('hyperschema-c')
	36
	37	const schema = CHyperschema.from('./spec')
	38	const { header, source } = schema.toCode() // strings
	39	CHyperschema.toDisk(schema, './output') // or write them
	40	```
	41
	42	The whole public API, from `index.d.ts`:
	43
	44	```ts
	45	declare class CHyperschema {
	46	toCode(): { header: string; source: string }
	47	static from(dir: string): CHyperschema
	48	static toDisk(hyperschema: CHyperschema, dir?: string \| null): void
	49	}
	50	```
	51
	52	`toDisk` writes `<target>.h`, `<target>.c`, `schema.json` and a `CMakeLists.txt`.
	53	`<target>` comes from the namespaces: one namespace `hc` gives `hc_schema.{h,c}`;
	54	several give `<ns1>_<ns2>_schema`.
	55
	56	## The generated shape
	57
	58	Read from `lib/codegen.js:219-338`. Every type becomes a struct plus the same
	59	three functions:
	60
	61	```c
	62	typedef struct <name>_s { /* fields */ } <name>_t;
	63
	64	int <name>_preencode (compact_state_t state, const <name>_t value);
	65	int <name>_encode (compact_state_t state, const <name>_t value);
	66	int <name>_decode (compact_state_t state, <name>_t result);
	67	```
	68
	69	⚠ **That is the same preencode → allocate → encode triad our hand-written
	70	`compact_encoding.h` already uses**, so generated codecs drop into the existing
	71	call sites without restructuring anything.
	72
	73	Versioned types become tagged unions (`codegen.js:219`):
	74
	75	```c
	76	typedef struct <name>_s {
	77	uint64_t version;
	78	union { /* one member per version */ };
	79	} <name>_t;
	80	```
	81
	82	preencode/encode take the version by value; decode reads into it.
	83
	84	## Field types
	85
	86	The complete table (`codegen.js:19-46`). A type not in it is a build-time error
	87	naming the supported set — it never silently degrades.
	88
	89	\| schema \| C \|
	90	\|---\|---\|
	91	\| `bool` \| `bool` \|
	92	\| `uint` / `int` \| `uint64_t` / `int64_t` (varint) \|
	93	\| `uint8/16/32/64`, `int8/16/32/64` \| the matching fixed-width type \|
	94	\| `uint24/40/48/56`, `int24/40/48/56` \| widened to 32/64-bit \|
	95	\| `fixed32` / `fixed64` \| `uint8_t` array \|
	96	\| `buffer` \| `uint8_t` array (`uint8array` on the wire) \|
	97	\| `string`, `json` \| `utf8_string_view_t` (both encode as utf8) \|
	98	\| `float32` / `float64` \| `float` / `double` \|
	99
	100	⚠ `json` and `string` are the SAME wire type. The schema distinguishes intent,
	101	not bytes.
	102
	103	## Dependencies
	104
	105	Generated code needs `libcompact` (`compact_state_t`) and nothing else. The
	106	generated `CMakeLists.txt` expects the consumer to provide a `compact` target.
	107
	108	## Related
	109
	110	- [[hrpc-c]] — layers typed RPC on top of these struct codecs
	111	- [[libcompact]] — the C runtime the output links; ABI-identical to the JS codec
	112	- [[hyperschema]] — the JS schema definitions these are generated from

hypercore-kb commits / 3654abb

Changed files (2) +222 -0