NautilusTrader Docs · ภาษาไทย

Adapters

บทนำ

คู่มือนี้ใช้สำหรับสร้างหรือขยาย adapter แบบ Rust-native สำหรับ NautilusTrader โดย adapter เชื่อมต่อ แพลตฟอร์มเข้ากับ venue และผู้ให้บริการข้อมูล รักษา semantics ของ venue สร้าง domain event ของ Nautilus ที่ถูกต้อง และทำให้ผลลัพธ์ที่ไม่แน่นอนปรากฏอย่างชัดเจน adapter จะ implement trait ของ data client และ execution client ของแพลตฟอร์มใน Rust

คู่มือนี้ครอบคลุม adapter แบบ Rust ที่อยู่ใน repository (in-tree)

ให้เลือกใช้ adapter อ้างอิงอย่างพิจารณา เพราะโครงสร้างของแต่ละตัวสะท้อนโปรโตคอลของ venue, กลุ่มผลิตภัณฑ์ และประวัติการพัฒนาที่แตกต่างกัน

Adapterสิ่งที่ใช้อ้างอิงได้
BybitHTTP และ WebSocket client แบบหลายผลิตภัณฑ์, ข้อมูล option และการจัดการผลลัพธ์ของ execution
OKXWebSocket endpoint แบบ public, private และ business พร้อมครอบคลุม instrument อย่างกว้างขวาง
Binanceการแยกผลิตภัณฑ์ spot และ futures, trading WebSocket และ market data แบบ SBE
Krakensubmodule ของ spot และ futures ที่มีเส้นทาง HTTP, WebSocket, data และ execution แยกกัน
Lighterการ sign บน Layer-2, canonical benchmark, coverage-guided fuzzing และการจัดการ execution state อย่างละเอียด
Derivedata และ execution แบบ JSON-RPC, การ sign แบบ EIP-712, canonical benchmark และ fuzzing แบบอิง invariant

คู่มือนี้แบ่งแนวทางออกเป็นสี่ประเภท:

  • กฎร่วม (shared rules) มาจาก trait ร่วม, network abstraction, hook หรือ CI
  • รูปแบบที่ใช้กันทั่วไป (common patterns) ปรากฏในหลาย adapter แต่ยังเปิดให้ออกแบบแบบอื่นได้
  • ตัวอย่าง (examples) แสดง implementation ที่ดีแบบหนึ่งโดยไม่บังคับ
  • ข้อยกเว้น (exceptions) ใช้ได้เมื่อ semantics ของ venue หรือขอบเขตของโปรโตคอลบังคับให้ต้องทำเช่นนั้น

Conformance

adapter ถือว่า conform เมื่อเป็นไปตามกฎแต่ละข้อด้านล่างที่เกี่ยวข้อง หรือมีการบันทึกข้อยกเว้นไว้ ให้ระบุ พฤติกรรมของ venue ที่ทำให้ต้องมีข้อยกเว้นนั้น เก็บข้อยกเว้นไว้ภายใน adapter และเพิ่ม test ที่จะ fail หาก venue ไม่ต้องการข้อยกเว้นนั้นอีกต่อไป Phase 7 เรียงลำดับงาน ที่ใช้พิสูจน์ conformance

พื้นฐานของ adapter

Runtime และวงจรชีวิตของ client

กฎใช้กับ
วงจรชีวิตของ connectiondata client และ execution client
Data event และความสดของ requestdata client
Backpressureทุก adapter
การจัดการ taskทุก adapter
Deterministic simulationadapter ที่มีการดูแลรักษา

Execution และ reconciliation

Transport และ streaming

กฎใช้กับ
ลำดับการทำงานของ requestHTTP client
การ sign request และ authenticationเส้นทาง request ของ HTTP และ WebSocket
การจัดการ error และ retry logicเส้นทาง request ของ HTTP และ WebSocket
Rate limitingHTTP client และ WebSocket client
Handshake ตอน initialize handlerWebSocket client
AuthenticationWebSocket client
การจัดการ subscriptionWebSocket client
การ route messageWebSocket client
Reconnection และ shutdownWebSocket client

ข้อกำหนดการทดสอบ data และ ข้อกำหนดการทดสอบ execution รวบรวม scenario ที่ใช้พิสูจน์ contract เหล่านี้กับ venue จริง

Baseline ร่วม

ให้ใช้ implementation ร่วมของแต่ละส่วนด้านล่าง จากนั้นจึงเลือกโครงสร้าง state ใดก็ได้ที่เป็นไปตาม contract ของมัน type ร่วมเป็นผู้ถือ contract และทำให้พฤติกรรมเทียบกันได้ข้าม venue ส่วนโครงสร้างที่สร้างขึ้นเองต้องพิสูจน์ contract เดียวกันผ่าน implementation ของตัวเอง

baseline นี้ไม่ใช้กับ execution client สองตัวที่ implement trait เดียวกันโดยไม่ได้ซื้อขาย ผ่าน API ของ venue:

  • Sandbox จำลอง fill ที่ฝั่ง local
  • Blockchain execute บน chain ภายใต้ feature defi

deterministic simulation เป็นข้อบังคับสำหรับ adapter ที่มีการดูแลรักษา adapter แต่ละตัวต้องเป็นไปตาม adapter DST contract หรือมี migration record ระดับ venue ที่ติดตามส่วนที่ยังขาดอยู่ โดย OKX เป็น implementation อ้างอิง Deterministic simulation กำหนด seam, gate และเกณฑ์สำหรับ adapter ใหม่

เป้าหมายส่วนร่วมContract
หลักฐานผลลัพธ์ของคำสั่งCommandFailureการตั้งชื่อประเภทหลักฐาน
identity และ context ของ orderOrderIdentity and OrderContextUpdate ที่ติดตามอยู่และจากภายนอก
การตัดรายการซ้ำตอน replayFifoCache and FifoCacheMapลำดับของ event และการตัดรายการซ้ำ
เหตุผลการ deny orderOrderDeniedReasonDiagnostics และเหตุผล
วงจรชีวิตของ taskTaskGroup and TaskHandlesการจัดการ task
precision ตอนรับข้อมูลเข้าDomain numeric typesการ model payload ของ venue
HTTP transportHttpClientลำดับการทำงานของ request
state ของ authenticationAuthTrackerAuthentication
identity ของ subscriptionSubscriptionStateการจัดการ subscription
คำขอ reconnectrequest_reconnectReconnection และ shutdown
กลไก retryRetryManagerการจัดการ error และ retry logic
commission ของ inferred fillExecutionClientการจัดการเมื่อ commission ล้มเหลว
เวลา, task และ runtimenautilus_common::live::dstDeterministic simulation
การอ่าน wall-clockduration_since_unix_epochDeterministic simulation

venue อาจส่งค่าที่เป็นค่าไม่ต่อเนื่อง (discrete) เป็นฟิลด์ IEEE-754 แทนที่จะเป็น decimal string หรือ JSON number ใน กรณีนี้ให้บันทึกข้อยกเว้นไว้ที่ขอบเขตการ parse และเก็บ f64 ไว้ภายในขอบเขตนั้น

การจัดประเภท retry เป็นข้อยกเว้นของตารางนี้ คือยังคงเป็นความรับผิดชอบของ adapter เพราะ status code ของ venue และ semantics ของ rate limit แตกต่างกัน แต่กลไกร่วมที่อยู่รอบ ๆ ไม่ใช่ ดู การจัดการ error และ retry logic สำหรับทั้งสองส่วน

Deterministic simulation

adapter ที่มีการดูแลรักษาทุกตัว ซึ่งคือ adapter ระดับ Official ตาม ADAPTERS.md ต้องเป็นไปตาม adapter DST contract adapter ที่ยังไม่ conform ต้องมี migration record ระดับ venue ที่ติดตามส่วนที่ยังขาด ส่วน capability ที่ยังไม่ได้อ้างสิทธิ์ จะอยู่นอก contract จนกว่าจะมี slice ที่พิสูจน์ได้

OKX เป็น implementation อ้างอิง ซึ่งพิสูจน์ contract ผ่าน seam ร่วม, static gate และ behavioral gate:

  • Seam: facade nautilus_common::live::dst จัดหาเวลา, task, runtime และ signal ส่วน seam nautilus_core::time จัดหาการเข้าถึง wall-clock และ nautilus-network จัดหา HTTP และ WebSocket transport แบบจำลอง ตาราง baseline ด้านบนแสดงกลไกร่วมของ subscription, reconnect และ retry
  • Static gate: check-dst-conventions ครอบคลุมทุกไฟล์ production ที่อยู่บนเส้นทาง DST (ADAPTER_PATHS ใน .pre-commit-hooks/check_dst_conventions.sh) และ gate dst-smoke ที่รันทุกคืนจะรัน Clippy และ test ในโหมด simulation
  • Behavioral gate: crates/adapters/okx/tests/integration/dst.rs ตรึง byte ของการ subscribe ที่แน่นอน และ ฟิลด์ wire ของแต่ละ operation ที่แน่นอนกับ local peer ที่ควบคุมได้ ส่วนการเปรียบเทียบแบบ fresh-process ครบตั้งแต่ wire ถึง domain อยู่ใน harness ปลายน้ำ (downstream)

ส่วน DST ในคู่มือ integration ของ OKX บันทึก slice ที่ผ่านการ audit แล้ว

adapter ใหม่พิสูจน์ contract ตั้งแต่ transport แรก:

  1. เพิ่ม gate สำหรับไฟล์บนเส้นทาง DST แต่ละไฟล์ทันทีที่เพิ่มไฟล์นั้น
  2. ขับแต่ละ endpoint ตั้งแต่ configuration ไปจนถึง local peer
  3. ตรึง byte บน wire ก่อนจะขยาย slice

อย่าสร้าง abstraction ร่วมจนกว่าจะมี adapter ตัวที่สองพิสูจน์ว่าต้องการขอบเขตเดียวกัน

โครงสร้างของ adapter

Rust crate เป็นแหล่งความจริง (source of truth) ของพฤติกรรมโปรโตคอล โดยทั่วไป adapter จะแยก ส่วนรับผิดชอบเหล่านี้ออกจากกัน:

crates/adapters/<adapter>/
├── Cargo.toml
├── src/
│   ├── common/              # Shared credentials, enums, models, parsing, symbols, and URLs
│   ├── http/                # Typed requests, responses, signing hooks, and transport client
│   │   ├── client.rs
│   │   ├── error.rs
│   │   ├── models.rs
│   │   ├── parse.rs
│   │   └── query.rs
│   ├── websocket/           # Streaming transport, protocol messages, parsing, and routing
│   │   ├── client.rs
│   │   ├── handler.rs
│   │   ├── messages.rs
│   │   ├── parse.rs
│   │   ├── subscription.rs  # When subscription identity or replay needs a boundary
│   │   └── dispatch.rs      # When execution routing needs a boundary
│   ├── config.rs
│   ├── data.rs              # Or data/ when product implementations need a split
│   ├── execution.rs         # Or execution/ when product implementations need a split
│   ├── factories.rs
│   ├── signing/             # When authentication or transaction signing is a subsystem
│   └── lib.rs
├── tests/                   # Public Rust boundary tests
├── test_data/               # Canonical venue payloads and protocol vectors
├── benches/                 # When confirmed hot paths warrant benchmarks
│   ├── common/              # Shared benchmark fixtures
│   ├── data.rs
│   ├── exec.rs
│   └── micros.rs
├── fuzz/                    # When untrusted codecs warrant coverage-guided fuzzing
│   ├── fuzz_targets/
│   └── README.md
├── examples/                # Rust tester nodes and focused usage examples
├── bin/                     # Optional protocol inspection or capture tools
└── README.md

เอกสารสำหรับผู้ใช้อยู่นอก crate:

docs/integrations/<adapter>.md              # User-facing integration guide

มีเพียง Cargo.toml และ src/lib.rs ที่เป็นขอบเขตสากลของ crate ให้เพิ่ม module อื่นเมื่อ adapter ต้องการ:

  • วาง symbol, credential, URL, enum ร่วม และการ parse ร่วมไว้ใต้ common/
  • วาง transport model, typed request, การ sign และ HTTP client ไว้ใต้ http/
  • วาง frame, message, subscription state, การ route และ WebSocket client ไว้ใต้ websocket/
  • implement trait ของ live data และ execution ใน data.rs และ execution.rs หาก venue มีโปรโตคอลที่ ต่างกันอย่างมีนัยสำคัญ อาจใช้ submodule ตามผลิตภัณฑ์แทนได้
  • จัด integration test ตามขอบเขต public หรือตามผลิตภัณฑ์ ไม่จำเป็นต้องบังคับให้ทุก adapter ใช้ ชื่อไฟล์เหมือนกัน

การแยกตามผลิตภัณฑ์เป็นสิ่งที่ถูกต้องเมื่อกลุ่มผลิตภัณฑ์มีโปรโตคอลต่างกัน และ client ร่วมก็สามารถ ครอบคลุมหลาย endpoint ได้เมื่อ semantics ของ request และ state ยังเหมือนกัน ให้ยึดตามขอบเขตจริงของ venue และวางพฤติกรรมร่วมไว้เหนือการแยกเหล่านั้น

การเชื่อมต่อกับ repository

adapter crate ใหม่ต้องถูกค้นพบได้โดย build surface แต่ละจุดที่เป็นเจ้าของมัน:

Surfaceการเปลี่ยนแปลงที่ต้องทำการบังคับใช้หรือการพิสูจน์
Root Rust workspaceเพิ่ม crate ลงใน members และ workspace dependencies ใน Cargo.tomlworkspace metadata และ Cargo check เฉพาะจุดจะค้นพบ crate
Workspace test inventoryเพิ่ม crate ลงใน ADAPTER_CRATES ใน Makefileworkspace coverage check กำหนดให้มี test inventory หนึ่งชุด
User guideเพิ่ม integration guide เฉพาะ capability ที่ adapter เปิดให้ใช้documentation check ครอบคลุม surface นี้

ลำดับการ implement adapter

ใช้ phase เหล่านี้เพื่อจัดระเบียบงาน phase อธิบายความสัมพันธ์ของการพึ่งพา ไม่ใช่ gate ของการ release adapter ที่มีเฉพาะ market data จะข้ามส่วน execution ไป และ adapter สามารถทำผลิตภัณฑ์หนึ่งให้เสร็จก่อนเริ่ม อีกผลิตภัณฑ์ได้ ให้ปรับ capability matrix ให้เป็นปัจจุบันตลอดการทำงาน แทนที่จะรอถึง phase เอกสารสุดท้าย ข้าม phase และขั้นตอนที่ไม่เกี่ยวกับ adapter ได้

Phase 0: กำหนดขอบเขต

StepComponentWork
0.1Capability matrixระบุผลิตภัณฑ์, environment, account mode, data type, order type และ report ที่อยู่ในขอบเขต
0.2Venue constraintsบันทึกข้อจำกัดของ venue, capability ที่ไม่รองรับ และความแตกต่างของ testnet
0.3Protocol boundariesระบุ API ของผลิตภัณฑ์ที่แยกกัน, endpoint แบบ public และ private และ transport แบบ binary หรือ JSON
0.4Initial sliceเลือก slice ที่เล็กที่สุดที่พิสูจน์เส้นทางแบบ end-to-end ได้
0.5Repository wiringเพิ่ม crate ลงใน Rust workspace และ test inventory แล้วเพิ่มเฉพาะ projection surface ที่ crate เปิดให้ใช้

Exit: integration guide มี capability matrix เบื้องต้น, ช่องว่างที่ทราบ และแผนการทดสอบ

Phase 1: สร้างแกนของโปรโตคอล

StepComponentWork
1.1HTTP error typesmodel ความล้มเหลวด้าน transport, HTTP status, venue, การ parse และการ validate และจัดประเภทว่า retry ได้หรือไม่เมื่อรองรับ
1.2HTTP clientimplement การ resolve endpoint และ typed request รวมถึง credential, การ sign, rate limit, retry และ pagination ตามที่จำเป็น
1.3HTTP API modelsกำหนด typed request และ response โดยทั่วไปอยู่ใต้ http/ หรือ module เฉพาะผลิตภัณฑ์
1.4HTTP parsingแปลง response ของ venue เป็น domain type ที่ขอบเขตแบบ deterministic ใน http/parse.rs หรือ common/parse.rs
1.5WebSocket error typesmodel ความล้มเหลวด้าน connection, โปรโตคอล และการ parse รวมถึงความล้มเหลวด้าน authentication และคำสั่งเมื่อเกี่ยวข้อง
1.6WebSocket clientimplement วงจรชีวิตและ shutdown รวมถึง authentication, heartbeat, subscription state และ reconnection เมื่อเกี่ยวข้อง
1.7WebSocket messagesกำหนด frame และ message ใต้ websocket/ หรือ module เฉพาะผลิตภัณฑ์ รวม acknowledgement และ error ของ venue ตามที่จำเป็น
1.8WebSocket parsingdecode แต่ละ frame เพียงครั้งเดียว แปลงเป็น domain event และ route message ของ data หรือ execution ตาม typed identity
1.9Protocol testsพิสูจน์ fixture, canonical request, signing vector ที่เกี่ยวข้อง, วงจรชีวิต และการแลกเปลี่ยนข้อมูลดิบกับ mock peer

Exit: crate compile ผ่าน, fixture ของโปรโตคอล parse ได้, signing vector ที่เกี่ยวข้องผ่าน และ request แบบ mock หรือแบบ ควบคุมได้ทำ authentication ที่จำเป็นได้ครบและแลกเปลี่ยน message ดิบของ venue ได้

Phase 2: Implement instrument

StepComponentWork
2.1Instrument parsingparse ทุกกลุ่มที่รองรับพร้อม identity, precision, currency และฟิลด์ของสัญญาครบถ้วน
2.2Instrument loadingload, filter, cache และ emit definition ที่ขอบเขตการ parse แต่ละจุดที่ต้องการ context
2.3Symbol mappingกำหนดการแปลงสองทางระหว่าง venue symbol กับ InstrumentId โดยไม่รวม instrument ที่ต่างกันให้เป็นตัวเดียวกัน
2.4Instrument updatesimplement request ของ instrument แบบสด และ update ของ definition หรือ status ที่รองรับ

Exit: fixture ที่แตกต่างกันครอบคลุมทุกกลุ่ม instrument ที่รองรับ, definition ที่ไม่ถูกต้อง fail อย่างชัดเจน และ data client emit หรือคืนค่า instrument ของ Nautilus ที่ครบถ้วน

Phase 3: Implement market data

เริ่มจาก public stream หนึ่งตัวและ instrument หนึ่งตัว ก่อนจะขยายไปยังหลายผลิตภัณฑ์หรือหลาย endpoint

StepComponentWork
3.1Public WebSocket streamssubscribe และ unsubscribe live data type แต่ละตัวที่ประกาศไว้ โดยรักษาเจตนาของ subscription
3.2Historical data requestsrequest bar, trade, quote หรือ order book snapshot ที่รองรับ ด้วยกฎ correlation และความสดที่แน่นอน
3.3Data clientimplement request, subscription และวงจรชีวิตของ DataClient และการ emit DataEvent ที่ครบถ้วน
3.4Order book handlingรักษาขอบเขตของ snapshot, incremental update, sequence, clear และ batch
3.5Stream recoveryจัดการ input ที่ผิดรูปแบบ, gap, unsubscribe, disconnect, reconnect และการ replay subscription

Exit: unit test และ mock transport test พิสูจน์ domain event ที่ครบถ้วนสำหรับ matrix ของ request และ subscription ที่รองรับ

Phase 4: Implement execution

สร้าง account state และ reconciliation ให้เรียบร้อยก่อนเปิดให้ส่ง order

StepComponentWork
4.1Account bootstrapสร้าง identity ของ account, account state เริ่มต้น, private subscription และความพร้อมแบบ connected
4.2Reconciliation reportsสร้าง report ของ order, fill, position และ mass-status ที่เกี่ยวข้อง ตอน startup และเมื่อมีการร้องขอ
4.3Basic order submissionimplement การ submit order แบบ market และ limit ที่รองรับ พร้อมการ validate ฝั่ง local แบบ deterministic
4.4Order modificationimplement คำสั่ง modify และ cancel ที่รองรับ รวมถึง semantics แบบ cancel-replace ของ venue
4.5Execution clientimplement คำสั่ง, วงจรชีวิต, การ route แบบติดตามอยู่และจากภายนอก และการ emit event ตามลำดับของ ExecutionClient
4.6Outcome recoveryรักษาผลลัพธ์ที่ไม่ทราบ, ตัด fill ซ้ำ และ resolve state ผ่าน stream, query หรือ reconciliation

Exit: mock transport test ครอบคลุมทุกคำสั่งที่รองรับ, การ reject ที่ชัดเจน, การส่งที่ไม่แน่นอน (uncertain transmission), update ที่ซ้ำหรือผิดลำดับ และ reconciliation ตอน startup

Phase 5: เพิ่ม capability เสริมของ venue

เพิ่มส่วนเหล่านี้หลังจากวงจรชีวิตพื้นฐานเสถียรแล้วเท่านั้น

StepComponentWork
5.1Advanced order typesเพิ่ม order แบบมีเงื่อนไข, stop, take-profit, trailing-stop หรือ advanced order อื่นที่เกี่ยวข้อง
5.2Batch operationsเพิ่ม batch submission, batch cancellation และ mass cancel พร้อมจัดการผลลัพธ์ราย order
5.3Venue-specific dataเพิ่ม funding, greeks, liquidation หรือส่วนขยายของ venue เป็น capability slice แยกกัน
5.4Product or endpoint splitsแยกความเป็นเจ้าของเฉพาะเมื่อขอบเขตของโปรโตคอล, authentication, quota หรือการกู้คืนบังคับให้ต้องทำ
5.5Capability proofเพิ่ม fixture, functional test, acceptance case และบันทึกข้อจำกัดสำหรับแต่ละ capability

Exit: capability เสริมแต่ละตัวทดสอบได้อย่างอิสระ และไม่ทำให้เส้นทางพื้นฐานที่มีอยู่ อ่อนแอลง

Phase 6: ทำ factory และ projection ให้ครบ

StepComponentWork
6.1Configuration structsสรุป config แบบ typed ของ data และ execution, ค่าเริ่มต้น, การ fallback ไปยัง environment และการ redact secret
6.2Client factoriesimplement Rust factory ที่รับ CacheView เป็น input และใช้ clock ของ data client

Exit: Rust factory test ผ่าน

Phase 7: พิสูจน์ conformance

StepComponentWork
7.1Rust unit testsพิสูจน์ parser, serializer, symbol, signature, state transition และ input ที่ผิดรูปแบบ
7.2Rust integration testsทดสอบขอบเขต public ของ HTTP, WebSocket, data และ execution กับ mock transport แบบ deterministic
7.3Acceptance testsรันทุก case ที่เกี่ยวข้องของ DataTester และ ExecTester บน testnet หรือ account ที่ควบคุมได้
7.4Recovery testsทดสอบความล้มเหลวของ connection, reconnect, shutdown, rate limit และการกู้คืน state
7.5Specification gapsบันทึกทุก specification case ที่ข้ามไปพร้อมเหตุผลด้าน venue หรือ capability

Exit: ข้อกำหนดการทดสอบ data และ execution ที่เกี่ยวข้องผ่านทั้งหมด และทุก capability ที่ประกาศไว้ มีหลักฐานทั้งแบบ deterministic และจาก venue

Phase 8: วัดประสิทธิภาพและความทนทาน

StepComponentWork
8.1Canonical benchmarksวัด hot path แบบ end-to-end ของ data และ execution ที่ยืนยันแล้ว ด้วย fixture ที่เป็นตัวแทนได้
8.2Microbenchmarksแยกวัดต้นทุนของการ sign, hashing, authentication, codec, การ parse หรือ serialization ที่ยืนยันแล้ว
8.3Fuzz targetsfuzz ขอบเขตการ parse, decode, normalize, sign และ encode ที่รับข้อมูลไม่น่าเชื่อถือ ด้วย corpus ที่สมจริง
8.4Invariantsassert คุณสมบัติด้าน domain และโปรโตคอลที่เข้มกว่าแค่การไม่ panic

Exit: canonical benchmark และ fuzz suite รันได้ด้วย fixture ที่เป็นตัวแทนได้ มี invariant ที่บันทึกไว้ และไม่มีหมวดบังคับที่ adapter ไม่ได้ใช้

Phase 9: ทำเอกสารและการปฏิบัติการให้เสร็จ

StepComponentWork
9.1Capability matrixตรวจสอบให้ทุกคำกล่าวอ้างเรื่องการรองรับและข้อยกเว้นตรงกับ implementation ที่ทดสอบแล้ว
9.2Integration guideบันทึก credential, config, ข้อจำกัด, reconciliation, ความแตกต่างของ environment และช่องว่างที่ทราบ
9.3Tester entry pointsจัดเตรียม data tester และ execution tester ฝั่ง Rust ที่เกี่ยวข้อง พร้อมค่าเริ่มต้นที่ปลอดภัย
9.4Operationsบันทึกการกู้คืน, การแก้ปัญหา และพฤติกรรมใด ๆ ของ venue ที่ผู้ดูแลระบบต้องเข้าใจ
9.5Final verificationตรวจสอบลิงก์, output ที่ generate, ตัวอย่าง และ documentation check ที่เกี่ยวข้อง

Exit: ผู้ใช้สามารถตั้งค่า, ทดสอบ, ใช้งาน และวินิจฉัย adapter ได้โดยไม่ต้องอ่าน source code

รูปแบบของ Rust adapter

