Fomoxa.Net 0.1.4

dotnet add package Fomoxa.Net --version 0.1.4
                    
NuGet\Install-Package Fomoxa.Net -Version 0.1.4
                    
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="Fomoxa.Net" Version="0.1.4" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Fomoxa.Net" Version="0.1.4" />
                    
Directory.Packages.props
<PackageReference Include="Fomoxa.Net" />
                    
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 Fomoxa.Net --version 0.1.4
                    
#r "nuget: Fomoxa.Net, 0.1.4"
                    
#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 Fomoxa.Net@0.1.4
                    
#: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=Fomoxa.Net&version=0.1.4
                    
Install as a Cake Addin
#tool nuget:?package=Fomoxa.Net&version=0.1.4
                    
Install as a Cake Tool

Fomoxa.Net

1. Overview

Fomoxa.Net is the .NET runtime implementation of the Fomoxa protocol. It implements framing, the schema handshake, heartbeat, and a non-blocking TCP/UDP tick loop, as defined by the Fomoxa specification. The library targets netstandard2.1, so a single assembly runs on .NET 6/7/8/9 and inside Unity 2021+ under IL2CPP. The library contains no wire-format codec, no threading, and no async/await usage.

2. Authoritative references

The documents below define the behavior of this library. Where this library and another Fomoxa SDK disagree, those documents decide.

Document Scope
RFC-0001 Protocol rationale and design decisions
RFC-0002 Wire format: primitives, string, bytes, model, array, enum, version differences
RFC-0003 Conformance: the test vectors an implementation must pass
Implementation guide Framing, handshake, heartbeat, and the transport contract

3. Architecture

The protocol is divided into three layers. This library implements one of them.

application
    |
codec        RFC-0002 - Model <-> bytes             generated by fomoxac,
                                                      not part of this repository
    |
runtime      implementation guide - frames,          src/Fomoxa.Net/Framing,
(this repo)  handshake, heartbeat, tick loop, events  Session.cs, FomoxaConnection.cs,
                                                       FomoxaServer.cs
    |
transport    TCP, UDP, or a user-supplied transport   src/Fomoxa.Net/Transports

A message payload is treated as opaque data from the socket up to the event delivered to the application. No code in this repository inspects the content of a payload.

4. Installation

The package is published on NuGet as Fomoxa.Net.

dotnet add package Fomoxa.Net

The package declares no dependency that reaches a consumer. Microsoft.SourceLink.GitHub is referenced with PrivateAssets="All" and is used only to embed source-link metadata into the package at build time.

5. Building from source

dotnet build Fomoxa.Net.sln
dotnet run --project tests/Fomoxa.Net.Tests

The test project requires no external test framework and no package restore beyond the solution itself.

6. Quick start

6.1 Client

using Fomoxa.Net;
using Fomoxa.Net.Transports;

var transport = TcpTransport.Connect(new IPEndPoint(IPAddress.Loopback, 7777));
using var connection = FomoxaConnection.Connect(transport, MySchema.Build(), new SessionConfig());

while (!connection.IsClosed)
{
    foreach (var raised in connection.Tick(MonotonicClock.Now))
    {
        switch (raised.Kind)
        {
            case FomoxaEventKind.Ready:
                break;

            case FomoxaEventKind.Message:
                Handle(raised.MessageId, raised.Payload.Span);
                break;

            case FomoxaEventKind.HandshakeFailed:
            case FomoxaEventKind.Disconnected:
                return;
        }
    }

    if (connection.IsReady)
    {
        connection.Send(MySchema.PositionMessageId, payload);
    }

    Thread.Sleep(16);
}

A call to Send before the connection reaches the Ready state is refused. No application byte reaches the transport until both ends have confirmed that they read the schema the same way.

6.2 Server

var listener = new TcpListenerTransport(new IPEndPoint(IPAddress.Loopback, 7777));
using var server = new FomoxaServer(listener, MySchema.Build(), new SessionConfig());

while (true)
{
    foreach (var raised in server.Tick(MonotonicClock.Now))
    {
        if (raised.Kind == FomoxaEventKind.Message)
        {
            server.Send(raised.PeerId, raised.MessageId, raised.Payload.Span);
        }
    }

    Thread.Sleep(16);
}

