Skip to main content

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.
npm install koffi
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?

LibraryCompile stepCall overhead
koffiNone~100-200ns
ffi-napiNone~300-500ns
N-API addonnode-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.