Add NodeStatus service package and docs

Introduce a new EntglDb.Services.NodeStatus project implementing a node-status diagnostic service. Added: project file (csproj) with Proto/Grpc dependencies, nodestatus.proto (wire types 1000/1001), INodeStatusService API, NodeStatusClient (uses IPeerMessenger), NodeStatusHandler (INetworkMessageHandler responder), NodeStatusInfo model, and DI extension AddEntglDbNodeStatus. Also updated README examples and docs to clarify custom message type ranges (32–999) and that official packages use 1000+; updated sync README examples to use a sample custom type (100). This enables querying remote peer runtime status over the shared EntglDb P2P connection.

Author: mrdevrobot

README.md

@@ -537,8 +537,8 @@ Reserve a message type constant (≥ 32):
 ```csharp
 public static class MyMessageType
 {
-    public const int PingRequest  = 32;
-    public const int PingResponse = 33;
+    public const int PingRequest  = 100;  // any value in the 32–999 custom range
+    public const int PingResponse = 101;
 }
 ```
 
@@ -637,7 +637,8 @@ builder.Services.AddSingleton<MyClientService>();
 | 0–2   | Protocol control (handshake, keepalive) |
 | 3–15  | Built-in sync messages (`SyncMessageType`) |
 | 16–31 | Reserved for future EntglDb use |
-| **32+** | **Your custom services** |
+| **32–999** | **Your custom services** |
+| 1000+ | Official EntglDb service packages (e.g. `EntglDb.Services.NodeStatus` uses 1000–1001) |
 
 ---
 

src/EntglDb.Services.NodeStatus/EntglDb.Services.NodeStatus.csproj

@@ -0,0 +1,43 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>netstandard2.1;net10.0</TargetFrameworks>
+    <LangVersion>latest</LangVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <Version>1.0.0</Version>
+    <Authors>MrDevRobot</Authors>
+    <Description>Node status diagnostic service for the EntglDb P2P mesh network. Allows any node to query the runtime status of remote peers over the shared TCP connection.</Description>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageTags>p2p;mesh;entgldb;distributed;diagnostics;nodestatus</PackageTags>
+    <PackageProjectUrl>https://github.com/EntglDb/EntglDb.Net</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/EntglDb/EntglDb.Net</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageIcon>icon.png</PackageIcon>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="\" />
+    <None Include="..\..\assets\icon.png" Pack="true" PackagePath="\" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\EntglDb.Network\EntglDb.Network.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Google.Protobuf" Version="3.34.1" />
+    <PackageReference Include="Grpc.Tools" Version="2.78.0">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.5" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.5" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Protobuf Include="nodestatus.proto" GrpcServices="None" />
+  </ItemGroup>
+
+</Project>

src/EntglDb.Services.NodeStatus/INodeStatusService.cs

@@ -0,0 +1,28 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace EntglDb.Services.NodeStatus;
+
+/// <summary>
+/// Client-side API for querying the runtime status of a remote peer
+/// over the EntglDb P2P mesh network.
+/// </summary>
+/// <remarks>
+/// Inject this service and call <see cref="QueryAsync"/> with the peer's
+/// <c>host:port</c> address.  The underlying TCP connection is shared with
+/// the sync engine — no extra socket is opened.
+/// <code>
+/// var status = await nodeStatusService.QueryAsync("192.168.1.10:7000", ct);
+/// Console.WriteLine($"{status.NodeId} up for {status.Uptime.TotalMinutes:F0} min");
+/// </code>
+/// </remarks>
+public interface INodeStatusService
+{
+    /// <summary>
+    /// Queries a remote peer for its current runtime status.
+    /// </summary>
+    /// <param name="peerAddress">Remote peer address in <c>host:port</c> format.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A <see cref="NodeStatusInfo"/> snapshot from the remote peer.</returns>
+    Task<NodeStatusInfo> QueryAsync(string peerAddress, CancellationToken ct = default);
+}

src/EntglDb.Services.NodeStatus/NodeStatusClient.cs

