view release on metacpan or  search on metacpan

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

            message, and raise a channel exception if this is not the case.
          </doc>
        </rule>
      </field>
    </method>
    
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    
    <method name = "reject" index = "100" label = "reject an incoming message">
      <doc>
        This method 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 method to interrupt delivery of a
        large message.
      </doc>
      
      <rule name = "01">
        <doc>
          The server SHOULD interpret this method as meaning that the client is unable to
          process the message at this time.
        </doc>
      </rule>
      
      <!-- TODO: Rule split? -->
      
      <rule name = "02">
        <doc>
          A client MUST NOT use this method 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>
      
      <chassis name = "server" implement = "MUST" />
      
      <field name = "delivery-tag" domain = "delivery-tag" />
      
      <field name = "requeue" domain = "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 = "01">
          <!-- TODO: Rule split? -->
          <doc>
            The server MUST NOT deliver the message to the same client within the
            context of the current channel. 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>
    </method>
  </class>

  <!-- ==  STREAM  =========================================================== -->

  <class name = "stream" handler = "channel" index = "80" label = "work with streaming content">
    <doc>
      The stream class provides methods 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 favour
      of high priority messages.
    </doc>
    
    <doc type = "grammar">
      stream              = C:QOS S:QOS-OK
                          / C:CONSUME S:CONSUME-OK
                          / C:CANCEL S:CANCEL-OK
                          / C:PUBLISH content
                          / S:RETURN
                          / S:DELIVER content
    </doc>

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

    <rule name = "01">
      <doc>
        The server SHOULD discard stream messages on a priority basis if the queue size
        exceeds some configured limit.
      </doc>
    </rule>
    
    <rule name = "02">
      <!-- TODO: Rule split? -->
      <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 = "03">
      <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 method, the server must
        remove it from the queue.
      </doc>
    </rule>
    
    <!--  These are the properties for a Stream content  -->

    <field name = "content-type"    domain = "shortstr"   label = "MIME content type" />
    <field name = "content-encoding" domain = "shortstr"  label = "MIME content encoding" />
    <field name = "headers"         domain = "table"      label = "message header field table" />
    <field name = "priority"        domain = "octet"      label = "message priority, 0 to 9" />
    <field name = "timestamp"       domain = "timestamp"  label = "message timestamp" />

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <method name = "qos" synchronous = "1" index = "10" label = "specify quality of service">
      <doc>
        This method requests a specific quality of service. The QoS can be specified for the
        current channel or for all channels on the connection. The particular properties and
        semantics of a qos method always depend on the content class semantics. Though the
        qos method could in principle apply to both peers, it is currently meaningful only
        for the server.
      </doc>
      
      <chassis name = "server" implement = "MUST" />
      
      <response name = "qos-ok" />
      
      <field name = "prefetch-size" domain = "long" label = "prefetch 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 down the channel. Prefetching gives a performance
          improvement. This field specifies the prefetch window size in octets. May be set
          to zero, meaning "no specific limit". Note that other prefetch limits may still
          apply.
        </doc>
      </field>
      
      <field name = "prefetch-count" domain = "short" label = "prefetch window in messages">
        <doc>
          Specifies a prefetch 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 prefetch windows (and those at the channel and connection level)
          allow it.
        </doc>
      </field>
      
      <field name = "consume-rate" domain = "long" 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 = "01">
          <!-- TODO: Rule split? -->
          <doc>
            The server MAY ignore the prefetch values and consume rates, depending on
            the type of stream and the ability of the server to queue and/or reply it.
            The server MAY drop low-priority messages in favour of high-priority
            messages.
          </doc>
        </rule>
      </field>
      
      <field name = "global" domain = "bit" label = "apply to entire connection">
        <doc>
          By default the QoS settings apply to the current channel only. If this field is
          set, they are applied to the entire connection.
        </doc>
      </field>
    </method>
    
    <method name = "qos-ok" synchronous = "1" index = "11" label = "confirm the requested qos">
      <doc>
        This method 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>
      
      <chassis name = "client" implement = "MUST" />
    </method>
    
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    
    <method name = "consume" synchronous = "1" index = "20" label = "start a queue consumer">
      <doc>
        This method asks the server to start a "consumer", which is a transient request for
        messages from a specific queue. Consumers last as long as the channel they were
        created on, or until the client cancels them.
      </doc>

      <rule name = "01">
        <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 = "02">
        <doc>
          Streaming applications SHOULD use different channels 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>

      <chassis name = "server" implement = "MUST" />
      <response name = "consume-ok" />

      <field name = "ticket" domain = "access-ticket">
        <rule name = "01">
          <doc>
            The client MUST provide a valid access ticket giving "read" access rights to
            the realm for the queue.
          </doc>
        </rule>
      </field>

      <field name = "queue" domain = "queue-name">
        <doc>
          Specifies the name of the queue to consume from. If the queue name is null,
          refers to the current queue for the channel, which is the last declared queue.
        </doc>

        <rule name = "01">
          <doc>
            If the client did not previously declare a queue, and the queue name in this
            method is empty, the server MUST raise a connection exception with reply
            code 530 (not allowed).
          </doc>
        </rule>
      </field>

      <field name = "consumer-tag" domain = "consumer-tag">
        <doc>
          Specifies the identifier for the consumer. The consumer tag is local to a
          connection, so two clients can use the same consumer tags. If this field is
          empty the server will generate a unique tag.
        </doc>

        <rule name = "01">
          <!-- TODO: Rule split? -->
          <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 a
            connection exception with reply code 530 (not allowed).
          </doc>
        </rule>
      </field>

      <field name = "no-local" domain = "no-local" />

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


        <!-- Rule test name: was "amq_file_00" -->    
        <rule name = "01">