NodeMaven Rust SDK
Builds the proxy username a gateway expects, and refuses the input it would silently drop.
Proxy opens no socket. It builds the username a proxy gateway expects, refuses
the input that gateway would mishandle, and hands the result to whatever HTTP
client you already use. One call reaches the network, by name and never on
construction: proxy.check() opens a single CONNECT and reports what came back.
Works with reqwest · ureq · curl · chromiumoxide · thirtyfour - and anything else that takes a proxy URL, because that is all it hands back.
cargo add nodemaven
The API reference is on docs.rs; what follows is the part you need before adding the dependency.
Quick start
login and password are the Proxy Username and Proxy Password assigned
under Proxy Setup in the dashboard - a separate
pair from the account you sign in with. The other option there is IP
whitelisting, which needs no credentials in the username at all; both are
described in
authentication methods.
use Proxy;
let proxy = builder
.login
.password
.param
.param
.build?;
let client = builder
.proxy
.build?;
Credentials can come from NODEMAVEN_LOGIN and NODEMAVEN_PASSWORD instead, so
nothing is in your source, and the gateway address from NODEMAVEN_HOST and
NODEMAVEN_PORT:
let proxy = builder.param.build?;
The same identity, for other clients:
proxy.url; // http://user:pass@gate.nodemaven.com:8080 - reqwest, ureq, curl
proxy.browser; // { server, username, password } - unencoded, for a browser driver
proxy.username; // the username on its own
proxy.server; // host:port, no credentials
url() encodes the credentials for use in a URL; browser() returns them raw,
because a browser driver takes the three fields separately and encodes them
itself.
Parameters
What the shipped NodeMaven definition accepts. Every name here was confirmed against the gateway rather than transcribed:
| parameter | what it selects | values measured to work |
|---|---|---|
country |
country code, or any |
us, de, ... |
region |
area inside the country | a name |
city |
city inside the country - send it with its region |
a name |
isp |
the exit's ISP | a name |
type |
mobile or residential exits, which are different pools | mobile, residential |
sid |
the sticky session - see below | any string with no - |
ttl |
how long that session is held | 1m, 10m, 10h, 24h |
filter |
IP quality | low, medium, high |
speed |
claims a connection speed class | fast, slow |
ipv4 |
claims to force IPv4 | true |
ipv4 and speed are accepted by the gateway, but their effects have not been
independently verified, and the table says claims to for that reason.
Parameter names are validated locally; values are passed through unless a gateway definition constrains them. A name that is not in this table fails before anything is sent, because the gateway answers an unknown name with 200 and drops the setting.
A value is written with Display, so .param("ipv4", true) produces ipv4-true
and .param("port_hint", 8080) produces port_hint-8080 without a cast.
Case and spacing
country, region, city, isp and type are folded to the gateway's wire
form: surrounding whitespace trimmed, ASCII upper case lowered, each remaining
space turned into _. So
builder.login.password
.param
.build?
.username; // u-region-district_of_columbia
Which parameters fold is declared in the gateway definition, as data, so a gateway you describe yourself folds what you say it folds and nothing else.
sid, filter, ttl and speed are sent with their case unchanged, so
pass those in lower case. sid is yours, and folding an identifier a caller
chose would rename their session.
Every value not folded is refused if it contains whitespace. There is no spelling of a space that reaches this gateway intact.
Sticky sessions
One Proxy is one identity. Pin it to a sticky session:
let held = proxy.session?;
A session id cannot contain the gateway's separator, which for this one is
-, and the builder returns an error rather than connecting. The gateway cuts a
value at its separator, so this applies to every parameter and not only to
sid.
The session key is the whole parameter set, not the session id. country=us, sid=A and country=us, sid=A, filter=medium are two different sessions, so
adding or removing any parameter moves you to a different exit address. That is
why parameters change through a method returning a new Proxy rather than
through &mut self:
let germany = proxy.with_param?; // a new identity, a new exit
let plain = proxy.without_param?; // also a new identity
The order the parameters are written in does not change which exit you get.
For a pool of workers, draw the ids rather than inventing them:
for identity in proxy.sessions?
sessions(n) draws hexadecimal ids from the operating system's random source,
12 characters by default, so none can contain a separator. They are distinct
within one call; separate processes rely on the size of the id space.
sessions_of_length(n, bytes) sets the length.
Validation
A proxy gateway is bad at telling you that you got the username wrong. A value it
will not take comes back as 406, 407, 410, 500 or a connection that hangs,
none of which name the parameter - and an unknown parameter name is answered
200 and dropped, so the request succeeds, your code carries on, and the setting
you asked for was never applied. Nothing that comes back over the wire can tell
you that happened.
So this crate checks before anything is sent:
Proxy::builder().login("u").password("p").param("contry", "us").build()
Error::Param: NodeMaven does not know the parameter "contry": it is answered
with 200 and dropped, so the connection would succeed and your setting would
NOT be applied. Known: ["city", "country", "filter", "ipv4", "isp", "region",
"sid", "speed", "ttl", "type"]
Which names a gateway recognises, what its status codes mean and which values it
folds are data in the gateway definition rather than decisions in this code, so
they are quotable, correctable and per-gateway. Print the shipped one's own notes
with nodemaven::load("nodemaven")?.notes().
Errors
One enum, Error, with one variant per kind of thing that can be wrong. It is
#[non_exhaustive], so matching it needs a _ arm and a new variant is not a
breaking change.
| variant | returned when |
|---|---|
Error::Param |
a parameter name is unknown, a value is empty, a value contains the gateway's separator, or a value is outside a list the definition declares |
Error::Credentials |
no login, no password, or no gateway address, from arguments or environment; or a port that is not 1-65535 |
Error::Provider |
a gateway definition is missing, unreadable, or internally inconsistent |
Error::Check |
a CONNECT produced no answer at all - no route, no reply, no status line |
The first three are found before a socket exists. Error::Check is deliberately
narrow: a gateway that answers is not an error. A 407 is the gateway
answering the question that was asked, so it comes back as a value.
Checking a connection
Validation catches everything knowable without sending anything. For the rest - a wrong password, a country the pool does not have, a value the gateway dislikes - one call opens a single CONNECT and reports what came back:
let result = proxy.check?;
println!;
200 Connection established via gate.nodemaven.com:8080 in 0.42s, exit 203.0.113.7
The exit address arrives on the CONNECT reply itself, so knowing where you came
out costs one handshake and no traffic through the tunnel. Handle exit_ip()
being None - more than one implementation answers behind this hostname and
they do not agree about the header. If you need it every time, read it through
the tunnel from a service that echoes it.
A refusal is a value, not an Err. A refused tunnel comes back as
Ok(Check) carrying the gateway's own reading of its own status code, because
the status code is the thing you came for and a general HTTP client buries it:
407 Proxy Authentication Required via gate.nodemaven.com:8080 in 0.19s
usually NOT your credentials, despite what the status says. A value the gateway will not take on `country`, `filter`, `ttl`, `type` or `speed` answers 407, and so does a wrong password. Check the values before the password - and check the case of `ttl`, which is the one value that is case-sensitive: `10M` is refused where `10m` is accepted.
ok() does not mean your parameters were applied. An unrecognised name is
answered 200 too, which is the whole reason unknown names are refused before
sending. No call can recover that after the fact and this one does not pretend to.
check() tunnels to api.ipify.org:443 by default, and whatever you name will
see a TCP connection from your exit address. To choose it, or to change the
timeout, configure the CONNECT instead of taking the default:
let result = proxy.connect
.target
.timeout
.send?;
The timeout defaults to 15 seconds rather than something brisk, because one of this gateway's measured reactions is no reply for about 20 seconds. A 5-second timeout would report that as a network problem.
Account API
Quota, usage, sub-users, whitelisted addresses and the location catalogue. Separately credentialled: the API key and the proxy password are different secrets from different places.
use Client;
let client = builder.build?; // NODEMAVEN_APIKEY from the environment
let me = client.me?;
println!; // traffic left, in bytes
# Ok::
Responses are the server's own JSON, as serde_json::Value, unrenamed and
unmodelled: data is the traffic left, and is_traffic_frozen is a string.
me() returns your proxy password in clear text, and so do sub_users(),
create_sub_user() and reset_sub_user_usage(). Do not print or log them
whole.
client.countries?; // one page of the catalogue
client.regions?; // Django's lookup, the server's spelling
client.cities?;
client.isps?;
client.zip_codes?;
client.isp_regions?;
client.isp_cities?; // pages of 100: this one is slow
client.zip_code_regions?;
client.zip_code_cities?;
// Per proxy username. Dates are dd-mm-yyyy; ISO is answered 400, and no
// window at all is answered 500.
client.statistics_data?;
client.statistics_requests?;
client.domain_statistics?;
client.sub_users?;
client.create_sub_user?;
client.update_sub_user?;
client.delete_sub_user?;
client.reset_sub_user_usage?;
client.whitelist_ips?;
client.whitelist_ip?;
client.upsert_whitelist_ip?;
client.delete_whitelist_ip?;
A list endpoint returns a Page - one page, not the collection. The server
caps a page at 1000 rows, and a page that stops there looks exactly like a
finished one. iterate() walks the rest:
let first = client.cities?;
let every_city = client.iterate.?;
The gateway answers a country it does not have with 407, which reads as a
credentials problem. The catalogue knows better:
for problem in client.validate?
A 2xx whose body is not JSON is an error: the API host redirects a path it
does not serve to a not-found page, which a client that follows redirects
receives with 200. The built-in transport follows no
redirect, because the key travels in a header, and reads no proxy from the
environment. To use your own HTTP client, pass any owned, thread-safe function
of (method, url, headers, body) -> io::Result<(status, body)> to
Client::builder().transport(...), and build without the default http
feature if you want no TLS stack compiled in.
What this crate does not do
It does not retry. Retry policy belongs to the caller, and ours measured that repeated failures correlate with sharply worse outcomes - a session several failures deep spends roughly a hundred attempts per delivered page against under two in a healthy one. The harness behind that number is open source at nodemaven/proxy-benchmark, so it can be re-run rather than believed.
It also does not own the HTTP client your proxy traffic goes through, a connection pool or a browser, and it brings no async runtime with it. Those are yours. The one HTTP client inside is the account API's transport, and it can be replaced or compiled out.
Other gateways
Parameters are data, not hardcoded keywords. A gateway is its prefix, separators, session parameter and the set of parameter names it recognises - and a definition written by you goes through the same builder and the same validation as the one shipped here. Keep it in a TOML file:
# my-gateway.toml
= "My proxy"
= ["country", "session"]
= "session"
= "proxy.example.com"
= 8000
use ;
let mine = load_file?;
let proxy = builder
.provider
.login
.password
.param
.build?;
proxy.session?; // u-country-us-session-order4417
Provider::builder does the same thing in code, for a proxy you have no
definition for. An empty known_params is not a stub: it says nobody has
established what that gateway recognises, so every parameter is refused rather
than sent to be dropped in silence.
Credentials fall back to the environment under the definition's id in upper case,
so the file above reads MY_GATEWAY_LOGIN and MY_GATEWAY_PASSWORD and never
NODEMAVEN_*. One process can hold several gateways without their credentials
reaching each other. The id comes from the filename, not from the variable you
bind it to - use load_file_as to state it outright.
Requirements
Rust 1.85 or newer, which is the MSRV toml and ureq declare - nothing in this
crate's own code needs it. Dependencies: toml (reader only), getrandom for
session ids, serde_json for the account API's responses, and - behind the
default http feature - ureq with rustls as the API's transport. That last
one compiles ring; turn the feature off (default-features = false) if you
only build usernames, or bring your own transport. No unsafe code
(#![forbid(unsafe_code)]) in this crate, no build script of its own, no async
runtime.
License
MIT.