mirror of
https://github.com/chatmail/core.git
synced 2026-04-18 05:56:31 +03:00
0887acf1bf
* integrate json-rpc repo https://github.com/deltachat/deltachat-jsonrpc * get target dir from cargo * fix clippy * use node 16 in ci use `npm i` instead of `npm ci` try fix ci script and fix a doc comment * fix get_provider_info docs * refactor function name * fix formatting make test pass fix clippy * update .gitignore * change now returns event names as id directly, no conversion method or number ids anymore also longer timeout for requesting test accounts from mailadm * fix compile after rebase * add json api to cffi and expose it in dc node * add some files to npm ignore that don't need to be in the npm package * add jsonrpc crate to set_core_version * add jsonrpc feature flag * call a jsonrpc function in segfault example * break loop on empty response * fix closing segfault thanks again to link2xt for figguring this out * activate other tests again * remove selectAccount from highlevel client * put jsonrpc stuff in own module * disable jsonrpc by default * add @deltachat/jsonrpc-client to make sure its dependencies are installed, too whwn installing dc-node * commit types.ts that dc-node has everything it needs to provide @deltachat/jsonrpc-client without an extra ts compile step * improve naming * Changes for tokio compat, upgrade to yerpc 0.3 This also changes the webserver binary to use axum in place of tide. * Improvements to typescript package * Improve docs. * improve docs, fix example * Fix CFFI for JSON-RPC changes * use stable toolchain not 1.56.0 * fix ci * try to fix ci * remove emtpy file allow unused code for new_from_arc * expose anyhow errors feature name was wrong * use multi-threaded runtime in JSON-RPC webserver * improve test setup and code style * don't wait for IO on webserver start * Bump yerpc to 0.3.1 with fix for axum server * update todo document remove specific api stuff for now, we now have the an incremental aproach on moving not the all at-once effort I though it would be * remove debug logs * changelog entry about the jsonrpc * Fix method name casings and cleanups * Improve JSON-RPC CI, no need to build things multiple times * Naming consistency: Use DeltaChat not Deltachat * Improve documentation * fix docs * adress dig's comments - description in cargo.toml - impl From<EventType> for EventTypeName - rename `CommandApi::new_from_arc` -> `CommandApi::from_arc` - pre-allocate if we know the entry count already - remove unused enumerate - remove unused serde attribute comment - rename `FullChat::from_dc_chat_id` -> `FullChat::try_from_dc_chat_id` * make it more idiomatic: rename `ContactObject::from_dc_contact -> `ContactObject::try_from_dc_contact` * apply link2xt's suggestions: - unref jsonrpc_instance in same thread it was created in - increase `max_queue_size` from 1 to 1000 * reintroduce segfault test script * remove unneeded context thanks to link2xt for pointing that out * Update deltachat-ffi/deltachat.h Co-authored-by: bjoern <r10s@b44t.com> * Update deltachat-ffi/deltachat.h Co-authored-by: bjoern <r10s@b44t.com> * make sure to use dc_str_unref instead of free on cstrings returned/owned by rust * Increase online test timeouts for CI * fix the typos thanks to ralphtheninja for finding them * restore same configure behaviour as desktop: make configure restart io with the old configuration if it had one on error * found another segfault: this time in batch_set_config * remove print from test * make dcn_json_rpc_request return undefined instead of not returning this might have been the cause for the second segfault * add set_config_from_qr to jsonrpc * add `add_device_message` to jsonrpc * jsonrpc: add `get_fresh_msgs` and `get_fresh_msg_cnt` * jsonrpc: add dm_chat_contact to ChatListItemFetchResult * add webxdc methods to jsonrpc: - `webxdc_send_status_update` - `webxdc_get_status_updates` - `message_get_webxdc_info` * add `chat_get_media` to jsonrpc also add viewtype wrapper enum and use it in `MessageObject`, additionally to using it in `chat_get_media` * use camelCase in all js object properties * Add check_qr function to jsonrpc * Fixed clippy errors and formatting * Fixed formatting * fix changelog ordering after rebase * fix compile after merging in master branch Co-authored-by: Simon Laux <mobile.info@simonlaux.de> Co-authored-by: Simon Laux <Simon-Laux@users.noreply.github.com> Co-authored-by: bjoern <r10s@b44t.com> Co-authored-by: flipsimon <28535045+flipsimon@users.noreply.github.com>
124 lines
5.0 KiB
Markdown
124 lines
5.0 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 targetting 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 `DCC_NEW_TMP_EMAIL` environment variable to your mailadm token before running the tests.
|
|
|
|
```
|
|
DCC_NEW_TMP_EMAIL=https://testrun.org/new_email?t=yourtoken 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.
|