(no-ticket) Zeus documentation.

Change-Id: I2f082e26ecfdb80c0bdd2ced41ab6e05562cd518

oioioi/zeus/__init__.py

@@ -0,0 +1,2 @@
+"""The zeus app is used for integration between oioioi and zeus, a system for
+   grading distributed programing problems."""

oioioi/zeus/fixtures/test_zeus_correct.json

@@ -0,0 +1,62 @@
+[
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/problem/1/job/INITIAL/",
+      "method" : "POST",
+      "result" : "{\"check_uid\": 1001}"
+   },
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/problem/1/job/NORMAL/",
+      "method" : "POST",
+      "result" : "{\"check_uid\": 1002}"
+   },
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/problem/1/job/TESTRUN/",
+      "method" : "POST",
+      "result" : "{\"check_uid\": 1003}"
+   },
+   {
+      "result_code" : 404,
+      "url" : "zeus_fixture_server/problem/4/job/INITIAL/",
+      "method" : "POST",
+      "result" : "{\"error\": \"Tm8gc3VjaCBwcm9ibGVtLg==\"}"
+   },
+   {
+      "result_code" : 500,
+      "url" : "zeus_fixture_server/problem/4/job/TESTRUN/",
+      "method" : "POST",
+      "result" : "{}"
+   },
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/reports_since/0/",
+      "method" : "GET",
+      "result" : "{\"next_seq\": 13, \"reports\": [{\"status\": \"T0s=\", \"compilation_successful\": true, \"compilation_message\": \"\", \"check_uid\": 1001, \"time_limit_ms\": 1000, \"report_kind\": \"SU5JVElBTA==\", \"result_string\": \"b2theSE=\", \"memory_limit_byte\": 33554432, \"execution_time_ms\": 621, \"metadata\": \"MW9jZW4sLDA=\"}, {\"status\": \"T0s=\", \"compilation_successful\": true, \"compilation_message\": \"\", \"stdout_size\": 15, \"check_uid\": 1003, \"time_limit_ms\": 1000, \"stdout\": \"SGVsbG8sIHdvcmxkISAK\", \"report_kind\": \"VEVTVFJVTg==\", \"stdout_uid\": 531, \"result_string\": \"\", \"memory_limit_byte\": 33554432, \"execution_time_ms\": 786, \"metadata\": \"\"}]}"
+   },
+   {
+      "result_code" : 404,
+      "url" : "zeus_fixture_server/reports_since/1/",
+      "method" : "GET",
+      "result" : "{\"error\": \"SW52YWxpZCBzZXF1ZW50aWFsIG51bWJlcg==\"}"
+   },
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/reports_since/13/",
+      "method" : "GET",
+      "result" : "{\"next_seq\": 14, \"reports\": [{\"status\": \"V0E=\", \"compilation_successful\": true, \"compilation_message\": \"\", \"check_uid\": 1002, \"time_limit_ms\": 1000, \"report_kind\": \"Tk9STUFM\", \"result_string\": \"TGluaWEgODogb2N6ZWtpd2FubyBUQUssIHdjenl0YW5vIE5JRS4=\", \"memory_limit_byte\": 33554432, \"execution_time_ms\": 221, \"metadata\": \"MSxncjEsMTA=\"}, {\"status\": \"T0s=\", \"compilation_successful\": true, \"compilation_message\": \"\", \"check_uid\": 1002, \"time_limit_ms\": 1000, \"report_kind\": \"Tk9STUFM\", \"result_string\": \"b2theSE=\", \"memory_limit_byte\": 33554432, \"execution_time_ms\": 0, \"metadata\": \"MixncjEsMTA=\"}]}"
+   },
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/reports_since/14/",
+      "method" : "GET",
+      "result" : "{\"next_seq\": 14, \"reports\": []}"
+   },
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/full_stdout/531/",
+      "method" : "GET",
+      "result" : "{\"full_stdout\": \"SGVsbG8sIHdvcmxkISAK\"}"
+   }
+]

oioioi/zeus/fixtures/test_zeus_incorrect.json

@@ -0,0 +1,14 @@
+[
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/problem/1/job/INITIAL/",
+      "method" : "POST",
+      "result" : "{\"check_uid\": -4}"
+   },
+   {
+      "result_code" : 200,
+      "url" : "zeus_fixture_server/problem/1/job/NORMAL/",
+      "method" : "POST",
+      "result" : "{}"
+   }
+]

