@panorama-industries/effect-vercel-blob 0.0.0 → 0.2.0

package/src/implementation/blob-uploads-live.ts

@@ -0,0 +1,326 @@
+import { VercelSystemEnv } from "@panorama-industries/effect-vercel-core";
+import { Clock, DateTime, Effect, Layer, Option, Redacted, Schema } from "effect";
+import { HttpServerRequest, HttpServerResponse } from "effect/http";
+
+import type {
+  ClientTokenOptions,
+  PresignedUploadHandlerOptions,
+  UploadHandlerOptions,
+} from "../contracts/blob-uploads.ts";
+import type { ClientTokenFields } from "../internal/client-token.ts";
+
+import { BlobConfig } from "../contracts/blob-config.ts";
+import { UploadCompleted, UploadRequest } from "../contracts/blob-domain.ts";
+import {
+  BlobReadWriteTokenRequired,
+  BlobUploadEventRejected,
+  EventMalformed,
+  SignatureInvalid,
+  SignatureMissing,
+  WebhookPublicKeyMissing,
+} from "../contracts/blob-errors.ts";
+import { BlobUploads } from "../contracts/blob-uploads.ts";
+import {
+  callbackSignatureHeader,
+  deriveCallbackUrl,
+  parseCallbackBody,
+  resolveCallbackUrl,
+  verifyEd25519CallbackSignature,
+  verifyHmacCallbackSignature,
+} from "../internal/callback.ts";
+import {
+  clientTokenPayloadJson,
+  contradictsIfMatch,
+  defaultClientTokenLifetimeMillis,
+  ifMatchContradictionMessage,
+  signClientToken,
+} from "../internal/client-token.ts";
+import { presignPayload } from "../internal/presign.ts";
+import { storeIdFromReadWriteToken } from "../internal/store-id.ts";
+import { PutBlobResponse } from "../internal/wire.ts";
+
+/** How long a client token issued by an upload route stays valid by default, as the SDK. */
+const uploadRouteTokenLifetimeMillis = 60 * 60 * 1000;
+
+const generateClientTokenEvent = "blob.generate-client-token";
+const generatePresignedUrlEvent = "blob.generate-presigned-url";
+const uploadCompletedEvent = "blob.upload-completed";
+
+/** What the browser sends to start an upload; extra fields (such as a `callbackUrl`) are ignored. */
+const UploadRequestPayload = Schema.Struct({
+  pathname: Schema.String,
+  clientPayload: Schema.OptionFromOptionalNullOr(Schema.String),
+  multipart: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false))),
+}).pipe(Schema.decodeTo(UploadRequest));
+
+/** The `payload` of `blob.upload-completed`. */
+const UploadCompletedPayload = Schema.Struct({
+  blob: PutBlobResponse,
+  tokenPayload: Schema.OptionFromOptionalNullOr(Schema.String),
+}).pipe(Schema.decodeTo(UploadCompleted));
+
+const UploadRouteEvent = Schema.Struct({
+  type: Schema.Literals([generateClientTokenEvent, uploadCompletedEvent]),
+  payload: Schema.Unknown,
+});
+
+const PresignedRouteEvent = Schema.Struct({
+  type: Schema.Literals([generatePresignedUrlEvent, uploadCompletedEvent]),
+  payload: Schema.Unknown,
+});
+
+const rejected = (reason: BlobUploadEventRejected["reason"]) =>
+  new BlobUploadEventRejected({ reason });
+
+const malformed = (message: string) => rejected(new EventMalformed({ message }));
+
+const decodeOrReject = <S extends Schema.Decoder<unknown>>(schema: S, input: unknown) =>
+  Schema.decodeUnknownEffect(schema)(input).pipe(
+    Effect.mapError((error) => malformed(error.message)),
+  );
+
+/**
+ * The request's body as the SDK receives it (`await request.json()`), and as callback signatures
+ * cover it. A body that cannot be read or is not JSON is `EventMalformed`.
+ */
+const readEvent = <S extends Schema.Decoder<{ readonly type: string; readonly payload: unknown }>>(
+  schema: S,
+) =>
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const text = yield* request.text.pipe(
+      Effect.mapError(() => malformed("The request body could not be read.")),
+    );
+    const body = yield* Option.match(parseCallbackBody(text), {
+      onNone: () => Effect.fail(malformed("The request body is not JSON.")),
+      onSome: Effect.succeed,
+    });
+    const event = yield* Schema.decodeUnknownEffect(schema)(body.json).pipe(
+      Effect.mapError(() => malformed("Invalid event type")),
+    );
+    return { request, event, normalizedBody: body.normalized };
+  });
+
+const signatureOf = (request: HttpServerRequest.HttpServerRequest) =>
+  Effect.gen(function* () {
+    const signature = request.headers[callbackSignatureHeader] ?? "";
+    if (signature === "") {
+      return yield* rejected(new SignatureMissing());
+    }
+    return signature;
+  });
+
+/**
+ * Fields of a client token or route authorization in wire form and in the caller's key order,
+ * which the SDK serializes as given: `validUntil` becomes epoch milliseconds, unknown keys are
+ * dropped.
+ */
+const wireFields = (
+  options: object,
+  keys: ReadonlySet<string>,
+  except?: string,
+): Record<string, unknown> => {
+  const fields: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (!keys.has(key) || key === except) continue;
+    fields[key] =
+      key === "validUntil" && DateTime.isDateTime(value) ? DateTime.toEpochMillis(value) : value;
+  }
+  return fields;
+};
+
+const constraintKeys = [
+  "maximumSizeInBytes",
+  "allowedContentTypes",
+  "validUntil",
+  "addRandomSuffix",
+  "allowOverwrite",
+  "cacheControlMaxAge",
+  "ifMatch",
+];
+
+const clientTokenOptionKeys: ReadonlySet<string> = new Set([
+  "pathname",
+  "onUploadCompleted",
+  ...constraintKeys,
+]);
+
+const uploadAuthorizationKeys: ReadonlySet<string> = new Set([
+  "tokenPayload",
+  "callbackUrl",
+  ...constraintKeys,
+]);
+
+/**
+ * Implements {@link BlobUploads} with the store's read-write token from `BlobConfig` (client tokens
+ * and their callbacks) and `BlobConfig.webhookPublicKey` (presigned callbacks). Callback URLs are
+ * derived from `BlobConfig.callbackBaseUrl` and `VercelSystemEnv`; the time comes from `Clock`.
+ */
+export const BlobUploadsLive: Layer.Layer<BlobUploads, never, BlobConfig | VercelSystemEnv> =
+  Layer.effect(
+    BlobUploads,
+    Effect.gen(function* () {
+      const config = yield* BlobConfig;
+      const systemEnv = yield* VercelSystemEnv;
+
+      const readWriteToken = (operation: string) =>
+        Option.match(config.readWriteToken, {
+          onNone: () => Effect.fail(new BlobReadWriteTokenRequired({ operation })),
+          onSome: (token) => Effect.succeed(Redacted.value(token)),
+        });
+
+      /** The SDK's `generateClientTokenFromReadWriteToken`, over fields already in wire form. */
+      const signFields = Effect.fnUntraced(function* (
+        token: string,
+        fields: ClientTokenFields,
+        now: number,
+      ) {
+        if (contradictsIfMatch(fields)) {
+          return yield* Effect.die(new Error(ifMatchContradictionMessage));
+        }
+        const storeId = storeIdFromReadWriteToken(token);
+        if (Option.isNone(storeId)) {
+          return yield* Effect.die(new Error("Invalid `BLOB_READ_WRITE_TOKEN`"));
+        }
+        const payload = clientTokenPayloadJson(fields, now + defaultClientTokenLifetimeMillis);
+        return yield* signClientToken(token, storeId.value, payload);
+      });
+
+      const callbackUrlFor = (
+        request: HttpServerRequest.HttpServerRequest,
+        provided: string | undefined,
+        handlesCallback: boolean,
+      ) =>
+        resolveCallbackUrl({
+          provided,
+          handlesCallback,
+          derive: deriveCallbackUrl({
+            requestUrl: request.originalUrl,
+            callbackBaseUrl: config.callbackBaseUrl,
+            env: systemEnv,
+          }),
+        });
+
+      const generateClientToken = Effect.fn("BlobUploads.generateClientToken")(function* (
+        options: ClientTokenOptions,
+      ) {
+        const token = yield* readWriteToken("BlobUploads.generateClientToken");
+        const now = yield* Clock.currentTimeMillis;
+        return yield* signFields(token, wireFields(options, clientTokenOptionKeys), now);
+      });
+
+      const handler = Effect.fn("BlobUploads.handler")(function* <E, R, E2, R2>(
+        options: UploadHandlerOptions<E, R, E2, R2>,
+      ) {
+        const token = yield* readWriteToken("BlobUploads.handler");
+        const { request, event, normalizedBody } = yield* readEvent(UploadRouteEvent);
+        switch (event.type) {
+          case "blob.generate-client-token": {
+            const uploadRequest = yield* decodeOrReject(UploadRequestPayload, event.payload);
+            const authorization = yield* options.onBeforeGenerateToken(uploadRequest);
+            const tokenPayload =
+              authorization.tokenPayload ?? Option.getOrNull(uploadRequest.clientPayload);
+            const callbackUrl = yield* callbackUrlFor(
+              request,
+              authorization.callbackUrl,
+              options.onUploadCompleted !== undefined,
+            );
+            const now = yield* Clock.currentTimeMillis;
+            const validUntil =
+              authorization.validUntil === undefined
+                ? now + uploadRouteTokenLifetimeMillis
+                : DateTime.toEpochMillis(authorization.validUntil);
+            const clientToken = yield* signFields(
+              token,
+              {
+                ...wireFields(authorization, uploadAuthorizationKeys, "callbackUrl"),
+                pathname: uploadRequest.pathname,
+                onUploadCompleted: Option.match(callbackUrl, {
+                  onNone: () => undefined,
+                  onSome: (url) => ({ callbackUrl: url, tokenPayload }),
+                }),
+                validUntil,
+              },
+              now,
+            );
+            return HttpServerResponse.jsonUnsafe({ type: event.type, clientToken });
+          }
+          case "blob.upload-completed": {
+            const signature = yield* signatureOf(request);
+            const verified = yield* verifyHmacCallbackSignature(token, signature, normalizedBody);
+            if (!verified) {
+              return yield* rejected(new SignatureInvalid());
+            }
+            if (options.onUploadCompleted !== undefined) {
+              const completed = yield* decodeOrReject(UploadCompletedPayload, event.payload);
+              yield* options.onUploadCompleted(completed);
+            }
+            return HttpServerResponse.jsonUnsafe({ type: event.type, response: "ok" });
+          }
+        }
+      });
+
+      const presignedHandler = Effect.fn("BlobUploads.presignedHandler")(function* <E, R, E2, R2>(
+        options: PresignedUploadHandlerOptions<E, R, E2, R2>,
+      ) {
+        if (Option.isNone(config.webhookPublicKey)) {
+          return yield* rejected(new WebhookPublicKeyMissing());
+        }
+        const webhookPublicKey = config.webhookPublicKey.value;
+        const { request, event, normalizedBody } = yield* readEvent(PresignedRouteEvent);
+        switch (event.type) {
+          case "blob.generate-presigned-url": {
+            const uploadRequest = yield* decodeOrReject(UploadRequestPayload, event.payload);
+            const { token, urlOptions = {} } = yield* options.getSignedToken(uploadRequest);
+            const { callbackUrl: providedCallbackUrl, tokenPayload, ...putOptions } = urlOptions;
+            const callbackTokenPayload =
+              tokenPayload ?? Option.getOrUndefined(uploadRequest.clientPayload);
+            const callbackUrl = yield* callbackUrlFor(
+              request,
+              providedCallbackUrl,
+              options.onUploadCompleted !== undefined,
+            );
+            const payload = yield* presignPayload(
+              token,
+              {
+                ...putOptions,
+                onUploadCompleted: Option.match(callbackUrl, {
+                  onNone: () => undefined,
+                  onSome: (url) => ({ callbackUrl: url, tokenPayload: callbackTokenPayload }),
+                }),
+                operation: "put",
+                pathname: uploadRequest.pathname,
+              },
+              yield* Clock.currentTimeMillis,
+            );
+            return HttpServerResponse.jsonUnsafe({
+              type: event.type,
+              presignedUrlPayload: {
+                delegationToken: payload.delegationToken,
+                signature: payload.signature,
+                params: payload.params,
+              },
+            });
+          }
+          case "blob.upload-completed": {
+            const signature = yield* signatureOf(request);
+            const verified = yield* verifyEd25519CallbackSignature(
+              webhookPublicKey,
+              signature,
+              normalizedBody,
+            );
+            if (!verified) {
+              return yield* rejected(new SignatureInvalid());
+            }
+            if (options.onUploadCompleted !== undefined) {
+              const completed = yield* decodeOrReject(UploadCompletedPayload, event.payload);
+              yield* options.onUploadCompleted(completed);
+            }
+            return HttpServerResponse.jsonUnsafe({ type: event.type, response: "ok" });
+          }
+        }
+      });
+
+      return BlobUploads.of({ generateClientToken, handler, presignedHandler });
+    }),
+  );

