# 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

```sh
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)

```ts
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)

```tsx
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:

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

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

Tasks can express dependencies:

```ts
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:

```ts
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:

```tsx
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.

```ts
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:

```ts
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:

```ts
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.

```ts
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

1. Install [Bazel](https://docs.bazel.build/versions/4.0.0/install.html)

2. Run the main entrypoint

```sh
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
```

### Debugging gRPC

Set the variables `GRPC_TRACE=all` and `GRPC_VERBOSITY=DEBUG`.