# file: admin.aus

## class: KafkaAdmin

[34:14] (extern: com.lehman.aussom.KafkaAdmin) **extends: object** 

The Kafka Admin client: cluster management from Aussom code.
adm = new KafkaAdmin("broker1:9092");
adm.connect();
adm.createTopic("orders.created", 3);
Every method is synchronous: it blocks on the broker (bounded by
default.api.timeout.ms, settable with setConfig) and returns
native Aussom maps and lists. Shared shapes: topic-partition maps
{ "topic", "partition" }; offsets lists (those maps plus
"offset"); ACL binding maps { "resourceType", "name",
"patternType", "principal", "host", "operation",
"permissionType" }.

#### Methods

- **KafkaAdmin** (`string Bootstrap`)

	> Creates an admin client for a bootstrap address. Does not connect yet.

	- **@p** `Bootstrap` is a string with host:port[,host:port...].


- **newAdmin** (`string Bootstrap`)


- **setClientId** (`string Id`)

	> Sets the client id used in broker logs, metrics, and quotas.

	- **@p** `Id` is a string with the client id.
	- **@r** `this` object


- **setConfig** (`string Key, Value`)

	> Sets any admin config key directly (security, default.api.timeout.ms, and the rest). The ssl.*.location keys are rejected here - use the dedicated setters.

	- **@p** `Key` is a string with the config key.
	- **@p** `Value` is the config value.
	- **@r** `this` object


- **setConfigs** (`map Cfg`)

	> Applies a whole config map at once.

	- **@p** `Cfg` is a map of config key to value.
	- **@r** `this` object


- **setSslKeystoreFile** (`string Path`)

	> Sets the TLS keystore file. Under Aussom Server the path is resolved through the app_data sandbox.

	- **@p** `Path` is a string with the app-relative keystore path.
	- **@r** `this` object


- **setSslTruststoreFile** (`string Path`)

	> Sets the TLS truststore file. Under Aussom Server the path is resolved through the app_data sandbox.

	- **@p** `Path` is a string with the app-relative truststore path.
	- **@r** `this` object


- **connect** ()

	> Builds the admin client from the stored config.

	- **@r** `this` object


- **close** (`int TimeoutMs = -1`)

	> Closes the admin client. Idempotent.

	- **@p** `TimeoutMs` is an optional int bound on the close wait.
	- **@r** `this` object


- **isConnected** ()

	> Reports whether connect() has been called.

	- **@r** `A` bool with true when connected.


- **metrics** ()

	> Gets the client metrics.

	- **@r** `A` map of metric group.name to numeric value.


- **createTopic** (`string Name, int Partitions = 1, int Replication = 1, map Configs = null`)

	> Creates one topic.

	- **@p** `Name` is a string with the topic name.
	- **@p** `Partitions` is an optional int partition count (default 1).
	- **@p** `Replication` is an optional int replication factor (default 1).
	- **@p** `Configs` is an optional map of topic config overrides.
	- **@r** `this` object


- **createTopics** (`list Specs`)

	> Creates several topics at once.

	- **@p** `Specs` is a list of { "name", "partitions"?, "replication"?, "configs"? } maps.
	- **@r** `this` object


- **deleteTopics** (`list Names`)

	> Deletes topics by name.

	- **@p** `Names` is a list of topic name strings.
	- **@r** `this` object


- **listTopics** (`bool IncludeInternal = false`)

	> Lists topics.

	- **@p** `IncludeInternal` is an optional bool to include internal topics like __consumer_offsets.
	- **@r** `A` list of { "name", "topicId", "internal" } maps.


- **describeTopics** (`list Names`)

	> Describes topics by name.

	- **@p** `Names` is a list of topic name strings.
	- **@r** `A` list of { "name", "topicId", "internal", "partitions": [{ "partition", "leader", "replicas", "isr" }] } maps.


- **createPartitions** (`map TopicToCount`)

	> Grows topics to new total partition counts (never shrinks).

	- **@p** `TopicToCount` is a map of topic name to total count.
	- **@r** `this` object


- **deleteRecords** (`list Offsets`)

	> Deletes all records before the given offsets.

	- **@p** `Offsets` is an offsets list; each entry's offset is the first one to KEEP.
	- **@r** `A` list of { "topic", "partition", "lowWatermark" } maps.


- **describeConfigs** (`string Type, string Name`)

	> Describes the configs of one resource.

	- **@p** `Type` is a string: topic, broker, broker_logger, group, or client_metrics.
	- **@p** `Name` is a string with the resource name (a broker id for brokers).
	- **@r** `A` map of config name to { "value", "source", "readOnly", "sensitive" }.


