policy-codebase-reference

# Policy Toolkit Codebase Reference This skill provides an inventory of the codebase structure, shared infrastructure, reference policy selection, and naming conventions for the Azure API Management policy toolkit. ## File Path Conventions ### Authoring & Compilation | Artifact | Location | Example | |---|---|---| | Config record | `src/Authoring/Configs/{PolicyName}Config.cs` | `RateLimitConfig.cs` | | Document attribute | `src/Authoring/Attributes/DocumentAttribute.cs` | — | | Expression attribute | `src/Authoring/Attributes/ExpressionAttribute.cs` | — | | Expression-allowed attribute | `src/Authoring/Attributes/ExpressionAllowedAttribute.cs` | — | | Section interfaces | `src/Authoring/I{Section}Context.cs` | `IInboundContext.cs` | | Compiler class | `src/Core/Compiling/Policy/{PolicyName}Compiler.cs` | `RateLimitCompiler.cs` | | Compiler test class | `test/Test.Core/Compiling/{PolicyName}Tests.cs` | `RateLimitTests.cs` | | Available policies doc | `docs/AvailablePolicies.md` | — | | Compiler utilities | `src/Core/Compiling/CompilerUtils.cs` | — | | Syntax extensions | `src/Core/Compiling/SyntaxExtensions.cs` | — | | Diagnostics | `src/Core/Compiling/Diagnostics/CompilationErrors.cs` | — | | IoC / auto-registration | `src/Core/IoC/CompilerModule.cs` | — | | Test initialization | `test/Test.Core/CompilerTestInitialize.cs` | — | | Assertion helpers | `test/Test.Core/Assertions/` | `CompilationResultAssertion.cs` | | Generic compiler utilities | `src/Core/Compiling/Policy/GenericCompiler.cs` | — | | Add-policy guide | `docs/AddPolicyGuide.md` | — | ### Gateway Emulator | Artifact | Location | Example | |---|---|---| | Emulator handler class | `src/Testing/Emulator/Policies/{PolicyName}Handler.cs` | `SetHeaderHandler.cs` | | Handler base classes | `src/Testing/Emulator/Policies/PolicyHandler.cs` | — | | IPolicyHandler interface | `src/Testing/Emulator/IPolicyHandler.cs` | — | | Section attribute | `src/Testing/Emulator/Policies/SectionAttribute.cs` | — | | Argument extensions | `src/Testing/Emulator/Policies/ArgumentsExtensions.cs` | — | | Policy exception | `src/Testing/Emulator/PolicyExeption.cs` | Note: filename has typo | | SectionContextProxy | `src/Testing/Emulator/SectionContextProxy.cs` | — | | GatewayContext | `src/Testing/GatewayContext.cs` | — | | TestDocument | `src/Testing/TestDocument.cs` | — | | Emulator test class | `test/Test.Testing/Emulator/Policies/{PolicyName}Tests.cs` | `SetHeaderTests.cs` | | Emulator policy checklist | `docs/EmulatorPolicyChecklist.md` | — | ## Naming Conventions ### Authoring & Compilation | Artifact | Convention | Example | |---|---|---| | Config record | `{PolicyName}Config` | `RateLimitConfig` | | Sub-config record | `{DescriptiveName}` | `ApiRateLimit`, `AddressRange` | | Compiler class | `{PolicyName}Compiler` | `RateLimitCompiler` | | Compiler test class | `{PolicyName}Tests` | `RateLimitTests` | | Context method | `{PolicyName}` | `RateLimit` | | XML element name | kebab-case | `rate-limit` | | Config namespace | `Microsoft.Azure.ApiManagement.PolicyToolkit.Authoring` | — | | Compiler namespace | `Microsoft.Azure.ApiManagement.PolicyToolkit.Compiling.Policy` | — | | Compiler test namespace | `Microsoft.Azure.ApiManagement.PolicyToolkit.Compiling` | — | ### Gateway Emulator | Artifact | Convention | Example | |---|---|---| | Handler class | `{PolicyName}Handler` | `SetHeaderHandler` | | Emulator test class | `{PolicyName}Tests` | `SetHeaderTests` | | PolicyName property | PascalCase method name from section interface | `SetHeader` | | Handler namespace | `Microsoft.Azure.ApiManagement.PolicyToolkit.Testing.Emulator.Policies` | — | | Emulator test namespace | `Test.Emulator.Emulator.Policies` | — | > **Note:** `JsonToXmlHandle.cs` is a naming inconsistency in the source (missing the `r` in `Handler`). Do not rename it. ## Copyright Header Every new `.cs` file must start with: ```csharp // Copyright (c) Microsoft Corporation. // Licensed under the MIT License. ``` ## Reference Policy Selection Guide When implementing a new policy, choose the closest structural match as your reference: | Policy Structure | Reference Config | Reference Compiler | Reference Tests | |---|---|---|---| | Simple attributes only | `RateLimitByKeyConfig` | `RateLimitByKeyCompiler` | `RateLimitByKeyTests` | | Attributes + child elements | `RateLimitConfig` | `RateLimitCompiler` | `RateLimitTests` | | Attributes + typed child arrays | `IpFilterConfig` | `IpFilterCompiler` | `IpFilterTests` | | String-list child elements | `ValidateJwtConfig` | `ValidateJwtCompiler` | `ValidateJwtTests` | | Complex nested configs | `CorsConfig` | `CorsCompiler` | `CorsTests` | | Direct parameters (no config) | — | `SetMethodCompiler` | `SetMethodTests` | ## Shared Infrastructure Inventory ### Expression Support - **`[Document]`** attribute (`src/Authoring/Attributes/DocumentAttribute.cs`) — Marks a class as a policy document. Optional `name` parameter; `Scope` and `Type` properties control document scope and type. - **`[Expression]`** attribute (`src/Authoring/Attributes/ExpressionAttribute.cs`) — Marks a method as a policy expression helper. Captures source file path via `[CallerFilePath]`. - **`[ExpressionAllowed]`** attribute (`src/Authoring/Attributes/ExpressionAllowedAttribute.cs`) — Marks properties or parameters that accept policy expressions. - **`Expression<T>`** delegate (`src/Authoring/Expression.cs`) — `delegate T Expression<out T>(IExpressionContext context)`. - **`IHaveExpressionContext`** interface (`src/Authoring/IHaveExpressionContext.cs`) — Base interface for all section contexts, providing `IExpressionContext ExpressionContext { get; }`. ### Compiler Infrastructure - **`IMethodPolicyHandler`** interface (`src/Core/Compiling/IMethodPolicyHandler.cs`) — The primary compiler interface. Properties: `string MethodName { get; }`. Method: `void Handle(IDocumentCompilationContext context, InvocationExpressionSyntax node)`. - **`IReturnValueMethodPolicyHandler`** interface (`src/Core/Compiling/IReturnValueMethodPolicyHandler.cs`) — For policies returning a value. Currently disabled (the `LocalDeclarationStatementCompiler` is commented out in `CompilerModule.cs`). - **Auto-registration** (`src/Core/IoC/CompilerModule.cs`) — Uses reflection to find and register all public, non-abstract classes in the `Microsoft.Azure.ApiManagement.PolicyToolkit.Compiling.Policy` namespace that implement `IMethodPolicyHandler`. No manual DI wiring needed for standard compilers. - **`CompilerUtils`** (`src/Core/Compiling/CompilerUtils.cs`) — Static utility class with methods for parameter extraction (`ProcessParameter`, `TryExtractingConfig`), expression processing, and syntax normalization. Also defines `InitializerValue` for property name → value mapping. - **`SyntaxExtensions`** (`src/Core/Compiling/SyntaxExtensions.cs`) — Extension methods for Roslyn syntax trees: attribute detection (`ContainsAttributeOfType<T>`), document class discovery (`GetDocumentAttributedClasses`), and document metadata extraction. - **`GenericCompiler.HandleList`** (`src/Core/Compiling/Policy/GenericCompiler.cs`) — Utility for compiling string arrays into repeated child XML elements. - **`CompilationErrors`** (`src/Core/Compiling/Diagnostics/CompilationErrors.cs`) — Static class with `DiagnosticDescriptor` fields for all compilation error types. ### Compiler Test Infrastructure - **`CompilerTestInitialize`** (`test/Test.Core/CompilerTestInitialize.cs`) — Assembly-level MSTest setup. Creates Roslyn compilation with references to `System`, `System.Xml.Linq`, and the Authoring assembly. Provides the `CompileDocument()` extension method. - **`CompilationResultAssertion`** (`test/Test.Core/Assertions/CompilationResultAssertion.cs`) — FluentAssertions extension providing `BeSuccessful()` and `DocumentEquivalentTo(string expectedXml)`. - **`Usings.cs`** (`test/Test.Core/Usings.cs`) — Global usings: `FluentAssertions`, `Microsoft.VisualStudio.TestTools.UnitTesting`, assertion helpers, test extensions. ### Emulator Infrastructure - **`IPolicyHandler`** interface (`src/Testing/Emulator/IPolicyHandler.cs`) — The handler interface. Properties: `string PolicyName { get; }`. Method: `object? Handle(GatewayContext context, object?[]? args)`. - **`PolicyHandler<T>`** base classes (`src/Testing/Emulator/Policies/PolicyHandler.cs`) — Three generic variants: single config, optional config, and two-parameter. All include `CallbackSetup` for test mocking. - **`SectionContextProxy<T>`** (`src/Testing/Emulator/SectionContextProxy.cs`) — Uses `System.Reflection.DispatchProxy` to dynamically route method calls to handlers. Discovers handlers via reflection on namespace + `[Section]` attribute. - **`[Section]`** attribute (`src/Testing/Emulator/Policies/SectionAttribute.cs`) — Constructor takes `string scope` (use `nameof(IInboundContext)`, etc.). Multiple attributes can be stacked. - **`ArgumentsExtensions`** (`src/Testing/Emulator/Policies/ArgumentsExtensions.cs`) — Static utility for safe argument extraction from `object?[]?`: `ExtractArgument<T>()` (required single arg), `ExtractOptionalArgument<T>()` (nullable), and `ExtractArguments<T1, T2>()` (two-param handlers). - **`PolicyException`** (`src/Testing/Emulator/PolicyExeption.cs`) — Exception thrown when a handler fails. Carries `Policy`, `Section`, and `PolicyArgs` context. Note: filename has a typo (`Exeption`) — do not rename. - **`GatewayContext`** (`src/Testing/GatewayContext.cs`) — Central mock object with section proxies, mock stores (CertificateStore, CacheStore, ResponseExampleStore, LoggerStore), and expression context. - **`TestDocument`** (`src/Testing/TestDocument.cs`) — Orchestrates test execution across policy sections. Wraps `IDocument` and calls section methods through proxies. - **`FinishSectionProcessingException`** — Thrown by handlers (e.g., MockResponse, ReturnResponse) to terminate section processing early. ### Emulator Test Infrastructure - **`.AsTestDocument()`** extension — Creates `TestDocument` from `IDocument` for fluent test setup. - **`SetupInbound()`/`SetupOutbound()`/etc.** — Returns `MockPoliciesProvider<TSection>` for mock configuration. - **`Usings.cs`** (`test/Test.Testing/Usings.cs`) — Global usings for `FluentAssertions` and MSTest. ## Section Interfaces Policies can be available in one or more pipeline sections: | Section | Interface File | XML Section | |---|---|---| | Inbound | `src/Authoring/IInboundContext.cs` | `<inbound>` | | Outbound | `src/Authoring/IOutboundContext.cs` | `<outbound>` | | Backend | `src/Authoring/IBackendContext.cs` | `<backend>` | | On-Error | `src/Authoring/IOnErrorContext.cs` | `<on-error>` | | Fragment | `src/Authoring/IFragmentContext.cs` | N/A (reusable fragment) | Note: `IFragmentContext` duplicates method signatures from other interfaces (see `//TODO` at top of file). Copy signatures verbatim when adding policies there. ## Emulator Reference Handler Selection Guide When implementing a new emulator handler, choose the closest structural match: | Policy Structure | Reference Handler | Reference Test | |---|---|---| | Single config, simple state change | `SetStatusHandler` | `SetStatusTests` | | Two parameters (name + values) | `SetHeaderHandler` | `SetHeaderTests` | | Config with callback hooks only (no-op) | `RateLimitHandler` | `RateLimitTests` | | Optional config | `MockResponseHandler` | `MockResponseTests` | | Validation + short-circuit | `CheckHeaderHandler` | `CheckHeaderTests` | | Authentication + token | `AuthenticationManagedIdentityHandler` | `AuthenticationManagedIdentityHandlerTests` | | Cache interaction | `CacheLookupValueHandler` | `CacheLookupValueTests` | | Logging/store interaction | `LogToEventHubHandler` | `LogToEventHubTests` | | No-config (no-arg method) | `BaseHandler` | `BaseTests` | | Custom flow control / wrapper | `ReturnResponseHandler` | — | | AzureOpenAi variant (inherits Llm) | `AzureOpenAiEmitTokenMetricHandler` | — | ## Common Pitfalls | Pitfall | Rule | |---------|------| | Modifying `.csproj` files | Do **not** change `Compiling.csproj` or `Testing.csproj` unless explicitly required. Reformatting, reordering, or encoding changes (BOM, line endings) cause noisy diffs and will be rejected in review. | | Missing `IFragmentContext` entry | Every method added to a section interface (`IInboundContext`, `IOutboundContext`, etc.) must also be added to `IFragmentContext.cs`. See the authoring skill for details. | | Missing expression tests | Every property marked `[ExpressionAllowed]` in a config must have a corresponding expression test `[DataRow]`. See the testing skill section 3 for the pattern. | ## Build and Test Commands ```bash # Build the entire solution dotnet build # Run all compiler tests dotnet test --project test/Test.Core # Run all emulator tests dotnet test --project test/Test.Testing # Run tests for a specific policy dotnet test --filter "FullyQualifiedName~{PolicyName}Tests" ```