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ó.
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
RFC
Compiler
SDK
Application
Không phải thế này
SDK
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
Model
Bytes
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.
01Specification first
Specification là nguồn sự thật duy nhất. Không sửa spec để chiều một implementation.
02Protocol over framework
Fomoxa định nghĩa dữ liệu hiện ra trên wire, không định nghĩa API hay runtime.
03Minimal 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.
04Deterministic 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.
05Language 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.
06Implementation independent
Không quy định parser, macro hay generator. Spec mô tả byte rồi dừng.
07Implementation 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.
08User 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.
09Compile-time over runtime
Thứ gì xác định được lúc build thì xong lúc build.
10Zero 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.
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 →
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í.
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
ID
Input
Byte mong đợi
P-002
bool true
01
P-011
u8 255
FF
P-021
u16 300
2C 01
P-032
u32 0x12345678
78 56 34 12
P-035
i32 −2147483648
00 00 00 80
P-042
u64 2⁶⁴−1
FF FF FF FF FF FF FF FF
F-005
f32 0x4048F5C3 · 3.14
C3 F5 48 40
F-002
f32 0x80000000 · −0.0
00 00 00 80
F-031
f32 0x7FC00001 · NaN
01 00 C0 7F
S-004
String “中”
03 00 00 00 E4 B8 AD
S-005
String “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
ID
Input
Byte mong đợi
T-001
Item{ id=42, name="Sword" }
2A 00 00 00 05 00 00 00 53 77 6F 72 64
T-002
Empty{}
- 0 byte
T-003
Vector3{1.5, 2.5, 3.5}
00 00 C0 3F 00 00 20 40 00 00 60 40
T-004
Body{ 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-010
Mixed{ a=1, b=2, c=3 }
01 02 00 00 00 03
T-011
Order{ 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
ID
Input
Byte mong đợi
A-001
Array<u32> []
00 00 00 00
A-002
Array<u32> [1,2,3]
03 00 00 00 01 00 00 00 02 00 00 00 03 00 00 00
A-003
Array<String> ["a","bc"]
02 00 00 00 01 00 00 00 61 02 00 00 00 62 63
A-004
Array<Array<u8>> [[1,2],[]]
02 00 00 00 02 00 00 00 01 02 00 00 00 00
A-005
Array<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
ID
Input
Byte mong đợi
E-001
PlayerState::Idle
00 00 00 00
E-002
PlayerState::Walk
01 00 00 00
E-003
PlayerState::Jump
03 00 00 00
E-010
Kích thước encode của mọi enum
luô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
ID
Ghi
Đọc
Byte
Kỳ vọng
V-001
ItemV1{ 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-002
ItemV2{ 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ệ
ID
Byte đầu vào
Kết quả mong đợi
N-001
bool · 02
từ chối · không phải 00/01
N-010
u32 · 00 00 00
từ chối · EOF bất ngờ
N-020
String · 02 00 00 00 FF FE
từ chối · UTF-8 không hợp lệ
N-021
String · 03 00 00 00 ED A0 80
từ chối · surrogate bị encode
N-022
String · 05 00 00 00 41 6C 69
từ chối · độ dài 5, còn 3 byte
N-023
String · 64 00 00 00 41 6C 69 63 65
từ chối · độ dài 100, còn 5 byte
N-030
Array<u32> · 03 00 00 00 01 00 00 00
từ chối · số lượng 3, có một phần tử
N-031
Array<u32> · FF FF FF FF
từ chối · trước khi cấp phát
N-040
enum{0,1} · 63 00 00 00
từ 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.
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 →