Iret NPM | npm.io

Action Runner

Action Runner is a task runner that allows to resume tasks, and continue the execution with custom flows.

The key features are:

Custom UI components to drive the execution of a task: Think of the command line tools you currently use as the backend to these UI components.
Gain control back: Quickly iterate over code changes by initializing the specific tasks you are interested on. Thus, save time and money.
Get deeper insights: Track metrics over time. All logs are automatically indexed, and available for quick search.
Anywhere: Initialize tasks locally, in the cloud, or in any CI/CD environment, and share them with your teammates in seconds.
Modern APIs: Use TypeScript to write your scripts, and optionally add types where necessary.

Installation

npm install iret --save

Getting Started

Say a task failed, you add an action to handle the exception.

This action yields control to the user through a user interface, which have full access to the state of the task.

tasks.ts (Bot-side code)

import { action, task } from 'iret/bot';

task('Task with interrupt and return handler', async () => {
  try {
    throw new Error('Something bad happened');
  } catch (error) {
    action('Show hostname', './show-hostname.tsx');
    throw error;
  }
});

show-hostname.tsx (Client-side code)

import React, { useState } from 'react';
import { exec, logger, resumeTask } from 'iret/client';

export default function() {
  const [currHostname, setCurrHostname] = useState<string>('unknown');
  return (
    <div>The hostname is: {currHostname}.</div>
    <button onClick={
      resumeTask(async () => {
        const result = await exec('hostname');
        logger.info('Log sent from the client');
        setCurrHostname(result.stdout);
      })
    }>Get again</button>
  );
}

The above example runs a task named Task with interrupt and return handler.

The action Show hostname displays the hostname of the bot that ran the task.

Once the button "Get again" is clicked, the task is resumed, the hostname command runs in the CI bot, and the UI is updated instantly.

Task Definition

A task is defined by calling the function task(name, callback, options?), for example:

import { task, logger } from 'iret/bot';

task('First task', async () => {
  logger.info('Hello world!');
});

Tasks can express dependencies:

import { task, logger } from 'iret/bot';

const firstTask = task('First task', async () => {
  logger.info('Hello world 1!');
});

task('Second task', async () => {
  logger.info('Hello world 2!');
}, {
  dependsOn: [ firstTask ],
});

In the above example, Second task runs after First task.

By default, tasks run in parallel when possible, but setting dependencies changes the order in which the tasks are executed.

Steps

Within a task, the step function can be used to indicate the current step of the task. This allows to provide context into what the output that is generated by the code. That is, attachments, logs, etc...

For example, here's a task that runs itself for ever after installing the dependencies, and waiting for 1 second:

import { task, step, sleep } from 'iret/bot';

task('Build app', async () => {
  step('Install dependencies');
  await exec('npm', ['install']);

  step('Wait for 1s');
  await sleep(1000);

  step('Run tasks');
  await exec('npm', ['run', 'tasks']);
});

Input and Output

In many cases, it's useful to have a task depend on the dynamic output of another task. For example, one task may produce a file, that another task takes as an input to produce a report.

As a result, a task can use dependsOnInput to make the output of another task its input.

You use type generics to specify the desired input and output of task. For example:

import { task, logger, AttachedFile } from 'iret/bot';

const producer = task<void, AttachedFile>('Produce foo.txt', async () => {
  await exec('touch', ['foo.txt']);
  return attachFile('foo.txt');
});

task<AttachedFile>('Consumes file', async (file?: AttachedFile) => {
  if (file) {
    const content = await file.read();
    logger.info(`Got file ${file.name} and the content is ${content}`);
  }
}, {
 dependsOnInput: [ producer ],
});

The above example sends Got value foo to the logger.

Groups

It can be handy to have some tasks defined under a group. Groups make it easier to retry all the tasks or nested groups.

import { group, task, exec } from 'iret/bot';

group('Build app', () => {
  task('Build with webpack', async () => {
    await exec('webpack', [], { cwd: 'app' });
  });
});

Streams

Insta provides a powerful stream API that allows to stream logs, images, video or binaries of any kind.

Streams can originate from multiple sources. For example, reading a file from disk, fetching a file from the network, or a byte buffer.

By default, streams have a media type equivalent to text/plain, and it's used for logs, but it can be changed by setting the option mediatype.

You can use Async generators to write to the stream:

task('Task with custom stream', async () => {
  await stream('Custom stream').
    generate(async function* () {
      yield 'Message 1';
      await sleep(1000);
      yield 'Message 2';
    },
  );
});

exec also allows to specify a custom stream to write the stdout and stderr. For example:

task('ls -la with custom stream', async () => {
  exec('ls', '-la', { stream: stream('Custom stream') });
});

Sharing Tasks

You can create higher order functions that take some configuration, and export a task.

import { task, logger } from 'iret/bot';

// Shared library
function CustomTask(name: string, config?: { message?: string }) {
  return task(name, async () => {
    logger.info(config?.message);
  });
}

// User code
CustomTask('First task', {
  message: 'Hello world',
});

Configuring Tasks

Tasks shall be defined statically. That is, no task should be configured based on values defined at runtime.

This ensures that the task DAG is deterministic, and reproducible.

Development

Install Bazel
Run the main entrypoint

INSTA_REPOSITORY='<repository>' \
INSTA_REPOSITORY_ACCESS_TOKEN='<access-token>' \
INSTA_REPOSITORY_BRANCH='<repository-branch>' \
INSTA_COMMIT_ID=1 \
INSTA_PROJECT_ID=1 \
INSTA_RUNNER_ADDRESS=':7000' \
bazel run --run_under="cd $PWD && " //:bin