Files

Juergen Kunz aec545fe8c feat(readme): document QoS, telemetry, MTU, and rate limiting capabilities in the README

2026-03-15 18:16:15 +00:00

18 KiB

Raw Blame History

@push.rocks/smartvpn

A high-performance VPN with a TypeScript control plane and a Rust data plane daemon. Manage VPN connections with clean, fully-typed APIs while all networking heavy lifting — encryption, tunneling, QoS, rate limiting — runs at native speed in Rust.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm install @push.rocks/smartvpn

🏗️ Architecture

TypeScript (control plane)              Rust (data plane)
┌──────────────────────────┐            ┌────────────────────────────────────┐
│ VpnClient / VpnServer    │            │ smartvpn_daemon                     │
│   └─ VpnBridge           │──stdio/──▶ │  ├─ management (JSON IPC)          │
│      └─ RustBridge       │  socket    │  ├─ transport (WebSocket/TLS)      │
│         (smartrust)      │            │  ├─ crypto (Noise NK + XCha20)     │
└──────────────────────────┘            │  ├─ codec (binary framing)         │
                                        │  ├─ keepalive (adaptive state FSM) │
                                        │  ├─ telemetry (RTT/jitter/loss)    │
                                        │  ├─ qos (classify + priority Q)    │
                                        │  ├─ ratelimit (token bucket)       │
                                        │  ├─ mtu (overhead calc + ICMP)     │
                                        │  ├─ tunnel (TUN device)            │
                                        │  ├─ network (NAT/IP pool)          │
                                        │  └─ reconnect (exp. backoff)       │
                                        └────────────────────────────────────┘

Key design decisions:

Decision	Choice	Why
Transport	WebSocket over HTTPS	Works through Cloudflare and other terminating proxies
Encryption	Noise NK + XChaCha20-Poly1305	Strong forward secrecy, large nonce space (no counter needed)
Keepalive	Adaptive app-level pings	Cloudflare drops WS pings; interval adapts to link health (10–60s)
QoS	Packet classification + priority queues	DNS/SSH/ICMP always drain first; bulk flows get deprioritized
Rate limiting	Per-client token bucket	Byte-granular, dynamically reconfigurable via IPC
IPC	JSON lines over stdio / Unix socket	`stdio` for dev, `socket` for production (daemon stays alive)
Binary protocol	`[type:1B][length:4B][payload:NB]`	Minimal overhead, easy to parse at wire speed

🚀 Quick Start

VPN Client

import { VpnClient } from '@push.rocks/smartvpn';

const client = new VpnClient({
  transport: { transport: 'stdio' },
});

await client.start();

const { assignedIp } = await client.connect({
  serverUrl: 'wss://vpn.example.com/tunnel',
  serverPublicKey: 'BASE64_SERVER_PUBLIC_KEY',
  dns: ['1.1.1.1', '8.8.8.8'],
  mtu: 1420,
  keepaliveIntervalSecs: 30,
});

console.log(`Connected! Assigned IP: ${assignedIp}`);

// Connection quality (adaptive keepalive + telemetry)
const quality = await client.getConnectionQuality();
console.log(quality);
// {
//   srttMs: 42.5, jitterMs: 3.2, minRttMs: 38.0, maxRttMs: 67.0,
//   lossRatio: 0.0, consecutiveTimeouts: 0,
//   linkHealth: 'healthy', currentKeepaliveIntervalSecs: 60
// }

// MTU info
const mtu = await client.getMtuInfo();
console.log(mtu);
// { tunMtu: 1420, effectiveMtu: 1421, linkMtu: 1500, overheadBytes: 79, ... }

// Traffic stats (includes quality snapshot)
const stats = await client.getStatistics();

await client.disconnect();
client.stop();

VPN Server

import { VpnServer } from '@push.rocks/smartvpn';

const server = new VpnServer({
  transport: { transport: 'stdio' },
});

// Generate a Noise keypair first
await server.start();
// If you don't have keys yet:
const keypair = await server.generateKeypair();

