diff --git a/server/README.md b/server/README.md index 0aa3ff58f..ecb047ccd 100644 --- a/server/README.md +++ b/server/README.md @@ -18,24 +18,23 @@ Launch VolView (e.g. using `npm run serve`) and check out the "Remote Functions" ## Customizing the RPC API -The following is a definition of a really simple RPC API with two functions. The first adds two numbers, while the second just performs an async sleep and then returns. +The following is a definition of a really simple RPC API that adds two numbers. ```python -import asyncio from volview_server import VolViewAPI, rpc class Api(VolViewAPI): @rpc("add") def add(self, a: int, b: int): return a + b - - @rpc("sleep") - def sleep(self): - asyncio.sleep(5) ``` An important note is that the RPC endpoint name can only contain lower-case letters, numbers, and underscores. +An example set of RPC endpoints are defined in `custom/user_api.py`. + +### Custom Object Encoding + If you have encoded objects that have a native Python representation, you can add encode/decode hooks to encode/decode the objects seamlessly. @@ -69,5 +68,42 @@ class Api(VolViewAPI): return dt ``` +### Async Support + +Async function support works right out of the box, as shown below. + +```python +import asyncio +from volview_server import VolViewAPI, rpc + +class Api(VolViewAPI): + @rpc("sleep") + async def sleep(self): + await asyncio.sleep(5) +``` + +### Progress via Streaming Async Generators + +Streaming support is achievable with async generators. Instead of decorating your methods with `rpc`, you instead use `stream`. + +```python +import asyncio +from volview_server import VolViewAPI, stream + +class Api(VolViewAPI): + @stream("progress") + async def progress(self): + for i in range(100): + yield { "progress": i, "done": False } + await asyncio.sleep(0.1) + yield { "progress": 100, "done": True } +``` + +On the client, you will use the corresponding `remoteConn.stream` method. -An example set of RPC endpoints are defined in `custom/user_api.py`. \ No newline at end of file +```js +await remoteConn.stream('progress', [/* optional args */], (data) => { + const { progress, done } = data; + ... +}) +``` \ No newline at end of file