pEp.foundation
/
pEpJSONServerAdapter
9
1
Fork 4
Code Issues 1 Pull Requests Releases 1 Wiki Activity

Update documentation

Browse Source
JSON-35
Thomas 6 years ago
parent c88495b627
commit 1b338efada
1 changed files with 108 additions and 31 deletions
Show Stats Download Patch File Download Diff File

139
README.md
Unescape Escape View File

@ -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)

Write Preview
Loading…
Cancel
Save