GStorage Client

Giới thiệu

Đây là một thư viện NodeJS để tương tác với GStorage server.

Cách sử dụng

Cấu hình

const gstorageClient = new GStorageClient({
    apiKey: 'gstorage_api_key',
});

Tải lên tệp

!!!: Trong các ví dụ bên dưới, bạn có thể truyền vào stream của tệp thay vì filePath.

Single upload

!!!: Cách này chỉ sử dụng với file có kích thước không quá 1GiB.

const filePath = join(__dirname, './assets/matthew-dep-trai.mp4');
const uploadedFile = await gstorageClient.files.singleUpload(filePath);

Resumable upload

!!!: Cách này có thể sử dụng để upload tệp có kích thước rất lớn.

const filePath = join(__dirname, './assets/matthew-dep-trai.mp4');
const uploadedFile = await gstorageClient.files.resumableUpload(filePath, {
    fileName: 'matthew-dep-trai.mp4',
    mimeType: 'video/mp4',
});

Webhook resumable upload

!!!: Cũng giống như Resumable upload nhưng đối với cách này, các client sẽ có thể upload trực tiếp lên GStorage thông qua một đường link upload thay vì phải đi qua một server trung gian.

Các bước thực hiện quá trình tải lên không liên tục có sử dụng webhook như sau:

1. Client gửi yêu cầu khởi tạo phiên tải lên.

// Client NÊN gửi lên data có chứa các thông tin như sau
const data = {
    "fileName": "matthew-dep-trai.mp4",
    "mimeType": "video/mp4",
    "size": 123456
};

2. Server nhận thông tin file từ client và khởi tạo phiên tải lên GStorage.

const dataReceivedFromClient = data;

const uploadSession =
    await gstorageClient.files.createWebhookResumableUploadSession(
      dataReceivedFromClient,
      {
        url: 'https://webhookserver/gstorage/webhook',
        secret: 'bi_mat_qua_ne_hi_hi',
      },
    );

3. GStorage tạo phiên tải lên trực tiếp sau đó trả về cho server.

// Thông tin về phiên tải lên có interface như sau
interface IGStorageFilesCreateWebhookResumableUploadSession {
  size: number;
  webhookUrl: string;
  webhookSecret: string;
  token: string; // Đây là token cho client sử dụng để xác thực với GStorage khi tải lên
  name: string;
  mimeType: string;
  canResume: boolean;
  createdAt: string;
  _id: string;
  __v: number;
};

4. Server trả về thông tin về phiên tải lên cho client.

// Phía client cần thông tin có dạng như sau
const sessionCredentials = {
    id: '652cc33c2ff955460082c319', // Chính là trường `_id` trong phản hồi của GStorage
    token: 'OpNIJRjSmeTC8f6AnFBTDF9KAUFZJJHnySYz2l3lnzezAaCKABPna2ADeFPO09vpKwmeQOUFbu17C3czEwtUGA=='
};

5. Client thực hiện tải lên thông qua đường dẫn GStorage.

Từ thông tin nhận được, client sẽ tạo được đường dẫn tải lên trực tiếp tới GStorage có dạng như sau:

const uploadUrl = `https://api.gstorage.vfast.dev/file/resumable/${sessionCredentials.id}/webhook?token=${encodeURIComponent(sessionCredentials.token)}`

// https://api.gstorage.vfast.dev/file/resumable/652cc33c2ff955460082c319/webhook?token=OpNIJRjSmeTC8f6AnFBTDF9KAUFZJJHnySYz2l3lnzezAaCKABPna2ADeFPO09vpKwmeQOUFbu17C3czEwtUGA%3D%3D

Sau đó client sẽ thực hiện tải lên không liên tục bằng đường link này. Hoặc có thể sử dụng thư viện GStorage Client:

const uploadedFile = await gstorageClient.files.webhookResumableUpload(
  {
    id: session._id,
    token: session.token,
  },
  filePath,
  fileInfo.size,
);

6. GStorage gửi thông tin file nhận được từ client cho server thông qua webhook.

7. Server đồng bộ thông tin file sau đó phản hồi lại GStorage trong đó có kèm theo id của file trên CSDL của server.

8. GStorage nhận id từ server sau đó đính kèm vào body chứa thông tin file trả về cho client, kết thúc quá trình tải lên.