CODESANDBOX

Important

UNIX system ONLY

---

⚙️ System Requirements

To run this project, make sure the following dependencies are installed and available in your system PATH:

Requirement	Description
Python 3.12+	Required for backend logic and Python-based modules
G++	Used for compiling and running C++ submissions
GCC	Used for compiling C submissions
JAVAC	Java compiler (for compiling .java files)
JAVA	Java runtime environment (for executing compiled Java code)

Important

📦 Install all required packages using your system package manager

For Debian/Ubuntu (APT):

sudo apt update && sudo apt install python3.12 g++ gcc openjdk-17-jdk -y

For Arch Linux / Manjaro (PACMAN):

sudo pacman -Syu python g++ gcc jdk-openjdk

📂 FOLDER STRUCTURE

CodeSandBox/
├── Module/
│   ├── __init__.py
│   ├── abstract.py
│   ├── cpp.py
│   ├── java.py
│   ├── python.py
│   └── register.py
├── Route/
│   ├── info.py
│   └── submit.py
├── models/
│   └── model.py
├── utils/
│   ├── data/
│   │   ├── enums.py
│   │   ├── problems.py
│   │   ├── random.py
│   │   ├── storage.py
│   │   └── sumissions.py
│   ├── logger/
│   │   └── logger.py
│   ├── safepy/
│   │   └── safeimport.py
│   ├── runGuard.py
│   └── tokencompare.py
│
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── .gitignore
├── checker.py
├── main.py
├── readme.md
└── requirements.txt

---

🐳 Docker Setup

This project includes a fully configured Dockerfile and an optional Docker Compose setup for easy deployment and scaling.

---

⚙️ Dockerfile Overview

Base image: ubuntu:24.04 Default user: lhuser Working directory: /app Exposed port: 8000 Startup command: python3 main.py

The Dockerfile installs and configures everything needed for code execution and judging:

• gcc, g++ → for compiling C/C++
• openjdk-21-jdk, openjdk-21-jre-headless → for Java
• python3-full, python3-pip, python3-venv → for Python
• curl, git, ca-certificates → basic utilities

Environment Variables:

Variable	Description
JAVA_HOME	Path to Java installation
PATH	Includes both Java and Python virtual env paths

---

🧱 Docker Compose

A docker-compose.yml file can be used to easily run or scale the judge service.

version: "3.9"

services:
  judge:
    build: .
    container_name: problem_judge
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
      - PATH=/usr/lib/jvm/java-21-openjdk-amd64/bin:/app/.venv/bin:$PATH
    volumes:
      - .:/app
    command: ["python3", "main.py"]

---

🚀 How to Use

# Build Docker image
docker build -t problem-judge .

# Run container
docker run -d -p 8000:8000 problem-judge

Or with Docker Compose 👇

# Build and start
docker compose up -d

# View logs
docker compose logs -f

# Stop everything
docker compose down

---

⚡ Scaling Example

Wanna simulate multiple judge nodes? Just scale it up:

docker compose up --scale judge=5 -d

---

🧩 Problem API Endpoints

1️⃣ POST /problem/submit_problem_local

Submit a solution for automatic judging (local problem only).

🧾 Form Data

Field	Type	Required	Description
id	string	✅	The submission ID
problem_id	string	✅	The problem ID
module	string	✅	Programming language used (e.g. python3, c++17, java17, etc.)
file	file	✅	The source file to be submitted

---

1️⃣.5️⃣ POST /problem/submit_problem

Submit a solution with your testcases included in the formdata.

🧾 Form Data

