Pardon Collection Layering

Stacking layers

In pardon, we have collections which are organized by services, and the endpoints are organized within these directories. The design invites version controlled and broad sharing, but that, in turn, limits what kind of specifics can go into the collection.

For instance, where to source credentials for the same services differs across teams, and also perhaps some other defaults and patterns of use.

To support easy inter-team, intra-team, and personal (or other) patterns of use, a Pardon application context references one or more collection layers and composes them.

For example, let’s add a layer to the base service.yaml of our example service.

base

The base configuration defines production and staging endpoints, which is fine for sharing, but what about the developers of the service testing locally on their machines?

.../common/collection/example/service.yaml

config:
  origin:
    env:
      prod: https://example.com
      stage: https://stage.example.com

dev-team

We can extend the configuration with another option. Because the config structure is based on maps, there’s really only one way for this to be interpreted.

With this Now env=local will configure any call to go to http://localhost:8080.

.../dev/collection/example/service.yaml

config:
  origin:
    env:
      local: http://localhost:8080

With targetted overrides, we can define additional configurations, update defaults, and add or customize mixins.

Exercises

env=local

extend the configuration with a local env

Let’s try this out! First, we extend the our service configuration with a local environment:

/extension/example/service.yaml

config:
  origin:
    env:
      local: http://localhost:8080

Then we can configure the request for local

env=local

You can also try setting the URL to http://localhost:8080/ping instead, as always, feel free to experiment.

flexible port

allow flexibility with the port

We don’t need to choose :8080 as our port here. It’s nice that env=local works by itself, but maybe we’re running a service on 8080 and we’d like to use port=8081 one time.

As you might expect, we can do this with a default port number variable.

/extension/example/service.yaml

config:
  origin:
    env:
      local: http://localhost:{{port=8080}}

Then we can configure the request for local

env=local port=8081

Loading Pardon Playground...

Disambiguating requests

The above http://localhost:8080/ping request is unambiguous in the context of a single example service, a developer will likely be running more than one from time to time, and perhaps the rules (headers) for calling these services differs a little bit.

Pardon will happily call env=local + https://example.com/ping but will be confused by http://localhost:8080/ping without additional context.

The following exercises should help clarify this situation. Here we’ve defined another sample service that also takes the x-sample: true header for its ping endpoint.

Exercises

service=...

Disambiguate an ambiguous request.

Try changing the request to a localhost ping, observe that pardon doesn’t quite know how to handle it.

http://localhost:1337/ping

To help pardon out, specify a service value ()

service=example

service=sample

Doing this gives pardon the missing context it needs. (endpoint=example/ping also works, action=ping does not help here).

Loading Pardon Playground...

Pardon Testcases Using pardon for tests