v0.0.22 · .NET 10 · pre-1.0

A small, explicit HTTP & WebSocket server for C#

HSB (Http Server Boxed) is a lightweight framework for APIs, real-time WebSocket, streaming and embedded servers. It doesn't hide the HTTP lifecycle: you stay close to the protocol.

$ git clone https://github.com/lorenzoconcas/HSB.git && cd HSB && dotnet build HSB.sln
Program.cs
using HSB;

Configuration config = new() { Port = 8080 };

config.Get("/", (Request req, Response res) =>
{
    res.Send("Hello from HSB");
});

config.Get("/json", (Request req, Response res) =>
{
    res.Json(new { message = "ok", timestamp = DateTime.UtcNow });
});

new Server(config).Start();
Features

Everything a small server needs

No heavy stack, no magic. HSB gives you routing, real-time communication and hardening while keeping requests, responses, sockets and headers visible.

Two routing styles

Attribute-based controllers ([Controller], [Get], [Post]…) or Express-style minimal mappings with config.Get(...).

WebSocket

Endpoints with OnOpen, OnMessage, OnClose, async support and per-endpoint broadcast.

Streaming

Chunked responses and NDJSON with InitStream, AddStreamChunk and EndStream.

Security hardening

Opt-in security headers, request validation, per-IP rate limiting, anti-Slowloris timeouts, CORS and IP filters.

TLS & authentication

.p12 certificates, dual-port or single-port HTTPS, Bearer / Basic / API key auth with [RequireAuth].

Middleware & modules

A compiled middleware pipeline (config.Use) plus modules for interceptors, services and global hooks.

OpenAPI 3.2

Generate API documentation from attributes, including the new HTTP QUERY method (RFC 10008).

Static files

Serve a folder or embedded resources when no route matches. Great for single-page apps and dashboards.

Quick start

Pick your style

Minimal endpoints for prototypes, controllers for organized APIs, WebSocket and streaming for real-time.

Express-style mappings

  • Helpers for Get, Post, Put, Delete, Patch, Head, Options, Trace, Connect and Query.
  • Resolution order: minimal mapping → controller → static files → 404.
  • Perfect for small endpoints and prototypes.
Minimal API
config.Get("/health", (Request req, Response res) =>
{
    res.Json(new { status = "ok", uptime = Environment.TickCount64 });
});

config.Post("/auth/login", (Request req, Response res) =>
{
    if (!req.Body.Contains("admin"))
    {
        res.Json(new { error = "invalid_credentials" }, 401);
        return;
    }
    res.Json(new { accessToken = Guid.NewGuid(), expiresIn = 3600 });
});
Performance

Light, and measured

Results from the stress-test project in Experiments/StressTest (health check, JSON, large payload, slow endpoint, NDJSON streaming, WebSocket broadcast).

~18krequests/s on a minimal endpoint
~8krequests/s with medium JSON
Slowlorisslow connections closed by timeouts and limits

Indicative numbers: they depend on machine, .NET runtime, OS, payload and tooling, and are not a production throughput guarantee.