Getting started · fomoxac 0.2.3
Install the generator, mark up a type you already have, generate a codec, and write
Player{ id: 100, name: "Alice" } to the wire. The steps take about ten minutes.
Before you start
Fomoxa is the specification. fomoxac is one tool that implements it: it reads
annotations on your own types and writes plain source code that encodes and decodes them.
The generated code has no runtime dependency, not even on fomoxac. Hand-written
codecs are equally valid, as long as they pass the
RFC-0003 test vectors.
Every snippet on this page was generated with fomoxac 0.2.3 and run.
Steps
fomoxac ships on crates.io and needs a Rust toolchain
(rustup) to install, whatever language your project uses.
The same command installs fomoxa-inspect, a payload debugger.
cargo install fomoxac
fomoxac --version
# fomoxac 0.2.3
There is no IDL file. The Schema is a set of annotations on a type you already own:
which type is a Model, which codec it generates (game here), and each field's
wire type. Unannotated fields never reach the wire.
// src/models/player.rs needs: cargo add fomoxa-attributes
use fomoxa_attributes::*;
#[network]
#[codec(game)]
pub struct Player {
#[network(u32)]
#[codec(game)]
pub id: u32,
#[network(string)]
#[codec(game)]
pub name: String,
}
Also add pub mod player; to src/models/mod.rs.
// src/Models/Player.cs needs: dotnet add package Fomoxa.Attributes
using Fomoxa;
namespace Game.Models
{
[Network]
[Codec("game")]
public class Player
{
[Network("u32")]
[Codec("game")]
public uint Id { get; set; }
[Network("string")]
[Codec("game")]
public string Name { get; set; }
}
}
// models/player.go needs: nothing - a comment and a struct tag are valid Go
package models
//fomoxa:model codec=game
type Player struct {
ID uint32 `fomoxa:"u32" codec:"game"`
Name string `fomoxa:"string" codec:"game"`
}
// src/models/player.ts needs: nothing - directives are comments
// FOMOXA_MODEL
// FOMOXA_CODEC("game")
export class Player {
// FOMOXA_FIELD(u32)
// FOMOXA_CODEC("game")
id: number = 0;
// FOMOXA_FIELD(string)
// FOMOXA_CODEC("game")
name: string = "";
}
// src/models/player.js needs: nothing - directives are comments
// FOMOXA_MODEL
// FOMOXA_CODEC("game")
export class Player {
// FOMOXA_FIELD(u32)
// FOMOXA_CODEC("game")
id = 0;
// FOMOXA_FIELD(string)
// FOMOXA_CODEC("game")
name = "";
}
/* include/fomoxa.h - three markers that expand to nothing */ #define FOMOXA_MODEL #define FOMOXA_FIELD(type) #define FOMOXA_CODEC(...) /* src/models/player.h */ #pragma once #include "fomoxa.h" #include <stdint.h> FOMOXA_MODEL FOMOXA_CODEC("game") struct Player { FOMOXA_FIELD(u32) FOMOXA_CODEC("game") uint32_t id; FOMOXA_FIELD(string) FOMOXA_CODEC("game") const char *name; };
// src/models/player.hpp needs: the same fomoxa.h as C
#pragma once
#include "fomoxa.h"
#include <cstdint>
#include <string>
FOMOXA_MODEL
FOMOXA_CODEC("game")
struct Player
{
FOMOXA_FIELD(u32)
FOMOXA_CODEC("game")
uint32_t id = 0;
FOMOXA_FIELD(string)
FOMOXA_CODEC("game")
std::string name;
};
Two rules to keep in mind. The wire type comes from the annotation, never from
the host type: u32 is four bytes even on a 64-bit field. And fields go on the
wire in declaration order: renaming a field is free, reordering one is a breaking change.
No separate message type. There is no schema file to keep beside this struct and
no generated class to map to and from: the codec reads and writes the Player you just
annotated. If a second language uses the same model, annotate it there too. The schema fingerprint
in .fomoxa/schema.json tells you whether the two match.
Put a fomoxa.toml at the project root, next to Cargo.toml,
go.mod, package.json or your .csproj, then run the generator.
One run reads one language.
# fomoxa.toml src = "src" # Go example above: "models" out = "src/generated" # Go example above: "generated"
fomoxac generate
fomoxac: src/generated/runtime.rs
fomoxac: src/generated/handshake.rs
fomoxac: src/generated/player_game.rs
fomoxac: src/generated/mod.rs
fomoxac: .fomoxa/schema.json
fomoxac: .fomoxa/build-graph.json
You get one file per codec (PlayerGameCodec), a small copied runtime
(Writer, Reader), and .fomoxa/schema.json. Commit the schema
file: later runs compare against it and report breaking changes.
fomoxac generate --watch regenerates on every save.
Every language produces the same bytes for the same value.
// src/main.rs run: cargo run
mod generated;
mod models;
use generated::{PlayerGameCodec, Reader, Writer};
use models::player::Player;
fn main() {
let player = Player { id: 100, name: "Alice".to_string() };
let mut writer = Writer::new();
PlayerGameCodec::encode(&mut writer, &player);
let bytes = writer.into_bytes();
println!("{:02X?}", bytes);
let mut decoded = Player { id: 0, name: String::new() };
PlayerGameCodec::decode(&mut Reader::new(&bytes), &mut decoded).unwrap();
println!("id={} name={}", decoded.id, decoded.name);
}
// Program.cs run: dotnet run
using System;
using Game.Models;
using Generated;
var player = new Player { Id = 100, Name = "Alice" };
var writer = new Writer();
PlayerGameCodec.Encode(writer, player);
byte[] bytes = writer.ToArray();
Console.WriteLine(BitConverter.ToString(bytes));
var reader = new Reader(bytes);
var decoded = new Player();
PlayerGameCodec.Decode(ref reader, ref decoded);
Console.WriteLine($"{decoded.Id} {decoded.Name}");
The generated namespace comes from the out folder name. Decode throws DecodeException on a bad payload.
// main.go run: go run . (module: example.com/game)
package main
import (
"fmt"
"example.com/game/generated"
"example.com/game/models"
)
func main() {
player := models.Player{ID: 100, Name: "Alice"}
w := generated.NewWriter()
generated.PlayerGameCodec{}.Encode(w, &player)
bytes := w.Bytes()
fmt.Printf("% X\n", bytes)
var decoded models.Player
if err := (generated.PlayerGameCodec{}).Decode(generated.NewReader(bytes), &decoded); err != nil {
panic(err)
}
fmt.Println(decoded.ID, decoded.Name)
}
// src/main.ts run: npx tsc && node dist/src/main.js
import { Player } from "./models/player";
import { Reader, Writer } from "./generated/runtime";
import { PlayerGameCodec } from "./generated/player_game";
const player = new Player();
player.id = 100;
player.name = "Alice";
const writer = new Writer();
PlayerGameCodec.encode(writer, player);
const bytes = writer.toUint8Array();
console.log(Buffer.from(bytes).toString("hex"));
const decoded = new Player();
PlayerGameCodec.decode(new Reader(bytes), decoded);
console.log(decoded.id, decoded.name);
Generated imports have no file extension, so compile with tsc (or a bundler) before running.
// src/main.js run: node src/main.js (package.json: "type": "module")
import { Player } from "./models/player.js";
import { Reader, Writer } from "./generated/runtime.js";
import { PlayerGameCodec } from "./generated/player_game.js";
const player = new Player();
player.id = 100;
player.name = "Alice";
const writer = new Writer();
PlayerGameCodec.encode(writer, player);
const bytes = writer.toUint8Array();
console.log(Buffer.from(bytes).toString("hex"));
const decoded = new Player();
PlayerGameCodec.decode(new Reader(bytes), decoded);
console.log(decoded.id, decoded.name);
/* src/main.c build: cc -std=c99 -I . -I include -I src src/main.c */
#include <stdio.h>
#include <string.h>
#include "generated/player_game.h"
#include "generated/player_fomoxa.h"
int main(void)
{
struct Player player = { 100, "Alice" };
FomoxaWriter writer;
fomoxa_writer_init(&writer);
if (!PlayerGameCodec_encode(&writer, &player)) return 1;
for (size_t i = 0; i < writer.len; i++) printf("%02X ", writer.data[i]);
printf("\n");
FomoxaReader reader;
fomoxa_reader_init(&reader, writer.data, writer.len, fomoxa_limits_unlimited());
struct Player decoded;
memset(&decoded, 0, sizeof(decoded));
FomoxaDecodeError error = PlayerGameCodec_decode(&reader, &decoded);
if (!fomoxa_decode_error_ok(&error)) return 1;
printf("%u %s\n", decoded.id, decoded.name);
Player_free(&decoded);
fomoxa_writer_free(&writer);
return 0;
}
A decoded string is heap-allocated: call Player_free exactly once per decoded value.
// src/main.cpp build: c++ -std=c++17 -I . -I include -I src src/main.cpp
#include <cstdio>
#include "generated/player_game.hpp"
int main()
{
Player player;
player.id = 100;
player.name = "Alice";
generated::Writer writer;
generated::PlayerGameCodec::encode(writer, player);
const auto& bytes = writer.bytes();
for (auto b : bytes) std::printf("%02X ", b);
std::printf("\n");
generated::Reader reader(bytes.data(), bytes.size());
Player decoded;
if (!generated::PlayerGameCodec::decode(reader, decoded).ok()) return 1;
std::printf("%u %s\n", decoded.id, decoded.name.c_str());
}
Header-only, C++17, works with -fno-exceptions: errors come back as a DecodeError value.
# output (formatting differs per language, the bytes do not) 64 00 00 00 05 00 00 00 41 6C 69 63 65 id = 100 length = 5 A l i c e 100 Alice
The payload is thirteen bytes with no metadata. Open it in the interactive inspector, or decode a captured payload against your schema from the command line:
fomoxa-inspect --schema .fomoxa/schema.json --message Player.game \
--hex '64000000 05000000 416c696365'
id : u32 = 100
offset: 0
bytes: 64 00 00 00
name : string = "Alice" (5 bytes)
offset: 4
bytes: 05 00 00 00 41 6C 69 63 65
fomoxac ci --base-ref origin/main fails the build when a change would break peers still on the old schema.
fomoxac docs ↗