Compass.NET 1.2.0

Compass.NET

Simple HTTP request router for .NET backends

This documentation refers the v1.X of the library

How to use

This library comes with an extremely simple API set (consits of a few methods only)

1. Register the known routes

    using System.Collections.Generic;
    using System.Net;
   
    using Solti.Utils.Router;
   
    RouterBuilder routerBuilder = new
    (
    	// This handler is called on every unknown routes
    	handler: (object? state, HttpStatusCode reason) =>
    	{
    		HttpListenerContext ctx = (HttpListenerContext) state;
    		...
    	},
    	// can be omitted
    	converters: DefaultConverters.Instance
    );
    routerBuilder.AddRoute
    (
    	// A route may contain parameter(s)
    	route: "/get/picture-{id:int}",
    	handler: (IReadOnlyDictionary<string, object?> paramz, object? state) =>
    	{
    		HttpListenerContext ctx = (HttpListenerContext) state;
    		int id = (int) paramz["id"];
    		...
    	},
    	// "GET" is the default
    	"GET", "OPTIONS"
    );
   

   A valid route looks like [/]segment1/[prefix]{paramName:converter[:style]}[suffix]/segment3[/]

2. Build the router delegate and start the HTTP backend

    Router route = routerBuilder.Build();
   
    HttpListener listener = new HttpListener();
    listener.Prefixes.Add("http://localhost:8080/");
    listener.Start();
    ...
    while (Listener.IsListening)  // probably this will run in a separate thread
    {
    	HttpListenerContext context = Listener.GetContext();
    	route(context, context.Request.Url!.AbsolutePath, context.Request.HttpMethod);
    }
   

For a more comprehensive example check out the use cases fixture

Converters

Converters are used to parse variable value coming from the request path. Default converters (int, guid, str and enum) can be accessed via the DefaultConverters.Instance property.

using System.Collections.Generic;

using Solti.Utils.Router;

RouterBuilder routerBuilder = new
(
	defaultHandler: (object? state) => {...},
	converters: new Dictionary<string, ConverterFactory>(DefaultConverters.Instance)
	{
		{"mytype", (string? style) => new MyConverter(style)}
	}
);

class MyTypeConverter: IConverter 
{
    public string Id { get; }
    public string? Style { get; }
    public bool ConvertToValue(string input, out object? value) { ... }
    public bool bool ConvertToString(object? input, out string? value) { ... }
    public MyTypeConverter(string? style)
    {
        Id = $"{GetType().Name}:{style}";
        Style = style;
    }
}

Building routes from template

using System.Collections.Generic;

using Solti.Utils.Router;

RouteTemplateCompiler compile = RouteTemplate.CreateCompiler("http://localhost:8080/get/picture-{id:int}");
string route = compile(new Dictionary<string, object?> { { "id", 1986 } });  // route == "http://localhost:8080/get/picture-1986"
...

Advanced usage, async routing

In real world, request handlers often contain complex, async logic. AsyncRouterBuilder is aimed to support this use case with an API set very similar to RouterBuilder:

using System.Collections.Generic;
using System.Net;

using Solti.Utils.Router;

AsyncRouterBuilder routerBuilder = AsyncRouterBuilder.Create
(
	handler: async (object? state, HttpStatusCode reason) =>
	{
		HttpListenerContext ctx = (HttpListenerContext) state;
		await ...
	},
	// can be omitted
	converters: DefaultConverters.Instance
);
routerBuilder.AddRoute
(
	route: "/get/picture-{id:int}",
	handler: async (IReadOnlyDictionary<string, object?> paramz, object? state) =>
	{
		HttpListenerContext ctx = (HttpListenerContext) state;
		int id = (int) paramz["id"];
		await ...
	},
	// "GET" is the default
	"GET", "OPTIONS"
);
routerBuilder.AddRoute
(
	route: "/",
	// non-async callbacks also supported
	handler: (IReadOnlyDictionary<string, object?> paramz, object? state) =>
	{
		...
	}
);
AsyncRouter route = routerBuilder.Build();

...

HttpListenerContext context = Listener.GetContext();
object? result = await route(context, context.Request.Url!.AbsolutePath, context.Request.HttpMethod);

Resources

• API Docs
• Benchmark Results
• Version History

Supported frameworks

This project currently targets .NET Standard 2.0 and 2.1.