Skip to content

1. Scope And Architecture

Common contract table of contents

1.1 Identity

The zlink HTTP client is a companion client that lets a framework handler and management tool call HTTP under the same framework error/codec/execution contract. It hides each language's representative HTTP transport stack behind a fluent builder, but it isn't a general-purpose client replacing an ordinary HTTP library. It also isn't a JSON-only client — the typed JSON path is a framework codec convenience layer laid on top of the raw HTTP path.

It isn't built from scratch. Transport is delegated to each language's representative stack, but the semantics (redirect, retry, cookie, compression, auth scrubbing) are owned directly by the wrapper, so they behave identically across the 5 languages. To this end, the native stack's automatic redirect, automatic decompression, and automatic cookie are all turned off, and the wrapper implements them.

Language Transport Stack Deliverable
cpp Boost.Beast + Asio (+OpenSSL optional) zlink::http_client (CMake, static)
dotnet System.Net.Http + SocketsHttpHandler Zlink.HttpClient (NuGet)
java java.net.http.HttpClient zlink-http-client (Gradle)
kotlin Reuses the java runtime transitively + coroutine extension zlink-http-client-kotlin (Gradle)
node undici low-level request @zlink-systems/http-client (npm)

1.2 Public Surface Rule

  • The public contract (contracts) doesn't expose a transport stack type (Beast/Asio, SocketsHttpHandler, java.net.http.*, and undici types are prohibited).
  • The public type name is unified to the ZLinkHttpClient / ZLinkHttpClientBuilder / ZLinkHttpRequestBuilder / RawHttpResponse / HttpResponse<T> / ZLinkHttpMethod family (applying language casing convention, see Per-Language Interface Definition).
  • The runtime implementation is confined to a per-language internal area (src/runtime, internal/, Runtime/) and can't be reached from the public API.

1.3 Relationship With Framework — One-Way Dependency

  • The dependency direction is HTTP client → Framework contracts. The HTTP client consumes the common Framework error model (ZLinkFrameworkException family) and codec contracts. It uses the same error classification for HTTP calls by sharing the exception hierarchy.
  • Framework core works without the HTTP client. The HTTP client is a separate deliverable; each language documents the scope of its Framework package or target dependency. The .NET split into Zlink.Framework.Contracts does not require the same binary boundary in other languages.
  • Integration connects server turns through the HTTP client execution scheduler injection point. HTTP Client §3.2 owns the completion/turn contract.
  • Typed body encode/decode shares the same codec extension as framework and stream-connector. A raw body doesn't go through the extension.

1.4 Kotlin's Position

The kotlin deliverable isn't an independent implementation — it's a thin idiom layer on top of the java runtime: it only adds a suspend bridge, DSL builder, reified generic, and Kotlin data class deserialization. The verification responsibility for the transport semantics contract falls to the java contract test.