16 KiB

Raw Blame History

Managing Foxx services

database.listServices

async database.listServices([excludeSystem]): Array<Object>

Fetches a list of all installed service.

Arguments

excludeSystem: boolean (Default: true)

Whether system services should be excluded.

Examples

const services = await db.listServices();

// -- or --

const services = await db.listServices(false);

database.installService

async database.installService(mount, source, [options]): Object

Installs a new service.

Arguments

mount: string

The service's mount point, relative to the database.
source: Buffer | Readable | File | string

The service bundle to install.
options: Object (optional)

An object with any of the following properties:
- configuration: Object (optional)
  
  An object mapping configuration option names to values.
- dependencies: Object (optional)
  
  An object mapping dependency aliases to mount points.
- development: boolean (Default: false)
  
  Whether the service should be installed in development mode.
- legacy: boolean (Default: false)
  
  Whether the service should be installed in legacy compatibility mode.
  
  This overrides the engines option in the service manifest (if any).
- setup: boolean (Default: true)
  
  Whether the setup script should be executed.

Examples

const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.installService('/hello', source);

// -- or --

const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.installService('/hello', source);

// -- or --

const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.installService('/hello', source);

database.replaceService

async database.replaceService(mount, source, [options]): Object

Replaces an existing service with a new service by completely removing the old service and installing a new service at the same mount point.

Arguments

mount: string

The service's mount point, relative to the database.
source: Buffer | Readable | File | string

The service bundle to replace the existing service with.
options: Object (optional)

An object with any of the following properties:
- configuration: Object (optional)
  
  An object mapping configuration option names to values.
  
  This configuration will replace the existing configuration.
- dependencies: Object (optional)
  
  An object mapping dependency aliases to mount points.
  
  These dependencies will replace the existing dependencies.
- development: boolean (Default: false)
  
  Whether the new service should be installed in development mode.
- legacy: boolean (Default: false)
  
  Whether the new service should be installed in legacy compatibility mode.
  
  This overrides the engines option in the service manifest (if any).
- teardown: boolean (Default: true)
  
  Whether the teardown script of the old service should be executed.
- setup: boolean (Default: true)
  
  Whether the setup script of the new service should be executed.

Examples

const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.replaceService('/hello', source);

// -- or --

const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.replaceService('/hello', source);

// -- or --

const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.replaceService('/hello', source);

database.upgradeService

async database.upgradeService(mount, source, [options]): Object

Replaces an existing service with a new service while retaining the old service's configuration and dependencies.

Arguments

mount: string

The service's mount point, relative to the database.
source: Buffer | Readable | File | string

The service bundle to replace the existing service with.
options: Object (optional)

An object with any of the following properties:
- configuration: Object (optional)
  
  An object mapping configuration option names to values.
  
  This configuration will be merged into the existing configuration.
- dependencies: Object (optional)
  
  An object mapping dependency aliases to mount points.
  
  These dependencies will be merged into the existing dependencies.
- development: boolean (Default: false)
  
  Whether the new service should be installed in development mode.
- legacy: boolean (Default: false)
  
  Whether the new service should be installed in legacy compatibility mode.
  
  This overrides the engines option in the service manifest (if any).
- teardown: boolean (Default: false)
  
  Whether the teardown script of the old service should be executed.
- setup: boolean (Default: true)
  
  Whether the setup script of the new service should be executed.

Examples

const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.upgradeService('/hello', source);

// -- or --

const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.upgradeService('/hello', source);

// -- or --

const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.upgradeService('/hello', source);

database.uninstallService

async database.uninstallService(mount, [options]): void

Completely removes a service from the database.

Arguments

mount: string

The service's mount point, relative to the database.
options: Object (optional)

An object with any of the following properties:
- teardown: boolean (Default: true)
  
  Whether the teardown script should be executed.

Examples

await db.uninstallService('/my-service');
// service was uninstalled

database.getService

async database.getService(mount): Object

Retrieves information about a mounted service.

Arguments

mount: string

