Disruptor.Surreal 1.0.0

Disruptor.Surreal

A .NET 10 client for SurrealDB, modeled on the official Rust client. CBOR over WebSocket. Single package. No embedded mode.

Unofficial. Not affiliated with the SurrealDB project. The Disruptor.Surreal name keeps that unambiguous. MIT; contributions welcome.

Why this exists

Targeted to our design goals — not intended as a general-purpose drop-in replacement for the official SDK.

(yet. evil laugh.)

Built alongside Disruptor.Surface, an ORM/source-generator project whose transport needs drive the v1 surface here: CBOR over WS, typed bindings, server-side transactions, faithful Value-tree round-tripping for SurrealDB's wire types (RecordId, decimal, DateTimeOffset, Guid, Datetime / Duration with full nanosecond precision). Embedded is permanently out — we trust the database.

Install

The project targets net10.0. Install from NuGet:

dotnet add package Disruptor.Surreal

or add a PackageReference:

<PackageReference Include="Disruptor.Surreal" Version="1.0.0" />

Quick start

using Disruptor.Surreal;
using Disruptor.Surreal.Connection;
using Disruptor.Surreal.Values;

// One-shot connect: parse the connection string, dial WS, signin, switch ns/db.
await using var db = await SurrealClient.ConnectAsync(SurrealOptions.Parse(
    "Url=ws://localhost:8000;Namespace=test;Database=test;User=root;Password=root"));

var jaime = new SurrealRecordId("person", "jaime");

// Create a record at a known id
await db.CreateAsync(jaime, new SurrealObject
{
    ["name"] = "Jaime",
    ["age"] = 30L,
    ["joined"] = DateTimeOffset.UtcNow,   // CBOR tag 12
    ["balance"] = 1234.56m,                // CBOR tag 10
    ["session"] = Guid.NewGuid(),          // CBOR tag 37
});

// Multi-statement query with bindings
var response = await db.QueryAsync(
    "SELECT * FROM person WHERE age >= $minAge",
    new SurrealObject { ["minAge"] = 21L });
var rows = response.Take(0);  // SurrealValue (a SurrealListValue of SurrealObjectValue)

// Server-side transaction with rollback
await using var tx = await db.BeginTransactionAsync();
await tx.UpdateAsync(jaime, new SurrealObject { ["balance"] = 9999m });
await tx.CommitAsync();   // or tx.CancelAsync() to roll back

Wire format

CBOR over WebSocket using the SurrealDB-flavoured tag scheme:

Datetimes preserve full nanosecond precision via an explicit Nanos field (since DateTimeOffset only resolves to 100ns ticks).

Feature matrix

Compared against the official Rust client as the de-facto reference implementation. (Status legend: yes = supported, no = open work, partial = some sub-features only, out = permanently out of scope, n/a = no wire representation in the protocol.)

Transports

Wire format

RPC methods

Auth credentials

Value tree

Connection lifecycle

Error / diagnostics

Consumer-side mapping

Layout

src/Disruptor.Surreal/         — the library (one package)
  Auth/                          — credentials + SurrealAccessToken
  Cbor/                          — tag table, reader, writer
  Connection/                    — SurrealEndpoint, Command, Rpc{Request,Response},
                                   ISurrealConnection, SurrealWebSocketConnection,
                                   SurrealOptions, SurrealConnectionConfig,
                                   ServerVersion
  Errors/                        — exception hierarchy
  Live/                          — SurrealLiveQueryHandle, SurrealNotification,
                                   SurrealLiveQueryOptions
  Query/                         — SurrealQueryResponse, SurrealQueryStatement
  Values/                        — Value tree + scalar wrappers
                                   (SurrealDateTime, SurrealDuration, etc.)
                                   + ISurrealRecordId
  Patch.cs                       — JSON-Patch op factories
  SurrealClient.cs               — main client class
  SurrealRetryPolicy.cs          — retry-on-conflict helper
  SurrealTransaction.cs          — transaction handle (auto-cancel on dispose)
tests/Disruptor.Surreal.Tests/   — xUnit (CBOR roundtrip, endpoint parsing,
                                   value semantics, error classifier,
                                   options parsing)
samples/Disruptor.Surreal.Sample/ — runnable demo

Run the tests

dotnet test

Run the sample (needs a local server)

docker run -d --rm --name surrealdb -p 8000:8000 surrealdb/surrealdb:latest \
  start --user root --pass root memory
dotnet run --project samples/Disruptor.Surreal.Sample

License

MIT. See LICENSE.