JSON-RPC modeling
Nexus uses typed Object Pascal objects to represent JSON-RPC messages. The wire protocol remains JSON-RPC 2.0; protocol-specific request classes describe their parameters and results through published properties.
The JSON value model lives in the serialization packages. The JSON-RPC envelope,
request/result contracts, and parsing helpers live under
packages/nexus-packages/network/json-rpc.
Message model
| Class/property | Role |
|---|---|
TNXJSONRPCMessage |
Envelope, jsonrpc, typed id, and message classification |
TNXJSONRPCCommandMessage |
method and TNXJSONRPCObjectParams |
TNXJSONRPCRequest |
Typed result, execution, and result validation |
TNXJSONRPCResponse |
Result or error response |
TNXJSONRPCError |
Code, message, and optional data |
TNXJSONRPCOutboundCommand |
Outbound request and its completion/error handling |
The ID uses TNXJSONRPCID; result APIs use TNXJSONRPCValue.
Protocol-specific parameter objects derive from the JSON-RPC parameter base.
Implement a request
A request descendant supplies its method through GetFactoryName, exposes
protocol-specific published parameter/result properties, and overrides:
function Execute: TNXJSONRPCValue; override;
Register the class with TNXClassFactory during initialization.
The message parser can then select the concrete class for a registered method.
Use PrepareResult to create the result required by the request's contract.
GetResultKind distinguishes no result, null, concrete, and nullable concrete
results. Validate the returned value against that contract.
The language-server request units provide complete examples, including
projects/ls/nxscript/src/protocol/obNexusScriptLSLifecycleRequests.pas.
Follow a real request with the desired result shape rather than treating all
results as arbitrary objects.
Dispatch and errors
TNXJSONRPC.ParseMessage and ParseMessages parse envelopes.
ValidateMessage checks them under the selected envelope policy.
Success/error response helpers construct the corresponding responses.
The application owns dispatch policy and lifecycle. Requests receive responses; notifications do not. Incoming responses belong to outbound-request matching, not ordinary inbound command dispatch.
Standard JSON-RPC error codes include parse error, invalid request, method not found, invalid params, and internal error. Application-specific structured error information belongs in the error data.
Ownership
Published JSON properties participate in the object model's serialization and ownership rules. Respect the owning request/response and dispatcher contracts; do not share managed Pascal objects across a native module ABI.
For a loadable test module, NexusTest instead exchanges UTF-8 JSON-RPC text through its C-style exported functions.