- **alterConfigs** (`string Type, string Name, list Ops`)

	> Incrementally alters the configs of one resource.

	- **@p** `Type` is a string with the resource type (see describeConfigs).
	- **@p** `Name` is a string with the resource name.
	- **@p** `Ops` is a list of { "name", "value"?, "op"? } maps; op is set (default), delete, append, or subtract.
	- **@r** `this` object


- **listConfigResources** (`list Types = null`)

	> Lists config resources on the cluster, optionally filtered by type strings.

	- **@p** `Types` is an optional list of resource type strings.
	- **@r** `A` list of { "type", "name" } maps.


- **createAcls** (`list Bindings`)

	> Creates ACL bindings.

	- **@p** `Bindings` is a list of ACL binding maps; patternType defaults to literal, host to "*", permissionType to allow.
	- **@r** `this` object


- **describeAcls** (`map Filter`)

	> Describes ACL bindings matching a filter.

	- **@p** `Filter` is a map with any of the binding keys; missing keys match anything ({} matches all).
	- **@r** `A` list of ACL binding maps.


- **deleteAcls** (`list Filters`)

	> Deletes ACL bindings matching the filters.

	- **@p** `Filters` is a list of filter maps.
	- **@r** `A` list of the deleted ACL binding maps.


- **listGroups** (`list Types = null`)

	> Lists groups of every kind.

	- **@p** `Types` is an optional list of type strings to filter: consumer, classic, share, streams.
	- **@r** `A` list of { "groupId", "type", "state", "protocol" } maps.


- **describeConsumerGroups** (`list Ids`)

	> Describes consumer groups.

	- **@p** `Ids` is a list of group id strings.
	- **@r** `A` list of { "groupId", "state", "type", "partitionAssignor", "coordinator", "simple", "members" } maps; each member is { "memberId", "clientId", "host", "groupInstanceId", "assignment" }.


- **deleteConsumerGroups** (`list Ids`)

	> Deletes consumer groups (must be empty).

	- **@p** `Ids` is a list of group id strings.
	- **@r** `this` object


- **listConsumerGroupOffsets** (`string GroupId`)

	> Lists a consumer group's committed offsets.

	- **@p** `GroupId` is a string with the group id.
	- **@r** `An` offsets list.


- **alterConsumerGroupOffsets** (`string GroupId, list Offsets`)

	> Overwrites a consumer group's committed offsets. The group must have no active members.

	- **@p** `GroupId` is a string with the group id.
	- **@p** `Offsets` is an offsets list.
	- **@r** `this` object


- **deleteConsumerGroupOffsets** (`string GroupId, list TopicPartitions`)

	> Deletes a consumer group's committed offsets for partitions.

	- **@p** `GroupId` is a string with the group id.
	- **@p** `TopicPartitions` is a list of topic-partition maps.
	- **@r** `this` object


- **removeMembersFromConsumerGroup** (`string GroupId, list MemberIds = null`)

	> Removes members from a consumer group.

	- **@p** `GroupId` is a string with the group id.
	- **@p** `MemberIds` is an optional list of member ids; absent removes every member.
	- **@r** `this` object


- **describeClassicGroups** (`list Ids`)

	> Describes classic-protocol groups.

	- **@p** `Ids` is a list of group id strings.
	- **@r** `A` list of { "groupId", "state", "protocol", "coordinator", "memberCount" } maps.


- **describeShareGroups** (`list Ids`)

	> Describes share groups (broker 4.2+).

	- **@p** `Ids` is a list of group id strings.
	- **@r** `A` list of { "groupId", "state", "coordinator", "groupEpoch", "members" } maps.


- **deleteShareGroups** (`list Ids`)

	> Deletes share groups (must be empty).

	- **@p** `Ids` is a list of group id strings.
	- **@r** `this` object


- **listShareGroupOffsets** (`string GroupId`)

	> Lists a share group's start offsets.

	- **@p** `GroupId` is a string with the group id.
	- **@r** `A` list of { "topic", "partition", "startOffset" } maps.


- **alterShareGroupOffsets** (`string GroupId, list Offsets`)

	> Overwrites a share group's start offsets. The group must have no active members.

	- **@p** `GroupId` is a string with the group id.
	- **@p** `Offsets` is an offsets list.
	- **@r** `this` object


- **deleteShareGroupOffsets** (`string GroupId, list Topics`)

	> Deletes a share group's offsets for whole topics.

	- **@p** `GroupId` is a string with the group id.
	- **@p** `Topics` is a list of topic name strings.
	- **@r** `this` object


