feat: add ncu-ci available

Check Jenkins shutdown state and PR job readiness before processing CI
requests. Report unavailable or unknown states with a nonzero exit code.

Signed-off-by: Filip Skokan <panva.ip@gmail.com>
Assisted-by: Codex

Author: panva

bin/ncu-ci.js

@@ -24,6 +24,7 @@ import {
   RunPRJob
 } from '../lib/ci/run_ci.js';
 import { ResumePRJob } from '../lib/ci/resume_ci.js';
+import { checkAvailability } from '../lib/ci/availability.js';
 import { writeJson, writeFile } from '../lib/file.js';
 import { getMergedConfig } from '../lib/config.js';
 import { runPromise } from '../lib/run.js';
@@ -54,6 +55,11 @@ const commandKeys = [
 
 const args = yargs(hideBin(process.argv))
   .completion('completion')
+  .command({
+    command: 'available',
+    desc: 'Check whether Jenkins is available for PR CI requests',
+    handler
+  })
   .command({
     command: 'rate <type>',
     desc: 'Calculate the green rate of a CI job in the last 100 runs',
@@ -598,7 +604,27 @@ class DailyCommand extends CICommand {
   }
 }
 
+async function checkJenkins() {
+  try {
+    let jenkins;
+    try {
+      const credentials = await auth({ github: false, jenkins: true });
+      jenkins = credentials.jenkins;
+    } catch {
+      throw new Error('Configure username and jenkins_token with ncu-config');
+    }
+    const request = new Request({ jenkins });
+    await checkAvailability(request);
+  } catch (err) {
+    console.error(`Unable to check Jenkins availability: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
 async function main(command, argv) {
+  if (command === 'available') {
+    return checkJenkins();
+  }
   const cli = new CLI();
   const credentials = await auth({
     github: true,

docs/ncu-ci.md

@@ -13,6 +13,7 @@ Supported jobs:
 ncu-ci <command>
 
 Commands:
+  ncu-ci available          Check whether Jenkins is available for PR CI requests
   ncu-ci rate <type>        Calculate the green rate of a CI job in the last 100
                             runs
   ncu-ci walk <type>        Walk the CI and display the failures
@@ -35,6 +36,30 @@ Options:
   --help             Show help                                         [boolean]
 ```
 
+### `ncu-ci available`
+
+`ncu-ci available` checks whether Jenkins is available for PR CI requests. It
+exits with status 0 and no output when the controller is not preparing for
+shutdown and `node-test-pull-request` is enabled and buildable. Otherwise it exits
+with status 1 and explains the reason on stderr. HTTP failures, timeouts, and
+unrecognized responses are treated as unavailable.
+
+The command only reads Jenkins state. It does not start or resume a build, check
+individual PRs, or require idle executors. Availability can change after the
+check.
+
+The command uses the configured `username` and `jenkins_token`; no GitHub token,
+repository configuration, or PR argument is required. It has a 20-second deadline
+for its Jenkins requests, including response bodies.
+
+For example, skip processing requests unless Jenkins is available:
+
+```sh
+ncu-ci available || exit 0
+
+# Process requests here.
+```
+
 ### `ncu-ci rate <type>`
 
 `ncu-ci rate <type>` calculate the success rate for CI jobs in the last 100 runs per [CI Health History](https://github.com/nodejs/reliability#ci-health-history), where `<type>` can be either `pr` for `node-test-pull-request` or `commit` for `node-test-commit`. See `ncu-ci rate --help` for more.

lib/ci/availability.js

@@ -0,0 +1,24 @@
+import { readJenkinsJSON } from './jenkins.js';
+
+export async function checkAvailability(request) {
+  const signal = AbortSignal.timeout(20_000);
+  const controller = await readJenkinsJSON(request, '/api/json?tree=quietingDown', signal);
+  if (controller?.quietingDown === true) {
+    throw new Error('Jenkins is preparing for shutdown');
+  }
+  if (controller?.quietingDown !== false) {
+    throw new Error('Jenkins quiet-down state is not confirmed');
+  }
+
+  const job = await readJenkinsJSON(request,
+    '/job/node-test-pull-request/api/json?tree=disabled,buildable', signal);
+  if (job?.disabled === true) {
+    throw new Error('Jenkins PR job is disabled');
+  }
+  if (job?.buildable === false) {
+    throw new Error('Jenkins PR job is not buildable');
+  }
+  if (job?.disabled !== false || job?.buildable !== true) {
+    throw new Error('Jenkins PR job availability is not confirmed');
+  }
+}

lib/ci/jenkins.js

@@ -0,0 +1,23 @@
+import { CI_DOMAIN } from './ci_type_parser.js';
+
+export async function readJenkinsJSON(request, path, signal) {
+  const response = await request.fetch(`https://${CI_DOMAIN}${path}`, {
+    method: 'GET',
+    headers: { Accept: 'application/json' },
+    redirect: 'error',
+    signal
+  });
+  if (response.status !== 200) {
+    await response.body?.cancel();
+    throw new Error(`Jenkins returned HTTP ${response.status} ${response.statusText ?? ''}`.trim());
+  }
+  try {
+    return await response.json();
+  } catch (cause) {
+    if (signal.aborted) throw signal.reason;
+    if (cause instanceof SyntaxError) {
+      throw new Error('Jenkins returned invalid JSON', { cause });
+    }
+    throw cause;
+  }
+}

test/unit/ci_availability.test.js

@@ -0,0 +1,156 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { checkAvailability } from '../../lib/ci/availability.js';
+
+const controllerURL = 'https://ci.nodejs.org/api/json?tree=quietingDown';
+const jobURL = 'https://ci.nodejs.org/job/node-test-pull-request/api/json?tree=disabled,buildable';
+const availableController = { quietingDown: false };
+const availableJob = { disabled: false, buildable: true };
+
+function requestFor(t, controller = availableController, job = availableJob) {
+  return {
+    fetch: t.mock.fn(async(url) => {
+      assert.ok(url === controllerURL || url === jobURL);
+      return { status: 200, json: async() => url === controllerURL ? controller : job };
+    })
+  };
+}
+
+describe('Jenkins availability', () => {
+  it('confirms controller and PR job availability with one shared deadline', async(t) => {
+    const controller = new AbortController();
+    const timeout = t.mock.method(AbortSignal, 'timeout', () => controller.signal);
+    const request = requestFor(t);
+
+    assert.equal(await checkAvailability(request), undefined);
+    assert.deepEqual(timeout.mock.calls.map(call => call.arguments), [[20_000]]);
+    assert.deepEqual(request.fetch.mock.calls.map(call => call.arguments), [
+      [controllerURL, {
+        method: 'GET', redirect: 'error',
+        headers: { Accept: 'application/json' }, signal: controller.signal
+      }],
+      [jobURL, {
+        method: 'GET', redirect: 'error',
+        headers: { Accept: 'application/json' }, signal: controller.signal
+      }]
+    ]);
+  });
+
+  it('stops before reading the job when Jenkins is quieting down', async(t) => {
+    const request = requestFor(t, { quietingDown: true });
+    await assert.rejects(checkAvailability(request), {
+      message: 'Jenkins is preparing for shutdown'
+    });
+    assert.equal(request.fetch.mock.callCount(), 1);
+  });
+
+  for (const controller of [null, {}, { quietingDown: 'false' }, { quietingDown: 0 }]) {
+    it(`rejects unknown controller state: ${JSON.stringify(controller)}`, async(t) => {
+      const request = requestFor(t, controller);
+      await assert.rejects(checkAvailability(request), {
+        message: 'Jenkins quiet-down state is not confirmed'
+      });
+      assert.equal(request.fetch.mock.callCount(), 1);
+    });
+  }
+
+  for (const job of [
+    { disabled: true, buildable: false },
+    { disabled: true, buildable: true }
+  ]) {
+    it(`rejects disabled PR job: ${JSON.stringify(job)}`, async(t) => {
+      await assert.rejects(checkAvailability(requestFor(t, availableController, job)), {
+        message: 'Jenkins PR job is disabled'
+      });
+    });
+  }
+
+  it('rejects a PR job that cannot be built', async(t) => {
+    const request = requestFor(t, availableController, { disabled: false, buildable: false });
+    await assert.rejects(checkAvailability(request), {
+      message: 'Jenkins PR job is not buildable'
+    });
+  });
+
+  for (const job of [
+    null, {}, { disabled: false }, { buildable: true },
+    { disabled: 'false', buildable: true }, { disabled: false, buildable: 'true' }
+  ]) {
+    it(`rejects unknown PR job state: ${JSON.stringify(job)}`, async(t) => {
+      await assert.rejects(checkAvailability(requestFor(t, availableController, job)), {
+        message: 'Jenkins PR job availability is not confirmed'
+      });
+    });
+  }
+
+  for (const failedURL of [controllerURL, jobURL]) {
+    it(`propagates network failures from ${failedURL}`, async(t) => {
+      const failure = new Error('Connection reset');
+      const request = requestFor(t);
+      request.fetch.mock.mockImplementation(async(url) => {
+        if (url === failedURL) throw failure;
+        return { status: 200, json: async() => availableController };
+      });
+      await assert.rejects(checkAvailability(request), error => error === failure);
+      assert.equal(request.fetch.mock.callCount(), failedURL === controllerURL ? 1 : 2);
+    });
+
+    it(`rejects malformed JSON from ${failedURL}`, async(t) => {
+      const request = requestFor(t);
+      request.fetch.mock.mockImplementation(async(url) => ({
+        status: 200,
+        json: async() => {
+          if (url === failedURL) throw new SyntaxError('Invalid JSON');
+          return availableController;
+        }
+      }));
+      await assert.rejects(checkAvailability(request), /JSON/);
+      assert.equal(request.fetch.mock.callCount(), failedURL === controllerURL ? 1 : 2);
+    });
+
+    for (const status of [302, 401, 403, 404, 503]) {
+      it(`rejects HTTP ${status} from ${failedURL}`, async(t) => {
+        const request = requestFor(t);
+        const cancel = t.mock.fn(async() => {});
+        const json = t.mock.fn(async() => availableJob);
+        request.fetch.mock.mockImplementation(async(url) => url === failedURL
+          ? { status, statusText: 'Unavailable', body: { cancel }, json }
+          : { status: 200, json: async() => availableController });
+        await assert.rejects(checkAvailability(request), new RegExp(String(status)));
+        assert.equal(request.fetch.mock.callCount(), failedURL === controllerURL ? 1 : 2);
+        assert.equal(json.mock.callCount(), 0);
+        assert.equal(cancel.mock.callCount(), 1);
+      });
+    }
+  }
+
+  it('preserves connection failures while reading a response body', async() => {
+    const failure = new Error('Connection reset while reading response');
+    const request = {
+      fetch: async() => ({ status: 200, json: async() => { throw failure; } })
+    };
+    await assert.rejects(checkAvailability(request), error => error === failure);
+  });
+
+  it('keeps the deadline active while reading the job response body', async(t) => {
+    const controller = new AbortController();
+    t.mock.method(AbortSignal, 'timeout', () => controller.signal);
+    const timeout = new DOMException('Availability check timed out', 'TimeoutError');
+    const request = requestFor(t);
+    request.fetch.mock.mockImplementation(async(url, { signal }) => ({
+      status: 200,
+      json: async() => {
+        if (url === controllerURL) return availableController;
+        const body = new Promise((resolve, reject) => {
+          signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        });
+        controller.abort(timeout);
+        return body;
+      }
+    }));
+
+    await assert.rejects(checkAvailability(request), error => error === timeout);
+    assert.equal(request.fetch.mock.callCount(), 2);
+  });
+});