Trash and restore

Deleted objects stay recoverable for 30 days, until you purge them or the daily sweep does.

Deleting an object moves it to the bucket's trash instead of removing the bytes. It stays there, restorable, for 30 days.

Deleting and restoring an object

import { GigadriveClient } from '@gigadrive/sdk';

const client = new GigadriveClient({
  applicationId: '0197b2f1-2f4a-7a0b-8a2d-222222222222',
});

const object = await client.storage.objects.getByKey('user-uploads', 'avatars/user-123.png', {
  environment: 'production',
});
if (!object) throw new Error('No such object');

// Soft delete: the object leaves the listing and lands in the trash.
await client.storage.objects.delete('user-uploads', object.id, { environment: 'production' });

// Changed your mind, within the retention window.
const restored = await client.storage.trash.restore('user-uploads', object.id, {
  environment: 'production',
});
console.log(restored.key);

Deleting needs the network:storage_objects:delete scope and restoring needs network:storage_objects:write. The object keeps its ID in the trash, which is what you restore and purge it by.

What counts as a delete

Every delete path is a soft delete: the console, the REST route, objects.delete() in the SDK, and DeleteObject and DeleteObjects through the S3-compatible API. An S3 client that deletes a thousand objects has filled the trash with a thousand objects.

The console has a trash view per bucket and one for the whole environment, so you can find a file without remembering which bucket it was in.

Trashed objects are still stored bytes

Their content stays on disk so it can be restored, and it is billed as stored until it is purged. Emptying the trash after a large cleanup is what actually reduces the bill.

Restoring

A restore is a metadata change, so it is instant regardless of file size, and the content is byte for byte what it was.

It fails with a 409 when a live object already occupies the key, because a restore never overwrites. Delete or rename the newer object, then restore again.

Purging

Purging is the permanent version, with no undo.

Operation	Effect
Purge one object	Removes that object from the trash
Empty the trash	Purges the bucket's trash in batches and returns how many were purged

The bytes go once nothing else points at them. Two objects uploaded with identical content share one stored copy, and a backup that names the file holds a reference of its own, so a purge removes the object while the content stays for whatever still refers to it.

The daily sweep

Every day at 03:45 UTC, Gigadrive Network purges trashed objects that are past the 30 day window. Nothing warns you first, so restore what you want to keep while the days are still on the clock.

Deleting a bucket purges its trash as part of the delete. The bucket has to have no live objects first, which is covered in Buckets.