diff --git a/README.md b/README.md index d493823..e84a9e5 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,116 @@ -# p≡p JSON Adapter +# p≡p JSON Server Adapter ## Introduction -The JSON Adapter provides a REST-like jQuery-compatible API to connect with +The p≡p JSON Server Adapter provides a REST-like jQuery-compatible API to connect with the p≡p engine. It is language-independent and can be used by any client. -[...] -## Getting started +## Getting started - build and run -In order to use the p≡p JSON Adapter, you need to build and run it. [...] +In order to use the p≡p JSON Server Adapter, you need to build and run it. Currently, Linux and OSX/macOS are supported, Windows is about to follow. -### Build process +### Building on Linux -The p≡p JSON adapter can be build on any Debian based OS. ??? [...] +The p≡p JSON Server Adapter can be build on Debian and Ubuntu. Other flavors may work, but are not officially supported. #### System requirements -* Debian version ...? -* ... +* Debian 9 (or higher) or Ubuntu 16.04 (or higher) #### Dependencies * g++ 4.8 or 4.9 * GNU make * libboost-filesystem-dev -* [p≡p Engine](link/to/pEp/Engine/documentation) (which needs gpgme-thread, +* [p≡p Engine](https://letsencrypt.pep.foundation/trac/wiki/Basic%20Concepts%20of%20p%E2%89%A1p%20engine) (which needs gpgme-thread, a patched libetpan, libboost-system-dev) #### Build steps -1. Build [p≡p Engine](link/to/pEp/Engine/build/instructions) -2. Build [libevent](link/to/libevent-2.0.22-stable/README] (a user-install in $HOME/local/ is fine) +1. Build [p≡p Engine](https://letsencrypt.pep.foundation/trac/wiki/Basic%20Concepts%20of%20p%E2%89%A1p%20engine) +2. Build [libevent](http://libevent.org/) (a user-install in $HOME/local/ is fine) 3. Edit the library and include paths server/Makefile so p≡p & libevent will be found 4. Run "make" in the server/ path +``` +cd server +make +``` + +### Building on macOS + +The p≡p JSON Server Adapter can be build on OS X or macOS with MacPorts. + +#### System requirements + +* OS X or macOS + +#### Preconditions + +For compiling the p≡p JSON Server Adapter and its dependencies, make sure you have the LANG variable set. + +``` +export LANG=en_US.UTF-8 +``` + +#### Dependencies + +The following dependencies need to be installed in order to be able to build the p≡p JSON Server Adapter. + +##### MacPorts +[Install MacPorts](https://www.macports.org/install.php) for your version of OS X/macOS. + +If MacPorts is already installed on your machine, but was installed by a different user, make sure your `PATH` variable is set as follows in `~/.profile`: + +``` +export PATH="/opt/local/bin:/opt/local/sbin:$PATH" +``` + +Install dependencies packaged with MacPorts as follows. + +``` +sudo port install openssl boost ossp-uuid +``` + +##### libevent + +Install [libevent](http://libevent.org/). + +``` +cd libevent-2.0.22-stable +export LDFLAGS=-L/opt/local +export CFLAGS=-I/opt/local/include + +./configure --prefix "$HOME" + +make +make install +``` + +#### Build steps + +1. Install dependencies +2. Run "make" in the server/ path + +``` +cd server +make +``` + ### Running the pEp JSON Adapter 1. Run ./pep-json-server. This creates a file that is readable only by the current user (/tmp/pEp-json-token-${USER}) and contains the address and port the JSON adapter is listening on, normally 127.0.0.1:4223 and a "security-token" that must be given in each function call to authenticate - you as the valid user. + you as the valid user. + + ``` + ./pep-json-server + ``` + 2. Visit that address (normally http://127.0.0.1:4223/) in your javascript-enabled web browser to see the test JavaScript client. -3. Call some functions ("version()" or "get_gpg_path()" should work just +3. Call any function ("version()" or "get_gpg_path()" should work just fine) with the correct security token. ## Using the p≡p JSON Adapter @@ -50,23 +118,31 @@ The p≡p JSON adapter can be build on any Debian based OS. ??? [...] In the following section, you'll find background information on how to use the adapter and its functions. -### General notes +### Preliminary notes -[in case there are general notes as to how the adapter should be used] +* When using the p≡p engine, a session is needed to which any adapter can connect. +In case of the p≡p JSON Server Adapter, it creates this session automatically and +attaches to / detaches from it automatically. Therefore, the client does not need +to take care of the session management. However, it might be necessary to set up a +[HTTP persistent connection](https://en.wikipedia.org/wiki/HTTP_persistent_connection). -### Functions +### API Principles -#### version() +All C data types are mapped the same way, so some day the JSON wrapper can be generated from the p≡p Engine header files (or the JSON wrapper and the p≡p engine header are both generated from a common interface description file) -Returns the version number of the JSON adapter. - -#### get_gpg_path() - -Returns the GPG path ... - -[...] +| C type | JSON mapping | +|--|--| +| `bool` | JSON boolean | +| `int` | JSON decimal number | +| `char*` (representing a UTF-8-encoded NULL-terminated string | JSON string | +| `char*` (representing a binary string | base64-encoded JSON string | +| `enum` | string with the enumerator constant (e.g. `PEP_KEY_NOT_FOUND` ) | +| `struct` | JSON object | +| linked lists (e.g. `bloblist_t`, `stringlist_t`, `identity_list` etc.) | JSON array of their member data type (without the `next` pointer) | +### API Reference +An complete overview with all functions that are callable from the client can be found in the [API Reference](pEp JSON Server Adapter/API Reference). ## Extending / customizing @@ -99,23 +175,24 @@ rules and defitions to take into account. * The specializations for "p≡p-specific types" are in pep-types.cc + ## TODOs The following issues are planned but not yet implemented. -* Windows build: (JSON-23) - * implement get_token_filename() for MS Windows (security-token.cc line 43 - * do the windows-specific stuff to build the software on Windows +* Windows build: + * implement get_token_filename() for MS Windows (security-token.cc line 43) + * do the Windows-specific stuff to build the software on Windows -* Add unit tests (I'd suggest GoogleTest/gtest? Any complaints?) +* Add unit tests * Fix the bugs that are found by the Unit tests, if any. -* Let's generate all the tedious boiler plate code +* Generate all the tedious boiler plate code * the content of pep-types.cc * perhaps the FunctionMap 'function' in mt-server.cc * perhaps the JavaScript side of the HTML test page to ensure to be consistent with the server side in pep-types.cc -* Adapt the "p≡p Transport API", when it is final. (either manually or by +* Adapt the "p≡p Transport API", when it is final. (either manually or by code generator, if ready)