@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 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; the read credential must never
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`). An answer
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
- export interface CollectorClientOptions {
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
- async function readToken() {
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
- [READ_TOKEN_HEADER]: await readToken(),
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;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@policyengine/microcosm-collector-client",
3
- "version": "0.21.1",
3
+ "version": "0.22.0",
4
4
  "description": "Typed client for version 2 of the Microcosm collector's read API",
5
5
  "license": "MIT",
6
6
  "repository": {