fix: fix occ concurrency comparison

[minottic]

Description

OCC comparisons had 2 problems:

1. 2 clients submitting requests at the same exact time, both of them would succeed since they would override each other since they had the same updatedAt as long as the mongo update takes sub milliseconds
2. when a client sends an http date in the header, this gets truncated to seconds resulting in a false 412. This ceils to 99 ms more

It includes a refactor to avoid duplication

Tests included

• Included for each change/fix?
• Passing?

Documentation

• swagger documentation updated (required for API changes)
• official documentation updated

official documentation info

Summary by Sourcery

Fix optimistic concurrency comparisons and centralize conditional update handling across resource services.

Bug Fixes:

• Prevent optimistic-concurrency updates from allowing simultaneous requests with the same timestamp to overwrite each other.
• Treat second-precision If-Unmodified-Since headers as covering the full second, avoiding false 412 responses while preserving explicit millisecond precision.

Enhancements:

• Centralize OCC update handling across supported services, including timestamp management and consistent not-found/precondition errors.
• Read and normalize If-Unmodified-Since values consistently across update controllers.

Tests:

• Add coverage for timestamp race prevention, header precision handling, shared OCC update behavior, and related controller updates.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="src/datasets/utils/occ-util.ts" line_range="19-21" />
<code_context>
+ * compares exactly, unaffected.
+ */
+function occComparisonBound(unmodifiedSince: Date): Date {
+  return unmodifiedSince.getMilliseconds() === 0
+    ? new Date(unmodifiedSince.getTime() + 999)
+    : unmodifiedSince;
+}
+
</code_context>
<issue_to_address>
**issue (bug_risk):** occComparisonBound treats every Date whose milliseconds are 0 as a coarse HTTP-date and widens it by 999 ms. A client that echoes an exact millisecond-precision updatedAt ending in .000 therefore gets a bound 999 ms later, so an intervening update within that second still matches the OCC filter and the stale client update succeeds.

**Triggers:** When a client sends the exact resource timestamp and that timestamp has zero milliseconds, such as 2026-01-01T00:00:00.000Z.

**Suggested fix:** Preserve whether the value came from a standard HTTP-date separately from the Date value, or use an explicit precision marker, instead of inferring precision from getMilliseconds() === 0.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[HayenNico]

The new logic looks good to me, I'd appreciate if someone else had a second look over the main changes in occ-util.ts before merging though.

All controller/service changes are solid and significantly reduce code duplication 👍

[HayenNico]

This file (and the .spec file) should be placed under common, they are not tied to datasets specifically