/**
 * Create a new cluster mirror.
 *
 * @param mirrorName The name of the cluster mirror
 * @param configs Configuration for the cluster mirror, including bootstrap servers and security settings
 * @param options Options for the create mirror operation
 * @return The CreateMirrorResult
 */
CreateMirrorResult createMirror(String mirrorName, Map<String, String> configs, CreateMirrorOptions options);

/**
 * Add topics to an existing cluster mirror for cross-cluster replication.
 *
 * When topics are added to a mirror, they become read-only on the destination cluster and start
 * replicating data from the source cluster. This operation marks the specified topics with the
 * mirror name, preventing local writes and enabling the MirrorFetcherThread to begin replication.
 *
 * @param mirrorName The mirror name to add the topics to
 * @param topics Set of topic names to add to mirroring
 * @param options Options for the add topics to mirror operation
 * @return The AddTopicsToMirrorResult containing futures for each topic addition
 */
AddTopicsToMirrorResult addTopicsToMirror(String mirrorName, Set<String> topics, AddTopicsToMirrorOptions options);

/**
 * Remove topics from cluster mirror, making them writable on the destination cluster.
 *
 * This operation is typically used during failover scenarios when the destination cluster needs to
 * be promoted from passive (read-only mirror) to active (accepting writes). Removing topics from
 * the mirror clears the mirrorName field from partition metadata, which allows producers to write
 * to these partitions.
 *
 * @param mirrorName The mirror name to remove the topics from
 * @param topics Set of topic names to remove from mirroring
 * @param options Options for the remove topics from mirror operation
 * @return The RemoveTopicsFromMirrorResult containing futures for each topic removal
 */
RemoveTopicsFromMirrorResult removeTopicsFromMirror(String mirrorName, Set<String> topics, RemoveTopicsFromMirrorOptions options);

/**
 * Pause mirroring for the specified topics.
 *
 * Paused topics remain read-only on the destination cluster but stop fetching new data from the
 * source cluster. The mirror fetcher threads are removed for these partitions, preserving the
 * current replicated state. Mirroring can be resumed later with {@link #resumeMirrorTopics}.
 *
 * @param mirrorName The mirror name to pause the topics for
 * @param topics Set of topic names to pause mirroring for
 * @param options Options for the pause mirror topics operation
 * @return The PauseMirrorTopicsResult containing futures for each topic
 */
PauseMirrorTopicsResult pauseMirrorTopics(String mirrorName, Set<String> topics, PauseMirrorTopicsOptions options);

/**
 * Resume mirroring for previously paused topics.
 *
 * Resumed topics restart fetching data from the source cluster, picking up from where they
 * left off. New mirror fetcher threads are created and the partitions transition back to the
 * MIRRORING state.
 *
 * @param mirrorName The mirror name to resume the topics for
 * @param topics Set of topic names to resume mirroring for
 * @param options Options for the resume mirror topics operation
 * @return The ResumeMirrorTopicsResult containing futures for each topic
 */
ResumeMirrorTopicsResult resumeMirrorTopics(String mirrorName, Set<String> topics, ResumeMirrorTopicsOptions options);

/**
  * ListDelete thea cluster mirrorsmirror availableincluding inits the clusterconfiguration.
  *
  * @paramThe optionsmirror Themust optionsbe toempty use(no whentopics) listingor theall mirrors.
its *topics @returnmust Thehave ListMirrorsResult.
 */
ListMirrorsResult listMirrors(ListMirrorsOptions options);

/**
 * Describe cluster mirrors.
 *
 * This operation retrieves detailed information about cluster mirrors including:
 * - Topics being mirrored
 * - Partition-level lag information (source offset vs destination offset)
 * - Mirroring state for each partition (INITIALIZING, PREPARING, MIRRORING, etc.)
 *
 * @param mirrorNames The names of the mirrors to describebeen removed (in STOPPED
  * state). After deletion, all mirror metadata are tombstoned and failback is no longer possible.
  *
  * @param mirrorName The name of the cluster mirror to delete
  * @param options Options for the delete mirror operation
  * @return The DeleteMirrorResult
  */
DeleteMirrorResult deleteMirror(String mirrorName, DeleteMirrorOptions options);

/**
 * List the cluster mirrors available in the cluster.
 *
 * @param options The options to use when describinglisting the mirrors.
 * @return The DescribeMirrorsResultListMirrorsResult.
 */
