Skip to main content

Server-side SDK reliability

This page is the shared reliability contract for all backend / server SDKs (.NET, Go, PHP, Ruby, Java, Python, Rust, and Node). It is not .NET-specific.

Language-specific APIs, package versions, and code samples live under each SDK’s own docs (linked below). For browser and mobile SDKs, see Client-side reliability.

Which filters each SDK evaluates locally (versus the Definitions worker), and what happens for unknown filters, is documented in the SDK × filter matrix. Runtime version floors live on Support floors.

Shared contract​

Every server SDK should:

  1. Verify raw signed bytes — persist the exact server defs JSON and verify that payload. Never re-serialize typed models for signature checks.
  2. Surface failures — report fetch, cache, storage, signature, and JWKS errors through an error callback and a last-error / debug surface.
  3. Keep last-known-good — after one successful load, transient refresh failures must not wipe in-memory flags.
  4. Clear caches — expose APIs to delete persisted feature and JWKS snapshots.
  5. Handle key rotation — on WebSocket signing-key-updated, clear JWKS (and any JWKS snapshot), then refresh definitions.
  6. Track revision — use ETag / X-Definitions-Revision for conditional HTTP fetches. Revision is caching metadata, not part of the signature.

Raw-field names differ by language (SignedDefsJson, RawDefs, signedDefsJson, signed_defs_json); the rule is the same: verify the exact server bytes.

Choose your SDK​

SDKWhere to go
.NETReliability · Snapshot providers · Troubleshooting
GoSnapshots · Signed definitions
PHPSnapshot providers
RubyConfiguration · Signed definitions · Live updates
JavaCaching · Signed definitions · Live updates
PythonCaching · Signed definitions · Live updates
RustCaching
NodeNode.js · Configuration · SDK × filter matrix

Troubleshooting Invalid signature​

Typical pattern: cold start logs Invalid signature, then a later HTTP refresh succeeds and rewrites the snapshot.

Cause: older packages re-serialized stored feature models when verifying. Storage round-trips changed the signed JSON bytes.

Fix (any language):

  1. Upgrade to a package version that stores the raw signed defs field.
  2. Clear the persisted snapshot / cache once.
  3. Let the next successful refresh rewrite the snapshot from the definitions API.

.NET note: if typed Features and verified SignedDefsJson diverge in storage, the .NET SDK refuses the load. Details and remediation: .NET reliability and Invalid signature on startup.