Question about race conditions and timestamp concistnecy when traversing the NuGet Catalog

[zleonov]

Hi, I have read the NuGet Catalog API documentation: catalog-reference and looked at the various use cases and examples. But it seems to me there is a possible race condition when traversing the catalog for new events.

Can someone please bear with me and clear things up for me?

I understand that:

• Events are added to the catalog in monotonically increasing, chronological order.
• Consumers are guaranteed that no duplicate lowercase(packageId)/version/timestamp combination can exist.
• The page items array in the catalog does not have a defined order and should be sorted by the consumer in timestamp order.

But I am at a loss how to guarantee that a consumer won't miss/lose any events if the catalog is updated during traversal.

Scenario:

• I have a prevMaxTimestamp from my last processing run
• I'm traversing through catalog pages to find events newer than prevMaxTimestamp
• Throughout the processing run I keep track of newMaxTimestamp which will become the prevMaxTimestamp in the next processing run.
• Now I am on the final page. The last event on this final page has timestamp prevMaxTimestamp + 5N (for some arbitrary definition of N).

The Problem:

What guarantees do I have that an event with timestamp prevMaxTimestamp + 3N wasn't added to an earlier page (that I've already processed) between the time I processed that page and now?

In other words, is there a race condition where:

At time T1: I process Page N - 1
At time T3: I process Page N

But at time T2 (between T1 and T3) two new events are published. First to Page N - 1, then subsequent to that to Page N. Thereby losing the new event on Page N - 1 forever.

Questions:

• Are we guaranteed that events are always published to the "last" page, where "last" is defined as the page with the latest timestamp? If so would it be correct to say that sorting all the page items by timestamp and then iterating through all the events while keeping track of the maxTimestamp is guaranteed to avoid a scenario where an event is lost (i.e. no matter what all newer events will always be picked up on the next processing run).
• Are timestamps at the Catalog level -> Page Item level -> Event level all consistent? That is to say, is it true that for a commitTimeStamp at the Catalog level, there exists a Page Item with that commitTimeStamp, and on that page there at exists an event with that commitTimeStamp.

If all the following is true, then this is the algorithm I can use:

1. If prevMaxTimestamp < Catalog.commitTimeStamp then
2. Get all PageItems and sort by timestamp.
3. Starting from least to greatest timestamp for any pages where prevMaxTimestamp < PageItem.commitTimestamp traverse all events and consume any event where prevMaxTimestamp < Event.commitTimestamp.
4. prevMaxTimestamp now becomes the latest of all event timestamps.

Thank you guys so much. Please advise.

[zleonov]

Ok I wrote an essay there above. Going to start to answer my own questions until a NuGet dev. chimes in. It does look like each new event is indeed published in chronological order to the last chronological page. When a new page is created, it becomes the "last" chronological page.

Thus, if pages are sorted from earliest commitTimestamp to latest commitTimestamp, you are free to iterate all available events in each page and do with them as you like.

Any new events which are published at the same time you are iterating will still be "after" the last event in your iteration. So you are not going to "miss" any events.

[joelverhagen]

Yes, that's correct.

[zleonov]

@joelverhagen is the order of events in any particular page deterministic and guaranteed? Right now if I am updating a page because it got new events I just download all the events in that page.

I could optimize the process by only getting the "new" events, but without knowing that the order is always guaranteed there is no way for me to know which events are "new".

This is because while projectId/version/timestamp is unique (and I assume projectId/version/commitId is also unique), neither commitId or timestamp are unique by themselves. Do I have this correct?

[joelverhagen]

The order of items within the page, or the index for that matter, is not guaranteed. You should load the entire JSON document to find candidate items.

To know which items are new, you must compare your cursor timestamp (the last max commit timestamp you processed) with each item timestamp.

projectId is now part of our domain language. Perhaps you mean package ID?

Commit ID is unique. The timestamp generally is unique but technically is not guaranteed to be so. It is extremely unlikely to have duplicates though because the worker that is producing the catalog is a singleton and using current clock time to produce the commit timestamp in a serial fashion.

[zleonov]

@joelverhagen yes you are right, I meant package id.

Regarding using the timestamp or commit id. Am I looking at the wrong keys? At the page level the keys I am referring to are commitId and commitTimeStamp, at the event level they are catalog:commitId and catalog:commitTimeStamp.

For example on page21381.json these two seemingly unrelated events have the same commit id and timestamp:

slimmessagebus.host.circuitbreaker.3.2.1

workleap.dotnet.codingstandards.1.1.13

      "catalog:commitId": "b5e9fa21-2451-47f4-b68d-9a1ffd2ce27c",
      "catalog:commitTimeStamp": "2025-06-15T14:29:42.9295988Z",
      "id": "Workleap.DotNet.CodingStandards",
      "version": "1.1.13",

and

      "catalog:commitId": "b5e9fa21-2451-47f4-b68d-9a1ffd2ce27c",
      "catalog:commitTimeStamp": "2025-06-15T14:29:42.9295988Z",
      "id": "SlimMessageBus.Host.CircuitBreaker",
      "version": "3.2.1-rc103",

Am I misunderstanding something? There many such instances, am I misunderstanding something?

[joelverhagen]

A commit can contain events related to different packages. What you're seeing is expected. A commit is essentially a batch of changes committed to the catalog since the last commit. In this particular case, it looks like the owners of these two packages happened to make changes around the same time and our catalog writer job detected these changes and included them in the same commit.