Capsule Supplement

Starter pack for using Capsule with common upload sources and storage solutions.

Add capsule_supplement to your mix.exs dependencies:

{:capsule_supplement, "~> 1.0"}

Supplement's only required dependency is Capsule itself. However, some of the implementations might require further dependencies (currently only S3) that you will also need to add to your project's deps. Consult the relevant dependencies section below.

Storages

All storages implement the Capsule.Storage behaviour. Supplement ships with the following implementations:

• Disk
• S3
• RAM

Disk

This saves uploaded files to a local disk. It is useful for caching uploads while you validate other data, and/or perform some file processing.

configuration

• root_dir (required): The root directory where files will be stored. Example: Application.put_env(:capsule, Capsule.Storages.Disk, root_dir: "tmp")

options

• prefix: This should be a valid system path that will be appended to the root. If it does not exist, Disk will create it.
• force: If this option is set to a truthy value, Disk will overwrite any existing file at the derived path. Use with caution!

notes

Since it is possible for files with the same name to be uploaded multiple times, Disk needs some additional info to uniquely identify the file. Disk does not overwrite files with the same name by default. To ensure an upload can be stored, the combination of the Upload.name and prefix should be unique.

S3

This storage uploads files to AWS's S3 service. It also works with Digital Ocean Spaces.

configuration

• bucket (required): The bucket where files will be stored. Example: Application.put_env(:capsule, Capsule.Storages.S3, bucket: "whatever")

options

• key: Path to store upload in bucket
• s3_options: Keyword list of options that will be passed directly to ex_aws_s3

dependencies

{:ex_aws, "~> 2.0"}
{:ex_aws_s3, "~> 2.0"}

RAM

Uses Elixir's StringIO module to store file contents in memory. Since the "files" are essentially just strings, they will not be persisted and will error if they are read back from a database, for example. However, operations are correspondingly very fast and thus suitable for tests or other temporary file operations.

Uploads

Supplement implements the Capsule.Upload protocol for the following modules:

• URI
• Plug.Upload

URI

This is useful for transferring files already hosted elsewhere, for example in cloud storage not controlled by your application, or a TUS server.

You can use it to allow users to post a url string in lieu of downloading and reuploading a file. A Phoenix controller action implementing this feature might look like this:

def attach(conn, %{"attachment" => %{"url" => url}}) when url != "" do
  uri = URI.parse(url)
  Disk.put(uri)

  # ...redirect, etc
end

configuration

None

options

None

notes

This implementation imposes a hard timeout limit of 15 seconds to download the file from the remote location.

Plug.Upload

This supports multi-part form submissions handled by Plug.

configuration

None

options

None

notes

None