Skip to content

Commit

Permalink
Fix Via and Redirect typos
Browse files Browse the repository at this point in the history
  • Loading branch information
devodo committed Dec 18, 2022
1 parent 58987c8 commit 819508a
Show file tree
Hide file tree
Showing 16 changed files with 53 additions and 52 deletions.
6 changes: 3 additions & 3 deletions docs/DI.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Console.WriteLine(demo.Name); // "Foo";

The resolved `IFoo` instance above is a Redirect proxy generated by the underlying `IRedirect<IFoo>` decorator that uses the original DI registration to initialise the proxy root.
In its initial state the `IFoo` proxy forwards all calls directly to its root. However, this behaviour can be modified by obtaining the underlying `Redirect`
from the `Diverter` instance and adding a *via*:
from the `Diverter` instance and adding a *Via*:

```csharp
// Obtain the underlying Redirect from the diverter instance
Expand All @@ -66,7 +66,7 @@ var foo = provider.GetService<IFoo>();
Console.WriteLine(foo.Name); // "Foo diverted"
```

Any redirects added to the `Redirect` are applied to all its existing proxies and any resolved afterwards:
Any Vias added to the `Redirect` are applied to all its existing proxies and any resolved afterwards:

```csharp
var foo2 = provider.GetService<IFoo>();
Expand Down Expand Up @@ -103,7 +103,7 @@ var barFactory = provider.GetService<IBarFactory>();
IBar bar = barFactory.Create("MrBar"); // The Create call now returns IBar proxies
Console.WriteLine(bar.Name); // "MrBar"
// Add a via to alter behaviour
// Add a Via to alter behaviour
barRedirect
.To(x => x.Name)
.Via(call => call.Root.Name + " diverted");
Expand Down
61 changes: 31 additions & 30 deletions docs/Redirect.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,8 @@ There are some special cases such as `Task` types are returned as `null` valued
# Via

`Via` instances are added to a `Redirect` to control the way its proxies behave.
Proxy calls are diverted and passed to the via for handling.
A fluent interface is provided on the Redirect for building and adding vias to itself:
Proxy calls are diverted and passed to the Vias for handling.
A fluent interface is provided on the Redirect for building and adding Vias to itself:

```csharp
var foo = new Foo("MrFoo");
Expand All @@ -66,21 +66,21 @@ var fooRedirect = new Redirect<IFoo>();
var fooProxy = fooRedirect.Proxy(foo);
Console.WriteLine(fooProxy.Name); // "MrFoo"
// Add a via to the Redirect
// Add a Via to the Redirect
fooRedirect
.To(x => x.Name) // 1. Match expression
.Via(() => "Hello Via"); // 2. Via delegate
Console.WriteLine(fooProxy.Name); // "Hello Via"
```

The via intercepts any proxy calls matching the `To` expression 1. and diverts them to the `Via` delegate 2.
The Via intercepts any proxy calls matching the `To` expression 1. and diverts them to the `Via` delegate 2.

Vias can be added to a Redirect at any time and apply immediately to all its existing proxies as well as any created afterwards.

# Reset

A Redirect can be *reset* which removes all its redirects, reverting its proxies to their original behaviour:
A Redirect can be *reset* which removes all its Vias, reverting its proxies to their original behaviour:

```csharp
fooRedirect.To(x => x.Name).Via("diverted");
Expand All @@ -92,18 +92,18 @@ Console.WriteLine(fooProxy.Name); // "MrFoo"
```

Reset can be called at any time and is applied immediately to all of the Redirect's proxies.
By adding redirects and resetting, proxy behaviour can be modified at runtime allowing a running process to be altered between tests, e.g. to avoid restart and initialisation overhead.
By adding Vias and resetting, proxy behaviour can be modified at runtime allowing a running process to be altered between tests, e.g. to avoid restart and initialisation overhead.

After a Redirect is reset its proxies are in their default, transparent state of forwarding all calls to their root instances.
This enables a pattern of testing where proxy behaviour is modified with redirects and then the system is reset to its original state between tests.
This enables a pattern of testing where proxy behaviour is modified with Vias and then the system is reset to its original state between tests.

# Method parameters

Via intercept rules can be configured based on the values of method parameters and call arguments values can be used by via delegates.
Via intercept match rules can be configured on method parameters using call argument values and these can also be passed to Via delegates.

## Parameter matching

If the via `To` expression specifies a method with parameters, these are matched to call arguments as follows:
If the Via `To` expression specifies a method with parameters, these are matched to call arguments as follows:

```csharp
// Match calls to the Echo method with any argument value
Expand All @@ -128,7 +128,7 @@ Console.WriteLine(fooProxy.Echo("three")); // "equal"

