Ingestion Health — API, Data Model, Error Classification (issue 5 of 29)

[gabemontero]

Dependencies: None
RHIDP Stories: RHIDP-15335, RHIDP-15337
Feature: RHDHPLAN-1513 — Epic RHIDP-15331

Implement the ingestion health backend: boost_sync_attempts table with database migration, SyncAttemptsRepository, HealthStatusService with status derivation (healthy/degraded/failing/unknown based on last 3 attempts; unknown = zero sync attempts recorded), GET /api/boost/ingestion-health REST endpoint, and ErrorClassifier utility with actionable diagnostic guidance for auth failures, network errors, schema mismatches, and rate limits. RBAC gating (ai-catalog.admin) for this endpoint is deferred to Issue 26. The admin UI consuming this API is also in Issue 26.

Tasks

From openspec/changes/ingestion-health-dashboard/tasks.md group 1 (RHIDP-15335):

• 1.1 Define boost_sync_attempts table schema in database migration (connector_id, timestamp, outcome, error_type, error_message, assets_added/updated/removed, duration_ms)
• 1.2 Create database migration file for boost_sync_attempts table with indexes on (connector_id, timestamp DESC)
• 1.3 Implement SyncAttemptsRepository class with methods: insertSyncAttempt(), getLatestAttempts(), cleanupOldAttempts()
• 1.4 Add retention policy config schema (boost.ingestion.healthRetention.maxAttemptsPerConnector, default 100)
• 1.5 Implement scheduled cleanup job for sync attempts (daily, enforces retention)
• 1.6 Add database indexes for efficient health status queries

From openspec/changes/ingestion-health-dashboard/tasks.md group 2 (RHIDP-15335):

• 2.1 Define ConnectorHealthStatus type in plugins/boost-common/src/types/ingestion-health.ts
• 2.2 Implement GET /api/boost/ingestion-health route returning array of connector health objects
• 2.3 Implement health status derivation logic in HealthStatusService.deriveStatus(attempts) (healthy/degraded/failing/unknown based on last 3 attempts; unknown = zero sync attempts recorded)
• 2.4 Add ?includeDisabled=true query parameter support
• 2.5 Implement RBAC gating via ai-catalog.admin permission check in route handler (using permissions.authorize()) — deferred to Issue 26
• 2.6 Add structured logging for health API requests via Backstage LoggerService (full audit event emitters deferred to Issue 21 / RHIDP-15277)
• 2.7 Implement empty state handling
• 2.8 Add health API integration tests

From openspec/changes/ingestion-health-dashboard/tasks.md group 3 (RHIDP-15337):

• 3.1 Create ErrorClassifier utility class
• 3.2 Implement classify(error, options?) method returning { errorType, errorMessage, diagnosticGuidance }
• 3.3 Add auth failure detection patterns (401/403, "Invalid token", "OAuth expired")
• 3.4 Add network failure detection patterns (ECONNREFUSED, ETIMEDOUT, DNS, TLS)
• 3.5 Add schema mismatch detection patterns (JSON parsing, "Unexpected field", GraphQL)
• 3.6 Add rate limit detection patterns (429, X-RateLimit-Remaining)
• 3.7 Implement connector-specific error matchers
• 3.8 Implement unknown error fallback classification
• 3.9 Add diagnostic guidance text for each error type
• 3.10 Add error classification unit tests

Specifications

• openspec/changes/ingestion-health-dashboard/specs/health-status-api/spec.md
• openspec/changes/ingestion-health-dashboard/specs/error-classification/spec.md

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 8:00 PM UTC · Completed 8:05 PM UTC
Commit: e03b281 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Category: Feature · Severity: Medium

This issue is well-specified and ready for implementation. It covers three backend components for the ingestion health dashboard:

1. Data Model & Storage — boost_sync_attempts table with Knex migration, SyncAttemptsRepository (insert/query/cleanup), and retention policy (default 100 per connector with scheduled daily cleanup)
2. Health Status API — GET /api/boost/ingestion-health with HealthStatusService deriving status from last 3 sync attempts (healthy/degraded/failing/unknown where unknown = zero recorded attempts), ?includeDisabled query param, structured logging, and empty-state handling
3. Error Classification — ErrorClassifier utility classifying errors into auth/network/schema/rate-limit/unknown with actionable diagnostic guidance

Implementation Notes

• The boost-backend already uses Backstage DatabaseService (Knex) in existing stores (ConversationStore, McpServerStore, AdminConfigService). Follow those patterns for SyncAttemptsRepository.
• RBAC gating via ai-catalog.admin (task 2.5) is explicitly deferred to Issue 26. The permission constant itself is tracked in AI Catalog Permissions, Backend Enforcement, Conditional Rules (issue 3 of 29) #4041 (issue 3 of 29), which is still open but is not a blocker here.
• Issue Ingestion Health Admin UI and Disconnected-Cluster View (issue 26 of 29) #4064 (admin UI) consumes this API downstream.
• Detailed behavioral specs exist at openspec/changes/ingestion-health-dashboard/specs/ covering health status derivation, error classification patterns, and force-sync.

Proposed Test Cases

HealthStatusService.deriveStatus():
- 3 successful attempts → status: 'healthy'
- Mixed results (success + failure) → status: 'degraded'
- 3 failed attempts → status: 'failing'
- 0 attempts → status: 'unknown'
- 1-2 attempts → derive from available data

