derrick-torkornoo/uws-boost · v1.0.0

uws-akwaaba

Project type: TypeScript library, published as an npm package that you import into your own uWebSockets.js server. Runnable example servers live in examples/.

A lightweight, dependency-free web framework and toolkit for building HTTP APIs on uWebSockets.js:

• a router with Koa-style middleware, params, typed query access and central error handling
• response helpers (json, text, html, send, redirect, empty, error) with compression and ETags
• body readers for JSON (with schema validation), text, urlencoded and raw bytes, readable even after await
• a streaming multipart/form-data parser (memory, disk or spill-over) with size, count and type limits
• static files with ETag/304, byte ranges, HEAD and backpressure-aware streaming
• authentication (bearer, API key, session + CSRF, roles and scopes), rate limiting, CSRF middleware
• CORS, cookies (including HMAC-signed values), security headers
• request ids and structured access logs, graceful shutdown, JSON WebSockets
• typed HTTP errors that map straight to responses

uWS is fast because it is low-level: the request object dies as soon as your handler returns or awaits, the body is lost unless you subscribe to it immediately, aborted responses must never be written, and the status line must come before every header. This library handles those rules for you, and its test suite checks them against a real uWS server.

Install

npm install uws-akwaaba uNetworking/uWebSockets.js#v20.52.0

uWebSockets.js is a peer dependency. Node.js 20 or newer is required (uWebSockets.js v20.52 ships no Node 18 binary). uWebSockets.js ships glibc builds only, so Alpine (musl) based environments are not supported.

Quick start

import uWS from "uWebSockets.js";
import pino from "pino";
import { createRouter, authenticate, bearerAuth, readJson, HttpError, structuredLogger } from "uws-akwaaba";

const app = uWS.App();
const logger = pino();
const api = createRouter(app, {
  prefix: "/api",
  compress: true,
  // one JSON line per request: id, method, url, status, durationMs, bytes
  requestLog: { log: structuredLogger(logger) },
  // unexpected errors (not 4xx HttpErrors), e.g. for Sentry.captureException
  onException: (err, ctx) => logger.error({ err, route: ctx.route, requestId: ctx.state.requestId }),
});

api.get("/users/:id", async (ctx) => {
  const user = await db.findUser(ctx.params.id);
  if (!user) throw new HttpError(404, "No such user");
  ctx.respond.json(user, { etag: true });
});

api.post("/users", authenticate({ strategies: [bearerAuth({ verify: verifyJwt })] }), async (ctx) => {
  // The body is captured at request start, so reading it after awaits is fine.
  const input = await readJson(ctx.res, ctx.req, { validate: (v) => UserSchema.parse(v) });
  ctx.respond.json(await db.createUser(input), { status: 201 });
});

app.listen(3000, (token) => token && logger.info({ port: 3000 }, "listening"));

