Mutations

Table of Contents

• How Mutations Work
  • Asynchronous Mutations

How Mutations Work

A Mutation is a GraphQL request that is supposed to have a side effect.

The mutations are supposed to execute either a synchronous or an asynchronous XenAPI call. Synchronous calls are used if and only if asynchronous calls are impossible.

Asynchronous calls are represented using Tasks (GTask type in GraphQL). A GTask is either a XenAPI task or similarly created structure (backend/customtask/customtask.py)(This is used for creating VMs and executing Playbooks).

##Synchronous Mutations

A synchronous mutation is executed using a MutationMethod. See backend/handlers/graphql/mutation_utils/mutationmethod.py.

This mutation is known as edit mutation and used for XenAPI calls that do not have an asynchronous version. The mutation combines several synchronous XAPI call into one API call and presented in form of:

mutation {
  OBJECT_TYPE(ref: OBJECT_REF, OBJECT_TYPE: STRUCTURE)
}

Here, STRUCTURE is an input object type akin to:

input VMInput {
  "Number of VCPUs at startup"
  VCPUsAtStartup: Int
  "Maximum number of VCPUs"
  VCPUsMax: Int
  "VM domain type: 'pv', 'hvm', 'pv_in_pvh'"
  domainType: DomainType
  "A user against whom the quotes are calculated"
  mainOwner: ID
  "Dynamic memory max in bytes"
  memoryDynamicMax: Float
  "Dynamic memory min in bytes"
  memoryDynamicMin: Float
  "Static memory max in bytes"
  memoryStaticMax: Float
  "Static memory min in bytes"
  memoryStaticMin: Float
  "Object's human-readable description"
  nameDescription: String
  "Object's human-readable name"
  nameLabel: String
  "VCPU platform properties"
  platform: PlatformInput
}

Each field in the input object type corresponds with one mutation method.

A mutation method is represented by MutationMethod class that takes a tuple of a setter function and a validation function and associated access action. A set of mutation methods represents a edit mutation where each field of an input is handled by its own mutationmethod

Asynchronous Mutations

Asynchronous mutations generally call asynchronous XenAPI methods.

Such methods are supposed to be called with AsyncMutationMethod.call static method (see documentation in code - backend/handlers/graphql/mutation_utils/asyncmutationmethod.py)

An asynchronous mutation takes in a ref - object ID (see vm_suspend) and sometimes other arguments (see vm_start)

An asynchronous mutation returns the following structure:

{
  granted: Boolean. If true, access is granted and taskId is presented. If false, access is not granted, and reason is presented
  taskId: ID - task ID. Use "task" query to get info on progress
  reason: String. Human-readable error description if granted is false.
}