# 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.