diff --git a/channel_api.md b/channel_api.md index bcccf740..02ae93ff 100644 --- a/channel_api.md +++ b/channel_api.md @@ -2,7 +2,7 @@ layout: default title: Channel API reference --- - + # Channel-oriented API reference * [Overview](#overview) @@ -77,7 +77,6 @@ argument (and usually some value as the second argument). Likewise, "reject" etc., will mean rejecting a promise or calling the callback with an `Error` as the first argument (and no value). -[^top](#top) ## Overview @@ -102,7 +101,6 @@ server. These return either nothing (`ack[All]`, `nack[All]`, `reject`) or a boolean (`publish` and `sendToQueue`); see [flow control](#flowcontrol). -[^top](#top) ## Dealing with failure @@ -142,7 +140,6 @@ connection.createChannel().then(function(ch) { }); ``` -[^top](#top) ### Exceptions and promises @@ -178,7 +175,6 @@ amqp.connect().then(function(conn) { }); ``` -[^top](#top) ### Exceptions and callbacks @@ -214,7 +210,6 @@ dom.run(function() { }); ``` -[^top](#top) ## Flow control @@ -316,7 +311,6 @@ aliases for most encodings, as shown in the examples. NB AMQP only has signed integers in tables. -[^top](#top) ## API reference @@ -368,17 +362,14 @@ URI, e.g., as in `'amqp://localhost?frameMax=0x1000'`. These are: connection. `0` means no limit (but since frames have a size field which is an unsigned 32 bit integer, it's perforce `2^32 - 1`); I default it to 0x1000, i.e. 4kb, which is the allowed minimum, will - fit many purposes, and not chug through Node.JS's buffer pooling. - + fit many purposes, and not chug through Node.JS's buffer pooling.

* `channelMax`, the maximum number of channels allowed. Default is - `0`, meaning `2^16 - 1`. - + `0`, meaning `2^16 - 1`.

* `heartbeat`: the period of the connection heartbeat, in - seconds. Defaults to `0`; see [heartbeating](#heartbeating) - + seconds. Defaults to `0`; see [heartbeating](#heartbeating)

* `locale`: the desired locale for error messages, I suppose. RabbitMQ only ever uses `en_US`; which, happily, is the - default. + default.

###### Connecting with an object instead of a URL @@ -455,7 +446,6 @@ the server value is also `0`. See NOTE: Please consider NOT disabling heartbeats because they exist for a [reason](http://www.rabbitmq.com/heartbeats.html). -[^top](#top) ## ChannelModel and CallbackModel @@ -464,7 +454,6 @@ take as an argument a `connection.Connection`. It is better to use `connect()`, which will open the connection for you. The constructors are exported as potential extension points. -[^top](#top) ### {Channel,Callback}Model#close @@ -523,7 +512,6 @@ open.then(function(conn) { **NB** it's no good using `process.on('exit', ...)`, since `close()` needs to do I/O. -[^top](#top) ### {Channel,Callback}Model events @@ -572,7 +560,6 @@ extension][rabbitmq-connection-blocked] for details. Emitted at some time after `'blocked'`, once the resource shortage has alleviated. -[^top](#top) ### {Channel,Callback}Model#createChannel @@ -589,7 +576,6 @@ channel; but it is not usable before the callback has been invoked). May fail if there are no more channels available (i.e., if there are already `channelMax` channels open). -[^top](#top) ### {Channel,Callback}Model#createConfirmChannel @@ -604,7 +590,6 @@ there are already `channelMax` channels open). Open a fresh channel, switched to "confirmation mode". See `ConfirmChannel` below. -[^top](#top) ## Channels @@ -623,7 +608,6 @@ point. When using a client API, obtain an open `Channel` by opening a connection (`connect()` above) and calling `#createChannel` or `#createConfirmChannel`. -[^top](#top) ### Channel#close @@ -645,7 +629,6 @@ channels, and thereby other things such as exclusive locks on queues, so it is occasionally worth being deliberate about opening and closing channels. -[^top](#top) ### Channel events @@ -684,7 +667,6 @@ if it has previously returned `false` from `#publish` or `#sendToQueue`, once its write buffer has been emptied (i.e., once it is ready for writes again). -[^top](#top) ### Channel#assertQueue @@ -697,10 +679,9 @@ is ready for writes again). `#assertQueue([queue, [options, [function(err, ok) {...}]]])` Assert a queue into existence. This operation is idempotent given -identical arguments; however, it will bork the channel if the queue +identical arguments; however, it will break the channel if the queue already exists but has different properties (values supplied in the -`arguments` field may or may not count for borking purposes; check the -borker's, I mean broker's, documentation). +`arguments` field may or may not matter; check the broker's, documentation). `queue` is a string; if you supply an empty string or other falsey value (including `null` and `undefined`), the server will create a @@ -710,17 +691,14 @@ random name for you. if it's the last argument. The relevant fields in options are: * `exclusive`: if true, scopes the queue to the connection (defaults - to false) - + to false)

* `durable`: if true, the queue will survive broker restarts, modulo the effects of `exclusive` and `autoDelete`; this defaults to true - if not supplied, unlike the others - + if not supplied, unlike the others

* `autoDelete`: if true, the queue will be deleted when the number of - consumers drops to zero (defaults to false) - + consumers drops to zero (defaults to false)

* `arguments`: additional arguments, usually parameters for some kind - of broker-specific extension e.g., high availability, TTL. + of broker-specific extension e.g., high availability, TTL.

RabbitMQ extensions can also be supplied as options. These typically require non-standard `x-*` keys and values, sent in the `arguments` @@ -730,26 +708,22 @@ prefix for the key is removed; e.g., `'expires'`. Values supplied in `options.arguments`. * `messageTtl` (0 <= n < 2^32): expires messages arriving in the - queue after n milliseconds - + queue after n milliseconds

* `expires` (0 < n < 2^32): the queue will be destroyed after n milliseconds of disuse, where use means having consumers, being declared (asserted or checked, in this API), or being polled with a - `#get`. - + `#get`.

* `deadLetterExchange` (string): an exchange to which messages discarded from the queue will be resent. Use `deadLetterRoutingKey` to set a routing key for discarded messages; otherwise, the message's routing key (and CC and BCC, if present) will be preserved. A message is discarded when it expires or is rejected or - nacked, or the queue limit is reached. - + nacked, or the queue limit is reached.

* `maxLength` (positive integer): sets a maximum number of messages the queue will hold. Old messages will be discarded (dead-lettered - if that's set) to make way for new messages. - + if that's set) to make way for new messages.

* `maxPriority` (positive integer): makes the queue a [priority - queue][rabbitmq-priority-queue]. + queue][rabbitmq-priority-queue].

