Skip to content

Commit 72f3e49

Browse files
lp247lp247
authored
Implement client quota APIs (#139)
* Implement client quota APIs
1 parent 265c9fc commit 72f3e49

File tree

13 files changed

+1224
-99
lines changed

13 files changed

+1224
-99
lines changed

‎docs/admin.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,32 @@ Options:
9090
| -------- | ---------- | ----------------- |
9191
| groups | `string[]` | Groups to delete. |
9292

93+
### `describeClientQuotas(options[, callback])`
94+
95+
Gets detailed information about client quotas.
96+
97+
The return value is an object specifying quotas for the requested user/client combination.
98+
99+
Options:
100+
101+
| Property | Type | Description |
102+
| ---------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
103+
| components | `DescribeClientQuotasRequestComponent[]` | Array of components specifying the entity types and match criteria for which to describe client quotas. |
104+
| strict | `boolean` | Whether to use strict matching for components. Defaults to `false`. |
105+
106+
### `alterClientQuotas(options[, callback])`
107+
108+
Alters client quotas for specified entities.
109+
110+
The return value is a list of entities for which quotas have been changed.
111+
112+
Options:
113+
114+
| Property | Type | Description |
115+
| ------------ | --------------------------------- | ----------------------------------------------------------------------------------------- |
116+
| entries | `AlterClientQuotasRequestEntry[]` | Array of entries specifying the entities and quotas to change. |
117+
| validateOnly | `boolean` | Whether to only validate the request without applying changes. Defaults to `false`. |
118+
93119
### `close([callback])`
94120

95121
Closes the admin and all its connections.

‎docs/diagnostic.md‎

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -61,21 +61,22 @@ Each tracing channel publishes events with the following common properties:
6161

6262
## Published tracing channels
6363

64-
| Name | Target | Description |
65-
| ----------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
66-
| `plt:kafka:connections:connects` | `Connection` | Traces a connection attempt to a broker. |
67-
| `plt:kafka:connections:api` | `Connection` | Traces a low level API request. |
68-
| `plt:kafka:connections:pools:gets` | `ConnectionPool` | Traces a connection retrieval attempt from a connection pool. |
69-
| `plt:kafka:base:apis` | `Base` | Traces a `Base.listApis` request. |
70-
| `plt:kafka:base:metadata` | `Base` | Traces a `Base.metadata` request. |
71-
| `plt:kafka:admin:topics` | `Admin` | Traces a `Admin.createTopics` or `Admin.deleteTopics` request. |
72-
| `plt:kafka:admin:groups` | `Admin` | Traces a `Admin.listGroups`, `Admin.describeGroups` or `Admin.deleteGroups` request. |
73-
| `plt:kafka:producer:initIdempotent` | `Producer` | Traces a `Producer.initIdempotentProducer` request. |
74-
| `plt:kafka:producer:sends` | `Producer` | Traces a `Producer.send` request. |
75-
| `plt:kafka:consumer:group` | `Consumer` | Traces a `Consumer.findGroupCoordinator`, `Consumer.joinGroup` or `Consumer.leaveGroup` requests. |
76-
| `plt:kafka:consumer:heartbeat` | `Consumer` | Traces the `Consumer` heartbeat requests. |
77-
| `plt:kafka:consumer:receives` | `Consumer` | Traces processing of every message. |
78-
| `plt:kafka:consumer:fetches` | `Consumer` | Traces a `Consumer.fetch` request. |
79-
| `plt:kafka:consumer:consumes` | `Consumer` | Traces a `Consumer.consume` request. |
80-
| `plt:kafka:consumer:commits` | `Consumer` | Traces a `Consumer.commit` request. |
81-
| `plt:kafka:consumer:offsets` | `Consumer` | Traces a `Consumer.listOffsets` or `Consumer.listCommittedOffsets` request. |
64+
| Name | Target | Description |
65+
| ------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------- |
66+
| `plt:kafka:connections:connects` | `Connection` | Traces a connection attempt to a broker. |
67+
| `plt:kafka:connections:api` | `Connection` | Traces a low level API request. |
68+
| `plt:kafka:connections:pools:gets` | `ConnectionPool` | Traces a connection retrieval attempt from a connection pool. |
69+
| `plt:kafka:base:apis` | `Base` | Traces a `Base.listApis` request. |
70+
| `plt:kafka:base:metadata` | `Base` | Traces a `Base.metadata` request. |
71+
| `plt:kafka:admin:topics` | `Admin` | Traces a `Admin.createTopics` or `Admin.deleteTopics` request. |
72+
| `plt:kafka:admin:groups` | `Admin` | Traces a `Admin.listGroups`, `Admin.describeGroups` or `Admin.deleteGroups` request. |
73+
| `plt:kafka:admin:admin:clientQuotas` | `Admin` | Traces a `Admin.describeClientQuotas` or `Admin.alterClientQuotas` request. |
74+
| `plt:kafka:producer:initIdempotent` | `Producer` | Traces a `Producer.initIdempotentProducer` request. |
75+
| `plt:kafka:producer:sends` | `Producer` | Traces a `Producer.send` request. |
76+
| `plt:kafka:consumer:group` | `Consumer` | Traces a `Consumer.findGroupCoordinator`, `Consumer.joinGroup` or `Consumer.leaveGroup` requests. |
77+
| `plt:kafka:consumer:heartbeat` | `Consumer` | Traces the `Consumer` heartbeat requests. |
78+
| `plt:kafka:consumer:receives` | `Consumer` | Traces processing of every message. |
79+
| `plt:kafka:consumer:fetches` | `Consumer` | Traces a `Consumer.fetch` request. |
80+
| `plt:kafka:consumer:consumes` | `Consumer` | Traces a `Consumer.consume` request. |
81+
| `plt:kafka:consumer:commits` | `Consumer` | Traces a `Consumer.commit` request. |
82+
| `plt:kafka:consumer:offsets` | `Consumer` | Traces a `Consumer.listOffsets` or `Consumer.listCommittedOffsets` request. |

‎src/apis/admin/alter-client-quotas-v1.ts‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,26 @@ import { type NullableString } from '../../protocol/definitions.ts'
33
import { type Reader } from '../../protocol/reader.ts'
44
import { Writer } from '../../protocol/writer.ts'
55
import { createAPI, type ResponseErrorWithLocation } from '../definitions.ts'
6+
import { type ClientQuotaEntityType, type ClientQuotaKey } from '../enumerations.ts'
67

78
export interface AlterClientQuotasRequestEntity {
8-
entityType: string
9-
entityName: NullableString
9+
entityType: ClientQuotaEntityType
10+
entityName?: NullableString
1011
}
1112

12-
export interface AlterClientQuotasRequestOp {
13-
key: string
13+
export interface AlterClientQuotaRequestOpAddition {
14+
key: ClientQuotaKey
1415
value: number
15-
remove: boolean
16+
remove: false
1617
}
1718

19+
export interface AlterClientQuotaRequestOpRemoval {
20+
key: ClientQuotaKey
21+
remove: true
22+
}
23+
24+
export type AlterClientQuotasRequestOp = AlterClientQuotaRequestOpAddition | AlterClientQuotaRequestOpRemoval
25+
1826
export interface AlterClientQuotasRequestEntry {
1927
entities: AlterClientQuotasRequestEntity[]
2028
ops: AlterClientQuotasRequestOp[]
@@ -56,7 +64,9 @@ export function createRequest (entries: AlterClientQuotasRequestEntry[], validat
5664
w.appendArray(e.entities, (w, e) => {
5765
w.appendString(e.entityType).appendString(e.entityName)
5866
}).appendArray(e.ops, (w, o) => {
59-
w.appendString(o.key).appendFloat64(o.value).appendBoolean(o.remove)
67+
w.appendString(o.key)
68+
.appendFloat64((o as AlterClientQuotaRequestOpAddition).value ?? 0)
69+
.appendBoolean(o.remove)
6070
})
6171
})
6272
.appendBoolean(validateOnly)

‎src/apis/admin/describe-client-quotas-v0.ts‎

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,32 @@ import { type NullableString } from '../../protocol/definitions.ts'
33
import { type Reader } from '../../protocol/reader.ts'
44
import { Writer } from '../../protocol/writer.ts'
55
import { createAPI } from '../definitions.ts'
6+
import { type ClientQuotaEntityType, type ClientQuotaKey, type ClientQuotaMatchTypes } from '../enumerations.ts'
67

7-
export interface DescribeClientQuotasRequestComponent {
8-
entityType: string
9-
matchType: number
10-
match: string | null
8+
export interface DescribeClientQuotasRequestMatchComponent {
9+
entityType: ClientQuotaEntityType
10+
matchType: typeof ClientQuotaMatchTypes.EXACT
11+
match: string
1112
}
1213

14+
export interface DescribeClientQuotasRequestSpecialComponent {
15+
entityType: ClientQuotaEntityType
16+
matchType: typeof ClientQuotaMatchTypes.DEFAULT | typeof ClientQuotaMatchTypes.ANY
17+
}
18+
19+
export type DescribeClientQuotasRequestComponent =
20+
| DescribeClientQuotasRequestMatchComponent
21+
| DescribeClientQuotasRequestSpecialComponent
22+
1323
export type DescribeClientQuotasRequest = Parameters<typeof createRequest>
1424

1525
export interface DescribeClientQuotasResponseValue {
16-
key: string
26+
key: ClientQuotaKey
1727
value: number
1828
}
1929

2030
export interface DescribeClientQuotasResponseEntity {
21-
entityType: string
31+
entityType: ClientQuotaEntityType
2232
entityName: NullableString
2333
}
2434

@@ -45,6 +55,7 @@ export interface DescribeClientQuotasResponse {
4555
export function createRequest (components: DescribeClientQuotasRequestComponent[], strict: boolean): Writer {
4656
return Writer.create()
4757
.appendArray(components, (w, c) => {
58+
// @ts-ignore - TS complains that 'match' is not available in all variants of DescribeClientQuotasRequestComponent
4859
w.appendString(c.entityType).appendInt8(c.matchType).appendString(c.match)
4960
})
5061
.appendBoolean(strict)
@@ -77,11 +88,11 @@ export function parseResponse (
7788
entries: reader.readArray(r => {
7889
return {
7990
entity: r.readArray(r => {
80-
return { entityType: r.readString(), entityName: r.readNullableString() }
91+
return { entityType: r.readString() as ClientQuotaEntityType, entityName: r.readNullableString() }
8192
}),
8293
values: r.readArray(r => {
8394
return {
84-
key: r.readString(),
95+
key: r.readString() as ClientQuotaKey,
8596
value: r.readFloat64()
8697
}
8798
})

‎src/apis/enumerations.ts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,17 @@ export type IncrementalAlterConfigType = keyof typeof IncrementalAlterConfigType
9595

9696
// ./admin/*-client-quotas.ts
9797
export const ClientQuotaMatchTypes = { EXACT: 0, DEFAULT: 1, ANY: 2 } as const
98-
export type ClientQuotaMatchType = keyof typeof ClientQuotaMatchTypes
98+
export type ClientQuotaMatchType = (typeof ClientQuotaMatchTypes)[keyof typeof ClientQuotaMatchTypes]
99+
100+
export const ClientQuotaEntityTypes = { CLIENT_ID: 'client-id', USER: 'user' } as const
101+
export type ClientQuotaEntityType = (typeof ClientQuotaEntityTypes)[keyof typeof ClientQuotaEntityTypes]
102+
103+
export const ClientQuotaKeys = {
104+
PRODUCER_BYTE_RATE: 'producer_byte_rate',
105+
CONSUMER_BYTE_RATE: 'consumer_byte_rate',
106+
REQUEST_PERCENTAGE: 'request_percentage'
107+
} as const
108+
export type ClientQuotaKey = (typeof ClientQuotaKeys)[keyof typeof ClientQuotaKeys]
99109

100110
// ./admin/*-scram-credentials.ts
101111
export const ScramMechanisms = { UNKNOWN: 0, SCRAM_SHA_256: 1, SCRAM_SHA_512: 2 } as const

0 commit comments

Comments
 (0)