Attachment transform, with attachment.stub: true support and tests

[stevebest]

As promised in #92, finally.

[nolanlawson]

technically this should be base64-encoded (e.g. btoa('hello world')). although I don't think it matters for the purpose of the test

[stevebest]

I'd like to clarify a few points I have before moving on with implementation.

It looks like there is no point in passing digests of stub attachments when saving. Here's why.

1. If I want to change the attachment, I pass new data. The digest will be calculated for me.
2. If I want to delete the attachment, I removeObject it from the array of attachments. No attachment, no digest.
3. Thus, when I save a model with one of attachments as { stub: true }, I want to say "I don't care what's in that attachment, *ouchDB, but please keep it intact, and don't delete it".

The only case where having a digest would matter is the one where attachment changes between reading the doc and trying to update it. But then, the doc's _rev also changes and we get a 409 anyways.

[stevebest]

length is required when you want to write a doc and its attachments in a single multipart/related request to a CouchDB. It doesn't support Transfer-Encoding: chunked, and thus Content-Length is required beforehand for every part of request. More info here: apache/nano#300

Same as with digest, there is no point in passing it when writing. Either it's the same as in DB, or you haven't refreshed your doc in a while and a thus have a conflicting _rev.

[nolanlawson]

@stevebest I think you might not have a clear picture of how stubs are used in P/CouchDB. Let me try to explain. (N.B.: I wrote most of PouchDB's attachment code. 😃)

When you insert a document with revision 1-x and a non-stub attachment, the digest is computed and the attachment is saved.

When you update the document with revision 2-y, but you use stub attachments (because e.g. you change something in the document unrelated to the attachment), then P/CouchDB uses the digest to determine that it already knows about the attachment. So it accepts your stub.

However, if you tried to insert a stub with a digest that was not known by P/CouchDB (e.g. because the revision was compacted, or because of an error on your part), then P/CouchDB will throw a 412 error to indicate that it doesn't know what stub you're talking about.

As for length, I'm not sure about CouchDB, but I know that in the case of PouchDB, weird stuff will happen if you omit it. For instance, say you did the 1-x/2-y scenario above, but you omitted the length on the stub. PouchDB will overwrite the existing attachment metadata without the length property, so even when you try to pull out the real attachment (using {attachments: true}), you will get an object with no length. (PouchDB avoids recomputing the length for stubs because it assumes it doesn't have to.)

[backspace]

I like the use of a transformer to define an attachment type for Ember Data. I’m excited to have this merged!

[stevebest]

Huh, never saw a 412 from any of them. TIL.

In any case, stub attachments seem to be a point of incompatibility between PouchDB and CouchDB. Couch happily accepts attachments which are nothing but {"stub": true}, and, from what you describe, Pouch corrupts the metadata? Doesn't seem right to me. :)

[nolanlawson]

@stevebest That might be a bug in CouchDB TBH. I don't know what it even means to push a stub of an attachment without a digest at least. The replicator and normal user operations (e.g. get() followed by put()) should never do this.

[nolanlawson]

Unfortunately there are conflicts; I'm clearing out old issues/PRs, so please reopen if you have time to add those changes. I would be nervous about merging attachment support changes if I know that those changes might cause incompatibility issues with Couch/Pouch, sorry about that.

[simonexmachina]

@stevebest what's the status of this PR? We're looking to implement this and it'd be good to get your solution added to ember-pouch. I've merged your branch with upstream master in jtribe/ember-pouch and fixed the conflicts. Let me know if you want me to submit a PR to this branch or create a new PR.

[simonexmachina]

@nolanlawson can you please clarify if there's a problem that needs to be fixed with the way digests are handled in this PR. If so then some advice would be welcome. Judging from the Attachments guide on the PouchDB docs the digest is provided by CouchDB. Should we simply include the digest when we send document updates?

[nolanlawson]

Couch and Pouch both calculate digests when attachments are inserted, and those digests are usually the same (modulo some slight differences in how Couch handles Erlang strings compared to Pouch using JavaScript strings). IIRC my beef with this PR was just that digest and length should be included in the tests.

[simonexmachina]

Okay, thanks. Excuse my ignorance, but it's not clear what needs to be done to add them to the tests.

[stevebest]

So I took some time to rebase my fork against latest master, added support for preserving digest and length, and started #135.