Fomoxa

EN/VI

Wire format specification · v1.1.0 · Final

Fomoxa Protocol

Same value. Same bytes.
In every language.

A deterministic binary wire format: one value has exactly one valid encoding, so a Rust server, a C# client and a C device agree byte for byte. The reference generator reads annotations on the types you already have.

Order

Specification first

The specification is the single source of truth. The spec is never changed to accommodate an implementation; everything else is derived from it.

The order Fomoxa follows

  1. RFC
  2. Compiler
  3. SDK
  4. Application

Not this

  1. SDK
  2. Protocol

A protocol shaped by the first library that wrote it.

The test applied to every sentence of the specification: could somebody writing an encoder in assembly on an 8-bit microcontroller follow it? If not, that sentence describes an implementation and is removed from the spec.

Definition

What is Fomoxa?

Fomoxa is a protocol.

Fomoxa is not

  • × RPC
  • × Networking
  • × Runtime
  • × Serialization library

Fomoxa only specifies

  1. Model
  2. Bytes
  3. Model

Transport, retransmission, ordering, matchmaking, encryption, compression, checksums: all of these are built on top of Fomoxa. The specification stops where the bytes are formed.

Philosophy

Ten principles, two layers.

Seven are conformance conditions. Three are choices the Reference Implementation made. Mixing the two gradually turns a protocol into a framework.

Principles of the specification

A format that violates any of these is not Fomoxa.

01 Specification first The spec is the single source of truth. Never change it to accommodate an implementation.
02 Protocol over framework Fomoxa defines how data appears on the wire, and defines no API or runtime.
03 Minimal wire format Send the data, never a description of it: no field names, type info, tags or padding.
04 Deterministic by design One value, exactly one byte sequence. Two valid encodings of the same data must not exist.
05 Language neutral No language is the reference language. Nothing in the format favours one type system.
06 Implementation independent No mandated parser, macro, or generator. The spec describes bytes and stops.
07 Implementation replaceable The Reference Implementation is not the standard. Replace it entirely and the wire format holds.

Principles of the Reference Implementation

Design choices, not conformance conditions. Another implementation may choose differently, provided the bytes stay the same.

08 User owns the Model No mandatory DTO layer, no base class. The RI reads the fields you mark and ignores the rest.
09 Compile-time over runtime Anything decidable at build time is decided at build time.
10 Zero runtime reflection The wire format permits a reflection-free implementation and the spec does not require one, so AOT and bare-metal targets stay viable.

The decision rule, in two questions. One: is this statement observable from the byte stream? If not, it belongs to the Reference Implementation and must not enter the spec. Two: does it violate one of the seven above? If yes, it is not part of Fomoxa.

Trade-offs

What Fomoxa deliberately does not do

Each of these is the direct cost of a guarantee above. None of them is on a roadmap.

✕

Schema evolution only at the end

Position is the only field identifier. Append or remove a field at the end of a Model and the wire holds (Version skew, RFC-0002 §9.1). Inserting a field in the middle, reordering fields, changing a field's type: breaking change.

✕

Compatibility only at the trailing edge

An old client reads a new server's message only when the sole change is a field appended at the end. The extra bytes are discarded (Version skew, RFC-0002 §9.1). A field inserted or changed in the middle is a hard break, and both ends must deploy together.

✕

No metadata, not self-describing

The stream carries no field names, types or tags. The receiver must already know the field order and types. As a consequence, decoding against the wrong definition usually raises no error and silently produces wrong values.

✕

No mandated IDL

The source of truth is the Schema. The spec does not dictate how you write the Schema down. No mandatory IDL, no mandatory .fomoxa file. The Reference Implementation expresses the Schema as annotations on your existing type. It extracts exactly three things: the type, its fields, and each field's Fomoxa type. The cost: no standalone Schema document to hand a third party. Each end must derive the same Schema independently.

✕

No Optional, no nullable, no explicit default

There is no wire-level marker for absence, neither a tag nor a null byte. A trailing field can end up with no data through Version skew (§9.1). How an implementation represents that (a default value, Option<T>, an exception) is left to the implementation, not to the wire format.

✕

No transport, no framing, no crypto

Fomoxa produces a byte sequence and stops. Message boundaries, retransmission, ordering, encryption and compression belong to layers built on top.

If any of these is unacceptable for your problem, a format with tag IDs and optional fields will serve it better.

Specification

RFC-0002

Wire format

Always little endian, with fixed widths and no varints. There is no tag, header, padding or terminator; position is the only identifier.

Primitive

Fixed width, little endian. A u32 is four bytes, even when the value is zero.

