123456789_123456789_123456789_123456789_123456789_

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

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Net::IMAP::SASLAdapter
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Forwardable
Instance Chain:
self, ProtocolAdapters::Generic
Inherits: Object
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 AuthenticationExchange. By default, most methods simply delegate to #client. Clients should subclass 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 ::Net::IMAP::SASL. Where possible, ClientAdapter delegates the handling of these requirements to ProtocolAdapters.

Class Method Summary

Instance Attribute Summary

Instance Method Summary

ProtocolAdapters::Generic - Included

#cancel_response

Returns the message used by the client to abort an authentication exchange.
#command_name

The name of the protocol command used to initiate a SASL authentication exchange.
#decode

Decodes a server challenge string.
#encode

Encodes a client response string.
#encode_ir

Encodes an initial response string.
#service

A service name from the GSSAPI/Kerberos/SASL Service Names registry.

Constructor Details

.new(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.

[ GitHub ] 

  


# 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   (readonly)
  



  

    

The client that handles communication with the protocol server.



Most ClientAdapter methods are simply delegated to #client by default.


  



  [ GitHub ]


  

  


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



attr_reader :client


  








  

    #command_proc   (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.


  



  [ GitHub ]


  

  


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



attr_reader :command_proc


  







Instance Method Details



  

    #authenticate  
  



  

    

Attempt to authenticate #client to the server.



By default, this simply delegates to AuthenticationExchange.authenticate.


  



  [ GitHub ]


  

  


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



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


  








  

    #response_errors  
  



  

    

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


  



  [ GitHub ]


  

  


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



def response_errors; [] end


  








  

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



  

    

Calls command_proc with command_name (see 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.


  



  [ GitHub ]


  

  


# 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