Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see https://docs.buildbot.net/current/.

3.10.13. Protocols

To exchange information over the network between master and worker, we need to use a protocol.

buildbot.worker.protocols.base provide interfaces to implement wrappers around protocol specific calls, so other classes which use them do not need to know about protocol calls or handle protocol specific exceptions.

class buildbot.worker.protocols.base.Listener(master)
Parameters:

master – buildbot.master.BuildMaster instance

Responsible for spawning Connection instances and updating registrations. Protocol-specific subclasses are instantiated with protocol-specific parameters by the buildmaster during startup.

class buildbot.worker.protocols.base.Connection(master, worker)

Represents connection to single worker.

proxies

Dictionary containing mapping between Impl classes and Proxy class for this protocol. This may be overridden by a subclass to declare its proxy implementations.

createArgsProxies(args)
Returns:

shallow copy of args dictionary with proxies instead of impls

Helper method that will use proxies, and replace Impl objects by specific Proxy counterpart.

notifyOnDisconnect(cb)
Parameters:

cb – callback

Returns:

buildbot.util.subscriptions.Subscription

Register a callback to be called if a worker gets disconnected.

loseConnection()

Close connection.

remotePrint(message)
Parameters:

message (string) – message for worker

Returns:

Deferred

Print message to worker log file.

remoteGetWorkerInfo()
Returns:

Deferred

Get worker information, commands and version, put them in dictionary, and then return back.

remoteSetBuilderList(builders)
Parameters:

builders (List) – list with wanted builders

Returns:

Deferred containing PB references XXX

Take a list with wanted builders, send them to the worker, and return the list with created builders.

remoteStartCommand(remoteCommand, builderName, commandId, commandName, args)
Parameters:

  • remoteCommand – RemoteCommandImpl instance

  • builderName (string) – self explanatory

  • commandId (string) – command number

  • commandName (string) – command which will be executed on worker

  • args (List) – arguments for that command

Returns:

Deferred

Start command on the worker.

remoteShutdown()
Returns:

Deferred

Shutdown the worker, causing its process to halt permanently.

remoteStartBuild(builderName)
Parameters:

builderName – name of the builder for which the build is starting

Returns:

Deferred

Start a build.

remoteInterruptCommand(builderName, commandId, why)
Parameters:

  • builderName (string) – self explanatory

  • commandId (string) – command number

  • why (string) – reason to interrupt

Returns:

Deferred

Interrupt the command executed on builderName with given commandId on worker, and print reason “why” to worker logs.

The following classes describe the worker -> master part of the protocol.

In order to support old workers, we must make sure we do not change the current pb protocol. This is why we implement a Impl vs Proxy method. All the objects that are referenced from the workers for remote calls have an Impl and a Proxy base class in this module.

Impl classes are subclassed by Buildbot master, and implement the actual logic for the protocol API. Proxy classes are implemented by the worker/master protocols, and implement the demux and de-serialization of protocol calls.

On worker sides, those proxy objects are replaced by a proxy object having a single method to call master side methods:

class buildbot.worker.protocols.base.workerProxyObject
callRemote(message, *args, **kw)

Calls the method "remote_" + message on master side

class buildbot.worker.protocols.base.RemoteCommandImpl

Represents a RemoteCommand status controller.

remote_update(updates)
Parameters:

updates – dictionary of updates

Called when the workers have updates to the current remote command.

Possible keys for updates are:

  • stdout: Some logs where captured in remote command’s stdout. value: <data> as string

  • stderr: Some logs where captured in remote command’s stderr. value: <data> as string

  • header: Remote command’s header text. value: <data> as  string

  • log: One of the watched logs has received some text. value: (<logname> as string, <data> as string)

  • rc: Remote command exited with a return code. value: <rc> as integer

  • elapsed: Remote command has taken <elapsed> time. value: <elapsed seconds> as float

  • stat: Sent by the stat command with the result of the os.stat, converted to a tuple. value: <stat> as tuple

  • files: Sent by the glob command with the result of the glob.glob. value: <files> as list of string

  • got_revision: Sent by the source commands with the revision checked out. value: <revision> as string

  • repo_downloaded: sent by the repo command with the list of patches downloaded by repo. value: <downloads> as list of string

class buildbot.worker.protocols.base.FileWriterImpl

Class used to implement data transfer between worker and master.

class buildbot.worker.protocols.base.FileReaderImpl(object)
remote_read(maxLength)
Parameters:

maxLength – maximum length of the data to send

Returns:

data read

Called when worker needs more data.

remote_close()

Called when master should close the file.