Merge pull request #160 from line-o/next

Add function readOptionsFromEnv

.github/workflows/semantic-release.yml

@@ -19,7 +19,7 @@ jobs:
       exist:
         image: existdb/existdb:${{ matrix.exist-version }}
         ports:
-          - 8080:8080
+          - 8443:8443
     steps:
       - uses: actions/checkout@v2
       - name: Use Node.js ${{ matrix.node-version }}

.gitignore

@@ -23,6 +23,10 @@ build/Release
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
 
+# dotenv files
+# .env, .env.development etc.
+.env*
+
 dev
 .idea
 .vscode

README.md

@@ -1,6 +1,8 @@
 # gulp-exist
 
-[![version](https://img.shields.io/npm/v/@existdb/gulp-exist.svg)](https://www.npmjs.com/package/@existdb/gulp-exist) [![travis-ci](https://api.travis-ci.com/eXist-db/gulp-exist.png)](https://travis-ci.com/eXist-db/gulp-exist) [![windows ci](https://ci.appveyor.com/api/projects/status/wcbi1e0yx47prhl6?svg=true)](https://ci.appveyor.com/project/olvidalo/gulp-exist)
+[![version](https://img.shields.io/npm/v/@existdb/gulp-exist.svg)](https://www.npmjs.com/package/@existdb/gulp-exist)
+![semantic release status](https://github.com/exist-db/gulp-exist/actions/workflows/semantic-release.yml/badge.svg)
+[![windows ci](https://ci.appveyor.com/api/projects/status/wcbi1e0yx47prhl6?svg=true)](https://ci.appveyor.com/project/olvidalo/gulp-exist)
 
 
 > A gulp plugin to deploy to and query an eXist-db using eXist's XML-RPC API.
@@ -25,8 +27,8 @@ npm install --save-dev gulp @existdb/gulp-exist
 Then create a file with the name `gulpfile.js` in the root of your project with the following contents
 
 ```js
-const gulp = require('gulp'),
-    exist = require('@existdb/gulp-exist')
+const {src} = require('gulp'),
+    {createClient} = require('@existdb/gulp-exist')
 
 // authenticate against local eXist instance for development 
 const connectionOptions = {
@@ -36,12 +38,12 @@ const connectionOptions = {
     }
 }
 
-const exClient = exist.createClient(connectionOptions)
+const exClient = createClient(connectionOptions)
 
 // deploy all
 function deploy () {
-    return gulp.src('**/*', {cwd: 'build'})
-        .pipe(exClient.dest({target: '/db/apps/myapp/'})
+    return src('**/*', {cwd: 'build'})
+        .pipe(exClient.dest({target: '/db/apps/myapp/'}))
 }
 
 exports.default = deploy
@@ -58,6 +60,63 @@ for a more complete gulpfile offering more advanced tasks.
 
 ## API
 
+### exist.readOptionsFromEnv()
+
+Read connection options from environment variables.
+Currently supported variables are listed in the table below.
+
+| variable name | default | description
+|----|----|----
+| `EXISTDB_USER` | _none_ | the user used to connect to the database and to execute queries with
+| `EXISTDB_PASS` | _none_ | the password to authenticate the user against the database
+| `EXISTDB_SERVER` | `https://localhost:8443` | the URL of the database instance to connect to (only http and https protocol allowed)
+
+#### Example
+
+With the below setup the connection is then controlled by the variables
+in the environment.  
+
+```js
+const {src} = require('gulp')
+const {createClient, readOptionsFromEnv} = require('@existdb/gulp-exist')
+const exClient = createClient(readOptionsFromEnv())
+
+// deploy all
+function deploy () {
+    return src('**/*', {cwd: 'build'})
+        .pipe(exClient.dest({target: '/db/apps/myapp/'}))
+}
+
+exports.default = deploy
+```
+
+```sh
+EXISTDB_SERVER=http://localhost:8080 \
+EXISTDB_USER=admin \
+EXISTDB_PASS= \
+gulp deploy
+```
+
+The npm package [dotenv-cli](https://www.npmjs.com/package/dotenv-cli) offers a great way to read and set environment
+variables from files.
+
+```sh
+npm install -g dotenv-cli
+```
+
+Create a `.env` in your project root.
+
+```sh
+EXISTDB_SERVER=http://localhost:8080
+EXISTDB_USER=admin
+EXISTDB_PASS=
+```
+And then 
+
+```sh
+dotenv gulp deploy
+```
+
 ### exist.createClient(options)
 
 Returns a set of functions to interact with an eXist-db instance.
@@ -80,7 +139,7 @@ Default: `'localhost'`
 ##### port
 
 Type: `number`
-Default: `8080`
+Default: `8443`
 
 ##### path
 
@@ -103,24 +162,39 @@ Default:
 
 ##### secure
 
-Use HTTPS to connect to the database instance.
-Needs a valid certificate installed in the keystore of
-exist.
+Use HTTPS (or HTTP) to connect to the database instance.
+
+**NOTE:** You need a valid certificate installed in the keystore of
+exist for connections to remote servers.
 
 Type: `Boolean`
-Default: `false`
+Default: `true`
 
 #### Example
 
+Connecting to a remote server using a secure connection.
+
 ```js
-const exClient = exist.createClient({
-    host: "my.server",
+const {createClient} = require('@existdb/gulp-exist')
+const exClient = createClient({
+    host: "my-server.tld",
     secure: true,
     port: 443,
     basic_auth: { user: "app", pass: "1 handmade eclectic eclaire" }
 })
 ```
 
+Connecting to localhost server using a insecure connection.
+
+```js
+const {createClient} = require('@existdb/gulp-exist')
+const exClient = createClient({
+    host: "localhost",
+    secure: false,
+    port: 8080
+})
+```
+
 ### existClient.dest(options)
 
 Uploads input files to a target collection in eXist.
@@ -439,9 +513,19 @@ exports.default = series(build, xar, install)
 
 ### Prerequisites
 
-A running instance of eXist-db v2.2+ at localhost port 8080 with an
+A running instance of eXist-db v2.2+ at localhost port 8443 with an
 admin user that has a blank password.
 
+You can override the above settings with environment variables (see [dbconnection.js](https://github.com/eXist-db/gulp-exist/tree/master/spec/dbconnection.js) for details).
+
 ### Run the Tests
 
-    npm test
+```sh
+npm test
+```
+
+[dotenv-cli](https://www.npmjs.com/package/dotenv-cli) can be used here, too:
+
+```sh
+dotenv npm test
+```

index.js

@@ -14,7 +14,7 @@ const PluginError = require('plugin-error')
 const assign = require('lodash.assign')
 const File = require('vinyl')
 const Path = require('path')
-const exist = require('@existdb/node-exist')
+const { connect, getMimeType, defineMimeTypes, readOptionsFromEnv } = require('@existdb/node-exist')
 
 /**
  * @typedef {Object} GulpExistConnectionOptions
@@ -36,8 +36,8 @@ const exist = require('@existdb/node-exist')
  */
 const defaultRPCoptions = {
   host: 'localhost',
-  port: '8080',
-  secure: false,
+  port: '8443',
+  secure: true,
   path: '/exist/xmlrpc',
   basic_auth: {
     user: 'guest',
@@ -147,13 +147,13 @@ function dest (client, options) {
 
       // then upload file
       .then(function (result) {
-        log('Storing "' + file.base + file.relative + '" as (' + exist.getMimeType(file.path) + ')...')
+        log('Storing "' + file.base + file.relative + '" as (' + getMimeType(file.path) + ')...')
         return client.documents.upload(file.contents)
       })
 
       // parse file on server
       .then(function (result) {
-        return client.documents.parseLocal(result, remotePath, { mimetype: exist.getMimeType(file.path) })
+        return client.documents.parseLocal(result, remotePath, { mimetype: getMimeType(file.path) })
       })
 
       // handle re-upload as octet stream if parsing failed and html5AsBinary is set
@@ -342,7 +342,7 @@ function install (client, options) {
 function createClient (options) {
   // TODO sanity checks
   const _options = assign({}, defaultRPCoptions, options)
-  const client = exist.connect(_options)
+  const client = connect(_options)
   return {
     dest: dest.bind(null, client),
     query: query.bind(null, client),
@@ -351,24 +351,9 @@ function createClient (options) {
   }
 }
 
-/**
- * define additional mapping of file extension to mimetype
- * will throw if already defined
- *
- * @param {Object<string,string>} mimeTypes
- */
-function defineMimeTypes (mimeTypes) {
-  exist.defineMimeTypes(mimeTypes)
+module.exports = {
+  createClient,
+  defineMimeTypes,
+  getMimeType,
+  readOptionsFromEnv
 }
-
-/**
- * returns the mimetype of a file
- *
- * @param {string} path
- * @returns {string}
- */
-function getMimeType (path) {
-  return exist.getMimeType(path)
-}
-
-module.exports = { createClient, defineMimeTypes, getMimeType }