Channel Mapping

This is the master reference for how the embedded KubeMQ Pub/Sub connector maps Pub/Sub topics and subscriptions onto KubeMQ. A topic is backed by exactly one KubeMQ Events Store log; each subscription is backed by its own KubeMQ Queue channel. This deterministic mapping is the contract that makes cross-protocol interop work — a Pub/Sub Publish and a native KubeMQ consume meet on the same channel.

Resource → channel table

The {p} project segment is parsed and validated but ignored — the connector is single-tenant, like the emulator, so resource ids are global across projects. Two clients using different project ids but the same topic id share one gcp.{t} log.

Topic grammar

A topic maps to exactly one KubeMQ Events Store log:

gcp.{t}
└┬┘ └┬┘
 │   └─ the topic id (the bare id you pass to CreateTopic — NOT the projects/.../topics/ path)
 └─ fixed connector prefix ("gcp.")

Subscription grammar

Each subscription maps to its own KubeMQ Queue channel:

gcp.sub.{s}
└──┬───┘ └┬┘
   │      └─ the subscription id (bare, not the projects/.../subscriptions/ path)
   └─ fixed connector prefix + reserved sub-namespace ("gcp.sub.")

A subscription id may not contain the reserved .k. or .h. infixes — those are owned by the per-key channel grammar below.

Per-ordering-key channels

When a subscription enables message ordering, the connector routes each ordering key onto its own queue channel so the broker preserves per-key order natively. The base gcp.sub.{s} channel continues to serve keyless messages:

gcp.sub.{s}.k.{enc(key)}
└───┬────┘ └┬┘ └───┬────┘
    │       │      └─ the ordering key, percent-encoded
    │       └─ fixed ".k." per-key separator
    └─ the subscription's base queue channel

enc percent-encodes any byte outside [a-zA-Z0-9_-]. If the encoded channel name would exceed its length budget, the connector falls back to a deterministic sha256 form gcp.sub.{s}.h.{hash} — the same key always hashes to the same channel on every node, so per-key order is still preserved (the fallback only couples multiple long keys onto one FIFO channel).

Write-once-then-fan-out

A Publish is not copied to every subscription on the wire. The connector:

1. Writes once to the topic log gcp.{t} via Array.SendEventsStore — the authoritative, cross-protocol, replayable copy and the source for Seek.
2. Fans out one queue copy per subscription via Array.SendQueueMessage(gcp.sub.{s}), applying each subscription's filter — a filtered-out message is never enqueued (≈ auto-acked). Detached subscriptions are skipped.

So the topic log holds the complete history; each subscription queue holds the filtered slice that subscription still owes its consumers.

Reserved tags

A PubsubMessage becomes a KubeMQ message whose body is data and whose Tags are the message attributes plus three reserved tags carried across the wire:

Attribute ⇄ tag round-trip

Attribute keys must not start with goog (Google's reserved prefix); the connector enforces this at publish (INVALID_ARGUMENT). See Limits & Rules.

Cross-protocol interoperability

Because the topic log is a normal KubeMQ Events Store channel, a Pub/Sub Publish to topic orders is consumable by a native gRPC/REST Events Store subscriber on channel gcp.orders, and a subscription's backlog is a native Queue channel gcp.sub.{s}.

The registry is authoritative

Topics, subscriptions, snapshots, and schemas live in a per-node replicated registry (synchronized across cluster nodes with a last-writer-wins rule). Only resources created through the Pub/Sub API are visible to the Pub/Sub surface — a Pull from a subscription that was never CreateSubscriptiond returns NOT_FOUND. (A native client can still read the raw gcp.{t} log directly regardless of the registry.)

Related