The first step is to build the containers. This can be done with the docker-compose build command. Let's perform that command. (You can just click the command below to execute it.)

docker-compose build

We can then run the client by using the docker-compose run client command. When run, we will be presented with the calculator client. This command will also start up the adder and discovery service.

docker-compose run client

Let's try adding 2 and 2.

add 2 2

Uh oh. Two plus two does not equal three. Let’s use Whip to pinpoint the error. (Though, it should be no surprise, the adder has not held up its part of the bargain to perform the addition correctly.)

Let's quit the client program first.

quit

Note that the adder and discovery services are still running. To view their status, run the docker-compose ps command.

docker-compose ps

To stop them, run docker-compose down.

docker-compose down

In the next step, we will install a Whip adapter on the client.

We will start by installing an adapter on the client to catch the error.

To do this we will need a Whip contract and a Whip adapter configuration. For the tutorial, we have provided both: the contract is located in whip/calculator.whip and the configuration file for the client is located in whip/adapter_client.yaml.

Of particular interest is the client proxy string:

  - discovery:8000 mapstoservice AdderDiscovery

This states that that there is an AdderDiscovery service at the discovery host with port 8000.

In order to deploy the client with the Whip adapter with the above configuration, we need to create an adapter and use the shim library on the client. The shim command is a shell script that instructs the operating system to preload the interposition library to intercept on new network connections.

The entry point of the client application is in the run_client.sh script (take a look at it in your editor in the top right window). Inspecting the file, we can see that the adapter is already created in the first line of the script. The only remaining step is to add the shim library. We can do that by modifying the last line of the run_client.sh script from:

python src/client.py discovery 8000

to:

shim python src/client.py discovery 8000

This will successfully install the Whip adapter on the client, without any code changes to the client itself.

With the adapter installed we can bring down the application, rebuild the containers (note: not the service applications themselves), and run the client again:

docker-compose down docker-compose build docker-compose run client

Now let's add 2 and 2:

add 2 2

Success! I mean, failure! We have a contract failure, that is. We have successfully captured a first-order contract failure (i.e., that 2 + 2 is not equal to 3).

Let's quit out of the program now.

quit

Note that the service was vouched for by unknown. That is, the imprecise blame label was used. That is because the client was using unenhanced communication due to partial deployment. In the next step, we will switch the client adapter to use enhanced communication with the other services.

To use enhanced communication, we must install an adapter on all services. It turns out that the other services were already enhanced (which can be confirmed by inspecting the run_adder.sh and run_discovery.sh scripts) and we only need to make the client aware of the discovery service's adapter. We can make the client aware of the discovery Whip adapter with a simple configuration change for the client adapters.

Change the last line of whip/adapter_client.yaml file from

  - discovery:8000 mapstoservice AdderDiscovery

to:

  - discovery:8000 proxiedby discovery:38000 mapstoservice AdderDiscovery

This change tells the client that the AdderDiscovery service has a Whip adapter on port 38000. This means that the Whip client will use enhanced communication (i.e., will talk to the Whip adapter) when communicating with the AdderDiscovery service.

With this we can bring down the application, rebuild the containers (note: not the applications themselves), and run the client again:

docker-compose down docker-compose build docker-compose run client

And now when we add 2 + 2...

add 2 2

We can see now in this case the adder service was vouched for by the adder adapter (the blame label name "adder" comes from the whip/adapter_adder.yaml configuration file).

In the next step, we will discuss indexed contracts.

Finally, we show how Whip tracks indexed contracts with a special indexed contract form given in whip/calculator.indexed.whip. This indexed contract provides adder services only when the first operand (a) is exactly equal to 1. In all other cases, the adder service and discovery service do not vouch for its behavior. In other words, if the client provides an a operand to the adder that is not exactly 1 then it will vouch for the behavior of the adder service. This indexed contract provides adder services only when the first operand a is exactly equal to 1. That is, if the first operand is 1, then the adder service vouches for the behavior of the adder service (and will be blamed if the service does not meet the contract). If the first operand is not equal to 1, then the adder service and discovery service do not vouch for the behavior of the adder service. So, that means that if the client invokes the adder service with the first argument being something other than 1, then it should be the client that is blamed for any incorrect behavior rather than the adder service. (Note that this example is representative of, for example, the client using an invalid authorization token or identifier.)

In the editor in the top right, modify each Whip configuration file (adapter_adder.yaml, adapter_client.yaml, and adapter_discovery.yaml) to have the spec field be whip/calculator.indexed.whip instead of whip/calculator.whip.

Once the configuration files are modified, we can rebuild the containers and try running the client with different arguments for a:

docker-compose down docker-compose build docker-compose run client

Let's now try adding 1 and 2:

add 1 2

Note that the adder was blamed (i.e., it was vouched for by adder).

Now let's try adding 2 and 2:

add 2 2

Now note that client vouched for the service, as a was not equal to 1.

Finally, let's quit out and fix the adder service error.

quit

You can fix the broken adder by inspecting and modifying Line 18 of src/adder.py. Just change return a + b - 1 to return a + b. By bringing down the services and bringing them back (as was done above), the error will go away.

docker-compose down docker-compose build docker-compose run client

And now let's try adding 2 and 2.

add 2 2

No more error!