dillard
193f65940b
Both live in the catalog on the location, so a new server sees them; the database holds a local copy for the lists. The retention policy leaves a pinned restore point alone and does not count it. Available on the restore page and as occ backup:pin and backup:note.
291 lines
11 KiB
PHP
291 lines
11 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
// SPDX-FileCopyrightText: 2026 Dillard Blom
|
|
// SPDX-License-Identifier: AGPL-3.0-or-later
|
|
|
|
namespace OCA\NgBackup\Service;
|
|
|
|
use OCA\NgBackup\AppInfo\Application;
|
|
use OCA\NgBackup\Db\RunMapper;
|
|
use OCA\NgBackup\Db\SnapshotMapper;
|
|
use OCA\NgBackup\Db\Target;
|
|
use OCA\NgBackup\Repository\Repository;
|
|
use OCP\IAppConfig;
|
|
use OCP\Lock\ILockingProvider;
|
|
use OCP\Lock\LockedException;
|
|
|
|
/**
|
|
* Applies the retention policy to a location: forgets snapshots the policy does not keep and
|
|
* prunes data no remaining snapshot uses. Never runs on append-only locations, never while a
|
|
* backup to the same location is running (the location lock is shared with BackupService).
|
|
*/
|
|
final class PruneService {
|
|
public function __construct(
|
|
private TargetService $targets,
|
|
private RunMapper $runs,
|
|
private SnapshotMapper $snapshots,
|
|
private IAppConfig $appConfig,
|
|
private ILockingProvider $locking,
|
|
private AlertService $alerts,
|
|
private KeyService $keys,
|
|
private LeaseService $leases,
|
|
) {
|
|
}
|
|
|
|
/** Characters of a note on a snapshot (the column holds 1000) */
|
|
public const NOTE_MAX = 500;
|
|
|
|
/** Pin or unpin a snapshot: the retention policy leaves a pinned one alone. */
|
|
public function setPinned(Target $target, string $snapshotId, bool $pinned): void {
|
|
$changed = $this->changeCatalog($target, function (Repository $repo) use ($snapshotId, $pinned): bool {
|
|
$was = in_array($snapshotId, $repo->pinnedSnapshots(), true);
|
|
$repo->setPinned($snapshotId, $pinned);
|
|
return $was !== $pinned;
|
|
});
|
|
$this->targets->syncSnapshot($target, $snapshotId, pinned: $pinned);
|
|
if ($changed) {
|
|
// Unpinning opens the way to removing it, so every administrator hears about that.
|
|
$this->alerts->securityEvent($pinned ? 'snapshot_pinned' : 'snapshot_unpinned', ['target' => $target->getName(), 'snapshot' => $snapshotId], !$pinned);
|
|
}
|
|
}
|
|
|
|
public function setNote(Target $target, string $snapshotId, string $note): void {
|
|
$note = trim((string)preg_replace('/[\x00-\x1f\x7f]+/', ' ', $note));
|
|
if (!mb_check_encoding($note, 'UTF-8')) {
|
|
throw new \InvalidArgumentException('A note must be valid UTF-8');
|
|
}
|
|
if (mb_strlen($note) > self::NOTE_MAX) {
|
|
throw new \InvalidArgumentException('A note has at most ' . self::NOTE_MAX . ' characters');
|
|
}
|
|
$this->changeCatalog($target, function (Repository $repo) use ($snapshotId, $note): bool {
|
|
$repo->setSnapshotNote($snapshotId, $note);
|
|
return true;
|
|
});
|
|
$this->targets->syncSnapshot($target, $snapshotId, note: $note);
|
|
}
|
|
|
|
/**
|
|
* Write to the catalog next to a running backup or restore, which only takes it for a moment to
|
|
* commit. Not during a cleanup, which holds a repository opened earlier and writes from that.
|
|
*
|
|
* @param callable(Repository): bool $change
|
|
*/
|
|
private function changeCatalog(Target $target, callable $change): bool {
|
|
try {
|
|
return $this->leases->with(self::lockKey($target), LeaseService::SHARED, 300,
|
|
fn (): bool => $this->leases->with(self::catalogLockKey($target), LeaseService::EXCLUSIVE, 300,
|
|
fn (): bool => $change($this->targets->repository($target))));
|
|
} catch (LockedException) {
|
|
throw new \RuntimeException('A cleanup of ' . $target->getName() . ' or another change to its restore points is in progress; try again later');
|
|
}
|
|
}
|
|
|
|
public function untrash(Target $target, string $snapshotId): void {
|
|
$lease = $this->lockExclusive($target, 300);
|
|
try {
|
|
$this->doUntrash($target, $snapshotId);
|
|
} finally {
|
|
$this->leases->release($lease);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Run $fn under the location's exclusive lock (to create a run atomically with respect to a
|
|
* cleanup, which takes the same lock and then refuses while a run exists).
|
|
*/
|
|
public function underStartLock(Target $target, callable $fn): mixed {
|
|
try {
|
|
return $this->leases->with(self::lockKey($target), LeaseService::EXCLUSIVE, 60, fn () => $fn());
|
|
} catch (LockedException) {
|
|
throw new \RuntimeException('A cleanup of ' . $target->getName() . ' is in progress; try again later');
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Exclusive lock on the location, then make sure no run of any kind (backup, restore, export)
|
|
* is in progress: their data may not be referenced by a snapshot yet, or is being read.
|
|
*/
|
|
private function lockExclusive(Target $target, int $ttl): string {
|
|
try {
|
|
$lease = $this->leases->acquire(self::lockKey($target), LeaseService::EXCLUSIVE, $ttl);
|
|
} catch (LockedException) {
|
|
throw new \RuntimeException('A backup, restore or cleanup of ' . $target->getName() . ' is in progress; try again later');
|
|
}
|
|
if ($this->runs->findRunning($target->getId()) !== []) {
|
|
$this->leases->release($lease);
|
|
throw new \RuntimeException('A backup or restore of ' . $target->getName() . ' is running; try again later');
|
|
}
|
|
return $lease;
|
|
}
|
|
|
|
private function doUntrash(Target $target, string $snapshotId): void {
|
|
$repo = $this->targets->repository($target);
|
|
if (!array_key_exists($snapshotId, $repo->trash())) {
|
|
throw new \InvalidArgumentException('That snapshot is not in the trash (or was already deleted)');
|
|
}
|
|
$repo->untrash($snapshotId);
|
|
// Put it back in the local snapshot list as well.
|
|
$meta = $repo->snapshotMeta($snapshotId);
|
|
$s = new \OCA\NgBackup\Db\Snapshot();
|
|
$s->setTargetId($target->getId());
|
|
$s->setSnapshotId($snapshotId);
|
|
$s->setKind((string)($meta['kind'] ?? 'full'));
|
|
$s->setLabel(($meta['label'] ?? '') !== '' ? $meta['label'] : null);
|
|
$s->setCreatedAt((int)strtotime((string)($meta['time'] ?? 'now')));
|
|
$s->setFiles((int)($meta['stats']['files'] ?? 0));
|
|
$s->setBytes((int)($meta['stats']['bytes'] ?? 0));
|
|
$s->setNote($repo->snapshotNotes()[$snapshotId] ?? null);
|
|
try {
|
|
$this->snapshots->insert($s);
|
|
} catch (\Throwable) {
|
|
}
|
|
$this->alerts->securityEvent('snapshot_untrashed', ['target' => $target->getName(), 'snapshot' => $snapshotId]);
|
|
}
|
|
|
|
public static function lockKey(Target $target): string {
|
|
return 'ng_backup/target/' . $target->getId();
|
|
}
|
|
|
|
/**
|
|
* A separate, short-lived exclusive lock serializing writes to the catalog itself. The
|
|
* per-target lock above only keeps readers/writers out while a cleanup runs; it does not
|
|
* stop two SHARED holders (e.g. two concurrent per-user backups, or one alongside a full
|
|
* backup) from both reading the same catalog generation and racing to write the next one,
|
|
* silently dropping whichever's change loses. The full-backup path avoids this today only
|
|
* because a Run row makes concurrent runs for the same target mutually exclusive; per-user
|
|
* backup/restore has no such row, so it takes this lock around the catalog write itself.
|
|
*/
|
|
public static function catalogLockKey(Target $target): string {
|
|
return self::lockKey($target) . '/catalog';
|
|
}
|
|
|
|
/** How many of each user's own exports (occ backup:user:backup) to keep, newest first. */
|
|
public function userExportRetention(): int {
|
|
return $this->appConfig->getValueInt(Application::APP_ID, 'user_export_retention', 3);
|
|
}
|
|
|
|
public function setUserExportRetention(int $keep): void {
|
|
if ($keep < 1) {
|
|
throw new \InvalidArgumentException('Keep at least the last export');
|
|
}
|
|
$old = $this->userExportRetention();
|
|
$this->appConfig->setValueInt(Application::APP_ID, 'user_export_retention', $keep);
|
|
if ($old !== $keep) {
|
|
$this->alerts->securityEvent('user_export_retention_changed', ['keep' => (string)$keep]);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Forgets a user's older exports once more than userExportRetention() exist for them,
|
|
* newest first; no trash, unlike a full snapshot (occ backup:user:backup is on-demand, not
|
|
* yet the primary safety net the deletion delay protects).
|
|
*
|
|
* @return array{kept: array<string, list<string>>, forgotten: list<string>}
|
|
*/
|
|
public function applyUserExports(Target $target, bool $dryRun = false): array {
|
|
if ($target->getAppendOnly()) {
|
|
throw new \RuntimeException('Location ' . $target->getName() . ' is append-only: NG Backup does not delete anything there');
|
|
}
|
|
$lease = $this->lockExclusive($target, 1800);
|
|
try {
|
|
$repo = $this->targets->repository($target);
|
|
$keep = $this->userExportRetention();
|
|
$byUser = [];
|
|
foreach ($repo->listUserExports() as $path) {
|
|
$uid = explode('/', $path)[1] ?? '';
|
|
$manifest = json_decode($repo->getObject($path), true, 512, JSON_THROW_ON_ERROR);
|
|
$byUser[$uid][$path] = (int)strtotime((string)($manifest['time'] ?? '@0'));
|
|
}
|
|
$kept = [];
|
|
$forget = [];
|
|
foreach ($byUser as $uid => $times) {
|
|
arsort($times);
|
|
$i = 0;
|
|
foreach (array_keys($times) as $path) {
|
|
if ($i++ < $keep) {
|
|
$kept[$uid][] = $path;
|
|
} else {
|
|
$forget[] = $path;
|
|
}
|
|
}
|
|
}
|
|
if (!$dryRun) {
|
|
foreach ($forget as $path) {
|
|
$repo->forgetUserExport($path);
|
|
}
|
|
if ($forget !== []) {
|
|
$this->alerts->securityEvent('user_exports_forgotten', ['target' => $target->getName(), 'count' => (string)count($forget)], false);
|
|
}
|
|
}
|
|
return ['kept' => $kept, 'forgotten' => $forget];
|
|
} finally {
|
|
$this->leases->release($lease);
|
|
}
|
|
}
|
|
|
|
public function policy(): RetentionPolicy {
|
|
return RetentionPolicy::fromArray(json_decode($this->appConfig->getValueString(Application::APP_ID, 'retention', '{}'), true) ?: []);
|
|
}
|
|
|
|
public function setPolicy(RetentionPolicy $policy): void {
|
|
if ($policy->last < 1) {
|
|
throw new \InvalidArgumentException('Keep at least the last snapshot');
|
|
}
|
|
$old = $this->policy()->toArray();
|
|
$this->appConfig->setValueString(Application::APP_ID, 'retention', json_encode($policy->toArray(), JSON_THROW_ON_ERROR));
|
|
if ($old !== $policy->toArray()) {
|
|
$this->alerts->securityEvent('retention_changed', ['policy' => json_encode($policy->toArray())]);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Snapshots the policy drops go to the trash on the location; trash entries older than the
|
|
* deletion delay are purged, and only then is their data freed.
|
|
*
|
|
* @return array{kept: array<string, list<string>>, forgotten: list<string>, purged: list<string>, prune: array}
|
|
*/
|
|
public function apply(Target $target, bool $dryRun = false, bool $scheduled = false): array {
|
|
if ($target->getAppendOnly()) {
|
|
throw new \RuntimeException('Location ' . $target->getName() . ' is append-only: NG Backup does not delete anything there');
|
|
}
|
|
$lease = $this->lockExclusive($target, 1800);
|
|
try {
|
|
$repo = $this->targets->repository($target);
|
|
$times = [];
|
|
foreach ($repo->listSnapshots() as $id) {
|
|
$meta = $repo->snapshotMeta($id);
|
|
$times[$id] = (int)strtotime((string)($meta['time'] ?? '@0'));
|
|
}
|
|
$keep = $this->policy()->keepWithPinned($times, $repo->pinnedSnapshots());
|
|
$forget = array_values(array_diff(array_keys($times), array_keys($keep)));
|
|
$actor = $scheduled ? 'retention policy' : $this->alerts->actor();
|
|
$purged = [];
|
|
if (!$dryRun) {
|
|
foreach ($forget as $id) {
|
|
$repo->forget($id, $actor);
|
|
try {
|
|
$this->snapshots->delete($this->snapshots->findOne($target->getId(), $id));
|
|
} catch (\Throwable) {
|
|
}
|
|
}
|
|
}
|
|
// Also removes leftovers of interrupted runs. A dry run counts the snapshots it would forget as gone.
|
|
$delay = $this->keys->deleteDelayDays();
|
|
if (!$dryRun && $forget !== []) {
|
|
// Scheduled cleanup follows the policy: audit log only, no notification every week.
|
|
$this->alerts->securityEvent('snapshots_forgotten', ['target' => $target->getName(), 'count' => (string)count($forget),
|
|
'until' => date('Y-m-d', time() + $delay * 86400)], !$scheduled);
|
|
}
|
|
if (!$dryRun) {
|
|
$purged = $repo->purgeTrash($delay * 86400);
|
|
}
|
|
$prune = $repo->prune($dryRun);
|
|
return ['kept' => $keep, 'forgotten' => $forget, 'purged' => $purged, 'prune' => $prune];
|
|
} finally {
|
|
$this->leases->release($lease);
|
|
}
|
|
}
|
|
}
|