[Feature Request]Proposal: Add a stable connection identifier accessible across all login-phase events

[xfy2412]

Requested Feature

Add a unique, stable connection identifier to the InboundConnection interface so plugins can reliably correlate the same TCP connection across PreLoginEvent, GameProfileRequestEvent, and LoginEvent.

Something like:

public interface InboundConnection {
    // existing methods...

    /**
     * Returns a unique identifier for this connection, stable for the
     * entire lifetime of the connection.
     */
    UUID getConnectionId();  // or long
}

The identifier should be:

• Generated once per TCP connection (in HandshakeSessionHandler / InitialInboundConnection constructor)
• Available across all login-phase events: PreLoginEvent, GameProfileRequestEvent, and ideally also from LoginEvent (via ConnectedPlayer or a similar accessor)
• Consistent even when the InboundConnection wrapper object changes internally

Why is this needed?

event.getConnection() returns a LoginInboundConnection that—while the same instance in normal code paths—can become a different wrapper in certain scenarios (possibly related to the 1.20.2+ login acknowledgement / config phase). This breaks plugin code that relies on object identity:

PreLoginEvent:          conn.hashCode() = 0x43BED29E  ← wrapper A
GameProfileRequestEvent: conn.hashCode() = 0x7EB37DA9  ← wrapper B (different!)

To give some context: we are developing an offline-mode authentication plugin that also supports premium (Mojang-authenticated) players. When a premium player logs in, we need to replace their Mojang UUID with an offline-mode UUID in GameProfileRequestEvent so the backend servers always see the same UUID regardless of the player's online/offline status. This requires tracking the same connection across PreLoginEvent (where we detect a premium login request), GameProfileRequestEvent (where we replace the UUID and playername), and LoginEvent (where we persist the premium UUID mapping). Without a stable connection identifier, we cannot reliably associate these three events.

I believe this feature would be useful for any plugin that needs to track state through the login pipeline—not just authentication plugins, but also anti-bot, name-restriction, or connection-rate-limiting plugins.

Alternative Solutions

Currently we use a triple-index fallback (connection → UUID → name), which works but is fragile:

1. Object reference identity (== comparison on InboundConnection): works in theory but fails when the wrapper object changes internally during the login pipeline transition.
2. Reflection on LoginInboundConnection.delegate: reaches the underlying MinecraftConnection.getChannel().id(), but depends on private field names that may change between versions.
3. getRemoteAddress() + getProtocolVersion() composite key: not reliable because port numbers can change on rapid reconnect.
4. Name-based fallback: fragile if the claimed name differs from the resolved name (online mode Mojang rename).

A dedicated getConnectionId() on InboundConnection is the cleanest solution.

Additional Information

I am a teenager from China communicating through a translator, so there may be unclear expressions—please excuse me. If you find this proposal feasible, I would be happy to help implement it with some guidance.

[WouterGritter]

MinecraftConnection would be the right class to hold the UUID here, as all [Velocity]InboundConnection implementations hold a reference to a shared reference to this class.

[xfy2412]

MinecraftConnection would be the right class to hold the UUID here, as all [Velocity]InboundConnection implementations hold a reference to a shared reference to this class. MinecraftConnection 正是用来存储 UUID 的合适类，因为所有的 [Velocity]InboundConnection 实现都包含了对这个类的引用。

Thanks for the guidance! I'm working on this in my fork and should have a PR ready soon.