@storyshelf/core 0.7.0 → 0.9.0-next-d2cc082

package/dist/test-helpers.d.mts

@@ -15,4 +15,5 @@ import { ManualClock, createManualClock } from "./test-helpers/manual-clock.mjs"
 import { runnerContractSuite } from "./test-helpers/runner-contract.mjs";
 import { storageContractSuite } from "./test-helpers/storage-contract.mjs";
 import { FakeStateNotifier, makeFakeStateNotifier } from "./test-helpers/fake-notifier.mjs";
-export { type Deferred, type DesignContractSamples, FAKE_PNG, type FakeDesign, type FakeStateNotifier, type FakeStorage, type Latch, type ManualClock, type MultiInstanceOptions, type PollableContractOptions, type QueueContractOptions, type QueueFactory, REQUIRED_TABLES, type ReleaseQueue, type SharedDatabaseFactory, createLatch, createManualClock, createReleaseQueue, createTestBuild, createTestProject, databaseContractSuite, databaseQueueMultiInstanceSuite, deferred, designContractSuite, fakeUrl, makeDatabase, makeFakeDesign, makeFakeStateNotifier, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, stateNotifierContractSuite, storageContractSuite, stubTables };
+import { BuildReferenceContractFixture, BuildReferenceContractFixtureRunner, buildReferenceContractSuite } from "./test-helpers/build-reference-contract.mjs";
+export { type BuildReferenceContractFixture, type BuildReferenceContractFixtureRunner, type Deferred, type DesignContractSamples, FAKE_PNG, type FakeDesign, type FakeStateNotifier, type FakeStorage, type Latch, type ManualClock, type MultiInstanceOptions, type PollableContractOptions, type QueueContractOptions, type QueueFactory, REQUIRED_TABLES, type ReleaseQueue, type SharedDatabaseFactory, buildReferenceContractSuite, createLatch, createManualClock, createReleaseQueue, createTestBuild, createTestProject, databaseContractSuite, databaseQueueMultiInstanceSuite, deferred, designContractSuite, fakeUrl, makeDatabase, makeFakeDesign, makeFakeStateNotifier, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, stateNotifierContractSuite, storageContractSuite, stubTables };

package/dist/test-helpers.mjs

@@ -16,4 +16,5 @@ import { createManualClock } from "./test-helpers/manual-clock.mjs";
 import { runnerContractSuite } from "./test-helpers/runner-contract.mjs";
 import { storageContractSuite } from "./test-helpers/storage-contract.mjs";
 import { makeFakeStateNotifier } from "./test-helpers/fake-notifier.mjs";
-export { FAKE_PNG, REQUIRED_TABLES, createLatch, createManualClock, createReleaseQueue, createTestBuild, createTestProject, databaseContractSuite, databaseQueueMultiInstanceSuite, deferred, designContractSuite, fakeUrl, makeDatabase, makeFakeDesign, makeFakeStateNotifier, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, stateNotifierContractSuite, storageContractSuite, stubTables };
+import { buildReferenceContractSuite } from "./test-helpers/build-reference-contract.mjs";
+export { FAKE_PNG, REQUIRED_TABLES, buildReferenceContractSuite, createLatch, createManualClock, createReleaseQueue, createTestBuild, createTestProject, databaseContractSuite, databaseQueueMultiInstanceSuite, deferred, designContractSuite, fakeUrl, makeDatabase, makeFakeDesign, makeFakeStateNotifier, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, stateNotifierContractSuite, storageContractSuite, stubTables };

package/dist/tracing.mjs

@@ -1,8 +1,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { redactSecrets } from "./utils/redact.mjs";
 import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
-//#region src/tracing.ts
+// src/tracing.ts
 /**
 * Internal span and propagation helpers over `@opentelemetry/api`.
 *
@@ -15,11 +16,41 @@ import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentele
 const SCOPE = "storyshelf.core";
 /** W3C traceparent header name. */
 const TRACEPARENT_HEADER = "traceparent";