rst/source/sections/misc.rst

@@ -152,3 +152,122 @@ Switching users (su)
 .. autofunction:: oioioi.su.utils.su_to_user
 
 .. autofunction:: oioioi.su.utils.reset_to_real_user
+
+Zeus integration (zeus)
+-----------------------
+
+.. currentmodule:: oioioi.zeus
+
+.. automodule:: oioioi.zeus
+
+Zeus instances are configured in ``settings.ZEUS_INSTANCES``, which is a dict
+mapping ``zeus_id`` - unique identifier of a zeus instance - to ``(zeus_url,
+zeus_login, zeus_secret)`` - base URL for zeus api (*ZBU*) and credentials.
+
+API specification
+.................
+
+Communication with zeus is done over HTTPS protocol, in a REST-like style. Data
+are encoded using JSON. OIOIOI authorizes itself to zeus using HTTP Basic
+Authentication, with login and secret fixed for a contest.
+
+Prefix **?** means optional attribute, prefix **T** marks attribute only for
+testrun.
+
+Sending submissions
+~~~~~~~~~~~~~~~~~~~
+
+:Request:
+
+|    POST *ZBU*/problem/*zeus_problem_id*/job/*INITIAL|NORMAL|TESTRUN*/
+
+:Data sent:
+
+|   {
+|       "source_code": source_code :: Base64String,
+|       **T** "library": library_generating_input :: Base64String,
+|       **T** "input_test" input_for_library :: Base64String,
+|       "language": source_language :: Base64String(CPP|...),
+|   }
+
+:Result:
+
+Code 200 and data:
+
+|    { "check_uid": unique_job_id :: Uint }
+
+or code 4xx|5xx and data:
+
+|    { **?** "error": error_description :: Base64String }
+
+Fetching results
+~~~~~~~~~~~~~~~~
+
+Fetching results is done using long polling.
+
+:Request:
+
+|   GET *ZBU*/reports_since/*last_seq*/
+
+:Result:
+
+Code 200 and data:
+
+|    {
+|        "next_seq": next_sequential_number :: Int,
+|        "reports": list_of_reports :: [Report]
+|    }
+
+where
+
+|    Report = {
+|        "check_uid": job_id :: Int,
+|        **T** "stdout_uid": unique_output_id :: Int,
+|        "compilation_successful": was_compilation_successful :: Bool,
+|        "compilation_message": compiler_result :: Base64String,
+|        "report_kind": check_kind :: Base64String(INITIAL|NORMAL|TESTRUN),
+|        "status": test_status :: Base64String(OK|WA|TLE|RE|RV|MSE|MCE),
+|        "result_string": status_description :: Base64String,
+|        "metadata": more_data_about_test :: Base64String,
+|        **T** "stdout": first_10kB_of_output :: Base64String
+|        **T** "stdout_size": size_of_full_stdout_in_bytes :: Int,
+|        "execution_time_ms": max_of_times_at_all_machines :: Int,
+|        "time_limit_ms": execution_time_limit :: Int,
+|        "memory_limit_byte": memory_limit :: Int,
+|    }
+
+or code 4xx|5xx and data:
+
+|    { **?** "error": error_description :: Base64String }
+
+Each check_uid will appear in at most one result - results for given job will
+be sent together, when all are ready.
+
+*MSE* and *MCE* are statuses meaning that size or count of outgoing messages
+sent by submitted program has exceeded the limit.
+
+Metadata are subject to coordination between judges and contest admins, they
+are just passed through zeus. They are designed to contain additional data
+about grouping, scoring etc. Currently we expect them to be in format:
+
+| "*test name*,\ *group name*,\ *max score*"
+
+Test name will be shown to users. All tests with the same, non-empty group name
+will be grouped together. All tests in group shall have the same max score.
+
+Fetching full output
+~~~~~~~~~~~~~~~~~~~~
+
+:Request:
+
+|   GET *ZBU*/full_stdout/*stdout_uid*/
+
+:Result:
+
+Code 200 and data:
+
+|   { "full_stdout" : full_stdout_limited_to_1MB :: Base64String }
+
+or code 4xx|5xx and data:
+
+|    { **?** "error": error_description :: Base64String }