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

client[R]

The client that handles communication with the protocol server.

Most ClientAdapter methods are simply delegated to client by default.

command_proc[R]

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

new(client, &command_proc) click to toggle source

By default, this simply sets the client and command_proc attributes. Subclasses may override it, for example: to set the appropriate command_proc automatically.

# File lib/net/imap/sasl/client_adapter.rb, line 56
def initialize(client, &command_proc)
  @client, @command_proc = client, command_proc
end

Public Instance Methods

auth_capable?(mechanism) click to toggle source

Does the server advertise support for the mechanism?

# File lib/net/imap/sasl/client_adapter.rb, line 76
def_delegator :client, :auth_capable?

authenticate(...) click to toggle source

Attempt to authenticate client to the server.

By default, this simply delegates to AuthenticationExchange.authenticate.

# File lib/net/imap/sasl/client_adapter.rb, line 64
def authenticate(...) AuthenticationExchange.authenticate(self, ...) end

drop_connection click to toggle source

Drop the connection gracefully, sending a “LOGOUT” command as needed.

# File lib/net/imap/sasl/client_adapter.rb, line 113
def_delegator :client, :drop_connection

drop_connection! click to toggle source

Drop the connection abruptly, closing the socket without logging out.

# File lib/net/imap/sasl/client_adapter.rb, line 118
def_delegator :client, :drop_connection!

host click to toggle source

The hostname to which the client connected.

# File lib/net/imap/sasl/client_adapter.rb, line 99
def_delegator :client, :host

port click to toggle source

The destination port to which the client connected.

# File lib/net/imap/sasl/client_adapter.rb, line 104
def_delegator :client, :port

response_errors click to toggle source

Returns an array of server responses errors raised by run_command. Exceptions in this array won’t drop the connection.

# File lib/net/imap/sasl/client_adapter.rb, line 108
def response_errors; [] end

run_command(mechanism, initial_response = nil, &continuations_handler) click to toggle source

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.

# 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

sasl_ir_capable? click to toggle source

Do the protocol, server, and client all support an initial response?

# File lib/net/imap/sasl/client_adapter.rb, line 69
def_delegator :client, :sasl_ir_capable?