+/** What a span records of an error instead of its message, set by the code that knows the error. */
+const spanMessages = /* @__PURE__ */ new WeakMap();
+/**
+* State what spans record as the message of `error`, instead of its own: an outbound HTTP failure
+* is recorded as its status, never the response body it carries. The error itself is not touched,
+* so what a caller catches is unchanged.
+*/
+function setSpanMessage(error, message) {
+	if (typeof error === "object" && error !== null) spanMessages.set(error, message);
+}
+/**
+* The form of a failure that may be recorded on a span: a new error of the same name whose message
+* (the one given to {@link setSpanMessage}, else the error's own) has gone through
+* `redactSecrets`, with the original's stack frames. Never the original, whose message, stack
+* header or `cause` can repeat a URL, a token or a response body. A thrown non-error is stringified
+* and redacted. This is the one way core records an exception on a span.
+*/
+function spanException(error) {
+	if (!(error instanceof Error)) return redactSecrets(String(error));
+	const message = redactSecrets(spanMessages.get(error) ?? error.message);
+	const copy = new Error(message);
+	copy.name = error.name;
+	copy.stack = `${error.name}: ${message}${redactSecrets(framesOf(error))}`;
+	return copy;
+}
+/** The stack after its `Name: message` header, which may hold what the span must not record. */
+function framesOf(error) {
+	const header = `${error.name}: ${error.message}`;
+	return error.stack?.startsWith(header) ? error.stack.slice(header.length) : "";
+}
 /**
 * Run `fn` inside an internal span.
 *
-* On throw the span records the exception, is marked ERROR, and the error
-* is rethrown — mirroring the pino `{ err }` convention.
+* On throw the span records a redacted copy of the exception ({@link spanException}), is marked
+* ERROR, and the original error is rethrown untouched — mirroring the pino `{ err }` convention.
 *
 * @param name - Span name (`domain.operation`, never a high-cardinality value).
 * @param fn - Work to run with the span active.
@@ -35,7 +66,7 @@ async function withSpan(name, fn, attributes, parent) {
 		try {
 			return await fn(span);
 		} catch (error) {
-			span.recordException(error instanceof Error ? error : String(error));
+			span.recordException(spanException(error));
 			span.setStatus({ code: SpanStatusCode.ERROR });
 			throw error;
 		} finally {
@@ -57,7 +88,6 @@ function parentContext(traceparent) {
 function injectTraceContext(headers) {
 	propagation.inject(context.active(), headers);
 }
-//#endregion
-export { injectTraceContext, parentContext, withSpan };
+export { injectTraceContext, parentContext, setSpanMessage, spanException, withSpan };
 
 //# sourceMappingURL=tracing.mjs.map

package/dist/tracing.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.mjs","names":[],"sources":["../src/tracing.ts"],"sourcesContent":["/**\n * Internal span and propagation helpers over `@opentelemetry/api`.\n *\n * Not exported from the package surface (see `package.json` exports): other\n * packages use `@storyshelf/observability`. Without a configured provider\n * every helper is a cheap noop, so call sites need no enabled-checks and\n * the hermetic vitest suite stays network-free.\n */\nimport {\n  SpanKind,\n  SpanStatusCode,\n  context,\n  propagation,\n  trace,\n  type Attributes,\n  type Context,\n  type Span,\n} from \"@opentelemetry/api\";\n\n/** Instrumentation scope for core spans. */\nconst SCOPE = \"storyshelf.core\";\n\n/** W3C traceparent header name. */\nconst TRACEPARENT_HEADER = \"traceparent\";\n\n/**\n * Run `fn` inside an internal span.\n *\n * On throw the span records the exception, is marked ERROR, and the error\n * is rethrown — mirroring the pino `{ err }` convention.\n *\n * @param name - Span name (`domain.operation`, never a high-cardinality value).\n * @param fn - Work to run with the span active.\n * @param attributes - Fixed span attributes.\n * @param parent - Parent context (defaults to the active context).\n * @returns Whatever `fn` returns.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T>,\n  attributes?: Attributes,\n  parent?: Context,\n): Promise<T> {\n  const tracer = trace.getTracer(SCOPE);\n  return await tracer.startActiveSpan(\n    name,\n    { kind: SpanKind.INTERNAL, attributes },\n    parent ?? context.active(),\n    async (span) => {\n      try {\n        return await fn(span);\n      } catch (error) {\n        span.recordException(error instanceof Error ? error : String(error));\n        span.setStatus({ code: SpanStatusCode.ERROR });\n        throw error;\n      } finally {\n        span.end();\n      }\n    },\n  );\n}\n\n/**\n * Resolve the parent context from an inbound `traceparent` value.\n *\n * @param traceparent - W3C value from a queue payload; absent keeps context.\n * @returns The extracted remote context, or the active context when absent.\n */\nexport function parentContext(traceparent?: string): Context {\n  if (!traceparent) {\n    return context.active();\n  }\n  return propagation.extract(context.active(), { [TRACEPARENT_HEADER]: traceparent });\n}\n\n/** Inject the active span context into a mutable header record. */\nexport function injectTraceContext(headers: Record<string, string>): void {\n  propagation.inject(context.active(), headers);\n}\n\n/**\n * Read the current W3C `traceparent` value for queue payloads.\n *\n * @returns The header value, or undefined when no span is active.\n */\nexport function currentTraceparent(): string | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  return carrier[TRACEPARENT_HEADER];\n}\n"],"mappings":";;;;;;;;;;;;;;AAoBA,MAAM,QAAQ;;AAGd,MAAM,qBAAqB;;;;;;;;;;;;;AAc3B,eAAsB,SACpB,MACA,IACA,YACA,QACY;CAEZ,OAAO,MADQ,MAAM,UAAU,KACb,CAAC,CAAC,gBAClB,MACA;EAAE,MAAM,SAAS;EAAU;CAAW,GACtC,UAAU,QAAQ,OAAO,GACzB,OAAO,SAAS;EACd,IAAI;GACF,OAAO,MAAM,GAAG,IAAI;EACtB,SAAS,OAAO;GACd,KAAK,gBAAgB,iBAAiB,QAAQ,QAAQ,OAAO,KAAK,CAAC;GACnE,KAAK,UAAU,EAAE,MAAM,eAAe,MAAM,CAAC;GAC7C,MAAM;EACR,UAAU;GACR,KAAK,IAAI;EACX;CACF,CACF;AACF;;;;;;;AAQA,SAAgB,cAAc,aAA+B;CAC3D,IAAI,CAAC,aACH,OAAO,QAAQ,OAAO;CAExB,OAAO,YAAY,QAAQ,QAAQ,OAAO,GAAG,GAAG,qBAAqB,YAAY,CAAC;AACpF;;AAGA,SAAgB,mBAAmB,SAAuC;CACxE,YAAY,OAAO,QAAQ,OAAO,GAAG,OAAO;AAC9C"}
+{"version":3,"file":"tracing.mjs","names":[],"sources":["../src/tracing.ts"],"sourcesContent":["/**\n * Internal span and propagation helpers over `@opentelemetry/api`.\n *\n * Not exported from the package surface (see `package.json` exports): other\n * packages use `@storyshelf/observability`. Without a configured provider\n * every helper is a cheap noop, so call sites need no enabled-checks and\n * the hermetic vitest suite stays network-free.\n */\nimport {\n  SpanKind,\n  SpanStatusCode,\n  context,\n  propagation,\n  trace,\n  type Attributes,\n  type Context,\n  type Span,\n} from \"@opentelemetry/api\";\nimport { redactSecrets } from \"./utils/redact.ts\";\n\n/** Instrumentation scope for core spans. */\nconst SCOPE = \"storyshelf.core\";\n\n/** W3C traceparent header name. */\nconst TRACEPARENT_HEADER = \"traceparent\";\n\n/** What a span records of an error instead of its message, set by the code that knows the error. */\nconst spanMessages = new WeakMap<object, string>();\n\n/**\n * State what spans record as the message of `error`, instead of its own: an outbound HTTP failure\n * is recorded as its status, never the response body it carries. The error itself is not touched,\n * so what a caller catches is unchanged.\n */\nexport function setSpanMessage(error: unknown, message: string): void {\n  if (typeof error === \"object\" && error !== null) {\n    spanMessages.set(error, message);\n  }\n}\n\n/**\n * The form of a failure that may be recorded on a span: a new error of the same name whose message\n * (the one given to {@link setSpanMessage}, else the error's own) has gone through\n * `redactSecrets`, with the original's stack frames. Never the original, whose message, stack\n * header or `cause` can repeat a URL, a token or a response body. A thrown non-error is stringified\n * and redacted. This is the one way core records an exception on a span.\n */\nexport function spanException(error: unknown): Error | string {\n  if (!(error instanceof Error)) {\n    return redactSecrets(String(error));\n  }\n  const message = redactSecrets(spanMessages.get(error) ?? error.message);\n  const copy = new Error(message);\n  copy.name = error.name;\n  copy.stack = `${error.name}: ${message}${redactSecrets(framesOf(error))}`;\n  return copy;\n}\n\n/** The stack after its `Name: message` header, which may hold what the span must not record. */\nfunction framesOf(error: Error): string {\n  const header = `${error.name}: ${error.message}`;\n  return error.stack?.startsWith(header) ? error.stack.slice(header.length) : \"\";\n}\n\n/**\n * Run `fn` inside an internal span.\n *\n * On throw the span records a redacted copy of the exception ({@link spanException}), is marked\n * ERROR, and the original error is rethrown untouched — mirroring the pino `{ err }` convention.\n *\n * @param name - Span name (`domain.operation`, never a high-cardinality value).\n * @param fn - Work to run with the span active.\n * @param attributes - Fixed span attributes.\n * @param parent - Parent context (defaults to the active context).\n * @returns Whatever `fn` returns.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T>,\n  attributes?: Attributes,\n  parent?: Context,\n): Promise<T> {\n  const tracer = trace.getTracer(SCOPE);\n  return await tracer.startActiveSpan(\n    name,\n    { kind: SpanKind.INTERNAL, attributes },\n    parent ?? context.active(),\n    async (span) => {\n      try {\n        return await fn(span);\n      } catch (error) {\n        span.recordException(spanException(error));\n        span.setStatus({ code: SpanStatusCode.ERROR });\n        throw error;\n      } finally {\n        span.end();\n      }\n    },\n  );\n}\n\n/**\n * Resolve the parent context from an inbound `traceparent` value.\n *\n * @param traceparent - W3C value from a queue payload; absent keeps context.\n * @returns The extracted remote context, or the active context when absent.\n */\nexport function parentContext(traceparent?: string): Context {\n  if (!traceparent) {\n    return context.active();\n  }\n  return propagation.extract(context.active(), { [TRACEPARENT_HEADER]: traceparent });\n}\n\n/** Inject the active span context into a mutable header record. */\nexport function injectTraceContext(headers: Record<string, string>): void {\n  propagation.inject(context.active(), headers);\n}\n\n/**\n * Read the current W3C `traceparent` value for queue payloads.\n *\n * @returns The header value, or undefined when no span is active.\n */\nexport function currentTraceparent(): string | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  return carrier[TRACEPARENT_HEADER];\n}\n"],"mappings":";;;;;;;;;;;;;;;AAqBA,MAAM,QAAQ;;AAGd,MAAM,qBAAqB;;AAG3B,MAAM,+BAAe,IAAI,QAAwB;;;;;;AAOjD,SAAgB,eAAe,OAAgB,SAAuB;CACpE,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,aAAa,IAAI,OAAO,OAAO;AAEnC;;;;;;;;AASA,SAAgB,cAAc,OAAgC;CAC5D,IAAI,EAAE,iBAAiB,QACrB,OAAO,cAAc,OAAO,KAAK,CAAC;CAEpC,MAAM,UAAU,cAAc,aAAa,IAAI,KAAK,KAAK,MAAM,OAAO;CACtE,MAAM,OAAO,IAAI,MAAM,OAAO;CAC9B,KAAK,OAAO,MAAM;CAClB,KAAK,QAAQ,GAAG,MAAM,KAAK,IAAI,UAAU,cAAc,SAAS,KAAK,CAAC;CACtE,OAAO;AACT;;AAGA,SAAS,SAAS,OAAsB;CACtC,MAAM,SAAS,GAAG,MAAM,KAAK,IAAI,MAAM;CACvC,OAAO,MAAM,OAAO,WAAW,MAAM,IAAI,MAAM,MAAM,MAAM,OAAO,MAAM,IAAI;AAC9E;;;;;;;;;;;;;AAcA,eAAsB,SACpB,MACA,IACA,YACA,QACY;CAEZ,OAAO,MADQ,MAAM,UAAU,KACb,CAAC,CAAC,gBAClB,MACA;EAAE,MAAM,SAAS;EAAU;CAAW,GACtC,UAAU,QAAQ,OAAO,GACzB,OAAO,SAAS;EACd,IAAI;GACF,OAAO,MAAM,GAAG,IAAI;EACtB,SAAS,OAAO;GACd,KAAK,gBAAgB,cAAc,KAAK,CAAC;GACzC,KAAK,UAAU,EAAE,MAAM,eAAe,MAAM,CAAC;GAC7C,MAAM;EACR,UAAU;GACR,KAAK,IAAI;EACX;CACF,CACF;AACF;;;;;;;AAQA,SAAgB,cAAc,aAA+B;CAC3D,IAAI,CAAC,aACH,OAAO,QAAQ,OAAO;CAExB,OAAO,YAAY,QAAQ,QAAQ,OAAO,GAAG,GAAG,qBAAqB,YAAY,CAAC;AACpF;;AAGA,SAAgB,mBAAmB,SAAuC;CACxE,YAAY,OAAO,QAAQ,OAAO,GAAG,OAAO;AAC9C"}

