rinha2-back-end-dotnet

Operator documentation for a C#/.NET 9 Native AOT implementation of Rinha de Backend 2024/Q1. The system exposes the required fictional bank API behind NGINX, keeps transaction rules inside PostgreSQL stored procedures, and stays inside the 1.5 CPU / 550MB container budget.

Start here

Implementation profile

• Runtime: ASP.NET Core Minimal API targeting net9.0, compiled with Native AOT for the release image.
• Serialization: System.Text.Json source generation with snake_case output and no reflection-heavy runtime path.
• Database access: Npgsql 10.0.2 with a bounded pool and Multiplexing=true in the compose connection string.
• Consistency boundary: PostgreSQL stored procedures validate limits and apply transactions atomically.
• Topology: Two API containers behind NGINX least_conn, backed by one PostgreSQL container (postgres:16 in the development compose file).
• Observability: OpenTelemetry, Grafana LGTM, InfluxDB, and k6 dashboards are available in the development stack.

Proof points

Quick command

git clone https://github.com/jonathanperis/rinha2-back-end-dotnet.git
cd rinha2-back-end-dotnet
docker compose up nginx -d --build
curl http://localhost:9999/healthz

Links

• Repository
• Live Pages site
• Original Rinha specification

Challenge

Rinha de Backend 2024/Q1

Rinha de Backend is a Brazilian backend challenge focused on constrained, concurrent API design. The 2024/Q1 edition models a small fictional bank called Rinha Financeira. The workload stresses debit and credit transactions plus balance statements for five predefined clients.

Required endpoints

Validation rules

• Only client IDs 1 through 5 exist.
• Transaction type must be debit (d) or credit (c).
• Transaction value must be a positive integer amount in cents (valor > 0).
• Description must be present, non-empty, and at most 10 characters.
• Transaction type must be checked by the API before the request reaches PostgreSQL.
• Debits are intended not to push the account beyond the configured credit limit.
• Statement responses return the current balance plus the latest 10 transactions.

Resource envelope

The official workload is intentionally small but hostile to inefficient coordination. All counted runtime containers must fit inside:

The k6 runner and observability containers are test infrastructure. They are useful for local inspection, but they are not part of the counted API budget.

What makes the challenge hard

• Concurrent requests can target the same client at the same time.
• Balance updates and statement reads must stay consistent.
• The database budget is tight enough that careless connection pools or chatty queries can dominate latency.
• The API budget leaves little room for runtime warmup, reflection, or over-instrumented production paths.

Source

Full specification: github.com/zanfranceschi/rinha-de-backend-2024-q1

Current implementation compatibility note

Payload validation is split across the API and PostgreSQL:

• Program.cs rejects invalid client IDs, non-positive values, invalid transaction types, and missing/empty/long descriptions before calling the database.
• InsertTransacao in docker-entrypoint-initdb.d/rinha.dump.sql performs the atomic balance update and transaction insert.

One important edge case is worth calling out: when a debit would exceed the account limit, the current SQL function returns the existing balance without inserting a transaction. Because the route handler treats the returned balance as a successful result, this case can surface as 200 OK with an unchanged balance rather than the strict Rinha 422 behavior. Treat this as a known implementation note until the SQL/API contract is changed.

Architecture

Runtime topology

The production path follows the Rinha pattern: two API instances behind NGINX, one PostgreSQL database, and a separate load-test/observability lane for local and CI verification.

client / k6
  -> nginx:9999 (least_conn)
    -> webapi1-dotnet:8080
    -> webapi2-dotnet:8080
      -> PostgreSQL (stored procedures)

Counted services

Support services

API layer

The API project targets net9.0; its Dockerfile currently builds and runs it with Microsoft .NET 10.0 SDK/runtime images. The API is intentionally thin:

