relic_headers 2.0.0
relic_headers: ^2.0.0 copied to clipboard
HTTP header names and stores shared by Relic adapters and other packages.
2.0.0 #
Relic 2.0 adds relic_native, a native HTTP adapter that answers about five times the requests per second of relic_io. To try it, add the package and call app.serveNative() where the program called app.serve().
The release also makes the typed headers fully RFC compliant, adds HTML form and multipart parsing, and fixes the findings of a security audit.
Relic 2.0.0 requires Dart 3.10.0 or later.
relic_native #
relic_native is a new package, a Relic adapter on an HTTP server written in Zig, a systems language that compiles to native code and has no garbage collector. The server accepts connections, parses requests, keeps connections alive, enforces timeouts, terminates TLS and frames WebSockets in native code, and a request reaches the handler as plain Dart data. It runs the same handlers, middleware and router as relic_io and passes the same conformance suite.
Benchmarks
The figures are from a GCP c4d-standard-32 instance, 16 AMD EPYC 9B45 cores with one thread per core, running Ubuntu 24.04 and Dart 3.13.7. oha held 64 keep-alive connections over loopback from the same machine.
One isolate at saturation over HTTP, in thousands of requests per second:
| Route | relic_io |
relic_native |
Speed-up |
|---|---|---|---|
| Plaintext, a 13-byte answer | 61.1 | 294.9 | 5x |
| Headers, three typed request headers read | 33.8 | 182.9 | 5x |
| Browser, 1 KB of JSON to a browser-like request | 30.4 | 128.6 | 4x |
The same over HTTPS. It is TLS 1.3 on connections that stay open, so it measures records, not handshakes:
| Route | relic_io |
relic_native |
Speed-up |
|---|---|---|---|
| Plaintext | 25.4 | 243.3 | 10x |
| Headers | 18.6 | 146.8 | 8x |
| Browser | 18.1 | 98.4 | 5x |
99th percentile latency over HTTP, in milliseconds, with each adapter at 75 percent of its own saturation rate:
| Route | relic_io |
relic_native |
|---|---|---|
| Plaintext | 1.29 | 0.27 |
| Headers | 1.41 | 0.44 |
| Browser | 1.59 | 0.66 |
Throughput grows with noOfIsolates. Four isolates answer 580 thousand requests per second on the headers route, against 105 thousand on relic_io.
With 10,000 idle WebSockets open over TLS, the server's resident memory grows by 14.8 KiB per connection on relic_native and 61.6 KiB on relic_io.
Protocols and platforms
The adapter is opt-in, and app.serve() stays on relic_io. It speaks HTTP/1.0 and HTTP/1.1, its HTTPS is TLS 1.3 only, and it supports WebSockets and hijacked connections. Prebuilt libraries ship for Linux, macOS and Windows on x64 and arm64, so a project needs no Zig toolchain. The gain shows once the server is the limit, not the database or the handler. The relic_native changelog and the serving page have the details.
All changes #
The changes are grouped by area, and each breaking change carries a BREAKING label in its group.
Headers
- feat!: RFC compliant typed headers (#360) - fixes #113, #142
- BREAKING: Many typed headers changed their Dart interface or their parse and serialize semantics. Parsing is lenient on receive, except for security-sensitive headers, and construction and serialization are strict
- BREAKING: Extended
Content-Dispositionparameters such asfilename*are RFC 8187 ext-values and always encode as UTF-8.ContentDispositionParameterhas noencoding, and itslanguageis aLanguageTag. Parsing throwsFormatExceptionfor a charset other than UTF-8 and for a malformed ext-value (#380) - Add a typed
ContentTypeHeader, read withheaders.contentType(#380) - Add
CacheControlHeader.parseStrictfor values under the sender's own control. It throwsFormatExceptionfor an unrecognized directive or a malformed delta-seconds value, andparsestays lenient per RFC 9111 5.2 (#370)
- refactor!: Cookie and Set-Cookie headers (#361)
- BREAKING:
SetCookieis a single cookie, andSetCookieHeaderis aList<SetCookie>, oneSet-Cookieline per cookie (RFC 6265 4.1). Build a cookie withSetCookie(...)and add it withmh.setCookie = (mh.setCookie ?? const SetCookieHeader.empty()).add(cookie) - The request
Cookieheader is parsed leniently: a malformed cookie is skipped, nameless=valuesegments are dropped, and the header is rejected only when no cookie in it is usable - Add
CookieHeader.getCookies(name), every cookie with that name in order, byte-identical duplicates included Set-Cookiedecode is strict: a malformed attribute rejects the cookieDomainis normalized per RFC 6265 5.2.3: the leading dots are stripped and the host is lower-cased. An all-dotsDomainis rejectedMax-Ageis a strict decimal integer per RFC 6265 5.2.2, so a value such as0xFFis rejected
- BREAKING:
- feat!: Rebase
HeadersonHeaderStore- BREAKING:
HeadersandMutableHeadersare notMaps. Read withheaders[name],headers(accessor),getortryGet. Write withHeaders.build,transform, andMutableHeaders.set,add,removeandassign. TheHeaders.x[headers]form, theHeaderextension type andHeadersBaseare gone - BREAKING:
Headers.fromMapthrowsFormatExceptionfor a name that is not a token or a value with CR, LF or NUL - BREAKING:
HeaderAccessortakes aHeaderName.ReadOnlyAccessorhas an abstractdecode, and an accessor built from a function extendsFunctionAccessor - BREAKING:
Request.targetholds the path and query as aRequestTarget. An adapter answers 400 to a malformed one - New package
relic_headers, re-exported by relic_core:HeaderName,HeaderStore,MutableHeaderStore,MapHeaderStoreandByteHeaderStore.HeaderName.customtakes a lowercase token - Typed headers decode from the wire bytes.
HeaderCodec.bytesandHeaderCodec.fieldstake a parser over bytes, andHeaderCodec.singleand the text constructors stay - The
Headers.xHeaderstring constants are deprecated in favour ofHeaderName.x
- BREAKING:
Bodies and forms
- feat!: The
Bodyframes every response- BREAKING:
Content-Length,Content-Typeand the chunked coding come from theBody. Setting them on the response headers has no effect - BREAKING:
BodyTypehas no const constructor. It carries Content-Type parameters such asboundaryinparameters, andBody.fromDataandBody.fromDataStreamtake aparametersargument - The
Bodyconstructor is public and takesbytes,streamoropen. A body built withopenopens only when read - Add
Body.bytes,Body.readAll()andBody.consume().read(maxLength:)rejects a body whose known length is over the limit without reading it - Add
BodyType.fromContentType, the type of a body sent with aContentTypeHeader - A HEAD request gets the same
Responseas GET. The adapter sends its length and type and no body
- BREAKING:
- feat: Add HTML form and multipart parsing (#380) - closes #379
- Add
req.urlEncodedForm(),req.multipartForm()andreq.formData(), which picks the parser from the request Content-Type - Add
req.multipart()to stream parts without aggregating them. Each part is aMultipartFieldPart,MultipartFilePartorMultipartOtherPart - Read fields through accessors such as
IntFormField('age')withform.fields.get,tryGetandgetAll, and files throughFormFile. A missing field throwsMissingFormFieldException, a value that does not decode throwsInvalidFormFieldException FormLimitscaps body size, part, field and file counts, and field and file sizes. Going over one throwsFormLimitExceededException, whoselimitnames theFormLimit- Uploads go to
MemoryUploadStorageby default.TempUploadStoragein relic_io writes each upload to its own directory. On POSIX systems the directory has mode 0700. On Windows it inherits the permissions of its parent, and the default parent, the user's temp directory, is private to that user. CallMultipartFormData.dispose()to delete them - Upload filenames are reduced to their basename, with control and bidi formatting characters removed.
.,..and an empty filename give a nullfilename.filename*is ignored, per RFC 7578 - The server answers an uncaught
FormExceptionwith itsstatusCode, which is 400, 413 or 415. When parsing fails it also sendsConnection: close, as the rest of the body may be unread
- Add
- fix: A 206 range response defaults its Content-Type to application/octet-stream
Routing
- fix!: A HEAD request to a path without a HEAD route runs its GET route (RFC 9110 9.1)
- BREAKING:
Router.lookup(Method.head, ...)returns the GET route of such a path, andMethodMiss.allowedlists HEAD beside GET. A GET handler that must not run on HEAD checksrequest.method - BREAKING:
RouterMatchhas no public constructor, andLookupResulttakesT extends Object - A
HijackorWebSocketUpgradeanswering such a HEAD gets 405.RouterMatch.headFallbackmarks the match andRouterMatch.registeredlists the path's own methods
- BREAKING:
- refactor!: Drop
NormalizedPathinterning (#375) - fixes #118, #342, closes #344- BREAKING:
NormalizedPath.internedis removed. Construction does not cache, so there is no per-isolate cache to size and no input that can thrash it - Add
Router.lookupUri(method, url), the entry point for request routing. It derives the path withNormalizedPath.fromUriand looks it up withlookupPath
- BREAKING:
- fix:
RelicApp.run(backtrack: false)androuteWith(backtrack: false)look routes up without backtracking - fix:
Request.forwardTokeeps thebacktrackanduseHostWhenRoutingoptions of the original
WebSockets
- feat:
FramedWebSocketframes RFC 6455 over anyStreamChannel<Uint8List>. The server upgrades through the adapter whencapabilities.webSocketis set and frames overhijackotherwise. With neither it answers 501 - fix: A
WebSocketUpgradeanswers a request other than GET with 405
Adapters and serving
- feat!: Replace the request stream with an exchange-based
Adapter- BREAKING:
Adapteris an interface withlisteners,capabilitiesandstart(sink). It hands overAdapterExchangeobjects withrespond,hijack,upgradeWebSocketandabort.Adapter.requests,Adapter.portandAdapterRequestare gone. The port is onlistenersand onRelicServer.port. The toolkit for writing an adapter is inpackage:relic_core/adapter.dart - BREAKING:
IOAdapter.port,requests,respond,hijack,connectandIOAdapterRequestare gone - BREAKING:
HttpResponseExtension.applyHeaders(headers, body)isapplyFraming(headers, framing) - BREAKING:
HijackCallbackreceives aStreamChannel<Uint8List> - BREAKING:
hijackthrowsHijackRefusedwhen the request body is chunked and not read to its end - BREAKING:
Request.protocolVersionisRequest.protocol, anHttpProtocol - BREAKING:
RelicWebSocketimplementers providedone, andtryCloseaccepts 1001 - BREAKING:
RelicServer.close()waits for the exchanges in flight and sends 1001 to every WebSocket.close(grace:)forces the close after a deadline, andclose(force: true)ends a graceful close that is still waiting.RelicApp.closetakes the sameforceandgrace - Add
Request.cancelled, a future that completes when the client went away before the response finished. The dart:io adapter sees that only once something was written - Hijacked and upgraded connections count in
connectionsInfo(), a graceful close drains them, andclose(force: true)destroys them
- BREAKING:
- feat: New package
relic_native, a Relic adapter on a Zig HTTP server with TLS, WebSockets and hijacking, prebuilt for Linux, macOS and Windows on x64 and arm64. Its own CHANGELOG describes it - fix: The dart:io adapter closes the connection after a request that lists
closein any Connection line, also beside a laterkeep-alive, which won in dart:io'spersistentConnection
Security
- fix!: Address security audit findings (#369)
- BREAKING: Cross-origin WebSocket upgrades are rejected with 403 by default. Pass
WebSocketUpgrade(..., allowAnyOrigin: true)to accept them. Only the host is compared, since a TLS-terminating proxy changes scheme and port - BREAKING: A header name that is not a token, or a value with CR, LF or NUL, throws
FormatExceptionwhere it is set - BREAKING: Malformed auth headers are rejected, and so are MIME type parts that are not tokens, which
io.ContentTypetook separately and so slipped past the CR and LF check on other header values - The request path is split into segments before percent-decoding, so an encoded separator (
%2F) cannot introduce a path boundary that no upstream proxy saw.NormalizedPath.fromUrinames the safe conversion - The path is normalized before the routing host is prepended, so a path resolving upwards cannot pop the host and select another virtual host
- Auth headers are parsed in one pass by the linear header scanner, with no quadratic backtracking on a long value, and text between auth-params is rejected instead of skipped
Content-Dispositionparameter values andAuthenticationHeaderchallenge parts are escaped and validated, so a quote in a filename or realm cannot end the value and graft on another parameter or challenge- Multi-range responses are streamed lazily and the range count is capped, so a short request cannot ask for many times the file size
- Multipart boundaries are drawn from a cryptographic generator instead of about 20 bits from
Random - A response that fails to write gets a 500, or an aborted connection once its head is out, instead of a client left waiting
use()on a catch-all route applies to the prefix itself, so/apidoes not bypass the middleware that/api/keysruns- Add
Token68for the RFC 9110token68form, used to validate a single-tokenWWW-Authenticatechallenge - docs: The static file handler serves every file in its directory, dot files included. The documentation no longer says it filters hidden files
- BREAKING: Cross-origin WebSocket upgrades are rejected with 403 by default. Pass
Other changes
- build!: The minimum Dart SDK is 3.10.0
- perf!: A sync response reaches the adapter without a Future, and a
ContextPropertytakes its slot once- BREAKING: The routing handler and
respondWithreturn a sync handler'sResponseas is. A handler that throws before its firstawaitthrows to the caller - BREAKING: A
ContextPropertyholds its slot for the life of the isolate. Create each one once, as a global
- BREAKING: The routing handler and
- feat: Add
httpDate().httpDate,logMessageandlogRequestsread the time throughpackage:clock, sowithClockcontrols them
1.2.0 #
- feat: Make
NormalizedPathinterning cache configurable (#343)- Introduce abstract
Cache<K, V>interface - Add
NoCacheimplementation for high-cardinality workloads LruCachenow implementsCacheNormalizedPath.internedcan be swapped to anyCacheimplementation
- Introduce abstract
- feat: Add
staticChangeCountand VM service extension toDeveloperTools(#341) - feat: Add
DeveloperToolsclass toRelicApp(#340)
1.1.0 #
1.0.0 #
Relic is now considered stable and production-ready! 🎉
0.15.0 #
- feat: Add virtual host routing support (#322)
- Add
useHostWhenRoutingparameter torouteWith()middleware - Add
useHostWhenRoutingparameter toRelicApp - When enabled, routing uses
{host}{path}for route matching
- Add
- feat: Add
paths,toString(), andtoDot()to PathTrie for debugging (#320) - feat: Add
forceparameter to serverclose()method (#317) - refactor: Restructure into multi-package workspace with relic_core, relic_io, and relic packages
0.14.0 #
- feat!: Add optional consume flag to attach (#309)
- BREAKING:
attachnow throwsArgumentErrorwhen called with a tail path (/**), unlessconsume: trueand the attached trie/router has a single value at the root (isSingle) - BREAKING:
groupnow throwsArgumentErrorwhen called with a tail path - Add
consumeflag toattachthat resets the attached trie's root after attachment - Add
isSingleproperty to check if a trie/router has only a single root value/route - Allow
attach(..., consume: true)at tail paths (/**) when the attached trie/routerisSingle - Update
injectAtto useattach(..., consume: true), still enabling injection at tail paths for simpleHandlerObjects (those adding a single handler at the root ('/'))
- BREAKING:
0.11.0 #
- feat!: Add typed accessor for query and path parameters (#288)
- feat: Introduce ConnectionInfo (#273)
- feat: Add IPAddress class (independent of dart:io) (#272)
- refactor!: Simplify ContextProperty interface
- refactor!: Disallow url rewriting in Request.copyWith (#289)
- refactor!: Use named ctors on all header classes (#283)
- refactor!: Avoid repeating ctor name on parameter (#282)
- fix!: Remove stale arguments from Request and Response class (#274)
- fix: Don't overwrite Content-Length when set as header (#291)
0.10.0 #
- refactor!: The Great Simplification (#264)
- Merged
RequestContextintoRequestby moving the token property HandledContextrenamed toResult- Merge
ResponseContextintoResponse(now implementsResult) - Removed
respond(),hijack(), andconnect()methods - handlers can construct and returnResults directly - Updated handler signatures:
Handler = FutureOr<Result> Function(Request req) - Consolidated context classes into single file using part files
- Updated all examples and tests
- Significant simplification of the class hierarchy by eliminating the:
Context,RequestContext,RespondableContext,HijackableContext,ConnectableContext, andResponseContextinterfaces- Renamed
ConnectionContexttoWebSocketUpgrade(now extendsResult) - Renamed
HijackedContexttoHijack(now extendsResult)
- Merged
0.9.2 #
0.9.1 #
- feat: Add async RelicServer.connectionsInfo() method (#255)
- Adds a
connectionsInfo()method toRelicServerthat returns the current number of active, closing, and idle connections. - A new
ConnectionsInfotypedef is introduced as a record type withactive,closing, andidlefields.
- Adds a
0.9.0 #
- refactor!: Context renaming (#251)
Renames core context types for improved clarity and consistency:
NewContext→RequestContextConnectContext→ConnectionContextHijackContext→HijackedContext- Base class
RequestContextrenamed toContext
- chore!: Upgrade sdk to ^3.7.0 (#239)
- feat: Introduce MultiIsolateRelicServer (#216)
Implements multi-isolate support for
RelicServerto enable concurrent request handling across multiple CPU cores. AddsnoOfIsolatesoptional named parameter toRelicServerconstructor, andRelicApp.run. - fix: Mask sensitive credentials in authorization header toString() methods (#238)
0.8.0 #
- feat!: RelicApp now supports hot-reload (#226)
- feat: Introduce RelicApp (#212)
- feat: Introduce MiddlewareObject (#211)
- feat: Introduce HandlerObject (#210)
- feat(router): Add fallback property for unmatched routes (#196)
- feat(router): Add asHandler extension to use Router
- feat: Adds support for cache busting (#192)
- feat: Support mime-type inference (#206)
- feat: Add NewContext.withRequest convenience method (#198)
- fix: Build platform correct path when serving files. (#207)
0.7.0 #
0.6.0 #
- feat!: Custom CacheControl header per file (#167)
- feat!: Distinguish between path and method miss in router lookups (#179)
- feat!: Remove automatic X-Powered-By header (#169)
- feat!: Remove unused strict flag (#181)
- feat(router): Router.group (#157)
- feat: Add operator== and hashCode on all header classes (#155)
- fix: HEAD request should match GET except for body, including Content-Length (#180)
- fix: Host header is not a Uri. Introduce an RFC3986 compliant HostHeader class (#142)
- fix: Rip out Router.staticCache (#172)
- fix: Set content length on body, not headers (#161)
0.5.0 #
0.4.1 #
0.4.0 #
- fix: Missing convenience getters and setter for Headers.xForwardedFor (#108)
- refactor!: Get rid of old context map on Message (Request/Response) (#105)
- feat: X-Forwarded-For typed header (#107)
- feat: Add ContextProperty class (wraps Expando) (#94)
- feat: Typed forwarded header (#101)
- build(deps): Bump cli_tools from 0.5.1 to 0.6.0 (#100)
- refactor!: Replace DuplexStreamChannel with RelicWebSocket (#91)
- test: Add headers constants test and rename file (#89)
- build(deps): Bump lints from 5.1.1 to 6.0.0 (#92)
- fix: Fix request/response header sets (#90)
- docs: Update router docs (#88)
- docs: Update router entry comment (#87)
- feat: WebSocket support (#84)
- feat: Store benchmark results with git notes (#79)
- feat: The routeWith middleware builder function is now generic. (#78)
- feat(Handler)!: Signature changed (#76)
- feat: Add Router.isEmpty getter (#75)
- docs: Add CONTRIBUTING.md and CODE_OF_CONDUCT.md (#69)
- feat: PathTrie wildcard and tail matching support (#70)
- feat: Router middleware (#68)
- feat!: Router now supports verb directly (#65)
- docs: Add badges for codecov, etc. (#67)
- feat: Add addOrUpdate, update, and remove to PathTrie (#63)
- feat: Support Router.attach (#62)
- feat: Allow a trie to be attached as a subtrie to another (#61)
- feat: Router class (#52)
- refactor!: Decouple from dart:io and avoid using exceptions for control-flow (#48)
- chore: Add serverpod lints (#46)
- feat!: Replace HeaderDecode with HeaderCodec to allow customization on encoding as well (#43)
- fix: Ensure cache is updated immediately (#42)
- feat!: Support typed access to custom headers (#38)
- ci: Hoist continue-on-error to job (#37)
- ci: Add test coverage (#36)
- fix!: RelicServer cannot reliably know the Uri to use to hit it (#32)
- chore: Automate publishing to pub.dev when semver tag is created (#31)
- chore: Add pull request title validation. (#30)
- refactor!: Get rid of RelicAddress. (#29)
0.3.0 #
- feat: Implements lazy loading when parsing headers to avoid unnecessary validation.
- feat: Makes address strongly typed and adds
RelicAddresstype. - fix: Resolves issue with
Content-Lengthheader conflicting withTransfer-Encoding: chunked.
0.2.0 #
- First tech preview.
0.1.0 #
- Initial version.