SocketJack 2026.15.0

⚡ SocketJack 2026

Typed messages · Reliable UDP · HTTP & WebSockets · One-port protocol hosting

📦 Install · ✨ What's new · 🧭 Features · 📚 Documentation

SocketJack is a .NET networking library for sending typed objects, hosting HTTP APIs, connecting browser clients, and routing peers. It supplies framing, serialization, segmentation, compression, callbacks, and connection metadata so you can build the application on top.

📦 Install

dotnet add package SocketJack --version 2026.15.0

🚀 First connection — typed TCP messages

Register a callback before connecting. Run the server and client in separate applications, or together while experimenting:

using System;
using SocketJack.Net;

// This example deliberately accepts anonymous text, with peer routing disabled.
var options = new NetworkOptions { UsePeerToPeer = false };
options.Authorization.AnonymousMessageTypes.Add(typeof(string));
using var server = new TcpServer(options, 12345);
server.RegisterCallback<string>(e =>
{
    Console.WriteLine(e.Object);
    e.Connection.Send("Received ✓");
});
server.Listen();

using var client = new TcpClient(new NetworkOptions { UsePeerToPeer = false });
client.RegisterCallback<string>(e => Console.WriteLine(e.Object));
if (await client.Connect("127.0.0.1", 12345))
    client.Send("Hello, SocketJack!");
Console.ReadLine();

Keep the host application running while connections are in use. Use matching serialization and compression settings on both endpoints.

✨ What's new in 2026.14

This release refreshes the documentation and publishing checks for the recent networking updates. Read each feature below for behavior, configuration, and limits.

🛡️ Authentication and safe type activation

SafeMode is enabled by default. Register each application contract assembly and SocketJack automatically SHA-256 hashes its reflected DLL location (or matching embedded DLL resource). Type names and client DLL fingerprints must match the server during handshaking. No server fingerprint is returned. Invalid clients are disconnected before typed messages are dispatched.

Authentication is a separate step. A server verifies credentials, then calls SetAuthenticatedPrincipal over encrypted TLS. Peer redirects and control messages require explicit authorization callbacks. Administrative DTOs require the Administrator role plus an operation policy and cannot be redirected between peers. Remote CLR reflection endpoints reject invocation. Allowlisted constructors, setters, converters, and application handlers remain trusted code.

Configuration, login flow, limitations and migration

🧭 Feature explorer

📡 Reliable UDP — fragments, acknowledgments, retries & ordering

UDP_Reliable adds a reliable session layer to SocketJack UDP. Ordinary UDP remains the default, and existing applications opt in explicitly.

• ✓ Indexed reassembly: fragments are placed at their indexed positions; duplicate packets are suppressed.
• ↻ Selective retries: missing data is retransmitted, with bounded queues and receiver backpressure.
• ⇄ Independent delivery: the default allows complete messages to proceed independently; callbacks must be thread-safe.
• ≡ Ordered delivery: set Ordering = true when callbacks must follow admission order.
• 📊 Statistics: inspect wire bytes, retries, queued payload, and smoothed RTT through ReliableStatistics.

using SocketJack.Net;
using SocketJack.Serialization;

var options = new NetworkOptions
{
    Serializer = new BinarySerializer(),
    UdpReliable = new UdpReliableOptions
    {
        Ordering = false,
        DatagramSize = 1200,
        BufferSize = 32768
    }
};
var client = UDP_Reliable.CreateClient(options);

Configure a matching reliable server with its own options instance. SendAsync waits for remote transport acceptance, not successful application processing or durable storage; use an explicit application reply for that guarantee.

Limits: reliability does not provide encryption. The recorded loopback benchmarks did not meet the goal of outperforming TCP on both throughput and latency. Choose this transport for its delivery behavior and measure your own workload.

📖 API, configuration & limits

🧩 Serialization — JSON by default, compact binary when selected

System.Text.Json remains the default. Select SocketJack.Serialization.BinarySerializer through NetworkOptions.Serializer on both peers to use SocketJack's versioned SB wire format.

This is a custom serializer, not BinaryFormatter. Register message callbacks or whitelist message types before sending, including nested types where required. Serializer and compression choices must agree between endpoints.

📂 Stream & file transfer — bounded chunks and verified completion

Reliable UDP supports stream/file transfers without materializing an entire file as one message. Transfer frames use bounded chunks, 64-bit byte offsets, SHA-256 verification, and explicit destination acceptance.

The per-I/O buffer cap is 32 KiB, not a total-file size limit. Whole-object messages still have separate memory budgets. Configure delivery timeouts and destination handling for your workload; transport acceptance alone does not establish successful storage.

📖 Transfer APIs and receiver requirements

🔐 SSH.NET 2026.0.0 — SFTP client integration

SocketJack now references SSH.NET 2026.0.0. SocketJack.Net.SftpClient wraps SSH.NET for remote file operations:

