Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: pass (athena.apache.org: domain of jchris@gmail.com designates
 209.85.212.200 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:sender:in-reply-to:references:date
         :x-google-sender-auth:message-id:subject:from:to:content-type
         :content-transfer-encoding;
        b=sc6k0VNaAcMBWQej0OsbiyRX+mbOBibCOfbxAzW3HkNdDn8EBTKKJuTqXsxs4F4G1J
         wIBFSD9xXi7xYEIKnsDXsh4JLYyJ6q/W1y2dliF077TaZqFGBFPzUo1i8yYsK4ACcXYa
         ZfcP1YgYNXaE8Fc1H9lo2rC8X/OeFVDAhVQQI=
MIME-Version: 1.0
Sender: jchris@gmail.com
In-Reply-To: <214c385b0907060550y5e43887em8ca16cdd31d06c7a@mail.gmail.com>
References: <214c385b0907060550y5e43887em8ca16cdd31d06c7a@mail.gmail.com>
Date: Mon, 6 Jul 2009 12:58:01 -0700
Message-ID: <e282921e0907061258n6417c8f8ra1cb4f808ea4bac0@mail.gmail.com>
Subject: Re: _changes resource
From: Chris Anderson <jchris@apache.org>
To: dev@couchdb.apache.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

On Mon, Jul 6, 2009 at 5:50 AM, Matt Goodall<matt.goodall@gmail.com> wrote:
> 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 ;-))
>

Please do! Thanks for digging in here.


>
> == 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').

Not sure here, maybe conflicts.


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

don't see why not

>
> Is last_seq at all useful?

yes, when filters are added to changes there will be the potential the
db seq when the  connection is closed is significantly later than the
last change sent.

>
>
> == 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.

There's a certain elegance to the current system. So far I've been
testing in the browser and it works fine. If there's demonstrated
problems for a client then we shouldn't hesitate to change it.

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

The plan is to drive replication from changes, so anything needed by
replication is on the roadmap. I don't think it'd hurt to have any of
those but Damien would be better to answer this one.

>
>
> Hope that all makes sense.
>
>
> - Matt
>

Thanks again for digging into the API here. The full API isn't there
yet but we're getting close.

Chris

-- 
Chris Anderson
http://jchrisa.net
http://couch.io