cleanup object-storage

Purge historical backup objects in the object store according to the remote retention policy of the current project.

OSS is not currently exposed as an independent external capability. The public command usescleanup object-storage; cleanup oss is just a historically compatible alias that has been hidden in the command help and is not recommended for continued use in manuals and new scripts.

Command Format:

peppykeep cleanup object-storage [--force] [--apply] [--config-home <DIR>]

Compatible entrances:

peppykeep cleanup oss [--force] [--apply] [--config-home <DIR>]

Description

• --apply: Perform the cleanup process. Only the dry-run summary is output without this parameter, no object storage is connected, and no remote objects are listed or deleted.
• --force: Really delete the object to be cleaned. Only takes effect when --apply is taken at the same time; when --force is not taken, only the object to be deleted is output in the log even if the cleanup process is entered.
• --config-home<DIR>: configuration directory for reading bak.toml' and prj.toml`.

Configuration Source

• [object_storage] of bak.toml provides object storage connection configuration. The current implementation supportsprovider = "oss"andprovider = "s3".
• The [local] prj_key of ’prj.toml` decides to clean up only the objects under the current project.
• The [remote.retain] of prj.toml determines the retention policy for remote backups.

The object-key scan scope is formed from [object_storage].prefix and prj_key:

<prefix>/<prj_key>/

When prefix is empty, the scan range is:

<prj_key>/

Usage Sample

First review the configuration and action summary:

peppykeep cleanup object-storage --config-home additional/conf/local

Enter the object-storage cleanup flow, but only log the objects that would be deleted; do not delete anything:

peppykeep cleanup object-storage --apply --config-home additional/conf/local

After confirming the objects to delete, perform the deletion:

peppykeep cleanup object-storage --force --apply --config-home additional/conf/local

Cleanup logic

1. Read prj.toml to obtain the current project prj_key and [remote.retain] settings.
2. Read bak.toml and create the object-storage client. The command fails if object storage is disabled or the provider, bucket, or credentials are missing.
3. Calculate the set of dates to retain:
   • Today.
   • Each value in remote.retain.days maps to a historical calendar date.
   • The 1st day of each month for the most recent remote.retain.months months.
   • Each year in remote.retain.years maps to January 1 of that historical year.
4. List objects under <prefix>/<prj_key>/.
5. Parse backup dates from object names. .ppke uses the matching .ppk name; strip .enc before parsing.
6. Objects matching retention dates are kept; others are marked for deletion.
7. When multiple objects match retention on the same day, keep only the newest; others go to the delete list.
8. If pending deletes would drop below remote.retain.minimum_retain_count, clear the delete list.
9. If the object date is within remote.retain.minimum_retain_date_count days of today, keep it—do not delete.
10. Objects whose dates cannot be parsed from backup naming rules go to the manual list; they are not auto-deleted.

Deletion criteria

The object-storage delete API is called only when all of the following conditions are met:

• The command includes --apply.
• The command includes --force.
• The object is within the current project scan scope.
• Object name encodes the backup date.
• Object is not covered by any retention policy.
• Object is not protected by minimum retain count or days.

Objects that do not qualify are kept, marked for deletion, or listed in manual for human review.