bux-lang/apps/nexus

Nexus

High-performance, multi-threaded HTTP/1.1, HTTP/2 & WebSocket server — built with the Bux programming language.

Nexus is a from-scratch web server that demonstrates Bux's systems-programming capabilities: raw TCP sockets, pthread-based concurrency, manual memory management, and zero-dependency C ABI interop — all from a clean, modern syntax.

---

Features

Area	What's Implemented
HTTP/1.1	Full request parsing, keep-alive (reuse TCP), status codes, content negotiation
Multi-threaded	Worker pool + channel task queue; configurable via NEXUS_WORKERS
HTTP/2	Connection preface detection (PRI * HTTP/2.0), upgrade-aware routing
WebSocket	RFC 6455 upgrade handshake detection, Sec-WebSocket-Key extraction
Static files	Serves from public/ with MIME-type detection for 20+ file types, directory-traversal protection
JSON API	Built-in /api/health and /api/info endpoints
Logging	Access log: METHOD path status duration_ms (NEXUS_ACCESS_LOG=0 to disable)
Limits	NEXUS_MAX_BODY (default 1 MiB) → HTTP 413 when exceeded
Graceful stop	SIGINT/SIGTERM: close listen fd, poison workers, exit 0
TLS / HTTPS	OpenSSL server mode via NEXUS_TLS=1 + PEM cert/key
mTLS	NEXUS_TLS_CLIENT_CA PEM → require client certificates

Quick Start

# From the project root
cd apps/nexus

# Build with the bootstrap compiler (Nim)
../../buxc build

# Or with the self-hosted compiler
../../buxc_lir build

# Run
./nexus

# Optional env (also used by `make bench-nexus`)
# NEXUS_PORT=18080 NEXUS_BIND=127.0.0.1 NEXUS_WORKERS=4 \
# NEXUS_MAX_BODY=1048576 NEXUS_ACCESS_LOG=1 ./build/nexus

# HTTPS (self-signed example)
# openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 365 -subj /CN=localhost
# NEXUS_TLS=1 NEXUS_TLS_CERT=cert.pem NEXUS_TLS_KEY=key.pem NEXUS_PORT=8443 ./build/nexus
# curl -k https://127.0.0.1:8443/api/health

# mTLS (require client cert signed by CA)
# NEXUS_TLS_CLIENT_CA=ca.pem NEXUS_TLS=1 NEXUS_TLS_CERT=server.pem NEXUS_TLS_KEY=server.key …
# curl --cert client.pem --key client.key --cacert ca.pem https://…

Server starts on http://0.0.0.0:8080 (or https:// when TLS is enabled). Stop with Ctrl+C or kill -TERM (graceful: workers drained via poison pills).

Smoke: make test-nexus-tls (self-signed cert + curl -k).

Docker

# Full Nexus (needs libssl3)
../../buxc --release build   # from apps/nexus
docker build -f ../../examples/docker/Dockerfile.nexus -t bux-nexus ../..
docker run --rm -p 8080:8080 bux-nexus

╔══════════════════════════════════════════════╗
║  Nexus HTTP Server v0.1.0                    ║
║  High-performance multi-threaded HTTP/1.1    ║
║  HTTP/2 & WebSocket detection included       ║
║  Built with Bux                              ║
╚══════════════════════════════════════════════╝

