chill-rs / chill

CouchDB client-side library for the Rust programming language

Chill

Chill is a client-side CouchDB library for the Rust programming language, available on crates.io. It targets Rust Stable.

Chill's three chief design goals are convenience, safety, and efficiency.

You can read more about its design and development here:

• Rethinking CouchDB in Rust (2016-02-23)
• Announcing Chill v0.1.1 (2016-04-18)

Roadmap

Chill's most recent release is v0.3.0, available as of 2016-10-01.

• v0.3.0 change log
• v0.3.0 documentation
• v0.3.0 issues
• v0.3.0 crates.io page

The next release will be v0.4.0 and will entail:

• A much-needed refresh of dependencies, Serde v1.x perhaps being the most important, and,
• Possibly an overhaul of the API to support asynchronous I/O via the Tokio model.

License

Chill is licensed under either of:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0), or,
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT).

Feedback

Do you find this crate useful? Not useful? Please send feedback!

chill's Issues

New action for bulk docs

Add a new action type for creating/updating/deleting documents in bulk via /db/_bulk_docs.

New support for asynchronous actions

Add support for running actions asynchronously.

Upgrade to url v1.x

The url crate released v1.x, with significant API changes.

New action to delete an attachment standalone

Add an action to delete an attachment—i.e., an action that sends an HTTP request to DELETE /db/docid/attachment.

Consider simplifying type parameterization for view execution

The ExecuteView action, along with related types such as ViewResponse, require applications to explicitly provide Key and Value type parameters. Consider changing the API to allow for type inference.

Replace AttachmentName type alias with a real type

The Document type relies on an AttachmentName type aliased to a String. Replace this with a real AttachmentName type (analogous to the DatabaseName type). Here's a snapshot of the source.

It makes the most sense to resolve this when Chill's API gains support for attachments.

New action to get all docs

Working on it :)

New support for the `key` query parameter when executing a view

Add support for the key query parameter when executing a view.

New action to read an attachment standalone

Add an action to read an attachment—i.e., an action that sends an HTTP request to GET /db/docid/attachment.

New support for creating, updating, and deleting attachments as part of updating a document

Add support for automatically creating, updating, and/or deleting attachments whenever the client updates a document.

Add support to ViewResponse for group-reduced views

Here are the issues for adding support for group-reduced views: #23 and #24.

Group-reduced views are technically reduced, but, structurally, their responses have the same form as unreduced views in that they consist of an array of key–value pairs. Correction: Group-reduced view responses lack the total_rows and offset fields.

Instead of distinguishing the two view variants by reduced vs unreduced, we should distinguish by scalar (i.e., value only) vs non-scalar (i.e., array of key–value pairs).

Group-reduced view responses may have multiple rows, with each row containing a non-null key and a value. Currently, Chill's ViewResponse enum has two variants, Reduced and Unreduced, with the reduced variant having exactly one value.

It may make sense to convert ViewResponse from an enum to a struct, thereby eliminating the distinction between reduced and unreduced views.

Optimize ViewRow to not clone and re-decode key and value

Currently, ViewRow clones and re-decodes (from JSON) the row's key and value in its key and value methods. It map be better to avoid this duplication of effort. Perhaps we could store the raw JSON text and do the decoding only once, during the call to key or value.

Consider removing the `Document::id` method

Document provides a path method returning a DocumentPath. The document id should be gotten from the path, not from a special Document::id method.

New action to create a database

Design and implement a new action type for creating a database. This action will have no options.

New support for the `descending` query parameter when executing a view

Add support for the descending query parameter when executing a view.

New support for the `reduce` query parameter when executing a view

Add support for the reduce query parameter when executing a view.

New action to update an attachment standalone

Add an action to update an attachment—i.e., an action that sends an HTTP request to PUT /db/docid/attachment.

New support for getting attachments as part of reading a document

Add support for optionally including attachment content as part of reading a document. This can at first be implemented by using the ?attachments query parameter for GET /db/doc, though long-term this should be implemented using multipart.

