Class: Net::IMAP::SASL::ClientAdapter

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
ProtocolAdapters::Generic
Defined in:
lib/net/imap/sasl/client_adapter.rb

Overview

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.

Direct Known Subclasses

Net::IMAP::SASLAdapter

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ProtocolAdapters::Generic

#cancel_response, #command_name, #decode, #encode, #encode_ir, #service

Constructor Details

#initialize(client, &command_proc) ⇒ ClientAdapter

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



56
57
58
 
# File 'lib/net/imap/sasl/client_adapter.rb', line 56

def initialize(client, &command_proc)
  @client, @command_proc = client, command_proc
end

Instance Attribute Details

#client ⇒ Object (readonly)

method: drop_connection! Drop the connection abruptly, closing the socket without logging out.



35
36
37
 
# File 'lib/net/imap/sasl/client_adapter.rb', line 35

def client
  @client
end

#command_proc ⇒ Object (readonly)

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.



51
52
53
 
# File 'lib/net/imap/sasl/client_adapter.rb', line 51

def command_proc
  @command_proc
end

Instance Method Details

#authenticate ⇒ Object

Attempt to authenticate #client to the server.

By default, this simply delegates to AuthenticationExchange.authenticate.



64
 
# File 'lib/net/imap/sasl/client_adapter.rb', line 64

def authenticate(...) AuthenticationExchange.authenticate(self, ...) end

#response_errors ⇒ Object

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



108
 
# File 'lib/net/imap/sasl/client_adapter.rb', line 108

def response_errors; [] end

#run_command(mechanism, initial_response = nil, &continuations_handler) ⇒ Object

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.



90
91
92
93
94
 
# 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