Serviço de matching de ordens de baixa latência, orientado a eventos, escrito em Rust.
Um livro de ofertas em memória com prioridade preço-tempo fica atrás de uma API gRPC. Cada execução vira evento no Kafka (Redpanda), e um segundo serviço consome esses eventos e os distribui em tempo real por WebSocket. Tudo roda com docker compose up, com métricas Prometheus e traces OpenTelemetry.
flowchart LR
C[clientes / loadgen] -- gRPC --> H
subgraph gw [gateway]
H[handlers gRPC] -- "mpsc (limitado)" --> M[matcher<br/>single writer]
M -- oneshot --> H
M -- broadcast --> S[StreamTrades]
M -- "mpsc (limitado)" --> P[publisher]
end
P -- "lotes" --> K[(Redpanda<br/>orderflow.events)]
subgraph md [market-data]
K --> Q[consumidor Kafka] -- broadcast --> W[WebSocket /ws]
end
W --> U[clientes WebSocket]
| Crate | Tipo | Papel |
|---|---|---|
crates/engine |
lib | Livro de ofertas puro, sem I/O: ordens limitadas e a mercado, cancelamento, execuções parciais. |
crates/proto |
lib | Contrato gRPC orderflow.v1 gerado com tonic-prost-build (protoc vendorizado). |
crates/events |
lib | Esquema JSON dos eventos e helpers de Kafka (conexão, criação de tópico, backoff). |
crates/telemetry |
lib | Logs JSON, exportação OTLP, recorder Prometheus, endpoints de operação e sinais. |
crates/gateway |
bin | API gRPC + task de matching + publisher Kafka. |
crates/market-data |
bin | Consumidor Kafka resiliente + fan-out por WebSocket. |
crates/loadgen |
bin | Gerador de carga gRPC com histograma HDR de latência. |
Um único escritor. Todos os livros de ofertas pertencem a uma única task Tokio. Os handlers gRPC nunca tocam no livro: montam um Command, enviam por um mpsc limitado e aguardam a resposta num oneshot.
- Sem locks no caminho quente. Não há
Mutex/RwLockem volta do livro; o motor é umstructcomum com&mut self. - Ordem determinística. A ordem de saída da fila é a sequência global da venue. Cada evento recebe um
sequencemonotônico. - Backpressure natural. A fila é limitada (
GATEWAY_QUEUE_CAPACITY). Se o matcher não acompanhar, os handlers esperam nosendem vez de acumular memória sem limite. - Lotes. O matcher drena até 256 comandos por wakeup (
recv_many), o que amortiza o custo de agendamento sob carga. - Trace ponta a ponta. O span do handler viaja junto com o comando, então o span
matchaparece dentro do tracePlaceOrdermesmo rodando em outra task. O tempo na fila (orderflow_matcher_queue_wait_seconds) é medido separado do tempo de matching (orderflow_match_duration_seconds).
Saída de eventos, fora do caminho quente:
broadcastpara os streams gRPCStreamTrades. Assinante lento recebeLaggede pula eventos; não trava ninguém.mpsclimitado para o publisher Kafka, que envia em lotes de até 1024 registros. Aqui a escolha é a oposta: backpressure em vez de perda. Se o broker ficar lento, a fila enche e o matcher espera. Lotes que falham são reenviados na mesma ordem (at-least-once).
Por que um escritor só e não um livro por thread? Um livro de ofertas é inerentemente sequencial: cada ordem depende do estado deixado pela anterior. Paralelizar o matching de um mesmo símbolo exigiria lock ou coordenação que custa mais do que o próprio matching (média de ~2,4 µs por comando dentro do matcher, medida abaixo). O caminho para escalar é particionar por símbolo (um escritor por grupo de símbolos), não compartilhar o livro.
Encerramento gracioso. Em SIGTERM/Ctrl+C um CancellationToken para os servidores gRPC e HTTP e encerra os streams abertos. Os handles do matcher são liberados, a fila é drenada, o publisher esvazia o que falta para o Kafka e só então o processo sai com código 0. Com o broker fora do ar, o publisher desiste em vez de prender o processo e loga quantos eventos ficaram sem envio.
- Preço em ticks (
i64) e quantidade em lotes (u64): nada de ponto flutuante. - Níveis de preço em
BTreeMap(bids pelo maior preço, asks pelo menor). - Ordens do mesmo nível formam uma lista duplamente encadeada intrusiva dentro de um
Slab, com índiceOrderId → slot. Consumir a cabeça da fila e cancelar do meio são O(1) depois de achar o nível (O(log n) no número de níveis). - A execução acontece sempre no preço do maker; ordens a mercado nunca ficam no livro (o saldo expira).
Testes de propriedade (proptest) geram sequências aleatórias de ordens limitadas, a mercado e cancelamentos e verificam, depois de cada comando:
- o livro nunca fica cruzado (
best_bid < best_ask); - conservação de quantidade:
enviado = 2 × negociado + em repouso + cancelado + expirado; - fills respeitam o limite do taker e consomem os melhores preços primeiro;
- o livro bate com um modelo de referência simples.
gRPC em :50051 (proto/orderflow/v1/orderflow.proto):
| RPC | Descrição |
|---|---|
PlaceOrder |
Ordem limitada ou a mercado. Retorna id, status (RESTING, FILLED, EXPIRED) e os fills. |
CancelOrder |
Cancela uma ordem em repouso. |
GetBook |
Profundidade agregada por nível (depth, padrão 10). |
StreamTrades |
Stream de trades do servidor, com filtro opcional por símbolo. |
Erros viram códigos gRPC: símbolo ou ordem inexistente → NOT_FOUND; quantidade ou preço inválidos → INVALID_ARGUMENT; servidor encerrando → UNAVAILABLE.
Eventos no tópico orderflow.events (JSON, chave = símbolo, uma partição para preservar a ordem global):
{"type":"trade","symbol":"BTC-USD","sequence":2,"maker_order_id":1,"taker_order_id":2,"taker_side":"buy","price":100,"quantity":2,"timestamp_ns":1790551197694587564}Tipos: trade, order_accepted, order_cancelled.
WebSocket do market-data: ws://localhost:18081/ws (tudo) ou ws://localhost:18081/ws?symbol=BTC-USD.
Pré-requisito: Docker com Compose v2.
docker compose up -d --build --wait # redpanda + gateway + market-data
curl localhost:18080/readyz # gateway
curl localhost:18081/readyz # market-data (pronto quando conectado ao Kafka)Enviando ordens com grpcurl:
grpcurl -plaintext -import-path proto -proto orderflow/v1/orderflow.proto \
-d '{"symbol":"BTC-USD","side":"SIDE_SELL","order_type":"ORDER_TYPE_LIMIT","price":100,"quantity":5}' \
localhost:50051 orderflow.v1.OrderGateway/PlaceOrder
grpcurl -plaintext -import-path proto -proto orderflow/v1/orderflow.proto \
-d '{"symbol":"BTC-USD","side":"SIDE_BUY","order_type":"ORDER_TYPE_MARKET","quantity":2}' \
localhost:50051 orderflow.v1.OrderGateway/PlaceOrderAcompanhando o fluxo:
websocat 'ws://localhost:18081/ws?symbol=BTC-USD'
docker compose exec redpanda rpk topic consume orderflow.eventsTeste de carga:
docker compose --profile tools run --rm loadgen --orders 100000 --concurrency 64Observabilidade (Jaeger em :16686, Prometheus em :19090):
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317 docker compose --profile observability up -d --waitTestes e lint dentro de container (usa o UID do host e guarda o cache em ./target/docker):
docker compose run --rm dev cargo test --workspace --locked
docker compose run --rm dev cargo clippy --workspace --all-targets -- -D warningsOu direto na máquina: cargo test --workspace e cargo bench -p orderflow-engine.
| Serviço | Porta | Variável para trocar |
|---|---|---|
| gateway gRPC | 50051 | GATEWAY_GRPC_PORT |
gateway HTTP (/healthz, /readyz, /metrics) |
18080 | GATEWAY_HTTP_PORT |
| market-data HTTP/WebSocket | 18081 | MARKET_DATA_PORT |
| Redpanda (Kafka externo) | 19092 | REDPANDA_KAFKA_PORT |
| Jaeger UI | 16686 | JAEGER_UI_PORT |
| Prometheus | 19090 | PROMETHEUS_PORT |
| Variável | Padrão | Serviço |
|---|---|---|
GATEWAY_GRPC_ADDR |
0.0.0.0:50051 |
gateway |
GATEWAY_HTTP_ADDR |
0.0.0.0:8080 |
gateway |
GATEWAY_SYMBOLS |
BTC-USD,ETH-USD |
gateway |
GATEWAY_QUEUE_CAPACITY |
65536 |
gateway |
GATEWAY_DEFAULT_DEPTH |
10 |
gateway |
GATEWAY_PUBLISHER_CAPACITY |
65536 |
gateway |
GATEWAY_PUBLISHER_BATCH |
1024 |
gateway |
MD_HTTP_ADDR |
0.0.0.0:8081 |
market-data |
MD_START_FROM |
latest (ou earliest) |
market-data |
MD_BUFFER |
4096 |
market-data |
KAFKA_BROKERS |
vazio (desliga o Kafka) | ambos |
KAFKA_TOPIC |
orderflow.events |
ambos |
OTEL_EXPORTER_OTLP_ENDPOINT |
vazio (desliga o OTLP) | ambos |
RUST_LOG |
info |
ambos |
- Reinício do broker: o offset fica em memória; se o fetch falhar, o consumidor derruba a conexão, faz backoff exponencial com jitter e retoma do mesmo offset. Validado com
docker compose restart redpandano meio do fluxo. - Retenção:
OffsetOutOfRangepula para o offset mais antigo disponível. - Duplicatas e lacunas: como o publisher é at-least-once, eventos com
sequencejá visto são descartados (md_duplicates_total) e lacunas são contadas (md_sequence_gaps_total). - Clientes lentos: o JSON é serializado uma vez e compartilhado via
Arc; o cliente que não acompanha pula eventos (md_ws_lagged_total) sem atrasar os demais.
Números medidos por mim, na minha máquina de desenvolvimento, com outros serviços rodando ao mesmo tempo. Servem como ordem de grandeza, não como benchmark controlado.
Máquina: Intel Core i7-10700 @ 2.90 GHz (8 núcleos / 16 threads, turbo até 4.8 GHz), 31 GiB de RAM, Linux 7.1.1, rustc 1.98.1, Docker 29.8.1.
cargo bench -p orderflow-engine| Benchmark | Tempo (estimativa central) | Observação |
|---|---|---|
submit/limit_resting |
132 ns | ordem que não cruza e entra no livro (~7,5 M ops/s) |
submit/limit_crossing_single_fill |
300 ns | executa contra um único maker, livro recém-criado a cada iteração |
submit/market_sweep_10_levels |
6,77 µs | ordem a mercado varrendo 10 níveis, 100 fills |
cancel_mid_queue |
261 ns | cancelamento no meio da fila de um nível |
mixed_flow/100k_orders |
8,16 ms | 100 mil ordens (90% limitadas, 10% a mercado): ~12,3 M ordens/s |
Stack completo no compose (Redpanda + gateway + market-data), com o loadgen rodando em outro container na mesma máquina. A latência é medida no cliente (ida e volta gRPC completa). Fluxo: 90% ordens limitadas em torno do preço médio, 10% a mercado, símbolo BTC-USD, 5.000 ordens de aquecimento fora da medição (2.000 no cenário com 1 cliente).
docker compose up -d --build --wait
docker compose --profile tools run --rm loadgen --orders 20000 --warmup 2000 --concurrency 1 --connections 1
docker compose --profile tools run --rm loadgen --orders 100000 --concurrency 64 # 3 execuções
docker compose --profile tools run --rm loadgen --orders 200000 --concurrency 256 --connections 8| Cenário | Throughput | p50 | p90 | p99 | p99.9 |
|---|---|---|---|---|---|
| 1 cliente, 1 conexão | 10.017 ordens/s | 96 µs | 119 µs | 149 µs | 223 µs |
| 64 em voo, 4 conexões (execução 1) | 103.951 ordens/s | 567 µs | 925 µs | 1,39 ms | 2,00 ms |
| 64 em voo, 4 conexões (execução 2) | 109.436 ordens/s | 539 µs | 871 µs | 1,33 ms | 1,80 ms |
| 64 em voo, 4 conexões (execução 3) | 107.014 ordens/s | 549 µs | 892 µs | 1,40 ms | 2,23 ms |
| 256 em voo, 8 conexões | 146.188 ordens/s | 1,67 ms | 2,48 ms | 3,43 ms | 4,30 ms |
Nenhum erro em nenhuma execução. Ao fim das rodadas acima (542.000 ordens no total, contando o aquecimento), as métricas mostravam:
- 985.953 eventos publicados no Kafka pelo gateway e os mesmos 985.953 consumidos pelo market-data, com
md_consumer_lag = 0; - tempo médio dentro do matcher de ~2,4 µs por comando (
orderflow_match_duration_seconds: soma de 1,318 s / 542.000), incluindo métricas, span e emissão de eventos; - tempo médio na fila antes do matcher de ~197 µs (
orderflow_matcher_queue_wait_seconds: soma de 106,65 s / 542.000). Ou seja, sob carga a latência é dominada por fila e rede, não pelo matching.
Uma correção que os números mostraram: a primeira rodada do loadgen tinha p50 abaixo de 1 ms, mas p99 perto de 41 ms, o padrão clássico de Nagle + delayed ACK. O gateway usa serve_with_incoming_shutdown com listener próprio e, nesse caminho, o tonic não aplica as opções de socket do builder. Ligar TCP_NODELAY em cada conexão aceita levou o p99 para ~2 ms e mais que dobrou o throughput (detalhes no PR #14).
GitHub Actions em cada PR: cargo fmt --check, clippy -D warnings, testes, compilação dos benchmarks, cargo-deny (advisories, licenças, fontes) e um job que builda as imagens, sobe o compose com --wait e faz smoke test nos endpoints de saúde.
- Estado só em memória: um restart perde o livro. O próximo passo seria um journal de comandos (ou snapshot + replay do tópico) para recuperação.
- Um escritor para todos os símbolos; escalar horizontalmente significa particionar símbolos entre instâncias e usar uma partição por símbolo.
- Sem autenticação, controle de risco ou self-trade prevention.
- O contexto de trace ainda não é propagado nos headers do Kafka até o market-data.
MIT — veja LICENSE.