ImagePipe.Source.File (image_pipe v0.1.0)

Copy Markdown View Source

Source adapter for image files below a directory.

media: [
  adapter: ImagePipe.Source.File,
  match: :path,
  options: [root: "/srv/images", root_id: "media"]
]

It resolves path sources, so photos/beach.jpg and /photos/beach.jpg both read /srv/images/photos/beach.jpg. Paths can't leave the root. A path that names no regular file is not found. Setting up a mount is covered in Serving images from local files.

A file that isn't stable: :immutable is identified by the SHA-256 of its bytes. After hashing, its size, mtime, ctime, inode, and device are kept, and a later request whose stat matches reuses the hash without reading the file. Stat times have one-second resolution, so a file whose mtime or ctime falls in the second it was hashed is hashed again on the next request. On a network filesystem the times come from the server's clock.

Options

  • :root (String.t/0) - Required. Directory the source serves. A relative path is expanded against the working directory when the configuration is built.

  • :root_id (String.t/0) - Required. Stable name for the directory. Caches identify the source's files by :root_id and path instead of by :root, so keep the name when the directory moves, and change it when the directory holds different files. File sources with the same :root_id share cache entries and must have the same :root.

  • :verify (:stat or :hash) - How a file that can change is checked. :stat reuses the file's hash while its size, timestamps, inode, and device are unchanged. :hash reads and hashes the file on every check, for filesystems whose times can't be trusted, such as a network filesystem whose server clock can lag behind this host's. The default value is :stat.

  • :copy (:none or :keep) - :keep stores a copy of each original in the originals cache, so other sizes and formats don't read the file again. Use it on network filesystems such as EFS or NFS. Needs :input_cache configured. The default value is :none.

  • :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.