## Call arguments

Proxy call arguments can be passed to the via delegate as follows:
Proxy call arguments can be passed to the Via delegate as follows:

```csharp
fooRedirect
Expand Down Expand Up @@ -160,11 +160,11 @@ then the discard type `__` must be used to provide a second dummy parameter.

# Relay

A special feature of redirects is their ability to control how calls are forwarded or *relayed* back to proxy root instances.
A special feature of Redirects is their ability to control how calls are forwarded or *relayed* back to proxy root instances.

## Relay root

The via delegate can *relay* calls back to the proxy root by calling the `Relay.Root` property:
The Via delegate can *relay* calls back to the proxy root by calling the `Relay.Root` property:

```csharp
fooRedirect
Expand All @@ -183,15 +183,15 @@ Console.WriteLine(fooProxy.Name); // "MrFoo relayed"
## Relay next

Any number of redirects can be added to a Redirect. When redirects are added they are pushed onto a stack (with the last added at the top).
Any number of Vias can be added to a Redirect. When Vias are added they are pushed onto a stack (with the last added at the top).

![Via Stack](./assets/images/Via_Stack.svg)

Proxy calls are traversed through the stack from top to bottom. If a call matches the `To` constraint it is passed to the via delegate for handling.
If no redirects match, the call falls through the stack to the root instance.
Proxy calls are traversed through the stack from top to bottom. If a call matches the `To` constraint it is passed to the Via delegate for handling.
If no Vias match, the call falls through the stack to the root instance.

Via delegates can relay the call directly to the root as in the previous example
but they can also continue the call down the via stack by calling the `Relay.Next` property as follows:
but they can also continue the call down the Via stack by calling the `Relay.Next` property as follows:

```csharp
fooRedirect
Expand All @@ -204,13 +204,13 @@ Console.WriteLine(fooRoot.Name); // "MrFoo"
Console.WriteLine(fooProxy.Name); // "MrFoo 1 2 3"
```

> The `Relay.Next` property is a proxy that relays calls to the next via that matches.
> If no redirects match it will relay to the root.
> The `Relay.Next` property is a proxy that relays calls to the next Via that matches.
> If no Vias match it will relay to the root.
> The Root and Next properties can also be accessed directly from the call argument for convenience.
## Call forwarding

A via can call `CallRoot()` to forward the call to the target method of the root instance:
A Via can call `CallRoot()` to forward the call to the target method of the root instance:

```csharp
fooRedirect
Expand All @@ -221,7 +221,7 @@ Console.WriteLine(fooRoot.Name); // "MrFoo"
Console.WriteLine(fooProxy.Name); // "MrFoo 1"
```

Or the call can be forwarded down the via stack using `CallNext()`:
Or the call can be forwarded down the Via stack using `CallNext()`:

```csharp
fooRedirect
Expand Down Expand Up @@ -253,11 +253,11 @@ fooRedirect
Console.WriteLine(fooProxy.Echo("me")); // "you"
```

# Via methods
# Method variations

## Async methods

Async is fully supported by DivertR and via delegates can be added to `Task` or `ValueTask` methods using the standard C# `async` syntax:
Async is fully supported by DivertR and Via delegates can be added to `Task` or `ValueTask` methods using the standard C# `async` syntax:

```csharp
fooRedirect
Expand All @@ -272,7 +272,7 @@ fooRedirect

## Property Getters and Setters

Vias for property getters, [demonstrated earlier](#via), are added using the same `To` syntax as for standard methods. However, to indicate a via is for a property setter, the `ToSet` method is used instead:
Vias for property getters, [demonstrated earlier](#via), are added using the same `To` syntax as for standard methods. However, to indicate a Via is for a property setter, the `ToSet` method is used instead:

```csharp
fooRedirect
Expand All @@ -283,7 +283,7 @@ fooRedirect
});
```

By default the via above will match any setter value input but the `ToSet` method accepts a second parameter as a value match expression using the usual [parameter matching](#parameter-matching) syntax:
By default the Via above will match any setter value input but the `ToSet` method accepts a second parameter as a value match expression using the usual [parameter matching](#parameter-matching) syntax:

```csharp
fooRedirect
Expand All @@ -299,7 +299,7 @@ Console.WriteLine(fooProxy.Name); // "Me changed"

## Void methods

For via methods that return `void`, the same `Redirect` fluent interface syntax is used, only the delegate provided is an `Action` rather than a `Func`:
For methods that return `void`, the same `Redirect` fluent interface syntax is used, only the `Via` delegate provided is an `Action` rather than a `Func`:

```csharp
fooRedirect
Expand All @@ -312,11 +312,12 @@ fooRedirect

## Generic methods

Generic method Vias are declared using the same fluent syntax ands are matched on the specified generic type arguments.

```csharp
fooRedirect
.To(x => x.Echo<int>(Is<int>.Any))
.Via(call => call.CallNext() * 2);

```

## Throwing exceptions
Expand Down Expand Up @@ -361,8 +362,8 @@ fooRedirect.Retarget(mock.Object);
Console.WriteLine(fooProxy.Echo("hello")); // "hello mock"
```

When a `Retarget` is added it is also pushed onto the Redirect via stack.
Retarget substitutes are also able to relay calls to the proxy root or next via from the Redirect's `Relay` property:
When a `Retarget` is added it is also pushed onto the Redirect Via stack.
Retarget substitutes are also able to relay calls to the proxy root or next Via from the Redirect's `Relay` property:

```csharp
IFoo next = fooRedirect.Relay.Next;
Expand All @@ -376,7 +377,7 @@ Console.WriteLine(fooProxy.Name); // "MrFoo two mock"

# Strict mode

Enable *strict mode* on a Redirect to ensure only methods with registered redirects are allowed to be called:
Enable *strict mode* on a Redirect to ensure only methods with matching Vias are allowed to be called:

```csharp
fooRedirect.Strict(); // enables strict mode
Expand All @@ -389,6 +390,6 @@ fooProxy.Echo("me"); // throws StrictNotSatisfiedException
fooProxy.Echo("ok"); // "ok"
```

When strict mode is enabled a `StrictNotSatisfiedException` is thrown if a call is made to a proxy and does not match any redirects.
When strict mode is enabled a `StrictNotSatisfiedException` is thrown if a call is made to a proxy and does not match any Vias.

Strict mode is disabled when a Redirect is created or [reset](#reset).
File renamed without changes
4 changes: 2 additions & 2 deletions src/DivertR/IDiverter.cs
Original file line number Diff line number Diff line change
Expand Up @@ -86,15 +86,15 @@ public interface IDiverter
/// <summary>
/// Reset all registered <see cref="IRedirect" />s.
/// </summary>
/// <param name="includePersistent">Optionally also reset persistent redirects.</param>
/// <param name="includePersistent">Optionally also reset persistent Redirects.</param>
/// <returns>The current <see cref="IDiverter"/> instance.</returns>
IDiverter ResetAll(bool includePersistent = false);

/// <summary>
/// Reset registered <see cref="IRedirect" /> group.
/// </summary>
/// <param name="name">The Redirect group name.</param>
/// <param name="includePersistent">Optionally also reset persistent redirects.</param>
/// <param name="includePersistent">Optionally also reset persistent Redirects.</param>
/// <returns>The current <see cref="IDiverter"/> instance.</returns>
IDiverter Reset(string? name = null, bool includePersistent = false);
}
Expand Down
12 changes: 6 additions & 6 deletions src/DivertR/IRedirect.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ namespace DivertR
/// The inserted Vias are applied to all proxies created by the Redirect.
/// Vias can be added or removed from the Redirect at any time allowing the proxy behaviour to be changed dynamically at runtime.
///
/// When a proxy is created it can be given a reference to a root instance of its type and by default it forwards all its call to this root, i.e. when no vias are configured on the Redirect.
/// When a proxy is created it can be given a reference to a root instance of its type and by default it forwards all its call to this root, i.e. when no Vias are configured on the Redirect.
/// If a root instance is not provided the proxy will be created with a dummy root that provides default return values on its members.
/// Optionally a proxy can also be created with a null root but in this case the proxy behaviour must be defined to handle any call received else a <see cref="DiverterNullRootException"/> will be thrown.
/// </summary>
Expand Down Expand Up @@ -63,7 +63,7 @@ public interface IRedirect
/// <summary>
/// Inserts an <see cref="IVia"/> into this Redirect.
/// </summary>
/// <param name="via">The via instance.</param>
/// <param name="via">The Via instance.</param>
/// <param name="optionsAction">Optional <see cref="IViaOptionsBuilder"/> action.</param>
/// <returns>This Redirect instance.</returns>
IRedirect Via(IVia via, Action<IViaOptionsBuilder>? optionsAction = null);
Expand Down Expand Up @@ -131,7 +131,7 @@ public interface IRedirect<TTarget> : IRedirect where TTarget : class?
/// <summary>
/// Insert a <see cref="IVia"/> into this Redirect.
/// </summary>
/// <param name="redirect">The redirect instance to insert.</param>
/// <param name="redirect">The Redirect instance to insert.</param>
/// <param name="optionsAction">Optional <see cref="IViaOptionsBuilder"/> action.</param>
/// <returns>This Redirect instance.</returns>
new IRedirect<TTarget> Via(IVia redirect, Action<IViaOptionsBuilder>? optionsAction = null);
Expand All @@ -152,16 +152,16 @@ public interface IRedirect<TTarget> : IRedirect where TTarget : class?
new IRedirect<TTarget> Strict(bool? isStrict = true);

/// <summary>
/// Inserts a retarget via with no call constraints (therefore all calls will be viaed).
/// Inserts a retarget Via with no call constraints (therefore all calls will be matched and retargeted).
/// </summary>
/// <param name="target">The target instance to retarget calls to.</param>
/// <param name="optionsAction">Optional <see cref="IViaOptionsBuilder"/> action.</param>
/// <returns>This Redirect instance.</returns>
IRedirect<TTarget> Retarget(TTarget target, Action<IViaOptionsBuilder>? optionsAction = null);

/// <summary>
/// Inserts a record via that captures incoming calls from all proxies.
/// By default record redirects are configured to not satisfy strict calls if strict mode is enabled.
/// Inserts a record Via that captures incoming calls from all proxies.
/// By default record Redirects are configured to not satisfy strict calls if strict mode is enabled.
/// </summary>
/// <param name="optionsAction">Optional <see cref="IViaOptionsBuilder"/> action.</param>
/// <returns>An <see cref="IRecordStream{TTarget}"/> instance for retrieving and iterating the recorded calls.</returns>
Expand Down
2 changes: 1 addition & 1 deletion src/DivertR/IRedirectPlan.cs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ namespace DivertR
public interface IRedirectPlan
{
/// <summary>
/// The ordered list of configured vias.
/// The ordered list of configured Vias.
/// </summary>
IReadOnlyList<IConfiguredVia> Vias
{
Expand Down
6 changes: 3 additions & 3 deletions src/DivertR/IRedirectRepository.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@ IRedirectPlan RedirectPlan
/// <summary>
/// Insert a <see cref="IVia"/> instance />.
/// </summary>
/// <param name="via">The via to insert.</param>
/// <param name="viaOptions">Optional via options.</param>
/// <param name="via">The Via to insert.</param>
/// <param name="viaOptions">Optional Via options.</param>
/// <returns>This <see cref="IRedirectRepository"/> instance.</returns>
IRedirectRepository InsertVia(IVia via, IViaOptions? viaOptions = null);

/// <summary>
/// Insert a <see cref="IConfiguredVia"/> instance />.
/// </summary>
/// <param name="configuredVia">The via container.</param>
/// <param name="configuredVia">The configured Via.</param>
/// <returns>This <see cref="IRedirectRepository"/> instance.</returns>
IRedirectRepository InsertVia(IConfiguredVia configuredVia);

Expand Down
4 changes: 2 additions & 2 deletions src/DivertR/IRedirectSet.cs
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,14 @@ public interface IRedirectSet
/// Reset the specified group of <see cref="IRedirect" />s in this set.
/// </summary>
/// <param name="name">The Redirect group name.</param>
/// <param name="includePersistent">Optionally also reset persistent redirects.</param>
/// <param name="includePersistent">Optionally also reset persistent Redirects.</param>
/// <returns>The current <see cref="IDiverter"/> instance.</returns>
IRedirectSet Reset(string? name = null, bool includePersistent = false);

/// <summary>
/// Reset all <see cref="IRedirect" />s in this set.
/// </summary>
/// <param name="includePersistent">Optionally also reset persistent redirects.</param>
/// <param name="includePersistent">Optionally also reset persistent Redirects.</param>
/// <returns>The current <see cref="IDiverter"/> instance.</returns>
IRedirectSet ResetAll(bool includePersistent = false);

Expand Down
6 changes: 3 additions & 3 deletions src/DivertR/Internal/Relay.cs
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ IRedirectCall IRelay.GetCurrentCall()
{
if (redirectPlan.IsStrictMode)
{
throw new StrictNotSatisfiedException("Strict mode is enabled and the call did not match any redirects");
throw new StrictNotSatisfiedException("Strict mode is enabled and the call did not match any Redirects");
}

return CallRoot(callInfo);
Expand Down Expand Up @@ -213,7 +213,7 @@ private ImmutableStack<RelayIndex<TTarget>> GetRelayIndexStack()
if (relayIndexStack == null || relayIndexStack.IsEmpty)
{
// The AsyncLocal value has not been initialised in the current context, therefore the caller in not within a call on this Relay.
throw new DiverterException("Access to this member is only valid within the context of a via call");
throw new DiverterException("Access to this member is only valid within the context of a Via call");
}

return relayIndexStack;
Expand All @@ -224,7 +224,7 @@ private static void ValidateStrict(RelayIndex<TTarget> relayIndex)
{
if (!relayIndex.StrictSatisfied)
{
throw new StrictNotSatisfiedException("Strict mode is enabled and the call did not match any redirects");
throw new StrictNotSatisfiedException("Strict mode is enabled and the call did not match any Redirects");
}
}

Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
4 changes: 2 additions & 2 deletions src/DivertR/TrueCallConstraint.cs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ namespace DivertR
{
public class TrueCallConstraint : ICallConstraint
{
public static readonly TrueCallConstraint Instance = new TrueCallConstraint();
public static readonly TrueCallConstraint Instance = new();

private TrueCallConstraint() { }

Expand All @@ -17,7 +17,7 @@ public bool IsMatch(ICallInfo callInfo)

public class TrueCallConstraint<TTarget> : ICallConstraint<TTarget> where TTarget : class?
{
public static readonly TrueCallConstraint<TTarget> Instance = new TrueCallConstraint<TTarget>();
public static readonly TrueCallConstraint<TTarget> Instance = new();

private TrueCallConstraint() { }

Expand Down

0 comments on commit 819508a

Please sign in to comment.