Plug.Upload (Plug v1.12.1) View Source

A server (a GenServer specifically) that manages uploaded files.

Uploaded files are stored in a temporary directory and removed from that directory after the process that requested the file dies.

During the request, files are represented with a Plug.Upload struct that contains three fields:

:path - the path to the uploaded file on the filesystem
:content_type - the content type of the uploaded file
:filename - the filename of the uploaded file given in the request

Note: as mentioned in the documentation for Plug.Parsers, the :plug application has to be started in order to upload files and use the Plug.Upload module.

Security

The :content_type and :filename fields in the Plug.Upload struct are client-controlled. These values should be validated, via file content inspection or similar, before being trusted.

Link to this section Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

give_away(upload, to_pid, from_pid \\ self())

Assign ownership of the given upload file to another process.

random_file(prefix)

Requests a random file to be created in the upload directory with the given prefix.

random_file!(prefix)

Requests a random file to be created in the upload directory with the given prefix. Raises on failure.

Link to this section Types

t()

Specs

t() :: %Plug.Upload{
  content_type: binary() | nil,
  filename: binary(),
  path: Path.t()
}

Link to this section Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

give_away(upload, to_pid, from_pid \\ self())

Specs

give_away(t() | binary(), pid(), pid()) :: :ok | {:error, binary()}

Assign ownership of the given upload file to another process.

Useful if you want to do some work on an uploaded file in another process since it means that the file will survive the end of the request.

random_file(prefix)

Specs

random_file(binary()) ::
  {:ok, binary()}
  | {:too_many_attempts, binary(), pos_integer()}
  | {:no_tmp, [binary()]}

Requests a random file to be created in the upload directory with the given prefix.

random_file!(prefix)

Specs

random_file!(binary()) :: binary() | no_return()

Requests a random file to be created in the upload directory with the given prefix. Raises on failure.