-js-proxy-router & -js-access-filter behaviour

[robvanoostenrijk]

First of all the scripting in dumbproxy is fantastic, allowing for dynamic advanced configuration scenarios with ease (split routing etc).

However, when using -js-proxy-router, I found some behaviour that I'd like to understand better.

Given the following simple proxy.js script:

function getProxy(req, dst, username) {
	alert(`Req: ${dst.originalHost}`);
	return "";
}

The output results are:

PROXY   : 2026/06/20 06:23:04 handler.go:244: INFO     Request: 192.168.10.189:50193 => 172.19.0.11:1080 "" HTTP/1.1 CONNECT //www.example.com:443
JSROUTER: 2026/06/20 06:23:04 printer.go:27: ERROR    Req: www.example.com
JSROUTER: 2026/06/20 06:23:04 printer.go:27: ERROR    Req: www.example.com

From this output it seems that getProxy() is called twice? Is there a reason this is happening?

Additionally adding -js-access-filter additionally in the mix with a similar script shows additional logs there as well:

PROXY   : 2026/06/20 06:22:07 handler.go:244: INFO     Request: 192.168.10.189:50159 => 172.19.0.11:1080 "" HTTP/1.1 CONNECT //www.example.com:443
JSROUTER: 2026/06/20 06:22:07 printer.go:27: ERROR    Req: www.example.com
JSACCESS: 2026/06/20 06:22:07 printer.go:27: ERROR    Req: www.example.com
JSACCESS: 2026/06/20 06:22:07 printer.go:27: ERROR    Req: www.example.com
JSACCESS: 2026/06/20 06:22:07 printer.go:27: ERROR    Req: www.example.com
JSACCESS: 2026/06/20 06:22:07 printer.go:27: ERROR    Req: www.example.com
PROXY   : 2026/06/20 06:22:07 handler.go:86: WARNING  Access denied: failed to dial www.example.com:443: 4 errors occurred:
	* access denied: denied by JS filter
	* access denied: denied by JS filter
	* access denied: denied by JS filter
	* access denied: denied by JS filter

I'd have expected one JSROUTER and one JSACCESS log entry. Note that only one JSROUTER log is output in this case.

Posting this as a discussion, because it might be by design and not an issue. Just looking to clarify the behaviour.

[Snawoot]

Hello,

Indeed, it's actually a very good topic to discuss.

README has only brief hint why does that happen:

Note

getProxy can be invoked once or twice per request. If first invocation with null resolved host address returns "direct" mode and no other dialer has suppressed name resolving, name resolution will be performed and getProxy will be invoked once again with resolved address for the final decision.

This shouldn't be much of concern, though, if getProxy function doesn't use dst.resolvedHost and returns consistent values across invocations with the rest of inputs having same values.

But I see it deserves more explanation.

How dumbproxy works with outbound connections

The problem is following: sometimes dumbproxy needs to know what will be the destination IP address of outgoing direct connection. It's needed for:

• Security filter -deny-dst-addr which by default denies any proxied connections to localhost and private networks.
• Destination address filtering in JS access filter.
• Routing policies based on destination address in JS proxy router.

Note that we need to resolve address only for direct connections made by dumbproxy server. But whenever we pass the connection to some upstream proxy it will be a mistake to resolve domain names:

• Upstream proxy server may have own DNS view and some requested domains may be resolved only from upstream proxy location.
• Domain name may have no IP address at all (e.g. .onion domains of Tor).
• Proxy server may reside in a different region and geo-aware authoritative DNS server may steer connection to wrong region if it was resolved in one region and address used for connection from another region.

For these reasons domain name resolution normally should happen only for dial outs made directly by dumbproxy instance. How it works internally: dumbproxy builds DAG (basically almost always a chain) of connection wrappers which build outbound connections with the help of each other. Some of them add a proxy into dialing chain, some change dialout settings and so on. But in addition to connection request they also support special protocol to answer simple question: "do you or other dialer in your chain require domain name NOT to be resolved and passed literally to another system?". Every remote proxy dialer answer "yes". Direct dialers answer "no".

Now, what happens when upstream proxy is decided with JS script? The dialer executing that JS gets asked before actual connection request: "do you need domain name preservation?". In order to answer that question JS dialer needs to know whether it will be a direct proxy returned by JS script or some upstream proxy. So it gathers all available data for request and calls getProxy to see what it will return. Such invocations have dst.preview property equal true (1.48.0+). And then, actual request will invoke getProxy again and either have dst.resolvedHost populated or not. That way we resolve chicken-and-egg problem with resolving in JS proxy router by asking what proxy it will be twice.

Tip

You can influence that behavior and always resolve names in advance with force-resolve:// pseudo-proxy in the end of proxy chain. In that case no "preview" request to getProxy will be made. See also GeoIP support in wiki for example how to trigger name resolution programmatically from JS script.

What happens to connections which have their destination resolved

If connection request had it destination address resolved (e.g. due to direct connect or forced resolution), the resolver rewrites single connection attempt by domain name into a sequence of attempts to dial each literal IP address, preserving original symbolic destination only in the request context. We make sure that we dial exactly addresses we resolved, not just pass them futher. It has to be like this in order to:

• Prevent attacks similar to DNS rebinding when domain IP addresses change rapidly to bypass filtering policies.
• Decide on each destination address independently in case if domain name resolves both to some real addresses and local network addresses, and deny malicious destinations with filters.

For that reason access filter will be invoked 4 times for example.com because it has 2 IPv4 addresses and 2 IPv6 addresses.

Tip

It is possible to signal dumbproxy stop asking access function about further IP addresses in that request. throw newStopAddressIteration(); will stop address iteration in that request and deny the request.

[robvanoostenrijk]

Great answer, now it makes a lot of sense! Would be great to include this somewhere in the readme, in case anyone else comes across this.

I did update my access script to use throw newStopAddressIteration();, since I block domains and not per IP address.