package/src/index.ts

@@ -0,0 +1,18 @@
+export * from "./contracts/blob-config.ts";
+export * from "./contracts/blob-domain.ts";
+export * from "./contracts/blob-errors.ts";
+export * from "./contracts/blob-signed-urls.ts";
+export * from "./contracts/blob-store.ts";
+export * from "./contracts/blob-uploads.ts";
+export {
+  type BlobConfigOptions,
+  BlobConfigLive,
+  blobConfigLayer,
+} from "./implementation/blob-config-live.ts";
+export { storeIdFromDelegationToken } from "./internal/store-id.ts";
+export { downloadUrl } from "./internal/urls.ts";
+export { BlobStoreLive } from "./implementation/blob-store-live.ts";
+export { BlobSignedUrlsLive } from "./implementation/blob-signed-urls-live.ts";
+export { BlobUploadsLive } from "./implementation/blob-uploads-live.ts";
+export { ClientTokenPayload, getPayloadFromClientToken } from "./internal/client-token.ts";
+export { BlobLive } from "./implementation/blob-live.ts";

package/src/internal/blob-errors.ts

@@ -0,0 +1,325 @@
+import type { Headers, HttpClientResponse } from "effect/http";
+
+import { VercelApiError, vercelApiErrorFromStatus } from "@panorama-industries/effect-vercel-core";
+import { Clock, Effect, Option, Predicate, Schema } from "effect";
+
+import {
+  BlobClientTokenNotAllowed,
+  BlobNotFound,
+  BlobOidcEnvironmentNotAllowed,
+  BlobPreconditionFailed,
+  BlobStoreNotFound,
+  BlobStoreSuspended,
+  BlobStoreUnavailable,
+  BlobUploadRejected,
+  ClientTokenExpired,
+  ContentTypeNotAllowed,
+  FileTooLarge,
+  PathnameMismatch,
+} from "../contracts/blob-errors.ts";
+
+/** Every Blob-specific failure an error response can map to. */
+export type BlobDomainError =
+  | BlobNotFound
+  | BlobStoreUnavailable
+  | BlobPreconditionFailed
+  | BlobUploadRejected
+  | BlobClientTokenNotAllowed
+  | BlobOidcEnvironmentNotAllowed;
+
+/** Tag of a {@link BlobDomainError}, used to choose which ones an operation reports. */
+export type BlobDomainErrorTag = BlobDomainError["_tag"];
+
+/** The domain errors among `K`, plus `VercelApiError` for every other error response. */
+export type BlobApiError<K extends BlobDomainErrorTag = BlobDomainErrorTag> =
+  | VercelApiError
+  | Extract<BlobDomainError, { readonly _tag: K }>;
+
+/** An error response (non-2xx) whose body has been read. */
+export interface BlobErrorResponse {
+  /** Traced operation name stored in `VercelApiError.operation`, such as `BlobStore.put`. */
+  readonly operation: string;
+
+  readonly status: number;
+
+  /** The raw response body; JSON `{"error":{"code","message"}}` when the API produced it. */
+  readonly body: string;
+
+  /** Response headers; `Retry-After` is read from them for `rate_limited`. */
+  readonly headers: Headers.Headers;
+
+  /** The pathname or URL the call addressed, stored in `BlobNotFound.locator`. */
+  readonly locator: string;
+}
+
+const ErrorBody = Schema.fromJsonString(
+  Schema.Struct({
+    error: Schema.optionalKey(
+      Schema.Struct({
+        code: Schema.optionalKey(Schema.String),
+        message: Schema.optionalKey(Schema.String),
+      }),
+    ),
+  }),
+);
+
+const decodeErrorBody = Schema.decodeUnknownOption(ErrorBody);
+
+/** What the SDK's `getBlobError` reads from an error body, after its message-based rewrites. */
+export interface BlobErrorCode {
+  /** The effective code: `unknown_error` when the body had none or was not JSON. */
+  readonly code: string;
+
+  /** The code exactly as the body sent it, if it sent one. */
+  readonly bodyCode: Option.Option<string>;
+
+  readonly message: Option.Option<string>;
+}
+
+/**
+ * Read the error code and message from an error body like the SDK's `getBlobError`, including the
+ * rewrites it applies to codes older API clients cannot receive: a message about a disallowed
+ * `contentType`, a `"pathname"` that does not match the token, `Token expired`, a file length
+ * limit, or OIDC being disabled for an environment selects the matching code.
+ */
+export const blobErrorCode = (body: string): BlobErrorCode => {
+  const error = Option.flatMap(decodeErrorBody(body), (decoded) =>
+    Option.fromUndefinedOr(decoded.error),
+  );
+  const bodyCode = Option.flatMap(error, (error) => Option.fromUndefinedOr(error.code));
+  const message = Option.flatMap(error, (error) => Option.fromUndefinedOr(error.message));
+  let code = Option.getOrElse(bodyCode, () => "unknown_error");
+  const text = Option.getOrUndefined(message);
+  if (text !== undefined) {
+    if (text.includes("contentType") && text.includes("is not allowed")) {
+      code = "content_type_not_allowed";
+    }
+    if (text.includes('"pathname"') && text.includes("does not match the token payload")) {
+      code = "client_token_pathname_mismatch";
+    }
+    if (text === "Token expired") {
+      code = "client_token_expired";
+    }
+    if (text.includes("the file length cannot be greater than")) {
+      code = "file_too_large";
+    }
+    if (
+      text.startsWith("OIDC is enabled for this project, but not for the") &&
+      text.includes("environment.")
+    ) {
+      code = "oidc_environment_not_allowed";
+    }
+  }
+  return { code, bodyCode, message };
+};
+
+const unknownErrorMessage = "Unknown error, please visit https://vercel.com/help.";
+
+/**
+ * The message the store sends with `bad_request`, instead of a dedicated code, when a key does not
+ * exist: the source of a copy or rename, or the blob an `ifMatch` write or delete targets.
+ */
+export const missingKeyMessage = "The specified key does not exist.";
+
+const domainError = (
+  code: string,
+  message: Option.Option<string>,
+  locator: string,
+): Option.Option<BlobDomainError> => {
+  const text = Option.getOrUndefined(message);
+  switch (code) {
+    case "not_found":
+      return Option.some(new BlobNotFound({ locator }));
+    case "store_not_found":
+      return Option.some(new BlobStoreUnavailable({ reason: new BlobStoreNotFound() }));
+    case "store_suspended":
+      return Option.some(new BlobStoreUnavailable({ reason: new BlobStoreSuspended() }));
+    case "precondition_failed":
+      return Option.some(new BlobPreconditionFailed());
+    case "content_type_not_allowed":
+      return Option.some(
+        new BlobUploadRejected({
+          reason: new ContentTypeNotAllowed({ message: `Content type mismatch, ${text}.` }),
+        }),
+      );
+    case "file_too_large":
+      return Option.some(
+        new BlobUploadRejected({
+          reason: new FileTooLarge({ message: `File is too large, ${text}.` }),
+        }),
+      );
+    case "client_token_pathname_mismatch":
+      return Option.some(
+        new BlobUploadRejected({
+          reason: new PathnameMismatch({
+            message:
+              `Pathname mismatch, ${text}. Check the pathname used in upload() or put() ` +
+              "matches the one from the client token.",
+          }),
+        }),
+      );
+    case "client_token_expired":
+      return Option.some(new BlobUploadRejected({ reason: new ClientTokenExpired() }));
+    case "client_token_not_allowed":
+      return Option.some(
+        new BlobClientTokenNotAllowed({
+          message:
+            text ??
+            "This operation is not available when using a client token. Use a read–write or OIDC token on the server.",
+        }),
+      );
+    case "oidc_environment_not_allowed":
+      return Option.some(
+        new BlobOidcEnvironmentNotAllowed({
+          message:
+            text ?? "OIDC is enabled for this project, but not for this token's environment.",
+        }),
+      );
+    default:
+      return Option.none();
+  }
+};
+
+const rateLimitedMessage = (headers: Headers.Headers): string => {
+  const seconds = Number.parseInt(headers["retry-after"] ?? "", 10);
+  return `Too many requests please lower the number of concurrent requests${
+    seconds ? ` - try again in ${seconds} seconds` : ""
+  }.`;
+};
+
+/**
+ * The status whose `Api*` reason the SDK's error matches, and that reason's message. Codes the SDK
+ * maps regardless of status (`forbidden`, `bad_request`, `rate_limited`) force their status; the
+ * rest keep the response's.
+ */
+const apiReasonFor = (
+  code: string,
+  response: BlobErrorResponse,
+  message: Option.Option<string>,
+): { readonly status: number; readonly message: string } => {
+  const status = response.status;
+  switch (code) {
+    case "forbidden":
+      return {
+        status: 403,
+        message: "Access denied, please provide a valid token for this resource.",
+      };
+    case "bad_request":
+      return { status: 400, message: Option.getOrElse(message, () => "Bad request") };
+    case "rate_limited":
+      return {
+        status: 429,
+        message: rateLimitedMessage(response.headers),
+      };
+    case "service_unavailable":
+      return {
+        status,
+        message: "The blob service is currently not available. Please try again.",
+      };
+    default:
+      return { status, message: Option.getOrElse(message, () => unknownErrorMessage) };
+  }
+};
+
+/**
+ * Map an error response to the failure the SDK's `getBlobError` would throw, as a typed error.
+ *
+ * Domain codes become the errors in `contracts/blob-errors.ts`; `forbidden`, `bad_request` and
+ * `rate_limited` become `VercelApiError` with `ApiForbidden`, `ApiBadRequest` and `ApiRateLimited`
+ * (with `Retry-After`) whatever the status; every other code becomes the `VercelApiError` matching
+ * the status (`vercelApiErrorFromStatus`). `VercelApiError.errorCode` is the code the body sent, if
+ * any. A domain code not listed in `domainErrors` is reported as a `VercelApiError` for its status
+ * instead, with that code, so an operation only surfaces the domain errors its contract declares.
+ *
+ * Unlike the SDK, a `bad_request` with {@link missingKeyMessage} becomes `BlobNotFound` for an
+ * operation that reports it (a missing copy or rename source), and `BlobPreconditionFailed`
+ * otherwise (`ifMatch` on a missing blob, which HTTP treats as a failed precondition).
+ *
+ * @param now - Current time in epoch milliseconds, to resolve an HTTP-date `Retry-After`.
+ * @param domainErrors - Domain errors the operation reports; all of them by default.
+ */
+export const blobErrorFromResponse = <K extends BlobDomainErrorTag = BlobDomainErrorTag>(
+  response: BlobErrorResponse,
+  now: number,
+  domainErrors?: ReadonlyArray<K>,
+): BlobApiError<K> => {
+  const { code, bodyCode, message } = blobErrorCode(response.body);
+  const reports = (tag: BlobDomainErrorTag) =>
+    domainErrors === undefined || (domainErrors as ReadonlyArray<string>).includes(tag);
+  if (code === "bad_request" && Option.getOrUndefined(message) === missingKeyMessage) {
+    if (reports("BlobNotFound")) {
+      return new BlobNotFound({ locator: response.locator }) as BlobApiError<K>;
+    }
+    if (reports("BlobPreconditionFailed")) {
+      return new BlobPreconditionFailed() as BlobApiError<K>;
+    }
+  }
+  const domain = domainError(code, message, response.locator).pipe(
+    Option.filter((error) => reports(error._tag)),
+  );
+  if (Option.isSome(domain)) {
+    return domain.value as Extract<BlobDomainError, { readonly _tag: K }>;
+  }
+  const reason = apiReasonFor(code, response, message);
+  return vercelApiErrorFromStatus(
+    {
+      operation: response.operation,
+      status: reason.status,
+      message: reason.message,
+      errorCode: bodyCode,
+      headers: response.headers,
+    },
+    now,
+  );
+};
+
+/**
+ * Read an error response's body and map it with {@link blobErrorFromResponse}. A body that cannot be
+ * read counts as not JSON (`unknown_error`).
+ */
+export const blobErrorFromHttpResponse = Effect.fnUntraced(function* <
+  K extends BlobDomainErrorTag = BlobDomainErrorTag,
+>(
+  response: HttpClientResponse.HttpClientResponse,
+  options: {
+    readonly operation: string;
+    readonly locator: string;
+    readonly domainErrors?: ReadonlyArray<K> | undefined;
+  },
+): Effect.fn.Return<never, BlobApiError<K>> {
+  const body = yield* Effect.orElseSucceed(response.text, () => "");
+  const now = yield* Clock.currentTimeMillis;
+  return yield* Effect.fail(
+    blobErrorFromResponse(
+      {
+        operation: options.operation,
+        status: response.status,
+        body,
+        headers: response.headers,
+        locator: options.locator,
+      },
+      now,
+      options.domainErrors,
+    ),
+  );
+});
+
+const retryableCodes: ReadonlySet<string> = new Set([
+  "unknown_error",
+  "service_unavailable",
+  "internal_server_error",
+]);
+
+/**
+ * Whether the SDK retries a failed attempt: network failures, and error responses whose body code
+ * is absent (a body that is not JSON counts as `unknown_error`), `unknown_error`,
+ * `service_unavailable` or `internal_server_error`. Never `rate_limited`, a domain error, or any
+ * other code. Use it as `vercelApiTransientRetry({ isRetryable })`.
+ */
+export const isRetryableBlobError = (error: unknown): boolean =>
+  error instanceof VercelApiError &&
+  (Predicate.isTagged(error.reason, "ApiNetworkFailure") ||
+    Option.match(error.errorCode, {
+      onNone: () => true,
+      onSome: (code) => retryableCodes.has(code),
+    }));