Workflow

A workflow groups configurations for services to perform distinct use cases. By default, Stoobly provides configurations for four workflows: record, mock, test, and develop. Use --workflow when creating a service to select a subset instead of all four (see the Scaffold FAQ for details).

Background

To learn more about the role of individual services, see:

Service

To run a workflow, see:

How to Run a Workflow

To validate a workflow, see:

Validation

File Structure

To learn how each file is used, see here.

Any hidden file will be overritten when the scaffold service create command is rerun.

bin/init

First script that executes when a workflow runs. Should contain any commands needed for the service to initialize. Can also contain configuration commands for Stoobly. See filter rules, match rules, and rewrite rules.

bin/.init

Maintained file that will be overriden on scaffold create.

docker-compose.yml

Custom docker-compose.yml file. Container services defined in this should should include:

• Respective <WORKFLOW-NAME> under the profiles property

• Either app.egress or app.ingress under the networks property

.docker-compose.<WORKFLOW-NAME>.yml

Maintained file that will be overriden on scaffold create.

fixtures.yml

Enables defining mock responses for specific URL patterns. To learn more see here.

lifecycle_hooks.py

Enables reading and modifying requests during specific points in their lifecycle. To learn more see here.

public

Enables defining mock request paths and responses using files stored in this folder. To learn more see here.

Core Workflows

Record

Flow diagram for recording requests

The journey of a request:

1. A request gets sent from the host e.g. browser or cURL

2. Gets sent to the gateway service

3. Gateway service routes the request based on hostname

4. Request gets intercepted by Stoobly running as a proxy

   1. Lifecycle hooks get triggered

5. Stoobly reverse proxies the request to the local or external API

6. On response, Stoobly records the request to its respective .stooblyfolder

   1. Lifecycle hooks get triggered

Mock

Flow diagram for mocking requests

The journey of a request:

1. A request gets sent from the host e.g. browser or cURL

2. Gets sent to the gateway service

3. Gateway service routes the request based on hostname

4. Request gets intercepted by Stoobly running as a proxy

   1. Lifecycle hooks get triggered

5. Stoobly mocks requests if it has been previously recorded. If the request is not found, it can conditionally reverse proxy the request to the local or external API

   1. Lifecycle hooks get triggered

Test

Flow diagram for testing an application that sends requests

The journey of a request:

1. A request gets sent from the entrypoint service

2. Gateway service routes the request based on hostname

3. Request gets intercepted by Stoobly running as a proxy

   1. Lifecycle hooks get triggered

4. Stoobly mocks requests if it has been previously recorded. If the request is not found, it can conditionally reverse proxy the request to the local or external API

   1. Lifecycle hooks get triggered

Develop

Unlike record, mock, and test, the develop workflow isn't about capturing or replaying fixed responses.

It's for working against a service's real hostname (e.g. an endpoint your app already calls in staging or production) while transparently redirecting requests to a local development server.

This redirection is driven by rewrite rules generated from the service's configured upstream hostname, port, and scheme. Whenever a service's upstream configuration changes, resync its develop rewrite rules with:

stoobly-agent scaffold workflow rewrite develop

The journey of a request:

1. A request gets sent from the host e.g. browser or cURL

2. Gets sent to the gateway service

3. Gateway service routes the request based on hostname

4. Request gets intercepted by Stoobly running as a proxy

   1. Lifecycle hooks get triggered

5. Stoobly rewrites the request, redirecting it from the service's original upstream hostname, port, and scheme to the local development target defined by the synced rewrite rules

6. Stoobly reverse proxies the rewritten request to the local development server and returns its response to the host

   1. Lifecycle hooks get triggered

develop is created automatically along with record, mock, and test whenever you run scaffold service create without a --workflow filter:

# Creates record, mock, test, AND develop workflows for the service
stoobly-agent scaffold service create api

# To create only a subset, list the workflows you want explicitly
stoobly-agent scaffold service create api --workflow mock --workflow test

# Or add develop to an existing service that was scaffolded with a subset
stoobly-agent scaffold workflow create develop --template develop --service api