KafkaJSStaleTopicMetadataAssignmentMetadata

Kind: Interface

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

Part of: Microservices

KafkaJSStaleTopicMetadataAssignmentMetadata describes stale Kafka topic metadata detected during partition assignment. It identifies the affected topic and lists partitions whose metadata is unknown or outdated, allowing the microservice transport layer to refresh topic metadata before retrying assignment or consumption operations.

Properties

Diagram

mermaid
graph LR
  A[KafkaJSStaleTopicMetadataAssignmentMetadata] --> B[topic: string]
  A --> C[unknownPartitions: PartitionMetadata[]]
  C --> D[Partition 0 metadata]
  C --> E[Partition 1 metadata]
  C --> F[Additional unknown partitions]

Usage

ts
import type {
  KafkaJSStaleTopicMetadataAssignmentMetadata,
  PartitionMetadata,
} from './kafka.interface';

const staleMetadata: KafkaJSStaleTopicMetadataAssignmentMetadata = {
  topic: 'orders.created',
  unknownPartitions: [
    {
      partitionId: 2,
      leader: -1,
      replicas: [],
      isr: [],
    } as PartitionMetadata,
  ],
};

async function refreshStaleTopicMetadata(
  metadata: KafkaJSStaleTopicMetadataAssignmentMetadata,
) {
  console.warn(
    `Refreshing metadata for ${metadata.topic}; ` +
      `unknown partitions: ${metadata.unknownPartitions.map(
        ({ partitionId }) => partitionId,
      ).join(', ')}`,
  );

  // Refresh Kafka client/admin metadata before retrying assignment.
}

AI Coding Instructions

• Populate topic with the exact Kafka topic name used by the producer or consumer configuration.
• Include only partitions with missing, unknown, or stale metadata in unknownPartitions.
• Treat this interface as diagnostic and retry metadata refresh or assignment after handling it.
• Preserve the PartitionMetadata structure returned by KafkaJS; avoid creating partial partition objects unless explicitly supported.
• Handle empty unknownPartitions safely when logging or deciding whether a metadata refresh is required.