---
name: rotate_backups
kind: function
lang: bash
domain: infra
version: "1.0.0"
purity: impure
signature: "rotate_backups(dir: string, new_file: string, daily: int, weekly: int, monthly: int) -> string"
description: "Aplica retention policy estilo rsnapshot (daily/weekly/monthly) sobre un directorio de backups. Mueve el backup recien creado a daily.0, desplaza los anteriores y promueve a weekly/monthly al fin de periodo."
tags: ["backup", "rotate", "retention"]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: dir
    desc: "Directorio donde viven los backups. Se crea si no existe."
  - name: new_file
    desc: "Ruta al backup recien creado. Se mueve dentro de dir como daily.0."
  - name: daily
    desc: "Numero de slots diarios a conservar. Por defecto 7."
  - name: weekly
    desc: "Numero de slots semanales a conservar (promovidos cada domingo). Por defecto 4."
  - name: monthly
    desc: "Numero de slots mensuales a conservar (promovidos el dia 1 de cada mes). Por defecto 12."
output: "Linea ROTATED daily=<N> weekly=<N> monthly=<N> dir=<dir> en stdout con el conteo de slots ocupados tras la rotacion. Exit code != 0 en error (1: new_file no existe, 2: dir no se puede crear, 3: argumento numerico invalido)."
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/infra/rotate_backups.sh"
---

## Ejemplo

```bash
source bash/functions/infra/rotate_backups.sh

rotate_backups ~/backups/registry /tmp/registry-snap.db 7 4 12
# ROTATED daily=1 weekly=0 monthly=0 dir=/root/backups/registry

# Con key=value
rotate_backups ~/backups/pg /tmp/pg-dump.sql daily=7 weekly=4 monthly=12
```

## Notas

Estilo rsnapshot: los slots se numeran desde 0 (mas reciente). El algoritmo aplica rotaciones en orden inverso para no sobreescribir:

1. **Monthly** (dia 1): copia `weekly.<weekly-1>` → `monthly.0` antes de desplazar, borra el mas viejo.
2. **Weekly** (domingo): copia `daily.<daily-1>` → `weekly.0` antes de desplazar, borra el mas viejo.
3. **Daily** (siempre): borra `daily.<daily-1>`, desplaza daily.i → daily.i+1, mueve new_file → daily.0.

La promocion weekly y monthly se ejecuta ANTES de la rotacion daily para que `daily.<daily-1>` y `weekly.<weekly-1>` aun existan cuando se necesitan. Sin dependencias externas — solo `mv`, `rm`, `cp`, `mkdir`, `date`.

Los slots pueden ser archivos o directorios (caller decide el formato del backup).