Hcode Online Judge (HOJ) Documentation

Hcode Online Judge (HOJ) is a distributed, microservices-based online judging system built using a decoupled frontend and backend architecture. It is designed to support both ACM and OI style programming contests and training.

Core Features

• Scalability: Distributed judging architecture.
• Security: Uses cgroup to isolate user programs during judging, preventing resource exhaustion.
• Versatility: Supports ACM and OI problem types, including special features like testlib evaluation, interactive judging, and subtask judging.
• Content Sourcing: Supports local problem data and can crawl problems from popular OJs like HDU, Codeforces, GYM, POJ, AtCoder, SPOJ, and Libre.
• Social & Training: Includes discussion forums (problem, contest, and public), an internal messaging system, private/public training sets, and various team types (private, public, protected).
• UI/UX: Responsive design supporting mobile devices and full internationalization (Chinese/English).

Hcode Online Judge (HOJ) is a distributed, decoupled system designed for online programming contests and training. It uses a microservices architecture where the frontend and backend are separated, and services are orchestrated using Docker and Docker-Compose on Ubuntu systems.

Core Components

Frontend

• Framework: Vue2 with Element-UI.
• Features: Responsive layout for mobile support.
• Editors:
  • CodeMirror for online code editing.
  • Mavon-Editor for rich text editing.
  • Vxe-Table for data tables.

Backend (hoj-backend / Data Service)

• Framework: Spring Boot.
• Service Discovery & Config: Nacos (supports dynamic configuration refreshing).
• Database & Persistence: MySQL with Mybatis-Plus.
• Security: Shiro (manages user roles, permissions, and token refreshing).
• Caching & Queuing: Redis (used for data caching and as a list for the evaluation queue).

Evaluation Service (hoj-judgeserver)

• Framework: Spring Boot.
• Integration: Registers with Nacos for scheduling by hoj-backend and retrieves configurations.
• Evaluation Modes:
  • Local Evaluation: Uses the Go-Judge (SandBox) for high-performance, secure execution. Supports normal, special, interactive evaluation, and online debugging.
  • Remote Evaluation: Uses crawler technology to submit code to external platforms (e.g., HDU, Codeforces, POJ), retrieves submission IDs, and polls for results to write back to the database.

Request Flow

1. User requests are sent to Nginx.
2. Nginx proxies requests to either the Vue static files or the Backend services.
3. The Backend processes business logic using MySQL and Redis, returning JSON to the Vue frontend.
4. For evaluation requests: hoj-backend queries Nacos for healthy hoj-judgeserver instances, sends the task to a judge, which then executes the code via the Go-Judge sandbox and updates the database.

HOJ supports two primary contest formats with different scoring and ranking behaviors:

ACM Mode

Follows strict ACM-ICPC rules. The Seal Time Rank setting determines if the leaderboard is frozen (sealed).

• Sealing Options: 30 minutes before the end, 1 hour before the end, or for the entire duration.
• Behavior during Sealing:
  • Super Admins & Contest Creators: Can view problem statistics and submit data normally. Submissions are visible, but they will not be included in the leaderboard automatically. The leaderboard must be manually refreshed to see updates.
  • Regular Users & Other Admins: Can see their own submission results, but cannot see anyone else's submissions made after the seal time. They cannot see problem statistics. The leaderboard remains frozen at the state it was in before the seal.

OI Mode

Scoring is based on individual problem points. Multiple submissions are judged by either the last submission or the highest score submission (depending on configuration). Ranking is determined by the total score across all problems.

• Behavior during Sealing:
  • Super Admins & Contest Creators: Same as ACM mode (can see stats/results, but results won't update the leaderboard without manual refresh).
  • Regular Users & Other Admins: Cannot see their own or anyone else's submission results made after the seal time. They cannot see problem statistics. The leaderboard remains frozen at the state it was in before the seal.

Note: By default, all data becomes visible again once the contest ends, but the backend can be configured to continue the seal after the contest concludes.

HOJ supports four distinct judging modes, each with a different execution logic:

1. Ordinary Judging (普通评测)

• Process: Compiles user code $\rightarrow$ Runs program using standard input files $\rightarrow$ Checks time/memory limits $\rightarrow$ Compares user output against standard output.
• Failure points: Compilation failure or exceeding time/memory limits.

2. Special Judging (特殊评测)

• Process: Compiles user code $\rightarrow$ Compiles a special program (SPJ) if not already compiled $\rightarrow$ Runs user program $\rightarrow$ Uses the SPJ to compare standard input, standard output, and user output.
• Use case: When standard output comparison is insufficient and custom logic is needed to validate results.

3. Interactive Judging (交互评测)

• Process: Compiles user code $\rightarrow$ Compiles an interactive program $\rightarrow$ Runs both programs simultaneously, allowing them to interact via standard input/output streams.
• Use case: For problems where the judge must respond to user program actions in real-time.

4. Remote Judging (远程评测)

• Process: Uses crawler/simulation technology to submit code to external platforms (e.g., HDU, POJ, Codeforces, GYM, AtCoder, SPOJ).
• Implementation:
  • Requires platform account cookies configured in the submission API parameters.
  • Includes a retry mechanism for submission failures.
  • If a submission ID is obtained, a background thread polls the remote platform every 3 seconds.
  • If no result is found within 3 minutes, the submission is marked as failed. Otherwise, the remote result is mapped to the HOJ format.