File Storage

This is a file storage server for the MAXIT project.

Build

Prerequisites:

• Docker

To build docker image for local usage run the following command:

docker build -t maxit/file-storage .

Usage

Prerequisites:

• Go: Ensure you have Go installed on your machine (version 1.23.2).

To set up and run the File Storage API, follow these steps:

1. Clone the Repository:

    git clone https://github.com/mini-maxit/file-storage.git
    cd file-storage
   

2. Install Go Packages: Ensure all necessary Go packages are installed by running:

    go mod tidy
   

3. Environment Configuration: Copy the .env.dist file to .env:

    cp .env.dist .env
   

   Update the .env file with the necessary environment variables.
4. Run the Application: To run the application, you can use the prepared Makefile. jut run:

   make
   

Endpoints

Error Structure

When an error occurs, the response is returned in JSON format with the following structure:

{
  "reason": "A brief explanation of the error",
  "details": "A more detailed description of the error",
  "context": {
    "key": "value",
    "key2": "value2"
  }
}

Field Descriptions:

• reason: A high-level message describing the cause of the error, such as "Failed to process task" or "Submission not found."
• details: A more specific message or description of the error, often based on the underlying issue (e.g., "Invalid task parameters").
• context: An optional field containing additional context information about the error. This might include values like taskID, userID, submissionNumber, or other key-value pairs that provide insight into the specific conditions under which the error occurred. This field is included when relevant context is available.

1. Create Task

• Endpoint: /createTask
• Method: POST
• Description: Creates a new task directory with a specified structure, including input and output files.

Request Body (Form-Data):

• taskID (required): Integer value representing the unique task identifier.
• overwrite (optional): Boolean value indicating whether to overwrite an existing task directory.
• archive (required): Archive file (.zip or .tar.gz) with the following folder structure after decompressing:
  • Task - directory that should contain the description.pdf file
    • input - directory with input files (that match pattern {number}.in)
    • output - directory with output files (that match pattern {number}.out)

Request example:

  curl -X POST http://localhost:8080/createTask \
  -F "taskID=1" \
  -F "overwrite=false" \
  -F "archive=@/path/to/archive.zip"

Response:

• Success: 200 OK with the message "Task directory created successfully"
• Failure: 400 or 500 error code with a specific error message.

2. Submit File

• Endpoint: /submit
• Method: POST
• Description: Submits a file for a specific user and task.

Request Body (Form-Data):

• taskID (required): Integer ID of the task.
• userID (required): Integer ID of the user submitting the file.
• submissionFile (required): The file the user wants to submit (e.g., solution.c or similar).

Request example:

  curl -X POST http://localhost:8080/submit \
  -F "taskID=1" \
  -F "userID=1" \
  -F "submissionFile=@/path/to/solution.c"

Response:

• Success: 200 OK with JSON response containing "message" and "submissionNumber". Example:

  {
    "message": "Submission created successfully",
    "submissionNumber": 5
  }
  

• Failure: 400 or 500 error code with a specific error message.

3. Store Outputs

• Endpoint: /storeOutputs
• Method: POST
• Description: Stores output files generated by the user's program under a specific submission directory. This can either be a set of output files with possible stderr files or a compile error file.

Request Body (Form-Data):

• taskID (required): Integer ID of the task.
• userID (required): Integer ID of the user.
• submissionNumber (required): Integer indicating the submission version for which the output files are stored.
• archive (required): Archive file (.zip or .tar.gz) with the following folder structure after decompressing:
  • Outputs - directory with the output files and possibly stderr files (that match pattern {number}.out and {number}.err respectively) or with an error file (compile-err.err)

Constraints:

• Either outputs with stderr or compilation error must be provided, but not both.
• The number of output files in outputs must match the expected number specified in the taskID/src/output folder.
• The number of stderr might differ from the number of output files.

Request example (with output files):

  curl -X POST http://localhost:8080/storeOutputs \
  -F "taskID=1" \
  -F "userID=1" \
  -F "submissionNumber=1" \
  -F "archive=@/path/to/archive.zip"

