https://github.com/JairusSW/wipc
Minimal and performant binary IPC over Standard I/O
https://github.com/JairusSW/wipc
assemblyscript channel ipc protocol rpc stdio wasm
Last synced: 5 days ago
JSON representation
Minimal and performant binary IPC over Standard I/O
- Host: GitHub
- URL: https://github.com/JairusSW/wipc
- Owner: JairusSW
- License: mit
- Created: 2026-02-04T01:25:22.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-02-04T21:12:49.000Z (about 2 months ago)
- Last Synced: 2026-03-29T00:50:59.667Z (5 days ago)
- Topics: assemblyscript, channel, ipc, protocol, rpc, stdio, wasm
- Language: TypeScript
- Homepage:
- Size: 23.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-assemblyscript - wipc - Frame-based socket and rpc over stdio. Supports any runtime. (Packages / I/O)
README
╦ ╦ ╦ ╔═╗ ╔═╗
║║║ ║ ╠═╝ ║
╚╩╝ ╩ ╩ ╚═╝
**Wire IPC** -- minimal binary framing over standard i/o.
WIPC gives you a bidirectional byte channel between any two processes connected by pipes. It handles framing, buffering, and resync. Everything else -- payload encoding, RPC semantics, method dispatch -- is yours to define.
If a process can read `stdin` and write `stdout`, it can speak WIPC.
## Install
```sh
npm install wipc-js
```
## Example: Echo
### Host (Node.js / Bun)
```ts
import { Channel, MessageType } from "wipc-js";
import { spawn } from "node:child_process";
const child = spawn("wasmtime", ["./build/test.wasm"], {
stdio: ["pipe", "pipe", "inherit"],
});
class Echo extends Channel {
onDataMessage(data: Buffer) {
console.log("<-", data.toString("utf8"));
}
onPassthrough(data: Buffer) {
// Anything the guest writes to stdout that isn't a WIPC frame
process.stderr.write(data);
}
}
const ch = new Echo(child.stdout!, child.stdin!);
ch.send(MessageType.DATA, Buffer.from("hello"));
```
### Guest (AssemblyScript)
```ts
import { readFrame, writeFrame, MessageType, Frame } from "wipc-js/assembly/channel";
while (true) {
const frame: Frame | null = readFrame();
if (frame === null) break;
writeFrame(frame.type, frame.payload);
if (frame.type == MessageType.CLOSE) break;
}
```
That's it. The guest reads frames, echoes them back. The host sends frames, receives echoes.
## Wire Format
9-byte header, then payload:
```
0 4 5 9 9+N
┌───────┬──────┬─────────┬─────────┐
│ WIPC │ type │ length │ payload │
└───────┴──────┴─────────┴─────────┘
4 B 1 B u32 LE N B
```
```
┌────────┬──────┬─────────┬──────────────────────┐
│ Offset │ Size │ Field │ Description │
├────────┼──────┼─────────┼──────────────────────┤
│ 0 │ 4 │ MAGIC │ ASCII "WIPC" │
│ 4 │ 1 │ TYPE │ Message type │
│ 5 │ 4 │ LENGTH │ Payload size, u32 LE │
│ 9 │ N │ PAYLOAD │ Opaque bytes │
└────────┴──────┴─────────┴──────────────────────┘
```
### Message Types
```
┌───────┬───────┬────────────────────────────┐
│ Value │ Name │ Purpose │
├───────┼───────┼────────────────────────────┤
│ 0x00 │ OPEN │ Channel initialization │
│ 0x01 │ CLOSE │ Graceful shutdown │
│ 0x02 │ CALL │ RPC / request-response │
│ 0x03 │ DATA │ Raw data transfer │
└───────┴───────┴────────────────────────────┘
```
Payloads are opaque. WIPC does not prescribe encoding -- use JSON, protobuf, raw bytes, whatever fits your use case.
See [SPEC.md](./SPEC.md) for the full protocol specification.
## Architecture
```
┌───────────────┐
│ FFI │
└───────────────┘
│
┌────────────────────┐ stdin / stdout (WIPC) ┌───────────────────────┐
│ Host │ <──────────────────────> │ Guest / Child │
└────────────────────┘ └───────────────────────┘
│
┌───────────────┐
│ passthrough │
└───────────────┘
```
WIPC frames and regular stdout coexist on the same stream. The `Channel` parser separates them: frames are dispatched, everything else goes to `onPassthrough()`.
## API
### `Channel`
```ts
import { Channel, MessageType } from "wipc-js";
```
**Sending:**
- `send(type, payload?)` -- send a frame
- `sendJSON(type, msg)` -- send a frame with a JSON-encoded payload
**Receiving** (override in a subclass):
- `onOpen()` -- OPEN frame
- `onClose()` -- CLOSE frame
- `onCall(msg)` -- CALL frame (payload parsed as JSON)
- `onDataMessage(data)` -- DATA frame (raw Buffer)
- `onPassthrough(data)` -- non-WIPC bytes
### Guest API (AssemblyScript)
```ts
import { readFrame, writeFrame, MessageType } from "wipc-js/assembly";
```
- `writeFrame(type, payload?)` -- write a frame to stdout
- `readFrame(): Frame | null` -- blocking read from stdin
- `encode(type, payload): ArrayBuffer` -- encode without sending
- `decode(data): Frame | null` -- decode without reading
## Building
```sh
npm run asbuild # build all targets
npm run asbuild:debug # debug build
npm run asbuild:release # release build
npm test # run test suite
```
## Performance
Here's some benchmarks taken on my personal machine using Node.js v25:
```
Encode
encode small (27 B)
388ms | 2,577,150 ops/s | 57 MB/s
encode 1 KB
593ms | 1,685,483 ops/s | 1,726 MB/s
encode 64 KB
449ms | 222,904 ops/s | 14,608 MB/s
Decode (zero-copy, returns subarray view)
decode small (27 B)
88ms | 11,325,136 ops/s | 249 MB/s
decode 1 KB
88ms | 11,388,579 ops/s | 11,662 MB/s
decode 64 KB
88ms | 11,422,528 ops/s | 748,587 MB/s
Decode + copy (Buffer.from)
decode+copy small (27 B)
130ms | 7,694,254 ops/s | 169 MB/s
decode+copy 1 KB
222ms | 4,496,633 ops/s | 4,605 MB/s
decode+copy 64 KB
387ms | 258,641 ops/s | 16,950 MB/s
Channel round-trip (in-process echo)
echo small (27 B)
500,000 round-trips in 1,228ms | 407,213 rt/s | 18 MB/s
```
Decoding returns a `subarray` view -- no copies, constant time regardless of payload size. When you need to own the data, `Buffer.from()` copies at memcpy speed. Encoding cost is dominated by `Buffer.concat`. Round-trip throughput is limited by Node.js stream backpressure, not framing overhead.
Run benchmarks yourself:
```sh
npm run bench
```
## Runtime Requirements
**Host:** Any runtime that WIPC is ported to.
**Guest:** Anything that reads stdin and writes stdout. The included AssemblyScript library targets WASI runtimes (Wasmtime, Wasmer). Porting to Rust, C, Go, or any other language is straightforward -- see [SPEC.md](./SPEC.md).
## License
This project is distributed under an open source license. Work on this project is done by passion, but if you want to support it financially, you can do so by making a donation to the project's [GitHub Sponsors](https://github.com/sponsors/JairusSW) page.
You can view the full license using the following link: [License](./LICENSE)
## Contact
Please send all issues to [GitHub Issues](https://github.com/JairusSW/wipc/issues) and to converse, please send me an email at [me@jairus.dev](mailto:me@jairus.dev)
- **Email:** Send me inquiries, questions, or requests at [me@jairus.dev](mailto:me@jairus.dev)
- **GitHub:** Visit the official GitHub repository [Here](https://github.com/JairusSW/wipc)
- **Website:** Visit my official website at [jairus.dev](https://jairus.dev/)
- **Discord:** Contact me at [My Discord](https://discord.com/users/600700584038760448) or on the [AssemblyScript Discord Server](https://discord.gg/assemblyscript/)