SocksProxy.java

/*
 * Copyright 2015-2025 the original author or authors.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package sockslib.client;

import sockslib.common.AnonymousCredentials;
import sockslib.common.Credentials;
import sockslib.common.SocksException;
import sockslib.common.UsernamePasswordCredentials;
import sockslib.common.methods.SocksMethod;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.InetAddress;
import java.net.Socket;
import java.net.SocketAddress;
import java.net.UnknownHostException;
import java.util.List;

/**
 * The interface <code>SocksProxy</code> define a SOCKS proxy. it's will be used by
 * {@link SocksSocket} or {@link Socks5DatagramSocket}
 *
 * @author Youchao Feng
 * @version 1.0
 * @date Mar 18, 2015 3:29:18 PM
 */
public interface SocksProxy {

  /**
   * Default SOCKS server port.
   */
  int SOCKS_DEFAULT_PORT = 1080;

  /**
   * Get the socket which connect SOCKS server.
   *
   * @return java.net.Socket.
   */
  Socket getProxySocket();

  /**
   * Set a unconnected socket which will be used to connect SOCKS server.
   *
   * @param socket a unconnected socket.
   * @return instance of SocksProxy.
   */
  SocksProxy setProxySocket(Socket socket);

  /**
   * Get SOCKS Server port.
   *
   * @return server port.
   */
  int getPort();

  /**
   * Set SOCKS server port.
   *
   * @param port SOCKS server's port.
   * @return instance of SocksProxy.
   */
  SocksProxy setPort(int port);

  /**
   * Get SOCKS server's address as IPv4 or IPv6.
   *
   * @return server's IP address.
   */
  InetAddress getInetAddress();

  /**
   * Set SOCKS server's host.
   *
   * @param host SOCKS server's host.
   * @return instance of SocksProxy.
   * @throws UnknownHostException if host can't resolve to {@link java.net.InetAddress}
   */
  SocksProxy setHost(String host) throws UnknownHostException;

  /**
   * Connect SOCKS server using SOCKS protocol. This method will ask SOCKS server to select
   * a method from the methods listed by client. If SOCKS server need authentication, it will
   * do authentication. If SOCKS server select 0xFF,It means that none of the methods listed by the
   * client are acceptable and this method should throw {@link SocksException}.
   *
   * @throws IOException    if any IO error occurs.
   * @throws SocksException if any error about SOCKS protocol occurs.
   */
  void buildConnection() throws IOException, SocksException;

  /**
   * This method will send a CONNECT command to SOCKS server and ask SOCKS server to connect remote
   * server.
   *
   * @param host Remote server's host.
   * @param port Remote server's port.
   * @return The message that reply by SOCKS server.
   * @throws SocksException If any error about SOCKS protocol occurs.
   * @throws IOException    if any I/O error occurs.
   */
  CommandReplyMessage requestConnect(String host, int port) throws SocksException, IOException;

  /**
   * This method will send a CONNECT command to SOCKS server and ask SOCKS server to connect remote
   * server.
   *
   * @param address Remote server's address as java.net.InetAddress instance.
   * @param port    Remote server's port.
   * @return The message that reply by SOCKS server.
   * @throws SocksException If any error about SOCKS protocol occurs.
   * @throws IOException    If any I/O error occurs.
   */
  CommandReplyMessage requestConnect(InetAddress address, int port) throws SocksException,
      IOException;

  /**
   * This method will send a CONNECT command to SOCKS server and ask SOCKS server to connect remote
   * server.
   *
   * @param address Remote server's address as java.net.SocketAddress instance.
   * @return The message that reply by SOCKS server.
   * @throws SocksException If any error about SOCKS protocol occurs.
   * @throws IOException    If any I/O error occurs.
   */
  CommandReplyMessage requestConnect(SocketAddress address) throws SocksException, IOException;

  /**
   * This method will send a BIND command to SOKCS server.
   *
   * @param host Remote server's host.
   * @param port Remote server's port.
   * @return The message that reply by SOCKS server.
   * @throws SocksException If any error about SOCKS protocol occurs.
   * @throws IOException    If any I/O error occurs.
   */
  CommandReplyMessage requestBind(String host, int port) throws SocksException, IOException;

  /**
   * This method will send a BIND command to SOKCS server.
   *
   * @param inetAddress Remote server's IP address.
   * @param port        Remote server's port.
   * @return The message that reply by SOCKS server.
   * @throws SocksException If any error about SOCKS protocol occurs.
   * @throws IOException    If any I/O error occurs.
   */
  CommandReplyMessage requestBind(InetAddress inetAddress, int port) throws
      SocksException, IOException;