Resolves to the "ok" reply from the server, which includes fields for the queue name (important if you let the server name it), a recent @@ -763,7 +737,6 @@ consumer count, and a recent message count; e.g., } ``` -[^top](#top) ### Channel#checkQueue @@ -775,12 +748,11 @@ consumer count, and a recent message count; e.g., `#checkQueue(queue, [function(err, ok) {...}])` -Check whether a queue exists. This will bork the channel if the named +Check whether a queue exists. This will break the channel if the named queue *doesn't* exist; if it does exist, you go through to the next round! There's no options, unlike `#assertQueue()`, just the queue name. The reply from the server is the same as for `#assertQueue()`. -[^top](#top) ### Channel#deleteQueue @@ -798,11 +770,10 @@ RabbitMQ version 3.2.0 and after[1][rabbitmq-idempotent-delete]). The options here are: * `ifUnused` (boolean): if true and the queue has consumers, it will - not be deleted and the channel will be closed. Defaults to false. - + not be deleted and the channel will be closed. Defaults to false.

* `ifEmpty` (boolean): if true and the queue contains messages, the queue will not be deleted and the channel will be closed. Defaults - to false. + to false.

Note the obverse semantics of the options: if both are true, the queue will be deleted only if it has no consumers *and* no messages. @@ -813,7 +784,6 @@ queue unconditionally. The server reply contains a single field, `messageCount`, with the number of messages deleted or dead-lettered along with the queue. -[^top](#top) ### Channel#purgeQueue @@ -834,7 +804,6 @@ closes without acknowledging them). The server reply contains a single field, `messageCount`, containing the number of messages purged from the queue. -[^top](#top) ### Channel#bindQueue @@ -859,7 +828,6 @@ it's the last argument, which is equivalent to an empty object. The server reply has no fields. -[^top](#top) ### Channel#unbindQueue @@ -880,7 +848,6 @@ mistake; RabbitMQ before version 3.2.0 softens this to a channel error, and from version 3.2.0, doesn't treat it as an error at all[1][rabbitmq-idempotent-delete]. Good ol' RabbitMQ). -[^top](#top) ### Channel#assertExchange @@ -894,8 +861,8 @@ all[1][rabbitmq-idempotent-delete]. Good ol' RabbitMQ). Assert an exchange into existence. As with queues, if the exchange exists already and has properties different to those supplied, the -channel will 'splode; fields in the arguments object may or may not be -'splodey, depending on the type of exchange. Unlike queues, you must +channel will break; fields in the arguments object may or may not matter, +depending on the type of exchange. Unlike queues, you must supply a name, and it can't be the empty string. You must also supply an exchange type, which determines how messages will be routed through the exchange. @@ -907,25 +874,21 @@ use the `arguments` table to supply parameters. The options: * `durable` (boolean): if true, the exchange will survive broker - restarts. Defaults to true. - + restarts. Defaults to true.

* `internal` (boolean): if true, messages cannot be published directly to the exchange (i.e., it can only be the target of - bindings, or possibly create messages ex-nihilo). Defaults to false. + bindings, or possibly create messages ex-nihilo). Defaults to false.

