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:
Belt.Provider.Filesystem
for local storageBelt.Provider.SFTP
for storing on SFTP servers with private key and username/password authenticationBelt.Provider.S3
supports services with S3-compatible APIs such as Amazon S3, EMC Elastic Cloud Storage or Minio thoughExAws
.
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
Options for all requests made through Belt. Additional options might be supported by certain providers and are documented there.
Link to this section Functions
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 interm
{:error, :timeout}
- Job timed out
delete(Belt.Provider.configuration(), Belt.Provider.identifier(), [ Belt.Provider.delete_option() ]) :: :ok | {:error, String.t()}
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(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
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
get_info(Belt.Provider.configuration(), Belt.Provider.file_identifier(), [ Belt.Provider.info_option() ]) :: {:ok, Belt.FileInfo.t()} | {:error, term()}
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(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(Belt.Provider.configuration(), [Belt.Provider.list_files_option()]) :: {:ok, [Belt.Provider.identifier()]} | {:error, term()}
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(Belt.Provider.configuration(), Belt.Provider.file_source(), [ Belt.Provider.store_option() ]) :: {:ok, Belt.FileInfo.t()} | {:error, term()}
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 returnedBelt.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 fromfile_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(Belt.Provider.configuration(), Belt.Provider.file_source(), list()) :: {:ok, Belt.Job.t()}
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
.
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 returnedBelt.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
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
.
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