gorums: add the ID alias, Config.Node, and ServerContext.SenderID

[meling]

Closes #165

Problem

Gorums identifies nodes with plain uint32 values, so signatures do not say what a number means. Applications also kept writing the same two helpers. The decision comment on #165 looked at five systems built on Gorums and found these gaps:

• There is no lookup by ID. Several applications wrote Config.Node(id) themselves.
• A handler cannot see who sent a request. Applications put a sender ID in every message, or, like HotStuff, read it from gRPC metadata or the TLS certificate.

#248 tried a generic node ID type parameter. It is closed, because the type parameter would spread to Server, ServerContext, every handler, and every option.

Change

• gorums.ID is an alias for uint32. It replaces node-ID uint32 in the API, in gorumstest, in the storage example, and in the guides. Its doc comment states the ID rules: 0 is reserved, back-channel clients get IDs from 2^20, servers configured with WithPeers must agree on IDs, and under stream deduplication the lower ID dials. Because it is an alias, code that uses uint32 and protobuf uint32 fields keeps compiling.

• Config.Node(id) returns the node with the given ID, or nil. Contains, CallContext.Node, and gorumstest.PeerNode now use it.

• ServerContext.SenderID() returns the ID of the node that sent the request, as this server knows it:

  • a configured peer has its configured ID;
  • a back-channel client has the ID that the server assigned to it;
  • a request on a connection that this server dialed has the dialed node's ID;
  • a request that the server sends to itself has the server's own ID.

  Regular clients and unknown IDs report 0, because Gorums already gives them untracked channels with ID 0. The sender is the last hop, and the server does not authenticate it; feat: stronger peer identity guarantees #325 covers authentication.

  Every channel already holds its peer's ID. The internal stream.RequestHandler.HandleRequest now takes it as a senderID parameter.

• User guide: a new "Node IDs" section covers the ID rules, choosing IDs, mapping application IDs such as strings to node IDs, and finding the sender.

The public changes are additions. The alias is the same type as uint32, so no existing call site breaks.

Keeping the NodeAddress value on the node, for a reverse mapping or per-node keys, is deferred to #325.

Testing

• TestConfigNode covers present, absent, unsorted, zero, empty, and nil configurations.
• TestServerSenderID covers six paths: known peers and self, stream deduplication, regular client, unknown peer ID, back-channel client, and the client side of a back-channel call. When the stream or local channel passes 0 instead of its ID, the subtests fail.
• go test ./... passes in the root and examples modules, also with -tags=integration. -race passes for the root, internal/conn, internal/stream, internal/impl, and gorumstest packages. benchkit builds and vets unchanged.
• Each commit builds and passes the affected package tests on its own.

[Copilot]

🟢 Approval recommended

Sender identity is consistently propagated across channel types with comprehensive tests and documentation.

0 open findings

What changed in this PR

Implements issue #165 by making node identity explicit and available to handlers.

Changes:

• Adds the gorums.ID alias and updates node-ID APIs.
• Adds Config.Node and ServerContext.SenderID.
• Adds sender-path tests and node-ID documentation.

File	Description
config.go	Exposes ID and updates node configuration APIs.
server.go	Propagates and exposes request sender IDs.
server_test.go	Tests sender IDs across connection paths.
server_options.go	Uses ID for peer configuration.
local_servers.go	Uses ID for local server IDs.
internal/​stream/​transport.go	Uses ID in transports.
internal/​stream/​session.go	Passes sender IDs to handlers.
internal/​stream/​send_queue.go	Uses ID in send queues.
internal/​stream/​request.go	Defines the stream-layer ID alias.
internal/​stream/​request_test.go	Updates handler test adapter.
internal/​stream/​outbound.go	Uses ID for outbound channels.
internal/​stream/​local.go	Passes local sender IDs.
internal/​stream/​inbound.go	Uses ID for inbound channels.
internal/​stream/​channel.go	Extends the request-handler contract.
internal/​stream/​channel_test.go	Updates handler test implementation.
internal/​impl/​responses.go	Keys collected responses by ID.
internal/​impl/​call_context.go	Delegates node lookup to Config.Node.
internal/​impl/​call_context_test.go	Updates handler test implementation.
internal/​impl/​aliases.go	Adds the implementation-layer ID alias.
internal/​conn/​testhelpers.go	Uses ID in node test construction.
internal/​conn/​outbound_manager.go	Keys outbound lookup by ID.
internal/​conn/​node.go	Defines and applies the connection-layer ID alias.
internal/​conn/​node_source.go	Uses ID when building configurations.
internal/​conn/​inbound_manager.go	Uses ID for peers and dynamic clients.
internal/​conn/​inbound_manager_test.go	Updates handler test adapter.
internal/​conn/​errors.go	Uses ID in per-node errors.
internal/​conn/​dial_options.go	Uses ID for local-node options.
internal/​conn/​config.go	Adds node lookup and updates ID APIs.
internal/​conn/​config_test.go	Covers node lookup edge cases.
gorumstest/​gorumstest.go	Uses Config.Node in PeerNode.
gorumstest/​errors.go	Uses gorums.ID for error maps.
examples/​storage/​server.go	Adopts gorums.ID in the storage example.
doc/​user-guide.md	Documents node-ID rules and sender lookup.
doc/​dev-guide.md	Updates architecture diagrams and handler flow.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.