Symboles de débogage et obfuscation

Par défaut, la CLI tk-ota-push compile toutes les Releases et tous les Patchs avec l'obfuscation Dart activée (--obfuscate) et génère les tables de symboles DWARF (--split-debug-info). Ces fichiers .symbols sont automatiquement téléversés et scellés par architecture dans le Coffre-Fort du serveur OTA afin de permettre la dé-obfuscation des stacktraces de crash à tout moment via tk-ota-push symbols.

1. Génération et archivage automatique lors du build (release & patch)

Options CLI associées (addCommonOptions)

Option / Flag	Défaut	Comportement dans Publisher
--obfuscate	true	Ajoute --obfuscate et --split-debug-info=<symDir> aux arguments de flutter build.
--no-obfuscate	—	Désactive l'obfuscation (sauf si --split-debug-info est explicitement renseigné).
--split-debug-info <dir>	build/ota_symbols/<version>	Permet de personnaliser le dossier local où Flutter écrit les fichiers .symbols.

Résolution par plateforme et architecture (Publisher.resolveSymbolsFile)

Dans le répertoire build/ota_symbols/<version> (ou le dossier --split-debug-info), la CLI recherche dans l'ordre :

• Android 64-bits (aarch64) : app.android-arm64.symbols
• Android 32-bits (arm) : app.android-arm.symbols
• iOS (aarch64) : app.ios-arm64.symbols
• Générique : app.<platform>-<arch>.symbols (puis repli sur le premier fichier *.symbols trouvé).

Particularité du Linker iOS (patchIos)

Lors de la création d'un patch iOS, flutter build ios --release --no-codesign produit le noyau app.dill, puis gen_snapshot_arm64 et aot-tools.dill link assemblent le snapshot final. Lorsque l'obfuscation est active, la CLI passe explicitement les 4 drapeaux DWARF suivants à gen_snapshot_arm64 ainsi qu'à aot_tools link (après --) :

--dwarf-stack-traces
--resolve-dwarf-paths
--save-debugging-info=<symDir>/patch_<version>.symbols
--strip

Cela garantit que le snapshot artefact de patch et le binaire de base partagent exactement les mêmes conventions de pile DWARF et évite toute erreur dwarf_stack_traces vs no-dwarf_stack_traces.

Envoi Multipart au serveur

Dans OtaApiClient._multipart, si symbolsFile existe sur le disque, il est joint dans le champ multipart symbols_file lors de POST /api/admin/v1/releases et POST /api/admin/v1/patches. Le serveur calcule son empreinte symbolsSha256Hash et l'affiche dans le reçu CLI :

  │ Symboles (.symbols) : Archivés (app.android-arm64.symbols • SHA-256 : 998877665544...)

2. Télécharger les symboles d'un patch (tk-ota-push symbols)

Lorsqu'une stacktrace obfusquée remonte d'un téléphone en production, utilisez la sous-commande symbols pour récupérer le fichier .symbols exact rattaché à l'UUID du patch :

tk-ota-push symbols --patch-id <uuid> [-o <chemin_sortie>] [options]

Options de tk-ota-push symbols

Option	Abrév.	Obligatoire	Défaut	Description
--patch-id	—	Oui	—	Identifiant UUID du patch dont on veut télécharger les .symbols.
--output	-o	Non	patch_<patchId>.symbols	Chemin du fichier .symbols enregistré localement.
--tenant-id	—	Non	shorebird.yaml / session / default	Identifiant du Tenant.
--server	—	Non	shorebird.yaml / env / http://localhost:8080	URL du serveur OTA.
--project	—	Non	.	Chemin du projet Flutter (pour lire shorebird.yaml).

Exemple complet de dé-obfuscation locale (flutter symbolize)

# 1. Télécharger le fichier .symbols du patch
tk-ota-push symbols \
  --patch-id 8b73f831-29cf-4cb6-8801-44ebda29910a \
  -o build/crash_triage/patch_1.symbols

Sortie de la CLI :

Téléchargement du fichier .symbols pour le patch 8b73f831-29cf-4cb6-8801-44ebda29910a...

✅ Fichier .symbols enregistré dans : build/crash_triage/patch_1.symbols (418204 octets)
Pour dé-obfusquer une stacktrace : flutter symbolize -i crash.txt -d build/crash_triage/patch_1.symbols

# 2. Dé-obfusquer la stacktrace avec l'outil standard Flutter
flutter symbolize -i crash.txt -d build/crash_triage/patch_1.symbols

3. Téléchargement des symboles d'une Release ou dé-obfuscation côté serveur

En complément de tk-ota-push symbols, OtaApiClient et le contrôleur OtaAdminController exposent deux endpoints additionnels :

• Télécharger le .symbols de base d'une Release (OtaApiClient.downloadReleaseSymbols) :

  curl -L "$OTA_SERVER_URL/api/admin/v1/releases/$RELEASE_ID/symbols" \
    -H "Authorization: Bearer $OTA_API_KEY" \
    -o release_base.symbols
• Dé-obfusquer directement une stacktrace via l'API :

  curl -X POST "$OTA_SERVER_URL/api/admin/v1/patches/$PATCH_ID/deobfuscate" \
    -H "Authorization: Bearer $OTA_API_KEY" \
    --data-urlencode "stacktrace@crash.txt"