6 AMQP Connection and Channel Contracts

6.1 Learning Objectives

One Link, Many Safe Work Streams

Picture a factory site that sends alarms, meter readings, and work updates to one central service. Opening a new network link for every small task would waste time and memory. Letting all tasks share one unmarked stream would make faults hard to contain.

A protocol means a shared set of communication rules. Advanced Message Queuing Protocol (AMQP) is one such set for moving messages between systems. It solves this problem with two levels. A connection is the main network link. The central message service receives each item and routes it onward. A channel is a numbered work stream inside that link. Many channels can share one connection while keeping their own actions and errors separate.

Start with one connection per trust and failure boundary. Add channels for work that may share that boundary. Give each channel an owner and a clear use. Watch both levels: a broken channel may affect one task, while a broken connection affects every channel inside it.

This is a useful first model, not the whole wire story. Limits, recovery, ordering, and flow rules add detail.

Use Practitioner to plan channel ownership and recovery. Use Under the Hood to inspect frames, limits, and failure spread.

A protocol is a set of exchange rules. Advanced Message Queuing Protocol (AMQP) is a set of broker rules for queued messages. A broker is the service that stores and routes those messages. A gateway is a local bridge. Transmission Control Protocol (TCP) is a checked byte stream. Telemetry is measured device data. Transport layer security is a way to protect a link. Transport Layer Security (TLS) protects this link.

Plain AMQP check

• Name the long link. Name each small channel. Name each broker object. Name each owner.
• Test one closed channel. Test one closed link. Test old broker state. Save each result.
• Check channel numbers. Check frame order. Check access bounds. Keep each flow apart.
• Plan safe retry. Plan safe cleanup. Plan a full restart. Record what state remains.
• Check one busy channel. Check one quiet channel. Check shared link loss. Keep each result clear.
• Use Practitioner to manage. Use deeper frame checks. Test one shared fault. State each bound.

After this page, you should be able to:

• Distinguish an AMQP TCP connection from the channels multiplexed inside it.
• Explain why topology objects live on the broker rather than inside clients.
• Use idempotent and passive declarations to make exchanges and queues reviewable.
• Scope prefetch, acknowledgements, channel errors, and heartbeats correctly.
• Explain why concurrent publishing threads need separate channels on a shared connection.

6.2 Why This Follows AMQP Core Architecture

AMQP Core Architecture introduces the producer, exchange, binding, queue, and consumer model used for server-side routing. This page tightens the lower-level operating contract underneath that model: one process typically keeps a shared connection, workers use separate channels, durable topology is declared repeatably, and frame ordering remains channel-scoped.

Use it when an IoT gateway publishes telemetry while consuming commands, when a broker sees channel churn or thread-safety errors, when a deployment needs repeatable topology declarations, or when packet captures must separate connection liveness from message acknowledgement.

6.3 One Connection, Many Channels, a Stateful Broker

A typical AMQP 0-9-1 client process keeps one or a small number of long-lived TCP/TLS connections to the broker and multiplexes lightweight channels inside each one. A channel is a lightweight AMQP 0-9-1 protocol context: publishes, subscriptions, acknowledgements, and topology commands happen on a channel, and the broker keeps channel-scoped state. Opening a fresh TCP connection per operation would waste handshakes, memory, and file descriptors; channels let one connection carry concurrent conversations without confusing them with AMQP 1.0 sessions.

The other half of the picture is that routing topology belongs to the broker, not to client memory. Its lifetime still follows declaration properties. Durable exchanges and queues can survive a broker restart; an exclusive queue ends with its declaring connection; auto-delete queues and expiry policies can remove temporary resources. A reconnecting client should therefore redeclare or passively verify the topology it expects instead of assuming that every resource has the same lifetime.

Worked example — gateway fan-in. Suppose an IoT gateway process publishes telemetry, receives command replies, and runs a small health consumer. A poor design opens a new TLS connection for each publish and tears it down after the message. That repeats TCP setup, TLS negotiation, AMQP authentication, and broker resource allocation for work that may last only milliseconds. A better design opens one process-level connection, creates one publishing channel for telemetry, one consuming channel for commands, and another channel for health checks. If the command consumer is redeclared or restarted, the telemetry channel does not need a new socket.

The broker-side objects explain why this works. The exchange called iot.telemetry, the queue called ingest, and the binding between them live on the broker, not inside the gateway’s memory. The gateway can reconnect after a crash, declare the same durable topology, and resume publishing through a fresh channel. For learners, the mental model is: the connection is the pipe, channels are labeled lanes in the pipe, and the broker stores the map that says where each message should go.

The figure below separates three scopes that are easy to collapse into one: the TCP/TLS connection, the AMQP 0-9-1 channels multiplexed inside it, and the exchanges, bindings, and queues maintained within the broker’s virtual host.

