@blokjs/trigger-pubsub 0.2.3 → 0.6.2

package/__tests__/integration/gcp-pubsub.real-emulator.test.ts

@@ -0,0 +1,235 @@
+import type { PubSubMessage } from "@blokjs/runner";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { GCPPubSubAdapter } from "../../src/adapters/GCPPubSubAdapter";
+
+/**
+ * Real-GCP-emulator integration test for `GCPPubSubAdapter` (closes
+ * Phase 2.1 broker-adapter test debt deferred from PR #91).
+ *
+ * Gated on `BLOK_INTEGRATION_GCP_PUBSUB_ENDPOINT`. Skipped when unset.
+ *
+ * Bring up the emulator via:
+ *   docker compose -f infra/testing/docker-compose.yml up -d pubsub-emulator
+ *
+ * Then run:
+ *   BLOK_INTEGRATION_GCP_PUBSUB_ENDPOINT=localhost:8086 \
+ *   PUBSUB_EMULATOR_HOST=localhost:8086 \
+ *   PUBSUB_PROJECT_ID=blok-test \
+ *   bun run test
+ *
+ * Note: the GCP SDK's `PubSub` client only routes to the emulator when
+ * `PUBSUB_EMULATOR_HOST` is set BEFORE import. We set it in beforeAll
+ * to keep developers from having to remember the dance.
+ */
+
+const GCP_PUBSUB_ENDPOINT = process.env.BLOK_INTEGRATION_GCP_PUBSUB_ENDPOINT;
+const d = GCP_PUBSUB_ENDPOINT ? describe : describe.skip;
+
+const TEST_TIMEOUT_MS = 30_000;
+const TEST_PROJECT = "blok-test";
+
+/**
+ * Narrow shape for the bits of `@google-cloud/pubsub` we drive directly
+ * from this test (topic + subscription creation). Keeps us off `any`
+ * per the repo's no-`any`-in-tests rule.
+ */
+interface GcpTopic {
+	createSubscription(name: string): Promise<unknown>;
+	delete(): Promise<unknown>;
+	get(opts?: { autoCreate?: boolean }): Promise<unknown>;
+}
+
+interface GcpSubscription {
+	delete(): Promise<unknown>;
+}
+
+interface GcpPubSubClient {
+	topic(name: string): GcpTopic;
+	subscription(name: string): GcpSubscription;
+	createTopic(name: string): Promise<[GcpTopic, unknown]>;
+	close(): Promise<void>;
+}
+
+interface GcpPubSubModule {
+	PubSub: new (opts: { projectId: string }) => GcpPubSubClient;
+}
+
+d("GCPPubSubAdapter — real GCP Pub/Sub emulator", () => {
+	let adapter: GCPPubSubAdapter;
+	let testClient: GcpPubSubClient | null = null;
+	const createdTopics: string[] = [];
+	const createdSubscriptions: string[] = [];
+
+	beforeAll(async () => {
+		// Both the SDK and the adapter look at PUBSUB_EMULATOR_HOST — set
+		// it BEFORE importing to make sure the gRPC client routes to the
+		// emulator instead of trying production endpoints (and waiting
+		// for credentials we don't have).
+		process.env.PUBSUB_EMULATOR_HOST = GCP_PUBSUB_ENDPOINT;
+		process.env.PUBSUB_PROJECT_ID = TEST_PROJECT;
+		process.env.GOOGLE_CLOUD_PROJECT = TEST_PROJECT;
+
+		adapter = new GCPPubSubAdapter({ projectId: TEST_PROJECT });
+		await adapter.connect();
+
+		// Direct SDK client used only to create / tear down topics +
+		// subscriptions. The adapter doesn't expose these (production
+		// users provision them ahead of time via Terraform / gcloud).
+		const sdk = (await import("@google-cloud/pubsub")) as unknown as GcpPubSubModule;
+		testClient = new sdk.PubSub({ projectId: TEST_PROJECT });
+	}, TEST_TIMEOUT_MS);
+
+	async function createTopicAndSub(topicName: string, subscriptionName: string): Promise<void> {
+		if (!testClient) throw new Error("test client not initialised — beforeAll didn't run");
+		const [topic] = await testClient.createTopic(topicName);
+		createdTopics.push(topicName);
+		await topic.createSubscription(subscriptionName);
+		createdSubscriptions.push(subscriptionName);
+	}
+
+	afterEach(async () => {
+		// Tear down per-test resources so a flaky test doesn't poison
+		// the next one with stale messages or shared subscriptions.
+		for (const name of createdSubscriptions.splice(0)) {
+			try {
+				await testClient?.subscription(name).delete();
+			} catch {
+				/* ignore — best-effort */
+			}
+		}
+		for (const name of createdTopics.splice(0)) {
+			try {
+				await testClient?.topic(name).delete();
+			} catch {
+				/* ignore */
+			}
+		}
+	});
+
+	afterAll(async () => {
+		await adapter.disconnect();
+		try {
+			await testClient?.close();
+		} catch {
+			/* ignore */
+		}
+	});
+
+	it(
+		"publishes a message and the subscriber receives it",
+		async () => {
+			const topic = `blok-test-gcp-publish-${Math.random().toString(36).slice(2)}`;
+			const subscription = `${topic}-sub`;
+			await createTopicAndSub(topic, subscription);
+
+			const received: PubSubMessage[] = [];
+			await adapter.subscribe({ topic, subscription, durable: true }, async (msg) => {
+				received.push(msg);
+				await msg.ack();
+			});
+
+			// Pub/Sub subscriptions can take a moment to register the
+			// streaming pull connection. Give it a short warm-up so the
+			// first publish lands after the subscriber is actively pulling.
+			await new Promise((r) => setTimeout(r, 500));
+
+			await adapter.publish(topic, { hello: "gcp", n: 1 });
+
+			await waitFor(() => received.length === 1, TEST_TIMEOUT_MS - 5_000);
+
+			expect(received[0].body).toEqual({ hello: "gcp", n: 1 });
+			expect(received[0].topic).toBe(topic);
+			expect(received[0].subscription).toBe(subscription);
+
+			await adapter.unsubscribe(subscription);
+		},
+		TEST_TIMEOUT_MS,
+	);
+
+	it(
+		"delivers multiple messages to a single subscriber in publish order",
+		async () => {
+			const topic = `blok-test-gcp-order-${Math.random().toString(36).slice(2)}`;
+			const subscription = `${topic}-sub`;
+			await createTopicAndSub(topic, subscription);
+
+			const received: number[] = [];
+			await adapter.subscribe({ topic, subscription, durable: true }, async (msg) => {
+				const body = msg.body as { n: number };
+				received.push(body.n);
+				await msg.ack();
+			});
+			await new Promise((r) => setTimeout(r, 500));
+
+			for (let i = 0; i < 5; i++) {
+				await adapter.publish(topic, { n: i });
+			}
+
+			await waitFor(() => received.length === 5, TEST_TIMEOUT_MS - 5_000);
+
+			// GCP Pub/Sub doesn't guarantee order across a topic without
+			// `messageOrdering: true` + an `orderingKey`. Assert the set
+			// of values, not the sequence.
+			const seen = new Set(received);
+			expect(seen.size).toBe(5);
+			for (let i = 0; i < 5; i++) {
+				expect(seen.has(i)).toBe(true);
+			}
+
+			await adapter.unsubscribe(subscription);
+		},
+		TEST_TIMEOUT_MS,
+	);
+
+	it(
+		"isolates subscriptions across topics",
+		async () => {
+			const topicA = `blok-test-gcp-iso-a-${Math.random().toString(36).slice(2)}`;
+			const topicB = `blok-test-gcp-iso-b-${Math.random().toString(36).slice(2)}`;
+			const subA = `${topicA}-sub`;
+			const subB = `${topicB}-sub`;
+			await createTopicAndSub(topicA, subA);
+			await createTopicAndSub(topicB, subB);
+
+			const receivedA: PubSubMessage[] = [];
+			const receivedB: PubSubMessage[] = [];
+
+			await adapter.subscribe({ topic: topicA, subscription: subA, durable: true }, async (msg) => {
+				receivedA.push(msg);
+				await msg.ack();
+			});
+			await adapter.subscribe({ topic: topicB, subscription: subB, durable: true }, async (msg) => {
+				receivedB.push(msg);
+				await msg.ack();
+			});
+			await new Promise((r) => setTimeout(r, 500));
+
+			await adapter.publish(topicA, { from: "A" });
+			await adapter.publish(topicB, { from: "B" });
+
+			await waitFor(() => receivedA.length === 1 && receivedB.length === 1, TEST_TIMEOUT_MS - 5_000);
+
+			expect(receivedA[0].body).toEqual({ from: "A" });
+			expect(receivedB[0].body).toEqual({ from: "B" });
+
+			await adapter.unsubscribe(subA);
+			await adapter.unsubscribe(subB);
+		},
+		TEST_TIMEOUT_MS,
+	);
+
+	it("isConnected + healthCheck reflect the live state", async () => {
+		expect(adapter.isConnected()).toBe(true);
+		const healthy = await adapter.healthCheck();
+		expect(healthy).toBe(true);
+	});
+});
+
+async function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) {
+		if (predicate()) return;
+		await new Promise((r) => setTimeout(r, 100));
+	}
+	throw new Error(`waitFor timed out after ${timeoutMs}ms`);
+}

