Documentation Index
Fetch the complete documentation index at: https://docs.oxd.sh/llms.txt
Use this file to discover all available pages before exploring further.
Setup
Node.js calls the C library via koffi — a fast FFI library with no native compilation step.
Place liboxaccel.so / liboxaccel.dylib / oxaccel.dll in your project directory or system library path.
Usage
import koffi from 'koffi';
const libPath = process.env.OXACCEL_LIB_PATH
|| (process.platform === 'linux' ? 'liboxaccel.so'
: process.platform === 'darwin' ? 'liboxaccel.dylib'
: 'oxaccel.dll');
const lib = koffi.load(libPath);
// Define C types
const OxAccelConfig = koffi.struct('OxAccelConfig', {
api_key: 'str',
relay_host: 'str',
relay_port: 'uint16_t',
enable_fec: 'bool',
enable_compression: 'bool',
enable_multipath: 'bool',
});
const AccelStats = koffi.struct('AccelStats', {
packets_sent: 'uint64_t',
packets_recv: 'uint64_t',
bytes_sent: 'uint64_t',
bytes_recv: 'uint64_t',
});
// Bind functions
const ox_accel_create = lib.func('void* ox_accel_create(OxAccelConfig*)');
const ox_accel_connect = lib.func('int ox_accel_connect(void*)');
const ox_accel_send = lib.func('int ox_accel_send(void*, const uint8_t*, size_t)');
const ox_accel_recv = lib.func('int ox_accel_recv(void*, uint8_t*, size_t, size_t*)');
const ox_accel_stats = lib.func('int ox_accel_stats(void*, AccelStats*)');
const ox_accel_destroy = lib.func('void ox_accel_destroy(void*)');
const ox_accel_version = lib.func('const char* ox_accel_version()');
// Usage
console.log(`Oxidize Accel SDK v${ox_accel_version()}`);
const config = {
api_key: 'your-api-key',
relay_host: 'relay.oxd.sh',
relay_port: 51820,
enable_fec: true,
enable_compression: false,
enable_multipath: true,
};
const ctx = ox_accel_create(config);
if (!ctx) throw new Error('Failed to create context');
try {
let err = ox_accel_connect(ctx);
if (err !== 0) throw new Error(`Connect failed: ${err}`);
// Send — Buffer maps directly to uint8_t*
const payload = Buffer.from('hello world');
err = ox_accel_send(ctx, payload, payload.length);
if (err !== 0) throw new Error(`Send failed: ${err}`);
// Recv
const recvBuf = Buffer.alloc(65536);
const received = [0];
err = ox_accel_recv(ctx, recvBuf, recvBuf.length, received);
if (err === 0) console.log(`Received ${received[0]} bytes`);
const stats = {};
ox_accel_stats(ctx, stats);
console.log(`Sent: ${stats.packets_sent} pkts / ${stats.bytes_sent} bytes`);
} finally {
ox_accel_destroy(ctx);
}
Why koffi?
| Library | Compile step | Call overhead |
|---|
| koffi | None | ~100-200ns |
| ffi-napi | None | ~300-500ns |
| N-API addon | node-gyp required | ~50-100ns |
koffi is the best balance of performance and developer experience. No native compilation, fast enough for network I/O workloads.
Electron integration
For Electron apps, bundle the native library alongside your app:
import { join } from 'path';
import { app } from 'electron';
const libDir = app.isPackaged
? join(process.resourcesPath, 'native')
: join(__dirname, '..', 'native');
const lib = koffi.load(join(libDir, 'liboxaccel.so'));
Add to your package.json build config:
{
"build": {
"extraResources": [
{ "from": "native/", "to": "native/" }
]
}
}
Node.js Buffer objects map directly to uint8_t* in koffi — no intermediate copies on send. For receive, pre-allocate and reuse Buffer.alloc(65536) to avoid GC pressure.