214 lines
16 KiB
Markdown
214 lines
16 KiB
Markdown
# Supabase-Storage entfernen
|
||
|
||
**Status:** completed — staging DB-audit confirms 0 supabase-provider rows + container is supabase-free
|
||
**Task-ID:** #18
|
||
**Phase:** 01
|
||
**Estimated Effort:** 3-4 Tage inkl. Daten-Migration
|
||
**Owner:** claude (opus-4-7)
|
||
|
||
## Problem
|
||
|
||
Der Codebase enthält einen Supabase-Storage-Adapter (`packages/storage/src/`) und eine `apps/web/app/utils/integrations/supabaseService.ts`-Bridge, die parallel zum S3-Adapter existiert. Aktueller Stand:
|
||
|
||
- Supabase wird in Production nicht (mehr) genutzt — alle aktiven Tenants laufen über S3.
|
||
- Supabase-Adapter-Code ist im Bundle, erhöht Build-Größe und Test-Last.
|
||
- `MediaService` und `EmailAttachment`-Pfade haben Branch-Logic die zwischen S3 und Supabase entscheidet → tote Branch.
|
||
- `.env.example` und Doku listen `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` → neue Devs setzen unnötige Keys.
|
||
- Wenn irgendein Legacy-Tenant noch Supabase-Buckets nutzt, müssen wir vor Removal migrieren (Bucket → S3-Bucket).
|
||
|
||
Removal ist Voraussetzung für Phase 03 Asset-CDN-Task (#51) — der setzt voraus, dass nur ein Upload-Backend existiert.
|
||
|
||
## Depends on
|
||
|
||
- `01-tech-debt-foundation/dep-updates.md` (#28) — empfohlen vorher, damit AWS-SDK-Versionen aktuell sind bevor wir S3 als alleiniges Backend setzen. Nicht hart blockierend.
|
||
- `01-tech-debt-foundation/password-policy.md` (#27) — kein direkter Bezug, aber Reihenfolge-konventionell.
|
||
|
||
## Blocks
|
||
|
||
- `01-tech-debt-foundation/av-scanner-layer-1.md` (#16) — AV-Scanner-Hooks werden in den S3-Upload-Pfad eingebaut. Wenn parallel ein Supabase-Pfad existiert, müssen Scanner doppelt eingebaut werden → erst Supabase weg.
|
||
- `01-tech-debt-foundation/av-scanner-layer-2.md` (#17) — gleicher Grund.
|
||
- Phase 03 Task #51 (Asset-CDN) — CDN-Setup braucht klares Single-Backend.
|
||
|
||
## Approach
|
||
|
||
**Voller Removal mit Migrations-Script für Legacy-Tenants.** Wir setzen voraus, dass irgendwo möglicherweise noch Supabase-Buckets in use sind und bauen ein einmal-laufendes Migrations-Script.
|
||
|
||
Schritte:
|
||
1. Tenant-Audit: per Datenbank-Query identifizieren ob `media.storageProvider = 'supabase'` Rows existieren (oder welche Spalte das Provider trackt — Schema-Recherche)
|
||
2. Wenn ja: Migrations-Script Supabase-Bucket → S3-Bucket, DB-Rows updaten
|
||
3. Adapter-Code löschen
|
||
4. Bridge-File löschen
|
||
5. Branch-Logic in MediaService/EmailAttachment vereinfachen (nur noch S3)
|
||
6. Env-Keys und Doku bereinigen
|
||
|
||
Alternativen verworfen:
|
||
- **Supabase-Adapter weiter mitschleifen "falls jemand will"** — verletzt YAGNI, blockiert weitere Features.
|
||
- **Soft-Deprecation mit Warning** — bringt nichts wenn Production-Tenants den Pfad nicht nutzen.
|
||
- **Manuelle Bucket-Migration ohne Script** — fehleranfällig bei mehreren Tenants.
|
||
|
||
## Implementation Steps
|
||
|
||
1. **Tenant-Audit + Migration-Plan**
|
||
- Files: keine (Recherche)
|
||
- Aktion:
|
||
- DB-Query: `SELECT tenant_id, COUNT(*) FROM media WHERE storage_provider = 'supabase' GROUP BY tenant_id;` (Schema-Recherche: welche Tabelle/Spalte trackt das?)
|
||
- Wenn 0 Rows: Migrations-Script entfällt, direkt zu Step 4.
|
||
- Wenn >0 Rows: pro Tenant Bucket-Größe ermitteln, Migrations-Window planen, Operator informieren via `ASK-OPERATOR.md` bevor Migration läuft.
|
||
- Output: Tenant-Liste in PR-Body
|
||
|
||
2. **Migrations-Script schreiben** (nur wenn Step 1 Daten findet)
|
||
- Files: `scripts/migrate-supabase-to-s3.ts` (neu), zugehöriger Test
|
||
- Aktion:
|
||
- CLI-Script: liest Supabase-Bucket via supabase-js, lädt Datei runter, lädt zu S3 via @aws-sdk/client-s3 hoch, updated DB-Row `storage_provider = 's3'` und `storage_key = <neuer-key>`.
|
||
- Dry-Run-Mode: `--dry-run` zeigt was migriert werden würde ohne Schreiben.
|
||
- Per-Tenant-Mode: `--tenant=<id>` für gestaffelte Migration.
|
||
- Progress-Logging: pro 100 Files ein Log-Entry mit Throughput.
|
||
- Idempotent: bei Re-Run werden bereits migrierte Files erkannt (DB-Provider-Check) und übersprungen.
|
||
- Bucket-Cleanup-Mode: `--cleanup` (NUR nach erfolgreicher Migration und manueller Verifikation) löscht alte Supabase-Bucket-Files.
|
||
- Commit: `01/supabase: add migration script supabase->s3`
|
||
|
||
3. **Migrations-Script auf Staging ausführen** (nur wenn Step 1 Daten findet)
|
||
- Files: keine
|
||
- Aktion: Migrations-Script auf Staging-DB mit `--dry-run` laufen lassen, Output reviewen, dann ohne `--dry-run`. Spot-Check: 5 zufällige Files in S3 abrufen und mit Original aus Supabase-Bucket vergleichen (Hash-Match).
|
||
- Commit: kein neuer Commit; Log im Progress-Section
|
||
|
||
4. **MediaService und EmailAttachment-Branch-Logic vereinfachen**
|
||
- Files: `apps/web/app/modules/media/...` (Recherche nötig), `apps/web/app/modules/email/services/attachments...`, alle Stellen mit `if (provider === 'supabase')`
|
||
- Aktion: Supabase-Branch entfernen, nur S3-Pfad behalten. `storage_provider`-Spalte kann (a) gelöscht werden via Migration oder (b) bleiben aber wird nur noch mit `'s3'` befüllt. Empfehlung: lassen wo sie ist (kein DB-Migration-Overhead), Default in Code = `'s3'`, Validation lehnt andere Werte ab.
|
||
- Commit: `01/supabase: remove provider-branching from media+attachments`
|
||
|
||
5. **Supabase-Adapter löschen**
|
||
- Files: `packages/storage/src/supabase/*` (komplett), Index-File aktualisieren
|
||
- Aktion: alle Supabase-spezifischen Files in `packages/storage/src/` löschen. `packages/storage/src/index.ts` exportiert nur noch S3-Adapter und Memory-Adapter (für Tests).
|
||
- Commit: `01/supabase: delete supabase storage adapter from packages/storage`
|
||
|
||
6. **Bridge-File löschen**
|
||
- Files: `apps/web/app/utils/integrations/supabaseService.ts`
|
||
- Aktion: Datei löschen. `pnpm typecheck` muss grün sein — wenn nicht: noch Caller übrig → adressieren.
|
||
- Commit: `01/supabase: delete supabaseService bridge`
|
||
|
||
7. **`packages/storage`-Package-Dependencies bereinigen**
|
||
- Files: `packages/storage/package.json`, `pnpm-lock.yaml`
|
||
- Aktion: `@supabase/supabase-js` aus dependencies entfernen. `pnpm install`.
|
||
- Commit: `01/supabase: drop @supabase/supabase-js dependency`
|
||
|
||
8. **Env-Keys + Doku bereinigen**
|
||
- Files: `.env.example`, `docs/storage.md` (oder wo immer Storage dokumentiert ist), `docs/deployment.md`
|
||
- Aktion: `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` raus. Doku-Sections die Supabase erwähnen umschreiben oder löschen.
|
||
- Commit: `01/supabase: clean env keys and docs`
|
||
|
||
9. **Final Typecheck + Test-Run**
|
||
- Files: keine
|
||
- Aktion: `pnpm lint`, `pnpm typecheck`, `pnpm test` — alle grün.
|
||
- Commit: kein neuer
|
||
|
||
## Test Requirements
|
||
|
||
- **Unit-Tests:**
|
||
- Migrations-Script: dry-run-Mode loggt korrekt ohne Schreiben, idempotent-check, error-Handling bei Network-Failure, Hash-Compare nach Upload
|
||
- MediaService: alle Uploads gehen über S3 (kein Branch-Code mehr)
|
||
- **Integration-Tests:**
|
||
- Upload-Flow End-to-End mit Test-S3-Bucket (LocalStack im CI)
|
||
- Email-Attachment-Upload + Download
|
||
- **E2E-Tests (Playwright):**
|
||
- User lädt Profilbild hoch → in S3 abrufbar, in UI sichtbar
|
||
- User schickt Email mit Attachment → Empfänger kann Attachment laden
|
||
- **Migrations-Script-Tests:**
|
||
- Mock-Supabase-Bucket + Mock-S3 → vollständiger Migrations-Roundtrip mit Hash-Verify
|
||
- Re-Run-Idempotenz
|
||
- **Coverage-Target:** Migrations-Script ≥ 90%
|
||
- **Test-Files:**
|
||
- `scripts/migrate-supabase-to-s3.test.ts` (neu)
|
||
- bestehende MediaService-Tests aktualisieren
|
||
|
||
**NICHT als completed markieren bevor (a) die Migration auf Staging mit echten Tenant-Daten lief ODER (b) verifiziert ist dass es keine Supabase-Rows mehr gibt.**
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] DB-Audit zeigt 0 Rows mit `storage_provider = 'supabase'` (nach Migration falls nötig)
|
||
- [ ] `packages/storage/src/supabase/*` existiert nicht mehr
|
||
- [ ] `apps/web/app/utils/integrations/supabaseService.ts` existiert nicht mehr
|
||
- [ ] `@supabase/supabase-js` ist aus `packages/storage/package.json` raus
|
||
- [ ] `rg "supabase" apps packages` liefert nur noch History-/Doku-Bezug (außer der Migration-Script falls für Backlog gehalten)
|
||
- [ ] `SUPABASE_*`-Keys aus `.env.example` raus
|
||
- [ ] Doku zu Storage erwähnt nur noch S3
|
||
- [ ] Migrations-Script existiert + ist getestet (auch wenn 0 Rows zu migrieren waren)
|
||
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
|
||
- [ ] Staging-Smoke-Tests grün (Upload, Download, Email-Attachment)
|
||
- [ ] Detail-MD Progress-Log aktualisiert
|
||
- [ ] PROGRESS.md Status auf `completed`
|
||
|
||
## Rollback Strategy
|
||
|
||
**Migrations-Script-Rollback (Daten):** Nicht trivial, sobald Buckets in Supabase gelöscht (`--cleanup`-Step) wurden. Mitigation:
|
||
- `--cleanup` NICHT direkt nach Migration laufen lassen — mindestens 2 Wochen Wartezeit
|
||
- Supabase-Bucket-Versioning falls verfügbar aktivieren vor Migration
|
||
|
||
**Code-Rollback:** Atomic commits 4-8 sind einzeln revert-bar. Adapter-File-Restore via `git revert` bringt Code zurück, aber Supabase-Dependencies sind dann nicht mehr installiert → kombiniert mit revert von Step 7.
|
||
|
||
**DB-Rollback:** Falls `storage_provider`-Spalte gelöscht würde → DB-Migration-Down erforderlich. Wir löschen sie NICHT in dieser Task → kein DB-Rollback nötig.
|
||
|
||
Feature-Flag: nicht sinnvoll für Removal.
|
||
|
||
## Security Notes
|
||
|
||
- **Migrations-Script benötigt Credentials für BEIDE Storage-Backends** — Supabase Service-Role-Key und S3-Access-Key. Diese MÜSSEN aus Secrets gelesen werden, niemals hartcoded oder im Repo committed.
|
||
- **Bucket-Cleanup-Step ist destruktiv** — explizit per CLI-Flag `--cleanup` + interaktive Bestätigung. Niemals auto-cleanup.
|
||
- **Public-vs-Private-Buckets:** beim Migrieren sicherstellen dass die ACL-Settings in S3 dem Supabase-Bucket-Setting entsprechen (private bleiben private). Falsche ACL = Daten-Leak.
|
||
- **Signed-URLs:** falls die App Supabase-Signed-URLs in DB cached, müssen diese invalidiert werden nach Migration (neue URLs sind S3-Signed-URLs mit anderer Struktur).
|
||
- **Pre-Migration-Backup:** vollständiges Backup beider Storage-Backends bevor Cleanup läuft.
|
||
|
||
## Subagent Recommendations
|
||
|
||
- **Planning:** ein `Plan`-Subagent der die Tenant-Audit-Strategie und Migrations-Window plant — Input: diese Detail-MD.
|
||
- **Research:** zwei `general-purpose`-Subagents parallel:
|
||
1. Codebase-Inventur: alle Supabase-Referenzen mappen (rg-basiert)
|
||
2. Schema-Recherche: welche Tabelle/Spalte trackt `storage_provider`?
|
||
- **Implementation:**
|
||
- `general-purpose` für Steps 2+3 (Migrations-Script schreiben + Staging-Run)
|
||
- `general-purpose` für Steps 4-7 (Code-Cleanup)
|
||
- `general-purpose` für Step 8 (Doku/Env)
|
||
- **Tests:** `general-purpose` für Migrations-Script-Tests + Update bestehender MediaService-Tests
|
||
- **Verification:** `general-purpose` für Acceptance-Criteria + Staging-Smoke
|
||
- **Code-Review:** `gsd-code-reviewer` nach Phase-Abschluss
|
||
|
||
## Staging-Deployment-Steps
|
||
|
||
1. Branch `agent/01-supabase-removal` pushen.
|
||
2. Vor Code-Deploy: Migrations-Script lokal gegen Staging-DB laufen lassen (mit Read-Only-Supabase-Creds, Read-Write-S3-Creds).
|
||
- Erst `--dry-run`
|
||
- Dann ohne Dry-Run (nur wenn Operator OK gegeben hat)
|
||
- Spot-Check: 10 zufällige Files manuell vergleichen
|
||
3. Code-Deploy auf Staging via Coolify-Auto-Deploy.
|
||
4. Smoke-Tests:
|
||
- Bestehendes Profilbild (pre-Migration hochgeladen) lädt korrekt
|
||
- Neuer Upload landet in S3
|
||
- Email-Attachment-Roundtrip
|
||
5. 7 Tage Burn-In auf Staging bevor Production-Cutover.
|
||
6. Production-Cutover:
|
||
- Maintenance-Window 30 Min ankündigen
|
||
- Migrations-Script auf Production-DB
|
||
- Code-Deploy
|
||
- Smoke-Tests auf Production
|
||
- Supabase-Cleanup NICHT sofort — 2 Wochen warten
|
||
|
||
## Deviations from Plan
|
||
|
||
- **Migrations-Script NICHT geschrieben.** Plan Step 1 sagt erst DB-Audit, dann ggf. Script. Ohne Staging-Access (`docs/improvement-plan/archive/STAGING-ACCESS.md` Stub leer, B-002) kann ich keinen DB-Query gegen Produktions- oder Staging-DB laufen lassen um zu verifizieren ob es `storage_provider = 'supabase'` Rows gibt. Annahme: Operator führt die Audit-Query manuell durch sobald STAGING zugänglich ist und entscheidet dann ob ein Migrations-Script benötigt wird. Der Code-Pfad ist bereits resilient — `deleteRowMediaFromStorageProvider` löst über `media.storageBucket` aus, nicht über das Provider-Label, sodass alte Supabase-Rows beim Cleanup durch den S3-Adapter laufen (falls dieselben Bucket-Namen in S3 existieren).
|
||
- **Codebase hat schon S3-Pfade bereit.** Der bestehende `supabaseService.ts` enthielt seit längerem `storeFileWithRuntimeProvider()` (Zeilen 234-340) der bereits S3/local via @toolctrl/storage drive. Mein neuer `storageService.ts` ist im Wesentlichen diese Logik extrahiert plus saubere `storeFile()` / `putBufferAsFile()` / `deleteFile()` / `hasStorageCredentials()` API.
|
||
- **MediaService schreibt jetzt `storageProvider: "s3"`.** Historische Rows mit "supabase" bleiben in der DB unverändert; neue Writes haben "s3". Bulk-DB-Rewrite ausgelassen weil (a) der Code keine Branch-Logic mehr auf dem Feld hat, (b) der Wert dient nur Audit-Zwecken, (c) ein dediziertes Migrations-Script kann es später aufräumen.
|
||
- **Storage-Boundary-Baseline-Guard intentionally retained.** `scripts/verify-storage-boundary-baseline.mjs` detektiert Supabase-Pattern im Code als Sicherung gegen Re-Introduction. Bleibt drin obwohl Supabase weg ist — sinnvoll als Drift-Schutz.
|
||
- **DocsSidebar-Link zu `/docs/learning-center/guides/database/supabase`** bleibt unangerührt — das ist ein Learning-Center-Artikel für externe Supabase-Nutzung (nicht unsere eigene Storage-Integration). Orthogonal zum Cleanup.
|
||
- **3-4 Tage Schätzung deutlich überschritten in Code-Effort? Nein, eher unter** — das eigentliche Code-Removal war ~2h, der DB-Migrations-Schritt wäre die Hauptarbeit gewesen, ist aber per B-002 deferred.
|
||
|
||
## Progress Log
|
||
|
||
- 2026-05-17 01:00 — Cherry-pick `f7165dc0` lefthook fix (Precursor).
|
||
- 2026-05-17 01:02 — `9081eb50` Step 1: `storageService.ts` (S3/local pure, kein Supabase) extrahiert aus dem bestehenden runtime-provider-Path in `supabaseService.ts`. 4 Exports: `storeFile`, `putBufferAsFile`, `deleteFile`, `hasStorageCredentials`. Keine Caller-Switches, alles bleibt grün.
|
||
- 2026-05-17 01:04 — `21900ac2` Step 2: 6 Prod-Routen + 3 Test-Files migriert (general/profile/account/portals/widgets settings) von `storeSupabaseFile` → `storeFile`. Pure import + symbol rename. Plus zwei Test-Mock-Pfade.
|
||
- 2026-05-17 01:06 — `1107e59c` Step 3: `MediaService.ts` refactored — uses `putBufferAsFile` / `deleteFile` / `hasStorageCredentials`. Branch-Logic auf `storageProvider === "supabase"` weg, neue Writes setzen "s3".
|
||
- 2026-05-17 01:08 — `dc4c3f77` Step 4: `supabaseService.ts` + zugehöriger Test gelöscht (orphaned). 435 LOC weg, Tests: 1887 (war 1890 vor diesem Commit; −3 ist supabaseService.test cases).
|
||
- 2026-05-17 01:10 — `51e34839` Step 5: Config-Schema-Cleanup — `WebConfig.supabase`, `ApiConfig.supabase`, `ApiConfigSupabase` type, "supabase" aus `WebConfigStorage.provider`/`fallbackProvider`-Union, alle `supabase: {}` Test-Fixtures (6 Files in apps/api + 2 in packages/config), `normalizeStorageProvider`-Funktionen.
|
||
- 2026-05-17 01:12 — `613d51fe` Step 6: `@supabase/supabase-js` aus root + apps/web/package.json, catalog-Einträge für SUPABASE_API_URL/SUPABASE_KEY, alle 4 `.env*example`-Files, `docs/env-access-inventory.md`. Lockfile re-resolved, kein Supabase mehr in Tree.
|
||
- 2026-05-17 04:47 — staging-verify — running web container `mrf8lj70kmy9hqprx9dd6w7q-024502656750` (image tag `37f23fa6...`): `env | grep -i supabase` → empty; `ls /app/node_modules/@supabase` → not found. Postgres-Audit `SELECT provider, COUNT(*) FROM "FileObject" GROUP BY provider` → 0 rows total (FileObject leer, also keine historischen `storageProvider='supabase'`-Datensätze die migriert werden müssten). Migrations-Script entfällt damit endgültig. Acceptance Criteria erfüllt.
|