นโยบายการ import ระดับ repository ใช้กับ code ของ adapter ด้วย: ให้ import type ของ Nautilus และใช้ชื่อสั้น แทนการเขียนชื่อเต็ม (fully qualified) ที่จุดเรียกใช้ Nautilus conventions hook บังคับใช้ กฎนี้และอธิบาย marker สำหรับข้อยกเว้นเฉพาะจุดไว้

Configuration (config.rs)

ให้ทำตามคู่มือ configuration ร่วม โดยเฉพาะ config ของ Rust ต้องใช้ฟิลด์แบบ typed, การ decode ด้วย Serde แบบเข้มงวด, แหล่งความจริงเดียวสำหรับค่าเริ่มต้น และ bon::Builder จากนั้น config ของ adapter จึงเพิ่มเฉพาะ semantics ของ venue:

  • ใช้ enum สำหรับชุดค่าแบบปิด เช่น environment, กลุ่มผลิตภัณฑ์, account mode หรือ endpoint

  • ใช้ Option<T> เฉพาะเมื่อการไม่มีค่ามีความหมายเฉพาะ รวมถึงการ fallback ไปหา credential ตอน runtime

  • แยก config ของ data และ execution เมื่อ capability หรือ credential ต่างกัน

  • เก็บฟิลด์ที่ต้องไม่ปรากฏใน Debug เป็น SecretString ให้ derive Debug เมื่อฟิลด์อ่อนไหวทุกตัว ใช้ type ที่ redact ได้ และเขียน implementation เองเฉพาะเมื่อมีเงื่อนไขข้อใดข้อหนึ่ง:

    • มีฟิลด์ที่ใช้ type ที่ redact ได้ไม่ได้
    • type ต้องการ output ที่จำกัดมากกว่านั้น

รวมการ resolve HTTP และ WebSocket endpoint ค่าเริ่มต้นไว้ที่จุดเดียว เพื่อไม่ให้การเลือก environment เดียวผสม endpoint ของ live และ test เข้าด้วยกัน คงการ override URL แบบระบุชัดไว้เฉพาะเมื่อ gateway ที่กำหนดเอง, mock server หรือ deployment ของ venue ต้องการ ทดสอบทุก environment ที่รองรับ และลำดับความสำคัญระหว่างการเลือก environment กับการ override แบบระบุชัด

จัดเรียงฟิลด์ของ config ตามลำดับนี้:

ลำดับกลุ่มฟิลด์กฎการวาง
1Account identity, credentials, environmentค่าที่เทียบเท่าของ venue นับรวมด้วย: network, deployment, region
2URL overridesอยู่ติดกันเป็นกลุ่มเดียว: base_url_http ก่อน แล้วตามด้วย base_url_ws* แต่ละตัว
3proxy_urlอยู่ถัดจากกลุ่ม URL ทันที
4ที่เหลือทั้งหมดtimeout, retry, พฤติกรรมเฉพาะของ venue

resolve override ที่เป็น None แต่ละตัวให้เป็นค่าเริ่มต้นของ environment ใน method ของ config แล้วส่ง URL ที่ resolve แล้วไปยัง constructor ของ client โดย constructor จะไม่อ่านฟิลด์ Option โดยตรง

รักษาลำดับสัมพัทธ์เดียวกันระหว่างฟิลด์ของ struct และ accessor ของ bon::Builder

Credential และการจัดการ secret

เมื่อ HTTP client และ WebSocket client ใช้ key material เดียวกัน ให้รวมการจัดการ credential ไว้ใน type เดียว โดยทั่วไป อยู่ใต้ common/credential.rs ให้ config เป็นเพียง data transfer object และ resolve credential ตอนสร้าง credential, factory หรือ client อย่า resolve credential ใน method ของ request แต่ละตัว

จัดประเภทค่าที่อ่อนไหว

จัดประเภทค่าก่อนเลือก type และ output สำหรับ diagnostic ให้ใช้กฎที่เข้มงวดกว่า เมื่อ venue ให้ค่าเดียวมีมากกว่าหนึ่งบทบาท

ประเภทค่าตัวอย่างOutput สำหรับ diagnostic
Secret materialpassword, private key, API secret, passphrase, bearer token และ session token, refresh token และ signatureแสดง <redacted> เสมอ
Credential identityAPI key, client ID, username และ account identifier ที่ใช้ระหว่าง authenticationredact โดยค่าเริ่มต้น ใช้ API key แบบ mask เฉพาะเมื่อจำเป็นต้องเชื่อมโยงข้อมูลในการปฏิบัติการ
Secret-bearing locationproxy URL, RPC URL, request path และ query parameter ที่อาจมี credentialแสดงได้อย่างมากแค่ public origin (ดูด้านล่าง) และ redact ทั้ง location หาก origin เป็น secret
Deliberately public identitywallet address, vault address และชื่อ account สาธารณะที่ venue เปิดเผยต่อสาธารณะแสดงเฉพาะเมื่อ type และ contract ของ adapter จัดประเภทค่านั้นเป็น public อย่างจงใจ

API key, username หรือ URL อาจไม่เพียงพอที่จะ authenticate ได้ด้วยตัวเอง แต่อย่าสรุปจากข้อนี้ว่า พิมพ์ออกมาได้อย่างปลอดภัย config มักข้ามขอบเขตของ logging และ error ซึ่ง identity ของ credential แม้เพียงบางส่วนก็ยังถือว่าอ่อนไหว

เมื่อ adapter จัดประเภท scheme, host และ port ของ URL เป็น public แล้ว diagnostic อาจแสดงได้เฉพาะ origin นั้น ให้ตัด user information, path, query และ fragment ออก หาก origin เองมี credential identity อยู่ อย่างที่ RPC URL บางตัวเป็น ให้ redact ทั้ง URL ด้วย SecretString หรือ REDACTED

ใช้ secret type ร่วม

ใช้ nautilus_core::string::secret, nautilus_network และ zeroize แทนการกำหนดแนวทางการ redact หรือ zeroize เฉพาะใน adapter

กลไกการใช้งาน
SecretStringถือ string ที่ต้อง zeroize เมื่อ drop และแสดงเป็น <redacted> เมื่อใช้ Debug
ConnectionUrlเก็บ URL ที่มี public origin โดย Debug จะแสดง origin นั้น ยืมค่าเดิมผ่าน expose() เฉพาะเมื่อจำเป็น
url_originformat public origin ของ URL แบบ HTTP หรือ WebSocket รวมถึงฟิลด์ String ที่เก็บไว้ซึ่งเข้ากันได้ มิฉะนั้นแสดง <redacted>
TransportError::redacted_messageรักษาหมวดของ transport แบบ typed, ชนิด I/O และ HTTP rejection status โดยตัด payload ของ error ที่ไม่แน่นอนออก
REDACTEDแทนที่ฟิลด์ secret แบบไม่มีเงื่อนไขใน implementation ของ Debug หรือ Display ที่เขียนเอง
redact_optionรักษาความต่างระหว่าง Some กับ None ขณะ redact ฟิลด์ optional ใน Debug ที่เขียนเอง
mask_api_keyเชื่อมโยง API key ผ่าน method สำหรับ identity แบบ mask ที่ระบุชัดเท่านั้น อย่าใช้กับ secret material
Zeroizing<T>จำกัดอายุของ String แบบ plaintext ที่ถือครอง, byte buffer, key ที่ decode แล้ว, canonical payload หรือ authentication message ที่ serialize แล้ว
Zeroize and ZeroizeOnDropล้างฟิลด์ที่มี secret ใน struct ที่ใช้ SecretString ไม่ได้ รวมถึง byte array และ type สำหรับการ sign
zeroize_json_valueล้าง string ที่ถือครองใน JSON value ที่แก้ไขได้ หลังจาก serialize ฟิลด์ที่มี secret

ใช้ SecretString อย่างปลอดภัย

  • ถือว่าการ serialize คือ plaintext เพราะ SecretString ใช้ string ข้างในเพื่อให้เข้ากันได้กับ wire format ดังนั้นห้าม serialize config, credential หรือ authentication model เพื่อใช้ทำ diagnostic
  • อย่าใช้การเปรียบเทียบความเท่ากันแบบปกติของ SecretString เพื่อตรวจสอบ secret ที่ผู้โจมตีควบคุมได้ เพราะไม่ใช่ constant-time
  • ยืม plaintext ผ่าน expose_secret() เฉพาะที่ขอบเขตการ sign, encode หรือ transport ที่ต้องใช้เท่านั้น
  • ใช้ into_inner() เฉพาะเพื่อโอนความเป็นเจ้าของ หาก API ปลายทางต้องการ String ให้สร้าง สำเนาสุดท้ายที่ขอบเขตการเรียก และอย่าเก็บสำเนานั้นไว้ใน code ของ adapter
  • หาก function แค่อ่านค่า ให้ส่ง &SecretString หาก function เก็บหรือใช้ค่านั้นจนหมด ให้ส่ง แบบ by value
  • วางฟิลด์ที่มี secret ไว้ใน wire model ที่ authenticate แล้ว แทนการสร้าง model ที่สองเพียง เพื่อเปลี่ยน Debug ให้ derive Serialize และ derive Debug เมื่อฟิลด์อ่อนไหวทุกตัว redact ได้
  • credential บางชนิดใช้ byte array, signing key หรือ type อื่นที่เก็บฟิลด์ secret เป็น SecretString ไม่ได้ สำหรับ credential เหล่านี้ให้เขียน Debug เอง
  • หลีกเลี่ยง Display สำหรับ type ที่มี secret เว้นแต่ผู้เรียกต้องการ และ implementation ใด ๆ ต้อง redact secret material

Resolve และแชร์ credential

  • กำหนดชื่อ environment variable เพียงครั้งเดียว และเลือกจากค่า environment และผลิตภัณฑ์แบบ typed
  • บันทึกชื่อ environment variable ที่กำหนดไว้ใน integration guide ของ adapter
  • ลงทะเบียน environment variable ทุกตัวของ adapter ใน scripts/strip-adapter-env.bash เพราะ make pre-flight รันผ่าน wrapper นั้นโดย unset ตัวแปรทั้งหมด ตัวแปรที่ไม่ได้ลงทะเบียนอาจทำให้ test ผ่าน บนเครื่อง local ทั้งที่พึ่งพา credential ที่มีอยู่ในสภาพแวดล้อม
  • resolve ทุกฟิลด์เป็น credential set เดียว public client อาจไม่ต้อง authenticate ได้ แต่ client ที่ authenticate ต้องปฏิเสธชุดที่ไม่ครบหรือไม่ถูกต้องก่อนส่ง request
  • แปลง string จาก config และ environment เป็นเจ้าของแบบ zeroizing ที่ขอบเขตของ credential และอย่า เก็บสำเนา plaintext ที่ไม่ zeroize ไว้ใน state ของ adapter หลังการแปลง
  • แชร์ที่เก็บ credential ข้าม transport เฉพาะเมื่อใช้ key material เดียวกัน ให้แยก method การ sign ของ HTTP, WebSocket และ transaction เมื่อ canonical payload ต่างกัน

จำกัดอายุของ plaintext

  • zeroize การ allocate แบบ plaintext ที่ถือครองแต่ละตัวหลังใช้งานครั้งสุดท้าย ซึ่งรวมถึง key ที่ normalize และ decode แล้ว, signing payload ที่มี secret, authentication message ที่ serialize แล้ว, ค่าของ form ที่ encode แล้ว และ request model ที่แก้ไขได้
  • เลือกใช้ slice แบบยืมและเจ้าของแบบ zeroizing ที่มีอยู่ แทนการทำสำเนาเป็น String และ Vec<u8> ระหว่างทาง
  • จำกัดการรับประกันไว้เฉพาะการ allocate ที่ adapter ถือครอง เพราะ serialization library, transport, TLS และระบบปฏิบัติการอาจทำสำเนาที่ adapter เข้าไม่ถึง
  • ทำให้อายุของ plaintext สั้น และอย่าสัญญาว่าจะลบข้อมูลได้ทั้ง process หรือทั้ง transport

Redact diagnostic และ transport error

  • ห้ามใส่ credential, signature, secret material หรือส่วนของ URL ที่มี secret ลงใน error หรือ log ไม่ว่าระดับใด แสดงได้อย่างมากแค่ origin ที่จัดประเภทเป็น public ตามกฎ location ด้านบน
  • log metadata ของ request เช่น method, จำนวนฟิลด์ และความยาว byte แทน credential หรือ authentication payload โดย transport ร่วมจะ log metadata แทนเนื้อหาของ payload
  • ถือว่า TRACE เป็น output สำหรับ diagnostic ที่มีไว้สำหรับนักพัฒนา อนุญาตให้มี payload ขาเข้าดิบได้เมื่อ schema ของมันไม่สามารถมี credential material ได้
  • ถือว่า TRACE output ดิบของ private stream เป็นข้อมูลอ่อนไหว เพราะอาจเปิดเผย order, balance, position และ identity ของ account ให้ redact ก่อนแชร์
  • เลือกใช้ metadata หรือข้อความบางส่วนที่ sanitize และจำกัดขนาดแล้ว เมื่ออย่างใดอย่างหนึ่งเพียงพอสำหรับวินิจฉัยโปรโตคอล
  • ล้าง source model ที่แก้ไขได้หลัง serialize เมื่อ model นั้นถือสำเนา plaintext อีกชุด
  • ห้าม log authentication request หรือ response ดิบ หรือ frame ใด ๆ ที่ schema อาจมี secret material
Surfaceการจัดการที่ต้องทำขอบเขต
HTTP secret bodyใช้ HttpClient::request_with_secret_bodyclient ถือเจ้าของแบบ zeroizing ไว้ ชั้นที่ต่ำกว่าอาจทำสำเนา
HTTP path or HashMap queryใช้ HttpClient::requestclient เพิ่มเฉพาะ origin ของ request เป็น URL context
HTTP typed queryใช้ HttpClient::request_with_paramsclient เพิ่มเฉพาะ origin ของ request เป็น URL context
HTTP secret originตั้ง HttpClient::builder().redact_url(true) สำหรับ endpoint ที่ origin เป็น secretclient ไม่เพิ่ม URL context ใด ๆ
HTTP headers and proxyสร้าง string ที่มี credential ที่ขอบเขตของ client, หลีกเลี่ยงการ clone และอย่าเก็บไว้ใน state ของ adapterclient หรือ transport ร่วมอาจเก็บสำเนาไว้
WebSocket authenticationเก็บฟิลด์และ frame ที่ serialize แล้วใน SecretString และสร้าง String สุดท้ายทันทีก่อน send_textclient ร่วมไม่มี method ส่งที่รักษาเจ้าของ secret ไว้
Unsupported combinationขยาย client ร่วมแทนการ implement การ scrub URL หรือ error เฉพาะใน adapterAPI ร่วมต้องกำหนดกฎความเป็นเจ้าของและการ redact ที่เป็นผลลัพธ์

policy ของ HTTP URL ควบคุม URL context ที่ HttpClient เพิ่มเข้าไป ส่วน diagnostic message จาก ชั้นที่ต่ำกว่าจะไม่เปลี่ยนแปลง ตัวอย่างเช่น การตรวจสอบ TLS certificate อาจใส่ hostname ไว้ใน error และ log ของ dependency แม้จะตั้ง redact_url(true) แล้วก็ตาม

ปิด redirect สำหรับ request ที่ authenticate

client ที่ส่ง credential หรือ payload ที่ sign แล้วต้องตั้ง HttpRedirectPolicy::Reject สำหรับ HTTP transport อื่นให้ใช้ policy ที่ไม่ redirect ในลักษณะเดียวกัน เพื่อไม่ให้ redirect ส่งต่อ credential หรือ payload ที่ sign แล้วไปยังปลายทางอื่น

ตรวจสอบการจัดการ credential

ทดสอบ contract ของการจัดการ secret นอกเหนือจากการ authenticate สำเร็จ:

  • ครอบคลุมค่าที่ระบุชัด, การ fallback ไปยัง environment, credential ที่ไม่ครบ และ credential ที่ไม่ถูกต้อง
  • assert ว่า output ของ Debug จาก config, credential, request, response และ client ไม่มี secret ที่ใส่เข้าไปตรงตัว ทดสอบ Display แยกต่างหากสำหรับทุก type ที่มี secret และ implement Display
  • assert ว่าการ serialize และ transport รักษาค่าบน wire ที่แน่นอนไว้ในจุดที่ venue ต้องการ plaintext
  • บังคับให้ transport ล้มเหลวสำหรับ URL ที่มี credential แล้ว assert ว่าทั้ง output ของ error แบบ Display และ Debug ไม่มี user information, secret ใน path, secret ใน query และ fragment และ assert ว่า public origin ที่อนุญาตยังมองเห็นได้ มิฉะนั้นให้ assert ว่า redact ทั้งหมด
  • ใช้ trait assertion ตอน compile สำหรับ Zeroize หรือ ZeroizeOnDrop และทดสอบการล้างค่าอย่างชัดเจนสำหรับ request model และ response model ที่แก้ไขได้
  • เก็บ signature vector แบบ deterministic ไว้ เพื่อไม่ให้การเปลี่ยนแปลงด้าน redaction และ zeroization เปลี่ยน byte ของการ sign, ลำดับฟิลด์ หรือ encoding

Symbol และ identity ของ instrument

แยก venue symbol ออกจากค่า InstrumentId ของ Nautilus โดยทั่วไป symbol module จะรับผิดชอบ:

  • การ parse และ format venue symbol
  • suffix ของผลิตภัณฑ์หรือสัญญาที่จำเป็นเพื่อให้ได้ Nautilus symbol ที่ไม่ซ้ำ
  • การ validate identity ของ venue และผลิตภัณฑ์
  • round-trip test สำหรับรูปแบบที่รองรับ และ test การปฏิเสธสำหรับรูปแบบที่กำกวม

เลือกการ map ตามรูปแบบ identity ของ venue:

Identity ของ venueรูปแบบใน Nautilusตัวอย่าง
native symbol แยกแยะผลิตภัณฑ์ได้อยู่แล้วคง symbol ไว้แล้วเพิ่ม venueBTC-USDT-SWAP -> BTC-USDT-SWAP.OKX
raw symbol ถูกใช้ซ้ำข้ามกลุ่มผลิตภัณฑ์เพิ่มและ validate suffix ของผลิตภัณฑ์ที่คงที่Bybit linear BTCUSDT -> BTCUSDT-LINEAR.BYBIT
Nautilus และ venue ใช้เครื่องหมายสัญญาต่างกันimplement ทั้งสองทิศทางไว้ที่ขอบเขตเดียวBinance USD-M BTCUSDT -> BTCUSDT-PERP.BINANCE
ตัวพิมพ์เล็กใหญ่ใน transport ต่างจาก identity แบบ canonicalแปลงเฉพาะตอนสร้างค่าสำหรับ transportBinance stream BTCUSDT-PERP.BINANCE -> btcusdt

wrapper BybitSymbol และ การแปลง symbol ของ Binance แสดงรูปแบบการใช้ suffix และการแปลงสองทิศทาง ให้ถือเป็นตัวอย่าง ไม่ใช่รูปแบบ suffix ร่วม

อย่า normalize instrument ของ venue ที่แตกต่างกันให้เป็น InstrumentId เดียวกัน ให้ test fixture มี symbol, precision, currency และฟิลด์ของสัญญาที่ต่างกัน เพื่อให้การสลับหรือการตกหล่นทำให้ test fail อย่างเห็นได้ชัด

สำหรับทุกกลุ่มผลิตภัณฑ์ที่รองรับ ให้ทดสอบ venue symbol -> InstrumentId -> venue symbol ให้ normalize ตัวพิมพ์เล็กใหญ่เพียงครั้งเดียวที่ขอบเขตของ identity และรักษาตัวพิมพ์ที่มีความหมายต่อ venue ไว้ในส่วนอื่น เมื่อการ map ต้องใช้ marker ของผลิตภัณฑ์ ให้ปฏิเสธ marker ที่ขาดหายหรือกำกวมก่อนนำ instrument เข้า cache

สร้าง instrument จาก definition ปัจจุบันของ venue ให้ validate identity และ precision ที่จำเป็น ก่อนนำเข้า cache หรือ emit และทำให้ function การ parse เป็นแบบ deterministic และไม่ขึ้นกับ state ของ live client เท่าที่ทำได้

การ model payload ของ venue

ให้ model ตาม wire format จริง ไม่ใช่ subset ที่คิดว่าคงที่:

  • ใช้ typed request struct และ response struct สำหรับฟิลด์ที่รู้จัก
  • ใช้ Serde alias หรือ custom deserializer เฉพาะเมื่อ payload ที่รองรับจำเป็นต้องใช้
  • ปฏิเสธค่าที่ไม่รู้จักสำหรับชุดค่าแบบปิดที่ความหมายมีผลต่อพฤติกรรมของ domain
  • รักษาไว้หรือจัดประเภทอย่างชัดเจนสำหรับค่าที่ไม่รู้จักในชุดค่าแบบเปิดของ venue ที่อาจขยายเพิ่มได้โดยไม่มี การเปลี่ยน version ของโปรโตคอล
  • แยก raw model ออกจาก domain object ของ Nautilus และแปลงที่ขอบเขตเดียวที่ตรวจสอบได้
  • ส่ง context ที่จำเป็นต่อการ parse อย่างชัดเจน รวมถึง precision ของ instrument, currency, identity ของ account และ ts_init และเก็บ state ของ live client ไว้นอก parser
  • จัดการค่าที่หายไป, null และค่าว่างตาม schema ของ venue อย่ารวมทั้งหมดเป็น fallback เดียวเมื่อแต่ละแบบมีความหมายต่างกัน
  • ใช้ timestamp ของ venue สำหรับ ts_event เมื่อ payload มีให้ และกำหนด ts_init จาก clock ของ adapter ตอนที่ได้รับหรือสร้าง event ใช้เวลาที่ได้รับเป็นเวลาของ event เฉพาะเมื่อ venue ไม่มี timestamp ที่เชื่อถือได้ และให้ทดสอบ fallback นั้นด้วย

หลีกเลี่ยง fallback แบบหละหลวมที่เปลี่ยนค่าใหม่จาก venue ให้กลายเป็นค่าทาง semantics ที่มีอยู่แล้วอย่างเงียบ ๆ การจัดการ error ที่คงที่เป็นส่วนหนึ่งของ contract ของ parser

Numeric precision

deserialize ราคา, ปริมาณ, เงิน, ค่าธรรมเนียม และค่าแบบ discrete อื่น ๆ เป็น Decimal แล้วสร้างค่า domain ด้วย Price::from_decimal, Price::from_decimal_dp, Quantity::from_decimal, Quantity::from_decimal_dp, Money::from_decimal หรือ Money::zero ห้ามส่งค่าจาก wire ผ่าน f64 เด็ดขาด ดู domain numeric types

เลือก precision ของ domain ตาม contract ของฟิลด์ ไม่ใช่ตามการ format ของ payload ที่บังเอิญเป็น:

Contract ของฟิลด์ผลลัพธ์ของ "25.000"การแปลง
scale ที่ venue ประกาศมีความหมาย25.000 ที่ precision 3ใช้ Price::from_decimal หรือ Quantity::from_decimal
ศูนย์ท้ายที่ระบุในเอกสารเป็นเพียง padding ที่ไม่มีความหมาย25 ที่ precision 0เรียก Decimal::normalize แล้วใช้ constructor ที่อนุมาน scale เอง
precision ของ instrument หรือ currency เป็นตัวกำหนดค่า25.00 ที่ precision 2ใช้ Price::from_decimal_dp หรือ Quantity::from_decimal_dp

ใช้ precision ของ instrument หรือ currency สำหรับค่าใน event และ report เมื่อมีให้ใช้ venue อาจส่งค่าเดียวกัน เป็น "25", "25.0" หรือ "25.000" ก็ได้ อย่าอนุมาน precision จากแต่ละ payload เว้นแต่ adapter จะกำหนดและ ทดสอบ compatibility fallback ไว้อย่างชัดเจน constructor ที่ประกาศ precision จะใช้ banker's rounding เมื่อ ค่ามีตัวเลขที่ไม่ใช่ศูนย์เกินมา หาก contract ของฟิลด์ต้องการการแทนค่าที่ตรงทุกประการ ให้ validate ความเท่ากันแบบ round-trip ระหว่าง reconciliation ให้ทำตาม การ resolve instrument เมื่อ metadata ของ precision ขาดหายไป

Fallback ของ enum ของ venue

venue ขยาย enum บน wire โดยไม่แจ้งล่วงหน้า: สถานะ order ใหม่, order type ใหม่ และรหัสหมวดหมู่ใหม่ปรากฏใน production ก่อนที่ client จะอัปเดต ให้ enum ของ venue ที่ขยายได้แต่ละตัวมี variant สำหรับ fallback ที่รองรับอนาคต ด้วย #[serde(other)] ใช้ Unknown สำหรับสถานะของ venue และใช้ Other สำหรับชุดค่าแบบเปิด เช่น type และ หมวดหมู่ ดังนั้นค่าใหม่ค่าเดียวจะไม่ทำให้การ deserialize ของ message ที่ถือค่านั้นล้มเหลว ส่วนชุดค่าแบบปิดที่ adapter กำหนดเองยังคงเข้มงวด

