Protokol tus

tus adalah protokol terbuka untuk upload file yang dapat dilanjutkan. Gunakan untuk upload yang andal yang dapat bertahan dari gangguan jaringan.

Mengapa tus?

• Dapat dilanjutkan: Lanjutkan upload setelah kegagalan jaringan
• Efisien: Lanjutkan dari tempat terakhir, bukan dari awal
• Terstandarisasi: Protokol yang terdefinisi dengan baik dengan banyak implementasi server
• Chunked: Otomatis menangani file besar

Instalasi

npm install @samithahansaka/dropup tus-js-client

tus-js-client adalah peer dependency.

Penggunaan Dasar

import { useDropup } from '@samithahansaka/dropup';
import { createTusUploader } from '@samithahansaka/dropup/tus';

function TusUploader() {
  const { files, actions, state, getDropProps, getInputProps } = useDropup({
    upload: createTusUploader({
      endpoint: 'https://tusd.tusdemo.net/files/',
    }),

    onUploadComplete: (file) => {
      console.log('Upload selesai:', file.uploadedUrl);
    },
  });

  return (
    <div>
      <div {...getDropProps()} style={styles.dropzone}>
        <input {...getInputProps()} />
        <p>Lepas file untuk upload yang dapat dilanjutkan</p>
      </div>

      {files.map(file => (
        <div key={file.id} style={styles.fileItem}>
          <span>{file.name}</span>
          <span>{file.progress}%</span>
          <span>{file.status}</span>
        </div>
      ))}

      <button onClick={() => actions.upload()}>
        Upload
      </button>
    </div>
  );
}

Opsi Konfigurasi

createTusUploader({
  // Wajib
  endpoint: 'https://your-tus-server.com/files/',

  // Ukuran chunk (default: Infinity = tanpa chunking)
  chunkSize: 5 * 1024 * 1024,  // chunk 5MB

  // Konfigurasi retry
  retryDelays: [0, 1000, 3000, 5000],  // Retry setelah 0d, 1d, 3d, 5d

  // Header untuk semua request
  headers: {
    'Authorization': 'Bearer token',
  },

  // Metadata dikirim ke server
  metadata: {
    filename: 'file.name',
    filetype: 'file.type',
    // Tambahkan metadata kustom
    userId: 'user123',
  },

  // Aktifkan resumabilitas via localStorage
  storeFingerprintForResuming: true,

  // Hapus fingerprint setelah upload berhasil
  removeFingerprintOnSuccess: true,

  // Upload paralel
  parallelUploads: 3,
});

Lanjutkan Upload Sebelumnya

tus dapat melanjutkan upload yang terputus:

const { files, actions } = useDropup({
  upload: createTusUploader({
    endpoint: 'https://your-tus-server.com/files/',

    // Simpan URL upload untuk melanjutkan
    storeFingerprintForResuming: true,

    // Opsional: kunci penyimpanan kustom
    urlStorageKey: 'my-app-tus-uploads',

    onShouldRetry: (error, retryAttempt) => {
      // Logika retry kustom
      if (error.message.includes('network')) {
        return retryAttempt < 5;
      }
      return false;
    },
  }),
});

// File dapat dilanjutkan otomatis saat ditambahkan kembali
// atau secara manual dengan retry:
actions.retry(['file-id']);

Pelacakan Progres

function TusWithProgress() {
  const { files, actions, getDropProps, getInputProps } = useDropup({
    upload: createTusUploader({
      endpoint: 'https://your-tus-server.com/files/',
    }),

    onUploadProgress: (file, progress) => {
      console.log(`${file.name}: ${progress}%`);
    },

    onUploadStart: (file) => {
      console.log(`Memulai upload: ${file.name}`);
    },

    onUploadComplete: (file) => {
      console.log(`Selesai: ${file.uploadedUrl}`);
    },
  });

  return (
    <div>
      <div {...getDropProps()}>
        <input {...getInputProps()} />
        <p>Lepas file di sini</p>
      </div>

      {files.map(file => (
        <div key={file.id}>
          <span>{file.name}</span>
          {file.status === 'uploading' && (
            <div style={styles.progressBar}>
              <div
                style={{
                  ...styles.progress,
                  width: `${file.progress}%`,
                }}
              />
            </div>
          )}
          <span>{file.status}</span>
        </div>
      ))}
    </div>
  );
}

Jeda dan Lanjutkan

