|
| 1 | +--- |
| 2 | +'@objectstack/spec': minor |
| 3 | +'@objectstack/connector-mcp': patch |
| 4 | +'@objectstack/connector-openapi': patch |
| 5 | +'@objectstack/connector-rest': patch |
| 6 | +'@objectstack/connector-slack': patch |
| 7 | +'@objectstack/service-automation': patch |
| 8 | +--- |
| 9 | + |
| 10 | +feat(spec)!: retire the connector resilience family — `health` (health probe + circuit breaker), `status` and the nested `webhooks`, sixteen keys nothing read (#20273) |
| 11 | + |
| 12 | +**BREAKING** — `connector.health` (the `healthCheck` probe, eight keys, and the |
| 13 | +`circuitBreaker`, six keys), `connector.status` and the connector-nested |
| 14 | +`webhooks` are removed from `ConnectorSchema` and `DeclarativeConnectorEntrySchema` |
| 15 | +— so from `defineConnector`, `stack.connectors[]`, the `PUT /api/v1/meta/connector/:name` |
| 16 | +door and `AutomationEngine.registerConnector`. ADR-0049 enforce-or-remove, one |
| 17 | +batch for the family, by the maintainer's criterion: does the mainstream platform |
| 18 | +offer this capability? Author-configured health probes and circuit breakers are |
| 19 | +not connector metadata in the mainstream (breakers live in API-gateway |
| 20 | +infrastructure), and an authored status and a nested webhook list duplicate what |
| 21 | +is already delivered here by other keys. |
| 22 | + |
| 23 | +Measured before removal, each against a lit control: zero reads of any of the |
| 24 | +sixteen keys outside `packages/spec`. No loop ever polled a connector endpoint, |
| 25 | +counted consecutive failures or tripped a breaker, and none of the four |
| 26 | +`fallbackStrategy` behaviours existed. Nothing read an authored `status`: the |
| 27 | +runtime's dispatchability answer is the COMPUTED `state` (`ready` / `degraded`) |
| 28 | +on `GET /api/v1/automation/connectors`, which no authored value sets. A webhook |
| 29 | +nested in a connector was never registered as a `webhook` item, so it was never |
| 30 | +materialized into `sys_webhook` and never delivered. |
| 31 | + |
| 32 | +### FROM → TO |
| 33 | + |
| 34 | +| removed | what to write instead | |
| 35 | +| --- | --- | |
| 36 | +| `connector.health` (`healthCheck.*`, `circuitBreaker.*`, including `monitoringWindowMs` and the pre-rename `monitoringWindow`) | delete the block. Put health probes and circuit breaking in the connector provider or an upstream gateway. | |
| 37 | +| `connector.status` | delete the key. `enabled: false` on a declarative entry is what withdraws a materialized instance or marks a catalog-only descriptor; whether a registered connector can be dispatched is the computed `state`. | |
| 38 | +| `connector.webhooks` | delete the array. A webhook that is actually delivered is declared in the stack's top-level `webhooks:` collection — moving one there STARTS deliveries this connector never made, so decide per webhook. `events` and `signatureAlgorithm` have no counterpart there. | |
| 39 | +| `ConnectorHealth`, `HealthCheckConfig`, `CircuitBreakerConfig`, `ConnectorStatus`, `WebhookConfig`, `WebhookEvent`, `WebhookSignatureAlgorithm` (schemas, types, `…Parsed` types) | no replacement — nothing parsed or constructed them. | |
| 40 | + |
| 41 | +**The one-line fix: delete `health:`, `status:` and `webhooks:` from every connector.** |
| 42 | +`os migrate meta --from 17` lists the mechanical edits for existing sources. |
| 43 | + |
| 44 | +⚠️ Runtime behaviour is deliberately **unchanged**: none of the sixteen keys ever |
| 45 | +changed what a connector did. What changes is the answer an author gets — each |
| 46 | +key is refused at parse with a prescription, and in `tsc` (its input type is |
| 47 | +`never`), instead of being saved with no effect. |
| 48 | + |
| 49 | +### The retirement kit |
| 50 | + |
| 51 | +- **Tombstones.** `health`, `status` and `webhooks` are `retiredKey()` tombstones |
| 52 | + on the private `ConnectorBaseSchema` both published carriers wrap (the schema |
| 53 | + is not `.strict()`, so a bare deletion would be a silent strip, ADR-0104). |
| 54 | + `RETIRED_KEYS_BY_MAJOR[18]`: `integration/Connector:{health,status,webhooks}` |
| 55 | + and `integration/DeclarativeConnectorEntry:{health,status,webhooks}`. |
| 56 | +- **Retired-default residue.** `status` was `.default('inactive')`, so every 17.x |
| 57 | + parse emitted `status: 'inactive'` into every connector; that exact value joins |
| 58 | + `connectionTimeoutMs: 30000` in the residue stage (accepted and stripped, so a |
| 59 | + def a 17.x toolchain built still registers). Every other value is refused. |
| 60 | +- **Seven defs leave whole** (`RETIRED_DEFS_BY_MAJOR[18]`): the four |
| 61 | + `integration/` schemas and three enums listed above. |
| 62 | +- **D2 conversion `connector-resilience-keys-removed`** (step 18, retired from |
| 63 | + the load path): strips the three keys from `connectors[]` and from stored |
| 64 | + `sys_metadata` connector rows (the rehydration seam replays it), one notice per |
| 65 | + key, as a lossless delete. Nested webhooks are stripped, never moved. |
| 66 | +- **The chain.** In the same step, `connector-health-and-trigger-durations-unit-in-key` |
| 67 | + renamed `health.circuitBreaker.monitoringWindow` to `monitoringWindowMs`. That |
| 68 | + breaker half is absorbed by this removal: the renamed key is itself removed, so |
| 69 | + an author holding either spelling ends with no `health` block. The |
| 70 | + conversion's `triggers[].interval` → `intervalSeconds` rename is unaffected. |
| 71 | +- **D3 entry `connector-resilience-keys-retired`** carries the family's |
| 72 | + judgement: which probe, breaker or nested webhook the author actually relied |
| 73 | + on, and where it goes now. |
| 74 | +- **Writers deleted.** The four shipped connector packages wrote |
| 75 | + `status: 'active'` and the automation service's degraded husk wrote |
| 76 | + `status: 'error'`; nothing read either back, and both writes are gone. |
| 77 | +- **No deprecation window**, per the project's startup-stage posture. |
| 78 | + |
| 79 | +⚠️ **The out-of-repo consumer population is NOT MEASURED.** `@objectstack/spec` |
| 80 | +is published, so this is breaking for consumers no telemetry was consulted for. |
| 81 | + |
| 82 | +Clause-②: no (narrowing) |
| 83 | + |
| 84 | +<!-- adr-0087: registered connector-resilience-keys-removed, connector-resilience-keys-retired --> |
0 commit comments