src/dma/vendor/github.com/streadway/amqp/doc.go

   1 // Copyright (c) 2012, Sean Treadway, SoundCloud Ltd.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4 // Source code and contact info at http://github.com/streadway/amqp
   5
   6 /*
   7 Package amqp is an AMQP 0.9.1 client with RabbitMQ extensions
   8
   9 Understand the AMQP 0.9.1 messaging model by reviewing these links first. Much
  10 of the terminology in this library directly relates to AMQP concepts.
  11
  12   Resources
  13
  14   http://www.rabbitmq.com/tutorials/amqp-concepts.html
  15   http://www.rabbitmq.com/getstarted.html
  16   http://www.rabbitmq.com/amqp-0-9-1-reference.html
  17
  18 Design
  19
  20 Most other broker clients publish to queues, but in AMQP, clients publish
  21 Exchanges instead.  AMQP is programmable, meaning that both the producers and
  22 consumers agree on the configuration of the broker, instead requiring an
  23 operator or system configuration that declares the logical topology in the
  24 broker.  The routing between producers and consumer queues is via Bindings.
  25 These bindings form the logical topology of the broker.
  26
  27 In this library, a message sent from publisher is called a "Publishing" and a
  28 message received to a consumer is called a "Delivery".  The fields of
  29 Publishings and Deliveries are close but not exact mappings to the underlying
  30 wire format to maintain stronger types.  Many other libraries will combine
  31 message properties with message headers.  In this library, the message well
  32 known properties are strongly typed fields on the Publishings and Deliveries,
  33 whereas the user defined headers are in the Headers field.
  34
  35 The method naming closely matches the protocol's method name with positional
  36 parameters mapping to named protocol message fields.  The motivation here is to
  37 present a comprehensive view over all possible interactions with the server.
  38
  39 Generally, methods that map to protocol methods of the "basic" class will be
  40 elided in this interface, and "select" methods of various channel mode selectors
  41 will be elided for example Channel.Confirm and Channel.Tx.
  42
  43 The library is intentionally designed to be synchronous, where responses for
  44 each protocol message are required to be received in an RPC manner.  Some
  45 methods have a noWait parameter like Channel.QueueDeclare, and some methods are
  46 asynchronous like Channel.Publish.  The error values should still be checked for
  47 these methods as they will indicate IO failures like when the underlying
  48 connection closes.
  49
  50 Asynchronous Events
  51
  52 Clients of this library may be interested in receiving some of the protocol
  53 messages other than Deliveries like basic.ack methods while a channel is in
  54 confirm mode.
  55
  56 The Notify* methods with Connection and Channel receivers model the pattern of
  57 asynchronous events like closes due to exceptions, or messages that are sent out
  58 of band from an RPC call like basic.ack or basic.flow.
  59
  60 Any asynchronous events, including Deliveries and Publishings must always have
  61 a receiver until the corresponding chans are closed.  Without asynchronous
  62 receivers, the sychronous methods will block.
  63
  64 Use Case
  65
  66 It's important as a client to an AMQP topology to ensure the state of the
  67 broker matches your expectations.  For both publish and consume use cases,
  68 make sure you declare the queues, exchanges and bindings you expect to exist
  69 prior to calling Channel.Publish or Channel.Consume.
  70
  71   // Connections start with amqp.Dial() typically from a command line argument
  72   // or environment variable.
  73   connection, err := amqp.Dial(os.Getenv("AMQP_URL"))
  74
  75   // To cleanly shutdown by flushing kernel buffers, make sure to close and
  76   // wait for the response.
  77   defer connection.Close()
  78
  79   // Most operations happen on a channel.  If any error is returned on a
  80   // channel, the channel will no longer be valid, throw it away and try with
  81   // a different channel.  If you use many channels, it's useful for the
  82   // server to
  83   channel, err := connection.Channel()
  84
  85   // Declare your topology here, if it doesn't exist, it will be created, if
  86   // it existed already and is not what you expect, then that's considered an
  87   // error.
  88
  89   // Use your connection on this topology with either Publish or Consume, or
  90   // inspect your queues with QueueInspect.  It's unwise to mix Publish and
  91   // Consume to let TCP do its job well.
  92
  93 SSL/TLS - Secure connections
  94
  95 When Dial encounters an amqps:// scheme, it will use the zero value of a
  96 tls.Config.  This will only perform server certificate and host verification.
  97
  98 Use DialTLS when you wish to provide a client certificate (recommended),
  99 include a private certificate authority's certificate in the cert chain for
 100 server validity, or run insecure by not verifying the server certificate dial
 101 your own connection.  DialTLS will use the provided tls.Config when it
 102 encounters an amqps:// scheme and will dial a plain connection when it
 103 encounters an amqp:// scheme.
 104
 105 SSL/TLS in RabbitMQ is documented here: http://www.rabbitmq.com/ssl.html
 106
 107 */
 108 package amqp