Skip to content

Add pluggable envelope ID generation with GuidV7 option#2376

Merged
jeremydmiller merged 2 commits intomainfrom
pluggable-envelope-id
Mar 30, 2026
Merged

Add pluggable envelope ID generation with GuidV7 option#2376
jeremydmiller merged 2 commits intomainfrom
pluggable-envelope-id

Conversation

@jeremydmiller
Copy link
Copy Markdown
Member

Summary

Fixes #2375

  • Problem: NewId.NextSequentialGuid() generates envelope IDs based on machine identity (MAC/DNS hostname). In cloud environments where multiple instances share network properties (Google Cloud Run, Kubernetes, serverless), this produces duplicate envelope IDs causing Duplicate incoming envelope errors.
  • Solution: New EnvelopeIdGeneration enum with NewId (default, backward compatible) and GuidV7 (Guid.CreateVersion7() per RFC 9562) options.
  • Implementation: Static Func<Guid> delegate on Envelope set once at startup — zero runtime branching overhead. All internal NewId.NextSequentialGuid() calls replaced with Envelope.IdGenerator().

Usage

using var host = await Host.CreateDefaultBuilder()
    .UseWolverine(opts =>
    {
        // Recommended for greenfield apps and cloud deployments
        opts.EnvelopeIdGeneration = EnvelopeIdGeneration.GuidV7;
    }).StartAsync();

Files changed

File Change
WolverineOptions.cs Added EnvelopeIdGeneration enum and property
Envelope.cs Added static IdGenerator delegate, property initializer uses it
WolverineRuntime.cs Sets Envelope.IdGenerator at startup based on config
CloudEventsMapper.cs Uses Envelope.IdGenerator()
DurableReceiver.cs Uses Envelope.IdGenerator() (2 occurrences)
EnvelopeGenerator.cs Uses Envelope.IdGenerator()
messages.md Documentation with comparison table

Test plan

  • 7 new tests pass (default setting, NewId sanity, V7 version bits, time ordering, cross-thread uniqueness, InvokeAsync integration, delegate wiring)
  • CoreTests: 1221 passed, 0 failed

🤖 Generated with Claude Code

jeremydmiller and others added 2 commits March 30, 2026 08:14
NewId generates sequential GUIDs based on machine identity (MAC/DNS),
which produces duplicate envelope IDs in cloud environments where
multiple instances share network properties (Cloud Run, Kubernetes,
serverless). This adds EnvelopeIdGeneration.GuidV7 as an opt-in
alternative using Guid.CreateVersion7() per RFC 9562.

Implementation uses a static Func<Guid> delegate on Envelope that is
set once at startup — no runtime if/then overhead. All internal
NewId.NextSequentialGuid() calls replaced with Envelope.IdGenerator().

Fixes #2375

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Guid.CreateVersion7() was added in .NET 9. Since Wolverine
multi-targets net8.0/net9.0/net10.0, wrap the call in
#if NET9_0_OR_GREATER and throw NotSupportedException on net8.0.
Tests also wrapped in the same conditional.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Conflicting message/envelope id generation

1 participant