Fomoxa

EN/VI

Why Fomoxa

A format with no choices

Most formats let the encoder choose: field order, integer width, whether to write a default. Fomoxa takes every one of those choices away, so the same value gives the same bytes in every language. This page covers when that is worth it, and what it costs.

Problem

The same value, different bytes

With JSON or Protobuf, the same data can come out as different bytes depending on the language, the library or the version. Usually nobody notices, but it causes failures in three places.

Signatures and hashes

A signature covers bytes. If another implementation re-encodes the value differently, verification fails although the data did not change.

Replay and lockstep

Two machines must reach the same state from the same inputs. A checksum over that state only works if both sides serialize it identically.

SDK compatibility

The only way to prove two SDKs agree is to compare their bytes. That needs exactly one right answer to compare against.

Idea

Remove every choice

Wherever an encoder is allowed to choose, two encoders will eventually choose differently. Four rules leave the encoder nothing to choose.

  1. Numbers are fixed width, little endian. A u32 is four bytes, even for zero, and there are no varints.
  2. Strings and arrays start with a u32 length or count. String length counts UTF-8 bytes.
  3. A Model is its fields, in declaration order. No tags, no header, no padding.
  4. Nothing describes the data. Both ends already know the schema.

Each rule has a price, listed under trade-offs: fields evolve only at the end, nothing is optional, and decoding against the wrong schema usually gives wrong values rather than an error. What you get in return is a single test for correctness: pass 100% of the RFC-0003 vectors.

Workflow

Two ways to keep a schema

Protobuf keeps the schema in one .proto file and generates a type per language. The Fomoxa reference tools keep it on the types you already have. Each approach has costs, listed below.

IDL · Protobuf
  1. Write each message once, in a .proto file.
  2. Run protoc or buf for each target language.
  3. Use the generated message types, or map them to and from your own types.
  4. Check for breaking changes with a tool such as buf breaking.
Annotations · fomoxac
  1. Annotate your own type, in each language that uses it.
  2. Run fomoxac generate in each of those projects.
  3. Encode and decode that type directly. There is no generated message type.
  4. Compare schema fingerprints across languages; fomoxac ci fails a pull request on a breaking change.
What annotations save
  • No second type per message, and no mapping code between it and yours.
  • Fields you do not annotate never reach the wire, so one type can also carry local state.
  • With one language on both ends there is nothing else to keep in sync.
What they cost
  • A model used by several languages is written in each of them. Field order and wire types must match by hand.
  • A mismatch is caught by comparing fingerprints, by fomoxac ci and by the runtime handshake at connect time, not by the compiler.
  • No hand-written schema file to give a third party. .fomoxa/schema.json is generated output.

Seen in practice: fomoxa-example-game declares its protocol in Rust, C# and C++, and a script checks that each schema fingerprint matches the server's.

Annotations are a choice of the reference tools, not of the specification. A separate schema file, macros or a hand-written codec are equally valid, as long as the bytes pass RFC-0003.

Fit

When it is worth it

Worth it when
  • The bytes themselves matter: they are signed, hashed, cached or compared.
  • Two or more languages must agree on those bytes.
  • Both ends ship from the same schema and can deploy together.
Not worth it when
  • Clients and servers evolve independently for years.
  • You need optional fields, or readers that do not know the schema.
  • Nobody compares the bytes, so any well-supported format will do.