Skip to main content

AdminRpc

surfpool_core::rpc::admin

Trait AdminRpc 

Source 
pub trait AdminRpc:
    Sized
    + Send
    + Sync
    + 'static {
    type Metadata: Metadata;

    // Required methods
    fn exit(&self, meta: Self::Metadata) -> Result<()>;
    fn reload_plugin(
        &self,
        meta: Self::Metadata,
        name: String,
        config_file: String,
    ) -> BoxFuture<Result<()>>;
    fn unload_plugin(
        &self,
        meta: Self::Metadata,
        name: String,
    ) -> BoxFuture<Result<()>>;
    fn load_plugin(
        &self,
        meta: Self::Metadata,
        config_file: String,
    ) -> BoxFuture<Result<String>>;
    fn list_plugins(
        &self,
        meta: Self::Metadata,
    ) -> BoxFuture<Result<Vec<PluginInfo>>>;
    fn start_time(&self, meta: Self::Metadata) -> Result<String>;

    // Provided method
    fn to_delegate(self) -> IoDelegate<Self, Self::Metadata> { ... }
}

Required Associated Types§

Source

type Metadata: Metadata

Required Methods§

Source

fn exit(&self, meta: Self::Metadata) -> Result<()>

Immediately shuts down the RPC server.

This administrative endpoint is typically used during controlled shutdowns of the validator or service exposing the RPC interface. It allows remote administrators to gracefully terminate the process, stopping all RPC activity.

§Returns
  • Result<()> — A unit result indicating successful shutdown, or an error if the call fails.
§Example Request (JSON-RPC)
{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "exit",
  "params": []
}
§Notes
  • This method is privileged and should only be accessible to trusted clients.
  • Use with extreme caution in production environments.
  • If successful, the RPC server process will terminate immediately after processing this call.
§Security

Access to this method should be tightly restricted. Implement proper authorization mechanisms via the RPC metadata to prevent accidental or malicious use.

Source

fn reload_plugin( &self, meta: Self::Metadata, name: String, config_file: String, ) -> BoxFuture<Result<()>>

Source

fn unload_plugin( &self, meta: Self::Metadata, name: String, ) -> BoxFuture<Result<()>>

Reloads a runtime plugin with new configuration.

This administrative endpoint is used to dynamically reload a plugin without restarting the entire RPC server or validator. It is useful for applying updated configurations to a plugin that supports hot-reloading.

§Parameters
  • name: The identifier of the plugin to reload.
  • config_file: Path to the new configuration file to load for the plugin.
§Returns
  • BoxFuture<Result<()>> — A future resolving to a unit result on success, or an error if reloading fails.
§Example Request (JSON-RPC)
{
  "jsonrpc": "2.0",
  "id": 101,
  "method": "reloadPlugin",
  "params": ["myPlugin", "/etc/plugins/my_plugin_config.toml"]
}
§Notes
  • The plugin must support reloading in order for this to succeed.
  • A failed reload will leave the plugin in its previous state.
  • This method is intended for administrators and should be properly secured.
§Security

Ensure only trusted clients can invoke this method. Use metadata-based access control to limit exposure.

Source

fn load_plugin( &self, meta: Self::Metadata, config_file: String, ) -> BoxFuture<Result<String>>

Dynamically loads a new plugin into the runtime from a configuration file.

This administrative endpoint is used to add a new plugin to the system at runtime, based on the configuration provided. It enables extensibility without restarting the validator or RPC server.

§Parameters
  • config_file: Path to the plugin’s configuration file, which defines its behavior and settings.
§Returns
  • BoxFuture<Result<String>> — A future resolving to the name or identifier of the loaded plugin, or an error if the plugin could not be loaded.
§Example Request (JSON-RPC)
{
  "jsonrpc": "2.0",
  "id": 102,
  "method": "loadPlugin",
  "params": ["/etc/plugins/my_plugin_config.toml"]
}
§Notes
  • The plugin system must be initialized and support runtime loading.
  • The config file should be well-formed and point to a valid plugin implementation.
  • Duplicate plugin names may lead to conflicts or errors.
§Security

This method should be restricted to administrators only. Validate inputs and use access control.

Source

fn list_plugins( &self, meta: Self::Metadata, ) -> BoxFuture<Result<Vec<PluginInfo>>>

Returns a list of all currently loaded plugin names.

This administrative RPC method is used to inspect which plugins have been successfully loaded into the runtime. It can be useful for debugging or operational monitoring.

§Returns
  • Vec<PluginInfo> — A list of plugin information objects, each containing:
    • plugin_name: The name of the plugin (e.g., “surfpool-subgraph”)
    • uuid: The unique identifier of the plugin instance
§Example Request (JSON-RPC)
{
  "jsonrpc": "2.0",
  "id": 103,
  "method": "listPlugins",
  "params": []
}
§Example Response
{
  "jsonrpc": "2.0",
  "result": [
    {
      "plugin_name": "surfpool-subgraph",
      "uuid": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "id": 103
}
§Notes
  • Only plugins that have been successfully loaded will appear in this list.
  • This method is read-only and safe to call frequently.
Source

fn start_time(&self, meta: Self::Metadata) -> Result<String>

Returns the system start time.

This RPC method retrieves the timestamp of when the system was started, represented as a SystemTime. It can be useful for measuring uptime or for tracking the system’s runtime in logs or monitoring systems.

§Returns
  • SystemTime — The timestamp representing when the system was started.
§Example Request (JSON-RPC)
{
  "jsonrpc": "2.0",
  "id": 106,
  "method": "startTime",
  "params": []
}
§Example Response
{
  "jsonrpc": "2.0",
  "result": "2025-04-24T12:34:56Z",
  "id": 106
}
§Notes
  • The result is a String in UTC, reflecting the moment the system was initialized.
  • This method is useful for monitoring system uptime and verifying system health.

Provided Methods§

Source

fn to_delegate(self) -> IoDelegate<Self, Self::Metadata>

Create an IoDelegate, wiring rpc calls to the trait methods.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§