New Commands Guide

Defining new GD2 Gluster commands

This is a guide to help developers define new GD2 commands and get ready for implementation. The guide will be updated with implementation details later.

Overview of a Gluster command

A Gluster command involves 3 main parts,

1. API
2. Handler
3. CLI

To define a new command, a developer needs to implement all the 3 parts.

API

GD2 uses a HTTP/ReST based API as its external interface. Each Gluster command has one or more APIs defined for it. A single API consists of,

• HTTP endpoint
• Request and response objects

Handler

Each API has a handler function that gets called when a request is recieved. This function performs all the actions needed to satisfy the request. The handler also defines and executes a GD2 transaction if required.

CLI

A Gluster command has a related CLI. A CLI consists of,

• Syntax
• Command handler
• API Client

Defining the API

GD2 has a HTTP based (psuedo?) ReST API. Every command supported by GD2 needs to define its API. Defining an API involves specifying the HTTP endpoint and the request response objects.

Endpoint

The endpoint is a combination of a HTTP path and a HTTP method.

The HTTP path needs to follow a object based hierarchy. For eg., a the path for a volume info command is /volumes/{volname}. The HTTP method needs to be set based on what action the command is performing. Right now we use,

• GET when a command needs to just read some information
• POST when a command needs to modify some information in the cluster
• DELETE when a command needs to delete something in the cluster

Request & Response objects

GD2 uses JSON documents for encoding the request arguments and returned responses of APIs. The developer needs to define the JSON document structure of the request and response objects. Once the document structure is defined, the respective Go structs can be defined.

Not all commands have the need to define both the request and response objects. In some cases, the all required information about a request can be provided just by the defined endpoint, and all information about the response can be provided by the returned HTTP status code.

Handler

Each defined endpoint needs to have an associated handler function. The handler function,

• Decodes the request object for the endpoint if needed
• Performs any required actions, including performing cluster wide transactions
• Returns a response status code and object if needed.

Transactions

GD2 has a transaction framework that allows handlers to perform cluster wide operations. To make use of the transaction framework, a handler defines a 'Transaction' and hands it over to the the transaction framework for execution.

In simple terms, a GD2 transaction is series of steps. A step is a combination of a function, an undo function and a list of nodes on which the step needs to be executed. An undo function is required if the step function does any changes (create/modify/delete), and needs to undo the change that was done. Each step must provide the list of nodes it should be executed.

The transaction framework provides a transaction context that is available to all step functions (and undo functions) across the cluster. Steps can use this context to store and pass along information between steps. The transaction context is also available to the handler function before and after the transaction is executed.

The transaction framework also provides a locking mechanism, to protect objects from changes when a transaction is active. If a transaction modifies and object, it needs obtain a lock before doing any modifications and release the lock after everything is done. There is a helper function to generate lock/unlock steps.

Transaction steps can modify the central store. Normally, a step modifying the store should be run on just one node. A step modiying the store can run on more than one node, only if node specific information is being modified.

Responses

A handler needs to send a response back to requester. A response consists of a HTTP status code, and if required a response JSON object. Some common status codes used in GD2 are,

• StatusOK - General success code
• StatusCreated - For POST requests that succesfully create an object
• StatusNoContent - For succesful DELETE requests
• StatusBadRequest - When request cannot be decoded
• StatusNotFound - When requested object doesn't exist
• StatusInternalServerError - When some error occurs

CLI

Defining a CLI involves defining the syntax for the command, a command handler and an API client.

Syntax

Each GD2 command needs to define its CLI syntax. The syntax generally follows the existing gluster command structure, with some optional arguments being made flags instead of being positional arguments. For eg., lots of commands have a force options that used to be specified as a positional argument. But now, it will be a flag --force.

Also, in particular with the --force flag, GD2 encourages having multiple individual flags to force individual operations instead of a single flag. For eg., volume create could have individual force flags to bypass replica set check, brick check etc.

Command handler

The command handler parses the provided CLI arguments and ensures it conforms to the syntax. It then creates a request and passes it on the API client. It then formats and outputs the information returned from the API client.

API client

Every GD2 CLI command needs to add a client function into the GD2 rest client package, instead of directly doing it in the CLI. This to allow reuse of the client package for writing functional end-to-end tests and from external programs that want to communicate with GD2.

Others

Testing

GD2 has a end-to-end testing framework. Developers are encouraged to also define functional end-to-end test cases for the commands they define.