Merge branch 'devel' of https://github.com/arangodb/arangodb into vpack

CHANGELOG

@@ -110,6 +110,12 @@ 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)
+
 
 v2.7.2 (XXXX-XX-XX)
 -------------------
@@ -120,6 +126,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)
 -------------------

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 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 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

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:
 

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

Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp

@@ -0,0 +1,45 @@
+!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 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
+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
+});
+```

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;

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
 /// });
 ///