Wire format specification · v1.0.0 · Draft
Một binary wire format xác định.
Không hơn. Không kém.
Cyclone định nghĩa dữ liệu logic được biến thành byte như thế nào, và byte được biến ngược lại thành dữ liệu logic như thế nào.
Thứ tự
Specification là nguồn sự thật duy nhất. Không bao giờ sửa spec để chiều một implementation. Mọi thứ khác đều nằm phía sau nó.
Thứ tự Cyclone đi theo
Không phải thế này
Một protocol bị nắn theo bất kỳ thứ gì thư viện đầu tiên của nó tình cờ làm.
Phép thử áp cho từng câu của 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à nó không thuộc về spec.
Định nghĩa
Cyclone là một protocol.
Transport, retransmission, thứ tự gói, matchmaking, mã hoá, nén, checksum — tất cả đều xây phía trên Cyclone. Specification dừng lại đúng ở chỗ byte được hình thành.
Triết lý
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 thứ đó chính là cách một protocol âm thầm biến thành một framework.
Vi phạm một trong số này thì không phải Cyclone.
Là lựa chọn thiết kế, không phải điều kiện tuân thủ. Một implementation khác được phép chọn khác, miễn byte sinh ra không đổi.
Quy tắc quyết định, gồm 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 về Reference Implementation và không được đư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 Cyclone.
Đánh đổi
Mỗi điều dưới đây đều 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.
Vị trí là định danh field duy nhất, nên thêm, bớt hay đổi thứ tự một field đều là breaking change. v1 không có thương lượng phiên bản, không có migration cho field.
Không có unknown-field skipping, không có default, nên client cũ không đọc được message của server mới. Hai đầu deploy cùng nhau, hoặc không deploy.
Stream không mang tên field, kiểu hay tag — bên nhận bắt buộc phải biết trước thứ tự và kiểu của từng field. Hệ quả nguy hiểm: decode sai định nghĩa thường không báo lỗi gì cả. Nó sinh ra giá trị sai, im lặng.
Nguồn sự thật là Schema, nhưng spec không quy định bạn phải viết nó ra
bằng cách nào — không IDL bắt buộc, không file .cyclone bắt buộc. Reference
Implementation diễn đạt Schema bằng annotation ngay trên type có sẵn của bạn, chỉ trích ra
ba thứ: tên type, các field, và Cyclone type của từng field. Đổi lại: không có một tài liệu
schema độc lập để đưa cho bên thứ ba — hai phía tự lo việc rút ra cùng một Schema.
Mọi field đều mang giá trị. v1 không có cách encode field vắng mặt — và chính vì vậy không có chỗ nào mơ hồ về việc sự vắng mặt sẽ được ghi ra sao.
Cyclone 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 đều là phần bạn tự xây phía trên.
Nếu có điều nào không chấp nhận được với bài toán của bạn, một format có tag ID và optional field sẽ phục vụ tốt hơn. Đó là lựa chọn đúng, không phải thất bại của Cyclone.
Specification
Ba tài liệu. Mỗi tài liệu trả lời đúng một câu hỏi.
Bản tiếng Việt là bản gốc. Chỗ nào bản dịch nói khác đi, bản tiếng Việt thắng. Xem repository specification ↗
RFC-0002
Little endian, luôn luôn. Kích thước cố định, không varint. Không tag, không header, không padding, không terminator. Vị trí là định danh duy nhất.
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, không canonical NaN.
Độ dài UInt32, rồi tới byte UTF-8. Độ dài đếm byte, không bao giờ đế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ự và ba byte. Độ dài MUST là 3. Vùng byte phải là UTF-8 hợp lệ.
Độ dài UInt32, rồi tới byte thô. Giống hệt 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 bao giờ suy ra từ nội dung.
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 được đổi một byte nào của output.
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 là số lượng 0 và không byte nào thêm.
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.
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 những byte nó sở hữu, hoặc rê lên một byte để tìm chủ của nó.
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
}
Không có gì ngăn cách các field. Không length prefix cho Model lồng, không dấu phân cách giữa
position và health, không terminator ở cuối. Decoder biết đang đọc field
nào thuần tuý nhờ con trỏ đã đi được bao xa — và đó chính là lý do
đổi thứ tự field là breaking change, còn đổi tên field thì miễn phí.
RFC-0003
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 nào, ngôn ngữ nào, API nào.
Input→Byte mong đợi
| 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: một implementation big-endian sẽ ghi 12 34 56 78 và trượt ở đây.
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.
| 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 những implementation sắp field theo thứ tự chữ cái “cho ổn định” — 02 01 là bug.
| 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.
| 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 những implementation “tối ưu” một enum bốn thành viên xuống còn một byte.
| 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-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 đúng một thứ: độ dài có được kiểm tra trước khi cấp phát không? Pass N-031 bằng cách crash rồi bắt exception thì không tính là pass.
Bộ đầy đủ — gồm số nguyên 8 byte, f64, kiểm tra round-trip và kiểm tra chéo giữa các
implementation — nằm trong
RFC-0003.
Conformance
Một implementation là Cyclone Compatible khi và chỉ khi nó pass 100% test vector.
Không có “tương thích một phần”. Không có 98%. Một vector trượt nghĩa là tồn tại một dữ liệu mà implementation này và một implementation khác bất đồng — im lặng, trên production.
Một implementation chậm gấp 10 lần nhưng pass 100% vector là Cyclone Compatible.
Implementation nhanh nhất thế giới mà trượt một vector thì không.
Công cụ
Những công cụ này là reference implementation của Cyclone Protocol. Chúng không phải là một phần của protocol.
Thay cả ba, wire format không đổi. Không có gì trong Cyclone bắt bạn phải dùng chúng — chúng tồn tại để được đọc, và để bị vượt qua.
Bắt đầu