Eternet.AspNetCore.Yarp.Generator 1.2.13

Eternet.AspNetCore.Yarp.Generator

Incremental generator for YARP forwarding configuration backed by Eternet.Mediator.EndpointModel manifests.

The generator is intended for two shapes:

• BFF projects that explicitly republish a small subset of contract endpoints.
• API gateway projects that republish all gateway projections from referenced contract assemblies.

The generator consumes the contract manifest. It can forward mediator request/response endpoints and OData entity sets declared by lightweight contract attributes from Eternet.Mediator.Abstractions; see src/Eternet.Mediator/plans/contract-api-surface-yarp-and-odata-plan.md.

The input is a descriptor class decorated with [GenerateYarpForwarding]. Nested classes select endpoint contracts in the same style as Eternet.Client.Http.Generator.

using Eternet.AspNetCore.Yarp;
using Eternet.Banks.Contracts.Features.PayrollBankArtifacts;
using Eternet.Payroll.Contracts.Features.PayrollPaymentBatches;

[GenerateYarpForwarding(
    "eternet-api-cluster",
    DestinationConfigKey = "EternetApiSettings:ConnectionUrl")]
internal abstract class PayrollBankTransferForwarding
{
    internal abstract class CreateBatch : CreatePayrollPaymentBatch;
    internal abstract class CancelBatch : CancelPayrollPaymentBatch;
    internal abstract class GenerateArtifact : GeneratePayrollBankArtifact;
}

OData entity sets can be selected the same way when the contract exposes marker classes:

[GenerateYarpForwarding(
    "eternet-api-cluster",
    DestinationConfigKey = "EternetApiSettings:ConnectionUrl")]
internal abstract class PayrollODataForwarding
{
    internal abstract class Lines : PayrollOData.PayrollBankTransferLines;
}

IncludeAll = true forwards every mediator endpoint and OData entity set present in the referenced contract manifests.

When Transport = YarpForwardingTransport.Gateway, the generator requires an explicit Gateway transport in the contract manifest. It never substitutes the Internal route. Set DestinationTransport = Internal when the public Gateway route must be forwarded to a different service-owned route.

OData contracts can publish an exact subset of their conventional routes:

[ODataGatewayProjection(
    OperationNamespace.Billing,
    "Billing/OData",
    RouteKinds = ODataGatewayRouteKinds.EntitySet | ODataGatewayRouteKinds.Key)]

ODataGatewayRouteKinds.All remains the default. Select only the route kinds that are intentionally part of the public gateway surface.

Gateway hosts can compose their aggregate EDM from the same generated projection descriptors instead of naming contract DTO types manually:

var builder = new ODataConventionModelBuilder();
var forwardingOptions = new GeneratedYarpForwardingOptions
{
    ShouldIncludeRoute = route => route.ContractReadiness == "Ready"
};
GeneratedYarpForwarding.AddODataEntitySets(
    builder,
    sourceIdentity: "Eternet.Payroll.Contracts",
    routePrefix: string.Empty,
    static (modelBuilder, modelType, entitySetName) =>
    {
        var entityType = modelBuilder.AddEntityType(modelType);
        modelBuilder.AddEntitySet(entitySetName, entityType);
    },
    options: forwardingOptions);

The source identity and public route prefix select the contract-owned portion of the aggregate EDM; DTO types remain generator-owned. Only generated routes with contract route kind set participate. A contract projection restricted to ODataGatewayRouteKinds.EntitySet therefore contributes its entity set and model to the selected aggregate EDM without forwarding the destination service's /$metadata, /$count, or key routes. Projected entity-set names come from the public route, so a renamed gateway route and its aggregate EDM stay aligned. When forwarding options are supplied, the same route and cluster predicates used by CreateYarpConfiguration are applied to the EDM registrations.

Common forwarding conventions can be declared once with [YarpForwardingDefaults]. The generator applies values in this order:

1. [GenerateYarpForwarding] on the forwarding class.
2. [YarpForwardingDefaults] on the forwarding class.
3. [assembly: YarpForwardingDefaults].

using Eternet.AspNetCore.Yarp;

[assembly: YarpForwardingDefaults(
    ClusterId = "{sourceService}-cluster",
    DestinationServiceName = "eternet-{sourceService}-api",
    AuthorizationPolicy = "IsAuthorized")]

[GenerateYarpForwarding(
    SourceServiceName = "Payroll",
    OperationNames =
    [
        "PayrollBankTransferLines",
        "CancelPayrollPaymentBatch",
        "CreatePayrollPaymentBatch"
    ])]
internal abstract class PayrollBankTransferForwarding;

[GenerateYarpForwarding(
    SourceServiceName = "Banks",
    OperationNames = ["GeneratePayrollBankArtifact"])]
internal abstract class PayrollBankArtifactForwarding;

The generated code exposes logical descriptors first:

Eternet.AspNetCore.Yarp.Generated.GeneratedYarpForwarding.Clusters;
Eternet.AspNetCore.Yarp.Generated.GeneratedYarpForwarding.Routes;

Consumers can build a YARP snapshot from those descriptors and keep environment-specific choices outside the generator:

var yarp = GeneratedYarpForwarding.CreateYarpConfiguration(
    new GeneratedYarpForwardingOptions
    {
        ShouldIncludeRoute = route => route.ContractOperation == "PayrollBankTransferLines",
        ResolveDestinations = cluster => new Dictionary<string, DestinationConfig>
        {
            ["primary"] = new() { Address = ResolveAddress(cluster) }
        }
    });

AddGeneratedYarpForwarding(routes, clusters, options) remains as a convenience wrapper, but CreateYarpConfiguration is the preferred general API because it returns the generated routes and clusters instead of mutating caller-owned state. The generator does not read IConfiguration or infer service-discovery keys; destination resolution is always consumer-owned.

Generated route metadata includes the contract operation, route kind, authorization metadata, source service, route signature, the contract-owned response properties, and the possible response status/type pairs. Gateways can use those response descriptors to reproduce the destination OpenAPI surface without exposing inherited runtime-only fields from a response base type. BFFs can project the route metadata into the active OpenTelemetry HTTP activity by adding the generated proxy middleware:

app.MapReverseProxy(proxyPipeline =>
{
    proxyPipeline.Use(GeneratedYarpForwarding.UseGeneratedYarpForwardingTelemetry);
});

Hosts that already own a custom proxy middleware can call GeneratedYarpForwarding.ApplyGeneratedYarpForwardingTelemetry(context) inside that middleware before forwarding.