v-hono/usockets/README.md

uSockets Backend for V-Hono

High-performance server backend using uSockets library.

High Concurrency Performance

The included libusockets_full.a has been optimized with backlog=16384 to support high concurrency:

Concurrent	RPS	Success Rate
4,000	112,614	100%
6,000	56,728	100%
8,000	33,255	100%
10,000	25,964	100%

System Requirements

For 10,000+ concurrent connections:

# macOS
sudo sysctl -w kern.ipc.somaxconn=8192
ulimit -n 65535

# Linux
sudo sysctl -w net.core.somaxconn=8192
ulimit -n 65535

Performance

Based on benchmark tests (200 connections, 100K requests):

Backend	RPS	Avg Latency	P95	P99
uSockets	~22,000	8.75ms	16.66ms	25.73ms
picoev	~15,000	13.36ms	18.89ms	31.66ms

uSockets provides ~50% higher throughput under high concurrency.

Usage

import meiseayoung.hono

fn main() {
    mut app := hono.Hono.new()
    
    app.get('/', fn (mut c hono.Context) http.Response {
        return c.text('Hello from uSockets!')
    })
    
    // Use uSockets backend
    app.listen_usockets(3000)
}

Build Command

# macOS / Linux
v -enable-globals -prod -o app your_app.v
./app

# Windows (must use gcc, tcc does not support .a static library format)
v -enable-globals -cc gcc -ldflags "-ldbghelp" -o app.exe your_app.v
.\app.exe

Required flags:

• -enable-globals - Required for uSockets global state
• -cc gcc - Use GCC compiler (MinGW-w64 on Windows, required because V's default compiler tcc does not support MinGW .a static library format)
• -ldflags "-ldbghelp" - Required on Windows for libuv linking

Prerequisites (Windows)

To use uSockets backend on Windows, you need:

1. GCC (MinGW-w64) - C compiler (required, tcc is not supported)

   # Install via Scoop (recommended)
   scoop install mingw
   
   # Or via Chocolatey
   choco install mingw
   
   # Or download w64devkit from: https://github.com/skeeto/w64devkit/releases
   

2. V Compiler - Version 0.4.x or later

   # Install via Scoop
   scoop install vlang
   
   # Or download from: https://vlang.io/
   

3. Verify Installation

   gcc --version   # Should show MinGW-w64 GCC
   v version       # Should show V 0.4.x
   

Pre-compiled Libraries

The uSockets library and libuv are pre-compiled and included in the lib/{platform}/ directory:

• lib/windows/ - Windows x64
• lib/linux/ - Linux x64
• lib/macos-arm64/ - macOS Apple Silicon
• lib/macos-x64/ - macOS Intel

Directory Structure

usockets/
├── include/           # Header files
│   ├── libusockets.h  # uSockets API
│   ├── uv.h           # libuv API
│   └── uv/            # libuv headers
├── lib/               # Pre-compiled libraries
│   ├── windows/       # Windows x64
│   ├── linux/         # Linux x64
│   ├── macos-arm64/   # macOS Apple Silicon
│   └── macos-x64/     # macOS Intel
├── src/               # Modified source files
│   └── bsd.c          # Modified with backlog=16384
├── build.sh           # Build script
├── usockets.v         # V bindings
└── README.md          # This file

Configuration

// Custom configuration
app.listen_usockets_with_config(meiseayoung.hono.UsocketsConfig{
    port: 8080
    host: '0.0.0.0'
    keepalive_timeout: 30
    max_keepalive_req: 10000
})

Building uSockets Library from Source

If you need to rebuild the uSockets library (e.g., for a different platform or custom modifications), use the provided build script.

Build Prerequisites

• Git - For cloning source repositories
• GCC - C compiler
• CMake - For building libuv
• ar - Archive tool (included with GCC)

Installing Prerequisites

macOS:

xcode-select --install
brew install cmake

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install build-essential cmake git

Linux (CentOS/RHEL):

sudo yum groupinstall "Development Tools"
sudo yum install cmake git

Windows (Git Bash/MSYS2):

# Install via Scoop
scoop install mingw cmake git

# Or via Chocolatey
choco install mingw cmake git

Running the Build Script

cd usockets
chmod +x build.sh
./build.sh

The script will:

1. Clone uSockets and libuv repositories to /tmp/
2. Apply the backlog=16384 modification for high concurrency
3. Compile libuv as a static library
4. Compile uSockets with libuv support
5. Merge both libraries into libusockets_full.a
6. Output to the appropriate lib/{platform}/ directory

Build Script Details

The build script (build.sh) automatically:

• Detects your operating system (Windows/macOS/Linux)
• Detects CPU architecture (x64/arm64 on macOS)
• Applies the backlog modification from src/bsd.c
• Compiles with optimizations (-O3)
• Creates a merged static library containing both uSockets and libuv

Custom Modifications

To customize the build:

1. Change backlog size: Edit src/bsd.c and modify the listen() call
2. Enable SSL: Remove -DLIBUS_NO_SSL from the build script and link OpenSSL
3. Use different event loop: Modify -DLIBUS_USE_LIBUV flag

Troubleshooting Build Issues

CMake not found:

# macOS
brew install cmake

# Linux
sudo apt install cmake  # or sudo yum install cmake

# Windows
scoop install cmake

GCC not found (Windows):

scoop install mingw
# Make sure MinGW bin directory is in PATH

Permission denied:

chmod +x build.sh

Notes

• On Windows, uSockets and picoev have similar performance
• On Linux, uSockets may have greater advantages due to epoll optimization
• uSockets excels under high concurrency (200+ connections)