view release on metacpan or  search on metacpan

spec/amqp0-10.xml  view on Meta::CPAN

    <!-- - Command: file.reject  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <command name="reject" code="0xd" label="reject an incoming message">
      <doc>
        This command allows a client to reject a message. It can be used to return untreatable
        messages to their original queue. Note that file content is staged before delivery, so the
        client will not use this command to interrupt delivery of a large message.
      </doc>

      <rule name="server-interpretation">
        <doc>
          The server SHOULD interpret this command as meaning that the client is unable to process
          the message at this time.
        </doc>
      </rule>

      <rule name="not-selection">
        <doc>
          A client MUST NOT use this command as a means of selecting messages to process. A rejected
          message MAY be discarded or dead-lettered, not necessarily passed to another client.
        </doc>
      </rule>

      <implement role="server" handle="MUST" />

      <field name="delivery-tag" type="uint64">
        <doc>
        the identifier of the message to be rejected
        </doc>
        <rule name="session-local">
          <doc>
            The delivery tag is valid only within the session from which the message was received.
            i.e. A client MUST NOT receive a message on one session and then reject it on another.
          </doc>
        </rule>
      </field>

      <field name="requeue" type="bit" label="requeue the message">
        <doc>
          If this field is zero, the message will be discarded. If this bit is 1, the server will
          attempt to requeue the message.
        </doc>

        <rule name="requeue-strategy">
          <doc>
            The server MUST NOT deliver the message to the same client within the context of the
            current session. The recommended strategy is to attempt to deliver the message to an
            alternative consumer, and if that is not possible, to move the message to a dead-letter
            queue. The server MAY use more sophisticated tracking to hold the message on the queue
            and redeliver it to the same client at a later stage.
          </doc>
        </rule>
      </field>
    </command>

  </class>

  <!-- == Class: stream ======================================================================== -->

  <class name="stream" code="0xa" label="work with streaming content">
    <doc>
      The stream class provides commands that support multimedia streaming. The stream class uses
      the following semantics: one message is one packet of data; delivery is unacknowledged and
      unreliable; the consumer can specify quality of service parameters that the server can try to
      adhere to; lower-priority messages may be discarded in favor of high priority messages.
    </doc>

    <doc type="grammar">
      stream  = C:QOS S:QOS-OK
              / C:CONSUME S:CONSUME-OK
              / C:CANCEL
              / C:PUBLISH content
              / S:RETURN
              / S:DELIVER content
    </doc>

    <rule name="overflow-discard">
      <doc>
        The server SHOULD discard stream messages on a priority basis if the queue size exceeds some
        configured limit.
      </doc>
    </rule>

    <rule name="priority-levels">
      <doc>
        The server MUST implement at least 2 priority levels for stream messages, where priorities
        0-4 and 5-9 are treated as two distinct levels. The server MAY implement up to 10 priority
        levels.
      </doc>
    </rule>

    <rule name="acknowledgement-support">
      <doc>
        The server MUST implement automatic acknowledgements on stream content. That is, as soon as
        a message is delivered to a client via a Deliver command, the server must remove it from the
        queue.
      </doc>
    </rule>

    <role name="server" implement="MAY" />
    <role name="client" implement="MAY" />

    <!--  These are the properties for a Stream content  -->
    <struct name="stream-properties" size="4" code="0x1" pack="2">
      <field name="content-type" type="str8" label="MIME content type" />
      <field name="content-encoding" type="str8" label="MIME content encoding" />
      <field name="headers" type="map" label="message header field table" />
      <field name="priority" type="uint8" label="message priority, 0 to 9" />
      <field name="timestamp" type="datetime" label="message timestamp" />
    </struct>

    <domain name="return-code" type="uint16" label="return code from server">
      <doc>
        The return code. The AMQP return codes are defined by this enum.
      </doc>
      <enum>
        <choice name="content-too-large" value="311">
          <doc>
            The client attempted to transfer content larger than the server could accept.
          </doc>
        </choice>

        <choice name="no-route" value="312">
          <doc>
            The exchange cannot route a message, most likely due to an invalid routing key. Only
            when the mandatory flag is set.
          </doc>
        </choice>

        <choice name="no-consumers" value="313">
          <doc>
            The exchange cannot deliver to a consumer when the immediate flag is set. As a result of
            pending data on the queue or the absence of any consumers of the queue.
          </doc>
        </choice>
      </enum>
    </domain>

    <!-- - Command: stream.qos - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <command name="qos" code="0x1" label="specify quality of service">
      <doc>
        This command requests a specific quality of service. The QoS can be specified for the
        current session or for all sessions on the connection. The particular properties and
        semantics of a qos command always depend on the content class semantics. Though the qos
        command could in principle apply to both peers, it is currently meaningful only for the
        server.
      </doc>

      <implement role="server" handle="MUST" />

      <response name="qos-ok" />

      <field name="prefetch-size" type="uint32" label="pre-fetch window in octets">
        <doc>
          The client can request that messages be sent in advance so that when the client finishes
          processing a message, the following message is already held locally, rather than needing
          to be sent within the session. Pre-fetching gives a performance improvement. This field
          specifies the pre-fetch window size in octets. May be set to zero, meaning "no specific
          limit". Note that other pre-fetch limits may still apply.
        </doc>
      </field>

      <field name="prefetch-count" type="uint16" label="pre-fetch window in messages">
        <doc>
          Specifies a pre-fetch window in terms of whole messages. This field may be used in
          combination with the prefetch-size field; a message will only be sent in advance if both
          pre-fetch windows (and those at the session and connection level) allow it.
        </doc>
      </field>

      <field name="consume-rate" type="uint32" label="transfer rate in octets/second">
        <doc>
          Specifies a desired transfer rate in octets per second. This is usually determined by the
          application that uses the streaming data. A value of zero means "no limit", i.e. as
          rapidly as possible.
        </doc>

        <rule name="ignore-prefetch">
          <doc>
            The server MAY ignore the pre-fetch values and consume rates, depending on the type of
            stream and the ability of the server to queue and/or reply it.
          </doc>
        </rule>

        <rule name="drop-by-priority">
          <doc>
            The server MAY drop low-priority messages in favor of high-priority messages.
          </doc>
        </rule>
      </field>

      <field name="global" type="bit" label="apply to entire connection">
        <doc>
          By default the QoS settings apply to the current session only. If this field is set, they
          are applied to the entire connection.
        </doc>
      </field>
    </command>

    <!-- - Command: stream.qos-ok  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <command name="qos-ok" code="0x2" label="confirm the requested qos">
      <doc>
        This command tells the client that the requested QoS levels could be handled by the server.
        The requested QoS applies to all active consumers until a new QoS is defined.
      </doc>

      <implement role="client" handle="MUST" />
    </command>

    <!-- - Command: stream.consume - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <command name="consume" code="0x3" label="start a queue consumer">
      <doc>
        This command asks the server to start a "consumer", which is a transient request for
        messages from a specific queue. Consumers last as long as the session they were created on,
        or until the client cancels them.
      </doc>

      <rule name="min-consumers">
        <doc>
          The server SHOULD support at least 16 consumers per queue, unless the queue was declared
          as private, and ideally, impose no limit except as defined by available resources.
        </doc>
      </rule>

      <rule name="priority-based-delivery">
        <doc>
          Streaming applications SHOULD use different sessions to select different streaming
          resolutions. AMQP makes no provision for filtering and/or transforming streams except on
          the basis of priority-based selective delivery of individual messages.
        </doc>
      </rule>

      <implement role="server" handle="MUST" />

      <response name="consume-ok" />

      <field name="queue" type="queue.name">
        <doc>
          Specifies the name of the queue to consume from.
        </doc>

        <exception name="queue-exists-if-empty" error-code="not-allowed">
          <doc>
            If the queue name in this command is empty, the server MUST raise an exception.
          </doc>
        </exception>
      </field>

      <field name="consumer-tag" type="str8">
        <doc>
          Specifies the identifier for the consumer. The consumer tag is local to a connection, so
          two clients can use the same consumer tags.
        </doc>

        <exception name="not-existing-consumer" error-code="not-allowed">
          <doc>
            The tag MUST NOT refer to an existing consumer. If the client attempts to create two
            consumers with the same non-empty tag the server MUST raise an exception.
          </doc>
        </exception>

        <exception name="not-empty-consumer-tag" error-code="not-allowed">
          <doc>
            The client MUST NOT specify a tag that is empty or blank.
          </doc>
          <doc type="scenario">
            Attempt to create a consumers with an empty tag.
          </doc>
        </exception>
      </field>

      <field name="no-local" type="bit">
        <doc>If the no-local field is set the server will not send messages to the connection that
        published them.</doc>
      </field>

      <field name="exclusive" type="bit" label="request exclusive access">
        <doc>
          Request exclusive consumer access, meaning only this consumer can access the queue.
        </doc>

        <exception name="in-use" error-code="resource-locked">
          <doc>
            If the server cannot grant exclusive access to the queue when asked, - because there are
            other consumers active - it MUST raise an exception with return code 405
            (resource locked).
          </doc>