Home

The promoted default is the x86-64 assembly load balancer. It is the shared YOLO-mode transport layer for Jonathan Peris’ Rinha de Backend 2026 entries, with a C baseline kept in the same repo for controlled C-vs-ASM comparisons.

Downstream stacks

• rinha4-back-end-dotnet: .NET 10 NativeAOT backend using raw HTTP over Unix sockets behind proxy mode.
• rinha4-back-end-c: C fraud-scoring backend, usually benchmarked behind either the C baseline LB or the promoted ASM LB.
• rinha4-yolo-mode: pure x86-64 assembly backend, used as the assembly lane for proving the shared ASM LB.
• FD-passing backend lanes: APIs that receive accepted client FDs through Unix control sockets.

Image contract

ghcr.io/jonathanperis/rinha4-lb-yolo-mode:latest        # promoted ASM LB
ghcr.io/jonathanperis/rinha4-lb-yolo-mode:vX.Y.Z        # release tag, promoted ASM LB
ghcr.io/jonathanperis/rinha4-lb-yolo-mode:asm-ci-<sha>  # commit-specific ASM LB
ghcr.io/jonathanperis/rinha4-lb-yolo-mode:c-ci-<sha>    # commit-specific C baseline LB
ghcr.io/jonathanperis/rinha4-lb-yolo-mode:c-latest      # moving C baseline pointer

latest and release tags mean ASM. Use immutable asm-ci-<sha> or c-ci-<sha> tags for comparison runs so CI-vs-CI evidence does not mix moving pointers.

The comparison lane still matters. Future default changes should keep C-vs-ASM runs clean, repeated, and separated from official runner evidence.

Challenge

Rinha de Backend rewards correctness first and latency second. A faster LB is only useful if it preserves the official contract under repeated, official-like runs.

The shared YOLO load balancer now defaults to the x86-64 assembly implementation. Can it stay the default across the downstream stacks without correctness or p99 regressions?

The comparison harness exists to answer that by testing:

• the promoted ASM image under pinned tags;
• proxy mode for raw Unix-socket HTTP APIs;
• fdpass mode for accepted-socket APIs;
• repeated runs to smooth noisy GitHub-hosted runners;
• official-vs-official results separately from CI-vs-CI runs.

Correctness failures close the result immediately. p99 only matters after false positives, false negatives, HTTP errors, and readiness checks are clean.

Architecture

The repository builds two load-balancer implementations from one source tree. The default runtime image is ASM; the C binary is retained as a baseline and troubleshooting fallback.

Both binaries expose the same two external runtime shapes.

Proxy mode

k6 / judge
    |
    v
rinha4-lb-yolo-mode :9999
    |  TCP acceptor to Unix stream proxy
    +-- unix:/sockets/api1.sock -> raw HTTP API
    +-- unix:/sockets/api2.sock -> raw HTTP API

Use this for raw HTTP backends such as the .NET implementation. The promoted ASM proxy path accepts TCP clients, connects to one configured Unix stream upstream, forwards request/response bytes without parsing the fraud payload, and closes the client after the exchange.

FD-passing mode

k6 / judge
    |
    v
rinha4-lb-yolo-mode :9999
    |  SCM_RIGHTS accepted-fd handoff
    +-- unix:/run/rinha/api1.sock -> API receives accepted client fd
    +-- unix:/run/rinha/api2.sock -> API receives accepted client fd

Use this for APIs built around inherited accepted sockets.

The fdpass control socket type is explicit:

• LB_FDPASS_SOCKET_TYPE=seqpacket for datagram-preserving control sockets;
• LB_FDPASS_SOCKET_TYPE=stream for stream control sockets.

The ASM implementation accepts client sockets in blocking mode for fdpass so simple backend read() paths do not immediately see EAGAIN. Proxy mode uses a compact blocking syscall loop in ASM; the C baseline uses epoll/nonblocking forwarding.

Design constraints

The default ASM LB is intentionally narrow:

• exactly two upstream workers, matching the Rinha4 topology and enforced by the ASM validation path;
• no fraud payload parsing;
• no request-level logging;
• fixed minimal syscall path;
• environment parsing only for the contract knobs needed by the stacks.

The C baseline supports up to 16 upstream paths and broader mode aliases, but it is not the promoted image.

Contracts

Environment

Compatibility notes:

• The promoted ASM binary reads LB_MODE, PORT, BACKLOG, UPSTREAMS, and LB_FDPASS_SOCKET_TYPE directly from its environment.
• The C baseline accepts MODE as a fallback when LB_MODE is unset, and also accepts uds-proxy/unix-proxy for proxy mode.
• The ASM binary intentionally requires exactly two upstream paths. The C baseline supports up to 16 upstreams.

Image contract

Proxy-mode contract

• Listen on TCP PORT.
• Connect each accepted client to one configured Unix stream upstream.
• Forward bytes without parsing fraud payloads.
• Avoid per-request logging in the hot path.
• Keep the runtime compatible with raw HTTP backends.

