feat(framework): support admin IPC and RPC

[317787106]

What does this PR do?

This PR adds the Admin JSON-RPC transport foundation requested by tronprotocol/java-tron#6497. A single annotated AdminJsonRpc interface is shared by an HTTP endpoint and a local Unix-domain-socket service. The initial admin_example method verifies typed command dispatch and annotation-based JSON-RPC error handling; additional administrative methods can be added to the same interface.

Admin HTTP RPC

The HTTP service is available to FullNode processes at POST /admin and is disabled by default. It binds Jetty to the configured address and port. Enabling it on a non-loopback address emits a warning.

The servlet validates the Host header against the configured virtual-host allowlist, while accepting IPv4 and IPv6 literals. It accepts application/json, application/json-rpc, and application/*+json media types, and rejects unsupported content types with HTTP 415. JSON-RPC parsing reuses a constrained object mapper with nesting-depth and token-count limits. JSON-RPC results, including protocol errors, use HTTP 200 responses.

The configuration is:

node.admin.rpc {
  enable = false
  listenAddress = "127.0.0.1"
  port = 8575
  virtualHosts = ["localhost"]
}

Admin IPC service

The IPC service is also FullNode-only and disabled by default. By default it creates an endpoint at:

<output-directory>/.ipc/<pid>.sock

node.admin.ipc.socketDirectory can select another socket root and must be an existing absolute directory on a POSIX-compatible filesystem. The service creates the private .ipc directory with owner-only access and sets the socket to 0600. It refuses to replace a symbolic link or non-directory at the private directory path.

The complete encoded socket path is limited to 100 bytes for portability across supported Unix-domain-socket implementations. If the path is longer, startup fails with guidance to configure a shorter node.admin.ipc.socketDirectory; it does not silently relocate the endpoint.

node.admin.ipc {
  enable = false
  socketDirectory = ""
}

IPC uses newline-delimited, single-line JSON-RPC messages and the same AdminJsonRpc, error resolver, and constrained JSON mapper as HTTP. Request size is bounded by the existing node.rpc.maxMessageSize value, whose default is 4 MiB. Each client has a ten-minute idle timeout. The bounded client executor supports concurrent console sessions and immediately closes connections that arrive after all handlers are occupied. Unexpected accept failures use a five-second retry delay.

Startup failures and normal shutdown both clean up owned sockets and the private directory. Shutdown closes active clients before stopping executors so blocked native socket reads do not unnecessarily delay node termination.

IPC console

The FullNode executable can attach to an active node without initializing another node instance:

java -jar FullNode.jar --attach <socket-path>

A single command can be executed for scripting:

java -jar FullNode.jar --attach <socket-path> --exec "<command> [arguments]"

Attach mode is handled immediately after CLI argument parsing and before CommonParameter, Logback, database, witness, or node services are initialized. --exec requires --attach, an empty socket path is rejected, and attach mode cannot be combined with --config.

The JLine console derives command names, parameter names, and parameter types from the annotated Admin API. It supports quoted arguments, typed JSON conversion, sorted help, canonical command completion, formatted JSON results, help, exit, and quit. One-shot execution returns a non-zero process status for invalid commands, JSON-RPC errors, communication failures, disconnection before a response, or the 30-second response timeout.

Supporting changes

HttpService now supports binding a service to a specific listen address. The regular JSON-RPC servlet and the Admin transports share the new constrained JsonRpcMapper, and supported JSON media-type matching is centralized in JsonRpcMediaType.

The framework adds JLine for the interactive console and junixsocket for Unix-domain-socket support. Dependency verification metadata is updated accordingly.

Why are these changes required?

Administrative operations need a local, scriptable interface without starting a second node or exposing the existing public APIs as privileged management endpoints. The Unix-domain socket provides a private local transport, while the optional HTTP endpoint supports controlled integration when explicitly enabled.

Sharing one typed Admin API across both transports keeps command names, parameters, results, and JSON-RPC errors consistent. Explicit address binding, virtual-host validation, parser limits, filesystem permissions, bounded clients, and deterministic cleanup provide safer operational defaults.

Testing

The PR adds or updates tests covering:

• Admin configuration defaults, binding, and attach-mode CLI validation.
• HTTP listen-address handling, loopback classification, virtual-host validation, JSON media types, and parser limits.
• IPC path resolution and encoded-length limits, absolute-directory validation, POSIX permissions, stale-path safety, startup rollback, and shutdown cleanup.
• IPC request limits, annotated errors, concurrent clients, idle timeouts, overload rejection, and active-client shutdown.
• Console command discovery, typed arguments, quoted whitespace, completion, help, response formatting, one-shot exit codes, timeouts, and disconnect behavior.
• FullNode startup ordering to ensure attach mode does not initialize node logging.

The related Admin HTTP, IPC, CLI, configuration, and FullNode tests, together with production and test checkstyle checks, passed during development.

Follow-up

Runtime parameter export is split into stacked Draft PR #83. Peer management commands will be implemented separately on feature/peer_management using the Admin transports introduced here.