Belt v0.5.1 Belt View Source

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{…}}

Link to this section 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

Stores iodata using config and waits for the upload to complete

Asynchronously stores iodata using config

Tests if the connection to a Provider can be successfully established

Link to this section Types

Link to this type request_option() View Source
request_option() :: {:timeout, integer()}

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

Link to this section Functions

Link to this function await(job, options \\ []) View Source
await(Belt.Job.t(), [{atom(), term()}]) ::
  :ok | {: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

Returns

This function relays the return values of the individual Job callbacks:

  • :ok - Job completed successfully without additional return value (e. g. Belt.delete/3)
  • {:ok, term} - Job completed successfully with additional return value (e. g. Belt.store/2)
  • {:error, term} - Job experienced an error, further specified in term
  • {:error, :timeout} - Job timed out
Link to this function delete(config, identifier, options \\ []) View Source

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
Link to this function delete_all(config, options \\ []) View Source
delete_all(Belt.Provider.configuration(), [Belt.Provider.delete_option()]) ::
  :ok | {:error, term()}

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
Link to this function delete_scope(config, scope, options \\ []) View Source
delete_scope(Belt.Provider.configuration(), String.t(), [
  Belt.Provider.delete_option()
]) :: :ok | {:error, term()}

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
Link to this function get_info(config, identifier, options \\ []) View Source

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
Link to this function get_url(config, identifier, options \\ []) View Source
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
Link to this function list_files(config, options \\ []) View Source

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
Link to this function store(config, file_source, options \\ []) View Source

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 - [Belt.Hasher.hash_algorithm] - 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
Link to this function store_async(config, file_source, options \\ []) View Source

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.

Link to this function store_data(config, iodata, options \\ []) View Source
store_data(Belt.Provider.configuration(), iodata(), [
  Belt.Provider.store_option()
]) :: {:ok, Belt.FileInfo.t()} | {:error, term()}

Stores iodata using config and waits for the upload to complete.

Use this instead of store/3 when your data is in-memory.

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

Options

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

  • :key - String.t - The key to be used for storing the file. For most providers, this corresponds to the file name. Required.
  • :hashes - [Belt.Hasher.hash_algorithm] - Hashes to include in the returned Belt.FileInfo struct.
  • :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
Link to this function store_data_async(config, iodata, options \\ []) View Source
store_data_async(Belt.Provider.configuration(), iodata(), list()) ::
  {:ok, Belt.Job.t()}

Asynchronously stores iodata using config.

Use this instead of store_async/3 when your data is in-memory.

Returns {:ok, Belt.Job.t}

For available options see Belt.store/3.

Link to this function test_connection(config, options \\ []) View Source
test_connection(Belt.Provider.configuration(), [request_option()]) ::
  :ok | {:error, term()}

Tests if the connection to a Provider can be successfully established.

Options

  • :timeout - integer - Maximum time (in milliseconds) to wait for the job to finish