Documenting aspnetcore hosting gap analysis progress

[Copilot]

This pull request introduces strict validation and support for the X-Forwarded-Prefix header in the Minimal API host, ensuring that path base forwarding is secure and predictable. It adds an option to enable or disable this feature, updates documentation to reflect the new behavior, and provides comprehensive tests to verify correct handling of valid, invalid, and ambiguous prefixes.

Forwarded Prefix Handling and Validation

• Added a UseForwardedPrefix option to ArkMinimalApiHostOptions (default: true), allowing the host to accept and strictly validate the X-Forwarded-Prefix header. If enabled, a valid prefix is prepended to PathBase, while malformed or ambiguous values result in a 400 Bad Request before downstream middleware runs. A private method, TryGetForwardedPrefix, implements the validation logic. ([[1]](https://github.com/ARKlab/Ark.Tools/pull/838/files#diff-17beb4389c729323e36094919ca76aae4e89b338da7a3af5b883a5b3f835b8e9R37-R41), [[2]](https://github.com/ARKlab/Ark.Tools/pull/838/files#diff-17beb4389c729323e36094919ca76aae4e89b338da7a3af5b883a5b3f835b8e9R113-R133), [[3]](https://github.com/ARKlab/Ark.Tools/pull/838/files#diff-17beb4389c729323e36094919ca76aae4e89b338da7a3af5b883a5b3f835b8e9R152-R211))

Documentation Updates

• Updated the host setup and composition guide to document the new UseForwardedPrefix option, describe the validation process, and clarify the order of middleware execution. The documentation now explains how invalid or ambiguous X-Forwarded-Prefix values are handled and how to disable the feature if handled externally. ([[1]](https://github.com/ARKlab/Ark.Tools/pull/838/files#diff-5c75e2f737b7656e9b1177be1b75d861f5bea87ddde3c539dbf5d94f90a4a9a8R142), [[2]](https://github.com/ARKlab/Ark.Tools/pull/838/files#diff-5c75e2f737b7656e9b1177be1b75d861f5bea87ddde3c539dbf5d94f90a4a9a8L173-R174), [[3]](https://github.com/ARKlab/Ark.Tools/pull/838/files#diff-5c75e2f737b7656e9b1177be1b75d861f5bea87ddde3c539dbf5d94f90a4a9a8L192-R196))

Testing

• Added ForwardedPrefixTests to verify that valid prefixes are accepted, malformed prefixes are rejected, and multiple prefixes are treated as ambiguous and rejected with a 400 status. ([samples/Ark.MediatorFramework.Sample/test/Ark.MediatorFramework.Sample.Tests/ForwardedPrefixTests.csR1-R54](https://github.com/ARKlab/Ark.Tools/pull/838/files#diff-0ebd5a9647b64f9062ff6f623f21f897166caa26b9aec9227c9ad64202d0ad3cR1-R54))
• Updated the progress tracking document to mark the relevant acceptance criteria as completed for forwarded prefix validation and error handling. ([docs/mediator-framework/progress/tasks/aspnetcore/HST-03-path-base-validation.mdL33-R37](https://github.com/ARKlab/Ark.Tools/pull/838/files#diff-3a23c981c679cc2d08d43aad13e539de26f887dd5c5604bc03ad56ce0b23fb5dL33-R37))Pull request created by AI Agent

[Copilot]

Pull request overview

Adds strict X-Forwarded-Prefix handling to the Minimal API host pipeline (with an application opt-out) and documents the new behavior as part of the ASP.NET Core hosting gap-analysis progress.

Changes:

• Add ArkMinimalApiHostOptions.UseForwardedPrefix (default true) and middleware that validates X-Forwarded-Prefix, rejecting malformed/ambiguous values with HTTP 400.
• Add sample integration tests covering valid/invalid/multiple X-Forwarded-Prefix header scenarios.
• Update mediator framework docs and task tracking to reflect the new forwarded-prefix validation behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/aspnetcore/Ark.Tools.AspNetCore.MinimalApi/ArkMinimalApiHostExtensions.cs	Introduces forwarded-prefix option + request middleware that validates and applies X-Forwarded-Prefix to PathBase.
samples/Ark.MediatorFramework.Sample/test/Ark.MediatorFramework.Sample.Tests/ForwardedPrefixTests.cs	Adds integration tests verifying 200 for a valid prefix and 400 for invalid/multiple prefixes.
docs/mediator-framework/progress/tasks/aspnetcore/HST-03-path-base-validation.md	Marks the forwarded-prefix validation acceptance items as completed.
docs/mediator-framework/guide/host-setup-and-composition.md	Documents forwarded-prefix validation in host setup and middleware ordering guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.