feat(docs): Update Middleware Documentation

api-management/plugins/plugin-developer-guide.mdx

@@ -0,0 +1,108 @@
+---
+title: Plugin Developer Guide
+description: A comprehensive guide for developers building custom plugins for the Tyk Gateway.
+---
+
+import { Callout } from '/components/callout';
+
+This guide provides an in-depth technical reference for developers building custom plugins for the Tyk Gateway. It is intended for developers who want to extend the functionality of the Tyk Gateway with custom logic.
+
+This guide covers the following topics:
+
+*   An overview of the Tyk Gateway's middleware architecture.
+*   A detailed reference of all built-in middleware.
+*   Information on the data available to custom plugins.
+*   Best practices for plugin development.
+
+For information on how to write plugins in a specific language, see the following guides:
+
+*   [Go Plugins](/api-management/plugins/golang)
+*   [Python Plugins](/api-management/plugins/python)
+*   [gRPC Plugins](/api-management/plugins/grpc)
+
+## Data Available to Plugins
+
+Custom plugins have access to a rich set of data, including the request and response objects, the session object, and metadata.
+
+### Request and Response Objects
+
+The request and response objects provide access to the HTTP request and response, including headers, body, and other information.
+
+### Session Object
+
+The session object contains information about the authenticated user, including their API key, rate limits, and access rights. The session object is only available in the `PostKeyAuth`, `Post`, and `Response` stages.
+
+### Metadata
+
+The metadata object is a key-value store that can be used to pass data between middleware and plugins. The metadata object is available in all stages of the middleware execution chain.
+
+## Best Practices for Plugin Development
+
+*   **Keep plugins small and focused.** Each plugin should have a single responsibility.
+*   **Handle errors gracefully.** Plugins should not crash the Tyk Gateway.
+*   **Write unit tests for your plugins.** This will help to ensure that your plugins are working correctly.
+*   **Use the metadata object to pass data between plugins.** This is more efficient than modifying the request or response objects directly.
+
+## Middleware Execution Order
+
+The Tyk Gateway processes requests in a series of stages, with middleware executing in a specific order. Understanding this execution order is crucial for developing custom plugins that interact with the request and response lifecycle.
+
+The middleware execution chain is divided into five stages:
+
+1.  **Pre (Pre-authentication)**: Executes before any authentication checks. This stage is ideal for tasks like header injection, request validation, or IP filtering.
+2.  **AuthCheck (Authentication)**: Responsible for authenticating the client. Custom authentication plugins can be injected here.
+3.  **PostKeyAuth (Post-authentication)**: Executes after a successful authentication. This stage can be used for tasks like granular access control or rate limiting.
+4.  **Post (Final Request Processing)**: Performs final transformations and checks before proxying the request to the upstream service.
+5.  **Response**: Executes on the response from the upstream service before it is returned to the client.
+
+The following diagram illustrates the middleware execution chain and the points where custom plugins can be injected.
+
+![Tyk Middleware Execution Chain](/assets/images/middleware-chain.png)
+
+## Built-in Middleware Reference
+
+The following table provides an exhaustive list of all built-in middleware in the Tyk Gateway, along with their execution stage and data access capabilities.
+
+| Middleware | Execution Stage | Session Access | Context Vars Access | Metadata Access | Configurable |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| VersionCheck | Pre | No | Yes | No | Yes |
+| CORSMiddleware | Pre | No | Yes | No | Yes |
+| RateCheckMW | Pre | Yes | Yes | No | Yes |
+| IPWhiteListMiddleware | Pre | No | No | No | Yes |
+| IPBlackListMiddleware | Pre | No | No | No | Yes |
+| CertificateCheckMW | Pre | No | No | No | Yes |
+| OrganizationMonitor | Pre | No | No | No | Yes |
+| Oauth2KeyExists | AuthCheck | Yes | Yes | Yes | Yes |
+| ExternalOAuthMiddleware | AuthCheck | Yes | Yes | Yes | Yes |
+| BasicAuthKeyIsValid | AuthCheck | Yes | Yes | Yes | Yes |
+| HTTPSignatureValidationMiddleware | AuthCheck | Yes | Yes | Yes | Yes |
+| JWTMiddleware | AuthCheck | Yes | Yes | Yes | Yes |
+| OpenIDMW | AuthCheck | Yes | Yes | Yes | Yes |
+| StripAuth | AuthCheck | No | No | No | Yes |
+| KeyExpired | PostKeyAuth | Yes | No | No | Yes |
+| AccessRightsCheck | PostKeyAuth | Yes | No | No | Yes |
+| GranularAccessMiddleware | PostKeyAuth | Yes | No | No | Yes |
+| RateLimitAndQuotaCheck | PostKeyAuth | Yes | No | No | Yes |
+| RateLimitForAPI | Post | No | No | No | Yes |
+| GraphQLMiddleware | Post | No | Yes | Yes | Yes |
+| ValidateJSON | Post | No | Yes | No | Yes |
+| RequestSigning | Post | No | Yes | No | Yes |
+| ValidateRequest | Post | No | Yes | No | Yes |
+| TransformMiddleware | Post | No | Yes | Yes | Yes |
+| URLRewriteMiddleware | Post | No | Yes | No | Yes |
+| mockResponseMiddleware | Post | No | Yes | No | Yes |
+| ResponseMiddleware | Response | Yes | Yes | Yes | Yes |
+
+## Custom Plugin Injection Points (Hooks)
+
+Custom plugins can be injected into the middleware chain at specific points, known as hooks. These hooks allow you to execute custom logic at different stages of the request and response lifecycle.
+
+The following hooks are available for custom plugins:
+
+*   **Pre-request Hook**: Executes at the beginning of the `Pre` stage.
+*   **Authentication Hook**: Executes during the `AuthCheck` stage.
+*   **Post-authentication Hook**: Executes at the beginning of the `PostKeyAuth` stage.
+*   **Post-request Hook**: Executes at the beginning of the `Post` stage.
+*   **Response Hook**: Executes at the beginning of the `Response` stage.
+
+Each hook provides access to the request and response objects, as well as the session and metadata. The data available at each hook is detailed in the middleware reference table above.

