nodemaven 0.2.2

Build and validate NodeMaven proxy connection strings, and call its account API. No retries.
Documentation

NodeMaven Rust SDK

Builds the proxy username a gateway expects, and refuses the input it would silently drop.

CI crates.io docs.rs license

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 nodemaven::Proxy;

let proxy = Proxy::builder()
    .login("your-login")
    .password("your-password")
    .param("country", "us")
    .param("filter", "medium")
    .build()?;

let client = reqwest::Client::builder()
    .proxy(reqwest::Proxy::all(proxy.url())?)
    .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 = Proxy::builder().param("country", "us").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

Proxy::builder().login("u").password("p")
    .param("region", "District of Columbia")
    .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("order4417")?;

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("country", "de")?;   // a new identity, a new exit
let plain   = proxy.without_param("filter")?;       // 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(50)? {
    queue.push(identity);                           // each one a different exit
}

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!("{result}");
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("example.com:443")
    .timeout(Duration::from_secs(30))
    .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 nodemaven::Client;

let client = Client::builder().build()?;            // NODEMAVEN_APIKEY from the environment
let me = client.me()?;
println!("{}", me["data"]);                         // traffic left, in bytes
# Ok::<(), nodemaven::Error>(())

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(&[("country__code", "us")])?;              // Django's lookup, the server's spelling
client.cities(&[("country__code", "us"), ("region__code", "dc")])?;
client.isps(&[("country__code", "us")])?;
client.zip_codes(&[("country__code", "us")])?;
client.isp_regions(&[("country__code", "us")])?;
client.isp_cities(&[("country__code", "us")])?;           // pages of 100: this one is slow
client.zip_code_regions(&[("country__code", "us")])?;
client.zip_code_cities(&[("country__code", "us")])?;

// Per proxy username. Dates are dd-mm-yyyy; ISO is answered 400, and no
// window at all is answered 500.
client.statistics_data("acct-1", &[("start", "01-09-2026"), ("end", "07-09-2026")])?;
client.statistics_requests("acct-1", &[("period", "today")])?;
client.domain_statistics("acct-1", &[("period", "hours24")])?;

client.sub_users(&[])?;
client.create_sub_user("worker-1", "a-password", &[("traffic_limit", 1024.into())])?;
client.update_sub_user(id, &[("traffic_limit", 2048.into())])?;
client.delete_sub_user(id)?;
client.reset_sub_user_usage(&[id.into()])?;

client.whitelist_ips(&[])?;
client.whitelist_ip(ip_id)?;
client.upsert_whitelist_ip("203.0.113.7", 10, &[("name", "the office".into())])?;
client.delete_whitelist_ip(ip_id)?;

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(&[("country__code", "us")])?;
let every_city = client.iterate(first).collect::<Result<Vec<_>, _>>()?;

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(&proxy)? {
    eprintln!("{problem}");
}

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
label = "My proxy"
known_params = ["country", "session"]
session_param = "session"
host = "proxy.example.com"
port = 8000
use nodemaven::{load_file, Proxy};

let mine = load_file("my-gateway.toml")?;
let proxy = Proxy::builder()
    .provider(mine)
    .login("u")
    .password("p")
    .param("country", "us")
    .build()?;
proxy.session("order4417")?;     // 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.