Kick off examples

To understand how the library works, let's kick off with a startup example. The following shows how to append a response Header to any request traversing Fluxzy.

This sample was tested using .NET 7.0.

using Fluxzy;
using Fluxzy.Rules;
using Fluxzy.Rules.Actions;
using Fluxzy.Rules.Filters;

namespace TestFluxzyLibrary;

internal class Program
{
    private static async Task Main()
    {
        var fluxzyStartupSetting = FluxzySetting
            .CreateDefault(IPAddress.Loopback, 44344)
            .AddAlterationRules(
                new Rule(
                    new AddResponseHeaderAction("X-Proxy", "Passed through fluxzy"),
                    AnyFilter.Default
                ));

        await using (var proxy = new Proxy(fluxzyStartupSetting))
        {
            var _ = proxy.Run();

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

The FluxzySetting class holds the the startup configuration of the proxy. In the sample above, we instruct fluxzy to listen to the IPV4 loopback address on port 44344.

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

The fluent method AddAlterationRules() adds an alteration rule to the proxy, more precisely in this sample it will append a new response header (AddResponseHeaderAction) to any response traversing the proxy (AnyFilter).

To test this sample, execute the application above along with following `curl` command on the same machine.

curl -x 127.0.0.1:44344 -I -k https://example.com

This command will print the response header directly to the console. This response will contains the appended response header X-Proxy with the value Passed through fluxzy.

Let's break down the curl command to know what happens :

• -x option orders curl to use the proxy at 127.0.0.1:44344, which points to our fluxzy instance
• -I option : make curl send an HEAD method, meaning that it's requesting only reponse header with any body. Additionally, this option will make curl print the request header
• -k option : instruct curl to ignore any SSL certificate error. There are several ways to make curl trust the certificate generated by fluxzy, but this is out of the scope of this sample.

fluxzy can store capture trafic to hard drive. This is useful to inspect a trafic later or to share it with other people.

During a capture session, and in order to have a optimize disk usage performance, fluxzy will save the trafic to a temporary directory with a specific format.

At the end of the capture, you will be able to export the trafic to a Http Archive (HAR) file or to a Fluxzy Archive File (fxzy).

We recommend to use this later as it'is optimized for speed and it's the only file format who can store the full HTTP trafic along with the raw network packets.

To save the trafic, you need to specify the live capture directory by calling the fluent method SetOutDirectory() on the FluxzySetting instance.

var fluxzyStartupSetting = FluxzySetting
    .CreateDefault()
    .SetOutDirectory("my_capture_session_directory");

Then at the end of the capture session, use the Packager helper class to export the directory to a file.

// Export to a fxzy file
Packager.Export("my_capture_session_directory", "my_capture_session.fxzy");

// Export to a HAR file
Packager.ExportAsHttpArchive("my_capture_session_directory", "my_capture_session.har");

With reusing the previous example above, the following full code will save the trafic to a fxzy file.

using System.Net;
using Fluxzy;

namespace TestFluxzyLibrary;

internal class Program
{
    private static async Task Main()
    {
        var fluxzyStartupSetting = FluxzySetting
            .CreateDefault(IPAddress.Loopback, 44344)
            .SetOutDirectory("my_capture_session_directory");

        using var client = new HttpClient(new HttpClientHandler()
        {
            Proxy = new WebProxy("localhost", 44344)
        }); 

        await using (var proxy = new Proxy(fluxzyStartupSetting))
        {
            var endPoints = proxy.Run();

            Console.WriteLine($"Fluxzy is listen on the following endpoints: " +
                              $"{string.Join(" ", endPoints.Select(t => t.ToString()))}");

            await client.GetByteArrayAsync("https://example.com");
        }

        // Capture to a fxzy file 
        Packager.Export("my_capture_session_directory", "my_capture_session.fxzy");

        // Capture to a har file
        Packager.ExportAsHttpArchive("my_capture_session_directory", "my_capture_session.har");
    }
}

Rule file are a convenient way to store and share rules. The format is defined at this specific page.

AddAlterationRules extensions method (on FluxzySetting) supports immediately a plain string containing the yaml rule.

var fluxzyStartupSetting = FluxzySetting
    .CreateDefault(IPAddress.Loopback, 44344)
    .AddAlterationRules("""
        rules:
            - filter: 
                typeKind: HostFilter
                pattern: google.com
                operation: endsWith
            action : 
                # This action remove any cache directive from request and response header
                typeKind: AddBasicAuthenticationAction
                username: leeloo
                password: multipass
        """);

We instruct fluxzy to add a basic authentication header to any request to google.com