ImagePipe.Source.CacheSettings (image_pipe v0.1.0)

Copy Markdown View Source

Cache settings shared by source adapters.

The built-in adapters accept these options, and a custom adapter can append schema/0 to its own option schema to accept them too:

@schema NimbleOptions.new!([bucket: [type: :string, required: true]] ++ CacheSettings.schema())

After validating, validate/1 rejects a lifetime or stale window on an immutable source. fields/2 then turns the validated options into the cache fields of ImagePipe.Source.Resolved. Their effect is explained in Caching and freshness.

Options

  • :stable (:auto or :immutable) - :immutable marks an immutable source: an identifier always names the same bytes, so its originals and processed images never expire and are never revalidated. With :auto, each original is identified by its content. See immutable sources. The default value is :auto.

  • :cache_policy (keyword/0) - Cache policy for this source, with the fields of ImagePipe.Source.CachePolicy. Each field it sets replaces that field of the :source_cache_policy of ImagePipe.config/1. A source with stable: :immutable can't set a :freshness duration or a :stale_while_revalidate window. The default value is [].

  • :internal_cache (:auto, :enabled, or :disabled) - :disabled keeps this source's originals and processed images out of the caches, including images that use this source for a watermark. :auto and :enabled cache what the source's storage policy allows. The default value is :auto.

  • :http_cache (:inherit, :validators, :auto, :public, or :private) - HTTP cache headers for responses from this source. :inherit uses the mount's :http_cache (see ImagePipe.Plug), and any other value replaces it. See per-source modes. The default value is :inherit.

Summary

Functions

fields(opts, source)

Returns the :internal_cache, :http_cache, and :cache_semantics fields of ImagePipe.Source.Resolved.

immutable?(opts)

Whether the options mark the source as immutable.

schema()

NimbleOptions schema entries for the shared cache settings.

validate(opts)

Rejects a TTL or stale-while-revalidate window on an immutable source, which has no freshness deadline. Returns the options unchanged when valid.

Functions

fields(opts, source)

@spec fields(keyword(), keyword()) :: keyword()

Returns the :internal_cache, :http_cache, and :cache_semantics fields of ImagePipe.Source.Resolved.

Takes the validated options and:

  • :stable? - whether this source's bytes can't change, either because the options trust it or because the source itself pins them.
  • :seed - the byte-identity seed used when the source is stable. It must not contain secrets.
  • :copy? - whether to keep a local copy of the original in the input pool. Remote adapters pass true.

A source that isn't stable is identified by its content. internal_cache: :auto enables internal caching.

immutable?(opts)

@spec immutable?(keyword()) :: boolean()

Whether the options mark the source as immutable.

schema()

@spec schema() :: keyword()

NimbleOptions schema entries for the shared cache settings.

validate(opts)

@spec validate(keyword()) ::
  {:ok, keyword()} | {:error, {:invalid_source_config, String.t()}}

Rejects a TTL or stale-while-revalidate window on an immutable source, which has no freshness deadline. Returns the options unchanged when valid.