Skip to content

ZLink HTTP Client Common Contract

This document set defines the contract C++, .NET, Java, Kotlin, and Node.js HTTP clients must provide in common. The per-language document expresses this common behavior with that language's exact public type and signature.

10 Revision Candidates isn't yet a public contract. Only a promoted item is reflected in the matching contract document and every language's interface.

Table Of Contents

12 HTTP Client defines the whole boundary for registering and calling an HTTP client in the Framework. 01-09 each own the detailed contract of builder, response, execution, auth, and error, and 11 defines the item an implementation and contract test must verify.

Ch. Document Content
12 HTTP Client (Framework Contract) Canonical — identity, fluent builder, terminator (submit/async/yield + callback), turn seam, DI server surface
1 Scope And Architecture Identity, deliverable boundary, relationship with framework
2 Client Builder Contract The whole builder option set and default value table
3 Request Contract HTTP method, header/query, the 5 body sources, and exclusion rules
4 Response Contract raw/typed/download/fetch, the status ≥ 400 policy
5 Execution Model Async contract, the no-blocking rule, client lifetime
6 Redirect · Retry · Cookie Rewrite rule table, retry contract, cookie subset
7 Auth · TLS · Proxy Basic/Bearer, PEM trust/mTLS, CONNECT tunnel
8 Compression gzip/deflate transparent decompression semantics
9 Error Model The common error kind set, per-language mapping and implementation gap
10 Revision Candidates Not a contract — items under review before promotion (R1-R14)
11 Regression Test Contract Common contract case matrix, gate, coverage gap
— Per-Language Interface Cross-Reference Non-normative — a cross-reference table viewing the five languages' surfaces side by side. Doesn't fix a contract

Per-Language Public API

The exact type and signature of each language is owned by the following document.

Language Document
C++ languages/cpp
.NET languages/dotnet
Java languages/java
Kotlin languages/kotlin
Node.js languages/node

Contract Change Procedure

  1. A new behavior/public API is first registered as an R-item in Chapter 10 Revision Candidates. A revision candidate isn't a contract and doesn't become an implementation basis.
  2. Once promotion is decided, it moves to that chapter's contract body, and the 5 languages' implementation, contract test, and per-language spec are updated together. Implementing only one language first isn't allowed (the repository's public contract parity policy).
  3. A language-specific deviation (keyword avoidance delete_, kotlin DSL, etc.) is recognized only if explicitly stated as a "language deviation" section in that chapter of this canonical document.