@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/http/transport.js

@@ -1,143 +1,477 @@
-import { classifyError, ExpiredAuthTokenError, B2Error, NetworkError } from "../errors/index.js";
-import { DEFAULT_RETRY_OPTIONS, sleep, computeBackoff } from "./retry.js";
+import { B2Error, B2RedirectError, B2SsrfError, ExpiredAuthTokenError, NetworkError, classifyError } from "../errors/index.js";
+import { abortReason, raceWithAbort, throwIfSignalAborted } from "../util/abort.js";
+import { DEFAULT_RETRY_OPTIONS, computeBackoff, sleep } from "./retry.js";
 import { UrlGuard } from "./url-guard.js";
 import { getUserAgent } from "./user-agent.js";
-class FetchTransport {
-  /** User-Agent string sent with every request. */
-  userAgent;
-  /** SSRF allow-list applied to every outgoing URL. Mutable so `B2Client.authorize()` can lock it down post-auth. */
-  urlGuard;
-  /**
-   * Creates a new FetchTransport.
-   * @param options - Optional configuration: custom User-Agent prefix and SSRF guard.
-   */
-  constructor(options) {
-    this.userAgent = getUserAgent(options?.userAgent);
-    this.urlGuard = options?.urlGuard ?? new UrlGuard();
-  }
-  /**
-   * Sends the request using the global `fetch` function.
-   * @param request - The HTTP request to execute.
-   *
-   * @returns The HTTP response.
-   *
-   * @throws B2SsrfError when the URL fails the configured SSRF guard.
-   */
-  async send(request) {
-    this.urlGuard.check(request.url);
-    const headers = new Headers(request.headers);
-    if (!headers.has("User-Agent")) {
-      headers.set("User-Agent", this.userAgent);
-    }
-    const response = await fetch(request.url, {
-      method: request.method,
-      headers,
-      body: request.body ?? null,
-      ...request.signal !== void 0 ? { signal: request.signal } : {}
-    });
-    return {
-      status: response.status,
-      headers: response.headers,
-      body: response.body,
-      json: () => response.json(),
-      text: () => response.text(),
-      arrayBuffer: () => response.arrayBuffer()
-    };
-  }
-}
-class RetryTransport {
-  /** The wrapped transport that performs actual HTTP requests. */
-  inner;
-  /** Resolved retry options (defaults merged with user overrides). */
-  options;
-  /** Optional callback to refresh auth credentials on 401 — returns the fresh token. */
-  onReauth;
-  /** Sleep implementation used between retries; injectable for tests. */
-  sleepImpl;
-  /**
-   * Creates a new RetryTransport.
-   * @param opts - Retry transport configuration.
-   */
-  constructor(opts) {
-    this.inner = opts.transport;
-    this.options = { ...DEFAULT_RETRY_OPTIONS, ...opts.retry };
-    if (opts.onReauth !== void 0) this.onReauth = opts.onReauth;
-    this.sleepImpl = opts.sleepImpl ?? sleep;
-  }
-  /**
-   * Sends the request with automatic retry on transient failures.
-   * On expired auth tokens, calls {@link RetryTransportOptions.onReauth} and retries.
-   * @param originalRequest - The HTTP request to execute. The caller's
-   *   reference is not mutated; on reauth, a copy with a refreshed
-   *   Authorization header is sent.
-   *
-   * @returns The HTTP response.
-   */
-  async send(originalRequest) {
-    let request = originalRequest;
-    let lastError;
-    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
-      if (attempt > 0 && lastError) {
-        const retryAfter = lastError instanceof NetworkError ? void 0 : lastError.retryAfter;
-        const delay = computeBackoff(attempt - 1, this.options, retryAfter);
-        await this.sleepImpl(delay, request.signal);
-      }
-      try {
-        const response = await this.inner.send(request);
-        if (response.status >= 200 && response.status < 300) {
-          return response;
-        }
-        let errorBody;
-        try {
-          errorBody = await response.json();
-        } catch {
-          errorBody = {
-            status: response.status,
-            code: "internal_error",
-            message: `HTTP ${response.status}`
-          };
-        }
-        const retryAfterHeader = response.headers.get("Retry-After");
-        const retryAfterSec = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : void 0;
-        const requestId = response.headers.get("X-Bz-Request-Id") ?? void 0;
-        const error = classifyError(errorBody, {
-          ...retryAfterSec !== void 0 ? { retryAfter: retryAfterSec } : {},
-          ...requestId !== void 0 ? { requestId } : {}
-        });
-        if (error instanceof ExpiredAuthTokenError && this.onReauth) {
-          const freshToken = await this.onReauth();
-          request = {
-            ...request,
-            headers: { ...request.headers ?? {}, Authorization: freshToken }
-          };
-          continue;
-        }
-        if (!error.retryable || attempt === this.options.maxRetries) {
-          throw error;
-        }
-        lastError = error;
-      } catch (err) {
-        if (err instanceof B2Error || err instanceof NetworkError) {
-          throw err;
-        }
-        if (err instanceof DOMException && err.name === "AbortError") {
-          throw err;
-        }
-        const networkErr = new NetworkError(
-          err instanceof Error ? err.message : "Network error",
-          err
-        );
-        if (attempt === this.options.maxRetries) {
-          throw networkErr;
-        }
-        lastError = networkErr;
-      }
-    }
-    throw lastError ?? new NetworkError("Max retries exceeded");
-  }
-}
-export {
-  FetchTransport,
-  RetryTransport
+//#region src/http/transport.ts
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+var MAX_SAME_ORIGIN_REDIRECTS = 5;
+/**
+* Returns the URL guard exposed by `transport`, if it implements
+* {@link UrlGuardedTransport}.
+*
+* @param transport - Transport to inspect.
+*
+* @returns The exposed URL guard, or undefined for unguarded transports.
+*/
+function getTransportUrlGuard(transport) {
+	const candidate = transport;
+	return candidate.urlGuard instanceof UrlGuard ? candidate.urlGuard : void 0;
+}
+/**
+* Default transport implementation using the global `fetch` API.
+* Automatically sets the User-Agent header on each request and applies the
+* SSRF {@link UrlGuard} (if configured) before opening the connection.
+* Redirect following is disabled so redirected URLs cannot bypass the guard or
+* receive credential-bearing headers without an explicit checked request.
+*/
+var FetchTransport = class {
+	/** User-Agent string sent with every request. */
+	userAgent;
+	/** Whether same-origin GET/HEAD redirects should be followed after guard checks. */
+	followSameOriginRedirects;
+	/** SSRF allow-list applied to every outgoing URL. Mutable so `B2Client.authorize()` can lock it down post-auth. */
+	urlGuard;
+	/**
+	* Creates a new FetchTransport.
+	* @param options - Optional configuration: custom User-Agent prefix and SSRF guard.
+	*/
+	constructor(options) {
+		this.userAgent = getUserAgent(options?.userAgent);
+		this.followSameOriginRedirects = options?.followSameOriginRedirects ?? true;
+		this.urlGuard = options?.urlGuard ?? new UrlGuard();
+	}
+	/**
+	* Sends the request using the global `fetch` function.
+	* @param request - The HTTP request to execute.
+	*
+	* @returns The HTTP response.
+	*
+	* @throws B2SsrfError when the URL fails the configured SSRF guard.
+	* @throws B2RedirectError when a response attempts to redirect.
+	*/
+	async send(request) {
+		let currentRequest = request;
+		let redirectCount = 0;
+		while (true) {
+			this.urlGuard.check(currentRequest.url);
+			const headers = new Headers(currentRequest.headers);
+			if (!headers.has("User-Agent")) headers.set("User-Agent", this.userAgent);
+			const timeoutScope = createRequestTimeoutScope(currentRequest);
+			let response;
+			try {
+				response = await fetch(currentRequest.url, {
+					method: currentRequest.method,
+					headers,
+					body: currentRequest.body ?? null,
+					redirect: "manual",
+					...timeoutScope.signal !== void 0 ? { signal: timeoutScope.signal } : {}
+				});
+			} catch (err) {
+				timeoutScope.dispose();
+				if (timeoutScope.timedOut) throw createRequestTimeoutError(timeoutScope);
+				throw err;
+			}
+			if (isBlockedRedirect(response)) {
+				const location = response.headers.get("Location");
+				if (this.followSameOriginRedirects && location !== null && redirectCount < MAX_SAME_ORIGIN_REDIRECTS && canFollowSameOriginRedirect(currentRequest, location)) {
+					const nextUrl = new URL(location, currentRequest.url).toString();
+					await cancelResponseBody(response);
+					timeoutScope.dispose();
+					this.urlGuard.check(nextUrl);
+					currentRequest = {
+						...currentRequest,
+						url: nextUrl
+					};
+					redirectCount += 1;
+					continue;
+				}
+				await cancelResponseBody(response);
+				timeoutScope.dispose();
+				throw new B2RedirectError(currentRequest.url, response.status, location);
+			}
+			return createTimedHttpResponse(response, timeoutScope);
+		}
+	}
 };
-//# sourceMappingURL=transport.js.map
+function createRequestTimeoutScope(request) {
+	const timeoutMs = request.retry?.requestTimeoutMs ?? DEFAULT_RETRY_OPTIONS.requestTimeoutMs;
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+		const scope = {
+			timeoutMs: 0,
+			timedOut: false,
+			reset() {},
+			dispose() {}
+		};
+		if (request.signal !== void 0) return {
+			...scope,
+			signal: request.signal
+		};
+		return scope;
+	}
+	const controller = new AbortController();
+	let timedOut = false;
+	let timer;
+	const abortFromUpstream = () => {
+		clearTimeout(timer);
+		controller.abort(request.signal?.reason ?? new DOMException("Aborted", "AbortError"));
+	};
+	const armTimer = () => {
+		const nextTimer = setTimeout(() => {
+			timedOut = true;
+			controller.abort(new DOMException("HTTP request timed out", "TimeoutError"));
+		}, timeoutMs);
+		unrefTimer(nextTimer);
+		return nextTimer;
+	};
+	timer = armTimer();
+	const reset = () => {
+		if (timedOut || controller.signal.aborted) return;
+		clearTimeout(timer);
+		timer = armTimer();
+	};
+	if (request.signal?.aborted === true) {
+		clearTimeout(timer);
+		abortFromUpstream();
+	} else request.signal?.addEventListener("abort", abortFromUpstream, { once: true });
+	return {
+		signal: controller.signal,
+		timeoutMs,
+		get timedOut() {
+			return timedOut;
+		},
+		reset,
+		dispose() {
+			clearTimeout(timer);
+			request.signal?.removeEventListener("abort", abortFromUpstream);
+		}
+	};
+}
+function unrefTimer(timer) {
+	const maybeUnref = timer.unref;
+	if (typeof maybeUnref === "function") maybeUnref.call(timer);
+}
+function createRequestTimeoutError(scope) {
+	return new DOMException(`HTTP request timed out after ${scope.timeoutMs} ms`, "TimeoutError");
+}
+function createTimedHttpResponse(response, timeoutScope) {
+	const body = response.body;
+	if (body === null) timeoutScope.dispose();
+	let timedBody;
+	return {
+		status: response.status,
+		headers: response.headers,
+		get body() {
+			if (body === null) return null;
+			timedBody ??= createTimedResponseBody(body, timeoutScope);
+			return timedBody;
+		},
+		json: () => readTimedResponseBody(timeoutScope, response, () => response.json()),
+		text: () => readTimedResponseBody(timeoutScope, response, () => response.text()),
+		arrayBuffer: () => readTimedResponseBody(timeoutScope, response, () => response.arrayBuffer())
+	};
+}
+async function readTimedResponseBody(timeoutScope, response, read) {
+	try {
+		return await raceBodyReadWithAbort(timeoutScope, read(), (reason) => cancelResponseBody(response, reason));
+	} catch (err) {
+		if (timeoutScope.timedOut) throw createRequestTimeoutError(timeoutScope);
+		throw err;
+	} finally {
+		timeoutScope.dispose();
+	}
+}
+function createTimedResponseBody(body, timeoutScope) {
+	let reader;
+	let disposed = false;
+	const dispose = () => {
+		if (disposed) return;
+		disposed = true;
+		timeoutScope.dispose();
+	};
+	return new ReadableStream({
+		async pull(controller) {
+			reader ??= body.getReader();
+			try {
+				const result = await raceBodyReadWithAbort(timeoutScope, reader.read(), (reason) => reader?.cancel(reason));
+				if (result.done) {
+					dispose();
+					controller.close();
+					return;
+				}
+				timeoutScope.reset();
+				controller.enqueue(result.value);
+			} catch (err) {
+				dispose();
+				if (timeoutScope.timedOut) {
+					controller.error(createRequestTimeoutError(timeoutScope));
+					return;
+				}
+				controller.error(err);
+			}
+		},
+		async cancel(reason) {
+			dispose();
+			try {
+				if (reader !== void 0) {
+					await reader.cancel(reason);
+					return;
+				}
+				await body.cancel(reason);
+			} catch {}
+		}
+	});
+}
+async function raceBodyReadWithAbort(timeoutScope, read, abortCleanup) {
+	const signal = timeoutScope.signal;
+	if (signal === void 0) return read;
+	if (signal.aborted) {
+		read.catch(() => {});
+		const reason = abortReason(signal);
+		await runAbortCleanup(abortCleanup, reason);
+		throw reason;
+	}
+	let removeAbortListener;
+	const abort = new Promise((_, reject) => {
+		const onAbort = () => {
+			const reason = abortReason(signal);
+			read.catch(() => {});
+			reject(reason);
+			runAbortCleanup(abortCleanup, reason);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+	});
+	try {
+		return await Promise.race([read, abort]);
+	} finally {
+		removeAbortListener?.();
+	}
+}
+async function runAbortCleanup(abortCleanup, reason) {
+	try {
+		await abortCleanup?.(reason);
+	} catch {}
+}
+function isBlockedRedirect(response) {
+	return response.type === "opaqueredirect" || REDIRECT_STATUSES.has(response.status);
+}
+function canFollowSameOriginRedirect(request, location) {
+	if (request.method !== "GET" && request.method !== "HEAD") return false;
+	try {
+		return new URL(request.url).origin === new URL(location, request.url).origin;
+	} catch {
+		return false;
+	}
+}
+async function cancelResponseBody(response, reason) {
+	try {
+		await response.body?.cancel(reason);
+	} catch {}
+}
+/**
+* Decide whether `url` points at a URL-pinned upload POST endpoint.
+*
+* @param url - Request URL to inspect.
+*
+* @returns Whether the request is a direct upload endpoint.
+*/
+function isUploadEndpoint(url) {
+	const endpoint = b2ApiEndpointName(url);
+	return endpoint === "b2_upload_file" || endpoint === "b2_upload_part";
+}
+function isFinishLargeFileEndpoint(url) {
+	return b2ApiEndpointName(url) === "b2_finish_large_file";
+}
+function isAuthorizeEndpoint(url) {
+	return b2ApiEndpointName(url) === "b2_authorize_account";
+}
+function isStartLargeFileEndpoint(url) {
+	return b2ApiEndpointName(url) === "b2_start_large_file";
+}
+function isPartnerMutationEndpoint(url) {
+	const endpoint = b2ApiEndpointName(url);
+	return endpoint === "b2_create_group_member" || endpoint === "b2_eject_group_member" || endpoint === "b2_reserve_trial_create_account";
+}
+function isBackupMutationEndpoint(url) {
+	return backupApiEndpointName(url) === "bz_delete_computer";
+}
+function isNonIdempotentMutationRequest(request) {
+	return request.method === "POST" && (isPartnerMutationEndpoint(request.url) || isBackupMutationEndpoint(request.url));
+}
+function b2ApiEndpointName(url) {
+	const segments = new URL(url).pathname.split("/").filter((segment) => segment.length > 0);
+	const apiRootIndex = segments.lastIndexOf("b2api");
+	if (apiRootIndex === -1) return void 0;
+	return segments[apiRootIndex + 2];
+}
+function backupApiEndpointName(url) {
+	const segments = new URL(url).pathname.split("/").filter((segment) => segment.length > 0);
+	const apiRootIndex = segments.lastIndexOf("api");
+	if (apiRootIndex === -1 || segments[apiRootIndex + 1] !== "backup") return void 0;
+	if (!/^v\d+$/.test(segments[apiRootIndex + 2] ?? "")) return void 0;
+	return segments[apiRootIndex + 3];
+}
+function isReplayUnsafePostRequest(request) {
+	if (request.method !== "POST") return false;
+	return isUploadEndpoint(request.url) || isStartLargeFileEndpoint(request.url) || isFinishLargeFileEndpoint(request.url) || isNonIdempotentMutationRequest(request);
+}
+/**
+* Decide whether a classified error should be retried in place for `url`.
+* Transient errors normally retry; upload endpoints bubble to the upload layer
+* for fresh-URL retry except account-level 429 throttling, where fetching a new
+* upload URL only amplifies the rate limit.
+*
+* @param error - The classified, retryability-tagged error.
+* @param request - The request being considered for in-place retry.
+*
+* @returns Whether to retry the request in place.
+*/
+function shouldRetryInPlace(error, request) {
+	if (!error.retryable) return false;
+	if (isAuthorizeEndpoint(request.url) && error instanceof ExpiredAuthTokenError) return false;
+	if (isNonIdempotentMutationRequest(request)) return false;
+	if (isStartLargeFileEndpoint(request.url) || isFinishLargeFileEndpoint(request.url)) return false;
+	if (isUploadEndpoint(request.url) && error.status === 429) return true;
+	if (isUploadEndpoint(request.url)) return false;
+	return true;
+}
+function isRequestTimeoutError(err) {
+	return err instanceof DOMException && err.name === "TimeoutError";
+}
+function isTerminalTransportError(err) {
+	return err instanceof B2Error || err instanceof B2RedirectError || err instanceof NetworkError || err instanceof B2SsrfError || err instanceof DOMException && err.name === "AbortError";
+}
+/**
+* Transport wrapper that adds automatic retry with exponential backoff.
+* Handles transient errors (408, 429, and the transient 5xx set 500/502/503/504),
+* expired auth tokens, and network failures. Delegates to an inner
+* {@link HttpTransport}.
+*
+* Upload endpoints (`b2_upload_file` / `b2_upload_part`) are URL-pinned. Their
+* retryable pod failures bubble to the upload layer, which evicts the failed
+* URL, fetches a fresh one, and retries there. HTTP 429 remains an in-place
+* retry so account-level throttling does not trigger extra upload URL fetches.
+*/
+var RetryTransport = class {
+	/** URL guard from the wrapped transport, when the transport exposes one. */
+	urlGuard;
+	/** The wrapped transport that performs actual HTTP requests. */
+	inner;
+	/** Resolved retry options (defaults merged with user overrides). */
+	options;
+	/** Optional callback to refresh auth credentials on 401 — returns the fresh token. */
+	onReauth;
+	/** Sleep implementation used between retries; injectable for tests. */
+	sleepImpl;
+	/**
+	* Creates a new RetryTransport.
+	* @param opts - Retry transport configuration.
+	*/
+	constructor(opts) {
+		this.inner = opts.transport;
+		this.urlGuard = getTransportUrlGuard(opts.transport);
+		this.options = {
+			...DEFAULT_RETRY_OPTIONS,
+			...opts.retry
+		};
+		if (opts.onReauth !== void 0) this.onReauth = opts.onReauth;
+		this.sleepImpl = opts.sleepImpl ?? sleep;
+	}
+	/**
+	* Sends the request with automatic retry on transient failures.
+	* On expired auth tokens, calls {@link RetryTransportOptions.onReauth} and retries.
+	* @param originalRequest - The HTTP request to execute. The caller's
+	*   reference is not mutated; on reauth, a copy with a refreshed
+	*   Authorization header is sent.
+	*
+	* @returns The HTTP response.
+	*/
+	async send(originalRequest) {
+		let request = originalRequest;
+		const retryOptions = {
+			...this.options,
+			...originalRequest.retry
+		};
+		let lastError;
+		let didReauth = false;
+		let attempt = 0;
+		while (attempt <= retryOptions.maxRetries) {
+			throwIfSignalAborted(request.signal);
+			if (attempt > 0 && lastError) {
+				const retryAfter = lastError instanceof NetworkError ? void 0 : lastError.retryAfter;
+				const delay = computeBackoff(attempt - 1, retryOptions, retryAfter);
+				await this.sleepImpl(delay, request.signal);
+			}
+			try {
+				const response = await this.inner.send({
+					...request,
+					retry: retryOptions
+				});
+				await throwIfSignalAbortedAfterResponse(request.signal, response);
+				if (response.status >= 200 && response.status < 300) return response;
+				let errorBody;
+				try {
+					errorBody = await response.json();
+				} catch (err) {
+					if (isRequestTimeoutError(err)) throw err;
+					errorBody = {
+						status: response.status,
+						code: "internal_error",
+						message: `HTTP ${response.status}`
+					};
+				}
+				const retryAfterHeader = response.headers.get("Retry-After");
+				const retryAfterSec = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : void 0;
+				const requestId = response.headers.get("X-Bz-Request-Id") ?? void 0;
+				const error = classifyError(errorBody, {
+					...retryAfterSec !== void 0 ? { retryAfter: retryAfterSec } : {},
+					...requestId !== void 0 ? { requestId } : {}
+				});
+				if (error instanceof ExpiredAuthTokenError && this.onReauth && !isAuthorizeEndpoint(request.url) && !isUploadEndpoint(request.url) && !isNonIdempotentMutationRequest(request) && !didReauth) {
+					const freshToken = await raceWithAbort(this.onReauth(request.signal), request.signal);
+					throwIfSignalAborted(request.signal);
+					request = {
+						...request,
+						headers: {
+							...request.headers ?? {},
+							Authorization: freshToken
+						}
+					};
+					didReauth = true;
+					lastError = void 0;
+					continue;
+				}
+				if (!shouldRetryInPlace(error, request) || attempt === retryOptions.maxRetries) throw error;
+				lastError = error;
+				attempt += 1;
+			} catch (err) {
+				throwIfSignalAborted(request.signal);
+				if (isTerminalTransportError(err)) throw err;
+				const networkErr = new NetworkError(err instanceof Error ? err.message : "Network error", err);
+				if (isReplayUnsafePostRequest(request) || attempt === retryOptions.maxRetries) throw networkErr;
+				lastError = networkErr;
+				attempt += 1;
+			}
+		}
+		throw lastError ?? new NetworkError("Max retries exceeded");
+	}
+};
+async function throwIfSignalAbortedAfterResponse(signal, response) {
+	if (signal?.aborted !== true) return;
+	const reason = abortReason(signal);
+	try {
+		await response.body?.cancel(reason);
+	} catch {}
+	throw reason;
+}
+//#endregion
+export { FetchTransport, RetryTransport, getTransportUrlGuard };
+
+//# sourceMappingURL=transport.js.map