@@ -0,0 +1,45 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using EntglDb.Network;
+using EntglDb.Services.NodeStatus.Proto;
+
+namespace EntglDb.Services.NodeStatus;
+
+/// <summary>
+/// Default implementation of <see cref="INodeStatusService"/>.
+/// Uses <see cref="IPeerMessenger"/> to send a <see cref="NodeStatusRequest"/> to the remote peer
+/// and parse the <see cref="NodeStatusResponse"/> back as a <see cref="NodeStatusInfo"/>.
+/// </summary>
+internal sealed class NodeStatusClient : INodeStatusService
+{
+    private readonly IPeerMessenger _messenger;
+
+    public NodeStatusClient(IPeerMessenger messenger)
+    {
+        _messenger = messenger;
+    }
+
+    /// <inheritdoc/>
+    public async Task<NodeStatusInfo> QueryAsync(string peerAddress, CancellationToken ct = default)
+    {
+        var (responseType, payload) = await _messenger.SendAndReceiveAsync(
+            peerAddress,
+            (int)NodeStatusMessageType.NodeStatusReq,
+            new NodeStatusRequest(),
+            ct);
+
+        if (responseType != (int)NodeStatusMessageType.NodeStatusRes)
+            throw new InvalidOperationException(
+                $"Unexpected response type {responseType} from peer '{peerAddress}'.");
+
+        var proto = NodeStatusResponse.Parser.ParseFrom(payload);
+
+        return new NodeStatusInfo
+        {
+            NodeId = proto.NodeId,
+            Uptime = TimeSpan.FromSeconds(proto.UptimeSeconds),
+            KnownPeerAddresses = proto.KnownPeerAddresses,
+        };
+    }
+}

src/EntglDb.Services.NodeStatus/NodeStatusExtensions.cs

@@ -0,0 +1,38 @@
+using EntglDb.Network;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+
+namespace EntglDb.Services.NodeStatus;
+
+/// <summary>
+/// Extension methods for registering EntglDb node-status diagnostic services.
+/// </summary>
+public static class NodeStatusExtensions
+{
+    /// <summary>
+    /// Adds the EntglDb node-status service to the DI container.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Registers:
+    /// <list type="bullet">
+    ///   <item><see cref="NodeStatusHandler"/> as <see cref="INetworkMessageHandler"/> (server-side responder, wire type 1000)</item>
+    ///   <item><see cref="INodeStatusService"/> / <see cref="NodeStatusClient"/> (client-side query API)</item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// Call <c>AddEntglDbNetwork&lt;T&gt;()</c> before this method so that
+    /// <see cref="IPeerMessenger"/> is already registered.
+    /// </para>
+    /// </remarks>
+    public static IServiceCollection AddEntglDbNodeStatus(this IServiceCollection services)
+    {
+        // Server side: handle incoming NodeStatusRequest messages (wire type 1000)
+        services.AddSingleton<INetworkMessageHandler, NodeStatusHandler>();
+
+        // Client side: let consumers query remote peers
+        services.TryAddSingleton<INodeStatusService, NodeStatusClient>();
+
+        return services;
+    }
+}

src/EntglDb.Services.NodeStatus/NodeStatusHandler.cs

@@ -0,0 +1,69 @@
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+using EntglDb.Core.Network;
+using EntglDb.Network;
+using EntglDb.Services.NodeStatus.Proto;
+using Google.Protobuf;
+using Microsoft.Extensions.Logging;
+
+namespace EntglDb.Services.NodeStatus;
+
+/// <summary>
+/// Server-side handler that responds to <see cref="NodeStatusMessageType.NodeStatusReq"/> (wire type 1000)
+/// with a snapshot of the local node's runtime status.
+/// </summary>
+/// <remarks>
+/// Register this handler in DI <em>after</em> <c>AddEntglDbNetwork</c>:
+/// <code>
+/// services.AddEntglDbNetwork&lt;MyConfig&gt;();
+/// services.AddEntglDbNodeStatus();   // registers NodeStatusHandler + INodeStatusService
+/// </code>
+/// </remarks>
+public sealed class NodeStatusHandler : INetworkMessageHandler
+{
+    private readonly IPeerNodeConfigurationProvider _configProvider;
+    private readonly IDiscoveryService _discovery;
+    private readonly ILogger<NodeStatusHandler> _logger;
+    private readonly DateTimeOffset _startTime = DateTimeOffset.UtcNow;
+
+    // Assembly version is resolved once at construction time.
+    private static readonly string ServiceVersion =
+        typeof(NodeStatusHandler).Assembly.GetName().Version?.ToString() ?? "unknown";
+
+    public int MessageType => (int)NodeStatusMessageType.NodeStatusReq;
+
+    public NodeStatusHandler(
+        IPeerNodeConfigurationProvider configProvider,
+        IDiscoveryService discovery,
+        ILogger<NodeStatusHandler> logger)
+    {
+        _configProvider = configProvider;
+        _discovery = discovery;
+        _logger = logger;
+    }
+
+    /// <inheritdoc/>
+    public async Task<(IMessage? Response, int ResponseType)> HandleAsync(IMessageHandlerContext context)
+    {
+        var config = await _configProvider.GetConfiguration();
+
+        var activePeers = _discovery.GetActivePeers().ToList();
+
+        var response = new NodeStatusResponse
+        {
+            NodeId = config.NodeId,
+            UptimeSeconds = (long)(DateTimeOffset.UtcNow - _startTime).TotalSeconds,
+            KnownPeerCount = activePeers.Count,
+            ServiceVersion = ServiceVersion,
+        };
+
+        foreach (var peer in activePeers)
+            response.KnownPeerAddresses.Add(peer.Address);
+
+        _logger.LogDebug("NodeStatus query from {Remote}: responded with {PeerCount} known peers",
+            context.RemoteEndPoint, activePeers.Count);
+
+        return (response, (int)NodeStatusMessageType.NodeStatusRes);
+    }
+}