examples/EchoServer and examples/EchoClient are two runnable processes that implement this exchange. The server must be started first.

dotnet run --project examples/EchoServer          # append "7777 udp" to use UDP
dotnet run --project examples/EchoClient

6.3 UDP

Switching to UDP changes one line on the client and one on the server; the code above the transport layer stays the same.

var transport = UdpTransport.Connect(new IPEndPoint(IPAddress.Loopback, 7777));
var listener  = new UdpServerTransport(new IPEndPoint(IPAddress.Loopback, 7777));

The event sequence, the tick loop, and the heartbeat behavior are identical to the TCP case. UDP does not guarantee delivery, ordering, or deduplication of packets, and this library adds none of these guarantees; datagrams reach the application in the order the socket received them. Heartbeat and dead-peer detection are unaffected, because elapsed time drives them and sequence numbers play no part. A single UDP datagram carries at most 65,499 bytes of frame (65,507 minus the 8-byte session identifier), and the transport rejects a larger send without fragmenting it. The identifier at the start of each datagram lets a peer keep its session when its source address changes; implementation-guide/en/03-udp-transport.md defines it.

7. Schema construction

The runtime does not compute a schema fingerprint. The application supplies, per message, the triple (id, field count, prefix-fingerprint chain), and the runtime only compares these values during the handshake.

public static Schema Build() =>
    new Schema(
        Handshake.FomoxaSchemaFingerprint,
        new[]
        {
            new MessageSchema(
                Handshake.PlayerEdgeMessageId,
                Handshake.PlayerEdgeFingerprint,
                Handshake.PlayerEdgePrefixes),
        });

fomoxac writes these constants into a generated Handshake.cs file. The prefix chain is never sent in full: a peer sends its own field count and its last fingerprint entry, and the two sides compare at the smaller of the two field counts, per RFC-0002 §9.1.

Two peers running schemas that differ can still connect, provided every message declared by both sides agrees on the fields both sides carry. A field appended at the end of a message, or removed from the end, is a valid version difference, and RFC-0003 §8.6 vectors V-001 and V-002 require that such a peer is accepted. A session is closed only when a field differs at an index carried by both ends.

8. Timekeeping

Tick(TimeSpan now) receives the current instant as a parameter. No code in this library reads a system or wall clock on its own, so timeout and expiry behavior can be tested without waiting in real time.

MonotonicClock.Now is provided as a default time source. It is backed by System.Diagnostics.Stopwatch, a monotonic source, so a change to the system clock cannot expire a running handshake or end a healthy connection.

8.1 SessionConfig defaults

Setting Default Meaning
HandshakeTimeout 5 s Client: deadline for the whole handshake. Server: silence window allowed for a peer that has not completed one
HeartbeatInterval 5 s Duration of silence on a link before a probe frame is sent
HeartbeatTimeout 15 s Duration an unanswered probe is allowed before the peer is declared dead
MaxFramesPerTick 64 Maximum number of frames processed in a single tick, bounding the work one peer can impose per call

A probe is sent only after a period of silence, never on a fixed timer, so a link carrying regular traffic produces no heartbeat frames. No peer is disconnected without first being probed, so the longest time to detect a dead peer is HeartbeatInterval plus HeartbeatTimeout: 20 seconds with the defaults above.

9. Payload lifetime

FomoxaEvent.Payload references a buffer owned and reused by the connection. The reference is valid only until the next call to Tick on the same session, after which the bytes it points to are undefined. To retain a payload beyond the current tick, copy it explicitly.

byte[] mine = raised.CopyPayload();

Implementation guide §6.2 permits either this behavior or handing out an owned copy per event, and requires the choice to be documented. This library returns a reference into a reused buffer, which avoids an allocation on the receive path.

10. Status and event enumerations

Enumeration Values
FomoxaEventKind Connected, Ready, HandshakeFailed, Message, Ping, Pong, Disconnected
HandshakeFailure VersionMismatch, SchemaConflict, Corrupt, Timeout
DisconnectReason PeerClosed, TransportError, Timeout
SendStatus Sent, NotReady, Congested, TooLarge, Closed
SessionState Handshaking, Ready, Closed