Field	Type	Required	Description
id	string	✅	The submission ID
data_test	string	✅	The test data for the jugde (see #testcase)
module	string	✅	Programming language used (e.g. python3, c++17, java17, etc.)
file	file	✅	The source file to be submitted
time_limit_sec	int	✅	The time limit for the problem
memory_limit_mb	int	✅	The memory limit for the problem

Testcase payload (/submit_problem only)

Basic

{
  "testcases": [
    {
      "input": "hello world",
      "output": "hello world"
    },
    {
      "input": "fastapi is cool",
      "output": "fastapi is cool"
    }
  ]
}

More advanced

{
  "testcases": [
    {
      "input": "Line1\nLine2\nLine3",
      "output": "Line1\nLine2\nLine3"
    },
    {
      "input": "    leading and trailing spaces    ",
      "output": "    leading and trailing spaces    "
    },
    {
      "input": "Tabs\tand\tmultiple\tspaces",
      "output": "Tabs\tand\tmultiple\tspaces"
    },
    {
      "input": "🔥💀🥀🚀🌌", 
      "output": "🔥💀🥀🚀🌌"
    },
    {
      "input": "Escaped\\nnewline\\tand tab",
      "output": "Escaped\\nnewline\\tand tab"
    },
    {
      "input": "",
      "output": ""
    }
  ]
}

📤 Response Examples

✅ Accepted (AC)

{
  "id": "75ffb5d0-0e9b-47a6-930b-af7922adbd73",
  "problem_name": "donghoso",
  "module_used": "python3",
  "status": "Accepted",
  "message": "All testcases passed",
  "running_time": 0.1576685905456543,
  "usage_memory": 34.8828125
}

❌ Wrong Answer (WA)

{
  "id": "75ffb5d0-0e9b-47a6-930b-af7922adbd73",
  "problem_name": "donghoso",
  "module_used": "python3",
  "status": "WrongAnswer",
  "message": "Expected: 7111111111111111111111111111111111111111111111111, GOT: 71111111111111111111111111111111111111111111111111\n, STDIN: 101 | WrongAnswer on test case 6",
  "running_time": 0.1573479175567627,
  "usage_memory": 34.84375
}

💀 Runtime Error (RE)

{
  "id": "75ffb5d0-0e9b-47a6-930b-af7922adbd73",
  "problem_name": "donghoso",
  "module_used": "python3",
  "status": "RUNTIME_ERROR",
  "message": "RUNTIME_ERROR on test case 1",
  "running_time": 0,
  "usage_memory": 0
}

🧠 Memory Limit Exceeded (MLE)

{
  "id": "75ffb5d0-0e9b-47a6-930b-af7922adbd73",
  "problem_name": "print_helloworld",
  "module_used": "python3",
  "status": "MEMORY_LIMIT_EXCEEDED",
  "message": "MEMORY_LIMIT_EXCEEDED on test case 1",
  "running_time": 0,
  "usage_memory": 0
}

⏰ Time Limit Exceeded (TLE)

{
  "id": "75ffb5d0-0e9b-47a6-930b-af7922adbd73",
  "problem_name": "print_helloworld",
  "module_used": "python3",
  "status": "TIME_LIMIT_EXCEEDED",
  "message": "TIME_LIMIT_EXCEEDED on test case 1",
  "running_time": 0,
  "usage_memory": 0
}

🧩 Compile Error

{
  "id": "75ffb5d0-0e9b-47a6-930b-af7922adbd73",
  "problem_name": "print_helloworld",
  "module_used": "c++17",
  "status": "COMPILE_ERROR",
  "message": "Compilation command exit with non-zero status",
  "running_time": 0,
  "usage_memory": 0
}

❌ Denied submission

{
    "id": "75ffb5d0-0e9b-47a6-930b-af7922adbd73",
    "problem_name": "donghoso",
    "module_used": "python3",
    "status": "DENIED_SUBMISSION",
    "message": "Traceback (most recent call last):\n  File \"/mnt/d/Code/CodeSandBox/run/1e4d03ad-19fa-4884-90ad-6509053c5f69/main.py\", line 3, in <module>\n  File \"/mnt/d/Code/CodeSandBox/run/1e4d03ad-19fa-4884-90ad-6509053c5f69/safeimport.py\", line 12, in safe_import\nImportError: Import of 'pathlib' not allowed\n| DENIED_SUBMISSION on test case 1",
    "running_time": 0,
    "usage_memory": 0
}

---

2️⃣ GET /problem/status

Get the current node status (to check if it’s busy or free).

📤 Response

{
  "status": "IDLE",       // or "BUSY"
  "available_slot": 16,   // number of submissions that can run concurrently
  "max_concurrency": 16   // maximum concurrency supported
}

---

3️⃣ GET /api/info/problems

Return a list of available problems on this node.

📤 Response

[
  "print_helloworld",
  "print_input"
]

---

4️⃣ GET /api/info/languages

Return a list of supported programming languages.

📤 Response

[
  "python3",
  "c++98",
  "c++11",
  "c++17",
  "c++",
  "java8",
  "java11",
  "java17",
  "java21",
  "java"
]