s * `autoDelete` (boolean): if true, the exchange will be destroyed once the number of bindings for which it is the source drop to - zero. Defaults to false. - + zero. Defaults to false.

* `alternateExchange` (string): an exchange to send messages to if - this exchange can't route them to any queues. - + this exchange can't route them to any queues.

* `arguments` (object): any additional arguments that may be needed - by an exchange type. + by an exchange type.

The server reply echoes the exchange name, in the field `exchange`. -[^top](#top) ### Channel#checkExchange @@ -940,7 +903,6 @@ The server reply echoes the exchange name, in the field `exchange`. Check that an exchange exists. If it doesn't exist, the channel will be closed with an error. If it does exist, happy days. -[^top](#top) ### Channel#deleteExchange @@ -955,7 +917,7 @@ be closed with an error. If it does exist, happy days. Delete an exchange. The only meaningful field in `options` is: * `ifUnused` (boolean): if true and the exchange has bindings, it - will not be deleted and the channel will be closed. + will not be deleted and the channel will be closed.

If the exchange does not exist, a channel error is raised (RabbitMQ version 3.2.0 and after will not raise an @@ -963,7 +925,6 @@ error[1][rabbitmq-idempotent-delete]). The server reply has no fields. -[^top](#top) ### Channel#bindExchange @@ -985,7 +946,6 @@ a routing key equal to the pattern. The server reply has no fields. -[^top](#top) ### Channel#unbindExchange @@ -1004,7 +964,6 @@ exists, it's – you guessed it – a channel error, except in RabbitMQ >= version 3.2.0, for which it succeeds trivially[1][rabbitmq-idempotent-delete]. -[^top](#top) ### Channel#publish @@ -1022,63 +981,56 @@ Publish a single message to an exchange. The mandatory parameters are: (or undefined) as the exchange, which will send directly to the queue named by the routing key; `#sendToQueue` below is equivalent to this special case. If the named exchange does not exist, the channel will be - closed. - + closed.

* `content`: a buffer containing the message content. This will be copied during encoding, so it is safe to mutate it once this method - has returned. + has returned.

The remaining parameters are provided as fields in `options`, and are divided into those that have some meaning to RabbitMQ and those that will be ignored by RabbitMQ but passed on to consumers. `options` may -be omitted altogether, in which case defaults as noted will apply. +be omitted altogether, in which case defaults as noted will apply.

The "meaningful" options are a mix of fields in BasicDeliver (the method used to publish a message), BasicProperties (in the message header frame) and RabbitMQ extensions which are given in the `headers` -table in BasicProperties. +table in BasicProperties.

Used by RabbitMQ and sent on to consumers: * `expiration` (string): if supplied, the message will be discarded from a queue once it's been there longer than the given number of milliseconds. In the specification this is a string; numbers - supplied here will be coerced to strings for transit. - + supplied here will be coerced to strings for transit.

* `userId` (string): If supplied, RabbitMQ will compare it to the username supplied when opening the connection, and reject messages - for which it does not match. - + for which it does not match.

* `CC` (string or array of string): an array of routing keys as strings; messages will be routed to these routing keys in addition to that given as the `routingKey` parameter. A string will be implicitly treated as an array containing just that string. This will override any value given for `CC` in the `headers` parameter. **NB** The property names `CC` and `BCC` are - case-sensitive. - + case-sensitive.

* `priority` (positive integer): a priority for the message; ignored by versions of RabbitMQ older than 3.5.0, or if the queue is not a [priority queue][rabbitmq-priority-queue] (see `maxPriority` - above). - + above).

* `persistent` (boolean): If truthy, the message will survive broker restarts provided it's in a queue that also survives restarts. Corresponds to, and overrides, the property - `deliveryMode`. - + `deliveryMode`.

* `deliveryMode` (boolean or numeric): Either `1` or falsey, meaning non-persistent; or, `2` or truthy, meaning persistent. That's just - obscure though. Use the option `persistent` instead. + obscure though. Use the option `persistent` instead.

Used by RabbitMQ but not sent on to consumers: * `mandatory` (boolean): if true, the message will be returned if it is not routed to a queue (i.e., if there are no bindings that match - its routing key). - + its routing key).

