kenzuya/unshackle
1
0
Fork 2
mirror of https://github.com/unshackle-dl/unshackle.git synced 2026-11-12 12:05:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(proxies): share proxy dispatch between dl, search and resolve_proxy

Browse Source 
A bare query skips a failing provider and errors when none answers; an unknown prefix such as us:seattle fails with a hint. The REST path now loads WindscribeVPN.
This commit is contained in:
imSp4rky
2026-09-25 18:14:26 -06:00
parent 80c0dc4ebf
commit 746bf184d2
7 changed files with 351 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide/proxies-and-vpn.md
+12 -8
View File
@@ -96,15 +96,19 @@ flowchart TD
1. **An explicit URI.** unshackle uses anything shaped like `http://...`,
`https://...`, or a `socks...` URI exactly as you give it. unshackle logs
`Using explicit Proxy: ...` and does no lookup.
`Using explicit Proxy: ...` and does no lookup. A `host:port` value such as
`localhost:8080` is also an explicit proxy.
2. **A provider-prefixed query**: `provider:query`, for example `nordvpn:us` or
`gluetun:windscribe:us`. unshackle finds the proxy provider whose name matches
the prefix (case-insensitive). It then asks *only* that proxy provider to find a
proxy for the remainder. If unshackle loads no such proxy provider, or if that
proxy provider returns no proxy, the download errors.
3. **A bare query**: a region like `us`, `gb`, `us:seattle`, or `us1234`. unshackle
asks each loaded proxy provider **in order** and uses the first proxy any of them
returns.
3. **A bare query**: a region like `us`, `gb`, or `us1234`. unshackle asks each
loaded proxy provider **in order** and uses the first proxy any of them returns. A
bare city query such as `us:seattle` does not work: unshackle reads `us` as a proxy
provider name. Use the proxy provider prefix, for example `nordvpn:us:seattle`.
If no proxy provider has a proxy for the query, unshackle stops with
`No proxy provider had a proxy for <query>` and does not continue without a proxy.
unshackle compares the query against a region grammar: a country or location code of two
to four letters, with an optional `_code` part (`res_yyz`), then an optional server
@@ -659,7 +663,7 @@ that server for a day or two as a workaround, until it degrades and you swap in
|---|---|
| `us` | A recommended US server. |
| `us1234` | The specific server `us1234`. |
| `us:seattle` | A recommended server in Seattle. |
| `nordvpn:us:seattle` | A recommended server in Seattle. |
| `228` | A NordVPN numeric country ID. |
The returned proxy is HTTPS on **port 89** (NordVPN disabled its plain-HTTP proxies on
@@ -799,8 +803,8 @@ fall back to the `us` entry.
unshackle ignores case, spaces, hyphens and accents in a city name, so `us:new-york`
matches New York. A city also matches the start of a longer name: `de:frankfurt` matches
Frankfurt am Main. A bare `us` also reaches Surfshark, but a bare `us-bos` or
`us:seattle` can stop at a proxy provider earlier in the order, so use the
Frankfurt am Main. A bare `us` also reaches Surfshark. A bare `us-bos` can stop at a
proxy provider earlier in the order, and a bare `us:seattle` does not work, so use the
`surfsharkvpn:` prefix for those forms.
The returned proxy is HTTPS on **port 443**.
@@ -830,7 +834,7 @@ proxy_providers:
|---|---|
| `us` | A random US server. |
| `us150` / `sg007` | A specific numbered server. |
| `us:seattle` | A random server in Seattle. |
| `windscribevpn:us:seattle` | A random server in Seattle. |
The returned proxy is HTTPS on **port 443**.
docs/reference/configuration/network.md
+2 -3
View File
@@ -102,7 +102,6 @@ Config keys of the Control D proxy provider. See
| `max_profiles` | `int` | `4` | The most profiles unshackle uses: your pairs plus the `unshackle-*` endpoints on the account. It must be 1 or more. unshackle creates an `unshackle-<region>` profile and endpoint only while the total is lower. |
!!! note "Provider loading differs between CLI and REST server"
The `dl` CLI loads all providers, including `windscribevpn` and `gluetun`. The REST API /
remote-client path uses a separate resolver that does **not** load `windscribevpn` or
`gluetun`. ExpressVPN and ProtonVPN also auto-load when their cached session exists, and Hola
The `dl` CLI loads all providers, including `gluetun`. The REST API / remote-client path
does **not** load `gluetun`, because it starts a local Docker container. ExpressVPN and ProtonVPN also auto-load when their cached session exists, and Hola
auto-loads whenever the `hola-proxy` binary is present.