diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..c5ca097 --- /dev/null +++ b/README.rst @@ -0,0 +1,163 @@ +restlog +======= + +JSON log-structured data storage with REST API. + + +About +----- + +`restlog` provides simple data storage with REST access for registering +and retrieving arbitrary JSON data. During data registration, additional +meta-data is associated with each entry: + + * `entry_id` + + Number uniquely identifying each entry. This number is generated + by `restlog` and provides monotonously rising sequence used for + determining order of entry registrations. + + * `timestamp` + + Timestamp representing point in time when `restlog` obtained + registration request. + + * `address` + + IP address, as seen by `restlog`, of client initiating registration + request. `restlog` will try to use ``X-Forwarded-*`` HTTP header values + provided by reverse proxy. + + * `source` + + String label, set by client, used for filtering and additional + identification of client instance. + + * `type` + + String label, set by client, used for filtering and additional + identification of data structure/semantics. + + * `data` + + Arbitrary JSON data. + +Registered entries can be obtained based on optional query parameters +`last_entry_id`, `source` and `type`. If `last_entry_id` is not specified, +resulting entries will contain "newest" entries (entries with greatest +`entry_id` number). If `last_entry_id` is specified, resulting entries will +have `entry_id` less or equal to specified `last_entry_id`. Entry retrieval +results always contain lists of entries ordered by `entry_id` where "latest" +entries (entries with greater `entry_id`) are first and "oldest" entries are +last. + +Together with REST API, `restlog` provides simple web-based view of data +available through REST API. + + +Runtime requirements +-------------------- + +* python >=3.8 + + +Install +------- + +:: + + $ pip install restlog + + +Configuration +------------- + +Configuration structure is defined by `JSON schema <schemas_json/main.yaml>`_ . + +Example:: + + log: + version: 1 + host: '127.0.0.1' + port: 23233 + db_path: restlog.db + max_results: 100 + + +Run +--- + +:: + + $ restlog [--conf restlog.yaml] + +If path to configuration file is not set, default configuration path +``$XDG_CONFIG_HOME/restlog/restlog.{yaml|yml|json}`` is assumed. + +Once `restlog` is running, web-based data view can be accessed on +`http://<host>:<port>` (`<host>` and `<port>` are defined by configuration +parameters). + + +REST API +-------- + +REST API is defined by `Open API schema <schemas_openapi/main.yaml>`_ . + +Available endpoints: + + * POST ``/entry/{source}/{type}`` + + Registration of single entry with JSON data provided as content + of HTTP request body. + + * GET ``/entries?source={source}&type={type}&last_entry_id={last_entry_id}&max_results={max_results}`` + + Multiple entry retrieval. All query parameters are optional. + HTTP response contains list of entries and `more` flag indicating + if more entries, satisfying provided filters, are available. + + * GET ``/entry/{entry_id}`` + + Single entry retrieval. + + +Security +-------- + +If `restlog` is used by clients not running on the same machine, reverse +proxy with additional authentication methods should be used. Additionally, +`X-Forward-*` header entries should be included. + +Example of `nginx <https://nginx.org/>`_ configuration:: + + location / { + proxy_pass http://127.0.0.1:23233; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + auth_basic "restlog"; + auth_basic_user_file /etc/nginx/restlog.htpasswd; + } + + +License +------- + +restlog - JSON log-structured data storage with REST API + +Copyright (C) 2021 Bozo Kopic + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see <http://www.gnu.org/licenses/>. |