net-smtp icon indicating copy to clipboard operation
net-smtp copied to clipboard

Public disconnect methods

Open nevans opened this issue 9 months ago • 0 comments

There are circumstances when an authenticator needs to disconnect the client before @start = true. This PR refactors the private #do_finish method:

  • renames it to #quit!,
  • makes it public,
  • adds an option to ignore or warn on exceptions,
  • extracts its ensure block into a new public #disconnect method.

The motivation for making these public is given in the rdoc.

As documented in the rdoc, #quit!:

Calls #quit and ensures that #disconnect is called. Returns the result from #quit. Returns +nil+ when the client is already disconnected or when a prior error prevents the client from calling #quit. Unlike #finish, this an exception will not be raised when the client has not started.

If #quit raises a StandardError, the connection is dropped and the exception is re-raised. When exception: :warn is specified, a warning is printed and the exception is returned. When exception: false is specified, the warning is not printed. This is useful when the connection must be dropped, for example in a test suite or due to security concerns.

As documented in the rdoc, #disconnect:

Disconnects the socket without checking if the connection has started yet, and without sending a final QUIT message to the server.

Generally, either #finish or #quit! should be used instead.

nevans avatar May 08 '24 19:05 nevans