feat(#4039): add boost-connector-utils shared package - #4144
feat(#4039): add boost-connector-utils shared package#4144fullsend-ai-coder[bot] wants to merge 7 commits into
Conversation
|
Important This PR includes changes that affect public-facing API. Please ensure you are adding/updating documentation for new features or behavior. Missing ChangesetsThe following package(s) are changed by this PR but do not have a changeset:
See CONTRIBUTING.md for more information about how to add changesets. Changed Packages
|
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #4144 +/- ##
==========================================
+ Coverage 58.11% 58.16% +0.04%
==========================================
Files 2422 2425 +3
Lines 96490 96608 +118
Branches 26892 26928 +36
==========================================
+ Hits 56079 56193 +114
- Misses 40168 40172 +4
Partials 243 243
*This pull request uses carry forward flags. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
|
/fs-review |
|
🤖 Finished Review · ✅ Success · Started 2:04 PM UTC · Completed 2:25 PM UTC |
ReviewFindingsMedium
Low
Previous runReviewFindingsMedium
Low
Labels: PR adds a new shared utility package for connector infrastructure in the boost workspace Previous run (2)ReviewFindingsMedium
Low
Labels: PR adds a new package under workspaces/boost/plugins/ |
fullsend-ai-review
Bot
added
requires-manual-review
|
/fs-fix |
|
🤖 Finished Fix · ✅ Success · Started 7:39 AM UTC · Completed 7:52 AM UTC |
- Remove unreachable FetchError branch in classifyConnectorError (already covered by generic retryable-code check) - Add rejectUnauthorized: true to createHttpsAgent to guard against NODE_TLS_REJECT_UNAUTHORIZED=0 leaking from dev environments - Switch ca-bundle.ts from namespace imports to named destructured imports to match existing boost workspace conventions - Update connector-shared-infrastructure design doc, tasks, proposal, and spec files to use ai-catalog.providers config root per #4069 - Fix loadCaBundle signature in docs to include logger parameter - Fix createProviderWrapper signature in docs to use ConnectorEntityProvider type and optional ctx parameter - Update exports list in design doc to include classifyConnectorError, validateConnectorStartupConfig, ValidateConnectorStartupConfigOptions, and ConnectorEntityProvider Addresses review feedback on #4144
🔧 Fix agent — iteration 1 (human-triggered)Addressed 11 of 14 review findings: removed dead FetchError branch, added rejectUnauthorized:true TLS hardening, switched to named destructured imports, and updated all connector-shared-infrastructure design docs/specs to use ai-catalog.providers config root with correct function signatures and exports list. Disagreed with 3 findings (pluginPackages cross-ref, file naming convention, out-of-scope openspec updates). Fixed (11):
Disagreed (3):
Tests: passed Updated by fullsend fix agent |
|
/fs-fix following CI error: |
|
🤖 Finished Fix · ✅ Success · Started 8:07 AM UTC · Completed 8:21 AM UTC |
…ompat ConnectorErrorContext lacked a string index signature, making it incompatible with Backstage LoggerService's JsonObject metadata parameter. Add `[key: string]: string | boolean | undefined` so the interface satisfies the `error(message, meta?)` signature without type assertions. Regenerate API reports for boost-connector-utils (new) and boost (re-ordered by api-extractor). Addresses review feedback on #4144
🔧 Fix agent — iteration 2 (human-triggered)Fixed TS2345 compilation error by adding a string index signature to ConnectorErrorContext, making it compatible with Backstage LoggerService's JsonObject metadata type. All 47 tests pass, lint and prettier checks pass, API reports regenerated. Fixed (1):
Tests: passed Updated by fullsend fix agent |
|
/fs-fix Address SonarQube findings (per https://sonarcloud.io/project/issues?id=redhat-developer_rhdh-plugins&pullRequest=4144&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true) and rebase |
|
🤖 Finished Fix · ✅ Success · Started 10:31 AM UTC · Completed 10:47 AM UTC |
Create @red-hat-developer-hub/backstage-plugin-boost-connector-utils providing shared utilities for AI catalog connector entity providers: - loadCaBundle(config, logger): resolve CA bundles from tls.caFile (file path) or tls.caSecret (resolved $env), with graceful failure (WARN for missing file, ERROR for invalid PEM, no expire check) - createHttpsAgent(caBundle?): factory for https.Agent with custom CA - createProviderWrapper(provider, logger, ctx?): wrap EntityProvider connect() in try/catch to prevent unhandled rejections crashing the catalog backend process - createSafeRefresh(fn, connectorId, logger, ctx?): wrap scheduled refresh callbacks with the same fault isolation pattern - classifyConnectorError(error): classify errors as retryable (ECONNREFUSED, ETIMEDOUT, HTTP 5xx/429) or non-retryable (HTTP 4xx, TypeError, TLS cert errors) - isConnectorEnabled(config): check enabled boolean with default true - validateConnectorStartupConfig(config, opts): reject empty credentials and invalid/non-HTTPS endpoint URLs at startup Includes 47 unit tests covering CA loading (file, env, missing, invalid PEM, chains, isolation), fault isolation (connect crash, refresh crash, no rethrow, multi-provider independence, structured error logging), config guards (enabled/disabled/default), and startup validation (HTTPS URLs, credential fields, descriptive errors). Reference app-config YAML at workspaces/boost/examples/ demonstrates MCP Registry, RHOAI, and OCI Skill connector configuration with an air-gapped deployment variant. Config root: ai-catalog.providers.<id> per #4069 clarification. No Helm charts or Operator CRs (deferred per issue clarification). Closes #4039
- Remove unreachable FetchError branch in classifyConnectorError (already covered by generic retryable-code check) - Add rejectUnauthorized: true to createHttpsAgent to guard against NODE_TLS_REJECT_UNAUTHORIZED=0 leaking from dev environments - Switch ca-bundle.ts from namespace imports to named destructured imports to match existing boost workspace conventions - Update connector-shared-infrastructure design doc, tasks, proposal, and spec files to use ai-catalog.providers config root per #4069 - Fix loadCaBundle signature in docs to include logger parameter - Fix createProviderWrapper signature in docs to use ConnectorEntityProvider type and optional ctx parameter - Update exports list in design doc to include classifyConnectorError, validateConnectorStartupConfig, ValidateConnectorStartupConfigOptions, and ConnectorEntityProvider Addresses review feedback on #4144
…ompat ConnectorErrorContext lacked a string index signature, making it incompatible with Backstage LoggerService's JsonObject metadata parameter. Add `[key: string]: string | boolean | undefined` so the interface satisfies the `error(message, meta?)` signature without type assertions. Regenerate API reports for boost-connector-utils (new) and boost (re-ordered by api-extractor). Addresses review feedback on #4144
- Use node: protocol for built-in module imports (node:fs, node:https) - Use optional chaining for credential field empty check - Use String.replaceAll() instead of String.replace() with regex - Parameterize retryable error code tests with it.each - Regenerate API reports after rebase Addresses review feedback on #4144
🔧 Fix agent — iteration 3 (human-triggered)Addressed all 5 SonarQube findings: node: protocol imports for built-in modules (fs, https), optional chaining for credential validation, replaceAll() for string replacement, and parameterized test for retryable error codes. Also rebased onto main (resolved 2 merge conflicts in openspec docs) and regenerated API reports. Fixed (5):
Tests: passed Decision points
Updated by fullsend fix agent |
c460dad to
6937075
Compare
|
/fs-fix address CI issues (recently for |
|
🤖 Finished Fix · ✅ Success · Started 11:04 AM UTC · Completed 11:18 AM UTC |
Run `yarn backstage-cli repo fix --publish` to add the new boost-connector-utils package to the pluginPackages array in all sibling package.json files sharing pluginId "boost", and fix alphabetical ordering in the connector-utils package itself. Addresses CI failure in `yarn fix --check --publish` on PR #4144
🔧 Fix agent — iteration 4 (human-triggered)Fixed CI failure caused by missing pluginPackages sync. The new boost-connector-utils package needed to be added to all sibling package.json pluginPackages arrays via Fixed (1):
Tests: passed Updated by fullsend fix agent |
|
/fs-review |
|
🤖 Finished Review · ✅ Success · Started 12:23 PM UTC · Completed 12:42 PM UTC |
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
/fs-fix Address all fullsend-ai-review comments plus following:
|
|
🤖 Finished Fix · ✅ Success · Started 1:01 PM UTC · Completed 1:17 PM UTC |
- Reorder classifyConnectorError to check retryable/non-retryable codes on err.code and err.cause?.code before NON_RETRYABLE_TYPES so native fetch TypeErrors with network causes (ECONNREFUSED, ETIMEDOUT, etc.) are correctly classified as retryable - Add axios-shaped err.response?.status to HTTP status extraction so 429/5xx/4xx classification works with the documented HTTP client - Introduce FaultIsolationContext interface with optional nextRetryAt; wrappers pass it through to error context when retryable=true, documenting nextRetryAt as connector-owned (not computed by wrappers) - Add changeset for the new public package - Add 7 new unit tests covering native-fetch TypeError+cause, axios response.status, and nextRetryAt passthrough/omission Addresses review feedback on #4144
🔧 Fix agent — iteration 5 (human-triggered)Addressed all 4 human review findings. (1) Reordered classifyConnectorError to check err.code/err.cause?.code before NON_RETRYABLE_TYPES so native-fetch TypeErrors with network causes are retryable. (2) Introduced FaultIsolationContext with connector-owned nextRetryAt passthrough. (3) Added axios err.response?.status to HTTP status extraction. (4) Added changeset for new package. 7 new unit tests, all 54 tests passing. Fixed (4):
Tests: passed Updated by fullsend fix agent |
|
/fs-review |
|
🤖 Finished Review · ✅ Success · Started 1:21 PM UTC · Completed 1:38 PM UTC |
|
/fs-fix both the latest review comments and the failing CI |
|
🤖 Finished Fix · ✅ Success · Started 1:50 PM UTC · Completed 2:06 PM UTC |
- Remove dead code: unreachable value?.trim() === '' check in validateCredentialField (ConfigReader throws on empty strings first) - Fix misleading JSDoc: rewrite validateCredentialField comment to match actual non-empty validation behavior - Fix import convention: use node: prefix for fs/os/path in test file - Move ConnectorEntityProvider interface from fault-isolation.ts to types.ts, consolidating all public interfaces in one location - Align @backstage/config dependency to ^1.3.8 matching monorepo - Regenerate boost/report.api.md to fix CI api-report check Addresses review feedback on #4144
🔧 Fix agent — iteration 6 (human-triggered)Addressed 6 of 7 review findings and fixed the CI api-report failure. Fixed dead code removal, misleading JSDoc, import convention, interface location, dependency version alignment, and regenerated API reports. Disagreed with 1 finding (path traversal) as admin-controlled config consistent with Backstage patterns. Fixed (6):
Disagreed (1):
Tests: passed Updated by fullsend fix agent |
|
1 participant
Create @red-hat-developer-hub/backstage-plugin-boost-connector-utils providing shared utilities for AI catalog connector entity providers:
(file path) or tls.caSecret (resolved $env), with graceful failure
(WARN for missing file, ERROR for invalid PEM, no expire check)
connect() in try/catch to prevent unhandled rejections crashing the
catalog backend process
refresh callbacks with the same fault isolation pattern
(ECONNREFUSED, ETIMEDOUT, HTTP 5xx/429) or non-retryable (HTTP
4xx, TypeError, TLS cert errors)
credentials and invalid/non-HTTPS endpoint URLs at startup
Includes 47 unit tests covering CA loading (file, env, missing, invalid PEM, chains, isolation), fault isolation (connect crash, refresh crash, no rethrow, multi-provider independence, structured error logging), config guards (enabled/disabled/default), and startup validation (HTTPS URLs, credential fields, descriptive errors).
Reference app-config YAML at workspaces/boost/examples/ demonstrates MCP Registry, RHOAI, and OCI Skill connector configuration with an air-gapped deployment variant.
Config root: ai-catalog.providers. per #4069 clarification. No Helm charts or Operator CRs (deferred per issue clarification).
Closes #4039
Post-script verification
agent/4039-connector-utils)fe4298b658c7868ca806e4edaf082e0417ba7cb2..HEAD)