fallback เปลี่ยนตำแหน่งที่ความเข้มงวดอยู่ ไม่ได้ทำให้ความเข้มงวดหายไป:

  • ห้าม panic เมื่อเจอ wire variant ที่ไม่รู้จัก fallback ช่วยให้ connection และ record อื่นใน payload เดียวกันยังทำงานต่อได้
  • ห้าม map variant ที่ไม่รู้จักไปยังค่า domain ที่มีอยู่ ให้การ map ไปยัง domain เป็นแบบที่ล้มเหลวได้ (TryFrom) เพื่อให้ variant ของ fallback ถูกปฏิเสธอย่างชัดเจนที่ขอบเขตการ map
  • รักษาข้อมูลใน payload ที่สำคัญต่อความปลอดภัยไว้ แม้การจัดประเภทข้างเคียงจะ map ไม่ได้ หากสถานะ order หรือ order type ไม่รู้จัก adapter ยังต้อง parse และ emit fill เพราะฟิลด์ของ fill มีราคา, ปริมาณ และค่าธรรมเนียมของตัวเอง
  • ข้ามเฉพาะการจัดประเภทที่ map ไม่ได้ และ log warning พร้อม identifier ของ venue (order ID, instrument) ที่จำเป็นต่อการตรวจสอบ เมื่อ message ไม่มีข้อมูลที่ควรเก็บรักษา ให้ fail record นั้นอย่างชัดเจนแทน การสร้างสถานะขึ้นมาเอง reconciliation จะเติมช่องว่างเมื่อ order ไปถึงสถานะที่ map ได้ ค่าที่ map ไม่ได้ จะ fail แบบเดียวกันบนเส้นทาง reconciliation ดังนั้นให้ถือว่า warning เป็นสัญญาณให้เพิ่มการ map

แยก authority ออกจาก projection

endpoint อาจคืนทั้งหลักฐานด้าน authority และข้อมูลสำหรับการอ่านที่แคบกว่า โดยหลักฐานนั้นใช้ยืนยัน สิทธิ์หรืออนุญาตให้เปลี่ยน state สำหรับ endpoint แบบนี้ให้ใช้ response model แยกกัน

ขอบเขตจุดประสงค์การ validateความหมายของความสำเร็จ
Authoritative responseยืนยันสิทธิ์หรืออนุญาตให้เปลี่ยน stateต้องมีฟิลด์ authority ครบทั้งหมด และปฏิเสธข้อขัดแย้งแบบ legacy และรายการซ้ำทาง semantics ก่อนการ mapresponse สามารถรองรับการตัดสินใจด้าน authority ที่มัน model ไว้ได้
Narrow projectionอ่าน balance, ค่า health หรือ metadata โดยไม่ใช้ authoritydecode เฉพาะฟิลด์ที่คืนมา และ type ของมันไม่สามารถเปิดเผย, ให้ หรืออนุมาน authority ที่ถูกละไว้ได้เฉพาะค่าที่ project ออกมา ส่วนหลักฐานด้านสิทธิ์หรือ account ที่ถูกละไว้ถือว่าไม่ทราบ

ใช้ projection เมื่อฟิลด์ authority ที่ผิดรูปแบบต้องไม่ขัดขวางการอ่านที่แคบกว่า และให้ authoritative model เข้มงวดเสมอ

Client trait และ factory (data.rs, execution.rs, factories.rs)

trait ร่วม DataClient, ExecutionClient และ client factory กำหนดขอบเขตของ adapter ให้ implement method ที่รองรับ และระบุ capability ที่ไม่รองรับไว้อย่างชัดเจนใน integration guide

client trait ใช้ #[async_trait(?Send)] object ของ client ไม่ได้ออกแบบมาให้ย้ายข้าม thread และอาจถือ state ที่ไม่เป็น Send ไว้ เมื่องาน asynchronous ต้องอยู่นานกว่าการเรียก trait แบบ synchronous ให้ move input ที่เป็นเจ้าของและเป็น Send เข้าไปใน runtime task ที่สร้างอย่างชัดเจน

การตั้งชื่อและลงทะเบียน client

ตั้งชื่อแต่ละกลุ่มของ client ให้สมมาตรกัน:

  • Data: <Venue>DataClient, <Venue>DataClientConfig และ <Venue>DataClientFactory
  • Execution: <Venue>ExecutionClient, <Venue>ExecutionClientConfig และ <Venue>ExecutionClientFactory

factory แต่ละตัวรับ client config ที่คู่กันโดยตรง อย่าเพิ่ม wrapper ของ factory config แยกต่างหาก live node ส่ง LiveNodeConfig.trader_id ไปยัง execution factory ขณะที่ค่าเฉพาะของ venue เช่น account_id อยู่ใน config ของ execution client

อย่าใส่ prefix Live ให้กลุ่ม client ปกติ เพราะ client ที่เชื่อมต่อแล้วเป็นค่าเริ่มต้นอยู่แล้ว ชื่ออย่าง SandboxExecutionClient และ DatabentoHistoricalClient ใช้ระบุพฤติกรรมทางเลือก ให้คง Live ไว้เฉพาะเมื่อ ใช้แยกแยะ sibling ด้าน runtime หรือโปรโตคอลอย่างชัดเจน ส่วน runtime type อย่าง LiveNode, LiveClock และกลุ่ม Live*EngineConfig ยังคงใช้คำนำหน้านี้

อย่าย่อ Execution ในชื่อ type แบบ PascalCase ที่เป็น public และโปรเจกต์เป็นเจ้าของ type ภายใน implementation อาจคงชื่อ Exec ที่ใช้กันมาได้ และให้คง Exec ไว้ในจุดที่ แนวทางการตั้งชื่อทั่วไป อนุญาต รวมถึงคำศัพท์ในโปรโตคอลของ venue เช่น ExecType ตั้งชื่อ wire model เฉพาะโปรโตคอลตามแนวคิดของ venue เช่น HyperliquidExchangeAction ให้คงชื่อ public ที่ใช้กันมาแล้ว และใช้แนวทางนี้กับ API ใหม่

Input ของ factory และความเป็นเจ้าของ cache

factory ได้รับ ClientConfig ที่ downcast แล้ว และ CacheView แบบอ่านอย่างเดียว ส่วน data factory ได้รับ clock ร่วมด้วย ใช้ view นี้เพื่อ resolve instrument และ state ที่มีอยู่ การเขียน cache ของ engine ยังคงอยู่ใน engine: ให้ emit domain event และ report แทนการแก้ไข cache ของ engine จาก adapter ส่วน protocol cache แบบ private ใช้ได้เมื่อการ parse, การ replay subscription หรือการจับคู่ response ต้องใช้

State ที่ adapter เป็นเจ้าของ

เลือก collection ตามความเป็นเจ้าของและพฤติกรรมการอัปเดต:

  • ใช้ AHashMap หรือ AHashSet ธรรมดาสำหรับ state ที่ task เดียวเป็นเจ้าของ
  • ใช้ AtomicMap หรือ AtomicSet สำหรับ snapshot แบบ immutable ที่อ่านบ่อยและเขียนไม่บ่อย ใช้ rcu เมื่อ writer อาจแข่งกัน (race) เพราะการ load และ store แยกกันอาจทำให้ update ของ writer อีกตัวหายไป
  • ใช้ DashMap หรือ DashSet สำหรับ key ที่เป็นอิสระต่อกันซึ่งได้รับ entry update พร้อมกัน

adapter ใช้รูปแบบเหล่านี้ผสมกันแตกต่างกันไป ให้เก็บ collection ไว้หลัง component ที่เป็นเจ้าของ invariant ของมัน แทนการแชร์เพียงเพื่อเลี่ยงการส่ง message ใช้ Ustr สำหรับ string ของโปรโตคอลที่ซ้ำกัน เมื่อการ intern ช่วยลดต้นทุนการ allocate หรือการเปรียบเทียบ ส่วน request ID ที่ไม่ซ้ำและข้อความ payload อายุสั้นให้เก็บใน type ตามธรรมชาติของมัน

วงจรชีวิตของ connection (connect)

ถือว่า method ของวงจรชีวิตแต่ละตัวเป็น contract:

MethodความรับผิดชอบPostcondition เมื่อสำเร็จ
startติดตั้งระบบส่ง event ฝั่ง local และเริ่มงาน background ที่ client เป็นเจ้าของเส้นทาง event ฝั่ง local มีอยู่ก่อนที่ task ใดจะ publish ได้
connectสร้าง transport, authenticate, load definition หรือ account state ที่จำเป็น และเริ่มประมวลผล streamคำสั่ง public ใช้ transport ได้ และ state สำหรับ bootstrap ที่จำเป็นสังเกตได้แล้ว
disconnectหยุดงาน network ใหม่และปิด transportclient ไม่ส่งหรือรับ traffic ของ venue อีก
stopยุติงานที่ client เป็นเจ้าของผ่านเส้นทางแบบ idempotentการ teardown ซ้ำปลอดภัย
resetล้าง cache ที่ reconnect ได้, counter, state ของการ cancel และ state ของ in-flight ที่เก่าแล้วการ start หรือ connect ครั้งถัดไปจะไม่รับ state ของ session ที่ไม่ถูกต้องสืบทอดมา
disposeปล่อย background task, thread และ handle ภายนอกไม่มี resource ที่ client เป็นเจ้าของเหลือทำงานอยู่

อย่ารายงานว่า connected จนกว่าคำสั่ง public จะใช้ transport ได้ และ state ที่จำเป็นฝั่ง engine สังเกตได้แล้ว reconciliation และการเริ่มต้น strategy ถือว่า connected เป็นสัญญาณความพร้อม:

  • execution client ที่ emit account state เริ่มต้นแบบ asynchronous ต้องรอจนกว่า cache ของ engine จะมี account ก่อนเรียก set_connected
  • ใช้กฎความพร้อมเดียวกันกับ state สำหรับ bootstrap ของ instrument หรือ stream ที่จำเป็น
  • เมื่อการเชื่อมต่อ transport เสร็จก่อนที่ socket จะ active ให้ใช้ขั้นตอน wait_until_active แบบมีขอบเขตก่อน subscribe หรือรายงานความพร้อม

หากการเชื่อมต่อล้มเหลวหลังจาก resource บางส่วนเริ่มทำงานแล้ว ให้ cleanup resource เหล่านั้น และทิ้ง state ให้สอดคล้องสำหรับการ retry หรือการ dispose

การตั้งค่า sender ของ execution event

สำหรับ execution client ที่ใช้ ExecutionEventEmitter ให้ติดตั้ง sender ทั้งสองขั้นตอน:

  1. ตอนสร้าง factory: resolve sender ด้วย try_get_exec_event_sender เมื่อคืนค่า Some ให้ติดตั้ง sender ใน create ก่อนคืน client LiveNodeBuilder จะ bind sender ของ runner เข้ากับ thread-local storage ก่อนเรียก factory ที่ลงทะเบียนไว้ ดังนั้น sender จึงพร้อมใช้ในทุก factory

    None หมายความว่า thread ที่เรียกไม่มี sender ที่ bind ไว้ ซึ่งเป็นเรื่องปกติใน unit test ของ factory หรือ host ที่ bind ภายหลัง และไม่ถือว่าการสร้างล้มเหลว

  2. ตอน client start: ติดตั้ง sender จาก get_exec_event_sender ใน start โดยไม่มีเงื่อนไข LiveNode จะ bind sender ของ runner ใหม่บน thread ที่เรียกก่อน start client ดังนั้น การติดตั้งนี้จึงเป็นตัวที่มีผลจริง emitter แชร์ช่องเก็บ sender เดียวกันข้าม clone ทั้งหมด จึงไปถึง ทุก clone ที่สร้างระหว่างการ construct รวมถึง clone ที่ส่งให้ task ที่ client เป็นเจ้าของ

หาก host เรียก factory นอก LiveNodeBuilder ต้อง bind sender ของ runner บน thread ของ client ก่อน start เพราะ get_exec_event_sender อ่านเฉพาะช่อง thread-local และจะ panic หากไม่มีใคร bind ช่องนั้น

sender ที่ส่งผ่าน factory หรือ constructor ของ client ของ host จะไปถึงช่องร่วมของ emitter ผ่าน set_sender แต่ไม่ได้เติมช่อง thread-local ดังนั้น constructor injection เพียงอย่างเดียวจึงไม่เพียงพอสำหรับ การ lookup

constructor injection ใช้ได้โดยลำพังเฉพาะเมื่อ start ของ client ยอมรับ sender ที่ติดตั้งไว้แล้ว แทนการ lookup แบบไม่มีเงื่อนไข execution client ที่ใช้ emitter ทั้งหมดใน repository นี้ทำการ lookup ดังกล่าว

ลำดับการ bootstrap

code ของการเชื่อมต่อแตกต่างกันไป แต่ความสัมพันธ์ของการพึ่งพาไม่เปลี่ยน โดยทั่วไป data client จะ:

  1. resolve environment และ validate credential ที่จำเป็นระหว่าง bootstrap
  2. fetch definition ของ instrument ที่จำเป็นและเติม context สำหรับการ parse
  3. publish definition ที่ engine ต้องสังเกตเห็นก่อนข้อมูลจะมาถึง
  4. start transport และรอให้เส้นทางคำสั่ง active
  5. subscribe หรือ replay เจตนาหลังจาก handler initialize แล้วเท่านั้น
  6. รายงาน connected หลังจาก state ของ engine และโปรโตคอลที่จำเป็นพร้อมแล้ว

execution client โดยทั่วไปจะ:

  1. validate credential, identity ของ account และ context ของ instrument ที่จำเป็น
  2. สร้างและ authenticate private transport
  3. เริ่มประมวลผล stream และ subscription ในลำดับที่ไม่ทำให้ acknowledgement หรือ account update สูญหาย
  4. fetch และ emit account state เริ่มต้น หรือรอ snapshot จาก stream ที่เชื่อถือได้
  5. รอให้ account state และ instrument state ที่จำเป็นสังเกตได้จากฝั่ง engine
  6. รายงาน connected หลังจากคำสั่งและ reconciliation รันได้แล้วเท่านั้น

ให้ถือสิ่งเหล่านี้เป็นข้อจำกัดด้านการพึ่งพา ไม่ใช่ชื่อ function ที่บังคับ venue สามารถรวมหรือสลับลำดับ ขั้นตอนได้เมื่อ test พิสูจน์ postcondition เดียวกัน หากขั้นตอนใดล้มเหลวหลังจาก resource เริ่มทำงานแล้ว ให้ teardown resource เหล่านั้นก่อนคืน error

Data client

subscription แสดงเจตนาที่ต่อเนื่อง ส่วน request คือการขอข้อมูลปัจจุบันหรือข้อมูลย้อนหลังจาก provider ให้แยก semantics ด้านความสดของทั้งสองอย่างออกจากกัน:

  • request ของ instrument แบบระบุชัดจะ fetch จาก provider เว้นแต่ contract ของ API จะอนุญาตให้ใช้ผลจาก cache อย่างชัดเจน
  • private cache สามารถให้ context สำหรับการ parse ได้ แต่ต้องไม่ทำให้ request ใหม่กลายเป็น response ที่เก่า
  • emit response เฉพาะข้อมูลที่ตรงกับ identity และ filter ของ request
  • รักษา correlation ID และ parameter ดั้งเดิมของ request ไว้ใน response event

envelope ร่วม DataEvent เป็นตัวกำหนดว่าข้อมูล จะเข้าสู่ engine อย่างไร:

Variantการใช้งานContract ที่ต้องรักษา
DataEvent::Instrumentdefinition ของ instrument จาก bootstrap, request หรือ updateรักษา identity, precision และ timestamp ของ venue ให้ครบเมื่อมี
DataEvent::InstrumentStatusการเปลี่ยนสถานะการซื้อขายหรือความพร้อมใช้งานemit transition ที่มีความหมาย แทน snapshot จากการ poll ที่ไม่เปลี่ยนแปลง
DataEvent::Datatrade, quote, ข้อมูล order book, bar และ market data แบบ typed อื่น ๆparse และสร้างขอบเขตของ event ให้เสร็จก่อน emit
DataEvent::Responseผลลัพธ์ของ request ข้อมูลปัจจุบันหรือข้อมูลย้อนหลังรักษา correlation, parameter, filter และ semantics ด้านความสดของ request
DataEvent::FundingRateupdate ของ funding rate สำหรับ derivativeรักษาเวลาที่มีผลหรือเวลาของ event จาก venue และ identity ของ instrument
DataEvent::OptionGreeksoption greeks ที่ venue ให้มารักษา instrument ต้นทาง และแยกค่าจาก venue ออกจากการคำนวณฝั่ง local
DataEvent::DeFiข้อมูล decentralized finance ที่อยู่หลัง feature flagemit เฉพาะเมื่อ adapter และ build เปิด feature ร่วม defi

เพิ่ม regression test ที่เปลี่ยน response ของ instrument จาก upstream ระหว่างสอง request response ที่สองต้องสะท้อน state ใหม่ของ venue แทนที่จะเป็น entry ใน private cache

publish ข้อมูลแบบ typed ผ่านเส้นทาง data event ของ engine ให้ parse และ validate ก่อน emit และอย่าถือ state ของ adapter ที่แก้ไขได้ค้างไว้ระหว่างการ dispatch ไปปลายทาง event receiver ที่ปิดแล้วโดยปกติหมายความว่า engine กำลัง หยุดทำงาน ให้ log ความล้มเหลวในการส่ง และให้การ teardown ตามวงจรชีวิตเป็นผู้จัดการการกู้คืน แทนการ retry event เดิม ไปเรื่อย ๆ

สำหรับ order-book delta ให้ทำตาม contract ของ delta flag และขอบเขตของ event update เชิงตรรกะแต่ละครั้งจบด้วย F_LAST ส่วน snapshot ใช้ F_SNAPSHOT และจบด้วย F_SNAPSHOT | F_LAST รวมถึง snapshot ว่างที่แทนด้วย Clear เพียงอย่างเดียว

หาก venue ให้สถานะของ instrument เป็น snapshot จากการ poll เท่านั้น ให้เปรียบเทียบกับ snapshot เต็มครั้งก่อน แล้ว emit เฉพาะการเปลี่ยนแปลง ไม่ใช่ส่งสถานะทั้งหมดซ้ำ จัดการ instrument ที่หายไปจาก snapshot ตาม contract ของ venue โดย map การหายไปเป็น NotAvailableForTrading เฉพาะเมื่อการหายไปหมายความว่า instrument นั้น ใช้งานไม่ได้ ให้อัปเดต private cache ทั้งหมดแม้การ emit จะถูกกรองเหลือเฉพาะ subscription ที่ active

ความเป็นเจ้าของการกู้คืน order book

nautilus_live::book มีกลไกการกู้คืนร่วมให้ใช้ ให้เก็บ การ synchronize และการกู้คืน book เฉพาะของ venue ไว้ใน src/book/ ของแต่ละ adapter โดยให้ stream handler เป็นผู้ dispatch คำสั่งและ frame

การ sync ราย book

BookSync เก็บ phase ของ book หนึ่งตัว (รอ snapshot แรก, sync แล้วที่ตำแหน่งหนึ่งของ venue หรือ กำลังกู้คืน), snapshot ที่ค้างอยู่ และ state ของการกู้คืน มันไม่ทำ I/O ใด ๆ ดังนั้น L0 property test จึงขับมันผ่านลำดับเหตุการณ์ใด ๆ ของ subscribe, snapshot, gap, rejection, reconnect และ deadline ได้

book ที่ไม่ sync ต้องมีเจ้าของ: การกู้คืนที่กำลังทำงานอยู่ หรือ snapshot deadline ที่ตั้งไว้ BookSync::gap จะขอการกู้คืนเฉพาะเมื่อไม่มีทั้งสองอย่าง และ BookSync::claim ยอมให้มีการกู้คืนที่ทำงานอยู่ เพียงหนึ่งตัวในแต่ละครั้ง ดังนั้นการรายงาน gap ซ้ำ ๆ จึงไม่ทำให้เกิดการกู้คืนที่แข่งกัน ให้ตั้ง deadline เฉพาะ ในจุดที่มี monitor คอยตรวจ มิฉะนั้น book จะมีเจ้าของที่ไม่เคยทำอะไรเลย ส่วนการรายงาน feed ที่ค้าง (stale) จะครอบคลุม ทุก book ที่ไม่มีการกู้คืนที่ทำงานอยู่เป็นเจ้าของ

  • OKX, Polymarket, Binance, Hyperliquid, Bybit และ AX Exchange เก็บ BookSync หนึ่งตัวต่อหนึ่ง book
  • Derive เก็บ BookSync หนึ่งตัวต่อ wire channel ที่ตรงกันพอดี โดยแชร์ระหว่างผู้ใช้ delta และ depth ที่มี argument ตรงกัน
  • Betfair เก็บ BookSync หนึ่งตัวต่อหนึ่ง market เพราะมันสร้างภาพ (image) ของทั้ง market
  • Lighter เก็บ BookRecoveryState หนึ่งตัวต่อหนึ่ง book ไว้ใน tracker ที่ handler เป็นเจ้าของ

การเริ่มการกู้คืน

การกู้คืนของ book ที่ใช้ BookSync ผ่านสี่ขั้นตอน และ book อาจหยุดระหว่างขั้นตอนใดก็ได้:

  1. Mark: BookSync::gap ย้าย book ไปเป็น Recovering ซึ่งจะไม่ emit อะไรเลย
  2. Request: การเรียกเดียวกันจะคืนค่า BookSequenceOutcome::Recover เฉพาะเมื่อไม่มีการกู้คืนที่ทำงานอยู่ หรือ snapshot deadline ที่ตั้งไว้เป็นเจ้าของ book การ request ไม่ได้ให้ความเป็นเจ้าของ ดังนั้นการเรียกครั้งต่อ ๆ ไปจะคืน Recover อีกจนกว่าจะมีการ claim episode
  3. Claim: BookSync::claim รับ episode หนึ่งตัว ซึ่งจะเป็นเจ้าของ book และยกเลิกการรอ snapshot ที่ค้างอยู่
  4. Run: adapter spawn BookRecovery::run สำหรับ episode ที่ claim แล้วภายใน task scope ของตัวเอง

Binance ทำการ claim ในขั้นตอนเดียวกับที่ตรวจพบ gap: ทุก diff ของ book ที่ยังไม่ sync จะลอง claim ซึ่งจะปฏิเสธขณะที่มี episode ทำงานอยู่

เมื่อเริ่มการกู้คืนไม่ได้ ให้ book ยังสามารถขอใหม่ได้:

  • ตรวจสอบสิ่งที่การแทนที่ต้องใช้ เช่น socket, channel หรือ token ก่อน claim เพื่อให้การ return ก่อนกำหนดทิ้ง book ไว้โดยไม่มีเจ้าของ
  • ส่ง incremental update ทุกตัวของ book ที่ยังไม่ sync ผ่าน BookSync::gap รวมถึง update ที่มาถึงขณะที่ book กำลังกู้คืนอยู่แล้ว การระงับ update โดยดูแค่ phase จะทิ้ง book ที่ ไม่มีใครเป็นเจ้าของไว้: output ของมันจะเงียบไปจนกว่า snapshot จะบังเอิญมาถึง
  • หาก task scope ปฏิเสธ task ของ episode ที่ claim แล้ว ให้ cancel episode นั้น เช่น ใช้ drop guard บน cancellation token ของ episode โดย task จะรับความเป็นเจ้าของ guard นี้ไป episode ที่ทำงานอยู่โดยไม่มี task จะเป็นเจ้าของ book และปฏิเสธการ claim ทุกครั้งหลังจากนั้น
  • อย่าเริ่มอะไรหลัง unsubscribe หรือ shutdown การลบ book จะ cancel episode ของมัน และ task scope ที่ปิดแล้วจะปฏิเสธ task ดังนั้น drop guard จะ cancel การ claim ที่มาช้า

State ของการกู้คืนและงบการ retry

เก็บ BookRecoveryState หนึ่งตัวต่อหนึ่ง book ที่ subscribe ไว้ ภายใต้ state lock ที่มีอยู่ของ adapter หรือ task ที่เป็นเจ้าของ จะเก็บ โดยตรงหรือเก็บไว้ใน BookSync ร่วมราย book ก็ได้ มันยอมให้มีการกู้คืนที่ทำงานอยู่หนึ่งตัวและ cancel งาน ที่ล้าสมัย book จะไม่จบลงในสถานะล้มเหลวเลย

BookRecovery::run เป็นเจ้าของความพยายามแทนที่, child cancellation token, การรอ snapshot, backoff และขีดจำกัดการ retry มันจะพยายามได้สูงสุดแปดครั้งภายใน 180 วินาที หลังจากใช้งบนั้นหมด ช่วงเวลาการ retry จะเพิ่มเป็นสองเท่าจากหนึ่ง นาทีจนถึงสิบห้านาที การ retry จะดำเนินต่อไปจนกว่า book จะยอมรับ snapshot หรือ episode ถูก cancel ส่วน error ที่ classifier ปฏิเสธจะข้ามไปใช้ช่วงเวลานั้นทันที

แต่ละความพยายามหลังจากใช้งบหมดจะมีขอบเขต max(snapshot_timeout, 60 seconds) ดังนั้นการเขียนที่ค้างหรือ snapshot deadline ที่ปิดไว้จะไม่สามารถหยุดการ retry ได้ adapter เป็นผู้จัดหา operation สำหรับการแทนที่และ error classifier

ให้ invocation ที่ทำงานอยู่ยังคงอยู่ข้ามการ reconnect เพื่อไม่ให้การ reconnect เติมงบใหม่ หรือละทิ้งการเขียนเพื่อแทนที่ การ reconnect ไม่เคยขัดจังหวะความพยายามหรือทำให้ backoff สั้นลง ภายในงบ แต่จะปลุก invocation ที่กำลังรอระหว่างความพยายามหลังจากใช้งบหมด เพื่อให้ ความพยายามถัดไปใช้ connection ใหม่ทันที ส่วนการ reconnect ที่เกิดขึ้นระหว่างความพยายาม หรือก่อน งบจะหมด จะไปยุติการรอระหว่างความพยายามครั้งถัดไปหลังจากใช้งบหมดแทน

