Reading a proxy seller's grammar off one pasted line

Most residential proxy sellers carry their options in the username: a country, sometimes a state and a city, a session id that holds one exit, and how long that session lives. The exact words, their order, their case and the characters between them change from seller to seller. Mosaic reads that grammar off the one line you paste, so the line is the specification and our table only fills in what one line cannot say.

Proxy username parameters: country, session, lifetime

Here are the shapes of three lines we have captured from real accounts, with the account parts replaced:

geonode_<id>-type-residential-country-us-state-connecticut-city-branford-lifetime-120-session-<6 chars>
<user>-region-us-sess-146592-sessTime-30
<user>__cr.de

The first is Geonode, the second IP Oasis, the third DataImpulse. Same idea, three dialects. Geonode writes country, IP Oasis writes region, DataImpulse writes cr behind a double underscore with a dot in place of a hyphen. Geonode calls the lifetime lifetime, IP Oasis calls it sessTime. One seller's session id is six digits and another's is six letters and digits.

Every one of those tokens tells us something. region-us says this seller writes country codes in lower case. state-AZ on an IP Oasis line says its states are upper-case codes. sess-146592 says a session id here is six digits, so a fresh one we mint for the next profile should be six digits too.

How it works: Provider minting

The pasted line is the specification

So Mosaic keeps the line you paste as a provider and reads the grammar back off it every time it mints. The vendor table supplies one thing a single line cannot: the word to use when adding an option the line did not carry. You cannot learn how a seller spells "city" from a line that has no city in it. Where the table has no word, the editor offers no city control, and a pick that names one is refused by name.

A token we have never heard of is kept, key and value, and survives a round trip. Every flag in a line is something the operator paid for. Dropping -zip-85001 because it is new to us would produce a proxy that targets the wrong place while the editor reports success. For Cat Proxies, the proxy editor lists such tokens under "Carried through unchanged", so what we do not understand stays visible.

A docs page for a similar product is not evidence

We wrote the Cat Proxies grammar from five real endpoints and the dashboard's own Location Settings form, because at the time its documentation answered 403 to anything but a logged-in browser. The one public document we could read described a differently named product with a different grammar and a different host. Building a parser from it would have matched no line anybody held.

The port turned out to matter too. On Cat Proxies, ports 9000, 10000 and 12000 answer HTTP and 11000 answers SOCKS5. A pasted host:port:user:pass carries no scheme, so without reading the port a SOCKS5 gateway would be stored as HTTP and fail at launch, one profile at a time.

We had also written down that the port did not decide stickiness. The dashboard said otherwise, and we believed our note until we asked the gateway itself:

9000  + -session-          400 "Can not use -session- on rotating ports"
9000  no session           exits PA, then AZ on the next connection
10000 + -session-ab12cd34  97.238.70.34 … and 97.238.70.34 again
10000 + -session-zz99yy11  152.13.118.218, a different id, a different exit

A session token on that seller's rotating port is a hard error, not a no-op. So when the sticky switch goes on, the editor moves the gateway to the sticky port instead of saving a line that would fail at every launch.

The username is the model

The Cat Proxies panel in the proxy editor has no state of its own. Every control parses the username, changes one token and writes the username straight back. A panel holding its own copy of the flags would be a second source of truth, and the moment somebody edited the username by hand the two would disagree and one would silently win.

We learned the store-level version of that the hard way. A saved proxy kept its session id in a second field as well as inside the username, and the second copy won. A username edited through the API was rewritten back to an hours-old session on every check, and the proxy looked dead from inside the app while answering in 1.3 seconds from the command line. The session id is now derived from the username whenever the username is written. When a fact lives inside a string the user can edit, the string is the fact.

Why it is worth this much care

A wrong token rarely fails loudly. A misspelled city usually authenticates, connects and loads pages from somewhere else, and the profile's timezone then contradicts its address. A reused session id puts two profiles on one exit. A dead session retried on the same token stays dead, which is the story in four 504s on one session.

Reading the grammar off the line is how Mosaic mints one session per profile for the sellers in its table that publish a format, including ones it has only read about in their documentation. The sellers and what each line can carry are on proxy providers. Whatever the grammar, a minted proxy is still checked before it is trusted: it has to answer and tunnel before a profile opens behind it.