611 lines
23 KiB
Markdown
611 lines
23 KiB
Markdown
# NexusWeb
|
|
|
|
A lightweight, high-performance HTTP server library built on top of Netty. NexusWeb provides a fluent API for routing, middleware, CORS handling, and rate limiting — all running on Java virtual threads for maximum concurrency.
|
|
|
|
## Features
|
|
|
|
- **Netty-based** — uses epoll/kqueue/NIO automatically based on the platform
|
|
- **Virtual thread dispatch** — each request is handled on a Java virtual thread, with per-connection read backpressure and HTTP keep-alive
|
|
- **TLS / HTTPS** — enable encryption with a single `withTls(...)` call (PEM files or a custom `SslContext`)
|
|
- **Pluggable authentication** — insert an auth layer that protects selected paths; API key, cookie, HTTP Basic, bearer or any custom scheme (not tied to bearer tokens)
|
|
- **Trie-based router** — supports static paths, path parameters (`{id}`), and wildcards (`*`)
|
|
- **Annotation-based controllers** — define routes declaratively with `@Controller`, `@GET`, `@POST`, etc.
|
|
- **Middleware chain** — attach cross-cutting logic to all routes
|
|
- **CORS support** — configurable origins, methods, headers, credentials, and preflight caching
|
|
- **Security headers** — opt-in `nosniff`, `X-Frame-Options`, `Referrer-Policy`, CSP and HTTPS-only HSTS, applied to every response
|
|
- **Rate limiting** — four algorithm implementations with per-IP, per-header, per-cookie, per-principal or custom key strategies, with automatic eviction of idle state
|
|
- **Spoofing-safe client IP** — `X-Forwarded-For` is honoured only behind configured trusted proxies
|
|
- **WebSockets** — path-routed handlers with origin validation, optional authentication, ordered per-connection delivery, backpressure, idle timeout, frame size limits and permessage-deflate
|
|
- **JSON I/O** — built-in Jackson integration for request parsing and response serialization
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```java
|
|
Router router = new Router();
|
|
|
|
router.get("/hello", (req, res) -> {
|
|
res.status(200).json("{\"message\":\"Hello, World!\"}");
|
|
});
|
|
|
|
HttpServer.builder(8080, router).start();
|
|
```
|
|
|
|
---
|
|
|
|
## Routing
|
|
|
|
Routes are registered with `GET`, `POST`, `PUT`, `DELETE`, or the generic `register` method.
|
|
|
|
```java
|
|
Router router = new Router();
|
|
|
|
// Static path
|
|
router.get("/users", (req, res) -> { ... });
|
|
|
|
// Path parameter
|
|
router.get("/users/{id}", (req, res) -> {
|
|
String id = req.pathParam("id");
|
|
res.json("{\"id\":\"" + id + "\"}");
|
|
});
|
|
|
|
// Wildcard
|
|
router.get("/files/*", (req, res) -> { ... });
|
|
|
|
// POST with JSON body
|
|
router.post("/users", (req, res) -> {
|
|
MyDto dto = req.jsonAs(MyDto.class);
|
|
res.status(201).json(dto);
|
|
});
|
|
```
|
|
|
|
### Router resolution
|
|
|
|
| Outcome | HTTP Status |
|
|
|---|---|
|
|
| Path and method match | Handler is called |
|
|
| Path exists, method not registered | `405 Method Not Allowed` + `Allow` header |
|
|
| Path not found | `404 Not Found` |
|
|
|
|
### Annotation-based Controllers
|
|
|
|
Instead of registering lambdas on the `Router` directly, you can declare routes as methods on a class and register the whole object at once via `AnnotationScanner`.
|
|
|
|
**Annotations**
|
|
|
|
| Annotation | Target | Description |
|
|
|---|---|---|
|
|
| `@Controller("prefix")` | class | Optional path prefix applied to all methods in the class |
|
|
| `@GET("/path")` | method | Maps a `GET` route |
|
|
| `@POST("/path")` | method | Maps a `POST` route |
|
|
| `@PUT("/path")` | method | Maps a `PUT` route |
|
|
| `@DELETE("/path")` | method | Maps a `DELETE` route |
|
|
| `@PATCH("/path")` | method | Maps a `PATCH` route |
|
|
| `@Route(method="…", path="…")` | method | Generic — any standard HTTP method by name |
|
|
| `@CUSTOM(method="…", value="…")` | method | Custom/non-standard HTTP methods |
|
|
|
|
Every annotated method **must** have the exact signature `(Request req, Response res)` and return `void`.
|
|
|
|
```java
|
|
@Controller("/users")
|
|
public class UserController {
|
|
|
|
@GET("")
|
|
public void list(Request req, Response res) {
|
|
res.json("[{\"id\":1}]");
|
|
}
|
|
|
|
@GET("/{id}")
|
|
public void get(Request req, Response res) {
|
|
res.json("{\"id\":\"" + req.pathParam("id") + "\"}");
|
|
}
|
|
|
|
@POST("")
|
|
public void create(Request req, Response res) {
|
|
UserDto dto = req.jsonAs(UserDto.class);
|
|
// ... persist ...
|
|
res.status(201).json(dto);
|
|
}
|
|
|
|
@PUT("/{id}")
|
|
public void update(Request req, Response res) {
|
|
// ...
|
|
}
|
|
|
|
@DELETE("/{id}")
|
|
public void delete(Request req, Response res) {
|
|
res.status(204);
|
|
}
|
|
|
|
@PATCH("/{id}")
|
|
public void patch(Request req, Response res) {
|
|
// ...
|
|
}
|
|
}
|
|
```
|
|
|
|
Register the controller with:
|
|
|
|
```java
|
|
Router router = new Router();
|
|
AnnotationScanner.register(router, new UserController());
|
|
|
|
HttpServer.builder(8080, router).start();
|
|
```
|
|
|
|
`AnnotationScanner.register` prints each registered route to stdout:
|
|
|
|
```
|
|
Registered: GET /users -> UserController.list
|
|
Registered: GET /users/{id} -> UserController.get
|
|
Registered: POST /users -> UserController.create
|
|
```
|
|
|
|
Multiple controllers can be registered on the same router:
|
|
|
|
```java
|
|
AnnotationScanner.register(router, new UserController());
|
|
AnnotationScanner.register(router, new OrderController());
|
|
```
|
|
|
|
---
|
|
|
|
### Middleware
|
|
|
|
Middleware runs before the matched handler on every request.
|
|
|
|
```java
|
|
router.use((req, res) -> {
|
|
res.header("X-Request-Id", UUID.randomUUID().toString());
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Request API
|
|
|
|
```java
|
|
req.pathParam("id") // path parameter, e.g. from /users/{id}
|
|
req.queryParam("search") // first value of ?search=
|
|
req.queryParams("tag") // all values of ?tag= as List<String>
|
|
req.header("Authorization") // raw header value
|
|
req.cookie("sid") // value of a named cookie
|
|
req.body() // raw body as UTF-8 String
|
|
req.json() // body parsed as Jackson JsonNode
|
|
req.jsonAs(MyDto.class) // body deserialized into a POJO
|
|
req.method() // HttpMethod
|
|
req.path() // decoded path without query string
|
|
req.clientIp() // resolved client IP (honours trusted proxies)
|
|
req.principal() // authenticated principal, or null (see Authentication)
|
|
req.isAuthenticated() // whether a principal is attached
|
|
req.attribute("k", value) // attach per-request state
|
|
req.<T>attribute("k") // read it back
|
|
```
|
|
|
|
`json()` and `jsonAs()` throw `BadRequestException` (→ `400`) on malformed JSON.
|
|
|
|
---
|
|
|
|
## Response API
|
|
|
|
```java
|
|
res.status(201)
|
|
.header("X-Custom", "value")
|
|
.json("{\"ok\":true}"); // sets Content-Type: application/json
|
|
|
|
res.text("plain text"); // sets Content-Type: text/plain
|
|
res.json(someObject); // serializes POJO via Jackson
|
|
```
|
|
|
|
---
|
|
|
|
## CORS
|
|
|
|
```java
|
|
CorsConfig config = CorsConfig.builder()
|
|
.allowedOrigins("https://app.example.com")
|
|
.allowedMethods(HttpMethod.GET, HttpMethod.POST)
|
|
.allowedHeaders("Content-Type", "Authorization")
|
|
.allowCredentials(true)
|
|
.maxAgeSeconds(3600)
|
|
.build();
|
|
|
|
CorsHandler cors = new CorsHandler(config);
|
|
|
|
HttpServer.builder(8080, router)
|
|
.withCorsHandler(cors)
|
|
.start();
|
|
```
|
|
|
|
Use `CorsConfig.permissive()` for a development preset that allows any origin with common methods and headers (incompatible with `allowCredentials`).
|
|
|
|
**Preflight requests** (`OPTIONS` + `Access-Control-Request-Method`) are handled automatically and short-circuit before the router.
|
|
|
|
---
|
|
|
|
## TLS / HTTPS
|
|
|
|
Enable encryption by attaching a `TlsConfig`. The TLS handler becomes the first element of every connection's pipeline, so both HTTP and WebSocket traffic are served over TLS (HTTPS / WSS).
|
|
|
|
```java
|
|
import dev.coph.nextusweb.server.tls.TlsConfig;
|
|
|
|
HttpServer.builder(443, router)
|
|
.withTls(TlsConfig.fromPem(
|
|
new File("fullchain.pem"), // PEM certificate chain
|
|
new File("privkey.pem"))) // PKCS#8 private key
|
|
.start();
|
|
```
|
|
|
|
| Factory | Use |
|
|
|---|---|
|
|
| `TlsConfig.fromPem(cert, key)` | PEM certificate chain + unencrypted PKCS#8 key |
|
|
| `TlsConfig.fromPem(cert, key, password)` | …with a password-protected key |
|
|
| `TlsConfig.fromPem(certStream, keyStream, password)` | Load PEM material from the classpath or another stream |
|
|
| `TlsConfig.fromSslContext(ctx)` | Full control — supply a Netty `SslContext` (custom ciphers, mutual TLS, …) |
|
|
|
|
Any initialisation failure (missing/invalid material) is reported as an `IllegalStateException`.
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
The auth layer authenticates **selected paths** before they reach handlers and attaches a `Principal` to the request (visible to rate limiting, middleware and handlers). It is deliberately **not** tied to bearer tokens — choose any credential scheme.
|
|
|
|
```java
|
|
import dev.coph.nextusweb.server.auth.*;
|
|
|
|
// 1. An authenticator turns a credential into a Principal (or null if invalid).
|
|
Authenticator auth = Authenticator.apiKey("X-API-Key", key ->
|
|
key.equals(System.getenv("API_KEY")) ? Principal.of("service", Set.of("admin")) : null);
|
|
|
|
// 2. Decide which paths it protects.
|
|
AuthConfig authConfig = AuthConfig.builder(auth)
|
|
.protectPrefix("/api/") // required: 401 if missing/invalid
|
|
.optional("/feed") // attach principal if present, never reject
|
|
.challenge("ApiKey realm=\"api\"")
|
|
.build();
|
|
|
|
HttpServer.builder(8080, router)
|
|
.withAuth(new AuthGate(authConfig))
|
|
.start();
|
|
```
|
|
|
|
In a handler:
|
|
|
|
```java
|
|
router.get("/api/me", (req, res) -> {
|
|
Principal p = req.principal(); // never null on a protected path
|
|
if (!p.hasRole("admin")) { res.status(403); return; }
|
|
res.json(Map.of("id", p.id()));
|
|
});
|
|
```
|
|
|
|
### Authenticators
|
|
|
|
| Factory | Credential |
|
|
|---|---|
|
|
| `Authenticator.apiKey(header, validator)` | An API key in a request header (e.g. `X-API-Key`) |
|
|
| `Authenticator.cookie(name, validator)` | A session (or other) cookie |
|
|
| `Authenticator.basic(validator)` | HTTP Basic `username` / `password` |
|
|
| `Authenticator.bearer(validator)` | A bearer token (provided for completeness; never required) |
|
|
| `Authenticator.anyOf(a, b, …)` | Tries each in order, first match wins |
|
|
| Custom | Implement `Authenticator` — e.g. mutual-TLS cert, HMAC-signed request |
|
|
|
|
`validator` returns the resolved `Principal`, or `null` for missing/invalid credentials (→ `401` on a `REQUIRED` path). A thrown exception is treated as an internal error (→ generic `500`); details are logged, never sent to the client. Rate limiting runs **before** authentication, so an unauthenticated flood is shed before reaching a (potentially expensive) authenticator.
|
|
|
|
When a validator compares a presented secret (API key, token, password) against an expected value, use `Authenticator.constantTimeEquals(presented, expected)` instead of `String.equals` to avoid leaking how many characters matched through a timing side channel:
|
|
|
|
```java
|
|
Authenticator auth = Authenticator.apiKey("X-API-Key",
|
|
key -> Authenticator.constantTimeEquals(key, EXPECTED_KEY) ? Principal.of("svc") : null);
|
|
```
|
|
|
|
WebSocket upgrades on protected paths are authenticated the same way; the resolved principal is available via `session.principal()`.
|
|
|
|
---
|
|
|
|
## Trusted proxies & client IP
|
|
|
|
`req.clientIp()` and `KeyResolver.clientIp()` return a spoofing-safe client address. By default (`TrustedProxies.none()`) the transport peer address is used and `X-Forwarded-For` is ignored — a directly connected client cannot forge its IP. When running behind a reverse proxy, declare it trusted so the forwarded header is honoured:
|
|
|
|
```java
|
|
import dev.coph.nextusweb.server.net.TrustedProxies;
|
|
|
|
HttpServer.builder(8080, router)
|
|
.withTrustedProxies(TrustedProxies.of("10.0.0.0/8", "127.0.0.1", "::1"))
|
|
.start();
|
|
```
|
|
|
|
The resolver walks `X-Forwarded-For` from right to left and returns the first hop that is **not** a trusted proxy, so forged left-most entries are ignored. Use `TrustedProxies.all()` only when the server can never be reached except through a trusted proxy.
|
|
|
|
---
|
|
|
|
## Hardening & limits
|
|
|
|
| Concern | How it's handled |
|
|
|---|---|
|
|
| Connection reuse | HTTP keep-alive is honoured; connections close only on `Connection: close` or error |
|
|
| Slow-client / Slowloris | A per-connection read timeout (`httpReadTimeout`, default 30s) closes stalled/idle connections |
|
|
| Request memory | Auto-read is disabled while a request is in flight (one buffered body per connection); `maxHttpContentLength` (default 1 MiB) caps the body, returning `413` |
|
|
| Error disclosure | Handler exceptions return a generic `500`; the detail is logged server-side, never sent to the client |
|
|
|
|
```java
|
|
HttpServer.builder(8080, router)
|
|
.maxHttpContentLength(2 * 1024 * 1024) // 2 MiB body cap
|
|
.httpReadTimeout(Duration.ofSeconds(20)) // null/zero disables
|
|
.start();
|
|
```
|
|
|
|
---
|
|
|
|
## Security headers
|
|
|
|
`withSecurityHeaders(...)` adds standard browser-hardening response headers to **every** response (handler responses, errors, CORS preflights and rejections alike). It is opt-in; without the call no security headers are sent.
|
|
|
|
```java
|
|
import dev.coph.nextusweb.server.security.SecurityHeaders;
|
|
|
|
HttpServer.builder(443, router)
|
|
.withTls(TlsConfig.fromPem(cert, key))
|
|
.withSecurityHeaders(SecurityHeaders.defaults())
|
|
.start();
|
|
```
|
|
|
|
`SecurityHeaders.defaults()` emits a conservative baseline:
|
|
|
|
| Header | Value | Notes |
|
|
|---|---|---|
|
|
| `X-Content-Type-Options` | `nosniff` | Blocks MIME sniffing |
|
|
| `X-Frame-Options` | `DENY` | Click-jacking defence |
|
|
| `Referrer-Policy` | `no-referrer` | No referrer leakage |
|
|
| `Strict-Transport-Security` | `max-age=31536000` | **Only sent over HTTPS** (when `withTls(...)` is set); pins HTTPS for a year |
|
|
|
|
Two safety rules keep it from breaking anything: **HSTS is emitted only on TLS connections** (a browser ignores it on plain HTTP), and a header a handler has **already set is never overwritten** — so per-route choices win.
|
|
|
|
For full control use the builder. Passing `null`/blank to a setter omits that header:
|
|
|
|
```java
|
|
SecurityHeaders headers = SecurityHeaders.builder()
|
|
.frameOptions("SAMEORIGIN") // or null to omit
|
|
.referrerPolicy("strict-origin-when-cross-origin")
|
|
.contentSecurityPolicy("default-src 'self'") // off by default (app-specific)
|
|
.hsts(Duration.ofDays(365), true, false) // maxAge, includeSubDomains, preload
|
|
.header("Permissions-Policy", "geolocation=()") // any extra header
|
|
.build();
|
|
|
|
HttpServer.builder(443, router)
|
|
.withTls(TlsConfig.fromPem(cert, key))
|
|
.withSecurityHeaders(headers)
|
|
.start();
|
|
```
|
|
|
|
> `includeSubDomains` and `preload` are hard to roll back — enable them only once every subdomain is reliably served over HTTPS.
|
|
|
|
---
|
|
|
|
## Rate Limiting
|
|
|
|
### Algorithms
|
|
|
|
| Class | Description |
|
|
|---|---|
|
|
| `TokenBucketLimiter` | Smooth bursts up to a configurable capacity, refills at a steady rate |
|
|
| `FixedWindowLimiter` | Hard limit per fixed time window |
|
|
| `SlidingWindowLimiter` | Weighted sliding window — reduces boundary spikes vs. fixed window |
|
|
| `LeakyBucketLimiter` | Constant outflow rate; excess requests are rejected immediately |
|
|
|
|
### Configuration
|
|
|
|
```java
|
|
RateLimitConfig config = RateLimitConfig.builder()
|
|
// Global rule for all routes — keyed by client IP
|
|
.global(new TokenBucketLimiter(100, 200), KeyResolver.clientIp())
|
|
// Stricter rule for a specific path
|
|
.forPath("/login", new FixedWindowLimiter(5, 60_000), KeyResolver.clientIp())
|
|
// Per-API-key rule for an entire path prefix (no bearer token required)
|
|
.forPrefix("/api/", new SlidingWindowLimiter(1000, 1000), KeyResolver.header("X-API-Key"))
|
|
.build();
|
|
|
|
RateLimitGate gate = new RateLimitGate(config);
|
|
|
|
HttpServer.builder(8080, router)
|
|
.withRateLimitGate(gate)
|
|
.start();
|
|
```
|
|
|
|
When the limit is exceeded the server responds with `429 Too Many Requests` and a `Retry-After` header.
|
|
|
|
Per-key limiter state is evicted automatically by a background task (every 5 minutes, entries idle for >10 minutes), so a high-cardinality key (many distinct IPs/API keys) cannot grow the limiter maps without bound. Call `gate.shutdown()` when stopping the server.
|
|
|
|
### Response headers
|
|
|
|
Every response automatically includes:
|
|
|
|
| Header | Description |
|
|
|---|---|
|
|
| `X-RateLimit-Limit` | Configured limit for the matched rule |
|
|
| `X-RateLimit-Remaining` | Remaining requests in the current window |
|
|
| `Retry-After` | Seconds until the client may retry (only on `429`) |
|
|
|
|
### Key resolvers
|
|
|
|
| Factory | Behaviour |
|
|
|---|---|
|
|
| `KeyResolver.clientIp()` | The resolved client IP (honours trusted proxies — `X-Forwarded-For` is **not** trusted from a direct client) |
|
|
| `KeyResolver.header(name)` | Header value (e.g. an API key in `X-API-Key`); falls back to `ip:<addr>` when absent |
|
|
| `KeyResolver.cookie(name)` | Cookie value (e.g. a session id); falls back to `ip:<addr>` when absent |
|
|
| `KeyResolver.principal()` | The authenticated principal id (`p:<id>`); falls back to `ip:<addr>` when anonymous (requires the auth layer to run for the path) |
|
|
| Custom lambda | `(req, clientIp) -> myKey(req)` — `req` is the framework `Request`, `clientIp` the resolved IP |
|
|
|
|
> The old `KeyResolver.userOrIp()` (which trusted any client's `X-Forwarded-For` and keyed on a raw bearer token) has been removed. It allowed trivial rate-limit bypass and unbounded key growth; use `header(...)`, `cookie(...)` or `principal()` instead.
|
|
|
|
---
|
|
|
|
## WebSockets
|
|
|
|
WebSocket routes are registered on a `WebSocketRouter` and attached to the server alongside the HTTP `Router`. Upgrade requests (`GET` + `Upgrade: websocket`) are intercepted before the HTTP router runs.
|
|
|
|
### Handler
|
|
|
|
Implement `WebSocketHandler`. All callbacks are optional.
|
|
|
|
```java
|
|
public class ChatSocket implements WebSocketHandler {
|
|
|
|
private final WebSocketGroup room = new WebSocketGroup("chat");
|
|
|
|
@Override
|
|
public void onOpen(WebSocketSession session) {
|
|
room.add(session);
|
|
session.send("{\"type\":\"welcome\",\"id\":\"" + session.id() + "\"}");
|
|
}
|
|
|
|
@Override
|
|
public void onMessage(WebSocketSession session, String message) {
|
|
room.broadcastExcept(session, message);
|
|
}
|
|
|
|
@Override
|
|
public void onClose(WebSocketSession session, int code, String reason) {
|
|
room.remove(session);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Registration
|
|
|
|
```java
|
|
WebSocketRouter wsRouter = new WebSocketRouter()
|
|
.on("/ws/chat", new ChatSocket())
|
|
.on("/ws/rooms/{room}", new RoomSocket());
|
|
|
|
WebSocketConfig wsConfig = WebSocketConfig.builder()
|
|
.allowedOrigins("https://app.example.com")
|
|
.maxFramePayloadLength(64 * 1024) // 64 KiB per frame
|
|
.maxAggregatedMessageSize(1024 * 1024) // 1 MiB cap on a reassembled (fragmented) message
|
|
.maxQueuedMessages(1024) // per-connection backlog before backpressure
|
|
.idleTimeout(Duration.ofSeconds(60)) // close idle peers
|
|
.subprotocols("chat.v1")
|
|
.compression(true) // permessage-deflate
|
|
.build();
|
|
|
|
HttpServer.builder(8080, router)
|
|
.withWebSockets(wsRouter, wsConfig)
|
|
.start();
|
|
```
|
|
|
|
Use `WebSocketConfig.defaults()` (or `.anyOrigin()` on the builder) only for local development — production deployments should always allow-list origins explicitly.
|
|
|
|
### Session API
|
|
|
|
```java
|
|
session.id(); // stable UUID for this connection
|
|
session.path(); // matched path
|
|
session.pathParam("room"); // path parameter, e.g. from /ws/rooms/{room}
|
|
session.remoteAddress(); // client IP
|
|
session.principal(); // authenticated principal, or null
|
|
session.attribute("userId", id); // attach state to the session
|
|
session.attribute("userId"); // read it back
|
|
|
|
session.send("text"); // text frame
|
|
session.sendJson(dto); // serialized via Jackson
|
|
session.sendBinary(bytes); // binary frame
|
|
session.ping(); // ping frame
|
|
session.close(); // normal close (1000)
|
|
session.close(1011, "internal"); // close with code + reason
|
|
```
|
|
|
|
### Broadcasting
|
|
|
|
`WebSocketGroup` is a thin fluent wrapper around Netty's `ChannelGroup` — joining a session is cheap and removal happens automatically when the channel closes.
|
|
|
|
```java
|
|
WebSocketGroup group = new WebSocketGroup("lobby")
|
|
.add(sessionA)
|
|
.add(sessionB);
|
|
|
|
group.broadcast("hello everyone");
|
|
group.broadcastJson(eventDto);
|
|
group.broadcastExcept(sessionA, "everyone but A");
|
|
```
|
|
|
|
### Security & limits
|
|
|
|
| Concern | How it's handled |
|
|
|---|---|
|
|
| Cross-origin upgrades | `Origin` header validated against `WebSocketConfig.allowedOrigins(...)`; mismatched origins are rejected with `403` |
|
|
| Authentication | When an `AuthGate` is configured, protected upgrade paths are authenticated and the principal is exposed via `session.principal()` |
|
|
| Memory exhaustion | `maxFramePayloadLength` caps a single frame; `maxQueuedMessages` (default 1024) bounds the per-connection callback backlog and pauses reads (backpressure) when exceeded |
|
|
| Message ordering | Callbacks for a single connection run **strictly in arrival order** on a per-connection serial drainer (still on virtual threads, so handlers may block) |
|
|
| Idle / zombie connections | `idleTimeout` triggers a server-side close when no read **and** no write happen within the window |
|
|
| User code isolation | All callbacks dispatch onto Java virtual threads, never the Netty event loop |
|
|
| Subprotocol negotiation | Server advertises the configured `subprotocols(...)` list; clients that ask for an unsupported subprotocol fail the handshake |
|
|
|
|
---
|
|
|
|
## Full Example
|
|
|
|
```java
|
|
// Controller class
|
|
@Controller("/users")
|
|
public class UserController {
|
|
|
|
@GET("")
|
|
public void list(Request req, Response res) {
|
|
res.json("[{\"id\":1}]");
|
|
}
|
|
|
|
@GET("/{id}")
|
|
public void get(Request req, Response res) {
|
|
res.json("{\"id\":\"" + req.pathParam("id") + "\"}");
|
|
}
|
|
|
|
@POST("")
|
|
public void create(Request req, Response res) {
|
|
UserDto dto = req.jsonAs(UserDto.class);
|
|
res.status(201).json(dto);
|
|
}
|
|
}
|
|
|
|
// Server setup
|
|
Router router = new Router();
|
|
|
|
// Middleware — add request ID to every response
|
|
router.use((req, res) -> res.header("X-Request-Id", UUID.randomUUID().toString()));
|
|
|
|
AnnotationScanner.register(router, new UserController());
|
|
|
|
CorsHandler cors = new CorsHandler(CorsConfig.permissive());
|
|
|
|
RateLimitConfig rlConfig = RateLimitConfig.builder()
|
|
.global(new TokenBucketLimiter(200, 400), KeyResolver.clientIp())
|
|
.build();
|
|
RateLimitGate gate = new RateLimitGate(rlConfig);
|
|
|
|
// WebSockets
|
|
WebSocketRouter wsRouter = new WebSocketRouter()
|
|
.on("/ws/chat", new ChatSocket());
|
|
|
|
WebSocketConfig wsConfig = WebSocketConfig.builder()
|
|
.allowedOrigins("https://app.example.com")
|
|
.idleTimeout(Duration.ofSeconds(60))
|
|
.build();
|
|
|
|
HttpServer.builder(8080, router)
|
|
.withCorsHandler(cors)
|
|
.withRateLimitGate(gate)
|
|
.withSecurityHeaders(SecurityHeaders.defaults())
|
|
.withWebSockets(wsRouter, wsConfig)
|
|
.start();
|
|
```
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Java 26+
|
|
- Netty 4.x
|
|
- Jackson (tools.jackson)
|