src/EntglDb.Services.NodeStatus/NodeStatusInfo.cs

@@ -0,0 +1,19 @@
+using System;
+using System.Collections.Generic;
+
+namespace EntglDb.Services.NodeStatus;
+
+/// <summary>
+/// Runtime status snapshot reported by a remote peer.
+/// </summary>
+public sealed class NodeStatusInfo
+{
+    /// <summary>The unique node identifier of the responding peer.</summary>
+    public string NodeId { get; init; } = string.Empty;
+
+    /// <summary>How long the peer process has been running.</summary>
+    public TimeSpan Uptime { get; init; }
+
+    /// <summary>Addresses (<c>host:port</c>) of all peers currently visible to the responding node.</summary>
+    public IReadOnlyList<string> KnownPeerAddresses { get; init; } = Array.Empty<string>();
+}

src/EntglDb.Services.NodeStatus/nodestatus.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package EntglDb.Services.NodeStatus.Proto;
+
+option csharp_namespace = "EntglDb.Services.NodeStatus.Proto";
+
+// Wire values 1000–1001 are reserved for EntglDb.Services.NodeStatus.
+// User-defined services should pick blocks that do not overlap with other
+// registered packages.  The range 32–999 is available for custom use;
+// ranges above 1000 are used by official EntglDb service packages.
+enum NodeStatusMessageType {
+  NodeStatusUnknown = 0;     // Required by proto3; never sent on the wire.
+  NodeStatusReq     = 1000;
+  NodeStatusRes     = 1001;
+}
+
+// Sent by a node that wants to know the remote peer's runtime status.
+message NodeStatusRequest {
+}
+
+// Returned by the remote peer with its current runtime status.
+message NodeStatusResponse {
+  // The unique node identifier of the responding peer.
+  string node_id = 1;
+
+  // How long the node process has been running, in whole seconds.
+  int64 uptime_seconds = 2;
+
+  // Number of peers currently visible to this node via discovery.
+  int32 known_peer_count = 3;
+
+  // Addresses (host:port) of all currently active peers.
+  repeated string known_peer_addresses = 4;
+
+  // Semantic version string of the running EntglDb.Services.NodeStatus package.
+  string service_version = 5;
+}

src/EntglDb.Sync/README.md

@@ -39,7 +39,7 @@ Message types ≥ 32 are reserved for user services.
 // Server side — handle incoming requests
 public class PingHandler : INetworkMessageHandler
 {
-    public int MessageType => 32;
+    public int MessageType => 100;  // pick any value in the 32–999 custom range
 
     public Task<(IMessage? Response, int ResponseType)> HandleAsync(IMessageHandlerContext context)
     {
@@ -54,7 +54,7 @@ services.AddSingleton<INetworkMessageHandler, PingHandler>();
 
 // Client side — send a request
 var (_, payload) = await messenger.SendAndReceiveAsync(
-    "192.168.1.10:7000", 32, new PingRequest { Message = "hello" }, ct);
+    "192.168.1.10:7000", 100, new PingRequest { Message = "hello" }, ct);
 var response = PingResponse.Parser.ParseFrom(payload);
 ```