FD-passing contract

• Maintain persistent Unix control sockets to API workers.
• Accept TCP clients on PORT.
• Send accepted client FDs with SCM_RIGHTS.
• Close the LB copy after handoff.
• Do not inspect or mutate request payloads.
• Match the worker socket type with LB_FDPASS_SOCKET_TYPE.

Stack-specific socket type

Correctness comes before p99. If any participant reports false positives, false negatives, HTTP errors, or readiness failures, reject that comparison result before reading latency.

Getting Started

Build and test locally

make clean test

The test target builds the C and ASM load balancers, then runs local integration checks against dummy Unix-socket backends.

make clean all            # default ASM binary: build/rinha4-lb-yolo-mode
make asm                  # build/rinha4-lb-yolo-mode-asm
make c                    # build/rinha4-lb-yolo-mode-c

Use the promoted ASM image

services:
  lb:
    image: ghcr.io/jonathanperis/rinha4-lb-yolo-mode:latest
    platform: linux/amd64
    environment:
      LB_MODE: proxy
      PORT: "9999"
      UPSTREAMS: /sockets/api1.sock,/sockets/api2.sock
    ports:
      - "9999:9999"

latest is ASM. For a pinned rollout, prefer asm-ci-<sha> or a release tag.

Use the C baseline image

services:
  lb:
    image: ghcr.io/jonathanperis/rinha4-lb-yolo-mode:c-ci-<sha>
    platform: linux/amd64
    environment:
      LB_MODE: proxy
      PORT: "9999"
      UPSTREAMS: /sockets/api1.sock,/sockets/api2.sock
    ports:
      - "9999:9999"

Use the C image only for comparison and fallback experiments. c-latest exists, but repeatable benchmark runs should pin c-ci-<sha>.

Use fdpass mode

services:
  lb:
    image: ghcr.io/jonathanperis/rinha4-lb-yolo-mode:latest
    platform: linux/amd64
    environment:
      LB_MODE: fdpass
      LB_FDPASS_SOCKET_TYPE: seqpacket
      PORT: "9999"
      UPSTREAMS: /run/rinha/api1.sock,/run/rinha/api2.sock
    ports:
      - "9999:9999"

For stream fdpass backends, switch only the socket contract:

environment:
  LB_MODE: fdpass
  LB_FDPASS_SOCKET_TYPE: stream
  UPSTREAMS: /run/rinha/api1.sock,/run/rinha/api2.sock

Build the image locally

docker build --build-arg LB_IMPL=asm -t rinha4-lb-yolo-mode:asm .
docker build --build-arg LB_IMPL=c   -t rinha4-lb-yolo-mode:c .

Docker access is required for image builds. The repository integration tests do not require Docker.

Performance Notes

The ASM LB is promoted because it should reduce transport overhead without changing the backend contract. The C implementation remains published so each claim can be checked against a pinned same-commit baseline.

Promotion gates

1. zero correctness regressions and zero unexpected HTTP errors;
2. equal or lower p99 latency across downstream stacks;
3. stable behavior across repeated workflow runs;
4. no hidden socket-contract changes in compose files;
5. same-lane image tags: compare asm-ci-<sha> against c-ci-<sha> for the same commit whenever possible.

What to watch

• LB_MODE=proxy should not parse payloads or add per-request logs.
• LB_MODE=fdpass should close the LB-owned accepted FD after handoff.
• LB_FDPASS_SOCKET_TYPE must match the backend control socket.
• GitHub-hosted runners are noisy, so one lucky p99 should not decide a promotion.
• latest, c-latest, and release tags are moving or semver pointers; pin immutable tags for evidence.

Tag discipline

latest and release tags are ASM. Benchmark runs that need repeatability should pin asm-ci-<sha> for the promoted implementation and c-ci-<sha> for the C baseline instead of relying on a moving pointer.

Comparison Lane

The comparison workflow benchmarks the promoted ASM LB against the C baseline across the Rinha4 implementation families.

The main workflow’s matrix writes participant artifacts and then summarizes them into comparison-results/latest.json. The Pages workflow copies that file into docs/public/comparison/latest.json when it exists so the site can render the latest table.

Branch shape

The comparison branch should stay a lean benchmark harness. It normally tracks only:

• .github/workflows/benchmark.yml;
• LICENSE;
• competitor-compose/**;
• comparison-results/**.

Do not merge main wholesale into comparison just to refresh the harness. Copy or cherry-pick only the workflow, compose files, and archived results that belong to the benchmark lane.

Evidence rules

• Pin image tags for every participant.
• Use asm-ci-<sha> for ASM lanes and c-ci-<sha> for C baseline lanes; prefer matching SHAs when the comparison is meant to isolate implementation differences.
• Keep latest and c-latest out of comparisons unless the test is explicitly about the current moving pointer.
• Record whether the fdpass socket contract is seqpacket or stream.
• Keep CI-vs-CI and official-vs-official conclusions separate.
• Reject correctness failures before evaluating p99.