Fomoxa

EN/VI

Wire format specification · v1.1.0 · Final

Fomoxa Protocol

Cùng giá trị. Cùng byte.
Ở mọi ngôn ngữ.

Một binary wire format xác định: mỗi giá trị có đúng một encoding hợp lệ, nên server Rust, client C# và thiết bị C khớp nhau từng byte. Bộ sinh code tham chiếu đọc annotation trên chính các type bạn đã có.

Thứ tự

Specification first

Specification là nguồn sự thật duy nhất. Spec không bao giờ được sửa để chiều một implementation; mọi thứ khác đều suy ra từ nó.

Thứ tự Fomoxa đi theo

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

Không phải thế này

  1. SDK
  2. Protocol

Protocol bị nắn theo thư viện đầu tiên viết ra nó.

Phép thử cho từng câu trong specification: một người viết encoder bằng assembly trên vi điều khiển 8-bit có làm theo được không? Nếu không, câu đó đang mô tả một implementation và phải được bỏ khỏi spec.

Định nghĩa

Fomoxa là gì?

Fomoxa là một protocol.

Fomoxa không phải

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

Fomoxa chỉ quy định

  1. Model
  2. Bytes
  3. Model

Transport, retransmission, thứ tự gói, matchmaking, mã hoá, nén, checksum: tất cả đều xây phía trên Fomoxa. Specification dừng ở chỗ byte hình thành.

Triết lý

Mười nguyên tắc, hai tầng.

Bảy nguyên tắc là điều kiện tuân thủ. Ba nguyên tắc là lựa chọn của Reference Implementation. Trộn lẫn hai loại này sẽ dần biến protocol thành framework.

Nguyên tắc của specification

Format vi phạm bất kỳ nguyên tắc nào dưới đây thì không phải Fomoxa.

01 Specification first Specification là nguồn sự thật duy nhất. Không sửa spec để chiều một implementation.
02 Protocol over framework Fomoxa định nghĩa dữ liệu hiện ra trên wire, không định nghĩa API hay runtime.
03 Minimal wire format Gửi dữ liệu, không gửi mô tả dữ liệu: không tên field, type info, tag hay padding.
04 Deterministic by design Một giá trị, đúng một chuỗi byte. Cấm hai cách encode hợp lệ cho cùng một dữ liệu.
05 Language neutral Không ngôn ngữ nào là ngôn ngữ chính. Không chi tiết nào trong format ưu ái một type system.
06 Implementation independent Không quy định parser, macro hay generator. Spec mô tả byte rồi dừng.
07 Implementation replaceable Reference Implementation không phải chuẩn. Thay hết nó, wire format vẫn nguyên.

Nguyên tắc của Reference Implementation

Là lựa chọn thiết kế, không phải điều kiện tuân thủ. Implementation khác được chọn khác, miễn byte sinh ra không đổi.

08 User owns the Model Không bắt buộc tầng DTO, không base class. RI đọc field bạn đánh dấu, bỏ qua phần còn lại.
09 Compile-time over runtime Thứ gì xác định được lúc build thì xong lúc build.
10 Zero runtime reflection Wire format cho phép implementation không dùng reflection và spec không bắt buộc điều đó, nên AOT và bare-metal vẫn khả thi.

Quy tắc quyết định, hai câu hỏi. Một: phát biểu này có quan sát được từ byte stream không? Không → nó thuộc Reference Implementation, không đưa vào spec. Hai: nó có vi phạm một trong bảy nguyên tắc trên không? Có → không thuộc Fomoxa.

Đánh đổi

Những gì Fomoxa cố ý không làm

Mỗi điều dưới đây là cái giá trực tiếp của một đảm bảo ở trên. Không điều nào nằm trong roadmap.

✕

Schema evolution chỉ ở cuối

Vị trí là định danh field duy nhất. Thêm hoặc bớt một field ở cuối Model thì không phá wire (Version skew, RFC-0002 §9.1). Chèn field vào giữa, đổi thứ tự field, đổi type của field: breaking change.

✕

Compatibility chỉ ở phần đuôi

Client cũ đọc được message của server mới khi thay đổi duy nhất là một field thêm ở cuối. Byte thừa bị bỏ qua (Version skew, RFC-0002 §9.1). Một field bị chèn hoặc đổi ở giữa thì breaking hoàn toàn, và hai đầu phải deploy cùng nhau.

✕

Không metadata, không tự mô tả

Stream không mang tên field, kiểu hay tag. Bên nhận bắt buộc biết trước thứ tự và kiểu của từng field. Hệ quả là decode sai định nghĩa thường không báo lỗi gì cả mà âm thầm sinh ra giá trị sai.

✕

Không có IDL bắt buộc