- **describeStreamsGroups** (`list Ids`)

	> Describes broker-side streams groups (KIP-1071).

	- **@p** `Ids` is a list of group id strings.
	- **@r** `A` list of { "groupId", "state", "coordinator", "groupEpoch", "memberCount" } maps.


- **deleteStreamsGroups** (`list Ids`)

	> Deletes streams groups (must be empty).

	- **@p** `Ids` is a list of group id strings.
	- **@r** `this` object


- **listStreamsGroupOffsets** (`string GroupId`)

	> Lists a streams group's committed offsets.

	- **@p** `GroupId` is a string with the group id.
	- **@r** `An` offsets list.


- **alterStreamsGroupOffsets** (`string GroupId, list Offsets`)

	> Overwrites a streams group's committed offsets. The group must have no active members.

	- **@p** `GroupId` is a string with the group id.
	- **@p** `Offsets` is an offsets list.
	- **@r** `this` object


- **deleteStreamsGroupOffsets** (`string GroupId, list TopicPartitions`)

	> Deletes a streams group's committed offsets for partitions.

	- **@p** `GroupId` is a string with the group id.
	- **@p** `TopicPartitions` is a list of topic-partition maps.
	- **@r** `this` object


- **listOffsets** (`list Query`)

	> Looks up partition offsets by spec.

	- **@p** `Query` is a list of { "topic", "partition", "spec" } maps; spec is earliest, latest, max_timestamp, or an int timestamp.
	- **@r** `A` list of { "topic", "partition", "offset", "timestamp" } maps.


- **describeCluster** ()

	> Describes the cluster.

	- **@r** `A` map { "clusterId", "controller", "nodes" }; nodes are { "id", "host", "port", "rack" } maps.


- **describeFeatures** ()

	> Describes the cluster's feature levels.

	- **@r** `A` map { "finalized": { name: { "minVersionLevel", "maxVersionLevel" } }, "supported": { name: { "minVersion", "maxVersion" } } }.


- **updateFeatures** (`map Updates`)

	> Updates finalized feature levels.

	- **@p** `Updates` is a map of feature name to { "maxVersionLevel", "upgradeType"? } (upgrade, safe_downgrade, unsafe_downgrade).
	- **@r** `this` object


- **describeMetadataQuorum** ()

	> Describes the KRaft metadata quorum.

	- **@r** `A` map { "leaderId", "leaderEpoch", "highWatermark", "voters", "observers" }.


- **unregisterBroker** (`int BrokerId`)

	> Unregisters a stopped broker from a KRaft cluster.

	- **@p** `BrokerId` is an int with the broker id.
	- **@r** `this` object


- **addRaftVoter** (`int VoterId, string DirectoryId, list Endpoints`)

	> Adds a KRaft controller voter.

	- **@p** `VoterId` is an int with the voter's node id.
	- **@p** `DirectoryId` is a string with the voter's directory uuid.
	- **@p** `Endpoints` is a list of { "name", "host", "port" } maps.
	- **@r** `this` object


- **removeRaftVoter** (`int VoterId, string DirectoryId`)

	> Removes a KRaft controller voter.

	- **@p** `VoterId` is an int with the voter's node id.
	- **@p** `DirectoryId` is a string with the voter's directory uuid.
	- **@r** `this` object


- **electLeaders** (`string Type, list TopicPartitions`)

	> Triggers partition leader election.

	- **@p** `Type` is a string: preferred or unclean.
	- **@p** `TopicPartitions` is a list of topic-partition maps.
	- **@r** `this` object


- **alterPartitionReassignments** (`list Reassignments`)

	> Starts or cancels partition reassignments.

	- **@p** `Reassignments` is a list of { "topic", "partition", "replicas": [brokerIds] or null to cancel } maps.
	- **@r** `this` object


- **listPartitionReassignments** (`list TopicPartitions = null`)

	> Lists in-progress partition reassignments.

	- **@p** `TopicPartitions` is an optional list of topic-partition maps to narrow the query.
	- **@r** `A` list of { "topic", "partition", "replicas", "addingReplicas", "removingReplicas" } maps.


- **describeLogDirs** (`list BrokerIds`)

	> Describes broker log directories.

	- **@p** `BrokerIds` is a list of int broker ids.
	- **@r** `A` map of broker id to { dir: { "error", "totalBytes", "usableBytes", "replicas" } }.


