
# Resources from the network

An `http:` or `https:` resource of the `ResourceLoader` (a `Resource` of `@Value`, `getResource`, a `ResourceView`, a `ResourceImage`) is downloaded once and kept in the app's files: read from the disk from then on, across starts too, and asked again in the background past its age.

## Why

On iOS, Android and the desktops `Image.network` keeps an image in memory only: after every start the avatars and pictures are downloaded again. In the browser its HTTP cache keeps them, but only as the server's headers allow. A resource kept in the app's files is there at the next start without the network, and is checked with the server only now and then.

## Example

```yaml
spring:
  flutter:
    resources:
      cache:
        max-size: 300MB          # the kept resources, together
        max-age: 7d              # past it: used, and asked again
        max-entry-size: 50MB     # larger: from the network every time
        locations:               # the first rule that matches
          - pattern: https://avatars.steamstatic.com/**
            max-age: 1d
          - pattern: https://api.example.com/**
            enabled: false
      view:
        fade: 200ms
```

```dart
// Any resource: an image now, a type of the app's own by a renderer bean.
ResourceView(
  player.avatarUrl,
  width: 40,
  height: 40,
  fit: BoxFit.cover,
  shape: const CircleBorder(),
  placeholder: const AvatarPlaceholder(),
  error: (context, error) => const AvatarPlaceholder(),
)

// For Flutter's widgets that take an ImageProvider.
CircleAvatar(backgroundImage: ResourceImage(player.avatarUrl))
```

## How it works

- **Where.** In the files' `cache` place (the system may clear it; IndexedDB in a browser): `spring/resources/<sha256 of the address>/`, the bytes in `data` and in `meta.json` the address, the digest of the bytes, the media type, when it was fetched, `ETag` and `Last-Modified`.
- **Freshness.** A kept resource is read from the disk. Past its age it is still read from the disk, and asked again in the background with `If-None-Match` / `If-Modified-Since`: an unchanged one costs no download. Bytes that do not match their digest are downloaded again.
- **A limit of their own.** `spring.flutter.resources.cache.max-size` is for the resources alone, their folder `spring/resources/`; past it the least recently used go first. The `@Cacheable` results kept on disk ([`spring.cache.type: disk`](../spring-boot-starter-cache/disk-caches.md), `spring/caches/`) are data, not files: a cache of their own with limits of their own, not counted here, not cleared with the resources.
- **The app's own resources** (`asset:`, `resources:`) are never copied there; in a browser its HTTP cache keeps them, as [the web build's headers](cache-headers.md) say.
- **One widget.** `ResourceView` reads the resource, finds its media type (the server's, else the extension) and the first `ResourceRenderer` bean that shows it, and does the rest the same for every kind: the placeholder, the error, the fade, the size, the shape, the semantics. Images are the starter's (`ImageResourceRenderer`); an app adds a renderer for a document or a video as one more bean.

```dart
@Component()
class PdfRenderer implements ResourceRenderer {
  @override
  bool supports(String mediaType) => mediaType == 'application/pdf';

  @override
  Widget build(BuildContext context, LoadedResource resource,
          ResourceLayout layout) =>
      PdfView(bytes: resource.bytes);
}
```

## A video with the player you chose

The framework has no player: a kept resource gives `playableUri()`, the address a player can play it from: the kept file (`file:`), a `blob:` of it in a browser, or, the first time, its own address while it is being kept for the next time.

```dart
final clip = resources.getResource(highlightUrl) as CachedResource;
final uri = await clip.playableUri();
final controller = uri.scheme == 'file'
    ? VideoPlayerController.file(File(uri.toFilePath()))
    : VideoPlayerController.networkUrl(uri);
await controller.initialize();
```

A single file is kept (mp4, webm); a playlist of pieces (HLS, DASH) is not, and a file still being written is played from the network.

## Properties

| Key | Default | Meaning |
|---|---|---|
| `spring.flutter.resources.cache.enabled` | `true` | Whether `http(s)` resources are kept |
| `spring.flutter.resources.cache.max-age` | `7d` | How long one is used as it is |
| `spring.flutter.resources.cache.max-entry-size` | `50MB` | The largest one kept |
| `spring.flutter.resources.cache.max-size` | none | The most bytes the kept resources take, together |
| `spring.flutter.resources.cache.locations` | none | Rules by address: `pattern`, `max-age`, `enabled` |
| `spring.flutter.resources.view.fade` | `200ms` | The fade of a `ResourceView` |
