@spec delete(doc_ref(), Sofa.t(), String.t(), keyword()) ::
  {:ok, Sofa.Doc.t()} | {:error, error()}

Deletes an attachment, and returns the document with its new revision and without the stub. A revision is required, from the document or as rev:. batch: :ok defers the write as the docs describe.

@spec delete!(doc_ref(), Sofa.t(), String.t(), keyword()) :: Sofa.Doc.t()

Bang! version of delete/4. Returns the updated document or raises Sofa.Error.

@spec digest(binary()) :: digest()

The md5- digest CouchDB reports for content.

CouchDB computes it over the bytes it stores. For content types in its compressible_types list, such as text/plain, those are the gzipped bytes, so the digest of such an attachment does not match its plain content. encoding tells the two apart.

iex> Sofa.Attachment.digest("My hovercraft is full of eels!")
"md5-uoLJeG8NfCWNzP/3AI2Ytw=="

@spec from_stub(String.t(), map()) :: t()

Builds an attachment from one entry of a document's _attachments.

Inline data is base64 decoded. A stub keeps data as nil.

@spec get(Sofa.t(), doc_ref(), String.t(), keyword()) ::
  {:ok, t() | :not_modified} | {:error, error()}

Fetches an attachment's content with the metadata from the response headers. The bytes are verified against the digest CouchDB sends as the ETag, giving {:error, :digest_mismatch} if they differ, and an attachment CouchDB stored gzipped is then decompressed, with encoding and encoded_length recording that.

Options

• rev: and if_none_match: as for head/4
• range: a first..last byte range, fetched with a Range header. length is then the size of the part, which is not verified
• into: a Req sink, such as File.stream!(path) or a function, for content too large to hold in memory. data is then whatever the sink returns, decompressed by Req on the way but not verified

Examples

{:ok, att} = Sofa.Attachment.get(db, doc, "recipe.txt")
att.data
#=> "1. Cook spaghetti\\n2. Cook meatballs\\n..."

Sofa.Attachment.get(db, doc, "video.mp4", into: File.stream!("/tmp/video.mp4"))
#=> {:ok, %Sofa.Attachment{data: %File.Stream{}, ...}}

@spec get!(Sofa.t(), doc_ref(), String.t(), keyword()) :: t()

Bang! version of get/4. Returns the attachment or raises Sofa.Error.

@spec head(Sofa.t(), doc_ref(), String.t(), keyword()) ::
  {:ok, t() | :not_modified} | {:error, error()}

Fetches an attachment's metadata from the headers of a HEAD request: content type, size and the digest CouchDB uses as the ETag.

For an attachment CouchDB stored compressed, encoding is set and encoded_length holds the size from the headers, which is the compressed one as the docs warn. The plain length is then unknown.

Options

• rev: a document revision, otherwise the current one is used
• if_none_match: a digest. {:ok, :not_modified} is returned when it still matches

Examples

Sofa.Attachment.head(db, "SpaghettiWithMeatballs", "recipe.txt")
#=> {:ok, %Sofa.Attachment{name: "recipe.txt", content_type: "text/plain", ...}}

@spec new(String.t(), binary(), keyword()) :: t()

An attachment with content, ready to be attached to a document.

The content type comes from the name via MIME.from_path/1, falling back to application/octet-stream, unless given as content_type:. The digest is left to CouchDB, which computes it over the bytes it stores.

@spec put(doc_ref(), Sofa.t(), String.t(), content(), keyword()) ::
  {:ok, Sofa.Doc.t()} | {:error, error()}

Uploads content as an attachment in its own request, and returns the document with its new revision and the attachment's stub, ready for the next write. The document comes first so that uploads pipe.

The document's rev is sent as If-Match, which CouchDB requires for an existing document. A document without one, or a bare id, is created by the upload, as the docs describe. Content is a binary, {:file, path} streamed from disk, or any enumerable of binaries sent as a chunked upload. The returned stub has no digest, as CouchDB computes that over the bytes it stores, which it may compress first.

Options

• content_type: the MIME type, by default taken from the name via MIME.from_path/1
• rev: a revision to use instead of the document's

Examples

doc
|> Sofa.Attachment.put!(db, "recipe.txt", File.read!("recipe.txt"))
|> Sofa.Attachment.put!(db, "video.mp4", {:file, "video.mp4"})

@spec put!(doc_ref(), Sofa.t(), String.t(), content(), keyword()) :: Sofa.Doc.t()

Bang! version of put/5. Returns the updated document or raises Sofa.Error.

@spec to_stub(t()) :: map()

The _attachments entry for an attachment: inline, with the content base64 encoded, when it has content, otherwise a stub that tells CouchDB to keep the attachment it already has. Keys CouchDB did not report are left out.

@spec verified?(t()) :: boolean()

Whether the content matches the digest. false when either is missing, or when CouchDB stored the content compressed, as the digest then covers the gzipped bytes. get/4 verifies those while it still has them.

iex> att = Sofa.Attachment.new("a.bin", "eels")
iex> %{att | digest: Sofa.Attachment.digest("eels")} |> Sofa.Attachment.verified?()
true
iex> %Sofa.Attachment{name: "a", content_type: "text/plain"} |> Sofa.Attachment.verified?()
false