File Download

This document describes the /api/download endpoint used for downloading files.

Endpoint Summary

• Route: /api/download
• Method: GET
• Description: Retrieves and streams a specified file from the server to the client.
• Authentication: Required (WithAuth: true). The specific authentication mechanism should be documented elsewhere (e.g., JWT Bearer token in Authorization header or as a query parameter like token mentioned in code comments).

Request Details

• Method: GET
• Path: /api/download
• Authentication: Requires valid authentication credentials. Provide details on how the token should be sent (e.g., Authorization: Bearer <token> header is standard).
• Query Parameters:
  • filepath (string, required): The path (including filename) relative to the server’s configured base directory from which the file should be downloaded. Example: user_files/data/image.png.
  • fstype (string, optional): Specifies the target filesystem abstraction layer. Defaults to "OsFs" if omitted, typically representing the server’s native filesystem.

Response Details

• Success Response:

  • Code: 200 OK
  • Headers:
    • Content-Disposition: attachment; filename="<filename.ext>": Suggests the browser should download the file with the given name. <filename.ext> is the actual name of the file on the server.
    • Content-Type: <mime_type>: The MIME type of the file (e.g., image/png, application/pdf). Defaults to application/octet-stream if the type cannot be determined from the file extension.
    • Content-Length: <file_size_in_bytes>: The size of the file being sent.
    • Content-Description: File Transfer
    • Content-Transfer-Encoding: binary
  • Body: The raw binary data of the requested file.

• Error Responses: (Error codes depend partially on the e.ToHttp mapping function, common examples below)

  • Code: 400 Bad Request
    • Reason: Missing filepath query parameter, or an internal error occurred that doesn’t map to a specific gRPC/HTTP status.
    • Body Example: {"error": "provide a file path is required -> could not download file"} or similar message from the underlying DownloadFile function or handler.
  • Code: 401 Unauthorized / 403 Forbidden
    • Reason: Authentication failed, or the requested filepath resolves to a location outside the allowed base directory, or the file is a directory, or it lacks read permissions, or it’s not a regular file.
    • Body Example: {"error": "file path is not allowed"}, {"error": "<path> is a directory and not a file"}, {"error": "file is not readable"}, {"error": "file is not a regular file"}. Authentication errors depend on middleware.
  • Code: 404 Not Found
    • Reason: The file specified by filepath does not exist on the server within the allowed directory.
    • Body Example: {"error": "file not found at <path>"}
  • Code: 412 Precondition Failed (or similar, check e.ToHttp mapping)
    • Reason: The requested file is empty, or the filesystem layer specified by fstype could not be accessed.
    • Body Example: {"error": "file is empty"}, {"error": "failed to get file system: <detail>"}
  • Code: 413 Payload Too Large (or similar, check e.ToHttp mapping for e.ResourceExhausted)
    • Reason: The requested file exceeds the maximum allowed download size (currently 50 MB).
    • Body Example: {"error": "file too large, max size is 50 MB"}
  • Code: 500 Internal Server Error
    • Reason: An unexpected server error occurred while processing the request, such as failing to resolve the path, open the file (for reasons other than ‘not found’), get file stats, or read the file content.
    • Body Example: {"error": "failed to get absolute path: <detail>"}, {"error": "failed to open file: <detail>"}, {"error": "failed to read file: <detail>"}

Underlying Logic (DownloadFile function)

The DownloadFileHttp handler uses the DownloadFile function to perform the core logic:

1. Path Construction: It internally combines the fstype and filepath query parameters into a format like ostype=filepath before processing.
2. Path Validation & Security: It resolves the filepath relative to a configured base directory on the server. Crucially, it verifies that the final absolute path is within this allowed base directory to prevent unauthorized access to other parts of the filesystem.
3. Filesystem Abstraction: Uses filetools.GetLayer(ostype) for potentially OS-specific file operations.
4. File Validation: Before reading, it checks that the target:
   • Exists.
   • Is a regular file (not a directory).
   • Is readable (has read permissions).
   • Is not empty.
   • Does not exceed the maximum size limit (50 MB).
5. File Reading: If all checks pass, it reads the entire file content into memory.
6. Response Preparation: Returns the file content and metadata (name, path, size) to the HTTP handler.

Example Usage (Conceptual cURL)

# Using Authorization header (Recommended)
curl -X GET \
  'http://localhost:5050/api/download?filepath=user_files/data/report.pdf' \
  -H 'Authorization: Bearer your_auth_token' \
  -o 'downloaded_report.pdf' # -o saves the output to a file

# Using token query parameter (If supported based on code comments)
# curl -X GET \
#  'http://localhost:5050/api/download?filepath=user_files/data/report.pdf&token=your_auth_token' \
#  -o 'downloaded_report.pdf'