add onTransactionConnection* events, docs

Author: chrisdickinson

README.md

@@ -81,6 +81,8 @@ Install a database `Session` on the domain `d`.
 
 Sessions accept the following options:
 
+<img align="right" src="https://cloud.githubusercontent.com/assets/37303/12259904/985ef78a-b8cd-11e5-8665-0535caa69334.png" alt="assets/event-flowchart.dot" />
+
 * `maxConcurrency`: An integer specifying the maximum number of connections a
   given session will make at a time. `0` is treated as `Infinity`. Defaults to
   `Infinity`. *Note:* this number is implicitly bound by the size of the `pg`
@@ -99,21 +101,29 @@ Sessions accept the following options:
   an optional `err` parameter that will be called when a connection is released
   back to the session.
 * `onTransactionRequest(baton, operation, args)`: A function accepting a baton,
-  function, and array of arguments representing the request for a transaction
+  function, and array of arguments, representing the request for a transaction
   session. Called coincident with `onConnectionRequest`.
 * `onTransactionStart(baton, operation, args)`: A function accepting a baton,
-  function, and array of arguments representing the fulfillment of a request
+  function, and array of arguments, representing the fulfillment of a request
   for a transaction session. Called before `BEGIN`, coincident with
   `onConnectionStart`.
 * `onTransactionFinish(baton, operation, args, PromiseInspection)`:
   A function accepting a baton, function, array of arguments, and a
   [`PromiseInspection`][bluebird-inspection] representing the state of the
   transaction. Called coincident with `onConnectionFinish`.
+* `onTransactionConnectionRequest(baton)`: A function accepting a baton,
+  representing the request for a connection within a transaction session.
+* `onTransactionConnectionStart(baton)`: A function accepting a baton,
+  representing the fulfillment of a request for a connection within a
+  transaction session.
+* `onTransactionConnectionFinish(baton, err)`: A function accepting a baton
+  and an optional `err` argument, representing the completion of a transaction
+  connection within a transaction session.
 * `onAtomicRequest(baton, operation, args)`: A function accepting a baton,
-  function, and array of arguments representing the request for an atomic
+  function, and array of arguments, representing the request for an atomic
   session.
 * `onAtomicStart(baton, operation, args)`: A function accepting a baton,
-  function, and array of arguments representing the fulfillment of a request
+  function, and array of arguments, representing the fulfillment of a request
   for an atomic session.
 * `onAtomicFinish(baton, operation, args, PromiseInspection)`:
   A function accepting a baton, function, array of arguments, and a

assets/event-flowchart.dot

@@ -0,0 +1,28 @@
+digraph metrics {
+  A [label="(beginning state)"];
+  A                   -> onConnectionRequest;
+  onConnectionRequest -> onConnectionStart;
+  onConnectionStart   -> onConnectionFinish;
+  onConnectionFinish  -> onSessionIdle;
+  onConnectionFinish  -> onConnectionStart;
+  onSessionIdle       -> onConnectionRequest;
+
+  onConnectionRequest             -> onTransactionRequest;
+  onTransactionRequest            -> onConnectionStart;
+  onConnectionStart               -> onTransactionStart;
+  onTransactionStart        -> onTransactionFinish;
+  onTransactionFinish       -> onConnectionFinish;
+
+  onTransactionStart -> onTransactionConnectionRequest;
+  onTransactionConnectionRequest -> onTransactionConnectionStart;
+  onTransactionConnectionRequest -> onAtomicRequest;
+  onAtomicRequest -> onTransactionConnectionStart;
+  onTransactionConnectionStart -> onTransactionConnectionFinish;
+  onTransactionConnectionFinish -> onTransactionConnectionStart;
+  onTransactionConnectionFinish -> onTransactionFinish;
+
+  onTransactionConnectionStart -> onAtomicStart;
+  onAtomicFinish -> onTransactionConnectionFinish;
+  onAtomicStart -> onAtomicFinish;
+}
+

db-session.js

@@ -28,6 +28,9 @@ const api = module.exports = {
       onTransactionRequest: noop,
       onTransactionStart: noop,
       onTransactionFinish: noop,
+      onTransactionConnectionRequest: noop,
+      onTransactionConnectionStart: noop,
+      onTransactionConnectionFinish: noop,
       onAtomicRequest: noop,
       onAtomicStart: noop,
       onAtomicFinish: noop
@@ -90,6 +93,9 @@ class Session {
       onTransactionRequest: opts.onTransactionRequest,
       onTransactionStart: opts.onTransactionStart,
       onTransactionFinish: opts.onTransactionFinish,
+      onTransactionConnectionRequest: opts.onTransactionConnectionRequest,
+      onTransactionConnectionStart: opts.onTransactionConnectionStart,
+      onTransactionConnectionFinish: opts.onTransactionConnectionFinish,
       onAtomicRequest: opts.onAtomicRequest,
       onAtomicStart: opts.onAtomicStart,
       onAtomicFinish: opts.onAtomicFinish
@@ -167,10 +173,13 @@ class TransactionSession {
         reject(new NoSessionAvailable())
       })
     }
+
+    const baton = {}
+    this.metrics.onTransactionConnectionRequest(baton)
     // NB(chrisdickinson): creating a TxConnPair implicitly
     // swaps out "this.operation", creating a linked list of
     // promises.
-    return new TxSessionConnectionPair(this).onready
+    return new TxSessionConnectionPair(this, baton).onready
   }
 
   transaction (operation, args) {

lib/tx-session-connpair.js

@@ -16,9 +16,10 @@ const REJECT_SYM = Symbol()
 // connection — see Session#transaction and TransactionSession#atomic
 // for more details (specifically, look for "release()".)
 module.exports = class TransactionSessionConnPair {
-  constructor (session) {
+  constructor (session, baton) {
+    const metrics = session.metrics
     this.pair = session.connectionPair
-    this.release = err => release(this, err)
+    this.release = err => release(this, metrics, baton, err)
     this.completed = new Promise((resolve, reject) => {
       this[RESOLVE_SYM] = resolve
       this[REJECT_SYM] = reject
@@ -38,7 +39,10 @@ module.exports = class TransactionSessionConnPair {
     //                |                             |
     //  completed → onready → (work happens) → completed → onready
     //
-    this.onready = session.operation.then(() => this)
+    this.onready = session.operation.then(() => {
+      metrics.onTransactionConnectionStart(baton)
+      return this
+    })
     session.operation = this.completed
   }
 
@@ -47,6 +51,7 @@ module.exports = class TransactionSessionConnPair {
   }
 }
 
-function release (conn, err) {
+function release (conn, metrics, baton, err) {
+  metrics.onTransactionConnectionFinish(baton, err)
   return err ? conn[REJECT_SYM](err) : conn[RESOLVE_SYM]()
 }