FluentYarp 1.0.1

Fluent YARP API 🚀

A strongly-typed, developer-friendly configuration library for Microsoft YARP (Yet Another Reverse Proxy) that eliminates JSON configuration pain points.

Say goodbye to repetitive JSON configuration and hello to IntelliSense-driven, compile-time validated proxy setup.

✨ Why Fluent YARP API?

Before: Repetitive JSON Hell 😵

{
  "route1": {
    "ClusterId": "catalog",
    "Match": { 
      "Path": "/catalog-api/api/catalog/items", 
      "QueryParameters": [{"Name": "api-version", "Values": ["1.0", "1"], "Mode": "Exact"}] 
    },
    "Transforms": [{ "PathRemovePrefix": "/catalog-api" }]
  },
  "route2": {
    "ClusterId": "catalog",
    "Match": { 
      "Path": "/catalog-api/api/catalog/items/{id}", 
      "QueryParameters": [{"Name": "api-version", "Values": ["1.0", "1"], "Mode": "Exact"}] 
    },
    "Transforms": [{ "PathRemovePrefix": "/catalog-api" }]
  }
  // ... 8 more nearly identical routes 😱
}

After: Clean, Type-Safe Configuration ✨

builder.Services.AddFluentYarpProxy(proxy =>
    proxy.AddRouteGroup("catalog", group =>
        group.WithBasePath("/catalog-api/api/catalog")
             .RequireApiVersion("1.0", "1")
             .AddTransform(t => t.RemovePathPrefix("/catalog-api"))
             .ToCluster("catalog")
             .Get("items")
             .Get("items/{id}")
             .Post("items"))
         .AddCluster("catalog", c => c.WithPrimaryDestination("http://catalog-api")));

🎯 Key Benefits

• 🛡️ Type Safety: Compile-time validation instead of runtime JSON errors
• 🔄 Zero Duplication: Shared configuration across route groups
• 💡 IntelliSense: Rich code completion and documentation
• 🧪 Testability: Built-in testing utilities for route validation
• 📈 Maintainability: Clear, readable configuration code
• ⚡ Performance: Zero runtime overhead compared to native YARP

🚀 Quick Start

Installation

dotnet add package FluentYarp

Simple Example

using FluentYarp;
using FluentYarp.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Replace complex JSON with simple fluent configuration
builder.Services.AddFluentYarpProxy(proxy =>
    proxy.AddRouteGroup("api", group =>
        group.WithBasePath("/api/v1")
             .RequireApiVersion("1.0")
             .Get("users/{id}", r => r.ToCluster("users"))
             .Post("users", r => r.ToCluster("users")))
         .AddCluster("users", c => c.WithPrimaryDestination("http://users-api")));

var app = builder.Build();
app.UseFluentYarpProxy();
app.Run();

Real-World API Gateway

builder.Services.AddFluentYarpProxy(proxy =>
{
    proxy.UseApiGatewayProfile()  // Common API gateway settings
         
         // Catalog microservice routes
         .AddRouteGroup("catalog", group =>
             group.WithBasePath("/api/catalog")
                  .RequireApiVersion("1.0")
                  .AddTransform(t => t.AddCorrelationId())
                  .ToCluster("catalog")
                  .Get("items")
                  .Get("items/{id}")
                  .Get("items/search")
                  .Post("items"))
         
         // Order microservice routes
         .AddRouteGroup("orders", group =>
             group.WithBasePath("/api/orders")
                  .RequireHeader("Authorization", "Bearer")
                  .ToCluster("orders")
                  .Get("{userId}/orders")
                  .Post(""))
         
         // Clusters with load balancing
         .AddCluster("catalog", c => c
             .WithPrimaryDestination("http://catalog-api")
             .WithBackupDestination("http://catalog-backup")
             .WithLoadBalancing(LoadBalancingPolicy.RoundRobin)
             .WithHealthCheck("/health"))
         
         .AddCluster("orders", c => c
             .WithPrimaryDestination("http://orders-api")
             .WithSessionAffinity(SessionAffinityPolicy.Cookie));
});

