docs: Update docs and add adding new policy guide

.github/ISSUE_TEMPLATE/1-feature.yml

@@ -17,6 +17,7 @@ body:
         - Authoring library
         - Compiler
         - Emulator library
+        - Documentation
     validations:
       required: true
   - type: input

.github/ISSUE_TEMPLATE/2-bug.yml

@@ -42,6 +42,7 @@ body:
         - Authoring library
         - Compiler
         - Emulator library
+        - Documentation
     validations:
       required: true
   - type: input

CONTRIBUTING.md

@@ -31,6 +31,10 @@ This will greatly increase alignment of your PR with the project goals and reduc
 For more information on how to set up the development environment,
 see [Development environment setup](docs/DevEnvironmentSetup.md).
 
+### Implementaition guides
+
+ - [Add new policy guide](docs/AddPolicyGuide.md)
+
 ## License
 
 This project welcomes contributions and suggestions. Most contributions require you to

docs/AddPolicyGuide.md

@@ -0,0 +1,152 @@
+# Guide to adding new policy
+
+This guide outlines the steps to add a new policy to the system, following the established pattern used for existing
+policies.
+
+Guide covers how to add a new policy that can be used in policy documents with a config.
+All new policies should follow this pattern. If a policy does not fit this pattern,
+please discuss it in an issue before impementing it. 
+
+## TL;DR;
+
+When adding a new policy, you will typically need to create or modify the following files:
+
+- Config: `src/Authoring/Configs/YourPolicyConfig.cs` (Exampe: `RateLimitConfig.cs`)
+- Section or framgent interface: `src/Authoring/IInboundContext.cs` (or other context)
+- Compiler: `src/Core/Compiling/Policy/YourPolicyCompiler.cs` (Exampe: `RateLimitCompiler.cs`)
+- Tests: `test/Test.Core/Compiling/YourPolicyTests.cs` (Exampe: `RateLimitTests.cs`)
+- Documentation: `docs/AvailablePolicies.md`
+
+Refer to existing policies for detailed examples. It is recommended to look at `RateLimit` or `Quota` policies.
+They are contain all possible aspects of a policy compilation implementation.
+
+## Steps to add a new policy
+
+- Create `src/Authoring/Configs/YourPolicyConfig.cs` as a public record.
+  - Required parameters as `required` `init` properties
+  - Optional properties should be `nullable`
+  - Properties allowing policy expressions should have `[ExpressionAllowed]` attribute assigned.
+  - Add XML documentation for the record and its properties.
+
+```csharp
+  /// <summary>
+  /// Description of config.
+  /// </summary>
+  public record YourPolicyConfig
+  {
+      /// <summary>
+      /// Description of your property.
+      /// </summary>
+      [ExpressionAllowed]
+      public required string Property { get; init; }
+
+      /// <summary>
+      /// Optional property description.
+      /// </summary>
+      [ExpressionAllowed]
+      public int? OptionalProperty { get; init; }
+
+      // Add more properties as needed.
+  }
+```
+
+- Add a method signature to section context interfaces in which policy is avaliable (e.g. `src/Authoring/IInboundContext.cs`).
+  Add method to policy fragment context interface to make policy avaliable in policy fragment. 
+  Make sure to add XML documentation.
+
+```csharp
+    /// <summary>
+    /// Description of your policy.
+    /// <param name="config">
+    /// Configuration for the YourPolicy policy.
+    /// </param>
+    /// </summary>
+    void YourPolicy(YourPolicyConfig config);
+```
+
+- Create compiler class `src/Core/Compiling/Policy/YourPolicyCompiler.cs` implementing `IMethodPolicyHandler`.
+  This class will be responsible for translating the C# method call into the corresponding XML policy element.
+  - Make sure that the class is `public` and in `Microsoft.Azure.ApiManagement.PolicyToolkit.Compiling.Policy` namespace.
+    This is required for the automatic adding your policy compiler to the compilation.
+  - Implement the `Handle` method to extract parameters from the method invocation and construct the XML element.
+  - Use `TryExtractingConfigParameter<T>` to extract the config object into initialization object.
+  - Use `AddAttribute` extension method to add attributes to the XML element.
+  - Report diagnostics for missing required parameters using `context.ReportDiagnostic`.
+    For avaliable errors see `CompilationErrors.cs` file.
+  - For complex policies with sub elements, refer to existing compilers for guidance (eg. RateLimitCompiler).
+
+```csharp
+namespace Microsoft.Azure.ApiManagement.PolicyToolkit.Compiling.Policy;
+
+public class YourPolicyCompiler : IMethodPolicyHandler
+{
+    public string MethodName => nameof(IInboundContext.YourPolicy);
+
+    public void Handle(IDocumentCompilationContext context, InvocationExpressionSyntax node)
+    {
+        if (!node.TryExtractingConfigParameter<YourPolicyConfig>(context, "your-policy", out var values))
+        {
+            return;
+        }
+
+        var element = new XElement("your-policy");
+
+        if (!element.AddAttribute(values, nameof(YourPolicyConfig.Property), "propery"))
+        {
+            context.Report(Diagnostic.Create(
+                CompilationErrors.RequiredParameterNotDefined,
+                node.GetLocation(),
+                "your-policy",
+                nameof(YourPolicyConfig.Property)
+            ));
+            return;
+        }
+
+        element.AddAttribute(values, nameof(YourPolicyConfig.OptionalProperty), "optional-property");
+
+        context.AddPolicy(element);
+    }
+}
+```
+
+- Add tests to `test/Test.Core/Compiling/YourPolicyTests.cs`. 
+  - Use a `[DataRow]` for each test case, following the pattern of existing tests.
+  - Check that compiler 
+    - handles compiling policy in all of sections which you added the method to
+    - required aparameters with constant values
+    - optional parameters with constant values
+    - expressions for properties which define [ExpressionAllowed] attribute
+
+```csharp
+[TestClass]
+public class YourPolicyTests : PolicyCompilerTestBase
+{
+    [TestMethod]
+    [DataRow(
+        """
+        [Document]
+        public class PolicyDocument : IDocument
+        {
+            public void Inbound(IInboundContext context) {
+                context.YourPolicy(new YourPolicyConfig()
+                    {
+                        Property = "Value"
+                    });
+            }
+        }
+        """,
+        """
+        <policies>
+            <inbound>
+                <your-policy property="Value" />
+            </inbound>
+        </policies>
+        """)]
+    public void ShouldCompileYourPolicy(string code, string expectedXml)
+    {
+        code.CompileDocument().Should().BeSuccessful().And.DocumentEquivalentTo(expectedXml);
+    }
+}
+```
+
+- Update `docs/AvailablePolicies.md` to include your new policy in the list of implemented policies.

