mirror of
https://github.com/Cog-Creators/Red-DiscordBot.git
synced 2025-11-06 11:18:54 -05:00
b983d5904b
* Switch RPC libs for websockets support * Implement RPC handling for core * Black reformat * Fix docs for build on travis * Modify RPC to use a Cog base class * Refactor rpc server reference as global * Handle cogbase unload method * Add an init call to handle mutable base attributes * Move RPC server reference back to the bot object * Remove unused import * Add tests for rpc method add/removal * Add tests for rpc method add/removal and cog base unloading * Add one more test * Black reformat * Add RPC mixin...fix MRO * Correct internal rpc method names * Add rpc test html file for debugging/example purposes * Add documentation * Add get_method_info * Update docs with an example RPC call specifying parameter formatting * Make rpc methods UPPER * Black reformat * Fix doc example * Modify this to match new method naming convention * Add more tests
64 lines
2.2 KiB
ReStructuredText
64 lines
2.2 KiB
ReStructuredText
.. rpc docs
|
|
|
|
===
|
|
RPC
|
|
===
|
|
|
|
V3 comes default with an internal RPC server that may be used to remotely control the bot in various ways.
|
|
Cogs must register functions to be exposed to RPC clients.
|
|
Each of those functions must only take JSON serializable parameters and must return JSON serializable objects.
|
|
|
|
To enable the internal RPC server you must start the bot with the ``--rpc`` flag.
|
|
|
|
********
|
|
Examples
|
|
********
|
|
|
|
.. code-block:: Python
|
|
|
|
def setup(bot):
|
|
c = Cog()
|
|
bot.add_cog(c)
|
|
bot.register_rpc_handler(c.rpc_method)
|
|
|
|
*******************************
|
|
Interacting with the RPC Server
|
|
*******************************
|
|
|
|
The RPC server opens a websocket bound to port ``6133`` on ``127.0.0.1``.
|
|
This is not configurable for security reasons as broad access to this server gives anyone complete control over your bot.
|
|
To access the server you must find a library that implements websocket based JSONRPC in the language of your choice.
|
|
|
|
There are a few built-in RPC methods to note:
|
|
|
|
* ``GET_METHODS`` - Returns a list of available RPC methods.
|
|
* ``GET_METHOD_INFO`` - Will return the docstring for an available RPC method. Useful for finding information about the method's parameters and return values.
|
|
* ``GET_TOPIC`` - Returns a list of available RPC message topics.
|
|
* ``GET_SUBSCRIPTIONS`` - Returns a list of RPC subscriptions.
|
|
* ``SUBSCRIBE`` - Subscribes to an available RPC message topic.
|
|
* ``UNSUBSCRIBE`` - Unsubscribes from an RPC message topic.
|
|
|
|
All RPC methods accept a list of parameters.
|
|
The built-in methods above expect their parameters to be in list format.
|
|
|
|
All cog-based methods expect their parameter list to take one argument, a JSON object, in the following format::
|
|
|
|
params = [
|
|
{
|
|
"args": [], # A list of positional arguments
|
|
"kwargs": {}, # A dictionary of keyword arguments
|
|
}
|
|
]
|
|
|
|
# As an example, here's a call to "get_method_info"
|
|
rpc_call("GET_METHOD_INFO", ["get_methods",])
|
|
|
|
# And here's a call to "core__load"
|
|
rpc_call("CORE__LOAD", {"args": [["general", "economy", "downloader"],], "kwargs": {}})
|
|
|
|
*************
|
|
API Reference
|
|
*************
|
|
|
|
Please see the :class:`redbot.core.bot.RedBase` class for details on the RPC handler register and unregister methods.
|