File Upload
This document describes the /api/upload
endpoint used for uploading files.
Endpoint Summary
Section titled “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
Section titled “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 bemyFile
. 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
Section titled “Response Details”- Success Response:
- Code:
200 OK
- Body:
{"message": "Uploaded successfully"}
- Code:
- Error Responses:
- Code:
400 Bad Request
- Body Example:
{"error": "No save path provided"}
(IfsaveToPath
is missing). - Body Example:
{"error": "No files uploaded"}
(If themyFile
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).
- Body Example:
- Code:
401 Unauthorized
/403 Forbidden
(Not explicitly shown in code, but implied byWithAuth: 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 theCreateFile
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).
- Body Example:
- Code:
Underlying Logic (CreateFile
function)
Section titled “Underlying Logic (CreateFile function)”The UploadFiles
handler delegates the actual file creation to the CreateFile
function. Key aspects of CreateFile
:
- Path Validation: It cleans the provided
savePATH
and ensures it’s a valid path format. - Base Directory: It resolves the
savePATH
relative to a configuredBaseUploadDir
on the server. - 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
). - Directory Existence: It verifies that the directory part of the target path already exists. It does not create parent directories automatically.
- Filesystem Abstraction: Uses
filetools.GetLayer(ostype)
to interact with the filesystem, allowing for potential differences between OS (e.g., Windows vs. Linux). - Permissions: Sets default file permissions based on the server’s operating system (
0o644
for Linux,0o666
for Windows). - File Creation: Opens the file with flags to write, create (if it doesn’t exist), and truncate (if it does exist, overwriting it).
- Data Writing: Writes the received file data to the newly created file on the server’s disk.
Example Usage (Conceptual cURL)
Section titled “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