Notification API reject out of order notifications

[tzuan16]

Description

UPDATE/CREATE notifications will be rejected if the timestamp is older than the latest processed for the table. DROP notifications won't be affected since messing up the order of DROPs is acceptable as they are idempotent.

Update the notification API spec to clarify that the API caller should ensure the correct order of timestamps for a sequence of notifications. Also added the description for 409 conflict error.

Type of change

Please delete options that are not relevant.

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] Documentation update
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

• [x] BasePolarisCatalogTest::testUpdateNotificationRejectOutOfOrderTimestamp

Test Configuration:

• Hardware:
• Toolchain:
• SDK:

Checklist:

Please delete options that are not relevant.

• [x] I have performed a self-review of my code
• [x] I have commented my code, particularly in hard-to-understand areas
• [x] I have made corresponding changes to the documentation
• [x] My changes generate no new warnings
• [ ] If adding new functionality, I have discussed my implementation with the community using the linked GitHub issue

[tzuan16]

I am a little concerned about clock skew across multiple senders with this approach though. Rather than timestamp, would it be possible for notification senders to use something like an ordering key, and potentially for them to obtain it from Polaris?

Discussed with Eric offline, we leave it to the notification sender to ensure the correct order of timestamps for a sequence of notifications. This is due to Polaris serving as the "external" catalog, where the single source of truth should come from the actual catalog that "owns" the table. We don't want the proprietary catalog to have to speak with Polaris first prior to sending the notification.

[RussellSpitzer]

Thanks @eric-maynard and @tzuan16 , set to auto-merge on tests passing