From 56a35cc3924d2c4f3dd400d2523683ee504da91c Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Tue, 24 Nov 2015 13:58:35 +0100 Subject: [PATCH 1/6] Add #1495 to CHANGELOG --- CHANGELOG | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG b/CHANGELOG index 231b36d463..5402742b3f 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -120,6 +120,8 @@ v2.7.2 (XXXX-XX-XX) * fixed potentially invalid pointer access in shaper when the currently accessed document got re-located by the WAL collector at the very same time +* Foxx: optional configuration options no longer log validation errors when assigned + empty values (#1495) v2.7.1 (2015-11-07) ------------------- From 5d3b0b06196d29325886d015996cd6729dd8a66c Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Tue, 24 Nov 2015 15:00:11 +0100 Subject: [PATCH 2/6] Set returnBodyOnError: true by default in org/arangodb/request Fixes #1437. --- CHANGELOG | 4 ++++ .../Books/Users/ModuleRequest/README.mdpp | 1 + .../Users/Upgrading/UpgradingChanges28.mdpp | 23 +++++++++++++++++++ js/common/modules/org/arangodb/request.js | 3 ++- 4 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp diff --git a/CHANGELOG b/CHANGELOG index 5402742b3f..3f1ccb4ba2 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -110,6 +110,10 @@ v2.8.0 (XXXX-XX-XX) * added convenience function `db._explain(query)` for human-readable explanation of AQL queries +* the `org/arangodb/request` module now returns response bodies for error responses + by default. The old behaviour of not returning bodies for error responses can be + re-enabled by explicitly setting the option `returnBodyOnError` to `false` (#1437) + v2.7.2 (XXXX-XX-XX) ------------------- diff --git a/Documentation/Books/Users/ModuleRequest/README.mdpp b/Documentation/Books/Users/ModuleRequest/README.mdpp index 5847bb113f..b60d825aa6 100644 --- a/Documentation/Books/Users/ModuleRequest/README.mdpp +++ b/Documentation/Books/Users/ModuleRequest/README.mdpp @@ -64,6 +64,7 @@ The request function takes the following options: * *maxRedirects*: the maximum number of redirects to follow. Default: `10`. * *encoding*: encoding to be used for the response body. If set to `null`, the response body will be returned as a `Buffer`. Default: `"utf-8"`. * *timeout*: number of milliseconds to wait for a response before aborting the request. +* *returnBodyOnError*: whether the response body should be returned even when the server response indicates an error. Default: `true`. The function returns a *Response* object with the following properties: diff --git a/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp b/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp new file mode 100644 index 0000000000..bb38eafb45 --- /dev/null +++ b/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp @@ -0,0 +1,23 @@ +!CHAPTER Incompatible changes in ArangoDB 2.8 + +It is recommended to check the following list of incompatible changes **before** +upgrading to ArangoDB 2.8, and adjust any client programs if necessary. + + +!SECTION Miscellaneous changes + +!SUBSECTION Module `org/arangodb/request` + +The module now always returns response bodies, even for error responses. In versions +prior to 2.8 the module would silently drop response bodies if the response header +indicated an error. + +The old behaviour of not returning bodies for error responses can be restored by +explicitly setting the option `returnBodyOnError` to `false`: + +```js +let response = request({ + //... + returnBodyOnError: false +}); +``` diff --git a/js/common/modules/org/arangodb/request.js b/js/common/modules/org/arangodb/request.js index 1d3eba55be..d1abb9ce45 100644 --- a/js/common/modules/org/arangodb/request.js +++ b/js/common/modules/org/arangodb/request.js @@ -152,7 +152,8 @@ function request(req) { let options = { method: (req.method || 'get').toUpperCase(), headers: headers, - returnBodyAsBuffer: true + returnBodyAsBuffer: true, + returnBodyOnError: req.returnBodyOnError !== false }; if (is.existy(req.timeout)) { options.timeout = req.timeout; From 0c336d4548a72748b11ed5dfe6fbbca1a3d8b8b1 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Tue, 24 Nov 2015 15:01:11 +0100 Subject: [PATCH 3/6] Add info on having changed in 2.8 --- CHANGELOG | 2 ++ .../Users/Upgrading/UpgradingChanges28.mdpp | 22 +++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/CHANGELOG b/CHANGELOG index 3f1ccb4ba2..743dda29ab 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -110,6 +110,8 @@ v2.8.0 (XXXX-XX-XX) * added convenience function `db._explain(query)` for human-readable explanation of AQL queries +* module resolution as used by `require` now behaves more like in node.js + * the `org/arangodb/request` module now returns response bodies for error responses by default. The old behaviour of not returning bodies for error responses can be re-enabled by explicitly setting the option `returnBodyOnError` to `false` (#1437) diff --git a/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp b/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp index bb38eafb45..3c5d0d32c5 100644 --- a/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp +++ b/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp @@ -6,6 +6,28 @@ upgrading to ArangoDB 2.8, and adjust any client programs if necessary. !SECTION Miscellaneous changes +!SUBSECTION Module resolution + +The behaviour of the JavaScript module resolution used by the `require` function has +been modified to improve compatibility with modules written for Node.js. + +Specifically + +* absolute paths (e.g. `/some/absolute/path`) are now always interpreted as absolute + file system paths, relative to the file system root + +* global names (e.g. `global/name`) are now first intepreted as references to modules + residing in a relevant `node_modules` folder, a built-in module or a matching + document in the internal `_modules` collection, and only resolved to local file paths + if no other match is found + +Previously the two formats were treated interchangeably and would be resolved to local +file paths first, leading to problems when local files used the same names as other +modules (e.g. a local file `chai.js` would cause problems when trying to load the +`chai` module installed in `node_modules`). + +For more information see the [blog announcement of this change](https://www.arangodb.com/blog/). + !SUBSECTION Module `org/arangodb/request` The module now always returns response bodies, even for error responses. In versions From 01aaa5f95a3823f4499a6a863de0c224f4e9cbd4 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Tue, 24 Nov 2015 16:18:37 +0100 Subject: [PATCH 4/6] Adjust docs so it no longer implies IDs in ArangoDB might be numbers Fixes #1408. --- .../modules/org/arangodb/foxx/request_context.js | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/js/server/modules/org/arangodb/foxx/request_context.js b/js/server/modules/org/arangodb/foxx/request_context.js index a0ec32d803..b802109345 100644 --- a/js/server/modules/org/arangodb/foxx/request_context.js +++ b/js/server/modules/org/arangodb/foxx/request_context.js @@ -170,7 +170,7 @@ class RequestContext { /// ```js /// app.get("/foxx/:name", function { /// // Do something -/// }).pathParam("name", joi.number().integer().required().description("Name of the Foxx")); +/// }).pathParam("name", joi.string().required().description("Name of the Foxx")); /// ``` /// /// You can also pass in a configuration object instead: @@ -179,7 +179,7 @@ class RequestContext { /// app.get("/foxx/:name", function { /// // Do something /// }).pathParam("name", { -/// type: joi.number().integer(), +/// type: joi.string(), /// required: true, /// description: "Name of the Foxx" /// }); @@ -280,7 +280,7 @@ class RequestContext { /// app.get("/foxx", function { /// // Do something /// }).queryParam("id", -/// joi.number().integer() +/// joi.string() /// .required() /// .description("Id of the Foxx") /// .meta({allowMultiple: false}) @@ -293,7 +293,7 @@ class RequestContext { /// app.get("/foxx", function { /// // Do something /// }).queryParam("id", { -/// type: joi.number().integer().required().description("Id of the Foxx"), +/// type: joi.string().required().description("Id of the Foxx"), /// allowMultiple: false /// }); /// ``` @@ -752,7 +752,7 @@ _.each([ /// *Examples* /// /// ```js -/// app.allRoutes.pathParam("id", joi.number().integer().required().description("Id of the Foxx")); +/// app.allRoutes.pathParam("id", joi.string().required().description("Id of the Foxx")); /// /// app.get("/foxx/:id", function { /// // Secured by pathParam @@ -763,7 +763,7 @@ _.each([ /// /// ```js /// app.allRoutes.pathParam("id", { -/// type: joi.number().integer(), +/// type: joi.string(), /// required: true, /// description: "Id of the Foxx" /// }); @@ -786,7 +786,7 @@ _.each([ /// /// ```js /// app.allroutes.queryParam("id", -/// joi.number().integer() +/// joi.string() /// .required() /// .description("Id of the Foxx") /// .meta({allowMultiple: false}) @@ -801,7 +801,7 @@ _.each([ /// /// ```js /// app.allroutes.queryParam("id", { -/// type: joi.number().integer().required().description("Id of the Foxx"), +/// type: joi.string().required().description("Id of the Foxx"), /// allowMultiple: false /// }); /// From a27f7faa32b3d7a2f8d273b0eb0f81a453eb279e Mon Sep 17 00:00:00 2001 From: Jan Steemann Date: Tue, 24 Nov 2015 17:01:14 +0100 Subject: [PATCH 5/6] issue #1587 --- Documentation/Books/Users/Glossary/README.mdpp | 18 +++++++++++------- .../Users/NamingConventions/DocumentKeys.mdpp | 6 ++++-- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/Documentation/Books/Users/Glossary/README.mdpp b/Documentation/Books/Users/Glossary/README.mdpp index 71e7a23d74..998a7f1700 100644 --- a/Documentation/Books/Users/Glossary/README.mdpp +++ b/Documentation/Books/Users/Glossary/README.mdpp @@ -71,30 +71,34 @@ apps/ # the instance's application directory !SUBSECTION Document -Documents in ArangoDB are JSON objects. These objects can be nested (to any depth) and may contains lists. Each document is uniquely identified by its document handle. +Documents in ArangoDB are JSON objects. These objects can be nested (to any depth) and may contain arrays. Each document is uniquely identified by its document handle. !SUBSECTION Document ETag -The document revision enclosed in double quotes. The revision is returned by several HTTP API methods in the Etag HTTP header. +The document revision (`_rev` value) enclosed in double quotes. The revision is returned by several HTTP API methods in the Etag HTTP header. !SUBSECTION Document Handle -A document handle uniquely identifies a document in the database. It is a string and consists of the collection's name and the document key (_key attribute) separated by /. +A document handle uniquely identifies a document in the database. It is a string and consists of the collection's name and the document key (`_key` attribute) separated by /. The document handle is stored in a document's `_id` attribute. !SUBSECTION Document Key -A document key uniquely identifies a document in a given collection. It can and should be used by clients when specific documents are searched. Document keys are stored in the _key attribute of documents. The key values are automatically indexed by ArangoDB in a collection's primary index. Thus looking up a document by its key is regularly a fast operation. The _key value of a document is immutable once the document has been created. +A document key uniquely identifies a document in a given collection. It can and should be used by clients when specific documents are searched. Document keys are stored in the `_key` attribute of documents. The key values are automatically indexed by ArangoDB in a collection's primary index. Thus looking up a document by its key is regularly a fast operation. The `_key` value of a document is immutable once the document has been created. -By default, ArangoDB will auto-generate a document key if no _key attribute is specified, and use the user-specified _key otherwise. +By default, ArangoDB will auto-generate a document key if no `_key` attribute is specified, and use the user-specified `_key` value otherwise. -This behavior can be changed on a per-collection level by creating collections with the keyOptions attribute. +This behavior can be changed on a per-collection level by creating collections with the `keyOptions` attribute. -Using keyOptions it is possible to disallow user-specified keys completely, or to force a specific regime for auto-generating the _key values. +Using `keyOptions` it is possible to disallow user-specified keys completely, or to force a specific regime for auto-generating the `_key` values. + +There are some restrictions for user-defined keys (see [NamingConventions for document keys](../NamingConventions/DocumentKeys.html). !SUBSECTION Document Revision As ArangoDB supports MVCC, documents can exist in more than one revision. The document revision is the MVCC token used to identify a particular revision of a document. It is a string value currently containing an integer number and is unique within the list of document revisions for a single document. Document revisions can be used to conditionally update, replace or delete documents in the database. In order to find a particular revision of a document, you need the document handle and the document revision. +The document revision is stored in the `_rev` attribute of a document, and is set and updated by ArangoDB automatically. The `_rev` value cannot be set from the outside. + ArangoDB currently uses 64bit unsigned integer values to maintain document revisions internally. When returning document revisions to clients, ArangoDB will put them into a string to ensure the revision id is not clipped by clients that do not support big integers. Clients should treat the revision id returned by ArangoDB as an opaque string when they store or use it locally. This will allow ArangoDB to change the format of revision ids later if this should be required. Clients can use revisions ids to perform simple equality/non-equality comparisons (e.g. to check whether a document has changed or not), but they should not use revision ids to perform greater/less than comparisons with them to check if a document revision is older than one another, even if this might work for some cases. !SUBSECTION Edge diff --git a/Documentation/Books/Users/NamingConventions/DocumentKeys.mdpp b/Documentation/Books/Users/NamingConventions/DocumentKeys.mdpp index 0ae7627539..668c454cd4 100644 --- a/Documentation/Books/Users/NamingConventions/DocumentKeys.mdpp +++ b/Documentation/Books/Users/NamingConventions/DocumentKeys.mdpp @@ -5,14 +5,16 @@ be saved along with a document in the *_key* attribute. Users can pick key values as required, provided that the values conform to the following restrictions: +* The key must be a string value. Numeric keys are not allowed, but any numeric + value can be put into a string and can then be used as document key. * The key must be at least 1 byte and at most 254 bytes long. Empty keys are disallowed when specified (though it may be valid to completely omit the *_key* attribute from a document) * It must consist of the letters a-z (lower or upper case), the digits 0-9 or any of the following punctuation characters: `_` `-` `:` `.` `@` `(` `)` `+` `,` `=` `;` `$` `!` `*` `'` `%` -* Any other characters, especially multi-byte sequences, whitespace or punctuation - characters cannot be used inside key values +* Any other characters, especially multi-byte UTF-8 sequences, whitespace or + punctuation characters cannot be used inside key values * The key must be unique within the collection it is used Keys are case-sensitive, i.e. *myKey* and *MyKEY* are considered to be From 7b595ad16d7ca66b21054353d8cb5324ce138b71 Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Tue, 24 Nov 2015 17:24:01 +0100 Subject: [PATCH 6/6] Update README.mdpp --- Documentation/Books/Users/Glossary/README.mdpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Books/Users/Glossary/README.mdpp b/Documentation/Books/Users/Glossary/README.mdpp index 998a7f1700..3fbc5fd5b5 100644 --- a/Documentation/Books/Users/Glossary/README.mdpp +++ b/Documentation/Books/Users/Glossary/README.mdpp @@ -83,7 +83,7 @@ A document handle uniquely identifies a document in the database. It is a string !SUBSECTION Document Key -A document key uniquely identifies a document in a given collection. It can and should be used by clients when specific documents are searched. Document keys are stored in the `_key` attribute of documents. The key values are automatically indexed by ArangoDB in a collection's primary index. Thus looking up a document by its key is regularly a fast operation. The `_key` value of a document is immutable once the document has been created. +A document key is a string that uniquely identifies a document in a given collection. It can and should be used by clients when specific documents are searched. Document keys are stored in the `_key` attribute of documents. The key values are automatically indexed by ArangoDB in a collection's primary index. Thus looking up a document by its key is regularly a fast operation. The `_key` value of a document is immutable once the document has been created. By default, ArangoDB will auto-generate a document key if no `_key` attribute is specified, and use the user-specified `_key` value otherwise.