Request example (with an error file):

  curl -X POST http://localhost:8080/storeOutputs \
  -F "taskID=1" \
  -F "userID=1" \
  -F "submissionNumber=1" \
  -F "error=@/path/to/compile-error.err"

Response:

• Success:
  • 200 OK with "Output files stored successfully" if outputs were provided.
  • 200 OK with "Error file stored successfully" if error was provided.
• Failure: 400 or 500 error code with a specific error message.

4. Get Task Files

• Endpoint: /getTaskFiles
• Method: GET
• Description: Retrieves all files (description, input, and output) for a given task.

Query Params:

• taskID (required): Integer ID of the task.

Request example:

  curl --location 'http://localhost:8080/getTaskFiles?taskID=123'

Response:

• Success: Returns a .tar.gz file containing the task's src folder, named as task{taskID}Files.tar.gz. The archive includes:
  • description.pdf file if present
  • input/ folder with all input .txt files
  • output/ folder with all output .txt files
• Failure: 400 or 500 error code with a specific error message.

5. Get User Submission

• Endpoint: /getUserSubmission
• Method: GET
• Description: Fetches the specific submission file for a user.

Query Params:

• taskID (required): Integer ID of the task.
• userID (required): Integer ID of the user.
• submissionNumber (required): Integer indicating the submission version for which the output files are stored.

Request example:

  curl --location 'http://localhost:8080/getUserSubmission?taskID=123&userID=1&submissionNumber=1'

Response:

• Success: Returns a file containing user's solution for the requested submission
• Failure: 400 or 500 error code with a specific error message.

6. Get Input/Output Files

Endpoint: /getInputOutput
Method: GET
Description: Retrieves specific input and output files for a given task.

Query Params:

• taskID (required): Integer ID of the task.
• inputOutputID (required): Integer ID of the input/output of the task.

Request example:

  curl --location 'http://localhost:8080/getInputOutput?taskID=123&inputOutputID=1'

Response:

• Success: Returns a .tar.gz file containing the task's src folder, named as Task{taskID}InputOutput{inputOutputID}Files.tar.gz. The archive includes:
  • input and output files
• Failure: 400 or 500 error code with a specific error message.

7. Delete Task

• Endpoint: /deleteTask
• Method: DELETE
• Description: Deletes the entire directory and all files associated with a specific task.

Query Params:

• taskID (required): Integer ID of the task to be deleted.

Request example:

  curl --location --request DELETE 'http://localhost:8080/deleteTask?taskID=123'

Response:

• Success: 200 OK with the message "Task {taskID} successfully deleted."
• Failure:
  • 400 Bad Request if taskID is missing or invalid.
  • 404 Not Found if the task directory does not exist.
  • 500 Internal Server Error if there is an error during the deletion process.

8. Get User Solution Package

• Endpoint: /getSolutionPackage
• Method: GET
• Description: Retrieves a structured package containing input, output, and solution files for a specific user’s submission in a task. The package is returned as a .tar.gz archive.

Query Params:

• taskID (required): Integer ID of the task.
• userID (required): Integer ID of the user.
• submissionNumber (required): Integer indicating the submission version for which the solution package is requested.

Request example:

  curl --location 'http://localhost:8080/getSolutionPackage?taskID=123&userID=1&submissionNumber=1'

Response:

• Success:
  • Status: 200 OK
  • Returns a .tar.gz file named Task{taskID}_User{userID}_Submission{submissionNumber}_Package.tar.gz containing:
    • inputs/ folder with all input .in files
    • outputs/ folder with all output .out files
    • solution file with any original extension
• Failure:
  • Status: 400 Bad Request if any required parameter is missing or invalid.
  • Status: 404 Not Found if the specified task, submission, or required files (input, output, solution) are missing.
  • Status: 500 Internal Server Error for other server-related issues.

9. Get Task Description

• Endpoint: /getTaskDescription
• Method: GET
• Description: Fetches the description file for the given task.

Query Params:

• taskID (required): Integer ID of the task.

Request example:

  curl --location 'http://localhost:8080/getTaskDescription?taskID=123'

Response:

• Success: Returns a file containing task's description.
• Failure: 400 or 500 error code with a specific error message.