socks_handler 0.1.0

data/sig/defs.rbs

@@ -0,0 +1,509 @@
+# This file was generated by "rake generate_rbs"
+
+# An implementation of https://www.ietf.org/rfc/rfc1928.txt
+# @private
+module SocksHandler
+  PROTOCOL_VERSION: Integer
+  VERSION: String
+
+  # _@param_ `socket`
+  # 
+  # _@param_ `username`
+  # 
+  # _@param_ `password`
+  def negotiate: ((Socket | TCPSocket) socket, String? username, String? password) -> void
+
+  # _@param_ `socket`
+  # 
+  # _@param_ `username`
+  # 
+  # _@return_ — code of authentication method
+  def choose_auth_method: ((Socket | TCPSocket) socket, String? username) -> Integer
+
+  # _@param_ `socket`
+  # 
+  # _@param_ `command`
+  # 
+  # _@param_ `remote_host`
+  # 
+  # _@param_ `remote_port` — a port number or service name such as "http"
+  # 
+  # _@return_ — an array of [bound_address, bound_port]
+  def send_details: (
+                      (Socket | TCPSocket) socket,
+                      Integer command,
+                      String remote_host,
+                      (Integer | String) remote_port
+                    ) -> [String, Integer]
+
+  # _@param_ `remote_host`
+  # 
+  # _@param_ `remote_port`
+  def build_destination_packets: (String remote_host, (Integer | String) remote_port) -> String
+
+  # _@param_ `io`
+  # 
+  # _@return_ — an array of [bound_address, bound_port]
+  def process_reply: ((TCPSocket | Socket | StringIO) io) -> [String, Integer]
+
+  class TCP
+    extend SocksHandler
+
+    # Socksifies all TCP connections created by TCPSocket.new or Socket.tcp
+    # 
+    # _@param_ `rules` — socksify a socket according to the first rule whose remote host patterns match the remote host
+    # 
+    # ```ruby
+    # SocksHandler::TCP.socksify([
+    #   # Access 127.0.0.1, ::1 or hosts that end in ".local" directly
+    #   SocksHandler::DirectAccessRule.new(host_patterns: %w[127.0.0.1 ::1] + [/\.local\z/]),
+    # 
+    #   # Access hosts that end in ".ap-northeast-1.compute.internal" through 127.0.0.1:1080
+    #   SocksHandler::ProxyAccessRule.new(
+    #     host_patterns: [/\.ap-northeast-1\.compute\.internal\z/],
+    #     socks_server: "127.0.0.1:1080",
+    #   ),
+    # 
+    #   # Access hosts that end in ".ec2.internal" through 127.0.0.1:1081
+    #   SocksHandler::ProxyAccessRule.new(
+    #     host_patterns: [/\.ec2\.internal\z/],
+    #     socks_server: "127.0.0.1:1081",
+    #   ),
+    # 
+    #   # Access others hosts through 127.0.0.1:1082 with username/password auth
+    #   SocksHandler::ProxyAccessRule.new(
+    #     host_patterns: [//],
+    #     socks_server: "127.0.0.1:1082",
+    #     username: "user",
+    #     password: ENV["SOCKS_SERVER_PASSWORD"],
+    #   ),
+    # ])
+    # ```
+    def self.socksify: (::Array[(DirectAccessRule | ProxyAccessRule)] rules) -> void
+
+    def self.desocksify: () -> void
+
+    # _@param_ `host` — a domain name or IP address of a remote host
+    def self.find_rule: (String host) -> (DirectAccessRule | ProxyAccessRule)?
+
+    # Connects a host through a socks server
+    # 
+    # _@param_ `socket` — a socket that has connected to a socks server
+    # 
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port` — a port number or service name such as "http"
+    # 
+    # _@param_ `username`
+    # 
+    # _@param_ `password`
+    # 
+    # ```ruby
+    # socket = TCPSocket.new("127.0.0.1", 1080) # or Socket.tcp("127.0.0.1", 1080)
+    # # "nginx" is an HTTP server only the socks server can access
+    # SocksHandler::TCP.establish_connection(socket, "nginx", 80)
+    # 
+    # socket.write(<<~REQUEST.gsub("\n", "\r\n"))
+    #   HEAD / HTTP/1.1
+    #   Host: nginx
+    # 
+    # REQUEST
+    # puts socket.gets #=> HTTP/1.1 200 OK
+    # ```
+    def self.establish_connection: (
+                                     (Socket | TCPSocket) socket,
+                                     String remote_host,
+                                     (Integer | String) remote_port,
+                                     ?String? username,
+                                     ?String? password
+                                   ) -> void
+
+    def self.rules: () -> ::Array[(DirectAccessRule | ProxyAccessRule)]
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `username`
+    # 
+    # _@param_ `password`
+    def self.negotiate: ((Socket | TCPSocket) socket, String? username, String? password) -> void
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `username`
+    # 
+    # _@return_ — code of authentication method
+    def self.choose_auth_method: ((Socket | TCPSocket) socket, String? username) -> Integer
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `command`
+    # 
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port` — a port number or service name such as "http"
+    # 
+    # _@return_ — an array of [bound_address, bound_port]
+    def self.send_details: (
+                             (Socket | TCPSocket) socket,
+                             Integer command,
+                             String remote_host,
+                             (Integer | String) remote_port
+                           ) -> [String, Integer]
+
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port`
+    def self.build_destination_packets: (String remote_host, (Integer | String) remote_port) -> String
+
+    # _@param_ `io`
+    # 
+    # _@return_ — an array of [bound_address, bound_port]
+    def self.process_reply: ((TCPSocket | Socket | StringIO) io) -> [String, Integer]
+  end
+
+  class UDP
+    extend SocksHandler
+
+    # Associates a TCP socket with a UDP connection
+    # 
+    # _@param_ `socket` — a socket that has connected to a socks server
+    # 
+    # _@param_ `bind_host` — host for UDPSocket#bind
+    # 
+    # _@param_ `bind_port` — port for UDPSocket#bind
+    # 
+    # _@param_ `username`
+    # 
+    # _@param_ `password`
+    # 
+    # ```ruby
+    # tcp_socket = TCPSocket.new("127.0.0.1", 1080) # or Socket.tcp("127.0.0.1", 1080)
+    # udp_socket = SocksHandler::UDP.associate_udp(tcp_socket, "0.0.0.0", 0)
+    # 
+    # "echo" is a UDP echo server that only the socks server can access
+    # udp_socket.send("hello", 0, "echo", 7)
+    # puts udp_socket.gets #=> hello
+    # ```
+    def self.associate_udp: (
+                              (Socket | TCPSocket) socket,
+                              String bind_host,
+                              (Integer | String) bind_port,
+                              ?String? username,
+                              ?String? password
+                            ) -> SocksHandler::UDPSocket
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `username`
+    # 
+    # _@param_ `password`
+    def self.negotiate: ((Socket | TCPSocket) socket, String? username, String? password) -> void
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `username`
+    # 
+    # _@return_ — code of authentication method
+    def self.choose_auth_method: ((Socket | TCPSocket) socket, String? username) -> Integer
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `command`
+    # 
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port` — a port number or service name such as "http"
+    # 
+    # _@return_ — an array of [bound_address, bound_port]
+    def self.send_details: (
+                             (Socket | TCPSocket) socket,
+                             Integer command,
+                             String remote_host,
+                             (Integer | String) remote_port
+                           ) -> [String, Integer]
+
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port`
+    def self.build_destination_packets: (String remote_host, (Integer | String) remote_port) -> String
+
+    # _@param_ `io`
+    # 
+    # _@return_ — an array of [bound_address, bound_port]
+    def self.process_reply: ((TCPSocket | Socket | StringIO) io) -> [String, Integer]
+  end
+
+  # @!attribute [r] host
+  #   @return [String, nil]
+  # @!attribute [r] port
+  #   @return [Integer, nil]
+  # @!attribute [r] username
+  #   @return [String, nil]
+  # @!attribute [r] password
+  #   @return [String, nil]
+  # @!attribute [r] host_patterns
+  #   @return [Array<String, Regexp>]
+  class Rule
+    # sord omit - no YARD type given for "**kwargs", using untyped
+    def self.new: (**untyped kwargs) -> Rule
+
+    # _@param_ `host_patterns`
+    # 
+    # _@param_ `host`
+    # 
+    # _@param_ `port`
+    # 
+    # _@param_ `username`
+    # 
+    # _@param_ `password`
+    def initialize: (
+                      host_patterns: ::Array[(String | Regexp)],
+                      ?host: String?,
+                      ?port: Integer?,
+                      ?username: String?,
+                      ?password: String?
+                    ) -> void
+
+    def direct: () -> bool
+
+    # _@param_ `remote_host`
+    def match?: (String remote_host) -> bool
+
+    # _@param_ `value`
+    def convert_regexps: (::Array[(String | Regexp)] value) -> ::Array[Regexp]
+
+    attr_reader host: String?
+
+    attr_reader port: Integer?
+
+    attr_reader username: String?
+
+    attr_reader password: String?
+
+    attr_accessor host_patterns: ::Array[(String | Regexp)]
+  end
+
+  class UnsupportedProtocol < StandardError
+  end
+
+  class NoAcceptableMethods < StandardError
+  end
+
+  class AuthenticationFailure < StandardError
+  end
+
+  class RelayRequestFailure < StandardError
+    # _@param_ `code`
+    def initialize: (Integer code) -> void
+  end
+
+  module Command
+    CONNECT: Integer
+    BIND: Integer
+    UDP_ASSOCIATE: Integer
+  end
+
+  class UDPSocket < ::UDPSocket
+    include SocksHandler
+    MAX_REPLY_SIZE: Integer
+
+    # _@param_ `host`
+    # 
+    # _@param_ `port`
+    def connect_socks_server: (String host, Integer port) -> Integer
+
+    # _@param_ `host`
+    # 
+    # _@param_ `port`
+    # 
+    # _@see_ `UDPSocket#connect`
+    def connect: (String host, Integer port) -> Integer
+
+    # _@param_ `maxlen`
+    # 
+    # _@param_ `flags`
+    # 
+    # _@see_ `UDPSocket#recv`
+    def recv: (Integer maxlen, ?Integer flags) -> String
+
+    # _@param_ `maxlen`
+    # 
+    # _@param_ `maxlen`
+    # 
+    # _@param_ `flags`
+    def recvfrom_socks_server: (Integer maxlen, ?Integer flags) -> [String, [String, Integer, String, String]]
+
+    # _@param_ `maxlen`
+    # 
+    # _@param_ `flags`
+    # 
+    # _@see_ `UDPSocket#recvfrom)`
+    def recvfrom: (Integer maxlen, ?Integer flags) -> [String, [String, Integer, String, String]]
+
+    # _@param_ `maxlen`
+    # 
+    # _@param_ `flags`
+    def recvfrom_socks_server_nonblock: (Integer maxlen, ?Integer flags) -> [String, [String, Integer, String, String]]
+
+    # _@param_ `maxlen`
+    # 
+    # _@param_ `flags`
+    # 
+    # _@see_ `UDPSocket#recvfrom_nonblock`
+    def recvfrom_nonblock: (Integer maxlen, ?Integer flags) -> [String, [String, Integer, String, String]]
+
+    # _@param_ `mesg`
+    # 
+    # _@param_ `flags`
+    # 
+    # _@param_ `host`
+    # 
+    # _@param_ `port`
+    # 
+    # _@see_ `UDPSocket#send`
+    def send: (
+                String mesg,
+                Integer flags,
+                ?String? host,
+                ?(Integer | String)? port
+              ) -> Integer
+
+    # _@param_ `method`
+    # 
+    # _@param_ `maxlen`
+    # 
+    # _@param_ `flags`
+    def recvfrom_via: (Method method, Integer maxlen, Integer flags) -> [String, [String, Integer, String, String]]
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `username`
+    # 
+    # _@param_ `password`
+    def negotiate: ((Socket | TCPSocket) socket, String? username, String? password) -> void
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `username`
+    # 
+    # _@return_ — code of authentication method
+    def choose_auth_method: ((Socket | TCPSocket) socket, String? username) -> Integer
+
+    # _@param_ `socket`
+    # 
+    # _@param_ `command`
+    # 
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port` — a port number or service name such as "http"
+    # 
+    # _@return_ — an array of [bound_address, bound_port]
+    def send_details: (
+                        (Socket | TCPSocket) socket,
+                        Integer command,
+                        String remote_host,
+                        (Integer | String) remote_port
+                      ) -> [String, Integer]
+
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port`
+    def build_destination_packets: (String remote_host, (Integer | String) remote_port) -> String
+
+    # _@param_ `io`
+    # 
+    # _@return_ — an array of [bound_address, bound_port]
+    def process_reply: ((TCPSocket | Socket | StringIO) io) -> [String, Integer]
+  end
+
+  module AddressType
+    IPV4: Integer
+    DOMAINNAME: Integer
+    IPV6: Integer
+  end
+
+  module SocketSocksify
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port`
+    # 
+    # _@param_ `local_host`
+    # 
+    # _@param_ `local_port`
+    # 
+    # _@param_ `connect_timeout`
+    # 
+    # _@param_ `resolv_timeout`
+    def tcp: (
+               String remote_host,
+               (Integer | String) remote_port,
+               ?String? local_host,
+               ?(Integer | String)? local_port,
+               ?connect_timeout: (Integer | Float)?,
+               ?resolv_timeout: (Integer | Float)?
+             ) -> Socket
+  end
+
+  class ProxyAccessRule < SocksHandler::Rule
+    # _@param_ `host_patterns`
+    # 
+    # _@param_ `socks_server` — a string in the format "<host>:<port>"
+    # 
+    # _@param_ `username`
+    # 
+    # _@param_ `password`
+    def initialize: (
+                      host_patterns: ::Array[(String | Regexp)],
+                      socks_server: String,
+                      ?username: String?,
+                      ?password: String?
+                    ) -> void
+
+    def direct: () -> bool
+  end
+
+  class DirectAccessRule < SocksHandler::Rule
+    # _@param_ `host_patterns`
+    def initialize: (host_patterns: ::Array[(String | Regexp)]) -> void
+
+    def direct: () -> bool
+  end
+
+  module TCPSocketSocksify
+    # _@param_ `remote_host`
+    # 
+    # _@param_ `remote_port`
+    # 
+    # _@param_ `local_host`
+    # 
+    # _@param_ `local_port`
+    # 
+    # _@param_ `connect_timeout`
+    def initialize: (
+                      String remote_host,
+                      (Integer | String) remote_port,
+                      ?String? local_host,
+                      ?(Integer | String)? local_port,
+                      ?connect_timeout: (Integer | Float)?
+                    ) -> void
+  end
+
+  module AuthenticationMethod
+    NONE: Integer
+    GSSAPI: Integer
+    USERNAME_PASSWORD: Integer
+  end
+
+  # An implementation of https://www.ietf.org/rfc/rfc1929.txt
+  class UsernamePasswordAuthenticator
+    SUBNEGOTIATION_VERSION: Integer
+
+    # _@param_ `username`
+    # 
+    # _@param_ `password`
+    def initialize: (String username, String password) -> void
+
+    # _@param_ `socket`
+    def authenticate: ((Socket | TCPSocket) socket) -> void
+  end
+end

data/sig/lib/socks_handler/rule.rbs

@@ -0,0 +1,5 @@
+module SocksHandler
+  class Rule
+    @remote_host_pattern_regex: Regexp
+  end
+end

data/sig/lib/socks_handler/username_password_authenticator.rbs

@@ -0,0 +1,6 @@
+module SocksHandler
+  class UsernamePasswordAuthenticator
+    @username: String
+    @password: String
+  end
+end

data/sig/socket.rbs

@@ -0,0 +1,4 @@
+# Workaround for the error "RBS::NoTypeFoundError: Could not find Socket/TCPSocket/UDPSocket"
+class Socket end
+class TCPSocket end
+class UDPSocket end

data/socks_handler.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/socks_handler/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "socks_handler"
+  spec.version = SocksHandler::VERSION
+  spec.authors = ["abicky"]
+  spec.email = ["takeshi.arabiki@gmail.com"]
+
+  spec.summary = "A flexible socksifier for sockets created by TCPSocket.new, Socket.tcp or UDPSocket.new"
+  spec.description = <<~DESC
+    SocksHandler is a flexible socksifier for sockets created by `TCPSocket.new`, `Socket.tcp` or UDPSocket.new that solves the following issues:
+    1) `SOCKSSocket` is not easy to use, 2) Famous socksifiers such as socksify and proxychains4 don't support rules using domain names.
+  DESC
+  spec.homepage = "https://github.com/abicky/socks_handler"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: socks_handler
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- abicky
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-08-30 00:00:00.000000000 Z
+dependencies: []
+description: |
+  SocksHandler is a flexible socksifier for sockets created by `TCPSocket.new`, `Socket.tcp` or UDPSocket.new that solves the following issues:
+  1) `SOCKSSocket` is not easy to use, 2) Famous socksifiers such as socksify and proxychains4 don't support rules using domain names.
+email:
+- takeshi.arabiki@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- docker-compose.yml
+- lib/socks_handler.rb
+- lib/socks_handler/address_type.rb
+- lib/socks_handler/authentication_method.rb
+- lib/socks_handler/command.rb
+- lib/socks_handler/direct_access_rule.rb
+- lib/socks_handler/errors.rb
+- lib/socks_handler/proxy_access_rule.rb
+- lib/socks_handler/rule.rb
+- lib/socks_handler/socket_socksify.rb
+- lib/socks_handler/tcp.rb
+- lib/socks_handler/tcpsocket_socksify.rb
+- lib/socks_handler/udp.rb
+- lib/socks_handler/udpsocket.rb
+- lib/socks_handler/udpsocket_socksify.rb
+- lib/socks_handler/username_password_authenticator.rb
+- lib/socks_handler/version.rb
+- sig/defs.rbs
+- sig/lib/socks_handler/rule.rbs
+- sig/lib/socks_handler/username_password_authenticator.rbs
+- sig/socket.rbs
+- socks_handler.gemspec
+homepage: https://github.com/abicky/socks_handler
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/abicky/socks_handler
+  source_code_uri: https://github.com/abicky/socks_handler
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A flexible socksifier for sockets created by TCPSocket.new, Socket.tcp or
+  UDPSocket.new
+test_files: []