Storine v0.3.0

Clients

Writing a client

What every official client does, and how to add one for another language.

Official clients of the Storine document API. Every SDK:

  • has no runtime dependencies (standard library only);
  • speaks the same wire protocol (protocol/PROTOCOL.md) and passes the same byte-for-byte conformance vectors (protocol/vectors/vectors.json);
  • uses the same vocabulary (RULE-DX-01 – RULE-DX-05): connect, collection, get / put / insert / replace / update / delete, find / first / count / scan, transaction, filters eq … key_prefix, field operations set / unset / add(...).min(...) / append;
  • maps money to the language's exact decimal type and never to a binary float;
  • retries writes with the same request id (applied at most once), follows cluster leader redirects and fails over between seeds;
  • is tested end to end against a real storage-server, single node and a 3-node cluster with the leader killed.
  • connects over TLS 1.3 with storines:// (or a tls_ca option: the PEM certificates to trust) and checks the server's certificate and name. TLS uses the platform's own TLS library (Rust: the tls feature, which uses the engine's own TLS crate; .NET on Windows cannot, as its TLS stack has no Ed25519).
LanguageDirectoryMoney typeTests
Python 3.8+python/decimal.Decimalpython3 -m unittest discover -s tests
TypeScript / Node.js 18+typescript/Decimal (exact, bigint mantissa)npm test
Go 1.21+go/storine.Decimalgo test -race .
Java 17+java/java.math.BigDecimalmvn test
C# / .NET 8+csharp/decimal (or BigDecimal beyond 28 digits)dotnet test
Rust 1.70+rust/storine::Decimalcargo test
PHP 8.1+php/Storine\Decimal (exact, keeps its scale)php tests/harness.php
Ruby 3.2+ruby/Storine::Decimal (exact, keeps its scale; converts to BigDecimal)ruby -Ilib test/test_vectors.rb && ruby -Ilib test/test_e2e.rb

The end-to-end tests use target/release/storage-server (build it with cargo build --release -p storage-server) or the binary named by $STORINE_SERVER; without it they are skipped.

Adding an SDK: implement §3 (values) and §5 – §6 (requests / responses) of the protocol, make every vector in vectors.json pass, then port the end-to-end suite of an existing SDK.