feat(sns): read-first subscription reconciliation with typed managedAttributes

[kibertoad]

Every consumer init() wrote to its subscription even when nothing had changed: Subscribe on the creation path, and one SetSubscriptionAttributes per attribute on the locateOnly path and for the reused DLQ. There was also no way to say which attributes the application owns, so an attribute removed from the config stayed on the subscription forever. This PR reads first, writes only what differs, and adds a typed managedAttributes list.

Stacked on #608, so merge that one first.

Changes

• assertSubscription looks up the existing subscription (ListSubscriptionsByTopic) and reads its attributes (GetSubscriptionAttributes). If everything matches, it returns without writing. If something differs, it writes only those attributes when updateAttributesIfExists is on, and throws otherwise. The error lists the differing attribute names.
• Subscribe is only called when no confirmed subscription exists. If it then fails with "already exists with different attributes" (another instance won the race), the subscription is reconciled the same way as above.
• New subscriptionConfig.managedAttributes?: SubscriptionManagedAttributeName[] on both the creation and the locateOnly variants. It defaults to all of FilterPolicy, FilterPolicyScope, RawMessageDelivery and RedrivePolicy.
  • A managed attribute missing from Attributes is reset. FilterPolicy is set to {} (as in the SNS docs). RedrivePolicy is removed by leaving AttributeValue out, because AWS rejects an empty string for it (the Terraform provider does the same). The other two go back to MessageAttributes and false.
  • An unmanaged attribute is never read or written.
  • Listing an unmanaged attribute in Attributes throws invalid_subscription_configuration.
• setSubscriptionAttributes (used by locateOnly) applies the same read-first logic and runs even when Attributes is empty, so resets also happen in locate mode.
• The consumer's DLQ RedrivePolicy write goes through setSubscriptionAttributes. With reuseConsumerDeadLetterQueue, RedrivePolicy is removed from the managed set. Without that, the subscription step would clear it and the DLQ step would set it again on every startup. Managing it explicitly alongside that flag throws.

Decisions

• The type is limited to the four attributes that apply to SQS subscriptions and can be reset. Other keys in Attributes (e.g. ReplayPolicy) are still compared and written when present, but never reset.
• Policy attributes are compared as parsed JSON, because SNS can return a different formatting than the one we sent. A missing value, "", the default value, and {} for FilterPolicy all count as unset.
• FilterPolicyScope is not reset on its own when the subscription ends up without a filter policy. On its own, the scope has no effect.

Risk

• Behaviour change through the default. Every attribute is managed unless configured otherwise. Existing subscriptions that carry attributes missing from the config (for example RawMessageDelivery or RedrivePolicy set by Terraform) are now reset when updateAttributesIfExists is on. When it is off, startup fails instead. This also covers locateOnly configs without Attributes. Services that share ownership with Terraform need managedAttributes: ['FilterPolicy', 'FilterPolicyScope'] before upgrading.
• Startup now calls ListSubscriptionsByTopic (30 TPS per account) before anything else. Many consumers starting at once against topics with many subscriptions could hit throttling sooner than before.
• When updateAttributesIfExists is off, the error message for differing attributes changes. The error code sns_subscription_creation_failed stays the same.
• Removing a RedrivePolicy can't be tested on localstack, which rejects both an empty and an omitted value, so that test runs on fauxqs only. The reset values follow the AWS docs and the Terraform provider, but haven't been run against real AWS.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: e8c6659a-857d-462f-9ab8-4a1495da875c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[CarlosGamero]

Merging this on #608 to trigger a single release and ask facilitate review of the new feature