  /**
   * When server has income connection, this method will read second response message from
   * SOCKS server. <br>
   * This method will be blocked if there is no income connection. When there is a income
   * connection, this method will return a socket that looks like connect the remote host.
   *
   * @return Socket that connect the remote host.
   * @throws SocksException If any error about SOCKS protocol occurs.
   * @throws IOException    If any I/O error occurs.
   */
  Socket accept() throws SocksException, IOException;

  /**
   * This method will send a UDP ASSOCIATE command to SOCKS server and ask SOCKS server to establish
   * a relay server.
   *
   * @param host Remote UDP server's host.
   * @param port Remote UDP server's port.
   * @return The message that reply by SOCKS server.
   * @throws SocksException If any error about SOCKS protocol occurs.
   * @throws IOException    If any I/O error occurs.
   */
  CommandReplyMessage requestUdpAssociate(String host, int port) throws SocksException, IOException;

  /**
   * This method will send a UDP ASSOCIATE command to SOCKS server and ask SOCKS server to establish
   * a relay server.
   *
   * @param address Remote UDP server's address.
   * @param port    Remote UDP server's port.
   * @return The message that reply by SOCKS server.
   * @throws SocksException If any error about SOCKS protocol occurs.
   * @throws IOException    If any I/O error occurs.
   */
  CommandReplyMessage requestUdpAssociate(InetAddress address, int port) throws SocksException,
      IOException;

  /**
   * Gets InputStream from the socket that connected SOCKS server.
   *
   * @return java.net.InputStream.
   * @throws IOException if any I/O error occurs.
   */
  InputStream getInputStream() throws IOException;

  /**
   * Gets OutputStream from the socket that connected SOCKS server.
   *
   * @return java.net.OutputStream.
   * @throws IOException if any I/O error occurs.
   */
  OutputStream getOutputStream() throws IOException;

  /**
   * Gets credentials from the SocksProxy.
   *
   * @return {@link Credentials} instance.
   */
  Credentials getCredentials();

  /**
   * Sets credentials.
   *
   * @param credentials {@link Credentials} instance.
   * @return instance of SocksProxy.
   * @see UsernamePasswordCredentials
   * @see AnonymousCredentials
   */
  SocksProxy setCredentials(Credentials credentials);

  /**
   * Gets client's acceptable methods.
   *
   * @return client's acceptable methods.
   */
  List<SocksMethod> getAcceptableMethods();

  /**
   * Sets client's acceptable methods.
   *
   * @param methods methods.
   * @return instance of SocksProxy.
   */
  SocksProxy setAcceptableMethods(List<SocksMethod> methods);

  /**
   * Gets {@link SocksMethodRequester}.
   *
   * @return {@link SocksMethodRequester}.
   */
  SocksMethodRequester getSocksMethodRequester();

  /**
   * Sets {@link SocksMethodRequester}.
   *
   * @param requester {@link SocksMethodRequester}
   * @return instance of SocksProxy.
   */
  SocksProxy setSocksMethodRequester(SocksMethodRequester requester);

  /**
   * Gets version of SOCKS protocol.
   *
   * @return Version of SOCKS protocol.
   */
  int getSocksVersion();

  /**
   * This method can build a same SocksProxy instance. The new instance created by this method has
   * the same properties with the original instance, but they have different socket instance. The
   * new instance's socket is also unconnected.
   *
   * @return The copy of this SocksProxy.
   */
  SocksProxy copy();

  /**
   * Copy the {@link SocksProxy}. It will copy all properties of the {@link SocksProxy} but without
   * chain proxy.
   *
   * @return The copy of this SocksProxy but without chain proxy.
   */
  SocksProxy copyWithoutChainProxy();

  /**
   * Returns the chain proxy.
   *
   * @return the chain proxy.
   */
  SocksProxy getChainProxy();

  /**
   * Returns the instance of <code>SocksProxy</code>.
   *
   * @param chainProxy chain proxy.
   * @return the instance of <code>SocksProxy</code>.
   */
  SocksProxy setChainProxy(SocksProxy chainProxy);

  /**
   * Creates a proxy socket.
   *
   * @param address address.
   * @param port    port.
   * @return Socket instance.
   * @throws IOException If an I\O error occurred.
   */
  Socket createProxySocket(InetAddress address, int port) throws IOException;

  /**
   * Creates a unconnected socket.
   *
   * @return a unconnected socket.
   * @throws IOException If an I\O error occurred.
   */
  Socket createProxySocket() throws IOException;

}