Table of Contents

How to use rule file ?

Rule file are plain yaml file that holds an alteration configuration of a fluxzy instance. It consists of a list of filters and actions that are evaluated during the traversal of the request.

Rules are optional when using the .NET lib, however it's the only way to configure the CLI without any recompiling. Also, it'a a good way to share a configuration between the CLI and Fluxzy Desktop.

What is rule file?

Here is an example of a rule file:

rules:
- filter: 
    type: HostFilter
    pattern: example.com
    operation: endsWith
  actions:
    - type: setRequestCookieAction
      name: my-session-cookie
      value: my-session-value
- filter: 
    type: PostFilter
  actions:
    - type: AddResponseHeaderAction
      headerName: X-Proxy
      headerValue: Passed through fluxzy
    - type: ForceHTTP11Action

The root element rules must be unique within the file and contains a list of one filter and multiple actions.

In this example, there are two distinct rules:

  • The first rule, triggered when the Host the domain or the subdomain of example.com, will add a cookie to the request.
  • The second rule, triggered when the HTTP method is POST, will add a response header and force the HTTP version to 1.1. You have probably noted that inside a rule, there can be multiple actions for one filter. To enable multiple filtering, a special filter named FilterCollection can combine multiple filter with a merging operation (OR or AND). Children filters of this collection can also be another collection.

When the scope of two or more rules overlap, the order of evaluation will be the order of appearance in the file.

Finaly filter names and actions are case insensitive and suffix Filter and Action can be omitted.

Using a rule file with the CLI

The option -r or --rule-file can be used to specify a rule file to the CLI.

fluxzy start --rule-file my-rule-file.yaml

Using a rule file with .NET

AddAlterationRules() can take as argument a string that contains the content of a rule file.

using System.Net;
using Fluxzy;

var ruleContent = File.ReadAllText("rule.yaml");

var fluxzyStartupSetting = FluxzySetting
    .CreateDefault(IPAddress.Loopback, 44344)
    .AddAlterationRules(ruleContent);

await using var proxy = new Proxy(fluxzyStartupSetting);

_ = proxy.Run();

Console.WriteLine("Press any key to exit");
Console.ReadKey();

Limitation

Most builtin actions and filters