package/__tests__/integration/kafka-pubsub.real-kafka.test.ts

@@ -0,0 +1,269 @@
+import type { PubSubMessage } from "@blokjs/runner";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { KafkaPubSubAdapter } from "../../src/adapters/KafkaPubSubAdapter";
+
+/**
+ * Narrow shapes for the bits of `kafkajs` we touch in this test. The
+ * runtime types in the package are loosely-typed (the adapter itself
+ * pins `any` behind biome-ignore comments); these test-local interfaces
+ * keep us on the safe `as unknown as <T>` boundary-cast path required
+ * by the repo's no-`any`-in-tests rule.
+ */
+interface KafkaAdminClient {
+	connect(): Promise<void>;
+	disconnect(): Promise<void>;
+	createTopics(opts: {
+		waitForLeaders?: boolean;
+		topics: Array<{ topic: string; numPartitions: number; replicationFactor: number }>;
+	}): Promise<boolean>;
+	fetchTopicMetadata(opts: { topics: string[] }): Promise<unknown>;
+}
+
+interface KafkaConsumerForWarmup {
+	connect(): Promise<void>;
+	subscribe(opts: { topic: string; fromBeginning?: boolean }): Promise<void>;
+	run(opts: { eachMessage: () => Promise<void> }): Promise<void>;
+	disconnect(): Promise<void>;
+}
+
+interface KafkaClient {
+	admin(): KafkaAdminClient;
+	consumer(opts: { groupId: string }): KafkaConsumerForWarmup;
+}
+
+interface KafkaJsModule {
+	Kafka: new (opts: { clientId: string; brokers: string[] }) => KafkaClient;
+}
+
+/**
+ * Real-Kafka integration test for `KafkaPubSubAdapter` (closes Phase 2.1
+ * broker-adapter test debt deferred from PR #91).
+ *
+ * Exercises both the **fan-out** (no `consumerGroup` — adapter generates
+ * per-subscriber group ids) and **competing-consumer** (explicit shared
+ * `consumerGroup`) delivery patterns documented in the adapter.
+ *
+ * Gated on `BLOK_INTEGRATION_KAFKA_BROKERS`. Skipped when unset, so the
+ * regular unit test run on a developer laptop without docker-compose
+ * doesn't break.
+ *
+ * Bring up the test fixtures via:
+ *   docker compose -f infra/testing/docker-compose.yml up -d kafka
+ *
+ * Then run:
+ *   BLOK_INTEGRATION_KAFKA_BROKERS=localhost:9094 bun run test
+ */
+
+const KAFKA_BROKERS = process.env.BLOK_INTEGRATION_KAFKA_BROKERS;
+const d = KAFKA_BROKERS ? describe : describe.skip;
+
+// CI runners are slower than local — Kafka group coordinator assignment
+// alone takes a few seconds for a fresh consumer, and the first message
+// after subscribe usually waits one heartbeat. Bump the per-test cap so
+// CI doesn't flake on the assignment + first-poll round-trip.
+const TEST_TIMEOUT_MS = 45_000;
+const SUBSCRIPTION_WARMUP_MS = 2_000;
+
+d("KafkaPubSubAdapter — real Kafka", () => {
+	let producer: KafkaPubSubAdapter;
+	let consumerA: KafkaPubSubAdapter;
+	let consumerB: KafkaPubSubAdapter;
+	let admin: KafkaAdminClient | null = null;
+
+	beforeAll(async () => {
+		const brokers = KAFKA_BROKERS?.split(",").map((s) => s.trim()) ?? [];
+		producer = new KafkaPubSubAdapter({ brokers, clientId: "blok-test-pubsub-producer" });
+		await producer.connect();
+
+		consumerA = new KafkaPubSubAdapter({ brokers, clientId: "blok-test-pubsub-consumer-a" });
+		await consumerA.connect();
+
+		consumerB = new KafkaPubSubAdapter({ brokers, clientId: "blok-test-pubsub-consumer-b" });
+		await consumerB.connect();
+
+		// Admin client used only by this test to pre-create topics
+		// before consumers subscribe — eliminates the metadata-propagation
+		// race where `auto.create.topics.enable` lets a subscribe succeed
+		// against a topic the producer can't immediately see (kafkajs
+		// reports "This server does not host this topic-partition" on the
+		// first publish attempt). The adapter itself relies on auto-create
+		// in production (Kafka's durable-log model means orphan publishes
+		// are valid); this guard is purely a test-hygiene measure.
+		const kafkajs = (await import("kafkajs")) as unknown as KafkaJsModule;
+		const adminKafka = new kafkajs.Kafka({ clientId: "blok-test-pubsub-admin", brokers });
+		admin = adminKafka.admin();
+		await admin.connect();
+
+		// Cold-start warmup. On a freshly booted broker (the CI case),
+		// Kafka's `__consumer_offsets` topic and the group-coordinator
+		// election aren't ready immediately after the broker accepts
+		// admin connections. The first `consumer.run()` that triggers
+		// `findCoordinator` hits the 5-retry budget before the offsets
+		// topic is fully initialised and throws
+		// `KafkaJSNumberOfRetriesExceeded: This is not the correct
+		// coordinator for this group`.
+		//
+		// Drive that initialisation explicitly here: create a throwaway
+		// topic, run a brief consumer against it (which forces group-
+		// coordinator election), then disconnect. Subsequent real test
+		// subscribes find a warm coordinator and skip the race.
+		const warmupTopic = `blok-test-pubsub-warmup-${Math.random().toString(36).slice(2)}`;
+		await admin.createTopics({
+			waitForLeaders: true,
+			topics: [{ topic: warmupTopic, numPartitions: 1, replicationFactor: 1 }],
+		});
+		const warmupConsumer = adminKafka.consumer({ groupId: `blok-test-warmup-${Math.random().toString(36).slice(2)}` });
+		await warmupConsumer.connect();
+		await warmupConsumer.subscribe({ topic: warmupTopic, fromBeginning: true });
+		await warmupConsumer.run({
+			eachMessage: async () => {
+				/* never fires — topic stays empty */
+			},
+		});
+		// Give the group coordinator a beat to finalise the join+sync
+		// for the warmup group. Without this, the next test's subscribe
+		// can still race on a brand-new group's coordinator lookup.
+		await new Promise((r) => setTimeout(r, 2_000));
+		await warmupConsumer.disconnect();
+	}, TEST_TIMEOUT_MS);
+
+	afterAll(async () => {
+		// Best-effort cleanup. A failed test can leave a consumer in a
+		// state where `disconnect()` hangs (kafkajs internal retry loop
+		// still running). Wrap each call in a 5s timeout so a single
+		// stuck consumer doesn't trip vitest's default 10s afterAll
+		// cap and cascade-mask the real failure.
+		const safeDisconnect = async (label: string, fn: () => Promise<void>): Promise<void> => {
+			try {
+				await Promise.race([
+					fn(),
+					new Promise((_, reject) => setTimeout(() => reject(new Error(`${label} disconnect timed out`)), 5_000)),
+				]);
+			} catch {
+				/* ignore — afterAll is best-effort */
+			}
+		};
+		await safeDisconnect("consumerA", () => consumerA.disconnect());
+		await safeDisconnect("consumerB", () => consumerB.disconnect());
+		await safeDisconnect("producer", () => producer.disconnect());
+		if (admin) {
+			await safeDisconnect("admin", () => admin?.disconnect() ?? Promise.resolve());
+		}
+	}, 30_000);
+
+	async function createTopic(topic: string, numPartitions = 1): Promise<void> {
+		if (!admin) throw new Error("admin client not initialised — beforeAll didn't run");
+		await admin.createTopics({
+			waitForLeaders: true,
+			topics: [{ topic, numPartitions, replicationFactor: 1 }],
+		});
+	}
+
+	it(
+		"fan-out: every subscriber without an explicit consumerGroup receives every message",
+		async () => {
+			// Topic name varies per run so the consumer-group offset state
+			// from a prior run doesn't bleed into this one. Pre-create via
+			// admin so the producer's metadata is fresh before the first
+			// publish — bypasses the auto-create-on-publish race that
+			// shows up as "This server does not host this topic-partition".
+			const topic = `blok-test-pubsub-fanout-${Math.random().toString(36).slice(2)}`;
+			await createTopic(topic, 1);
+			const receivedA: PubSubMessage[] = [];
+			const receivedB: PubSubMessage[] = [];
+
+			await consumerA.subscribe({ topic, durable: false, startFrom: "earliest" }, async (msg) => {
+				receivedA.push(msg);
+			});
+			await consumerB.subscribe({ topic, durable: false, startFrom: "earliest" }, async (msg) => {
+				receivedB.push(msg);
+			});
+
+			// Kafka group-coordinator assignment is asynchronous; the
+			// `consumer.run` call above returns once the consumer LOOP has
+			// started, but the first heartbeat-driven assignment isn't done
+			// yet. Without this warm-up we routinely lose the first publish
+			// to "no assigned partition" on cold-CI runs.
+			await new Promise((r) => setTimeout(r, SUBSCRIPTION_WARMUP_MS));
+
+			await producer.publish(topic, { hello: "kafka", n: 1 });
+
+			await waitFor(() => receivedA.length === 1 && receivedB.length === 1, TEST_TIMEOUT_MS - 10_000);
+
+			expect(receivedA[0].body).toEqual({ hello: "kafka", n: 1 });
+			expect(receivedB[0].body).toEqual({ hello: "kafka", n: 1 });
+			expect(receivedA[0].topic).toBe(topic);
+			expect(receivedB[0].topic).toBe(topic);
+		},
+		TEST_TIMEOUT_MS,
+	);
+
+	it(
+		"competing-consumer: explicit consumerGroup means each message goes to exactly one subscriber",
+		async () => {
+			// Three partitions so each consumer in the shared group gets at
+			// least one assignment — exercises the actual competing-consumer
+			// load-balance instead of routing all 10 messages to whichever
+			// consumer happened to win the single-partition leadership.
+			const topic = `blok-test-pubsub-competing-${Math.random().toString(36).slice(2)}`;
+			await createTopic(topic, 3);
+			const group = `blok-test-workers-${Math.random().toString(36).slice(2)}`;
+			const receivedA: PubSubMessage[] = [];
+			const receivedB: PubSubMessage[] = [];
+
+			await consumerA.subscribe({ topic, consumerGroup: group, durable: false, startFrom: "earliest" }, async (msg) => {
+				receivedA.push(msg);
+			});
+			await consumerB.subscribe({ topic, consumerGroup: group, durable: false, startFrom: "earliest" }, async (msg) => {
+				receivedB.push(msg);
+			});
+
+			await new Promise((r) => setTimeout(r, SUBSCRIPTION_WARMUP_MS));
+
+			// Publish 10 messages with distinct partition keys so the
+			// broker spreads them across the topic's partitions. The
+			// auto-created topic defaults to 1 partition, which means BOTH
+			// consumers join the same group but only ONE gets the partition
+			// assignment — and therefore all 10 messages. We can't assert a
+			// 50/50 split, but we CAN assert exactly-once delivery across
+			// the union.
+			for (let i = 0; i < 10; i++) {
+				await producer.publish(topic, { n: i }, { partitionKey: String(i) });
+			}
+
+			await waitFor(() => receivedA.length + receivedB.length === 10, TEST_TIMEOUT_MS - 10_000);
+
+			expect(receivedA.length + receivedB.length).toBe(10);
+			const seenN = new Set<number>();
+			for (const m of [...receivedA, ...receivedB]) {
+				const n = (m.body as { n: number }).n;
+				expect(seenN.has(n)).toBe(false);
+				seenN.add(n);
+			}
+			expect(seenN.size).toBe(10);
+		},
+		TEST_TIMEOUT_MS,
+	);
+
+	it(
+		"publish to a topic with no subscribers does not throw",
+		async () => {
+			// Note: kafkajs's auto.create.topics.enable is true on the test
+			// broker, so this also exercises the on-publish topic-create
+			// path. The publish should succeed even if no consumer is
+			// listening — that's the durable-log model Kafka guarantees.
+			const topic = `blok-test-pubsub-orphan-${Math.random().toString(36).slice(2)}`;
+			await expect(producer.publish(topic, { dropped: true })).resolves.toBeUndefined();
+		},
+		TEST_TIMEOUT_MS,
+	);
+});
+
+async function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) {
+		if (predicate()) return;
+		await new Promise((r) => setTimeout(r, 50));
+	}
+	throw new Error(`waitFor timed out after ${timeoutMs}ms`);
+}

