File Upload

This document describes the /api/upload endpoint used for uploading files.

Endpoint Summary

• Route: /api/upload
• Method: POST
• Description: Handles multipart/form-data requests to upload one or more files to a specified path on the server.
• Authentication: Required (WithAuth: true). The specific authentication mechanism (e.g., JWT Bearer token) should be documented elsewhere.

Request Details

• Method: POST
• Path: /api/upload
• Headers:
  • Content-Type: multipart/form-data; boundary=<boundary_string> (This header is automatically set by clients when sending multipart forms).
  • Authorization: <Credentials> (Replace <Credentials> with the appropriate auth token/method).
• Form Data:
  • saveToPath (string, required): The destination path relative to the server’s configured base upload directory, including the desired filename. Example: user_files/documents/report.pdf.
  • myFile (file, required): The file(s) to be uploaded. The form field name must be myFile. Multiple files can be attached using the same field name.
  • fstype (string, optional): Specifies the filesystem abstraction layer to use. If omitted, it defaults to "OsFs", which typically corresponds to the server’s native operating system filesystem.

Response Details

• Success Response:
  • Code: 200 OK
  • Body:

    {
      "message": "Uploaded successfully"
    }

• Error Responses:
  • Code: 400 Bad Request
    • Body Example: {"error": "No save path provided"} (If saveToPath is missing).
    • Body Example: {"error": "No files uploaded"} (If the myFile field is present but contains no files).
    • Body Example: {"error": "Failed to parse form: file too large"} (If the total upload size exceeds the server limit, currently 50MB).
    • Body Example: {"error": "Failed to open uploaded file"} (If an uploaded file part cannot be opened).
  • Code: 401 Unauthorized / 403 Forbidden (Not explicitly shown in code, but implied by WithAuth: true)
    • Body: Depends on the authentication middleware implementation. Usually indicates missing or invalid credentials.
  • Code: 500 Internal Server Error
    • Body Example: {"error": "Failed to read uploaded file"} (If reading data from an opened file part fails).
    • Body Example: {"error": "Failed to create file on server: <specific error message>"} (If the CreateFile function encounters an issue, such as an invalid path, permissions error, directory not existing, or disk write failure. The <specific error message> provides more detail).

Underlying Logic (CreateFile function)

The UploadFiles handler delegates the actual file creation to the CreateFile function. Key aspects of CreateFile:

1. Path Validation: It cleans the provided savePATH and ensures it’s a valid path format.
2. Base Directory: It resolves the savePATH relative to a configured BaseUploadDir on the server.
3. Security: It performs a crucial security check to ensure the final absolute path is still within the configured BaseUploadDir, preventing directory traversal attacks (e.g., trying to save files to ../../etc/passwd).
4. Directory Existence: It verifies that the directory part of the target path already exists. It does not create parent directories automatically.
5. Filesystem Abstraction: Uses filetools.GetLayer(ostype) to interact with the filesystem, allowing for potential differences between OS (e.g., Windows vs. Linux).
6. Permissions: Sets default file permissions based on the server’s operating system (0o644 for Linux, 0o666 for Windows).
7. File Creation: Opens the file with flags to write, create (if it doesn’t exist), and truncate (if it does exist, overwriting it).
8. Data Writing: Writes the received file data to the newly created file on the server’s disk.

Example Usage (Conceptual cURL)

curl -X POST \
  'http://localhost:5050/api/upload' \
  -H 'Authorization: Bearer your_auth_token' \
  -F 'saveToPath=user_uploads/avatar.jpg' \
  -F 'myFile=@/path/to/local/avatar.jpg' \
  -F 'myFile=@/path/to/local/document.pdf' # Example of uploading multiple files