• CreateSlimBuilder trims default ASP.NET Core hosting overhead.
• Route handlers map directly to the required contest endpoints.
• JSON output uses JsonNamingPolicy.SnakeCaseLower and generated metadata from SourceGenerationContext.
• Client IDs and credit limits are kept in a small in-memory map for fast invalid-ID rejection.
• OpenTelemetry instrumentation is compiled out when ExtraOptimize=true defines EXTRAOPTIMIZE.

Database boundary

PostgreSQL owns the race-sensitive work. The API calls stored procedures for balance reads and transaction inserts instead of doing multi-step application-side coordination. Payload-shape validation remains API-side; the stored procedure should be read as the atomic consistency boundary, not as the only validation layer.

The compose command also tunes write durability for the contest setting:

checkpoint_timeout=600
max_wal_size=4096
synchronous_commit=0
fsync=0
full_page_writes=0

Connection strategy

The API uses one Npgsql data source per process and a bounded connection string:

Minimum Pool Size=10;Maximum Pool Size=10;Multiplexing=true;

That shape keeps database concurrency explicit, avoids unbounded connection growth, and lets Npgsql pipeline compatible work where possible.

Release profile

API and database contract

The NGINX config currently uses least_conn. If this repository is used as a strict official challenge submission, keep the config comments and docs aligned with whatever balancing policy is allowed by the target ruleset.

Getting Started

Prerequisites

• Docker with Docker Compose.
• Git.
• Optional: .NET 9 SDK if you want to build src/WebApi outside Docker. Docker builds use the repository Dockerfile’s .NET 10 SDK/runtime images while the project itself targets net9.0.

Clone and run

git clone https://github.com/jonathanperis/rinha2-back-end-dotnet.git
cd rinha2-back-end-dotnet
docker compose up nginx -d --build

The API is exposed through NGINX at:

http://localhost:9999

Smoke check

curl -i http://localhost:9999/healthz

A healthy stack returns HTTP/1.1 200 OK.

API endpoints

Example transaction

Credits use tipo: "c", debits use tipo: "d". Values are positive integer cents.

curl -X POST http://localhost:9999/clientes/1/transacoes \
  -H "Content-Type: application/json" \
  -d '{"valor": 1000, "tipo": "c", "descricao": "deposito"}'

The successful response returns the client ID, limit, and updated balance:

{
  "id": 1,
  "limite": 100000,
  "saldo": 1000
}

Invalid payloads return 422. Unknown client IDs return 404.

Example statement

curl http://localhost:9999/clientes/1/extrato

Example response:

{
  "saldo": {
    "total": 1000,
    "limite": 100000,
    "data_extrato": "2026-04-01T19:20:20.000000"
  },
  "ultimas_transacoes": [
    {
      "valor": 1000,
      "tipo": "c",
      "descricao": "deposito"
    }
  ]
}

For the full endpoint contract and the current over-limit debit behavior, see API Reference.

Run the load-test lane

The compose file includes the shared k6 runner and observability services. After the API stack is up, run:

docker compose up k6

By default, the k6 service runs with MODE=dev, exports data to InfluxDB, and exposes the k6 web dashboard on port 5665.

Useful local ports

Stop and clean up

docker compose down

Add -v only when you intentionally want to remove database and telemetry volumes:

docker compose down -v

API Reference

Base URL

Local and CI smoke tests reach the API through NGINX:

http://localhost:9999

The production compose file exposes the same public entrypoint on port 9999.

Client IDs and limits

The implementation has five predefined clients. The API keeps this small map in memory for fast invalid-client rejection, and PostgreSQL seeds the same limits in docker-entrypoint-initdb.d/rinha.dump.sql.

POST /clientes/{id}/transacoes

Submits a credit or debit transaction.

Request body

{
  "valor": 1000,
  "tipo": "c",
  "descricao": "deposito"
}

Successful response

The response uses snake_case JSON output generated by System.Text.Json source generation.

{
  "id": 1,
  "limite": 100000,
  "saldo": 1000
}

Status codes

Current implementation note

