Return the local proxy when offline for Optimize-Storage assets

AlexV525 · claude · AlexV525 · commit e035d7e3e476 · 2026-07-09T00:38:02.000+08:00
On-device log for #1118 revealed a second gap: with the network off, both the PHImageManager (HighQualityFormat + networkAccessAllowed=YES) primary path AND the PHAssetResource walker fail with `NSURLErrorNotConnectedToInternet (-1009)`, because both are trying to materialise the iCloud original. The user's caller then receives an opaque -1009 with no image bytes — worse UX than Photos.app itself, which happily displays the local downsampled proxy under Optimize Storage. `AssetEntity.originFile` should degrade gracefully the same way, not fail hard. Add a tail fallback `fetchOfflineImageProxyFor:` that fires after both the primary and walker terminal-fail. It issues one more PHImageManager request with `deliveryMode=Opportunistic + networkAccessAllowed=NO`, accepts the degraded result, and writes to a `proxy_`-prefixed filename in the standard image cache directory. Callers get *something* displayable offline; hitting the primary path online later still materialises the iCloud original because `cachedPathForAsset:` does not scan the `proxy_` prefix — no cross-mode pollution. Also add an error log line inside the primary `dataHandler` so field diagnostics can distinguish "PHImageManager errored with -1009" from "PHImageManager returned no data" — the on-device log that surfaced this offline gap was silent on which of the two triggered the walker fallback. Wired into both terminal-failure branches of `runWalker` — the common case (PHImageManager primary → walker fallback → both fail) and the RAW/exotic case (walker primary → PHImageManager fallback → both fail). Guard against double-reply from Opportunistic mode's multi-callback contract with a `__block BOOL replied` — with networkAccessAllowed=NO a second callback is unlikely, but PMResultHandler treats a second reply as a programmer error. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/darwin/photo_manager/Sources/photo_manager/core/PMManager.m b/darwin/photo_manager/Sources/photo_manager/core/PMManager.m
@@ -1479,11 +1479,26 @@ - (void)fetchOriginImageFile:(PHAsset *)asset resultHandler:(PMResultHandler *)h
             }
             __strong typeof(weakSelf) inner = weakSelf;
             if (!inner) { return; }
+            void (^tryOfflineProxy)(NSObject *finalError) = ^(NSObject *finalError) {
+                // Every network-touching path has failed. Try one last request
+                // with networkAccessAllowed=NO to surface the local proxy
+                // Photos keeps under Optimize Storage — better a small image
+                // than an opaque -1009.
+                [inner fetchOfflineImageProxyFor:asset
+                                progressHandler:progressHandler
+                                          block:^(NSString *proxyPath, NSObject *proxyError) {
+                    if (proxyPath) {
+                        [handler reply:proxyPath];
+                        return;
+                    }
+                    [inner notifyProgress:progressHandler progress:0 state:PMProgressStateFailed];
+                    [handler replyError:finalError ?: proxyError];
+                }];
+            };
             if (seedError) {
                 // PHImageManager already ran and failed — walker was the
-                // fallback. Nothing else to try.
-                [inner notifyProgress:progressHandler progress:0 state:PMProgressStateFailed];
-                [handler replyError:walkerError ?: seedError];
+                // fallback. Try offline proxy as last resort.
+                tryOfflineProxy(walkerError ?: seedError);
                 return;
             }
             // Walker ran as the primary path (RAW / exotic UTI) and every
@@ -1497,8 +1512,7 @@ - (void)fetchOriginImageFile:(PHAsset *)asset resultHandler:(PMResultHandler *)h
                     [handler reply:fbPath];
                     return;
                 }
-                [inner notifyProgress:progressHandler progress:0 state:PMProgressStateFailed];
-                [handler replyError:walkerError ?: fbError];
+                tryOfflineProxy(walkerError ?: fbError);
             }];
         }];
     };
@@ -1677,6 +1691,8 @@ - (void)fallbackFetchImageDataFor:(PHAsset *)asset
         }
         NSObject *error = info[PHImageErrorKey];
         if (error) {
+            [[PMLogUtils sharedInstance] info:[NSString stringWithFormat:
+                @"[#1118] PHImageManager error: %@", error]];
             block(nil, error);
             return;
         }
@@ -1740,6 +1756,125 @@ - (void)fallbackFetchImageDataFor:(PHAsset *)asset
     });
 }
 
