KvAsm.Client
0.3.0
dotnet add package KvAsm.Client --version 0.3.0
NuGet\Install-Package KvAsm.Client -Version 0.3.0
<PackageReference Include="KvAsm.Client" Version="0.3.0" />
<PackageVersion Include="KvAsm.Client" Version="0.3.0" />
<PackageReference Include="KvAsm.Client" />
paket add KvAsm.Client --version 0.3.0
#r "nuget: KvAsm.Client, 0.3.0"
#:package KvAsm.Client@0.3.0
#addin nuget:?package=KvAsm.Client&version=0.3.0
#tool nuget:?package=KvAsm.Client&version=0.3.0
KvAsm.Client for .NET
The .NET client for KvAsm, the gRPC key-value server written in x86-64 assembly. Targets .NET 8 (LTS) and .NET 10.
Install
dotnet add package KvAsm.Client
docker run --rm -p 50051:50051 ghcr.io/asmfoundation/kvasm:0.3.0 # a server to talk to
Client and server are released together under one version number, and
both speak the kvasm.v1 protocol
(docs/PROTOCOL.md).
Usage
using KvAsm.Client;
// One long-lived client per server: it multiplexes all calls over HTTP/2
// (4 connections by default, taken in turn).
using var kv = new KvAsmClient(new Uri("http://kvasm:50051"));
await kv.PutAsync("greeting", "hello"); // true = created
string? text = await kv.GetStringAsync("greeting"); // null when missing
byte[] key = [0x00, 0xFF, 0x10];
await kv.PutAsync(key, File.ReadAllBytes("blob.bin"));
ReadOnlyMemory<byte>? blob = await kv.GetAsync(key); // empty ≠ missing
bool removed = await kv.DeleteAsync(key);
bool serving = await kv.IsServingAsync(); // grpc.health.v1
Large values: Upload and Download
Values above KVASM_MAX_VALUE_BYTES (1 MiB by default), up to
KVASM_MAX_UPLOAD_BYTES (64 MiB by default), move as streams of chunks,
each end checking the CRC-32C of the bytes:
// From memory (sent without copying) or from a stream (one chunk in memory at a time).
UploadResult up = await kv.UploadAsync(key, bytes); // Created, Length, Crc32C
await using (FileStream file = File.OpenRead("video.mp4"))
{
await kv.UploadAsync(key, file); // seekable: length from the stream
}
byte[]? all = await kv.DownloadAsync(key); // null when missing
byte[]? part = await kv.DownloadAsync(key, offset: 1_000, length: 500);
await using (FileStream copy = File.Create("copy.mp4"))
{
DownloadResult? r = await kv.DownloadToAsync(key, copy); // TotalSize, Offset, Length, Crc32C
}
uint mine = Crc32C.Compute(bytes); // == up.Crc32C
- Atomic: readers see the old value until the upload completes, then the new one. A cancelled, refused or broken upload stores nothing.
- One version per download: a value replaced or deleted during a download is still read whole as it was when the download started. Two separate downloads (for example two ranges) may see different versions.
- Never silently partial: a download that breaks, ends early or fails
its checksum throws; only a returned result vouches for the bytes (after
a failure, a
DownloadToAsyncdestination may hold a prefix). - Retries: Download is retried on
UNAVAILABLEuntil its first chunk arrives; Upload, like Put, never. A transfer broken mid-way is not resumed automatically — the value may have changed; resume withoffsetonly when you know it did not. Retries recover from a connection that breaks after it was established. A server that refuses connections fails the call fast instead, because gRPC's reconnect backoff (1 s at first) outlasts the ~150 ms the attempts take (ReadAttempts). - Stalls: a transfer that makes no progress for
TransferIdleTimeout(30 s) fails withDEADLINE_EXCEEDED, however long it has run; the whole transfer is bounded byTransferTimeout(10 minutes). GetAsyncof a value above the server'sKVASM_MAX_VALUE_BYTESfails withRESOURCE_EXHAUSTED("read it with Download").- No garbage per chunk: Upload refills one message object for the whole
call and serializes it straight into gRPC's write buffer; Download parses
every message into a pooled frame whose bytes sit in an
ArrayPoolbuffer until they are checksummed and written. A 1 MiB download used to allocate ~1.07 MB (a message and a copy of every 64 KiB chunk); what is left per call is gRPC's own per-call state (benchmarks/results/ 2026-09-30-streaming). - Fast checksums:
Crc32Cfolds with carry-less multiplies — 256-bit (VPCLMULQDQ + AVX2, .NET 9+) or 128-bit (PCLMULQDQ) — for buffers of 256 bytes and more, the server's own algorithm, and falls back to the CRC32 instruction (x64 SSE4.2, Arm64 CRC) and then to the runtime's software path. All give identical results; measured 9% less client CPU per GB. - Several connections: a client spreads its calls over 4 HTTP/2
connections (
Connections), each opened by the first call that takes it. One connection pushes every frame through .NET's single reader and writer loop and is served by one server worker thread; four measured 2.8x (1 MiB uploads), 1.3-1.4x (downloads) and 1.4x (Gets, 64 in flight) against one, with one call at a time unchanged. - A receive window that fits the transfer: every call starts with a
16 MiB HTTP/2 receive window (
StreamReceiveWindowBytes) instead of .NET's 64 KiB, so the server never waits for credit within a transfer of a few MiB and .NET sends a fraction of its WINDOW_UPDATE frames. The price: a call whose data you read slower than it arrives may hold up to that much in memory — lower it for many concurrent downloads into slow destinations.
Options
var options = new KvAsmClientOptions
{
MaxKeyBytes = 1024, // mirror KVASM_MAX_KEY_BYTES
MaxValueBytes = 4 * 1024 * 1024,// mirror KVASM_MAX_VALUE_BYTES
MaxUploadBytes = 64 << 20, // mirror KVASM_MAX_UPLOAD_BYTES (also caps DownloadAsync in memory)
Timeout = TimeSpan.FromSeconds(2), // unary calls
TransferTimeout = TimeSpan.FromMinutes(10), // a whole upload/download
TransferIdleTimeout = TimeSpan.FromSeconds(30), // no chunk moved for this long: fail
UploadChunkBytes = 1 << 20, // 1 byte..4 MiB per upload message (fewer messages: faster)
DownloadChunkBytes = 0, // 0 = server default (64 KiB); up to 1 MiB
StreamReceiveWindowBytes = 16 << 20, // HTTP/2 receive window per call: download speed vs memory held for slow readers
Connections = 4, // HTTP/2 connections calls take in turn (1..64); 1 = a single connection
ReadAttempts = 3, // Get/Download/health retried on UNAVAILABLE; Put/Delete/Upload never
CompactLongKeys = true, // the contract; keep it on in every client
};
using var kv = new KvAsmClient(new Uri("http://kvasm:50051"), options);
To bring your own channel (TLS, interceptors), start from
KvAsmClient.CreateChannelOptions(options) and pass the channel to the
KvAsmClient(ChannelBase, options) constructor. The client does not
dispose a channel it did not create.
Errors
- Invalid input that can be checked locally throws before any network I/O:
an empty key (
ArgumentException), or a key or value over the configured limits (ArgumentOutOfRangeException). - Server and transport errors are
Grpc.Core.RpcException— every one, including a connection that breaks in the middle of an upload. The status codes are listed in docs/PROTOCOL.md; for example,RESOURCE_EXHAUSTEDmeans the store is full,DATA_LOSSthat transferred bytes failed their checksum. Cancellation isCANCELLEDfor every call. - Exceptions of your own streams (an upload source, a download
destination) propagate unchanged; a source shorter than the announced
length throws
EndOfStreamExceptionand nothing is stored.
Long keys
Keys longer than 64 bytes are sent as 0xFF ‖ SHA-512(key)
(KeyCompaction), which is the cross-language contract. Short keys are sent
as-is.
Snapshots
Build a data file for KVASM_SNAPSHOT:
// Unknown count: streams to a temporary file, then atomically replaces the target.
long written = await SnapshotFile.WriteAsync("seed.kvs", ReadRecordsAsync());
// Known count: single pass to any stream.
await using var writer = new SnapshotWriter(stream, recordCount: 3);
await writer.WriteAsync("a"u8.ToArray(), "1"u8.ToArray());
...
await writer.CompleteAsync(); // without this, the file stays invalid by design
The writer enforces the server's limits at export time
(SnapshotWriterOptions), applies the long-key contract, and computes the
SipHash-2-4-128 checksum the server verifies.
Tests
docker build --target runtime -t kvasm:0.3.0 ../.. # the image under test
dotnet test --solution KvAsm.Client.slnx
- Unit tests: all 64 SipHash reference vectors, key compaction, the snapshot writer (its output must match the server tool's file byte for byte), CRC-32C (published vectors, every split, a bitwise reference, each implementation forced in turn at every length to 1,200), the streaming codecs (byte-identical to the generated messages, payloads cut into random buffer segments, unknown fields, malformed input, pool reuse) and the transfer options.
- Benchmark:
bench/KvAsm.Client.Benchmeasures Upload/Download throughput, client CPU, bytes allocated per transfer and GC counts against a running server (see its header; the A/B drivers are in benchmarks/results/2026-09-30-streaming). - Integration tests: Testcontainers starts the real image. They run
without Docker too, but are then skipped. Set
KVASM_REQUIRE_DOCKER=1to fail instead (use it in CI), andKVASM_IMAGEto test another tag. Upload/Download are tested across sizes and chunkings, streams, ranges, refusals (also through the raw generated client), cancellation, one version per download, concurrency; throughFaultProxy, a TCP proxy that resets, hangs, throttles or refuses connections at exact byte counts; and against a dedicated server with small memory and budget limits.
License
Apache-2.0, like the rest of KvAsm (LICENSE).
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Google.Protobuf (>= 3.36.2)
- Grpc.HealthCheck (>= 2.84.0)
- Grpc.Net.Client (>= 2.84.0)
-
net8.0
- Google.Protobuf (>= 3.36.2)
- Grpc.HealthCheck (>= 2.84.0)
- Grpc.Net.Client (>= 2.84.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.3.0 | 53 | 11/17/2026 |