CoordinatorMetadata

Kind: Interface

Source: packages/microservices/external/kafka.interface.ts

Part of: Microservices

CoordinatorMetadata represents the result of discovering a Kafka group coordinator. It includes an errorCode for the lookup operation and, when successful, the coordinator broker's node ID, host, and port for subsequent group-related requests.

Properties

Diagram

mermaid
graph LR
  Client[Kafka Client] --> Lookup[Find Group Coordinator]
  Lookup --> Metadata[CoordinatorMetadata]
  Metadata --> Error[errorCode: number]
  Metadata --> Coordinator[coordinator]
  Coordinator --> NodeId[nodeId: number]
  Coordinator --> Host[host: string]
  Coordinator --> Port[port: number]

Usage

ts
import type { CoordinatorMetadata } from './kafka.interface';

function getCoordinatorAddress(metadata: CoordinatorMetadata): string | undefined {
  if (metadata.errorCode !== 0) {
    console.error(`Coordinator lookup failed with code ${metadata.errorCode}`);
    return undefined;
  }

  const { host, port } = metadata.coordinator;
  return `${host}:${port}`;
}

const metadata: CoordinatorMetadata = {
  errorCode: 0,
  coordinator: {
    nodeId: 2,
    host: 'kafka-broker.internal',
    port: 9092,
  },
};

const coordinatorAddress = getCoordinatorAddress(metadata);
// "kafka-broker.internal:9092"

AI Coding Instructions

• Check errorCode before using coordinator; a non-zero code indicates the coordinator lookup did not succeed.
• Use coordinator.host and coordinator.port together when creating requests to the coordinator broker.
• Preserve the broker nodeId when caching or correlating coordinator connections.
• Treat coordinator information as refreshable metadata, since Kafka may rebalance or move a group coordinator between brokers.

How it works

CoordinatorMetadata is an exported TypeScript interface in the file’s KafkaJS type declarations, rather than an implementation with runtime logic. packages/microservices/external/kafka.interface.ts:1-8 packages/microservices/external/kafka.interface.ts:190-197

It describes metadata with two required fields:

• errorCode: a number. packages/microservices/external/kafka.interface.ts:190-192
• coordinator: a required object identifying a coordinator node through:
  • nodeId: number
  • host: string
  • port: number
    packages/microservices/external/kafka.interface.ts:192-197

Within this declaration file, Cluster.findGroupCoordinatorMetadata accepts an object containing a required groupId: string and returns Promise<CoordinatorMetadata>. packages/microservices/external/kafka.interface.ts:199-220

The interface declares no validation, error handling, or side effects. packages/microservices/external/kafka.interface.ts:190-197