package/__tests__/integration/nats-pubsub.real-nats.test.ts

@@ -0,0 +1,138 @@
+import type { PubSubMessage } from "@blokjs/runner";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { NATSPubSubAdapter } from "../../src/adapters/NATSPubSubAdapter";
+
+/**
+ * Real-NATS integration test for `NATSPubSubAdapter` (closes the
+ * integration test debt from PR #87).
+ *
+ * Exercises both the **fan-out** (no `consumerGroup`) and
+ * **competing-consumer** (with `consumerGroup`) delivery patterns
+ * documented in the trigger.
+ *
+ * Gated on `BLOK_INTEGRATION_NATS_SERVERS`. Skipped when unset.
+ *
+ * Bring up the test fixtures via:
+ *   docker compose -f infra/testing/docker-compose.yml up -d nats
+ */
+
+const NATS_SERVERS = process.env.BLOK_INTEGRATION_NATS_SERVERS;
+const d = NATS_SERVERS ? describe : describe.skip;
+
+// CI runners are slower than local — JetStream stream + consumer creation
+// + cross-instance subscription propagation can take several seconds on
+// a cold container. Override the default 5s timeout so CI doesn't flake.
+const TEST_TIMEOUT_MS = 30_000;
+const SUBSCRIPTION_WARMUP_MS = 500;
+
+d("NATSPubSubAdapter — real NATS", () => {
+	let producer: NATSPubSubAdapter;
+	let consumerA: NATSPubSubAdapter;
+	let consumerB: NATSPubSubAdapter;
+
+	beforeAll(async () => {
+		producer = new NATSPubSubAdapter({
+			servers: NATS_SERVERS?.split(",").map((s) => s.trim()) ?? [],
+		});
+		await producer.connect();
+
+		consumerA = new NATSPubSubAdapter({
+			servers: NATS_SERVERS?.split(",").map((s) => s.trim()) ?? [],
+		});
+		await consumerA.connect();
+
+		consumerB = new NATSPubSubAdapter({
+			servers: NATS_SERVERS?.split(",").map((s) => s.trim()) ?? [],
+		});
+		await consumerB.connect();
+	});
+
+	afterAll(async () => {
+		await consumerA.disconnect();
+		await consumerB.disconnect();
+		await producer.disconnect();
+	});
+
+	it(
+		"fan-out: every subscriber without consumerGroup receives every message",
+		async () => {
+			const topic = `blok-test-pubsub-fanout-${Math.random().toString(36).slice(2)}`;
+			const receivedA: PubSubMessage[] = [];
+			const receivedB: PubSubMessage[] = [];
+
+			await consumerA.subscribe({ topic, durable: false }, async (msg) => {
+				receivedA.push(msg);
+			});
+			await consumerB.subscribe({ topic, durable: false }, async (msg) => {
+				receivedB.push(msg);
+			});
+
+			// JetStream subscription registration is asynchronous — give the
+			// consumer a moment to install before publishing.
+			await new Promise((r) => setTimeout(r, SUBSCRIPTION_WARMUP_MS));
+
+			await producer.publish(topic, { hello: "world", n: 1 });
+
+			await waitFor(() => receivedA.length === 1 && receivedB.length === 1, TEST_TIMEOUT_MS - 5_000);
+
+			expect(receivedA[0].body).toEqual({ hello: "world", n: 1 });
+			expect(receivedB[0].body).toEqual({ hello: "world", n: 1 });
+		},
+		TEST_TIMEOUT_MS,
+	);
+
+	it(
+		"competing-consumer: consumerGroup means each message goes to one subscriber",
+		async () => {
+			const topic = `blok-test-pubsub-competing-${Math.random().toString(36).slice(2)}`;
+			const group = "workers";
+			const receivedA: PubSubMessage[] = [];
+			const receivedB: PubSubMessage[] = [];
+
+			await consumerA.subscribe({ topic, consumerGroup: group, durable: false }, async (msg) => {
+				receivedA.push(msg);
+			});
+			await consumerB.subscribe({ topic, consumerGroup: group, durable: false }, async (msg) => {
+				receivedB.push(msg);
+			});
+
+			await new Promise((r) => setTimeout(r, SUBSCRIPTION_WARMUP_MS));
+
+			// Publish 10 messages — should split across A + B (not exact 50/50
+			// but each message reaches exactly one).
+			for (let i = 0; i < 10; i++) {
+				await producer.publish(topic, { n: i });
+			}
+
+			await waitFor(() => receivedA.length + receivedB.length === 10, TEST_TIMEOUT_MS - 5_000);
+
+			expect(receivedA.length + receivedB.length).toBe(10);
+			// No duplicate keys across both lists.
+			const seenN = new Set<number>();
+			for (const m of [...receivedA, ...receivedB]) {
+				const n = (m.body as { n: number }).n;
+				expect(seenN.has(n)).toBe(false);
+				seenN.add(n);
+			}
+		},
+		TEST_TIMEOUT_MS,
+	);
+
+	it(
+		"publish to an unsubscribed topic does not throw",
+		async () => {
+			const topic = `blok-test-pubsub-orphan-${Math.random().toString(36).slice(2)}`;
+			await expect(producer.publish(topic, { dropped: true })).resolves.toBeUndefined();
+		},
+		TEST_TIMEOUT_MS,
+	);
+});
+
+async function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) {
+		if (predicate()) return;
+		await new Promise((r) => setTimeout(r, 50));
+	}
+	throw new Error(`waitFor timed out after ${timeoutMs}ms`);
+}