docs: specify planned capabilities and make the platform philosophy explicit#226
Open
OmarAlJarrah wants to merge 2 commits into
Open
docs: specify planned capabilities and make the platform philosophy explicit#226OmarAlJarrah wants to merge 2 commits into
OmarAlJarrah wants to merge 2 commits into
Conversation
Add docs/product-spec.md, a normative, implementation-neutral specification of the SDK's behavior and contracts. It states the product thesis (an HTTP-client toolkit rather than a client), the pluggable seams and their discovery rules, the immutable HTTP model, both execution-pipeline layers, and the retry, redirect, authentication, pagination, streaming, serialization, observability, configuration, and transport/async-adapter contracts as RFC 2119 requirements. Each requirement carries a stable identifier, a rationale, and a conformance-test note, and the document closes with a glossary, a conformance checklist, and a consolidated requirement index, so the SDK can be reimplemented faithfully in another language or runtime.
…xplicit Extend the product specification so it states the toolkit's platform stance as first-class principles and captures the capabilities it does not yet provide. - Add two architectural principles. The public API is platform surface for external consumers — generated clients, downstream SDKs, and applications that build on top of the core — so a primitive with no in-core caller is not dead code, and shipped surface must carry consumer-facing discoverability (SEAM-31). Interchangeable implementations of a seam must not diverge in observable results for core-owned behavior, differing only in performance and dependencies (SEAM-32). - Add a "Planned Capabilities" section defining the contract each capability must satisfy when built, its core-versus-adapter placement, and its opt-in discipline: response decompression and Accept-Encoding negotiation, a reference observability adapter, an OAuth2 token-provider adapter, a challenge-driving authentication step, an optional client-side rate limiter, a transfer-progress primitive, and an opt-in asynchronous redirect step. These are marked not yet implemented and are excluded from the current-behavior requirement index until they ship. - Correct the front matter: remove the reference to a nonexistent companion document, complete the requirement-prefix legend, and index the new current-behavior requirements.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Follow-up to the product specification (merged in #211). Two additions and one correction to
docs/product-spec.md.Platform philosophy, now first-class principles
Two architectural principles were implicit in the design but unstated in the spec:
SEAM-31): the public API is surface for external consumers — generated service clients, downstream SDKs, and application code that build on top of the core. A primitive with no in-core caller is expected on a platform and is not dead code; shipped public surface must carry the discoverability (documented contract, and a worked example for non-obvious compositions) a consumer needs to adopt it.SEAM-32): for core-owned behavior, two implementations of the same seam must produce identical observable results for the same input, differing only in performance and dependencies; a transformation like transparent decompression belongs in the core as a single authority, never baked unevenly into one adapter.Planned capabilities (new §21)
A new section specifies the capabilities the SDK does not yet provide, each with the contract it must satisfy when built, its core-versus-adapter placement, its opt-in discipline, and a tracking issue: response decompression +
Accept-Encodingnegotiation (#212), a reference observability adapter (#213), an OAuth2 token-provider adapter (#214), a challenge-driving authentication step (#215), an optional client-side rate limiter (#216), a transfer-progress primitive (#217), and an opt-in asynchronous redirect step (#218). ThesePLAN-*requirements are marked not-yet-implemented and are excluded from the current-behavior requirement index until they ship.Correction
The front matter referenced a nonexistent "companion document" and its requirement-prefix legend omitted eight subsystems; both are corrected, and the new current-behavior requirements are added to the consolidated index.
Docs-only; no code or build changes.