+// Tail fallback used when both the PHImageManager (HighQualityFormat +
+// networkAccessAllowed=YES) primary and the PHAssetResource walker have
+// failed — typically because the device is offline and the requested
+// resource is only present as an iCloud stub. Requests one more time with
+// deliveryMode=Opportunistic + networkAccessAllowed=NO and *accepts the
+// degraded result*, so the caller receives the local downsampled proxy
+// (the "small image" Photos.app itself falls back to offline) instead of
+// an opaque network error. The proxy is cached at a distinct
+// `proxy_`-prefixed filename so a subsequent online call still traverses
+// the primary path and materialises the iCloud original — no cross-mode
+// pollution.
+- (void)fetchOfflineImageProxyFor:(PHAsset *)asset
+                  progressHandler:(NSObject <PMProgressHandlerProtocol> *)progressHandler
+                            block:(void (^)(NSString *path, NSObject *error))block {
+    NSFileManager *manager = NSFileManager.defaultManager;
+    NSString *base = [self makeAssetOutputPath:asset resource:nil isOrigin:YES fileType:nil manager:manager];
+    NSString *dir = [base stringByDeletingLastPathComponent];
+    NSString *proxyPath = [dir stringByAppendingPathComponent:
+                           [@"proxy_" stringByAppendingString:[base lastPathComponent]]];
+    if ([manager fileExistsAtPath:proxyPath]) {
+        [[PMLogUtils sharedInstance] info:[NSString stringWithFormat:
+            @"[#1118] local proxy cache hit → %@", proxyPath]];
+        [self notifySuccess:progressHandler];
+        block(proxyPath, nil);
+        return;
+    }
+
+    PHImageRequestOptions *options = [PHImageRequestOptions new];
+    [options setDeliveryMode:PHImageRequestOptionsDeliveryModeOpportunistic];
+    [options setNetworkAccessAllowed:NO];
+    [options setSynchronous:NO];
+    [options setVersion:PHImageRequestOptionsVersionCurrent];
+
+    __weak typeof(self) weakSelf = self;
+    // Opportunistic mode can fire the result handler more than once in
+    // principle. With networkAccessAllowed=NO a second callback is unlikely
+    // (no iCloud round trip is scheduled), but guard against double-reply
+    // regardless — the wrapping PMResultHandler treats a second reply as a
+    // programmer error.
+    __block BOOL replied = NO;
+    void (^dataHandler)(NSData *_Nullable, NSDictionary *_Nullable) = ^(NSData *_Nullable imageData, NSDictionary *_Nullable info) {
+        __strong typeof(weakSelf) strongSelf = weakSelf;
+        if (!strongSelf) { return; }
+        if (replied) { return; }
+        if ([info[PHImageCancelledKey] boolValue]) {
+            replied = YES;
+            [[PMLogUtils sharedInstance] info:@"[#1118] local-proxy PHImageManager cancelled"];
+            block(nil, [NSError errorWithDomain:@"PMPhotoManager" code:-2 userInfo:@{
+                NSLocalizedDescriptionKey: @"PHImageManager request was cancelled."
+            }]);
+            return;
+        }
+        NSObject *error = info[PHImageErrorKey];
+        if (error) {
+            replied = YES;
+            [[PMLogUtils sharedInstance] info:[NSString stringWithFormat:
+                @"[#1118] local-proxy PHImageManager error: %@", error]];
+            block(nil, error);
+            return;
+        }
+        if (!imageData) {
+            replied = YES;
+            [[PMLogUtils sharedInstance] info:@"[#1118] local-proxy no data available"];
+            block(nil, [NSError errorWithDomain:@"PMPhotoManager" code:-1 userInfo:@{
+                NSLocalizedDescriptionKey: @"No local proxy available for asset."
+            }]);
+            return;
+        }
+        replied = YES;
+        NSUInteger dataLength = imageData.length;
+        BOOL degraded = [info[PHImageResultIsDegradedKey] boolValue];
+        dispatch_async(strongSelf->_imageFileProcessingQueue, ^{
+            __strong typeof(weakSelf) innerSelf = weakSelf;
+            if (!innerSelf) { return; }
+            NSError *writeError;
+            [imageData writeToFile:proxyPath options:NSDataWritingAtomic error:&writeError];
+            if (writeError) {
+                block(nil, writeError);
+                return;
+            }
+            [[PMLogUtils sharedInstance] info:[NSString stringWithFormat:
+                @"[#1118] local proxy delivered %lu bytes%@ → %@",
+                (unsigned long)dataLength, degraded ? @" (degraded)" : @"", proxyPath]];
+            [innerSelf notifySuccess:progressHandler];
+            block(proxyPath, nil);
+        });
+    };
+
+    dispatch_async(dispatch_get_main_queue(), ^{
+        __strong typeof(weakSelf) strongSelf = weakSelf;
+        if (!strongSelf) { return; }
+        if (@available(iOS 13.0, macOS 10.15, *)) {
+            [strongSelf.cachingManager requestImageDataAndOrientationForAsset:asset
+                                                                     options:options
+                                                               resultHandler:^(NSData *_Nullable imageData,
+                                                                               NSString *_Nullable dataUTI,
+                                                                               CGImagePropertyOrientation orientation,
+                                                                               NSDictionary *_Nullable info) {
+                dataHandler(imageData, info);
+            }];
+        } else {
+#if TARGET_OS_IOS
+            [strongSelf.cachingManager requestImageDataForAsset:asset
+                                                        options:options
+                                                  resultHandler:^(NSData *_Nullable imageData,
+                                                                  NSString *_Nullable dataUTI,
+                                                                  UIImageOrientation orientation,
+                                                                  NSDictionary *_Nullable info) {
+                dataHandler(imageData, info);
+            }];
+#else
+            dataHandler(nil, @{PHImageErrorKey: [NSError errorWithDomain:@"PMPhotoManager" code:-1 userInfo:@{
+                NSLocalizedDescriptionKey: @"requestImageDataForAsset unavailable on this platform version."
+            }]});
+#endif
+        }
+    });
+}
+
 - (void)fetchFullSizeImageFile:(PHAsset *)asset
                  resultHandler:(PMResultHandler *)handler
                progressHandler:(NSObject <PMProgressHandlerProtocol> *)progressHandler {