Nguồn sự thật là Schema. Spec không quy định bạn viết Schema ra bằng cách nào. Không IDL bắt buộc, không file .fomoxa bắt buộc. Reference Implementation diễn đạt Schema bằng annotation trên type có sẵn của bạn. Nó trích đúng ba thứ: tên type, các field, Fomoxa type của từng field. Cái giá: không có tài liệu Schema độc lập để đưa cho bên thứ ba. Mỗi phía phải tự rút ra cùng một Schema.

✕

Không Optional, không nullable, không default tường minh

Ở mức wire không có dấu hiệu nào cho sự vắng mặt, kể cả tag hay null byte. Một field ở cuối có thể không có dữ liệu do Version skew (§9.1). Cách implementation biểu diễn điều đó (default value, Option<T>, hay exception) do implementation quyết định, không do wire format.

✕

Không transport, không framing, không crypto

Fomoxa sinh ra một chuỗi byte rồi dừng. Ranh giới message, retransmission, thứ tự gói, mã hoá và nén thuộc các tầng xây phía trên.

Nếu bài toán của bạn không chấp nhận được điều nào trong số này, một format có tag ID và optional field sẽ phù hợp hơn.

Specification

RFC-0002

Wire format

Luôn little endian, kích thước cố định, không varint. Không có tag, header, padding hay terminator; vị trí là định danh duy nhất.

Primitive

Kích thước cố định, little endian. Một u32 là bốn byte, kể cả khi giá trị bằng không.

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       → không hợp lệ
f32   3.14       → [C3 F5 48 40]
f32   -0.0       → [00 00 00 80]

Float giữ nguyên bit pattern IEEE 754, không normalize và không có canonical NaN.

String

Độ dài UInt32, rồi tới byte UTF-8. Độ dài đếm byte, không đếm ký tự.

"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]

“中” là một ký tự, ba byte. Độ dài MUST là 3. Vùng byte MUST là UTF-8 hợp lệ.

Bytes

Độ dài UInt32, rồi tới byte thô. Giống String, trừ ràng buộc UTF-8.

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

Đúng những byte mà String phải từ chối. Kiểu đến từ Schema, không suy ra từ nội dung.

Model

Các field nối liền nhau theo thứ tự khai báo. Không metadata, không field ID, không 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 byte
                   12 byte = đang chép layout bộ nhớ

Compiler được phép sắp xếp lại field trong RAM. Việc đó không đổi một byte nào của output.

Array

Số lượng UInt32, rồi từng phần tử theo hình dạng byte của T. Đếm phần tử, không đếm byte.

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]

Số lượng của [1,2,3] là 3, không phải 12. Mảng con rỗng: số lượng 0, không byte nào thêm.

Enum

Luôn là UInt32. Bốn byte, bất kể nó khai báo ít thành viên tới đâu.

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   → không hợp lệ - ngoài tập đã định nghĩa

Đây là quyết định của protocol, không phải tối ưu lưu trữ. Không có gì để hai đầu thương lượng.

Version skew

Writer và reader có thể chạy hai phiên bản khác nhau của cùng một Model. Điều kiện: khác biệt duy nhất là một field thêm hoặc bớt ngay ở cuối.

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

ghi bằng ItemV1, đọc bằng ItemV2
  [2A 00 00 00] → id=42, byte hết đúng ranh giới trước name
                  → hợp lệ - name không có dữ liệu

ghi bằng ItemV2, đọc bằng ItemV1
  [2A 00 00 00 05 00 00 00 53 77 6F 72 64] → id=42, còn dư 9 byte
                  → hợp lệ - phần dư bị bỏ qua

ghi bằng ItemV2, đọc bằng ItemV2, bị cắt giữa field
  [2A 00 00 00 05 00 00 00 53 77] → length=5, chỉ còn 2 byte dữ liệu
                  → không hợp lệ - Unexpected EOF, KHÔNG phải version skew

Quy tắc dừng là “phần thiếu hay dư có rơi đúng ranh giới field không?”, chứ không phải “có thiếu dữ liệu không?”. Chèn field vào giữa Model, đổi thứ tự field, đổi type của field: vẫn breaking change. Xem RFC-0002 §9.1.

Một message đầy đủ, từng byte một

Ví dụ từ RFC-0002 §15. Model lồng, string, số nguyên, bool. Encode ra 31 byte. Rê chuột lên một field để làm sáng byte nó sở hữu. Rê lên một byte để tìm chủ của nó. Muốn đổi giá trị? Mở trong 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 byte Vị trí là định danh duy nhất
00000000 2A000000060000004B6E696768740000
00000010 28416666A2413333A3C06400000001
Tổng31 byte · 0 byte metadata

