KvAsm.Client 0.3.0

dotnet add package KvAsm.Client --version 0.3.0
                    
NuGet\Install-Package KvAsm.Client -Version 0.3.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="KvAsm.Client" Version="0.3.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="KvAsm.Client" Version="0.3.0" />
                    
Directory.Packages.props
<PackageReference Include="KvAsm.Client" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add KvAsm.Client --version 0.3.0
                    
#r "nuget: KvAsm.Client, 0.3.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package KvAsm.Client@0.3.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=KvAsm.Client&version=0.3.0
                    
Install as a Cake Addin
#tool nuget:?package=KvAsm.Client&version=0.3.0
                    
Install as a Cake Tool

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 DownloadToAsync destination may hold a prefix).
  • Retries: Download is retried on UNAVAILABLE until its first chunk arrives; Upload, like Put, never. A transfer broken mid-way is not resumed automatically — the value may have changed; resume with offset only 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 with DEADLINE_EXCEEDED, however long it has run; the whole transfer is bounded by TransferTimeout (10 minutes).
  • GetAsync of a value above the server's KVASM_MAX_VALUE_BYTES fails with RESOURCE_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 ArrayPool buffer 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: Crc32C folds 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_EXHAUSTED means the store is full, DATA_LOSS that transferred bytes failed their checksum. Cancellation is CANCELLED for every call.
  • Exceptions of your own streams (an upload source, a download destination) propagate unchanged; a source shorter than the announced length throws EndOfStreamException and 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.Bench measures 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=1 to fail instead (use it in CI), and KVASM_IMAGE to 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; through FaultProxy, 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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