Skip to content

Latest commit

 

History

History
239 lines (190 loc) · 12.6 KB

API.md

File metadata and controls

239 lines (190 loc) · 12.6 KB

FIG API & Documentation Index

Crate and module map. For a user reading order (SUBSCRIBE vs REQUEST, bindings caveats), start at README.md in this folder.

Project documentation

Document Description
README.md Docs map — start here
TUTORIAL.md Step-by-step getting started
PROTOCOL.md Design rationale, channel directions, migration
STREAMING.md Live SUBSCRIBE paths and gateway WS mapping
QUERY.md Historical REQUEST/RESPONSE paths and REST GET mapping
GATEWAY.md Legacy FIX/REST/WebSocket/OUCH/ITCH gateway deployment
SECURITY_AUDIT.md Security checklist (1.0 sign-off recorded)
TODO.md §18 1.0 release criteria · §0 backlog
DEPLOYMENT.md HA deployment and operations
PUBLISHING.md Build and install SDKs
COMPATIBILITY.md SPEC vs crate vs git tag; fig.h contract
BENCHMARKS.md msgs/sec, tail latency, Criterion methodology
adr/README.md Architecture decision records
adr/0004-fsl-single-source-of-truth.md FSL schema evolution & multi-language codegen
adr/0006-broker-api-parity.md Native FIG first; broker API parity policy
adr/0008-named-gateway-adapters.md FIX/REST/WS/OUCH/ITCH as named adapters
adr/0009-market-data-plane.md TREE L2 native; ITCH is L2 egress
adr/0010-batch-request.md Atomic multi-action REQUEST
../SPEC.md Normative wire format specification
../TODO.md Implementation roadmap

Generate Rust API docs:

cargo doc --workspace --no-deps --open

fig-core — protocol engine

Module Purpose
frame 16-byte header encode/decode, streaming FrameDecoder
ext TLV extension tags (29 tags)
channel Channel lifecycle, sequence numbers, per-channel send credits
session Session model; MemorySessionStore, FileSessionStore, optional RedisSessionStore (session-redis feature)
transport TREE transport, FigConnection, 0-RTT, migration, replay cache
tcp TCP downgrade mode (FIG\x01 magic prefix)
migration Connection migration tokens and channel reconstruction
codec CBOR helpers; JSON ↔ CBOR for gateways
constraints decimal64 scale/bounds and constrained-string checks used by generated codecs
replay 0-RTT resumption token replay cache
sbe SBE encoder/decoder (encode / encode_into)
compression zstd payload compression
fragment Payload fragmentation and reassembly
control CONTROL frame dispatcher (PING, AUTH_REFRESH, SEQ_RESET, …)
auth Wire auth: token/mTLS types, constant-time verify, refresh hooks — not credential issuance
jwt JWT bearer decode/verify (HS256 for tests/conformance)
jwt_keys RS256 verification from a JWKS/PEM key set, kid rotation, KMS adapter
session_token Server-signed (HMAC-SHA256) session resumption tokens
replay Replay window: per-process or shared Redis cache
oauth OAuth2/OIDC dev introspection stub (venues wire real IdP)
channel_auth Per-channel permission policy
rate_limit Token-bucket rate limiter
dos Connection-level DoS guard and flood detector
trace W3C traceparent ↔ TRACE_ID extension
observability Tracing spans, metrics, Prometheus export
messages Trading message types; channel_path constants for §17 paths
error FrameError, ChannelError, SessionError, FigError

Binaries

Binary Command Purpose
fig-observability cargo run -p fig-core --features observability-bin --bin fig-observability Prometheus /metrics on :9090

fig-gateways — legacy adapters

Module Purpose
fix FIX 4.4 parse/serialize, FIG message conversion
fix_session FIX session state machine (logon, heartbeat, resend)
rest HTTP/1.1 parse/serialize, JSON ↔ CBOR
rest_query REST GET → native FIG REQUEST (candles, fills, funding, …)
ws WebSocket RFC 6455 frame mapping
ws_catalog Legacy WS topic → native FIG SUBSCRIBE (Binance/HL reference aliases)
ws_listener HTTP upgrade handler for fig-gateway WS listener
backend proxy_frame (REQUEST/EOF), BackendSession (live SUBSCRIBE)
sse Server-Sent Events ↔ STREAM_ITEM
soupbin SoupBinTCP session framing for OUCH/ITCH
ouch FIG OUCH 4.2-shaped order entry (--ouch-addr)
itch ITCH L2 price-level egress (SoupBin + MoldUDP64)

Binaries

Binary Command Purpose
fig-gateway FIG_TLS_CA=.fig/dev-ca.pem cargo run -p fig-gateways --bin fig-gateway -- --fig-backend 127.0.0.1:8443 REST :8080, WS :8090, FIX :9876; OUCH/ITCH opt-in

E2E alias round-trip: cargo test -p fig-gateways --test gateway_legacy_ws_alias_e2e (Binance / Hyperliquid / FIX / REST fixture tables in one test file). OUCH/ITCH: cargo test -p fig-gateways --test gateway_ouch_itch_e2e.


fig-fsl — schema language