การยอมรับ snapshot

การเขียนที่ได้รับการยืนยันเพียงอย่างเดียวไม่ได้ทำให้ได้ book ที่ใช้งานได้ ให้ประสานการแทนที่และการยอมรับตาม ลำดับนี้:

  1. ปิด SnapshotGate ก่อนการแทนที่
  2. เปิด gate หลังจาก connection ที่ตั้งใจใช้ยืนยันการเขียน subscription แล้ว
  3. ยอมรับ snapshot ภายใต้ขอบเขตความเป็นเจ้าของเดียวกับที่เริ่มการกู้คืน แล้วแทนที่ทุก level รวมถึงกรณี snapshot ว่าง

PendingSnapshot จะ cancel การรอเริ่มต้นเมื่อ snapshot ถูกยอมรับ หรือเมื่อเจ้าของที่ค้างอยู่ถูกลบออก

กฎของ venue และการตัดสินใจร่วม

adapter เป็นเจ้าของการจัดลำดับ (sequencing), การ route channel, คำสั่งบน wire, การจับคู่ acknowledgement และ การ parse snapshot ส่วน type ร่วมอธิบายผลลัพธ์ของการ validate และการ monitor:

  • BookSequenceOutcome: accept, suppress หรือ recover โดย adapter ยังคงกฎการ validate และ diagnostic ของ gap ไว้เอง

  • BookSyncSignal: feed ที่ค้างหรือ snapshot ที่ขาดหายของ book หนึ่งตัว

  • Lighter: คง generation ของ subscription และการจับคู่ control-ack/typed-snapshot ไว้

  • OKX: คง ข้อจำกัดของการจับคู่ acknowledgement ที่บันทึกไว้

  • Hyperliquid: ยอมรับทุก frame l2Book เป็น snapshot เมื่อเปิดการกู้คืน stream ที่ค้าง stream health monitor ของมันจะเริ่มการกู้คืนสำหรับ delta book ที่ค้าง

  • Betfair: มี market subscription หนึ่งตัวต่อหนึ่ง connection ดังนั้นการแทนที่จะสร้างภาพใหม่ของทุก market การกู้คืนจะเข้าร่วมกับ image request ที่ค้างอยู่แทนการเขียน subscription ที่แข่งกัน และการ reconnect จะกลับมาใช้ book ที่ sync แล้วต่อจาก clock ของ subscription

  • AX Exchange: ยอมรับทุก frame ของ L2 และ L3 เป็น snapshot และเก็บ book ไว้ข้ามการ reconnect ของ client เพราะ WebSocket client ของมัน replay subscription ตอน connect

  • Derive: ยอมรับ full snapshot เฉพาะเมื่อ timestamp เดินหน้า และคงค่าต่ำสุดนั้นไว้ข้าม การ reconnect snapshot ว่างที่ timestamp เดินหน้าจะนับเป็น update การแทนที่ใช้คู่ unsubscribe/subscribe บน socket ที่มีอยู่ ดู การกู้คืน order book ของ Derive สำหรับ ค่าเริ่มต้นของ timer และข้อจำกัดของการจับคู่ notification

adapter แบ่งออกเป็นสองกลุ่มตามการกู้คืน ซึ่งเป็นตัวกำหนด oracle ที่ stress harness ใช้ได้:

  • Push (OKX, Polymarket, Lighter, Hyperliquid, Bybit, Betfair, AX Exchange, Derive): การแทนที่ จะ subscribe ใหม่ และ stream ของ venue จะส่ง snapshot มา
  • Pull (Binance): diff stream ยังคง subscribe อยู่ การแทนที่จะ fetch REST snapshot และ adapter จะยอมรับเฉพาะเมื่อ diff ที่ buffer ไว้ต่อเนื่องจาก lastUpdateId ของมันโดยไม่มี gap

อายุของ task และการ cancel

รันงาน asynchronous ภายใน task scope ของ client หรือ future ที่ handler เป็นเจ้าของ handler ต้อง ดึงคำสั่งและ frame ออกมาประมวลผลต่อไปขณะที่การเขียนรออยู่ เพื่อให้ unsubscribe, shutdown และ recovery deadline สามารถ cancel operation ที่ล้าสมัยได้

การตั้งชื่อและการตั้งค่า

adapter ที่ implement กลไกนี้ใช้ชื่อและการปรับจูนร่วมกัน เพื่อให้ผู้ดูแลระบบย้ายไปมาระหว่าง venue ได้โดยไม่ต้องเรียนรู้พฤติกรรมใหม่:

  • เก็บ state ของการ sync book ไว้ใน src/book/sync.rs หลัง BookSyncTracker
  • รอ snapshot ด้วย book_snapshot_timeout_secs ซึ่งมีค่าเริ่มต้นเป็นค่าร่วม DEFAULT_BOOK_SNAPSHOT_TIMEOUT_SECS (10 วินาที) ใน nautilus_live::book ค่านี้ยังปรับได้ตาม deployment
  • ถือว่า timeout เป็นศูนย์คือการปิด snapshot deadline บนเส้นทางการรอทั้งหมด ซึ่งรวมถึงการส่งที่ adapter เป็นเจ้าของและ การรอ snapshot นอก runner ร่วม เมื่อไม่มี deadline การรอเหล่านั้นจะจบเฉพาะเมื่อถูก cancel ส่วน runner ร่วมยังคงจำกัดการกู้คืนด้วยงบเริ่มต้น 180 วินาที และด้วยความพยายามครั้งละหนึ่งนาทีหลังจากนั้น
  • เก็บ live stress harness ไว้ที่ tests/stress/book_stress.rs ในฐานะ test target <venue>-book-stress โดยข้อกำหนด order book sync conformance กำหนด contract ที่มันตรวจสอบและ fault ที่มันบังคับให้เกิด

Execution client

execution client แปลคำสั่ง, รักษา identity ของ order, publish account state และสร้าง report สำหรับ reconciliation โดยต้องรองรับขอบเขตเหล่านี้อย่างสม่ำเสมอ:

  • validate ข้อจำกัดฝั่ง local แบบ deterministic ก่อน submit
  • emit OrderSubmitted เฉพาะเมื่อคำสั่งเข้าสู่เส้นทางการ submit ของ adapter แล้ว
  • จับคู่ response ของ venue และ stream update กับ client order ID และ venue order ID ที่ถูกต้อง
  • emit balance และ margin ด้วย account type และ base currency ที่ factory ใช้
  • สร้าง report ของ order, fill, position และ mass-status จาก state ของ venue สำหรับ reconciliation
  • ปล่อยการยืม (borrow) ของ clock, cache หรือ account ร่วมก่อน publish account state เพราะ subscriber อาจเข้าถึง state เดียวกันแบบ synchronous

เก็บการตรวจสอบเฉพาะ adapter แบบ deterministic ไว้ใน function validate_order เดียวที่คืนค่า OrderDeniedReason และเรียกก่อน emit OrderSubmitted จากทั้งเส้นทางการ submit แบบ order เดียวและแบบ order list

อย่าอนุมานการรองรับจาก API ของ venue เพียงอย่างเดียว ให้ implement และทดสอบ semantics ของคำสั่งและ event ของ Nautilus ก่อน แล้วจึงประกาศ capability นั้น

Reconciliation report

reconciliation อ่าน state ของ venue ผ่าน method สำหรับ report ห้าตัวของ ExecutionClient โดย method เหล่านี้คืน report แทนการ emit order event และปล่อยให้ execution engine ตัดสินว่าความแตกต่าง ระหว่าง state ใน cache กับ state ของ venue หมายถึงอะไร

Methodสิ่งที่สร้างถูกเรียกโดย
generate_order_status_reportOrderStatusReport แบบ optional หนึ่งตัวprobe เฉพาะเจาะจงสำหรับ order หนึ่งตัวที่ open-order check ยัง resolve ไม่ได้
generate_order_status_reportsค่า OrderStatusReportmass status และ open-order check แบบเป็นรอบ
generate_fill_reportsค่า FillReportmass status
generate_position_status_reportsค่า PositionStatusReportmass status และ position check แบบเป็นรอบ
generate_mass_statusExecutionMassStatus แบบ optional หนึ่งตัวreconciliation ตอน startup หนึ่งครั้งต่อ execution client

Execution reconciliation อธิบายว่า engine ทำอะไรกับ report เหล่านี้ รวมถึงขั้นตอนตอน startup, การตรวจสอบตอน runtime ที่ขับ request แบบเป็นรอบและแบบเฉพาะเจาะจง และกฎการ retry และ throttling ของ request เหล่านั้น case TC-E84 ถึง TC-E87 และ TC-E101 ใน ข้อกำหนดการทดสอบ execution ทดสอบ reconciliation ตอน startup กับ venue จริง ส่วน case TC-E88 และ TC-E89 ใช้ fixture แบบ deterministic เพื่อทดสอบความล้มเหลวของ commission ทั้งจาก REST และ private stream

Mass status ตอน startup

generate_mass_status รันหนึ่งครั้งต่อ execution client ก่อนเริ่มซื้อขาย implementation ค่าเริ่มต้นของมัน:

  • ประกอบ bulk method ทั้งสามตัวพร้อมกันจาก ts_init เดียว
  • คำนวณ start ของแต่ละคำสั่งจาก lookback_mins
  • ขอประวัติ order ทั้งหมดด้วย open_only=false

ดังนั้นการ implement bulk method จึงเพียงพอสำหรับ startup ให้ override การประกอบเมื่อ client ประกาศขอบเขตของประวัติ ตามที่อธิบายใน mass-status report แบบมีขอบเขต หรือเมื่อไม่ได้ใช้ realtime clock

การคืน Ok(None) จะ log warning และปล่อยให้ client นั้นไม่ได้ reconcile ส่วน error จะทำให้ startup ล้มเหลว

หลักฐานของ order ใน mass status

ให้ fill report แต่ละตัวมีหลักฐานของ order จากแหล่งใดแหล่งหนึ่งต่อไปนี้:

  • order report ของ venue order ID นั้นใน mass status เดียวกัน
  • order ที่ cache ถืออยู่แล้ว

reconciliation จะทิ้งกลุ่ม fill ที่ไม่มีทั้งสองอย่างและ log warning ยกเว้นเมื่อ fill ของกลุ่มนั้นมี venue_position_id สำหรับข้อยกเว้นนี้ reconciliation จะสร้าง order เมื่อเปิด generate_missing_orders และข้ามไปในกรณีอื่น

ดังนั้น mass status ที่มีเฉพาะ order ที่เปิดอยู่จะสูญเสีย fill ของ order ที่ปิดแล้วซึ่ง cache ไม่มี ตัวอย่างเช่น order ที่วางจากนอก node หรือก่อน restart โดยไม่มี cache ที่ persist ไว้

หาก venue ไม่มี record ของ order ที่ query ได้ ให้สร้าง order report สถานะ FILLED จาก fill ของมัน ตัวอย่างเช่น venue ที่ไม่มีประวัติ order ที่ปิดแล้ว, fill จาก block trade และ fill จากการ settle แต่ให้ระงับ fill ไว้แทนเมื่อ การ apply จะทำให้ position ผิดเพี้ยน เช่น เมื่อ fill เหล่านั้นไม่ได้รวมการเปลี่ยนแปลง balance ที่เกิดขึ้นโดยไม่มี trade

ราคาเข้าเฉลี่ยใน position report

ส่งราคาเข้าเฉลี่ยของ venue ผ่านไปโดยไม่ปัดเศษเป็น avg_px_open และระบุว่า reconciliation ใช้ค่านี้ได้อย่างไร:

  • Nautilus คำนวณค่าเฉลี่ยถ่วงน้ำหนักด้วยปริมาณของ fill ที่เปิด position การลด position ไม่เปลี่ยนค่านี้ และการกลับฝั่ง จะ reset ค่านี้ หากค่าเฉลี่ยของ venue เป็นไปตามกฎเดียวกัน ให้ใช้ค่าเริ่มต้น
  • เรียก with_avg_px_open_reconciliation(AvgPxReconciliation::OpeningOnly) เมื่อ venue คำนวณ ค่าเฉลี่ยด้วยวิธีอื่น เช่น ตาม FIFO lot แล้ว reconciliation จะใช้ค่านี้เฉพาะเพื่อเปิด position จาก flat และจะไม่เปรียบเทียบกับค่าเฉลี่ยใน cache
  • เรียก with_avg_px_open_precision(precision) เมื่อ venue ปัดหรือตัดค่าเฉลี่ย การเปรียบเทียบ จะยอมให้คลาดได้หนึ่งหน่วยที่ precision นั้น การจับคู่ปริมาณไม่เปลี่ยน ให้เอา marker ออกเมื่อ adapter แทนค่าเฉลี่ยด้วยค่าที่แน่นอน

Reported entry averages อธิบาย ผลของแต่ละแบบ

Contract ของ timestamp ใน mass status

ExecutionMassStatus.ts_init ระบุจุดเริ่มต้นของการเก็บ snapshot สำหรับผู้สร้างทุกราย รวมถึง snapshot ตอน reconnect และ implementation ของ generate_mass_status ที่เขียนเอง:

  • เก็บก่อนการรวบรวม: อ่าน local clock ของ adapter ก่อน request แรก, การอ่าน cache หรือ task รวบรวมข้อมูลที่ทำงานพร้อมกัน
  • ใช้ clock ที่สอดคล้องกัน: ใช้ local clock ตัวเดียวกับ timestamp ตอน initialize ของ execution fill และ fill-void ห้ามใช้ timestamp ของ venue หรือศูนย์แทน
  • รักษาขอบเขตไว้: คงค่านั้นไว้ตลอดการสร้างและ publish snapshot ทั้งเวลาที่เสร็จและ timestamp ของ report แต่ละตัวต่างไม่ได้มาแทนที่ค่านี้

runtime reconciliation จะข้าม snapshot ของ order เมื่อ fill หรือ fill void ใน cache มี ts_init ตรงหรือหลังขอบเขตนี้ ส่วน trade ที่มาคู่กันยังประมวลผลตามปกติ

timestamp ที่ไม่ถูกต้องจะเปลี่ยนพฤติกรรมของ reconciliation:

  • timestamp ตอนเสร็จ อาจทำให้ snapshot ที่เก่ากว่าดูใหม่กว่า fill ที่ซ้อนทับกัน ส่งผลให้ engine void fill นั้นอย่างผิดพลาด
  • timestamp เป็นศูนย์ อาจระงับการแก้ไข snapshot ที่ถูกต้องไปอย่างไม่มีกำหนด

สำหรับผู้สร้างที่เขียนเอง ให้หน่วง response ของ report แล้ว assert ว่า timestamp ของ mass status ถูกเก็บก่อน การรวบรวมเริ่ม และ assert ว่า timestamp ไม่เปลี่ยนเมื่อการรวบรวมเสร็จสิ้น

ดู Snapshot freshness and fill corrections สำหรับความแตกต่างตอน startup และข้อจำกัดเมื่อ state ของ venue เก่าอยู่แล้ว

Filter ของ bulk report

bulk method รับคำสั่ง filter ที่มี instrument_id, start และ end รวมถึง open_only สำหรับ order report และ venue_order_id สำหรับ fill report ให้ใช้ทุก filter ที่ endpoint ของ venue รองรับ และทำส่วนที่เหลือให้ครบที่ฝั่ง local:

  • open_only แยก order ที่เปิดอยู่ในปัจจุบันที่การตรวจสอบแบบเป็นรอบต้องการ ออกจากประวัติที่ mass status ต้องการ สำหรับ open_only ให้เก็บ report ที่สถานะเป็น open หรือ in-flight ไม่ใช่ open อย่างเดียว venue จะรายงาน order เป็น SUBMITTED หากถือ order ไว้แต่ยังไม่ได้ตอบรับ สถานะนี้เป็น in-flight ไม่ใช่ open
  • ใช้ start และ end กับ report ที่ปิดแล้วเท่านั้น order ที่ทำงานอยู่ที่ venue ถือเป็นข้อมูลที่เชื่อถือได้ ไม่ว่า จะค้างอยู่นานแค่ไหนโดยไม่มี update
  • ทดสอบว่า report อยู่ในสถานะ terminal ด้วย is_closed() ห้ามใช้ !is_open() ซึ่งจัดให้ SUBMITTED เป็น terminal

log จำนวน report ที่ log_receipt_level ของคำสั่ง เพื่อให้การตรวจสอบแบบเป็นรอบอยู่ที่ระดับ debug ขณะที่ mass status log ที่ระดับ info

หาก request ของการตรวจสอบแบบเป็นรอบล้มเหลว engine จะทำเครื่องหมายว่า client นั้นล้มเหลวสำหรับรอบนั้น และหยุดอนุมาน ว่าไม่มี order และ position ที่ client นั้นครอบคลุม ดังนั้นการคืน error จึงปลอดภัยกว่า การคืนชุดว่าง

Probe สำหรับ order เดียว

generate_order_status_report resolve order เดียว engine จะเรียกหลังจาก open-order check retry แล้วยังยืนยัน order ใน cache ไม่ได้ ซึ่งต้องให้การตรวจสอบนั้นรันในโหมด full-history (open_check_open_only=false) คำสั่งนี้มี instrument_id และ client_order_id ที่ query รวมถึง venue_order_id เมื่อ order มี ดังนั้นต้องรองรับการ lookup ที่ยังไม่มี venue identifier ด้วย engine จะทิ้ง report ที่ identity ไม่ตรงกับ query

แยกความแตกต่างระหว่าง "ไม่มี" กับ "ล้มเหลว" ใน probe นั้น เพราะ engine ทำงานต่างกันตามความแตกต่างนี้:

  • Ok(None) ระบุว่า venue ตอบแล้วและไม่มี order ดังกล่าว engine ถือคำตอบนั้นเป็นหลักฐาน และ resolve order ที่ accepted, submitted หรือ partially filled ไปเป็นสถานะ terminal ส่วนสถานะ pending cancel และ pending update ยังคงไม่ถูก resolve
  • error ระบุว่าการ lookup ไม่ได้คำตอบ ดังนั้น engine จะเลื่อนการ resolve order ที่หายไป ไปยังรอบถัดไป

การ lookup ที่ล้มเหลวแต่คืนเป็น Ok(None) จึงอาจทำให้ order ที่ยังทำงานอยู่ที่ venue ถูก reject หรือ cancel ได้ ค่าเริ่มต้นของ trait คืน Ok(None) หลังจาก log ว่ายังไม่ได้ implement handler ดังนั้น ต้อง implement method นี้ก่อนที่ open-order check จะรันในโหมด full-history

การเปลี่ยนแปลง reconciliation ร่วม

execution engine และ live ExecutionManager apply report ของทุก adapter ผ่าน code เดียวกัน ดังนั้น การเปลี่ยนแปลง logic ร่วมของ execution หรือ reconciliation จะเปลี่ยนพฤติกรรมของทุก venue พร้อมกัน ให้ประเมิน การเปลี่ยนแปลงแบบนี้กับทุก adapter ที่มี execution client ไม่ใช่เฉพาะ venue ที่เป็นต้นเหตุ สำหรับแต่ละ adapter ให้ตรวจสอบฟิลด์ของ report ที่การเปลี่ยนแปลงพึ่งพา เช่น:

  • เวลาที่ OrderStatusReport.ts_accepted เก็บไว้: เวลาที่ venue ยอมรับ, เวลาที่ update ครั้งล่าสุด หรือ timestamp ฝั่ง local เวลาของ update ครั้งล่าสุดหรือเวลา local อาจทำให้การยอมรับ order ไปอยู่หลัง fill ของ order นั้นเอง
  • เวลาที่ OrderStatusReport.ts_last เก็บไว้สำหรับ order ที่ปิดแล้ว: เวลาที่ปิด หรือเวลาก่อนหน้านั้น เช่น เวลาสร้าง เวลาก่อนหน้าอาจทำให้การ cancel ไปอยู่ก่อน fill ของ order นั้นเอง
  • fill report มี venue_order_id เดียวกับ order report ของ order เดียวกันหรือไม่
  • client order หนึ่งตัวมี venue order ID มากกว่าหนึ่งตัวใน mass status เดียวได้หรือไม่ เช่น หลังการแทนที่ราคา
  • mass status รวม order ที่ปิดแล้วด้วย หรือมีเฉพาะ order ที่เปิดอยู่

จัดประเภท adapter แต่ละตัวเป็นได้ประโยชน์, ไม่ได้รับผลกระทบ หรือมีความเสี่ยง โดยอ้างอิง code ที่ใช้ตัดสินการจัดประเภท และใส่ผลลัพธ์ไว้ในคำอธิบายของ pull request

การจัดการเมื่อ commission ล้มเหลว

commission เป็นส่วนหนึ่งของบันทึกทางเศรษฐกิจของ fill ให้คำนวณด้วยเลขคณิตทศนิยมแบบแม่นยำ แล้ว สร้างค่า Money ในสกุลเงินของ venue โดย hook ร่วม ExecutionClient::calculate_commission แยกแยะผลลัพธ์เหล่านี้:

ผลลัพธ์ความหมาย
Ok(Some(commission))ใช้สูตรของ venue ได้และได้ commission ที่แทนค่าได้ ให้ใช้ค่านั้นตรงตัว
Ok(None)adapter ไม่มีการ override ของ venue ผู้เรียกอาจใช้สูตร commission ทั่วไปได้
Err(error)ใช้สูตรของ venue แต่ไม่สามารถได้ค่าที่แทนได้ ให้ fail closed

ห้ามแทน Err(error) ด้วย commission เป็นศูนย์หรือสูตรทั่วไป เพราะการแทนที่นั้นจะบันทึก trade ที่ยืนยันแล้วด้วยข้อมูลทางเศรษฐกิจที่ venue ไม่ได้รายงาน

การสร้าง report จาก REST

การสร้าง commission เป็นส่วนหนึ่งของ REST report request หากการสร้าง commission ล้มเหลวสำหรับ fill ที่จำเป็น ให้คืน error จาก request ที่ได้รับผลกระทบ:

  • request ของ fill report โดยตรง
  • targeted recovery
  • mass status ที่สมบูรณ์

ห้ามทิ้ง fill, คืน mass status บางส่วน หรือทำเครื่องหมายว่าชุด report แบบมีขอบเขตไม่สมบูรณ์ด้วยความล้มเหลว นี้ มิฉะนั้น order report หรือ position report อาจทำให้ engine อนุมานปริมาณเดียวกัน โดยไม่มี commission ของ venue

ระหว่าง startup error นี้จะป้องกันไม่ให้ node เริ่มทำงาน และทิ้ง mass status ของ client นั้นไว้โดยไม่ apply ส่วน reconciliation แบบเป็นรอบและแบบเฉพาะเจาะจงจะเลื่อนงานที่ได้รับผลกระทบไปยังรอบถัดไป

Inferred fill

เรียก hook นี้สำหรับทุก inferred fill ที่มาจาก adapter: order ภายนอกและ order ใน cache, continuous reconciliation และ targeted order recovery หากการคำนวณ commission ล้มเหลว engine อาจ apply fill ที่ระบุชัดและถูกต้องได้ แต่จะทิ้งปริมาณ inferred ที่เหลือและ terminal transition ที่ขึ้นกับมันไว้ในสถานะ pending

สำหรับ order ภายนอก ให้คำนวณ commission ก่อนที่การเปลี่ยนแปลงของ cache หรือ event จะขัดขวางการ retry หาก execution client ที่รับผิดชอบไม่พร้อมใช้งาน ให้เลื่อน inferred fill ออกไป อย่าถือว่า client ที่หายไปนั้นเป็น response แบบ Ok(None)

ส่งปริมาณ, ราคา และฝั่ง liquidity เดียวกับ inferred-fill event order ใน cache อาจมี fill ก่อนหน้า สำหรับ order แบบนั้น ให้คำนวณ commission จากราคาที่คำนวณย้อนกลับของปริมาณส่วนเพิ่มที่ยังไม่ได้บันทึก อย่าใช้ราคาเฉลี่ยสะสมจาก report ของ venue สำหรับ commission นั้น

การแก้ไขแบบสังเคราะห์เฉพาะ position ไม่มีหลักฐาน trade รองรับ และอาจไม่ระบุ commission ได้ อย่า นำค่ารวมหรือค่าทั่วไปมาแสดงเป็น commission ที่แน่นอนของ fill ที่ไม่รู้จักนั้น กรณีนี้แตกต่าง จากการคำนวณของ venue ที่ล้มเหลว

การประมวลผล trade จาก WebSocket

ประมวลผล trade จาก WebSocket แต่ละตัวแบบ atomic ให้สร้าง fill report ของ maker และ taker ที่เป็นเจ้าของทั้งหมดก่อนการกระทำ ใด ๆ ต่อไปนี้:

  • การ emit report
  • การแก้ไข fill tracker
  • การใช้ deduplication key ของ trade

ใช้ key เฉพาะหลังจาก report ทั้งหมด route สำเร็จแล้ว

เมื่อล้มเหลว ให้ log error และทิ้ง trade ไว้โดยไม่ประมวลผล อย่ายืนยันหรือทำให้ order ที่ได้รับผลกระทบเป็น terminal หรือทำเครื่องหมายว่า reconcile ไม่ได้อย่างถาวร การ replay จากรายการซ้ำหรือการ reconnect สามารถ retry trade ได้ REST reconciliation ตามกำหนดเวลายังคงเป็นเส้นทางการกู้คืนที่เชื่อถือได้ และ WebSocket handler จะไม่เริ่ม REST request ทันที

