Network Utilities and Error Handling

/**
 * Detects if client has local network connection
 * @returns OnlineStatus indicating connection state
 */
function isOnline(): OnlineStatus;

enum OnlineStatus {
  Offline = 0,
  Online = 1,
  Unknown = 2
}

import { isOnline, OnlineStatus } from "@fluidframework/driver-utils";

const status = isOnline();
if (status === OnlineStatus.Online) {
  // Proceed with network operations
} else if (status === OnlineStatus.Offline) {
  // Handle offline scenario
}

/**
 * Checks if a network/connection error can be safely retried
 * @param error - Error object to check
 * @returns true if error explicitly has canRetry: true
 */
function canRetryOnError(error: any): boolean;

/**
 * Extracts retry delay in milliseconds from error's retryAfterSeconds property
 * @param error - Error object containing retry information
 * @returns Retry delay in milliseconds or undefined
 */
function getRetryDelayFromError(error: any): number | undefined;

/**
 * Extracts retry delay in seconds from error object
 * @param error - Error object containing retry information
 * @returns Retry delay in seconds or undefined
 */
function getRetryDelaySecondsFromError(error: any): number | undefined;

/**
 * Creates appropriate error type based on retry information
 * @param message - Error message
 * @param retryInfo - Retry configuration
 * @param props - Telemetry properties
 * @returns ThrottlingError or GenericNetworkError based on retry configuration
 */
function createGenericNetworkError(
  message: string,
  retryInfo: {canRetry: boolean; retryAfterMs?: number},
  props: DriverErrorTelemetryProps
): ThrottlingError | GenericNetworkError;

/**
 * Creates non-retryable write operation errors
 * @param message - Error message
 * @param props - Telemetry properties
 * @returns NonRetryableError for write operations
 */
function createWriteError(
  message: string, 
  props: DriverErrorTelemetryProps
): NonRetryableError<string>;

/**
 * General-purpose network error with retry capability flag
 */
class GenericNetworkError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
  constructor(message: string, canRetry: boolean, props: DriverErrorTelemetryProps);
  readonly canRetry: boolean;
  readonly errorType: string;
}

/**
 * Generic base class for typed network errors
 */
class NetworkErrorBasic<T> extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
  constructor(message: string, errorType: T, canRetry: boolean, props: DriverErrorTelemetryProps);
  readonly canRetry: boolean;
  readonly errorType: T;
}

/**
 * Non-retryable network error variant
 */
class NonRetryableError<T> extends NetworkErrorBasic<T> {
  constructor(message: string, errorType: T, props: DriverErrorTelemetryProps);
  readonly canRetry: false;
}

/**
 * Retryable network error variant
 */
class RetryableError<T> extends NetworkErrorBasic<T> {
  constructor(message: string, errorType: T, props: DriverErrorTelemetryProps);
  readonly canRetry: true;
}

/**
 * Non-retryable authorization/authentication errors
 */
class AuthorizationError extends LoggingError implements IAuthorizationError, IFluidErrorBase {
  constructor(
    message: string, 
    claims?: string, 
    tenantId?: string, 
    props: DriverErrorTelemetryProps
  );
  readonly canRetry: false;
  readonly claims?: string;
  readonly tenantId?: string;
}

/**
 * Non-retryable errors indicating resource has moved
 */
class LocationRedirectionError extends LoggingError implements ILocationRedirectionError, IFluidErrorBase {
  constructor(
    message: string, 
    redirectUrl: IResolvedUrl, 
    props: DriverErrorTelemetryProps
  );
  readonly canRetry: false;
  readonly redirectUrl: IResolvedUrl;
}

/**
 * Retryable errors from service throttling (429 responses)
 */
class ThrottlingError extends LoggingError implements IThrottlingWarning, IFluidErrorBase {
  constructor(
    message: string, 
    retryAfterSeconds: number, 
    props: DriverErrorTelemetryProps
  );
  readonly canRetry: true;
  readonly retryAfterSeconds: number;
}

/**
 * Non-retryable errors when delta stream connection is forbidden
 */
class DeltaStreamConnectionForbiddenError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
  constructor(
    message: string, 
    props: DriverErrorTelemetryProps, 
    storageOnlyReason?: string
  );
  readonly canRetry: false;
  readonly storageOnlyReason?: string;
}

/**
 * Non-retryable errors for invalid schema validation
 */
class FluidInvalidSchemaError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
  constructor(message: string, props: DriverErrorTelemetryProps);
  readonly canRetry: false;
}

/**
 * Non-retryable errors for API misuse
 */
class UsageError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
  constructor(message: string);
  readonly canRetry: false;
}

/**
 * Enhanced logging for network failures with connection type detection and online status
 * @param logger - Telemetry logger instance
 * @param event - Telemetry error event
 * @param error - Optional error object for additional context
 */
function logNetworkFailure(
  logger: ITelemetryLoggerExt, 
  event: ITelemetryErrorEventExt, 
  error?: any
): void;

/**
 * Required telemetry properties for driver errors
 */
type DriverErrorTelemetryProps = ITelemetryBaseProperties & { 
  driverVersion: string | undefined 
};

import { 
  canRetryOnError, 
  createGenericNetworkError,
  getRetryDelayFromError 
} from "@fluidframework/driver-utils";

try {
  await networkOperation();
} catch (error) {
  if (canRetryOnError(error)) {
    const delay = getRetryDelayFromError(error) ?? 1000;
    setTimeout(() => retryOperation(), delay);
  } else {
    // Handle non-retryable error
    throw error;
  }
}

import { 
  createGenericNetworkError, 
  ThrottlingError 
} from "@fluidframework/driver-utils";

// Create retryable error with delay
const throttleError = createGenericNetworkError(
  "Service temporarily unavailable",
  { canRetry: true, retryAfterMs: 5000 },
  { driverVersion: "2.60.0" }
);

// Create non-retryable error
const fatalError = createGenericNetworkError(
  "Invalid credentials",
  { canRetry: false },
  { driverVersion: "2.60.0" }
);

import { isOnline, OnlineStatus } from "@fluidframework/driver-utils";

function checkConnectionAndProceed() {
  const status = isOnline();
  
  switch (status) {
    case OnlineStatus.Online:
      return proceedWithNetworkOperation();
    case OnlineStatus.Offline:
      return handleOfflineMode();
    case OnlineStatus.Unknown:
      return proceedWithCaution();
  }
}