- **describeReplicaLogDirs** (`list Replicas`)

	> Describes where specific replicas live on disk.

	- **@p** `Replicas` is a list of { "broker", "topic", "partition" } maps.
	- **@r** `A` list of { "broker", "topic", "partition", "currentDir", "futureDir" } maps.


- **alterReplicaLogDirs** (`list Moves`)

	> Moves replicas between log directories on a broker.

	- **@p** `Moves` is a list of { "broker", "topic", "partition", "dir" } maps.
	- **@r** `this` object


- **describeClientQuotas** (`list Filter`)

	> Describes client quotas.

	- **@p** `Filter` is a list of { "entityType", "match" } maps; entityType is user, client-id, or ip; match is a name, null for the default quota, or "any". An empty list matches all.
	- **@r** `A` list of { "entity", "quotas" } maps.


- **alterClientQuotas** (`list Alterations`)

	> Alters client quotas.

	- **@p** `Alterations` is a list of { "entity": { entityType: name-or-null }, "set": { quota: value }, "remove": [quotaNames] } maps.
	- **@r** `this` object


- **describeUserScramCredentials** (`list Users = null`)

	> Describes SCRAM credentials.

	- **@p** `Users` is an optional list of user names (absent = all).
	- **@r** `A` list of { "user", "credentials": [{ "mechanism", "iterations" }] } maps.


- **alterUserScramCredentials** (`list Ops`)

	> Upserts or deletes SCRAM credentials.

	- **@p** `Ops` is a list of maps { "user", "mechanism" (SCRAM-SHA-256 / SCRAM-SHA-512), "password" + optional "iterations" to upsert, or "op": "delete" }.
	- **@r** `this` object


- **createDelegationToken** (`map Options = null`)

	> Creates a delegation token. Requires a SASL-authenticated connection and a broker with a token master key.

	- **@p** `Options` is an optional map { "owner", "renewers", "maxLifetimeMs" }; principals are "User:name" strings.
	- **@r** `A` map { "tokenId", "hmac", "owner", "issueTimestamp", "expiryTimestamp", "maxTimestamp", "renewers" }.


- **renewDelegationToken** (`string Hmac, int RenewTimePeriodMs = -1`)

	> Renews a delegation token.

	- **@p** `Hmac` is a string with the token's base64 HMAC.
	- **@p** `RenewTimePeriodMs` is an optional int renew period.
	- **@r** `An` int with the new expiry timestamp.


- **expireDelegationToken** (`string Hmac, ExpiryTimePeriodMs = null`)

	> Expires a delegation token (zero or negative period cancels it immediately).

	- **@p** `Hmac` is a string with the token's base64 HMAC.
	- **@p** `ExpiryTimePeriodMs` is an optional int expiry period (untyped so absent and negative stay distinct).
	- **@r** `An` int with the new expiry timestamp.


- **describeDelegationToken** (`list Owners = null`)

	> Describes delegation tokens.

	- **@p** `Owners` is an optional list of "User:name" owner principals.
	- **@r** `A` list of token maps (see createDelegationToken).


- **listTransactions** ()

	> Lists transactions known to the cluster.

	- **@r** `A` list of { "transactionalId", "producerId", "state" } maps.


- **describeTransactions** (`list Ids`)

	> Describes transactions.

	- **@p** `Ids` is a list of transactional id strings.
	- **@r** `A` list of { "transactionalId", "state", "producerId", "producerEpoch", "coordinatorId", "timeoutMs", "topicPartitions" } maps.


- **abortTransaction** (`map Spec`)

	> Forcefully aborts an open transaction by partition and producer details.

	- **@p** `Spec` is a map { "topic", "partition", "producerId", "producerEpoch", "coordinatorEpoch" }.
	- **@r** `this` object


- **forceTerminateTransaction** (`string TransactionalId`)

	> Forcefully terminates the open transaction of a transactional id.

	- **@p** `TransactionalId` is a string with the transactional id.
	- **@r** `this` object


- **fenceProducers** (`list TransactionalIds`)

	> Fences out the current producers of transactional ids.

	- **@p** `TransactionalIds` is a list of transactional id strings.
	- **@r** `this` object


- **describeProducers** (`list TopicPartitions`)

	> Describes the active idempotent/transactional producers of partitions.

	- **@p** `TopicPartitions` is a list of topic-partition maps.
	- **@r** `A` list of { "topic", "partition", "producers": [{ "producerId", "producerEpoch", "lastSequence", "lastTimestamp" }] } maps.


- **listClientMetricsResources** ()

	> Lists the client metrics subscription resources on the cluster (KIP-714).

	- **@r** `A` list of resource name strings.