Mass-status report แบบมีขอบเขต

เมื่อ execution client ใช้ขอบเขตเวลาล่างกับ reconciliation report ย้อนหลัง ให้บันทึก contract ด้วย ExecutionMassStatus::set_report_window(Some(lookback_start), reports_complete) เก็บ cutoff เพียงค่าเดียวสำหรับ mass-status request และใช้กับทุก query ย้อนหลังของ order และ fill cutoff ที่เลื่อนไปมาอาจทำให้ record ตกหล่นที่ขอบเขตต่างกันและได้ชุด report ที่ไม่เคยมีอยู่จริงที่ venue

ตั้ง reports_complete=true เฉพาะเมื่อทั้งสองเงื่อนไขเป็นจริง:

  • แหล่งข้อมูลทั้งหมดที่จำเป็นต่อการตีความประวัติแบบมีขอบเขตทำงานเสร็จ
  • record ที่จำเป็นทั้งหมดถูก parse, map และเชื่อมกับ order ของมันแล้ว

แหล่งข้อมูลที่จำเป็นที่ล้มเหลว, แถวที่จำเป็นที่ parse หรือ map ไม่ได้ หรือ fill ย้อนหลังที่ไม่มี order report ที่จำเป็น จะทำให้ชุดนั้นไม่สมบูรณ์ ให้เก็บส่วนที่สำเร็จและ order ที่ active อย่างเชื่อถือได้ไว้ แต่ อย่าแสดง query ย้อนหลังที่ล้มเหลวเป็นผลลัพธ์ว่างที่สำเร็จ

การสร้าง commission เป็นข้อยกเว้นของประวัติแบบมีขอบเขตบางส่วน ให้ทำตาม การจัดการเมื่อ commission ล้มเหลว และ fail report request แทน การคืนชุดที่ตัด fill ที่ได้รับผลกระทบออก

การ parse position report คือ market exposure

parse position report ให้ถูกต้องแม่นยำ engine ถือว่า report ที่ระบุชัดแต่ละตัวคือ position แล้ว ปรับให้ตรงกับมันภายใน tolerance ของ reconciliation หรือ fail closed ปริมาณที่ผิด, ฝั่งที่ผิด, แถวที่ตกหล่น หรือ flat ที่สร้างขึ้นเอง จะกลายเป็น exposure ที่ strategy จะซื้อขาย

โดยค่าเริ่มต้น engine จะสร้าง order และ fill ที่จำเป็นเพื่อไปให้ถึง report ที่คุณ emit มัน ไม่สามารถกู้ข้อเท็จจริงของ position ที่คุณทิ้งหรือสร้างขึ้นเองได้

emit report เฉพาะข้อเท็จจริงที่ venue ระบุไว้:

  • ปริมาณและทิศทางที่เปิดอยู่ ในรูป open report
  • ไม่มี position ในรูป flat report ที่ระบุชัด และเฉพาะหลังจาก coverage พิสูจน์แล้วว่า position เป็น flat

อย่า emit report สำหรับ:

  • instrument ที่ถูกละไว้โดยไม่มี coverage ที่เชื่อถือได้
  • ปริมาณที่เป็น null
  • แถวที่ parse ไม่ได้
  • venue ที่ไม่เผยแพร่ position

การทิ้งค่าศูนย์หรือ flat ที่ถูกรายงาน หรือการสร้างค่าศูนย์ขึ้นเองโดยไม่มี coverage ที่เชื่อถือได้ ถือเป็นข้อผิดพลาด ในการเขียน code ของ adapter snapshot ที่สมบูรณ์ของ venue จะยืนยัน flat ได้เฉพาะเมื่อ coverage ที่ระบุในเอกสารรวม position นั้นไว้ response ที่หายไปหรือล้มเหลวยืนยันไม่ได้

เมื่อ position มาจาก stream ที่ cache ไว้ การไม่มีอยู่จะพิสูจน์ว่า flat ได้เฉพาะเมื่อ snapshot ที่สมบูรณ์จาก connection epoch ปัจจุบันครอบคลุม instrument นั้นอย่างชัดเจน ให้ยกเลิก coverage ของ snapshot เมื่อ reconnect และถือว่าแถวที่ parse หรือ map ไม่ได้ไม่อยู่ใน coverage ให้ emit flat report ที่ระบุชัดสำหรับ instrument ที่เคยแตะแต่ไม่มีอยู่ หลังจากยืนยัน coverage แล้วเท่านั้น

รักษา identity ของ venue order และ trade ให้คงที่ทั้งใน live dispatch และ mass status ใส่การเชื่อมโยงกับ client order เมื่อ venue ให้มา และใส่ venue_position_id เมื่อ venue ให้มา ฟิลด์เหล่านี้ช่วยให้ execution engine แยกแยะวงจรชีวิตที่สอดคล้องกันออกจากประวัติที่กำกวมได้ ดู Bounded history safety สำหรับกฎ การ apply ทางเศรษฐกิจของ engine

การ resolve instrument ระหว่าง reconciliation

การสร้าง report จะ resolve instrument ของแต่ละ record เพื่อ parse payload ของ venue ด้วย precision ของราคาและขนาด ที่ถูกต้อง ให้ resolve จาก instrument ที่ adapter load ไว้ตอน connect และจัดประเภทกรณีที่หาไม่พบตามว่า record อยู่ในขอบเขตหรือไม่

อย่า request instrument จาก venue ระหว่างการสร้าง report:

  • request ราย record จะคูณจำนวน bulk query ที่ reconciliation ตอน startup ส่งไปแล้วซึ่งกิน rate limit ของ venue
  • request ที่ซ่อนอยู่ทำให้จังหวะเวลาและผลลัพธ์ของ reconciliation ทำซ้ำไม่ได้
  • request ที่ล้มเหลวไม่สามารถแยกออกจาก instrument ที่ venue ไม่มีได้

ให้ load สิ่งที่ adapter ต้องการตอน connect แทน

record ที่อยู่ในขอบเขตแต่หา instrument ไม่พบจะไม่ถูกทิ้งอย่างเงียบ ๆ เด็ดขาด เพราะ engine ไม่สามารถแยกแยะ open order report ที่ถูกทิ้งออกจาก order ที่ venue ไม่มีได้ จึงจะ resolve order ที่ยังทำงานอยู่ว่า หายไปที่ venue ขอบเขตเป็นตัวตัดสินว่าการหาไม่พบเป็นเรื่องที่คาดไว้หรือไม่ ดังนั้นให้ประเมินก่อนจัดประเภท record:

Recordผลลัพธ์ชุด report
อยู่นอกขอบเขตของ load_idslog ที่ระดับ debug แล้วทิ้งไม่ได้รับผลกระทบ
อยู่ในขอบเขต เป็น open order หรือ position status reportคืน error จาก report requestไม่ถูกคืน
อยู่ในขอบเขต เป็น record ที่ปิดแล้วหรือย้อนหลังlog warning ระบุชื่อ instrumentไม่สมบูรณ์เมื่อประวัติมีขอบเขต

InstrumentProviderConfig.load_ids กำหนดขอบเขตนั้น หากระบุชุดที่ชัดเจน record ของ instrument นอกชุดนั้นถือเป็นการไม่มีอยู่ที่คาดไว้ ไม่ใช่ error ดังนั้น node ที่จำกัดขอบเขตไว้ที่ instrument เดียวจะไม่ fail หรือ warn เมื่อ venue คืน record ของ instrument อื่น

query ย้อนหลังมักเลยขอบเขตของชุด instrument ที่ load ไว้ เพราะการหมดอายุทำให้ instrument ถูกปลดออกทั้งที่ fill ก่อนหน้ายังอ้างอิงถึง การทำให้ query ประวัติแบบมีขอบเขตล้มเหลวเพราะ instrument ที่หมดอายุตัวเดียวจะระงับ record อื่นทั้งหมดที่คืนมา ดังนั้นให้บันทึกความไม่สมบูรณ์ผ่าน set_report_window

ผลต่อ position:

  • ความไม่สมบูรณ์ไม่ได้ยับยั้ง position report ที่ระบุชัด
  • fill แบบมีขอบเขตของ instrument ที่ไม่มี position report ที่ระบุชัดจะไม่เปลี่ยน position
  • emit flat report ที่ระบุชัดเฉพาะเมื่อ coverage พิสูจน์ว่า venue ไม่มี position อย่าละ แถวไว้แล้วคาดหวังให้ engine อนุมานว่า flat

reconciliation_instrument_ids กรอง report หลังจาก execution engine ได้รับแล้ว ดังนั้นจึง ป้องกันความล้มเหลวในการ resolve ภายใน adapter ไม่ได้ ให้กำหนดขอบเขตของ adapter ไว้ใน configuration ของ instrument provider

Execution update ที่ติดตามอยู่และจากภายนอก

route execution update ตามความเป็นเจ้าของ order โดยไม่ขึ้นกับการจัดวาง module ของการ dispatch:

  • สำหรับ order ที่ client นี้ submit และติดตามอยู่ ให้ emit order event แบบ typed ผ่าน order state machine ตามปกติ
  • สำหรับ order ที่ไม่ได้ติดตามหรือ order ภายนอก ให้ emit ค่า OrderStatusReport และ FillReport โดย report เหล่านี้ช่วยให้ execution engine reconcile หรือสร้าง order ภายนอกได้

อย่าสร้าง identity ของ strategy หรือ client ขึ้นเองสำหรับ order ที่ไม่ได้ติดตาม ให้รักษา identity ของ venue ที่มีอยู่ไว้ใน report และให้ engine ใช้ ความเป็นเจ้าของ order ภายนอก adapter อาจใช้ โครงสร้าง state ใดก็ได้ที่พิสูจน์การตัดสินใจ route นี้ได้

model ความเป็นเจ้าของแบบติดตามด้วยสองชั้นเชิงแนวคิด:

  • Order identity มีฟิลด์ที่คงที่ซึ่งเชื่อม update เข้ากับ order ที่ submit: client order ID, strategy, instrument, side และ order type
  • Order context รวม identity นั้นเข้ากับรูปร่างของ order ที่ submit โดยรูปร่างนี้ให้ฟิลด์ ที่จำเป็นต่อการสร้าง event ภายหลังโดยไม่ต้องเข้าถึง cache ของ engine ฟิลด์เหล่านี้รวมถึงปริมาณ, ราคา และรายละเอียดของ trigger, time in force และ execution flag

เก็บการผูก venue order, การจับคู่ request, fill สะสม และ state ของการแทนที่ไว้ใน context ที่ adapter เป็นเจ้าของ รอบ ๆ surface ร่วมนั้น

OrderIdentity and OrderContext ให้ surface ดังกล่าว ให้เริ่มจากสิ่งเหล่านี้ และคงโครงสร้างเฉพาะ adapter ไว้เฉพาะที่พิสูจน์การตัดสินใจ route แบบเดียวกันได้

ลงทะเบียน order context ก่อนส่งหรือ spawn งานที่อาจสร้าง update ขาเข้า กู้คืน context ของ order ฝั่ง local ที่ active ก่อนประมวลผล live update ของมัน และเก็บไว้ตราบที่ order ยังสร้าง update ที่เป็นเจ้าของได้ อย่า evict context ที่ active เพียงเพื่อจำกัดขนาด state ของการ replay

ให้ execution update ทุกตัวไปตามเส้นทางที่ชัดเจนเพียงเส้นทางเดียว:

เส้นทางหลักฐานผลลัพธ์
Trackedcontext ที่ active หรือ pending เป็นเจ้าของ orderemit, ตัดรายการซ้ำ หรือเลื่อน order event แบบ typed อย่างปลอดภัย
Externalไม่มีความเป็นเจ้าของแบบ tracked, pending หรือ terminalส่งต่อ report สำหรับ reconciliation หรือการสร้าง order ภายนอก
Suppressedพิสูจน์แล้วว่า update ซ้ำ, เก่า หรือถูกแทนที่แล้วไม่ emit ทั้ง event และ report

metadata ของการติดตามที่หายไป, การ parse ที่ล้มเหลว หรือการผูก venue ที่ยัง resolve ไม่ได้ ไม่ได้พิสูจน์ว่า update นั้นมาจากภายนอก สถานะแบบ tracked ที่ไม่มี lifecycle event ของ Nautilus ที่ตรงกันถือเป็น tracked no-op หรือ update ที่เลื่อนไว้ เว้นแต่ adapter จะบันทึกและทดสอบข้อยกเว้นแบบ report ไว้

Parent order และ child order ที่ถูก trigger

venue บางแห่งแทนที่ parent venue order ที่ติดตามอยู่ด้วย child หลังจาก trigger ให้ถือว่า venue ID ทั้งสอง เป็น order context เดียวกัน:

  • รักษา identity ของ client ให้คงที่
  • ผูก child แบบ atomic พร้อมกับ trigger transition โดย child ID จะกลายเป็นตัวที่เชื่อถือได้สำหรับ event และคำสั่งภายหลัง
  • หาก child มาถึงระหว่าง race ของการผูก ให้ใช้การเชื่อมโยงของ venue เพื่อทำ tracked transition ให้เสร็จ หรือเลื่อน update ไว้ อย่า route เป็น external
  • เมื่อ child เป็นตัวที่เชื่อถือได้แล้ว ให้ระงับการยอมรับของ parent ที่เก่าแล้ว และ update ใด ๆ ของ parent ที่ถูกแทนที่ซึ่ง จะทำให้ความเชื่อถือของ child ถอยหลัง
Update ที่ไม่สมบูรณ์และที่มาช้า

แยกกรณีเหล่านี้ออกจาก tracked event ปกติ:

  • สถานะรวมของ parent ที่ไม่มี trade identity หรือฟิลด์อื่นที่จำเป็นต่อ event แบบ typed ยังคงเป็น tracked no-op หรือ update ที่เลื่อนไว้ child ที่เชื่อถือได้จะสร้าง live event ขณะที่ การกู้คืนแบบอิง report ยังคงอยู่ในเส้นทาง reconciliation
  • fill ที่มี trade identity ใหม่ซึ่งมาถึงหลังจาก tracked lifecycle ไปถึงสถานะ terminal แล้ว ยังคงเป็น FillReport เพราะ order context ที่ active ไม่มีให้ใช้สำหรับ event แบบ typed อีกแล้ว ดังนั้น reconciliation จะ apply หลักฐานจาก venue ที่มาช้านั้น

ระงับการ replay สถานะ terminal และ fill ที่ trade identity เคยถูกประมวลผลไปแล้ว

ลำดับของ event และการตัดรายการซ้ำ

venue อาจรายงาน transition เดียวกันผ่าน order response, private stream, query และ ผลของ reconciliation ให้ตัดรายการซ้ำด้วย identity ของ venue ที่คงที่ ไม่ใช่ด้วย transport ที่ส่ง update มา:

  • ใช้ trade ID หรือ match ID ของ venue สำหรับ fill และใส่ identity ของ account, instrument หรือผลิตภัณฑ์เมื่อ venue ไม่รับประกันความไม่ซ้ำแบบ global
  • แชร์ identity ของ fill ระหว่าง live dispatch และ reconciliation เมื่อเส้นทางเหล่านั้นอาจซ้อนทับกัน
  • อย่าใช้ deduplication key ก่อนที่การ parse และ route จะสำเร็จ หาก implementation จองไว้ก่อน ให้ปล่อย key หลังจากล้มเหลว เพื่อให้การ replay กู้ event คืนได้
  • จำกัดขนาด state ของการตัดรายการซ้ำที่อยู่นาน แต่เก็บประวัติข้ามการ reconnect ไว้มากพอที่จะครอบคลุมการ replay ของ venue และ reset เฉพาะเมื่อโปรโตคอลพิสูจน์ได้ว่า identifier เก่าจะไม่กลับมาอีก
  • ใช้ FifoCache and FifoCacheMap ร่วมเมื่อ การ evict แบบ first-in, first-out ตรงกับ contract ของการ replay และคงการ lock เฉพาะ adapter ไว้ในจุดที่ การเปลี่ยน state หลายอย่างต้องเป็น atomic
  • ทำให้ acknowledgement และ order snapshot ที่ซ้ำเป็น idempotent โดยต้องไม่ทำให้ state ถอยหลังหรือ emit lifecycle event ซ้ำเป็นครั้งที่สอง

state object หนึ่งตัวอาจเป็นเจ้าของทั้ง order context ที่ active, การจับคู่ที่ค้างอยู่, การตัดรายการซ้ำตอน replay และ tombstone ของ terminal ถึงอย่างนั้นก็ให้แยกเป็นแนวคิดวงจรชีวิตต่างหากกัน จำกัดขนาด state ของ replay และ tombstone โดยไม่ ปล่อยให้การ evict ทำให้ update ของ order ที่ active ถูกจัดประเภทใหม่เป็น external

สำหรับ order ที่ติดตามอยู่ fill ที่ชัดเจนอาจมาถึงก่อน acknowledgement หรือ open-order update ให้ emit lifecycle event ก่อนหน้าที่จำเป็นเฉพาะเมื่อทั้งสองเงื่อนไขเป็นจริง:

  • adapter มี order identity ครบถ้วน
  • หลักฐานจาก venue พิสูจน์ state นั้น

บันทึก transition ที่สังเคราะห์ขึ้นไว้ เพื่อไม่ให้ acknowledgement ที่มาภายหลังทำซ้ำ ส่วน order ที่ไม่ได้ติดตามจะดำเนินต่อ ผ่าน report แทน strategy event ที่สังเคราะห์ขึ้น

เมื่อ update ของ parent และ child อาจมาถึงทาง stream ที่ต่างกัน:

  • serialize การผูก venue order ID เข้ากับ lifecycle event ที่ publish มัน
  • emit event OrderAccepted, OrderUpdated และ OrderTriggered ที่จำเป็นก่อน route fill หรือการ cancel ของ child
  • route คำสั่งจากการผูกที่เชื่อถือได้ตัวเดียวกัน อย่าอนุมานจาก cache ของ engine ที่อาจ ยังประมวลผล event เหล่านั้นอยู่

เมื่อ venue implement การ modify เป็น cancel-replace ให้อัปเดตการ map venue order ID ก่อน route ขาที่มาแทนที่ แยกการ cancel ที่เก่าแล้วของขาเดิมออกจากการ cancel ขาแทนที่ที่ active และ คำนวณปริมาณของขาแทนที่จาก fill สะสมปัจจุบัน พฤติกรรมนี้เฉพาะของแต่ละ venue และต้องมี race test ที่เจาะจง ซึ่งไม่ได้หมายความว่าต้องใช้โครงสร้าง dispatch state ร่วม

test ที่เจาะจงจะแยกแยะ update แบบ tracked และ external, fill ที่มาก่อน acknowledgement, รายการซ้ำจากแหล่งที่ซ้อนทับ, race ของการ submit หรือการผูก venue และ update ที่เก่าแล้วหลัง terminal ให้ทดสอบการคง context ที่ active แยกจากการ evict ของ replay แบบมีขอบเขต

Policy ของผลลัพธ์คำสั่ง order

ใช้ Execution policies เป็น contract ข้าม adapter สำหรับ การส่งคำสั่ง, การ apply event, การ persist และการกู้คืน

แยกหลักฐานออกเป็นสามประเภท:

  • ความล้มเหลวฝั่ง local ที่ชัดเจน: หลักฐานฝั่ง local พิสูจน์ว่าคำสั่งไม่เคยถูกส่งออกไป การ validate แบบ deterministic ก่อน submit เป็นตัวอย่างหนึ่ง ให้ emit OrderDenied ก่อน OrderSubmitted ระหว่างการเตรียม cancel หรือ modify ให้ emit rejection ที่ตรงกันเฉพาะเมื่อทั้งสองเงื่อนไขเป็นจริง:

    • ความล้มเหลวเกิดจากคำสั่งนั้น
    • ความล้มเหลวพิสูจน์ว่าคำสั่งไม่ได้ถูกส่ง

    มิฉะนั้นให้ log ความล้มเหลวโดยไม่สร้าง rejection ขึ้นเอง

  • ผลลัพธ์จาก venue ที่ชัดเจน: response หรือสถานะที่มีโครงสร้างจาก venue ยอมรับ, อัปเดต หรือปฏิเสธคำสั่งหนึ่งอย่างชัดเจน ให้ emit domain event ที่ตรงกัน

  • ผลลัพธ์ที่ไม่ทราบ: request อาจไปถึง venue แล้ว แต่ไม่มีผลลัพธ์ที่ชัดเจน ให้คงคำสั่งไว้ในสถานะ in flight เพื่อรอ stream update, การ poll, query หรือ reconciliation

flowchart TD
    command[Submit order] --> valid{Deterministic local validation passes?}
    valid -->|No| denied[OrderDenied]
    valid -->|Yes| submitted[OrderSubmitted]
    submitted --> unsent{Local evidence proves no transmission?}
    unsent -->|Yes| rejected[Emit OrderRejected]
    unsent -->|No| evidence{Definitive venue evidence?}
    evidence -->|Accepted or updated| event[Apply the venue event]
    evidence -->|Explicit rejection| rejected
    evidence -->|No| unknown[Keep the outcome unknown]
    unknown --> recovery[Resolve from stream, query, polling, or reconciliation]
    recovery --> event
    recovery --> rejected

หาก submit ล้มเหลวหลัง OrderSubmitted ให้ emit OrderRejected เมื่อหลักฐานฝั่ง local พิสูจน์ ว่าคำสั่งไม่เคยถูกส่งออกไป มิฉะนั้นให้ปล่อย order ไว้ในสถานะ in flight เว้นแต่หลักฐาน จาก venue ที่ชัดเจนจะ resolve ได้

transport error, timeout, disconnect, การ cancel task, retry ที่ใช้หมดแล้ว, HTTP 5xx response, rate limit, acknowledgement ที่หายไป และการ parse ที่ล้มเหลวหลังการส่ง มักทิ้ง ผลลัพธ์ที่ไม่ทราบไว้ อย่าแปลงสิ่งเหล่านี้เป็น venue rejection

สำหรับคำสั่งแบบ batch ให้ apply หลักฐานราย order ความล้มเหลวของทั้ง request ไม่ได้พิสูจน์ว่า child command แต่ละตัว ล้มเหลว ให้จัดการ message ของ venue อย่าง "not found" หรือ "already closed" ตาม semantics ของ venue ที่บันทึกไว้ เพราะอาจอธิบาย race กับ fill หรือการ cancel แทนที่จะเป็นการปฏิเสธคำสั่งที่ชัดเจน

ให้ policy นี้ไม่ขึ้นกับว่าใช้เส้นทาง HTTP หรือ WebSocket ในการส่งคำสั่ง

การตั้งชื่อประเภทหลักฐาน

ใช้ชื่อที่สอดคล้องกัน เพื่อให้เปรียบเทียบการจัดประเภทความล้มเหลวของคำสั่งข้าม adapter ได้ และ สภาพบน wire แบบเดียวกันถูกจัดประเภทอย่างสม่ำเสมอ ให้จัดประเภทความล้มเหลวของคำสั่ง order ที่เปลี่ยน state ทุกตัวเป็น variant หนึ่งของ CommandFailure:

ประเภทหลักฐานVariant ของ CommandFailureTerminal event จากหลักฐานนี้
ความล้มเหลวฝั่ง local ที่ชัดเจนNotSentใช้ได้
venue rejection ที่ชัดเจนVenueRejectedใช้ได้
ผลลัพธ์ที่ไม่ทราบAmbiguousไม่เคย

การจัดประเภทเป็น Ambiguous จะไม่ emit terminal event ด้วยตัวเองเลย หลักฐานที่ชัดเจนที่มาภายหลัง จาก stream update, query, poll หรือ reconciliation ยังคง resolve คำสั่งได้ทั้งสองทาง

การยอมรับหรือการอัปเดตที่ชัดเจนจาก venue ไม่ใช่ความล้มเหลวและไม่มี variant ให้ apply event ของ venue โดยตรง

ใช้หลักฐานที่ชั้นล่างรักษาไว้เพื่อจัดประเภทเพียงครั้งเดียวที่ขอบเขตของ execution อย่าแยก branch ใหม่ ตาม error enum ที่จุด emit แต่ละจุด ใช้กฎนี้กับคำสั่ง order ที่เปลี่ยน state ทุกตัว ทั้ง submit, modify และ cancel เหมือนกัน รวมถึงรูปแบบ batch และ list classifier ที่จำกัดอยู่กับคำสั่งประเภทเดียวจะปล่อยให้ประเภทอื่น คลาดเคลื่อนไป ส่วน query ไม่สร้าง terminal command event และไม่ต้องจัดประเภท

แยกแกนนี้ออกจาก is_retryable ความสามารถในการ retry ตอบว่าจะส่ง request ใหม่หรือไม่ ส่วนความกำกวม ตอบว่า venue อาจดำเนินการกับความพยายามแรกไปแล้วหรือไม่ error หนึ่งอาจเป็นทั้งสองอย่าง, อย่างใดอย่างหนึ่ง หรือ ไม่เป็นเลย และการรวมสองอย่างนี้เข้าด้วยกันคือสิ่งที่ทำให้ผลลัพธ์ที่ไม่ทราบดูเหมือน rejection

