mirror of
https://github.com/chatmail/core.git
synced 2026-04-18 14:06:29 +03:00
124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
# deltachat-jsonrpc
|
|
|
|
This crate provides a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) interface to DeltaChat.
|
|
|
|
The JSON-RPC API is exposed in two fashions:
|
|
|
|
* A executable that exposes the JSON-RPC API through a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) server running on localhost.
|
|
* The JSON-RPC API can also be called through the [C FFI](../deltachat-ffi). The C FFI needs to be built with the `jsonrpc` feature. It will then expose the functions `dc_jsonrpc_init`, `dc_jsonrpc_request`, `dc_jsonrpc_next_response` and `dc_jsonrpc_unref`. See the docs in the [header file](../deltachat-ffi/deltachat.h) for details.
|
|
|
|
We also include a JavaScript and TypeScript client for the JSON-RPC API. The source for this is in the [`typescript`](typescript) folder. The client can easily be used with the WebSocket server to build DeltaChat apps for web browsers or Node.js. See the [examples](typescript/example) for details.
|
|
|
|
## Usage
|
|
|
|
#### Running the WebSocket server
|
|
|
|
From within this folder, you can start the WebSocket server with the following command:
|
|
|
|
```sh
|
|
cargo run --features webserver
|
|
```
|
|
|
|
If you want to use the server in a production setup, first build it in release mode:
|
|
|
|
```sh
|
|
cargo build --features webserver --release
|
|
```
|
|
You will then find the `deltachat-jsonrpc-server` executable in your `target/release` folder.
|
|
|
|
The executable currently does not support any command-line arguments. By default, once started it will accept WebSocket connections on `ws://localhost:20808/ws`. It will store the persistent configuration and databases in a `./accounts` folder relative to the directory from where it is started.
|
|
|
|
The server can be configured with environment variables:
|
|
|
|
|variable|default|description|
|
|
|-|-|-|
|
|
|`DC_PORT`|`20808`|port to listen on|
|
|
|`DC_ACCOUNTS_PATH`|`./accounts`|path to storage directory|
|
|
|
|
If you are targeting other architectures (like KaiOS or Android), the webserver binary can be cross-compiled easily with [rust-cross](https://github.com/cross-rs/cross):
|
|
|
|
```sh
|
|
cross build --features=webserver --target armv7-linux-androideabi --release
|
|
```
|
|
|
|
#### Using the TypeScript/JavaScript client
|
|
|
|
The package includes a JavaScript/TypeScript client which is partially auto-generated through the JSON-RPC library used by this crate ([yerpc](https://github.com/Frando/yerpc/)). Find the source in the [`typescript`](typescript) folder.
|
|
|
|
To use it locally, first install the dependencies and compile the TypeScript code to JavaScript:
|
|
```sh
|
|
cd typescript
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
The JavaScript client is not yet published on NPM (but will likely be soon). Currently, it is recommended to vendor the bundled build. After running `npm run build` as documented above, there will be a file `dist/deltachat.bundle.js`. This is an ESM module containing all dependencies. Copy this file to your project and import the DeltaChat class.
|
|
|
|
|
|
```typescript
|
|
import { DeltaChat } from './deltachat.bundle.js'
|
|
const dc = new DeltaChat('ws://localhost:20808/ws')
|
|
const accounts = await dc.rpc.getAllAccounts()
|
|
console.log('accounts', accounts)
|
|
```
|
|
|
|
A script is included to build autogenerated documentation, which includes all RPC methods:
|
|
```sh
|
|
cd typescript
|
|
npm run docs
|
|
```
|
|
Then open the [`typescript/docs`](typescript/docs) folder in a web browser.
|
|
|
|
## Development
|
|
|
|
#### Running the example app
|
|
|
|
We include a small demo web application that talks to the WebSocket server. It can be used for testing. Feel invited to expand this.
|
|
|
|
```sh
|
|
cd typescript
|
|
npm run build
|
|
npm run example:build
|
|
npm run example:start
|
|
```
|
|
Then, open [`http://localhost:8080/example.html`](http://localhost:8080/example.html) in a web browser.
|
|
|
|
Run `npm run example:dev` to live-rebuild the example app when files changes.
|
|
|
|
### Testing
|
|
|
|
The crate includes both a basic Rust smoke test and more featureful integration tests that use the TypeScript client.
|
|
|
|
#### Rust tests
|
|
|
|
To run the Rust test, use this command:
|
|
|
|
```
|
|
cargo test
|
|
```
|
|
|
|
#### TypeScript tests
|
|
|
|
```
|
|
cd typescript
|
|
npm run test
|
|
```
|
|
|
|
This will build the `deltachat-jsonrpc-server` binary and then run a test suite against the WebSocket server.
|
|
|
|
The test suite includes some tests that need online connectivity and a way to create test email accounts. To run these tests, talk to DeltaChat developers to get a token for the `testrun.org` service, or use a local instance of [`mailadm`](https://github.com/deltachat/docker-mailadm).
|
|
|
|
Then, set the `CHATMAIL_DOMAIN` environment variable to your testing email server domain.
|
|
|
|
```
|
|
CHATMAIL_DOMAIN=chat.example.org npm run test
|
|
```
|
|
|
|
#### Test Coverage
|
|
|
|
Running `npm run test` will report test coverage. For the coverage to be accurate the online tests need to be run.
|
|
|
|
> If you are offline and want to see the coverage results anyway (even though they are inaccurate), you can bypass the errors of the online tests by setting the `COVERAGE_OFFLINE=1` environment variable.
|
|
|
|
A summary of the coverage will be reported in the terminal after the test run. Open `coverage/index.html` in a web browser for a detailed report.
|