Url generation.

Saving your files is only the first half of any decent storage solution. Straightforward access to your uploaded files is equally as important as storing them in the first place.

Often times you will want to regain access to the stored files. As such, Waffle facilitates the generation of urls.

# Given some user record
user = %{id: 1}

Avatar.store({%Plug.Upload{}, user}) #=> {:ok, "selfie.png"}

# To generate a regular, unsigned url (defaults to the first version):
Avatar.url({"selfie.png", user})
#=> "https://bucket.s3.amazonaws.com/uploads/1/original.png"

# To specify the version of the upload:
Avatar.url({"selfie.png", user}, :thumb)
#=> "https://bucket.s3.amazonaws.com/uploads/1/thumb.png"

# To generate a signed url:
Avatar.url({"selfie.png", user}, :thumb, signed: true)
#=> "https://bucket.s3.amazonaws.com/uploads/1/thumb.png?AWSAccessKeyId=AKAAIPDF14AAX7XQ&Signature=5PzIbSgD1V2vPLj%2B4WLRSFQ5M%3D&Expires=1434395458"

# To generate urls for all versions:
Avatar.urls({"selfie.png", user})
#=> %{original: "https://.../original.png", thumb: "https://.../thumb.png"}

Default url

In cases where a placeholder image is desired when an uploaded file is not present, Waffle allows the definition of a default image to be returned gracefully when requested with a nil file.

def default_url(version) do
  MyApp.Endpoint.url <> "/images/placeholders/profile_image.png"
end

Avatar.url(nil) #=> "http://example.com/images/placeholders/profile_image.png"
Avatar.url({nil, scope}) #=> "http://example.com/images/placeholders/profile_image.png"

Virtual Host

To support AWS regions other than US Standard, it may be required to generate urls in the virtual_host style. This will generate urls in the style: https://#{bucket}.s3.amazonaws.com instead of https://s3.amazonaws.com/#{bucket}.

To use this style of url generation, your bucket name must be DNS compliant.

This can be enabled with:

config :waffle,
  virtual_host: true

When using virtual hosted–style buckets with SSL, the SSL wild card certificate only matches buckets that do not contain periods. To work around this, use HTTP or write your own certificate verification logic.

Asset Host

You may optionally specify an asset host rather than using the default bucket.s3.amazonaws.com format.

In your application configuration, you'll need to provide an asset_host value:

config :waffle,
  asset_host: "https://d3gav2egqolk5.cloudfront.net", # For a value known during compilation
  asset_host: {:system, "ASSET_HOST"} # For a value not known until runtime