มีสองสภาพที่มักจัดประเภทผิด:

  • HTTP 5xx ที่ไม่มีหลักฐานของคำสั่งที่ชัดเจนถือว่ากำกวม มันพิสูจน์ได้เพียงว่าคำสั่งไม่ได้รับ การยืนยัน ไม่ได้พิสูจน์ว่า venue ไม่ได้ apply คำสั่งนั้น และ gateway 5xx ก็ไม่ได้พิสูจน์ว่า request ไปไม่ถึง venue
  • การ parse response ที่ล้มเหลวถือว่ากำกวม ขณะที่การ encode request ที่ล้มเหลวเป็น NotSent ทั้งสองอาจ ปรากฏเป็น serialization error variant เดียวกัน ดังนั้นให้จัดประเภทตามว่าความล้มเหลวเกิดขึ้นฝั่งใดของ ขอบเขตการเขียน

แยก diagnostic ออกจากเหตุผลที่แสดงต่อ strategy

รักษา diagnostic error ที่มีโครงสร้างไว้ตลอดการจัดประเภทและการ log ให้สร้าง เหตุผลที่แสดงต่อ strategy เฉพาะที่ขอบเขตของ execution event หลังจากตัดสินใจเรื่องผลลัพธ์และการ retry แล้ว

สำหรับ error แบบ opaque จาก client trait ให้ log เฉพาะ operation และ metadata ของคำสั่งที่เป็น public และเชื่อถือได้ เก็บ typed status, venue code หรือหมวดของ transport ไว้ที่ขอบเขตของ adapter ที่รู้ type ของมัน อย่า format payload ของ error ที่ไม่แน่นอนเพื่อดึงรายละเอียดเหล่านั้นกลับมา command logger ร่วมยังคงรับ parameter error เพื่อความเข้ากันได้กับผู้เรียก แต่จะไม่แสดงข้อความของมัน

รูปแบบผู้ใช้เนื้อหาที่ต้องมี
Diagnostic errorการจัดประเภท, การควบคุม retry, log และผู้ดูแลระบบsource แบบ typed พร้อม status, venue code, endpoint, backoff, transport และ context ของการ decode ที่มี
Strategy-facing reasonrejection event ที่ strategy ใช้ความหมายจาก venue แบบจำกัดขนาด โดยไม่มี HTTP prefix, response envelope, markup, control character หรือ secret

format ข้อความ denial ฝั่ง local แบบมาตรฐานจาก OrderDeniedReason โดยใช้ suffix น้อยที่สุด ที่จำเป็นต่อการระบุ context ของ diagnostic:

  • emit CODE เมื่อ denial ไม่ต้องการ suffix สำหรับ diagnostic
  • ใช้ CODE: value สำหรับค่า typed หนึ่งค่าหรือ diagnostic แบบข้อความอิสระ code ระบุค่า เดียวอยู่แล้ว จึงไม่ต้องใส่ชื่อซ้ำ
  • ใช้ CODE: key=value, key=value เฉพาะเมื่อค่า typed หลายค่าต้องแยกแยะกัน
  • ใช้ CODE: value; free text เมื่อมีค่า typed หนึ่งค่านำหน้า diagnostic แบบข้อความอิสระ

เฉพาะ code นำหน้าเท่านั้นที่เป็น canonical อย่า parse suffix ของ diagnostic เพื่อดึงการจัดประเภท, ความสามารถในการ retry หรือผลลัพธ์ของคำสั่งกลับมา

ใช้กฎเหล่านี้ที่ขอบเขต:

  • จัดประเภทจากหลักฐานแบบ typed หรือมีโครงสร้าง ห้ามดึง status, ความสามารถในการ retry หรือผลลัพธ์ของคำสั่ง กลับมาจากข้อความที่ format สำหรับแสดงผล
  • การดึงเหตุผลที่สะอาดออกมาต้องไม่ลบ diagnostic error หรือหลักฐานที่ใช้จัดประเภท มัน
  • เลือกใช้ฟิลด์และ code ของ error ที่ venue บันทึกไว้ในเอกสาร ให้ sanitize และจำกัดขนาดข้อความดิบที่เป็น fallback ก่อน log, intern หรือ emit และใช้ fallback ที่คงที่เมื่อไม่มีข้อความที่มีประโยชน์เหลืออยู่
  • ใช้ function การจัดประเภทและเหตุผลที่ adapter เป็นเจ้าของตัวเดียวกันกับหลักฐานจาก venue ที่เทียบเท่ากัน ไม่ว่าจะมาจาก HTTP, WebSocket, การ poll หรือ reconciliation

ตั้ง OrderRejected.due_post_only จาก venue code หรือ flag ที่มีโครงสร้างเมื่อโปรโตคอลมี ให้ มิฉะนั้นให้ใช้ message classifier แบบแคบที่ adapter เป็นเจ้าของและมีแหล่งอ้างอิงตัวเดียวในทุกเส้นทาง ของ venue ทดสอบ case บวกที่ตรงทุกตัวอักษรและ message ที่ใกล้เคียงแต่ไม่ตรง อย่าสร้าง venue classifier ข้าม adapter

รูปแบบของ HTTP client

โครงสร้างของ client

การออกแบบที่พบบ่อยแยกความรับผิดชอบออกเป็นสามส่วน:

Layerรับสร้างเป็นเจ้าของ
Raw clienttype ของ request และ query ของ venueresponse model ของ venue และ transport errortransport, authentication, rate limit และการ encode บน wire ที่แน่นอน
Domain clientidentifier และค่า domain ของ Nautilusdomain object, report หรือ acknowledgementsemantics ของ operation, context การ parse, caching และการ map ไปยัง domain
Execution clientคำสั่ง execution ของ Nautiluslifecycle event และ execution reportวงจรชีวิตของคำสั่ง, การจัดประเภทหลักฐานความล้มเหลว และ policy ของ terminal event

execution client เป็นขอบเขตร่วมของผลลัพธ์คำสั่ง raw client และ domain client รักษาหลักฐาน เฉพาะ adapter ไว้มากพอที่จะแยกความล้มเหลวก่อนการส่งออกจากความล้มเหลวหลังจากที่ venue อาจได้ รับ request แล้ว โดยยังคง return type ตามธรรมชาติของ venue และ domain ไว้ อย่าบังคับให้คืน CommandFailure เพียงเพื่อทำให้การจัดการคำสั่งเป็นมาตรฐาน

แชร์ประเภทหลักฐานของ CommandFailure และ policy ของ terminal event ข้าม adapter แต่เก็บ error code ของ venue, response status, semantics ของโปรโตคอล และการ map ไปยังประเภทหลักฐานไว้ภายใน adapter อย่าสร้าง venue classifier ข้าม adapter หรือ classification trait ร่วม

ใช้ HTTP client ชั้นเดียวเมื่อโปรโตคอลเล็กและการแยก raw/domain จะเพิ่มแค่ method สำหรับส่งต่อ ให้แยกตามผลิตภัณฑ์เมื่อ endpoint, signature หรือ response model เปลี่ยนไปตาม กลุ่มผลิตภัณฑ์ ขอบเขตของ execution ยังคงเหมือนเดิมในทั้งสองโครงสร้าง

ตั้งชื่อ method ระดับล่างตาม operation ของ venue เมื่อทำได้ เช่น get_instruments หรือ place_order และตั้งชื่อ domain method ตาม semantics ของ Nautilus เช่น request_instruments, submit_order หรือ cancel_order

ลำดับการทำงานของ request

ไม่ว่าจะมี client หนึ่งหรือสองตัวเป็นเจ้าของความรับผิดชอบเหล่านี้ ให้ขอบเขตชัดเจนเสมอ:

  1. ที่ขอบเขต domain ให้ validate input ของ Nautilus และสร้าง parameter ของ venue แบบ typed
  2. ที่ขอบเขต transport ให้เลือก HTTP method และ path แล้ว serialize query หรือ body ที่แน่นอน
  3. จัดสรร request identity, timestamp หรือ nonce ที่จำเป็น sign รูปแบบบน wire ที่แน่นอน เมื่อจำเป็น แล้วส่งผ่าน nautilus_network::http::HttpClient ร่วมพร้อม rate-limit key ที่เกี่ยวข้อง
  4. decode response envelope และรักษาความล้มเหลวด้าน transport, HTTP status, venue และการ parse ไว้
  5. ที่ขอบเขต domain ให้แปลง payload ที่สำเร็จเป็น domain type ด้วย context ของ instrument, account และเวลาที่ระบุชัด

แยกการสร้าง typed request ออกจากการส่ง ซึ่งทำให้ทดสอบ signature และการ encode canonical query ได้โดยไม่ต้องมี server ให้วางการแปลง response ไว้ใน parser function แบบ pure เมื่อไม่ ต้องใช้ live state

typed request builder และ query builder รักษาความแตกต่างระหว่างฟิลด์ที่ละไว้, ศูนย์ที่ระบุชัด และ ค่าว่าง ให้ parameter ของ venue ที่จำเป็นยังคงจำเป็น ละ parameter ที่เป็น optional ที่ไม่มีค่าออกจากรูปแบบบน wire และทดสอบ query หรือ body ที่ serialize แล้วให้ตรงทุกประการ

test ของ pagination ครอบคลุมทิศทางของ cursor, ขอบเขตแบบรวมปลาย (inclusive), record ซ้ำที่ขอบเขต และ cursor ที่ซ้ำหรือหน้าว่าง เพื่อให้ pagination ไม่วนไม่รู้จบ

การ sign request และ authentication

สำหรับแต่ละความพยายาม ให้สร้าง canonical byte ที่แน่นอนตามที่ venue ต้องการ แล้ว sign รูปแบบ นั้นเพียงครั้งเดียว ให้ทดสอบ:

  • ลำดับฟิลด์และตัวคั่น
  • หน่วยของ timestamp และ receive-window
  • การ encode decimal และ enum
  • การ hash body หรือ query
  • identifier ของ environment และ account
  • vector ที่รู้จักของ venue เมื่อมี

ระบุความเป็นเจ้าของ nonce หรือ sequence ให้ชัดเจน หากคำสั่งรันพร้อมกันได้ ให้กำหนดว่า adapter serialize, จัดสรร หรือปฏิเสธ nonce ที่ขัดแย้งกันอย่างไร ห้าม retry request ที่ sign แล้วและเปลี่ยน state ด้วย identity ใหม่ เว้นแต่ semantics ของ venue ทำให้ปลอดภัย

ถือว่า request identity, timestamp และ nonce เป็นฟิลด์โปรโตคอลแยกกัน แม้ venue จะรวม ไว้ใน signed payload เดียว component ที่จัดสรร nonce ยังเป็นเจ้าของกฎการเรียงลำดับของมันด้วย

สำหรับการเตรียม request และการกู้คืน:

  1. สร้างและ sign จากค่าที่จองไว้ค่าเดียวกัน
  2. จัดการความล้มเหลวก่อนส่ง, การส่งที่ไม่แน่นอน และการที่ venue ปฏิเสธ nonce ตาม semantics การใช้ nonce ของ venue ที่บันทึกไว้
  3. เมื่อ sequence ไม่ตรงกัน ให้ resynchronize จากแหล่งที่เชื่อถือได้ก่อนส่งคำสั่งที่เปลี่ยน state เพิ่มเติม

ทดสอบ vector แบบ deterministic, การจัดสรรพร้อมกัน, ความเป็น monotonic หรือความไม่ซ้ำ และการกู้คืนหลัง sequence ถูกปฏิเสธ

การจัดการ error และ retry logic

map ความล้มเหลวด้าน transport, HTTP status, venue error, การ parse และการ validate โดยไม่ลบแหล่งที่มาของมัน ให้ retry เฉพาะเมื่อความล้มเหลวถูกจัดประเภทเป็นแบบชั่วคราว (transient) และ operation นั้นทำซ้ำได้อย่างปลอดภัย ให้ประกอบการตัดสินใจทั้งสอง ที่ขอบเขตของ client predicate ที่ดูเฉพาะ error ไม่ใช่ retry policy ที่สมบูรณ์ contract นี้ใช้ กับเส้นทาง request ทั้ง HTTP และ WebSocket

จัดประเภทความล้มเหลวชั่วคราว

ให้การจัดประเภทความล้มเหลวชั่วคราวเป็นของ adapter เพราะ status code, error code และ semantics ของ rate limit ของ venue แตกต่างกัน ให้ transport แต่ละตัวของ adapter มี entry point ของ classifier สำหรับ production เพียงหนึ่งจุด กำหนดกฎที่ HTTP และ WebSocket ใช้ร่วมกันเพียงครั้งเดียวภายใน adapter แล้วเรียกจาก entry point เหล่านั้น ลบเส้นทาง classifier ที่ถูกแทนที่แล้วออก อย่าสร้าง venue classifier ข้าม adapter หรือ trait ร่วม

กั้นการ retry ด้วยความปลอดภัยของ operation

ที่แต่ละจุดเรียก ให้ข้ามการ retry สำหรับ operation ที่ไม่ปลอดภัย หรือส่ง predicate should_retry ที่ รวมการจัดประเภทความล้มเหลวชั่วคราวเข้ากับความปลอดภัยของ operation POST อาจ retry ได้อย่างปลอดภัย และ DELETE อาจไม่ปลอดภัย นี่คือการ implement safety test

การทำซ้ำจะปลอดภัยก็ต่อเมื่อเงื่อนไขทั้งหมดนี้เป็นจริง:

  • ไม่สามารถ apply การเปลี่ยน state ซ้ำสองครั้ง
  • ไม่สามารถเปลี่ยน order ที่ความพยายามแรกไม่ได้ระบุ
  • ไม่สามารถรายงานความสำเร็จก่อนหน้าเป็น rejection

ใช้เงื่อนไขเหล่านี้กับแต่ละ operation:

  • การอ่านหรือ operation แบบ idempotent อื่นอาจ retry ความล้มเหลวชั่วคราวที่จัดประเภทแล้วได้ POST แบบ อ่านอย่างเดียวอาจ retry ได้ allowlist ตาม method เช่น GET และ DELETE ไม่ได้พิสูจน์ความปลอดภัย

  • request ของ session token จะ retry ได้เฉพาะภายใต้เงื่อนไขเหล่านี้:

    • การทำซ้ำเพียงสร้าง token อายุสั้นเพิ่มอีกตัว
    • ไม่ได้ revoke session ที่มีอยู่
    • ไม่ได้สร้าง credential ที่คงอยู่ถาวร
  • ส่งคำสั่ง submit, submit order list, modify, cancel, batch cancel และ cancel-all เพียงครั้งเดียว retry เฉพาะเมื่อการตรวจจับรายการซ้ำสำหรับ request identity ที่คงที่ หรือ semantics แบบ idempotent สำหรับเป้าหมายเดียวกัน ยังคงใช้ได้ ตลอดช่วงเวลาของการ retry

ช่วงเวลานั้นไม่ได้มีแค่เวลาที่ order แรกค้างอยู่:

  • รวมถึงเวลาหลังจาก order เป้าหมาย fill หรือ cancel แล้ว
  • ดำเนินไปจนกว่า clock การตัดรายการซ้ำของ venue จะหมดอายุ ให้งบการ retry จบภายใน clock นั้น

Betfair กำหนดงบการ retry ของ order ไว้ 45 วินาทีภายในช่วง customerRef 60 วินาที

เมื่อ test นั้นไม่เป็นจริง ให้ส่งคำสั่งเพียงครั้งเดียว และปล่อยผลลัพธ์ที่ไม่ทราบไว้ให้ stream update, query, การ poll หรือ reconciliation ดู รักษา identity และความกำกวม

รักษา identity และความกำกวม

จัดสรร request identity เชิง semantics ไว้นอก retry closure และให้คงที่ตลอด ความพยายาม สร้าง timestamp ของ authentication, signature หรือฟิลด์ transport อื่นใหม่เฉพาะเมื่อ การเปลี่ยนไม่ได้เปลี่ยน request identity ของ venue หรือการตรวจจับรายการซ้ำ

ความกำกวมเป็นแบบ monotonic ข้ามความพยายามของคำสั่งเชิง semantics เดียวกัน เมื่อความพยายามใดอาจไปถึง venue แล้ว ความล้มเหลวที่ตามมาจะยังคงกำกวม venue rejection ที่ตามมาจะ resolve ความกำกวมได้เฉพาะเมื่อ semantics ที่บันทึกไว้ทำให้ response นั้นเชื่อถือได้สำหรับ request identity เดียวกัน และ semantics เหล่านั้นต้องพิสูจน์ด้วยว่าไม่มีความพยายามใด ถูก apply

การยอมรับจะ resolve ความกำกวมได้เฉพาะเมื่อจับคู่กับคำสั่งเชิง semantics เดียวกัน ก่อนสร้าง domain identifier หรือผูกกับ order ฝั่ง local ให้ validate venue identifier ที่คืนมา ตรวจ syntax และ ขอบเขตที่คาดไว้ string ที่ไม่ว่างเพียงอย่างเดียวไม่ใช่หลักฐาน identifier ที่ผิดรูปแบบหรือไม่ตรงกันจะทำให้ผลลัพธ์ ยังกำกวม เว้นแต่มีหลักฐานที่เชื่อถือได้แยกต่างหากพิสูจน์การปฏิเสธ

response ของ venue ที่แจ้งว่า identity ซ้ำแสดงว่า venue เคยเห็น request ก่อนหน้าที่มี wire identity นั้น อย่า ถือว่าเป็นการปฏิเสธคำสั่งเดิมโดยปริยาย ให้ใช้เพื่อ resolve คำสั่งปัจจุบันเฉพาะ เมื่อ adapter พิสูจน์ได้ว่าเป็น identity เชิง semantics เดียวกัน หาก identity อาจชนกันหรือขอบเขตไม่แน่นอน ให้คงผลลัพธ์เป็นกำกวมและ reconcile กับ state ของ venue

จัดการ backoff และการยุติ

เคารพสัญญาณ backoff และ rate limit ของ venue และหยุด retry เมื่อถูก cancel ใช้ RetryManager ร่วมเมื่อ model การ cancel และ backoff ของมันเหมาะสม

RetryManager ส่ง RetryError แบบ typed ไปยัง error callback ของผู้เรียก: Canceled, OperationTimeout, ElapsedBudgetExceeded หรือ InvalidConfiguration ให้ match variant เมื่อ adapter ต้องแยกแยะเหตุผลของการควบคุม ห้ามแยก branch ตามข้อความที่แสดง error ที่คืนมาสำหรับ OperationTimeout จะถูกประเมินโดย should_retry ดังนั้นให้ map ไปยัง variant timeout แบบชั่วคราวของ adapter เมื่อ ต้องการให้ timeout retry ส่วนเหตุผลที่สังเคราะห์ขึ้นอื่น ๆ จะยุติโดยไม่จัดประเภทใหม่

InvalidConfiguration ถูกสร้างก่อนที่ operation จะรันได้ จึงเป็นความล้มเหลวฝั่ง local ที่ชัดเจน ให้รักษาหลักฐานนั้นไว้แทนการ map ไปเป็นผลลัพธ์ด้าน transport หรือแบบกำกวม

control error ของ RetryManager ไม่ได้บันทึกว่า operation ได้รันหรือไม่ ให้ติดตามความเป็นไปได้ของการส่งที่ ขอบเขตของ adapter สำหรับคำสั่งที่เปลี่ยน state โดยถือว่าการเข้าสู่ send operation คือการส่งที่อาจเกิดขึ้นแล้ว เว้นแต่มีหลักฐานที่แม่นยำกว่า จัดประเภทการ cancel, timeout ต่อความพยายาม และการใช้ retry หมดเป็น CommandFailure::NotSent เฉพาะเมื่อหลักฐานฝั่ง local พิสูจน์ว่าไม่มีความพยายามใดถูกส่ง หากไม่มีหลักฐานดังกล่าว ให้จัดประเภทเป็น CommandFailure::Ambiguous

map แต่ละเส้นทางการยุติเพราะงบเวลาหมดตามหลักฐานการส่ง แทนที่จะดูจากรูปร่างของ error ที่คืนมา หาก error กำหนด delay ขั้นต่ำและ retry delay ที่มีผลไม่สามารถอยู่ในงบที่เหลือได้ RetryManager จะคืน error ดั้งเดิมของ operation โดยไม่สังเคราะห์ budget error ในกรณีนี้

ทดสอบพฤติกรรมการ retry

test ที่เจาะจงจะแยกแยะ:

  • ความล้มเหลวชั่วคราวออกจากความล้มเหลวถาวร
  • HTTP 429 response ทั้งแบบที่มีและไม่มีคำแนะนำ backoff จาก venue เมื่อโปรโตคอลเปิดเผย
  • operation แบบอ่านอย่างเดียวหรือ idempotent ที่ retry รวมถึง request ที่ไม่ใช่ GET และ submit, modify, cancel, batch cancel หรือ cancel-all ที่ส่งครั้งเดียว โดย mock server ได้รับ request เพียงหนึ่งครั้งพอดีสำหรับคำสั่งเหล่านั้น ความล้มเหลวชั่วคราวหลังจากอาจส่งไปแล้วจะทิ้ง ผลลัพธ์ไว้เป็นกำกวมและไม่ emit rejection
  • ความล้มเหลวสุดท้ายหลังจากความพยายามก่อนหน้าที่อาจส่งไปแล้ว รวมถึง venue rejection ที่ตามมา
  • response ที่แจ้ง identity ซ้ำสำหรับคำสั่งเชิง semantics เดียวกัน และการชนกันของ wire identity กับ คำสั่งอื่น
  • request identity เชิง semantics ที่คงที่ข้ามความพยายาม รวมถึงการ retry ที่รีเฟรชฟิลด์ authentication เมื่อโปรโตคอลอนุญาต
  • การ cancel, timeout ต่อความพยายาม และทุกเส้นทางการยุติเพราะงบเวลาหมด ทั้งก่อนและหลัง การส่งที่อาจเกิดขึ้น

Conformance ของ retry gate

ตารางนี้ครอบคลุมเฉพาะ HTTP retry gate ไม่ใช่การสำรวจที่สมบูรณ์ และไม่ได้ประเมิน การ retry ของ WebSocket หรือ gRPC adapter ใหม่ต้องทำตาม safety test และอย่าคัดลอก gate ที่ไม่ปลอดภัย

คอลัมน์ status ใช้นิยามเหล่านี้:

  • Conforms: adapter ตัดสินใจตาม operation และส่งคำสั่ง order ครั้งเดียว เว้นแต่การทำซ้ำ จะปลอดภัย
  • Over-restricts: คำสั่ง order ถูกส่งครั้งเดียว แต่ gate คือ HTTP method ดังนั้น POST ที่ปลอดภัย จะไม่ถูก retry
  • Unsafe: คำสั่ง order หรือการเปลี่ยน state อื่นอาจถูก apply ซ้ำสองครั้ง
AdapterRetry gateคำสั่ง orderStatusหมายเหตุ
Architect AXallowlist ตาม method: GET, HEAD และ OPTIONSส่งครั้งเดียวOver-restrictsPOST /authenticate ไม่ถูก retry
Binanceallowlist ตาม method: GETส่งครั้งเดียวOver-restricts
Betfairการ retry order ที่กำกวมใช้ customerRef เดิมretry ภายในงบ 45 วินาทีและช่วง customerRef 60 วินาทีConforms
Bybitทุก method เมื่อ error retry ได้submit, submit order list, modify, cancel และ batch cancel บน demo จะ retry ส่วน cancel-all retry ในทุก environmentUnsafe
Coinbaseallowlist ตาม method: GET และ DELETEส่งครั้งเดียวOver-restrictsPOST แบบ preview ที่อ่านอย่างเดียวไม่ถูก retry
Deriveการอ่าน retry การเขียนส่งครั้งเดียวส่งครั้งเดียวConformsplace, cancel และ replace ใช้ send_private_write ส่วน cancel-all และ cancel-by-label ใช้ send_private_once
Hyperliquid/info retry ส่วน /exchange ไม่ retryส่งครั้งเดียวConforms
Kraken spotsend_request retrycancel เดี่ยว retry ส่วน submit และ amend ส่งครั้งเดียว cancel-all ของ execution เลือก ID ที่ระบุชัดและส่งครั้งเดียวUnsafeCancelAll และ EditOrder retry แต่ execution client ไม่ได้เรียกใช้ HTTP 4xx ที่ไม่เกี่ยวกับ auth ถูกจัดประเภทเป็น network error
Lighterการเขียน order และ referral ส่งครั้งเดียวส่งครั้งเดียวConforms
OKXเส้นทาง submit ได้รับการยกเว้น ส่วน POST request อื่น retrysubmit, modify และ cancel ปกติใช้ WebSocket ส่วน algo cancel, spread cancel และ spread cancel-all retry ผ่าน HTTPUnsafe

Rate limiting

HttpClient ร่วมรองรับ rate limiter ได้ตั้งแต่หนึ่งตัวขึ้นไป ให้กำหนดขอบเขต state ของ limiter ตาม quota ของ venue ไม่ใช่ตาม object ของ Rust ที่สะดวก:

  • แชร์ bucket ระหว่าง client และ operation ที่ใช้ allowance เดียวกัน
  • แยก bucket เฉพาะเมื่อ venue เผยแพร่ quota ที่เป็นอิสระต่อกัน
  • ขอ quota ที่จำเป็นทั้งหมดก่อนส่ง request
  • ให้ loop ของ pagination และ retry อยู่ภายใต้ policy เดียวกัน

ให้ตรงกับมาตรวัดจริงของ venue: รูปร่างของ window, พฤติกรรม burst, น้ำหนักของ endpoint และ traffic ภายนอกที่ใช้ ร่วมกัน token bucket ที่อัตราตามประกาศยังอาจเกิน rolling window แบบเข้มงวดได้หลังจาก burst หลังช่วงว่าง อย่าคิดว่า latency บน wire จะสร้างช่องว่างเผื่อให้

