rest-on-couch

Interface to CouchDB that allows the control of permissions on the documents.

Prerequisites

• Node.js >= 20
• CouchDB >= 1.7

Certain features are only supported with a version of CouchDB >= 2.2:

• Mango queries
• Automatic destruction of design documents present in the database but not in the configuration file

REST API

API documentation

Configuration

The configuration is being read on-load from many sources, in the following order (ascending priority):

1. Default configuration. Some configuration elements have default values. They are defined in the source code
2. Main configuration file (config.js or config.json in ROC's home directory). See this configuration example which is used for the dev server.
3. Database configuration file (config.js in database's subdirectory)
4. Environment variable (uppercase snake-case with REST_ON_COUCH_ prefix)
5. Custom config file passed with --config in the CLI

Main options

url

Type: string
Default: 'http://localhost:5984'
URL of the CouchDB server.

username

Type: string
Default: undefined
Username for CouchDB connection.

password

Type: string
Default: undefined
Password for CouchDB connection.

logLevel

Type: string
Default: 'WARN'
Level of the logs stored in the database. Possible values are FATAL (1), ERROR (2), WARN (3), INFO (4), DEBUG (5) and TRACE (6). Logs are only inserted if the current level is equal or higher to the log's level.

authRenewal

Type: number
Default: 570
Time in seconds that the application waits before revalidating the session with CouchDB. This number should be smaller than the session's cookie life.

Server options

port

Type: number
Default: 3300
Port used by the rest-on-couch server.

auth

Type: object
Default: {couchdb:{}}
Object describing the authentication strategies that are available and providing options to them.

proxy

Type: boolean
Default: true
Set to true if your application is behind a proxy and needs to trust X-Forwarded- headers.

proxyPrefix

Type: string
Default: '/'
If the proxy is not at the root level of the URL, set this value to the corresponding prefix.

publicAddress

Type: string Default: 'http://localhost:3300 Use by the application to construct authentication callback URLs.

allowedOrigins

Type: array<string>
Default: []
If cross-origin calls need to be done, set the list of trusted origins here.

sessionDomain

Type: string
Default: undefined
Domain of the session cookie.

sessionKey

Type: string Default: 'roc:sess' Key of the session cookie.

sessionPath

Type: string Default: '/' Path of the session cookie.

sessionSecure

Type: boolean
Default: false
Set to true if the cookie should only be valid on secure URLs.

sessionSameSite

Type: string Default: 'lax' Value of the "SameSite" cookie option. Set to 'strict', 'lax', or 'none'.

debugrest

Type: boolean
Default: false
If set to true, a stack trace will be print to the body of the response when an error occurs.
Do not use this in production!

Setup environment with Docker (for running tests)

docker-compose up -d
node scripts/setup_database.mjs
npm test

Automatic importation

rest-on-couch is able to watch folders and to automatically import data in the database.

A specific userguide is available here.

License

MIT