Language-agnostic specifications for Traffical SDKs - schemas and test vectors
npm install @traffical/sdk-specLanguage-agnostic specifications for implementing Traffical SDKs.
This repository contains:
- JSON Schemas - Type definitions for configuration bundles and events
- Test Vectors - Deterministic test fixtures for validating SDK implementations
All Traffical SDKs must implement these specifications to ensure consistent behavior across languages.
The complete configuration bundle that SDKs fetch and cache. Contains:
- Organization and project identifiers
- Hashing configuration (unit key, bucket count)
- Parameters with defaults and layer membership
- Layers with policies and allocations
- Conditions for targeting
Event payloads sent to the Traffical API:
- Exposure events (when a user is assigned to a variant)
- Track events (custom user actions)
Local project configuration file (.traffical/config.yaml) schema.
The test-vectors/ directory contains deterministic test fixtures for validating SDK implementations.
All Traffical SDKs must produce identical results for the same inputs:
1. Hashing consistency - FNV-1a hash produces the same bucket across all implementations
2. Resolution correctness - Parameter resolution follows the layered priority system
3. Condition evaluation - Context predicates are evaluated identically
``
test-vectors/
├── fixtures/
│ ├── bundle_*.json # Config bundles to test against
│ └── expected_*.json # Expected outputs for each bundle
└── README.md
Each SDK implementation should:
1. Load the bundle JSON
2. For each test case:
- Compute buckets and verify against expectedHashing
- Resolve parameters and verify against
Traffical uses FNV-1a (32-bit) for bucket computation:
`
Input: unitKeyValue + ":" + layerId
Hash: FNV-1a(input) >>> 0
Bucket: hash % bucketCount
- Input: "user-abc:layer_ui"
- FNV-1a hash:
- Bucket (mod 1000):
`
FNV_OFFSET_BASIS = 2166136261
FNV_PRIME = 16777619
hash = FNV_OFFSET_BASIS
for each byte in input:
hash = hash XOR byte
hash = hash * FNV_PRIME
return hash >>> 0 // Ensure unsigned 32-bit
``
| Language | Repository |
|----------|------------|
| JavaScript/TypeScript | traffical/js-sdk |
| Go | Coming soon |
| Java | Coming soon |
MIT License - see LICENSE for details.