Skip to content

Open-source status page, incident response and uptime monitoring

4.9 KB
Raw Blame
import { Code, ConnectError } from "@connectrpc/connect";

/**
 * Error reasons for structured error handling.
 */
export const ErrorReason = {
  MONITOR_NOT_FOUND: "MONITOR_NOT_FOUND",
  MONITOR_REQUIRED: "MONITOR_REQUIRED",
  MONITOR_ID_REQUIRED: "MONITOR_ID_REQUIRED",
  MONITOR_ID_INVALID: "MONITOR_ID_INVALID",
  MONITOR_CREATE_FAILED: "MONITOR_CREATE_FAILED",
  MONITOR_UPDATE_FAILED: "MONITOR_UPDATE_FAILED",
  MONITOR_PARSE_FAILED: "MONITOR_PARSE_FAILED",
  MONITOR_RUN_CREATE_FAILED: "MONITOR_RUN_CREATE_FAILED",
  MONITOR_TRIGGER_FAILED: "MONITOR_TRIGGER_FAILED",
  MONITOR_INVALID_DATA: "MONITOR_INVALID_DATA",
  MONITOR_TYPE_MISMATCH: "MONITOR_TYPE_MISMATCH",
  RESPONSE_LOG_NOT_FOUND: "RESPONSE_LOG_NOT_FOUND",
  RESPONSE_LOGS_NOT_ENABLED: "RESPONSE_LOGS_NOT_ENABLED",
  RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED",
} as const;

export type ErrorReason = (typeof ErrorReason)[keyof typeof ErrorReason];

const DOMAIN = "openstatus.dev";

/**
 * Creates a ConnectError with structured metadata.
 *
 * This provides machine-parseable error information via metadata headers
 * while maintaining human-readable error messages.
 */
function createError(
  message: string,
  code: Code,
  reason: ErrorReason,
  metadata?: Record<string, string>,
): ConnectError {
  const headers = new Headers({
    "error-domain": DOMAIN,
    "error-reason": reason,
  });

  if (metadata) {
    for (const [key, value] of Object.entries(metadata)) {
      headers.set(`error-${key}`, value);
    }
  }

  return new ConnectError(message, code, headers);
}

/**
 * Creates a "monitor not found" error with the monitor ID in metadata.
 */
export function monitorNotFoundError(monitorId: string): ConnectError {
  return createError(
    "Monitor not found",
    Code.NotFound,
    ErrorReason.MONITOR_NOT_FOUND,
    { "monitor-id": monitorId },
  );
}

/**
 * Creates a "monitor required" error.
 */
export function monitorRequiredError(): ConnectError {
  return createError(
    "Monitor is required",
    Code.InvalidArgument,
    ErrorReason.MONITOR_REQUIRED,
  );
}

/**
 * Creates a "monitor ID required" error.
 */
export function monitorIdRequiredError(): ConnectError {
  return createError(
    "Monitor ID is required",
    Code.InvalidArgument,
    ErrorReason.MONITOR_ID_REQUIRED,
  );
}

/**
 * Creates an "invalid monitor ID" error for an id that is not a decimal integer.
 */
export function monitorIdInvalidError(monitorId: string): ConnectError {
  return createError(
    `Invalid monitor id: "${monitorId}"`,
    Code.InvalidArgument,
    ErrorReason.MONITOR_ID_INVALID,
    // Raw input may hold CR/LF, which `Headers` rejects.
    { "monitor-id": encodeURIComponent(monitorId) },
  );
}

/**
 * Creates a "trigger failed" error when no region could be reached.
 */
export function monitorTriggerFailedError(monitorId: string): ConnectError {
  return createError(
    "Failed to trigger the monitor in any region",
    Code.Unavailable,
    ErrorReason.MONITOR_TRIGGER_FAILED,
    { "monitor-id": monitorId },
  );
}

/**
 * Creates a "monitor type mismatch" error when trying to update with wrong type.
 */
export function monitorTypeMismatchError(
  monitorId: string,
  expectedType: string,
  actualType: string,
): ConnectError {
  return createError(
    `Monitor type mismatch: expected ${expectedType}, got ${actualType}`,
    Code.InvalidArgument,
    ErrorReason.MONITOR_TYPE_MISMATCH,
    {
      "monitor-id": monitorId,
      "expected-type": expectedType,
      "actual-type": actualType,
    },
  );
}

/**
 * Creates a "response log not found" error.
 */
export function responseLogNotFoundError(
  monitorId: string,
  logId: string,
): ConnectError {
  return createError(
    "Response log not found",
    Code.NotFound,
    ErrorReason.RESPONSE_LOG_NOT_FOUND,
    { "monitor-id": monitorId, "log-id": logId },
  );
}

/**
 * Creates a "response logs not enabled" error.
 */
export function responseLogsNotEnabledError(): ConnectError {
  return createError(
    "Upgrade for response logs",
    Code.PermissionDenied,
    ErrorReason.RESPONSE_LOGS_NOT_ENABLED,
  );
}

/**
 * Creates a "failed to parse monitor data" error.
 */
export function monitorParseFailedError(monitorId?: string): ConnectError {
  return createError(
    "Failed to parse monitor data",
    Code.Internal,
    ErrorReason.MONITOR_PARSE_FAILED,
    monitorId ? { "monitor-id": monitorId } : undefined,
  );
}

/**
 * Creates an "invalid monitor data" error for corrupted data.
 */
export function monitorInvalidDataError(monitorId: string): ConnectError {
  return createError(
    "Invalid monitor data, please contact support",
    Code.Internal,
    ErrorReason.MONITOR_INVALID_DATA,
    { "monitor-id": monitorId },
  );
}

/**
 * Creates a rate limit exceeded error.
 */
export function rateLimitExceededError(
  limit: number,
  current: number,
): ConnectError {
  return createError(
    "Upgrade for more checks",
    Code.ResourceExhausted,
    ErrorReason.RATE_LIMIT_EXCEEDED,
    { limit: String(limit), current: String(current) },
  );
}