Traffic Rules

Modify network traffic with breakpoints, URL mapping, blocking, throttling, and header modification.

Traffic Rules

Rockxy’s rule engine intercepts matching requests in the proxy pipeline and applies actions before they reach the server or return to the client. Rules are evaluated in priority order against every HTTP and HTTPS request that passes through the proxy.

Entry Points

Action	How to Access
Rules sidebar	Left navigation panel > Rules
Breakpoints window	Tools > Breakpoints… (Cmd+Shift+B)
Map Local window	Tools > Map Local… (Cmd+Opt+L)
Map Local quick-create	Right-click a captured request > Map Local…
Map Remote window	Tools > Map Remote… (Cmd+Opt+R)
Map Remote quick-create	Right-click a captured request > Map Remote…
Block List window	Tools > Block List…
Modify Headers window	Tools > Modify Headers…
Network Conditions window	Tools > Network Conditions… (Cmd+Opt+N)
Network Conditions quick-create	Right-click a captured request > Tools > Network Conditions…
Add Breakpoint for selected	Tools > Add Breakpoint for Selected Request, or right-click > Add Breakpoint

Rule Types

Breakpoint

Pause a request or response for live editing before forwarding. Inspect and modify headers, body, URL, and method in real time.

Map Local

Serve a response from a local file instead of forwarding to the server. Returns the file contents with configurable status code and headers.

Map Remote

Redirect a matching request to a different URL. The client is unaware of the redirect — Rockxy proxies the rewritten request transparently.

Block

Block matching requests and return a custom HTTP status code. The request never reaches the server.

Throttle

Add artificial latency to matching requests. Simulate slow network conditions without changing the actual response.

Modify Header

Add, remove, or replace headers on the request, the response, or both. Applies the modification transparently in the proxy pipeline.

Network Conditions

Simulate slow networks with latency presets (3G, EDGE, LTE, WiFi, Custom). Dedicated window with one-active enforcement and quick-create from requests.

Creating Rules

1. Open the Rules sidebar from the left navigation panel.
2. Click Add Rule at the bottom of the rule list.
3. Configure the match condition — URL pattern, HTTP method, or header match.
4. Select the action type from the dropdown (Breakpoint, Map Local, Map Remote, Block, Throttle, or Modify Header).
5. Fill in the action-specific configuration (file path, target URL, delay, header operations, etc.).
6. Set the rule priority by dragging it to the desired position in the list.
7. Click Save. The rule takes effect immediately for all new requests.

Rule Matching

Each rule has a match condition that determines which requests it applies to. Match conditions support three criteria:

• URL Pattern — a regular expression matched against the full request URL (scheme, host, path, query string).
• HTTP Method — restrict to GET, POST, PUT, DELETE, PATCH, or any other method.
• Header Name/Value — match requests that contain a specific header with an optional value pattern.

Rules are evaluated in priority order. The first rule whose match condition is satisfied wins — subsequent rules are skipped for that request.

URL patterns use standard regular expressions. To match a literal dot in a domain name, escape it with a backslash: api\.example\.com. To match any path under a domain, use https://api\.example\.com/.*.

Breakpoints

Breakpoints pause a request at the proxy layer so you can inspect and edit it before it continues.

Workflow:

1. A request matching the breakpoint rule arrives at the proxy.
2. Rockxy pauses the request and queues it in the Breakpoints window (Cmd+Shift+B).
3. The window uses a two-column layout: a queue list on the left showing all paused requests (with elapsed time), and an editor on the right with editable URL, method, headers, query parameters, and body.
4. Modify any field, then click Execute to forward the modified request, Cancel to drop it silently, or Abort to return a 503 to the client.
5. Breakpoints can be set to pause on the request phase, the response phase, or both. Response breakpoints let you edit the status code, headers, and body before the response reaches the client.
6. Multiple requests can be paused simultaneously — resolve them individually or use Resolve All.

Breakpoints are a fast way to mock API behavior during development. Pause a request, edit the response body to return test data, and continue — no server changes needed.

Map Local

Map Local serves a response from a file on disk instead of forwarding the request to the server. Open the dedicated editor from Tools > Map Local… or right-click a captured request and choose Map Local… to create a rule with prefilled fields.

Quick-create: Right-click any captured request in the traffic list and choose Map Local…. The Map Local window opens with the editor prefilled from the selected request — URL pattern, method, and name are auto-populated.

Match modes:

Mode	Behavior
Exact Path	Matches the exact scheme + host + path. Query string is ignored. /api/users does not match /api/users/123.
Include Subpaths	Matches the path and everything under it. /api/users also matches /api/users/123 and /api/users/123/orders.
Regex Advanced	Full regular expression against the absolute URL. For advanced matching patterns.

Map-to modes:

Mode	Behavior
Local File	Serve a single file. Browse to select the file. Content-Type is inferred from the file extension.
Local Directory	Map a URL subtree to a directory. Subpaths resolve to local files. Falls back to index.html for directory requests.
Current Response Snapshot	Save the captured response body as a local file and create a rule pointing to it. Available when the selected request has a response body.

Configuration:

• File/Directory Path — absolute path to the local file or directory.
• Status Code — HTTP status code to return (default: 200).
• Content-Type — automatically inferred from the file extension (e.g., .json → application/json, .html → text/html). Applies to both file and directory modes.

Use cases:

• Mock API responses during frontend development without a running backend.
• Test error states by mapping an endpoint to a file containing an error response.
• Work offline by mapping critical endpoints to cached response files.
• Snapshot a live response and iterate on it locally without re-fetching.

Map Remote

Map Remote redirects matching requests to a different server by rewriting URL components. Open the dedicated editor from Tools > Map Remote… or right-click a captured request and choose Map Remote… to create a rule with prefilled fields.

Quick-create: Right-click any captured request in the traffic list and choose Map Remote…. The Map Remote window opens with the editor prefilled from the selected request.

Structured destination editing:

Each URL component can be overridden independently. Leave a field blank to keep the original request value.

Component	When Set	When Blank
Protocol	Use the specified protocol (http or https)	Keep the original request protocol
Host	Route to the specified host	Keep the original host
Port	Connect on the specified port	Use the default port for the protocol
Path	Replace the request path	Keep the original path
Query	Replace the query string	Keep the original query

Preserve Host Header — when enabled, the Host header sent to the destination server retains the original request’s host value instead of the remapped host. This is useful when the backend validates the Host header for routing or security.

Match modes:

Mode	Behavior
Exact Path	Matches the exact scheme + host + path. Query string is ignored.
Include Subpaths	Matches the path and everything under it.
Regex Advanced	Full regular expression against the absolute URL.

Examples:

Original URL	Changed Component	Purpose
https://api.prod.com/v2/users	Host → api.staging.com	Route production traffic to staging
https://api.example.com/v1/data	Path → /v2/data	Test against a newer API version
https://cdn.example.com/bundle.js	Protocol → http, Host → localhost, Port → 8080	Serve local development build

HTTP ↔ HTTPS remapping — Map Remote supports cross-protocol redirection. A plain HTTP request can be remapped to an HTTPS upstream, and vice versa. The proxy handles TLS negotiation automatically.

Use cases:

• Route production API traffic to a staging or development server.
• Test your app against a different API version without code changes.
• Redirect CDN requests to a local development server.
• Switch between environments (staging, QA, production) by changing only the host.

Block

Block prevents matching requests from reaching the server and returns a configurable HTTP status code (default: 403 Forbidden).

Use cases:

• Block analytics and tracking endpoints during debugging to reduce noise in the traffic list.
• Block third-party ad or SDK requests to isolate your app’s own network behavior.
• Simulate server-side blocking to test client error handling.

Throttle

Throttle adds artificial delay to matching requests. The proxy holds the request for the configured duration before forwarding it, simulating slow network conditions.

Configuration:

• Delay (ms) — milliseconds of latency added to each matching request.

Simulated Condition	Suggested Delay
Fast 4G	50–100 ms
Slow 4G	200–500 ms
3G	500–1500 ms
Edge / very slow	2000–5000 ms

Modify Header

Modify Header changes request or response headers for matching requests. Each rule can contain multiple header operations that are applied in order.

Open the dedicated editor from Tools > Modify Headers… to create and manage header modification rules.

Operations:

Operation	Behavior
Add	Appends a header. If the header already exists, a second value is added.
Remove	Removes all instances of the named header (case-insensitive match).
Replace	Removes existing values and sets a new one. If the header does not exist, it is added.

Phase — each operation targets a specific direction:

Phase	When Applied
Request	Before the request is forwarded to the server
Response	When the response arrives from the server, before it reaches the client
Both	Applied to both the outgoing request and the incoming response

Creating a Modify Header rule:

1. Open Tools > Modify Headers…
2. Click + or the Add Rule toolbar button.
3. Enter a name and a URL pattern (regex). Use .* to match all traffic.
4. Add one or more header operations. For each, pick the phase, operation type, header name, and value.
5. Click Add Rule. The rule takes effect immediately.

Operations within a rule are applied top to bottom. If two operations modify the same header, the later one wins.

WebSocket upgrade responses (HTTP 101) are not modified to avoid interfering with the protocol handshake.

Presets — common header rules you can create instantly from the Presets menu:

Preset	What It Does
Add CORS Headers	Adds Access-Control-Allow-Origin: * to all responses
Remove Authorization	Strips the Authorization header from all outgoing requests
Strip Server Header	Removes the Server header from all incoming responses

Use cases:

• Add authentication headers to test protected endpoints without modifying your app.
• Strip tracking or fingerprinting headers from responses.
• Inject CORS headers to bypass cross-origin restrictions during local development.
• Add feature flags via custom headers to toggle server behavior.
• Remove caching headers to force fresh responses during debugging.

Rule Persistence

Rules are stored as JSON at ~/Library/Application Support/Rockxy/rules.json. This file is human-readable and version-control friendly.

Import/Export:

• Export — right-click a rule or selection of rules and choose Export Rules. Saves a .json file you can share.
• Import — click Import Rules in the Rules sidebar and select a .json file. Imported rules are appended to the existing list.

Share rule files between machines or team members to standardize debugging configurations.

Rule Priority

Rules are evaluated top to bottom. The first matching rule wins — no further rules are checked for that request.

• Reorder by dragging rules in the sidebar list.
• Disable a rule without deleting it by toggling the checkbox next to its name.
• Delete by right-clicking and selecting Delete Rule, or pressing the Delete key with the rule selected.

If multiple rules could match the same request, only the highest-priority (topmost) rule applies. Order your most specific rules above broader catch-all rules.

Next Steps

Request Replay

Re-send captured requests with optional modifications for testing.

Traffic Capture

How Rockxy captures HTTP, HTTPS, and WebSocket traffic.