• 🔑 Authentication: password and private-key options, including encrypted-key passphrases.
• 📁 Directory operations: list, create, change, rename, and delete.
• ⇅ File operations: upload/download with progress callbacks; open read/write streams.
• ⚙️ Metadata: inspect and update SFTP file attributes.
• ⏱️ Configuration: host, port, username, and connection timeout through SftpClientOptions.

The convenience async methods wrap synchronous work with Task.Run; they are not a separate native asynchronous transport. SFTP server hosting requires an ISftpServerBackend implementation; SocketJack does not bundle an SSH server.

📖 SFTP implementation · 📦 SSH.NET package

🟦 TypeScript — generate clients from mapped HTTP routes

HttpServer.GenerateTypeScriptClient() emits a dependency-free TypeScript client from the server's currently mapped routes. Typed request bodies become TypeScript aliases, path variables become required inputs, and resolvable whitelisted message classes can be emitted as interfaces for WebSocket use.

using System.IO;
using SocketJack.Net;

var server = new HttpServer(port: 8080);
server.Map("GET", "/health", (connection, request, ct) => new { status = "ok" });

File.WriteAllText("SocketJackClient.ts", server.GenerateTypeScriptClient(
    new TypeScriptClientOptions
    {
        ClassName = "ApiClient",
        BaseUrl = "http://localhost:8080",
        IncludeWebSocketTypes = true
    }));

Generate after registering routes. Review generated contracts whenever the server API changes.

🔌 TCP & ordinary UDP — typed callbacks, replies and broadcasts

TcpClient / TcpServer provide framed object messaging over TCP. UdpClient / UdpServer provide the typed callback model for datagrams. Use RegisterCallback<T>() to receive a message, reply through its connection, or broadcast through the server.

TCP suits ordered streams and general application traffic. Ordinary UDP suits discovery and lightweight updates where applications tolerate loss. Select reliable UDP explicitly when you need its session delivery semantics.

🌐 HTTP & WebSockets — APIs, static files and realtime clients

HttpServer maps methods and paths to handlers, supports typed request bodies, and serves files, directories, redirects, uploads, and streaming responses. WebSocket clients and servers connect browser applications and native peers to typed callbacks and peer metadata.

var server = new SocketJack.Net.HttpServer(port: 8080);
server.Map("GET", "/health", (connection, request, ct) => new { status = "ok" });
server.MapDirectory("/static", @"C:\wwwroot");
server.Listen();

🔀 Protocol multiplexing — multiple protocols on one listener

MutableTcpServer detects and dispatches supported protocol traffic on one listening port. The repository includes HTTP, WebSocket, native SocketJack, RTMP, SQL/TDS, and FTP surfaces, with custom protocol handlers for extensions.

Every protocol is disabled by default. Add only the required names to the server's EnabledProtocols whitelist before listening:

var server = new MutableTcpServer(8080);
server.EnabledProtocols.Add(MutableTcpProtocols.Http);
server.EnabledProtocols.Add(MutableTcpProtocols.WebSocket);
server.Listen();

SQL/TDS additionally defaults to loopback-only access. Use server.SqlOptions.RemoteAccess to explicitly allow private-network or public clients, or add individual addresses to AllowedRemoteIpAddresses. SFTP runs over SSH and needs the separate backend described above; it is not supplied by ordinary TCP protocol detection.

🤝 Peer routing & metadata — discovery and coordinated delivery

Associate identity and metadata with peers, update that metadata during a connection, and route messages through a coordinating server. This supports room lists, capability registries, service discovery, and peer-directed application traffic. Server-mediated redirects are distinct from a direct peer connection.

🗄️ Data & streaming — SQL surfaces, management routes and RTMP

The repository includes data-server primitives, SQL/TDS handling, HTTP management routes, and RTMP ingest/relay support. These components can support embedded administration, application records, and media workflows alongside native SocketJack messaging.

See the examples and component source for configuration and supported protocol behavior.

🖥️ WPF companion — live controls and remote input

The separately versioned SocketJack.WPF package shares FrameworkElement content as a live image stream and forwards mouse, wheel, text, and keyboard input.

using SocketJack.WPF;

IDisposable shareHandle = GameCanvas.Share(client, remotePeer, fps: 10);
IDisposable viewerHandle = client.ViewShare(SharedImage, sharerPeer);

This fragment assumes an existing WPF application, connection, and peer references. Dispose the handles to stop sharing/viewing. The current core publishing workflow does not republish the WPF companion.

✅ Publishing & dependency checks — short-lived credentials

The release workflow builds on Linux and Windows, packs SocketJack, and publishes to NuGet and GitHub Packages. NuGet Trusted Publishing exchanges GitHub's workflow identity for a temporary credential using NuGet/login.

Before packaging, restore audits direct and transitive dependencies. Known vulnerability warnings and audit-feed failures block the core release. Package audits report known advisories at the time of the check; they do not prove the absence of all security defects.

📚 Documentation

🗺️ Repository map

⚖️ License: MIT