fix(ops): la sauvegarde des contrats archivait le mauvais repertoire

OBS-006. Trois racines etaient baties sur os.getcwd() : le magasin de
documents, les journaux et les sauvegardes. La vague G a corrige la
premiere, parce qu'elle bloquait aussi OPS-011, et a laisse les deux autres.
C'est la lecon deja consignee deux fois : un motif fautif corrige dans une
seule couche reste dans les autres.

Le plus serieux n'est pas le motif, c'est l'ecart qu'il a ouvert.
backup.py gardait sa propre constante DOCUMENTS_DIR sur os.getcwd(), donc
il ignorait DOCUMENTS_ROOT -- la variable que la vague G a introduite et que
docs/deployment.md dit maintenant de regler pour sortir les televersements
des repertoires de version. Des qu'un exploitant suit cette consigne, le
script archive un repertoire ou l'application n'a jamais rien ecrit. Et
comme il repond a un repertoire absent par une ligne d'information et un
code de sortie 0, une tache planifiee qui surveille le code de sortie voit
vert indefiniment.

Autrement dit : plus l'exploitant suivait correctement la documentation de
deploiement, plus surement ses sauvegardes de contrats etaient vides.

Les trois racines viennent desormais d'app/storage.py, resolues a l'appel et
non a l'import, et la sauvegarde imprime la source qu'elle a utilisee. Le
message d'absence nomme le chemin ou elle a cherche : "No documents
directory found" se lisait comme "il n'y a pas de documents" plutot que
comme "je regarde au mauvais endroit".

Le test qui porte est celui qui ouvre l'archive : un zip vide est un fichier
de taille non nulle, donc verifier qu'un fichier a ete produit ne prouvait
rien. Verifie par mutation.

Co-Authored-By: Claude Opus 5 <[email protected]>

app/.env.example

@@ -95,8 +95,37 @@ DISCORD_REDIRECT_URI=https://your-domain/auth/discord/callback
 # application. Set it to a path OUTSIDE the deployment directory if you move
 # to a release-directory layout, or a deployment will take the documents with
 # it (OPS-011, app/storage.py).
+#
+# IMPORTANT: the backup script reads this same variable. Before wave J it
+# did not, and archived `./documents` regardless — so setting this here and
+# nowhere else produced empty contract backups that still exited 0.
 DOCUMENTS_ROOT=
 
+# Where the log files go. Empty means `logs/` beside the application. Both
+# defaults are anchored on the application, not on the directory the process
+# was started from, which is what they used to be (OBS-006).
+LOG_DIR=
+
+# Where the backup script writes its archives. Empty means `backups/` beside
+# the application.
+BACKUP_DIR=
+
+# =============================================================================
+# Optional — rate limiting
+# =============================================================================
+
+# Where the rate limiter keeps its counters. Empty means `memory://`, which
+# is correct for a single Waitress process and is what this deployment runs.
+#
+# Set it to a shared backend (redis://…) BEFORE running more than one worker:
+# in-memory counters are per-process, so N workers let through N times every
+# configured limit, with nothing to show for it in the logs.
+#
+# Note that shared storage does not by itself make the limits sound: they are
+# keyed on the client IP, which is forgeable until TRUSTED_PROXY is set
+# correctly (SEC-WEB-002 / OPS-002 — see above).
+RATELIMIT_STORAGE_URI=
+
 # Tables are created at startup when missing. Set to false once Alembic owns
 # the schema (DB-002/DB-004): create_all() never ALTERs, so a column added to
 # a model is silently absent from an existing database.

app/logging_config.py

@@ -14,6 +14,8 @@ import os
 import re
 from logging.handlers import RotatingFileHandler
 
+from app.storage import logs_root
+
 #: Value used when a record is emitted outside a request — startup, the
 #: Discord bot thread, the scheduler. Short and obviously not an id, so a
 #: grep for one never matches it by accident.