Inspect Figure 6.1 to separate transport, protocol concurrency, and broker-owned topology before planning recovery.

Read Figure 6.1 from client tasks into channels inside one connection, then cross into the broker and its virtual-host resources. A channel fault can be local; connection loss removes every enclosed channel; resource lifetime follows declaration properties. That scope map determines the smallest safe recovery action.

Diagnose and recover at the smallest correct scope. Replace a failed channel without discarding healthy channels; after connection loss, create fresh channels and redeclare or passively verify the intended topology instead of assuming every broker resource had the same lifetime.

6.4 Try It: AMQP Virtual Host Boundaries

A connection also chooses a virtual host on the broker. That vhost scopes the exchanges, queues, bindings, users, and permissions the client can see, so two teams can reuse names such as telemetry without sharing the same resources. Treat the vhost as part of the connection contract: a bridge that moves messages between vhosts needs separate connections and explicit permissions on each side.

6.5 Connection vs Channel, and Declaring Topology

You build the routing topology by declaring it, and declarations are idempotent: queue.declare and exchange.declare create the object if it is absent and otherwise confirm it matches. A passive declare checks existence without creating, which is how a consumer can fail fast if the expected queue is missing. The durable flag is set here, on the object: a durable exchange or queue survives a broker restart. (Whether the messages inside survive is a separate setting covered in the delivery chapter — durability of the container and persistence of the contents are independent choices.)

Worked example. A gateway process with three worker threads opens one connection and three channels. Thread A declares (durable) exchange iot.telemetry and queue ingest, binding them once at startup. Threads B and C each consume on their own channel with their own prefetch. If thread C sends a malformed frame, the broker closes channel C with a channel.close carrying a reply code; threads A and B keep running on the same connection.

Worked example — declaration mismatch. A deployment script declares queue ingest as durable. Later, a test consumer starts with the same queue name but declares it as non-durable. The broker should reject the mismatch rather than silently changing the existing queue’s contract, because changing durability would alter restart behavior for every consumer using that queue. A safer consumer uses a passive declare in production: if the queue is missing or has the wrong properties, the service fails fast and the runbook points to the topology deployment step. The practical rule is to make topology declarations repeatable, but not ambiguous.

Prefetch belongs in the same review, but its exact scope depends on the broker and client call. In RabbitMQ, the common basic.qos(..., global=false) form applies the limit separately to each newly registered consumer; an additional global=true call can impose a shared channel-wide limit. If a worker holds 50 unacknowledged deliveries, those deliveries are unavailable to other consumers until acknowledged or the channel closes. A common IoT ingestion pattern is therefore a small number of long-lived connections, separate channels for concurrent workers, durable topology declared at startup, and bounded consumer prefetch chosen from processing time and acceptable retry delay.

6.6 Everything Travels as Channel-Tagged Frames

On the wire, AMQP 0-9-1 is a stream of frames, each stamped with the channel number it belongs to, which is how one TCP socket demultiplexes many channels. There are four frame kinds:

• Method frame — carries a command such as basic.publish, queue.declare, or basic.ack.
• Content header frame — for a message, carries the body size and the properties (delivery mode, content type, headers, correlation id).
• Content body frame(s) — the payload bytes, split across as many body frames as the frame-max negotiated at connection time requires.
• Heartbeat frame — sent on channel 0 to prove the connection is alive when no other traffic flows.

So publishing one message is really a method frame + content header frame + body frames on the same channel, in order. Channel 0 is reserved for connection-global negotiation (connection.start, connection.tune, heartbeats). This is the framing that AMQP 1.0 replaces entirely: instead of channels and these method frames, 1.0 negotiates sessions and links and moves payload in transfer frames — a genuinely different wire protocol, covered in the frames-and-reliability chapter.

Worked example — frame ordering. A publisher sends a 70 kB payload on channel 3 after the connection negotiated a body-frame size below that payload length. The broker sees a basic.publish method frame, then a content header frame that states the total body size, then multiple content body frames tagged with channel 3 until the declared byte count is complete. If another thread writes a second publish on the same channel at the same time, its method/header/body frames can interleave with the first sequence. The broker cannot reconstruct two ordered messages from an interleaved per-channel stream, which is why client libraries warn against sharing one channel across publishing threads.

Heartbeats show the connection boundary. A quiet connection still exchanges heartbeat frames on channel 0 so both sides know the TCP session is alive. Those heartbeats do not acknowledge messages and do not prove a consumer processed anything; they only prove the connection has not gone silent. Message progress is still visible through channel-scoped methods such as basic.ack, basic.nack, and basic.cancel. Under the hood, AMQP architecture is the discipline of keeping these scopes separate: connection liveness, channel state, topology objects, and message delivery are related but not interchangeable.