مهدی برنامه‌نویس خفنی است و پروژه‌های خفنی انجام می‌دهد. دوستان او از نحوه‌ی پیاده‌سازی سیستم داوری کوئرا در عجب‌اند، اما مهدی به آن‌ها می‌گوید پیاده‌سازی جاجی مثل کوئرا عین آب خوردنه! مهدی می‌خواهد این موضوع را به دوستانش اثبات کند، اما در حال حاضر مشغول انجام پروژه‌های خفن است و فرصت انجام این کار را ندارد.

از شما می‌خواهیم این موضوع را به دوستان مهدی اثبات کنید.

جزئیات پروژه

پروژه‌ی اولیه را از این لینک دانلود کنید.

judge-api
├── app
│   ├── Console
│   ├── Exceptions
│   ├── Http
│   ├── Jobs
│   │   └── JudgeSubmission.php
│   ├── Judge
│   │   ├── InputOutputJudge.php
│   │   ├── Judge.php
│   │   └── JudgeResult.php
│   ├── Models
│   │   ├── Submission.php
│   │   └── User.php
│   └── Providers
├── bootstrap
├── config
├── database
├── public
├── resources
├── routes
├── storage
├── tests
├── README.md
├── artisan
├── composer.json
├── composer.lock
├── package.json
├── phpunit.xml
├── server.php
└── webpack.mix.js

همان‌طور که می‌دانید، سیستم داوری کوئرا (در حالت ورودی/خروجی) به این‌صورت است که یک رشته به‌عنوان stdin به یک برنامه داده می‌شود و در انتها، نتیجه‌ی اجرای برنامه دریافت می‌شود.

مدل‌ها

علاوه بر مدل پیش‌فرض User، مدلی با نام Submission در برنامه تعریف شده است. مایگریشن‌ها و روابط بین مدل‌ها از قبل برقرار شده‌اند. با مطالعه‌ی این موارد، باید با ساختار مدل‌های برنامه آشنا شوید.

کلاس App\Judge\JudgeResult

از این کلاس برای نگه‌داری اطلاعات مربوط به داوری ارسال‌ها استفاده می‌شود.

class JudgeResult
{
    const SUCCESS = 0;
    const TIME_LIMIT_EXCEEDED = 1;
    const RUNTIME_ERROR = 2;
    const SYNTAX_ERROR = 3;

    public function __construct(
        public string $stderr,
        public string $stdout,
        public int $status
    ) {}
}

اینترفیس App\Judge\Judge

این اینترفیس شامل یک متد با نام run است که پارامترهای آن به‌صورت زیر هستند:

• code: متن کد
• timeLimit: محدودیت زمان برحسب میلی‌ثانیه
• stdin: ورودی برنامه

interface Judge
{
    public function run(string $code, int $timeLimit, string $stdin = ''): JudgeResult;
}

کلاس App\Judge\InputOutputJudge

این کلاس یک پیاده‌سازی از اینترفیس App\Judge\Judge است که باید کدهای PHP را اجرا کند و نتیجه را در قالب آبجکتی از کلاس App\Judge\JudgeResult برگرداند. مقدار پراپرتی‌های آبجکت خروجی باید مطابق توضیحات زیر باشد:

• اگر کد سینتکس ارور داشته باشد، مقدار status باید برابر با JudgeResult::SYNTAX_ERROR باشد و مقدار stderr و stdout باید برابر با رشته‌ی خالی باشد.
• اگر اجرای برنامه در زمان مشخص‌شده خاتمه یابد و داده‌ای توسط برنامه در stderr نوشته نشده باشد، مقدار status باید برابر با JudgeResult::SUCCESS باشد، مقدار stderr باید برابر با رشته‌ی خالی باشد و مقدار stdout باید برابر با خروجی برنامه باشد.
• اگر اجرای برنامه در زمان مشخص‌شده خاتمه یابد و داده‌ای توسط برنامه در stderr نوشته شده باشد، مقدار status باید برابر با JudgeResult::RUNTIME_ERROR باشد، مقدار stderr باید برابر با محتویات stderr باشد و مقدار stdout باید برابر با رشته‌ی خالی باشد.
• اگر اجرای برنامه در زمان مشخص‌شده خاتمه نیابد، فارغ از این که داده‌ای توسط در stdout یا stderr نوشته شده باشد، مقدار status باید برابر با JudgeResult::TIME_LIMIT_EXCEEDED باشد و مقدار stderr و stdout باید برابر با رشته‌ی خالی باشد.

جاب JudgeSubmission

این جاب شناسه‌ی یک Submission را دریافت می‌کند. وظیفه‌ی این جاب، داوری یک Submission است. متد handle این جاب را طوری پیاده‌سازی کنید که ابتدا مقدار ستون status مربوط به Submission را به judging تغییر دهد، سپس داوری را با استفاده از کلاس InputOutputJudge انجام دهد و در نهایت، status، stderr و stdout را مقداردهی کند و تغییرات را در دیتابیس ذخیره کند.

احراز هویت

پکیج laravel/sanctum در این پروژه نصب شده و از آن می‌توانید برای احراز هویت استفاده کنید. توکن‌های احراز هویت هنگام داوری توسط این پکیج تولید می‌شوند. هنگام ارسال درخواست‌ها، مقدار header برابر با یک توکن Bearer قرار داده می‌شود و مقدار هدر Accept برابر با application/json خواهد بود.

%align_right_start%

endpoint های API

%align_end%

در این برنامه باید سه endpoiont به‌صورت زیر تعریف کنید. همه‌ی این endpoint باید نیازمند احراز هویت کاربر باشند. در غیر این‌صورت، کد پاسخ 401 باید برگردانده شود:

• GET /api/submissions: با ارسال این درخواست، کاربر باید لیست ارسال‌هایش را در قالب یک آرایه ببیند (باید کالکشنی از Submissionها را به JSON تبدیل کرده و آن را برگردانید). کد پاسخ باید برابر با 200 باشد.
• POST /api/submissions: با ارسال این درخواست، باید یک Submission به Submissionهای کاربر اضافه شود. تضمین می‌شود که مقادیر code، time_limit و stdin در بدنه‌ی درخواست موجود خواهند بود. همچنین، جاب JudgeSubmission مربوط به Submission ارسال‌شده باید به صفی با عنوان judge اضافه شود. کد پاسخ باید برابر با 201 باشد.
• GET /api/submissions/{submission_id}: با ارسال این درخواست، کاربر باید اطلاعات Submission با شناسه‌ی submission_id را مشاهده کند (باید آبجکت Submission را به JSON تبدیل کرده و آن را برگردانید). اگر Submission وجود نداشته باشد یا متعلق به کاربر نباشد، کد پاسخ باید برابر با 404 باشد. در غیر این‌صورت، کد پاسخ باید برابر با 200 باشد.

نکات

• داوری در یک سیستم لینوکسی صورت می‌گیرد. بنابراین می‌توانید از امکانات خط فرمان آن استفاده کنید.
• شما تنها مجاز به اعمال تغییرات در پوشه‌های app و routes هستید (می‌توانید فایل‌های جدیدی نیز در این پوشه‌ها ایجاد کنید).

آن‌چه باید آپلود کنید

پس از پیاده‌سازی موارد خواسته‌شده، پوشه‌های app و routes را زیپ کرده و آپلود کنید.