Fomoxa

EN/VI

Vì sao Fomoxa

Một format không để lại lựa chọn

Phần lớn format để encoder tự chọn: thứ tự field, độ rộng số nguyên, có ghi giá trị mặc định hay không. Fomoxa bỏ hết những lựa chọn đó, nên cùng một giá trị cho ra cùng các byte ở mọi ngôn ngữ. Trang này nói khi nào điều đó đáng giá, và nó tốn gì.

Vấn đề

Cùng giá trị, khác byte

Với JSON hay Protobuf, cùng một dữ liệu có thể ra các byte khác nhau tuỳ ngôn ngữ, thư viện hay phiên bản. Thường thì không ai để ý, nhưng nó gây lỗi ở ba chỗ.

Chữ ký và hash

Chữ ký phủ lên byte. Nếu một implementation khác encode lại giá trị theo cách khác, việc kiểm tra thất bại dù dữ liệu không hề đổi.

Replay và lockstep

Hai máy phải đi đến cùng một trạng thái từ cùng các input. Checksum trên trạng thái đó chỉ dùng được khi hai bên serialize nó giống hệt nhau.

Tương thích SDK

Cách duy nhất để chứng minh hai SDK khớp nhau là so sánh byte của chúng. Việc đó cần đúng một đáp án để so.

Ý tưởng

Bỏ mọi lựa chọn

Chỗ nào encoder được phép chọn, sớm muộn hai encoder sẽ chọn khác nhau. Bốn quy tắc sau không để lại lựa chọn nào cho encoder.

  1. Số có độ rộng cố định, little endian. u32 là bốn byte, kể cả khi bằng 0, và không dùng varint.
  2. String và array bắt đầu bằng độ dài hoặc count kiểu u32. Độ dài string tính theo byte UTF-8.
  3. Một Model là các field của nó, theo thứ tự khai báo. Không tag, không header, không padding.
  4. Không có gì mô tả dữ liệu. Hai đầu đã biết sẵn schema.

Mỗi quy tắc có cái giá của nó, liệt kê ở phần đánh đổi: field chỉ tiến hoá ở cuối, không có gì là optional, và decode bằng sai schema thường cho ra giá trị sai thay vì báo lỗi. Đổi lại, tính đúng chỉ có một phép thử: đạt 100% các vector của RFC-0003.

Quy trình

Hai cách giữ schema

Protobuf giữ schema trong một file .proto và sinh một type cho mỗi ngôn ngữ. Công cụ tham chiếu của Fomoxa giữ schema ngay trên các type bạn đã có. Cách nào cũng có cái giá riêng, liệt kê bên dưới.

IDL · Protobuf
  1. Viết mỗi message một lần, trong file .proto.
  2. Chạy protoc hoặc buf cho từng ngôn ngữ đích.
  3. Dùng type message được sinh ra, hoặc chuyển đổi qua lại với type của bạn.
  4. Kiểm tra breaking change bằng công cụ như buf breaking.
Annotation · fomoxac
  1. Đánh dấu chính type của bạn, ở từng ngôn ngữ dùng nó.
  2. Chạy fomoxac generate trong từng project đó.
  3. Encode và decode thẳng type đó. Không có type message nào được sinh ra.
  4. So schema fingerprint giữa các ngôn ngữ; fomoxac ci làm pull request thất bại khi có breaking change.
Annotation tiết kiệm gì
  • Không có type thứ hai cho mỗi message, không có code chuyển đổi giữa nó và type của bạn.
  • Field không được đánh dấu không bao giờ lên wire, nên một type có thể mang cả trạng thái cục bộ.
  • Nếu hai đầu cùng một ngôn ngữ thì không còn gì khác phải đồng bộ.
Annotation tốn gì
  • Model dùng ở nhiều ngôn ngữ phải viết ở từng ngôn ngữ. Thứ tự field và wire type phải khớp bằng tay.
  • Sai lệch được phát hiện nhờ so fingerprint, nhờ fomoxac ci và nhờ handshake của runtime lúc kết nối, không phải nhờ compiler.
  • Không có file schema viết tay để đưa cho bên thứ ba. .fomoxa/schema.json là output được sinh ra.

Trong thực tế: fomoxa-example-game khai báo protocol bằng Rust, C# và C++, và một script kiểm tra từng schema fingerprint đều khớp với server.

Annotation là lựa chọn của bộ công cụ tham chiếu, không phải của specification. Một file schema riêng, macro hay codec viết tay đều hợp lệ như nhau, miễn là các byte đạt RFC-0003.

Phù hợp

Khi nào đáng dùng

Đáng dùng khi
  • Chính các byte mang ý nghĩa: chúng được ký, hash, cache hoặc so sánh.
  • Hai ngôn ngữ trở lên phải thống nhất về các byte đó.
  • Hai đầu phát hành từ cùng một schema và có thể deploy cùng lúc.
Không đáng khi
  • Client và server tiến hoá độc lập trong nhiều năm.
  • Bạn cần field optional, hoặc bên đọc không biết schema.
  • Không ai so sánh các byte, nên format phổ biến nào cũng được.