Linking services together

When using multiple services (or multiple copies of the same service) in thesame database, sometimes you may want to share collections or methods betweenthose services. Typical examples are:

  • collections or APIs for managing shared data(e.g. application users or session data)
  • common middleware that requires someconfiguration that would be identicalfor multiple services
  • reusable routers that provide the same APIfor different servicesFor scenarios like these, Foxx provides a way to link services together andallow them to export JS APIs other services can use.In Foxx these JS APIs are called dependencies,the services implementing them are called providers,the services using them are called consumers.

This chapter is about Foxx dependencies as described above. In JavaScript theterm dependencies can also refer tobundled node modules, which are an unrelated concept.

Declaring dependencies

Foxx dependencies can be declared in theservice manifestusing the provides and dependencies fields:

  • provides lists the dependencies a given service provides,i.e. which APIs it claims to be compatible with

  • dependencies lists the dependencies a given service consumes,i.e. which APIs its dependencies need to be compatible with

Explicitly naming your dependencies helps improving tooling support formanaging service dependencies in ArangoDB but is not strictly necessary.It is possible to omit the provides field even if your service provides aJS API and the dependencies field can be used without explicitly specifyingdependency names.

A dependency name should be an alphanumeric identifier, optionally using anamespace prefix (i.e. dependency-name or @namespace/dependency-name).For example, services maintained by the ArangoDB Foxx team typically usethe @foxx namespace whereas the @arangodb namespaceis reserved for internal use.

There is no official registry for dependency names but we recommend ensuringthe dependency names you use are unambiguous and meaningfulto other developers using your services.

A provides definition maps each provided dependency’s nameto the provided version:

  1. "provides": {
  2.   "@example/auth": "1.0.0"
  3. }

A dependencies definition maps the local alias of each consumed dependencyagainst a short definition that includes the name and version range:

  1. "dependencies": {
  2.   "myAuth": {
  3.     "name": "@example/auth",
  4.     "version": "^1.0.0",
  5.     "description": "This description is entirely optional.",
  6.     "required": false,
  7.     "multiple": false
  8.   }
  9. }

The local alias should be a valid JavaScript identifier(e.g. a valid variable name). When a dependency has been assigned,its JS API will be exposed in a corresponding property of theservice context,e.g. module.context.dependencies.myAuth.

Assigning dependencies

Like configuration,dependencies can be assigned usingthe web interface,the Foxx CLI orthe Foxx HTTP API.

The value for each dependency should be the database-relative mount path ofthe service (including the leading slash). Both services need to be mounted inthe same database. The same service can be used to provide a dependencyfor multiple services.

Also as with configuration, a service that declares required dependencies whichhave not been assigned will not be mounted by Foxx until all requireddependencies have been assigned. Instead any attempt to access the service’sHTTP API will result in an error code.

Exporting a JS API

In order to provide a JS API other services can consume as a dependency,the service’s main file needs to export something other services can use.You can do this by assigning a value to the module.exports or propertiesof the exports object as with any other module export:

  1. module.exports = "Hello world";

This also includes collections. In the following example, the collectionexported by the provider will use the provider’scollection prefix rather than the consumer’s,allowing both services to share the same collection:

  1. module.exports = module.context.collection("shared_documents");

Let’s imagine we have a service managing our application’s users.Rather than allowing any consuming service to access the collection directly,we can provide a number of methods to manipulate it:

  1. const auth = require("./util/auth");
  2. const users = module.context.collection("users");
  4. exports.login = (username, password) => {
  5.   const user = users.firstExample({ username });
  6.   if (!user) throw new Error("Wrong username");
  7.   const valid = auth.verify(user.authData, password);
  8.   if (!valid) throw new Error("Wrong password");
  9.   return user;
  10. };
  11. exports.setPassword = (user, password) => {
  12.   const authData = auth.create(password);
  13.   users.update(user, { authData });
  14.   return user;
  15. };

Or you could even export a factory function to create an API that uses acustom error type provided by the consumer rather than the producer:

  1. const auth = require("./util/auth");
  2. const users = module.context.collection("users");
  4. module.exports = (BadCredentialsError = Error) => {
  5.   return {
  6.     login(username, password) {
  7.       const user = users.firstExample({ username });
  8.       if (!user) throw new BadCredentialsError("Wrong username");
  9.       const valid = auth.verify(user.authData, password);
  10.       if (!valid) throw new BadCredentialsError("Wrong password");
  11.       return user;
  12.     },
  13.     setPassword(user, password) {
  14.       const authData = auth.create(password);
  15.       users.update(user, { authData });
  16.       return user;
  17.     }
  18.   };
  19. };

Example usage (the consumer uses the local alias usersApi):

  1. "use strict";
  2. const createRouter = require("@arangodb/foxx/router");
  3. const joi = require("joi");
  5. // Using the dependency with arguments
  6. const AuthFailureError = require("./errors/auth-failure");
  7. const createUsersApi = module.context.dependencies.usersApi;
  8. const users = createUsersApi(AuthFailureError);
  10. const router = createRouter();
  11. module.context.use(router);
  13. router.use((req, res, next) => {
  14.   try {
  15.     next();
  16.   } catch (e) {
  17.     if (e instanceof AuthFailureError) {
  18.       res.status(401);
  19.       res.json({
  20.         error: true,
  21.         message: e.message
  22.       });
  23.     } else {
  24.       console.error(e.stack);
  25.       res.status(500);
  26.       res.json({
  27.         error: true,
  28.         message: "Something went wrong."
  29.       });
  30.     }
  31.   }
  32. });
  34. router
  35.   .post("/login", (req, res) => {
  36.     const { username, password } = req.body;
  37.     const user = users.login(username, password);
  38.     // handle login success
  39.     res.json({ welcome: username });
  40.   })
  41.   .body(
  42.     joi.object().keys({
  43.       username: joi.string().required(),
  44.       password: joi.string().required()
  45.     })
  46.   );