~~~{#broker-allow-nothing.yaml .file .yaml}

db: ci-broker.db

report_dir: reports

default_adapter: mcadapterface

adapters:

  mcadapterface:

    command: ./adapter.sh

    env:

      RADICLE_NATIVE_CI: native-ci.yaml

    sensitive_env: {}

filters:

  - !Branch "this-branch-does-not-exist"

~~~

## A `refsFetched` node event

This is a node event from the node to signal that some git refs have

changed in repository.

        "name": "refs/namespaces/DUMMYNID/refs/heads/main",

## A shutdown event

## Set environment variables and run command

To avoid having to repeat environment variables to set up and use a

Radicle node for verification scenarios, we provide a script that

sets them and runs a command.

~~~{#radenv.sh .file .sh}

#!/bin/bash

set -euo pipefail

homedir="$(pwd)/homedir"

env \

	HOME="$homedir" \

	RAD_PASSPHRASE=secret \

	RAD_HOME="$homedir/.radicle" \

	RAD_SOCKET=synt.sock \

	RUST_LOG=trace \

	RADICLE_CI_BROKER_LOG=trace \

	"$@"

~~~

## Set up a node with repository

Most of our verification scenarios will need to set up a Radicle node

and a test repository there. Rather than repeat it in every scenario,

we use this helper script.

~~~{#setup-node.sh .file .sh}

#!/bin/bash

set -xeuo pipefail

mkdir -p "$HOME"

env | grep RAD

rad auth --alias brokertest

git config --global user.email radicle@example.com

git config --global user.name TestyMcTestFace

git init -b main testy

cd testy

echo "test file" > test.txt

git add .

git commit -am test

git status

git show

rad init --name testy --description test --default-branch main --private --no-confirm --no-seed

rad inspect --identity

rad id list

~~~

## Shows config as JSON

_Requirement:_ The CI broker can write out the configuration is uses

at run time as JSON.

_Justification:_ This is helpful for the node operator to verify that

they have configured the program correctly.

_Stakeholder:_ Lars

Our verification here is quite simplistic, and only checks that the

output is in the JSON format. It does not try to make sure the JSON

matches the YAML semantically.

~~~scenario

given an installed cib

given file broker.yaml

when I run cib --config broker.yaml config --output actual.json

when I run jq . actual.json

then command is successful

~~~

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

when I try to run bash radenv.sh RAD_SOCKET=synt.sock cib --config broker.yaml insert

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

given file broker.yaml

given a directory reports

when I try to run bash radenv.sh RAD_SOCKET=synt.sock cib --config broker.yaml insert

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

when I try to run bash radenv.sh RAD_SOCKET=xyzzy.sock cib --config broker.yaml insert

then stderr contains "node control socket does not exist: xyzzy.sock"

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

when I try to run env HOME=homedir cib --config not-yaml.yaml config

then stderr contains "failed to parse configuration file as YAML: not-yaml.yaml"

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

when I try to run bash radenv.sh RAD_SOCKET=synt.sock cib --config broker.yaml insert

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

when I try to run bash radenv.sh RAD_SOCKET=synt.sock cib --config broker.yaml insert

# Acceptance criteria for persistent database

The CI broker uses an SQLite database for persistent data. Many

processes may need to access or modify the database at the same time.

While SQLite is good at managing that, it needs to be used in the

right way for everything to work correctly. The acceptance criteria in

this chapter address that.

To enable the verification of these acceptance criteria, the CI broker

database allows for a "counter", as a single row in a dedicated table.

Concurrency is tested by having multiple processes update the counter

at the same time and verifying the end result is as intended and that

every value is set exactly once.

## Count in a single process

_Requirement:_ A single process can increment the test counter

correctly.

_Justification:_ If this doesn't work with a single process, it won't

work of multiple processes, either.

_Stakeholder:_ Lars.

~~~scenario

given an installed cibtool

then file count.db does not exist

when I run cibtool --db count.db counter show

then stdout is exactly "0\n"

when I run cibtool --db count.db counter count --goal 1000

when I run cibtool --db count.db counter show

then stdout is exactly "1000\n"

~~~

## Insert events into queue

_Requirement:_ Insert broker events generated from node events into

persistent event queue in the database, when allowed by the CI broker

event filter.

_Justification:_ This is fundamental for running CI when repositories

in a node change.

_Stakeholder:_ Lars.

~~~scenario

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

given an installed synthetic-events

given file trigger.json

given file shutdown.json

when I run synthetic-events synt.sock trigger.json shutdown.json --log synt.log

given file broker.yaml

when I try to run bash radenv.sh env RAD_SOCKET=synt.sock cib --config broker.yaml insert

then command is successful

when I run cibtool --db ci-broker.db event list --verbose

then stdout contains "RefChanged"

then stdout contains "oid: Oid(0000000000000000000000000000000000000000)"

then stdout contains "old: Some(Oid(0000000000000000000000000000000000000000))"

~~~

## Insert many events into queue

_Requirement:_ Insert many events that arrive quickly.

_Justification:_ We need at least some rudimentary performance testing.

_Stakeholder:_ Lars.

~~~scenario

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

given an installed synthetic-events

given file trigger.json

given file shutdown.json

when I run synthetic-events synt.sock trigger.json shutdown.json --log synt.log --repeat 1000

given file broker.yaml

when I try to run bash radenv.sh env RAD_SOCKET=synt.sock cib --config broker.yaml insert

then command is successful

when I run cibtool --db ci-broker.db event count

then stdout is exactly "1000\n"

~~~

## Don't insert events into queue when not allowed by filter

_Requirement:_ Nothing is inserted into the persistent event queue

then the CI broker's filter does not allow any events.

_Justification:_ This is fundamental for running CI when repositories

in a node change.

_Stakeholder:_ Lars.

~~~scenario

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cib

given an installed synthetic-events

given file trigger.json

given file shutdown.json

when I run synthetic-events synt.sock trigger.json shutdown.json --log synt.log

given file broker.yaml from broker-allow-nothing.yaml

when I try to run bash radenv.sh env RAD_SOCKET=synt.sock cib --config broker.yaml insert

then command is successful

when I run cibtool --db ci-broker.db event count

then stdout is exactly "0\n"

~~~

## Process queued events

_Requirement:_ It's possible to run the CI broker in a mode where it

only processes events from its persistent event queue.

_Justification:_ This is primarily useful for testing the CI broker

queuing implementation.

_Stakeholders:_ Lars.

We verify this by adding events to the queue with `cibtool`, and then

running the CI broker and verifying it terminates after processing the

events. We carefully add a shutdown event so that the CI broker shuts

down.

~~~scenario

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given file adapter.sh from dummy.sh

when I run chmod +x adapter.sh

given an installed cib

given an installed cibtool

when I run bash radenv.sh cibtool --db ci-broker.db event add --repo testy --ref main --commit HEAD

when I run cibtool --db ci-broker.db event shutdown

given file broker.yaml

when I run ls -l adapter.sh

when I run bash radenv.sh cib --config broker.yaml queued

then stderr contains "Action: run:"

then stderr contains "Action: shutdown"

when I run cibtool --db ci-broker.db event list

then stdout is exactly ""

~~~

## Count in concurrent processes

_Requirement:_ Two process can concurrently increment the test counter

correctly.

_Justification:_ This is necessary, if not necessarily sufficient, for

concurrent database use to work correctly.

_Stakeholder:_ Lars.

Due to limitations in Subplot we mange the concurrent processes using

a helper shell script,k `count.sh`, found below. It runs two

concurrent `cibtool` processes that update the same database file, and

count to a desired goal. The script then verifies that everything went

correctly.

~~~scenario

given an installed cibtool

given file count.sh

when I run bash -x count.sh 100 10

then stdout contains "OK\n"

~~~

~~~{#count.sh .file .sh}

#!/bin/bash

set -euo pipefail

run() {

	cibtool --db "$DB" counter count --goal "$goal"

}

DB=count.db

goal="$1"

reps="$2"

for x in $(seq "$reps"); do

	echo "Repetition $x"

	rm -f "$DB" ./?.out

	run >1.out 2>&1 &

	one=$!

	run >2.out 2>&1 &

	two=$!

	if ! wait "$one"; then

		echo "first run failed"

		cat 1.out

		exit 1

	fi

	if ! wait "$two"; then

		echo "second run failed"

		cat 2.out

		exit 1

	fi

	if grep ERROR ./?.out; then

		echo found ERRORs

		exit 1

	fi

	n="$(sqlite3 "$DB" 'select counter from counter_test')"

	[ "$n" == "$goal" ] || (

		echo "wrong count $n"

		exit 1

	)

	if awk '/increment to/ { print $NF }' ./?.out | sort -n | uniq -d | grep .; then

		echo "duplicate increments"

		exit 1

	fi

done

echo OK

~~~

# Acceptance criteria for event queue management

The CI builder database contains a queue of broker events. The

`cibtool` management tool can be used to examine and manipulate the

queue.

## Events can be queued and removed from queue

_Requirement:_ `cibtool` can show the queued events, can inject an

event, and remove an event.

_Justification:_ This is the minimum functionality needed to manage

the event queue.

_Stakeholder:_ Lars.

We verify that this works by adding a new broker event, and then

removing it. We randomly choose the repository id for the CI broker

itself for this test, but the id shouldn't matter, it just needs to

be of the correct form.

~~~scenario

given file radenv.sh

given file setup-node.sh

when I run bash radenv.sh bash setup-node.sh

given an installed cibtool

when I run cibtool --db x.db event list

then stdout is exactly ""

when I run bash radenv.sh cibtool --db x.db event add --repo testy --ref main --commit HEAD --base c0ffee --id-file id.txt

when I run cibtool --db x.db event show --id-file id.txt

then stdout contains "rad:"

then stdout contains "main"

then stdout contains "c0ffee"

when I run cibtool --db x.db event remove --id-file id.txt

when I run cibtool --db x.db event list

then stdout is exactly ""

~~~

## Can add shutdown event to queue

_Requirement:_ `cibtool` can add a shutdown event to the queued

events.

_Justification:_ This is needed for testing, and for the node operator

to be able to do this cleanly.

~~~scenario

given an installed cibtool

when I run cibtool --db x.db event list

then stdout is exactly ""

when I run cibtool --db x.db event shutdown --id-file id.txt

when I run cibtool --db x.db event show --id-file id.txt

then stdout contains "Shutdown"

~~~

- given: "an installed cib"

  impl:

    rust:

      function: install_cib

- given: "an installed cibtool"

  impl:

    rust:

      function: install_cibtool

fn install_cib(context: &ScenarioContext) {

    let target_path = bindir();

    assert!(target_path.join("cib").exists());

    context.with_mut(

        |context: &mut Runcmd| {

            context.prepend_to_path(target_path);

            Ok(())

        },

        false,

    )?;

}

#[step]

#[context(SubplotContext)]

#[context(Runcmd)]

fn install_cibtool(context: &ScenarioContext) {

    let target_path = bindir();

    assert!(target_path.join("cibtool").exists());

    context.with_mut(

        |context: &mut Runcmd| {

            context.prepend_to_path(target_path);

            Ok(())

        },

        false,

    )?;

}

#[step]

#[context(SubplotContext)]

#[context(Runcmd)]