* `BCC` (string or array of string): like `CC`, except that the value - will not be sent in the message headers to consumers. + will not be sent in the message headers to consumers.

Not used by RabbitMQ and not sent to consumers: @@ -1086,44 +1038,35 @@ Not used by RabbitMQ and not sent to consumers: server to return the message if it is not able to be sent immediately to a consumer. No longer implemented in RabbitMQ, and if true, will provoke a channel error, so it's best to leave it - out. + out.

Ignored by RabbitMQ (but may be useful for applications): - * `contentType` (string): a MIME type for the message content - - * `contentEncoding` (string): a MIME encoding for the message content - + * `contentType` (string): a MIME type for the message content

+ * `contentEncoding` (string): a MIME encoding for the message content

* `headers` (object): application specific headers to be carried along with the message content. The value as sent may be augmented by extension-specific fields if they are given in the parameters, for example, 'CC', since these are encoded as message headers; the - supplied value won't be mutated. - + supplied value won't be mutated.

* `correlationId` (string): usually used to match replies to - requests, or similar - + requests, or similar

* `replyTo` (string): often used to name a queue to which the receiving application must send replies, in an RPC scenario (many - libraries assume this pattern) - + libraries assume this pattern)

* `messageId` (string): arbitrary application-specific identifier for - the message - - * `timestamp` (positive number): a timestamp for the message - + the message

+ * `timestamp` (positive number): a timestamp for the message

* `type` (string): an arbitrary application-specific type for the - message - + message

* `appId` (string): an arbitrary identifier for the originating - application + application

`#publish` mimics the [`stream.Writable`][nodejs-write] interface in its return value; it will return `false` if the channel's write buffer is 'full', and `true` otherwise. If it returns `false`, it will emit a `'drain'` event at some later time. -[^top](#top) ### Channel#sendToQueue @@ -1138,7 +1081,6 @@ Send a single message with the `content` given as a buffer to the specific `queue` named, bypassing routing. The options and return value are exactly the same as for `#publish`. -[^top](#top) ### Channel#consume @@ -1158,30 +1100,25 @@ Options (which may be omitted if the last argument): distinguish message deliveries for the consumer; mustn't be already in use on the channel. It's usually easier to omit this, in which case the server will create a random name and supply it in the - reply. - + reply.

* `noLocal` (boolean): in theory, if true then the broker won't deliver messages to the consumer if they were also published on this connection; RabbitMQ doesn't implement it though, and will ignore - it. Defaults to false. - + it. Defaults to false.

* `noAck` (boolean): if true, the broker won't expect an acknowledgement of messages delivered to this consumer; i.e., it will dequeue messages as soon as they've been sent down the wire. Defaults to false (i.e., you will be expected to acknowledge - messages). - + messages).

* `exclusive` (boolean): if true, the broker won't let anyone else consume from this queue; if there already is a consumer, there goes your channel (so usually only useful if you've made a 'private' - queue by letting the server choose its name). - + queue by letting the server choose its name).