docs/AvailablePolicies.md

@@ -1,57 +1,103 @@
 # Available Policies
 
-The Project is in the development stage.
-That means that not all policies are implemented yet.
-In this document, you can find a list of implemented policies. For policy details, see the Azure API Management [policy reference](https://learn.microsoft.com/azure/api-management/api-management-policies).
-
-#### :white_check_mark: Implemented policies
-
-* authentication-basic
-* authentication-certificate
-* authentication-managed-identity
-* azure-openai-emit-token-metric
-* azure-openai-semantic-cache-lookup
-* azure-openai-semantic-cache-store
-* base
-* cache-lookup
-* cache-lookup-value
-* cache-remove-value
-* cache-store
-* cache-store-value
-* check-header
-* choose
-* cors
-* emit-metric
-* find-and-replace
-* forward-request
-* ip-filter
-* json-to-xml
-* jsonp
-* llm-emit-token-metric
-* llm-semantic-cache-lookup
-* llm-semantic-cache-store
-* mock-response
-* quota
-* rate-limit
-* rate-limit-by-key
-* return-response
-* rewrite-uri
-* send-request
-* set-backend-service
-* set-body
-* set-header
-* set-method
-* set-query-parameter
-* set-variable
-* validate-jwt
-
-Policies not listed here are not implemented yet, we are curious to know which [ones you'd like to use and are happy to review contributions](./../CONTRIBUTING.md).
-
-## InlinePolicy
-
-InlinePolicy is a workaround until all the policies are implemented.
+This document lists policy elements that the toolkit's authoring and compiler support by mapping C# APIs to Azure API
+Management policy elements. The list below was generated from the public authoring interfaces (
+inbound/outbound/backend/on-error/fragment contexts) and reflects which policies the toolkit can compile into XML.
+
+If a policy you need is missing you can either:
+
+- Use `InlinePolicy(...)` to insert raw XML into the compiled document, or
+- Open an issue / contribute a patch (see [CONTRIBUTING.md](../CONTRIBUTING.md)).
+
+Notes:
+
+- The C# compiler maps C# constructs to policy constructs. For example, if/else in C# is compiled to the `choose`
+  policy (with `when` / `otherwise`).
+- `InlinePolicy(string)` allows inserting arbitrary XML when a policy isn't implemented as a first-class API.
+
+## Implemented policies
+
+- authentication-basic
+- authentication-certificate
+- authentication-managed-identity
+- azure-openai-emit-token-metric
+- azure-openai-semantic-cache-lookup
+- azure-openai-semantic-cache-store
+- azure-openai-token-limit
+- base
+- cache-lookup
+- cache-lookup-value
+- cache-remove-value
+- cache-store
+- cache-store-value
+- check-header
+- choose (implemented via C# if/else -> choose/when/otherwise)
+- cors
+- cross-domain
+- emit-metric
+- find-and-replace
+- forward-request
+- get-authorization-context
+- include-fragment
+- inline-policy (method to insert raw XML)
+- invoke-dapr-binding (publish/send to Dapr bindings)
+- ip-filter
+- json-to-xml
+- jsonp
+- limit-concurrency
+- llm-content-safety
+- llm-emit-token-metric
+- llm-semantic-cache-lookup
+- llm-semantic-cache-store
+- llm-token-limit
+- log-to-eventhub
+- mock-response
+- proxy
+- publish-to-dapr
+- quota
+- quota-by-key
+- rate-limit
+- rate-limit-by-key
+- redirect-content-urls
+- remove-header (via SetHeader/RemoveHeader APIs)
+- remove-query-parameter (via SetQueryParameter/Remove APIs)
+- return-response
+- retry
+- rewrite-uri
+- send-one-way-request
+- send-request
+- set-backend-service
+- set-body
+- set-header
+- set-header-if-not-exist
+- set-method
+- set-query-parameter
+- set-query-parameter-if-not-exist
+- set-status
+- set-variable
+- trace
+- validate-azure-ad-token
+- validate-client-certificate
+- validate-content
+- validate-headers
+- validate-jwt
+- validate-odata-request
+- validate-parameters
+- validate-status-code
+- wait
+- xml-to-json
+- xsl-transform
+
+## How to work around missing policies
+
+InlinePolicy is a workaround until all the policies are implemented or new policies are not added yet to toolkit.
 It allows you to include policy not implemented yet to the document.
 
 ```csharp
 c.InlinePolicy("<set-backend-service base-url=\"https://internal.contoso.example\" />");
 ```
+
+## Contributing
+
+If you'd like a specific policy implemented natively in the toolkit, please open an issue or a pull request in this
+repository. See [CONTRIBUTING.md](../CONTRIBUTING.md) and [Add new policy guide](AddPolicyGuide.md) for guidance.