Fomoxa.Net
0.1.4
dotnet add package Fomoxa.Net --version 0.1.4
NuGet\Install-Package Fomoxa.Net -Version 0.1.4
<PackageReference Include="Fomoxa.Net" Version="0.1.4" />
<PackageVersion Include="Fomoxa.Net" Version="0.1.4" />
<PackageReference Include="Fomoxa.Net" />
paket add Fomoxa.Net --version 0.1.4
#r "nuget: Fomoxa.Net, 0.1.4"
#:package Fomoxa.Net@0.1.4
#addin nuget:?package=Fomoxa.Net&version=0.1.4
#tool nuget:?package=Fomoxa.Net&version=0.1.4
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.
fomoxacgenerates theWriter/Readerimplementation 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'sTickcall 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,
NeedCapacitynot discarding the packet,TooLargenot 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 | Versions 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. |
-
.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.