Skip to content

File Upload

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

  • 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.
  • 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.
  • 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).

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.
Terminal window
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