all repos — litestore @ bc1b6b8c476cc1e566023aa6fc7a42b25a71da66

A minimalist nosql document store.

Updated docs, final changes before release.
h3rald h3rald@h3rald.com
Sat, 07 Mar 2020 18:45:50 +0100
commit

bc1b6b8c476cc1e566023aa6fc7a42b25a71da66

parent

f30c43a1f32519a845421c9ea4852ba0650518a7

M build_guidebuild_guide

@@ -7,8 +7,10 @@ md/architecture.md

md/getting-started.md md/usage.md md/auth.md + md/configuration-file.md md/middleware.md - md/litestore_js_object.md + md/global-js-objects.md + md/system-documents.md md/admin_app.md md/api.md md/api_info.md

@@ -26,7 +28,7 @@ for page in ${pages[@]}

do (cat "${page}"; printf "\n\n") >> LiteStore_UserGuide.md done -hastyscribe --field/version:1.7.0 LiteStore_UserGuide.md +hastyscribe --field/version:1.8.0 LiteStore_UserGuide.md rm LiteStore_UserGuide.md mv LiteStore_UserGuide.htm .. cd ../..
M src/admin/js/components/navbar.jssrc/admin/js/components/navbar.js

@@ -20,7 +20,7 @@ {path: "/guide/usage", title: "Usage"},

{path: "/guide/auth", title: "Authorization"}, {path: "/guide/configuration-file", title: "Configuration File"}, {path: "/guide/middleware", title: "Middleware"}, - {path: "/guide/global_js_objects", title: caret+"Global JavaScript Objects"}, + {path: "/guide/global-js-objects", title: caret+"Global JavaScript Objects"}, {path: "/guide/system-documents", title: "System Documents"}, {path: "/guide/admin_app", title: "Administration App"}, {path: "/guide/api", title: "HTTP API Reference"},

@@ -29,7 +29,6 @@ {path: "/guide/api_dir", title: caret+"dir (LiteStore Directory)"},

{path: "/guide/api_docs", title: caret+"docs (LiteStore Documents)"}, {path: "/guide/api_tags", title: caret+"tags (LiteStore Tags)"}, {path: "/guide/api_indexes", title: caret+"indexes (LiteStore Indexes)"}, - {path: "/guide/api_custom", title: caret+"custom (LiteStore Custom Resources)"}, {path: "/guide/nim-api", title: "Nim API Reference"}, {path: "/guide/nim-api_high", title: caret+"High-Level Nim API"}, {path: "/guide/nim-api_low", title: caret+"Low-Level Nim API"},
M src/admin/md/admin_app.mdsrc/admin/md/admin_app.md

@@ -1,6 +1,6 @@

## Administration App -A simple but fully-functional administration app can be used to manage LiteStore data stores. This app can simply be imported into a data store file and then run via LiteStore. +A simple, *slightly* dated, but fully-functional administration app can be used to manage LiteStore data stores. This app can simply be imported into a data store file and then run via LiteStore. ### Obtaining and Running the Administration App

@@ -64,4 +64,4 @@ * It is possible to upload local files instead of creating them by hand.

* Preview is available for images and HTML documents * Source code highlighting is available for Javascript, CSS, HTML, JSON and Markdown files. -![Document](images/app_document.png) +![Document](images/app_document.png)
M src/admin/md/auth.mdsrc/admin/md/auth.md

@@ -2,6 +2,11 @@ ## Authorization