* `priority` (integer): gives a priority to the consumer; higher priority consumers get messages in preference to lower priority consumers. See [this RabbitMQ extension's - documentation][rabbitmq-consumer-priority] - - * `arguments` (object): arbitrary arguments. Go to town. + documentation][rabbitmq-consumer-priority]

+ * `arguments` (object): arbitrary arguments. Go to town.

The server reply contains one field, `consumerTag`. It is necessary to remember this somewhere if you will later want to cancel this consume @@ -1217,7 +1154,6 @@ sent in the `headers` table so will appear there in deliveries. If the [consumer is cancelled][rabbitmq-consumer-cancel] by RabbitMQ, the message callback will be invoked with `null`. -[^top](#top) ### Channel#cancel @@ -1238,7 +1174,6 @@ will no longer be invoked. The `consumerTag` is the string given in the reply to `#consume`, which may have been generated by the server. -[^top](#top) ### Channel#get @@ -1260,9 +1195,8 @@ Options: * `noAck` (boolean): if true, the message will be assumed by the server to be acknowledged (i.e., dequeued) as soon as it's been sent over the wire. Default is false, that is, you will be expected to - acknowledge the message. + acknowledge the message.

-[^top](#top) ### Channel#ack @@ -1286,10 +1220,9 @@ omitted, only the message supplied is acknowledged. It's an error to supply a message that either doesn't require acknowledgement, or has already been acknowledged. Doing so will -errorise the channel. If you want to acknowledge all the messages and +break the channel. If you want to acknowledge all the messages and you don't have a specific message around, use `#ackAll`. -[^top](#top) ### Channel#ackAll @@ -1303,7 +1236,6 @@ Acknowledge all outstanding messages on the channel. This is a "safe" operation, in that it won't result in an error even if there are no such messages. -[^top](#top) ### Channel#nack @@ -1328,7 +1260,6 @@ dead-lettered or discarded, supply `false` here. This and `#nackAll` use a [RabbitMQ-specific extension][rabbitmq-nack]. -[^top](#top) ### Channel#nackAll @@ -1341,7 +1272,6 @@ extension][rabbitmq-nack]. Reject all messages outstanding on this channel. If `requeue` is truthy, or omitted, the server will try to re-enqueue the messages. -[^top](#top) ### Channel#reject @@ -1354,22 +1284,23 @@ truthy, or omitted, the server will try to re-enqueue the messages. Reject a message. Equivalent to `#nack(message, false, requeue)`, but works in older versions of RabbitMQ (< v2.3.0) where `#nack` does not. -[^top](#top) ### Channel#prefetch -##### Promises and callback APIs +##### Promises API `#prefetch(count, [global])` -**NOTE**: Does not return a promise in the promises API, or accept a callback in the callback API. +##### Callback API + +`#prefetch(count, [[global], [function(err, ok) {...}]])` Set the prefetch count for this channel. The `count` given is the maximum number of messages sent over the channel that can be awaiting acknowledgement; once there are `count` messages outstanding, the server will not send more messages on this channel until one or more have been acknowledged. A falsey value for `count` indicates no such -limit. +limit. The server will reply (with an empty object) if successful. **NB** RabbitMQ v3.3.0 changes the meaning of prefetch (basic.qos) to apply per-*consumer*, rather than per-channel. It will apply to @@ -1380,7 +1311,6 @@ Use the `global` flag to get the per-channel behaviour. To keep life interesting, using the `global` flag with an RabbitMQ older than v3.3.0 will bring down the whole connection. -[^top](#top) ### Channel#recover @@ -1395,7 +1325,6 @@ v3.3.0 will bring down the whole connection. Requeue unacknowledged messages on this channel. The server will reply (with an empty object) once all messages are requeued. -[^top](#top) ## ConfirmChannel @@ -1450,7 +1379,6 @@ This constructor is a channel that uses confirms. It is exported as an extension point. To obtain such a channel, use `connect` to get a connection, then call `#createConfirmChannel`. -[^top](#top) ### ConfirmChannel#publish @@ -1463,7 +1391,6 @@ connection, then call `#createConfirmChannel`. `options` argument must be supplied, at least as an empty object. -[^top](#top) ### ConfirmChannel#sendToQueue @@ -1476,7 +1403,6 @@ connection, then call `#createConfirmChannel`. `options` argument must be supplied, at least as an empty object. -[^top](#top) ### ConfirmChannel#waitForConfirms @@ -1495,7 +1421,6 @@ way, the channel is still usable afterwards. It is also possible to call waitForConfirms multiple times without waiting for previous invocations to complete. -[^top](#top) --------- @@ -1509,7 +1434,6 @@ This does not apply to preconditions given to the operations. For example deleting a queue with `{ifEmpty: true}` will still fail if there are messages in the queue. -[^top](#top) [amqpurl]: http://www.rabbitmq.com/uri-spec.html [rabbitmq-tutes]: http://www.rabbitmq.com/getstarted.html