Remote Procedure Calls (RPC)

The CodeSonar hub can request analysis information that is not stored on the hub via a remote procedure call (RPC) mechanism. There are numerous predefined RPC handlers which provide the information required by the standard features of the CodeSonar hub, but if you want to process hub requests from a plugin you need to register your own RPC handler.

The rpc_handler() decorator can be used on any function that takes one argument (the request) and returns a response object.

RPC Handler Tutorial

Let’s make a sample RPC handler that takes the names of procedures and returns the number of callers to each procedure.

1. Save the following as $INSTALL/codesonar/plugins/rpc_tutorial.plugin.py.

   import cs
   
   @cs.rpc_handler('get_num_callers')
   def ncallers(request):
       response = dict()
       project = cs.project.current()
       for proc_name in request['procedures']:
           proc = project.find_procedure(proc_name)
           response[proc_name] = proc.callers_count()
       return response
   

2. Build and analyze any CodeSonar project. Make a note of the analysis ID.

3. Navigate to the RPC Test page on your hub: http://<host>:<port>/rpc/test/ (or https://<host>:<port>/rpc/test/, if your hub is running HTTPS).

4. Fill out the form as follows.

   • Analysis ID: enter your analysis ID

   • Message Kind: leave empty

   • Message Content:

     {
         "jsonrpc": "2.0",
         "method": "plugin_message",
         "params": {
                     "arguments": "{\"procedures\": [\"main\"]}",
                     "plugin_handler_name": "get_num_callers"
                   }
     }
     

     Note that the “arguments” field is itself a string encoding of a JSON value.

5. Click Submit Query.

The page will update to display Encoded Message Content and Message Response for your query.

In the example above an exception could be thrown due to a malformed request (missing the ‘procedures’ key) or due to a failure to look up one of the requested procedure names. In most cases you will want to add your own error handling within your function to return a partial response or a more detailed error message, but any exceptions that are not caught will cause a generic RPC failure response to be sent back to the hub.

RPC Handler Decorator

@cs.rpc_handler(handlername[, JSON = True])

Add the decorated function as a remote procedure call handler.

Parameters:

• handlername (str) – A unique name for the handler. This is the name that must be used to issue the RPC request from the hub.
• JSON (bool) – (optional) If True, the argument passed to the decorated function will be a JSON object, and the response value should be encoded as a JSON string. If False, the request and response will be plain strings.

The request and response messages that are exchanged between the hub and the analysis are plain strings. However, it is very common to use JSON to exchange richer request and response objects so the default mode for the rpc_handler() decorator is to decode the request string as a JSON object before passing it to your function and to encode your response as a JSON string. If you want to have direct access to the request and response strings, (that is, you don’t want to use JSON) specify JSON=False.