class Net::IMAP::SASL::ClientAdapter
This API is experimental, and may change.
TODO: use with more clients, to verify the API can accommodate them.
Represents the client to a SASL::AuthenticationExchange. By default, most methods simply delegate to client. Clients should subclass SASL::ClientAdapter and override methods as needed to match the semantics of this API to their API.
Subclasses should also include a protocol adapter mixin when the default ProtocolAdapters::Generic isn’t sufficient.
Protocol Requirements¶ ↑
RFC4422 §4 lists requirements for protocol specifications to offer SASL. Where possible, ClientAdapter delegates the handling of these requirements to SASL::ProtocolAdapters.
Attributes
The client that handles communication with the protocol server.
Most ClientAdapter methods are simply delegated to client by default.
command_proc can used to avoid exposing private methods on client. It’s value is set by the block that is passed to ::new, and it is used by the default implementation of run_command. Subclasses that override run_command may use command_proc for any other purpose they find useful.
In the default implementation of run_command, command_proc is called with the protocols authenticate command name, the mechanism name, an optional initial_response argument, and a continuations block. command_proc must run the protocol command with the arguments sent to it, yield the payload of each continuation, respond to the continuation with the result of each yield, and return the command’s successful result. Non-successful results MUST raise an exception.
Public Class Methods
Source
# File lib/net/imap/sasl/client_adapter.rb, line 56 def initialize(client, &command_proc) @client, @command_proc = client, command_proc end
By default, this simply sets the client and command_proc attributes. Subclasses may override it, for example: to set the appropriate command_proc automatically.
Public Instance Methods
Source
# File lib/net/imap/sasl/client_adapter.rb, line 76 def_delegator :client, :auth_capable?
Does the server advertise support for the mechanism?
Source
# File lib/net/imap/sasl/client_adapter.rb, line 64 def authenticate(...) AuthenticationExchange.authenticate(self, ...) end
Attempt to authenticate client to the server.
By default, this simply delegates to AuthenticationExchange.authenticate.
Source
# File lib/net/imap/sasl/client_adapter.rb, line 113 def_delegator :client, :drop_connection
Drop the connection gracefully, sending a “LOGOUT” command as needed.
Source
# File lib/net/imap/sasl/client_adapter.rb, line 118 def_delegator :client, :drop_connection!
Drop the connection abruptly, closing the socket without logging out.
Source
# File lib/net/imap/sasl/client_adapter.rb, line 99 def_delegator :client, :host
The hostname to which the client connected.
Source
# File lib/net/imap/sasl/client_adapter.rb, line 104 def_delegator :client, :port
The destination port to which the client connected.
Source
# File lib/net/imap/sasl/client_adapter.rb, line 108 def response_errors; [] end
Returns an array of server responses errors raised by run_command. Exceptions in this array won’t drop the connection.
Source
# File lib/net/imap/sasl/client_adapter.rb, line 90 def run_command(mechanism, initial_response = nil, &continuations_handler) command_proc or raise Error, "initialize with block or override" args = [command_name, mechanism, initial_response].compact command_proc.call(*args, &continuations_handler) end
Calls command_proc with command_name (see SASL::ProtocolAdapters::Generic#command_name), mechanism, initial_response, and a continuations_handler block. The initial_response is optional; when it’s nil, it won’t be sent to command_proc.
Yields each continuation payload, responds to the server with the result of each yield, and returns the result. Non-successful results MUST raise an exception. Exceptions in the block MUST cause the command to fail.
Subclasses that override this may use command_proc differently.
Source
# File lib/net/imap/sasl/client_adapter.rb, line 69 def_delegator :client, :sasl_ir_capable?
Do the protocol, server, and client all support an initial response?