In the Postman SDK, how does ProxyConfigList.resolve choose an entry when several could serve the same URL?

## One entry versus the list of entries The Postman SDK (`postman-collection`) keeps proxy entries in a **`ProxyConfigList`**. Each element is a `ProxyConfig`, which knows only how to answer for itself: `ProxyConfig.test(url)` returns true or false for that one entry. Deciding *which* entry a URL actually gets is the list's job, and it belongs to **`ProxyConfigList.resolve(url)`**. Two different mechanisms are involved, and conflating them is the usual source of confusion: - `ProxyConfig.test` — **does this single entry apply?** - `ProxyConfigList.resolve` — **given several entries that might apply, which one is returned?** ## What resolve actually does 1. Walk the entries in the order they appear in the list. 2. Skip any entry whose `disabled` property is set — a disabled entry is not tested at all, so its patterns are irrelevant. 3. Ask each remaining entry whether it applies (which internally runs its `bypass` check before its `match` check). 4. **Return the first entry that says yes**, and stop. 5. If no entry says yes, resolve nothing — and the runtime then falls back to its **`systemProxy`** resolver. The single word that matters in step 4 is **first**. Not the most specific pattern, not the narrowest host, not the last one written, not a merge of several. Position in the list is the tie-breaker, and it is the *only* tie-breaker. | Behaviour people assume | What the list actually does | |---|---| | the most specific pattern wins | array position wins | | a later entry overrides an earlier one | the earlier one wins and the later is never reached | | a disabled entry still contributes its `bypass` | a disabled entry is skipped entirely | | no entry matching means the call goes direct | the runtime still consults `systemProxy` | ## Order shadowing Because the first hit wins, an entry written broadly and placed early **shadows** every narrower entry after it. A catch-all entry near the top of the list makes the rest of the list decorative: the specific entry someone added for one host is correct, tested, and never reached. The symptom is distinctive. The narrow entry can be verified in isolation — its own `test` returns true for the URL — while the run behaves as though it did not exist. The entry is fine; its position is not. ## The systemProxy fallback When `resolve` finds nothing, the run does not automatically go direct. The runtime falls back to **`systemProxy`**, which supplies a proxy from the environment the run is executing in rather than from the list. Two consequences follow, and both bite in real diagnosis: - **"No entry matched" is not the same as "no proxy was used."** A call can traverse a proxy that appears nowhere in the configured list. - **The same list behaves differently on two machines**, because the fallback reads something outside the list. Reproducing a colleague's result requires knowing not only their entries but what their environment hands the fallback. ## Practical implications - Order the list **most specific first, catch-all last**. The list is evaluated top-down, so this is the only arrangement in which narrow entries are ever reached. - Treat `disabled` as "not present", not as "present but off". It contributes neither `match` nor `bypass`. - When an entry seems to be ignored, check for an earlier entry that also applies before you touch the entry's patterns. - When no entry seems to apply and traffic is still proxied, look at the fallback rather than assuming a hidden match. ## What stays outside this mechanism Which single entry applies is decided here; what the *sending program* reads off the request itself, and how those switches merge down the collection tree, is a separate concern with its own resolution rules. Keep the two apart when reasoning about a run: entry selection is positional and terminates at the first hit.