kcpjs

A pure JavaScript implementation of KCP (KCP Protocol) with FEC (Forward Error Correction) and encryption support.

Features

• Pure JavaScript Implementation: No native dependencies
• FEC Support: Reed-Solomon error correction
• Encryption Support: AES-GCM encryption
• TypeScript Support: Full type definitions
• High Performance: Optimized for real-time communication

Compared to node-kcp-x, this implementation adds two key features:

1. FEC (Forward Error Correction): Improves reliability over unreliable networks
2. Encryption: Secure data transmission

Installation

npm install kcpjs

Quick Start

Example 1: Echo Server

ts-node examples/echo.ts

Example 2: Client-Server Communication

# Terminal 1
ts-node examples/server.ts

# Terminal 2
ts-node examples/client.ts

API Reference

Server

ListenWithOptions(options)

Creates a KCP server listener

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | port | number | Server port | | block | CryptBlock \| undefined | Encryption module | | dataShards | number | FEC data shards | | parityShards | number | FEC parity shards | | callback | (session: Session) => void | Client connection callback |

Client

DialWithOptions(options)

Creates a KCP client connection

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | host | string | Server address | | port | number | Server port | | conv | number | Session ID | | block | CryptBlock \| undefined | Encryption module | | dataShards | number | FEC data shards | | parityShards | number | FEC parity shards |

Usage Examples

Basic Server

import { ListenWithOptions } from 'kcpjs';
import { AesBlock } from 'kcpjs/crypt';
import * as crypto from 'crypto';

// Encryption setup
const algorithm: crypto.CipherGCMTypes = 'aes-128-gcm';
const key = crypto.randomBytes(128 / 8);
const iv = crypto.randomBytes(12);

// FEC configuration
const dataShards = 4;
const parityShards = 1;

const server = ListenWithOptions({
    port: 22333,
    block: new AesBlock(algorithm, key, iv),
    dataShards,
    parityShards,
    callback: (session) => {
        console.log('New client connected');
        
        session.on('recv', (data: Buffer) => {
            // Echo back received data
            session.write(data);
        });
    },
});

Basic Client

import { DialWithOptions } from 'kcpjs';
import { AesBlock } from 'kcpjs/crypt';
import * as crypto from 'crypto';

// Same encryption setup as server
const algorithm: crypto.CipherGCMTypes = 'aes-128-gcm';
const key = crypto.randomBytes(128 / 8);
const iv = crypto.randomBytes(12);

const dataShards = 4;
const parityShards = 1;

const session = DialWithOptions({
    host: '127.0.0.1',
    port: 22333,
    conv: 255,
    block: new AesBlock(algorithm, key, iv),
    dataShards,
    parityShards,
});

session.on('recv', (data: Buffer) => {
    console.log('Received:', data.toString());
});

// Send data
setInterval(() => {
    const message = Buffer.from('Hello from client');
    session.write(message);
}, 1000);

Configuration

FEC (Forward Error Correction)

FEC helps recover lost packets without retransmission

• dataShards: Number of data shards
• parityShards: Number of parity shards
• Set either to 0 to disable FEC

Window Limits

session.setWindowSize(sndwnd, rcvwnd) controls the KCP send and receive windows. Values above IKCP_WND_SND_MAX or IKCP_WND_RCV_MAX are clamped to the exported hard limits to keep per-session memory bounded.

Encryption

Supports AES-GCM encryption

• algorithm: Cipher algorithm (e.g., 'aes-128-gcm')
• key: Encryption key
• iv: Initialization vector
• Set any parameter to empty to disable encryption

Development

Build

yarn build

Format

yarn format

Lint

yarn lint

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• kcp-go - Original KCP implementation in Go
• node-kcp-x - Basic Node.js KCP implementation