How chawinkn/judge-ma-di works
Project type and purpose
• This is a backend-focused “Programming Judge System” (Judge Ma Di), written in Rust, exposing a REST API for submitting code, dispatching it to a sandbox (IOI Isolate), and returning judge results.
• It relies on Axum (HTTP), RabbitMQ (job queue), PostgreSQL (persistence), and the IOI Isolate tool for safe execution.
High-level file-structure analysis
• Top-level files and config:
• Dockerfile, docker-compose.yml, .env.example – define containerized environments (Axum server, RabbitMQ, Postgres, Isolate).
• config.json, setup.sh, checker.sh – sandbox and system setup scripts.
• test.py – a simple client to exercise API endpoints.
• src/: Application code organized into modules:
• main.rs – server bootstrap.
• rbmq.rs – RabbitMQ producer/consumer logic.
• isolate.rs & runner.rs – encapsulate sandbox invocation and job-processing loop.
• helper.rs – shared utilities.
• routes/ – HTTP route handlers (desc, healthchecker, manifest, submission, task).
Key README insights
• Core services: HTTP API, job queue, sandbox, database.
• Env var MAX_WORKER throttles concurrent runners.
• Docker Compose spawns Axum server, RabbitMQ, Postgres, optionally the isolate service.
Main components
a. HTTP API Layer (Axum server)
– Handles incoming requests on endpoints: /health, /desc, /submission, /manifest, /task.
– Reads/Writes to PostgreSQL and enqueues submission jobs to RabbitMQ.
b. Job Queue (RabbitMQ)
– Holds incoming code-judge tasks, decouples request handling from execution.
c. Runner & Sandbox (runner.rs + IOI Isolate)
– Worker process that consumes messages from RabbitMQ, runs submissions inside the Isolate sandbox via checker.sh, and pushes results back.
d. Persistence Layer (PostgreSQL)
– Stores submission metadata, statuses, results.
e. Configuration & Orchestration
– Docker Compose spins up all services; .env and config.json provide runtime parameters.
f. Optional Frontend / Client
– test.py or any UI consuming the JSON API to display results.
Relationships and data flow
1. Client → HTTP API (/submission)
2. API writes submission metadata to Postgres
3. API publishes a “new submission” message to RabbitMQ
4. Runner service subscribes to queue, receives job
5. Runner invokes IOI Isolate with code & test data (via isolate.rs + checker.sh)
6. Sandbox executes code, returns verdict and logs
7. Runner updates submission status and results in Postgres
8. Client polls API (/task or /manifest) to retrieve final status and details
Architectural patterns & design principles
• Separation of concerns: HTTP layer, queueing, execution, and persistence are distinct modules/services.
• Asynchronous, event-driven processing via RabbitMQ for scalability and reliability.
• Sandboxed execution isolating untrusted code.
• Configuration-driven deployment (Docker + .env + config.json).