dust_server
Runtime support for Dust-generated Dart HTTP servers on shelf.
Important
0.1.0-beta.2. Complete enough to build on; the API may still change before 1.0, so pin the exact version.
The code generator described in docs/design/server-plugin.md does not exist yet. This package is the runtime that generated code will call, built first so the design is checked against working code rather than a sketch — which has found more than twenty defects the generated code would otherwise have been built on top of. See CHANGELOG.md.
Documentation
Full documentation lives in docs/dust_server.
| Section | Covers |
|---|---|
| Getting started | the smallest server, entry points, layout |
| Routing | paths, methods, nesting, mounting, matching rules, speed |
| Extraction | the built-in extractors, coercion, writing one |
| Responses | encoders, rejections, guard, error reporting |
| WebSockets | upgrades, sessions, close codes |
| Rendering | templates, static files, single-page apps |
| Serving | draining, TLS, isolate clustering |
| Middleware | layers, ordering, what ships |
| Testing | running the suite, testing an application |
| Dependencies | what is reused, and what is not |
At a glance
final app = Router()
..layer(const RequestId())
..route('/todos/{id}', get(readTodo))
..route('/chat/{room}', ws(joinRoom))
..mount('/assets', staticFiles('web/assets'))
..withState(repository)
..fallback(singlePageApp('web/index.html'));
final server = await serve(app, InternetAddress.anyIPv4, 8080);
HTTP, WebSockets, server-rendered HTML, static assets, and isolate clustering, all on one router.
Examples
example/ holds one file per question — under 60 lines
each, named after the question it answers, so the answer is not buried in an
application. The index lists them by area.
Every one is served over a loopback socket by test/example/ and driven with a
real client, which is what keeps a directory that size from rotting.
Tests
100% line coverage, gated in CI.
dart test
Libraries
- annotations
- Annotations: what Dust reads to generate handlers.
- extraction
- Extractors: turning a request into the values a handler declares.
- layers
- Middleware that ships in the box: deadlines, request ids, access records.
- response
- Responses: what a handler answers with, and how failures become status codes.
- router
- Routing: the request tree, how it is composed, and how it is inspected.
- server
- Runtime support for Dust-generated Dart HTTP servers.
- serving
- Running a router as a server, including shutting one down.
- templating
- Server-rendered HTML: a template seam, an adapter, and the response helpers.
- testing
- Test utilities for dust_server.
- tracing
- Tracing: one span per request, and a trace that survives a hop.
- ws
- WebSockets, served by the same router as HTTP.