Errors vs Exceptions: Foundations of Robust Error Handling

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

/**
 * Fail-Fast philosophy in action
 */
 
// Validate at system boundaries - fail immediately on bad input
class OrderProcessor {
    constructor(
        private readonly config: ProcessorConfig,
        private readonly paymentGateway: PaymentGateway,
        private readonly inventory: InventoryService
    ) {
        // Fail-fast: Validate configuration at construction time
        // Don't wait until processOrder() is called to discover problems
        this.validateConfig(config);
    }
    
    private validateConfig(config: ProcessorConfig): void {
        if (!config.merchantId) {
            throw new ConfigurationError('merchantId is required');
        }
        if (config.maxRetries < 0) {
            throw new ConfigurationError('maxRetries must be non-negative');
        }
        if (!config.timeoutMs || config.timeoutMs < 100) {
            throw new ConfigurationError('timeoutMs must be at least 100ms');
        }
        // All configuration problems caught at startup, not during runtime
    }
    
    async processOrder(order: Order): Promise<ProcessedOrder> {
        // Fail-fast: Validate order immediately
        this.validateOrder(order);
        
        // Fail-fast: Check inventory before charging
        const stockCheck = await this.inventory.checkAvailability(order.items);
        if (!stockCheck.allAvailable) {
            // Don't try to proceed with partial order - fail cleanly
            throw new OrderValidationError(
                'Insufficient stock for one or more items',
                { unavailableItems: stockCheck.unavailableItems }
            );
        }
        
        // Fail-fast: If payment fails, don't continue
        const payment = await this.paymentGateway.charge(order);
        if (!payment.success) {
            throw new PaymentFailedError(payment.error, payment.declineCode);
        }
        
        // Only reach here if everything succeeded
        return this.completeOrder(order, payment);
    }
    
    private validateOrder(order: Order): void {
        // Check each invariant immediately
        if (!order.id) {
            throw new InvalidOrderError('Order must have an ID');
        }
        if (!order.items || order.items.length === 0) {
            throw new InvalidOrderError('Order must have at least one item');
        }
        if (order.total <= 0) {
            throw new InvalidOrderError('Order total must be positive');
        }
        // Any invalid order is rejected immediately at the boundary
    }
}
 
// Fail-fast with assertions for internal invariants
class ShoppingCart {
    private items: Map<string, CartItem> = new Map();
    
    addItem(item: CartItem): void {
        // Precondition - caller's responsibility to provide valid item
        if (!item.productId || item.quantity <= 0) {
            throw new PreconditionError(
                'addItem requires valid productId and positive quantity'
            );
        }
        
        const existing = this.items.get(item.productId);
        if (existing) {
            existing.quantity += item.quantity;
        } else {
            this.items.set(item.productId, { ...item });
        }
        
        // Postcondition check (in development) - verify our invariants
        this.assertInvariants();
    }
    
