/** * Copyright 2026 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ import { Span } from '@opentelemetry/api'; /** * System and network error codes mapped to CLIENT_CONNECTION_ERROR. */ export declare const connectionCodes: string[]; /** * System and client request error codes mapped to CLIENT_REQUEST_ERROR. */ export declare const requestCodes: string[]; /** * Stream and body error codes mapped to CLIENT_REQUEST_BODY_ERROR. */ export declare const requestBodyCodes: string[]; /** * Buffer error codes mapped to CLIENT_RESPONSE_DECODE_ERROR. */ export declare const decodeCodes: string[]; /** * Redirect error codes mapped to CLIENT_REDIRECT_ERROR. */ export declare const redirectCodes: string[]; /** * Generic class / constructor names that should be unwrapped to find more specific error causes. */ export declare const genericClasses: string[]; /** * Error codes indicating failures prior to network connection establishment. */ export declare const preConnectionCodes: string[]; /** * Maximum traversal depth for unwrapping nested error causes. */ export declare const DEPTH_TO_CHECK = 10; /** * Decodes binary gRPC status details (`grpc-status-details-bin`) onto the error * object if present and not yet parsed. * * @param {unknown} e - The error to inspect and populate with parsed gRPC status details. */ export declare function ensureGrpcStatusDetailsParsed(e: unknown): void; /** * Normalized `google.rpc.ErrorInfo` fields resolved from a single `ErrorInfo` source. */ export interface ResolvedErrorInfo { reason?: string; domain?: string; metadataAttributes: Record<`gcp.errors.metadata.${string}`, string>; } /** * Resolves `google.rpc.ErrorInfo` (`reason`, `domain`, and `gcp.errors.metadata.*` * attributes) in a single walk of the error and its `.cause` chain. * * At each depth, decodes binary `grpc-status-details-bin` metadata if present, then * inspects the error itself, its `errorInfo` object, each `statusDetails` entry, and * that entry's `errorInfo`. Stops at the first `ErrorInfo` source found so optional * fields omitted by an outer `ErrorInfo` are never mixed with fields from a deeper * `.cause` or another detail entry. * * @param {unknown} e - The error to inspect. * @returns {ResolvedErrorInfo} The resolved `ErrorInfo` fields, or `{metadataAttributes: {}}` * if no `ErrorInfo` is present. */ export declare function resolveErrorInfo(e: unknown): ResolvedErrorInfo; /** * Resolves google.rpc.ErrorInfo reason if present on the error or its cause chain. * Corresponds to Tier 1 in the error.type hierarchy. * * @param {unknown} e - The error to inspect. * @returns {string | undefined} The ErrorInfo reason string if found, or undefined. */ export declare function resolveErrorInfoReason(e: unknown): string | undefined; /** * Resolves google.rpc.ErrorInfo domain (e.g. 'googleapis.com') if present on the error * or its cause chain. Populates the `gcp.errors.domain` attribute. * * @param {unknown} e - The error to inspect. * @returns {string | undefined} The ErrorInfo domain string if found, or undefined. */ export declare function resolveErrorInfoDomain(e: unknown): string | undefined; /** * Resolves google.rpc.ErrorInfo metadata from the error or its cause chain as * `gcp.errors.metadata.` attributes, one per metadata entry (e.g. * `{service: 'translate.googleapis.com'}` becomes * `{'gcp.errors.metadata.service': 'translate.googleapis.com'}`). * Entries with an empty key or a non-string value are skipped. The first ErrorInfo * found is used even if it omits metadata or has no usable entries, so the attributes * never mix in metadata from a deeper cause. * * @param {unknown} e - The error to inspect. * @returns {Record<`gcp.errors.metadata.${string}`, string>} The metadata attributes, * or an empty object if the error has no ErrorInfo metadata. */ export declare function resolveErrorInfoMetadataAttributes(e: unknown): Record<`gcp.errors.metadata.${string}`, string>; /** * Resolves a server error code received from the backend service: * - For HTTP: The HTTP status code string (e.g. '400', '403', '503'). * - For gRPC: The canonical gRPC status code name in uppercase (e.g. 'PERMISSION_DENIED', 'UNAVAILABLE'). * Corresponds to Tier 2 in the error.type hierarchy. * * @param {unknown} e - The error to inspect. * @param {'grpc' | 'http'} rpcType - The RPC transport protocol. * @returns {string | undefined} The server error code string if the error came from the server, or undefined. */ export declare function resolveServerErrorCode(e: unknown, rpcType: 'grpc' | 'http'): string | undefined; /** * Resolves client-side network and operational errors to standard CLIENT_* identifiers. * Corresponds to Tier 3 in the error.type hierarchy. * * @param {unknown} e - The error to inspect. * @returns {string | undefined} The standardized CLIENT_* error type if matched, or undefined. */ export declare function resolveClientNetworkOrOperationalError(e: unknown): string | undefined; /** * Resolves a language-specific error type name (e.g. AbortError, TypeError, RangeError, CustomRpcError). * Generic wrapper types (Error, GoogleError, Object, DOMException) are excluded and unwrap e.cause. * Corresponds to Tier 4 in the error.type hierarchy. * * @param {unknown} e - The error to inspect. * @returns {string | undefined} The language-specific error class or name if found, or undefined. */ export declare function resolveLanguageSpecificErrorType(e: unknown): string | undefined; /** * Resolves the OpenTelemetry `error.type` attribute according to the 5-tier hierarchy: * 1. google.rpc.ErrorInfo.reason * 2. Specific Server Error Code (HTTP status code or gRPC status name) * 3. Client-Side Network/Operational Errors (CLIENT_* standardized strings) * 4. Language-specific error type (e.g. AbortError, RangeError, TypeError, CustomRpcError) * 5. Internal Fallback ("INTERNAL") * * @param {unknown} e - The error to classify. * @param {'grpc' | 'http'} rpcType - The RPC transport protocol. * @param {ResolvedErrorInfo} [errorInfo] - Pre-resolved `ErrorInfo` from {@link resolveErrorInfo}, * when the caller also reads `domain` or `metadataAttributes`, to avoid walking `.cause` again. * @returns {string} The resolved `error.type` value. */ export declare function resolveErrorType(e: unknown, rpcType: 'grpc' | 'http', errorInfo?: ResolvedErrorInfo): string; /** * Resolves the exception type name for a failed call. Prefers specific * exception names (e.g. `AbortError`, `TimeoutError`, `TypeError`) and * constructor names over generic `Error`, falling back to `e.name` when * the constructor is generic or `DOMException`. * * @param {unknown} e - The error or other value thrown or reported. * @returns {string} The resolved `exception.type` string. */ export declare function resolveExceptionType(e: unknown): string; /** * Resolves a Node system error code (e.g. `ECONNREFUSED`), checking the error * itself and any underlying cause attached by fallback wrapping. * * @param {unknown} e - The error to inspect. * @returns {string | undefined} The system error code string if present, or undefined. */ export declare function resolveSystemErrorCode(e: unknown): string | undefined; /** * Resolves the canonical gRPC status name for a failed call. Status 0 (OK) * and codes outside the `Status` enum are treated as absent for failed calls. * * @param {unknown} e - The error to inspect. * @returns {string | undefined} The canonical gRPC status name if present, or undefined. */ export declare function resolveRpcStatusName(e: unknown): string | undefined; /** * Reads the HTTP response status recorded on a fallback error. * * @param {unknown} e - The error to inspect. * @returns {number | undefined} The numeric HTTP status code if present, or undefined. */ export declare function resolveHttpStatusCode(e: unknown): number | undefined; /** * Resolves the transport response status code for a completed call or attempt, * recorded as `rpc.response.status_code` (gRPC) or `http.response.status_code` (HTTP). * Successful calls resolve to `OK` (gRPC) or `200` (HTTP). Failed calls resolve the * status from the error, which is undefined when the error carries no status. * * @param {'grpc' | 'http'} rpcType - The RPC transport protocol. * @param {boolean} failed - Whether the call or attempt failed. * @param {unknown} [e] - The error the call or attempt failed with, if it failed. * @returns {{rpcStatusName?: string; httpStatusCode?: number}} The gRPC status name * (gRPC) or HTTP status code (HTTP) for the transport. */ export declare function resolveResponseStatusCode(rpcType: 'grpc' | 'http', failed: boolean, e?: unknown): { rpcStatusName?: string; httpStatusCode?: number; }; /** * Determines if a failure occurred on the client side before DNS resolution * or connection establishment. * * @param {unknown} e - The error to inspect. * @returns {boolean} True if the error occurred before connection establishment. */ export declare function isPreConnectionFailure(e: unknown): boolean; /** * Resolves a human-readable description for non-Error throws, extracting * `message` if present or falling back to `String(e)`. * * @param {unknown} e - The non-Error value thrown or reported. * @returns {string} The resolved error message string. */ export declare function resolveErrorMessage(e: unknown): string; /** * Determines whether a failure is a server-side error (i.e. a server response arrived), * excluding pre-connection failures, client network/operational errors, and aborts/timeouts. * * @param {unknown} e - The error to inspect. * @param {'grpc' | 'http'} rpcType - The RPC transport protocol. * @returns {boolean} True if a server error code was resolved for the transport. */ export declare function isServerSideError(e: unknown, rpcType: 'grpc' | 'http'): boolean; /** * Safely converts a value to a JSON string without throwing exceptions on * circular references, BigInt values, or non-serializable properties. Binary data * (e.g. a Buffer or Uint8Array) is serialized as a base64 string rather than one * JSON entry per byte. * * @param {unknown} value - The value to serialize. * @returns {string | undefined} The serialized JSON string, or undefined if `value` is undefined or unserializable. */ export declare function safeJsonStringify(value: unknown): string | undefined; /** * Resolves the `response.payload` attribute: the full response payload of a call, * serialized as JSON without truncation or redaction. String payloads are returned * as-is and binary payloads (e.g. a Buffer or Uint8Array) as base64, as are binary * values nested in the response (e.g. `bytes` fields). Prefers `rawResponse`, the * unprocessed response gax provides for paginated and long-running calls (the full * page response or the raw Operation), over the processed `response`. * * @param {unknown} response - The response passed to the callback or resolved by the promise. * @param {unknown} [rawResponse] - The raw (unprocessed) response, when gax provides one. * @returns {string | undefined} The serialized payload, or undefined if there is no response. */ export declare function resolveResponsePayload(response: unknown, rawResponse?: unknown): string | undefined; /** * Resolves the `response.payload` attribute from a failed RPC attempt error: * - For HTTP REST errors translated by GAX fallback, extracts the full raw HTTP * response payload attached to the {@link GoogleError} (or a direct `response.data` * payload when usable). * - For gRPC errors, unwraps `Metadata#getMap()` so header values are serialized * as scalar strings / base64 rather than single-element arrays from `Metadata#toJSON()`, * and omits empty `Metadata` instances (such as the empty `new grpc.Metadata()` * attached by `@grpc/grpc-js` on pre-connection failures like `ECONNREFUSED`). * * @param {unknown} e - The error thrown or returned by a failed attempt. * @returns {string | undefined} The serialized response payload, or undefined if none arrived. */ export declare function resolveErrorResponsePayload(e: unknown): string | undefined; /** * Extracts the server-side error details message attached by GFE/backend on * server-side errors, checking the error and its `.cause` chain and falling * back to `e.message` when no non-empty `details` string is present. * * @param {Error} e - The server Error instance. * @returns {{message: string}} The resolved server error message. */ export declare function resolveServerExceptionDetails(e: Error): { message: string; }; /** * Resolves the `exception.message` for a failed call or attempt. Server-side Error * instances prefer the server-provided error details over the generic error message * (see `resolveServerExceptionDetails`). All other values use their `message`, or the * stringified value for non-Error throws (see `resolveErrorMessage`). * * @param {unknown} e - The error or other value thrown or reported for the call. * @param {'grpc' | 'http'} rpcType - The RPC transport protocol. * @returns {string} The resolved `exception.message` string. */ export declare function resolveExceptionMessage(e: unknown, rpcType: 'grpc' | 'http'): string; /** * Resolves the `exception.stacktrace` attribute as the natural JavaScript call stack * (`stack`) from the error (or the first non-empty `stack` along its `.cause` chain). * Raw server status details and metadata belong in L4 `response.payload`, not * `exception.stacktrace`. * * @param {unknown} e - The error or other value thrown or reported for the call. * @returns {string | undefined} The resolved `exception.stacktrace` string, if any. */ export declare function resolveExceptionStacktrace(e: unknown): string | undefined; /** * Records an `exception` span event with `exception.type` (and `exception.message` * when `includeMessage` is true, such as on low level network attempt spans). * * @param {Span} span - The span on which to record the exception event. * @param {Error} e - The error instance. * @param {'grpc' | 'http'} rpcType - The RPC transport protocol. * @param {boolean} [includeMessage=false] - Whether to include `exception.message` on the event * (true for low level network attempt spans, false for client request spans). */ export declare function recordExceptionEvent(span: Span, e: Error, rpcType: 'grpc' | 'http', includeMessage?: boolean): void;