The intended Rinha contract treats a debit that would exceed the client’s limit as an unprocessable transaction. The current PostgreSQL function keeps the balance unchanged and returns the current balance when the limit update fails, so the API can return 200 with an unchanged balance for this case. If strict challenge behavior is required, adjust InsertTransacao/the route handler before documenting over-limit debits as guaranteed 422 responses.

GET /clientes/{id}/extrato

Returns the current account statement.

Successful response

{
  "saldo": {
    "total": 1000,
    "limite": 100000,
    "data_extrato": "2026-04-01T19:20:20.000000"
  },
  "ultimas_transacoes": [
    {
      "valor": 1000,
      "tipo": "c",
      "descricao": "deposito"
    }
  ]
}

The statement returns the latest 10 transactions ordered from newest to oldest.

Status codes

GET /healthz

Health check used by local smoke tests and GitHub Actions.

Responsibility split

Performance

Budget summary

The challenge allows 1.5 CPU and 550MB RAM across the counted runtime containers. This implementation uses the full CPU envelope deliberately, while keeping each component’s responsibility narrow.

Implementation choices that affect latency

Stress testing

Load tests run through the shared rinha2-back-end-k6 test suite. The runner drives transaction and statement requests through NGINX, so the measured path includes load balancing, both API containers, and PostgreSQL.

The homepage benchmark cards are intentionally treated as archived-run claims, not timeless guarantees. When updating numbers like 46k+ requests/second, <50ms p95 latency, or 99.9% success rate, tie the change to a concrete archived report and keep the report file in docs/public/reports/.

CI runners and local machines can vary. Prefer wording such as “archived run” or “representative run” unless the number comes from a repeatable benchmark protocol documented here.

docker compose up nginx -d --build
docker compose up k6

Local observability path

The development compose file keeps telemetry separate from the counted service budget:

Release validation

The Main Release workflow validates more than a build:

1. Restores and builds the WebApi project with AOT=true, TRIM=false, and EXTRA_OPTIMIZE=true.
2. Builds and pushes the amd64 image to GHCR.
3. Starts the production compose stack and checks /healthz.
4. Runs the load-test job and uploads the HTML stress-test report artifact.
5. Builds and pushes the arm64 image.
6. Merges the platform images into the latest manifest.

Report archive workflow

The release workflow uploads the HTML stress-test report as a GitHub Actions artifact. Reports that should be published on Pages are committed under docs/public/reports/; the Astro reports page indexes every .html file in that directory at build time. The reports index is an archive, not a parser, so summary metrics must be copied into docs/homepage copy deliberately.

Evidence links

CI/CD Pipeline

Workflow map

This repository uses GitHub Actions for PR validation, release image publishing, security analysis, and the public documentation deploy.

PR gate

Pull requests run the fast safety checks before merge:

1. Checkout the repository.
2. Install the .NET 9 SDK.
3. Restore src/WebApi/WebApi.csproj with release flags.
4. Build the WebApi project with AOT=true and EXTRA_OPTIMIZE=true.
5. Start the compose stack through NGINX.
6. Check http://localhost:9999/healthz.
7. Run CodeQL analysis.

Main release path

After a PR is rebased into main, the release workflow publishes the runtime image:

Published artifacts

Build/version matrix

The project targets net9.0 even when Docker build images are 10.0.

Documentation deploy

The Pages workflow delegates to Jonathan’s shared GitHub Pages workflow and uses Bun as the package manager. The docs package is an Astro 6.4 static site under docs/; Markdown content lives in docs/wiki/, and production routes are served under the /rinha2-back-end-dotnet base path.

The docs site uses Astro’s markdown.processor API with @astrojs/markdown-satteri. That keeps Markdown rendering explicit, but it also means future Remark/Rehype-style extensions should be tested against Sätteri before they are assumed to work.

Operational notes

• Use PR branches for this repository. The repo allows rebase merges and keeps main linear.
• Main releases are intentionally heavier than PR checks because they publish images and execute the load-test lane.
• Docs changes still trigger the main release workflow after merge, so report Pages status separately from image publishing when a change only affects documentation.