# CoordinatorMetadata

**Kind:** Interface

**Source:** [`packages/microservices/external/kafka.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/microservices/external/kafka.interface.ts#L190)

**Part of:** [Microservices](subsystem-packages-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

| Property | Type |
|---|---|
| `errorCode` | `number` |
| `coordinator` | `{ nodeId: number; host: string; port: number; }` |

## 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#L1-L8) [packages/microservices/external/kafka.interface.ts:190-197](packages/microservices/external/kafka.interface.ts#L190-L197)

It describes metadata with two required fields:

- `errorCode`: a `number`. [packages/microservices/external/kafka.interface.ts:190-192](packages/microservices/external/kafka.interface.ts#L190-L192)
- `coordinator`: a required object identifying a coordinator node through:
  - `nodeId`: `number`
  - `host`: `string`
  - `port`: `number`  
  [packages/microservices/external/kafka.interface.ts:192-197](packages/microservices/external/kafka.interface.ts#L192-L197)

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](packages/microservices/external/kafka.interface.ts#L199-L220)

The interface declares no validation, error handling, or side effects. [packages/microservices/external/kafka.interface.ts:190-197](packages/microservices/external/kafka.interface.ts#L190-L197)