diff --git a/docs/pouch-express.md b/docs/pouch-express.md index 7b9c81b..7bdea48 100644 --- a/docs/pouch-express.md +++ b/docs/pouch-express.md @@ -10,12 +10,15 @@ that is meant to be wired into the root of [a `gpii.express` instance](https://g In addition to the options supported by the `gpii.express.router` component, this component has the following unique options. -| Option | Type | Description | -| ------------------------ | ---------- | ----------- | -| `databases` (required) | `{Object}` | An object that describes one or more databases to create. See below for full details. | -| `dbOptions` | `{Object}` | Options that will be used when constructing each individual database. See [the PouchDB docs](https://pouchdb.com/api.html#create_database) for supported options. ] -| `expressPouchConfig` | `{Object}` | Options that will be used when constructing the express-pouchdb instance. See [the express-pouchdb docs](https://github.com/pouchdb/express-pouchdb#api) for supported options.| -| `expressPouchConfigPath` | `{String}` | The path to the temporary file where the settings in `expressPouchConfig` will be stored and read by express-pouchdb. The settings in `expressPouchConfig` will be saved to a file named `pouchdb.conf` in this directory. Defaults to `os.tmpdir() + "/pouch.conf"`.| +| Option | Type | Description | +| ------------------------- | ---------- | ----------- | +| `baseDir` | `String` | The path to the "base directory" that will contain our logs and database content. Defaults to a subdirectory under `os.tmpdir()` that matches the component ID. | +| `databases` (required) | `{Object}` | An object that describes one or more databases to create. See below for full details. | +| `dbOptions` | `{Object}` | Options that will be used when constructing each individual database. See [the PouchDB docs](https://pouchdb.com/api.html#create_database) for supported options. ] +| `expressPouchConfig` | `{Object}` | Options that will be used when constructing the express-pouchdb instance. See [the express-pouchdb docs](https://github.com/pouchdb/express-pouchdb#api) for supported options. | +| `expressPouchLogFilename` | `{String}` | The log file name to create in `expressPouchLogPath` (see below). Defaults to `express-pouchdb-log-{component_id}.txt`. | +| `expressPouchLogPath` | `{String}` | The full path to the log file. By default, the file is stored in `options.baseDir` under the name defined in `options.expressPouchLogFilename` (see above). | +| `rimrafTimeout` | `{Number}` | When cleaning up filesystem content, the number of milliseconds to wait before forcing a timeout. Defaults to `1000` (one second). | ### The `databases` option diff --git a/docs/pouchdb.md b/docs/pouchdb.md index d451b28..6e756a4 100644 --- a/docs/pouchdb.md +++ b/docs/pouchdb.md @@ -34,7 +34,7 @@ A Fluid component that wraps a PouchDB instance and exposes select methods from # Component Invokers -#`{that}.allDocs([options])` +# `{that}.allDocs([options])` * `options {Object}`: The options to control which records are returned. * Returns: A `Promise` that will be resolved once the database has been initialized. @@ -43,7 +43,7 @@ Return the full list of documents in the database, optionally filtered using `op Check the [Pouchdb `allDocs` documentation](https://pouchdb.com/api.html#batch_fetch) for more details. -##`{that}.bulkDocs(docs, [options])` +## `{that}.bulkDocs(docs, [options])` Create or update multiple documents at once. You will need to have valid `_id` and `_rev` values for each existing document you wish to update. @@ -51,7 +51,7 @@ document you wish to update. Check the [PouchDB `bulkDocs` docs](https://pouchdb.com/api.html#batch_create) for more details. -##`{that}.bulkGet(options)` +## `{that}.bulkGet(options)` Retrieve a set of full documents based on `options` like the following: @@ -63,35 +63,35 @@ Retrieve a set of full documents based on `options` like the following: Check the [PouchDB `bulkGet` docs](https://pouchdb.com/api.html#bulk_get) for more details. -##`{that}.close([options])` +## `{that}.close([options])` Close the database. Returns a promise that will be completed when the database is closed. Also fires the `onCloseComplete` event when the database is closed. Check the [PouchDB `close` docs](https://pouchdb.com/api.html#close_database) for more details. -##`{that}.destroyPouch()` +## `{that}.destroyPouch()` Destroy the database, including all records. This is called `destroyPouch` to avoid overriding the implicit `destroy` invoker that is part of [the Fluid component lifecycle](http://docs.fluidproject.org/infusion/development/ComponentLifecycle.html). Check the [PouchDB `destroy` docs](https://pouchdb.com/api.html#destroy) for more details. -##`{that}.compact([options])` +## `{that}.compact([options])` Compact the database, removing deleted data and older revisions. This method is not tested and is used at your own risk. Check the [PouchDB `compact` docs](https://pouchdb.com/api.html#compaction) for more details. -##`{that}.get(docId, [options])` +## `{that}.get(docId, [options])` Retrieve the document whose ID matches `docId`. Check the [PouchDB `get` docs](https://pouchdb.com/api.html#fetch_document) for more details. -##`{that}.getAttachment(docId, attachmentId, [options])` +## `{that}.getAttachment(docId, attachmentId, [options])` Retrieve an attachment from `docId` whose id matches `attachmentId`. This method is not tested and is used at your own risk. @@ -99,28 +99,28 @@ risk. Check the [PouchDB `getAttachment` docs](https://pouchdb.com/api.html#get_attachment) for more details. -##`{that}.info()` +## `{that}.info()` Get information about the current database, including the number of records. Check the [PouchDB `info` docs](https://pouchdb.com/api.html#database_information) for more details. -##`{that}.post(doc, [options])` +## `{that}.post(doc, [options])` POST a new document `doc`. This may (but does not have to) contain an `_id` variable. Check the [PouchDB `post` docs](https://pouchdb.com/api.html#create_document) for more details. -##`{that}.put(doc, [docId], [docRev], [options])` +## `{that}.put(doc, [docId], [docRev], [options])` PUT a new document or an update to an existing document. Check the [PouchDB `put` docs](https://pouchdb.com/api.html#create_document) for more details. -##`{that}.putAttachment(docId, attachmentId, [rev], attachment, type)` +## `{that}.putAttachment(docId, attachmentId, [rev], attachment, type)` Create or update an attachment. @@ -128,21 +128,21 @@ Check the [PouchDB `putAttachment` docs](https://pouchdb.com/api.html#save_attac not tested and is used at your own risk. -##`{that}.query(fun, [options])` +## `{that}.query(fun, [options])` Execute the supplied `fun` function and return the results. Intended to be used with a map/reduce function. Check the [PouchDB `query` docs](https://pouchdb.com/api.html#query_database) for more details. -##`{that}.remove(doc, [options])` +## `{that}.remove(doc, [options])` Remove the document `doc` from the database. `doc` must contain a valid `_id` and `_rev`. Check the [PouchDB `remove` docs](https://pouchdb.com/api.html#delete_document) for more details. -##`{that}.removeAttachment(docId, attachmentId, rev)` +## `{that}.removeAttachment(docId, attachmentId, rev)` Remove an existing attachment. @@ -150,7 +150,7 @@ Check the [PouchDB `removeAttachment` docs](https://pouchdb.com/api.html#delete_ method is not tested and is used at your own risk. -##`{that}.viewCleanup()` +## `{that}.viewCleanup()` Clean up any stale map/reduce indexes. This method is not tested and is used at your own risk. @@ -165,10 +165,13 @@ Check the [PouchDB `viewCleanup` docs](https://pouchdb.com/api.html#view_cleanup | -------------------- | ----------- | ----------- | | `baseDir` | `{String}` | The path in which our database content will live. Will be used to populate `options.dbOptions.prefix` (see below). Defaults to a subdirectory based on the component's id in `os.tmpDir()`. | | `dbOptions.prefix` | `{String}` | `baseDir`, and `dbOptions.name` (see above), combined into a final path, with a trailing separator. | +| `removeDirOnCleanup` | `{Boolean}` | Whether to remove `options.baseDir` during our "cleanup" phase. Defaults to `true`. | +| `rimrafTimeout` | `{Number}` | When cleaning up filesystem content, the number of milliseconds to wait before forcing a timeout. Defaults to `1000` (one second). | + ## Component Invokers -###`{that}.loadData(dbPaths)` +### `{that}.loadData(dbPaths)` * `dbPaths {String|Array}`: One or more package-relative paths to a JSON file to be loaded. * Returns: A `Promise` that will be resolved once the data has been loaded. diff --git a/package.json b/package.json index c893e4f..ede497e 100644 --- a/package.json +++ b/package.json @@ -32,7 +32,7 @@ "eslint": "3.19.0", "eslint-config-fluid": "1.1.0", "fluid-grunt-eslint": "18.1.2", - "gpii-testem": "1.0.0-dev.20170421T144625Z.05a2708", + "gpii-testem": "1.0.0-dev.20170426T161352Z.8a06597", "grunt": "1.0.1", "grunt-jsonlint": "1.1.0", "kettle": "1.4.1", diff --git a/src/js/pouch-express.js b/src/js/pouch-express.js index a7f9eba..f92178c 100644 --- a/src/js/pouch-express.js +++ b/src/js/pouch-express.js @@ -32,7 +32,7 @@ var expressPouchdb = require("express-pouchdb"); var PouchDB = require("pouchdb"); -fluid.require("path", require, "path"); +var path = fluid.require("path", require, "path"); // The cleanup cycle used by express-pouchdb leaves a shedload of listeners around. To avoid these, we disable the // event listener warnings, but only for PouchDB itself. @@ -85,14 +85,8 @@ gpii.pouch.express.initExpressPouchdb = function (that) { that.baseDirBelongsToUs = true; } - // There are unfortunately options that can only be configured via a configuration file. - // - // To allow ourselves (and users configuring and extending this grade) to control these options, we create the file - // with the contents of options.pouchConfig before configuring and starting express-pouchdb. - fs.writeFileSync(that.options.expressPouchConfigPath, JSON.stringify(that.options.expressPouchConfig, null, 2)); - that.PouchDB = PouchDB.defaults(that.options.dbOptions); - that.expressPouchdb = expressPouchdb(that.PouchDB, { configPath: that.options.expressPouchConfigPath }); + that.expressPouchdb = expressPouchdb(that.PouchDB, that.options.expressPouchConfig); return that.expressPouchdb; }; @@ -206,8 +200,8 @@ gpii.pouch.express.cleanup = function (that) { cleanupPromises.push(function () { return databaseInstance.destroyPouch(); }); }); - var optionsFileCleanupPromise = gpii.pouchdb.timelyRimraf(that.options.expressPouchConfigPath, {}, that.options.rimrafTimeout); - cleanupPromises.push(optionsFileCleanupPromise); + var logCleanupPromise = gpii.pouchdb.timelyRimraf(path.resolve(that.options.expressPouchLogPath), {}, that.options.rimrafTimeout); + cleanupPromises.push(logCleanupPromise); var cleanupSequence = fluid.promise.sequence(cleanupPromises); cleanupSequence.then(function () { @@ -233,6 +227,10 @@ gpii.pouch.express.cleanup = function (that) { return togo; }; +gpii.pouch.express.generateUniqueLogPath = function (that) { + return path.resolve(that.options.baseDir, "express-pouchcdb-log-" + that.id + ".txt"); +}; + fluid.defaults("gpii.pouch.express.base", { gradeNames: ["fluid.component", "gpii.express.middleware"], method: "use", // We have to support all HTTP methods, as does our underlying router. @@ -240,19 +238,18 @@ fluid.defaults("gpii.pouch.express.base", { namespace: "pouch-express", // Namespace to allow other routers to put themselves in the chain before or after us. tmpDir: os.tmpdir(), baseDir: "@expand:path.resolve({that}.options.tmpDir, {that}.id)", - expressPouchConfigFilename: "config.json", - expressPouchConfigPath: "@expand:path.resolve({that}.options.baseDir, {that}.options.expressPouchConfigFilename)", - expressPouchLogFilename: "log.txt", + expressPouchLogFilename: "@expand:gpii.pouch.express.generateUniqueLogPath({that})", + expressPouchLogPath: "@expand:path.resolve({that}.options.baseDir, {that}.options.expressPouchLogFilename)", expressPouchConfig: { + inMemoryConfig: true, mode: "minimumForPouchDB", overrideMode: { exclude: [ - "routes/changes", // Disable the unused changes API to avoid a leaked listener. - "routes/security" // Disable the unused security API to avoid holding the user db open. + "routes/changes" // Disable the unused changes API to avoid a leaked listener. ] }, log: { - file: "@expand:path.resolve({that}.options.tmpDir, {that}.options.expressPouchLogFilename)" + file: "{that}.options.expressPouchLogPath" } }, events: { diff --git a/tests/js/pouchdb-express-tests/persistence-tests.js b/tests/js/pouchdb-express-tests/persistence-tests.js index ad8072d..e4e5589 100644 --- a/tests/js/pouchdb-express-tests/persistence-tests.js +++ b/tests/js/pouchdb-express-tests/persistence-tests.js @@ -206,11 +206,14 @@ fluid.defaults("gpii.tests.pouch.persistent.caseHolder", { } }); +fluid.registerNamespace("gpii.tests.pouch.persistent.environment"); + fluid.defaults("gpii.tests.pouch.persistent.environment", { gradeNames: ["gpii.test.pouch.environment"], components: { harness: { type: "gpii.pouch.harness.persistent" + }, caseHolder: { type: "gpii.tests.pouch.persistent.caseHolder" diff --git a/yarn.lock b/yarn.lock index 4b40141..e5da437 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1660,9 +1660,9 @@ gpii-express@1.0.7: express-session "1.15.2" infusion "3.0.0-dev.20170322T234120Z.278de35" -gpii-testem@1.0.0-dev.20170421T144625Z.05a2708: - version "1.0.0-dev.20170421T144625Z.05a2708" - resolved "https://registry.yarnpkg.com/gpii-testem/-/gpii-testem-1.0.0-dev.20170421T144625Z.05a2708.tgz#03480ce7a9ac867409e1f033da195170abda27e0" +gpii-testem@1.0.0-dev.20170426T161352Z.8a06597: + version "1.0.0-dev.20170426T161352Z.8a06597" + resolved "https://registry.yarnpkg.com/gpii-testem/-/gpii-testem-1.0.0-dev.20170426T161352Z.8a06597.tgz#b71c39ab5ca388cdee1f92852779d3f6e0f05741" dependencies: gpii-express "1.0.7" infusion "3.0.0-dev.20170322T234120Z.278de35"