Không có gì ngăn cách các field: Model lồng không có length prefix, không có dấu phân cách giữa position và health, và không có terminator ở cuối. Decoder biết đang đọc field nào nhờ con trỏ đã đi được bao xa. Đó là lý do đổi thứ tự field là breaking change, còn đổi tên field thì miễn phí.

RFC-0003

Test vector

Một test vector là một cặp (giá trị logic, chuỗi byte), không bao giờ là cặp (lời gọi hàm, giá trị trả về). Một vector không nêu tên method, ngôn ngữ hay API nào.

Input→Byte mong đợi

Primitive

IDInputByte mong đợi
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 bắt lỗi endianness. Implementation big-endian ghi 12 34 56 78 và trượt. F-031 bắt lỗi canonical hoá NaN. Cho ra 00 00 C0 7F nghĩa là dữ liệu người dùng đã bị sửa.

Model

IDInputByte mong đợi
T-001Item{ id=42, name="Sword" }2A 00 00 00 05 00 00 00 53 77 6F 72 64
T-002Empty{}- 0 byte
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 bắt lỗi chép layout bộ nhớ (12 byte) và lỗi compiler sắp xếp lại field. T-011 bắt implementation sắp field theo thứ tự chữ cái “cho ổn định”. 02 01 là bug.

Array

IDInputByte mong đợi
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 bắt lỗi nhầm số lượng với độ dài byte. Số lượng đúng là 3, không phải 12.

Enum

IDInputByte mong đợi
E-001PlayerState::Idle00 00 00 00
E-002PlayerState::Walk01 00 00 00
E-003PlayerState::Jump03 00 00 00
E-010Kích thước encode của mọi enumluôn 4 byte

E-010 bắt implementation “tối ưu” một enum bốn thành viên xuống còn một byte.

Version skew

IDGhiĐọcByteKỳ vọng
V-001ItemV1{ id: u32 }ItemV2{ id: u32; name: String }2A 00 00 00✓ không bị từ chối · name không có dữ liệu
V-002ItemV2{ id: u32; name: String }ItemV1{ id: u32 }2A 00 00 00 05 00 00 00 53 77 6F 72 64✓ không bị từ chối · 9 byte dư bị bỏ qua

Chỉ hợp lệ khi phần thiếu hay dư rơi đúng ranh giới field. So với N-022 bên dưới: thiếu byte ngay giữa field, MUST bị từ chối. Coi mọi byte thiếu hay dư là version skew, kể cả giữa field, là lỗi conformance phổ biến nhất khi thêm hỗ trợ này (RFC-0002 §9.1).

Stream không hợp lệ

IDByte đầu vàoKết quả mong đợi
N-001bool · 02từ chối · không phải 00/01
N-010u32 · 00 00 00từ chối · EOF bất ngờ
N-020String · 02 00 00 00 FF FEtừ chối · UTF-8 không hợp lệ
N-021String · 03 00 00 00 ED A0 80từ chối · surrogate bị encode
N-022String · 05 00 00 00 41 6C 69từ chối · độ dài 5, còn 3 byte
N-023String · 64 00 00 00 41 6C 69 63 65từ chối · độ dài 100, còn 5 byte
N-030Array<u32> · 03 00 00 00 01 00 00 00từ chối · số lượng 3, có một phần tử
N-031Array<u32> · FF FF FF FFtừ chối · trước khi cấp phát
N-040enum{0,1} · 63 00 00 00từ chối · giá trị 99 không định nghĩa

Từ chối là MUST; tên lỗi chỉ là SHOULD. N-023 và N-031 kiểm tra độ dài có được kiểm tra trước khi cấp phát hay không. Crash rồi bắt exception không tính là pass.

Bộ đầy đủ nằm trong RFC-0003. Gồm số nguyên 8 byte, f64, kiểm tra round-trip, kiểm tra chéo giữa các implementation.

Conformance

Fomoxa Compatible

Một implementation là Fomoxa Compatible khi và chỉ khi nó pass 100% test vector.

  • ✓ RFC-0002
  • ✓ Test vector
  • ✓ Output xác định

Không có mức “tương thích một phần” như 98%. Một vector trượt nghĩa là tồn tại một dữ liệu mà hai implementation hiểu khác nhau, âm thầm, trên production.

Implementation chậm gấp 10 lần nhưng pass 100% vector là Fomoxa Compatible.
Một implementation nhanh hơn mà trượt một vector thì không.

Mã nguồn

Công cụ

Công cụ chính thức

Những công cụ này là reference implementation của Fomoxa Protocol. Chúng không phải là một phần của protocol.

Thay tất cả, wire format không đổi. Không gì trong Fomoxa bắt bạn phải dùng chúng. Chúng được công bố để người khác đọc và viết bản tốt hơn. Xem toàn bộ hệ sinh thái →

Bắt đầu