Clustron Nodus
Clustron Nodus is a clustering and messaging core for .NET. It gives a process everything it needs to join a peer-to-peer cluster, agree on a leader, exchange typed messages point-to-point or cluster-wide, and observe the health of its peers — without an external coordinator such as ZooKeeper, etcd, or Consul.
Nodus is the coordination layer other Clustron products build on. Zaris, the distributed key-value store, clusters on it, and Nodus is equally usable on its own wherever a set of processes must discover each other, elect a coordinator, and stay in agreement through failures.
- Version: 1.1.0
- Package to install:
Clustron.Nodus.Client - Transport and serialization: pipelined TCP with a prioritized outbound path; MessagePack on the wire.
The problem Nodus solves
A single-process application never has to ask who is in charge?, is my collaborator alive?, or did that message arrive? — the answers are local. The moment your application runs as more than one instance — for scale, for availability, or because it lives in containers — each of those questions becomes a distributed-systems problem that is easy to get almost right.
The distinct problems Nodus solves are these:
- Membership. Who is in the cluster right now, and how do you tell "slow" from "gone"?
- Coordination. Which instance runs the singleton job, and how do the others find out when it fails?
- Communication. How does one instance address another, send it work, and get an answer back?
- Failure detection. When a peer stops answering, how long do you wait before evicting it — without flapping?
The conventional answer is to stand up a separate coordination service (ZooKeeper, etcd, Consul), secure it, and keep it alive alongside your app. Nodus takes the opposite approach: it is a library you embed, so a Nodus cluster forms and heals itself with nothing external to run.
What Nodus gives you
A product holds a single INodusNode handle, and every capability hangs off that handle as a named area. Each area is a thin facade over the core services — transport, election, membership, heartbeat, and gossip — which in turn speak only the contracts defined in Clustron.Nodus.Abstractions.
Capabilities at a glance
Nodus groups its capabilities into the six areas below, each reached from the one INodusNode handle. Each area maps to a concept page that explains the model and the failure semantics.
| Capability | What it does | Node area | Concept |
|---|---|---|---|
| Peer-to-peer membership | Nodes discover and admit each other from a static or dynamically supplied peer set; join and leave surface as events. | node.Cluster | Membership |
| Leader election | Pluggable bully-style strategies (highest-id, oldest-node) with an epoch counter and an application-supplied tiebreaker for equal-epoch collisions. | node.Leadership | Leader election |
| Point-to-point and broadcast messaging | Send a typed payload to one node or to every member, drop to the raw wire message for full control, or use request/reply. | node.Messaging | Messaging |
| Cluster-wide events | A typed publish/subscribe bus, distinct from direct messaging, that propagates events across the cluster. | node.Events | Cluster events |
| Health and liveness | Heartbeat monitoring, per-peer reachability and last-heard-from timestamps, and a suspicion window before eviction. | node.Health, node.Cluster | Health and gossip |
| Gossip plane | Ride your own state digest on the heartbeat traffic and observe peers' digests, without running a second protocol. | node.Gossip | Health and gossip |
| Deterministic lifecycle | One entry point builds the container, joins the cluster, and returns a running handle; disposal leaves the cluster gracefully. | NodusNode, INodusNode | Building a node |
Standalone, or the foundation for Zaris
Nodus is designed to be used either way, and which layer you start at depends on whether you need a data store.
Use Nodus directly whenever a set of processes must discover each other, elect a coordinator, and stay in agreement through failures — and you do not need a data store:
- a leader-only scheduler — exactly one instance runs a cron-like job, and a survivor takes over on failure;
- a work distributor — a coordinator fans chunks of work across live members and aggregates the results (this is what the shipped
ClusterCoordinationsample does); - a cache that must invalidate peers — broadcast an eviction to every member;
- any cluster-aware service that needs to know who its live peers are and message them.
Rely on Nodus as a foundation when you use Zaris. Zaris clusters on Nodus for membership, leadership, and inter-node messaging, and layers partitioned storage, replication, and a control plane on top. If your need mentions data or cache, start at Zaris; otherwise Nodus is the right layer.
Nodus replaces the role that ZooKeeper, etcd, or Consul would play — but as an in-process library, with nothing external to run, secure, or keep alive.
Packages and targets
Nodus ships two packages: the contracts, which target netstandard2.0, and the node runtime, which targets net8.0. A host references only the runtime package.
| Package | Target | Purpose |
|---|---|---|
Clustron.Nodus.Abstractions | netstandard2.0 | Contracts, message and config models, cluster events. Reference this from thin clients, including .NET Framework 4.8. |
Clustron.Nodus.Client | net8.0 | The node facade (NodusNode / INodusNode) and the client runtime. Bundles the internal Clustron.Nodus.Core engine, so this is the only package a host needs. |
dotnet add package Clustron.Nodus.Client
Because the abstractions target netstandard2.0, the contracts run on .NET Framework 4.8 and .NET 8+ alike; the node runtime targets net8.0.
Next steps
- Getting started — install the package, form a two-node cluster on localhost, and observe join/leave events and the elected leader.
- Concepts — the mental model: membership, leader election, messaging, cluster events, and health and gossip.
- Developer guide — task-focused how-tos: building a node, sending messages, request/reply, subscribing to events, and querying health.