Initial commit moved from jsonrpcserver repo

Author: bcb

.github/workflows/deploy-docs.yml

@@ -0,0 +1,48 @@
+# ⚠️ This workflow deploys docs to explodinglabs.com
+# It is active only in the official repo. Forks won't trigger deployment.
+name: Build and Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - main # or your main development branch
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source repo
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: pip install mkdocs mkdocs-material
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Clone target repo
+        run: |
+          git clone https://x-access-token:${{ secrets.TARGET_REPO_PAT }}@github.com/explodinglabs/explodinglabs.com.git target-repo
+          rm -rf target-repo/$(basename "$GITHUB_REPOSITORY")
+          mkdir -p target-repo/$(basename "$GITHUB_REPOSITORY")
+          cp -a site/. target-repo/$(basename "$GITHUB_REPOSITORY")/
+        env:
+          GIT_AUTHOR_NAME: GitHub Actions
+          GIT_COMMITTER_NAME: GitHub Actions
+          GIT_AUTHOR_EMAIL: [email protected]
+          GIT_COMMITTER_EMAIL: [email protected]
+
+      - name: Commit and push
+        run: |
+          cd target-repo
+          git config user.name "Exploding Labs Bot"
+          git config user.email "[email protected]"
+          git add .
+          git commit -m "Update site from docs source repo" || echo "No changes to commit"
+          git push

docs/async.md

@@ -0,0 +1,41 @@
+# Async
+
+Async dispatch is supported.
+
+```python
+from jsonrpcserver import method, Success, async_dispatch
+
+@method
+async def ping() -> Result:
+    return Success("pong")
+
+await async_dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}')
+```
+
+Some reasons to use this:
+
+- Use it with an asynchronous protocol like sockets or message queues.
+- `await` long-running functions from your method.
+- Batch requests are dispatched concurrently.
+
+## Notifications
+
+Notifications are requests without an `id`. We should not respond to
+notifications, so jsonrpcserver gives an empty string to signify there is *no
+response*.
+
+```python
+>>> await async_dispatch('{"jsonrpc": "2.0", "method": "ping"}')
+''
+```
+
+If the response is an empty string, don't send it.
+
+```python
+if response := dispatch(request):
+    send(response)
+```
+
+> 📝 A synchronous protocol like HTTP requires a response no matter
+> what, so we can send back the empty string. However with async
+> protocols, we have the choice of responding or not.

docs/dispatch.md

@@ -0,0 +1,65 @@
+# Dispatch
+
+The `dispatch` function takes a JSON-RPC request, calls the appropriate method
+and gives a JSON-RPC response.
+
+```python
+>>> dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}')
+'{"jsonrpc": "2.0", "result": "pong", "id": 1}'
+```
+
+[See how dispatch is used in different frameworks.](examples.md)
+
+## Optional parameters
+
+### methods
+
+This lets you specify a group of methods to dispatch to. It's an alternative to
+using the `@method` decorator. The value should be a dict mapping function
+names to functions.
+
+```python
+def ping():
+    return Success("pong")
+
+dispatch(request, methods={"ping": ping})
+```
+
+Default is `global_methods`, which is an internal dict populated by the
+`@method` decorator.
+
+### context
+
+If specified, this will be the first argument to all methods.
+
+```python
+@method
+def greet(context, name):
+    return Success(context + " " + name)
+
+>>> dispatch('{"jsonrpc": "2.0", "method": "greet", "params": ["Beau"], "id": 1}', context="Hello")
+'{"jsonrpc": "2.0", "result": "Hello Beau", "id": 1}'
+```
+
+### deserializer
+
+A function that parses the request string. Default is `json.loads`.
+
+```python
+dispatch(request, deserializer=ujson.loads)
+```
+
+### serializer
+
+A function that serializes the response string. Default is `json.dumps`.
+
+```python
+dispatch(request, serializer=ujson.dumps)
+```
+
+### validator
+
+A function that validates the request once the json has been parsed.
+The function should raise an exception (any exception) if the request
+doesn't match the JSON-RPC spec. Default is `default_validator` which
+validates the request against a schema.

docs/examples.md

