Mailing-List: contact user-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: user@couchdb.apache.org
Received-SPF: pass (athena.apache.org: domain of matt.goodall@gmail.com
 designates 74.125.78.27 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:date:message-id:subject:from:to:content-type;
        b=mkYgiYhAEXqAUWTMP0hwa1zE7vh/7fvAeweSoPKIKmGpxECFiT999Y44dKsxrL9FP8
         4XRbN85Nv68OZSruvxuDtu/qz2zgH+GrBHjykCszwd1vHoS11DiA3gEnFR5EssXD2oco
         EhnffnRrQC4stSMybNiGTl2Wt7HfqE4gEg1pM=
MIME-Version: 1.0
Date: Mon, 6 Jul 2009 13:50:45 +0100
Message-ID: <214c385b0907060550y5e43887em8ca16cdd31d06c7a@mail.gmail.com>
Subject: _changes resource
From: Matt Goodall <matt.goodall@gmail.com>
To: user@couchdb.apache.org, dev@couchdb.apache.org
Content-Type: multipart/mixed; boundary=0015174c398a66562e046e08f41e

--0015174c398a66562e046e08f41e
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

Hi,

Not sure if this is a user or dev message so posting to both.

I've started playing with the _changes resource to improve the
response time of some update processes that currently use
_all_docs_by_seq. cron is not exactly high resolution and a fast poll
is just not a nice thing to do.


== API ==

AFAICT, the _changes API supports four query params:

* since: non-inclusive seq num to start emitting changes from.
* continuous: boolean to enable "streaming" mode.
* heartbeat: period of inactivity (ms) after which a heartbeat newline
will be sent. continuous=true only.
* timeout: period of inactivity (ms) after which the end of the
document is sent and the connection closed. continuous=true only.

Did I find everything and are my descriptions correct? (I can feel a
wiki page coming on ;-))


== Response Document ==

The response looks something like this:

$ curl "http://localhost:5984/test/_changes"
{"results":[
{"seq":2,"id":"75a5d0495630527b4641199681e1abc3","changes":[{"rev":"2-1358922619"}]},
{"seq":5,"id":"3fb654a7094e7cfb4774030ed5c0aefb","changes":[{"rev":"2-4123934944"}]},
{"seq":16,"id":"399f99e0a89856d4627833d1cd11bf10","changes":[{"rev":"11-1674861745"}]}
],
"last_seq":16}

Under what circumstances would 'changes' contain more than one item?
(Note: I couldn't see anything testing multiple 'changes').

Would it make sense to rename 'results' to 'rows' for just a little
consistency with a view's response?

Is last_seq at all useful?


== Line Breaks ==

If each results item is sent with its ending newline (the "," is sent
with the next item) it would make clients much easier and correct to
write, i.e. buffer bytes until a newline is received, split the
buffer, process the row, repeat. You've still got to remove the ","
from all but the first line but it's in a predictable place. Actually,
I don't believe TCP provides any guarantees that bytes sent are
received in the same chunks so relying on anything other than the
newline is probably flawed.

It's a trivial change, patch attached.


== Deleted and Conflicts==

_all_docs_by_seq includes a 'deleted' flag and a list of 'conflicts'.
Should the _changes API to do the same?


Hope that all makes sense.


- Matt

--0015174c398a66562e046e08f41e
Content-Type: text/x-patch; charset=US-ASCII; name="changes-linebreak.diff"
Content-Disposition: attachment; filename="changes-linebreak.diff"
Content-Transfer-Encoding: base64
X-Attachment-Id: f_fwt6nypy0

ZGlmZiAtLWdpdCBhL3NyYy9jb3VjaGRiL2NvdWNoX2h0dHBkX2RiLmVybCBiL3NyYy9jb3VjaGRi
L2NvdWNoX2h0dHBkX2RiLmVybAppbmRleCBjMDBmZDg3Li4xODk3YWZlIDEwMDY0NAotLS0gYS9z
cmMvY291Y2hkYi9jb3VjaF9odHRwZF9kYi5lcmwKKysrIGIvc3JjL2NvdWNoZGIvY291Y2hfaHR0
cGRfZGIuZXJsCkBAIC0xNDEsOCArMTQxLDggQEAgc2VuZF9jaGFuZ2VzKFJlcSwgUmVzcCwgRGIs
IFN0YXJ0U2VxLCBQcmVwZW5kMCkgLT4KICAgICAgICAgICAgIF8gLT4KICAgICAgICAgICAgICAg
ICBzZW5kX2NodW5rKFJlc3AsCiAgICAgICAgICAgICAgICAgICAgIFtQcmVwZW5kLCA/SlNPTl9F
TkNPREUoe1t7c2VxLFNlcX0sIHtpZCwgSWR9LAotICAgICAgICAgICAgICAgICAgICAgICAgICAg
ICAgICAgICAgICAgICAgICAgIHtjaGFuZ2VzLFJlc3VsdHN9XX0pXSksCi0gICAgICAgICAgICAg
ICAge29rLCB7U2VxLCA8PCIsXG4iPj59fQorICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg
ICAgICAgICAgICAgICAgIHtjaGFuZ2VzLFJlc3VsdHN9XX0pLCA8PCJcbiI+Pl0pLAorICAgICAg
ICAgICAgICAgIHtvaywge1NlcSwgPDwiLCI+Pn19CiAgICAgICAgICAgICBlbmQKICAgICAgICAg
ZW5kLCB7U3RhcnRTZXEsIFByZXBlbmQwfSkuCiAK
--0015174c398a66562e046e08f41e--