|
| 1 | +# frozen_string_literal: true |
| 2 | + |
| 3 | +module Net |
| 4 | + class IMAP < Protocol |
| 5 | + |
| 6 | + # This module handles deprecated arguments to various Net::IMAP methods. |
| 7 | + module DeprecatedClientOptions |
| 8 | + |
| 9 | + # :call-seq: |
| 10 | + # Net::IMAP.new(host, **options) # standard keyword options |
| 11 | + # Net::IMAP.new(host, options) # obsolete hash options |
| 12 | + # Net::IMAP.new(host, port) # obsolete port argument |
| 13 | + # Net::IMAP.new(host, port, usessl, certs = nil, verify = true) # deprecated SSL arguments |
| 14 | + # |
| 15 | + # Translates Net::IMAP.new arguments for backward compatibility. |
| 16 | + # |
| 17 | + # ==== Obsolete arguments |
| 18 | + # |
| 19 | + # Using obsolete arguments does not a warning. Obsolete arguments will be |
| 20 | + # deprecated by a future release. |
| 21 | + # |
| 22 | + # If a second positional argument is given and it is a hash (or is |
| 23 | + # convertable via +#to_hash+), it is converted to keyword arguments. |
| 24 | + # |
| 25 | + # # Obsolete: |
| 26 | + # Net::IMAP.new("imap.example.com", options_hash) |
| 27 | + # # Use instead: |
| 28 | + # Net::IMAP.new("imap.example.com", **options_hash) |
| 29 | + # |
| 30 | + # If a second positional argument is given and it is not a hash, it is |
| 31 | + # converted to the +port+ keyword argument. |
| 32 | + # # Obsolete: |
| 33 | + # Net::IMAP.new("imap.example.com", 114433) |
| 34 | + # # Use instead: |
| 35 | + # Net::IMAP.new("imap.example.com", port: 114433) |
| 36 | + # |
| 37 | + # ==== Deprecated arguments |
| 38 | + # |
| 39 | + # Using deprecated arguments prints a warning. Convert to keyword |
| 40 | + # arguments to avoid the warning. Deprecated arguments will be removed in |
| 41 | + # a future release. |
| 42 | + # |
| 43 | + # If +usessl+ is false, +certs+, and +verify+ are ignored. When it true, |
| 44 | + # all three arguments are converted to the +ssl+ keyword argument. |
| 45 | + # Without +certs+ or +verify+, it is converted to <tt>ssl: true</tt>. |
| 46 | + # # DEPRECATED: |
| 47 | + # Net::IMAP.new("imap.example.com", nil, true) # => prints a warning |
| 48 | + # # Use instead: |
| 49 | + # Net::IMAP.new("imap.example.com", ssl: true) |
| 50 | + # |
| 51 | + # When +certs+ is a path to a directory, it is converted to <tt>ca_path: |
| 52 | + # certs</tt>. |
| 53 | + # # DEPRECATED: |
| 54 | + # Net::IMAP.new("imap.example.com", nil, true, "/path/to/certs") # => prints a warning |
| 55 | + # # Use instead: |
| 56 | + # Net::IMAP.new("imap.example.com", ssl: {ca_path: "/path/to/certs"}) |
| 57 | + # |
| 58 | + # When +certs+ is a path to a file, it is converted to <tt>ca_file: |
| 59 | + # certs</tt>. |
| 60 | + # # DEPRECATED: |
| 61 | + # Net::IMAP.new("imap.example.com", nil, true, "/path/to/cert.pem") # => prints a warning |
| 62 | + # # Use instead: |
| 63 | + # Net::IMAP.new("imap.example.com", ssl: {ca_file: "/path/to/cert.pem"}) |
| 64 | + # |
| 65 | + # When +verify+ is +false+, it is converted to <tt>verify_mode: |
| 66 | + # OpenSSL::SSL::VERIFY_NONE</tt>. |
| 67 | + # # DEPRECATED: |
| 68 | + # Net::IMAP.new("imap.example.com", nil, true, nil, false) # => prints a warning |
| 69 | + # # Use instead: |
| 70 | + # Net::IMAP.new("imap.example.com", ssl: {verify_mode: OpenSSL::SSL::VERIFY_NONE}) |
| 71 | + # |
| 72 | + def initialize(host, port_or_options = nil, *deprecated, **options) |
| 73 | + if port_or_options.nil? && deprecated.empty? |
| 74 | + super host, **options |
| 75 | + elsif options.any? |
| 76 | + # Net::IMAP.new(host, *__invalid__, **options) |
| 77 | + raise ArgumentError, "Do not combine deprecated and keyword arguments" |
| 78 | + elsif port_or_options.respond_to?(:to_hash) and deprecated.any? |
| 79 | + # Net::IMAP.new(host, options, *__invalid__) |
| 80 | + raise ArgumentError, "Do not use deprecated SSL params with options hash" |
| 81 | + elsif port_or_options.respond_to?(:to_hash) |
| 82 | + super host, **Hash.try_convert(port_or_options) |
| 83 | + elsif deprecated.empty? |
| 84 | + super host, port: port_or_options |
| 85 | + elsif deprecated.shift |
| 86 | + warn "DEPRECATED: Call Net::IMAP.new with keyword options", uplevel: 1 |
| 87 | + super host, port: port_or_options, ssl: create_ssl_params(*deprecated) |
| 88 | + else |
| 89 | + warn "DEPRECATED: Call Net::IMAP.new with keyword options", uplevel: 1 |
| 90 | + super host, port: port_or_options, ssl: false |
| 91 | + end |
| 92 | + end |
| 93 | + |
| 94 | + # :call-seq: |
| 95 | + # starttls(**options) # standard |
| 96 | + # starttls(options = {}) # obsolete |
| 97 | + # starttls(certs = nil, verify = true) # deprecated |
| 98 | + # |
| 99 | + # Translates Net::IMAP#starttls arguments for backward compatibility. |
| 100 | + # |
| 101 | + # Support for +certs+ and +verify+ will be dropped in a future release. |
| 102 | + # |
| 103 | + # See ::new for interpretation of +certs+ and +verify+. |
| 104 | + def starttls(*deprecated, **options) |
| 105 | + if deprecated.empty? |
| 106 | + super(**options) |
| 107 | + elsif options.any? |
| 108 | + # starttls(*__invalid__, **options) |
| 109 | + raise ArgumentError, "Do not combine deprecated and keyword options" |
| 110 | + elsif deprecated.first.respond_to?(:to_hash) && deprecated.length > 1 |
| 111 | + # starttls(*__invalid__, **options) |
| 112 | + raise ArgumentError, "Do not use deprecated verify param with options hash" |
| 113 | + elsif deprecated.first.respond_to?(:to_hash) |
| 114 | + super(**Hash.try_convert(deprecated.first)) |
| 115 | + else |
| 116 | + warn "DEPRECATED: Call Net::IMAP#starttls with keyword options", uplevel: 1 |
| 117 | + super(**create_ssl_params(*deprecated)) |
| 118 | + end |
| 119 | + end |
| 120 | + |
| 121 | + private |
| 122 | + |
| 123 | + def create_ssl_params(certs = nil, verify = true) |
| 124 | + params = {} |
| 125 | + if certs |
| 126 | + if File.file?(certs) |
| 127 | + params[:ca_file] = certs |
| 128 | + elsif File.directory?(certs) |
| 129 | + params[:ca_path] = certs |
| 130 | + end |
| 131 | + end |
| 132 | + params[:verify_mode] = |
| 133 | + verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE |
| 134 | + params |
| 135 | + end |
| 136 | + |
| 137 | + end |
| 138 | + end |
| 139 | +end |
0 commit comments