@@ -0,0 +1,3 @@
+# Examples
+
+Examples have moved to the [Community Wiki](https://github.com/explodinglabs/jsonrpcserver/wiki).

docs/faq.md

@@ -0,0 +1,41 @@
+# FAQ
+
+## How to disable schema validation?
+
+Validating requests is costly - roughly 40% of dispatching time is spent on schema validation.
+If you know the incoming requests are valid, you can disable the validation for better
+performance.
+
+```python
+dispatch(request, validator=lambda _: None)
+```
+
+## Which HTTP status code to respond with?
+
+I suggest:
+
+```python
+200 if response else 204
+```
+
+If the request was a notification, `dispatch` will give you an empty string. So
+since there's no http body, use status code 204 - no content.
+
+## How to rename a method
+
+Use `@method(name="new_name")`.
+
+Or use the dispatch function's [methods
+parameter](https://www.explodinglabs.com/jsonrpcserver/dispatch/#methods).
+
+## How to get the response in other forms?
+
+Instead of `dispatch`, use:
+
+- `dispatch_to_serializable` to get the response as a dict.
+- `dispatch_to_response` to get the response as a namedtuple (either a
+  `SuccessResponse` or `ErrorResponse`, these are defined in
+  [response.py](https://github.com/explodinglabs/jsonrpcserver/blob/main/jsonrpcserver/response.py)).
+
+For these functions, if the request was a batch, you'll get a list of
+responses. If the request was a notification, you'll get `None`.

docs/images/logo.png

@@ -0,0 +1,26 @@
+---
+hide:
+  - toc
+---
+
+<style>
+.md-content__inner h1:first-of-type {
+  display: none;
+}
+</style>
+
+![jsonrpcserver](images/logo.png)
+
+_Process incoming JSON-RPC requests in Python._
+
+Jump to:
+[GitHub](https://github.com/explodinglabs/jsonrpcserver) | [Community Wiki](https://github.com/explodinglabs/jsonrpcserver/wiki)
+
+## Documentation
+
+- [Installation](installation.md)
+- [Methods](methods.md)
+- [Dispatch](dispatch.md)
+- [Async](async.md)
+- [Faq](faq.md)
+- [Examples](examples.md)

docs/index.md

@@ -0,0 +1,7 @@
+# Installation
+
+Install with Pip:
+
+```sh
+pip install jsonrpcserver
+```

docs/installation.md

@@ -0,0 +1,68 @@
+# Methods
+
+Methods are functions that can be called by a JSON-RPC request. To write one,
+decorate a function with `@method`:
+
+```python
+from jsonrpcserver import method, Result, Success, Error
+
+@method
+def ping() -> Result:
+    return Success("pong")
+```
+
+If you don't need to respond with any value simply `return Success()`.
+
+## Responses
+
+Methods return either `Success` or `Error`. These are the [JSON-RPC response
+objects](https://www.jsonrpc.org/specification#response_object) (excluding the
+`jsonrpc` and `id` parts). `Error` takes a code, message, and optionally 'data'.
+
+```python
+@method
+def test() -> Result:
+    return Error(1, "There was a problem")
+```
+
+> 📝 Alternatively, raise a `JsonRpcError`, which takes the same
+> arguments as `Error`.
+
+## Parameters
+
+Methods can accept arguments.
+
+```python
+@method
+def hello(name: str) -> Result:
+    return Success("Hello " + name)
+```
+
+Testing it:
+
+```sh
+$ curl -X POST http://localhost:5000 -d '{"jsonrpc": "2.0", "method": "hello", "params": ["Beau"], "id": 1}'
+{"jsonrpc": "2.0", "result": "Hello Beau", "id": 1}
+```
+
+## Invalid params
+
+A common error response is _invalid params_. The JSON-RPC error code
+for this is **-32602**. A shortcut, _InvalidParams_, is included so
+you don't need to remember that.
+
+```python
+from jsonrpcserver import method, Result, InvalidParams, Success, dispatch
+
+@method
+def within_range(num: int) -> Result:
+    if num not in range(1, 5):
+        return InvalidParams("Value must be 1-5")
+    return Success()
+```
+
+This is the same as saying
+
+```python
+return Error(-32602, "Invalid params", "Value must be 1-5")
+```

docs/methods.md

@@ -0,0 +1,43 @@
+site_name: jsonrpcserver
+site_url: https://explodinglabs.com/jsonrpcserver/
+repo_url: https://github.com/explodinglabs/jsonrpcserver
+theme:
+  name: material
+  features:
+    - navigation.footer
+    - palette.toggle
+    - content.code.copy
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      primary: pink
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: pink
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: pink
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Methods: methods.md
+  - Dispatch: dispatch.md
+  - Async: async.md
+  - FAQ: faq.md
+  - Examples: examples.md