A lot of the infrastructure for handling document attachments is already implemented as of v0.1.0, but some design work will need to be done to expose the attachments via the Chill API.

New support for the `group` query parameter when executing a view

Add support for the group query parameter when executing a view.

Travis CI builds don't run documentation tests

The Travis CI builds don't run documentation tests.

The root cause is that Cargo doesn't support running doc tests without also running integration tests, and Chill's integration tests can't run on a build agent because of the CouchDB dependency.

Here's the relevant Cargo issue.

New support for the `endkey` query when executing a view

Add support for the endkey query parameter when executing a view.

New support for the `inclusive_end` query parameter when executing a view

Add support for the inclusive_end query parameter when executing a view.

Simplify path-related types

The path-related types should be as convenient to use as possible while retaining strong type-safety to guard against, say, a programmer mistakenly referencing a normal document when a design document is needed. See my commentary below for what this means specifically.

As they're currently implemented, the path-related types cannot all implement Borrow. E.g., impl std::borrow::Borrow<DocumentPathRef> for DocumentPath makes no sense. One consequence is that when these types are stored as keys in a HashMap, each lookup into that collection requires a temporary heap allocation.

Here's the relevant StackOverflow question:
http://stackoverflow.com/q/36480845/1094609

By using a Cow as the underlying storage for path-related types, we could implement Borrow. We could also eliminate the distinction between owning-types and borrowing-types—e.g., DocumentPath and DocumentPathRef<'a> would collapse into a single DocumentPath<'a> type. However, one downside is that the new type would require a lifetime parameter, which may be too bitter a pill to swallow.

Unit tests for the HyperTransport

The HyperTransport is tested indirectly, via the integration tests. Consider writing unit tests for it to ensure all cases are covered.

Consider generalizing the transport layer regarding queries and bodies

Currently, the transport layer is specific to the CouchDB API. For example, the RequestOptions struct contains values for CouchDB-specific query parameters. Consequently, to add support for a new query parameter, the programmer must extend RequestOptions by adding a new field, as well as touching several other points in the transport layer to handle that new field.

New support for the `limit` query parameter when executing a view

Add support for the limit query parameter when executing a view.

Delay handling of path parsing errors?

Currently, executing an action requires unwrapping of two results:

let foo = db.action().unwrap().run().unwrap();

For some actions, there are a few more, like when you're receiving a document:

let content = foo.get_conent().unwrap();

This results in a lot of nested try! calls. IMO, we should change the actions to return Self and store the path as Result<Path, Error> that gets unwrapped in run(). That's also how hyper does it.

Integration tests emit Erlang noise on Windows

The cargo test command on Windows emits noisy [os_mon] lines to stderr. This output should be omitted.

Here's an example run:

     Running target\debug\actions-660b01cc45c8e1bd.exe

running 6 tests
[os_mon] win32 supervisor port (win32sysinfo): Erlang has closed
[os_mon] win32 supervisor port (win32sysinfo): Erlang has closed
[os_mon] win32 supervisor port (win32sysinfo): Erlang has closed
[os_mon] win32 supervisor port (win32sysinfo): Erlang has closed
[os_mon] win32 supervisor port (win32sysinfo): Erlang has closed
[os_mon] win32 supervisor port (win32sysinfo): Erlang has closed
test create_document_ok_with_document_id ... ok
test read_document_nok_not_found ... ok
test create_database_ok_with_default_options ... ok
test create_document_ok_default_options ... ok
test read_document_ok_default_options ... ok
test create_document_nok_document_conflict ... ok

test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured

New integration tests for unauthorized error response

Implement integration tests for receiving a 401 Unauthorized response from the CouchDB server for all actions that return an Error::Unauthorized error result.

Eliminate heap temporaries when constructing a request URL

Eliminate heap temporaries when constructing a request URL in the HyperTransport::make_request_url method. Here's a snapshot of the source.

