mirror of
https://github.com/samiyev/puaros.git
synced 2025-12-28 15:26:53 +05:00
feat(ipuaro): add error handling matrix and ErrorHandler service
Implemented comprehensive error handling system according to v0.16.0 roadmap: - ERROR_MATRIX with 9 error types (redis, parse, llm, file, command, conflict, validation, timeout, unknown) - Enhanced IpuaroError with options, defaultOption, context properties - New methods: getMeta(), hasOption(), toDisplayString() - ErrorHandler service with handle(), wrap(), withRetry() methods - Utility functions: getErrorOptions(), isRecoverableError(), toIpuaroError() - 59 new tests (27 for IpuaroError, 32 for ErrorHandler) - Coverage maintained at 97.59% Breaking changes: - IpuaroError constructor signature changed to (type, message, options?) - ErrorChoice deprecated in favor of ErrorOption
This commit is contained in:
imfozilbek
295
packages/ipuaro/src/shared/errors/ErrorHandler.ts
Normal file
295
packages/ipuaro/src/shared/errors/ErrorHandler.ts
Normal file
@@ -0,0 +1,295 @@
|
||||
/**
|
||||
* ErrorHandler service for handling errors with user interaction.
|
||||
* Implements the error handling matrix from ROADMAP.md.
|
||||
*/
|
||||
|
||||
import { ERROR_MATRIX, type ErrorOption, type ErrorType, IpuaroError } from "./IpuaroError.js"
|
||||
|
||||
/**
|
||||
* Result of error handling.
|
||||
*/
|
||||
export interface ErrorHandlingResult {
|
||||
action: ErrorOption
|
||||
shouldContinue: boolean
|
||||
retryCount?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Callback for requesting user choice on error.
|
||||
*/
|
||||
export type ErrorChoiceCallback = (
|
||||
error: IpuaroError,
|
||||
availableOptions: ErrorOption[],
|
||||
defaultOption: ErrorOption,
|
||||
) => Promise<ErrorOption>
|
||||
|
||||
/**
|
||||
* Options for ErrorHandler.
|
||||
*/
|
||||
export interface ErrorHandlerOptions {
|
||||
maxRetries?: number
|
||||
autoSkipParseErrors?: boolean
|
||||
autoRetryLLMErrors?: boolean
|
||||
onError?: ErrorChoiceCallback
|
||||
}
|
||||
|
||||
const DEFAULT_MAX_RETRIES = 3
|
||||
|
||||
/**
|
||||
* Error handler service with matrix-based logic.
|
||||
*/
|
||||
export class ErrorHandler {
|
||||
private readonly maxRetries: number
|
||||
private readonly autoSkipParseErrors: boolean
|
||||
private readonly autoRetryLLMErrors: boolean
|
||||
private readonly onError?: ErrorChoiceCallback
|
||||
|
||||
private readonly retryCounters = new Map<string, number>()
|
||||
|
||||
constructor(options: ErrorHandlerOptions = {}) {
|
||||
this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES
|
||||
this.autoSkipParseErrors = options.autoSkipParseErrors ?? true
|
||||
this.autoRetryLLMErrors = options.autoRetryLLMErrors ?? false
|
||||
this.onError = options.onError
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle an error and determine the action to take.
|
||||
*/
|
||||
async handle(error: IpuaroError, contextKey?: string): Promise<ErrorHandlingResult> {
|
||||
const key = contextKey ?? error.message
|
||||
const currentRetries = this.retryCounters.get(key) ?? 0
|
||||
|
||||
if (this.shouldAutoHandle(error)) {
|
||||
const autoAction = this.getAutoAction(error, currentRetries)
|
||||
if (autoAction) {
|
||||
return this.createResult(autoAction, key, currentRetries)
|
||||
}
|
||||
}
|
||||
|
||||
if (!error.recoverable) {
|
||||
return {
|
||||
action: "abort",
|
||||
shouldContinue: false,
|
||||
}
|
||||
}
|
||||
|
||||
if (this.onError) {
|
||||
const choice = await this.onError(error, error.options, error.defaultOption)
|
||||
return this.createResult(choice, key, currentRetries)
|
||||
}
|
||||
|
||||
return this.createResult(error.defaultOption, key, currentRetries)
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle an error synchronously with default behavior.
|
||||
*/
|
||||
handleSync(error: IpuaroError, contextKey?: string): ErrorHandlingResult {
|
||||
const key = contextKey ?? error.message
|
||||
const currentRetries = this.retryCounters.get(key) ?? 0
|
||||
|
||||
if (this.shouldAutoHandle(error)) {
|
||||
const autoAction = this.getAutoAction(error, currentRetries)
|
||||
if (autoAction) {
|
||||
return this.createResult(autoAction, key, currentRetries)
|
||||
}
|
||||
}
|
||||
|
||||
if (!error.recoverable) {
|
||||
return {
|
||||
action: "abort",
|
||||
shouldContinue: false,
|
||||
}
|
||||
}
|
||||
|
||||
return this.createResult(error.defaultOption, key, currentRetries)
|
||||
}
|
||||
|
||||
/**
|
||||
* Reset retry counters.
|
||||
*/
|
||||
resetRetries(contextKey?: string): void {
|
||||
if (contextKey) {
|
||||
this.retryCounters.delete(contextKey)
|
||||
} else {
|
||||
this.retryCounters.clear()
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get retry count for a context.
|
||||
*/
|
||||
getRetryCount(contextKey: string): number {
|
||||
return this.retryCounters.get(contextKey) ?? 0
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if max retries exceeded for a context.
|
||||
*/
|
||||
isMaxRetriesExceeded(contextKey: string): boolean {
|
||||
return this.getRetryCount(contextKey) >= this.maxRetries
|
||||
}
|
||||
|
||||
/**
|
||||
* Wrap a function with error handling.
|
||||
*/
|
||||
async wrap<T>(
|
||||
fn: () => Promise<T>,
|
||||
errorType: ErrorType,
|
||||
contextKey?: string,
|
||||
): Promise<{ success: true; data: T } | { success: false; result: ErrorHandlingResult }> {
|
||||
try {
|
||||
const data = await fn()
|
||||
if (contextKey) {
|
||||
this.resetRetries(contextKey)
|
||||
}
|
||||
return { success: true, data }
|
||||
} catch (err) {
|
||||
const error =
|
||||
err instanceof IpuaroError
|
||||
? err
|
||||
: new IpuaroError(errorType, err instanceof Error ? err.message : String(err))
|
||||
|
||||
const result = await this.handle(error, contextKey)
|
||||
return { success: false, result }
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Wrap a function with retry logic.
|
||||
*/
|
||||
async withRetry<T>(fn: () => Promise<T>, errorType: ErrorType, contextKey: string): Promise<T> {
|
||||
const key = contextKey
|
||||
|
||||
while (!this.isMaxRetriesExceeded(key)) {
|
||||
try {
|
||||
const result = await fn()
|
||||
this.resetRetries(key)
|
||||
return result
|
||||
} catch (err) {
|
||||
const error =
|
||||
err instanceof IpuaroError
|
||||
? err
|
||||
: new IpuaroError(
|
||||
errorType,
|
||||
err instanceof Error ? err.message : String(err),
|
||||
)
|
||||
|
||||
const handlingResult = await this.handle(error, key)
|
||||
|
||||
if (handlingResult.action !== "retry" || !handlingResult.shouldContinue) {
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
throw new IpuaroError(
|
||||
errorType,
|
||||
`Max retries (${String(this.maxRetries)}) exceeded for: ${key}`,
|
||||
)
|
||||
}
|
||||
|
||||
private shouldAutoHandle(error: IpuaroError): boolean {
|
||||
if (error.type === "parse" && this.autoSkipParseErrors) {
|
||||
return true
|
||||
}
|
||||
if ((error.type === "llm" || error.type === "timeout") && this.autoRetryLLMErrors) {
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
private getAutoAction(error: IpuaroError, currentRetries: number): ErrorOption | null {
|
||||
if (error.type === "parse" && this.autoSkipParseErrors) {
|
||||
return "skip"
|
||||
}
|
||||
|
||||
if ((error.type === "llm" || error.type === "timeout") && this.autoRetryLLMErrors) {
|
||||
if (currentRetries < this.maxRetries) {
|
||||
return "retry"
|
||||
}
|
||||
return "abort"
|
||||
}
|
||||
|
||||
return null
|
||||
}
|
||||
|
||||
private createResult(
|
||||
action: ErrorOption,
|
||||
key: string,
|
||||
currentRetries: number,
|
||||
): ErrorHandlingResult {
|
||||
if (action === "retry") {
|
||||
this.retryCounters.set(key, currentRetries + 1)
|
||||
const newRetryCount = currentRetries + 1
|
||||
|
||||
if (newRetryCount > this.maxRetries) {
|
||||
return {
|
||||
action: "abort",
|
||||
shouldContinue: false,
|
||||
retryCount: newRetryCount,
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
action: "retry",
|
||||
shouldContinue: true,
|
||||
retryCount: newRetryCount,
|
||||
}
|
||||
}
|
||||
|
||||
this.retryCounters.delete(key)
|
||||
|
||||
return {
|
||||
action,
|
||||
shouldContinue: action === "skip" || action === "confirm" || action === "regenerate",
|
||||
retryCount: currentRetries,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get available options for an error type.
|
||||
*/
|
||||
export function getErrorOptions(errorType: ErrorType): ErrorOption[] {
|
||||
return ERROR_MATRIX[errorType].options
|
||||
}
|
||||
|
||||
/**
|
||||
* Get default option for an error type.
|
||||
*/
|
||||
export function getDefaultErrorOption(errorType: ErrorType): ErrorOption {
|
||||
return ERROR_MATRIX[errorType].defaultOption
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if an error type is recoverable by default.
|
||||
*/
|
||||
export function isRecoverableError(errorType: ErrorType): boolean {
|
||||
return ERROR_MATRIX[errorType].recoverable
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert any error to IpuaroError.
|
||||
*/
|
||||
export function toIpuaroError(error: unknown, defaultType: ErrorType = "unknown"): IpuaroError {
|
||||
if (error instanceof IpuaroError) {
|
||||
return error
|
||||
}
|
||||
|
||||
if (error instanceof Error) {
|
||||
return new IpuaroError(defaultType, error.message, {
|
||||
context: { originalError: error.name },
|
||||
})
|
||||
}
|
||||
|
||||
return new IpuaroError(defaultType, String(error))
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a default ErrorHandler instance.
|
||||
*/
|
||||
export function createErrorHandler(options?: ErrorHandlerOptions): ErrorHandler {
|
||||
return new ErrorHandler(options)
|
||||
}
|
||||
@@ -12,6 +12,72 @@ export type ErrorType =
|
||||
| "timeout"
|
||||
| "unknown"
|
||||
|
||||
/**
|
||||
* Available options for error recovery.
|
||||
*/
|
||||
export type ErrorOption = "retry" | "skip" | "abort" | "confirm" | "regenerate"
|
||||
|
||||
/**
|
||||
* Error metadata with available options.
|
||||
*/
|
||||
export interface ErrorMeta {
|
||||
type: ErrorType
|
||||
recoverable: boolean
|
||||
options: ErrorOption[]
|
||||
defaultOption: ErrorOption
|
||||
}
|
||||
|
||||
/**
|
||||
* Error handling matrix - defines behavior for each error type.
|
||||
*/
|
||||
export const ERROR_MATRIX: Record<ErrorType, Omit<ErrorMeta, "type">> = {
|
||||
redis: {
|
||||
recoverable: false,
|
||||
options: ["retry", "abort"],
|
||||
defaultOption: "abort",
|
||||
},
|
||||
parse: {
|
||||
recoverable: true,
|
||||
options: ["skip", "abort"],
|
||||
defaultOption: "skip",
|
||||
},
|
||||
llm: {
|
||||
recoverable: true,
|
||||
options: ["retry", "skip", "abort"],
|
||||
defaultOption: "retry",
|
||||
},
|
||||
file: {
|
||||
recoverable: true,
|
||||
options: ["skip", "abort"],
|
||||
defaultOption: "skip",
|
||||
},
|
||||
command: {
|
||||
recoverable: true,
|
||||
options: ["confirm", "skip", "abort"],
|
||||
defaultOption: "confirm",
|
||||
},
|
||||
conflict: {
|
||||
recoverable: true,
|
||||
options: ["skip", "regenerate", "abort"],
|
||||
defaultOption: "skip",
|
||||
},
|
||||
validation: {
|
||||
recoverable: true,
|
||||
options: ["skip", "abort"],
|
||||
defaultOption: "skip",
|
||||
},
|
||||
timeout: {
|
||||
recoverable: true,
|
||||
options: ["retry", "skip", "abort"],
|
||||
defaultOption: "retry",
|
||||
},
|
||||
unknown: {
|
||||
recoverable: false,
|
||||
options: ["abort"],
|
||||
defaultOption: "abort",
|
||||
},
|
||||
}
|
||||
|
||||
/**
|
||||
* Base error class for ipuaro.
|
||||
*/
|
||||
@@ -19,60 +85,142 @@ export class IpuaroError extends Error {
|
||||
readonly type: ErrorType
|
||||
readonly recoverable: boolean
|
||||
readonly suggestion?: string
|
||||
readonly options: ErrorOption[]
|
||||
readonly defaultOption: ErrorOption
|
||||
readonly context?: Record<string, unknown>
|
||||
|
||||
constructor(type: ErrorType, message: string, recoverable = true, suggestion?: string) {
|
||||
constructor(
|
||||
type: ErrorType,
|
||||
message: string,
|
||||
options?: {
|
||||
recoverable?: boolean
|
||||
suggestion?: string
|
||||
context?: Record<string, unknown>
|
||||
},
|
||||
) {
|
||||
super(message)
|
||||
this.name = "IpuaroError"
|
||||
this.type = type
|
||||
this.recoverable = recoverable
|
||||
this.suggestion = suggestion
|
||||
|
||||
const meta = ERROR_MATRIX[type]
|
||||
this.recoverable = options?.recoverable ?? meta.recoverable
|
||||
this.options = meta.options
|
||||
this.defaultOption = meta.defaultOption
|
||||
this.suggestion = options?.suggestion
|
||||
this.context = options?.context
|
||||
}
|
||||
|
||||
static redis(message: string): IpuaroError {
|
||||
return new IpuaroError(
|
||||
"redis",
|
||||
message,
|
||||
false,
|
||||
"Please ensure Redis is running: redis-server",
|
||||
)
|
||||
/**
|
||||
* Get error metadata.
|
||||
*/
|
||||
getMeta(): ErrorMeta {
|
||||
return {
|
||||
type: this.type,
|
||||
recoverable: this.recoverable,
|
||||
options: this.options,
|
||||
defaultOption: this.defaultOption,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if an option is available for this error.
|
||||
*/
|
||||
hasOption(option: ErrorOption): boolean {
|
||||
return this.options.includes(option)
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a formatted error message with suggestion.
|
||||
*/
|
||||
toDisplayString(): string {
|
||||
let result = `[${this.type}] ${this.message}`
|
||||
if (this.suggestion) {
|
||||
result += `\n Suggestion: ${this.suggestion}`
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
static redis(message: string, context?: Record<string, unknown>): IpuaroError {
|
||||
return new IpuaroError("redis", message, {
|
||||
suggestion: "Please ensure Redis is running: redis-server",
|
||||
context,
|
||||
})
|
||||
}
|
||||
|
||||
static parse(message: string, filePath?: string): IpuaroError {
|
||||
const msg = filePath ? `${message} in ${filePath}` : message
|
||||
return new IpuaroError("parse", msg, true, "File will be skipped")
|
||||
return new IpuaroError("parse", msg, {
|
||||
suggestion: "File will be skipped during indexing",
|
||||
context: filePath ? { filePath } : undefined,
|
||||
})
|
||||
}
|
||||
|
||||
static llm(message: string): IpuaroError {
|
||||
return new IpuaroError(
|
||||
"llm",
|
||||
message,
|
||||
true,
|
||||
"Please ensure Ollama is running and model is available",
|
||||
)
|
||||
static llm(message: string, context?: Record<string, unknown>): IpuaroError {
|
||||
return new IpuaroError("llm", message, {
|
||||
suggestion: "Please ensure Ollama is running and model is available",
|
||||
context,
|
||||
})
|
||||
}
|
||||
|
||||
static file(message: string): IpuaroError {
|
||||
return new IpuaroError("file", message, true)
|
||||
static llmTimeout(message: string): IpuaroError {
|
||||
return new IpuaroError("timeout", message, {
|
||||
suggestion: "The LLM request timed out. Try again or check Ollama status.",
|
||||
})
|
||||
}
|
||||
|
||||
static command(message: string): IpuaroError {
|
||||
return new IpuaroError("command", message, true)
|
||||
static file(message: string, filePath?: string): IpuaroError {
|
||||
return new IpuaroError("file", message, {
|
||||
suggestion: "Check if the file exists and you have permission to access it",
|
||||
context: filePath ? { filePath } : undefined,
|
||||
})
|
||||
}
|
||||
|
||||
static conflict(message: string): IpuaroError {
|
||||
return new IpuaroError(
|
||||
"conflict",
|
||||
message,
|
||||
true,
|
||||
"File was modified externally. Regenerate or skip.",
|
||||
)
|
||||
static fileNotFound(filePath: string): IpuaroError {
|
||||
return new IpuaroError("file", `File not found: ${filePath}`, {
|
||||
suggestion: "Check the file path and try again",
|
||||
context: { filePath },
|
||||
})
|
||||
}
|
||||
|
||||
static validation(message: string): IpuaroError {
|
||||
return new IpuaroError("validation", message, true)
|
||||
static command(message: string, command?: string): IpuaroError {
|
||||
return new IpuaroError("command", message, {
|
||||
suggestion: "Command requires confirmation or is not in whitelist",
|
||||
context: command ? { command } : undefined,
|
||||
})
|
||||
}
|
||||
|
||||
static timeout(message: string): IpuaroError {
|
||||
return new IpuaroError("timeout", message, true, "Try again or increase timeout")
|
||||
static commandBlacklisted(command: string): IpuaroError {
|
||||
return new IpuaroError("command", `Command is blacklisted: ${command}`, {
|
||||
recoverable: false,
|
||||
suggestion: "This command is not allowed for security reasons",
|
||||
context: { command },
|
||||
})
|
||||
}
|
||||
|
||||
static conflict(message: string, filePath?: string): IpuaroError {
|
||||
return new IpuaroError("conflict", message, {
|
||||
suggestion: "File was modified externally. Regenerate or skip the change.",
|
||||
context: filePath ? { filePath } : undefined,
|
||||
})
|
||||
}
|
||||
|
||||
static validation(message: string, field?: string): IpuaroError {
|
||||
return new IpuaroError("validation", message, {
|
||||
suggestion: "Please check the input and try again",
|
||||
context: field ? { field } : undefined,
|
||||
})
|
||||
}
|
||||
|
||||
static timeout(message: string, timeoutMs?: number): IpuaroError {
|
||||
return new IpuaroError("timeout", message, {
|
||||
suggestion: "Try again or increase the timeout value",
|
||||
context: timeoutMs ? { timeoutMs } : undefined,
|
||||
})
|
||||
}
|
||||
|
||||
static unknown(message: string, originalError?: Error): IpuaroError {
|
||||
return new IpuaroError("unknown", message, {
|
||||
context: originalError ? { originalError: originalError.message } : undefined,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,2 +1,3 @@
|
||||
// Shared errors
|
||||
export * from "./IpuaroError.js"
|
||||
export * from "./ErrorHandler.js"
|
||||
|
||||
Reference in New Issue
Block a user