Map Local

Map Local answers a request with content that MeowX already has, without contacting the server. It is often used to replace an ad or configuration API response with a harmless one, or to mock an endpoint while debugging.

Behavior

• The first matching Map Local rule applies, and only when no URL rewrite already answered the request locally.
• Rules match against the original URL (see How URLs are matched).
• The response is a local response: body rewrites and scripts don’t run on it. If the request has a body, it is read and discarded; above 1 MB the connection is closed after the response.
• A host covered entirely by a Map Local rule (and by no URL rewrite) is answered without connecting upstream at all; see Hosts answered entirely locally.

Surge [Map Local]

[Map Local]
^https:\/\/api\.example\.com\/v1\/splash data-type=text data="{}" header="Content-Type:application/json"
^https:\/\/ad\.example\.com\/banner\.png data-type=tiny-gif
^https:\/\/api\.example\.com\/v1\/config data-type=file data="https://example.com/mock/config.json"
^https:\/\/api\.example\.com\/v1\/gone data-type=text data="" status-code=410

Each line is the URL regex followed by key=value parameters. Values containing spaces or quotes go in double quotes; a value like data="{"code":0}" with unescaped inner quotes is understood too.

data-type	data	Default Content-Type
file (default)	An https:// URL. The app downloads the content (see Remote data). Relative paths, local file paths and http:// are unsupported.	From the URL’s file extension: json, js, html/htm, css, txt, xml, plist, gif, png, jpg/jpeg, webp, svg, mp4; otherwise application/octet-stream
text	The text itself	text/plain
tiny-gif	Not needed: a 1×1 transparent GIF	image/gif
base64	Base64-encoded bytes	application/octet-stream

Other parameters:

Parameter	Meaning
header="Name:Value|Name2:Value2"	Response headers, separated by |. If the value contains no colon at all, it is decoded as Base64 into lines of Name: value. A Content-Type here overrides the default. Content-Length, Transfer-Encoding and Connection are ignored; MeowX sets them itself.
status-code=	Status code from 200 to 999. Default 200.

Loon plugins

mock-response-body in classic [Rewrite]

[Rewrite]
^https:\/\/api\.example\.com\/v1\/splash mock-response-body data-type=json data="{}"
^https:\/\/api\.example\.com\/v1\/home mock-response-body data-type=json data-path=https://example.com/mock/home.json
^https:\/\/api\.example\.com\/v1\/logo mock-response-body data-type=png data="iVBORw0KGgo…" mock-data-is-base64=true

Parameter	Meaning
data-type=	Sets the Content-Type (default text): json, text, plain, text/event-stream, css, html, javascript, png, gif, jpeg, tiff, svg, mp4. Other values are unsupported.
data=	Inline content.
data-path=	An https:// URL to download the content from, instead of data.
mock-data-is-base64=true	The content (inline or downloaded) is Base64 and is decoded first.
status-code=	200 to 999, default 200.

mock-request-body is unsupported.

response.body.mock in the new syntax

[Rewrite]
response if ${url} ~= /^https:\/\/api\.example\.com\/v1\/splash/ then response.body.mock("json", "{}")

The first argument is one of the data-type values above, the second is the body text. The status is always 200. Only the ${url} ~= /…/ condition is supported.

Remote data

When a rule refers to remote content, the app downloads it when you install, update or enable the module, caches it on the device and embeds it into the compiled rules. The tunnel itself never downloads anything.

• Only https:// URLs, with a successful (2xx) response, are accepted.
• Until the content is available, the rule shows Data not downloaded and doesn’t take effect. If a download fails, a banner (“Map Local data not downloaded”) offers Retry.
• Each Map Local item may be at most 512 KB on iOS or 2 MB on macOS.
• All Map Local content together may be at most 2 MB on iOS or 16 MB on macOS. Rules beyond these limits are reported as unsupported with the reason.
• These limits also apply to text and base64 data written inline in a module.

Note

If a remote module update changes a Map Local rule so that its data now comes from a host the old version didn’t use, the update waits for your confirmation. See Remote updates.