v2.2.2 — English-first Palworld reference

Dedicated Server Save Sync v2.2.2

v2.2.2 is a documentation/packaging maintenance release. It makes the public project consistently English-first while preserving a complete Spanish Wiki and backward-compatible Windows entrypoints.

What changed

• English is now canonical for README, Pages, technical docs, maintenance docs, templates and release documentation.
• The GitHub Wiki source is fully bilingual: English Home/FAQ/navigation plus a complete Spanish path beginning at Inicio.
• The Windows package adds English entrypoints:
  • Configure-Secrets.cmd
  • Test-Connection.cmd
  • Start-PalworldSync.cmd
• Existing Spanish .cmd entrypoints remain in the package so old shortcuts and automation continue to work.
• Public navigation is aligned with the companion Ayerdi/PROX2-AutoSwitch project: README → Website → Wiki → Docs/Support/Security → Releases.
• Scope language now explicitly reserves the future multi-game and device/cloud-sync product for a separate successor repository.

Compatibility

There are no intentional changes to:

• the synchronization HTTP API;
• baseVersion or lock semantics;
• saveIdentity / worldGuid rules;
• save or ZIP format;
• SQLite schema (still v3);
• Palworld REST interaction;
• clientVersion=1.2.0.

This is therefore a patch release rather than a feature/minor release.

Release assets

The release publishes:

dedicated-server-save-sync-client-v2.2.2.zip
dedicated-server-save-sync-client-v2.2.2.zip.sha256

The workflow builds the client twice, compares SHA-256 and ZIP bytes, then publishes only if both builds are identical.

v2.2.1 — Durable backup hardening

Dedicated Server Save Sync v2.2.1

v2.2.1 es la release de mantenimiento que cierra el hardening operativo antes de la publicación pública del repositorio.

No cambia el protocolo del cliente, el formato ZIP/save ni el esquema SQLite (permanece en v3). El cambio principal está en cómo se supervisan y retienen los backups externos.

Backup durable independiente de Gunicorn

• pending_backups pasa de marker efímero a cola durable en SQLite.
• Publicar/restaurar una versión y encolar su backup forman el mismo commit SQLite.
• Un sidecar backup-supervisor, independiente del proceso web, consume la cola y ejecuta el hook externo.
• Si cae Gunicorn, el backup continúa.
• Si cae el propio supervisor, la fila permanece y se reintenta al arrancar con semántica at-least-once.
• El comando externo debe permanecer en foreground y ser idempotente o tolerar reintentos.

Crash-safety y retención

La retención de backend y supervisor usa dos fases:

1. confirma en SQLite el resultado, auditoría, marker y retención de metadata;
2. reabre un write-lock, revalida las referencias actuales y solo entonces elimina ZIPs físicos que siguen huérfanos.

Un crash tras el commit puede dejar un ZIP de más, que una reconciliación posterior elimina. No puede provocar que un rollback de SQLite deje metadata apuntando a un ZIP que ya fue borrado por la misma operación de retención.

Las versiones con backup pendiente permanecen protegidas aunque el marker sea antiguo. stalePending queda como señal de observabilidad, no como permiso para borrar la cola.

Supervisor y healthcheck

• Rechaza bases cuyo PRAGMA user_version no coincida exactamente con el esquema soportado.
• El healthcheck exige heartbeat reciente y esquema correcto.
• Si existe cola pendiente pero SAVE_SYNC_POST_PUBLISH_COMMAND está vacío, el supervisor se marca unhealthy.
• Los hooks se ejecutan en un process-group propio; timeout/parada escalan SIGTERM → SIGKILL sobre todo el grupo, incluso si el proceso líder ya terminó.

Restic reproducible

Restic 0.18.0 deja de instalarse desde APT. La imagen descarga los binarios oficiales para amd64/arm64, valida SHA-256 fijados y CI comprueba que la imagen resultante expone exactamente restic 0.18.0.

Despliegue y recuperación

• config/deploy.sh exige que backend y backup-supervisor estén healthy antes de publicar la ruta Traefik.
• Rollback detiene ambos servicios sin borrar datos.
• El stack local/E2E inicializa de forma explícita los permisos del volumen compartido.

Validación

El candidato que introduce este hardening se validó con:

• Ruff;
• checker de documentación;
• 132 tests con 88,38 % de cobertura (mínimo 85 %);
• pip-audit sin vulnerabilidades conocidas;
• Docker Compose y Docker build;
• comprobación de Restic 0.18.0 dentro de la imagen;
• E2E normal;
• E2E que mata el contenedor web durante un backup;
• E2E que mata con SIGKILL el supervisor y exige reintento desde SQLite;
• Pester para el cliente Windows;
• Gitleaks sobre el historial Git.

