monday_ruby 1.0.0 → 1.2.0

data/docs/explanation/best-practices/errors.md

@@ -0,0 +1,478 @@
+# Error Handling Best Practices
+
+Error handling is a critical aspect of building resilient applications that integrate with external APIs. This guide explores the philosophy and patterns for effective error handling when using the monday_ruby gem.
+
+## Error Handling Philosophy
+
+In Ruby, exceptions are the primary mechanism for handling error conditions. The monday_ruby gem embraces this philosophy by providing a rich exception hierarchy that maps to specific API error conditions. This approach follows the principle that **errors should be specific enough to make informed decisions about recovery, but not so granular that they become burdensome to handle**.
+
+The alternative—using status codes or error objects—would require checking return values after every API call, leading to verbose, error-prone code. Ruby's exception model allows your "happy path" code to remain clean while still providing robust error handling when needed.
+
+## Why Specific Exception Types Matter
+
+The monday_ruby gem provides specific exception classes for different error conditions:
+
+```ruby
+Monday::AuthorizationError   # Authentication/authorization failures
+Monday::InvalidRequestError   # Malformed requests
+Monday::ResourceNotFoundError # Missing resources
+Monday::ComplexityError       # Query complexity exceeded
+```
+
+**Why not just catch a generic `Monday::Error`?** Specific exceptions enable different recovery strategies:
+
+- **AuthorizationError**: Might indicate expired credentials → refresh token or prompt re-authentication
+- **ComplexityError**: Query too complex → simplify query or retry with pagination
+- **ResourceNotFoundError**: Item deleted → remove from local cache or skip processing
+- **InvalidRequestError**: Programming error → log for debugging, don't retry
+
+Using specific exceptions makes your intent clear and prevents accidentally catching unrelated errors.
+
+## When to Rescue Specific Errors vs Base Classes
+
+The decision of which exception level to catch depends on your recovery strategy:
+
+### Catch Specific Exceptions When:
+
+```ruby
+begin
+  client.item.query(ids: [item_id])
+rescue Monday::ResourceNotFoundError
+  # Specific recovery: remove from local database
+  Item.find_by(monday_id: item_id)&.destroy
+rescue Monday::AuthorizationError
+  # Specific recovery: refresh credentials
+  refresh_monday_token
+  retry
+end
+```
+
+This approach is best when **different errors require different recovery actions**.
+
+### Catch Base Exception When:
+
+```ruby
+begin
+  client.board.query(ids: [board_id])
+rescue Monday::Error => e
+  # Generic recovery: log and notify
+  logger.error("Monday API error: #{e.message}")
+  notify_monitoring_system(e)
+  nil # Return nil to allow graceful degradation
+end
+```
+
+This approach is best when **all API errors should be handled the same way** (logging, monitoring, graceful failure).
+
+### Catch at Multiple Levels:
+
+```ruby
+begin
+  sync_monday_data
+rescue Monday::ComplexityError
+  # Specific: wait and retry
+  sleep(60)
+  retry
+rescue Monday::Error => e
+  # Catch-all: log and fail gracefully
+  logger.error("Sync failed: #{e.message}")
+  false
+end
+```
+
+This pattern handles specific cases specially while catching all other API errors generically.
+
+## Error Recovery Patterns
+
+### 1. Immediate Retry (Transient Errors)
+
+Some errors are transient—temporary network issues, service hiccups. These warrant immediate retry:
+
+```ruby
+def fetch_with_retry(max_attempts: 3)
+  attempts = 0
+  begin
+    attempts += 1
+    client.board.query(ids: [board_id])
+  rescue Monday::InternalServerError, Monday::ServiceUnavailableError
+    retry if attempts < max_attempts
+    raise
+  end
+end
+```
+
+**When to use**: Network timeouts, 5xx errors, temporary service issues.
+
+**Trade-off**: Immediate retries can compound problems during outages. Use sparingly.
+
+### 2. Exponential Backoff (Rate Limiting)
+
+Rate limit errors should be retried with increasing delays:
+
+```ruby
+def fetch_with_backoff(max_attempts: 5)
+  attempts = 0
+  begin
+    attempts += 1
+    client.item.query(ids: item_ids)
+  rescue Monday::ComplexityError => e
+    wait_time = 2 ** attempts  # 2, 4, 8, 16, 32 seconds
+    sleep(wait_time)
+    retry if attempts < max_attempts
+    raise
+  end
+end
+```
+
+**Why exponential**: Linear backoff (1s, 2s, 3s) doesn't reduce load enough. Exponential backoff gives the service time to recover.
+
+**Trade-off**: Long waits can impact user experience. Consider background processing for retries.
+
+### 3. Circuit Breaker (Cascading Failures)
+
+When an API is consistently failing, stop making requests to prevent cascading failures:
+
+```ruby
+class MondayCircuitBreaker
+  def initialize(failure_threshold: 5, timeout: 60)
+    @failure_count = 0
+    @failure_threshold = failure_threshold
+    @timeout = timeout
+    @opened_at = nil
+  end
+
+  def call
+    raise CircuitOpenError if circuit_open?
+
+    begin
+      result = yield
+      reset_failures
+      result
+    rescue Monday::Error => e
+      record_failure
+      raise
+    end
+  end
+
+  private
+
+  def circuit_open?
+    @failure_count >= @failure_threshold &&
+      (@opened_at.nil? || Time.now - @opened_at < @timeout)
+  end
+
+  def record_failure
+    @failure_count += 1
+    @opened_at = Time.now if @failure_count == @failure_threshold
+  end
+
+  def reset_failures
+    @failure_count = 0
+    @opened_at = nil
+  end
+end
+```
+
+**When to use**: High-traffic applications where API failures could cascade to other systems.
+
+**Trade-off**: Adds complexity. May reject requests even when service has recovered.
+
+### 4. Graceful Degradation
+
+Instead of failing completely, provide reduced functionality:
+
+```ruby
+def get_board_data(board_id)
+  begin
+    client.board.query(ids: [board_id])
+  rescue Monday::Error => e
+    logger.warn("Failed to fetch live data: #{e.message}")
+    # Fall back to cached data
+    Rails.cache.read("board_#{board_id}")
+  end
+end
+```
+
+**When to use**: User-facing features where some data is better than no data.
+
+**Trade-off**: Users get stale data. Must communicate data freshness clearly.
+
+## Retry Strategies: When and How Many Times
+
+**How many retries?**
+- **Transient errors**: 2-3 retries (network blips are usually brief)
+- **Rate limiting**: 5-7 retries (may need multiple backoff intervals)
+- **Service outages**: 0-1 retries (unlikely to resolve quickly)
+
+**When not to retry:**
+- `InvalidRequestError`: The request is malformed; retrying won't help
+- `AuthorizationError`: Credentials are invalid; retry only after refreshing
+- `ResourceNotFoundError`: The resource doesn't exist; retrying won't create it
+
+**Retry budgets**: Consider a total time budget rather than retry count:
+
+```ruby
+def fetch_with_budget(timeout: 30)
+  deadline = Time.now + timeout
+  attempts = 0
+
+  begin
+    attempts += 1
+    client.board.query(ids: [board_id])
+  rescue Monday::ComplexityError
+    wait_time = 2 ** attempts
+    raise if Time.now + wait_time > deadline
+    sleep(wait_time)
+    retry
+  end
+end
+```
+
+## Logging Errors for Debugging and Monitoring
+
+Effective logging balances detail with signal-to-noise ratio.
+
+### What to Log
+
+**Always log:**
+- Exception class and message
+- Request details (endpoint, parameters—except secrets)
+- Context (user ID, board ID, operation being performed)
+- Timestamp and correlation ID
+
+```ruby
+begin
+  client.item.create(board_id: board_id, item_name: name)
+rescue Monday::Error => e
+  logger.error({
+    error_class: e.class.name,
+    error_message: e.message,
+    operation: 'create_item',
+    board_id: board_id,
+    item_name: name,
+    user_id: current_user.id,
+    correlation_id: request_id
+  }.to_json)
+  raise
+end
+```
+
+**Don't log:**
+- API tokens or credentials
+- Sensitive user data (unless required for compliance)
+- Full response bodies (unless debugging a specific issue)
+
+### Log Levels
+
+- **ERROR**: Unexpected failures that impact functionality
+- **WARN**: Handled errors (graceful degradation, retries that succeed)
+- **INFO**: Normal API errors that are part of business logic (e.g., validation failures)
+- **DEBUG**: Full request/response details (disable in production)
+
+```ruby
+rescue Monday::ResourceNotFoundError => e
+  logger.info("Item not found, skipping: #{item_id}")  # Expected condition
+  nil
+rescue Monday::InternalServerError => e
+  logger.error("Monday API error: #{e.message}")  # Unexpected failure
+  raise
+```
+
+## User-Facing vs Internal Error Messages
+
+Exception messages serve two audiences:
+
+### Internal Messages (for developers/logs)
+
+Include technical details:
+```ruby
+"Failed to create item: ComplexityError - Query complexity exceeds limit (60/58).
+Reduce query fields or implement pagination."
+```
+
+### User-Facing Messages (for end users)
+
+Be generic and actionable:
+```ruby
+begin
+  client.item.create(...)
+rescue Monday::ComplexityError
+  flash[:error] = "The operation is too complex. Please try creating fewer items at once."
+rescue Monday::Error
+  flash[:error] = "We couldn't complete this action. Please try again later."
+end
+```
+
+**Why separate them?**
+- Users don't need technical details
+- Exposing internal errors can be a security risk
+- User messages should suggest solutions, not explain implementation
+
+## Graceful Degradation Patterns
+
+Graceful degradation means providing partial functionality when full functionality fails.
+
+### Pattern 1: Cache Fallback
+
+```ruby
+def get_board_items(board_id)
+  begin
+    items = client.item.query_by_board(board_id: board_id)
+    Rails.cache.write("board_items_#{board_id}", items, expires_in: 1.hour)
+    items
+  rescue Monday::Error => e
+    logger.warn("API failed, using cache: #{e.message}")
+    Rails.cache.read("board_items_#{board_id}") || []
+  end
+end
+```
+
+### Pattern 2: Feature Toggle
+
+```ruby
+def sync_monday_data
+  client.board.query(...)
+rescue Monday::Error => e
+  logger.error("Sync failed: #{e.message}")
+  disable_monday_sync_feature!
+  notify_admins
+end
+```
+
+### Pattern 3: Partial Success
+
+```ruby
+def sync_multiple_boards(board_ids)
+  results = { success: [], failed: [] }
+
+  board_ids.each do |board_id|
+    begin
+      sync_board(board_id)
+      results[:success] << board_id
+    rescue Monday::Error => e
+      logger.error("Board #{board_id} sync failed: #{e.message}")
+      results[:failed] << board_id
+    end
+  end
+
+  results
+end
+```
+
+**Trade-offs**: Users may not notice degraded functionality, leading to confusion. Always communicate what's working and what's not.
+
+## Transaction-Like Error Handling
+
+APIs don't support transactions like databases, but you can implement transaction-like patterns:
+
+### Pattern 1: Compensation (Undo on Error)
+
+```ruby
+def create_board_with_items(board_name, items)
+  board = nil
+
+  begin
+    board = client.board.create(board_name: board_name).dig('data', 'create_board')
+
+    items.each do |item|
+      client.item.create(board_id: board['id'], item_name: item['name'])
+    end
+
+    board
+  rescue Monday::Error => e
+    # Compensate: delete the board if item creation failed
+    client.board.delete(board_id: board['id']) if board
+    raise
+  end
+end
+```
+
+### Pattern 2: All-or-Nothing (Validate First)
+
+```ruby
+def bulk_update_items(updates)
+  # Validate all updates first
+  updates.each do |update|
+    validate_update!(update)
+  end
+
+  # If validation passes, perform updates
+  updates.map do |update|
+    client.item.update(item_id: update[:id], column_values: update[:values])
+  end
+rescue Monday::Error => e
+  logger.error("Bulk update failed, no changes made: #{e.message}")
+  raise
+end
+```
+
+**Limitation**: Between validation and execution, state can change. True atomicity isn't possible with APIs.
+
+## Testing Error Scenarios
+
+Error handling code is only as good as its tests.
+
+### Test Each Error Type
+
+```ruby
+RSpec.describe 'error handling' do
+  it 'retries on complexity errors' do
+    allow(client).to receive(:make_request)
+      .and_raise(Monday::ComplexityError)
+      .exactly(3).times
+      .and_return(mock_response)
+
+    result = fetch_with_retry
+    expect(result).to eq(mock_response)
+  end
+
+  it 'does not retry on invalid request errors' do
+    allow(client).to receive(:make_request)
+      .and_raise(Monday::InvalidRequestError)
+
+    expect { fetch_with_retry }.to raise_error(Monday::InvalidRequestError)
+  end
+end
+```
+
+### Test Retry Logic
+
+```ruby
+it 'implements exponential backoff' do
+  allow(client).to receive(:make_request)
+    .and_raise(Monday::ComplexityError)
+
+  expect(self).to receive(:sleep).with(2)
+  expect(self).to receive(:sleep).with(4)
+  expect(self).to receive(:sleep).with(8)
+
+  expect { fetch_with_backoff(max_attempts: 4) }
+    .to raise_error(Monday::ComplexityError)
+end
+```
+
+### Test Graceful Degradation
+
+```ruby
+it 'falls back to cache on error' do
+  allow(client).to receive(:make_request)
+    .and_raise(Monday::InternalServerError)
+
+  Rails.cache.write('board_123', cached_data)
+
+  result = get_board_data(123)
+  expect(result).to eq(cached_data)
+end
+```
+
+## Key Takeaways
+
+1. **Be specific**: Use specific exception types to enable targeted recovery
+2. **Retry wisely**: Use exponential backoff for rate limits, limited retries for transient errors
+3. **Fail gracefully**: Provide reduced functionality when possible
+4. **Log thoughtfully**: Include context for debugging, but protect sensitive data
+5. **Separate concerns**: Internal errors ≠ user-facing messages
+6. **Test thoroughly**: Error handling code needs tests too
+7. **Monitor**: Track error rates to identify patterns and systemic issues
+
+Error handling is not just about preventing crashes—it's about creating resilient systems that degrade gracefully and recover automatically when possible.