api-management/traffic-transformation.mdx

@@ -1,19 +1,15 @@
 ---
-title: "Transform Traffic by using Tyk Middleware"
-description: "Learn how to transform API traffic using Tyk's middleware capabilities."
-keywords: "Overview, Allow List, Block List, Ignore Authentication, Internal Endpoint, Request Method , Request Body , Request Headers , Response Body, Response Headers, Request Validation, Mock Response, Virtual Endpoints, Go Templates, JQ Transforms, Request Context Variables"
+title: "Traffic Transformation"
+description: "An overview of how to transform API traffic using Tyk's middleware capabilities."
+keywords: "Overview, Middleware, Plugins, Traffic Transformation"
 sidebarTitle: "Overview"
 ---
 
 ## Overview
 
-When you configure an API on Tyk, the Gateway will proxy all requests received at the listen path that you have defined through to the upstream (target) URL configured in the API definition. Responses from the upstream are likewise proxied on to the originating client. Requests and responses are processed through a powerful [chain of middleware](/api-management/traffic-transformation#request-middleware-chain) that perform security and processing functions.
+When you configure an API on Tyk, the Gateway processes all requests through a powerful chain of middleware. This middleware performs security checks, transformations, and other processing on the request before it reaches your upstream service, and on the response before it is returned to the client.
 
-Within that chain are a highly configurable set of optional middleware that can, on a per-endpint basis:
-- apply processing to [API requests](#middleware-applied-to-the-api-request) before they are proxied to the upstream service
-- apply customization to the [API response](#middleware-applied-to-the-api-response) prior to it being proxied back to the client
-
-Tyk also supports a powerful custom plugin feature that enables you to add custom processing at different stages in the processing chains. For more details on custom plugins please see the [dedicated guide](/api-management/plugins/overview#).
+This page provides a high-level overview of the middleware execution chain and the most commonly used middleware for transforming traffic. For a detailed technical reference of all middleware and custom plugin development, see the [Plugin Developer Guide](/api-management/plugins/plugin-developer-guide).
 
 ### Middleware applied to the API Request
 
@@ -102,6 +98,54 @@ The [Response Body Transform](/api-management/traffic-transformation/response-bo
 #### Response Header Transform
 
 The [Response Header Transform](/api-management/traffic-transformation/response-headers) middleware allows you to modify the header information provided in the response before it leaves the Gateway and is passed to the client.
-### Request Middleware Chain
 
-<img src="/img/diagrams/middleware-execution-order@3x.png" alt="Middleware execution flow" />
+## Middleware Execution Chain
+
+The Tyk Gateway processes requests in five distinct stages. The following diagram illustrates the middleware execution chain and shows where custom plugins can be injected.
+
+![Tyk Middleware Execution Chain](/assets/images/middleware-chain.png)
+
+## Commonly Used Middleware
+
+The following is a curated list of the most commonly used, user-configurable middleware, organized by execution stage.
+
+### Pre (Pre-authentication)
+
+*   **CORS**: Manages Cross-Origin Resource Sharing for your APIs.
+*   **IP Whitelisting/Blacklisting**: Restricts access to your APIs based on IP address.
+*   **Request Size Limiting**: Enforces size limits on incoming requests.
+
+### AuthCheck (Authentication)
+
+*   **OAuth 2.0**: Secures your APIs using the OAuth 2.0 protocol.
+*   **JWT**: Validates JSON Web Tokens.
+*   **Basic Authentication**: Uses standard basic authentication.
+
+### PostKeyAuth (Post-authentication)
+
+*   **Rate Limiting and Quotas**: Enforces rate limits and quotas on a per-key basis.
+*   **Access Rights**: Controls access to specific endpoints based on the API key.
+
+### Post (Final Request Processing)
+
+*   **Header Transformations**: Modifies request and response headers.
+*   **URL Rewriting**: Rewrites the request URL before it is proxied to the upstream service.
+*   **Mock Responses**: Returns a mock response without proxying the request to the upstream service.
+
+### Response
+
+*   **Response Transformations**: Modifies the response body before it is returned to the client.
+
+## Custom Plugins
+
+Tyk allows you to inject custom logic into the middleware chain using custom plugins. This is a powerful feature that enables you to implement custom authentication, transformations, and other logic.
+
+Custom plugins can be injected at the following points in the middleware chain:
+
+*   **Pre-request**: Before any other processing.
+*   **Authentication**: To implement custom authentication.
+*   **Post-authentication**: After a successful authentication.
+*   **Post-request**: Before the request is proxied to the upstream service.
+*   **Response**: On the response from the upstream service.
+
+For more information on developing custom plugins, see the [Plugin Developer Guide](/api-management/plugins/plugin-developer-guide).