Skip to content

Commit 566e7ce

Browse files
committed
docs: link API request option helpers
1 parent 8cf9830 commit 566e7ce

5 files changed

Lines changed: 63 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',

‎src/middleware.ts‎

Lines changed: 10 additions & 9 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) => {
@@ -38,10 +46,7 @@ export function requestTimeoutMiddleware(milliseconds: number): ObservableMiddle
3846
}
3947

4048
/** Returns call options that abort a request after the given number of milliseconds. */
41-
export function setRequestTimeoutOptions(
42-
milliseconds: number,
43-
opt?: ConfigurationOptions<ObservableMiddleware>,
44-
): ConfigurationOptions<ObservableMiddleware> {
49+
export function setRequestTimeoutOptions(milliseconds: number, opt?: ApiRequestOptions): ApiRequestOptions {
4550
const existingMiddleware = opt?.middleware || [];
4651
return {
4752
...opt,
@@ -51,11 +56,7 @@ export function setRequestTimeoutOptions(
5156
}
5257

5358
// Returns ConfigurationOptions that set a header
54-
export function setHeaderOptions(
55-
key: string,
56-
value: string,
57-
opt?: ConfigurationOptions<ObservableMiddleware>,
58-
): ConfigurationOptions<ObservableMiddleware> {
59+
export function setHeaderOptions(key: string, value: string, opt?: ApiRequestOptions): ApiRequestOptions {
5960
const newMiddlware = setHeaderMiddleware(key, value);
6061
const existingMiddlware = opt?.middleware || [];
6162
return {

0 commit comments

Comments
 (0)