Skip to content

Commit 088cb13

Browse files
Merge pull request #3064 from davidgamero/timeout-middleware-milliseconds
Timeout middleware milliseconds
2 parents cb3bd67 + 7e11cba commit 088cb13

9 files changed

Lines changed: 195 additions & 9 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ kubernetes-client-node-*.tgz
1313
**/*.swp
1414
.idea/
1515
docs/*
16+
!docs/docs/
1617
.DS_Store
1718

1819
# Docusaurus

‎docs/docs/request-options.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
sidebar_position: 2
3+
title: Request Options
4+
---
5+
6+
# Request Options
7+
8+
Generated API methods accept
9+
[`ApiRequestOptions`](/sdk/middleware/type-aliases/ApiRequestOptions) as an optional
10+
second argument. Request options can replace, append, or prepend middleware for one API call without
11+
changing the client-wide configuration.
12+
13+
## Timeout
14+
15+
Use
16+
[`setRequestTimeoutOptions()`](/sdk/middleware/functions/setRequestTimeoutOptions)
17+
to apply an absolute deadline to one request:
18+
19+
```ts
20+
const pods = await api.listNamespacedPod({ namespace: 'default' }, setRequestTimeoutOptions(5_000));
21+
```
22+
23+
For client-wide configuration or custom composition, use
24+
[`requestTimeoutMiddleware()`](/sdk/middleware/functions/requestTimeoutMiddleware)
25+
directly. This timeout is an absolute request deadline, regardless of network activity; it is not an
26+
inactivity timeout.
27+
28+
## Headers
29+
30+
Use [`setHeaderOptions()`](/sdk/middleware/functions/setHeaderOptions) to set a header for one request:
31+
32+
```ts
33+
await api.patchNamespacedPod(
34+
{ name, namespace, body: patch },
35+
setHeaderOptions('Content-Type', PatchStrategy.JsonPatch),
36+
);
37+
```
38+
39+
Options helpers can be composed by passing existing options to the next helper:
40+
41+
```ts
42+
const options = setRequestTimeoutOptions(5_000, setHeaderOptions('Content-Type', PatchStrategy.JsonPatch));
43+
```

‎docs/scripts/transform-gen-docs.mjs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -429,6 +429,13 @@ function fixImports(content) {
429429
.replace(/from\s+\"\"/g, "from '@kubernetes/client-node'");
430430
}
431431

432+
function addRequestOptionsLinks(content) {
433+
return content.replace(
434+
/^(> .+\(\)\n)/gm,
435+
'$1\nGenerated API methods accept optional [request options](/request-options) as a second argument.\n',
436+
);
437+
}
438+
432439
const MODEL_GROUP_MAP = {
433440
core: /^V1(Pod|Service|Node|Namespace|ConfigMap|Secret|Endpoint|Event|Binding|Component|LimitRange|PersistentVolume|ReplicationController|ResourceQuota|PodTemplate|ServiceAccount|API)/,
434441
workloads:
@@ -952,6 +959,7 @@ export function transformMarkdown(content, { className, sidebarPosition, apiGrou
952959
transformed = normalizeHeadings(transformed);
953960
transformed = rewriteLinks(transformed, apiGroupMap, warnings);
954961
transformed = fixImports(transformed);
962+
transformed = addRequestOptionsLinks(transformed);
955963
transformed = truncateExamples(transformed);
956964
transformed = inlineMinimalBodies(transformed);
957965
transformed = stripBoilerplate(transformed);

‎docs/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ const sidebars: SidebarsConfig = {
1616
collapsed: false,
1717
items: [
1818
'intro',
19+
'request-options',
1920
{
2021
type: 'category',
2122
label: 'Examples',

‎examples/timeout-example.js‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
import * as k8s from '@kubernetes/client-node';
2+
3+
const kc = new k8s.KubeConfig();
4+
kc.loadFromDefault();
5+
6+
const k8sApi = kc.makeApiClient(k8s.CoreV1Api);
7+
8+
try {
9+
const pods = await k8sApi.listNamespacedPod(
10+
{ namespace: 'default' },
11+
k8s.setRequestTimeoutOptions(5_000),
12+
);
13+
console.log(`Found ${pods.items.length} pods.`);
14+
} catch (err) {
15+
if (err instanceof Error && err.name === 'TimeoutError') {
16+
console.error('The Kubernetes API request timed out.');
17+
} else {
18+
throw err;
19+
}
20+
}
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import { CoreV1Api, KubeConfig, setRequestTimeoutOptions } from '@kubernetes/client-node';
2+
3+
const kc = new KubeConfig();
4+
kc.loadFromDefault();
5+
6+
const k8sApi = kc.makeApiClient(CoreV1Api);
7+
8+
try {
9+
const pods = await k8sApi.listNamespacedPod({ namespace: 'default' }, setRequestTimeoutOptions(5_000));
10+
console.log(`Found ${pods.items.length} pods.`);
11+
} catch (err) {
12+
if (err instanceof Error && err.name === 'TimeoutError') {
13+
console.error('The Kubernetes API request timed out.');
14+
} else {
15+
throw err;
16+
}
17+
}

‎src/fullrequest_test.ts‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
import { afterEach, beforeEach, describe, it } from 'node:test';
2-
import { deepEqual } from 'node:assert';
2+
import { deepEqual, rejects } from 'node:assert';
33
import { MockAgent, setGlobalDispatcher, getGlobalDispatcher, type Dispatcher } from 'undici';
44

55
import { CoreV1Api } from './api.js';
66
import { KubeConfig } from './config.js';
77
import { Cluster, User } from './config_types.js';
8+
import { requestTimeoutMiddleware, setRequestTimeoutOptions } from './middleware.js';
89

910
describe('FullRequest', () => {
1011
describe('getPods', () => {
@@ -56,8 +57,33 @@ describe('FullRequest', () => {
5657
headers: { 'content-type': 'application/json' },
5758
});
5859

59-
const list = await k8sApi.listNamespacedPod({ namespace: 'default' });
60+
const list = await k8sApi.listNamespacedPod(
61+
{ namespace: 'default' },
62+
{
63+
middleware: [requestTimeoutMiddleware(60_000)],
64+
middlewareMergeStrategy: 'append',
65+
},
66+
);
6067
deepEqual(list, result);
6168
});
69+
70+
it('should abort a generated API request after the configured timeout', async () => {
71+
const kc = new KubeConfig();
72+
kc.loadFromClusterAndUser(
73+
{ name: 'foo', server: 'https://nowhere.foo' } as Cluster,
74+
{ name: 'my-user' } as User,
75+
);
76+
const k8sApi = kc.makeApiClient(CoreV1Api);
77+
78+
mockAgent
79+
.get('https://nowhere.foo')
80+
.intercept({ path: '/api/v1/namespaces/default/pods', method: 'GET' })
81+
.reply(200, { kind: 'PodList', apiVersion: 'v1', items: [] })
82+
.delay(100);
83+
84+
await rejects(k8sApi.listNamespacedPod({ namespace: 'default' }, setRequestTimeoutOptions(10)), {
85+
name: 'TimeoutError',
86+
});
87+
});
6288
});
6389
});

‎src/middleware.ts‎

Lines changed: 38 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,14 @@ import type {
66
} from './gen/index.js';
77
import { of } from './gen/rxjsStub.js';
88

9+
/**
10+
* Per-call options accepted as the optional second argument by generated API methods.
11+
*
12+
* Use {@link setHeaderOptions} and {@link setRequestTimeoutOptions} for common options, or add
13+
* middleware such as {@link requestTimeoutMiddleware} directly for custom composition.
14+
*/
15+
export type ApiRequestOptions = ConfigurationOptions<ObservableMiddleware>;
16+
917
export function setHeaderMiddleware(key: string, value: string): ObservableMiddleware {
1018
return {
1119
pre: (request: RequestContext) => {
@@ -18,12 +26,37 @@ export function setHeaderMiddleware(key: string, value: string): ObservableMiddl
1826
};
1927
}
2028

29+
/**
30+
* Aborts a request after the given number of milliseconds, regardless of request activity.
31+
*
32+
* Uses Node.js's native AbortSignal.timeout(), whose timer does not keep the process running and
33+
* can be reclaimed after the signal is no longer referenced. Streaming response bodies must be
34+
* consumed or canceled so the HTTP client can release its abort listeners.
35+
*/
36+
export function requestTimeoutMiddleware(milliseconds: number): ObservableMiddleware {
37+
return {
38+
pre: (request: RequestContext) => {
39+
request.setSignal(AbortSignal.timeout(milliseconds));
40+
return of(request);
41+
},
42+
post: (response: ResponseContext) => {
43+
return of(response);
44+
},
45+
};
46+
}
47+
48+
/** Returns call options that abort a request after the given number of milliseconds. */
49+
export function setRequestTimeoutOptions(milliseconds: number, opt?: ApiRequestOptions): ApiRequestOptions {
50+
const existingMiddleware = opt?.middleware || [];
51+
return {
52+
...opt,
53+
middleware: existingMiddleware.concat(requestTimeoutMiddleware(milliseconds)),
54+
middlewareMergeStrategy: 'append',
55+
};
56+
}
57+
2158
// Returns ConfigurationOptions that set a header
22-
export function setHeaderOptions(
23-
key: string,
24-
value: string,
25-
opt?: ConfigurationOptions<ObservableMiddleware>,
26-
): ConfigurationOptions<ObservableMiddleware> {
59+
export function setHeaderOptions(key: string, value: string, opt?: ApiRequestOptions): ApiRequestOptions {
2760
const newMiddlware = setHeaderMiddleware(key, value);
2861
const existingMiddlware = opt?.middleware || [];
2962
return {

‎src/middleware_test.ts‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
11
import { describe, it } from 'node:test';
22
import { RequestContext, ConfigurationOptions, HttpMethod, ObservableMiddleware } from './gen/index.js';
3-
import { deepStrictEqual } from 'node:assert';
4-
import { setHeaderMiddleware, setHeaderOptions } from './middleware.js';
3+
import { deepStrictEqual, strictEqual } from 'node:assert';
4+
import { once } from 'node:events';
5+
import { setTimeout } from 'node:timers/promises';
6+
import {
7+
requestTimeoutMiddleware,
8+
setHeaderMiddleware,
9+
setHeaderOptions,
10+
setRequestTimeoutOptions,
11+
} from './middleware.js';
512

613
describe('Middleware', async () => {
714
describe('setHeaderMiddleware', async () => {
@@ -47,4 +54,34 @@ describe('Middleware', async () => {
4754
deepStrictEqual(postMiddlewareRequest.getHeaders(), { 'test-key': 'test-value' });
4855
});
4956
});
57+
58+
describe('requestTimeoutMiddleware', () => {
59+
it('should set a timeout signal on the request', async () => {
60+
const reqContext = new RequestContext('http://nowhere.com', HttpMethod.GET);
61+
const timeoutMiddleware = requestTimeoutMiddleware(10);
62+
63+
const postMiddlewareRequest = await timeoutMiddleware.pre(reqContext).toPromise();
64+
const signal = postMiddlewareRequest.getSignal();
65+
66+
strictEqual(signal?.aborted, false);
67+
await Promise.race([once(signal!, 'abort'), setTimeout(100)]);
68+
strictEqual(signal?.aborted, true);
69+
strictEqual(signal?.reason.name, 'TimeoutError');
70+
});
71+
});
72+
73+
describe('setRequestTimeoutOptions', () => {
74+
it('should append timeout middleware to existing call options', async () => {
75+
const existingMiddleware = setHeaderMiddleware('test-key', 'test-value');
76+
const options = setRequestTimeoutOptions(10, { middleware: [existingMiddleware] });
77+
78+
strictEqual(options.middlewareMergeStrategy, 'append');
79+
strictEqual(options.middleware?.[0], existingMiddleware);
80+
strictEqual(options.middleware?.length, 2);
81+
82+
const reqContext = new RequestContext('http://nowhere.com', HttpMethod.GET);
83+
const postMiddlewareRequest = await options.middleware?.[1].pre(reqContext).toPromise();
84+
strictEqual(postMiddlewareRequest?.getSignal()?.aborted, false);
85+
});
86+
});
5087
});

0 commit comments

Comments
 (0)