ErrorClassifier.classify():
- 401/403 HTTP status → errorType: 'auth', guidance: check credentials
- ECONNREFUSED/ETIMEDOUT → errorType: 'network', guidance: check connectivity
- JSON parse failure → errorType: 'schema', guidance: check API response
- 429 status → errorType: 'rate-limit', guidance: reduce sync frequency
- Unrecognized error → errorType: 'unknown', guidance: check logs

GET /api/boost/ingestion-health:
- Authorized request → 200 with connector health array
- ?includeDisabled=true → includes disabled connectors
- No connectors configured → 200 with []
- Audit log entry recorded for each request

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

Previous run

Triage Summary

Category: Feature · Severity: Medium

This issue is well-specified and ready for implementation. It covers three backend components for the ingestion health dashboard:

1. Data Model & Storage — boost_sync_attempts table with Knex migration, SyncAttemptsRepository (insert/query/cleanup), and retention policy (default 100 per connector)
2. Health Status API — GET /api/boost/ingestion-health with HealthStatusService deriving status from last 3 sync attempts, RBAC via ai-catalog.admin, ?includeDisabled support, and audit logging
3. Error Classification — ErrorClassifier utility classifying errors into auth/network/schema/rate-limit/unknown with diagnostic guidance

Implementation Notes

• The boost-backend already uses Backstage DatabaseService (Knex) in existing stores (ConversationStore, McpServerStore, AdminConfigService). Follow those patterns for SyncAttemptsRepository.
• The ai-catalog.admin permission is being defined in AI Catalog Permissions, Backend Enforcement, Conditional Rules (issue 3 of 29) #4041 (issue 3 of 29), which is still open. If AI Catalog Permissions, Backend Enforcement, Conditional Rules (issue 3 of 29) #4041 hasn't landed when work begins, define the permission constant in boost-common/src/permissions.ts and coordinate merge order to avoid conflicts.
• Detailed behavioral specs exist at openspec/changes/ingestion-health-dashboard/specs/ covering health status derivation, error classification patterns, RBAC gating, and force-sync.
• Issue Ingestion Health Admin UI and Disconnected-Cluster View (issue 26 of 29) #4064 (admin UI) consumes this API downstream.

Proposed Test Cases

HealthStatusService.deriveStatus():
- 3 successful attempts → status: 'healthy'
- Mixed results (success + failure) → status: 'degraded'
- 3 failed attempts → status: 'failing'
- 0 attempts → status: 'unknown'
- 1-2 attempts → derive from available data

ErrorClassifier.classify():
- 401/403 HTTP status → errorType: 'auth', guidance: check credentials
- ECONNREFUSED/ETIMEDOUT → errorType: 'network', guidance: check connectivity
- JSON parse failure → errorType: 'schema', guidance: check API response
- 429 status → errorType: 'rate-limit', guidance: reduce sync frequency
- Unrecognized error → errorType: 'unknown', guidance: check logs

GET /api/boost/ingestion-health:
- Authorized request → 200 with connector health array
- Unauthorized request → 403 Forbidden
- ?includeDisabled=true → includes disabled connectors
- No connectors configured → 200 with []
- Audit log entry recorded for each request

Previous run (2)

Triage Summary

Category: Feature · Severity: Medium

This issue is well-specified and ready for implementation. It covers three backend components for the ingestion health dashboard:

1. Data Model & Storage — boost_sync_attempts table with Knex migration, SyncAttemptsRepository (insert/query/cleanup), and retention policy (default 100 per connector)
2. Health Status API — GET /api/boost/ingestion-health with HealthStatusService deriving status from last 3 sync attempts, RBAC via ai-catalog.admin, and ?includeDisabled support
3. Error Classification — ErrorClassifier utility classifying errors into auth/network/schema/rate-limit/unknown with diagnostic guidance

Implementation Notes

• The boost-backend already uses Backstage DatabaseService (Knex) in existing stores (ConversationStore, McpServerStore, AdminConfigService). Follow those patterns for SyncAttemptsRepository.
• The ai-catalog.admin permission constant is also being defined in AI Catalog Permissions, Backend Enforcement, Conditional Rules (issue 3 of 29) #4041 (issue 3 of 29). Coordinate to avoid merge conflicts — if AI Catalog Permissions, Backend Enforcement, Conditional Rules (issue 3 of 29) #4041 hasn't landed, define the permission in boost-common/src/permissions.ts as part of this work.
• Detailed behavioral specs exist at openspec/changes/ingestion-health-dashboard/specs/ covering health status derivation, error classification patterns, RBAC gating, and force-sync.

Proposed Test Cases

HealthStatusService.deriveStatus():
- 3 successful attempts → status: 'healthy'
- Mixed results (success + failure) → status: 'degraded'
- 3 failed attempts → status: 'failing'
- 0 attempts → status: 'unknown'
- 1-2 attempts → same rules on available data

ErrorClassifier.classify():
- 401/403 HTTP status → errorType: 'auth', guidance: check credentials
- ECONNREFUSED/ETIMEDOUT → errorType: 'network', guidance: check connectivity
- JSON parse failure → errorType: 'schema', guidance: check API response
- 429 status → errorType: 'rate-limit', guidance: reduce sync frequency
- Unrecognized error → errorType: 'unknown', guidance: check logs

GET /api/boost/ingestion-health:
- Authorized request → 200 with connector health array
- Unauthorized request → 403 Forbidden
- ?includeDisabled=true → includes disabled connectors
- No connectors configured → 200 with []

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 7:30 PM UTC · Completed 7:34 PM UTC
Commit: 1b270c9 · View workflow run →

[fullsend-ai-triage]

🤖 Finished Triage · ❌ Failure · Started 8:26 PM UTC · Completed 8:29 PM UTC
Commit: f089b0c · View workflow run →