La CI de main posterior al merge del hardening también quedó completamente verde.

Compatibilidad

No hay cambios deliberados en:

• API pública de sincronización;
• protocolo del cliente Windows;
• formato de saves/ZIP;
• saveIdentity / worldGuid;
• esquema SQLite v3.

El adaptador Palworld sigue identificándose internamente como clientVersion=1.2.0; ese número corresponde al componente Windows y es independiente de la release del producto v2.2.1.

v2.2.0 — Stable Palworld reference release

v2.2.0 — Stable Palworld reference release

Español

v2.2.0 cierra la etapa funcional de Dedicated Server Save Sync como
implementación estable para Palworld.

Novedades

• GET /backup-status y tarjeta de estado de backup en el panel.
• Estado conservador ante markers de backup vencidos.
• Separación visible entre “la versión actual fue respaldada” y “el backup
  automático está habilitado ahora”.
• Último backup correcto sin límite artificial de 500 eventos.
• Degradación segura: un fallo del endpoint de observabilidad no rompe el panel.
• Retención configurable, backup externo post-publicación y auditoría heredados
  de v2.1.1.
• Documentación pública ES/EN, GitHub Pages y fuente versionada para la wiki.

Verificación del HEAD funcional

• 101 tests Python.
• 86,63 % de cobertura.
• Ruff limpio.
• pip-audit sin vulnerabilidades conocidas.
• Docker build y E2E correctos.
• Pester correcto en Windows.
• Gitleaks sobre el historial Git.

Artefactos

La release adjunta:

• dedicated-server-save-sync-client-v2.2.0.zip
• dedicated-server-save-sync-client-v2.2.0.zip.sha256

El ZIP se construye de forma determinista. El workflow lo genera dos veces y
compara el SHA-256 antes de publicar.

Alcance

Desde esta release el repositorio entra en mantenimiento: bugs, seguridad,
dependencias y compatibilidad Palworld. Un rediseño multi-juego de mayor alcance
se desarrollará por separado.

---

English

v2.2.0 closes the feature-development phase of Dedicated Server Save Sync as
a stable Palworld reference implementation.

Highlights

• GET /backup-status and an operational backup card in the private panel.
• Conservative state handling for stale backup markers.
• Clear separation between “the current version was backed up” and “automatic
  backups are enabled now”.
• Latest successful backup is no longer limited by a 500-event window.
• Safe degradation: backup observability failures do not break the rest of the
  panel.
• Configurable retention, post-publication external backup and auditing from
  v2.1.1.
• Public Spanish/English documentation, GitHub Pages and versioned wiki source.

Verified functional HEAD

• 101 Python tests.
• 86.63% coverage.
• Clean Ruff run.
• pip-audit with no known vulnerabilities.
• Successful Docker build and isolated E2E.
• Successful Pester run on Windows.
• Gitleaks over Git history.

Assets

The release attaches:

• dedicated-server-save-sync-client-v2.2.0.zip
• dedicated-server-save-sync-client-v2.2.0.zip.sha256

The ZIP is deterministic. The workflow builds it twice and compares the SHA-256
before publication.

Scope

From this release onward the repository is in maintenance mode: bugs, security,
dependency updates and Palworld compatibility. A broader multi-game redesign
will be developed separately.

v2.1.1

v2.1.1 — Save Sync estable

Retención configurable y backup externo tras cada publicación confirmada.

Cambios principales

• SAVE_SYNC_RETENTION_PER_SLOT (defecto 1): conserva N versiones por slot.
• SAVE_SYNC_POST_PUBLISH_COMMAND + SAVE_SYNC_POST_PUBLISH_TIMEOUT_SECONDS:
  backup externo (p. ej. restic) tras publicar, con 201 garantizado aunque
  falle el hook.
• pending_backups atómico (protección contra la retención desde la misma
  transacción de publicación), 409 backup_in_progress en DELETE /history,
  purga stale en cleanup_canonical_versions.
• Timeout con cancelación del grupo de proceso (SIGTERM → SIGKILL); auditoría
  de exitCode/timedOut en backup_hook_completed/backup_hook_failed.
• restic incluido en la imagen Docker (caché excluido del backup).
• SCHEMA_VERSION → 3.

Dependencias y CI

• gunicorn 26, pytest 9.1.1, ruff 0.16 (hashes fijados); checkout v7 y
  setup-python v7 en GitHub Actions.

Verificación

• 96 tests, cobertura 86.27 %, ruff limpio.
• Prueba DR end-to-end realizada: publicación → snapshot restic → pérdida del
  volumen → restauración íntegra del save.