[Twisted-Python] IOpenSSLClientConnectionCreator was ContextFactory, now it's IOpenSSLClientConnectionCreator not ContextFactory

exarkun at twistedmatrix.com exarkun at twistedmatrix.com
Mon May 19 12:24:14 MDT 2014


Hello,

I just noticed that #7098 expanded the meaning of the objects Twisted 
typically refers to as "context factories".

Prior to #7098, these were things that implemented a `getContext` method 
that returned an `OpenSSL.SSL.Context` instance.

Subsequent to #7098, these are now *either* that or an object that 
provides `IOpenSSLClientConnectionCreator`.

It seems that parts of Twisted itself were updated to reflect this 
change.  For example, the very bottom of the TLS implementation stack in 
Twisted, `twisted.protocols.tls`, acknowledges this change (I imagine 
this was unavoidable).  Also, way on the other side of Twisted, 
`twisted.web.client.Agent` takes advantage of this change to implement 
the great new certificate and hostname validation features introduced in 
14.0.0.

However, other parts of Twisted itself were not updated.  For example, 
the layers that sit in between `twisted.protocols.tls` and 
`twisted.web.client.Agent` weren't touched much.  `SSL4ClientEndpoint`, 
for example, still documents its `sslContextFactory` as "SSL 
Configuration information as an instance of 
L{twisted.internet.ssl.ContextFactory}.".  And, somewhat insanely I 
think, `IReactorSSL.connectSSL` still says "@param contextFactory: a 
L{twisted.internet.ssl.ClientContextFactory} object.".

Merely from a documentation standpoint, this seems suboptimal.  From a 
compatibility standpoint...  Well, it seems incompatible to me.  Perhaps 
this is an instance where the compatibility policy can be broken (though 
really that's academic since 14.0.0 has already been released, the 
policy has been broken already) but I don't recall any explicit 
discussion about a decision to do this.

I *hope* and suspect there won't be much fall-out from this change 
considering it's hard to implement TLS and as far as I know there are no 
third-party implementations of `IReactorSSL` (GNUTLS came to mind but 
they have their own incompatible interface afaict).  In other words, 
maybe we'll get lucky this time.

I wrote this email instead of filing tickets about the documentation 
problems because doing the latter was implicit acknowledgement that this 
incompatible change is okay.  Having written the email now, I see 
there's probably no going back, regardless.  Maybe we can learn 
something from this incident and avoid repeating it with a more popular 
interface, though.

We could probably add a description of this particular kind of 
incompatible change to the `CompatibilityPolicy` wiki page.  If 
reviewers read that page, then they'll know to watch out for it.

And of course (assuming we're committed to this direction, which we seem 
to be) we need to fix the rest of the "contextFactory" documentation 
throughout Twisted.  I'll go file one ticket related to that now...

Jean-Paul



More information about the Twisted-Python mailing list