Module Purpose
parser FSL tokenizer and recursive-descent parser
ast Schema AST (messages, types, gateway mappings)
codegen Rust struct codegen
sbe_codegen SBE Rust encode/decode codegen
target_codegen Go, Python, TS, OCaml, Zig, C++, C#, Proto, SBE XML, JSON Schema, FIX YAML

CLI (ftlc)

cargo run -p fig-fsl --bin ftlc -- compile schemas/orders.fsl --lang go --out /tmp/out
cargo run -p fig-fsl --bin ftlc -- validate schemas/orders.fsl

Supported --lang values: rust, sbe, sbe-go, sbe-cpp, sbe-csharp, sbe-typescript (sbe-ts), sbe-zig, go, proto, sbe-xml, cpp, csharp, python, typescript, ocaml, zig, java, json-schema, fix-yaml, protocol-cpp, protocol-zig.


fig-exchange-sim — reference server

Module Purpose
server FIG server: FigServer::accept_0rtt, held-open subscribe fan-out
broker_api §17 query/subscribe routing and post-fill fan-out
market_data Candles, trades, BBO, ticker aggregation
account_state Balances, positions, funding, ledger
auth Simulator test harness: fig-dev-{account} path scoping (not production issuance)
market_state Session status, security status, price collars
md_rate Public MD rate limits by tier (SPEC §9.3)
matching Price-time matching engine
orderbook Limit order book

Default listen address: 127.0.0.1:8443 (UDP/TREE).


fig-cli — demo client

Native FIG client connecting to 127.0.0.1:8443 by default. Uses FigSdkClient for seven validated demo flows plus an SBE order demo. Attaches simulator test token fig-dev-DEMO-ACCT on private paths (see SPEC §9.3 wire semantics; not a key-issuance API).

fig-client — SDK merge helpers

Module State type Streams
order_book OrderBookState book snapshot/delta
candles CandleState candle bars
account AccountCache balances, positions, margin
agg_trades AggTradeState aggregate trades
funding FundingState funding payments
ledger LedgerState ledger updates
liquidations LiquidationState user + public liquidations
client FigSdkClient, LiveSubscription request() / request_* (EOF); subscribe_* / subscribe_live (held open)

fig-ffi — C ABI

Live subscribe: fig_client_subscribe, fig_client_sub_next, fig_client_sub_close (header: fig.h). REQUEST uses fig_client_request_and_recv (waits for EOF). Two-connection proof: cargo test -p fig-ffi --test client_integration.

fig-python — reference binding

PyO3 module fig (build with maturin develop -m crates/fig-python/Cargo.toml).

import fig
fig.version()                       # crate version

c = fig.FigPyClient()
c.connect("127.0.0.1:8443")         # TLS verified by default: set FIG_TLS_CA

c.request(".well-known/capabilities", "GET")   # -> list[bytes] of encoded response frames
c.subscribe("accounts/A/balances", "accounts/A/balances", "fig-dev-A", 1, 1)  # -> list[bytes] snapshot

sub = c.subscribe_live("accounts/A/balances", "accounts/A/balances", "fig-dev-A", 2, 1)
sub.snapshot                      # property -> list[bytes] of the snapshot frames
try:
    frame = sub.next(500)         # bytes; None on EOF; raises on timeout
except RuntimeError as e:         # RuntimeError("timeout") when nothing arrived
    frame = None
sub.close()
c.ping()

token = fig.jwt_encode("alice", 4_000_000_000, "fig-smoke-secret")
fig.jwt_decode_sub(token, "fig-smoke-secret")   # "alice"
fig.jwt_verify_bearer(token, "fig-smoke-secret")

c.request_session_status()
c.request_security_status("AAPL")
c.mass_cancel("MC-001", "DEMO", symbol="AAPL", side="buy")
c.post_batch("DEMO", batch_request_cbor)        # -> bytes, a CBOR BatchReport

candle = fig.PyCandleState()
candle.apply_bytes(candle_bar_event_cbor)
candle.close_price()                            # None until a bar is applied
candle.is_final()

request and subscribe return lists of encoded frames (decode with fig.frame_decode_header). subscribe_live returns a subscription whose snapshot is a property, not a method. Requests are REQUEST-mode; use subscribe_live (not request) for streams that keep pushing.


fig-bench — benchmarks

Three layers: Criterion mean time, HDR tail latency, wall-clock msgs/sec.

Suite Role
frame_bench, codec_bench, gateway_bench, matching_bench, transport_bench, alloc_bench Criterion mean/median + elems/s regression
fig-latency, latency_bench HDR Histogram p50 / p99 / p99.9 per operation
fig-throughput Sustained msgs/sec over FIG_THROUGHPUT_SECS
fig-load Encode/decode flood smoke (CI), not for citing rates
cargo bench -p fig-bench
cargo bench -p fig-bench --features alloc --bench alloc_bench
cargo run --release -p fig-bench --bin fig-latency
FIG_LATENCY_ITERS=1000 cargo run --release -p fig-bench --bin fig-latency
cargo run --release -p fig-bench --bin fig-throughput
FIG_THROUGHPUT_SECS=1 cargo run --release -p fig-bench --bin fig-throughput

See BENCHMARKS.md for methodology and reference numbers.