// Start the VPN listener (or pass config to start() directly)
await server.start({
  listenAddr: '0.0.0.0:443',
  privateKey: keypair.privateKey,
  publicKey: keypair.publicKey,
  subnet: '10.8.0.0/24',
  dns: ['1.1.1.1'],
  mtu: 1420,
  enableNat: true,
  // Optional: default rate limit for all new clients
  defaultRateLimitBytesPerSec: 10_000_000, // 10 MB/s
  defaultBurstBytes: 20_000_000,           // 20 MB burst
});

// List connected clients
const clients = await server.listClients();

// Per-client rate limiting (live, no reconnect needed)
await server.setClientRateLimit('client-id', 5_000_000, 10_000_000);
await server.removeClientRateLimit('client-id'); // unlimited

// Per-client telemetry
const telemetry = await server.getClientTelemetry('client-id');
console.log(telemetry);
// {
//   clientId, assignedIp, lastKeepaliveAt, keepalivesReceived,
//   packetsDropped, bytesDropped, bytesReceived, bytesSent,
//   rateLimitBytesPerSec, burstBytes
// }

// Kick a client
await server.disconnectClient('client-id');

await server.stopServer();
server.stop();

Production: Socket Transport

In production, the daemon runs as a system service and you connect over a Unix socket:

const client = new VpnClient({
  transport: {
    transport: 'socket',
    socketPath: '/var/run/smartvpn.sock',
    autoReconnect: true,
    reconnectBaseDelayMs: 100,
    reconnectMaxDelayMs: 30000,
    maxReconnectAttempts: 10,
  },
});

await client.start(); // connects to existing daemon (does not spawn)

When using socket transport, client.stop() closes the socket but does not kill the daemon — exactly what you want in production.

📋 API Reference

`VpnClient`

Method	Returns	Description
`start()`	`Promise<boolean>`	Start the daemon bridge (spawn or connect)
`connect(config?)`	`Promise<{ assignedIp }>`	Connect to VPN server
`disconnect()`	`Promise<void>`	Disconnect from VPN
`getStatus()`	`Promise<IVpnStatus>`	Current connection state
`getStatistics()`	`Promise<IVpnStatistics>`	Traffic stats + connection quality
`getConnectionQuality()`	`Promise<IVpnConnectionQuality>`	RTT, jitter, loss, link health
`getMtuInfo()`	`Promise<IVpnMtuInfo>`	MTU info and overhead breakdown
`stop()`	`void`	Kill/close the daemon bridge
`running`	`boolean`	Whether bridge is active

`VpnServer`

Method	Returns	Description
`start(config?)`	`Promise<void>`	Start daemon + VPN server
`stopServer()`	`Promise<void>`	Stop the VPN server
`getStatus()`	`Promise<IVpnStatus>`	Server connection state
`getStatistics()`	`Promise<IVpnServerStatistics>`	Server stats (includes client counts)
`listClients()`	`Promise<IVpnClientInfo[]>`	Connected clients with QoS stats
`disconnectClient(id)`	`Promise<void>`	Kick a client
`generateKeypair()`	`Promise<IVpnKeypair>`	Generate Noise NK keypair
`setClientRateLimit(id, rate, burst)`	`Promise<void>`	Set per-client rate limit (bytes/sec)
`removeClientRateLimit(id)`	`Promise<void>`	Remove rate limit (unlimited)
`getClientTelemetry(id)`	`Promise<IVpnClientTelemetry>`	Per-client telemetry + drop stats
`stop()`	`void`	Kill/close the daemon bridge

`VpnConfig`

Static utility class for config validation and file I/O:

import { VpnConfig } from '@push.rocks/smartvpn';

// Validate (throws on invalid)
VpnConfig.validateClientConfig(config);
VpnConfig.validateServerConfig(config);

// Load/save JSON configs
const config = await VpnConfig.loadFromFile<IVpnClientConfig>('/etc/smartvpn/client.json');
await VpnConfig.saveToFile('/etc/smartvpn/client.json', config);

`VpnInstaller`

Generate system service units for the daemon:

import { VpnInstaller } from '@push.rocks/smartvpn';

const platform = VpnInstaller.detectPlatform(); // 'linux' | 'macos' | 'windows' | 'unknown'

// Linux (systemd)
const unit = VpnInstaller.generateSystemdUnit({
  binaryPath: '/usr/local/bin/smartvpn_daemon',
  socketPath: '/var/run/smartvpn.sock',
  mode: 'server',
});

