[nano] replication needs cancellation/options support

[perezd]

http://wiki.apache.org/couchdb/Replication#Cancelling_a_continuous_replication_task

rather than explicitly supporting continuous as the only option, what we really need is a way to pass any options to the request body, cancel, continuous, doc_ids, are examples of legitimate attributes for replication requests. also, filters and query_params for filtered replication, we need support for all of that.

I'm happy to contribute this, not sure what your opinions are on design/backwards compatibility.

[dscape]

Can you give me a sample using the relax method and also how you
feel the api for canceling a compacting should look like?

Also is this something you need on your code or just something you
feel we need? If it's just something you feel we need don't bother,
that's the whole point of being minimalistic. Also how many times are
you going to call that function in your code? Enough to matter if it's
in the relax format or not?

This helps determining if it's general case enough for a minimalistic
driver. My intuition is that it is not, but I'm open to it. We all
have the common goal of making nano awesome :)

What do you think Derek?

Would also like to see what @mikeal @daleharvey and @jhs think too.

[perezd]

Our code is actually calling to replications, quite a bit. My general point is, replications take a whole host of options as part of the "body" of the potential request, continuous replication is one of many of those options, so simplifying the function call to only support one of those many operations just seems necessarily limiting.

here are some examples of common ways I use replication. You'll notice the augmentation I am proposing is around the body that we send with the request.

// replicate only two documents from db-1 to db-2
relax({
  db: "_replicate",
  method: "POST",
  body: {
    "source": "db-1",
    "target": "db-2",
    "doc_ids": ["doc-1","doc-2"]
  }
}, fn)

// setup a filtered, continuous replication
relax({
  db: "_replicate",
  method: "POST"
  body: {
    "source": "db-1",
    "target": "db-2",
    "continuous": true,
    "filter": "some/design/filter",
    "query_params": {"key": "value"}
  }
}, fn)

// cancel an existing filtered, continuous replication
relax({
  db: "_replicate",
  method: "POST"
  body: {
    "source": "db-1",
    "target": "db-2",
    "continuous": true,
    "filter": "some/design/filter",
    "query_params": {"key": "value"},
    "cancel" : true
  }
}, fn)

[perezd]

Also, from a deprecation perspective, I believe we could assume that the continuous argument should be either a boolean or an object.

[dscape]

I see. I think that was a design error by myself actually.

You know what, we should do the opposite. Instead of creating a more specific method we should generalize the one we have.

How about:

function replicate_db(body, callback) {
  return relax({db: "_replicate", body: body, method: "POST"},callback);
}

I'm ok with this change. More generic, less crap. Fine! :)

More stuff that would need to be changed:

• Change Existing Tests
• Add Cancel Replication Test
• Change docs (function signature at least)
• Bump up version number by a minimum release in package.json
• Create and push git tag
• Publish in npm (I need to do this one)

Sounds like a good plan?
I don't know when I'll find the time to do this but feel free to send in a pull request! :)

[perezd]

I could add this, I imagine this needs to be backwards compatible, yes?

[dscape]

Don't worry about that for now. :)

We are pre-1.0 so interface is supposed to change. Even after 1.0 I'll
be open to small changes like this one. After the API is stable and
perfect then we will have 1.0 (and browser support) and from then on
we need to think about backward compatibility.

[dscape]

Just means we need another action item.

• Add to CHANGELOG since the interface changes.

All significant additions or interface changes are supposed to go there.

[perezd]

OK, I'll see if I can get to this, in the middle of some software for the day job!

[peetersn]

Apologies for commenting on something that is closed such a long time ago, but was this actually implemented? What is the recommended way to cancel replications?