io library

Serving an HttpsServer with dart:io.

A separate library from trust_tasks_https.dart because dart:io does not exist on the web, and the client — which a browser or Flutter web app may well want — should not lose the web for the server's sake.

Classes

BearerAuthenticator
Resolves a bearer token to the VID it authenticates (§3).
HttpsClient
A client for the HTTPS binding (bindings/https/0.2).
HttpsReply
The server's answer.
HttpsRequest
An HTTP request, as far as this binding needs one.
HttpsServer
A Trust Tasks server for the HTTPS binding (bindings/https/0.2).
HttpsTransport
The TransportHandler for one HTTPS exchange.
RequestContext
What a handler is told about the exchange.
StaticBearerAuth
A BearerAuthenticator backed by a fixed token → VID map. For demos and tests; §3 says a production deployment SHOULD bind tokens to identifiers under a controlled trust framework instead.

Enums

ResponseBinding
Which binding of a response to its request did not hold.

Constants

attributionRequiredWireMessage → const String
Wire message for the attribution gate. See HttpsServer.requireAttribution.
bindingUri → const String
The binding's stable identifier (bindings/https/0.2 §1). It never appears on the wire; HTTPS has no envelope to carry it.
defaultClientTimeout → const Duration
Default budget for one exchange, connection included.
defaultRequestTimeout → const Duration
Default wall-clock budget for one request, body read included. A request still open after this is wedged, and holding it is what a slowloris wants.
internalErrorWireMessage → const String
Wire message for a handler that threw something other than a Refusal.
malformedBodyWireMessage → const String
Wire message for a body that is not a Trust Task document at all, and for the suppressed identityMismatch answer (§8.1) — the same words for both, so the two cannot be told apart (SPEC §12.4).
maxBodyBytes → const int
Largest request body the server reads (SPEC §12.2). Trust Task documents are small, and the body is parsed before the sender is authenticated, so an unbounded read would be a pre-authentication memory exhaustion vector.
trustTasksPath → const String
The request path, relative to the Trust-Task base (§2, §6.1).

Functions

handleIoRequest(HttpsServer server, HttpRequest request, {Duration requestTimeout = defaultRequestTimeout}) → Future<void>
Answer one dart:io request with server — for an application that owns its own HttpServer and routes only some paths here.
newUrnUuid() → String
A fresh urn:uuid: identifier (UUID version 4).
routingKey(String typeUri) → String
The routing key for a Type URI: #request and no fragment route alike, #response keeps its fragment so a response document never reaches a request handler (§4.4.1 item 1).
serve(HttpsServer server, {Object address = '127.0.0.1', int port = 0, SecurityContext? securityContext, Duration requestTimeout = defaultRequestTimeout}) → Future<HttpServer>
Bind address:port and answer every request with server.
statusForCode(String code) → int
Map a framework error code to its HTTP status, per the binding's §4 table.

Exceptions / Errors

DuplicateAbsorbedException
The consumer had already accepted this document (§5.1) and returned no result: 202 while the first execution runs, 204 once it has finished with nothing retained. Not a failure — the task did not fail, it already happened, or is happening.
HttpsClientException
Why HttpsClient.send did not return a response document.
HttpStatusException
A non-2xx answer with no trust-task-error body: a proxy, a 401, a bare 500. §4.1: this establishes nothing about the document's state. Retry by re-sending the same bytes (SPEC §8.4).
ResponseDecodeException
A 2xx body that is not the document this client can accept.
ResponseMismatchException
A response that does not belong to the request that was sent.
ResponseProofException
A HttpsClient.responseVerifier is configured and the response's proof is missing (missing) or does not verify.
TransportException
The exchange never produced an answer: a connection failure or timeout. Like HttpStatusException, not a statement about the document (§4.1).
TrustTaskErrorException
The server refused with a trust-task-error document. error carries the framework code, which is authoritative; httpStatus is informative (§4).