fix(download): suffix only colliding quality variants

2026-08-02 17:18:36 +02:00 · 2026-07-29 02:43:35 +07:00
parent 1f55523b64
commit e7fbaf7b75
41 changed files with 629 additions and 110 deletions
@@ -126,6 +126,10 @@ final _qualityFilenameTokenPattern = RegExp(
  r'\{quality_variant\}',
  caseSensitive: false,
 );
+final _explicitQualityFilenameTokenPattern = RegExp(
+  r'\{(?:quality|quality_variant)\}',
+  caseSensitive: false,
+);

 class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
  Timer? _queuePersistDebounce;
@@ -176,9 +180,31 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
  int _queueItemSequence = 0;
  bool _isLoaded = false;
  final Set<String> _ensuredDirs = {};
+  final Map<String, Future<void>> _qualityVariantFileLocks = {};
  Future<String>? _appFolderStorageFallback;
  final Set<String> _rejectedAppFolderRoots = {};
  int _idleProgressPollTick = 0;
+
+  Future<T> _withQualityVariantFileLock<T>(
+    String path,
+    Future<T> Function() action,
+  ) async {
+    final key = path.toLowerCase();
+    final previous = _qualityVariantFileLocks[key];
+    final completer = Completer<void>();
+    final current = completer.future;
+    _qualityVariantFileLocks[key] = current;
+    if (previous != null) await previous;
+    try {
+      return await action();
+    } finally {
+      completer.complete();
+      if (identical(_qualityVariantFileLocks[key], current)) {
+        _qualityVariantFileLocks.remove(key);
+      }
+    }
+  }
+
  bool _networkPausedByWifiOnly = false;
  List<ConnectivityResult>? _lastConnectivityResults;
  DateTime _lastConnectionCleanupAt = DateTime.fromMillisecondsSinceEpoch(0);
@@ -444,6 +470,7 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
    String? label,
    String? copyright,
    bool stageSafForDeferredPublish = false,
+    bool qualityVariantCollisionOnly = false,
  }) {
    final resolvedAlbumArtist = _resolveAlbumArtistForMetadata(track, settings);
    final postProcessingEnabled =
@@ -529,6 +556,7 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
      qualityVariant: item.preserveQualityVariant
          ? qualityVariantStagingLabel(item.id)
          : '',
+      qualityVariantCollisionOnly: qualityVariantCollisionOnly,
      songLinkRegion: settings.songLinkRegion,
    );
  }
@@ -193,6 +193,35 @@ extension _DownloadQueueFinalization on DownloadQueueNotifier {
    }
  }

