Queue Ingresses

A queue ingress is an ingress that consumes messages from a queue on a connection and invokes a reactor component for each delivery. It is built for work messages — settled, competing-consumer queues where each message is processed once.

Delivery is at-least-once: a delivery is only settled after the component's outcome is known. A successful component run completes the message; a failing one requeues it and the broker redelivers. A message that keeps failing is eventually dead-lettered so a single poison message cannot block the queue.

Supported connections

Connection type	Queue ingress	Notes
rabbitmq	Yes	Addresses like /queues/my-queue.
azureServiceBus	Yes	Addresses pass through verbatim — Service Bus interprets queue and topic names.
azureEventHubs	No	Event Hubs is a retained event stream, not a queue — use a stream ingress.

Defining a queue ingress

A queue ingress can be created through the HTTP API, applied as a CLI manifest file, or declared in an app's manifest — whichever fits how you work:

PUT /resources/ingresses/consume
Content-Type: application/json

{
  "componentId": "ingresses/consume.hrc",
  "type": "queue",
  "properties": {
    "connectionId": "apps/my-app/partner-rabbit",
    "address": "/queues/orders-created",
    "priority": 100,
    "receive": {
      "credit": 16,
      "maxConcurrentMessages": 4,
      "settlement": "manual",
      "maxAttempts": 5
    },
    "body": { "mode": "structured" },
    "applicationProperties": { "eventType": "eventType" },
    "response": { "mode": "none" }
  },
  "acl": ["actors/ticket:create:*"]
}

Properties

Property	Required	Description
connectionId	Yes	The connection to consume from.
address	Yes	The logical queue or entity address, interpreted by the connection's adapter.
priority	No	Collision priority for the same connection+address; higher wins (default 0).
receive	No	Receive tuning (below).
body	No	Body binding (below).
applicationProperties	No	Maps named message application properties to declared component parameters.
response	No	Response mode; none (default) or replyTo.

Receive tuning:

Property	Default	Description
receive.credit	32	The credit window granted to the broker.
receive.maxConcurrentMessages	8	Upper bound on components running concurrently for one receiver.
receive.settlement	manual	manual settles each delivery after the component outcome (at-least-once); auto settles on receive.
receive.maxAttempts	5	Redelivery attempts before a delivery that keeps failing is rejected (dead-lettered).

Response mode replyTo: when the incoming message supplies a supported reply-to address, the normal component result is serialized and sent back over the same connection before the delivery completes.

Parameter binding

The queue runtime binds each delivery to the component's declared parameters using the same normalized envelope as other ingresses:

Parameter name	Binds
(body fields)	A structured body binds each JSON field to the same-named parameter.
(raw body parameter)	With body.mode: raw, the raw bytes bind to the parameter named by body.parameter. A structured non-JSON body also falls back to this parameter when one is configured.
messageId	The message's id.
correlationId	The message's correlation id.
subject	The message's subject.
replyTo	The message's reply-to address.
contentType	The message's content type.
creationTime	The message's creation time.
(application properties)	Each key of applicationProperties maps a named message property to a declared parameter.

body:
  mode: structured
applicationProperties:
  eventType: eventType   # binds the message's 'eventType' property to the 'eventType' param

Settlement outcomes

The component's result decides the settlement the broker receives:

Component outcome	Settlement	Effect
Success	Complete	The message is removed from the queue.
Failure (error result)	Retry	The message is requeued; the broker redelivers it.
Delivery count reaches maxAttempts	Reject	The message is dead-lettered (or dropped without a dead-letter exchange).

A failing component never loses its message — but make idempotency a habit: redelivery means the component may see the same message twice if it fails mid-side-effect.

Collisions

Two queue ingresses on the same connection and address do not both consume. The platform elects one winner:

1. Higher priority wins.
2. At equal priority, a tenant-created ingress precedes an app resource.
3. At equal priority and origin, the lexically smaller ingress id wins.

The losers stay installed but inactive, with a warning signal on the losing ingress (signals/ingresses/{id}/collision) naming the winner. Lower the winner's priority or change an address to hand consumption over.

Trace propagation

A message sent through an egress send carries the sending egress's trace. The queue ingress restores that trace — the ingress's request row names the sending egress as its trace parent. Connections to untrusted partners can opt out with traceContext: { receive: ignore } on the connection.

Authorization

ingresses:read    # View ingress configurations
ingresses:write   # Create, update, and delete ingresses

The component runs under the ingress's acl when one is declared (see Ingresses: ACL elevation).

Related

• Connections — endpoint and credentials
• Stream ingresses — for retained event streams
• Egresses — the send macro on the producing side