Package: jsonrpcx
OverviewA JSON-RPC 2.0 implementation.Features:Experimental support for request canceling withrpc.cancel(id)in async serversExperimental support for response streaming in the ASGI serverExperimental support for MQTT TransportSupports calling JSON-RCP 2.0 serversBuild a JSON-RPC server using ASGI, WSGI and CGIOptionally supports async client and server codeUse the JSON-RPC 2.0 with any transport layer by using building blocksBattle tested code because it was alreay used ~10 years in varioius closed source projectsUnittests are written for new code and whenever a bug is fixed for older partsAbstracts handling of datetime.datetime() over the RPCBecause this is a serious library a GPG signature is uploaded to PIP so the integrity of updates can be easily verified.Plays nice with OpenRPC (https://open-rpc.org/)Drawbacks:Depnends on libraries to support async and correctly convert Pythons datatime.datetime() to JSON and to ensure timezone information is not swallowedThis library is commited not to brake existing code so it can get bloated over timeFeatures under construction:Note: For features under construction it is open if they will arrive as a separate package or merged in to this oneExperimental code for OpenRPC is already included and will get more major over time. Several closed source applications already rely on it.A JSON-RPC 2.0 over MQTT is under considerationInstallpip install jsonrpcxA GPG signature is available at PIP that can be checked as well.Build clientsAsyncNote:acalldoes not support a session parameter because it could lead to hard to debug code.
If for example you have two paralel requests one is logging you in to the server and sets a cookie and the other is calling a method where it already needs to be logged in
Then it can happen that sometimes it works while other times the login happens after the first request to a resource that requires a login thus withuot the login.
In the last case the server would return some kind of error message and the develper with a headage.
If you want to use async requests please only do so with stateless RPC servers or use the sync version instead.Note: There currenlty is code to support sessions foracallbut that will be removed in a future version unless a way to circumvent the problem described above is found.fromjsonrpcximportacallimportasyncioasyncdefmain():result1=awaitacall("https://yourjsonrpc.online",method="add",params=[1,2])print(result1)result2=awaitacall("https://yourjsonrpc.online",method="add",params={a:1,b:2})print(result2)if__name__=="__main__":asyncio.run(main())If you don't want to write the URL over and over again you can do this trickfromjsonrpcximportacallimportasynciofromfunctoolsimportpartialasyncdefmain():rpc=partial(acall"https://yourjsonrpc.online")result=awaitrpc("add",[2,2])print(result)if__name__=="__main__":asyncio.run(main())SyncCall RPC via stringfromjsonrpcximportcallimporthttpsresult1=call("https://yourjsonrpc.online",method="add",params=[1,2])print(result1)result2=call("https://yourjsonrpc.online",method="add",params={a:1,b:2})print(result2)# Generally you should keep JSON-RPC 2.0 servers state less that means not rely on sessions for stuff like authentication# Sessions can be used here but should be threaded as an implementation detail and only used if absolutely necessary# because it will only work as long as httpx is used under the hood# If you do need a session you can do the followingsession=httpx.Client()result3=call("https://yourjsonrpc.online",method="add",params=[1,2],session=session)print(result3)If you don't want to write the URL over and over again you can do this trickfromjsonrpcximportcallfromfunctoolsimportpartialrpc=partial(call,"https://yourjsonrpc.online")result=rpc("add",[2,2])print(result)Call RPC via proxy objectFor legacy reasonsServiceProxyexists and will automatically translate a method call on the ServiceProxy object to a method call on the RPC.Because this looks like normal Python code but static code analysis or auto complete can not support the developer here this way of calling an RPC has not made it to the newer async version.importjsonrpcx# The service proxy keeps track of HTTP sessionsrpc=jsonrpcx.ServiceProxy("https://yourjsonrpc.online")rpc.add(1,2)rpc.add(a=1,b=2)# As a limitation of the JSON-RPC 2.0 protocol this is not possible and would usually trhow an Exception but is dependend on the implementation detail of the serverrpc.add(1,b=2)Build ServersASGIimportloggingfromtypingimport*fromjsonrpcximport*logging.basicConfig(level=logging.DEBUG)classService(ASGIServer):asyncdefping(self)->str:return"pong"asyncdefadd(self,val1:float,val2:float)->float:returnval1+val2asyncdefecho(self,var:str)->str:returnvarasyncdeftestReturnNone(self):returnNone# You only need this if you want to overwrite the HTTP headers sent to the clientclassDelegate(ASGIServerDelegate):defHTMLHeaders(self)->List[str]:return[("Content-Type","application/json")]asyncdefapp(scope,receive,send):rpcServer=Service(delegate=Delegate())returnawaitrpcServer.parseRequest(scope,receive,send)WSGINote: WSGI does not support async. This is a limitation of WSGI itself not of this library.fromtypingimport*fromjsonrpcximport*classService(WSGIServer):defping(self)->str:return"pong"defadd(self,val1:int,val2:int)->int:returnval1+val2defecho(self,var):returnvardeftestReturnNone(self):returnNone# You only need this if you want to overwrite the HTTP headers sent to the clientclassDelegate(WSGIServerDelegate):defHTMLHeaders(self)->List[str]:return[("Content-Type","application/json")]defapp(environment,start_response):wsgiServer=Service(delegate=Delegate())returnwsgiServer.parseRequest(environment,start_response)CGICGI is the perfect choice for hosting providers that do not support WSGI or ASGI.Recomended configuration using Apache .htaccess as an example a similar configuration should work for other webservers.# If the webserver retuns some error your JSON-RPC 2.0 clients won't break even if they don't understand HTTP error codes which some don't
    ErrorDocument 500 '{"jsonrpc": "2.0", "error": {"code": -32603, "message": "Internal error issued by webserver"}, "id": null}'

    # Security precaution
    Options -Indexes

    DirectoryIndex index.py

    # Don't give hackes access to configuration secrets
    <Files ~ "\.pyc$">
        Order allow,deny
        Deny from all
    </Files>

    # Requied to make .py scripts executable
    Options +ExecCGI
    AddHandler cgi-script .py

    # Only if you intend to use the RPC from a browser.
    # Please check if you can use more strict CORS rules
    Header set Access-Control-Allow-Origin "*"
    Header set Access-Control-Allow-Headers "Accept,Content-Type,Cookie,Origin,Referer,User-Agent"
    Header set Access-Control-Allow-Methods "*"
    Header set Access-Control-Allow-Credentials trueAsyncfromjsonrpcximport*importasyncioclassService(AsyncCGIServer):# Will work becasue its marked with the `async` keyword`asyncdefping(self)->str:return"pong"# This will not work because it is missing the `async` keyworddefping2(self)->str:return"pong"# You only need this if you want to overwrite the HTTP headers sent to the clientclassDelegate(CGIServerDelegate):defHTTPHeader(self):return"Content-Type: application/json"if__name__=="__main__":service=Service(delegate=Delegate())asyncio.run(service.processRequests())Syncfromjsonrpcximport*classService(CGIServer):defping(self)->str:return"pong"# You only need this if you want to overwrite the HTTP headers sent to the clientclassDelegate(CGIServerDelegate):defHTTPHeader(self):return"Content-Type: application/json"if__name__=="__main__":Service(delegate=Delegate())OpenRPC documentationNote: If you want to use this with web based tooling you need to configure CORS headers in a way to allow that.This library already provieds experimental support forhttps://open-rpc.org/which means you can auto generate documenation.
This library uses Pythons typing support to figure out what input types a function has.If you point a tool that can generate documentation form the OpenRPC spec to your JSON-RPC 2.0 server it will already be able to generate documentation for it.
The method to generate the OpenRPC json document isrpc.discoverif you want to overwrite its behaviour then you can overrde the methoddef rpcDiscover(self):orasync rpcDiscover(self):depending on if you choose a sync or async JSON-RPC 2.0 server.Theinfoandserverparts of the documentation return a example information by default. If you want to add your own information you can do it like so:fromtypingimport*fromjsonrpcximport*# Make sure to inherit from the correct class here depending on how you deploy the serverclassDelegate(CGIServerDelegate):defexperimentalOpenRPCInfo(self):return{"version":"1.0.0","title":"Example Title","termsOfService":"https://example.eu/tos","contact":{"name":"Support Contact Name","email":"support@example.eu","url":"https://example.eu"},"description":"This API uses JSON-RPC 2.0. For simplicity it does not support batch method calls."}defexperimentalOpenRPCServers(self)->Optional[List[Dict]]:return[{"name":"Example endpoint","url":"http://localhost:8000"}]Experimental support for request cancelingThere is currently no definition for how request canceling should be implemented in JSON-RPC 2.0 but Microsoft has something like that in LSP and this works similar to that.WARNING: WHEN ENABLING EXPERIMENTAL REQUEST CANCELING ANYONE CAN CANCEL REQUESTS EVEN REQUESTS FROM OTHER CLIENTS AS LONG AS THEY CORRECTL GUESS THE MESSAGEID.The server supports a methodrpc.cancel(id)where id is the messageId the client sent to the server.fromjsonrpcximport*importasynciosomeVar=[]asyncdefcancel_me():print('cancel_me(): before sleep')try:# Wait for 1 hoursomeVar.append("example")awaitasyncio.sleep(3600)exceptasyncio.CancelledError:print('cancel_me(): cancel sleep')raisefinally:print('cancel_me(): after sleep')classService(ASGIServer,ExperimentalCancelRequestMixin):asyncdefgetLongRunningProcess2(self,bla:str):returnawaitcancel_me()classDelegate(ASGIServerDelegate):# You have these options to overwrite default behaviour (method signatures are subject to change):asyncdefexperimentalWaitOnCancelRequest(self)->None:super.experimentalWaitOnCancelRequest()asyncdefexperimentalAddRunningRequest(self,messageId:Any,task:asyncio.Task)->None:super.experimentalAddRunningRequest(messageId,task)asyncdefexperimentalRemoveRunningRequest(self,messageId:Any)->None:super.experimentalRemoveRunningRequest(messageID)Experimental support for response streamingThere is currently no definition for how request canceling should be implemented in JSON-RPC 2.0.On the Server:fromjsonrpcximport*classService(ASGIServer,ExperimentalCancelRequestMixin):asyncdefstreamedResponse(self):# Any dict or list (json serializable) that is returned with the `yield` keyword will be streamed to the clientforiinrange(10):yield{"res":f"test{i=}"}awaitasyncio.sleep(5)On the client:importhttpximportasyncioasyncdefmain():client=httpx.AsyncClient()asyncwithclient.stream('POST','http://127.0.0.1:8000',timeout=5000,json={"jsonrpc":"2.0","method":"streamedResponse","params":[],"id":1})asresponse:asyncforchunkinresponse.aiter_bytes():print(chunk)if__name__=='__main__':asyncio.run(main())MQTT TransportWARNING: MQTT Transport is currently EXPERIMENTAL and its interface is subject to change.
NOTE: To use MQTT Transport you need to install the packageasyncio_mqtt.Server:from jsonrpcx import *

class API(MqttJSONRPCServer):
    async def ping(self):
        return "pong"
    
    async def add(self, a, b):
        return a + b


async def main():
    server = API("localhost", "user", "password", "mqttChannel")
    await server.processRequests()


if __name__ == "__main__":
    asyncio.run(main())Client:from jsonrpcx import *

async def main():
    res = await mqttRPCCall("add", [5, 5], mqttHost="host", mqttUser="user", mqttPassword="password", mqttPort=1883, mqttChannel="mqttChannel")
    print(res)

if __name__ == "__main__":
    asyncio.run(main())Setup developmentRunpipenv installTestingRunpipenv run pytestRunning the Example serveruvicorn exampleserver:app --reloadPublishpython3 setup.py bdist_wheeltwine upload dist/* --skip-existingImprovement ideasInstead of throwing CircularReference detected when what is returned from a function can not be serialized by json send a JSON serialization exception.Add middle wear supportAdd authentication middlewearAdd stream support for websocketsImprove secutiry problem with rpc.cancel (currently anyone can cancel any request as long as they know the messageId)Force the client to use cryptographic securemessageId.Let the server provide a crypographic securecancelTokenor JWT so only the client that made the request can canel that without the need to generate cryptographic secure messageId on the client which some clients might not be capable of.Keep a dict which client requested which messageId and check against that before canceling a request somehow.Let the middlewear take care of this.Expose all required data into the delegate and let the developer handle this.