    private assertInvariants(): void {
        // In production, these might be disabled for performance
        if (process.env.NODE_ENV !== 'production') {
            for (const [id, item] of this.items) {
                if (item.quantity <= 0) {
                    throw new InvariantViolationError(
                        `Cart invariant violated: item ${id} has non-positive quantity`
                    );
                }
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

/**
 * Defensive programming philosophy in action
 */
 
class UserProfileService {
    /**
     * Get user profile with defensive handling
     * 
     * Even though the contract says userId should be valid,
     * defensive code handles the case where it isn't.
     */
    async getProfile(userId: string | null | undefined): Promise<UserProfile> {
        // Defensive: Handle null/undefined even if contract prohibits it
        if (!userId || typeof userId !== 'string') {
            return this.getDefaultProfile();
        }
        
        try {
            const user = await this.repository.findById(userId);
            
            // Defensive: Repository might return null even on valid ID
            if (!user) {
                return this.getDefaultProfile();
            }
            
            // Defensive: User data might be corrupted/incomplete
            return this.buildProfileSafely(user);
            
        } catch (error) {
            // Defensive: Log but don't crash, return safe default
            this.logger.warn('Failed to get user profile', { userId, error });
            return this.getDefaultProfile();
        }
    }
    
    private buildProfileSafely(user: User): UserProfile {
        // Defensive: Each field has safe fallbacks
        return {
            id: user.id ?? 'unknown',
            name: user.name ?? 'Anonymous',
            email: user.email ?? '',
            avatar: user.avatar ?? '/default-avatar.png',
            // Defensive: Sanitize potentially dangerous data
            bio: this.sanitize(user.bio ?? ''),
            joinDate: this.parseDate(user.createdAt) ?? new Date(),
        };
    }
    
    private parseDate(value: unknown): Date | null {
        // Defensive: Handle various date representations
        if (!value) return null;
        if (value instanceof Date) return value;
        if (typeof value === 'string' || typeof value === 'number') {
            const date = new Date(value);
            return isNaN(date.getTime()) ? null : date;
        }
        return null;
    }
    
    private getDefaultProfile(): UserProfile {
        return {
            id: 'guest',
            name: 'Guest',
            email: '',
            avatar: '/default-avatar.png',
            bio: '',
            joinDate: new Date(),
        };
    }
}
 
 
// Defensive input handling in API layer
class UserController {
    async updateUser(req: Request): Promise<Response> {
        // Defensive: Parse body safely
        let body: unknown;
        try {
            body = await req.json();
        } catch {
            return new Response(
                JSON.stringify({ error: 'Invalid JSON body' }),
                { status: 400 }
            );
        }
        
        // Defensive: Validate body is object
        if (!body || typeof body !== 'object' || Array.isArray(body)) {
            return new Response(
                JSON.stringify({ error: 'Body must be an object' }),
                { status: 400 }
            );
        }
        
        // Defensive: Extract and sanitize each field
        const updates: Partial<User> = {};
        
        if ('name' in body && body.name !== undefined) {
            const name = String(body.name).trim();
            if (name.length > 0 && name.length <= 100) {
                updates.name = name;
            }
        }
        
        if ('email' in body && body.email !== undefined) {
            const email = String(body.email).toLowerCase().trim();
            if (this.isValidEmail(email)) {
                updates.email = email;
            }
        }
        
        // Defensive: Only proceed if we have valid updates
        if (Object.keys(updates).length === 0) {
            return new Response(
                JSON.stringify({ error: 'No valid fields to update' }),
                { status: 400 }
            );
        }
        
        // Proceed with validated, sanitized data
        const updated = await this.userService.update(req.userId, updates);
        return new Response(JSON.stringify(updated));
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

/**
 * Fail-safe philosophy in action
 */
 
// Payment processor that prioritizes not charging twice over availability
class PaymentProcessor {
    private readonly circuitBreaker: CircuitBreaker;
    
    async processPayment(payment: Payment): Promise<PaymentResult> {
        // Check if system is in safe mode due to previous failures
        if (this.circuitBreaker.isOpen()) {
            // Fail-safe: Don't attempt payment, return safe failure
            return {
                success: false,
                error: 'SAFE_MODE',
                message: 'Payment system temporarily unavailable',
                canRetry: true,
                retryAfter: this.circuitBreaker.getResetTime()
            };
        }
        
        try {
            // Begin idempotent payment attempt
            const idempotencyKey = this.generateIdempotencyKey(payment);
            
            // Check if we've already processed this
            const existing = await this.checkExistingPayment(idempotencyKey);
            if (existing) {
                // Fail-safe: Return existing result, don't double-charge
                return existing;
            }
            
            // Record intent BEFORE calling payment gateway
            await this.recordPaymentIntent(idempotencyKey, payment);
            
            // Attempt payment
            const result = await this.gateway.charge(payment);
            
            // Record outcome
            await this.recordPaymentResult(idempotencyKey, result);
            
            return result;
            
        } catch (error) {
            this.circuitBreaker.recordFailure();
            
            // Fail-safe: Don't know if payment succeeded or failed
            if (this.isAmbiguousFailure(error)) {
                // Enter safe mode: assume payment might have succeeded
                // Better to not charge twice than to charge and not know
                return {
                    success: false,
                    error: 'AMBIGUOUS_FAILURE',
                    message: 'Payment status unknown - please check before retrying',
                    canRetry: false,
                    requiresManualReview: true
                };
            }
            
            // Known failure: can safely retry
            return {
                success: false,
                error: 'GATEWAY_ERROR',
                message: error.message,
                canRetry: true
            };
        }
    }
    
    private isAmbiguousFailure(error: Error): boolean {
        // Timeout, connection reset, etc. - we don't know if the
        // payment gateway processed the charge or not
        return error.message.includes('ETIMEDOUT') ||
               error.message.includes('ECONNRESET') ||
               error.message.includes('socket hang up');
    }
}
 
 
// Database writer that prioritizes data integrity
class TransactionalWriter {
    async writeUserData(userId: string, data: UserData): Promise<WriteResult> {
        const transaction = await this.db.beginTransaction();
        
        try {
            // Write to multiple tables within transaction
            await transaction.execute(
                'UPDATE users SET name = ?, email = ? WHERE id = ?',
                [data.name, data.email, userId]
            );
            
            await transaction.execute(
                'INSERT INTO user_history (user_id, change_type, data) VALUES (?, ?, ?)',
                [userId, 'update', JSON.stringify(data)]
            );
            
            await transaction.execute(
                'UPDATE user_stats SET last_updated = NOW() WHERE user_id = ?',
                [userId]
            );
            
            // All succeeded: commit
            await transaction.commit();
            
            return { success: true };
            
        } catch (error) {
            // Fail-safe: rollback ensures we don't have partial writes
            await transaction.rollback();
            
            // Log for investigation but return clean failure
            this.logger.error('User data write failed, rolled back', {
                userId,
                error: error.message
            });
            
            return {
                success: false,
                error: 'WRITE_FAILED',
                message: 'Update failed, no changes made'
            };
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

/**
 * Graceful degradation philosophy in action
 */
 
interface ProductPageData {
    product: Product;
    recommendations?: Product[];
    reviews?: Review[];
    inventory?: InventoryInfo;
    relatedProducts?: Product[];
    priceHistory?: PricePoint[];
}
 
interface DegradationStatus {
    isComplete: boolean;
    unavailableFeatures: string[];
}
 
class ProductPageService {
    /**
     * Loads product page data with graceful degradation.
     * Core functionality (product info) must succeed.
     * Auxiliary data (recommendations, reviews) can fail.
     */
    async getProductPage(productId: string): Promise<{
        data: ProductPageData;
        status: DegradationStatus;
    }> {
        const unavailableFeatures: string[] = [];
        
        // CORE: Product info must succeed - no degradation possible
        const product = await this.productService.getById(productId);
        if (!product) {
            throw new ProductNotFoundError(productId);
        }
        
        // OPTIONAL: Load auxiliary data with fallbacks
        const [
            recommendations,
            reviews,
            inventory,
            relatedProducts,
            priceHistory
        ] = await Promise.all([
            this.loadWithFallback(
                () => this.recommendationService.getForProduct(productId),
                'recommendations',
                unavailableFeatures
            ),
            this.loadWithFallback(
                () => this.reviewService.getForProduct(productId),
                'reviews',
                unavailableFeatures
            ),
            this.loadWithFallback(
                () => this.inventoryService.check(productId),
                'inventory',
                unavailableFeatures
            ),
            this.loadWithFallback(
                () => this.catalogService.getRelated(productId),
                'relatedProducts',
                unavailableFeatures
            ),
            this.loadWithFallback(
                () => this.pricingService.getHistory(productId),
                'priceHistory',
                unavailableFeatures
            ),
        ]);
        
        return {
            data: {
                product,
                recommendations: recommendations ?? undefined,
                reviews: reviews ?? undefined,
                inventory: inventory ?? undefined,
                relatedProducts: relatedProducts ?? undefined,
                priceHistory: priceHistory ?? undefined,
            },
            status: {
                isComplete: unavailableFeatures.length === 0,
                unavailableFeatures,
            },
        };
    }
    
    private async loadWithFallback<T>(
        loader: () => Promise<T>,
        featureName: string,
        unavailableFeatures: string[]
    ): Promise<T | null> {
        try {
            return await Promise.race([
                loader(),
                this.timeout(2000)  // Don't let slow services block the page
            ]);
        } catch (error) {
            // Log but don't fail the page
            this.logger.warn(`Failed to load ${featureName}`, { error });
            unavailableFeatures.push(featureName);
            return null;
        }
    }
    
    private timeout(ms: number): Promise<never> {
        return new Promise((_, reject) => 
            setTimeout(() => reject(new Error('Timeout')), ms)
        );
    }
}
 
 
// API response with degradation status
class ProductController {
    async getProduct(req: Request): Promise<Response> {
        const { data, status } = await this.productPageService
            .getProductPage(req.params.id);
        
        // Include degradation info in response headers
        const headers = new Headers();
        
        if (!status.isComplete) {
            headers.set('X-Degraded-Response', 'true');
            headers.set(
                'X-Unavailable-Features', 
                status.unavailableFeatures.join(',')
            );
        }
        
        return new Response(JSON.stringify(data), { headers });
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

/**
 * Real-world service mixing philosophies appropriately
 */
class OrderService {
    constructor(
        private readonly config: OrderServiceConfig,
        private readonly paymentService: PaymentService,
        private readonly inventoryService: InventoryService,
        private readonly notificationService: NotificationService,
        private readonly analyticsService: AnalyticsService
    ) {
        // FAIL-FAST: Validate configuration at startup
        this.validateConfiguration(config);
    }
    
    private validateConfiguration(config: OrderServiceConfig): void {
        // Startup - fail-fast philosophy
        if (!config.paymentGatewayUrl) {
            throw new ConfigurationError('paymentGatewayUrl is required');
        }
        if (!config.inventoryServiceUrl) {
            throw new ConfigurationError('inventoryServiceUrl is required');
        }
        // Optional services don't trigger failure
        if (!config.analyticsServiceUrl) {
            this.logger.info('Analytics service not configured - will skip');
        }
    }
    
    async createOrder(request: OrderRequest): Promise<OrderResult> {
        // DEFENSIVE: Validate untrusted input
        const validationResult = this.validateOrderRequest(request);
        if (!validationResult.isValid) {
            return {
                success: false,
                error: 'VALIDATION_ERROR',
                details: validationResult.errors
            };
        }
        
        // FAIL-SAFE: Payment handling - must not double-charge
        const paymentResult = await this.processPaymentSafely(request);
        if (!paymentResult.success) {
            return {
                success: false,
                error: paymentResult.error,
                message: paymentResult.message
            };
        }
        
        // FAIL-FAST for critical path - inventory reservation
        const inventory = await this.inventoryService.reserve(
            request.items,
            paymentResult.transactionId
        );
        if (!inventory.reserved) {
            // Must compensate the payment
            await this.paymentService.refund(paymentResult.transactionId);
            throw new InventoryError('Failed to reserve inventory after payment');
        }
        
        // Create the order
        const order = await this.orderRepository.create({
            ...request,
            paymentId: paymentResult.transactionId,
            inventoryReservationId: inventory.reservationId,
            status: 'CREATED'
        });
        
        // GRACEFUL DEGRADATION: Non-critical post-order actions
        await Promise.allSettled([
            // Notification failure shouldn't fail the order
            this.notificationService.sendOrderConfirmation(order)
                .catch(e => this.logger.warn('Failed to send confirmation', e)),
            
            // Analytics failure is definitely not critical
            this.analyticsService.trackOrder(order)
                .catch(e => this.logger.debug('Analytics tracking failed', e)),
        ]);
        
        return {
            success: true,
            orderId: order.id,
            order
        };
    }
    
    private async processPaymentSafely(request: OrderRequest): Promise<PaymentResult> {
        // FAIL-SAFE philosophy for payments
        const idempotencyKey = `order-${request.customerId}-${request.timestamp}`;
        
        try {
            return await this.paymentService.charge({
                amount: request.total,
                currency: request.currency,
                customerId: request.customerId,
                idempotencyKey
            });
        } catch (error) {
            if (this.isAmbiguousPaymentError(error)) {
                // Unknown state - require manual review
                return {
                    success: false,
                    error: 'PAYMENT_AMBIGUOUS',
                    message: 'Payment status unknown - please contact support',
                    requiresReview: true
                };
            }
            
            return {
                success: false,
                error: 'PAYMENT_FAILED',
                message: error.message
            };
        }
    }
}