DescribeMirrorsResultListMirrorsResult describeMirrors(Collection<String> mirrorNames, DescribeMirrorsOptions listMirrors(ListMirrorsOptions options);

/**
 * Describe cluster mirrors.
 *
 * This operation retrieves detailed information about cluster mirrors including:
 * - Topics being mirrored
 * - Partition-level lag information (source offset vs destination offset)
 * - Mirroring state for each partition (INITIALIZING, PREPARING, MIRRORING, etc.)
 *
 * @param mirrorNames The names of the mirrors to describe
 * @param options The options to use when describing mirrors
 * @return The DescribeMirrorsResult
 */
DescribeMirrorsResult describeMirrors(Collection<String> mirrorNames, DescribeMirrorsOptions options);

{
  "apiKey": TBD,
  "type": "request",
  "listeners": ["broker", "controller"]response",
  "name": "CreateMirrorRequestCreateMirrorResponse",
  "latestVersionUnstable": true,
  // Version 0 is the initial version.
  "validVersions": "0",
  "flexibleVersions": "0+",
  "fields": [
    { "name": "MirrorNameThrottleTimeMs", "type": "stringint32", "versions": "0+", "entityType": "mirrorName",
      "about": "The clusterduration in mirror name."},
    { "name": "Config", "type": "[]MirrorConfig", "versions": "0+",
      "about": "The cluster mirror configurations.",  "fields": [
      milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
    { "name": "NameErrorCode", "type": "stringint16", "versions": "0+", "mapKey": true,
        "about": "The configuration key name error code, or 0 if there was no error." },
      { "name": "ValueErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+",
        "about": "The error message, valueor tonull setif forthere thewas configurationno keyerror."}
    ]}
  ]
}

{
  "apiKey": TBD,
  "type": "request",
  "listeners": ["broker", "responsecontroller"],
  "name": "CreateMirrorResponseAddTopicsToMirrorRequest",
  // Version 0 is the initial version.
  "validVersions": "0",
  "flexibleVersions": "0+",
  "fields": [
    { "name": "MirrorName", "type": "string", "versions": "ThrottleTimeMs "0+", "entityType": "mirrorName",
      "about": "The cluster mirror name." },
    { "name": "Topics", "type": "int32[]TopicData", "versions": "0+",
      "about": "The duration in millisecondsdata for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
topics.",
      "fields": [
        { "name": "ErrorCodeTopicId", "type": "int16uuid", "versions": "0+",
      "about": "The errorunique code, or 0 if there was no errortopic ID." },
        { "name": "ErrorMessageTopicName", "type": "string", "versions": "0+", "nullableVersionsmapKey": "0+",
     true, "aboutentityType": "topicName"The,
  error message, or null if there was no error." }
  ]
}

"about": "The topic name." }
      ]}
  ]
}

{
  "apiKey": TBD,
  "type": "requestresponse",
  "listeners": ["broker", "controller"],
  "name": "AddTopicsToMirrorRequestAddTopicsToMirrorResponse",
  // Version 0 is the initial version.
  "validVersions": "0",
  "flexibleVersions": "0+",
  "fields": [
    { "name": "MirrorNameThrottleTimeMs", "type": "stringint32", "versions": "0+",
      "entityTypeabout": "mirrorName",
      "about": "The cluster mirror nameThe duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
      { "name": "TopicsErrorCode", "type": "[]TopicDataint16", "versions": "0+",
      "about": "The dataerror forcode, the topics.",
      "fields": [or 0 if there was no error." },
    { "name": "ErrorMessage",  {"type": "string", "nameversions": "TopicId0+", "typenullableVersions": "uuid0+", "versionsdefault": "0+null",
      "about": "The unique topic ID."},
     top-level error message, or null if there was no error." },
    { "name": "TopicNameMirrorName", "type": "string", "versions": "0+", "mapKey": true, "entityType": "topicNamemirrorName",
          "about": "The cluster topicmirror name." },
      ]}
  ]
}

{
  "apiKey": TBD,
  "type": "request",
  "listeners": ["broker", "controller"]response",
  "name": "RemoveTopicsFromMirrorRequestRemoveTopicsFromMirrorResponse",
  // Version 0 is the initial version.
  "validVersions": "0",
  "flexibleVersions": "0+",
  "fields": [
    { "name": "MirrorNameThrottleTimeMs", "type": "stringint32", "versions": "0+",
      "about": "The cluster mirror name duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
      { "name": "TopicsErrorCode", "type": "[]TopicDataint16", "versions": "0+",
      "about": "The dataerror forcode, the topics.",
      "fields": [
    or 0 if there was no error." },
    { "name": "TopicIdErrorMessage", "type": "uuidstring", "versions": "0+", "nullableVersions": "0+", "default": "null",
      "about": "The unique topic ID."},
     top-level error message, or null if there was no error." },
    { "name": "TopicNameMirrorName", "type": "string", "versions": "0+", "mapKey": true, "entityType": "topicNamemirrorName",
          "about": "The topic name." }
      ]}
  ]
}

{
  "apiKey": TBD,
  "type": "requestresponse",
  "name": "listeners"PauseMirrorTopicsResponse",
  // Version 0 is the initial version.
  "validVersions": ["broker0",
  "flexibleVersions": "controller0+"],
 ,
  "fields": [
    { "name": "PauseMirrorTopicsRequestThrottleTimeMs",
  // Version 0 is the initial version.
  "validVersions": "0",
  "flexibleVersions": "0+",
  "fields": ["type": "int32", "versions": "0+",
      "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
    { "name": "MirrorNameErrorCode", "type": "stringint16", "versions": "0+",
      "about": "The error code, mirroror name0 toif pausethere thewas topicsno forerror." },
      { "name": "TopicsErrorMessage", "type": "[]TopicDatastring", "versions": "0+", "aboutnullableVersions": "0+"The data for the topics., "default": "null",
      "fieldsabout": [
     "The top-level error message, or null if there was no error." },
    { "name": "TopicIdMirrorName", "type": "uuidstring", "versions": "0+", "entityType": "mirrorName",
      "about": "The uniquecluster topicmirror IDname." },
          { "name": "TopicNameTopics", "type": "string[]TopicResult", "versions": "0+", "mapKey": true, "entityType": "topicName",
          "about": "The topic name." }
 results for the topics.", "fields": [
     ]}
  ]
}