5.1 Event-Driven Messaging with Cloud Pub/Sub

Event-Driven Messaging with Cloud Pub/Sub

Google Cloud Pub/Sub is a fully managed, globally distributed asynchronous messaging service designed to decouple services that produce events from services that process events. In cloud-native microservices architectures, Pub/Sub acts as the core nervous system, providing low-latency ingestion, high availability across multiple availability zones and regions, and elastic scalability from zero to millions of messages per second without manual provisioning.

---

Architectural Components

Pub/Sub decouples publishers and subscribers through four fundamental resources:

1. Topic: A named resource to which publishers send messages. Topics exist globally across Google Cloud infrastructure.
2. Message: The data combination transmitted through the system. Each message consists of a payload (data, base64-encoded bytes up to 10 MB), user-defined key-value metadata pairs (attributes), a system-generated unique messageId, a publishTime timestamp, and an optional orderingKey.
3. Subscription: A named resource representing the stream of messages from a single specific topic to be delivered to the subscribing application. Multiple subscriptions can attach to a single topic, enabling 1-to-many fan-out message distribution.
4. Message Schemas: Formal contracts enforced by Pub/Sub that govern the structure and format of message payloads.

Message Schemas (Avro and Protocol Buffers)

To ensure data integrity between decoupled microservices, Pub/Sub supports schema enforcement using Apache Avro (.avsc) and Protocol Buffers (.proto). When a schema is attached to a topic, Pub/Sub validates published payloads before accepting them.

A topic with a schema validates message data against its configured Avro or Protobuf schema and selected JSON or binary encoding. Invalid payloads are rejected; there are no topic schema modes named FAIL_ALL_REQUESTS or ALLOW_ALL_REQUESTS. For a migration, manage compatible schema revisions and test publishers and subscribers before changing validation requirements.

## Create an Avro schema definition
gcloud pubsub schemas create order-schema-avro \
    --type=AVRO \
    --definition='{"type":"record","name":"Order","fields":[{"name":"orderId","type":"string"},{"name":"amount","type":"double"}]}'

## Create a topic enforcing the schema with JSON encoding
gcloud pubsub topics create orders-topic \
    --schema=order-schema-avro \
    --message-encoding=JSON

---

Subscription Types & Ingestion Modes

Pub/Sub offers four distinct subscription delivery architectures tailored to different processing models.

Pull Subscriptions: Synchronous vs. StreamingPull

• Synchronous Pull (projects.subscriptions.pull): The client application issues discrete unary RPC requests requesting up to maxMessages. This creates polling overhead and higher latency.
• StreamingPull: The client opens a persistent, bidirectional gRPC streaming connection. Pub/Sub pushes messages to the client immediately as they arrive. Client libraries maintain an internal thread pool that automatically extends acknowledgment deadlines (lease management) while messages are actively being processed, providing maximum throughput and minimal delivery latency.

Push Subscriptions & OIDC Authentication

Push subscriptions deliver messages by issuing an HTTPS POST request to a webhook endpoint. The payload is delivered in the HTTP request body as a JSON object containing the base64-encoded message.

## Create a Push subscription authenticated with an OIDC Service Account
gcloud pubsub subscriptions create orders-push-sub \
    --topic=orders-topic \
    --push-endpoint=https://orders-service-xyz.a.run.app/api/events \
    --push-auth-service-account=pubsub-invoker@my-project.iam.gserviceaccount.com \
    --ack-deadline=30

Push Acknowledgment Semantics:

• Success (ACK): The endpoint returns HTTP 102, 200, 201, 202, or 204. Pub/Sub marks the message as acknowledged.
• Failure (NACK): The endpoint returns any 4xx/5xx status code (e.g., 429, 500, 503) or fails to respond within the ack-deadline. Pub/Sub reschedules the message for redelivery.

---

Acknowledgment Deadlines & Lease Extensions

When a subscriber receives a message, Pub/Sub starts an Acknowledgment Deadline timer (configurable from 10 seconds to 600 seconds, defaulting to 10 seconds).

