pubsub refactor

[stephenplusplus]

resolves#98

A good portion of this change is to the docs/ directory to support the addition of a module. In this case, PubSub will only be documented on the site once a release contains this pull. To support that, we have to generate the sidebar links dynamically based on the version of the docs the user is browsing.

Most of the changes to do that will likely come with https://github.com/ryanseys/gcloud-node/pull/1, which had the same demands (we are adding a new Transaction sub-module in that case).

So, feel free to zoom by those changes for now. Since this PR drastically changed just about everything, a diff won't be all that friendly of a way to view the changes. Feel free to use https://github.com/stephenplusplus/gcloud-node/tree/spp--pubsub-refactor/lib/pubsub to get a better sense of how everything works, as well as the test directory: https://github.com/stephenplusplus/gcloud-node/tree/spp--pubsub-refactor/test/pubsub

[stephenplusplus]

b31f443 follows up from recent discussions in #98, with a change:

• Change: pull is still public to allow a user to customize the type of pull. They have the option to use returnImmediately currently, and perhaps other options / override of options. Without this method, the user would have no control with a .once listener.
• .on('message') is how messages begin pulling
• .removeListener('message', listener) is how messages stop pulling
  • if one listener is added with .on then removed with .removeListener, pulling stops
  • if two or more listeners are added with .on then only one is removed with .removeListener, pulling doesn't stop, but the removed handler no longer fires
• .removeAllListeners('message') is a quick way to stop message pulling

[ryanseys]

The returnImmediately flag in pull call, could it go in the options specified at pubsub creation time too as a default or is this a bad idea?

Also, is the only way to stop listening to pass in the "listener" (callback)? My puny brain doesn't quite understand Events fully yet. To support multiple listeners this makes the most sense, just curious if there was a better way?

[stephenplusplus]

The returnImmediately flag in pull call, could it go in the options specified at pubsub creation time too as a default or is this a bad idea?

I think it's too specific of a parameter to applied generally. returnImmediately false is wanted for auto pulling and returnImmediately true may or may not be wanted for individual pulls.

Also, is the only way to stop listening to pass in the "listener" (callback)?

An event can, and often will, have multiple handlers assigned. When one is no longer needed, it must be removed individually by passing the name of the event and the listener assigned. As long as there is still one active listener to the message event, pulling will continue. Once no more exist, pulling stops. A user can run .removeAllListeners('message') to achieve the same effect.

The nice thing about this is we are following the standard events spec, and not requiring any extra method calls.

[stephenplusplus]

Never mind, this is a static method, correct?

Yes.

Shouldn't listeners number be stored on the Subscription object and initialized to 0 in the constructor?

Either way. It's only of use to the one function, so I scoped it to it.

[ryanseys]

Shouldn't listeners number be stored on the Subscription object and initialized to 0 in the constructor?

Either way. It's only of use to the one function, so I scoped it to it.

We can get the listeners and .length() it from EventEmitter.listeners()

[stephenplusplus]

We can get the listeners and .length() it from EventEmitter.listeners()

The listeners could be of varying types, error & messages. Instead of looping and filtering to get a length, I found it was easier to just increment and decrement.

[ryanseys]

So if we only specify subscription.on('error', listener) it actually won't pull?

[stephenplusplus]

So if we only specify subscription.on('error', listener) it actually won't pull?

Yes, this design can be changed, but I think it would only make sense to listen for messages. We could also run into a problem where a message is pulled & emitted after an error handler was assigned but before a message handler was assigned.

[ryanseys]

Makes sense.

[stephenplusplus]

Updated to address:

• request -> makeReq_
• Document .on('error') and .removeListener
• Add tests for listenForEvents_

[ryanseys]

Overall looks good.

[ryanseys]

Are we awaiting additional reviews before shipping? Can I help?

[stephenplusplus]

@silvolu updated http://stephenplusplus.github.io/gcloud-node/#/docs/master