react-native-fast-image 8.18.2 → 8.19.1

package/README.md

@@ -125,8 +125,10 @@ Indicates the load order priority of an image. Images with `FastImage.priority.h
 
 ### `source.cache?: enum`
 
+How fresh the image must be. See [how caching is handled](docs/how-is-caching-handled.md) for how the options fit together.
+
 - `FastImage.cacheControl.immutable` - **(Default)** - Only updates if url changes.
-- `FastImage.cacheControl.web` - Use headers and follow normal caching procedures. On Android these responses are kept in a 50 MB HTTP cache (or the app's own, if its OkHttp client has one).
+- `FastImage.cacheControl.web` - Use headers and follow normal caching procedures. These responses are kept in their own HTTP cache (50 MB on each platform), which `clearDiskCache` also clears.
 - `FastImage.cacheControl.cacheOnly` - Only show images from cache, do not make any network requests.
 
 ---
@@ -367,7 +369,7 @@ if (result.ok) {
 }
 ```
 
-With `cache: 'cacheOnly'` it doesn't download: use it to check whether an image is cached.
+With `cache: 'cacheOnly'` it doesn't download: use it to check whether an image is cached. A source with a `cacheKey` and no `uri` is only looked up too (there's no url to download from), e.g. for an image whose signed url has expired.
 
 ```js
 const { ok } = await FastImage.getCachePath({
@@ -384,6 +386,69 @@ const { ok } = await FastImage.getCachePath({
 
 There's no way to remove a single image from the cache. To load an image again after it changed on the server, change its [`cacheKey`](#sourcecachekey-string).
 
+### `FastImage.writeToCache: (source: Source, file: string) => Promise<CachePathResult>`
+
+Stores a local image file as the source's image in the disk cache, so views and preloads of the source show it without downloading it. For example, after a user uploads a new avatar, store the photo they picked under the avatar's new url or [`cacheKey`](#sourcecachekey-string), and it shows at once. `file` is a `file://` uri or a path (or on Android a `content://` uri, as image pickers often return). A source with a `cacheKey` doesn't need a `uri`, so the image can be stored before its url is known. Resolves with `{ ok: true, path }` (the cached file) or `{ ok: false, error }`. Never rejects.
+
+```js
+const result = await FastImage.writeToCache(
+    {
+        uri: user.avatarUrl,
+        cacheKey: `avatar-${user.id}-${user.avatarUpdatedAt}`,
+    },
+    pickedPhoto.uri,
+)
+```
+
+- The file must be an image.
+- It doesn't replace an image that's already cached under the source's key: give a new image a new `cacheKey` (Glide can't replace one on Android).
+- Not for `cache: 'web'` sources, which are kept in an HTTP cache.
+- Like any cached image, it can be removed from the cache later, and then it's downloaded from the source's url.
+
+### `FastImage.configureCache: (limits?: CacheLimits) => Promise<CacheState>`
+
+How much the image cache keeps. Set the limits your app starts with in its native config, so they're in effect from the first image, and change them while the app runs with `configureCache`, e.g. from a storage setting. Runtime changes are saved, and used on the next launches too.
+
+| Limit                                                                                                             | iOS                                                                                        | Android                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `maxDiskSize`: the most bytes of images kept on disk. When it's over, the least recently used images are removed. | Changes apply at once (the cache is trimmed to half the limit). Default: no limit.         | Changes apply from the next launch (Glide's disk cache size is set when it starts). Default: 250 MB. |
+| `maxDiskAge`: seconds an image is kept on disk after it was last used.                                            | Default: 1 week (counted from when it was stored before SDWebImage 5.21, unless it's set). | No age limit.                                                                                        |
+| `maxMemorySize`: the most bytes of decoded images kept in memory.                                                 | Default: no limit (they're removed when the system is low on memory).                      | Sized from the screen by Glide.                                                                      |
+
+`0` means no limit.
+
+**Starting limits.** With Expo, in `app.json`:
+
+```json
+"plugins": [["react-native-fast-image", { "maxDiskSize": 209715200, "maxDiskAge": 2592000 }]]
+```
+
+Without Expo, in `ios/<App>/Info.plist`:
+
+```xml
+<key>FastImageMaxDiskSize</key>
+<integer>209715200</integer>
+<key>FastImageMaxDiskAge</key>
+<integer>2592000</integer>
+```
+
+and in `android/app/src/main/AndroidManifest.xml`, inside `<application>`:
+
+```xml
+<meta-data android:name="fastimage.MAX_DISK_SIZE" android:value="209715200" />
+```
+
+**Changing them at runtime.** Pass the limits to change; `null` goes back to the native config's (or the default). It resolves with the limits in effect and `diskSize`, the bytes the image disk cache uses now. Call it without limits to see them.
+
+```js
+await FastImage.configureCache({ maxDiskSize: 500 * 1024 * 1024 })
+const { maxDiskSize, diskSize } = await FastImage.configureCache()
+```
+
+On Android, if your app has its own `AppGlideModule` (see [Are you using Glide already](docs/app-glide-module.md)), set the disk cache size there instead: `maxDiskSize` isn't applied or reported.
+
+Images with `cache: 'web'` are kept in their own HTTP cache instead, up to 50 MB on each platform, which these limits don't change.
+
 ## Troubleshooting
 
 If you have any problems using this library try the steps in [troubleshooting](docs/troubleshooting.md) and see if they fix it.

package/android/src/main/java/com/dylanvann/fastimage/FastImageCacheLimits.java

@@ -0,0 +1,101 @@
+package com.dylanvann.fastimage;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.content.pm.ApplicationInfo;
+import android.content.pm.PackageManager;
+import android.os.Bundle;
+
+import androidx.annotation.Nullable;
+
+import com.bumptech.glide.load.engine.cache.DiskCache;
+
+import java.io.File;
+
+// configureCache's maxDiskSize on Android. Glide's disk cache size can only be
+// set when Glide starts, so FastImageGlideModule applies it then: the one
+// saved by configureCache at runtime, or the app's manifest's
+// (fastimage.MAX_DISK_SIZE meta-data), or Glide's default.
+final class FastImageCacheLimits {
+    private static final String PREFERENCES = "fast-image-cache-limits";
+    private static final String MAX_DISK_SIZE = "maxDiskSize";
+    private static final String MANIFEST_MAX_DISK_SIZE = "fastimage.MAX_DISK_SIZE";
+
+    // The disk cache size Glide started with, in bytes (0 for no limit), or
+    // -1 if FastImageGlideModule hasn't started it (not yet, or the app has
+    // its own AppGlideModule instead).
+    static volatile long startedMaxDiskSize = -1;
+
+    private FastImageCacheLimits() {
+    }
+
+    // Android loads the file on its own thread the first time; reading it
+    // waits for that. FastImageViewModule gets it early, off the main thread,
+    // so Glide doesn't wait on the disk when it starts.
+    static SharedPreferences preferences(Context context) {
+        return context.getApplicationContext().getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE);
+    }
+
+    // Starts loading the preferences file on a background thread, when
+    // FastImage's package creates its module and view manager (before any
+    // image loads).
+    static void loadInBackground(final Context context) {
+        new Thread(new Runnable() {
+            @Override
+            public void run() {
+                preferences(context);
+            }
+        }, "FastImageCacheLimits").start();
+    }
+
+    // Saves a runtime change (bytes, 0 for no limit), or with null removes it.
+    static void saveMaxDiskSize(Context context, @Nullable Long maxDiskSize) {
+        SharedPreferences.Editor editor = preferences(context).edit();
+        if (maxDiskSize == null) {
+            editor.remove(MAX_DISK_SIZE);
+        } else {
+            editor.putLong(MAX_DISK_SIZE, maxDiskSize);
+        }
+        editor.commit();
+    }
+
+    // The size to start Glide with: saved, or the manifest's, or Glide's
+    // default. 0 for no limit.
+    static long maxDiskSize(Context context) {
+        SharedPreferences preferences = preferences(context);
+        if (preferences.contains(MAX_DISK_SIZE)) {
+            return Math.max(preferences.getLong(MAX_DISK_SIZE, 0), 0);
+        }
+        Long manifest = manifestMaxDiskSize(context);
+        return manifest != null ? Math.max(manifest, 0) : DiskCache.Factory.DEFAULT_DISK_CACHE_SIZE;
+    }
+
+    @Nullable
+    private static Long manifestMaxDiskSize(Context context) {
+        try {
+            ApplicationInfo info = context.getPackageManager()
+                    .getApplicationInfo(context.getPackageName(), PackageManager.GET_META_DATA);
+            Bundle metaData = info.metaData;
+            Object value = metaData == null ? null : metaData.get(MANIFEST_MAX_DISK_SIZE);
+            if (value instanceof Number) return ((Number) value).longValue();
+            if (value instanceof String) return Long.parseLong(((String) value).trim());
+        } catch (PackageManager.NameNotFoundException | NumberFormatException e) {
+            // None.
+        }
+        return null;
+    }
+
+    // The bytes the disk cache (in Glide's default folder, where
+    // FastImageGlideModule puts it) uses now.
+    static long diskSize(Context context) {
+        return size(new File(context.getCacheDir(), DiskCache.Factory.DEFAULT_DISK_CACHE_DIR));
+    }
+
+    private static long size(File file) {
+        File[] files = file.listFiles();
+        if (files == null) return file.isFile() ? file.length() : 0;
+        long size = 0;
+        for (File child : files) size += size(child);
+        return size;
+    }
+}

package/android/src/main/java/com/dylanvann/fastimage/FastImageCacheWrite.java

@@ -0,0 +1,111 @@
+package com.dylanvann.fastimage;
+
+import android.content.Context;
+import android.net.Uri;
+
+import androidx.annotation.NonNull;
+
+import com.bumptech.glide.Priority;
+import com.bumptech.glide.load.DataSource;
+import com.bumptech.glide.load.Options;
+import com.bumptech.glide.load.data.DataFetcher;
+import com.bumptech.glide.load.model.GlideUrl;
+import com.bumptech.glide.load.model.ModelLoader;
+import com.bumptech.glide.load.model.ModelLoaderFactory;
+import com.bumptech.glide.load.model.MultiModelLoaderFactory;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+// What writeToCache loads: a local file's bytes (file:// or content://), with
+// a source's GlideUrl as their key, so Glide stores them in its disk cache
+// where loads of the source find them (the disk key is the url's cache key:
+// the source's cacheKey or url).
+final class FastImageCacheWrite {
+    final GlideUrl key;
+    final Uri file;
+
+    FastImageCacheWrite(GlideUrl key, Uri file) {
+        this.key = key;
+        this.file = file;
+    }
+
+    static final class LoaderFactory implements ModelLoaderFactory<FastImageCacheWrite, InputStream> {
+        private final Context context;
+
+        LoaderFactory(Context context) {
+            this.context = context;
+        }
+
+        @NonNull
+        @Override
+        public ModelLoader<FastImageCacheWrite, InputStream> build(@NonNull MultiModelLoaderFactory multiFactory) {
+            return new ModelLoader<FastImageCacheWrite, InputStream>() {
+                @Override
+                public LoadData<InputStream> buildLoadData(@NonNull FastImageCacheWrite model, int width, int height, @NonNull Options options) {
+                    return new LoadData<>(model.key, new Fetcher(context, model.file));
+                }
+
+                @Override
+                public boolean handles(@NonNull FastImageCacheWrite model) {
+                    return true;
+                }
+            };
+        }
+
+        @Override
+        public void teardown() {
+        }
+    }
+
+    private static final class Fetcher implements DataFetcher<InputStream> {
+        private final Context context;
+        private final Uri file;
+        private InputStream stream;
+
+        Fetcher(Context context, Uri file) {
+            this.context = context;
+            this.file = file;
+        }
+
+        @Override
+        public void loadData(@NonNull Priority priority, @NonNull DataCallback<? super InputStream> callback) {
+            try {
+                stream = context.getContentResolver().openInputStream(file);
+                if (stream == null) throw new IOException("Can't read " + file);
+                callback.onDataReady(stream);
+            } catch (IOException | SecurityException e) {
+                callback.onLoadFailed(e);
+            }
+        }
+
+        @Override
+        public void cleanup() {
+            if (stream == null) return;
+            try {
+                stream.close();
+            } catch (IOException e) {
+                // Closed as far as it could.
+            }
+            stream = null;
+        }
+
+        @Override
+        public void cancel() {
+        }
+
+        @NonNull
+        @Override
+        public Class<InputStream> getDataClass() {
+            return InputStream.class;
+        }
+
+        // Not DATA_DISK_CACHE or MEMORY_CACHE, which DiskCacheStrategy.DATA
+        // doesn't store.
+        @NonNull
+        @Override
+        public DataSource getDataSource() {
+            return DataSource.LOCAL;
+        }
+    }
+}

package/android/src/main/java/com/dylanvann/fastimage/FastImageGlideModule.java

@@ -1,9 +1,23 @@
 package com.dylanvann.fastimage;
 
+import android.content.Context;
+
+import androidx.annotation.NonNull;
+
+import com.bumptech.glide.GlideBuilder;
 import com.bumptech.glide.annotation.GlideModule;
+import com.bumptech.glide.load.engine.cache.InternalCacheDiskCacheFactory;
 import com.bumptech.glide.module.AppGlideModule;
 
 // We need an AppGlideModule to be present for progress events to work.
 @GlideModule
 public final class FastImageGlideModule extends AppGlideModule {
+    // The app's disk cache size (saved by configureCache, or in its manifest;
+    // FastImageCacheLimits), in Glide's default folder.
+    @Override
+    public void applyOptions(@NonNull Context context, @NonNull GlideBuilder builder) {
+        long maxDiskSize = FastImageCacheLimits.maxDiskSize(context);
+        builder.setDiskCache(new InternalCacheDiskCacheFactory(context, maxDiskSize == 0 ? Long.MAX_VALUE : maxDiskSize));
+        FastImageCacheLimits.startedMaxDiskSize = maxDiskSize;
+    }
 }

package/android/src/main/java/com/dylanvann/fastimage/FastImageKeyedGlideUrl.java

@@ -19,6 +19,13 @@ class FastImageKeyedGlideUrl extends GlideUrl {
         mCacheKey = cacheKey;
     }
 
+    // For a source with a cacheKey and no uri (getCachePath, writeToCache):
+    // GlideUrl needs a url, but only the key is used for the caches, and it's
+    // never loaded from the network.
+    static FastImageKeyedGlideUrl forKey(@NonNull String cacheKey) {
+        return new FastImageKeyedGlideUrl("fast-image-cache-key:" + cacheKey, Headers.DEFAULT, cacheKey);
+    }
+
     @Override
     public String getCacheKey() {
         return mCacheKey;

package/android/src/main/java/com/dylanvann/fastimage/FastImageOkHttpProgressGlideModule.java

@@ -130,6 +130,10 @@ public class FastImageOkHttpProgressGlideModule extends LibraryGlideModule {
         webCache = new Cache(new File(context.getCacheDir(), "fast-image-http-cache"), WEB_CACHE_SIZE);
         webClient = client.newBuilder().cache(webCache).build();
         registry.prepend(FastImageWebGlideUrl.class, InputStream.class, new WebUrlLoaderFactory(webClient));
+
+        // writeToCache: local files stored under a source's key.
+        registry.prepend(FastImageCacheWrite.class, InputStream.class,
+                new FastImageCacheWrite.LoaderFactory(context.getApplicationContext()));
     }
 
     // Loads GlideUrls with the given client, except `web` ones

package/android/src/main/java/com/dylanvann/fastimage/FastImageViewConverter.java

@@ -138,6 +138,16 @@ class FastImageViewConverter {
         return options;
     }
 
+    // The source's cacheKey, or null without one.
+    @Nullable
+    static String getCacheKey(@Nullable ReadableMap source) {
+        if (source == null || !source.hasKey("cacheKey") || source.getType("cacheKey") != ReadableType.String) {
+            return null;
+        }
+        String cacheKey = source.getString("cacheKey");
+        return cacheKey == null || cacheKey.isEmpty() ? null : cacheKey;
+    }
+
     static FastImageCacheControl getCacheControl(ReadableMap source) {
         return getValueFromSource("cache", "immutable", FAST_IMAGE_CACHE_CONTROL_MAP, source);
     }