@intellectual-frontiers/ergonex 0.3.4 → 0.3.6

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/dist/mod.js CHANGED
@@ -911,7 +911,7 @@ function toSarif(findings, tool = "ergonex") {
911
911
  }
912
912
 
913
913
  // src/state-record.ts
914
- var ERGONEX_VERSION = "0.3.4";
914
+ var ERGONEX_VERSION = "0.3.6";
915
915
  var STATE_RECORD_PATH = ".ergonex/state.auto.json";
916
916
  var EMPTY_RECORD = {
917
917
  ergonex: ERGONEX_VERSION,
@@ -2647,7 +2647,7 @@ function traceProcess(argv, run) {
2647
2647
  setProcessTracer(traceProcess);
2648
2648
  var UNTRACED = new WeakSet;
2649
2649
 
2650
- // ../ts/runtime/http-client.ts
2650
+ // ../net/src/http-client.ts
2651
2651
  var exchangeDecoder = object({
2652
2652
  method: literal("GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"),
2653
2653
  url: string,
@@ -14,7 +14,7 @@ import { type Sha256 } from "@intellectual-frontiers/crypto";
14
14
  import { type Finding } from "./findings.js";
15
15
  import { type GeneratedFile } from "./render.js";
16
16
  /** The version of Ergonex the record names. */
17
- export declare const ERGONEX_VERSION = "0.3.4";
17
+ export declare const ERGONEX_VERSION = "0.3.6";
18
18
  /** Where the state record is, below the root. */
19
19
  export declare const STATE_RECORD_PATH = ".ergonex/state.auto.json";
20
20
  /** One generated file as it was written. */
@@ -1,4 +1,4 @@
1
- import type { Transport } from "../runtime/http-client.js";
1
+ import type { Transport } from "@intellectual-frontiers/net/http-client";
2
2
  import type { GitHostClient } from "./types.js";
3
3
  /** How a GitHub client is made. */
4
4
  export type GithubOptions = {
@@ -1,4 +1,4 @@
1
- import type { Transport } from "../runtime/http-client.js";
1
+ import type { Transport } from "@intellectual-frontiers/net/http-client";
2
2
  import type { GitHostClient } from "./types.js";
3
3
  /** How a GitLab client is made. */
4
4
  export type GitlabOptions = {
@@ -1,4 +1,4 @@
1
- import { type Transport } from "../runtime/http-client.js";
1
+ import { type Transport } from "@intellectual-frontiers/net/http-client";
2
2
  import { type PlainGitOptions } from "./git.js";
3
3
  import type { GitHostClient, RepoRef } from "./types.js";
4
4
  export { CAPABILITIES, COMMON_CAPABILITIES, maxDepth, supports, unsupported } from "./capabilities.js";
package/ergonex.mjs CHANGED
@@ -3054,7 +3054,7 @@ function traceHttpClient(method, url, send, status) {
3054
3054
  }
3055
3055
  var UNTRACED = new WeakSet;
3056
3056
 
3057
- // ../ts/runtime/http-client.ts
3057
+ // ../net/src/http-client.ts
3058
3058
  var CREDENTIAL_HEADERS = [
3059
3059
  "authorization",
3060
3060
  "proxy-authorization",
@@ -3859,7 +3859,7 @@ function checkFiles(files, repositories) {
3859
3859
  }
3860
3860
 
3861
3861
  // src/state-record.ts
3862
- var ERGONEX_VERSION = "0.3.4";
3862
+ var ERGONEX_VERSION = "0.3.6";
3863
3863
  var STATE_RECORD_PATH = ".ergonex/state.auto.json";
3864
3864
  var EMPTY_RECORD = {
3865
3865
  ergonex: ERGONEX_VERSION,
@@ -8223,7 +8223,7 @@ var pathsModule = {
8223
8223
  commands: [paths]
8224
8224
  };
8225
8225
 
8226
- // ../ts/runtime/acme.ts
8226
+ // ../net/src/acme.ts
8227
8227
  var directoryDecoder = object({ newNonce: string, newAccount: string, newOrder: string });
8228
8228
  var accountDecoder = object({ status: string });
8229
8229
  var orderDecoder = object({ status: string, authorizations: array(string), finalize: string }, { certificate: string });
@@ -8235,170 +8235,7 @@ var cfError = object({ errors: array(object({ message: string })) });
8235
8235
  var cfZones = object({ result: array(object({ id: string, name: string })) });
8236
8236
  var cfRecord = object({ result: object({ id: string }) });
8237
8237
  var cfRecords = object({ result: array(object({ id: string, content: string })) });
8238
- // ../ts/kernel/grc.ts
8239
- var INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:[.,](\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/i;
8240
- var CANONICAL_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
8241
- function instantOf(text) {
8242
- const m = INSTANT.exec(text.trim());
8243
- if (m === null)
8244
- return;
8245
- const [y, mo, d, h, mi, s] = [m[1], m[2], m[3], m[4], m[5], m[6]].map((x) => Number(x ?? ""));
8246
- if (y === undefined || mo === undefined || d === undefined || h === undefined || mi === undefined || s === undefined)
8247
- return;
8248
- const ms = Number((m[7] ?? "").padEnd(3, "0").slice(0, 3));
8249
- if (mo < 1 || mo > 12 || d < 1 || d > daysInMonth(y, mo) || h > 23 || mi > 59 || s > 59)
8250
- return;
8251
- const zone = (m[8] ?? "Z").toUpperCase();
8252
- let offset = 0;
8253
- if (zone !== "Z") {
8254
- const oh = Number(zone.slice(1, 3));
8255
- const om = Number(zone.slice(4, 6));
8256
- if (oh > 23 || om > 59)
8257
- return;
8258
- offset = (zone.startsWith("-") ? -1 : 1) * (oh * 60 + om) * 60000;
8259
- }
8260
- const date = new Date(0);
8261
- date.setUTCFullYear(y, mo - 1, d);
8262
- date.setUTCHours(h, mi, s, ms);
8263
- return instantFromEpochMs(date.getTime() - offset);
8264
- }
8265
- function instantFromEpochMs(ms) {
8266
- if (!Number.isFinite(ms))
8267
- return;
8268
- const date = new Date(Math.trunc(ms));
8269
- if (Number.isNaN(date.getTime()))
8270
- return;
8271
- const text = date.toISOString();
8272
- return CANONICAL_INSTANT.test(text) ? text : undefined;
8273
- }
8274
- function daysInMonth(year, month) {
8275
- const leap = year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
8276
- return month === 2 ? leap ? 29 : 28 : [4, 6, 9, 11].includes(month) ? 30 : 31;
8277
- }
8278
- var DURATION = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:[.,]\d+)?)S)?)?$/;
8279
- function parseDuration(text) {
8280
- const m = DURATION.exec(text);
8281
- if (m === null || text === "P" || text.endsWith("T"))
8282
- return err({ kind: "duration", text });
8283
- const n = (i) => Number((m[i] ?? "0").replace(",", "."));
8284
- return ok({ text, years: n(1), months: n(2), weeks: n(3), days: n(4), hours: n(5), minutes: n(6), seconds: n(7) });
8285
- }
8286
- function duration(text) {
8287
- const r = parseDuration(text);
8288
- if (r.kind === "err")
8289
- throw new Error(`not an ISO 8601 duration: ${JSON.stringify(text)}`);
8290
- return r.value;
8291
- }
8292
- var ROLE = /^[a-z][a-z0-9]*(?:[-_./][a-z0-9]+)*$/;
8293
- function roleOf(text) {
8294
- return ROLE.test(text) ? text : undefined;
8295
- }
8296
- var SEVERITIES2 = ["info", "low", "medium", "high", "critical"];
8297
- var refined = (name, f) => {
8298
- return (input, path = "$") => {
8299
- if (typeof input === "string") {
8300
- const v = f(input);
8301
- if (v !== undefined)
8302
- return ok(v);
8303
- }
8304
- return err({
8305
- kind: "decode",
8306
- path,
8307
- expected: name,
8308
- found: typeof input === "string" ? `the string ${JSON.stringify(input).slice(0, 60)}` : typeof input
8309
- });
8310
- };
8311
- };
8312
- var instantDecoder = refined("an ISO 8601 date-time with a zone", instantOf);
8313
- var roleDecoder = refined("a role (lower-case words joined by - _ . or /)", roleOf);
8314
- var durationDecoder = refined("an ISO 8601 duration", (t) => {
8315
- const r = parseDuration(t);
8316
- return r.kind === "ok" ? r.value : undefined;
8317
- });
8318
- var severityDecoder = literal(...SEVERITIES2);
8319
- var waiverInput = mapDecoder(object({ id: string, control: string, subjects: array(string), reason: string, approvedBy: roleDecoder, grantedAt: instantDecoder }, { expiresAt: instantDecoder }), (w) => w);
8320
-
8321
- // ../ts/kernel/assess.ts
8322
- var impactDeclarationDecoder = object({ paths: array(string), controls: array(string) });
8323
- var RISK_LEVELS = ["very-low", "low", "moderate", "high", "very-high"];
8324
- var levelDecoder = literal(...RISK_LEVELS);
8325
- var riskDecoder = object({
8326
- id: string,
8327
- title: string,
8328
- likelihood: levelDecoder,
8329
- impact: levelDecoder,
8330
- treatment: literal("accept", "mitigate", "transfer", "avoid"),
8331
- owner: roleDecoder,
8332
- reviewBy: instantDecoder
8333
- }, { description: string, controls: array(string) });
8334
- // ../ts/runtime/grc.ts
8335
- var EXTENSIONS = new Map([
8336
- ["toml", "toml"],
8337
- ["yaml", "yaml"],
8338
- ["yml", "yaml"],
8339
- ["json", "json"],
8340
- ["json5", "json5"]
8341
- ]);
8342
- var GRC_SIGNALS = defineSignals({
8343
- "grc.pack": {
8344
- signal: "span",
8345
- role: "step",
8346
- description: "A pack run: its id, how many controls and subjects, and how many findings of each outcome.",
8347
- attributes: {
8348
- "grc.pack.id": "string",
8349
- "grc.pack.controls": "int",
8350
- "grc.pack.subjects": "int",
8351
- "grc.pack.findings?": "int",
8352
- "grc.outcome?": "string",
8353
- "grc.findings.not-applicable?": "int",
8354
- "grc.findings.pass?": "int",
8355
- "grc.findings.accepted?": "int",
8356
- "grc.findings.warn?": "int",
8357
- "grc.findings.gap?": "int",
8358
- "grc.findings.fail?": "int",
8359
- "grc.findings.error?": "int"
8360
- }
8361
- },
8362
- "grc.control": {
8363
- signal: "span",
8364
- role: "detail",
8365
- description: "One control's check of one subject: the join of its findings' statuses and of their outcomes, waivers applied.",
8366
- attributes: {
8367
- "grc.pack.id": "string",
8368
- "grc.control.id": "string",
8369
- "grc.subject.kind": "string",
8370
- "grc.subject.id": "string",
8371
- "grc.status?": "string",
8372
- "grc.outcome?": "string",
8373
- "grc.findings?": "int"
8374
- }
8375
- },
8376
- "grc.finding": {
8377
- signal: "log",
8378
- severity: SEVERITY.INFO,
8379
- role: "none",
8380
- description: "A finding; its body is the finding's OCSF Compliance Finding (class 2003), its severity the finding's.",
8381
- attributes: {
8382
- "grc.pack.id": "string",
8383
- "grc.control.id": "string",
8384
- "grc.subject.kind": "string",
8385
- "grc.subject.id": "string",
8386
- "grc.status": "string",
8387
- "grc.outcome": "string",
8388
- "grc.severity": "string",
8389
- "grc.waiver.id?": "string"
8390
- }
8391
- }
8392
- });
8393
- var FINDING_SEVERITY = {
8394
- info: SEVERITY.INFO,
8395
- low: SEVERITY.INFO,
8396
- medium: SEVERITY.WARN,
8397
- high: SEVERITY.ERROR,
8398
- critical: SEVERITY.FATAL
8399
- };
8400
- var telemetries = new WeakMap;
8401
- // ../ts/runtime/serve.ts
8238
+ // ../net/src/serve.ts
8402
8239
  var NO_BODY = new Set(["GET", "HEAD"]);
8403
8240
  // src/platform/r-http-client.ts
8404
8241
  var liveTransport2 = liveTransport;
@@ -10744,7 +10581,9 @@ var CONTROL2 = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(31)}
10744
10581
  var parseSpanId2 = parseSpanId;
10745
10582
  var parseTraceId2 = parseTraceId;
10746
10583
 
10747
- // ../ts/kernel/test-record.ts
10584
+ // ../test/src/record.ts
10585
+ var ROLE = /^[a-z][a-z0-9]*(?:[-_./][a-z0-9]+)*$/;
10586
+ var roleOf2 = (text) => ROLE.test(text) ? text : undefined;
10748
10587
  var OUTCOMES = ["pass", "fail", "skip", "todo", "cancelled"];
10749
10588
  function isOutcome(text) {
10750
10589
  return OUTCOMES.includes(text);
@@ -10787,7 +10626,7 @@ function installationFromEnv(self, env) {
10787
10626
  const given = get("IFC_TEST_ROLE");
10788
10627
  let role = fallback;
10789
10628
  if (given !== undefined) {
10790
- if (roleOf(given) === undefined)
10629
+ if (roleOf2(given) === undefined)
10791
10630
  warnings.push(`IFC_TEST_ROLE is not a role (lower-case words, never a person); ${fallback} is used`);
10792
10631
  else
10793
10632
  role = given;
@@ -11054,6 +10893,89 @@ var EVIDENCE_ROOT = "quality/evidence";
11054
10893
  var CASE_EVENT = "ifc.test.case";
11055
10894
  var RUN_GRADE = "E3";
11056
10895
  var NO_GRADE = "E0";
10896
+ // ../ts/kernel/grc.ts
10897
+ var INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:[.,](\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/i;
10898
+ var CANONICAL_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
10899
+ function instantOf(text) {
10900
+ const m = INSTANT.exec(text.trim());
10901
+ if (m === null)
10902
+ return;
10903
+ const [y, mo, d, h, mi, s] = [m[1], m[2], m[3], m[4], m[5], m[6]].map((x) => Number(x ?? ""));
10904
+ if (y === undefined || mo === undefined || d === undefined || h === undefined || mi === undefined || s === undefined)
10905
+ return;
10906
+ const ms = Number((m[7] ?? "").padEnd(3, "0").slice(0, 3));
10907
+ if (mo < 1 || mo > 12 || d < 1 || d > daysInMonth(y, mo) || h > 23 || mi > 59 || s > 59)
10908
+ return;
10909
+ const zone = (m[8] ?? "Z").toUpperCase();
10910
+ let offset = 0;
10911
+ if (zone !== "Z") {
10912
+ const oh = Number(zone.slice(1, 3));
10913
+ const om = Number(zone.slice(4, 6));
10914
+ if (oh > 23 || om > 59)
10915
+ return;
10916
+ offset = (zone.startsWith("-") ? -1 : 1) * (oh * 60 + om) * 60000;
10917
+ }
10918
+ const date = new Date(0);
10919
+ date.setUTCFullYear(y, mo - 1, d);
10920
+ date.setUTCHours(h, mi, s, ms);
10921
+ return instantFromEpochMs(date.getTime() - offset);
10922
+ }
10923
+ function instantFromEpochMs(ms) {
10924
+ if (!Number.isFinite(ms))
10925
+ return;
10926
+ const date = new Date(Math.trunc(ms));
10927
+ if (Number.isNaN(date.getTime()))
10928
+ return;
10929
+ const text = date.toISOString();
10930
+ return CANONICAL_INSTANT.test(text) ? text : undefined;
10931
+ }
10932
+ function daysInMonth(year, month) {
10933
+ const leap = year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
10934
+ return month === 2 ? leap ? 29 : 28 : [4, 6, 9, 11].includes(month) ? 30 : 31;
10935
+ }
10936
+ var DURATION = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:[.,]\d+)?)S)?)?$/;
10937
+ function parseDuration(text) {
10938
+ const m = DURATION.exec(text);
10939
+ if (m === null || text === "P" || text.endsWith("T"))
10940
+ return err({ kind: "duration", text });
10941
+ const n = (i) => Number((m[i] ?? "0").replace(",", "."));
10942
+ return ok({ text, years: n(1), months: n(2), weeks: n(3), days: n(4), hours: n(5), minutes: n(6), seconds: n(7) });
10943
+ }
10944
+ function duration(text) {
10945
+ const r = parseDuration(text);
10946
+ if (r.kind === "err")
10947
+ throw new Error(`not an ISO 8601 duration: ${JSON.stringify(text)}`);
10948
+ return r.value;
10949
+ }
10950
+ var ROLE2 = /^[a-z][a-z0-9]*(?:[-_./][a-z0-9]+)*$/;
10951
+ function roleOf3(text) {
10952
+ return ROLE2.test(text) ? text : undefined;
10953
+ }
10954
+ var SEVERITIES2 = ["info", "low", "medium", "high", "critical"];
10955
+ var refined = (name, f) => {
10956
+ return (input, path = "$") => {
10957
+ if (typeof input === "string") {
10958
+ const v = f(input);
10959
+ if (v !== undefined)
10960
+ return ok(v);
10961
+ }
10962
+ return err({
10963
+ kind: "decode",
10964
+ path,
10965
+ expected: name,
10966
+ found: typeof input === "string" ? `the string ${JSON.stringify(input).slice(0, 60)}` : typeof input
10967
+ });
10968
+ };
10969
+ };
10970
+ var instantDecoder = refined("an ISO 8601 date-time with a zone", instantOf);
10971
+ var roleDecoder = refined("a role (lower-case words joined by - _ . or /)", roleOf3);
10972
+ var durationDecoder = refined("an ISO 8601 duration", (t) => {
10973
+ const r = parseDuration(t);
10974
+ return r.kind === "ok" ? r.value : undefined;
10975
+ });
10976
+ var severityDecoder = literal(...SEVERITIES2);
10977
+ var waiverInput = mapDecoder(object({ id: string, control: string, subjects: array(string), reason: string, approvedBy: roleDecoder, grantedAt: instantDecoder }, { expiresAt: instantDecoder }), (w) => w);
10978
+
11057
10979
  // ../ts/kernel/evidence.ts
11058
10980
  var GENESIS = "0".repeat(64);
11059
10981
  var sha256Decoder = (input, path = "$") => {
@@ -11073,6 +10995,20 @@ var manifestDecoder2 = object({
11073
10995
  files: array(object({ path: string, size: refine(integer, "size", (n) => n >= 0), sha256: sha256Decoder }))
11074
10996
  });
11075
10997
 
10998
+ // ../ts/kernel/assess.ts
10999
+ var impactDeclarationDecoder = object({ paths: array(string), controls: array(string) });
11000
+ var RISK_LEVELS = ["very-low", "low", "moderate", "high", "very-high"];
11001
+ var levelDecoder = literal(...RISK_LEVELS);
11002
+ var riskDecoder = object({
11003
+ id: string,
11004
+ title: string,
11005
+ likelihood: levelDecoder,
11006
+ impact: levelDecoder,
11007
+ treatment: literal("accept", "mitigate", "transfer", "avoid"),
11008
+ owner: roleDecoder,
11009
+ reviewBy: instantDecoder
11010
+ }, { description: string, controls: array(string) });
11011
+
11076
11012
  // ../ts/kernel/oscal.ts
11077
11013
  var OPEN_OUTCOMES = new Set(["fail", "warn", "gap", "error", "accepted"]);
11078
11014
 
@@ -11206,7 +11142,7 @@ function requirementsOf2(tests, reviews, required) {
11206
11142
  };
11207
11143
  });
11208
11144
  }
11209
- function judge2(input) {
11145
+ function judge(input) {
11210
11146
  const failures = [];
11211
11147
  const counts = countsOf(input.tests);
11212
11148
  const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
@@ -11238,7 +11174,7 @@ function assembleRecord(input) {
11238
11174
  if (tests.kind === "err")
11239
11175
  return tests;
11240
11176
  const reviews = [...reviewsOf(closed), ...input.reviews ?? []];
11241
- const judgement = judge2({ tests: tests.value, runners: input.runners, required: input.required, reviews });
11177
+ const judgement = judge({ tests: tests.value, runners: input.runners, required: input.required, reviews });
11242
11178
  const resource = installationResource(input.runner);
11243
11179
  const runSpan = {
11244
11180
  name: RUN_SPAN,
@@ -12137,15 +12073,9 @@ function placesOf(env, os) {
12137
12073
  const shims = d.bin ?? rules.join(tools, "bin");
12138
12074
  return ok({ os, data: d.data, state: d.state, cache: d.cache, tools, shims });
12139
12075
  }
12140
- // ../ts/kernel/attest.ts
12141
- var PASSING = new Set(["pass"]);
12076
+
12142
12077
  // src/platform/k-test-record.ts
12143
- var TEST_SCOPE2 = TEST_SCOPE;
12144
12078
  var installationFromEnv2 = installationFromEnv;
12145
- var installationResource2 = installationResource;
12146
- var testCaseLog2 = testCaseLog;
12147
- var testCaseSpan2 = testCaseSpan;
12148
- var testId2 = testId;
12149
12079
 
12150
12080
  // src/setup/evidence.ts
12151
12081
  function optionNames(argv) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intellectual-frontiers/ergonex",
3
- "version": "0.3.4",
3
+ "version": "0.3.6",
4
4
  "description": "Ergonex, the workspaces management of Intellectual Frontiers: one command that sets up, configures and operates a team's software repositories, package registries and builds, on Windows, macOS and Linux, with Bun by default and Node 26 as the backup.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -19,10 +19,11 @@
19
19
  }
20
20
  },
21
21
  "dependencies": {
22
- "@intellectual-frontiers/core": "0.1.1",
23
- "@intellectual-frontiers/crypto": "0.1.1",
24
- "@intellectual-frontiers/formats": "0.1.1",
25
- "@intellectual-frontiers/terminal": "0.1.1"
22
+ "@intellectual-frontiers/core": "0.1.2",
23
+ "@intellectual-frontiers/crypto": "0.1.2",
24
+ "@intellectual-frontiers/formats": "0.1.2",
25
+ "@intellectual-frontiers/net": "0.1.1",
26
+ "@intellectual-frontiers/terminal": "0.1.2"
26
27
  },
27
28
  "files": [
28
29
  "dist",
@@ -1,149 +0,0 @@
1
- /**
2
- * How a typed client reaches a system over HTTP (commons 0005-typescript-runtime FR-040): a transport, live (`fetch`) or recorded (the
3
- * exchanges a test keeps, so it reaches no host), and over it the guards and helpers every client otherwise rewrites: a read-only guard
4
- * (safe methods only, POST to the token endpoints named, and the POSTs a predicate says only read, FR-066), AWS Signature Version 4 on each
5
- * request (FR-069), backoff on 429 and 503 that honours `Retry-After`, a JSON read decoded at the boundary with typed failures (a denied
6
- * call is told apart, so a caller can record a gap instead of failing), and every item of a list that pages by `Link: rel="next"` or by a
7
- * cursor in the body. A request that carries a credential is refused before it is sent unless the transport is made to allow it, so a
8
- * harness whose proxy injects credentials never sends one by mistake. Taken from erga's `lib/ts/http-client` and Stolos's connector SDK
9
- * (`src/archon/connect/sdk.ts`, `connector.ts`).
10
- *
11
- * @example
12
- * ```ts
13
- * import { array, object, string } from "@intellectual-frontiers/core";
14
- * import { getJson, liveTransport, withBackoff } from "./http-client.js";
15
- * const http = withBackoff(liveTransport());
16
- * const repo = await getJson(http, "https://api.github.com/repos/oven-sh/bun", object({ full_name: string }));
17
- * ```
18
- *
19
- * @module
20
- */
21
- import { type Decoder, type Result } from "@intellectual-frontiers/core";
22
- import { type AwsCredentials } from "@intellectual-frontiers/crypto/sigv4";
23
- /** A request a client makes. */
24
- export type OutRequest = {
25
- readonly method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
26
- readonly url: string;
27
- readonly headers: Readonly<Record<string, string>>;
28
- readonly body?: string;
29
- /** Read the answer as bytes (`Exchange.bytes`), for an artifact that is not text (a tarball, a zip); the text `body` of the answer is then empty. */
30
- readonly binary?: boolean;
31
- };
32
- /** One exchange: a request and what answered it. */
33
- export type Exchange = {
34
- readonly method: OutRequest["method"];
35
- readonly url: string;
36
- readonly status: number;
37
- /** The headers kept: the content type, paging, rate limits and `Retry-After`. */
38
- readonly headers: Readonly<Record<string, string>>;
39
- readonly body: string;
40
- /** The answer's bytes: present where the request asked for `binary` (a recorded exchange of an artifact holds them). */
41
- readonly bytes?: Uint8Array;
42
- };
43
- /** Why a request got no answer at all (a refusal before it was sent, or the network). */
44
- export type TransportError = {
45
- readonly kind: "refused";
46
- readonly message: string;
47
- } | {
48
- readonly kind: "network";
49
- readonly message: string;
50
- };
51
- /** A way to reach a system. */
52
- export type Transport = {
53
- readonly kind: "live" | "recorded";
54
- readonly send: (r: OutRequest) => Promise<Result<Exchange, TransportError>>;
55
- };
56
- /** The headers a credential travels in. */
57
- export declare const CREDENTIAL_HEADERS: readonly string[];
58
- /** Why a request may not be sent where credentials are refused: it carries one in a header or in its query. Undefined where it carries none. */
59
- export declare function carriesCredential(r: OutRequest): string | undefined;
60
- /** How the live transport sends. */
61
- export type LiveOptions = {
62
- /** The `fetch` to use (the platform's by default). */
63
- readonly fetch?: typeof fetch;
64
- /** Refuse a request that carries a credential (the default), or send it. */
65
- readonly credentials?: "refuse" | "allow";
66
- /** The `User-Agent` said to every system: a generic name, never a person's. */
67
- readonly userAgent?: string;
68
- /** No answer within this many seconds fails the request (30 by default). */
69
- readonly timeoutSeconds?: number;
70
- };
71
- /** The live transport, over `fetch`. */
72
- export declare function liveTransport(options?: LiveOptions): Transport;
73
- /** A transport that answers from recorded exchanges, by method and URL, and refuses a request it has none for, naming it. */
74
- export declare function recordedTransport(exchanges: readonly Exchange[]): Transport;
75
- /**
76
- * Whether a `POST` only reads (FR-066): a GraphQL query, a search, a JSON API's `Describe` and `Get` actions. It is given the whole
77
- * request (method, URL, headers and body), as an action may be named in a header (`x-amz-target`) or the body.
78
- */
79
- export type ReadPost = (r: OutRequest) => boolean;
80
- /**
81
- * A transport that sends only safe methods (GET, HEAD, ...), POST to URLs that start with one of `tokenEndpoints`, and the POSTs that
82
- * `readPost` says only read (FR-066). Every other request (PUT, PATCH, DELETE, any other POST) is refused without being sent.
83
- */
84
- export declare function readOnly(t: Transport, tokenEndpoints?: readonly string[], readPost?: ReadPost): Transport;
85
- /** How {@link withSigV4} signs. */
86
- export type SigV4TransportOptions = {
87
- readonly credentials: AwsCredentials;
88
- readonly region: string;
89
- readonly service: string;
90
- /** The clock read as each request is sent (`new Date()` by default; a test gives its own). */
91
- readonly now?: () => Date;
92
- /** Sign `UNSIGNED-PAYLOAD` instead of the body's hash (S3 allows it). */
93
- readonly unsignedPayload?: boolean;
94
- };
95
- /**
96
- * A transport that signs each request by AWS Signature Version 4 (FR-069, by the kernel's `sigv4`, FR-068) when it is sent. A signed
97
- * request carries a credential, so the live transport under it must be made with `credentials: "allow"`, or it refuses the request.
98
- */
99
- export declare function withSigV4(t: Transport, options: SigV4TransportOptions): Transport;
100
- /** How long to back off. */
101
- export type BackoffOptions = {
102
- /** Tries after the first (3 by default). */
103
- readonly retries?: number;
104
- /** How a wait is spent (a timer by default; a test passes one that returns at once). */
105
- readonly pause?: (ms: number) => Promise<void>;
106
- /** The longest wait, whatever `Retry-After` asks (60 s by default). */
107
- readonly capMs?: number;
108
- };
109
- /** A transport that waits and tries again on 429 and 503: as long as `Retry-After` asks (up to the cap), else 1, 2, 4 seconds. */
110
- export declare function withBackoff(t: Transport, options?: BackoffOptions): Transport;
111
- /** Why a JSON read failed. */
112
- export type ReadError = TransportError | {
113
- readonly kind: "denied";
114
- readonly status: 401 | 403;
115
- readonly url: string;
116
- } | {
117
- readonly kind: "status";
118
- readonly status: number;
119
- readonly url: string;
120
- } | {
121
- readonly kind: "decode";
122
- readonly url: string;
123
- readonly message: string;
124
- };
125
- /** A read error as one sentence; never a header or a body, so no credential or personal datum is said. */
126
- export declare function formatReadError(e: ReadError): string;
127
- /** A GET whose JSON body is decoded, with the exchange; 401 and 403 are `denied`, any other status from 400 up is `status`. */
128
- export declare function getExchange<T>(t: Transport, url: string, decoder: Decoder<T>, headers?: Readonly<Record<string, string>>): Promise<Result<{
129
- readonly value: T;
130
- readonly exchange: Exchange;
131
- }, ReadError>>;
132
- /** A GET whose JSON body is decoded. */
133
- export declare function getJson<T>(t: Transport, url: string, decoder: Decoder<T>, headers?: Readonly<Record<string, string>>): Promise<Result<T, ReadError>>;
134
- /** Every page of a list that pages by `Link: <...>; rel="next"`, at most `maxPages` (200 by default); the first failure ends it, as an error. */
135
- export declare function linkPages<T>(t: Transport, url: string, item: Decoder<T>, options?: {
136
- readonly headers?: Readonly<Record<string, string>>;
137
- readonly maxPages?: number;
138
- }): AsyncGenerator<T, Result<number, ReadError>>;
139
- /** Every item of a list that pages by a cursor in its body: `items` takes a page's items, `next` the next page's URL or undefined. */
140
- export declare function cursorPages<B, T>(t: Transport, first: string, page: Decoder<B>, items: (body: B) => readonly T[], next: (body: B, url: string) => string | undefined, options?: {
141
- readonly headers?: Readonly<Record<string, string>>;
142
- readonly maxPages?: number;
143
- }): AsyncGenerator<T, Result<number, ReadError>>;
144
- /** A recorded exchange read from the JSON5 text `recordedText` writes, or why it is not one. */
145
- export declare function decodeRecorded(text: string): Result<Exchange, string>;
146
- /** The text a recorded exchange is kept in: a comment that says where and when it was recorded, then the exchange as JSON5. */
147
- export declare function recordedText(x: Exchange, note: string): string;
148
- /** Headers that give a bearer token (for a transport made to allow credentials). */
149
- export declare function bearer(token: string, scheme?: string): Readonly<Record<string, string>>;