u32   100        → [64 00 00 00]
u32   0x12345678 → [78 56 34 12]
i32   -1         → [FF FF FF FF]
u16   300        → [2C 01]
bool  true       → [01]
bool  0x02       → invalid
f32   3.14       → [C3 F5 48 40]
f32   -0.0       → [00 00 00 80]

Floats keep their IEEE 754 bit pattern exactly, with no normalization and no canonical NaN.

String

UInt32 length, then UTF-8 bytes. Length counts bytes, never characters.

"abc"      → [03 00 00 00] [61 62 63]
"中"        → [03 00 00 00] [E4 B8 AD]
"Xin chào" → [09 00 00 00] [58 69 6E 20 63 68 C3 A0 6F]
""         → [00 00 00 00]

“中” is one character, three bytes. Length MUST be 3. The byte region MUST be valid UTF-8.

Bytes

UInt32 length, then raw bytes. Identical to String, minus the UTF-8 constraint.

[]         → [00 00 00 00]
[FF FE]    → [02 00 00 00] [FF FE]
[00 00]    → [02 00 00 00] [00 00]

The same bytes a String must reject. Type comes from the Schema, never inferred from content.

Model

Fields concatenated in declaration order. No metadata, no field ID, no padding.

model Item { id: u32; name: String }
Item{ 42, "Sword" }
  → [2A 00 00 00] [05 00 00 00] [53 77 6F 72 64]

model Mixed { a: u8; b: u32; c: u8 }
Mixed{ 1, 2, 3 } → [01 02 00 00 00 03]   6 bytes
                   12 bytes = copying memory layout

A compiler may reorder fields in RAM. That must not change a single byte of output.

Array

UInt32 count, then each element in the byte shape of T. Count is elements, not bytes.

Array<u32> [1,2,3]
  → [03 00 00 00] [01 00 00 00] [02 00 00 00] [03 00 00 00]

Array<String> ["a","bc"]
  → [02 00 00 00] [01 00 00 00 61] [02 00 00 00 62 63]

Array<Array<u8>> [[1,2],[]]
  → [02 00 00 00] [02 00 00 00 01 02] [00 00 00 00]

Count for [1,2,3] is 3, not 12. An empty inner array is a count of 0 and no further bytes.

Enum

Always UInt32. Four bytes, regardless of how few members it declares.

enum PlayerState { Idle=0, Walk=1, Run=2, Jump=3 }

Idle → [00 00 00 00]
Walk → [01 00 00 00]
Jump → [03 00 00 00]
99   → invalid - outside the defined set

A protocol decision, not a storage optimization. There is nothing for two peers to negotiate.

Version skew

The writer and the reader may run two different versions of the same Model. One condition: the only difference is a field appended or removed at the end.

model ItemV1 { id: u32 }
model ItemV2 { id: u32; name: String }

written ItemV1, read ItemV2
  [2A 00 00 00] → id=42, bytes end exactly on the boundary before name
                  → valid - name has no data

written ItemV2, read ItemV1
  [2A 00 00 00 05 00 00 00 53 77 6F 72 64] → id=42, 9 bytes remain
                  → valid - the leftover is discarded

written ItemV2, read ItemV2, truncated mid-field
  [2A 00 00 00 05 00 00 00 53 77] → length=5, only 2 bytes of data remain
                  → invalid - Unexpected EOF, NOT version skew

The stopping rule is “does the shortfall or surplus fall exactly on a field boundary?”, not “is data missing?”. Inserting a field mid-Model, reordering fields, changing a field's type: still a breaking change. See RFC-0002 §9.1.

A complete message, byte by byte

The example from RFC-0002 §15. Nested model, string, integers, bool. It encodes to 31 bytes. Hover a field to light up the bytes it owns. Hover a byte to find its owner. Want to change the values? Open it in the inspector →

model Vector3 { x: f32; y: f32; z: f32 }

model GameMessage {
  playerId:   u32       = 42
  playerName: String    = "Knight"
  position:   Vector3   = { 10.5, 20.3, -5.1 }
  health:     u32       = 100
  isAlive:    bool      = true
}
Hex dump · 31 bytes Position is the only identifier
00000000 2A000000060000004B6E696768740000
00000010 28416666A2413333A3C06400000001
Total31 bytes · 0 bytes of metadata

Nothing separates the fields: the nested model has no length prefix, there is no delimiter between position and health, and there is no terminator at the end. The decoder knows which field it is reading from how far the cursor has advanced. That is why reordering a field is a breaking change, and why renaming one is free.

RFC-0003

Test vectors

A test vector is a pair of (logical value, byte sequence), never a pair of (function call, return value). A vector names no method, no language, no API.

Input→Expected bytes

Primitive

