🔍 Simplify Net::IMAP#inspect with basic state

Most importantly, this no longer prints out *every* instance variable,
some of which could contain sensitive data, and others are just _very_
verbose.

Now `Net::IMAP#inspect` only prints the host:port, TLS state, and IMAP
connection state.  It will be extended to include more in the future.

Author: nevans

lib/net/imap.rb

@@ -1120,6 +1120,31 @@ def initialize(host, port: nil, ssl: nil, response_handlers: nil,
       start_imap_connection
     end
 
+    # Returns a string representation of +self+, showing basic client state
+    # information.
+    #
+    #   imap = Net::IMAP.new(hostname, ssl: true)
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS not_authenticated>"
+    #
+    #   imap.authenticate(:oauthbearer, "user", token)
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS authenticated>"
+    #
+    #   imap.select("INBOX")
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS selected>"
+    #
+    #   imap.logout
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS logout>"
+    #
+    def inspect
+      tls_state = tls_verified? ? "TLS" :
+        ssl_ctx ? "TLS (NOT VERIFIED)" :
+        "PLAINTEXT"
+      conn_state = disconnected? ? "disconnected" : connection_state.to_sym
+      "#<%s:0x%08x %s:%s %s %s>" % [
+        self.class.name, __id__, host, port, tls_state, conn_state
+      ]
+    end
+
     # Returns true after the TLS negotiation has completed and the remote
     # hostname has been verified.  Returns false when TLS has been established
     # but peer verification was disabled.

test/net/imap/test_imap_inspect.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "net/imap"
+require "test/unit"
+require_relative "fake_server"
+
+class IMAPInspectTest < Net::IMAP::TestCase
+  include Net::IMAP::FakeServer::TestHelper
+
+  def format_inspect(client, details)
+    "#<Net::IMAP:0x%s %s:%s %s>" % [
+      "%08x" % client.__id__, # NOTE: this is different from `super`
+      client.host,
+      client.port,
+      details,
+    ]
+  end
+
+  test "#inspect for every connection state (plaintext)" do
+    with_fake_server(preauth: false) do |server, imap|
+      assert_equal(format_inspect(imap, "PLAINTEXT not_authenticated"),
+                   imap.inspect)
+      # AUTHENTICATE, SELECT, CLOSE
+      imap.authenticate :plain, "test_user", "test-password"
+      assert_equal(format_inspect(imap, "PLAINTEXT authenticated"),
+                   imap.inspect)
+      imap.select "INBOX"
+      assert_equal(format_inspect(imap, "PLAINTEXT selected"),
+                   imap.inspect)
+      imap.close
+      assert_equal(format_inspect(imap, "PLAINTEXT authenticated"),
+                   imap.inspect)
+      imap.logout
+      assert_equal(format_inspect(imap, "PLAINTEXT logout"),
+                   imap.inspect)
+      imap.disconnect
+      assert_equal(format_inspect(imap, "PLAINTEXT disconnected"),
+                   imap.inspect)
+    end
+  end
+
+  test "#inspect for TLS verified" do
+    with_fake_server(implicit_tls: true) do |server, imap|
+      assert_equal(format_inspect(imap, "TLS authenticated"),
+                   imap.inspect)
+      imap.logout
+      assert_equal(format_inspect(imap, "TLS logout"),
+                   imap.inspect)
+      imap.disconnect
+      assert_equal(format_inspect(imap, "TLS disconnected"),
+                   imap.inspect)
+    end
+  end
+
+  test "#inspect for TLS unverified" do
+    with_fake_server(preauth: false) do |server, imap|
+      imap.starttls verify_mode: OpenSSL::SSL::VERIFY_NONE
+      assert_equal(format_inspect(imap, "TLS (NOT VERIFIED) not_authenticated"),
+                   imap.inspect)
+      imap.logout
+      assert_equal(format_inspect(imap, "TLS (NOT VERIFIED) logout"),
+                   imap.inspect)
+      imap.disconnect
+      assert_equal(format_inspect(imap, "TLS (NOT VERIFIED) disconnected"),
+                   imap.inspect)
+    end
+  end
+
+end