เมื่อ venue จำกัดจำนวนคำสั่งที่ยังไม่ได้ตอบรับพร้อมกันแยกต่างหาก ให้เพิ่ม in-flight gate แบบ closed-loop ข้าง ๆ send-rate limiter ปล่อย slot ของมันเมื่อได้รับ terminal acknowledgement, rejection หรือ send failure ทุกครั้ง และ reset gate เมื่อ reconnect rate limiter เพียงอย่างเดียวไม่สามารถสังเกต latency ของ acknowledgement ได้

อย่าคัดลอกชื่อ bucket หรือ quota ของ adapter หนึ่งไปใช้กับอีกตัว ให้บันทึกข้อจำกัดที่ผู้ใช้มองเห็นและ configuration ไว้ใน integration guide

รูปแบบของ WebSocket client

การ dispatch ของ WebSocket เป็นไปตาม contract ร่วมด้านความเป็นเจ้าของและการ route ขณะที่การจัดวาง module และ container ของ state ยังเป็นเรื่องเฉพาะของ adapter ให้ code ใหม่สอดคล้องกับ network abstraction ร่วม, cache primitive แบบมีขอบเขต และ protocol peer ที่ใกล้เคียงที่สุด อย่าถือว่า dispatch module ของ adapter ตัวใดตัวหนึ่ง หรือการรวม state ของหลาย venue เป็นสถาปัตยกรรมเป้าหมาย

โครงสร้างของ client

รูปแบบที่พบบ่อยแยก outer client ออกจาก handler task:

  • outer client เป็นเจ้าของวงจรชีวิต, การประสานงาน authentication, เจตนาของ subscription และ stream ที่เปิดให้ data client หรือ execution client ใช้
  • handler เป็นเจ้าของ WebSocketClient, serialize คำสั่ง, decode frame และ emit message แบบ typed
  • channel ใช้ส่งคำสั่งและ message ที่เป็นเจ้าของข้ามขอบเขต

บาง adapter ใช้ stream mode และทำ reconnection เองใน adapter ส่วนบางตัวใช้ handler mode ของ network client และ reconnection อัตโนมัติ ทั้งสองแบบใช้ได้ ให้แยก handler ของ market data และ trading เฉพาะเมื่อ endpoint, authentication, throughput หรือ semantics ของโปรโตคอลคุ้มค่ากับ วงจรชีวิตที่เพิ่มขึ้น

เลือกขอบเขตของ client จากข้อเท็จจริงของโปรโตคอล:

รูปร่างของโปรโตคอลโครงสร้างที่ควรพิจารณาข้อผูกพัน
endpoint เดียวและโปรโตคอลแบบ multiplex เดียวclient และ handler อย่างละหนึ่งroute ตาม typed channel identity โดยไม่ทำซ้ำ state ของวงจรชีวิต
โปรโตคอลเดียวข้าม endpoint ของผลิตภัณฑ์ที่แยกกันorchestrator หนึ่งตัวพร้อม collection ของ clientconnect, close และ replay เจตนาสำหรับ product client ที่ active ทุกตัว
endpoint แบบ public, private หรือ trading ที่แยกกันtransport แยกกันพร้อม model ร่วมเมื่อมีประโยชน์authenticate และกู้คืนแต่ละ endpoint ตาม contract ของตัวเอง
wire format, การ sign หรือกฎการ reconnect ที่ต่างกันprotocol module แยกกันหลัง logic ร่วมของ data หรือ execวาง identity ร่วมของ instrument และ order ไว้เหนือ code เฉพาะโปรโตคอล

ตารางนี้เป็นเครื่องช่วยตัดสินใจ ไม่ใช่สถาปัตยกรรม dispatch เป้าหมาย อย่าแยก client เพียงเพื่อให้ตรงกับ ชื่อไฟล์ของ adapter อื่น และอย่ารวม endpoint หากจะซ่อน authentication, quota หรือการกู้คืนที่เป็นอิสระต่อกัน

flowchart LR
    subgraph client["Client (orchestrator)"]
        cmd_tx["cmd_tx<br/>├ Subscribe { args }<br/>├ PlaceOrder { params }<br/>└ MassCancel { id }"]
        out_rx["out_rx<br/><- {Venue}WsMessage<br/><- Authenticated<br/><- ChannelData"]
    end

    subgraph handler["Handler (I/O boundary)"]
        cmd_rx[cmd_rx]
        out_tx[out_tx]
        ws[WebSocket]
    end

    cmd_tx --> cmd_rx
    cmd_rx -->|"serialize"| ws
    ws -->|"parse -> transform"| out_tx
    out_tx --> out_rx

แผนภาพแสดงขอบเขตความเป็นเจ้าของที่พบบ่อย ไม่ใช่ชื่อ type หรือชื่อฟิลด์ที่บังคับ

Handshake ตอน initialize handler (SetClient)

หลาย adapter ย้าย WebSocketClient ที่เชื่อมต่อแล้วเข้าไปใน handler ที่ทำงานอยู่แล้วผ่านคำสั่ง SetClient ส่วนตัวอื่นสร้างหรือ publish handler ด้วยวิธีอื่น ไม่ว่าจะออกแบบแบบใด ให้รักษา invariant นี้ ไว้:

ไม่มีคำสั่ง subscribe, order หรือ control แบบ public ใดที่แซงหน้าการ initialize handler ได้

สำหรับ client ที่ทำงานด้วยคำสั่ง ให้ใช้ลำดับการเริ่มต้นนี้:

  1. สร้าง transport และ command channel แบบ private
  2. เข้าคิว SetClient, การ initialize cache ที่จำเป็น และการ replay subscription เริ่มต้น
  3. publish sender ที่ initialize แล้วภายใต้ publication lock ที่มีอยู่
  4. publish connection epoch หากมี แล้วจึงตามด้วยสถานะ connection แบบ active

ให้ writer ของ cache synchronize กับ startup snapshot และการ publish sender เพื่อให้ update เข้าไปอยู่ใน snapshot หรือไปถึง handler ใหม่อย่างใดอย่างหนึ่ง หากการ dispatch ของ cache ขึ้นกับสถานะ active ให้ publish สถานะนั้น ก่อนปล่อย guard ส่วน writer ของ cache แบบ synchronous ต้องรักษาลำดับเดียวกัน

ให้ authentication ที่ต้องรอ response จาก handler อยู่หลังการเริ่ม handler และอยู่นอก lock เหล่านี้

client ที่สร้าง handler พร้อม transport หรือ publish slot ของ connection pool ที่ initialize แล้ว ต้องรักษา invariant เดียวกัน ให้ทดสอบคำสั่งที่ส่งตรงขอบเขตของ connection เพื่อไม่ให้ race ทิ้งคำสั่งนั้นไปอย่างเงียบ ๆ และทดสอบด้วยว่า client ยังคง inactive ขณะที่การ publish sender ถูก block

Authentication

ใช้ AuthTracker เมื่อ state ของ authentication ต้อง แชร์ระหว่าง client, handler และเส้นทาง reconnect โดย adapter ยังคงเป็นเจ้าของรายละเอียดของโปรโตคอล:

  • เริ่มความพยายาม authenticate หนึ่งครั้งและจับคู่ response
  • ทำเครื่องหมายความสำเร็จหรือความล้มเหลวที่ชัดเจนจาก frame ของ venue ที่ชัดเจน
  • ทำให้ authentication เป็นโมฆะเมื่อ connection หลุดแบบที่ reconnect ได้
  • ทำให้ผู้ที่รออยู่ล้มเหลวเมื่อ shutdown แบบ terminal
  • กั้นการ replay แบบ private และคำสั่งไว้จนกว่า authentication จะสำเร็จ

token ที่รีเฟรชได้, session ของหลาย account และ endpoint แบบผสม public/private ต้องใช้ state เฉพาะ adapter ให้เก็บ state นั้นไว้ใกล้กับเส้นทางของ credential และ subscription และครอบคลุม การหมุนเวียน (rotation) หรือการหมดอายุด้วย test ที่เจาะจง

การจัดการ subscription

ใช้ SubscriptionState เมื่อ venue มี subscription ที่ต้องตอบรับหรือมีการ replay ตอน reconnect มันแยกเจตนาออกจากการยืนยัน และมี reference count สำหรับ subscriber ที่ซ้ำกัน

Stateความหมาย
Pending subscribeclient ตั้งใจจะ subscribe และกำลังรอการยืนยันจาก venue หรือข้อมูลแรก
Confirmedvenue ตอบรับ subscription แล้ว หรือส่งข้อมูลที่เชื่อถือได้ของ subscription นั้นมาแล้ว
Pending unsubscribeclient ตั้งใจจะลบ subscription และกำลังรอการยืนยัน
TriggerOperation ร่วมผลลัพธ์
subscriber ฝั่ง local ตัวแรกtry_mark_subscribe or mark_subscribeบันทึกเจตนา pending subscribe และส่งเมื่อจำเป็น
acknowledgement ของ subscribe หรือ frame แรกที่เชื่อถือได้confirm_subscribeย้ายเจตนาที่ pending ไปเป็น confirmed
subscribe ล้มเหลวmark_failureคงเจตนา subscribe ไว้เป็น pending เพื่อการกู้คืน
subscriber ฝั่ง local ตัวสุดท้ายmark_unsubscribeลบเจตนาที่ active และบันทึก pending unsubscribe
acknowledgement ของ unsubscribeconfirm_unsubscribeลบ pending unsubscribe โดยไม่ลบ resubscribe ที่เกิดขึ้นภายหลัง

ให้ยืนยันจาก acknowledgement ที่ชัดเจนของ venue เมื่อโปรโตคอลมีให้ หาก acknowledgement ไม่มีหรือเชื่อถือไม่ได้ ข้อมูลแรกที่เชื่อถือได้สามารถยืนยัน topic ได้ ทั้งสองเส้นทางอยู่ร่วมกันได้ เพราะการยืนยันเป็น idempotent ห้ามยืนยันจากการส่งฝั่ง local สำเร็จเพียงอย่างเดียว

เมื่อผล subscribe เป็นลบ ให้เรียก mark_failure เพื่อให้ reconnect ยังคงเจตนาไว้ ให้จับคู่ ผลของ unsubscribe แยกกัน เพื่อไม่ให้ acknowledgement ของ subscribe ที่มาช้าทำให้เจตนาที่ลบไปแล้วกลับมา และไม่ให้ acknowledgement ของ unsubscribe ที่เก่าแล้วลบ resubscription ที่เกิดขึ้นภายหลัง

สร้าง topic key ที่คงที่จาก argument ของ subscription ของ venue หากการ replay จะต้อง parse key นั้น แบบสูญเสียข้อมูล ให้เก็บ argument ดั้งเดิมไว้ เมื่อ reconnect:

  1. ทำให้ state ของ connection และ authentication เป็นโมฆะ
  2. สร้าง transport ใหม่
  3. authenticate เมื่อจำเป็น
  4. replay เจตนา subscribe ที่ active และที่ pending
  5. ยืนยัน subscription จาก acknowledgement ที่ชัดเจนหรือข้อมูลที่เชื่อถือได้
  6. แจ้งผู้ใช้ปลายทางเมื่อต้อง reset state ของโปรโตคอล

อย่า replay unsubscription ที่ pending อยู่ และจัดการ acknowledgement ที่มาช้าหรือเก่าแล้วโดยไม่ทำให้ subscription ที่ลบไปแล้วกลับมา SubscriptionState จัดหา state transition เหล่านี้ ส่วน adapter จัดหาการจับคู่ บน wire

การ route message

ให้ขอบเขตของการ route ตรวจสอบได้:

  • decode raw frame เพียงครั้งเดียว
  • จัดการ transport control, authentication และ acknowledgement ของ subscription ก่อนข้อมูล domain
  • validate identity ของ channel และผลิตภัณฑ์ก่อนเลือก parser
  • แปลง payload ของ venue เป็น typed adapter message หนึ่งตัวหรือลำดับ message ที่มีขอบเขต
  • dispatch domain event นอก state ของโปรโตคอลที่แก้ไขได้เท่าที่ทำได้
  • รักษา identity ไว้มากพอที่จะจับคู่ execution response และตัดรายการซ้ำจากแหล่งที่ซ้อนทับกัน

handler เป็นเจ้าของ transport control, authentication, acknowledgement ของ subscription, การ decode frame และการจับคู่ของโปรโตคอล ส่วน data client หรือ execution client ที่ใช้งานเป็นเจ้าของการ route และการ emit ด้าน domain การ parse อาจอยู่ใน handler ได้เมื่อขึ้นกับ state ของโปรโตคอลที่ handler เป็นเจ้าของ แต่การตัดสินความเป็นเจ้าของ execution แบบ tracked หรือ external ยังคงเป็นการตัดสินใจของ client

เมื่อรายงาน frame ที่ผิดรูปแบบ ให้ log parse error แยกจากข้อความบางส่วนของ payload ที่ sanitize และจำกัดขนาดแล้ว ห้าม log raw authentication frame หรือ frame ที่ schema อาจมี secret material ให้ log close code ของ peer ที่ชั้น transport ที่ได้รับ เก็บเหตุผลที่ server ควบคุมได้ตามอำเภอใจไว้นอก diagnostic แต่รักษาไว้สำหรับการจัดประเภท retry หรือการส่งต่อเมื่อจำเป็น adapter ไม่ควร log ซ้ำกับ log ของ transport ร่วม

การจัดวาง dispatch module, ชื่อ enum ระหว่างกลาง, context registry, การผูก venue และ container ของ state ยังคง เป็นเรื่องเฉพาะของ adapter ให้เลือกการออกแบบที่เล็กที่สุดที่ทำให้ความเป็นเจ้าของโปรโตคอลและ state transition ทดสอบได้ แยก component ออกมาเพิ่มเฉพาะเมื่อหลาย adapter ใช้ semantics และความเป็น atomic ของมันร่วมกัน

Reconnection และ shutdown

reconnection ต้องกู้คืน state ของโปรโตคอล ไม่ใช่แค่ socket:

  • สร้างใหม่หรือแทนที่เส้นทางคำสั่งก่อนรายงานว่า client active
  • authenticate private session ใหม่
  • กู้คืนเจตนาของ subscription และ context ของ instrument ที่จำเป็น
  • reset state ของ sequence, snapshot หรือ gap เมื่อ venue ต้องการ bootstrap ใหม่
  • รักษา state ของ execution ที่ in-flight ซึ่งจำเป็นต่อการจับคู่ response ที่มาช้าหรือ reconciliation

รองรับทั้ง WebSocket control frame และ text heartbeat ของ venue เมื่อเกี่ยวข้อง ปล่อยให้ client ร่วมจัดการ protocol control frame และเก็บ application heartbeat message ไว้ใน venue handler

ความเป็นเจ้าของการ reconnect

client แบบ handler mode ขอ reconnect ผ่าน client ร่วมแทน reconnect loop แบบ private request_reconnect ของมันคืน true เฉพาะเมื่อการเรียกนั้นย้าย client ที่ active ไปเป็นสถานะ reconnecting หาก adapter ต้องแยกแยะ variant ของ ReconnectRequestOutcome ให้ใช้ request_reconnect ของ reconnect handle transport ที่กำลัง reconnect อยู่แล้ว, กำลัง disconnect, ปิดแล้ว หรือไม่รองรับ ต่างต้องการ การตอบสนองที่ต่างกัน client แบบ stream mode เป็นเจ้าของ reconnect loop ของตัวเอง และ handle ของมันจะรายงาน Unsupported

อย่ากำหนดให้ socket เดิมต้องยังทำงานจนกว่าตัวแทนที่จะพร้อม ให้ใช้เส้นทาง reconnect ที่มีอยู่ แทนการเพิ่มความเป็นเจ้าของ connection แบบขนาน, buffering และการประสาน epoch เพื่อเลี่ยง ช่องว่างตอน reconnect

execution reconciliation มักกู้ state ของ order และ fill ที่พลาดไปได้ ส่วนช่องว่างของ market data ให้ใช้ snapshot หรือ replay ที่ venue รองรับ การกู้คืนขึ้นกับ coverage ของ venue และไม่รับประกันว่าจะได้รับ ทุก message ที่พลาดไป

Shutdown

shutdown ส่งสัญญาณให้ task, ขอให้ transport ปิด แล้ว join หรือ abort งานที่เป็นเจ้าของตาม policy แบบมีขอบเขต ทำให้ shutdown ซ้ำปลอดภัย และอย่าคิดว่า JoinHandle ของ handler มี เจ้าของเดียวเมื่อ object ของ client สามารถ clone ได้

Backpressure

WebSocket transport ร่วมและเส้นทาง event ของ adapter ใช้ Tokio channel แบบ unbounded เพื่อให้ receive loop ไม่ต้องรอความจุของคิว ให้รักษาแนวทางนี้สำหรับเส้นทาง live event การเพิ่ม bounded channel, การรวม (coalescing), การทิ้ง หรือ policy แบบ disconnect-on-full จะเปลี่ยน semantics ของแพลตฟอร์ม และ ต้องมีการออกแบบร่วมที่ชัดเจน ไม่ใช่การเปลี่ยนแปลงเฉพาะใน adapter

คิวแบบ unbounded แลก backpressure กับการเติบโตของหน่วยความจำ ให้งานใน receive loop กระชับ, เปิดเผย ความล้มเหลวของ handler และทดสอบการกู้คืนจาก consumer ที่หลุดการเชื่อมต่อ ห้ามทิ้ง execution event เด็ดขาด market data สามารถใช้ snapshot และ resynchronization ได้เฉพาะเมื่อ contract ของโปรโตคอลกำหนด การกู้คืนนั้นไว้

การจัดการ task

จัดประเภททุก task ใน production ตามเจ้าของก่อนเลือกที่เก็บและเส้นทาง shutdown ของมัน

ความเป็นเจ้าของการใช้งานพฤติกรรมที่ต้องมี
Session-scopedstream consumer, keepalive, health poll, refresh loop และ reconnect driversession group หนึ่งเป็นเจ้าของ task ตั้งแต่รับเข้าสำเร็จจนถึง disconnect หรือ startup ล้มเหลว
Command-scopedงานที่ spawn จาก data request แบบ synchronous หรือคำสั่ง executioncommand group แยกต่างหากเป็นเจ้าของ task โดยไม่ผูกผลลัพธ์ไว้กับ transport session
Explicitly singulartask เดียวที่ handle หรือผลลัพธ์แบบ typed ต้องอยู่ใน state ของเจ้าของเพื่อ join โดยตรงเก็บ handle ที่มีชื่อหนึ่งตัว และใช้กฎเดียวกันเรื่อง bounded join, forced abort และการรายงานความล้มเหลว
Handler-localretry future, send worker และงานลูกที่สร้างและ join ภายใน handler เดียวhandler ระบายงานให้หมดก่อนออก และเปิดเผยความล้มเหลวต่อเจ้าของ
Protocol exceptionผลลัพธ์ fan-out แบบ typed, timeout แบบมี key หรืองานที่การ join ฝั่ง local รักษาความหมายของโปรโตคอลเก็บข้อยกเว้นไว้เฉพาะที่, ระบุว่าทำไม group ร่วมจะทำให้ความหมายหายไป และทดสอบเส้นทาง shutdown ของมัน

ใช้ session group และ command group แยกกันแม้ทั้งสอง group จะมี timeout policy เดียวกัน disconnect ยุติ session ขณะที่คำสั่งที่รับแล้วอาจยังต้องการ reconciliation หรือ ผลลัพธ์แบบกำกวมที่ระบุชัด อย่าปล่อยให้ transport shutdown จัดประเภทผลลัพธ์ของคำสั่งนั้นใหม่อย่างเงียบ ๆ

การเก็บและการสังเกต task

TaskHandles เก็บ unit task handle โดยไม่กำหนด policy ของ spawn, cancellation, generation หรือ join ให้ใช้ภายใน component ที่กำหนดกฎเหล่านั้น

TaskGroup จัดหา policy ร่วมของ live client สำหรับ session task และ command task ที่ output เป็น unit ใช้ TaskGroup::spawn_named เมื่อ state ของ client ต้องสังเกตชื่อเชิงตรรกะ, identity ของ instance หรือสถานะ terminal ของ task ใน group TaskRef ของมันเป็นแบบอ่านอย่างเดียว: group ยังคงเป็นเจ้าของการ cancel และการ join แต่เพียงผู้เดียว การสังเกตแบบอ่านอย่างเดียวไม่ได้ทำให้ task เป็น explicitly singular

TaskRef::is_active และ TaskRef::is_finished เปิดเผย state ของวงจรชีวิตแบบทางเดียวเดียวกัน active หมายความว่า task ได้รับเข้าแล้วและยังไม่ถึงสถานะ terminal task อาจเสร็จก่อนที่ spawn_named จะคืนค่า และไม่มี state ใดพิสูจน์ว่า future ของผู้ใช้ได้รับการ poll ครั้งแรกแล้ว

function finish_task ใน task module เดียวกันใช้ policy แบบมีขอบเขตกับ handle แบบ explicitly singular โดยไม่ลบผลลัพธ์แบบ typed สำหรับรูปแบบความเป็นเจ้าของแบบระบุชัดอื่น ให้ spawn ผ่าน nautilus_common::live::get_runtime().spawn() ตามที่อธิบายใน Async code แล้วเก็บไว้หรือ await handle ที่ได้คืนมาในที่นั้น

Spawn ผ่าน task group

method ของ client trait แบบ synchronous ต้องไม่ block Tokio runtime ที่ active ให้ clone input ที่เป็นเจ้าของ, spawn operation แบบ asynchronous และคืนผลการ validate ฝั่ง local ลงทะเบียนงานที่ client เป็นเจ้าของ ผ่าน TaskGroup ของมัน group จะเก็บ handle ก่อนเปิด start gate ของ task ดังนั้น shutdown ที่เกิดพร้อมกันจะเป็นเจ้าของ task หรือปฏิเสธการรับเข้าอย่างใดอย่างหนึ่ง

Tokio usage hook ปฏิเสธ tokio::spawn ใน production code ของ adapter และกำหนดให้ใช้ path แบบเต็มสำหรับ spawn, time และ sync ของ Tokio

ทำให้ขอบเขตแบบ synchronous เล็กที่สุด:

