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>
deltachat-jsonrpc
This crate provides a JSON-RPC 2.0 interface to DeltaChat.
The JSON-RPC API is exposed in two fashions:
- A executable that exposes the JSON-RPC API through a WebSocket server running on localhost.
- The JSON-RPC API can also be called through the C FFI. The C FFI needs to be built with the
jsonrpcfeature. It will then expose the functionsdc_jsonrpc_init,dc_jsonrpc_request,dc_jsonrpc_next_responseanddc_jsonrpc_unref. See the docs in the header file for details.
We also include a JavaScript and TypeScript client for the JSON-RPC API. The source for this is in the 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 for details.
Usage
Running the WebSocket server
From within this folder, you can start the WebSocket server with the following command:
cargo run --features webserver
If you want to use the server in a production setup, first build it in release mode:
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:
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). Find the source in the typescript folder.
To use it locally, first install the dependencies and compile the TypeScript code to JavaScript:
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.
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:
cd typescript
npm run docs
Then open the 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.
cd typescript
npm run build
npm run example:build
npm run example:start
Then, open 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.
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=1environment 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.