Fomoxa

EN/VI

Getting started · fomoxac 0.2.3

From a model to 13 bytes

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

Install fomoxac

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

Annotate your first model

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.

Configure and generate

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.

Encode and decode

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

Look at the bytes

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