powpow

PowPow 💥 A high-performance event notification library for Nim

nimble install powpow

API reference

😍 Key Features

• High-performance, event-driven networking library for Nim
• Support for low-level UDP, TCP sockets
• Built-in HTTP/1.1 server implementation
• Built-in WebSocket client and server: standalone + HTTP-upgrade modes, wss:// on both ends, subprotocol negotiation, custom handshake headers, keepalive pings/idle timeouts, and a self-managed client (newWsClient) with auto-reconnect and a sendMessage API
• Threadpool (import powpow/threadpool): a self-managed worker pool on raw threads with a private event loop for result delivery; submit CPU-bound or blocking work off a live event loop without blocking any single thread
• TLS/SSL support (implicit + STARTTLS-style upgrades)
• DTLS 1.2 over UDP — one socket, per-peer sessions, stateless cookie exchange
• Signal/Relay system for in-process event dispatch
• Built-in rate limiting per client IP with multi-window support (e.g. hourly + daily quotas checked atomically via newMultiRateLimiter)
• HTTP over Unix Domain Sockets (UDS) support for super fast local IPC
• Zero-copy file transmission using sendfile (Unix) and TransmitFile (Windows)
• Chunked Request Body support for streaming uploads and large payloads
• Memory-efficient Multipart Form Data parsing and Raw Body handling for file uploads
• SIMD-accelerated parsing and formatting of HTTP messages
• Built on top of epoll (Linux), and kqueue (BSD, macOS), IOCP (Windows)
• Opt-in Linux io_uring backend (submission-based, --features:io_uring) with zero-copy send_zc sends, SPLICE file transfers, registered buffers and a full io_uring API binding — documentation
• Support for edge-triggered and level-triggered event notification
• Support for multiple event loops and multi-threaded applications
• Support for MIME type detection based on file extensions
• FileSystem Monitoring via inotify (Linux) and kqueue (BSD, macOS) (Windows - not yet implemented)

[!NOTE] 💥 PowPow is now available in Supranim as a backend. Just switch --features:powpow when compiling your Supranim app!

[!WARNING] 💥 This library is not production-ready and may contain bugs and security vulnerabilities. It has been tested on Linux and macOS, but may not work on all platforms. Use it, test it, and do not hesitate to report any issues you find! 💥

[!NOTE] io_uring expectations. On plain HTTP/1.x, request/response cycles over TCP are serialized per connection, so io_uring doesn't dramatically outpace epoll on a single-connection benchmark — it's a way to reach parity with headroom as concurrency scales and for zero-copy file serving. See the performance docs for details and where HTTP/2/QUIC will make its parallelism count.

📚 Documentation

The full documentation lives in docs/:

• Overview — architecture and the complete feature matrix
• Getting started — install and your first server
• Event loop, TCP, HTTP server, WebSocket and more — per-feature guides
• Threadpool: offloading CPU-bound work off a live event loop
• io_uring — the opt-in Linux submission-based backend
• Examples index — every runnable example, its port and commands
• API reference — per-module signatures (plus the generated reference)
• Performance, Security, Testing

Security

Need to take input validation and DoS-resistance seriously. A dedicated security audit was performed; the high-priority findings it produced are fixed and covered by regression tests in tests/test_security.nim.

Recommended production configuration

