search

ruby / net-imap

Ruby client api for Internet Message Access Protocol
https://ruby.github.io/net-imap
Other
56 stars 29 forks source link

SSL parameters dropped from 0.3 to 0.4 #269

Closed hadmut closed 6 months ago

hadmut commented 6 months ago

Hi,

I just updated some of my ruby libs by re-running bundler to get the latest libs, and I got an update from net-imap (0.3.6) to net-imap (0.4.10), and then getting warning and complaints that I was calling Net::IMAP.new(...) with a list of parameters instead of keywords.

But when trying to change this into the new form, I noticed that two former parameters have been dropped, i.e. the path to the CA to use, and the flag whether to verify.

Old version 0.3.6: def initialize(host, port_or_options = {}, usessl = false, certs = nil, verify = true)

New version 0.4.10: def initialize(host, port: nil, ssl: nil, open_timeout: 30, idle_response_timeout: 5)

So the former parameters certs and verify do not exist anymore.

I have not found any documentation about how this is to be done now or obvious way to do it.

Have these parameters been dropped?

regards

nevans commented 6 months ago

Sorry for the confusion, @hadmut. The old version hadn't been documented since 2007 (e631911e1). But I know a lot of code from before then (and some written since, too) used that style, so I was hoping to smooth over the deprecation by adding documentation for the deprecated parameters...

However I didn't want to raise the visibility for parameters that have been obsolete for over a decade, so I didn't directly document the deprecated parameters document on .new (and #starttls). Additionally, some of the motivation for the change was to simplify the implementation of #initialize. So all of the code for handling deprecated parameters was moved into a module that is prepended onto Net::IMAP, and you won't see the old parameters in the instance method definitions. But that module is linked to from the Net::IMAP rdoc:

See DeprecatedClientOptions.new for deprecated arguments. -- the rdoc for #new

Examples for exactly how to translate the deprecated parameters to SSLContext params are provided by the DeprecatedClientOptions.new rdoc. Basically, all you need to do is send a hash for the ssl keyword argument. When ssl is a hash, it’s passed to OpenSSL::SSL::SSLContext#set_params; the keys are names of attribute assignment methods on SSLContext. Basically:

Net::IMAP.new("imap.example.com", ssl: {ca_file:, ca_path:, verify_mode:})

I hope this helps. Do you think it would have been helpful to mention the DeprecatedClientOptions rdoc in the deprecation warning?

hadmut commented 6 months ago

Yes, definitely, a hint in the warning would have been good.