The service's mount point, relative to the database.

Examples

const info = await db.getService('/my-service');
// info contains detailed information about the service

database.getServiceConfiguration

async database.getServiceConfiguration(mount, [minimal]): Object

Retrieves an object with information about the service's configuration options and their current values.

Arguments

mount: string

The service's mount point, relative to the database.
minimal: boolean (Default: false)

Only return the current values.

Examples

const config = await db.getServiceConfiguration('/my-service');
// config contains information about the service's configuration

database.replaceServiceConfiguration

async database.replaceServiceConfiguration(mount, configuration, [minimal]): Object

Replaces the configuration of the given service.

Arguments

mount: string

The service's mount point, relative to the database.
configuration: Object

An object mapping configuration option names to values.
minimal: boolean (Default: false)

Only return the current values and warnings (if any).

Note: when using ArangoDB 3.2.8 or older, enabling this option avoids triggering a second request to the database.

Examples

const config = {currency: 'USD', locale: 'en-US'};
const info = await db.replaceServiceConfiguration('/my-service', config);
// info.values contains information about the service's configuration
// info.warnings contains any validation errors for the configuration

database.updateServiceConfiguration

async database.updateServiceConfiguration(mount, configuration, [minimal]): Object

Updates the configuration of the given service my merging the new values into the existing ones.

Arguments

mount: string

The service's mount point, relative to the database.
configuration: Object

An object mapping configuration option names to values.
minimal: boolean (Default: false)

Only return the current values and warnings (if any).

Note: when using ArangoDB 3.2.8 or older, enabling this option avoids triggering a second request to the database.

Examples

const config = {locale: 'en-US'};
const info = await db.updateServiceConfiguration('/my-service', config);
// info.values contains information about the service's configuration
// info.warnings contains any validation errors for the configuration

database.getServiceDependencies

async database.getServiceDependencies(mount, [minimal]): Object

Retrieves an object with information about the service's dependencies and their current mount points.

Arguments

mount: string

The service's mount point, relative to the database.
minimal: boolean (Default: false)

Only return the current values and warnings (if any).

Examples

const deps = await db.getServiceDependencies('/my-service');
// deps contains information about the service's dependencies

database.replaceServiceDependencies

async database.replaceServiceDependencies(mount, dependencies, [minimal]): Object

Replaces the dependencies for the given service.

Arguments

mount: string

The service's mount point, relative to the database.
dependencies: Object

An object mapping dependency aliases to mount points.
minimal: boolean (Default: false)

Only return the current values and warnings (if any).

Note: when using ArangoDB 3.2.8 or older, enabling this option avoids triggering a second request to the database.

Examples

const deps = {mailer: '/mailer-api', auth: '/remote-auth'};
const info = await db.replaceServiceDependencies('/my-service', deps);
// info.values contains information about the service's dependencies
// info.warnings contains any validation errors for the dependencies

database.updateServiceDependencies

async database.updateServiceDependencies(mount, dependencies, [minimal]): Object

Updates the dependencies for the given service by merging the new values into the existing ones.

Arguments

mount: string

The service's mount point, relative to the database.
dependencies: Object

An object mapping dependency aliases to mount points.
minimal: boolean (Default: false)

Only return the current values and warnings (if any).

Note: when using ArangoDB 3.2.8 or older, enabling this option avoids triggering a second request to the database.

Examples

const deps = {mailer: '/mailer-api'};
const info = await db.updateServiceDependencies('/my-service', deps);
// info.values contains information about the service's dependencies
// info.warnings contains any validation errors for the dependencies

database.enableServiceDevelopmentMode

async database.enableServiceDevelopmentMode(mount): Object

Enables development mode for the given service.

Arguments

mount: string

The service's mount point, relative to the database.

Examples

const info = await db.enableServiceDevelopmentMode('/my-service');
// the service is now in development mode
// info contains detailed information about the service

database.disableServiceDevelopmentMode

async database.disableServiceDevelopmentMode(mount): Object

Disabled development mode for the given service and commits the service state to the database.

