# Http processing

> MITM, URL/header/body rewrite, mocking

[← Back to index](/llms.txt)

---

# HTTP Processing

Surge provides multiple capabilities for modifying HTTP requests and responses. These modifications follow a specific processing sequence:

1. URL Rewrite
2. Header Rewrite
3. Body Rewrite
4. Script Processing

## Processing Rules

An important distinction exists in how these modifications interact: script processing can only be modified by one script, while if there are multiple hits for other rewrite rules, they will take effect in sequence.

This means that when multiple URL rewrite, header rewrite, or body rewrite rules match a request, all applicable rules execute in order. However, only a single script can process any given request at the script processing stage.


## Body rewrite

# Body Rewrite

**Availability:** iOS 5.10.0+ | Mac 5.6.0+

## Overview

Surge enables rewriting HTTP request and response bodies using regular expressions to replace original content.

### Basic Syntax

Rules follow this format:
```
http-request ^http(s)?://example\.com regex replacement
http-response ^http(s)?://example\.com regex replacement
```

The structure consists of:
1. Direction (`http-request` or `http-response`)
2. URL pattern (regular expression)
3. Search pattern (regex to match)
4. Replacement text

### Multiple Replacements

You can chain multiple regex-replacement pairs on a single line:

```
http-response ^https?://example\.com/ regex1 replacement1 regex2 replacement2
```

### Key Behaviors

- If a request hits multiple body rewrite rules, they will be executed in sequence
- Rules can generate new content even when the original request lacks a body (using patterns like `^$`)

## JQ Body Rewrite

**Availability:** iOS 5.14.0+ | Mac 5.9.0+

Manipulate JSON bodies using JQ expressions:

```
http-request-jq url-pattern jq-expression
http-response-jq url-pattern jq-expression
```

**Example:**
```
http-response-jq ^http://httpbingo.org/anything '.headers |= with_entries(select(.key | test("^X-") | not))'
```


## Header rewrite

# Header Rewrite

Surge enables modification of request or response headers before forwarding them to servers.

## Syntax Structure

A rewrite rule contains:
1. HTTP direction (`http-request` or `http-response`)
2. URL regular expression
3. Action type
4. Header field name
5. Value (omitted for header-del)
6. Replace template (only for header-replace-regex)

Legacy syntax omits the HTTP direction.

## Operations

### header-add
Appends a new header line, even if the field already exists.

```
http-request ^http://example.com header-add DNT 1
```

### header-del
Removes a header line from the request/response.

```
http-request ^http://example.com header-del DNT
```

### header-replace
Replaces an existing header value. Takes no action if the field doesn't exist.

```
http-request ^http://example.com header-replace DNT 1
```

To add-or-replace (ensuring a value exists), combine deletion and addition operations.

### header-replace-regex
Replaces header values using regular expression matching and template substitution. Has no effect if the header field is absent.

```
http-request ^http://example.com header-replace-regex User-Agent Safari Chrome
```

This approach enables pattern-based transformations of header content.


## Mitm

# HTTPS Decryption

## Overview

Surge can decrypt HTTPS traffic through Man-in-the-Middle (MitM) interception.

## Certificate Management

The certificate generator creates a new CA certificate for debugging purposes, available in Surge Dashboard (Mac) and Surge iOS Config Editor. Certificates are generated locally, stored in your profile file and system Keychain, with keys created randomly via OpenSSL.

You may also use an existing CA certificate by exporting it to PKCS#12 format (.p12) with a passphrase (required—cannot be empty). Encode the certificate in base64 and add these settings to your config:

```
[MITM]
ca-p12 = MIIJtQ.........
ca-passphrase = password
hostname = *google.com
h2 = true
```

## Hostname Configuration

Surge only decrypts traffic to hosts listed in the hostname parameter. A typical configuration might look like:

```
hostname = -*.apple.com, -*.icloud.com, *
```

Some applications have a strict security policy to use pinned certificates or CA. Enabling decryption to these hosts may cause problems.

This parameter uses the Host List type—see documentation for detailed rules.

## Configuration Options

**skip-server-cert-verify** (Boolean, default: false)
Skip verification of the remote host's certificate during MitM.

**h2** (Boolean, default: false)
Enable MitM over HTTP/2 protocol for improved concurrent request performance.

**client-source-address**
Restrict MitM to specific devices by IP address or CIDR block (IPv4/IPv6 supported). Use `-` prefix to exclude clients. Includes `127.0.0.1` if enabling for the current device. Supports MAC addresses on Mac version 6.1.0+.

**auto-quic-block** (Boolean, default: true)
Automatically blocks QUIC connections matching the MitM hostname list, forcing fallback to HTTP/2 or HTTP/1.1 for interception.


## Mock

# Mock (Map Local)

## Overview

The Mock feature enables you to simulate HTTP server responses by returning static content. This capability is also referred to as Map Local or API Mocking. For dynamic responses, consider using scripting instead.

## Example Configuration

```
[Map Local]
^http://surgetest\.com/json data-type=text data="{}" status-code=500
^http://surgetest\.com/gif data-type=tiny-gif status-code=200
^http://surgetest\.com/file data-type=file data="data/map-local.json" header="a:b|foo:bar"
^http://surgetest\.com/base64 data="dGVzdA==" data-type=base64
```

## Parameters

### URL Pattern

Each configuration line contains parameters separated by spaces. The first parameter is a regular expression matching the target URL. When an HTTP (or decrypted HTTPS) request matches this pattern, the rule applies.

### `data-type`

Four data types are supported:

- **`file`**: Returns content from a specified file or URL
- **`text`**: Returns UTF-8 encoded text (iOS 5.9.1+, Mac 5.5.1+)
- **`tiny-gif`**: Returns a 1-pixel GIF (iOS 5.9.1+, Mac 5.5.1+)
- **`base64`**: Returns binary data in base64 encoding (iOS 5.9.1+, Mac 5.5.1+)

### `data`

- For `file`: Path to the data file, relative to the configuration directory (absolute paths supported on macOS)
- For `text`: The actual content to return
- For `tiny-gif`: This field is ignored
- For `base64`: Valid base64-encoded data

Use `data-type=text data=""` to return an empty response.

### `header`

Customize HTTP headers in the returned response. Separate multiple key-value pairs with `|`.

## Content-Type Handling

Surge automatically determines Content-Type when not explicitly provided via the `header` parameter:

- **`file`**: Converts file extension to MIME type; defaults to `application/octet-stream`
- **`text`**: Defaults to `text/plain`
- **`tiny-gif`**: Defaults to `image/gif`
- **`base64`**: Defaults to `application/octet-stream`


## Url rewrite

# URL Rewrite

Surge enables rewriting of request URLs using two different methods or rejecting specific requests based on URL patterns.

## Structure

Rewrite rules consist of three components: a regular expression pattern, a replacement value, and a mode type.

## Header Mode

In this mode, Surge will modify the request header and redirect the request to another host if necessary. The client will not notice this rewrite action. The Host field in the request header is automatically updated to match the new URL.

Example:
```
^http://www\.google\.cn http://www.google.com header
```

## 302 Redirect Mode

This method returns a 302 HTTP redirect response to the client. HTTPS requests can be redirected if the hostname has MitM enabled.

Example:
```
^http://yachen\.com https://yach.me 302
```

## Reject Mode

Matching requests are blocked entirely. The replacement parameter is ignored in this mode. HTTPS requests are rejected when the hostname has MitM enabled.

Example:
```
^http://ad\.com/ad\.png _ reject
```