package/dist/types.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/types.d.ts
 /** All lifecycle statuses a build can carry. */
 declare const BUILD_STATUSES: readonly ["pending", "capturing", "comparing", "reviewing", "approved", "rejected", "failed", "cancelled"];
 /** Lifecycle status of a build. */
@@ -69,6 +68,5 @@ declare const RESERVED_LABEL_KEYS: readonly ["build"];
  * Attach `persistent=true` to keep a build indefinitely, even after its TTL expires.
  */
 declare const PERSISTENT_LABEL_KEY = "persistent";
-//#endregion
 export { AuthUser, BUILD_STATUSES, BuildStatus, CANCELLABLE_BUILD_STATUSES, PERSISTENT_LABEL_KEY, PROJECT_ROLES, ProjectRole, RESERVED_LABEL_KEYS, REVIEW_VERDICTS, ReviewVerdict, SEEDED_LABEL_KEYS, SESSION_COOKIE, SITE_ROLES, SNAPSHOT_STATUSES, SiteRole, SnapshotStatus, TERMINAL_BUILD_STATUSES, isProjectRole };
 //# sourceMappingURL=types.d.mts.map

package/dist/types.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/types.ts
+// src/types.ts
 /** All lifecycle statuses a build can carry. */
 const BUILD_STATUSES = [
 	"pending",
@@ -81,7 +81,6 @@ const RESERVED_LABEL_KEYS = ["build"];
 * Attach `persistent=true` to keep a build indefinitely, even after its TTL expires.
 */
 const PERSISTENT_LABEL_KEY = "persistent";
-//#endregion
 export { BUILD_STATUSES, CANCELLABLE_BUILD_STATUSES, PERSISTENT_LABEL_KEY, PROJECT_ROLES, RESERVED_LABEL_KEYS, REVIEW_VERDICTS, SEEDED_LABEL_KEYS, SESSION_COOKIE, SITE_ROLES, SNAPSHOT_STATUSES, TERMINAL_BUILD_STATUSES, isProjectRole };
 
 //# sourceMappingURL=types.mjs.map

package/dist/urls.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/urls.d.ts
 /** Type-safe URL builder for project pages and published Storybooks. */
 interface UrlBuilder {
   projectsList(): string;
@@ -37,6 +36,5 @@ declare function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string)
  * app-relative paths only, so `javascript:`/`data:` payloads fall back.
  */
 declare function safeImageUrl(value: string | undefined): string | null;
-//#endregion
 export { UrlBuilder, createUrlBuilder, safeImageUrl };
 //# sourceMappingURL=urls.d.mts.map

package/dist/urls.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/urls.ts
+// src/urls.ts
 /**
 * Create a URL builder rooted at the given base URL.
 *
@@ -52,7 +52,6 @@ function safeImageUrl(value) {
 function encodePath(value) {
 	return value.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 }
-//#endregion
 export { createUrlBuilder, safeImageUrl };
 
 //# sourceMappingURL=urls.mjs.map

package/dist/utils/adaptive-concurrency.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Logger } from "../logger.mjs";
-//#region src/utils/adaptive-concurrency.d.ts
 /** Tuning for {@link AdaptiveConcurrency}. */
 interface AdaptiveOptions {
   /** Starting in-flight limit. */
@@ -61,6 +60,5 @@ declare class AdaptiveConcurrency {
 }
 /** Whether an error is a navigation/action timeout (Playwright and Puppeteer both name it `TimeoutError`). */
 declare function isTimeoutError(error: unknown): boolean;
-//#endregion
 export { AdaptiveConcurrency, AdaptiveOptions, Observation, isTimeoutError };
 //# sourceMappingURL=adaptive-concurrency.d.mts.map

package/dist/utils/adaptive-concurrency.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { monitorEventLoopDelay } from "node:perf_hooks";
-//#region src/utils/adaptive-concurrency.ts
+// src/utils/adaptive-concurrency.ts
 /** Adaptive page concurrency: raise while capture stays healthy, back off when it does not. */
 const MIN_WINDOW = 8;
 /**
@@ -143,7 +143,6 @@ function eventLoopLagReader() {
 		}
 	};
 }
-//#endregion
 export { AdaptiveConcurrency, isTimeoutError };
 
 //# sourceMappingURL=adaptive-concurrency.mjs.map

package/dist/utils/connect-retry.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/connect-retry.d.ts
 /** Retrying a connection to a remote browser service (ADR 0007, decision 4). */
 /** Options of {@link retryConnect}. */
 interface RetryConnectOptions {
@@ -8,6 +7,8 @@ interface RetryConnectOptions {
   retries: number;
   /** Delay before the first retry in ms; doubles each time, with jitter, capped at 10 s. */
   backoffMs: number;
+  /** Whether an error is worth another attempt; defaults to {@link isRetryableConnectError}. */
+  retryable?: (error: unknown) => boolean;
   /** Called before each retry with the error, the retry's number (from 1) and its delay. */
   onRetry?: (error: unknown, retry: number, delayMs: number) => void;
   /** Injectable for tests. */
@@ -21,6 +22,5 @@ declare function isRetryableConnectError(error: unknown): boolean;
  * while rendering. The last error is thrown once the retries are spent.
  */
 declare function retryConnect<T>(connect: () => Promise<T>, options: RetryConnectOptions): Promise<T>;
-//#endregion
 export { RetryConnectOptions, isRetryableConnectError, retryConnect };
 //# sourceMappingURL=connect-retry.d.mts.map

package/dist/utils/connect-retry.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/utils/connect-retry.ts
+// src/utils/connect-retry.ts
 const MAX_DELAY_MS = 1e4;
 /** Errors that no retry fixes: a refused credential, a missing endpoint, mismatched versions. */
 const PERMANENT = /\b(?:401|403|404|428|unauthorized|forbidden|version mismatch|invalid (?:token|credentials)|not found)\b/iu;
@@ -22,7 +22,7 @@ async function retryConnect(connect, options) {
 	for (let retry = 0;; retry += 1) try {
 		return await connect();
 	} catch (error) {
-		if (retry >= options.retries || !isRetryableConnectError(error)) throw error;
+		if (retry >= options.retries || !(options.retryable ?? isRetryableConnectError)(error)) throw error;
 		const delayMs = Math.min(MAX_DELAY_MS, options.backoffMs * 2 ** retry) * jitter();
 		options.onRetry?.(error, retry + 1, Math.round(delayMs));
 		await sleep(delayMs);
@@ -37,7 +37,6 @@ async function sleepFor(ms) {
 		setTimeout(resolve, ms);
 	});
 }
-//#endregion
 export { isRetryableConnectError, retryConnect };
 
 //# sourceMappingURL=connect-retry.mjs.map

package/dist/utils/connect-retry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"connect-retry.mjs","names":[],"sources":["../../src/utils/connect-retry.ts"],"sourcesContent":["/** Retrying a connection to a remote browser service (ADR 0007, decision 4). */\n\n/** Options of {@link retryConnect}. */\nexport interface RetryConnectOptions {\n  /** Retries after the first attempt. */\n  retries: number;\n  /** Delay before the first retry in ms; doubles each time, with jitter, capped at 10 s. */\n  backoffMs: number;\n  /** Called before each retry with the error, the retry's number (from 1) and its delay. */\n  onRetry?: (error: unknown, retry: number, delayMs: number) => void;\n  /** Injectable for tests. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst MAX_DELAY_MS = 10_000;\n\n/** Errors that no retry fixes: a refused credential, a missing endpoint, mismatched versions. */\nconst PERMANENT =\n  /\\b(?:401|403|404|428|unauthorized|forbidden|version mismatch|invalid (?:token|credentials)|not found)\\b/iu;\n\n/** Errors of the connection itself: refused, dropped, timed out, or a service with no free session. */\nconst CONNECTION =\n  /(?:ECONNREFUSED|ECONNRESET|EPIPE|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|socket hang up|websocket error|connection (?:closed|refused|reset)|timeout|timed out|capacity|too many|queue(?:d)? full|no (?:free )?(?:session|browser)|\\b(?:408|425|429|500|502|503|504)\\b)/iu;\n\n/** Whether a connect error is worth retrying: connection-level, not a configuration mistake. */\nexport function isRetryableConnectError(error: unknown): boolean {\n  const text = error instanceof Error ? error.message : String(error);\n  return !PERMANENT.test(text) && CONNECTION.test(text);\n}\n\n/**\n * Run `connect`, retrying a connection-level failure with exponential backoff, so a provider\n * outage or a full plan is absorbed here and crash isolation only ever sees a browser that died\n * while rendering. The last error is thrown once the retries are spent.\n */\nexport async function retryConnect<T>(\n  connect: () => Promise<T>,\n  options: RetryConnectOptions,\n): Promise<T> {\n  const sleep = options.sleep ?? sleepFor;\n  for (let retry = 0; ; retry += 1) {\n    try {\n      // oxlint-disable-next-line eslint/no-await-in-loop -- attempts are sequential by design\n      return await connect();\n    } catch (error) {\n      if (retry >= options.retries || !isRetryableConnectError(error)) {\n        throw error;\n      }\n      const delayMs = Math.min(MAX_DELAY_MS, options.backoffMs * 2 ** retry) * jitter();\n      options.onRetry?.(error, retry + 1, Math.round(delayMs));\n      // oxlint-disable-next-line eslint/no-await-in-loop -- backoff between sequential attempts\n      await sleep(delayMs);\n    }\n  }\n}\n\n/** 0.75 to 1.25: providers refusing for capacity should not see every shard retry in step. */\nfunction jitter(): number {\n  return 0.75 + Math.random() * 0.5;\n}\n\nasync function sleepFor(ms: number): Promise<void> {\n  await new Promise<void>((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n"],"mappings":";;;;AAcA,MAAM,eAAe;;AAGrB,MAAM,YACJ;;AAGF,MAAM,aACJ;;AAGF,SAAgB,wBAAwB,OAAyB;CAC/D,MAAM,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CAClE,OAAO,CAAC,UAAU,KAAK,IAAI,KAAK,WAAW,KAAK,IAAI;AACtD;;;;;;AAOA,eAAsB,aACpB,SACA,SACY;CACZ,MAAM,QAAQ,QAAQ,SAAS;CAC/B,KAAK,IAAI,QAAQ,IAAK,SAAS,GAC7B,IAAI;EAEF,OAAO,MAAM,QAAQ;CACvB,SAAS,OAAO;EACd,IAAI,SAAS,QAAQ,WAAW,CAAC,wBAAwB,KAAK,GAC5D,MAAM;EAER,MAAM,UAAU,KAAK,IAAI,cAAc,QAAQ,YAAY,KAAK,KAAK,IAAI,OAAO;EAChF,QAAQ,UAAU,OAAO,QAAQ,GAAG,KAAK,MAAM,OAAO,CAAC;EAEvD,MAAM,MAAM,OAAO;CACrB;AAEJ;;AAGA,SAAS,SAAiB;CACxB,OAAO,MAAO,KAAK,OAAO,IAAI;AAChC;AAEA,eAAe,SAAS,IAA2B;CACjD,MAAM,IAAI,SAAe,YAAY;EACnC,WAAW,SAAS,EAAE;CACxB,CAAC;AACH"}
+{"version":3,"file":"connect-retry.mjs","names":[],"sources":["../../src/utils/connect-retry.ts"],"sourcesContent":["/** Retrying a connection to a remote browser service (ADR 0007, decision 4). */\n\n/** Options of {@link retryConnect}. */\nexport interface RetryConnectOptions {\n  /** Retries after the first attempt. */\n  retries: number;\n  /** Delay before the first retry in ms; doubles each time, with jitter, capped at 10 s. */\n  backoffMs: number;\n  /** Whether an error is worth another attempt; defaults to {@link isRetryableConnectError}. */\n  retryable?: (error: unknown) => boolean;\n  /** Called before each retry with the error, the retry's number (from 1) and its delay. */\n  onRetry?: (error: unknown, retry: number, delayMs: number) => void;\n  /** Injectable for tests. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst MAX_DELAY_MS = 10_000;\n\n/** Errors that no retry fixes: a refused credential, a missing endpoint, mismatched versions. */\nconst PERMANENT =\n  /\\b(?:401|403|404|428|unauthorized|forbidden|version mismatch|invalid (?:token|credentials)|not found)\\b/iu;\n\n/** Errors of the connection itself: refused, dropped, timed out, or a service with no free session. */\nconst CONNECTION =\n  /(?:ECONNREFUSED|ECONNRESET|EPIPE|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|socket hang up|websocket error|connection (?:closed|refused|reset)|timeout|timed out|capacity|too many|queue(?:d)? full|no (?:free )?(?:session|browser)|\\b(?:408|425|429|500|502|503|504)\\b)/iu;\n\n/** Whether a connect error is worth retrying: connection-level, not a configuration mistake. */\nexport function isRetryableConnectError(error: unknown): boolean {\n  const text = error instanceof Error ? error.message : String(error);\n  return !PERMANENT.test(text) && CONNECTION.test(text);\n}\n\n/**\n * Run `connect`, retrying a connection-level failure with exponential backoff, so a provider\n * outage or a full plan is absorbed here and crash isolation only ever sees a browser that died\n * while rendering. The last error is thrown once the retries are spent.\n */\nexport async function retryConnect<T>(\n  connect: () => Promise<T>,\n  options: RetryConnectOptions,\n): Promise<T> {\n  const sleep = options.sleep ?? sleepFor;\n  for (let retry = 0; ; retry += 1) {\n    try {\n      // oxlint-disable-next-line eslint/no-await-in-loop -- attempts are sequential by design\n      return await connect();\n    } catch (error) {\n      if (retry >= options.retries || !(options.retryable ?? isRetryableConnectError)(error)) {\n        throw error;\n      }\n      const delayMs = Math.min(MAX_DELAY_MS, options.backoffMs * 2 ** retry) * jitter();\n      options.onRetry?.(error, retry + 1, Math.round(delayMs));\n      // oxlint-disable-next-line eslint/no-await-in-loop -- backoff between sequential attempts\n      await sleep(delayMs);\n    }\n  }\n}\n\n/** 0.75 to 1.25: providers refusing for capacity should not see every shard retry in step. */\nfunction jitter(): number {\n  return 0.75 + Math.random() * 0.5;\n}\n\nasync function sleepFor(ms: number): Promise<void> {\n  await new Promise<void>((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n"],"mappings":";;;;AAgBA,MAAM,eAAe;;AAGrB,MAAM,YACJ;;AAGF,MAAM,aACJ;;AAGF,SAAgB,wBAAwB,OAAyB;CAC/D,MAAM,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CAClE,OAAO,CAAC,UAAU,KAAK,IAAI,KAAK,WAAW,KAAK,IAAI;AACtD;;;;;;AAOA,eAAsB,aACpB,SACA,SACY;CACZ,MAAM,QAAQ,QAAQ,SAAS;CAC/B,KAAK,IAAI,QAAQ,IAAK,SAAS,GAC7B,IAAI;EAEF,OAAO,MAAM,QAAQ;CACvB,SAAS,OAAO;EACd,IAAI,SAAS,QAAQ,WAAW,EAAE,QAAQ,aAAa,wBAAA,CAAyB,KAAK,GACnF,MAAM;EAER,MAAM,UAAU,KAAK,IAAI,cAAc,QAAQ,YAAY,KAAK,KAAK,IAAI,OAAO;EAChF,QAAQ,UAAU,OAAO,QAAQ,GAAG,KAAK,MAAM,OAAO,CAAC;EAEvD,MAAM,MAAM,OAAO;CACrB;AAEJ;;AAGA,SAAS,SAAiB;CACxB,OAAO,MAAO,KAAK,OAAO,IAAI;AAChC;AAEA,eAAe,SAAS,IAA2B;CACjD,MAAM,IAAI,SAAe,YAAY;EACnC,WAAW,SAAS,EAAE;CACxB,CAAC;AACH"}

package/dist/utils/encrypt.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/encrypt.d.ts
 /** Current server secret plus the one it replaced, kept only to decrypt older rows. */
 interface SecretKeys {
   current: string;
@@ -43,6 +42,5 @@ declare function decryptWithKey(input: SecretInput, ciphertext: string): {
  * rotation hint. A missing secret keeps its own configuration error.
  */
 declare function decryptCredential(input: SecretInput, ciphertext: string): string;
-//#endregion
 export { KeyUsed, SecretInput, SecretKeys, UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt };
 //# sourceMappingURL=encrypt.d.mts.map

package/dist/utils/encrypt.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
-//#region src/utils/encrypt.ts
+// src/utils/encrypt.ts
 /** Thrown when a stored credential cannot be decrypted with any configured key. */
 var UndecryptableCredentialError = class extends Error {
 	constructor(cause) {
@@ -97,7 +97,6 @@ function decryptWith(secret, ciphertext) {
 function deriveKey(secret) {
 	return createHash("sha256").update(secret).digest();
 }
-//#endregion
 export { UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt };
 
 //# sourceMappingURL=encrypt.mjs.map

package/dist/utils/environment.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { CaptureEnvironment } from "../adapter/capture-runner.mjs";
-//#region src/utils/environment.d.ts
 /**
  * Digest of the installed system font families (`fc-list`), or undefined where fontconfig is not
  * available. Cached for the process (fonts do not change under a running server), except a failed
@@ -14,6 +13,5 @@ declare function systemFontsHash(): Promise<string | undefined>;
  * font digest. Runners call this once per render with the version their driver reports.
  */
 declare function detectCaptureEnvironment(browserVersion?: string, deviceScaleFactor?: number): Promise<CaptureEnvironment>;
-//#endregion
 export { detectCaptureEnvironment, systemFontsHash };
 //# sourceMappingURL=environment.d.mts.map

package/dist/utils/environment.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { sha256 } from "./hash.mjs";
-//#region src/utils/environment.ts
+// src/utils/environment.ts
 let fonts;
 /**
 * Digest of the installed system font families (`fc-list`), or undefined where fontconfig is not
@@ -53,7 +53,6 @@ function digestOf(stdout) {
 	const families = [...new Set(stdout.split("\n").map((line) => line.trim()))].filter(Boolean);
 	return families.length > 0 ? sha256(families.toSorted().join("\n")).slice(0, 16) : void 0;
 }
-//#endregion
 export { detectCaptureEnvironment, systemFontsHash };
 
 //# sourceMappingURL=environment.mjs.map

package/dist/utils/hash.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/utils/hash.d.ts
 /** Hash a value with SHA-256, returning lowercase hex. */
 declare function sha256(value: string): string;
 /** Sign a value with HMAC-SHA-256, returning lowercase hex. */
@@ -12,6 +11,5 @@ declare function randomToken(prefix: string): {
 };
 /** Compare two strings in constant time to avoid timing leaks. */
 declare function timingSafeEqualString(a: string, b: string): boolean;
-//#endregion
 export { hmacSha256, randomToken, sha256, timingSafeEqualString };
 //# sourceMappingURL=hash.d.mts.map

package/dist/utils/hash.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region src/utils/hash.ts
+// src/utils/hash.ts
 /** Hash a value with SHA-256, returning lowercase hex. */
 function sha256(value) {
 	return createHash("sha256").update(value).digest("hex");
@@ -25,7 +25,6 @@ function timingSafeEqualString(a, b) {
 	const bb = Buffer.from(b);
 	return ab.length === bb.length && timingSafeEqual(ab, bb);
 }
-//#endregion
 export { hmacSha256, randomToken, sha256, timingSafeEqualString };
 
 //# sourceMappingURL=hash.mjs.map

package/dist/utils/http.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Logger } from "../logger.mjs";
 import { Buffer } from "node:buffer";
-//#region src/utils/http.d.ts
 /**
  * Fetch JSON with timeout, retries, and structured errors.
  *
@@ -32,6 +31,18 @@ declare function httpBytes(url: string, options?: HttpRequestOptions): Promise<B
  * @returns The raw response body text.
  */
 declare function httpText(url: string, options?: HttpTextOptions): Promise<string>;
+/**
+ * Send a request and resolve with the response status, without ever reading the response body (it
+ * is cancelled on every response). Use it when the answer is only "did it succeed", such as webhook
+ * delivery, so a receiver cannot make the process buffer an arbitrarily large body. Retries,
+ * timeouts, redaction and tracing are those of {@link httpText}. A non-2xx response throws
+ * {@link HttpError} with an empty `body`.
+ *
+ * @param url - Absolute request URL.
+ * @param options - Method, headers, JSON body, timeout, retries, logger.
+ * @returns The 2xx response status.
+ */
+declare function httpStatus(url: string, options?: HttpTextOptions): Promise<number>;
 /** Failed HTTP response: status code plus a snippet of the response body. */
 declare class HttpError extends Error {
   readonly status: number;
@@ -69,6 +80,5 @@ interface HttpTextOptions {
   signal?: AbortSignal;
   logger?: Logger;
 }
-//#endregion
-export { HttpError, HttpRequestOptions, HttpTextOptions, httpBytes, httpJson, httpText };
+export { HttpError, HttpRequestOptions, HttpTextOptions, httpBytes, httpJson, httpStatus, httpText };
 //# sourceMappingURL=http.d.mts.map

package/dist/utils/http.mjs

@@ -1,9 +1,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { injectTraceContext, withSpan } from "../tracing.mjs";
+import { injectTraceContext, setSpanMessage, spanException, withSpan } from "../tracing.mjs";
 import { Buffer } from "node:buffer";
-//#region src/utils/http.ts
+// src/utils/http.ts
 /**
 * Fetch JSON with timeout, retries, and structured errors.
 *
@@ -39,6 +39,20 @@ async function httpBytes(url, options = {}) {
 async function httpText(url, options = {}) {
 	return await requestWithRetry(url, options, options.retries ?? DEFAULT_RETRIES, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, doFetchText);
 }
+/**
+* Send a request and resolve with the response status, without ever reading the response body (it
+* is cancelled on every response). Use it when the answer is only "did it succeed", such as webhook
+* delivery, so a receiver cannot make the process buffer an arbitrarily large body. Retries,
+* timeouts, redaction and tracing are those of {@link httpText}. A non-2xx response throws
+* {@link HttpError} with an empty `body`.
+*
+* @param url - Absolute request URL.
+* @param options - Method, headers, JSON body, timeout, retries, logger.
+* @returns The 2xx response status.
+*/
+async function httpStatus(url, options = {}) {
+	return await requestWithRetry(url, options, options.retries ?? DEFAULT_RETRIES, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, doFetchStatus);
+}
 /** Failed HTTP response: status code plus a snippet of the response body. */
 var HttpError = class extends Error {
 	status;
@@ -91,25 +105,54 @@ async function requestWithRetry(url, options, maxAttempts, timeoutMs, perform) {
 		for (let attempt = 1;; attempt += 1) try {
 			return await perform(url, options, timeoutMs);
 		} catch (error) {
-			span.recordException(error instanceof Error ? error : String(error));
+			describeFailure(span, error, url);
 			if (options.signal?.aborted || !shouldRetry(error, attempt, maxAttempts)) throw error;
+			span.recordException(spanException(error));
 			span.setAttribute("http.retry.count", attempt);
 			await backoff(error, attempt, url, options.logger);
 		}
 	}, {
 		"http.request.method": options.method ?? "GET",
-		"url.full": redactUrl(url)
+		"url.full": redactUrlForLog(url)
 	});
 }
-/** Strip the query string (tokens, signatures) from a URL for span attributes. */
-function redactUrl(url) {
-	const query = url.indexOf("?");
-	return query === -1 ? url : url.slice(0, query);
+/**
+* The form of a request URL that may appear in logs and span attributes: its origin
+* (`protocol//host`) and nothing else. The path of an incoming webhook (Slack, Teams) is the secret,
+* a bot token can be the first segment (Telegram), and other URLs carry credentials in the userinfo
+* or the query, so the path, query, fragment and userinfo are dropped by construction. There is no
+* opt-out.
+*/
+function redactUrlForLog(url) {
+	try {
+		const { protocol, host } = new URL(url);
+		return `${protocol}//${host}`;
+	} catch {
+		return "[invalid url]";
+	}
+}
+/**
+* What a span may say about a failed request. An HTTP failure carries its status and never the
+* response body, which can echo the request URL in any encoding. Any other failure keeps its
+* message with the request URL replaced by its origin, because native `fetch` repeats the whole
+* URL, userinfo included, when it refuses one. The error a caller catches is not changed.
+*/
+function describeFailure(span, error, url) {
+	if (error instanceof HttpError) {
+		span.setAttribute("http.response.status_code", error.status);
+		setSpanMessage(error, `HTTP ${String(error.status)}`);
+	} else if (error instanceof Error) setSpanMessage(error, scrubUrl(error.message, url));
+}
+/** `text` with the request URL, as given and as normalized, replaced by its origin. */
+function scrubUrl(text, url) {
+	const origin = redactUrlForLog(url);
+	const normalized = URL.canParse(url) ? new URL(url).href : url;
+	return text.replaceAll(url, origin).replaceAll(normalized, origin);
 }
 async function backoff(error, attempt, url, logger) {
 	const delay = retryDelayMs(error, attempt);
 	logger?.warn({
-		url,
+		url: redactUrlForLog(url),
 		attempt,
 		delayMs: delay
 	}, "http request failed, retrying");
@@ -137,15 +180,20 @@ async function doFetchJson(url, options, timeoutMs) {
 async function doFetchText(url, options, timeoutMs) {
 	return await (await doFetchResponse(url, options, timeoutMs)).text();
 }
+async function doFetchStatus(url, options, timeoutMs) {
+	const response = await doFetchResponse(url, options, timeoutMs, false);
+	await discardBody(response);
+	return response.status;
+}
 async function doFetchBytes(url, options, timeoutMs) {
 	const response = await doFetchResponse(url, options, timeoutMs);
 	return Buffer.from(await response.arrayBuffer());
 }
-async function doFetchResponse(url, options, timeoutMs) {
+async function doFetchResponse(url, options, timeoutMs, readErrorBody = true) {
 	const request = buildRequest(options);
 	injectTraceContext(request.headers);
 	options.logger?.debug({
-		url,
+		url: redactUrlForLog(url),
 		method: request.method
 	}, "http request");
 	const response = await fetch(url, {
@@ -154,13 +202,27 @@ async function doFetchResponse(url, options, timeoutMs) {
 		body: request.body,
 		signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs)
 	});
-	if (!response.ok) {
-		const text = await response.text();
-		throw new HttpError(response.status, text.slice(0, MAX_BODY_SNIPPET), response.headers);
-	}
+	if (!response.ok) throw await failureOf(response, readErrorBody);
 	return response;
 }
-//#endregion
-export { HttpError, httpBytes, httpJson, httpText };
+/**
+* Cancel an unread body. Cleanup only: a rejected cancel must never replace the request's outcome,
+* or a delivered request would look failed and be retried.
+*/
+async function discardBody(response) {
+	try {
+		await response.body?.cancel();
+	} catch {}
+}
+/** The {@link HttpError} for a non-2xx response; the body is read (and capped) only on request. */
+async function failureOf(response, readBody) {
+	if (!readBody) {
+		await discardBody(response);
+		return new HttpError(response.status, "", response.headers);
+	}
+	const text = await response.text();
+	return new HttpError(response.status, text.slice(0, MAX_BODY_SNIPPET), response.headers);
+}
+export { HttpError, httpBytes, httpJson, httpStatus, httpText, redactUrlForLog };
 
 //# sourceMappingURL=http.mjs.map