Introduce ~appFolder token to simplify referencing proxy installation folder

[waldekmastykarz]

When specifying file path you could choose to pass either an absolute path, relative to the current working folder, or ~AppFolder which is the default that we'd ship to avoid broken default behavior. Since it's a config setting you can choose how you want the Developer Proxy to work.

Right now we support only the relative path. Absolute and ~AppFolder would be enhancements for future releases.

Originally posted by @waldekmastykarz in #128 (comment)

[waldekmastykarz]

Here's how we resolve relative paths at the moment:

path specified in	relative to
-c, --config-file	working directory
pluginPath in config file	proxy executable location
mocksFile in MockResponsePlugin config	working directory
responseBody @-token for binary response in MockResponsePlugin	working directory
errorsFile in GenericRandomErrorPlugin	working directory
body @-token for binary response in GenericRandomErrorPlugin	working directory

This combination of working directory- and proxy executable location-based references leads to some quirks when working with proxy.

Problem 1: Relative to what?

The first challenge that we've got is that relative paths are implicit and it's unclear what they are relative to. Consider the following relationship:

(configFile) appsettings.json > (pluginPath) mock plugin path > (mockFile) mock-responses.json > (responseBody) binary-response.zip

Path to config file is relative to current working dir. Relative paths to plugins in appsettings.json are resolved relative to proxy's executable. In the plugin config (still in appsettings.json!), relative paths to the config file (such as mock responses) are resolve relative to working dir. Inside the config file, when we point to binary responses, we are still relative to working dir while you might have impression that you're relative to the config file.

On the outside, it's not obvious what the different paths are relative to which leads to confusion.

Problem 2: Configurable vs. hard-coded relative paths are relative to the working dir

The second problem is that we've got a combination of relative paths that can be passed via args and that are hard-coded in presets where both point to the current working dir. In order to use these presets I need to ensure that I'm starting the proxy from the correct working dir as setup in the different preset files.

Consider the following tree:

I've got a project stored in c:\projects\contoso-app. I've got a proxy preset stored in c:\projects\contoso-app\mgdp-contoso-app.json. The preset points to mock responses stored in c:\projects\contoso-app\mgdp. The mgdp-contoso-app.json preset refers to assets in the mgdp using a relative path so that everyone on the team can run the preset no matter to which path on their machine they have the project cloned.

Everything works fine as long as I run proxy from the workspace dir: c:\projects\contoso-app. But if change my working dir to c:\project\contoso-app\feature1 pointing to the preset file using a relative path: mgdp --config-file ..\mgdp-contoso-app.json proxy will fail to find mock assets because it will look for them in c:\project\contoso-app\feature1\mgdp rather than c:\projects\contoso-app\mgdp, because the relative paths are resolved relative to the current working dir rather than the location of the preset file.

Solutions

Solution 1: Relative paths are relative to their reference source

One way to solve this problem is to make all relative paths relative to the source of the reference:

path specified in	relative to
-c, --config-file (command line)	working directory
pluginPath in config file	config file
mocksFile in MockResponsePlugin config	config file
responseBody @-token for binary response in MockResponsePlugin	mocks file
errorsFile in GenericRandomErrorPlugin	config file
body @-token for binary response in GenericRandomErrorPlugin	mocks file

While it helps us avoid the problem with the working dir, it complicates the setup, because plugins are now relative to the config file. If you have a project-specific config file, you'd either have to copy plugins along with the project or use absolute paths to the proxy installation folder.

Solution 2: Relative paths are relative to their reference source. Plugins remain relative to the proxy executable

One way to solve this problem is to make all relative paths relative to the source of the reference:

path specified in	relative to
-c, --config-file (command line)	working directory
pluginPath in config file	proxy executable location
mocksFile in MockResponsePlugin config	config file
responseBody @-token for binary response in MockResponsePlugin	mocks file
errorsFile in GenericRandomErrorPlugin	config file
body @-token for binary response in GenericRandomErrorPlugin	mocks file

By keeping pluginPath relative to the proxy executable folder, we solve the issue with project-specific presets. The only challenge is, if we wanted to have a project-specific plugin for proxy.

Solution 3: Relative paths are relative to their reference source. ~appFolder token to refer to the proxy executable location

One way to solve this problem is to make all relative paths relative to the source of the reference:

path specified in	relative to
-c, --config-file (command line)	working directory
pluginPath in config file	config file
mocksFile in MockResponsePlugin config	config file
responseBody @-token for binary response in MockResponsePlugin	mocks file
errorsFile in GenericRandomErrorPlugin	config file
body @-token for binary response in GenericRandomErrorPlugin	mocks file

By default, relative paths in pluginPath are relative to the config file. To use the default plugins that we ship with proxy, we'd refer to them using a special token ~appFolder that would be resolved to the proxy executable location. That way we support both project-specific and default plugins.

Having the ~appFolder token would also allow us to ship multiple turn-key presets with the proxy and let customers easily refer to them from any working directory, like mgdp --config-file ~appFolder\presets\rate-limiting.json

[waldekmastykarz]

If we decide to use the token, let's double check if it's ok to use ~appFolder or if ~ would end up being parsed as a special location and lead to issues, and if it wouldn't be easier to use @appFolder instead.

[garrytrinder]

Great summary @waldekmastykarz 👏

I like your suggestion about using a specific token. It makes sense and is clear.

I wonder if calling it appFolder might be confusing though. As it refers to the install location of the proxy exe and not the app your are testing, it might be clearer to call it something like mgdpFolder instead.

[gavinbarron]

Great summary!

I'm torn between options 2 and 3, but leaning towards option 2.
This is because I'm not sure that I see the use-case for having plugins loaded from a location other than relative to the executable itself.

[waldekmastykarz]

@gavinbarron what about loading standard presets from the install folder? Without ~appFolder it would realistically require specifying absolute path as in 2) config path is relative to working dir.

[gavinbarron]

@waldekmastykarz oh... storing a bunch of custom presets alongside the executable in the install folder and keeping the plugin dlls in separate folders so that a preset could be shipped as a self contained zipped directory with all the dlls and config required in them, so all the user need do is unzip into the install dir and reference that config.

Ok, yeah, I'm sold on 3 now. Thanks for helping me understand that scenario better.

[waldekmastykarz]

And thank you for the critical thoughts and questions @gavinbarron so that we're sure that we won't miss anything.