web
A small router and middleware on http-server, over the Fetch
types: method routes with path parameters and wildcards, sub-apps, onion middleware, typed
per-request variables, error and not-found handlers, and the middleware cors, logger,
requestId, rateLimit, bodyLimit, compress and serveStatic.
web is held to full quality, but it is a reference: read it as the guide to building a
framework on http-server. Its API may change until it is promoted to a supported framework.
Its README is the full
API; this page gives the shape and what to watch for.
Adding it to a program
Like the other official packages, web lives in the Velt repository's
packages/. Depend on it, and on http-server, from there:
import type { Package } from "velt/package";
export const pkg: Package = {
name: "app",
version: "0.1.0",
dependencies: {
"http-server": { git: "https://github.com/velt-lang/velt", tag: "v0.6.0", path: "packages/http-server" },
web: { git: "https://github.com/velt-lang/velt", tag: "v0.6.0", path: "packages/web" },
},
};An app
import { serve } from "http-server";
import { App, cors, logger } from "web";
struct Vars {
user: string;
}
const app = new App<Vars>(() => ({ user: "anonymous" }));
app.use(logger());
app.use(cors());
app.around(async (c, next) => {
c.vars.user = c.req.headers.get("x-user") ?? c.vars.user;
return await next(c);
});
app.get("/users/:id", async (c) => c.json({ id: c.param("id"), by: c.vars.user }));
app.post("/users", async (c) => c.text("made", 201));
const handler = app.handler();
await serve({ port: 8080 }, (req: Request) => handler(req));App<V> takes a function that makes each request's variables (c.vars), typed by V.
app.handler() builds the routes and middleware once and gives a plain
(req: Request) => Promise<Response> for serve.
Routes
app.get, post, put, patch, delete and on(method, …) add a route. A pattern is
segments between slashes:
| Segment | Matches | Read with |
|---|---|---|
users | exactly that segment | |
:id | one non-empty segment | c.param("id"), percent-decoded |
a last * | the rest of the path, also nothing | c.param("*") |
- A literal beats a parameter, which beats a wildcard, and a lookup goes back to the next choice when the first leads nowhere. HEAD takes GET's route when it has none of its own.
- A path with no route gets the not-found answer (404 by default,
app.notFound(…)); a path with routes for other methods gets 405 withAllow./aand/a/are different paths. app.route("/api", sub)mounts anotherAppwith the same variables on a prefix, its middleware inside this app's. A/ending the prefix doesn't count, and the sub-app's/is the prefix alone:/api, not/api/.- A handler gets a
Context:c.req,c.path,c.vars,c.param(name),c.query(name), andc.text,c.html,c.jsonandc.redirectfor a response.
The path
Routes, middleware prefixes, c.path and serveStatic read one canonical path (pathOf,
exported), so an escape, a dot segment or a \ doesn't get past a check made on another
spelling: \ is /, . and .. segments are removed, and each character has one spelling
(/%61dmin is /admin; %2F stays encoded, inside its segment). Decide on c.path, not on
c.req.url, which is what the client sent.
- Case isn't folded. On a case-insensitive disk (Windows, and macOS by default) a prefix
doesn't guard files under
serveStatic:/PRIVATE/s.txtisn't under/private, but the disk givesserveStaticthe fileprivate/s.txtfor it. Keep files a prefix protects outsideserveStatic's root. - A parameter is data the client chose. Once decoded it can hold
/and.., so don't join one to a file path: useresolveUnder(http-server) orserveStatic.
Middleware
A middleware is a plain function from the handler it wraps to a new handler, over the Fetch
types, so it works on bare serve too: serve(opts, poweredBy("velt")(handler)).
import { Handler, Middleware } from "web";
function poweredBy(name: string): Middleware {
return (next: Handler): Handler => async (req: Request): Promise<Response> => {
const res = await next(req);
res.headers.set("x-powered-by", name);
return res;
};
}app.use(mw, prefix?)wraps the whole app, for every request under the prefix, routed or not. The first added is the outermost. It runs before routing and has no context.app.around((c, next) => …, prefix?)runs after routing and sees the context. It wraps the routes added after it and the not-found answer, callsawait next(c)for the rest of the onion, and can change the response or answer without calling it.- A prefix ends on a segment boundary:
/apicovers/apiand/api/x, not/apix. - A plain middleware can't be applied inside one route: a route that captures a handler a plain
middleware made (
const h = bodyLimit(5)(ok), then(c) => h(c.req)) panics inhandler(). Apply it to part of an app with a prefix:app.use(bodyLimit(5), "/upload"). - What a handler or middleware throws goes to
app.onError((e, c) => …)(by default logged, then a 500). A panic isn't an error:serveanswers it with a 500.
| Middleware | Does |
|---|---|
cors(options?) | answers preflights (204) and marks responses for the origins allowed; never sends credentials with * |
logger(write?) | a line per request when its head is ready, GET /a 200 3ms, with the canonical path and no query (which may hold secrets) |
requestId(options?) | an identifier on the request and response headers; a client's is kept only if it is safe to log |
rateLimit({ limit, windowMs, key, maxKeys? }) | requests per key per fixed window, shared by all requests; 429 with Retry-After and RateLimit-* headers |
bodyLimit(maxBytes) | 413 for a request body over the limit, holding no more than the limit |
compress(options?) | response bodies in Brotli or gzip, as Accept-Encoding prefers, streamed |
serveStatic(root, options?) | files under root, with serveFile's validators, 304 and Range; passes on what it has no file for |
A callback a middleware takes (logger's write, rateLimit's key and now) gets its own
copy of what it captures on each call, like a handler, and a change to that copy is lost:
logger((l) => { lines.push(l); }) leaves lines empty. Write to something shared, such as
shared(new Mutex<string[]>([])).
rateLimit
- Apply it to the app or to a prefix, not inside a route: a limiter built inside a route gets a new table on each request and never limits.
keytakes only theRequest, which doesn't hold the client's address. To count by address, set a header frominfo.remoteAddr.hostnameinserve's handler, overwriting what the client sent under that name, and key on it. Don't key onx-forwarded-fororforwardedunless a proxy you control sets them: a client could send a new value with each request.- The table holds at most
maxKeyskeys (default 100,000), and a key over 256 characters is kept as its hash. When the table is full and no window has ended, a new key gets a 429 until one has; the keys held go on being counted, since dropping a live window would hand a client its allowance back. The cost: a client who can vary the key can fill the table in about a second and hold new keys out for the rest of the window, again each window, and a long window makes that worse. Key on what a client can't vary at will: the address, and for IPv6 its /64.
import { serve, ServeInfo } from "http-server";
import { App, rateLimit } from "web";
const app = new App<number>(() => 0);
app.use(
rateLimit({
limit: 100,
windowMs: 60000,
key: (req) => req.headers.get("x-client-address") ?? "unknown",
}),
);
const handler = app.handler();
await serve({ port: 8080 }, (req: Request, info: ServeInfo) => {
const headers = new Headers(req.headers);
headers.set("x-client-address", info.remoteAddr.hostname);
return handler(new Request(req, { headers }));
});bodyLimit
bodyLimit(maxBytes) answers 413 for a body over the limit, by its Content-Length or while it
arrives, and holds no more than the limit. A GET or HEAD with a chunked body within the limit
reaches its route without the body.
compress
compress(options?) compresses response bodies with Brotli or gzip, whichever the request's
Accept-Encoding prefers by q-value (Brotli on a tie; * counts; q=0 refuses). It goes
outside the middleware whose responses it compresses: app.use(compress()) first, or
serve(opts, compress()(handler)).
- Options:
encodings(default Brotli quality 4, then gzip level 6, the levels for dynamic responses; anyEncodingfrom velt/compress or a package) andthreshold(default 1024 bytes). - Left alone: HEAD; 204, 206 and 304; bodies already encoded;
Cache-Control: no-transform; types that don't compress (images, video, archives); and bodies under the threshold, by theirContent-Length, or by their first chunk without one, so a stream is never held back. - A compressed response drops
Content-LengthandAccept-Ranges, and a strongETagbecomes weak.Vary: Accept-Encodingis set on every response of a type that compresses. - Bodies stream through the encoder with backpressure.
text/event-streamis flushed after every chunk, so each event arrives when it is sent.
Building a framework on http-server
The README's last section lists what the package had to get right, in the order you will meet
it: handlers copy what they capture per request (so route tables go in shared(...)), a router
holds no functions, middleware is composed once, the context is passed rather than captured,
and state between requests needs an explicit home (shared(new Mutex(…)), an Atomic, a
ConcurrentMap). Read it before writing a framework of your own.