Jenkins RxJs

Jenkins RxJs

This article is part of the Jenkins CLI series in which we describe how we built CLI application for executing a series of parallel Jenkins Jobs in a terminal

Jenkins RxJs is a small wrapper library on top of the Jenkins npm package that can be used in CLI, node, or browser environment. It encapsulates the whole process of starting a job and tracking it in a quiet, queue and build states. The consumer of the library simply executes run command with job options and receives a stream of JobResponse objects.

How it works?

This diagram describes the entire process:

And JobReponse can be expressed in the following interfaces:

type JobStatus = 'FAILURE' | 'SUCCESS' | 'PROGRESS';

type JobResponse = JobProgress | JobDone;

interface JobResponseBase {
  name: string;
  url: string;
  text: string;
  status: JobStatus;
}

interface JobProgress extends JobResponseBase {
  started: number;
  estimatedEnd: number;
  status: 'PROGRESS';
}
interface JobDone extends JobResponseBase {
  id: number;
  status: 'FAILURE' | 'SUCCESS';
}

Since Jenkins exposes no socket connection to keep track of the current state of the job Jenkins RxJs does it by executing consecutive calls to Jenkins API. It uses estimatedEnd time at first and then every 15 seconds should the original estimate be exceeded.

How to use it?

To use Jenkins RxJS first you need to install Jenkins RxJS and original Jenkins library:

npm install jenkins jenkins-rxjs

Then create a Jenkins RxJs object:

import * as createJenkins from 'jenkins';
import { JenkinsRxJs } from 'jenkins-rxjs';
const jenkinsPromisified = createJenkins({
  baseUrl: myJenkinsUrl,
  promisify: true,
});
const jenkinsRxJs = new JenkinsRxJs(jenkinsPromisified);

Finally, simply execute a job:

jenkinsRxJs.run(jobBuildOptions).subscribe(console.log);

Job Build Options are the same as the one in Jenkins npm package:

interface JobBuildOptions {
    name: string;
    parameters?: any;
    token?: string;
}

Summary

To summarise, Jenkins RxJs can be used both in web apps as well as CLI ones. With simple API it turns multistep Jenkins build process into a stream of simple JobResponse objects.

As a part of a Jenkins CLI this lib handles communication with Jenkins API. The next and the last part is about actually executing jobs and displaying their status.