class Net::IMAP::SASL::ClientAdapter - net-imap: Ruby Standard Library Documentation

# 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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/lib/net/imap/sasl/client_adapter.rb, line 69
    def_delegator :client, :sasl_ir_capable?