# NodeId Assignment Every node a server creates at runtime needs a NodeId. This document describes the mechanisms the stack uses to produce one: the factory contract, the identifier formats, how type declarations differ from instances, what the source generator emits, and what each NodeManager base class does. ## Contents - [The contract](#the-contract) - [DefaultNodeIdFactory](#defaultnodeidfactory) - [Types and instances](#types-and-instances) - [What the source generator emits](#what-the-source-generator-emits) - [NodeManager behaviour](#nodemanager-behaviour) - [Configuring the factory](#configuring-the-factory) - [Who forces a fresh identifier](#who-forces-a-fresh-identifier) ## The contract `INodeIdFactory` (`Opc.Ua.Types/State/ISystemContext.cs`) has one member: ```csharp NodeId New(ISystemContext context, NodeState node); ``` It reaches node code through `ISystemContext.NodeIdFactory`. A NodeManager publishes itself as that factory in its constructor (`SystemContext.NodeIdFactory = this`), so any node-authoring code holding the manager's `SystemContext` mints identifiers through the manager. This points at the *NodeManager*, not at its factory, so that a subclass overriding `New` is still the one node-level code reaches — which is why `AsyncCustomNodeManager` and `CustomNodeManager2` do it once for every manager that derives from them, and a subclass never repeats it. `IRebasableNodeIdFactory` (`Opc.Ua.Server/NodeManager/IRebasableNodeIdFactory.cs`) extends that with what a NodeManager needs and a bare `INodeIdFactory` cannot express: which namespace to mint into, which identifier style to mint, and an identifier for a node that does not exist yet. ```csharp NodeIdAssignmentMode Mode { get; } ushort DefaultNamespaceIndex { get; } IRebasableNodeIdFactory WithDefaultNamespaceIndex(ushort defaultNamespaceIndex); IRebasableNodeIdFactory WithMode(NodeIdAssignmentMode mode); NodeId NextCounterNodeId(); NodeId CreateChildNodeId(NodeId parentNodeId, QualifiedName browseName, ushort namespaceIndex, NamespaceTable namespaceUris); ``` The factory needs the NodeManager's namespace index, but the server adds that namespace only after constructing the manager. A factory registered through dependency injection is therefore created too early to receive the final index as constructor configuration. For that reason, `IRebasableNodeIdFactory` is a contract rather than constructor configuration. Implementations are immutable, and the `With…` methods return views with different namespaces. One registered factory can serve managers that own different namespaces. `AsyncCustomNodeManager.NodeIdFactory` uses this interface. A caller can decorate `DefaultNodeIdFactory` with a custom rule—for example, claim one subtree and delegate other nodes—instead of overriding `New` on the NodeManager and scattering the rule across it. The property is nullable, and null means *do not assign*. A node copy deliberately hides the factory from the children it materialises, so code that cannot work without one calls `ISystemContext.RequireNodeIdFactory()` and fails with a diagnosable error rather than a `NullReferenceException`. `New` may be called more than once for the same node — `AssignNodeIds` walks a subtree on every create pass — so an implementation has to be idempotent or the address space ends up with orphaned references. ## DefaultNodeIdFactory `Opc.Ua.Server/NodeManager/DefaultNodeIdFactory.cs` is the stack's implementation. It is immutable and safe to share. ### The canonical path Every mode except `Counter` derives from one canonical browse path: a length-prefixed encoding of the parent identifier and the child browse name. ``` v1:10:l:6:s=Root:10:l:6:Group1 ``` Each segment carries its own length, so no combination of parent and browse name can produce the same path as a different combination. The classic `{parentIdentifier}_{browseName}` convention could: `A_B` plus `C` and `A` plus `B_C` both gave `A_B_C`. The parent segment keeps the parent's identifier type prefix (`s=`, `i=`, `g=`, `b=`), so a string parent `"42"` never reads as a numeric parent `42`. Segments are qualified by namespace: | Prefix | Meaning | |---|---| | `l:` | in the namespace being minted into | | `z:` | in namespace 0 | | `u::` | in another namespace, named by URI | | `x::` | in another namespace that has no URI registered | The URI form is what makes an identifier independent of namespace-table ordering. The index form is a fallback for an unregistered namespace; it is deliberately distinct so identifiers minted before the namespace was registered cannot collide with the ones minted after. The path is temporary. Except in `String` mode, the factory hashes it and discards it without creating a string. It builds the path in a stack buffer, or rents a buffer from `ArrayPool` when needed. One routine measures and writes the path, so the reserved segment length always matches the written length. ### Modes `NodeIdAssignmentMode` selects how the path becomes an identifier. | Mode | Identifier | Stable across restarts | Collides when browse paths repeat | |---|---|---|---| | `None` | none — raises `BadConfigurationError` | — | — | | `Numeric` | first 32 bits of the path's SHA-256 | yes | yes, plus hash collisions | | `String` | the canonical path verbatim | yes | yes | | `Guid` | first 128 bits of the path's SHA-256 | yes | yes | | `Opaque` | first 128 bits of the path's SHA-256 | yes | yes | | `Counter` | sequential number | no | no | `Numeric` is the default: it is the most compact form on the wire and the most readable in a client UI. `String` is the only mode that cannot collide for distinct browse paths, because it keeps the canonical path whole and two different paths are never the same text. The others project the path through SHA-256 and inherit that hash's collision probability — negligible for `Guid` and `Opaque` at 128 bits, but real for `Numeric` at 32. ### Collision detection A 32 bit identifier is a birthday problem: distinct browse paths are expected to land on one after roughly 2^16 of them. Left alone that is silent damage, because the predefined-node index takes the last writer — one node would simply replace the other and the address space would be quietly wrong. So the factory records what it mints and raises `BadConfigurationError` when a second browse path lands on an identifier that a different one already has. The error names the path that was refused and the modes that do not have the problem. Minting the same path twice is normal — `AssignNodeIds` walks a subtree on every create pass — so the record keeps a witness of the path alongside the identifier, and only a *differing* witness is a collision. The witness is the tail of the same hash, so two paths would have to agree on the identifier and on a further 64 bits before a real collision could pass as a re-mint. Three consequences worth knowing: - The factory keeps a record per namespace because identifiers in different namespaces cannot collide. Views derived from one factory share that record. Therefore, two NodeManagers that rebase the registered factory onto the same namespace are checked against each other and draw sequential identifiers from one counter. NodeManagers that construct separate factories instead of using the registered factory do not share records. - The factory never prunes the record. An identifier handed to a client remains reserved after its node is removed, so re-minting it for another path is a collision. The record costs roughly 50 bytes per distinct path. - It covers identifiers the factory mints, not identifiers a caller assigns. `String` identifiers cannot collide, so the factory keeps no record for them. `Counter` identifiers cannot collide with each other, but they use the same numeric namespace as hashes. When checking is enabled, the factory reserves each counter value to prevent another mode from minting it. If a counter value is already taken, the factory advances to the next value because the counter can move. `Counter` is for nodes whose browse paths repeat over time — per-session diagnostics objects, inference jobs, rediscovered assets. Its counter starts above `0x40000000`, out of reach of any authored model, so a long-running server cannot walk a runtime instance onto a type node. (The predefined-node index takes the last writer, so such a collision silently replaces the type rather than failing.) ### Which namespace Every identifier is minted into the factory's `DefaultNamespaceIndex` — the NodeManager's own namespace. Neither the parent's namespace nor the browse name's is consulted: - a parent can belong to a companion-specification model whose NodeIds are fixed by its NodeSet (`DeviceSet` in the DI namespace, for instance). A server may not mint identifiers there. - a browse name only names the type that declared the child. A NodeManager whose instance namespace is not its first one rebases the factory with `WithDefaultNamespaceIndex`. ### When an existing NodeId is kept `New` keeps a node's current NodeId when the caller can plausibly have chosen it, and mints a fresh one otherwise. Two cases qualify: - the identifier is **already in this NodeManager's namespace**, which no other model's NodeIds ever are; - the node **stands on its own** rather than hanging off a parent. `NodeState.Create` hands a root its NodeId before running the assignment pass, so a caller naming a node explicitly arrives this way. Everything else is re-minted, because it reached `New` through `AssignNodeIds` walking a subtree copied from a type declaration and still carrying that declaration's identifiers. See [Who forces a fresh identifier](#who-forces-a-fresh-identifier). ### Nodes with no derivable path A node with no browse name, or one hanging off a transient parent that has no NodeId (an event instance and its fields), has no stable path. Those fall back to the counter whatever mode is selected, so a NodeManager never has to special-case them. ## Types and instances An information model ships **type declarations**: `PumpType` and every child below it, each with a NodeId fixed by the NodeSet. When a server creates an instance, `NodeState.CreateInstance` copies that subtree — and the copy carries the declaration's NodeIds. Rebasing the copy onto per-instance identifiers is what `NodeState.AssignNodeIds` does: it walks the subtree calling `INodeIdFactory.New` on each node, collects an old-to-new mapping table, and hands it to `UpdateReferenceTargets` so references inside the subtree follow. If `New` returns the declaration NodeId unchanged, every instance of the type aliases onto the type's own nodes. The failure is silent: the predefined-node index replaces rather than rejects, so the ObjectType quietly becomes an instance node. Guarding against that is the reason `DefaultNodeIdFactory` re-mints anything it did not mint itself, and the reason the generator's helpers check the declaration constant before rebasing. Type nodes themselves are never passed through `AssignNodeIds`; they are loaded from the NodeSet and registered as predefined nodes. ## What the source generator emits For each child of a generated type the generator emits helpers that materialise it, each with its own NodeId policy. `Create{Type}` / `CreateInstanceOf{Type}Type(parent, browseName)` — builds an instance and rebases the subtree through the context's factory. `Add{Child}(context, nodeId = default)`: | Argument | Behaviour | |---|---| | `nodeId` non-null | the child takes that NodeId, then its descendants are rebased around it | | `nodeId` null | rebased through the factory, but **only if** the child still carries its declaration constant | `CreateOrReplace{Child}(context, replacement, assignInstanceNodeIds)`: | Argument | Behaviour | |---|---| | `assignInstanceNodeIds` false | the child keeps whatever NodeId it has | | `assignInstanceNodeIds` true | rebased, but only if the NodeId is null or still the declaration constant | The declaration-constant guard (`nodeState.NodeId.Equals(TypeNodeIdConstant)`) is the generator's compile-time way of asking "is this still a declaration identifier?". It also means a caller who assigned an identifier explicitly keeps it. ## NodeManager behaviour ### CustomNodeManager2 Unchanged, for backwards compatibility: ```csharp public virtual NodeId New(ISystemContext context, NodeState node) { return node.NodeId; } ``` It mints nothing. A node keeps whatever NodeId it already has, and a node with none keeps `NodeId.Null`. Subclasses that need identifiers override `New` themselves. Existing servers built on this base see no change in behaviour. ### AsyncCustomNodeManager `New` delegates to the `NodeIdFactory` property and does nothing else. The manager holds no counter of its own. A subclass selects its identifier style by assigning that factory in its constructor rather than by overriding `New`: ```csharp NodeIdFactory = NodeIdFactory.WithMode(NodeIdAssignmentMode.Counter); ``` `WithMode` and `WithDefaultNamespaceIndex` both return a copy, so a factory shared through dependency injection is never mutated. Assigning a factory that names no namespace (a bare `new DefaultNodeIdFactory(mode)`) adopts the manager's own namespace; one that names a namespace is left alone. The default is `NodeIdAssignmentMode.Numeric`, so a manager that overrides nothing gets compact deterministic browse-path identifiers, checked for collisions. When `AddNodes` receives no `RequestedNewNodeId`, the preferred identifier may already belong to a live node, for example after that node's BrowseName was changed. The manager then asks the configured factory for a fresh counter identifier, skipping identifiers already registered or reserved by another in-flight `AddNodes` request. It reserves the choice before asynchronous registration and releases the reservation if registration fails or is canceled. The existing node and its references are not replaced. Clients must use the `addedNodeId` returned by the service rather than assuming the preferred browse-path identifier was available. A client-supplied `RequestedNewNodeId` is never substituted: an occupied or reserved identifier returns `BadNodeIdExists`. Duplicate BrowseNames and invalid namespaces are still rejected. Factory errors remain visible; a counter factory that repeats an occupied identifier reports `BadConfigurationError` instead of causing an unbounded retry. ### FluentNodeManagerBase and the fluent builders `FluentNodeManagerBase` derives from `AsyncCustomNodeManager` and inherits its behaviour. The fluent builders — `AddObject`, `WithProperty`, `CreateInstance`, and the alarm and state-machine helpers — mint through `FluentNodeRegistration.AssignNodeId`, which routes to the owning manager's `New`. They no longer each spell out a `{parentIdentifier}_{browseName}` concatenation. Inside a `Configure` delegate the mode can be selected for everything created after it: ```csharp builder.WithNodeIdAssignment(NodeIdAssignmentMode.Guid); ``` Every builder mints through the owning NodeManager's `New`, so there is no second identifier shape to fall back to. `WithNodeIdAssignment` needs the factory itself, which only an `AsyncCustomNodeManager` carries, so on any other NodeManager it raises `BadConfigurationError` rather than quietly doing nothing. ## Configuring the factory Through dependency injection, once for the whole server: ```csharp builder.AddNodeIdFactory(NodeIdAssignmentMode.Guid); ``` `DependencyInjectionStandardServer` resolves the registered `IRebasableNodeIdFactory`, `StandardServer` threads it into `ServerInternalData`, and every `AsyncCustomNodeManager` picks it up through `INodeIdFactoryProvider`, rebased onto its own namespace. The registration is keyed on the interface, so an implementation of your own — typically a decorator holding a `DefaultNodeIdFactory` — can be registered in its place: ```csharp builder.AddNodeIdFactory(new ReservingNodeIdFactory(new DefaultNodeIdFactory())); ``` ## Who forces a fresh identifier For a redundant server set, use [`UseReplicaNodeIdentity`](ReplicaNodeIdentity.md) rather than configuring independent default factories. It reserves the same shared namespace indexes before node-manager construction, binds the assignment policy across replicas, and preserves IDs during hydration. Counter/no-path allocation is not independently reproducible; only the configured active/passive writer may register those shared allocations. Ordinary single-server defaults are unchanged. Two things can be true of a node arriving at `New` with a NodeId already set: the caller chose that identifier, or it is a type declaration's identifier that `NodeState.CreateInstance` copied onto an instance. The factory cannot tell them apart, so the rule is positional rather than inferred: - a node that **stands on its own** keeps its NodeId; - a node **hanging off a parent** is re-minted, because it reached `New` through `AssignNodeIds` walking a copied subtree. A root that must also shed a declaration identifier says so by naming the identifier it wants. `ISystemContext.CreateInstance` is the short way to do that: it builds the subtree and then rebases it through `AssignInstanceNodeId`, which forces a fresh identifier by clearing the NodeId and asking again. That is the same path the generated `CreateInstanceOf{Type}` helpers take, so hand-written and generated authoring agree. Reaching for `NodeState.Create(..., NodeId.Null, ..., assignNodeIds: true)` on a generated state object is the trap: the object is born carrying its own type's NodeId, `Create` only replaces that when handed an identifier, and the result is an instance sitting on the type's node.