gateway upsert silently destroys delivery_policy.groups.overrides #393

Summary

Updating a delivery group's rate through gateway destination upsert or gateway connection upsert silently destroys delivery_policy.groups.overrides — per-group overrides the user never mentioned.

Found by exercising a v2.6.0 release-candidate build against the API.

Reproduce

Starting state on a destination:

"delivery_policy": {
  "rate": 200,
  "period": "hour",
  "groups": {
    "key": "body.customer_id",
    "rate": 10,
    "rate_period": "second",
    "overrides": { "cust_1": { "rate": 5, "rate_period": "minute" } }
  }
}

Bump only the group rate:

hookdeck gateway destination upsert my-dest --type HTTP --url https://example.com/x \
  --delivery-group-key body.customer_id --delivery-group-rate 30 --delivery-group-rate-period second

Result: rate: 200 and period: hour are preserved, groups.overrides is gone.

The same happens via gateway connection upsert with the --destination-delivery-group-* forms.

Mechanism

Confirmed by capturing the outgoing request (pointing the CLI at a local server via --api-base). The CLI sends:

{"config":{"delivery_policy":{"groups":{"key":"body.customer_id","rate":30,"rate_period":"second"}},"url":"..."}}

No overrides key — the CLI has no knowledge of the stored value and does not fetch it.

The server then merges delivery_policy one level deep but replaces groups wholesale: that is why sibling rate/period survive (the client omitted them too) while nested overrides does not.

So this is not a client-side bug alone. The CLI omits a field it cannot know; the API's merge treats the two nesting levels differently.

Why it matters

The CLI requires --delivery-group-key and --delivery-group-rate-period to be repeated whenever --delivery-group-rate is given, so "just bump the rate" is necessarily a three-flag command — and that command is exactly the one that wipes overrides. There is no warning and no diff; --dry-run prints only Destination 'x' would be updated.

gateway connection upsert --help states:

Only updates properties that are explicitly provided
Preserves existing properties that aren't specified

Overrides were not specified, and were not preserved.

Options

1. Client-side fetch-and-merge — read the existing delivery_policy before an upsert that touches groups, and re-send overrides unless the user passed --delivery-group-overrides. Fixes it without API changes; costs a request and introduces a read-modify-write race.
2. Fix the API merge — make the merge consistent at the groups level. Fixes it for every API consumer, not just the CLI.
3. Correct the help text — stop promising preservation, and warn when an upsert will replace a groups object that has overrides. Cheapest, but leaves the data loss in place.

Worth a decision involving the API side rather than a unilateral CLI patch, which is why it was left out of #392.

Related

• fix: delivery-group data loss and metrics defects, plus the missing acceptance coverage #392 fixes five other defects found in the same exercise
• feat: support 2026-09-01 gateway API #378 is the v2.6.0 release PR that introduces delivery groups

Filed by Claude on Phil's behalf, from release-candidate testing.