Uploading Files

Kala server use a filestore pattern to store files, which allows for efficient file management and retrieval. The filestore is organized by UUID, ensuring that files are stored in a structured manner.

Uploading Files

Uploading files to kala server can be done partially or fully, depending on the size of the file and the requirements of your application.

1. Generate upload session

To upload a file, you first need to generate an upload session. This session will provide you with a unique identifier (UUID) for the session

1. Create an upload session by sending a POST request to the /api/upload endpoint.

   • Endpoint: POST /api/manage/filestore/sessions
   • Request Body:

   {
     "originalFilename": "example.txt", // Optional, defaults to the file name
     "fileSize": 123456, // size in bytes
     "hash": "sha256:abc123" // SHA256 in base64 format
   }

   • Response:

   {
     "data": "your_upload_session_uuid"
   }

2. Store the returned UUID for the upload session. This UUID will be used to reference the file during the upload process

2. Upload the file

Once you have the upload session UUID, you can upload the file in parts or as a whole.

• Write mode:
  • WRITE: overwrite the file
  • APPEND: append to the existing file
• Endpoint: POST /api/manage/filestore/sessions/{uuid}/write
• Request Body:

const formData = new FormData();

// Append the mode part (e.g., 'WRITE', 'APPEND')
formData.append("mode", "WRITE"); // or any value representing FileSessionWriteMode

// Append the file or chunk as a byte array (Blob or File in JS)
const byteArray = new Uint8Array([
  /* your byte values here */
]);
const blob = new Blob([byteArray], { type: "application/octet-stream" });
formData.append("file or chunk", blob);

3. Close the upload session

After uploading the file, you need to close the upload session to finalize the upload process. When closing the session, it will check the file size and hash to ensure the integrity of the uploaded file.

• Endpoint: POST /api/manage/filestore/sessions/{uuid}/close

• Request Body: None

• Response:

  • Success return only OK status code (200 OK)

  • Error

  {
    "message": "File size does not match the expected size"
  }

4. Accessing the uploaded file

Once the upload session is closed successfully, you can access the uploaded file using the session UUID on the filestore files endpoint.

• Endpoint: GET /api/manage/filestore/files/{uuid}

The uploaded file then can be used as datastore inside Kala server