MVFC.Aspire.Helpers.ApigeeEmulator 7.3.0

MVFC.Aspire.Helpers.ApigeeEmulator

🇧🇷 Leia em Português

Helpers for integrating the Google Apigee Emulator with .NET Aspire projects, enabling local API proxy development and testing.

Motivation

Working with Apigee API proxies locally usually means:

• Spinning up the emulator container manually with the correct image and ports.
• Remembering to build and deploy the proxy bundle (ZIP) every time you make changes.
• Manually configuring TargetServers to point at your backend services.
• Dealing with host.docker.internal and port mismatches between your host and Docker.

With .NET Aspire you can define containers, but you still need to:

• Configure the emulator image, control port, and traffic port.
• Build and deploy your apiproxy bundle to the emulator on startup.
• Dynamically wire TargetServers to match the Aspire-allocated backend ports.

MVFC.Aspire.Helpers.ApigeeEmulator provides:

• AddApigeeEmulator(...) to start the emulator with sensible defaults.
• .WithWorkspace(...) to point at your local proxy bundle.
• .WithEnvironment(...) to set the Apigee environment name.
• .WithBackend(...) to automatically resolve Aspire backend endpoints as TargetServers.

Overview

This project facilitates the configuration and integration of the Apigee Emulator in distributed .NET Aspire applications, providing extension methods to:

• Add the Apigee Emulator container with pre-configured ports.
• Deploy the proxy bundle (apiproxy) automatically on startup.
• Dynamically inject TargetServer configurations pointing at Aspire-managed backends.
• Merge static and dynamic TargetServer definitions for hybrid scenarios.

Apigee Emulator advantages

• Develop and test API proxies locally without a Google Cloud account.
• Validate traffic policies, security flows, and SharedFlows before pushing to production.
• Full support for Trace/Debug sessions for request inspection.
• Seamless integration with existing Aspire-managed backend services.

Compatible Images

• Emulator:
  • gcr.io/apigee-release/hybrid/apigee-emulator (Default in Aspire helper)

Project Structure

• MVFC.Aspire.Helpers.ApigeeEmulator: Helpers and extensions library for Apigee Emulator.

Features

• Adds the Apigee Emulator container with default image and ports.
• Deploys the proxy bundle automatically when the emulator is ready.
• Resolves Aspire backend ports and injects TargetServer configurations.
• Merges existing static targetservers.json with dynamically generated entries.
• Extension methods for fluent AppHost configuration.

Installation

dotnet add package MVFC.Aspire.Helpers.ApigeeEmulator

Quick Aspire usage (AppHost)

using Aspire.Hosting;
using MVFC.Aspire.Helpers.ApigeeEmulator;

var builder = DistributedApplication.CreateBuilder(args);

var apigeeWorkspace = Path.Combine(Directory.GetCurrentDirectory(), "apigee-workspace");

var api = builder.AddProject<Projects.MyApi>("my-api");

var apigee = builder.AddApigeeEmulator("apigee-emulator")
                    .WithWorkspace(apigeeWorkspace)
                    .WithEnvironment("local")
                    .WithBackend(api, "origin");

await builder.Build().RunAsync();

Ports

Provisioning diagram

sequenceDiagram
    participant Aspire as .NET Aspire
    participant Container as Apigee Emulator Container
    participant Hook as Deploy Lifecycle Hook
    participant Backend as Aspire Backend

    Aspire->>Container: Start container (apigee-emulator)
    Container-->>Aspire: Ready (control port available)
    Aspire->>Hook: Trigger AfterResourcesCreatedEvent
    Hook->>Backend: Wait for backend Running state
    Backend-->>Hook: Running (port resolved)
    Hook->>Hook: Build ZIP (merge targetservers.json)
    Hook->>Container: POST /v1/emulator/deploy
    Container-->>Hook: Deploy successful
    Hook-->>Aspire: Deployment completed

Public methods

• AddApigeeEmulator – adds the emulator container with default image and ports.
• WithWorkspace – sets the local path to the apiproxy bundle.
• WithEnvironment – sets the Apigee environment name (default: "local").
• WithDockerImage – overrides the Docker image and tag.
• WithBackend – configures an Aspire backend as a TargetServer for the proxy.

Architecture and Policies of the Apigee Proxy

After validating the base project and the final configuration present in proxies/default.xml, this document was updated to present the real routing structure, the request flow diagram, and all 22 policies with their functions correctly applied to their respective routes.

General Flow Diagram

flowchart TD
    A["Request → /demo/*"] --> B{"Method / Route?"}
    
    B -->|OPTIONS| C["CORS Preflight (AM-Cors) → 200 No Backend"]
    B -->|DELETE/PUT/PATCH| D["Method Not Allowed (RF) → 405"]
    
    B -->|/sharedflow-check| Q["SharedFlow Check (FC-CallLogging)"]
    B -->|/spike-arrest| E["Spike Arrest Test (SA-SpikeArrest)"]
    B -->|/notfound| F["Not Found Demo (RF-NotFound) → 404"]
    B -->|/transform| G["Transform Envelope (JS-TransformResponse)"]
    B -->|/quota-test| H["Quota Rate Limit (QU-RateLimit)"]
    B -->|/health-check| I["Health Check (ServiceCallout + AM)"]
    B -->|/cached| J{"Cache Hit? (LookupCache)"}
    B -->|/admin| K["Admin Panel (AccessControl IP)"]
    B -->|/secure| L["Secure Resource (BasicAuth + JS Valid.)"]
    B -->|/xml| M["XML to JSON Format Convert"]
    B -->|/status/**| N["TargetRule: public (httpbin)"]
    B -->|Others| O["TargetRule: default (origin)"]

    J -->|Yes| J1["AM-CacheHit → Responds 200"]
    J -->|No| J2["Target Backend → Populates PC-Cache + AM-Miss"]

    E & G & H & I & J2 & K & L & M & N & O & Q --> P["PostFlow: Adds CORS + Custom Headers + FC-CallLogging"]

Policies Implemented directly in Flows

Below are detailed the applicabilities and the exact usage location of each policy configured in the emulator's XML files:

PostFlow Policies (Applied to all that survive and reach the response):

Whether an intercepted return, a planned error, or a successful call to the backend, the PostFlow policies enrich the output message:

• AM-AddCorsHeaders.xml: Guarantees specifications to avoid browser CORS errors (Allow-Origins).
• AM-AddCustomHeaders.xml: Reinforces additional ID information.
• FC-CallLogging.xml: A delegated callout that isolates our complex logging code, passing it to the common-logging SharedFlow.

Global Faults (Fault Rules Override)

• AM-DefaultFaultResponse.xml: An AssignMessage policy invoked by the Fault Rule when some systemic error happens in Apigee without a specific RaiseFault, modifying the ugly default output to our standard API JSON layout scope.

Requirements

• .NET 9+
• Aspire.Hosting >= 9.5.0
• Docker running locally

License

Apache-2.0