Record Class ProxyRoute

java.lang.Object
java.lang.Record
lol.trq.alts.net.ProxyRoute
Record Components:
kind - how to reach the network
host - the proxy host, or null for ProxyRoute.Kind.DIRECT
port - the proxy port, or 0 for ProxyRoute.Kind.DIRECT
username - the proxy username, or null when unauthenticated
password - the proxy password, or null when unauthenticated

public record ProxyRoute(ProxyRoute.Kind kind, String host, int port, String username, char[] password) extends Record
How one request should reach the network: directly, or through a proxy the host names.

A route is deliberately not stored on an account. A proxy is infrastructure rather than account identity, and — decisively — AltAccount travels into shared vault repositories, so a route living there would publish a paid proxy's host, port, and credentials to every member of every repository the alt is shared into.

Authenticated SOCKS5 is not supported. The JDK's SOCKS client reads credentials from process-global state — the java.net.socks.* system properties, or the default Authenticator — and a library that installs either has reached into its host's JVM to do it. withCredentials(String, char[]) therefore throws on a SOCKS5 route rather than silently connecting unauthenticated, which would send the request from an address the host did not choose. Unauthenticated SOCKS5 works; front an authenticated one with a local HTTP proxy.

The password is held as a private copy: the array passed in and the array password() returns are never the one stored, so neither a caller wiping its own array nor one scribbling on the returned array changes the credential a route authenticates with.

Since:
0.8.0
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    How a route reaches the network.
  • Constructor Summary

    Constructors
    Constructor
    Description
    ProxyRoute(ProxyRoute.Kind kind, String host, int port, String username, char[] password)
    Validates the shape, and refuses the credential combination the JDK cannot honour per-request.
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    Returns whether this route carries credentials.
    static ProxyRoute
    Returns the route meaning "no proxy".
    Returns the source address this route presents to a service, as a stable key.
    boolean
    equals(Object other)
    Compares routes by value, including the password's contents.
    int
    Returns a hash consistent with equals(Object).
    Returns the value of the host record component.
    static ProxyRoute
    http(String host, int port)
    Creates an unauthenticated HTTP proxy route.
    boolean
    Returns whether this route reaches the network without a proxy.
    Returns the value of the kind record component.
    char[]
    Returns a copy of the proxy password, so the caller cannot alter the stored credential.
    int
    Returns the value of the port record component.
    static ProxyRoute
    socks5(String host, int port)
    Creates an unauthenticated SOCKS5 proxy route.
    Returns a description carrying no credential.
    Returns the value of the username record component.
    withCredentials(String username, char[] password)
    Returns a copy carrying proxy credentials.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • ProxyRoute

      public ProxyRoute(ProxyRoute.Kind kind, String host, int port, String username, char[] password)
      Validates the shape, and refuses the credential combination the JDK cannot honour per-request.
      Since:
      0.8.0
  • Method Details

    • password

      public char[] password()
      Returns a copy of the proxy password, so the caller cannot alter the stored credential.
      Returns:
      a fresh copy of the password, or null when unauthenticated
      Since:
      0.8.0
    • direct

      public static ProxyRoute direct()
      Returns the route meaning "no proxy".
      Returns:
      the direct route
      Since:
      0.8.0
    • http

      public static ProxyRoute http(String host, int port)
      Creates an unauthenticated HTTP proxy route.
      Parameters:
      host - the proxy host
      port - the proxy port
      Returns:
      the route
      Since:
      0.8.0
    • socks5

      public static ProxyRoute socks5(String host, int port)
      Creates an unauthenticated SOCKS5 proxy route.
      Parameters:
      host - the proxy host
      port - the proxy port
      Returns:
      the route
      Since:
      0.8.0
    • withCredentials

      public ProxyRoute withCredentials(String username, char[] password)
      Returns a copy carrying proxy credentials.
      Parameters:
      username - the proxy username
      password - the proxy password
      Returns:
      a copy that authenticates
      Throws:
      UnsupportedOperationException - if this is a SOCKS5 route — see ProxyRoute
      IllegalStateException - if this is the direct route, which authenticates against nothing
      Since:
      0.8.0
    • isDirect

      public boolean isDirect()
      Returns whether this route reaches the network without a proxy.
      Returns:
      true if direct
      Since:
      0.8.0
    • authenticated

      public boolean authenticated()
      Returns whether this route carries credentials.
      Returns:
      true if a username is set
      Since:
      0.8.0
    • endpoint

      public String endpoint()
      Returns the source address this route presents to a service, as a stable key. Value identity for a route is its endpoint rather than the whole record, because what a service rate-limits is the address, not the credential that reached it.
      Returns:
      a key identifying the endpoint
      Since:
      0.8.0
    • equals

      public boolean equals(Object other)
      Compares routes by value, including the password's contents. The generated equals would compare the password arrays by identity, so two routes built from the same credential would never be equal.
      Specified by:
      equals in class Record
      Parameters:
      other - the object to compare with
      Returns:
      true if the other object is a route with the same kind, endpoint, and credential
      Since:
      0.12.0
    • hashCode

      public int hashCode()
      Returns a hash consistent with equals(Object).
      Specified by:
      hashCode in class Record
      Returns:
      the hash code
      Since:
      0.12.0
    • toString

      public String toString()
      Returns a description carrying no credential. The generated toString would print the password array, and a host logging the route it chose would write a proxy credential to its log. The username is left out as well: rotating gateways encode the session and the customer in it.
      Specified by:
      toString in class Record
      Returns:
      a loggable description
      Since:
      0.8.0
    • kind

      public ProxyRoute.Kind kind()
      Returns the value of the kind record component.
      Returns:
      the value of the kind record component
    • host

      public String host()
      Returns the value of the host record component.
      Returns:
      the value of the host record component
    • port

      public int port()
      Returns the value of the port record component.
      Returns:
      the value of the port record component
    • username

      public String username()
      Returns the value of the username record component.
      Returns:
      the value of the username record component