IStreamClientEndpoint / ClientFactory adapter

[glyph]

Quoting from ​ticket 1442, comment 43,

There's too much code in Twisted right now that requires either clientConnectionFailed or clientConnectionLost, and we need to make adopting endpoints as easy as humanly possible, so that protocol code can stop binding so tightly to the reactor. You shouldn't have to depend on getting rid of ClientFactory to get the new awesomeness of endpoints.

... and also ...

passing a ClientFactory to IStreamClientEndpoint.connect is formally correct; it implements the required interface. However, it is somewhat misleading and the code should probably emit a warning pointing at this legacy convenience class.

[glyph]

(In [29147]) Merge endpoints-1442-5: a high level connection and listening API

Author: rwall, dreid, glyph

Reviewer: radix, exarkun, glyph, jknight

Fixes: #1442

Refs: #4470 Refs: #4471 Refs: #4472 Refs: #4473 Refs: #3204

Added new "endpoint" interfaces in twisted.internet.interfaces, which abstractly describe stream transport endpoints which can be listened on or connected to. Implementations for TCP and SSL clients and servers are present in twisted.internet.endpoints. Notably, client endpoints' connect() methods return cancellable Deferreds, so code written to use them can bypass the awkward "ClientFactory.clientConnectionFailed" and "Connector.stopConnecting" methods, and handle errbacks from or cancel the returned deferred, respectively.

[davep]

So this is about making things like ReconnectingClientFactory work, is that right? Is there no way to use that factory with endpoints at the moment?

[glyph]

Replying to davep:

So this is about making things like ReconnectingClientFactory work, is that right? Is there no way to use that factory with endpoints at the moment?

Indeed not. There are duplicate notifications in the client factory API, which the new, shiny endpoints API does not perpetuate. I filed another ticket for making something a bit more 'native' to the endpoints API rather than simply retrofitting these ugly extra notification hooks so that ReconnectingClientFactory continues to work verbatim. (Although I am not going to stop somebody who likes this approach from implementing it; we are likely to be maintaining and supporting this code for quite a while before endpoints can really take over completely; we have a lot of docs to rewrite, a lot of user education to do, and, as this ticket indicates, a few convenience gaps to fill in.)