Arguments

mount: string

The service's mount point, relative to the database.

Examples

const info = await db.disableServiceDevelopmentMode('/my-service');
// the service is now in production mode
// info contains detailed information about the service

database.listServiceScripts

async database.listServiceScripts(mount): Object

Retrieves a list of the service's scripts.

Returns an object mapping each name to a more readable representation.

Arguments

mount: string

The service's mount point, relative to the database.

Examples

const scripts = await db.listServiceScripts('/my-service');
// scripts is an object listing the service scripts

database.runServiceScript

async database.runServiceScript(mount, name, [scriptArg]): any

Runs a service script and returns the result.

Arguments

mount: string

The service's mount point, relative to the database.
name: string

Name of the script to execute.
scriptArg: any

Value that will be passed as an argument to the script.

Examples

const result = await db.runServiceScript('/my-service', 'setup');
// result contains the script's exports (if any)

database.runServiceTests

async database.runServiceTests(mount, [reporter]): any

Runs the tests of a given service and returns a formatted report.

Arguments

mount: string

The service's mount point, relative to the database
options: Object (optional)

An object with any of the following properties:
- reporter: string (Default: default)
  
  The reporter to use to process the test results.
  
  As of ArangoDB 3.2 the following reporters are supported:
  - stream: an array of event objects
  - suite: nested suite objects with test results
  - xunit: JSONML representation of an XUnit report
  - tap: an array of TAP event strings
  - default: an array of test results
- idiomatic: boolean (Default: false)
  
  Whether the results should be converted to the apropriate string representation:
  - xunit reports will be formatted as XML documents
  - tap reports will be formatted as TAP streams
  - stream reports will be formatted as JSON-LD streams

Examples

const opts = {reporter: 'xunit', idiomatic: true};
const result = await db.runServiceTests('/my-service', opts);
// result contains the XUnit report as a string

database.downloadService

async database.downloadService(mount): Buffer | Blob

Retrieves a zip bundle containing the service files.

Returns a Buffer in Node or Blob in the browser version.

Arguments

mount: string

The service's mount point, relative to the database.

Examples

const bundle = await db.downloadService('/my-service');
// bundle is a Buffer/Blob of the service bundle

database.getServiceReadme

async database.getServiceReadme(mount): string?

Retrieves the text content of the service's README or README.md file.

Returns undefined if no such file could be found.

Arguments

mount: string

The service's mount point, relative to the database.

Examples

const readme = await db.getServiceReadme('/my-service');
// readme is a string containing the service README's
// text content, or undefined if no README exists

database.getServiceDocumentation

async database.getServiceDocumentation(mount): Object

Retrieves a Swagger API description object for the service installed at the given mount point.

Arguments

mount: string

The service's mount point, relative to the database.

Examples

const spec = await db.getServiceDocumentation('/my-service');
// spec is a Swagger API description of the service

database.commitLocalServiceState

async database.commitLocalServiceState([replace]): void

Writes all locally available services to the database and updates any service bundles missing in the database.

Arguments

replace: boolean (Default: false)

Also commit outdated services.

This can be used to solve some consistency problems when service bundles are missing in the database or were deleted manually.

Examples

await db.commitLocalServiceState();
// all services available on the coordinator have been written to the db

// -- or --

await db.commitLocalServiceState(true);
// all service conflicts have been resolved in favor of this coordinator

16 KiB Raw Blame History

Managing Foxx services

database.listServices

database.installService

database.replaceService

database.upgradeService

database.uninstallService

database.getService

database.getServiceConfiguration

database.replaceServiceConfiguration

database.updateServiceConfiguration

database.getServiceDependencies

database.replaceServiceDependencies

database.updateServiceDependencies

database.enableServiceDevelopmentMode

database.disableServiceDevelopmentMode

database.listServiceScripts

database.runServiceScript

database.runServiceTests

database.downloadService

database.getServiceReadme

database.getServiceDocumentation

database.commitLocalServiceState

16 KiB

Raw Blame History