1. ACK (acknowledge): The subscriber finishes processing and calls acknowledge. The message is removed from the subscription queue.
2. NACK (modifyAckDeadline to 0): The subscriber encounters a transient failure and resets the deadline to 0 seconds. Pub/Sub makes the message eligible for redelivery, subject to the configured retry/backoff behavior.
3. Auto-Extension (Lease Management): Modern Google Cloud client libraries automatically monitor processing time and issue modifyAckDeadline calls in the background to extend the message lease up to a configured library-specific maximum lease duration (for example, one hour). If the worker container crashes, the background thread dies, the lease expires, and Pub/Sub automatically redelivers the message to another instance.

---

Message Ordering & The Head-of-Line Blocking Trap

By default, Cloud Pub/Sub prioritizes throughput and availability over strict message sequence, delivering messages out of order. When an application requires strict First-In, First-Out (FIFO) processing, Message Ordering must be explicitly configured.

How Ordering Works

1. The subscription must have ordering enabled (--enable-message-ordering).
2. The publisher must attach a non-empty string as the ordering_key (e.g., account-1082, device-id-9421) to each message.
3. Pub/Sub guarantees that messages with the same ordering key sent to the same region are delivered to subscribers in the exact order they were received by the service.

## Enable message ordering on subscription
gcloud pubsub subscriptions create ordered-orders-sub \
    --topic=orders-topic \
    --enable-message-ordering \
    --ack-deadline=60

---

Dead-Letter Topics (DLQs)

A message that repeatedly fails processing due to formatting errors or poisoned payloads ("poison pill messages") can consume infinite retries, starving worker pools and blocking ordered streams. To mitigate this, Pub/Sub supports Dead-Letter Topics.

• With the required service-agent permissions, Pub/Sub makes a best-effort attempt to forward repeatedly failing messages after approximately the configured --max-delivery-attempts (5 to 100). It forwards the unacknowledged message to the designated dead-letter topic.
• Once forwarded, the message is acknowledged and removed from the primary subscription queue, unblocking subsequent messages.

## Configure a subscription with a Dead-Letter Topic
gcloud pubsub subscriptions create orders-sub-with-dlq \
    --topic=orders-topic \
    --dead-letter-topic=orders-dlq-topic \
    --max-delivery-attempts=5 \
    --ack-deadline=30

---

Message Attributes & Server-Side Subscription Filtering

Subscriptions can inspect message attributes and filter incoming traffic server-side using boolean expressions. Only messages matching the filter expression are delivered to subscribers.

## Create a subscription filtering on custom attributes
gcloud pubsub subscriptions create priority-us-sub \
    --topic=orders-topic \
    --message-filter='attributes.priority = "high" AND (attributes.region = "us-east" OR attributes.region = "us-west")'

Filter Syntax Capabilities

• Exact string matching: attributes.status = "PENDING"
• Attribute existence check: attributes:category
• String prefix check: hasPrefix(attributes.category, "hardware")
• Attribute values are strings; equality/inequality and prefix/existence tests are supported, not numeric range comparisons. Use a string category such as attributes.tier = "gold".

---

Fan-Out Patterns & At-Least-Once Delivery Semantics

Pub/Sub uses at-least-once delivery by default. Without a supported exactly-once pull configuration, transient network timeouts, worker crashes during acknowledgment, and distributed replication can cause duplicate message deliveries.

Achieving Consumer Idempotency

Because duplicate deliveries can occur, subscriber services must be engineered to be idempotent:

1. Durable business-event keys: Use a stable business identifier, not only a delivery-specific ID. Within the same database transaction, insert a unique processed-event receipt and apply the business update. Commit before acknowledging. A crash then either rolls back both operations or leaves both durable.
2. External side effects: Use a downstream payment API's idempotency key or a transactional outbox. Writing a Redis marker before charging risks losing the charge if the worker crashes; writing it afterward risks duplicates. A cache alone cannot atomically coordinate the effect.
3. Exactly-once delivery option: Supported pull subscriptions can enable regional exactly-once delivery. It prevents redelivery after a successful acknowledgment under its documented conditions, but does not deduplicate separately published business events or make external side effects atomic.

Official references checked October 18, 2026: Google Cloud 1, Google Cloud 2.