From 2df10857ca8c6456bfcc41338ae4a4cc6c27e2b4 Mon Sep 17 00:00:00 2001 From: "Franz Heinzmann (Frando)" Date: Thu, 30 Jun 2022 00:31:47 +0200 Subject: [PATCH] Improve documentation --- deltachat-jsonrpc/README.md | 92 +++++++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 29 deletions(-) diff --git a/deltachat-jsonrpc/README.md b/deltachat-jsonrpc/README.md index f1969d8db..50fe0fa6b 100644 --- a/deltachat-jsonrpc/README.md +++ b/deltachat-jsonrpc/README.md @@ -4,14 +4,14 @@ This crate provides a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) inte The JSON-RPC API is exposed in two fashions: -* The JSON-RPC API can be called through the [C FFI](../deltachat-ffi) with the functions `dc_jsonrpc_init`, `dc_jsonrpc_request`, `dc_jsonrpc_next_response` and `dc_jsonrpc_unref`. -* This crate includes a binary that serves the JSON-RPC API over a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API). +* 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 and published on NPM as `deltachat-jsonrpc`. +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 +#### Running the WebSocket server From within this folder, you can start the WebSocket server with the following command: @@ -19,7 +19,21 @@ From within this folder, you can start the WebSocket server with the following c cargo run --features webserver ``` -The server accepts WebSocket connections on `ws://localhost:20808/ws`. +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 environement 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): @@ -27,9 +41,9 @@ If you are targetting other architectures (like KaiOS or Android), the webserver cross build --features=webserver --target armv7-linux-androideabi --release ``` -### Using the typescript client +#### Using the TypeScript/JavaScript client -The package includes TypeScript bindings which are 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. The client is also published on npm as `@deltachat/jsonrpc-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 @@ -38,54 +52,74 @@ npm install npm run build ``` -You can also build autogenerated documentation, including all RPC methods: +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 ``` -Now, open the [`typescript/docs`](typescript/docs) folder in a web browser. +Then open the [`typescript/docs`](typescript/docs) folder in a web browser. +##### Usage in JavaScript projects -### Running the example app +It is not yet straightforward to use the client this way in a JavaScript project. If you have a need please open an issue. For now, clone this repo, run `npm run build` in the typescript folder and copy `dist/deltachat.bundle.js` into your project. This will be obsolete once we publish the client to NPM (likely soon). -We include a small demo web application that talks to the WebSocket server. To run it, follow these steps: +#### Running the example app +We include a small demo web application that talks to the WebSocket server. -* Then, build and run the example application: - ```sh - npm run example:dev - ``` +```sh +cd typescript +npm run build +npm run example:build +npm run example:start +``` +Then, open [`http://localhost:8080`](http://localhost:8080) in a web browser. -## Compiling server for kaiOS or android: +## Development -## Run the tests +### Testing -### Rust tests +The crate includes both (basic) Rust tests and integration tests that use the TypeScript client. + +#### Rust tests + +To run the Rust test, use this command: ``` -cargo test --features=webserver +cargo test ``` -### Typescript +#### TypeScript tests ``` cd typescript npm run test ``` -For the online tests to run you need a test account token for a mailadm instance, -you can use docker to spin up a local instance: https://github.com/deltachat/docker-mailadm +This will build the `deltachat-jsonrpc-server` binary and then run a test suite against the WebSocket server. -> set the env var `DCC_NEW_TMP_EMAIL` to your mailadm token: example: -> `DCC_NEW_TMP_EMAIL=https://testrun.org/new_email?t=1h_195dksa6544` +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 instannce of [`mailadm`](https://github.com/deltachat/docker-mailadm). -If your test fail with server shutdown at the start, then you might have a process from a last run still running probably and you need to kill that process manually to continue. +Then, set the `DCC_NEW_TMP_EMAIL` environemnt 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 -You can test coverage with `npm run coverage`, but you need to have `DCC_NEW_TMP_EMAIL` set, otherwise the result will be useless because some functions can only be tested with the online tests. +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 NOT correct), you can bypass the error with `COVERAGE_OFFLINE=1 npm run coverage` +> 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. -Open `coverage/index.html` for a detailed report. -`bindings.ts` is probably the most interesting file for coverage, because it describes the api functions. +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.