@blokjs/trigger-pubsub 0.6.18 → 0.6.20

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

@@ -1,269 +0,0 @@
-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

@@ -1,138 +0,0 @@
-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`);
-}

package/src/PubSubTrigger.test.ts

@@ -1,151 +0,0 @@
-/**
- * PubSubTrigger Tests
- *
- * Tests the PubSubTrigger base class and adapter interfaces.
- */
-
-import { describe, expect, it, vi } from "vitest";
-
-describe("PubSubTrigger", () => {
-	describe("PubSubMessage Interface", () => {
-		it("should accept valid pub/sub message structure", () => {
-			const message = {
-				id: "msg-123",
-				body: { event: "order.created", data: { orderId: 456 } },
-				attributes: { "content-type": "application/json", source: "orders-service" },
-				raw: {},
-				topic: "orders",
-				subscription: "orders-subscription",
-				publishTime: new Date(),
-				ack: async () => {},
-				nack: async () => {},
-			};
-
-			expect(message.id).toBe("msg-123");
-			expect(message.body).toEqual({ event: "order.created", data: { orderId: 456 } });
-			expect(message.topic).toBe("orders");
-			expect(message.subscription).toBe("orders-subscription");
-		});
-
-		it("should handle minimal required fields", () => {
-			const message = {
-				id: "msg-id",
-				body: null,
-				attributes: {},
-				raw: null,
-				topic: "test-topic",
-				ack: async () => {},
-				nack: async () => {},
-			};
-
-			expect(message.id).toBeDefined();
-			expect(message.topic).toBeDefined();
-			expect(message.ack).toBeDefined();
-			expect(message.nack).toBeDefined();
-		});
-	});
-
-	describe("PubSubAdapter Interface", () => {
-		it("should validate adapter interface methods", () => {
-			const mockAdapter = {
-				provider: "gcp" as const,
-				connect: vi.fn().mockResolvedValue(undefined),
-				disconnect: vi.fn().mockResolvedValue(undefined),
-				subscribe: vi.fn().mockResolvedValue(undefined),
-				unsubscribe: vi.fn().mockResolvedValue(undefined),
-				isConnected: vi.fn().mockReturnValue(true),
-				healthCheck: vi.fn().mockResolvedValue(true),
-			};
-
-			expect(mockAdapter.provider).toBe("gcp");
-			expect(typeof mockAdapter.connect).toBe("function");
-			expect(typeof mockAdapter.disconnect).toBe("function");
-			expect(typeof mockAdapter.subscribe).toBe("function");
-			expect(typeof mockAdapter.unsubscribe).toBe("function");
-			expect(typeof mockAdapter.isConnected).toBe("function");
-			expect(typeof mockAdapter.healthCheck).toBe("function");
-		});
-	});
-});
-
-describe("GCPPubSubAdapter", () => {
-	it("should create adapter with config from environment", () => {
-		const originalProject = process.env.GOOGLE_CLOUD_PROJECT;
-		process.env.GOOGLE_CLOUD_PROJECT = "test-project";
-
-		const config = {
-			projectId: process.env.GOOGLE_CLOUD_PROJECT,
-		};
-
-		expect(config.projectId).toBe("test-project");
-
-		process.env.GOOGLE_CLOUD_PROJECT = originalProject;
-	});
-});
-
-describe("AWSSNSAdapter", () => {
-	it("should create adapter with config from environment", () => {
-		const originalRegion = process.env.AWS_REGION;
-		const originalWaitTime = process.env.SQS_WAIT_TIME_SECONDS;
-
-		process.env.AWS_REGION = "eu-central-1";
-		process.env.SQS_WAIT_TIME_SECONDS = "15";
-
-		const config = {
-			region: process.env.AWS_REGION || "us-east-1",
-			waitTimeSeconds: Number.parseInt(process.env.SQS_WAIT_TIME_SECONDS || "20", 10),
-		};
-
-		expect(config.region).toBe("eu-central-1");
-		expect(config.waitTimeSeconds).toBe(15);
-
-		process.env.AWS_REGION = originalRegion;
-		process.env.SQS_WAIT_TIME_SECONDS = originalWaitTime;
-	});
-});
-
-describe("AzureServiceBusAdapter", () => {
-	it("should create adapter with config from environment", () => {
-		const originalConnStr = process.env.AZURE_SERVICE_BUS_CONNECTION_STRING;
-		const testConnStr = "Endpoint=sb://test.servicebus.windows.net/;SharedAccessKeyName=test;SharedAccessKey=abc";
-		process.env.AZURE_SERVICE_BUS_CONNECTION_STRING = testConnStr;
-
-		const config = {
-			connectionString: process.env.AZURE_SERVICE_BUS_CONNECTION_STRING,
-		};
-
-		expect(config.connectionString).toBe(testConnStr);
-
-		process.env.AZURE_SERVICE_BUS_CONNECTION_STRING = originalConnStr;
-	});
-});
-
-describe("PubSubTriggerOpts Schema", () => {
-	it("should validate pub/sub trigger configuration", () => {
-		const validConfig = {
-			provider: "gcp" as const,
-			topic: "my-topic",
-			subscription: "my-subscription",
-			ack: true,
-			maxMessages: 10,
-			ackDeadline: 30,
-		};
-
-		expect(validConfig.provider).toBe("gcp");
-		expect(validConfig.topic).toBe("my-topic");
-		expect(validConfig.subscription).toBe("my-subscription");
-	});
-
-	it("should support all provider types", () => {
-		const providers = ["gcp", "aws", "azure"];
-
-		for (const provider of providers) {
-			const config = {
-				provider: provider as any,
-				topic: "test-topic",
-				subscription: "test-sub",
-			};
-			expect(config.provider).toBe(provider);
-		}
-	});
-});