Errors thrown anywhere in the chain are rendered for you: an HttpError (or a body reader's 400/413/415/422) becomes its status and a JSON body; anything else becomes a 500 without leaking the message. A route that finishes without responding gets a 404.

Prefer plain uWS handlers? Every helper also works without the router; see Without the router.

examples/router-app.ts (npm run dev:example-router) is a complete small API using most of the features below.

Modules

Each module is its own build entry, so importing a subpath pulls in only that code.

Import path	What it provides
uws-akwaaba	everything below
uws-akwaaba/router	createRouter, compose, timeout, authenticate, limit, csrf
uws-akwaaba/responder	createResponder, withResponder, withSafeResponder
uws-akwaaba/body	readJson, readText, readUrlencoded, readBuffer, readRawBody, parseUrlencoded, decodeText
uws-akwaaba/multipart	parseMultipart, parseContentDisposition, getBoundary
uws-akwaaba/static	serveStatic, resolveSafePath
uws-akwaaba/auth-register	registerGlobalAuth, bearerAuth, apiKeyAuth, sessionAuth, getAuth, TinyTTLCache
uws-akwaaba/rate-limit	rateLimit, createRateLimiter, MemoryRateLimitStore
uws-akwaaba/cors	createCors(config) → { applyHeaders, preflight }
uws-akwaaba/cors-register	registerGlobalCors(app, config, opts)
uws-akwaaba/cookies	parseCookieHeader, serializeCookie, buildCookieHeaders, clearCookie, createCookieSigner
uws-akwaaba/security-headers	securityHeaders(opts)
uws-akwaaba/request-log	withRequestLog, getRequestId, jsonLineLogger
uws-akwaaba/lifecycle	createLifecycle (graceful shutdown)
uws-akwaaba/websocket	jsonWebSocket, sendJson, publishJson
uws-akwaaba/query	parseQuery, queryReader
uws-akwaaba/errors	HttpError, BadRequestError, PayloadTooLargeError, UnsupportedMediaTypeError, UnprocessableEntityError
uws-akwaaba/http	Status, reasonPhrase, statusLine
uws-akwaaba/file-ops	ensureDir, moveFile, copyFile, removeFile, fileHash, hashBuffer, detectMimeFromBytes, safeFilename

Router and middleware

const router = createRouter(app, { prefix: "/api", trustProxy: false });
router.use(timeout(5_000)); // 503 if nothing responded in time
router.use(limit({ max: 100, windowMs: 60_000 })); // RateLimit-* headers, 429 + Retry-After
router.post("/transfer", csrf(), authenticate({ strategies, require: { roles: ["admin"] } }), handler);

Each handler receives a Context:

Field	Description
ctx.res	the live uWS response (for body readers and streaming)
ctx.req	a snapshot of the request that stays valid after await
ctx.respond	the responder (below)
ctx.params	named route parameters, { id: "42" } for /users/:id
ctx.query	string/list/number/int/bool accessors over the query string
ctx.state	per-request storage for middleware; starts with ip

Middleware runs onion-style (await next()); calling next() twice is an error. onError and onUnhandled options customise error and 404 responses.

Responses

const respond = createResponder(res, req, {
  cors: { origin: ["https://app.example.com"], credentials: true },
  defaultHeaders: securityHeaders(),
  compress: true, // brotli/gzip for text-like bodies over 1 KB
  etag: true, // weak ETag + 304 on If-None-Match
});

respond.json({ ok: true }); // 200 application/json
respond.text("pong", { status: 201 });
respond.html("<h1>Hi</h1>");
respond.send(pngBytes, "image/png");
respond.redirect("/login", 303); // refuses //host, javascript: and CR/LF
respond.empty(); // 204
respond.error("Bad input"); // 400 { "error": "Bad input" }
respond.header("Server-Timing", "db;dur=12"); // queue a header for whatever is sent later
respond.json(data, {
  cookies: [{ name: "sid", value: token, options: { httpOnly: true, secure: true, sameSite: "Lax" } }],
  cors: false, // skip CORS for this response only
});
respond.sent; // true once a response went out; later calls are ignored

The status line is always written first (uWS fixes it at 200 as soon as any header is written), a second response is dropped instead of throwing, and nothing is written to a client that has disconnected.

Request bodies

All readers enforce maxBytes (default 1 MB), copy uWS's short-lived buffers, and reject with typed errors (413 too large, 400 malformed, 415 wrong type with strictContentType, 422 failed validation).

const user = await readJson(res, req, { validate: (v) => UserSchema.parse(v) }); // zod, valibot, ajv...
const form = await readUrlencoded(res, req, { strictContentType: true });
const text = await readText(res, req); // any WHATWG charset, e.g. ISO-8859-1
const raw = await readBuffer(res, req, { maxBytes: 10 * 1024 * 1024 });

uWS only delivers the body to a handler subscribed during the request callback. The router does this for you; in plain handlers call deferBody(res) first if you need to await before reading.

Multipart uploads

const { fields, files } = await parseMultipart(res, req, {
  fileStrategy: "auto", // "buffer" | "file" | "auto" (spill to disk above bufferFileThreshold)
  tempDir: "/var/tmp/uploads",
  maxBytes: 50 * 1024 * 1024,
  maxFileSize: 20 * 1024 * 1024,
  maxFileCount: 5,
  maxFieldSize: 64 * 1024,
  allowedMimeTypes: ["image/*", "application/pdf"],
});
// files[i]: { fieldName, filename, mime, size, buffer? , path? }

The parser streams with disk backpressure, enforces every limit as data arrives, sanitises file names (including Windows ..\ traversal), resolves only after files are flushed to disk, and deletes the temp files it created when anything fails. It never deletes a file it did not create.

Static files

const assets = serveStatic("./public", { prefix: "/assets", maxAgeSeconds: 3600, immutable: true });
app.get("/assets/*", assets);
app.head("/assets/*", assets);

Weak ETag + Last-Modified with 304, single byte ranges (206/416, If-Range), HEAD, index files, and streaming through tryEnd/onWritable so slow clients do not buffer whole files in memory. Encoded, backslash and .. traversal, NUL bytes and dotfiles are refused.

Authentication

Inside the router use authenticate(...). For plain handlers, register rules once for the whole app:

registerGlobalAuth(app, {
  default: { handlers: [bearerAuth({ verify: verifyJwt })] },
  rules: [
    { match: { prefix: "/public" }, skip: true },
    { match: { prefix: "/admin" }, require: { roles: ["admin"] } },
    { match: { prefix: "/ingest" }, handlers: [apiKeyAuth({ lookup: findKey })] },
  ],
  cache: { enabled: true, ttlMs: 5000 },
});

app.get("/me", (res) => {
  const auth = getAuth(res); // { user, claims, token }
});

Rules match exact path first, then longest prefix, then regex. Strategies may be async; the registrar keeps the request usable for your handler and turns a throwing strategy into a 500. Role and scope policies apply to cached tokens too.

Rate limiting, CSRF, cookies and headers

app.post("/login", rateLimit(loginHandler, { max: 5, windowMs: 60_000 }));

const signer = createCookieSigner([process.env.COOKIE_SECRET!, process.env.OLD_COOKIE_SECRET!]);
const value = signer.sign("user:42"); // "user:42.<hmac>"
signer.unsign(value); // "user:42", or undefined if tampered

buildCookieHeaders([{ name: "sid", value, options: { httpOnly: true, csrfToken: createCsrfToken() } }]);

securityHeaders({ strictTransportSecurity: { maxAgeSeconds: 31_536_000 } });

clientIp(res, req, { trustProxy }) uses the socket address unless you explicitly trust X-Forwarded-For. Set trustProxy: true behind one reverse proxy you control, or the number of chained proxies (trustProxy: 2); the client address is read that many entries from the right, so values a client puts in the header itself are ignored.

Logging, error tracking and shutdown

The library writes no logs of its own; you choose where entries go. With the router, pass requestLog and every route gets an access log and a request id (echoed as X-Request-Id, available as ctx.state.requestId). onException receives unexpected errors (not 4xx HttpErrors, not client aborts) before they are rendered, which is where an error tracker belongs.

import pino from "pino";
import * as Sentry from "@sentry/node";

const logger = pino();
createRouter(app, {
  requestLog: { log: structuredLogger(logger) }, // 5xx/aborted -> error, 4xx -> warn, else info
  onException: (err, ctx) => Sentry.captureException(err, { tags: { route: ctx.route } }),
});

structuredLogger accepts anything with pino-style info/warn/error(object, message) methods; jsonLineLogger writes JSON lines to stdout with no dependency. Outside the router, wrap individual handlers:

app.get("/files/*", withRequestLog(serveStatic("./files", { prefix: "/files" }), { log: jsonLineLogger }));
// {"time":"…","id":"3f7d…","method":"GET","url":"/files/a.pdf","status":200,"durationMs":5.3,"bytes":35,"aborted":false}

const life = createLifecycle();
app.get("/work", life.track(handler));
await life.listen(app, 3000);
process.once("SIGTERM", async () => {
  await life.shutdown({ timeoutMs: 15_000 }); // stop accepting, drain in-flight, then close
  process.exit(0);
});

Error tracking

onException(err, ctx) is the contract for error trackers. It is called once per request, with the original error, for anything that is not a 4xx HttpError or a client abort, and before the response is rendered; ctx.route and ctx.state.requestId identify the request. The client still gets the generic 500 body (the message is never leaked), and an exception thrown by the reporter itself is ignored. These guarantees are covered by tests/integration/routerObservability.int.test.ts.

createRouter(app, {
  requestLog: { log: structuredLogger(logger) },
  onException: (err, ctx) =>
    Sentry.captureException(err, { tags: { route: ctx.route }, extra: { requestId: ctx.state.requestId } }),
});

Production notes

• Graceful shutdown. Wrap routes with createLifecycle().track(...) and call shutdown({ timeoutMs }) on SIGTERM, so in-flight requests finish before the process exits.
• Health route. A cheap route such as api.get("/health", ...) (see examples/router-app.ts) gives monitoring something to call.
• Client addresses. Set trustProxy to the number of trusted proxies in front of the app (true for one) so ctx.state.ip and rateLimit see the real client; leave it off otherwise.
• Logs and errors. Pass requestLog (with jsonLineLogger or structuredLogger(pino())) and onException to the router.
• Configuration. The library reads no environment variables; you pass every option in code.

WebSockets

app.ws(
  "/chat",
  jsonWebSocket<{ name: string }, { text: string }>({
    validate: (v) => MessageSchema.parse(v),
    open: (ws) => ws.subscribe("room"),
    onMessage: (ws, msg) => publishJson(app, "room", { text: msg.text }),
  }),
);

Invalid JSON, binary frames and handler errors are reported to the client (or your onError) instead of crashing.

Without the router

app.post(
  "/echo",
  withResponder(async (respond, req, res) => {
    const body = await readJson(res, req, { maxBytes: 64 * 1024 });
    respond.json(body, { status: 201 });
  }),
);

withResponder installs the abort guard, reads the headers it needs up front, and renders thrown errors like the router does (onError to customise). registerGlobalCors(app, config) applies CORS to every route registered after it.

Architecture

uws-akwaaba is a library: every module is a function or factory that you call from your own uWebSockets.js app, and nothing runs on import. The layout:

src/
  index.ts             public entry: re-exports only
  router.ts            createRouter, compose, Context
  router/middleware.ts timeout, authenticate, limit, csrf
  responder.ts         createResponder, withResponder, withSafeResponder
  body.ts              body readers with limits, validation and typed errors
  multipart.ts         streaming multipart/form-data state machine
  multipart/           header parsing, FileSink (disk writes), public types
  static.ts            serveStatic with conditional/range requests
  auth-register.ts     rule-based auth registrar
  auth/                types, TTL cache, rule matching, strategies
  rate-limit.ts        fixed-window limiter, store, route wrapper
  request-log.ts       request ids and access logging
  lifecycle.ts         graceful shutdown
  websocket.ts         JSON WebSocket behaviour
  errors.ts            HttpError and friends
  cors.ts, cors-register.ts, cookies.ts, signed-cookies.ts, csrf.ts,
  security-headers.ts, query.ts, http.ts, types.ts
  utils/               abort fan-out, request snapshots, deferBody, client IP,
                       compression, range parsing, MIME types, file helpers
examples/              runnable servers, one per feature (not part of the package)
  docker/              optional isolated environment for the checks and examples
tests/                 unit suites mirroring src/, plus tests/integration which
                       runs everything against a real uWS server on a random port

Three small mechanisms carry most of the uWS-specific safety:

• utils/abort.ts owns the single onAborted registration uWS allows per response and fans it out, so readers, the responder and the parser never displace each other.
• utils/request-snapshot.ts copies a request (all headers, URL, method, query, params) so it can be used after await.
• utils/defer-body.ts captures the body at request start and pauses the socket until a reader asks for it.

Development

git clone https://github.com/DERRICK-TORKORNOO/uws-akwaaba.git
cd uws-akwaaba
npm ci
npm test               # unit + integration tests
npm run test:coverage  # with coverage thresholds (what CI runs)
npm run lint           # eslint
npm run format:check   # prettier
npm run typecheck      # tsc
npm run build          # ESM + CJS + .d.ts into dist/

Run an example (see package.json for the full list; set PORT or TEMP_DIR to change the port or upload directory, as listed in examples/.env.example):

npm run dev:example-router

A devcontainer configuration is included for VS Code and Codespaces, and examples/docker can run the checks and examples in an isolated environment.

See CONTRIBUTING.md for the workflow and CHANGELOG.md for release notes.

License

MIT © Derrick Mensah Torkornoo