@policyengine/microcosm-collector-client 0.21.1 → 0.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -2
- package/dist/index.d.ts +27 -6
- package/dist/index.js +30 -10
- package/dist/schema.d.ts +22 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
A typed client for version 2 of the Microcosm collector's read API: the runs a
|
|
4
4
|
collector has recorded, and for each run its state together with the telemetry
|
|
5
|
-
events its build sent. It runs on the server;
|
|
5
|
+
events its build sent. It runs on the server; neither credential it sends may
|
|
6
6
|
reach a browser.
|
|
7
7
|
|
|
8
8
|
```ts
|
|
@@ -19,6 +19,28 @@ const detail = await collector.getRun(runs[0].run_id); // null if unknown
|
|
|
19
19
|
console.log(detail?.run.status, detail?.events.length);
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
+
On Vercel, a server function can send its deployment's Vercel OIDC token
|
|
23
|
+
instead, once the collector lists the deployment's project and environment
|
|
24
|
+
among its readers (`TELEMETRY_VERCEL_OIDC_READERS`):
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import { getVercelOidcToken } from "@vercel/oidc";
|
|
28
|
+
import { createCollectorClient } from "@policyengine/microcosm-collector-client";
|
|
29
|
+
|
|
30
|
+
const collector = createCollectorClient({
|
|
31
|
+
baseUrl: process.env.MICROCOSM_TELEMETRY_COLLECTOR_URL!,
|
|
32
|
+
// Called before each request, so each request carries the current token.
|
|
33
|
+
vercelOidcToken: () => getVercelOidcToken(),
|
|
34
|
+
});
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
A client takes exactly one of `readToken` and `vercelOidcToken`; both or
|
|
38
|
+
neither throws a `TypeError`. The read credential is sent in
|
|
39
|
+
`X-Telemetry-Read-Token`, the Vercel OIDC token as `Authorization: Bearer`. An
|
|
40
|
+
empty or blank credential throws before any request is sent. The token's
|
|
41
|
+
audience is the Vercel team, not the collector, so never log it or pass it to
|
|
42
|
+
another service. This package does not depend on `@vercel/oidc`.
|
|
43
|
+
|
|
22
44
|
- `listRuns({ country, limit, before })` returns one page, newest registration
|
|
23
45
|
first; pass a page's `next_before` as `before` for the next one.
|
|
24
46
|
- `listRecentRuns({ country, count })` reads pages until it has `count` runs or
|
|
@@ -29,7 +51,10 @@ console.log(detail?.run.status, detail?.events.length);
|
|
|
29
51
|
|
|
30
52
|
An error answer throws `CollectorRequestError`, with `status`, `detail`, and
|
|
31
53
|
`retryable` for 408, 429 and 5xx, including the 503 that a collector answers
|
|
32
|
-
with while it deploys (`retryAfterSeconds` holds its `Retry-After`)
|
|
54
|
+
with while it deploys (`retryAfterSeconds` holds its `Retry-After`) or while
|
|
55
|
+
it cannot read Vercel's signing keys (without `Retry-After`). A Vercel OIDC
|
|
56
|
+
token the collector refuses answers 401, or 403 when its project and
|
|
57
|
+
environment may not read that collector. An answer
|
|
33
58
|
that is not a read API v2 answer throws `CollectorResponseError`. A request
|
|
34
59
|
that takes longer than `timeoutMs` (30 seconds by default), including reading
|
|
35
60
|
its answer, rejects with `fetch`'s `TimeoutError`. Arguments the collector
|
package/dist/index.d.ts
CHANGED
|
@@ -25,14 +25,15 @@ export declare const DEFAULT_TIMEOUT_MS = 30000;
|
|
|
25
25
|
export declare const RUN_ID_PATTERN: RegExp;
|
|
26
26
|
/** A country code the collector accepts, such as "US" or "GB". */
|
|
27
27
|
export declare const COUNTRY_PATTERN: RegExp;
|
|
28
|
-
|
|
28
|
+
/**
|
|
29
|
+
* A credential, or a function that returns it. The function is called for
|
|
30
|
+
* every request, so the credential may rotate or expire between requests.
|
|
31
|
+
*/
|
|
32
|
+
export type CredentialSource = string | (() => string | Promise<string>);
|
|
33
|
+
/** Where and how the client sends its requests. */
|
|
34
|
+
export interface CollectorConnectionOptions {
|
|
29
35
|
/** The collector's address: HTTPS, or HTTP on localhost or 127.0.0.1. */
|
|
30
36
|
baseUrl: string;
|
|
31
|
-
/**
|
|
32
|
-
* The dashboard read credential, or a function that returns it. The
|
|
33
|
-
* function is called for every request, so the credential may rotate.
|
|
34
|
-
*/
|
|
35
|
-
readToken: string | (() => string | Promise<string>);
|
|
36
37
|
/** The `fetch` to send requests with; the global one by default. */
|
|
37
38
|
fetch?: typeof globalThis.fetch | undefined;
|
|
38
39
|
/**
|
|
@@ -41,6 +42,26 @@ export interface CollectorClientOptions {
|
|
|
41
42
|
*/
|
|
42
43
|
timeoutMs?: number | undefined;
|
|
43
44
|
}
|
|
45
|
+
/** A client that sends the dashboard read credential. */
|
|
46
|
+
export interface ReadTokenClientOptions extends CollectorConnectionOptions {
|
|
47
|
+
/** The dashboard read credential, sent in `X-Telemetry-Read-Token`. */
|
|
48
|
+
readToken: CredentialSource;
|
|
49
|
+
vercelOidcToken?: never;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* A client that sends a consumer app's Vercel OIDC token, which the collector
|
|
53
|
+
* accepts from the Vercel projects and environments it is configured for.
|
|
54
|
+
*/
|
|
55
|
+
export interface VercelOidcClientOptions extends CollectorConnectionOptions {
|
|
56
|
+
/**
|
|
57
|
+
* The Vercel OIDC token, sent as `Authorization: Bearer <token>`, such as
|
|
58
|
+
* `getVercelOidcToken` from `@vercel/oidc`.
|
|
59
|
+
*/
|
|
60
|
+
vercelOidcToken: CredentialSource;
|
|
61
|
+
readToken?: never;
|
|
62
|
+
}
|
|
63
|
+
/** Exactly one of `readToken` and `vercelOidcToken`. */
|
|
64
|
+
export type CollectorClientOptions = ReadTokenClientOptions | VercelOidcClientOptions;
|
|
44
65
|
export interface ListRunsQuery {
|
|
45
66
|
/** Only runs of this country: two capital letters, such as "US" or "GB". */
|
|
46
67
|
country?: string | undefined;
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
/** The request header that carries the dashboard read credential. */
|
|
2
2
|
export const READ_TOKEN_HEADER = "X-Telemetry-Read-Token";
|
|
3
|
+
// The request header that carries a Vercel OIDC token, as a bearer token.
|
|
4
|
+
const AUTHORIZATION_HEADER = "Authorization";
|
|
3
5
|
/** The largest page the collector answers; it refuses a larger `limit`. */
|
|
4
6
|
export const MAX_PAGE_SIZE = 200;
|
|
5
7
|
/** How long a request may take, from sending it to reading its whole answer. */
|
|
@@ -81,6 +83,31 @@ function isAbandoned(error) {
|
|
|
81
83
|
return (error instanceof Error &&
|
|
82
84
|
(error.name === "TimeoutError" || error.name === "AbortError"));
|
|
83
85
|
}
|
|
86
|
+
async function credentialValue(source, emptyMessage) {
|
|
87
|
+
const value = typeof source === "function" ? await source() : source;
|
|
88
|
+
if (typeof value !== "string" || !value.trim()) {
|
|
89
|
+
throw new Error(emptyMessage);
|
|
90
|
+
}
|
|
91
|
+
return value;
|
|
92
|
+
}
|
|
93
|
+
// Exactly one credential, checked as a JavaScript caller may pass the
|
|
94
|
+
// options: a key given as undefined is not given.
|
|
95
|
+
function credentialHeader(options) {
|
|
96
|
+
const { readToken, vercelOidcToken } = options;
|
|
97
|
+
if (readToken !== undefined && vercelOidcToken === undefined) {
|
|
98
|
+
return async () => {
|
|
99
|
+
const token = await credentialValue(readToken, "The collector read credential is empty.");
|
|
100
|
+
return [READ_TOKEN_HEADER, token];
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
if (vercelOidcToken !== undefined && readToken === undefined) {
|
|
104
|
+
return async () => {
|
|
105
|
+
const token = await credentialValue(vercelOidcToken, "The Vercel OIDC token is empty.");
|
|
106
|
+
return [AUTHORIZATION_HEADER, `Bearer ${token}`];
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
throw new TypeError("A collector client takes exactly one of readToken and vercelOidcToken.");
|
|
110
|
+
}
|
|
84
111
|
function retryAfterSeconds(response) {
|
|
85
112
|
const value = response.headers.get("Retry-After");
|
|
86
113
|
if (value === null || !/^\d+$/.test(value.trim()))
|
|
@@ -159,27 +186,20 @@ function checkRunDetail(value, runId) {
|
|
|
159
186
|
export function createCollectorClient(options) {
|
|
160
187
|
const baseUrl = collectorBaseUrl(options.baseUrl);
|
|
161
188
|
const timeoutMs = requestTimeout(options.timeoutMs);
|
|
162
|
-
|
|
163
|
-
const token = typeof options.readToken === "function"
|
|
164
|
-
? await options.readToken()
|
|
165
|
-
: options.readToken;
|
|
166
|
-
if (typeof token !== "string" || !token.trim()) {
|
|
167
|
-
throw new Error("The collector read credential is empty.");
|
|
168
|
-
}
|
|
169
|
-
return token;
|
|
170
|
-
}
|
|
189
|
+
const credential = credentialHeader(options);
|
|
171
190
|
// The parsed JSON body of a 200 answer, or `MISSING_RUN` for a run the
|
|
172
191
|
// collector has no record of.
|
|
173
192
|
async function getJson(pathAndQuery, { missingRunAllowed = false } = {}) {
|
|
174
193
|
// The global fetch is looked up for each request, so one that a test or
|
|
175
194
|
// framework installs after the client is created is used.
|
|
176
195
|
const fetchFunction = options.fetch ?? globalThis.fetch;
|
|
196
|
+
const [credentialName, credentialText] = await credential();
|
|
177
197
|
const response = await fetchFunction(`${baseUrl}${pathAndQuery}`, {
|
|
178
198
|
method: "GET",
|
|
179
199
|
cache: "no-store",
|
|
180
200
|
headers: {
|
|
181
201
|
Accept: "application/json",
|
|
182
|
-
[
|
|
202
|
+
[credentialName]: credentialText,
|
|
183
203
|
},
|
|
184
204
|
signal: AbortSignal.timeout(timeoutMs),
|
|
185
205
|
});
|
package/dist/schema.d.ts
CHANGED
|
@@ -525,7 +525,7 @@ export interface operations {
|
|
|
525
525
|
"application/json": components["schemas"]["RunPage"];
|
|
526
526
|
};
|
|
527
527
|
};
|
|
528
|
-
/** @description The read credential is missing or wrong. */
|
|
528
|
+
/** @description The read credential is missing or wrong, or the Vercel OIDC token is invalid, expired or not accepted by this collector. */
|
|
529
529
|
401: {
|
|
530
530
|
headers: {
|
|
531
531
|
[name: string]: unknown;
|
|
@@ -534,6 +534,15 @@ export interface operations {
|
|
|
534
534
|
"application/json": components["schemas"]["ErrorMessage"];
|
|
535
535
|
};
|
|
536
536
|
};
|
|
537
|
+
/** @description The Vercel OIDC token is valid, but its Vercel project and environment may not read this collector. */
|
|
538
|
+
403: {
|
|
539
|
+
headers: {
|
|
540
|
+
[name: string]: unknown;
|
|
541
|
+
};
|
|
542
|
+
content: {
|
|
543
|
+
"application/json": components["schemas"]["ErrorMessage"];
|
|
544
|
+
};
|
|
545
|
+
};
|
|
537
546
|
/** @description Validation Error */
|
|
538
547
|
422: {
|
|
539
548
|
headers: {
|
|
@@ -543,7 +552,7 @@ export interface operations {
|
|
|
543
552
|
"application/json": components["schemas"]["HTTPValidationError"];
|
|
544
553
|
};
|
|
545
554
|
};
|
|
546
|
-
/** @description A deployment is in progress; retry after the `Retry-After` header's seconds. */
|
|
555
|
+
/** @description A deployment is in progress; retry after the `Retry-After` header's seconds. Without `Retry-After`, Vercel's token signing keys could not be read to check a Vercel OIDC token. */
|
|
547
556
|
503: {
|
|
548
557
|
headers: {
|
|
549
558
|
[name: string]: unknown;
|
|
@@ -574,7 +583,7 @@ export interface operations {
|
|
|
574
583
|
"application/json": components["schemas"]["RunDetail"];
|
|
575
584
|
};
|
|
576
585
|
};
|
|
577
|
-
/** @description The read credential is missing or wrong. */
|
|
586
|
+
/** @description The read credential is missing or wrong, or the Vercel OIDC token is invalid, expired or not accepted by this collector. */
|
|
578
587
|
401: {
|
|
579
588
|
headers: {
|
|
580
589
|
[name: string]: unknown;
|
|
@@ -583,6 +592,15 @@ export interface operations {
|
|
|
583
592
|
"application/json": components["schemas"]["ErrorMessage"];
|
|
584
593
|
};
|
|
585
594
|
};
|
|
595
|
+
/** @description The Vercel OIDC token is valid, but its Vercel project and environment may not read this collector. */
|
|
596
|
+
403: {
|
|
597
|
+
headers: {
|
|
598
|
+
[name: string]: unknown;
|
|
599
|
+
};
|
|
600
|
+
content: {
|
|
601
|
+
"application/json": components["schemas"]["ErrorMessage"];
|
|
602
|
+
};
|
|
603
|
+
};
|
|
586
604
|
/** @description The run was not found. */
|
|
587
605
|
404: {
|
|
588
606
|
headers: {
|
|
@@ -601,7 +619,7 @@ export interface operations {
|
|
|
601
619
|
"application/json": components["schemas"]["HTTPValidationError"];
|
|
602
620
|
};
|
|
603
621
|
};
|
|
604
|
-
/** @description A deployment is in progress; retry after the `Retry-After` header's seconds. */
|
|
622
|
+
/** @description A deployment is in progress; retry after the `Retry-After` header's seconds. Without `Retry-After`, Vercel's token signing keys could not be read to check a Vercel OIDC token. */
|
|
605
623
|
503: {
|
|
606
624
|
headers: {
|
|
607
625
|
[name: string]: unknown;
|