feat: expose delete bucket

[jzunigax2]

What

Adds DELETE /v2/gateway/users/:uuid/buckets/:id?name=<bucket-name>. removes a bucket, its entries, and credits the released bytes back to the user's totalUsedSpaceBytes in one call. Returns UserSpaceSnapshot (200).

Refuses (409) any bucket holding shard-backed entries.

200	bucket, entries and bytes released; returns the snapshot
400	malformed uuid / object id, or missing name
403	bucket belongs to another user
404	unknown user, unknown bucket, or name mismatch
409	bucket holds shard-backed entries. refused, nothing deleted

Why

mail-server is building the purge of suspended mail accounts: a downgraded plan suspends the account today, and 30 days later it has to be destroyed for real —the Stalwart principal, the local tables, and the Bridge storage behind it. Mail
already promises the user a deletionAt date it can't yet act on.

Each mail address owns one Bridge bucket, and Bridge is the only place that can release its entries and the quota they hold. There was no gateway route to do that, so the purge had nothing to call — BridgeClient.deleteMailBucket() on the
mail side was a placeholder pointing at a path Bridge never served. This is the Bridge half of that task; the mail-server client is now moved onto the real route.

The wholesale delete is safe because gateway-minted entries (createEntry) are metadata only: a bucket, a size, a version — nothing downstream. Real uploads always set frame (v1) or index + hmac (v2). That is the discriminator used
throughout, and dropping a shard-backed entry wholesale would strand its shards, mirrors and farmer bytes with nothing left pointing at them — hence the 409.

How

Order of operations:

1. Load user + bucket. 404 unknown user, 404 unknown bucket, 403 wrong owner, 404 if name doesn't match.
2. hasShardBackedEntriesByBucket: countDocuments with limit: 1, O(1) refusal before any scan.
3. summarizeByBucket: one aggregate returning shardBackedCount and metadataOnlyBytes; refuses again if the count is non-zero.
4. deleteMetadataOnlyByBucket: the delete filter itself excludes shard-backed entries, so a mixed bucket cannot strand anything even if every check above were wrong.
5. Single negative $inc on totalUsedSpaceBytes, only when bytes > 0.
6. hasEntriesByBucket: anything left means something was shard-backed: 409, and the bucket document is kept.
7. Remove the bucket document.

[apsantiso]

How are you going to make sure the bucket is the mail one? is there any way you can guarantee that only mail buckets are removed?

[jzunigax2]

that's one of my worries, currently there is a guard that checks for one bucket entry and then checks if it has shards associated. since mail generates none it assumes it is a mail bucket but it is a bit of a fragile check

[sg-gs]

Why do you need this @jzunigax2 ? Please provide a proper description

[jzunigax2]

description

ups sorry @sg-gs , I simply undrafted this. Updated description @sg-gs this is the bride side part of the mail account auto delete task. Involves cleaning up mail created metadata

[apsantiso]

@jzunigax2 Can you add some small comment in the controller so it's cleaner that the EP only deletes entries created from the gateway?

Just so we can remember this later, it's clear if you read the PR but this repo is somehow hard to navigate through so when it gets merged you'll need to dive into the funcions to be able to know what's happening