LiteStore can be configured to automatically validate [JWT](https://jwt.io/) tokens and authorize authenticated users on specific resources (and specific resource verbs even) based on their [OAuth2 scopes](https://oauth.net/2/scope/) specified in the token itself. +> %note% +> auth.json vs. config.json +> +> As of version 1.8.0, it is recommended to use the LiteStore configuration file to configure authorization. This specialized **auth.json** configuration file format will however be maintained for compatibility reasons. + To configure authorization, create an **auth.json** file like the following: ```
M src/admin/md/configuration-file.mdsrc/admin/md/configuration-file.md

@@ -1,1 +1,90 @@

-## Configuration File+## Configuration File + +As of version 1.8.0, you can specify a configuration file containing settings, middleware and authorization configuration using the **--config** or **-c** command line option: + +[litestore -c:config.json](class:cmd) + +A typical configuration file looks like this: + +``` +{ + "settings": { + "log": "debug", + "port": 9200 + }, + "resources": { + "/docs/vehicles/*": { + "GET": { + "middleware": ["validate", "log"] + }, + "HEAD": { + "middleware": ["validate", "log"] + }, + "POST": { + "allowed": false + }, + "PATCH": { + "auth": ["admin:vehicles"], + "middleware": ["validate", "log"] + }, + "PUT": { + "auth": ["admin:vehicles"], + "middleware": ["validate", "log"] + }, + "DELETE": { + "auth": ["admin:vehicles"], + "middleware": ["validate", "log"] + } + }, + "/docs/logs/*": { + "GET": { + "auth": ["admin:server"] + }, + "POST": { + "allowed": false + }, + "PUT": { + "allowed": false + }, + "PATCH": { + "allowed": false + }, + "DELETE": { + "allowed": false + } + } + }, + "signature": "\n-----BEGIN CERTIFICATE-----\n<certificate text goes here>\n-----END CERTIFICATE-----\n" +} +``` + +At present, it contains a [settings](class:kwd), a [resources](class:kwd), and a [signature](class:kwd) section. + +### settings + +This section contains some of the most common command-line options, i.e.: + +* address +* port +* store +* directory +* mount +* readonly +* middleware +* log + +If a configuration file is specified and some of these settings are configured, they will be recognized as if they were specified via command line. However, if you also specify the same settings via command line, the command line settings will take precedence over the settings defined in the configuration file. + +### resources + +This section can contain any number of resource paths, like [/docs/](class:kwd), [/info/](class:kwd), [/docs/vehicles/AA456CC](class:kwd) or [/docs/logs/*](class:kwd). If a wildcard is specified after a resource or folder path, the rules defined within that section will match any document within the specified path. So for examople [/docs/vehicles/*](class:kwd) will match both [/docs/vehicles/AB547QV](class:kwd) and [/docs/vehicles/BB326CZ](class:kwd), but *not* [/docs/vehicles/](class:kwd). + +Within each resource path, you can specify different HTTP methods (all uppercase) and within each method any of the following properties: + +* **auth** &mdash; A list of JWT scopes necessary to access the specified resource with the specified method. +* **middleware** &mdash; A list of middleware function definitions that will be executed in sequence when the resource is accessed with the specified method. +* **allowed** &mdash; If set to **false**, LiteStore will return a [405 - Method not allowed](class:kwd) error code when accessing the resource with the specified method. + +### signature + +This section must be set to a valid certificate used validate JWT tokens. Note that the certificate must follow a specific format and start with the appropriate begin/end blocks.
M src/admin/md/getting-started.mdsrc/admin/md/getting-started.md

@@ -5,7 +5,7 @@ ### Downloading Pre-built Binaries

The easiest way to get LiteStore is by downloading one of the prebuilt binaries from the [Github Release Page][release]: - * [LiteStore for Mac OS X (x64)](https://github.com/h3rald/litestore/releases/download/{{$version}}litestore_{{$version}}_macosx_x64.zip) + * [LiteStore for Mac OS X (x64)](https://github.com/h3rald/litestore/releases/download/{{$version}}/litestore_{{$version}}_macosx_x64.zip) * [LiteStore for Windows (x64)](https://github.com/h3rald/litestore/releases/download/{{$version}}/litestore_{{$version}}_windows_x64.zip) * [LiteStore for Linux (x64)](https://github.com/h3rald/litestore/releases/download/{{$version}}/litestore_{{$version}}_linux_x64.zip)

@@ -29,7 +29,7 @@ A simple but functional Administration App is available to manage LiteStore, create documents interactively, view and search content, etc.

To get the app up and running (assuming that you have the [litestore](class:cmd) executable in your path): -1. Download the default [data.db](https://github.com/h3rald/litestore/releases/download/{{$version}}/data.db) file. This file is a LiteStore data store file containing the sample app. +1. Extract the default **data.db** file included in the LiteStore release package. This file is a LiteStore data store file containing the sample app. 2. Go to the local directory in which you downloaded the [data.db](class:cmd) file. 3. Run [litestore -s:data.db](class:cmd) -4. Go to [localhost:9500/docs/admin/index.html](http://localhost:9500/docs/admin/index.html). +4. Go to [localhost:9500/docs/admin/index.html](http://localhost:9500/docs/admin/index.html).
M src/admin/md/overview.mdsrc/admin/md/overview.md

@@ -29,7 +29,7 @@ You can add custom tags to documents to easily categorize them and retrieve them. Some system tags are also added automatically to identify the document content type, format and collection.

#### Enhanced Querying of JSON documents -By leveraging the [SQLite JSON1 extension](https://www.sqlite.org/json1.html) and implementing custom query string parsing, LiteStore provides enhanced filtering, ordering, and custom field selection of JSON documents. +By leveraging the [SQLite JSON1 extension](https://www.sqlite.org/json1.html) and implementing custom query string parsing, LiteStore provides enhanced filtering, ordering, and custom field selection of JSON documents. Additionally, you can also configure custom indexes specifying JSON fields for extra speed! #### Full-text Search

@@ -43,9 +43,9 @@ #### JWT-based Authorization

LiteStore can be configure validate [JWT](https://jwt.io/) tokens and configure access to specific resources based on specific [OAuth2 scopes](https://oauth.net/2/scope/). -#### Custom Resources +#### Middleware -By leveraging the [duktape](https://duktape.org/) library, LiteStore lets you create your own custom resources coding HTTP handlers in JavaScript. +By leveraging the [duktape](https://duktape.org/) library, you can create your own middleware functions in JavaScript to perform additional tasks (validation, logging, data aggregation...) before accessing data. #### Nim API
M src/admin/md/system-documents.mdsrc/admin/md/system-documents.md

@@ -1,1 +1,43 @@

-## System Documents+## System Documents + +As of version 1.8.0, it is possible to import, export, or delete *system documents* besides ordinary documents. Such documents are different from ordinary documents, because: + +* they are only intended to be used internally by LiteStore. +* they cannot be accessed via any of the public APIs except for the [import](class:kwd), [export](class:kwd) and [delete](class:kwd) commands. +* they must have a well-known name and/or folder structure. + +At present, only the following system documents are recognized by LiteStore: + +* **auth.json** &mdash; The LiteStore authorization configuration file. +* **config.json** &mdash; The main LiteStore configuration file. +* **middleware/\*.js** &mdash; Any [.js](class:ext) file containing the definition of a middleware function, placed within a [middleware](class:dir) folder. + +### Importing, exporting and deleting System Documents + +You can import, export, and delete system documents with the respective commands, but you must specify the [--system](class:kwd) command line flag. + +For example, suppose you have a [sysdocs](class:dir) folder containing the following file hierarchy: + +* sysdocs/ + * auth.jsom + * config.json + * middleware/ + * log.js + * req.js + * validate.js + +To import all the documents stored within the [sysdocs](class:dir) folder, you must run the following command: + +[litestore -d:sysdocs --system import](class:kwd) + +Similarly, the [export](class:kwd) and [delete](class:kwd) commands can be used to export and delete system documents respectively, always specifying the [--system](class:kwd) flag. + +### How LiteStore uses System Documents + +While at development time you may want to be able to edit your system documents and therefore keep them outside your data store as ordinary text files (and load them using the **--auth**, **--config** and **--middleware** options), in production you may want to ship them within the data store along with your application data. + +At run time, LiteStore will attempt to retrieve settings/middleware/authorization configuration using the following order of precedence (first listed have higher precedence): + +1. Command line options +2. Configuration files specified via command line options +3. Configuration files loaded as system documents
M src/admin/md/use-cases.mdsrc/admin/md/use-cases.md

@@ -9,7 +9,7 @@

As a document store, LiteStore provides the following features * You can save and retrieve data as arbitrary JSON documents but also as arbitrary documents of virtually any content type. -* You can query data using user-specified and system tags and/or via the native full-text search functionality (available only for textual documents). +* You can query data using user-specified and system tags, via the native full-text search functionality (available only for textual documents) or writing SQL-like queries on JSON documents. * You can access data by the means of a RESTful API. #### SPA Prototyping Backend and Lightweight File Server

@@ -42,4 +42,4 @@ Your app could then be served on any desktop system able to run LiteStore (e.g. OSX, Windows, Linux, ...even on a [Raspberry Pi](https://www.raspberrypi.org)).

#### Static Site Backend -LiteStore can be configured to run in read-only mode, so that only GET, HEAD, or OPTIONS request are accepted by the server. This makes it ideal as a backend for static web site generated with something like [nanoc](http://nanoc.ws) or [Jekyll](http://jekyllrb.com). +LiteStore can be configured to run in read-only mode, so that only GET, HEAD, or OPTIONS request are accepted by the server. This makes it ideal as a backend for static web site generated with something like [nanoc](http://nanoc.ws) or [Jekyll](http://jekyllrb.com).
M src/litestorepkg/lib/config.nimsrc/litestorepkg/lib/config.nim

@@ -1,6 +1,6 @@

const pkgName* = "litestore" - pkgVersion* = "1.7.0" + pkgVersion* = "1.8.0" pkgAuthor* = "Fabio Cevasco" pkgDescription* = "Self-contained, lightweight, RESTful document store." pkgLicense* = "MIT"