function PausableUploader() {
  const { files, actions, getDropProps, getInputProps } = useDropup({
    upload: createTusUploader({
      endpoint: 'https://your-tus-server.com/files/',
      storeFingerprintForResuming: true,
    }),
  });

  return (
    <div>
      <div {...getDropProps()}>
        <input {...getInputProps()} />
        <p>Lepas file di sini</p>
      </div>

      {files.map(file => (
        <div key={file.id}>
          <span>{file.name}</span>
          <span>{file.progress}%</span>

          {file.status === 'uploading' && (
            <button onClick={() => actions.cancel(file.id)}>
              Jeda
            </button>
          )}

          {file.status === 'paused' && (
            <button onClick={() => actions.retry([file.id])}>
              Lanjutkan
            </button>
          )}

          {file.status === 'error' && (
            <button onClick={() => actions.retry([file.id])}>
              Coba Lagi
            </button>
          )}
        </div>
      ))}

      <button onClick={() => actions.upload()}>
        Mulai Semua
      </button>
    </div>
  );
}

Setup Server

tusd (Server Resmi)

# Install tusd
go install github.com/tus/tusd/cmd/tusd@latest

# Jalankan dengan opsi default
tusd -upload-dir=/uploads

# Jalankan dengan penyimpanan S3
tusd -s3-bucket=my-bucket -s3-endpoint=https://s3.amazonaws.com

Node.js (tus-node-server)

const { Server } = require('@tus/server');
const { FileStore } = require('@tus/file-store');

const server = new Server({
  path: '/files',
  datastore: new FileStore({ directory: './uploads' }),
});

// Dengan Express
app.all('/files/*', server.handle.bind(server));

Penanganan Metadata Kustom

// Sisi server: akses metadata
const server = new Server({
  path: '/files',
  datastore: new FileStore({ directory: './uploads' }),
  onUploadCreate: async (req, res, upload) => {
    // Akses metadata yang dikirim dari klien
    console.log(upload.metadata);
    // { filename: 'photo.jpg', filetype: 'image/jpeg', userId: 'user123' }
  },
  onUploadFinish: async (req, res, upload) => {
    // Proses upload yang selesai
    console.log('Upload selesai:', upload.id);
  },
});

Ekstensi tus

Integrasi tus Dropup mendukung ekstensi tus berikut:

Ekstensi	Deskripsi
Creation	Buat upload baru
Termination	Batalkan upload
Checksum	Verifikasi integritas
Concatenation	Upload paralel
Expiration	Pembersihan otomatis

Penanganan Error

const { files, actions } = useDropup({
  upload: createTusUploader({
    endpoint: 'https://your-tus-server.com/files/',
    retryDelays: [0, 1000, 3000, 5000, 10000],
  }),

  onUploadError: (file, error) => {
    if (error.code === 'TUS_OFFLINE') {
      console.log('Jaringan offline, akan dilanjutkan saat terhubung');
    } else if (error.code === 'TUS_EXPIRED') {
      console.log('Upload kedaluwarsa, memulai dari awal');
      actions.retry([file.id]);
    } else {
      console.error('Upload gagal:', error.message);
    }
  },
});

Upload File Besar

tus ideal untuk file besar:

function LargeFileUploader() {
  const { files, actions, getDropProps, getInputProps } = useDropup({
    maxSize: 10 * 1024 * 1024 * 1024, // Batas 10GB

    upload: createTusUploader({
      endpoint: 'https://your-tus-server.com/files/',
      chunkSize: 50 * 1024 * 1024, // chunk 50MB
      retryDelays: [0, 3000, 5000, 10000, 20000],
      storeFingerprintForResuming: true,
    }),

    onUploadProgress: (file, progress) => {
      // Tampilkan progres detail untuk file besar
      const uploadedMB = (file.size * progress / 100 / 1024 / 1024).toFixed(0);
      const totalMB = (file.size / 1024 / 1024).toFixed(0);
      console.log(`${uploadedMB}MB / ${totalMB}MB`);
    },
  });

  return (
    <div {...getDropProps()}>
      <input {...getInputProps()} />
      <p>Upload file besar (hingga 10GB)</p>
    </div>
  );
}

Perbandingan: tus vs Upload Chunked

Fitur	tus	Chunked Kustom
Resumabilitas	Bawaan	Manual
Dukungan server	Banyak opsi	Kustom
Overhead protokol	Lebih tinggi	Lebih rendah
Konfigurasi	Terstandarisasi	Fleksibel
Terbaik untuk	File besar, jaringan tidak stabil	Upload sederhana