🔧 Advanced Features

Route Groups with Shared Configuration

.AddRouteGroup("admin-api", group =>
    group.WithBasePath("/admin")
         .RequireHeader("X-Admin-Key", "secret")
         .RequireApiVersion("2.0")
         .AddTransform(t => t.AddHeader("X-Internal", "true"))
         // All routes inherit the above configuration
         .Get("users")
         .Get("users/{id}")
         .Delete("users/{id}"))

Multiple Environments

.ForEnvironment("Development", dev =>
    dev.AddCluster("users", c => c.WithDestination("dev", "http://localhost:5001")))
.ForEnvironment("Production", prod =>
    prod.AddCluster("users", c => c
        .WithPrimaryDestination("http://users-api")
        .WithBackupDestination("http://users-backup")))

Built-in Testing

[Test]
public async Task Should_Route_Correctly()
{
    var proxy = FluentProxyBuilder.Create()
        .Get("/api/users/{id}", r => r.ToCluster("users"))
        .AddCluster("users", c => c.WithPrimaryDestination("http://users-api"));

    await proxy.TestRoute("/api/users/123")
        .ShouldRouteToCluster("users")
        .ShouldApplyTransform("PathRemovePrefix");
}

📚 Documentation

• Complete Developer Guide - Comprehensive documentation with examples
• API Reference - Full interface documentation
• Migration Guide - Convert from JSON configuration
• Best Practices - Performance and security guidelines
• Examples - Real-world usage examples

🛠️ Use Cases

✅ Perfect For

• API Gateways - Route external requests to internal microservices
• Service Mesh - Internal service-to-service communication
• Load Balancing - Distribute traffic across multiple instances
• Legacy Migration - Gradually modernize APIs
• Multi-tenant SaaS - Route requests based on tenant context

📦 Pre-built Extensions

// E-commerce platform routes
proxy.AddCatalogApiRoutes("/api/catalog")
     .AddOrderingApiRoutes("/api/orders")
     .AddPaymentApiRoutes("/api/payments")
     .AddIdentityRoutes("/auth");

// Standard CRUD operations
proxy.AddStandardCrudRoutes("/api/users", "users")
     .AddStandardCrudRoutes("/api/products", "products");

🔄 Migration from JSON

Converting your existing YARP JSON configuration is straightforward:

Step 1: Install FluentYarp

dotnet add package FluentYarp

Step 2: Replace your service registration

// Remove this
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

// Add this
builder.Services.AddFluentYarpProxy(proxy => {
    // Your fluent configuration here
});

Step 3: Convert routes to fluent syntax (see Migration Guide)

🤝 Contributing

We welcome contributions! Here's how you can help:

• 🐛 Report bugs - Open an issue
• 💡 Request features - Start a discussion
• 🔧 Submit PRs - See our Contributing Guide
• 📝 Improve docs - Help make the documentation better
• ⭐ Star the repo - Show your support!

Development Setup

git clone https://github.com/yourorg/fluentyarp.git
cd fluentyarp
dotnet restore
dotnet build
dotnet test

📊 Performance

Fluent YARP API has zero runtime overhead compared to native YARP. The fluent configuration is converted to native YARP configuration at startup, so there's no performance penalty for the improved developer experience.

🌟 Examples in the Wild

• E-commerce Platform: See examples/ecommerce for a complete microservices setup
• Multi-tenant SaaS: Check examples/multitenant for tenant-based routing
• API Gateway: Browse examples/api-gateway for enterprise patterns

📋 Requirements

• .NET 6.0 or higher
• Microsoft.Extensions.DependencyInjection
• Yarp.ReverseProxy

📃 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on top of Microsoft YARP
• Inspired by the need for better developer experience in proxy configuration
• Thanks to all contributors

<div align="center">

⭐ Star this repo if it helped you! ⭐

Report Bug • Request Feature • Documentation

</div>