IDInputExpected bytes
P-002bool true01
P-011u8 255FF
P-021u16 3002C 01
P-032u32 0x1234567878 56 34 12
P-035i32 −214748364800 00 00 80
P-042u64 2⁶⁴−1FF FF FF FF FF FF FF FF
F-005f32 0x4048F5C3 · 3.14C3 F5 48 40
F-002f32 0x80000000 · −0.000 00 00 80
F-031f32 0x7FC00001 · NaN01 00 C0 7F
S-004String “中”03 00 00 00 E4 B8 AD
S-005String “Xin chào”09 00 00 00 58 69 6E 20 63 68 C3 A0 6F

P-032 catches endianness. A big-endian implementation writes 12 34 56 78 and fails here. F-031 catches NaN canonicalization. Producing 00 00 C0 7F means user data was modified.

Model

IDInputExpected bytes
T-001Item{ id=42, name="Sword" }2A 00 00 00 05 00 00 00 53 77 6F 72 64
T-002Empty{}- 0 bytes
T-003Vector3{1.5, 2.5, 3.5}00 00 C0 3F 00 00 20 40 00 00 60 40
T-004Body{ pos=Vector3{1.5,2.5,3.5}, hp=100 }00 00 C0 3F 00 00 20 40 00 00 60 40 64 00 00 00
T-010Mixed{ a=1, b=2, c=3 }01 02 00 00 00 03
T-011Order{ z=1, a=2 }01 02

T-010 catches memory-layout copying (12 bytes) and compiler field reordering. T-011 catches implementations that sort fields alphabetically “for stability”. 02 01 is a bug.

Array

IDInputExpected bytes
A-001Array<u32> []00 00 00 00
A-002Array<u32> [1,2,3]03 00 00 00 01 00 00 00 02 00 00 00 03 00 00 00
A-003Array<String> ["a","bc"]02 00 00 00 01 00 00 00 61 02 00 00 00 62 63
A-004Array<Array<u8>> [[1,2],[]]02 00 00 00 02 00 00 00 01 02 00 00 00 00
A-005Array<bool> [true,false,true]03 00 00 00 01 00 01

A-002 catches the count-versus-byte-length bug. The correct count is 3, not 12.

Enum

IDInputExpected bytes
E-001PlayerState::Idle00 00 00 00
E-002PlayerState::Walk01 00 00 00
E-003PlayerState::Jump03 00 00 00
E-010Encoded size of any enumalways 4 bytes

E-010 catches implementations that “optimize” a four-member enum down to one byte.

Version skew

IDWrittenReadBytesExpectation
V-001ItemV1{ id: u32 }ItemV2{ id: u32; name: String }2A 00 00 00✓ not rejected · name has no data
V-002ItemV2{ id: u32; name: String }ItemV1{ id: u32 }2A 00 00 00 05 00 00 00 53 77 6F 72 64✓ not rejected · 9 leftover bytes discarded

Valid only when the shortfall or surplus lands exactly on a field boundary. Compare with N-022 below: bytes go missing mid-field, and it MUST still be rejected. Treating every missing or extra byte as version skew, even mid-field, is the most common conformance bug when adding this support (RFC-0002 §9.1).

Invalid stream

IDInput bytesExpected result
N-001bool · 02reject · not 00/01
N-010u32 · 00 00 00reject · unexpected EOF
N-020String · 02 00 00 00 FF FEreject · invalid UTF-8
N-021String · 03 00 00 00 ED A0 80reject · encoded surrogate
N-022String · 05 00 00 00 41 6C 69reject · length 5, 3 bytes remain
N-023String · 64 00 00 00 41 6C 69 63 65reject · length 100, 5 bytes remain
N-030Array<u32> · 03 00 00 00 01 00 00 00reject · count 3, one element
N-031Array<u32> · FF FF FF FFreject · before allocating
N-040enum{0,1} · 63 00 00 00reject · value 99 undefined

Rejection is MUST; the error name is only SHOULD. N-023 and N-031 check whether the length is validated before allocating. Crashing and catching the exception does not count as a pass.

The full set is in RFC-0003. It covers 8-byte integers, f64, round-trip checks, and cross-implementation checks.

Conformance

Fomoxa Compatible

An implementation is Fomoxa Compatible if and only if it passes 100% of the test vectors.

  • ✓ RFC-0002
  • ✓ Test vectors
  • ✓ Deterministic output

There is no “partially compatible” level such as 98%. One failing vector means data exists on which two implementations disagree, silently, in production.

An implementation 10× slower that passes 100% of the vectors is Fomoxa Compatible.
A faster implementation that fails one vector is not.

Source

Tools

Official tools

These tools are reference implementations of the Fomoxa Protocol. They are not part of the protocol itself.

Replace all of them and the wire format holds. Nothing in Fomoxa requires you to use them. They are published so others can read them and write better ones. See the whole ecosystem →

Start here