Dekiru.Conduit 1.0.8

Conduits

Conduits is a minimal library for creating pipelines with middlewares. The intent is to use it encapsulate buisness logic in a way that is easy to overview and test.

A pipeline consists of an implementation of the Pipeline<TInput, TOutput>, with zero or more implementations of Interceptor<TInput, TOutput>.

TInput and TOutput may be the same type, or different types. The TInput of a pipeline is the type that is passed to the Process method of the pipeline. The TOutput of a pipeline is the type that is returned by the Process method of the pipeline. Both TInput and TOutput must be reference types.

Note: TInput is considered the endpoint of a pipeline, and must be unique. Creating multiple pipelines with the same TInput is not supported, regardless of the TOutput.

Creating a pipeline

The following example demonstrates how to create a pipeline with a single interceptor.

public class MyPipeline : Pipeline<MyClass, MyClassResult>
{
	public MyPipeline()
	{
		AddInterceptor<MyInterceptor>();
	}

	public override Task<MyClassResult> Process(MyClass input, CancellationToken cancellationToken)
	{
		return Task.FromResult(input);
	}
}

Things to note:

• The AddInterceptor method is used to add an interceptor to the pipeline. The MyInterceptor class is an implementation of Interceptor<TInput, TOutput>.
• The Process method is the entry point of the pipeline. This is where the input is processed by the pipeline.
• The Process method receives the input, and a CancellationToken.
• Any external services required by the pipeline should be declared as constructor parameters.
• Both the pipeline and the interceptors are registered as scoped services in the IServiceProvider.

Creating an interceptor

The following example demonstrates how to create an interceptor.

public class MyInterceptor : Interceptor<MyClass, MyClassResult>
{
	public override Task BeforeProcessing(MyClass input, CancellationToken cancellationToken)
	{
		return Task.CompletedTask;
	}

	public override Task AfterProcessing(MyClassResult output, CancellationToken cancellationToken)
	{
		return Task.CompletedTask;
	}

	public override Task OnError(MyClass input, Exception exception, CancellationToken cancellationToken)
	{
		return Task.CompletedTask;
	}
}

Things to note:

• Regardless of success or failure, interceptors are always called in the reverse order they were added to the pipeline.
  • If an exception occurs in an interceptor, the remaining interceptors are not called, but the OnError method is called for each interceptor in the reverse order.
• The BeforeProcessing and AfterProcessing methods have default implementations that return a completed task. These methods may be overridden to perform operations before and after the pipeline processes the input.
• The methods may modify, but not replace, the input and output of the pipeline.
• If an exception is thrown during the processing of the pipeline, the OnError method is called. This method may be overridden to perform operations when an exception occurs.
  • When an exception occurs, the AfterProcessing method is not called.
• If the interceptor requires services from the DI container, they can be declared as constructor parameters.

Registering the pipelines

PipelineExtensions provides the extension method AddPipelines for IServiceCollection that registers all pipelines and interceptors in the assembly, as well as any referenced assemblies.

Pipelines are registered as Pipeline<TInput, TOutput> rather than the concrete implementation. This allows the pipelines to be resolved from the DI container based on the TInput type. The interceptors are registered via their implementation type, as the order of interceptors is important.

AddPipelines will also register the Dispatcher class as a singleton service. The Dispatcher class is used to dispatch the input to the correct pipeline based on the TInput type.

Dispatching the input

Dispatching a payload is done by resolving the Dispatcher class from the DI container and calling the DispatchAsync method.

var dispatcher = serviceProvider.GetRequiredService<Dispatcher>();

var result = await dispatcher.DispatchAsync<MyClass, MyClassResult>(new MyClass());

Attempting to dispatch a payload with an unregistered TInput type will result in an exception.

Why?

The main goal of this library is to provide a way to encapsulate business logic in a way that is easy to overview and test. By using pipelines and interceptors, the business logic can be split into smaller, more manageable parts. This also makes it easier to test the individual parts of the business logic.

Why not use a library like MediatR? Honestly, mainly because MediatR contains a lot of features that are not needed for this project, as well as enouraging boiler-plate heavy code.