11. Writing a transport

The ITransport interface is the whole contract a transport implements, and it reports results through the TransportSignal values below.

Signal Meaning
Ok Operation completed
WouldBlock Operation cannot complete now; retry on the next tick
Closed The peer closed the connection cleanly
Error The underlying link failed
TooLarge The frame exceeds the transport's limit; the frame is not retried, and the session continues
NeedCapacity A packet arrived that does not fit in the supplied buffer; the required size is reported and the packet is retained
Partial A Stream transport took only the first Count bytes of a send; the connection keeps the rest and sends it before any new frame

A transport declaring TransportKind.Stream is wrapped by a reassembly layer provided by this library. When a Stream transport can take only part of a send, it returns SendOutcome.Partial(count) and keeps nothing; the connection holds the rest, and FomoxaConnection.IsCongested stays true until it has gone out. TcpTransport works this way, as the Rust TcpTransport does. A transport declaring TransportKind.Message must deliver exactly one whole packet per call to Receive.

A transport implementation handles only the operations ITransport defines. Framing, ordering, retrying a blocked send, measuring time, and reconnecting are left to the runtime or the application. No method on ITransport may block, sleep, spawn a thread, or call back into the runtime.

TcpTransport and UdpTransport, the two included implementations, are each about a hundred lines, and a new transport should be of similar size.

12. Non-goals

  • No codec. fomoxac generates the Writer/Reader implementation of RFC-0002. A second, hand-written implementation of the same wire format here could drift from the generated one while both kept decoding without error.
  • No WebSocket, TLS, or QUIC transport, and no extension point reserved for one. A transport for another protocol is a separate library written against ITransport, with no change to this one.
  • No background threads and no async. Every socket operation is non-blocking, and the caller's Tick call drives all I/O, per invariant B2 of the implementation guide.
  • No reconnection, reordering, or retransmission. The Fomoxa protocol has none of these, and a transport that did them silently would leave the two ends disagreeing about whether a session is still alive.

13. Tests

dotnet run --project tests/Fomoxa.Net.Tests runs the test suite with no external test framework and no extra package restore. The suite has 80 checks, organized by the checklist in implementation guide §11:

  • Wire format: byte-exact frames, a byte stream delivered one byte at a time, back-to-back frames, size ceilings at 16 MiB and 1 MiB, and a malformed byte being fatal on a stream transport while it costs only one packet on a datagram transport.
  • Handshake: all four branches of the fingerprint comparison, the query round in both directions, a field appended by the client and a field removed by the server (both must be accepted), malformed hello frames, and an oversized declared message count that must not overflow.
  • Heartbeat: traffic suppressing probes, exactly one probe per silence window, any frame clearing a pending probe, and a full expiry cycle verified without real-time waiting.
  • Core loop: a blocked link retaining exactly one pending frame, the rest of a partial send kept by the connection, congestion refused instead of queued, NeedCapacity not discarding the packet, TooLarge not terminating the session, the per-tick frame budget, and exactly one terminal event per session.
  • End to end: two peers over both transport kinds, including a byte stream delivered one byte at a time.
  • Real sockets: TCP and UDP on loopback, two UDP peers kept isolated from each other, a UDP peer that moves to a new source address keeping its session, a full UDP receive queue dropping the oldest datagram, and the peer-table ceiling under many unknown source addresses.

14. License

Apache-2.0. See LICENSE.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  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 was computed.  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. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.1

    • No dependencies.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Fomoxa.Net:

Package Downloads
Fomoxa.Net.WebSockets

WebSocket transport and listener for Fomoxa.Net: RFC 6455 on a non-blocking byte stream.

Fomoxa.Rpc

fRPC for .NET: the RPC layer on top of Fomoxa.

Fomoxa.Reliability

Per-message reliable/unreliable delivery on top of one Fomoxa session, without changing Fomoxa.Net or ITransport.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.4 97 11/10/2026
0.1.3 344 10/30/2026
0.1.2 111 10/25/2026
0.1.1 110 10/24/2026
0.1.0 209 8/24/2026