@@ -117,7 +119,12 @@ def configure_logging(app):
     Args:
         app: The Flask application instance to configure logging for.
     """
-    log_dir = os.path.join(os.getcwd(), 'logs')
+    # Anchored on the project, not on the working directory (OBS-006). The
+    # old form put the logs wherever the process happened to be started
+    # from, so a service restarted by hand from another directory quietly
+    # began writing somewhere else — and the file you go looking at when
+    # something is wrong is the one that must not move.
+    log_dir = logs_root()
     os.makedirs(log_dir, exist_ok=True)
 
     # Remove default Flask handlers to avoid duplicate logging

app/storage.py

@@ -1,4 +1,13 @@
-"""Where uploaded documents live, and how the database refers to them.
+"""Where the application's files live, and how the database refers to them.
+
+Three roots: the project itself, the document store, and the log directory.
+They are here together because they are the same defect three times over
+(OBS-006) — `os.path.join(os.getcwd(), …)`, evaluated at import or upload
+time, so every one of them moved with whatever directory the process was
+started from. The document store was fixed first, in wave G, because it was
+the one that also blocked OPS-011; the other two were left behind, which is
+the repeated lesson of this project: a faulty pattern corrected in one layer
+stays in the others.
 
 Contracts were stored at `os.path.join(os.getcwd(), 'documents', …)`,
 evaluated at upload time, and the resulting absolute path was written into
@@ -26,21 +35,60 @@ import os
 #: inside whichever one is current.
 DOCUMENTS_ROOT_ENV = 'DOCUMENTS_ROOT'
 
+#: Environment override for the log directory. Same reasoning: a release
+#: directory that carries its own logs loses them at the next switch.
+LOG_DIR_ENV = 'LOG_DIR'
+
+#: Environment override for the backup directory.
+BACKUP_DIR_ENV = 'BACKUP_DIR'
+
 #: Sub-directory holding uploaded contracts, under the document root.
 CONTRACTS_DIR = 'contrats signés'
 
 
+def project_root():
+    """Absolute path of the project, derived from this file's location.
+
+    The anchor every other root falls back to. Not `os.getcwd()`: the
+    process is started by Waitress under Pterodactyl, by pytest, by a task
+    scheduler and by a person in a shell, and only one of those four is
+    reliably in the project directory.
+    """
+    package_dir = os.path.dirname(os.path.abspath(__file__))
+    return os.path.dirname(package_dir)
+
+
 def documents_root():
     """Absolute path of the document store.
 
     Falls back to `documents/` beside this package — the project root
     wherever it is installed, rather than wherever the process was launched.
     """
-    configured = os.getenv(DOCUMENTS_ROOT_ENV)
+    return _rooted(DOCUMENTS_ROOT_ENV, 'documents')
+
+
+def logs_root():
+    """Absolute path of the log directory.
+
+    Was `os.path.join(os.getcwd(), 'logs')`. Starting the server from
+    another directory sent the logs somewhere new without a word, which is
+    the worst possible failure mode for the one file you go and read when
+    something else has gone wrong.
+    """
+    return _rooted(LOG_DIR_ENV, 'logs')
+
+
+def backups_root():
+    """Absolute path of the backup directory."""
+    return _rooted(BACKUP_DIR_ENV, 'backups')
+
+
+def _rooted(env_name, default_name):
+    """The configured path, or `default_name` under the project root."""
+    configured = os.getenv(env_name)
     if configured:
         return os.path.abspath(configured)
-    package_dir = os.path.dirname(os.path.abspath(__file__))
-    return os.path.join(os.path.dirname(package_dir), 'documents')
+    return os.path.join(project_root(), default_name)
 
 
 def discard_documents(stored_paths):

app/supporting_scripts/backup.py

@@ -37,13 +37,33 @@ import sys
 from datetime import datetime, timedelta
 from urllib.parse import unquote, urlparse
 
+# Run as `python app/supporting_scripts/backup.py`, sys.path[0] is this
+# script's directory, so the application package is not importable. It has
+# to be — see DOCUMENTS_DIR below.
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from app.storage import backups_root, documents_root  # noqa: E402 — needs the path above
+
 # Configuration
-BACKUP_DIR = os.getenv('BACKUP_DIR', os.path.join(os.getcwd(), 'backups'))
+BACKUP_DIR = backups_root()
 BACKUP_RETENTION_DAYS = int(os.getenv('BACKUP_RETENTION_DAYS', 30))
-DOCUMENTS_DIR = os.path.join(os.getcwd(), 'documents')
 PG_DUMP = os.getenv('PG_DUMP', 'pg_dump')
 PG_RESTORE = os.getenv('PG_RESTORE', 'pg_restore')
 
+# There is deliberately no DOCUMENTS_DIR constant any more. It held
+# `os.path.join(os.getcwd(), 'documents')`, which had stopped being true:
+# wave G introduced DOCUMENTS_ROOT so a release-directory deployment could
+# keep uploads outside the releases, and docs/deployment.md now tells the
+# operator to set it — at which point this script archived a directory the
+# application had never written to. It does not fail on a missing directory
+# either; it prints "No documents directory found", skips, and exits 0.
+#
+# So the more correctly an operator followed the deployment documentation,
+# the more certainly their contract backups were empty (OBS-006).
+#
+# backup_documents() now asks app.storage, at call time, the same question
+# the upload path asks. One source of truth, and one that a test can move.
+
 
 class BackupError(Exception):
     """Raised when a backup step fails in a way that must stop the run."""
@@ -235,20 +255,31 @@ def verify_backup(backup_path):
 def backup_documents():
     """Archive the uploaded contract documents directory.
 
+    The directory is resolved through `app.storage.documents_root()` — the
+    same function the upload path uses — so that setting DOCUMENTS_ROOT
+    moves both together. Resolved here rather than at import, so that what
+    is backed up depends on the environment the run has, not on the one the
+    module happened to be imported with.
+
     Returns:
         str: Path to the created archive, or None if there is nothing to
         archive. Signed contracts live only on disk, so losing this
         directory loses the documents themselves.
     """
-    if not os.path.exists(DOCUMENTS_DIR):
-        print('[INFO] No documents directory found. Skipping document backup.')
+    documents_dir = documents_root()
+
+    if not os.path.exists(documents_dir):
+        # Says where it looked. The previous message named no path, so an
+        # operator who had moved the documents read it as "there are no
+        # documents" rather than "I am looking in the wrong place".
+        print(f'[INFO] No documents directory at {documents_dir}. Skipping document backup.')
         return None
 
     timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
     archive_basename = os.path.join(BACKUP_DIR, f'documents_backup_{timestamp}')
 
     try:
-        shutil.make_archive(archive_basename, 'zip', DOCUMENTS_DIR)
+        shutil.make_archive(archive_basename, 'zip', documents_dir)
     except Exception as exc:  # noqa: BLE001 — a failed document archive must not lose the dump
         # This runs after the database dump has already succeeded. Letting
         # anything through here would abort the script with a traceback and
@@ -314,6 +345,9 @@ def main(argv=None):
     print('=== Team Tryouts Backup ===')
     print(f'Started at: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}')
     print(f'Backup directory: {BACKUP_DIR}')
+    # Printed because it is the value that was wrong for months without
+    # anyone being able to see it from the output.
+    print(f'Document source: {documents_root()}')
     print(f'Retention period: {BACKUP_RETENTION_DAYS} days')
     print()