destroyable EventStreams; closes #302

[boneskull]

• add reference to long-polling timer on class
• add EventStream method _destroy(), which clears any existing
  long-polling timer, and deletes it. Destroys stream if not already
  destroyed. Implements Readable#_destroy in Node.js v8.x and newer.
• add EventStream method abort(), an alias for _destroy(), which
  is not called via EventStream#destroy() in pre-Node.js-v8.x. Any
  version can use this method; _destroy() is private.
• add checks for destroyed stream state which effectively abort
  various tasks in EventStream
• consolidate long-polling retry logic into its own private method,
  EventStream#retryLongPoll().
• add tests for logic changes
• add note in docs

---

It'd be helpful to have an integration test (without use of Sinon's fake timers) which asserts a destroyed stream doesn't still have tasks in the event loop. If it does, such a test should hang--ostensibly due to the infinite recursion--because of Mocha's v4.x+ behavior.

Originally, I discovered this problem when writing some test code which consumes an EventStream. I could determine that this implementation was correct, because my test code was no longer hanging indefinitely. 😄

[boxcla]

Verified that @boneskull has signed the CLA. Thanks for the pull request!

[coveralls]

Pull Request Test Coverage Report for Build 1364

• 18 of 18 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.02%) to 97.346%

---

Totals
Change from base Build 1363:	0.02%
Covered Lines:	2145
Relevant Lines:	2173

---

💛 - Coveralls

[mattwiller]

@boneskull Overall the implementation looks good to me, but it looks like tests aren't passing on Node.js versions before 8.x — you'll need to ensure your code works correctly for versions all the way back to Node.js 4.0.0

[boneskull]

The coverage % decreased because this PR adds more covered LoC to the project. I don't love how Coveralls calculates that...

[boneskull]

@mattwiller The failures have been fixed on Travis-CI

[mattwiller]

The Node.js Stream docs say that _destroy() is called by destroy() — why call back into destroy() here?

[boneskull]

Because destroy was not added until v8 of Node.

[boneskull]

(so if you called abort you might as well have called destroy if it exists. this is moot if I just conditionally add the method)

[mattwiller]

It's a bit undesirable to have two different methods to call depending on which version of Node.js the user is running. Is it possible to check if EventStream.prototype.destroy already exists and conditionally add/polyfill it if it doesn't?

[boneskull]

yeah, we could do that.

[boneskull]

@mattwiller Build needs retry; Node.js v9 didn't seem to start.

[mattwiller]

You'll need to check against Readable.prototype.destroy here — this condition as written will always include the polyfill. Also, using !== might be more readable than !(... === ...)

[boneskull]

my bad

[boneskull]

@mattwiller addressed your latest comments

[boneskull]

@mattwiller Do you need anything else from me here?

[boneskull]

@mattwiller Possible to release this soon?

[mattwiller]

@boneskull We're looking to push out a release later this week!