The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
REST-Buildbot-0.02
River stage zero No dependents
++
/ REST::Buildbot

NAME

REST::Buildbot - Interface to the Buildbot v2 REST API

VERSION

Version 0.02

SYNOPSIS

This is an interface to the REST API provided by Buildbot instances. Most object types can be fetched by name or id, and most object types can be used to look up associated objects. The individual objects have no methods, but do have accessors for all of the data returned by the REST API. Most attributes are pure perl data types, the only exception is BuildSets and Changes, both of which have an attribute that contains a REST::BuildBot::SourceStamp or an arrayref of them.

    use REST::Buildbot;

    my $bb = REST::Buildbot->new(url => 'http://localhost:8010/api/v2/');

    # Get the 'linux' builder's first build
    my $linux_builder = $bb->get_builder_by_name('linux');
    my $build = $bb->get_build_by_builder_and_number($linux_builder, 1);

    # Learn about this build
    my $buildrequest = $bb->get_buildrequest_by_id($build->buildrequestid);
    my $buildset = $bb->get_buildset_by_id($buildrequest->buildsetid);
    my $sourcestamp = $buildset->sourcestamps->[0];
    # Branch, revision ID, and commit message are in the SourceStamp object

    # Look up all the builds with a certain revision
    my $rev = '0123456789abcdef...';
    my $buildsets = $bb->get_buildsets_by_revision($rev);
    # There may be several, choose in your own way
    my $buildset = $buildsets->[0];
    # Find all the builds on this buildset, and explore some information
    my $buildrequests = $bb->get_buildrequests_by_buildset($bsid);
    foreach my $buildrequest (@$buildrequests) {
        my $brid = $buildrequest->buildrequestid;
        my $builds = $bb->get_builds_by_buildrequest($brid);
        # Again, choose one build. Usually most recent, older ones may
        # be cancels or retries
        my $build = $builds->[0];
        my $steps = $bb->get_steps_by_build($build->buildid);
        # The last step is make test for me
        my $make_test = $steps->[-1];
        my $logs = $bb->get_logs_by_step($make_test->stepid);
        # Choose which log to use - probably by looping and
        # comparing against name
        my $log;
        foreach my $l (@$logs) {
            if ($l->name =~ /stdio/) {
                $log = $l;
                last;
            }
        }
        die "No stdio log" unless $log;
        my $stdio_text = $bb->get_log_text($log->logid);
    }

AVAILABLE METHODS

The following subtypes are available: Build, Builder, BuildRequest, BuildSet, Change, Log, SourceStamp, Step. Of these, all 8 have an ID which they can be looked up by, for example, get_build_by_id, or they can all be looked up at once by, for example, get_builds.

Additionally, Builders can be looked up by name, Changes can be looked up by revision. These methods use names like get_builder_by_name.

Builds can also be looked up using the build "number" (which is unique by builder, but not globally unique - it is distinct from the build id). This method requires the Builder object and the build number, and is called get_build_by_builder_and_number.

The objects themselves have a number of interrelationships. Most of these are one-to-many, even though some of them are one-to-one under most normal cases. For example, buildset to buildrequest is expected to be one-to-many (if one scheduler triggers more than one builder), but usually each buildrequest has only one build. There may be multiple builds per buildrequest if one of the builds was cancelled manually or due to a client restart. Here is a full list of valid relationships:

Builder to Build =item Builder to BuildRequest =item BuildSet to BuildRequest =item BuildRequest to Build =item Build to Step =item Step to Log

Each of the above is a one-to-many relationship. For example, get_builds_by_builder returns an arrayref of Builds, but get_builder_by_build returns a single Builder.

Additionally, a Change is one-to-one with a SourceStamp, and a BuildSet is one-to-many with SourceStamps. Generally, you will not use this relationship, instead using a helper function like get_buildsets_by_revision or get_changes_by_revision if you have a source control revision, or the ->sourcestamp->* properties of a Change, or the ->sourcestamps->[$i]->* properties of a BuildSet, to get a source control revision.

Finally, it is possible to get the text of a log object using get_log_text.

ERROR HANDLING

On error, REST::Buildbot methods will return undef and set an error string, which can be accessed by ->errorstr. An error is defined as an LWP::UserAgent error, a lookup by an ID that does not exist, or calling a method with insufficient or incorrect arguments.

If no items are found for a query, REST::Buildbot will return undef, for methods returning a single object, or an empty array ref, for methods potentially returning multiple objects.

CACHING

REST::Buildbot may cache the results of common calls, such as the list of all builders. In general, you should assume that data is no more recent than the first call made against a REST::Buildbot object. If you wish to ensure that cached data is not being used, for example, if you are using REST::Buildbot within an application that runs as a daemon, you should create a new REST::Buildbot object.

METHODS

new

Constructor. Takes one mandatory argument, the URL to the API of the Buildbot instance to use. Should end in /api/v2/.

    my $bb = REST::Buildbot->new(url => 'http://localhost:8010/api/v2/');

get_*

This set of methods allows lookup of all objects of a given type that the buildbot instance has. It returns a reference to an array of those objects. If there are none, it returns an empty array.

get_builds =item get_builders =item get_buildrequests =item get_buildsets =item get_changes =item get_logs =item get_sourcestamps =item get_steps

get_*_by_id

This set of methods allows looking up an item by its unique id. Looking up an item that does not exist is an error, and is currently handled by dying. In the future, this behavior may change, likely by having these methods return undef.

get_build_by_id =item get_builder_by_id =item get_buildrequest_by_id =item get_buildset_by_id =item get_change_by_id =item get_log_by_id =item get_sourcestamp_by_id =item get_step_by_id

get_*_by_*

This is the set of methods that employs the relationships between data types. In all cases, they take a single argument: an object of the type to be searched by.

The following items return a reference to an array containing any number of the target type:

get_buildrequests_by_builder =item get_buildrequests_by_buildset =item get_builds_by_builder =item get_builds_by_buildrequest =item get_steps_by_build =item get_logs_by_step =item get_sourcestamps_by_buildset

The following items return an object of the target type, or undef on failure.

get_builder_by_buildrequest =item get_buildset_by_buildrequest =item get_builder_by_build =item get_buildrequest_by_build =item get_build_by_step =item get_step_by_log =item get_sourcestamp_by_change

get_builder_by_name

Looks up a builder by name. Returns a REST::Buildbot::Builder object. Returns undef if there is not exactly one builder with a matching name.

get_changes_by_revision

Looks up changes by a revision string. Returns a reference to an array of REST::Buildbot::Change objects. If there are no results, the reference will be to an empty array.

get_buildsets_by_revision

Looks up buildsets by a revision string. Returns a reference to an array of REST::Buildbot::BuildSet objects. If there are no results, the reference will be to an empty array.

get_build_by_builder_and_number

Looks up a build using the Builder object and the build number. Returns a REST::Buildbot::Build object. Returns undef if there is no match.

get_log_text

Returns the contents of a log as a string. Returns undef on failure.

AUTHOR

Dan Collins, <DCOLLINS at cpan.org>

BUGS

Please report any bugs or feature requests to bug-rest-buildbot at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=REST-Buildbot. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc REST::Buildbot

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2016 Dan Collins.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.