Struct couchdb::attachment::Attachment

pub struct Attachment { /* fields omitted */ }

Attachment is a state-aware representation of a CouchDB document attachment.

Summary

• Attachment maintains state about whether it already exists on the server (i.e., originates from the server) or not (i.e., originates from the client).

• A CouchDB attachment may be stubbed, meaning it has no content but instead is a placeholder for attachment content that already exists on the server.

• An Attachment instance deserialized from JSON is server-originating.

• An Attachment instance constructed from content (e.g., via the Attachment::new method) is client-originating.

• When serialized to JSON, a server-originating Attachment instance emits a stub object—regardless whether the Attachment instance is a stub.

• When serialized to JSON, a client-originating Attachment instance emits a non-stub object that uses base64-encoding to encapsulate its content.

• Attachment supports conversion into a stub, which is useful when either:

  • Updating a document but not making changes to its existing attachments, or,
  • Uploading attachments via multipart-encoding.

Remarks

CouchDB document attachments are versatile but tricky. Generally speaking, there are several things the application must get right:

• When updating a document on the server, the client must send existing attachments—either stubbed or containing full content—otherwise the server will delete missing attachments as part of the document update.

• When enclosing attachment content directly in JSON, the content must be base64-encoded.

• To prevent sending redundant data to the server, the application serializes unmodified attachments as stubs (via "stub": true within the attachment object).

• When using multipart-encoding in lieu of base64-encoding, the application serializes attachments into yet another form (via "follows": true within the attachment object).

TODO

• Add a means for applications to construct server-originating attachments from multipart data.

Methods

impl Attachment

fn new(content_type: Mime, content: Vec<u8>) -> Self

Constructs a new attachment.

The newly constructed Attachment is internally marked as having originated from the client and therefore, when serialized as JSON, will include all content as a base64-encoded string (as opposed to being stubbed out). This may incur significant overhead when sent to the CouchDB server within an enclosed document because base64-encoding uses four encoded bytes to represent every three encoded bytes.

One way to reduce base64 overhead is to stub the attachment and instead use multipart-encoding when uploading the document. See the CouchDB documentation for details.

fn is_server_origin(&self) -> bool

Returns whether the attachment originates from the server.

fn is_client_origin(&self) -> bool

Returns whether the attachment originates from the client.

fn content_type(&self) -> &Mime

Borrows the attachment's content MIME type.

fn content(&self) -> Option<&[u8]>

Borrows the attachment's content, if available.

Content is available if and only if:

• The attachment originates from the client, or,
• The attachment originates from the server and is not a stub.

fn content_length(&self) -> u64

Returns the size of the attachment's content, in bytes.

fn to_stub(&self) -> Option<Attachment>

Constructs a stubbed copy of the attachment.

A stubbed attachment contains no content, instead marking itself as a stub and relying on the CouchDB server to already have the content if the attachment is sent to the server within its enclosing document.

Hence, only an attachment that originates from the server can be stubbed. Otherwise, content would be lost, which this method prevents by instead returning None if the attachment originates from the client.

Note: The stub retains all other information about the attachment, such as content type and digest.

fn to_multipart_stub(&self) -> Attachment

Constructs a stubbed copy of the attachment suitable for multipart-encoding.

The returned attachment loses all information about the attachment except for its content type and content length. The intention is for the application to:

1. Serialize the attachment stub within an enclosed document, as JSON, and,

2. Send the attachment content as multipart data, within the same HTTP request.

See the CouchDB documentation for details.

Example

extern crate couchdb;
extern crate mime;
extern crate serde_json;

let att = couchdb::Attachment::new(
    mime::TEXT_PLAIN,
    Vec::from(b"Lorem ipsum dolor sit amet".as_ref())
).to_multipart_stub();

let encoded = serde_json::to_vec(&att).unwrap();

// encoded:
//
// {
//     "content_type": "text/plain",
//     "follows": true,
//     "length": 26
// }

fn digest(&self) -> Option<&Digest>

Borrows the attachment's digest, if available.

An attachment's digest is available if and only if it originates from the server.

fn encoding(&self) -> Option<&Encoding>

Returns the attachment's encoding information, if available.

fn revision_sequence(&self) -> Option<u64>

Returns the attachment's revision sequence number—i.e., the revpos attachment field.

Trait Implementations

impl Clone for Attachment

fn clone(&self) -> Attachment

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Attachment

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Eq for Attachment

impl PartialEq for Attachment

fn eq(&self, __arg_0: &Attachment) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &Attachment) -> bool

This method tests for !=.

impl<'a> Deserialize<'a> for Attachment

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'a>, 

Deserialize this value from the given Serde deserializer.

impl Serialize for Attachment

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.