For publicly reachable endpoints, set explicit caps instead of relying on the defaults (the maxBodySize = 0 backstop is MaxStreamBodySize:

let server = newHttpServer(loop)
server.maxBodySize    = 50 * 1024 * 1024      # 50 MB total request body
server.maxStreamBodySize = 64 * 1024 * 1024   # hard cap even when maxBodySize=0
server.maxFileSize    = 10 * 1024 * 1024      # 10 MB per uploaded file
server.maxFieldSize   = 64 * 1024             # 64 KB per text field
server.maxConnections = 4096                  # cap concurrent connections
server.maxPipelineDepth = 4                   # cap pipelined requests
server.readTimeoutMs  = 5_000                 # slowloris / partial-request close
server.setKeepAliveTimeout(5_000)             # idle keep-alive close

The same caps apply to the standalone WsServer via maxFrameSize, handshakeTimeoutMs, maxHandshakeSessions, and (once enabled) a post-upgrade idleTimeoutMs.

Smuggler is a grammar-based HTTP/1.x request-smuggling fuzzer built for this library: it generates and mutates requests from a context-free grammar, detects CL/TE desyncs with an in-process oracle, and drives live servers with the two-request response-pairing technique.

Threadpool

Use the threadpool when you have CPU-bound or blocking work that must not stall an event loop. It creates N persistent worker threads plus one dispatch thread running a private event loop. Job results are delivered as callbacks serialized on that dispatch thread, so no user-side locking is needed.

import powpow/threadpool

let tp = newThreadPool(size = 4)

discard tp.submitWork(
  job = proc(): string = readFile("big.bin"),
  cb  = proc(data: string) = echo "read ", data.len, " bytes")

closeThreadPool(tp)   # drain queued jobs, then tear down

shutdownThreadPool(tp) discards queued-but-unstarted jobs for fast teardown; in-flight jobs still finish and deliver. Both are idempotent.

Unlike std/threadpool (deprecated), taskpools or malebolgia, powpow's threadpool never blocks the calling thread, making it safe inside event-driven services. Work-stealing forks like weave or taskpools still win for numeric crunching; powpow's pool optimizes for service workloads where results must flow back into an event loop. See the concurrency guide for the full comparison.

Examples (the fun part)

Most web servers out there are all rainbows and flowers, until you upload or stream a file, and it transforms into a nightmare at runtime. PowPow is slowly moving toward a production-ready server. Everything below is runnable and lives in the examples/ directory.

Dummy Benchmarks

Pow Pow is the #1 fastest HTTP server from Web Framework Benchmarks. Find the wrk-based benchmark I manually ran via Github Actions (see bench.yml)

• Single-threaded (keep-alive)

💥 powpow HTTP server listening on http://localhost:9000
  Press Ctrl+C to stop
Running 5s test @ http://127.0.0.1:9000/
  4 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.02ms   61.67us   3.25ms   81.86%
    Req/Sec    24.63k   818.23    26.67k    68.00%
  489946 requests in 5.00s, 277.55MB read
Requests/sec:  97965.24
Transfer/sec:     55.50MB

• Single-threaded (connection close)

💥 powpow HTTP server listening on http://localhost:9000
  Press Ctrl+C to stop
Running 5s test @ http://127.0.0.1:9000/
  4 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.97ms  202.12us   4.22ms   80.09%
    Req/Sec     9.13k     3.62k   18.16k    71.43%
  184469 requests in 5.10s, 103.62MB read
Requests/sec:  36174.22
Transfer/sec:     20.32MB

• Multi-threaded (keep-alive)

  worker #0 ready
  worker #2 ready
💥 powpow accepting on 0.0.0.0:9000 with 4 workers (SO_REUSEPORT)
  worker #1 ready
  worker #3 ready
Running 5s test @ http://127.0.0.1:9000/
  4 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   786.79us    1.11ms  11.73ms   84.24%
    Req/Sec    50.98k     3.97k   86.53k    91.50%
  1018820 requests in 5.03s, 526.62MB read
Requests/sec: 202743.27
Transfer/sec:    104.80MB

• Multi-threaded (connection close)

  worker #0 ready
  worker #2 ready
💥 powpow accepting on 0.0.0.0:9000 with 4 workers (SO_REUSEPORT)
  worker #3 ready
  worker #1 ready
Running 5s test @ http://127.0.0.1:9000/
  4 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.31ms    0.95ms  15.44ms   67.66%
    Req/Sec    13.24k   614.80    14.91k    81.50%
  264133 requests in 5.01s, 135.27MB read
Requests/sec:  52687.29
Transfer/sec:     26.98MB

• Event loop concurrency (macOS kqueue, release build)

Capacity scaling:

Head-of-line blocking (1024 fast + 64 slow at 200µs):

Security roadmap

• [ ] Coverage-guided fuzzing of the HTTP / WebSocket / multipart parsers (libFuzzer & nim-drchaos adapters in smuggler)
• [ ] ASan/UBSan sanitizer build wired into CI
• [ ] Stream body bytes before first-packet buffering (avoid peak RAM on large single-packet uploads)
• [x] Multipart per-file size limits wired to server configuration
• [x] Symlink-safe static serving (realpath checks)
• [x] WebSocket handshake timeout and handshake-session bound
• [x] Rate-limiter thread-safety in multi-threaded mode
• [x] Strict header parsing (reject obs-fold/leading-whitespace header lines, non-chunked Transfer-Encoding tokens)
• [x] Response-reflection guards for large attacker-controlled echoes under TLS

❤ Contributions & Support

• 🐛 Found a bug? Create a new Issue
• 👋 Wanna help? Fork it!

	Switch to Open-Source LLMs via OpenCode GO, choosing from a variety of powerful models such as DeepSeek, Qwen, Kimi, GLM-5, MiniMax, MiMo. 🍕 Use our referral link to get started!

🎩 License

MIT license. Made by Humans from OpenPeeps.
Copyright OpenPeeps & Contributors — All rights reserved.