# Pingap Location Module
This module provides an intelligent and flexible request routing system for reverse proxies and API gateways. It enables routing decisions based on request hostnames and URL paths, with support for powerful matching options, URL rewriting, and other essential proxying features.
## Features
- **Dynamic Host Matching**: Match requests based on the `Host` header using:
- **Exact Match**: e.g., `example.com`
- **Regex Match**: e.g., `~(?<subdomain>.+)\.example\.com`, with support for named captures.
- **Flexible Path Matching**: Match requests based on the URL path with different strategies:
- **Exact Match**: e.g., `=/api/login`
- **Prefix Match**: e.g., `/static`
- **Regex Match**: e.g., `~/users/(?<id>\d+)`, with support for named captures.
- **URL Rewriting**: Dynamically modify the request path before proxying, including substituting variables from named captures.
- **Request Throttling**: Limit the maximum number of concurrent requests a location will process.
- **Body Size Limiting**: Enforce a maximum size for the client request body to prevent abuse.
- **Header Modification**: Add or set custom HTTP headers before forwarding a request to an upstream service.
- **gRPC-Web Support**: Enable seamless proxying of gRPC-Web requests, translating them to standard gRPC.
- **Extensible Plugins**: Attach custom processing logic through a plugin system.
## Core Concepts
### `Location`
The `Location` is the central struct that encapsulates a complete set of routing rules. It is created from a `LocationConf` and contains all the logic to determine if an incoming request is a match and how it should be handled.
### `HostSelector`
This enum determines how to match the request's `Host` header. It can be an exact string match or a regular expression. When using a regex, named capture groups (e.g., `(?<name>...)`) can be used to extract variables from the hostname for use in rewriting or other logic.
For example, a `HostSelector` with the pattern `~(?<name>.+).npmtrend.com` will match `charts.npmtrend.com` and capture `charts` into the `name` variable.
### `PathSelector`
This enum determines how to match the request's URL path. The matching strategy is determined by a special prefix in the configuration string:
- **`=` (Exact Match)**: The path must be an exact match. e.g., `=/api/v1/status`.
- **`~` (Regex Match)**: The path is matched against a regular expression. e.g., `~/api/users/(\d+)`.
- **(Prefix Match)**: If no prefix is provided, the request path must start with the given string. e.g., `/api/`.
- **(Any)**: An empty path string matches any request path.