fn spawn_request<F>(&self, description: &'static str, future: F)
where
    F: Future<Output = anyhow::Result<()>> + Send + 'static,
{
    let future = async move {
        if let Err(e) = future.await {
            log::warn!("{description} failed: {e:?}");
        }
    };

    if let Err(e) = self.command_tasks.spawn(future) {
        log::warn!("Skipping {description} after shutdown began: {e}");
    }
}

validate คำสั่งและ clone input แต่ละตัวก่อนสร้าง future งานที่อยู่นานกว่าการเรียก trait ต้องไม่ capture ค่าเหล่านี้:

  • การยืม RefCell
  • cache guard
  • การยืม clock
  • reference ไปยังคำสั่ง

เมื่อ task อายุยาวสร้าง task ลูก ให้ capture TaskSpawner จาก group ที่เป็นเจ้าของ ใช้ TaskSpawner::spawn_named เมื่อ task ลูกเหล่านั้นต้องมี identity ในความล้มเหลวตอน shutdown ด้วย spawner จาก generation ที่เก่ากว่าไม่สามารถลงทะเบียนงานใน generation ที่มาแทนได้

ให้แต่ละ task มี:

  • เจ้าของหนึ่งรายที่รับผิดชอบการ join หรือ abort
  • คำอธิบายที่คงที่สำหรับ log ความล้มเหลว
  • เส้นทางการ cancel
  • input ที่เป็นเจ้าของซึ่งไม่ถือการยืม RefCell หรือ engine ค้างไว้

เก็บผลลัพธ์แบบ typed ของ task ไว้เฉพาะใน component ที่ await มัน อย่าลบ type ของ JoinHandle<T> เพื่อ ให้เข้ากับ group แบบ unit-output เมื่อ T มีหลักฐานของ order, transport หรือ startup

Shut down และเปิด task generation ใหม่

task shutdown แบ่งเป็นช่วง synchronous และ asynchronous แยกกัน:

  1. stop, reset และ dispose เรียก begin_shutdown ซึ่งปิดการรับเข้าและ cancel generation ปัจจุบันโดยไม่ block runtime ใช้ abort แทนเฉพาะเมื่อ contract แบบ synchronous ที่มีอยู่ต้องการให้ cancel task ทันที
  2. disconnect หรือ connect แบบ asynchronous ครั้งถัดไป จะปิด transport ของ generation ตาม ลำดับโปรโตคอลที่กำหนด และเรียก finish_shutdown ด้วยช่วงเวลา graceful และ forced ที่มีขอบเขต
  3. finish_shutdown ระบาย task ที่ลงทะเบียนเข้ามาจาก race ที่อนุญาตซ้ำ ๆ และรายงานการ cancel และความล้มเหลวของการ join ที่ไม่คาดคิด หลังช่วง graceful มันจะ abort งานที่ยังไม่เสร็จ และรอ การ forced abort ภายในขอบเขตที่สอง
  4. start_generation เปิด group ใหม่หลังจาก generation ก่อนหน้าระบายหมดแล้วเท่านั้น timeout จะเก็บ handle ที่เหลือไว้และคงการรับเข้าไว้ในสถานะปิด

เมื่อ connect ล้มเหลวหลังจากสร้าง transport หรือรับ task เข้าแล้ว ให้ใช้ลำดับเดียวกันก่อนคืน startup error ปิด transport ทั้งหมดที่สร้างโดยความพยายามนั้น ระบายทั้งงาน session และงาน command ที่ อยู่รอดจากความล้มเหลวไม่ได้ และรวมความล้มเหลวของการ teardown ไว้ในหลักฐานที่คืนหรือ log

ทำให้การเรียก begin_shutdown และ finish_shutdown ซ้ำปลอดภัย method ของวงจรชีวิตแบบ synchronous อาจ เริ่ม teardown มากกว่าหนึ่งครั้งก่อนที่ขอบเขต asynchronous จะทำให้เสร็จ

ห้ามใช้ block_on ใน trait method

live runner เรียก method ของ data และ execution แบบ synchronous จากภายใน Tokio การเรียก block_on ในจุดนั้นอาจ panic เพราะมี runtime ทำงานอยู่แล้ว

ขอบเขตสิ่งที่ adapter ทำเหตุผล
DataClient หรือ ExecutionClient แบบ synchronousclone input ที่เป็นเจ้าของ, spawn operation แล้ว returnlive runner อาจกำลังรัน method นั้นภายใน Tokio อยู่แล้ว
method ของ async client, handler หรือ taskawait operation หรือ select คู่กับการ cancelขอบเขต async มีส่วนร่วมกับ runtime ที่ active อยู่แล้ว
binary ระดับบนสุดหรือ thread เฉพาะที่ไม่ใช่ Tokioblock เฉพาะเมื่อขอบเขตนั้นเป็นเจ้าของวงจรชีวิตของ runtimeไม่มี runtime แวดล้อมอยู่เมื่อสร้างขอบเขตนั้นอย่างถูกต้อง
Testใช้ #[tokio::test] หรือ runtime ที่ test เป็นเจ้าของharness เป็นเจ้าของการตั้งค่า runtime และหลีกเลี่ยงการเรียก block_on ซ้อน

อย่าใช้ข้อยกเว้นของระดับบนสุดและ test มาอ้างเพื่อ block ภายใน method ของ live client trait ให้ออกแบบขอบเขตที่กำกวมใหม่เป็น async

Graceful shutdown ด้วย CancellationToken

ใช้ CancellationToken เมื่อหลาย task มีวงจรชีวิตร่วมกัน ให้ select การ cancel ควบคู่กับ stream, timer หรือ response channel สำหรับ task ใน group ให้ขอ child token จาก generation group หรือ spawner และปล่อยให้ begin_shutdown cancel parent ของมัน ขอ token สำหรับตัวแทนที่ หลังจาก finish_shutdown ระบายทุก handle และ start_generation เปิด group ใหม่แล้วเท่านั้น การใช้ token ที่ถูก cancel แล้วซ้ำจะทำให้ task ที่มาแทนออกทันที ขณะที่การแทนที่ก่อนระบายเสร็จจะปล่อยให้ งานเก่าข้ามขอบเขตของการ reconnect

การทดสอบ

test พิสูจน์ semantics ของ adapter ที่ขอบเขตที่กว้างขึ้นเป็นลำดับ ให้เก็บ fixture ที่ถูกต้องแบบ canonical ไว้ใต้ test_data/ และไม่ให้ unit test และ integration test ทั่วไปเข้าถึง network ให้ได้ payload ที่ถูกต้องมาจาก เอกสารทางการของ venue หรือ response ของ venue ที่บันทึกไว้ อย่าประดิษฐ์ขึ้นเอง ส่วน input ที่ผิดรูปแบบหรือ ถูกดัดแปลงแบบสังเคราะห์ยังมีประโยชน์สำหรับ negative test, property test และ fuzz test เมื่อ test ระบุไว้ชัดเจน

ขอบเขตตำแหน่งทั่วไปสิ่งที่ต้องพิสูจน์
Pure protocol logictest module ใน src/**symbol, enum, timestamp, decimal, signature, codec, parser และ input ที่ผิดรูปแบบ
Public Rust client boundarytests/พฤติกรรมแบบ typed ของ HTTP และ WebSocket ผ่าน mock server, การ dispatch event, วงจรชีวิต และการ retry
Live venue acceptanceตัวอย่างของ adapter หรือ test nodeauthentication, subscription, execution, report, การกู้คืน และข้อจำกัดที่ประกาศไว้

การทดสอบ Rust

policy การทดสอบร่วมของ repository ใช้ #[rstest] สำหรับ test function ของ Rust, อนุญาต #[tokio::test] สำหรับ async test และไม่อนุญาต comment แบบ arrange/act/assert testing conventions hook บังคับใช้กฎ ระดับ repository เหล่านี้

Fixture และ assertion ของ parser

ใช้ค่า fixture ที่แน่นอนและ assert ทุกฟิลด์ output ที่คงที่ input ที่แตกต่างกันควรทำให้เห็นการสลับ ฟิลด์, ค่าที่ตกหล่น, precision ที่ผิด และค่าเริ่มต้นที่เกิดขึ้นโดยไม่ตั้งใจ

test ของ parser และ serializer ควรครอบคลุม:

  • fixture ที่สมจริงหนึ่งตัวสำหรับทุกกลุ่ม message หรือ instrument ที่รองรับ
  • ค่าขอบเขตของ precision ทศนิยม, ปริมาณ, timestamp, ID และรหัส enum
  • ฟิลด์ที่ไม่รู้จัก, หายไป, null และผิดรูปแบบตาม contract ของ venue
  • round trip หรือ canonical byte ในจุดที่โปรโตคอลกำหนด
  • error ที่คงที่สำหรับ input ที่ถูกปฏิเสธ

เก็บ envelope ของ venue ไว้ครบเมื่อฟิลด์ status, cursor ของ pagination, timestamp หรือ wrapper ของผลลัพธ์ที่ซ้อนกัน มีผลต่อพฤติกรรม บันทึกที่มาของ fixture ไว้ใน fixture เอง, README ที่อยู่ใกล้ ๆ หรือ source manifest ใช้ payload จริงแยกกันสำหรับ state ที่ต่างกันเชิงโครงสร้าง เช่น long, short, flat, ว่าง และ partially filled อย่า ดัดแปลง fixture แบบ happy-path ตัวเดียวให้เป็นทุก case ที่ถูกต้อง

หาก test ของ HTTP และ WebSocket ใช้ fixture loader หรือ model builder ร่วมกัน ให้วาง code สำหรับ test ไว้ใน module common::testing อย่าคัดลอก code test ร่วมนั้นไปไว้ใน production module รูปแบบนี้เป็นทางเลือก เมื่อไม่มี code test ที่ใช้ร่วมกัน

การ synchronize ของ client

ขับ method ของ public client ผ่าน mock HTTP server หรือ mock WebSocket server แล้ว assert event ที่ emit, request, สถานะ connection, สถานะ subscription, จำนวน retry และพฤติกรรม shutdown

เลือกใช้ notification ที่ test หรือ mock เป็นเจ้าของเมื่อ operation เปิดให้ใช้ ให้ subscribe ก่อน อ่าน state ที่เชื่อถือได้ แล้วตรวจซ้ำหลังทุก notification เพื่อไม่ให้พลาด transition ที่เกิดระหว่าง การอ่านกับการ await เมื่อไม่มีสัญญาณที่เหมาะสม ให้ใช้ wait_until_async การ sleep สั้น ๆ ใช้ได้เมื่อช่วงเวลา นั้นคือสิ่งที่กำลังทดสอบ แต่ไม่ควรใช้ปกปิดจุด synchronization ที่ขาดหายไป

การทดสอบเชิงฟังก์ชันและ integration

ทดสอบแต่ละขอบเขต public ด้วยหลักฐานของโปรโตคอลทั้งแบบสำเร็จและแบบมีปัญหา:

Surfaceหลักฐานแบบสำเร็จหลักฐานของความล้มเหลวและการกู้คืน
HTTP clientmethod, path, query หรือ body, authentication และ typed response ที่ตรงทุกประการcredential ที่หายไป, venue error, body ที่ผิดรูปแบบ, การจัดประเภท retry และการจบ pagination
WebSocket clientconnection, authentication, heartbeat, acknowledgement ของ subscription และการ route แบบ typedauthentication ล้มเหลว, frame ที่ผิดรูปแบบ, acknowledgement ที่เก่าแล้ว, disconnect, replay และ shutdown
Data clientrequest และ subscription สร้าง domain event ที่ครบถ้วนพร้อม identity และเวลาที่ถูกต้องความสด, การกรอง, input ที่ผิดรูปแบบ, gap ของ stream, unsubscribe และพฤติกรรม reconnect
Execution clientคำสั่งสร้าง event ตามลำดับ, account state และ reconciliation reportlocal denial, rejection ที่ชัดเจน, ผลลัพธ์ที่ไม่ทราบ, รายการซ้ำ, batch บางส่วน และการกู้คืนตอน startup

mock transport ควรเปิดเผย state มากพอที่จะ assert request, จำนวน connection, authentication, subscription และ event ที่ emit ให้รอเงื่อนไขที่สังเกตได้เหล่านั้นแทนการ sleep assert ทั้งสองฝั่งของขอบเขต: request ของ venue ที่แน่นอน และ event หรือ report ของ Nautilus ที่เป็นผลลัพธ์

data test ครอบคลุมทุก request และ subscription ที่ประกาศไว้ รวมถึง:

  • identity, precision และความสดของ instrument
  • ขอบเขตของ snapshot และ incremental ของ order book
  • หลาย symbol หรือหลายกลุ่มผลิตภัณฑ์ที่ใช้ connection ร่วมกัน
  • พฤติกรรมของ acknowledgement, rejection, unsubscribe, reconnect และ resubscribe
  • message ที่ผิดรูปแบบหรือไม่รู้จัก โดยไม่สูญเสียข้อมูลที่ถูกต้องที่ตามมา

execution test ครอบคลุมทุกคำสั่งและ report ที่ประกาศไว้ รวมถึง:

  • local denial ก่อน submit
  • venue rejection ที่ชัดเจน
  • context ของ diagnostic และเหตุผลที่แสดงต่อ strategy แบบสะอาดที่ตรงทุกประการสำหรับทุกเส้นทาง rejection ที่เปลี่ยนแปลง
  • ผลลัพธ์ของ transport ที่ไม่ทราบซึ่งยังคง reconcile ได้
  • ความพยายามที่กำกวมตามด้วย response ที่ดูเหมือนชัดเจน
  • venue identifier ที่คืนมาซึ่งหายไป, ผิดรูปแบบ และไม่ตรงกัน
  • ฟิลด์ error ที่มีโครงสร้าง และ fallback ของ raw body แบบมีขอบเขต: ว่าง, plain text, ข้อมูลที่มีโครงสร้าง แต่ผิดรูปแบบ, markup, UTF-8 ที่ไม่ถูกต้อง และ input ที่ใหญ่เกินไป
  • หลักฐานที่เทียบเท่ากันจาก HTTP, WebSocket, การ poll และ reconciliation ให้เหตุผลและ การจัดประเภทเดียวกัน
  • หลักฐาน post-only ที่มีโครงสร้าง หรือ text classifier ที่ตรงทุกตัวอักษร รวมถึง message ที่ใกล้เคียงแต่ไม่ตรง
  • ผลลัพธ์ของ batch แบบบางส่วนและราย order
  • stream update ที่ซ้ำหรือผิดลำดับ
  • account state, order ที่เปิดอยู่, fill, position และ reconciliation ตอน startup
  • cutoff คงที่ค่าเดียวข้าม query ของ order และ fill แบบมีขอบเขต รวมถึง record ที่อยู่ตรงขอบเขต
  • mass status ที่สมบูรณ์และไม่สมบูรณ์สำหรับแหล่ง report แต่ละแหล่งที่ล้มเหลวได้อย่างอิสระ
  • coverage ของ position snapshot หลัง reconnect, แถวที่ถูกข้าม, flat ที่ระบุชัด และ instrument ที่ไม่มีอยู่
  • การกู้คืน order ที่แน่นอนโดยไม่มีผลต่อ position หรือ portfolio เมื่อประวัติแบบมีขอบเขตไม่สมบูรณ์หรือ กำกวม
  • stop, reset และ dispose ที่เป็น idempotent

ให้ test ของ adapter โฟกัสที่พฤติกรรมของ adapter ข้อกำหนดการทดสอบ data และ ข้อกำหนดการทดสอบ execution กำหนด catalog ของ scenario ร่วมและ กฎการข้าม ให้ลิงก์ไปยังเอกสารเหล่านั้นแทนการคัดลอกรายการบางส่วนไปไว้ใน README ของ adapter

Acceptance testing

รัน acceptance test หลังจาก deterministic test ผ่านแล้วเท่านั้น ใช้ testnet หรือ account ที่ควบคุมได้ และ บันทึก:

  • environment และผลิตภัณฑ์ของ venue
  • specification case ที่รองรับและที่ข้าม
  • order type และ flag ที่ทดสอบ
  • case ของ reconnect หรือการกู้คืนที่ทดสอบ
  • ข้อจำกัดของ venue, rate limit และช่องว่างที่ทราบ

acceptance test ต้องตรวจสอบ event และ state ของ venue ไม่ใช่แค่ว่าไม่มี error ให้เก็บกวาด order และ position ที่เปิดอยู่ตามแผนการทดสอบ และอย่าอนุมานว่ารองรับ production จาก happy path เพียงเส้นเดียว

จัดเตรียม tester entry point ที่เกี่ยวข้อง:

  • Rust: crates/adapters/<adapter>/examples/node_data_tester.rs และ node_exec_tester.rs พร้อม subdirectory ตามผลิตภัณฑ์เมื่อโปรโตคอลแยกตามผลิตภัณฑ์

Execution tester วาง order จริงโดยค่าเริ่มต้น ให้ระบุเรื่องนี้เป็นคำเตือนไว้ที่ด้านบนของ module ตั้ง dry_run=False อย่างชัดเจนใน ExecTesterConfig เพื่อให้เห็นว่ามี option dry-run อยู่ การควบคุมของ Rust tester แตกต่างกันไป ให้ตรวจสอบก่อนรัน

ประสิทธิภาพและความทนทาน

เพิ่ม suite เหล่านี้ในช่วงท้าย หลังจากงาน functional, integration และ acceptance ยืนยันพฤติกรรมที่ถูกต้องแล้ว suite เหล่านี้เพิ่มความมั่นใจให้กับ hot path ที่ยืนยันแล้วและ input จาก venue ที่ไม่น่าเชื่อถือ แต่ไม่ได้แทนที่ conformance test

Canonical benchmark

ใช้ Criterion สำหรับการตรวจประสิทธิภาพเชิงลึกบนขอบเขตของ production ที่การวัดระบุว่า สำคัญ suite ของ Lighter และ Derive เป็นโครงสร้างอ้างอิง:

Suiteขอบเขตแบบ canonicalอ้างอิง
benches/data.rsraw frame หรือ payload ของ venue ผ่านการ decode, parse, lookup ใน cache เมื่อจำเป็น และการสร้าง domain ของ NautilusLighter data, Derive data
benches/exec.rsคำสั่ง order ผ่านการ serialize และ sign และเมื่อเกี่ยวข้อง payload ของ execution ขาเข้าผ่านการ dispatch eventLighter execution, Derive execution
benches/micros.rsต้นทุนเฉพาะการ decode, เฉพาะการ parse และ component ที่เจาะจง เพื่อระบุตำแหน่ง regression ที่พบที่ขอบเขตของ pipelineLighter micros, Derive micros

วาง instrument, payload, state ของ signer และ fixture อื่นที่สมจริงและใช้ร่วมกันไว้ใน benches/common/ สร้าง setup, การ allocate และ state ที่คงที่ไว้นอกช่วงที่จับเวลา เมื่อ production ไม่ได้จ่ายต้นทุนนั้นต่อ operation และให้รวม setup ไว้เมื่อมันเป็นส่วนหนึ่งของ hot path จริง

วัด pipeline แบบ end-to-end ที่เป็นตัวแทนได้ก่อน เพิ่ม component สำหรับวินิจฉัยเพื่ออธิบาย regression ไม่ใช่เพื่อทำให้ suite ใหญ่ขึ้น ตั้ง throughput เมื่อ byte, message, order หรือหน่วยอื่น ช่วยให้เห็นความสามารถในการปฏิบัติการชัดเจนขึ้น

เพิ่ม suite เฉพาะของ venue สำหรับ hot path ที่ยืนยันแล้ว เช่น การ sign, hashing, binary codec หรือ authentication โดย Lighter มี suite ด้าน cryptography ที่เจาะจง และ Derive มี suite สำหรับการ sign อย่า บังคับหมวดที่ adapter ไม่ได้ใช้ ตัวเลขการ sign ของ Lighter ที่บันทึกไว้และการเปรียบเทียบกับ Go ทางการอยู่ใน Lighter adapter benchmarks

ทำตามคู่มือ benchmarking ของ repository สำหรับการเลือกเครื่องมือ, baseline, การควบคุม noise และการรายงานผล และใช้ Criterion practitioner guide สำหรับโครงสร้าง benchmark และคำสั่งที่รันบนเครื่อง local

Fuzz testing

coverage-guided fuzzing เพิ่มความมั่นใจในจุดที่ byte หรือค่าใด ๆ จาก venue ข้ามขอบเขตความเชื่อถือ ให้จัดลำดับความสำคัญ:

  • การ decode raw WebSocket frame หรือ binary frame
  • การ normalize decimal, timestamp, symbol และ enum
  • signing payload และ canonical encoding
  • hash และ binary codec
  • การจัดสรร nonce หรือ sequence
  • parser และ encoder เฉพาะของ venue อื่น ๆ ที่รับ input ที่ไม่น่าเชื่อถือ

ใส่ seed ให้ corpus ของ parser และ decoder ด้วย payload ที่เป็นตัวแทนจาก test_data/ เมื่อช่วยเพิ่ม coverage ให้ harness อยู่ต่ำกว่าชั้น live network และ runtime เว้นแต่ target ต้องการ ขอบเขตเหล่านั้นโดยเฉพาะ

การไม่ panic เป็นเพียง baseline ให้ assert คุณสมบัติแบบ deterministic เช่น:

  • round trip ของ encode/decode
  • canonical encoding และ idempotence
  • ขอบเขตของความยาว, precision, ช่วงค่า และการ allocate
  • hash และ signature แบบ deterministic
  • model ของ nonce หรือ sequence แบบ monotonic
  • ความสอดคล้องกับ implementation ที่เป็นอิสระ
  • การปฏิเสธ input ที่ไม่ถูกต้องอย่างคงที่

ใช้ differential fuzzing เมื่อมี reference ที่เป็นอิสระเพียงพอ target การคูณ scalar ของ Lighter และ nonce model ของ Derive แสดงวิธีเปรียบเทียบ implementation โดยไม่ใส่ state ของ network ไว้ใน harness

การเชื่อมต่อแบบ canonical ของ adapter คือ:

Surfaceการเชื่อมต่อที่ต้องทำการบังคับใช้หรือการใช้งาน
Adapter [features]fuzz = ["nautilus-live/fuzz"]เปิดการรองรับ fuzz ร่วมโดยไม่เปลี่ยน build ปกติ
Adapter [package.metadata]cargo-fuzz = trueให้ cargo fuzz ถือว่า manifest ของ adapter เป็น fuzz package
Adapter [[bin]]หนึ่ง entry ต่อหนึ่ง target พร้อม feature fuzz และตั้ง test, doc และ bench เป็น falseลงทะเบียน binary ที่ค้นพบได้โดยไม่เพิ่มเข้าไปในการรัน test ปกติ
fuzz/fuzz_targets/target ที่เจาะจงซึ่งอยู่ต่ำกว่าชั้น live network และ runtimeให้ input ใด ๆ อยู่ที่ขอบเขตของ parser, codec, การ normalize หรือ model
scripts/fuzz-adapter.shการค้นหา target ของ adapter และการรันซ้ำแบบแบ่งช่วงเวลาใช้ binary ที่ลงทะเบียนไว้และรักษาตำแหน่งของ corpus และ artifact

adapter crate ต้องไม่พึ่งพา libfuzzer-sys โดยตรง Cargo conventions hook บังคับใช้เส้นทาง feature ร่วม ให้ใช้ Lighter fuzz README และ Derive fuzz README ที่เจาะจงสำหรับคำสั่ง setup, corpus, artifact และ target แทนการ คัดลอกทุกคำสั่งมาไว้ที่นี่

เอกสาร

สร้างหรืออัปเดต docs/integrations/<adapter>.md ให้มี:

  • ผลิตภัณฑ์, environment, data type, order type และ report ที่รองรับ
  • authentication และ environment variable
  • ตัวอย่าง config และการลงทะเบียน factory
  • ข้อจำกัดของ venue, พฤติกรรม reconciliation และช่องว่างที่ทราบ
  • ความแตกต่างของ testnet หรือ sandbox
  • ลิงก์ไปยังเอกสารโปรโตคอลของ venue ที่ implementation ใช้

ทำให้คำกล่าวอ้างเรื่อง capability ทดสอบได้ และระบุข้อยกเว้นที่ชอบธรรม ให้ลิงก์ไปยังคู่มือร่วมด้าน configuration, benchmarking และการทดสอบ แทนการคัดลอก policy ของคู่มือเหล่านั้น

ทำตามคู่มือเอกสาร และ คู่มือรูปแบบ Markdown ของ repository ให้เปลี่ยน input ของ generator แล้ว generate output ใหม่

อ้างอิงข้อกำหนดการทดสอบ

ใช้ข้อกำหนดร่วมเหล่านี้เพื่อวางแผนและรายงาน conformance ของ adapter:

แปลจาก เอกสาร NautilusTrader © Nautech Systems Pty Ltd และผู้ร่วมพัฒนา เผยแพร่ภายใต้ LGPL-3.0 ฉบับแปลนี้ตัดเนื้อหาเฉพาะ Python ออกและเน้น Rust

ในหน้านี้

บทนำConformanceพื้นฐานของ adapterRuntime และวงจรชีวิตของ clientExecution และ reconciliationTransport และ streamingBaseline ร่วมDeterministic simulationโครงสร้างของ adapterการเชื่อมต่อกับ repositoryลำดับการ implement adapterPhase 0: กำหนดขอบเขตPhase 1: สร้างแกนของโปรโตคอลPhase 2: Implement instrumentPhase 3: Implement market dataPhase 4: Implement executionPhase 5: เพิ่ม capability เสริมของ venuePhase 6: ทำ factory และ projection ให้ครบPhase 7: พิสูจน์ conformancePhase 8: วัดประสิทธิภาพและความทนทานPhase 9: ทำเอกสารและการปฏิบัติการให้เสร็จรูปแบบของ Rust adapterConfiguration (config.rs)Credential และการจัดการ secretจัดประเภทค่าที่อ่อนไหวใช้ secret type ร่วมใช้ SecretString อย่างปลอดภัยResolve และแชร์ credentialจำกัดอายุของ plaintextRedact diagnostic และ transport errorตรวจสอบการจัดการ credentialSymbol และ identity ของ instrumentการ model payload ของ venueNumeric precisionFallback ของ enum ของ venueแยก authority ออกจาก projectionClient trait และ factory (data.rs, execution.rs, factories.rs)การตั้งชื่อและลงทะเบียน clientInput ของ factory และความเป็นเจ้าของ cacheState ที่ adapter เป็นเจ้าของวงจรชีวิตของ connection (connect)การตั้งค่า sender ของ execution eventลำดับการ bootstrapData clientความเป็นเจ้าของการกู้คืน order bookการ sync ราย bookการเริ่มการกู้คืนState ของการกู้คืนและงบการ retryการยอมรับ snapshotกฎของ venue และการตัดสินใจร่วมอายุของ task และการ cancelการตั้งชื่อและการตั้งค่าExecution clientReconciliation reportMass status ตอน startupหลักฐานของ order ใน mass statusราคาเข้าเฉลี่ยใน position reportContract ของ timestamp ใน mass statusFilter ของ bulk reportProbe สำหรับ order เดียวการเปลี่ยนแปลง reconciliation ร่วมการจัดการเมื่อ commission ล้มเหลวการสร้าง report จาก RESTInferred fillการประมวลผล trade จาก WebSocketMass-status report แบบมีขอบเขตการ resolve instrument ระหว่าง reconciliationExecution update ที่ติดตามอยู่และจากภายนอกParent order และ child order ที่ถูก triggerUpdate ที่ไม่สมบูรณ์และที่มาช้าลำดับของ event และการตัดรายการซ้ำPolicy ของผลลัพธ์คำสั่ง orderการตั้งชื่อประเภทหลักฐานแยก diagnostic ออกจากเหตุผลที่แสดงต่อ strategyรูปแบบของ HTTP clientโครงสร้างของ clientลำดับการทำงานของ requestการ sign request และ authenticationการจัดการ error และ retry logicจัดประเภทความล้มเหลวชั่วคราวกั้นการ retry ด้วยความปลอดภัยของ operationรักษา identity และความกำกวมจัดการ backoff และการยุติทดสอบพฤติกรรมการ retryConformance ของ retry gateRate limitingรูปแบบของ WebSocket clientโครงสร้างของ clientHandshake ตอน initialize handler (SetClient)Authenticationการจัดการ subscriptionการ route messageReconnection และ shutdownความเป็นเจ้าของการ reconnectShutdownBackpressureการจัดการ taskการเก็บและการสังเกต taskSpawn ผ่าน task groupShut down และเปิด task generation ใหม่ห้ามใช้ block_on ใน trait methodGraceful shutdown ด้วย CancellationTokenการทดสอบการทดสอบ RustFixture และ assertion ของ parserการ synchronize ของ clientการทดสอบเชิงฟังก์ชันและ integrationAcceptance testingประสิทธิภาพและความทนทานCanonical benchmarkFuzz testingเอกสารอ้างอิงข้อกำหนดการทดสอบ