Method: AMQP.connect

Defined in:

lib/amqp.rb

.connect(connection_string, options = {}) ⇒ AMQP::Session .connect(connection_options) ⇒ AMQP::Session

Note:

This method assumes that EventMachine even loop is already running. If it is not the case or you are not sure, we recommend you use start instead. It takes exactly the same parameters.

Connects to AMQP broker and yields connection object to the block as soon as connection is considered open.

Handling authentication failures

AMQP 0.9.1 specification dictates that broker closes TCP connection when it detects that authentication has failed. However, broker does exactly the same thing when other connection-level exception occurs so there is no way to guarantee that connection was closed because of authentication failure.

Because of that, AMQP gem follows Java client example and hints at possibility of authentication failure. To handle it, pass a callable object (a proc, a lambda, an instance of a class that responds to #call) with :on_possible_authentication_failure option.

Examples:

Using AMQP.connect with default connection settings

AMQP.connect do |connection|
  AMQP::Channel.new(connection) do |channel|
    # channel is ready: set up your messaging flow by creating exchanges,
    # queues, binding them together and so on.
  end
end

Using AMQP.connect to connect to a public RabbitMQ instance with connection settings given as a hash

AMQP.connect(:host => "dev.rabbitmq.com", :username => "guest", :password => "guest") do |connection|
  AMQP::Channel.new(connection) do |channel|
    # ...
  end
end

Using AMQP.connect to connect to a public RabbitMQ instance with connection settings given as a URI

AMQP.connect "amqp://guest:guest@dev.rabbitmq.com:5672", :on_possible_authentication_failure => Proc.new { puts("Looks like authentication has failed") } do |connection|
  AMQP::Channel.new(connection) do |channel|
    # ...
  end
end

Overloads:

• .connect(connection_string, options = {}) ⇒ AMQP::Session

  Used to pass connection parameters as a connection string

  Parameters:

  • :connection_string (String) —

    AMQP connection URI, à la JDBC connection string. For example: amqp://bus.megacorp.internal:5877/qa

• .connect(connection_options) ⇒ AMQP::Session

  Used to pass connection options as a Hash.

  Parameters:

  • :connection_options (Hash) —

    AMQP connection options (:host, :port, :username, :vhost, :password)

Parameters:

• connection_options_or_string (Hash) (defaults to: ) —

  a customizable set of options

Options Hash (connection_options_or_string):

• :host (String) — default: "localhost" —

  Host to connect to.

• :port (Integer) — default: 5672 —

  Port to connect to.

• :vhost (String) — default: "/" —

  Virtual host to connect to.

• :username (String) — default: "guest" —

  Username to use. Also can be specified as :user.

• :password (String) — default: "guest" —

  Password to use. Also can be specified as :pass.

• :ssl (Hash) —

  TLS (SSL) parameters to use.

• :heartbeat (Fixnum) — default: 0 —

  Connection heartbeat, in seconds. 0 means no heartbeat. Can also be configured server-side starting with RabbitMQ 3.0.

• :on_tcp_connection_failure (#call) —

  A callable object that will be run if connection to server fails

• :on_possible_authentication_failure (#call) —

  A callable object that will be run if authentication fails (see Authentication failure section)

Returns:

• (AMQP::Session)

# File 'lib/amqp.rb', line 232

def self.connect(connection_options_or_string = ENV['RABBITMQ_URL'], other_options = {}, &block)
  AMQP::Session.connect(connection_options_or_string, other_options, &block)
end