+  Future<({String uri, String fileName})?> _writeTempToSafCollisionAware({
+    required String treeUri,
+    required String relativeDir,
+    required String cleanFileName,
+    required String variantFileName,
+    required String mimeType,
+    required String srcPath,
+    String preservedSuffix = '',
+  }) async {
+    try {
+      final result = await PlatformBridge.createCollisionAwareSafFileFromPath(
+        treeUri: treeUri,
+        relativeDir: relativeDir,
+        cleanFileName: cleanFileName,
+        variantFileName: variantFileName,
+        mimeType: mimeType,
+        srcPath: srcPath,
+        preservedSuffix: preservedSuffix,
+      );
+      final uri = (result['uri'] as String? ?? '').trim();
+      final publishedName = (result['file_name'] as String? ?? '').trim();
+      if (uri.isEmpty || publishedName.isEmpty) return null;
+      return (uri: uri, fileName: publishedName);
+    } catch (e) {
+      _log.w('Failed to write collision-aware temp file to SAF: $e');
+      return null;
+    }
+  }
+
  Future<void> _writeLrcToSaf({
    required String treeUri,
    required String relativeDir,
@@ -251,6 +280,8 @@ extension _DownloadQueueFinalization on DownloadQueueNotifier {
    op,
    bool avoidOverwrite = false,
    String preservedSuffix = '',
+    String? collisionCleanFileName,
+    String? collisionVariantFileName,
    void Function(String fileName)? onPublishedFileName,
  }) async {
    final tempPath = await _copySafToTemp(uri);
@@ -267,7 +298,21 @@ extension _DownloadQueueFinalization on DownloadQueueNotifier {
      final dotIndex = fileName.lastIndexOf('.');
      final ext = dotIndex >= 0 ? fileName.substring(dotIndex) : '';
      String? newUri;
-      if (avoidOverwrite) {
+      if (collisionCleanFileName != null && collisionVariantFileName != null) {
+        final published = await _writeTempToSafCollisionAware(
+          treeUri: treeUri,
+          relativeDir: relativeDir,
+          cleanFileName: collisionCleanFileName,
+          variantFileName: collisionVariantFileName,
+          mimeType: _mimeTypeForExt(ext),
+          srcPath: outPath,
+          preservedSuffix: preservedSuffix,
+        );
+        newUri = published?.uri;
+        if (published != null) {
+          onPublishedFileName?.call(published.fileName);
+        }
+      } else if (avoidOverwrite) {
        final published = await _writeTempToSafUnique(
          treeUri: treeUri,
          relativeDir: relativeDir,
@@ -321,6 +366,7 @@ extension _DownloadQueueFinalization on DownloadQueueNotifier {
    String? downloadTreeUri,
    String? safRelativeDir,
    String? fileName,
+    bool collisionOnly = false,
  }) async {
    if (!item.preserveQualityVariant || result['already_exists'] == true) {
      return _QualityVariantFileOutcome(filePath: filePath, fileName: fileName);
@@ -391,11 +437,16 @@ extension _DownloadQueueFinalization on DownloadQueueNotifier {
    final currentFileName = storageMode == 'saf' && isContentUri(filePath)
        ? (fileName ?? result['file_name']?.toString() ?? '')
        : (localPathSegments.isEmpty ? '' : localPathSegments.last);
-    final preferredFileName = applyQualityVariantFilenameLabel(
+    final variantFileName = applyQualityVariantFilenameLabel(
      fileName: currentFileName,
      stagingLabel: stagingLabel,
      qualityLabel: qualityLabel,
    );
+    final cleanFileName = removeQualityVariantStagingLabel(
+      fileName: currentFileName,
+      stagingLabel: stagingLabel,
+    );
+    final preferredFileName = variantFileName;
    if (preferredFileName == currentFileName) {
      return _QualityVariantFileOutcome(
        filePath: filePath,
@@ -417,8 +468,10 @@ extension _DownloadQueueFinalization on DownloadQueueNotifier {
        uri: filePath,
        treeUri: downloadTreeUri,
        relativeDir: safRelativeDir ?? '',
-        avoidOverwrite: true,
+        avoidOverwrite: !collisionOnly,
        preservedSuffix: qualityLabel,
+        collisionCleanFileName: collisionOnly ? cleanFileName : null,
+        collisionVariantFileName: collisionOnly ? variantFileName : null,
        onPublishedFileName: (name) => publishedFileName = name,
        op: (tempPath, addCleanup) async => (tempPath, preferredFileName),
      );
@@ -441,44 +494,70 @@ extension _DownloadQueueFinalization on DownloadQueueNotifier {

    final source = File(filePath);
    final parent = source.parent;
-    var target = File(
-      '${parent.path}${Platform.pathSeparator}$preferredFileName',
+    final cleanTarget = File(
+      '${parent.path}${Platform.pathSeparator}$cleanFileName',
    );
-    var counter = 2;
-    while (await target.exists() && target.path != source.path) {
-      final dotIndex = preferredFileName.lastIndexOf('.');
-      final hasExtension = dotIndex > 0;
-      final stem = hasExtension
-          ? preferredFileName.substring(0, dotIndex)
+    final lockTarget = collisionOnly
+        ? cleanTarget
+        : File('${parent.path}${Platform.pathSeparator}$preferredFileName');
+    return _withQualityVariantFileLock(lockTarget.path, () async {
+      final selectedFileName = collisionOnly
+          ? resolveQualityVariantFilename(
+              fileName: currentFileName,
+              stagingLabel: stagingLabel,
+              qualityLabel: qualityLabel,
+              collisionOnly: true,
+              cleanNameExists:
+                  cleanTarget.path != source.path && await cleanTarget.exists(),
+            )
          : preferredFileName;
-      final extension = hasExtension
-          ? preferredFileName.substring(dotIndex)
-          : '';
-      target = File(
-        '${parent.path}${Platform.pathSeparator}$stem ($counter)$extension',
+      if (selectedFileName == currentFileName) {
+        return _QualityVariantFileOutcome(
+          filePath: filePath,
+          fileName: fileName,
+          metadata: metadata,
+        );
+      }
+
+      var target = File(
+        '${parent.path}${Platform.pathSeparator}$selectedFileName',
      );
-      counter++;
-    }
-    try {
-      final renamed = await source.rename(target.path);
-      result['file_path'] = renamed.path;
-      final renamedSegments = renamed.uri.pathSegments;
-      result['file_name'] = renamedSegments.isEmpty
-          ? null
-          : renamedSegments.last;
-      return _QualityVariantFileOutcome(
-        filePath: renamed.path,
-        fileName: result['file_name'] as String?,
-        metadata: metadata,
-      );
-    } catch (e) {
-      _log.w('Failed to apply measured quality filename: $e');
-      return _QualityVariantFileOutcome(
-        filePath: filePath,
-        fileName: fileName,
-        metadata: metadata,
-      );
-    }
+      var counter = 2;
+      while (await target.exists() && target.path != source.path) {
+        final dotIndex = selectedFileName.lastIndexOf('.');
+        final hasExtension = dotIndex > 0;
+        final stem = hasExtension
+            ? selectedFileName.substring(0, dotIndex)
+            : selectedFileName;
+        final extension = hasExtension
+            ? selectedFileName.substring(dotIndex)
+            : '';
+        target = File(
+          '${parent.path}${Platform.pathSeparator}$stem ($counter)$extension',
+        );
+        counter++;
+      }
+      try {
+        final renamed = await source.rename(target.path);
+        result['file_path'] = renamed.path;
+        final renamedSegments = renamed.uri.pathSegments;
+        result['file_name'] = renamedSegments.isEmpty
+            ? null
+            : renamedSegments.last;
+        return _QualityVariantFileOutcome(
+          filePath: renamed.path,
+          fileName: result['file_name'] as String?,
+          metadata: metadata,
+        );
+      } catch (e) {
+        _log.w('Failed to apply measured quality filename: $e');
+        return _QualityVariantFileOutcome(
+          filePath: filePath,
+          fileName: fileName,
+          metadata: metadata,
+        );
+      }
+    });
  }

  /// Shared decrypt finalize used by both the inline single-item pipeline
@@ -11,6 +11,7 @@ class _NativeWorkerRequestContext {
  final String? downloadTreeUri;
  final String? safRelativeDir;
  final String? safFileName;
+  final bool qualityVariantCollisionOnly;

  const _NativeWorkerRequestContext({
    required this.item,
@@ -22,6 +23,7 @@ class _NativeWorkerRequestContext {
    this.downloadTreeUri,
    this.safRelativeDir,
    this.safFileName,
+    this.qualityVariantCollisionOnly = false,
  });
 }

@@ -730,6 +732,9 @@ extension _DownloadQueueNativeWorker on DownloadQueueNotifier {
      item,
      baseFilenameFormat,
    );
+    final qualityVariantCollisionOnly =
+        item.preserveQualityVariant &&
+        !_explicitQualityFilenameTokenPattern.hasMatch(baseFilenameFormat);
    if (isSafMode) {
      safFileName = await _buildSafFileNameForItem(
        item,
@@ -775,6 +780,7 @@ extension _DownloadQueueNativeWorker on DownloadQueueNotifier {
      label: extendedMetadata?.label,
      copyright: extendedMetadata?.copyright,
      stageSafForDeferredPublish: isSafMode,
+      qualityVariantCollisionOnly: qualityVariantCollisionOnly,
    ).withStrategy(useExtensions: true, useFallback: state.autoFallback);

    return _NativeWorkerRequestContext(
@@ -787,6 +793,7 @@ extension _DownloadQueueNativeWorker on DownloadQueueNotifier {
      downloadTreeUri: isSafMode ? settings.downloadTreeUri : null,
      safRelativeDir: isSafMode ? outputDir : null,
      safFileName: safFileName,
+      qualityVariantCollisionOnly: qualityVariantCollisionOnly,
    );
  }

@@ -1177,6 +1184,7 @@ extension _DownloadQueueNativeWorker on DownloadQueueNotifier {
        downloadTreeUri: context.downloadTreeUri,
        safRelativeDir: context.safRelativeDir,
        fileName: result['file_name'] as String? ?? context.safFileName,
+        collisionOnly: context.qualityVariantCollisionOnly,
      );
      filePath = variantOutcome.filePath;
      actualBitDepth = readPositiveInt(result['actual_bit_depth']);
@@ -100,6 +100,7 @@ class _DownloadRun {
  String effectiveOutputDir = '';
  String? appOutputDir;
  String? safFileName;
+  bool qualityVariantCollisionOnly = false;
  String? safBaseName;
  String? finalSafFileName;

@@ -419,6 +420,9 @@ class _DownloadRun {
      item,
      baseFilenameFormat,
    );
+    qualityVariantCollisionOnly =
+        item.preserveQualityVariant &&
+        !_explicitQualityFilenameTokenPattern.hasMatch(baseFilenameFormat);
    if (isSafMode) {
      final builtSafFileName = await n._buildSafFileNameForItem(
        item,
@@ -549,6 +553,7 @@ class _DownloadRun {
      genre: genre,
      label: label,
      copyright: copyright,
+      qualityVariantCollisionOnly: qualityVariantCollisionOnly,
    );

    return PlatformBridge.downloadByStrategy(
@@ -705,6 +710,7 @@ class _DownloadRun {
        downloadTreeUri: settings.downloadTreeUri,
        safRelativeDir: effectiveOutputDir,
        fileName: finalSafFileName ?? safFileName,
+        collisionOnly: qualityVariantCollisionOnly,
      );
      filePath = variantOutcome.filePath;
      if (variantOutcome.fileName != null) {