It will be best to wait to resolve this issue until after the upstream Url refactor lands because that will change the Url interface to require fewer heap allocations.

Eliminate the heap temporary when constructing a DocumentId from a String

Eliminate the heap temporary when constructing a DocumentId from a String—at least for normal documents but maybe for design and local documents, too. Here's a snapshot of the source.

New action to execute a view

Design and implement a new action type for executing a view. Use default values for all options.

New action to delete a document

Design and implement a new action type for deleting a document. Use default values for all options.

New support for the `atts_since` query parameter when reading a document

Add support for the atts_since query parameter when reading a document via GET /db/docid.

Multipart support for attachments

Add support for uploading and downloading attachments using multipart.

New action to create an attachment standalone

Add an action to create an attachment—i.e., an action that sends an HTTP request to PUT /db/docid/attachment.

ViewResponse should implement Send

ViewRow contains an Rc<DatabaseName> as an optimization. However, this has the effect of making the ViewRow implement !Send. See #19 for more commentary.

I.e., the follow snippet causes a compile-time error:

fn f<T: Send>(_: T) {}
f(ViewResponse::Reduced(ReducedView {
    update_seq: None,
    value: 42,
}));

New support for reading a document with If-None-Match

Add support for reading a document with the If-None-Match header. This may require designing a new action type because the action's output will be an Option<Document>, unlike the ReadDocument action, which has an output type of Document.

New action to read a document

Design and implement an action type for reading a document. Use default values for all options. Consider the implications of the If-None-Match HTTP header for returning an Option or not.

New support for including the document in each view row

Add support for the include_docs query parameter when executing a view. Doing so will require changing the ViewRow type to optionally contain a Document.

It might be a good idea—either now or later—to make a new reference-counted document path type, similar to DocumentPath, whereby the database name component is stored as a std::rc::Rc<DatabaseName>. Otherwise, each view row containing a document will have a copy of the same database name, which could lead to a lot of allocations. I envision the reference-counted document path type to be an private type inside Chill.

The reference-counting idea is probably a bad idea. The std::rc::Rc type implements !Send, meaning Rc prevents anything containing it from moving to another thread. Having a Document (or ViewRow) contain an Rc would be prioritizing for efficiency over convenience—contrary to the central aim for Chill. For this specific case, it would be better merely to incur the cost of one extra allocation per document for the database name, as that cost will be lost in the noise of doing an HTTP round-trip with the CouchDB server.

New support for the `group_level` query parameter when executing a view

Add support for the group_level query parameter when executing a view.

New unit tests for getting and setting Document content

There are no unit tests for getting and setting Document content via the Document::get_content and Document::set_content methods.

New actions to receive changes

http://docs.couchdb.org/en/stable/api/database/changes.html

There are multiple ways to receive changes:

• Polling (without feed query): Send a request, get a response. Easy.
• Long Polling (feed=longpoll): Send a request, get a response when a change happens. Primarily for browsers, IMO this isn't needed, or at least not very high priority.
• Continuous (feed=continuous): Send a request, keep the connection open and continuously get changes. I want this.

Eliminate cloning when serializing a Document

Serializing a Document causes all content to be cloned, which may be an expensive operation. Here's a snapshot of the source.

Change serialization so that no cloning is needed.

New types for representing design document content

Define a set of types that applications may use to represent design documents or parts of design documents. E.g.,

pub struct Design {
    pub views: HashMap<String, ViewFunction>,
    // ...
}

Upgrade to rustfmt v0.4.x

Chill currently is formatted with rustfmt v0.3.0.

New support for the `startkey` query when executing a view

Add support for the startkey query parameter when executing a view.

New action to create a document

Design and implement an action type for creating a document. Use default values for all options.

New action to update a document

Design and implement a new action type for updating a document. Use default values for all options.

Consider making the action-constructing methods infallible

Currently, all Client methods that construct an action do so fallibly, returning a Result. For ergonomics, consider pushing fallibility to the time that the action executes so that the Client method always succeeds and returns the action type.