Fomoxa

EN/VI

Bắt đầu · fomoxac 0.2.3

Từ một model đến 13 byte

Cài công cụ sinh code, đánh dấu một type bạn đã có, sinh codec, rồi ghi Player{ id: 100, name: "Alice" } ra wire. Các bước mất khoảng mười phút.

Trước khi bắt đầu

Fomoxa là specification. fomoxac là một công cụ hiện thực nó: đọc annotation trên chính type của bạn và sinh ra source code thuần để encode và decode chúng.

Code sinh ra không có dependency lúc chạy, kể cả với fomoxac. Codec viết tay cũng hợp lệ như vậy, miễn là pass các test vector của RFC-0003. Mọi đoạn code trên trang này đều được sinh bằng fomoxac 0.2.3 và đã được chạy thật.

Các bước

Cài fomoxac

fomoxac được phát hành trên crates.io và cần Rust toolchain (rustup) để cài, dù project của bạn dùng ngôn ngữ nào. Cùng lệnh đó cài luôn fomoxa-inspect, công cụ debug payload.

cargo install fomoxac
fomoxac --version
# fomoxac 0.2.3

Đánh dấu model đầu tiên

Không có file IDL. Schema là một tập annotation trên type bạn đã sở hữu: type nào là Model, nó sinh codec nào (ở đây là game), và wire type của từng field. Field không có annotation không bao giờ lên wire.

// src/models/player.rs      cần: 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,
}

Thêm pub mod player; vào src/models/mod.rs.

// src/Models/Player.cs      cần: 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          không cần gì - comment và struct tag vốn là Go hợp lệ
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      không cần gì - directive chỉ là comment
// 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      không cần gì - directive chỉ là comment
// 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 - ba marker, mở rộng thành rỗng */
#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     cần: cùng file fomoxa.h như 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;
};

Hai quy tắc cần nhớ. Wire type lấy từ annotation, không bao giờ lấy từ type của ngôn ngữ: u32 là bốn byte kể cả trên field 64-bit. Và field lên wire theo thứ tự khai báo: đổi tên field thì miễn phí, đổi thứ tự là breaking change.

Không có kiểu message riêng. Không có file schema nào phải giữ cạnh struct này, và không có class sinh ra nào phải chuyển đổi qua lại: codec đọc ghi thẳng Player bạn vừa đánh dấu. Nếu một ngôn ngữ thứ hai dùng cùng model, hãy đánh dấu nó ở đó nữa. Schema fingerprint trong .fomoxa/schema.json cho biết hai bên có khớp nhau không.

Cấu hình và sinh code

Đặt fomoxa.toml ở thư mục gốc project, cạnh Cargo.toml, go.mod, package.json hoặc .csproj, rồi chạy công cụ sinh code. Mỗi lần chạy đọc một ngôn ngữ.

# fomoxa.toml
src = "src"             # ví dụ Go ở trên: "models"
out = "src/generated"   # ví dụ Go ở trên: "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

Bạn có một file cho mỗi codec (PlayerGameCodec), một runtime nhỏ được chép vào (Writer, Reader), và .fomoxa/schema.json. Hãy commit file schema: các lần chạy sau so sánh với nó và báo breaking change. fomoxac generate --watch sinh lại mỗi khi lưu file.

Encode và decode

Mọi ngôn ngữ cho ra cùng các byte với cùng một giá trị.

// 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}");

Namespace sinh ra lấy theo tên thư mục out. Decode ném DecodeException khi payload hỏng.

// 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);

Import sinh ra không có đuôi file, nên cần biên dịch bằng tsc (hoặc bundler) trước khi chạy.

// 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;
}

string sau khi decode được cấp phát trên heap: gọi Player_free đúng một lần cho mỗi giá trị đã decode.

// 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, chạy được với -fno-exceptions: lỗi trả về dưới dạng giá trị DecodeError.

# output (cách in khác nhau theo ngôn ngữ, byte thì không)
64 00 00 00 05 00 00 00 41 6C 69 63 65
id = 100    độ dài = 5  A  l  i  c  e
100 Alice

Xem các byte

Payload dài mười ba byte, không có metadata. Mở nó trong inspector tương tác, hoặc decode một payload bắt được theo schema của bạn bằng dòng lệnh:

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