Merge pull request #1047 from DuendeSoftware/bff-docs-cross-check

Update BFF docs (v3/v4 inconsistencies and undocumented functionality)

Author: maartenba

astro/src/content/docs/bff/extensibility/http-forwarder.md

@@ -0,0 +1,192 @@
+---
+title: "HTTP Forwarder"
+description: Learn how to customize the HTTP forwarding behavior in BFF by providing custom HTTP clients and request/response transformations
+date: 2020-09-10T08:22:12+02:00
+sidebar:
+  order: 40
+redirect_from:
+  - /bff/v2/extensibility/http_forwarder/
+  - /bff/v3/extensibility/http_forwarder/
+  - /identityserver/v5/bff/extensibility/proxy/
+  - /identityserver/v6/bff/extensibility/http_forwarder/
+  - /identityserver/v7/bff/extensibility/http_forwarder/
+---
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+You can customize the HTTP forwarder behavior in two ways
+
+* provide a customized HTTP client for outgoing calls
+* provide custom request/response transformation
+
+## Custom HTTP Clients
+
+By default, Duende.BFF will create and cache an HTTP client per configured route or local path.
+
+This invoker is set up like this:
+
+```csharp
+var client = new HttpMessageInvoker(new SocketsHttpHandler
+{
+    UseProxy = false,
+    AllowAutoRedirect = false,
+    AutomaticDecompression = DecompressionMethods.None,
+    UseCookies = false
+});
+```
+
+If you want to customize the HTTP client you can implement the `IForwarderHttpClientFactory` interface (from
+YARP's `Yarp.ReverseProxy.Forwarder` namespace), e.g.:
+
+```csharp
+public class MyInvokerFactory : IForwarderHttpClientFactory
+{
+    public HttpMessageInvoker CreateClient(ForwarderHttpClientContext context)
+    {
+        return new HttpMessageInvoker(new SocketsHttpHandler
+        {
+            // this API needs a proxy
+            UseProxy = true,
+            Proxy = new WebProxy("https://myproxy"),
+
+            AllowAutoRedirect = false,
+            AutomaticDecompression = DecompressionMethods.None,
+            UseCookies = false
+        });
+    }
+}
+```
+
+...and override our registration:
+
+```csharp
+services.AddSingleton<IForwarderHttpClientFactory, MyInvokerFactory>();
+```
+
+## Custom Transformations When Using Direct Forwarding
+
+The method `MapRemoteBffApiEndpoint` uses default transformations that:
+* removes the cookie header from the forwarded request
+* removes local path from the forwarded request
+* adds the access token to the original request
+
+If you wish to change or extend this behavior, you can do this for a single mapped endpoint
+or for all mapped API endpoints.
+
+### Changing The Transformer For A Single Mapped Endpoint
+
+This code block shows an example of how you can extend the default transformers with an additional custom
+transform.
+
+{/* prettier-ignore */}
+<Tabs syncKey="bffVersion">
+    {/* prettier-ignore */}
+    <TabItem label="Duende BFF v4">
+    ```csharp
+    app.MapRemoteBffApiEndpoint("/local", new Uri("https://target/"), context => {
+
+        // If you want to extend the existing behavior, then you must call the default builder:
+        DefaultBffYarpTransformerBuilders.DirectProxyWithAccessToken("/local", context);
+
+        // You can also add custom transformers, such as this one that adds an additional header
+        context.AddRequestHeader("custom", "with value");
+
+    });
+    ```
+
+    The default transform builder performs these transforms:
+
+    ```csharp
+    context.AddRequestHeaderRemove("Cookie");
+    context.AddPathRemovePrefix(pathMatch);
+    context.AddBffAccessToken(pathMatch);
+    ```
+    </TabItem>
+    {/* prettier-ignore */}
+    <TabItem label="Duende BFF v3">
+    ```csharp
+    app.MapRemoteBffApiEndpoint("/local", "https://target/", context => {
+
+        // If you want to extend the existing behavior, then you must call the default builder:
+        DefaultBffYarpTransformerBuilders.DirectProxyWithAccessToken("/local", context);
+
+        // You can also add custom transformers, such as this one that adds an additional header
+        context.AddRequestHeader("custom", "with value");
+
+    });
+    ```
+
+    The default transform builder performs these transforms:
+
+    ```csharp
+    context.AddRequestHeaderRemove("Cookie");
+    context.AddPathRemovePrefix(localPath);
+    context.AddBffAccessToken(localPath);
+    ```
+    </TabItem>
+</Tabs>
+
+For more information, also see the [YARP documentation on transforms](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/yarp/transforms?view=aspnetcore-9.0)
+
+### Changing The Default Transformer
+
+You can change the default transformer builder delegate by registering one in the services collection:
+
+{/* prettier-ignore */}
+<Tabs syncKey="bffVersion">
+    {/* prettier-ignore */}
+    <TabItem label="Duende BFF v4">
+    ```csharp
+    BffYarpTransformBuilder builder = (pathMatch, context) => {
+
+        // If you want to extend the existing behavior, then you must call the default builder:
+        DefaultBffYarpTransformerBuilders.DirectProxyWithAccessToken(pathMatch, context);
+
+        // You can also add custom transformers, such as this one that adds an additional header
+        context.AddResponseHeader("added-by-custom-default-transform", "some-value");
+
+    };
+
+    services.AddSingleton<BffYarpTransformBuilder>(builder);
+    ```
+    </TabItem>
+    {/* prettier-ignore */}
+    <TabItem label="Duende BFF v3">
+    ```csharp
+    BffYarpTransformBuilder builder = (localPath, context) => {
+
+        // If you want to extend the existing behavior, then you must call the default builder:
+        DefaultBffYarpTransformerBuilders.DirectProxyWithAccessToken(localPath, context);
+
+        // You can also add custom transformers, such as this one that adds an additional header
+        context.AddResponseHeader("added-by-custom-default-transform", "some-value");
+
+    };
+
+    services.AddSingleton<BffYarpTransformBuilder>(builder);
+    ```
+    </TabItem>
+</Tabs>
+
+## Changing The Forwarder Request Configuration
+
+:::note
+Forwarder request configuration is available in Duende BFF v4 and later.
+:::
+
+You can also modify the forwarder request configuration, either globally or per mapped path.
+This can be useful if you want to tweak things like activity timeouts.
+
+```csharp
+// Register a forwarder config globally:
+services.AddSingleton(new ForwarderRequestConfig()
+{
+    ActivityTimeout = TimeSpan.FromMilliseconds(100)
+});
+
+// Or modify one on a per mapped route basis:
+app.MapRemoteBffApiEndpoint("/local", new Uri("https://target/"),
+    requestConfig: new ForwarderRequestConfig()
+    {
+        ActivityTimeout = TimeSpan.FromMilliseconds(100)
+    });
+```

astro/src/content/docs/bff/extensibility/http-forwarder.mdx

@@ -42,7 +42,7 @@ builder.Services.AddTransient<IDiagnosticsEndpoint, DefaultDiagnosticsEndpoint>(
           title="IBffEndpoint.cs"
           code={`public interface IBffEndpoint
 {
-    Task ProcessRequestAsync(HttpContext context, CancellationToken ct);
+    Task ProcessRequestAsync(HttpContext context, CancellationToken ct = default);
 }`}/>
 
       You can customize the behavior of the endpoints by implementing the appropriate interface.

astro/src/content/docs/bff/extensibility/management/index.mdx

@@ -28,7 +28,7 @@ The `IReturnUrlValidator` ensures that the `returnUrl` parameter passed to the l
 <Tabs syncKey="bffVersion">
     <TabItem label="V4">
         You can customize the behavior of the logout endpoint by implementing the `ProcessRequestAsync` method of the
-        `ILogoutEndpoint` interface. The [default implementation][1]
+        `ILogoutEndpoint` interface. The [default implementation](https://github.com/DuendeSoftware/products/tree/releases/bff/4.0.x/bff/src/Bff/Endpoints/Internal/DefaultLogoutEndpoint.cs)
         can serve as a starting point for your own implementation.
 
         If you want to extend the default behavior of the logout endpoint, you can instead add a custom endpoint and
@@ -50,7 +50,7 @@ app.MapGet(bffOptions.LogoutPath, async (HttpContext context, CancellationToken
 `} />
     </TabItem>
     <TabItem label="V3">
-        `ProcessRequestAsync` is the top-level function called in the endpoint service `DefaultSilentLoginCallbackService`,
+        `ProcessRequestAsync` is the top-level function called in the endpoint service `DefaultLogoutService`,
         and can be used to add arbitrary logic to the endpoint.
 
         For example, you could take whatever actions you need before normal processing of the request like this:
@@ -73,5 +73,3 @@ public override Task ProcessRequestAsync(HttpContext context, CancellationToken
 To prevent open redirector attacks, the `returnUrl` parameter to the logout endpoint must be validated. You can
 customize this validation by implementing the `IReturnUrlValidator` interface. The default implementation enforces
 that return URLs are local.
-
-[1]: https://github.com/DuendeSoftware/products/tree/releases/bff/4.0.x/bff/src/Bff/Endpoints/Internal/DefaultLogoutEndpoint.cs