SDK Contract
Sign in with GitHub

View raw markdown

Tripswitch SDK Contract

Normative document

This document defines the required semantics and behavioral guarantees of all Tripswitch SDKs. All official SDKs MUST conform to this contract.

This document is authoritative. In the event of ambiguity between SDK behavior and this contract, the contract takes precedence.

Contract Version: 0.2 Last Updated: 2026-01-23

1. Purpose and Scope

This document defines the shared meaning, guarantees, and constraints that apply to all Tripswitch SDK implementations, regardless of programming language or runtime environment.

This contract exists to:

  • Preserve consistent behavior across SDKs
  • Prevent accidental semantic drift
  • Allow SDKs to evolve independently without breaking core guarantees

This document does not define:

  • SDK ergonomics or API surface details
  • Language-specific concurrency models
  • Implementation strategies

SDKs are clients, not policy engines. The Tripswitch server remains the source of truth.

2. Core Domain Model

This section defines the canonical domain concepts shared across all SDKs.

2.1 Breaker

A breaker represents the evaluated health of a dependency over time.

Breaker states are:

  • closed
  • open
  • half_open

Breaker state is:

  • Evaluated exclusively by the server
  • Observed by SDKs
  • Never inferred or predicted locally

SDKs MUST NOT derive or simulate breaker state.

2.2 Sample

A sample represents one logical attempt or observation reported by a client.

  • Each sample corresponds to exactly one attempt
  • Retries represent distinct attempts unless explicitly idempotent
  • Samples affect evaluation windows and breaker state transitions

SDKs MUST preserve sample semantics when sending data.

2.3 Time

Samples include a timestamp representing when the event occurred from the client’s perspective.

  • SDKs MUST send a timestamp with each sample
  • The server determines authoritative ordering and evaluation time
  • Server-assigned timestamps are authoritative

SDKs MUST NOT assume acceptance implies immediate evaluation.

3. Behavioral Invariants

This section defines required behavioral guarantees that apply to all SDKs.

Invariant: Sample Semantics

Rule SDKs MUST NOT introduce additional samples beyond what the caller intends to report.

Rationale Breaker evaluation depends on accurate attempt counts. Inflated sample counts distort rolling windows and can cause premature breaker transitions.

Clarifications

  • Retries represent distinct attempts unless explicitly idempotent
  • Automatic retries MUST preserve sample identity when idempotency is used
  • SDKs SHOULD prefer surfacing errors over silent retries

Invariant: Evaluation Authority

Rule SDKs MUST NOT derive, predict, or infer breaker state.

SDKs MAY apply server-provided breaker state and parameters locally (e.g. enforcing allow_rate for half_open breakers).

Rationale Breaker evaluation depends on global context unavailable to clients.

Invariant: Failure Handling

Rule
Transport- or SDK-level failures MUST NOT be interpreted as breaker state changes.

SDKs MUST NOT:

  • Assume a breaker is open due to local send failures
  • Suppress or reinterpret failures as successful samples

Rationale
Local failures reflect client-side conditions and do not imply dependency health.

4. Allowed Divergence

SDKs MAY diverge in implementation details where such divergence does not alter the semantics defined in this contract.

Allowed areas of divergence include:

  • Concurrency and execution model
  • HTTP client configuration
  • Error representation (e.g. typed errors vs exceptions)
  • Default retry behavior, provided sample semantics are preserved

SDKs MUST document any divergence that affects observable behavior or developer expectations.

5. Error Taxonomy

All SDKs MUST classify errors into the following canonical categories:

  • Authentication errors
  • Authorization errors
  • Rate limiting
  • Invalid requests
  • Not found
  • Conflict
  • Transport failures
  • Server faults

The exact error representation MAY vary by language, but the semantic meaning of each category MUST remain consistent across SDKs.

SDKs MUST NOT introduce new semantic error categories without updating this contract.

6. Idempotency and Retries

SDKs MAY expose idempotency mechanisms to allow callers to retry a logical sample safely.

  • An idempotency key identifies a single logical sample attempt
  • Retries using the same idempotency key MUST NOT create additional samples
  • Retries without idempotency represent distinct attempts

SDKs MUST NOT retry requests in a way that violates sample semantics.

Automatic retries, if present, MUST be:

  • Bounded
  • Documented
  • Semantically safe

7. Versioning and Compatibility

This contract is versioned independently of SDKs.

  • Contract changes precede SDK changes
  • Breaking contract changes require an explicit contract version bump
  • SDKs MUST declare which contract version they conform to in code (e.g. a public constant, metadata, or documentation)

8. Conformance Checklist

An SDK is considered conformant if it:

  • Implements all required endpoints
  • Preserves all behavioral invariants defined in this contract
  • Maps errors to the canonical error taxonomy
  • Documents any allowed divergence
  • Declares the contract version it conforms to

9. Amendments

Changes to this contract are deliberate and explicit.

All amendments MUST:

  • Be documented
  • Preserve backward compatibility where possible
  • Clearly describe behavioral impact and affected SDK behavior

Contract Version 0.2

  • Clarified Evaluation Authority to explicitly allow client-side application of server-provided half_open parameters (e.g. allow_rate).
  • Expanded the canonical error taxonomy to include Not Found and Conflict.
  • Clarified acceptable mechanisms for SDKs to declare contract version conformance.

End of document.