wiki:DevelopmentPlan-DataApi

Data Model

The data api enforces a strong and well-defined model on Buildbot's data. This model is influenced by REST, in the sense that it defines resources, representations for resources, and identifiers for resources.

For each resource type, the api specifies

  • the attributes of the resource and their types (e.g., changes have a string specifying their project)
  • the format of links to other resources (e.g., buildsets to sourcestamp sets)
  • the events that can occur on that resource (e.g., a buildrequest can be claimed)

Components

The interfaces for all components but the update component are intended to be language-agnostic. That is, they should be callable from JavaScript? via HTTP, or via some other interface added to Buildbot after the fact.

Getter Component

The getter component can get either a single resource, or a list of resources. Getting a single resource requires a resource identifier (a tuple of strings) and a set of options to support automatic expansion of links to other resources (thus saving round-trips). Lists are requested with a partial resource identifier (a tuple of strings) and an optional set of filter options. In some cases, certain filters are implicit in the path, e.g., the list of buildsteps for a particular build.

Message Component

Message subscriptions can be made to anything that can be listed or gotten from the getter component, using the same resource identifiers. Options and explicit filters are not supported - a message contains only the most basic information about a resource, and a list subscription results in a message for every new resource of the desired type. Implicit filters are supported.

Control Component

The control component defines a set of actions that cause Buildbot to behave in a certain way, e.g., rebuilding a build or shutting down a worker. Actions correspond to a particular resource, although sometimes that resource is the root resource (an empty tuple).

Update Component

The update component defines a free-form set of methods that Buildbot's process implementation calls to update data. Most update methods both modify state via the db api and send a message via the mq api. Some are simple wrappers for these APIs, while others contain more complex logic, e.g., building a source stamp set for a collection of changes. This component is the proper place to put common functionality required by disparate Buildbot components e.g., rebuilding builds.

Concrete Interface

The root of the data api is available at self.master.data. The first three components are implemented with the following methods:

  • get -- get a resource
  • startConsuming -- subscribe to a resource or list, optionally getting its current state
  • control -- perform an action on a resource

The update component is available at self.master.data.update, and contains a number of ad-hoc methods needed by the process modules.

Last modified 20 months ago Last modified on Jan 4, 2017, 1:59:36 AM