// macOS (launchd)
const plist = VpnInstaller.generateLaunchdPlist({
  binaryPath: '/usr/local/bin/smartvpn_daemon',
  socketPath: '/var/run/smartvpn.sock',
  mode: 'client',
});

// Auto-detect platform
const serviceUnit = VpnInstaller.generateServiceUnit({
  binaryPath: '/usr/local/bin/smartvpn_daemon',
  socketPath: '/var/run/smartvpn.sock',
  mode: 'server',
});

Events

Both VpnClient and VpnServer extend EventEmitter:

client.on('exit', ({ code, signal }) => { /* daemon exited */ });
client.on('reconnected', () => { /* socket reconnected */ });

server.on('client-connected', (info) => { /* IVpnClientInfo */ });
server.on('client-disconnected', ({ clientId, reason }) => { /* ... */ });

📊 QoS System

The Rust daemon includes a full QoS stack that operates on decrypted IP packets:

Adaptive Keepalive

The keepalive system automatically adjusts its interval based on connection quality:

Link Health	Keepalive Interval	Triggered When
🟢 Healthy	60s	Jitter < 30ms, loss < 2%, no timeouts
🟡 Degraded	30s	Jitter > 50ms, loss > 5%, or 1+ timeout
🔴 Critical	10s	Loss > 20% or 2+ consecutive timeouts

State transitions include hysteresis (3 consecutive good checks to upgrade, 2 to recover) to prevent flapping. Dead peer detection fires after 3 consecutive timeouts in Critical state.

Packet Classification

IP packets are classified into three priority levels by inspecting headers (no deep packet inspection):

Priority	Traffic
High	ICMP, DNS (port 53), SSH (port 22), small packets (< 128 bytes)
Normal	Everything else
Low	Bulk flows exceeding 1 MB within a 60s window

Priority channels drain with biased tokio::select! — high-priority packets always go first.

Smart Packet Dropping

Under backpressure, packets are dropped intelligently:

Low queue full → drop silently
Normal queue full → drop
High queue full → wait 5ms, then drop as last resort

Drop statistics are tracked per priority level and exposed via telemetry.

Per-Client Rate Limiting

Token bucket algorithm with byte granularity:

// Set: 10 MB/s sustained, 20 MB burst
await server.setClientRateLimit('client-id', 10_000_000, 20_000_000);

// Check drops via telemetry
const t = await server.getClientTelemetry('client-id');
console.log(`Dropped: ${t.packetsDropped} packets, ${t.bytesDropped} bytes`);

// Remove limit
await server.removeClientRateLimit('client-id');

Rate limits can be changed live without disconnecting the client.

Path MTU

Tunnel overhead is calculated precisely:

Layer	Bytes
IP header	20
TCP header (with timestamps)	32
WebSocket framing	6
VPN frame header	5
Noise AEAD tag	16
Total overhead	79

For a standard 1500-byte Ethernet link, effective TUN MTU = 1421 bytes. The default TUN MTU of 1420 is conservative and correct. Oversized packets get an ICMP "Fragmentation Needed" (Type 3, Code 4) written back into the TUN, so the source TCP adjusts its MSS automatically.

🔐 Security Model

The VPN uses a Noise NK handshake pattern:

