preserve and send cookies only for multistatement transactions

[ehennum]

Many load balancers set session cookies.

The API should throw away all session cookies returned in a response (so subsequent requests can be balanced) except when opening a multi-statement transaction. In this case, the API should cache the cookie in a transaction object and send it in subsequent requests for the same transaction so the load balancer can ensure host affinity (which is necessary for multi-statement transactions).

Maintaining a transaction object requires an interface change:

• The db.transactions.open() function will take an optional parameters object that can specify {loadBalancer:true}
• When load balancer is true, the open() function will return an opaque transaction object instead of a string transaction id
• Functions that accept a string transaction id parameter today will also accept a transaction object in the same position

On the next major semver boundary, loadBalancer will become the default. On the following major semver boundary, the string transaction id will be removed completely in favour of the transaction object.

[ehennum]

db.transactions.open() can take a new withState boolean parameter.

If withState is true, db.transactions.open() returns a Transaction object instead of a string transaction id.

The Transaction object can be passed instead of the string transaction id on any call that accepts a transaction id.

Internally, the Transaction object keeps all cookies sent in the response to the transaction open request. The Node.js API sends the same cookies back to the server on any request that specifies the transaction by means of the Transaction object.

In particular, if a load balancer sets cookies in the HTTP response to REST API requests, the Node.js API captures those cookies only for the transaction open response and resends the cookies only for other requests using the transaction.

[ayuwono]

Added test on nodejs-documents-transaction-withstate.js