Belt v0.2.0 Belt

Extensible OTP Application written in Elixir for storing files remotely or locally through a unified API.

The following backends are currently included:

Installation & Configuration

For more information on how to install and configure Belt, please take a look at the Getting Started guide.

Basic usage

#Simple file upload
{:ok, config} = Belt.Provider.SFTP.new(host: "example.com", directory: "/var/files",
                                       user: "…", password: "…")
Belt.store(config, "/path/to/local/file.ext")
#=> {:ok, %Belt.FileInfo{…}}


#Asynchronous file upload
{:ok, config}  = Belt.Provider.S3.new(access_key_id: "…", secret_access_key: "…",
                                      bucket: "belt-file-bucket")
{:ok, job} = Belt.store_async(config, "/path/to/local/file.ext")
#Do other things while Belt is uploading in the background
Belt.await(job)
#=> {:ok, %Belt.FileInfo{…}}

Summary

Types

Options for all requests made through Belt. Additional options might be supported by certain providers and are documented there

Functions

Convenience function for awaiting the reply of a running Belt.Job

Deletes file identified by its configuration and identifier

Deletes all files stored at the location specified by config

Deletes all files stored within a given scope at a location specified with config

Retrieves information about a file in a Belt.FileInfo struct

Retrieves the public URL of a file (if available) identified by its identifier and configuration. Additional options might be supported by specific providers

Returns list of all available file identifiers for a given configuration

Stores data from file_source using config and waits for the upload to complete. file_source can either be a local path to a file or a struct following the structure of %Plug.Upload{}

Asynchronously stores data from file_source using config

Types

request_option()
request_option() :: {:timeout, integer}

Options for all requests made through Belt. Additional options might be supported by certain providers and are documented there.

Functions

await(job, options)
await(Belt.Job.t, [{atom, term}]) ::
  {:ok, term} |
  {:error, :timeout} |
  {:error, term}

Convenience function for awaiting the reply of a running Belt.Job.

Terminates the Job after it has been completed or the timeout has expired.

Options

  • :timeout - integer - Maximum time (in milliseconds) to wait for the job to finish
delete(config, identifier, options \\ [])

Deletes file identified by its configuration and identifier.

Options

The following options are supported by all providers. Some providers might offer additional options.

  • :timeout - Timeout for this call in milliseconds
delete_all(config, options \\ [])

Deletes all files stored at the location specified by config.

Use with caution: this can also delete files which were not stored with Belt.

Options

The following options are supported by all providers. Some providers might offer additional options.

  • :timeout - Timeout for this call in milliseconds
delete_scope(config, scope, options \\ [])

Deletes all files stored within a given scope at a location specified with config.

Use with caution: this can also delete files which were not stored with Belt.

Options

The following options are supported by all providers. Some providers might offer additional options.

  • :timeout - Timeout for this call in milliseconds
get_info(config, identifier, options \\ [])

Retrieves information about a file in a Belt.FileInfo struct.

Example

Belt.get_info(config, identifier, hashes: [:sha256])
#=> {:ok, %Belt.FileInfo{hashes: ["2c2…7ae"], …}}

Options

The following options are supported by all providers. Some providers might offer additional options.

  • :hashes - Include a list with hashes of the given algorithms in the result
  • :timeout - Timeout for this call in milliseconds
get_url(config, identifier, options \\ [])
get_url(Belt.Provider.configuration, Belt.Provider.file_identifier, [Belt.Provider.url_option]) ::
  {:ok, String.t} |
  :unavailable |
  {:error, term}

Retrieves the public URL of a file (if available) identified by its identifier and configuration. Additional options might be supported by specific providers.

Returns {:ok, url}, :unavailable or {:error, term}.

Options

The following options are supported by all providers. Some providers might offer additional options.

  • :timeout - Timeout for this call in milliseconds
list_files(config, options \\ [])

Returns list of all available file identifiers for a given configuration.

Options

The following options are supported by all providers. Some providers might offer additional options.

  • :timeout - Timeout for this call in milliseconds
store(config, file_source, options \\ [])

Stores data from file_source using config and waits for the upload to complete. file_source can either be a local path to a file or a struct following the structure of %Plug.Upload{}.

Returns {:ok, %Belt.FileInfo{}} or {:error, reason}

Options

The following options are supported by all providers. Some providers might offer additional options.

  • :hashes - [:crypto.hash_algorithms] - Hashes to include in the returned Belt.FileInfo struct.
  • :key - String.t | :auto - The key to be used for storing the file. For most providers, this corresponds to the file name. When set to :auto, Belt tries to derive a key name from file_source. Defaults to :auto
  • :overwrite - true | false | :rename - How to handle conflicting keys. Defaults to :rename.
  • :scope - String.t - A namespace to be used for storing the file. For most providers, this corresponds to the name of a subdirectory.
  • :timeout - integer - Timeout (in milliseconds) for the request
store_async(config, file_source, options \\ [])

Asynchronously stores data from file_source using config.

file_source can either be a local path to a file or a struct following the structure of %Plug.Upload{}.

Returns {:ok, Belt.Job.t}

For available options see Belt.store/3.