NK = client does Not authenticate, but Knows the server's static public key
The client generates an ephemeral keypair, performs e, es (DH with server's static key)
Server responds with e, ee (DH with both ephemeral keys)
Result: forward-secret transport keys derived from both DH operations

Post-handshake, all IP packets are encrypted with XChaCha20-Poly1305:

24-byte random nonces (no counter synchronization needed)
16-byte authentication tags
Wire format: [nonce:24B][ciphertext:var][tag:16B]

📦 Binary Protocol

Inside the WebSocket tunnel, packets use a simple binary framing:

┌──────────┬──────────┬────────────────────┐
│ Type (1B)│ Len (4B) │ Payload (variable) │
└──────────┴──────────┴────────────────────┘

Type	Value	Description
`HandshakeInit`	`0x01`	Client → Server handshake
`HandshakeResp`	`0x02`	Server → Client handshake
`IpPacket`	`0x10`	Encrypted IP packet
`Keepalive`	`0x20`	App-level ping (8-byte timestamp payload)
`KeepaliveAck`	`0x21`	App-level pong (echoes timestamp for RTT)
`SessionResume`	`0x30`	Resume a dropped session
`SessionResumeOk`	`0x31`	Resume accepted
`SessionResumeErr`	`0x32`	Resume rejected
`Disconnect`	`0x3F`	Graceful disconnect

🛠️ Rust Daemon CLI

# Development: stdio management (JSON lines on stdin/stdout)
smartvpn_daemon --management --mode client
smartvpn_daemon --management --mode server

# Production: Unix socket management
smartvpn_daemon --management-socket /var/run/smartvpn.sock --mode server

# Generate a Noise keypair
smartvpn_daemon --generate-keypair

🔧 Building from Source

# Install dependencies
pnpm install

# Build TypeScript + cross-compile Rust (amd64 + arm64)
pnpm build

# Build Rust only (debug)
cd rust && cargo build

# Run all tests (71 Rust + 32 TypeScript)
cd rust && cargo test
pnpm test

TypeScript Interfaces

Click to expand full type definitions

// Transport options
type TVpnTransportOptions =
  | { transport: 'stdio' }
  | {
      transport: 'socket';
      socketPath: string;
      autoReconnect?: boolean;
      reconnectBaseDelayMs?: number;
      reconnectMaxDelayMs?: number;
      maxReconnectAttempts?: number;
    };

// Client config
interface IVpnClientConfig {
  serverUrl: string;
  serverPublicKey: string;
  dns?: string[];
  mtu?: number;
  keepaliveIntervalSecs?: number;
}

// Server config
interface IVpnServerConfig {
  listenAddr: string;
  privateKey: string;
  publicKey: string;
  subnet: string;
  tlsCert?: string;
  tlsKey?: string;
  dns?: string[];
  mtu?: number;
  keepaliveIntervalSecs?: number;
  enableNat?: boolean;
  defaultRateLimitBytesPerSec?: number;
  defaultBurstBytes?: number;
}

// Status
type TVpnConnectionState = 'disconnected' | 'connecting' | 'handshaking'
                         | 'connected' | 'reconnecting' | 'error';

interface IVpnStatus {
  state: TVpnConnectionState;
  assignedIp?: string;
  serverAddr?: string;
  connectedSince?: string;
  lastError?: string;
}

// Statistics
interface IVpnStatistics {
  bytesSent: number;
  bytesReceived: number;
  packetsSent: number;
  packetsReceived: number;
  keepalivesSent: number;
  keepalivesReceived: number;
  uptimeSeconds: number;
  quality?: IVpnConnectionQuality;
}

interface IVpnServerStatistics extends IVpnStatistics {
  activeClients: number;
  totalConnections: number;
}

// Connection quality (QoS)
type TVpnLinkHealth = 'healthy' | 'degraded' | 'critical';

interface IVpnConnectionQuality {
  srttMs: number;
  jitterMs: number;
  minRttMs: number;
  maxRttMs: number;
  lossRatio: number;
  consecutiveTimeouts: number;
  linkHealth: TVpnLinkHealth;
  currentKeepaliveIntervalSecs: number;
}

// MTU info
interface IVpnMtuInfo {
  tunMtu: number;
  effectiveMtu: number;
  linkMtu: number;
  overheadBytes: number;
  oversizedPacketsDropped: number;
  icmpTooBigSent: number;
}

// Client info (with QoS fields)
interface IVpnClientInfo {
  clientId: string;
  assignedIp: string;
  connectedSince: string;
  bytesSent: number;
  bytesReceived: number;
  packetsDropped: number;
  bytesDropped: number;
  lastKeepaliveAt?: string;
  keepalivesReceived: number;
  rateLimitBytesPerSec?: number;
  burstBytes?: number;
}

// Per-client telemetry
interface IVpnClientTelemetry {
  clientId: string;
  assignedIp: string;
  lastKeepaliveAt?: string;
  keepalivesReceived: number;
  packetsDropped: number;
  bytesDropped: number;
  bytesReceived: number;
  bytesSent: number;
  rateLimitBytesPerSec?: number;
  burstBytes?: number;
}

interface IVpnKeypair {
  publicKey: string;
  privateKey: string;
}

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

18 KiB Raw Blame History Unescape Escape