How zhangjiayin/truefix works
1. Overall shape
- This is a Rust workspace for a FIX protocol engine, organized as a set of layered crates plus conformance/test assets.
- The main runtime path is: configuration → engine facade → transport/session orchestration → FIX codec/dictionary validation → storage/logging → application callbacks.
2. truefix facade
- The top-level truefix crate is the public entry point.
- It re-exports the main API surface, defines the Application trait and MessageCracker, and exposes Engine::start for one-shot startup from a .cfg file.
- This crate is the boundary that application code typically depends on.
3. Protocol core: truefix-core
- truefix-core contains the low-level FIX message model and wire codec: fields, field maps, repeating groups, messages, tags, framing, encode/decode, checksum/body-length handling, and typed protocol errors.
- It is the lowest protocol layer and does not know about session state, transport sockets, or persistence.
- All higher layers depend on it for parsing and rendering FIX messages.
4. Dictionary system: truefix-dict
- truefix-dict is the dictionary and codegen layer.
- It has a dual-track architecture: build-time generation of typed Rust messages/enums/groups, and runtime DataDictionary validation from the same normalized source.
- It also includes dictionary parsing, validation, FIX repository/Orchestra conversion, hashing, and a CLI used by both build.rs and users.
- This crate is the bridge between protocol syntax and typed domain models.
5. Session engine: truefix-session
- truefix-session implements the FIX session state machine and protocol behavior: logon/logout, heartbeat timing, sequence management, resend/gap-fill handling, schedule windows, reset semantics, and reverse-route behavior.
- It also defines admin/application behavior boundaries and typed callback outcomes used by Application.
- This is where session correctness lives; it consumes decoded messages and emits session actions/responses.
6. Transport layer: truefix-transport
- truefix-transport owns the network-facing initiator/acceptor machinery.
- It handles multi-session and dynamic sessions, reconnect/failover, socket options, TLS/mTLS via rustls, proxy support, PROXY protocol, synchronous write behavior, and bounded inbound backpressure.
- Its job is to move bytes to/from the session engine while enforcing network and connection policies.
7. Persistence layer: truefix-store
- truefix-store abstracts message/session persistence behind a MessageStore-style boundary.
- Backends include memory, file-based storage, cached file storage, SQL, MSSQL, Redb, MongoDB, and no-op.
- The store is used by session recovery/resend flows to survive restarts and reconstruct sequence state.
8. Logging layer: truefix-log
- truefix-log provides the logging side of engine observability and audit trails.
- It supports screen, file, tracing, composite logs, plus backend variants aligned with store technology choices such as SQL, MSSQL, Redb, and MongoDB.
- The log layer is separate from the store but follows the same persistence/backing pattern, so engines can pair a store backend with a log backend.
9. Configuration and wiring: truefix-config
- truefix-config parses .cfg files into SessionSettings, performs interpolation/resolution, and maps config keys to engine/session/store/log/transport behavior.
- This crate is the main wiring boundary between declarative deployment config and runtime objects.
- The README shows that Engine::start consumes these resolved settings to assemble the full engine without extra application code.
10. End-to-end data flow
- Inbound: socket bytes enter truefix-transport, are framed and decoded by truefix-core, validated/typed by truefix-dict, then processed by truefix-session, which consults store/log state and invokes Application callbacks when needed.
- Outbound: Application may produce or modify messages, truefix-session applies session rules and sequence handling, truefix-dict/truefix-core render them, truefix-transport sends them, and store/log capture the session state and audit trail.
- Recovery/resend paths loop through store access to replay prior messages and preserve session continuity.
11. Build-time vs runtime boundaries
- Dictionary code generation happens at build time and is backed by checked-in normalized source plus conversion tooling.
- Runtime dictionary validation is separate, but the two are intentionally kept in sync by sharing the same normalized input and hash checks.
- This split is important for the diagram: one path produces typed Rust artifacts, the other validates live FIX traffic.
12. Testing, conformance, and release gating
- truefix-at is the acceptance-test crate and acts as the release gate; it ports FIX conformance scenarios across multiple FIX versions.
- The workspace also contains extensive unit/integration tests per crate, benchmarks for core/session performance, and CI workflows that exercise formatting, linting, tests, service-backed storage, and dictionary tooling.
- For architecture diagrams, this is the quality-assurance boundary around the engine.
13. Examples and operational docs
- crates/truefix/examples/ contains runnable sample programs showing how the engine is embedded in real applications.
- The specs/ and docs/ directories are not runtime components, but they are important design artifacts: they define contracts, roadmaps, and parity goals that the codebase is built against.
Main entry points: src/lib.rs Session · src/lib.rs Dictionary · src/lib.rs Config · src/lib.rs Transport
Components 15
Runtime crates
Core engine layers that assemble, validate, move, and persist FIX traffic.
- truefix · Top-level API boundary and engine entry point for application code.
crates/truefix/src/lib.rs - Config · Parses deployment config and resolves runtime settings.
crates/truefix-config/src/lib.rs - Session · Implements FIX session behavior, sequencing, recovery, and callback boundaries.
crates/truefix-session/src/lib.rs - Transport · Initiator/acceptor network layer with reconnect, TLS, proxy, and backpressure policies.
crates/truefix-transport/src/lib.rs - Core codec · Low-level FIX message model, framing, and encode/decode primitives.
crates/truefix-core/src/lib.rs - Dictionary · Dictionary parsing, validation, hashing, and code generation from normalized FIX sources.
crates/truefix-dict/src/lib.rs - Store · Message and session persistence backends used for recovery and resend flows.
crates/truefix-store/src/lib.rs - Log · Observability and audit backends for screen, file, tracing, and durable sinks.
crates/truefix-log/src/lib.rs - Application · Application-facing trait boundary and message cracking hooks exposed by the facade.
crates/truefix/src/lib.rs - Codegen · Build-time typed artifact generation from the FIX dictionary source.
crates/truefix-dict/build.rs - Dict CLI · Command-line dictionary tool used by build scripts and users.
crates/truefix-dict/src/bin/truefix-dict.rs
Quality gate
Acceptance tests, examples, and design contracts that constrain the runtime.
- AT suite · Conformance and release-gating scenarios across FIX versions.
crates/truefix-at/src/lib.rs - Examples · Runnable embedding examples for operational usage patterns.
crates/truefix/examples/banzai.rs - Specs · Versioned architecture and parity contracts that define target behavior.
specs/001-fix-engine-parity/spec.md - Docs · Roadmap, parity notes, and audit artifacts that guide implementation.
docs/roadmap.md
Connections 24
- truefix → Config: loads settings · Facade startup begins by resolving config into runtime settings.
- truefix → Session: starts engine · Public engine entry wires settings into session orchestration.
- truefix → Application: exports API · Facade exposes the application callback boundary.
- Config → Transport: maps network · Configuration selects initiator/acceptor, TLS, proxy, and socket behavior.
- Config → Session: maps session · Configuration feeds session identity, schedules, and behavior switches.
- Config → Store: maps store · Configuration chooses persistence backend and recovery options.
- Config → Log: maps log · Configuration chooses audit/logging backend.
- Session → Core codec: uses codec · Session logic consumes decoded FIX messages and renders outbound ones.
- Session → Dictionary: validates typed · Session consults dictionaries for message, field, and admin validation.
- Session → Store: recovers state · Sequence recovery and resend flows read and write persisted session data.
- Session → Log: audits state · Session events and message activity are recorded to logging backends.
- Session → Application: invokes callbacks · Session hands application messages and callback outcomes to user code.
- Transport → Session: delivers bytes · Network I/O passes framed traffic into session processing and sends outbound bytes.
- Transport → Core codec: frames messages · Transport relies on core framing and codec for wire parsing/rendering.
- Transport → Dictionary: checks groups · Transport integrates dictionary-aware decoding and message validation.
- Dictionary → Core codec: builds protocol · Dictionary layer is built on top of the core FIX model and codec types.
- Codegen → Dictionary: generates types · Build script produces typed Rust artifacts from normalized dictionary sources.
- Dict CLI → Dictionary: parses source · CLI shares parsing, validation, and conversion paths with the dictionary crate.
- AT suite → Dictionary: gates parity · Acceptance scenarios verify dictionary coverage and typed/runtime consistency.
- AT suite → Session: gates session · Conformance tests exercise state machine and recovery behavior.
- AT suite → Transport: gates transport · Scenario coverage includes connection handling, TLS, failover, and backpressure.
- Examples → truefix: show usage · Examples demonstrate embedding the facade in applications.
- Specs → truefix: defines target · Architecture contracts define the intended engine surface and boundaries.
- Docs → AT suite: tracks parity · Docs capture roadmap, audits, and acceptance status for the engine.