Skip to content

Commit

Permalink
Version 0.2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
ts5746 authored Oct 29, 2019
1 parent c3a2a2c commit 276e252
Show file tree
Hide file tree
Showing 9 changed files with 376 additions and 184 deletions.
34 changes: 25 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ digital equivalent of placing a physical protective sign.

Note that this utility only processes *cultural* heritage sites, because
Whiteflag (currently) only defines a message (`P52`) that corresponds with the
protective sign for cultural property i.a.w. [the 1954 Hague Convention](http://www.unesco.org/new/en/culture/themes/armed-conflict-and-heritage/convention-and-protocols/1954-hague-convention/).
protective sign for cultural property i.a.w. [the 1954 Hague Convention](http://www.unesco.org/new/en/culture/themes/armed-conflict-and-heritage/convention-and-protocols/1954-hague-convention/). The `P52` protective sign message is followed by an `R1(3)` resource message with an URL linking the protective sign to the corresponding WHL entry.

This utility is for technology development, test and evaluation purposes only.
This means that it is a tool in support of testing the Whiteflag protocol, but
Expand Down Expand Up @@ -58,18 +58,16 @@ wfwhl [-s <id> ...] [-w <url>|-f <file>]

The main options are the following:

* `-s`, `--sites` : Specify the world heritage site(s) to be processed by \<id\> number; multiple sites may be specified. If no sites are specified, all sites are processed.
* `-s`, `--sites` : Specifies the world heritage site(s) by \<id\> number; multiple sites may be specified. If no sites are specified, all sites are processed.
* `-w`, `--web` : The source \<url\> of the WHL in XML on the web. If not specified the default is `https://whc.unesco.org/en/list/xml/`. Cannot be used with `-f`.
* `-f`, `--file` : The source \<file\> containing the WHL in XML. Cannot be used with `-w`.
* `-t`, `--transmit`** : Transmit the Whiteflag message(s) on the blockchain. Requires `-i`, `-b` and `-a` to be specified.
* `-i`, `--interface`** : The Whiteflag API REST interface \<url\> to post the message(s) to be sent.
* `-b`, `--blockchain`** : The \<blockchain\> to be used for sending the message(s).
* `-a`, `--address`** : The blockchain \<address\> to be used for sending the message(s).
* `-t`, `--transmit` : Transmit the Whiteflag message(s) on the blockchain. Requires `-i`, `-b` and `-a` to be specified.
* `-i`, `--interface` : The Whiteflag API REST interface \<url\> to post the message(s) to be sent.
* `-b`, `--blockchain` : The \<blockchain\> to be used for sending the message(s).
* `-a`, `--address` : The blockchain \<address\> to be used for sending the message(s).
* `-o`, `--stdout` : Send the Whiteflag message(s) to stdout. This allows the data to be piped to other processes.
* `-v`, `--verbose` : Provide detailed processing output.

**: _in development_

Other supporting options are:

* `--help` : Show help message.
Expand All @@ -90,7 +88,7 @@ for 3 world heritage sites, with detailed processing information and the
Whiteflag messages on standard output:

```shell
wfwhl -s 23 25 32 -f /data/whl.xml -vo
wfwhl -f /data/whl.xml -s 23 25 32 -o -v
```

To send Whiteflag messages for all cultural heritage sites from the WHL XML
Expand All @@ -100,6 +98,24 @@ list contained in a file to standard output:
wfwhl -f /data/whl.xml -o
```

To transmit Whiteflag messages for 2 specified world heritage sites, with the
Whiteflag API interface and blockchain details in a JSON configuration file
and detailed processing information:

```shell
wfwhl -s 29 49 --config wfwhl.json -t -v
```

where the `wfwhl.json` configuration file contents may look as follows:

```json
{
"interface": "http://localhost:5746",
"blockchain": "ethereum",
"address": "10fe33a6a1B26877a2d6fA95eaf4153608B5B5f9"
}
```

## License

The Whiteflag WHL utility is dedicated to the public domain under the
Expand Down
14 changes: 9 additions & 5 deletions doc/man/wfwhl.1
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ Whiteflag is a fully neutral and secure communciations means based on
blockchain technology. It enables near real-time communication in armed
conflicts and disasters to exchange early warning and status information
to create shared situational awareness.
.PP
The Whiteflag messages that are created and sent are: (1) a \fBP52(0)\fR
protective sign, followed by (2) an \fBR1(3)\fR resource message with an URL
linking the protective sign to the corresponding WHL entry.
.SH OPTIONS
.TP
.BR \-s ", " \-\-sites =\fISITEID\fR
Expand All @@ -27,18 +31,18 @@ The source \fIURL\fR of the WHL in XML on the web. If not specified the default
The source \fIFILE\fR containing the WHL in XML. Cannot be used with \fB\-w\fR.
.TP
.BR \-t ", " \-\-transmit
(NOT IMPLEMENTED) Transmit the Whiteflag message(s) on the blockchain. Requires \fB\-i\fR,
Transmit the Whiteflag message(s) on the blockchain. Requires \fB\-i\fR,
\fB\-b\fR and \fB\-a\fR to be specified, either on the command line or using
a configuration file with \fB\-\-config\fR.
.TP
.BR \-i ", " \-\-interface =\fIURL\fR
(NOT IMPLEMENTED) The Whiteflag API REST interface \fIURL\fR to post the message(s) to be sent.
The Whiteflag API REST interface \fIURL\fR to post the message(s) to be sent.
.TP
.BR \-b ", " \-\-blockchain =\fIBLOCKCHAIN\fR
(NOT IMPLEMENTED) The \fIBLOCKCHAIN\fR to be used for sending the message(s).
The \fIBLOCKCHAIN\fR to be used for sending the message(s).
.TP
.BR \-a ", " \-\-address =\fIADDRESS\fR
(NOT IMPLEMENTED) The blockchain \fIADDRESS\fR to be used for sending the message(s).
The blockchain \fIADDRESS\fR to be used for sending the message(s).
.TP
.BR \-o ", " \-\-stdout
Send the Whiteflag message(s) to stdout. This allows the data to be piped to other processes.
Expand All @@ -54,7 +58,7 @@ Show version number.
.TP
.BR \-\-config =\fIFILE\fR
Path to a JSON config \fIFILE\fR with preconfigured arguments; especially useful to
specify Whiteflag API interface URL, blockchain and address.
specify the Whiteflag API interface URL, blockchain and address.
.SH LEGAL
THE USAGE OF SIGNS AND SIGNALS WITH THIS SOFTWARE IS SUBJECT TO LOCAL AND/OR INTERNATIONAL LAWS
.PP
Expand Down
81 changes: 0 additions & 81 deletions lib/arguments.js

This file was deleted.

110 changes: 110 additions & 0 deletions lib/common/httpreq.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
'use strict';
/**
* @module lib/common/httpreq
* @summary Whiteflag WHL common http requests module
* @description Module that handles http requests
*/
module.exports = {
// http functions
get: httpGET,
post: httpPOST
};

// Node.js core and external modules //
const http = require('http');
const https = require('https');

/**
* Performs an HTTP GET request
* @function httpGET
* @alias module:lib/common/httpreq.get
* @param {URL} url the URL of the request
* @param {function} callback function to be called upon completion
*/
function httpGET(url, callback) {
const options = {
method: 'GET'
};
httpRequest(url, options, null, function httpGetCb(err, statusCode, data = null) {
if (!err && statusCode !== 200) {
err = new Error(`Request failed (status code ${statusCode})`);
}
return callback(err, data);
});
}

/**
* Performs an HTTP GET request
* @function httpPOST
* @alias module:lib/common/httpreq.post
* @param {URL} url the URL of the request
* @param {data} data the data to be in the request body
* @param {function} callback function to be called upon completion
*/
function httpPOST(url, data, callback) {
const body = JSON.stringify(data);
const options = {
method: 'POST',
headers: {
'Content-Type': 'application/json'
}
};
httpRequest(url, options, body, function httpPostCb(err, statusCode, data = null) {
if (!err) {
if (statusCode < 200 || statusCode > 202) {
err = new Error(`Request failed (status code ${statusCode})`);
}
}
return callback(err, data);
});
}

// PRIVATE FUNCTIONS //
/**
* Performs an HTTP request
* @private
* @param {URL} url the URL of the request
* @param {object} data the data to be in the request body
* @param {function} callback function to be called upon completion
*/
function httpRequest(url, options, body, callback) {
// Create request with protocol specified in url
let req;
const protocol = url.protocol.slice(0, -1);
switch (protocol) {
case 'http': {
req = http.request(url, options, resCb);
break;
}
case 'https': {
req = https.request(url, options, resCb);
break;
}
default: {
// Method does not exist
return callback(new Error(`Unsupported protocol for request: ${protocol}`));
}
}
// Handle reqest errors
req.on('error', function httpErrCb(err) {
return callback(err);
});
req.on('timeout', function httpTimeoutCb(err) {
req.abort();
return callback(new Error(`Aborted request after timeout: ${err.message}`));
});
// Send request data
if (body) req.write(body);
req.end();

// Callback functions
function resCb(res) {
let data = '';
res.on('data', function(chunk) {
data += chunk;
});
res.on('end', function httpProcessCb() {
return callback(null, res.statusCode, data);
});
}
}
37 changes: 0 additions & 37 deletions lib/httpreq.js

This file was deleted.

Loading

0 comments on commit 276e252

Please sign in to comment.