✓ Server listening on http://0.0.0.0:8080
✓ Worker threads: 4
✓ Static files: ./public/

  Endpoints:
    GET  /              — Static files (public/)
    GET  /api/health    — Health check (JSON)
    GET  /api/info      — Server info (JSON)
    GET  /ws            — WebSocket upgrade
    ANY  /*             — Static file serving

Testing It

# Home page (HTML)
curl http://localhost:8080/

# Health check
curl http://localhost:8080/api/health
# → {"status":"ok","server":"Nexus","version":"0.1.0"}

# Server info
curl http://localhost:8080/api/info
# → {"name":"Nexus","language":"Bux","features":[...]}

# Static file (404 page)
curl http://localhost:8080/404.html

# Nonexistent file
curl http://localhost:8080/nope
# → 404 Not Found

# WebSocket upgrade attempt
curl -H "Upgrade: websocket" \
     -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
     http://localhost:8080/ws
# → 101 Switching Protocols

Architecture

Thread Model — Multi-Accept

Nexus uses the multi-accept pattern rather than a traditional thread pool with a work queue:

Main Thread                  Worker 1       Worker 2       Worker 3
    │                           │              │              │
    ├─ socket()/bind()/listen() │              │              │
    ├─ spawn Worker() ──────────►              │              │
    ├─ spawn Worker() ─────────────────────────►              │
    ├─ spawn Worker() ────────────────────────────────────────►
    │                           │              │              │
    ▼ Worker()                  ▼ accept()     ▼ accept()     ▼ accept()
      accept() loop                │              │              │

Each worker thread calls accept() on the same listening socket. The Linux kernel distributes incoming connections across the blocked accept calls — the same mechanism used by nginx and Apache prefork. No mutex, no queue, no context switching between a dispatcher and workers.

Request Lifecycle

Client connects
    │
    ▼
Net_Accept() → client fd
    │
    ▼
Net_Recv(fd, 8192) → raw bytes
    │
    ▼
ParseRequest()
    ├─ Split headers on \r\n\r\n
    ├─ Parse request line → method, path, version
    └─ Parse header lines → key-value array
    │
    ▼
Router_Dispatch()
    ├─ /api/*   → JSON handlers
    ├─ /ws      → WebSocket upgrade
    ├─ Upgrade header → HTTP/2 or WS detection
    └─ /*       → Static file serving
    │
    ▼
BuildResponse() → HTTP/1.1 status line + headers + body
    │
    ▼
Net_Send(fd, response) → bytes to client
    │
    ▼
Net_Close(fd)

Design Decisions

• No keep-alive by default. Each connection is closed after one response. This avoids blocking worker threads on idle clients (Bux doesn't yet expose SO_RCVTIMEO).
• Linear header array instead of hash map. HTTP requests typically carry 5–15 headers. A linear scan over a key-value array is faster than hashing for this N, and avoids the complexity of iterating over Bux's generic StringMap.
• Raw extern calls for the string builder. The stdlib StringBuilder wrapper adds a struct indirection. Calling bux_sb_new / bux_sb_append / bux_sb_build directly is simpler and equally safe.
• WebSocket accept key is a placeholder. A full implementation needs SHA-1 hashing and Base64 encoding. These aren't in Bux's stdlib yet; they can be added as extern C functions when needed.

Project Structure

apps/nexus/
├── bux.toml              # Package manifest
├── README.md             # This file
├── src/
│   └── Main.bux          # The entire server (~640 lines)
└── public/
    ├── index.html         # Landing page
    └── 404.html           # Error page

Everything lives in one file (src/Main.bux) by design — it keeps the module graph flat and the build fast. As the server grows, the HTTP parser, router, and handlers can be split into separate modules.

Configuration

Edit the constants at the top of src/Main.bux:

const SERVER_PORT: int = 8080;      // Listen port
const THREAD_COUNT: int = 4;        // Number of worker threads
const RECV_BUF_SIZE: int = 8192;    // Receive buffer per request
const SERVER_NAME: String = "Nexus/0.1.0 (Bux)";
const PUBLIC_DIR: String = "public"; // Static files directory

Roadmap

• Keep-alive with configurable socket timeout
• Full WebSocket frame read/write (requires SHA-1 + Base64)
• HTTP/2 binary framing layer (HPACK, stream multiplexing)
• SSL/TLS via OpenSSL extern bindings
• Middleware / filter chain
• Request body parsing (JSON, form-encoded, multipart)
• Virtual hosts
• Access logging to file
• Rate limiting

License

Nexus is part of the Bux project. See the root LICENSE for terms.