​

Dart HTTP transport

​

The seam

• Resolve with the response for every HTTP status. A 4xx or 5xx answer is not an error at this layer; the adapter maps it.
• Fail with a CratestackTransportException when there is no answer, never with a stack-specific type.
• Send request.body exactly as given, so a signer layered above sees the bytes that go out, and add no header the request does not carry beyond what the platform adds itself.

​

One adapter per protocol

final adapter = CratestackHttpAdapter(
  CratestackDioTransport(dio),
  baseUri: Uri.parse('https://api.example.com'),
  // format: CratestackWireFormat.cbor,   // the default
  // useRustTransport: false,             // REST only
);

final client = BlogClientCratestackClient(adapter, basePath: '/cstack');

final adapter = CratestackRpcHttpAdapter(
  CratestackDioTransport(dio),
  baseUri: Uri.parse('https://api.example.com'),
  format: CratestackWireFormat.json,
);

• baseUri is the scheme, authority and optional path prefix every request path is joined onto: https://api.example.com or https://example.com/v1. A prefix is kept. It replaces dio.options.baseUrl, which the transport no longer reads.
• format is CratestackWireFormat.cbor (the default) or CratestackWireFormat.json. It sets the request body format and the Accept preference. The answer is always decoded by its own Content-Type, so an adapter set to one format still reads the other. A response of an unsupported Content-Type is a FormatException on the JSON REST adapter too; it used to hand back the raw string.
• useRustTransport (REST only) marks every request with cratestackUseRustTransportExtraKey in CratestackHttpRequest.extra, for a host interceptor that routes marked requests through the Rust runtime. It is never a header.
• cborSeqDecoder (RPC only) swaps the boundary scanner that stream() uses; see Streaming.

​

Dio is one transport

​

Errors

try {
  final board = await client.boards.get(7);
} on CratestackRestException catch (e) {
  // The server said no: e.status, e.body.
} on CratestackTransportException catch (e) {
  switch (e) {
    case CratestackTransportAborted():
      break; // the caller gave up
    case CratestackTransportUnsent():
      // never left the device: resend freely
    case CratestackTransportTimedOut() || CratestackTransportBroken():
      // may have been applied: resend only with an idempotency key
  }
}

​

Call options

final cancel = Completer<void>();
final future = client.boards.create(
  input,
  options: CratestackCallOptions(
    abort: cancel.future,
    idempotencyKey: 'create-board-42',
  ),
);
cancel.complete(); // the call throws CratestackTransportAborted

​

Streaming

​

Query encoding

• pairs go out in map order, with keys and values through Uri.encodeQueryComponent;
• a list repeats its key, tag=a&tag=b;
• a nested map nests with literal brackets, filter[kind]=x;
• every other value is its toString(), percent-encoded (a double such as 1e+21 goes out as 1e%2B21, so the + of the exponent survives);
• a null value is omitted. Dio sent a bare key.

​

Writing your own transport

class MyTransport implements CratestackHttpTransport {
  @override
  Future<CratestackHttpResponse> send(CratestackHttpRequest request) async {
    // request.method, request.uri, request.headers, request.body (the exact
    // bytes to send), request.abort (completes when the caller gives up),
    // request.extra (attributes that are not sent on the wire).
    throw UnimplementedError();
  }
}

final adapter = CratestackRpcHttpAdapter(
  MyTransport(),
  baseUri: Uri.parse('https://api.example.com'),
);

​

Known gaps

• Call options cannot carry transport attributes. CratestackHttpRequest.extra exists and a transport forwards it, but neither CratestackCallOptions nor CratestackRpcCallOptions can fill it, so a single call cannot tell the transport chain under it something that is not a header. Tracked in cratestack#1207.
• An AuthProvider refusal cannot shape its response body. The generated handler encodes any auth error as the standard {code, message} envelope, so a client cannot distinguish refusal reasons by a body member. Tracked in cratestack#1208.

​

See also

• The fespalier preset — the Riverpod surface over fespalier’s HttpTransport, with no Dio
• Migrating the Dart client to the HTTP transport
• Dart client generation — presets, flags and the Riverpod surface
• Client Runtime — how the Dio-direct and FFI-bridge paths relate