rbs-relaxed 3.9.0.1

data/stdlib/socket/0/socket_error.rbs

@@ -0,0 +1,5 @@
+# <!-- rdoc-file=ext/socket/init.c -->
+# SocketError is the error class for socket.
+#
+class SocketError < StandardError
+end

data/stdlib/socket/0/tcp_server.rbs

@@ -0,0 +1,192 @@
+# <!-- rdoc-file=ext/socket/tcpserver.c -->
+# TCPServer represents a TCP/IP server socket.
+#
+# A simple TCP server may look like:
+#
+#     require 'socket'
+#
+#     server = TCPServer.new 2000 # Server bind to port 2000
+#     loop do
+#       client = server.accept    # Wait for a client to connect
+#       client.puts "Hello !"
+#       client.puts "Time is #{Time.now}"
+#       client.close
+#     end
+#
+# A more usable server (serving multiple clients):
+#
+#     require 'socket'
+#
+#     server = TCPServer.new 2000
+#     loop do
+#       Thread.start(server.accept) do |client|
+#         client.puts "Hello !"
+#         client.puts "Time is #{Time.now}"
+#         client.close
+#       end
+#     end
+#
+class TCPServer < TCPSocket
+  # <!--
+  #   rdoc-file=ext/socket/tcpserver.c
+  #   - tcpserver.accept => tcpsocket
+  # -->
+  # Accepts an incoming connection. It returns a new TCPSocket object.
+  #
+  #     TCPServer.open("127.0.0.1", 14641) {|serv|
+  #       s = serv.accept
+  #       s.puts Time.now
+  #       s.close
+  #     }
+  #
+  def accept: () -> TCPSocket
+
+  # <!--
+  #   rdoc-file=ext/socket/lib/socket.rb
+  #   - tcpserver.accept_nonblock([options]) => tcpsocket
+  # -->
+  # Accepts an incoming connection using accept(2) after O_NONBLOCK is set for the
+  # underlying file descriptor. It returns an accepted TCPSocket for the incoming
+  # connection.
+  #
+  # ### Example
+  #     require 'socket'
+  #     serv = TCPServer.new(2202)
+  #     begin # emulate blocking accept
+  #       sock = serv.accept_nonblock
+  #     rescue IO::WaitReadable, Errno::EINTR
+  #       IO.select([serv])
+  #       retry
+  #     end
+  #     # sock is an accepted socket.
+  #
+  # Refer to Socket#accept for the exceptions that may be thrown if the call to
+  # TCPServer#accept_nonblock fails.
+  #
+  # TCPServer#accept_nonblock may raise any error corresponding to accept(2)
+  # failure, including Errno::EWOULDBLOCK.
+  #
+  # If the exception is Errno::EWOULDBLOCK, Errno::EAGAIN, Errno::ECONNABORTED,
+  # Errno::EPROTO, it is extended by IO::WaitReadable. So IO::WaitReadable can be
+  # used to rescue the exceptions for retrying accept_nonblock.
+  #
+  # By specifying a keyword argument *exception* to `false`, you can indicate that
+  # accept_nonblock should not raise an IO::WaitReadable exception, but return the
+  # symbol `:wait_readable` instead.
+  #
+  # ### See
+  # *   TCPServer#accept
+  # *   Socket#accept
+  #
+  def accept_nonblock: (?exception: boolish) -> (TCPSocket | :wait_readable)
+
+  # <!--
+  #   rdoc-file=ext/socket/tcpserver.c
+  #   - socket.listen( int ) => 0
+  # -->
+  # Listens for connections, using the specified `int` as the backlog. A call to
+  # *listen* only applies if the `socket` is of type SOCK_STREAM or
+  # SOCK_SEQPACKET.
+  #
+  # ### Parameter
+  # *   `backlog` - the maximum length of the queue for pending connections.
+  #
+  # ### Example 1
+  #     require 'socket'
+  #     include Socket::Constants
+  #     socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
+  #     sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
+  #     socket.bind( sockaddr )
+  #     socket.listen( 5 )
+  #
+  # ### Example 2 (listening on an arbitrary port, unix-based systems only):
+  #     require 'socket'
+  #     include Socket::Constants
+  #     socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
+  #     socket.listen( 1 )
+  #
+  # ### Unix-based Exceptions
+  # On unix based systems the above will work because a new `sockaddr` struct is
+  # created on the address ADDR_ANY, for an arbitrary port number as handed off by
+  # the kernel. It will not work on Windows, because Windows requires that the
+  # `socket` is bound by calling *bind* before it can *listen*.
+  #
+  # If the *backlog* amount exceeds the implementation-dependent maximum queue
+  # length, the implementation's maximum queue length will be used.
+  #
+  # On unix-based based systems the following system exceptions may be raised if
+  # the call to *listen* fails:
+  # *   Errno::EBADF - the *socket* argument is not a valid file descriptor
+  # *   Errno::EDESTADDRREQ - the *socket* is not bound to a local address, and
+  #     the protocol does not support listening on an unbound socket
+  # *   Errno::EINVAL - the *socket* is already connected
+  # *   Errno::ENOTSOCK - the *socket* argument does not refer to a socket
+  # *   Errno::EOPNOTSUPP - the *socket* protocol does not support listen
+  # *   Errno::EACCES - the calling process does not have appropriate privileges
+  # *   Errno::EINVAL - the *socket* has been shut down
+  # *   Errno::ENOBUFS - insufficient resources are available in the system to
+  #     complete the call
+  #
+  # ### Windows Exceptions
+  # On Windows systems the following system exceptions may be raised if the call
+  # to *listen* fails:
+  # *   Errno::ENETDOWN - the network is down
+  # *   Errno::EADDRINUSE - the socket's local address is already in use. This
+  #     usually occurs during the execution of *bind* but could be delayed if the
+  #     call to *bind* was to a partially wildcard address (involving ADDR_ANY)
+  #     and if a specific address needs to be committed at the time of the call to
+  #     *listen*
+  # *   Errno::EINPROGRESS - a Windows Sockets 1.1 call is in progress or the
+  #     service provider is still processing a callback function
+  # *   Errno::EINVAL - the `socket` has not been bound with a call to *bind*.
+  # *   Errno::EISCONN - the `socket` is already connected
+  # *   Errno::EMFILE - no more socket descriptors are available
+  # *   Errno::ENOBUFS - no buffer space is available
+  # *   Errno::ENOTSOC - `socket` is not a socket
+  # *   Errno::EOPNOTSUPP - the referenced `socket` is not a type that supports
+  #     the *listen* method
+  #
+  # ### See
+  # *   listen manual pages on unix-based systems
+  # *   listen function in Microsoft's Winsock functions reference
+  #
+  def listen: (Integer backlog) -> void
+
+  # <!--
+  #   rdoc-file=ext/socket/tcpserver.c
+  #   - tcpserver.sysaccept => file_descriptor
+  # -->
+  # Returns a file descriptor of a accepted connection.
+  #
+  #     TCPServer.open("127.0.0.1", 28561) {|serv|
+  #       fd = serv.sysaccept
+  #       s = IO.for_fd(fd)
+  #       s.puts Time.now
+  #       s.close
+  #     }
+  #
+  def sysaccept: () -> Integer
+
+  private
+
+  def __accept_nonblock: (untyped) -> untyped
+
+  # <!--
+  #   rdoc-file=ext/socket/tcpserver.c
+  #   - TCPServer.new([hostname,] port) => tcpserver
+  # -->
+  # Creates a new server socket bound to *port*.
+  #
+  # If *hostname* is given, the socket is bound to it.
+  #
+  #     serv = TCPServer.new("127.0.0.1", 28561)
+  #     s = serv.accept
+  #     s.puts Time.now
+  #     s.close
+  #
+  # Internally, TCPServer.new calls getaddrinfo() function to obtain addresses. If
+  # getaddrinfo() returns multiple addresses, TCPServer.new tries to create a
+  # server socket for each address and returns first one that is successful.
+  #
+  def initialize: (?String host, Integer port) -> untyped
+end

data/stdlib/socket/0/tcp_socket.rbs

@@ -0,0 +1,79 @@
+# <!-- rdoc-file=ext/socket/tcpsocket.c -->
+# TCPSocket represents a TCP/IP client socket.
+#
+# A simple client may look like:
+#
+#     require 'socket'
+#
+#     s = TCPSocket.new 'localhost', 2000
+#
+#     while line = s.gets # Read lines from socket
+#       puts line         # and print them
+#     end
+#
+#     s.close             # close socket when done
+#
+class TCPSocket < IPSocket
+  # <!--
+  #   rdoc-file=ext/socket/tcpsocket.c
+  #   - TCPSocket.gethostbyname(hostname) => [official_hostname, alias_hostnames, address_family, *address_list]
+  # -->
+  # Use Addrinfo.getaddrinfo instead. This method is deprecated for the following
+  # reasons:
+  #
+  # *   The 3rd element of the result is the address family of the first address.
+  #     The address families of the rest of the addresses are not returned.
+  # *   gethostbyname() may take a long time and it may block other threads. (GVL
+  #     cannot be released since gethostbyname() is not thread safe.)
+  # *   This method uses gethostbyname() function already removed from POSIX.
+  #
+  # This method lookups host information by *hostname*.
+  #
+  #     TCPSocket.gethostbyname("localhost")
+  #     #=> ["localhost", ["hal"], 2, "127.0.0.1"]
+  #
+  def self.gethostbyname: (String host) -> [ String, Array[String], Integer, String ]
+
+  private
+
+  # <!--
+  #   rdoc-file=ext/socket/tcpsocket.c
+  #   - TCPSocket.new(remote_host, remote_port, local_host=nil, local_port=nil, resolv_timeout: nil, connect_timeout: nil, fast_fallback: true)
+  # -->
+  # Opens a TCP connection to `remote_host` on `remote_port`.  If `local_host` and
+  # `local_port` are specified, then those parameters are used on the local end to
+  # establish the connection.
+  #
+  # Starting from Ruby 3.4, this method operates according to the Happy Eyeballs
+  # Version 2 ([RFC 8305](https://datatracker.ietf.org/doc/html/rfc8305))
+  # algorithm by default, except on Windows.
+  #
+  # For details on Happy Eyeballs Version 2, see
+  # [Socket.tcp_fast_fallback=](rdoc-ref:Socket.tcp_fast_fallback=).
+  #
+  # To make it behave the same as in Ruby 3.3 and earlier, explicitly specify the
+  # option fast_fallback:false. Or, setting Socket.tcp_fast_fallback=false will
+  # disable Happy Eyeballs Version 2 not only for this method but for all Socket
+  # globally.
+  #
+  # When using TCPSocket.new on Windows, Happy Eyeballs Version 2 is not provided,
+  # and it behaves the same as in Ruby 3.3 and earlier.
+  #
+  # :resolv_timeout
+  # :   Specifies the timeout in seconds from when the hostname resolution starts.
+  #
+  # :connect_timeout
+  # :   This method sequentially attempts connecting to all candidate destination
+  #     addresses.
+  #     The `connect_timeout` specifies the timeout in seconds from the start of
+  #     the connection attempt to the last candidate.
+  #     By default, all connection attempts continue until the timeout occurs.
+  #     When `fast_fallback:false` is explicitly specified,
+  #     a timeout is set for each connection attempt and any connection attempt
+  #     that exceeds its timeout will be canceled.
+  #
+  # :fast_fallback
+  # :   Enables the Happy Eyeballs Version 2 algorithm (enabled by default).
+  #
+  def initialize: (String remote_host, Integer remote_port, ?String local_host, ?Integer local_port) -> untyped
+end

data/stdlib/socket/0/udp_socket.rbs

@@ -0,0 +1,133 @@
+# <!-- rdoc-file=ext/socket/udpsocket.c -->
+# UDPSocket represents a UDP/IP socket.
+#
+class UDPSocket < IPSocket
+  # <!--
+  #   rdoc-file=ext/socket/udpsocket.c
+  #   - udpsocket.bind(host, port) #=> 0
+  # -->
+  # Binds *udpsocket* to *host*:*port*.
+  #
+  #     u1 = UDPSocket.new
+  #     u1.bind("127.0.0.1", 4913)
+  #     u1.send "message-to-self", 0, "127.0.0.1", 4913
+  #     p u1.recvfrom(10) #=> ["message-to", ["AF_INET", 4913, "localhost", "127.0.0.1"]]
+  #
+  def bind: (String host, Integer port) -> void
+
+  # <!--
+  #   rdoc-file=ext/socket/udpsocket.c
+  #   - udpsocket.connect(host, port) => 0
+  # -->
+  # Connects *udpsocket* to *host*:*port*.
+  #
+  # This makes possible to send without destination address.
+  #
+  #     u1 = UDPSocket.new
+  #     u1.bind("127.0.0.1", 4913)
+  #     u2 = UDPSocket.new
+  #     u2.connect("127.0.0.1", 4913)
+  #     u2.send "uuuu", 0
+  #     p u1.recvfrom(10) #=> ["uuuu", ["AF_INET", 33230, "localhost", "127.0.0.1"]]
+  #
+  def connect: (String host, Integer port) -> void
+
+  # <!--
+  #   rdoc-file=ext/socket/lib/socket.rb
+  #   - udpsocket.recvfrom_nonblock(maxlen [, flags[, outbuf [, options]]]) => [mesg, sender_inet_addr]
+  # -->
+  # Receives up to *maxlen* bytes from `udpsocket` using recvfrom(2) after
+  # O_NONBLOCK is set for the underlying file descriptor. *flags* is zero or more
+  # of the `MSG_` options. The first element of the results, *mesg*, is the data
+  # received. The second element, *sender_inet_addr*, is an array to represent the
+  # sender address.
+  #
+  # When recvfrom(2) returns 0, Socket#recv_nonblock returns nil. In most cases it
+  # means the connection was closed, but it may also mean an empty packet was
+  # received, as the underlying API makes it impossible to distinguish these two
+  # cases.
+  #
+  # ### Parameters
+  # *   `maxlen` - the number of bytes to receive from the socket
+  # *   `flags` - zero or more of the `MSG_` options
+  # *   `outbuf` - destination String buffer
+  # *   `options` - keyword hash, supporting `exception: false`
+  #
+  # ### Example
+  #     require 'socket'
+  #     s1 = UDPSocket.new
+  #     s1.bind("127.0.0.1", 0)
+  #     s2 = UDPSocket.new
+  #     s2.bind("127.0.0.1", 0)
+  #     s2.connect(*s1.addr.values_at(3,1))
+  #     s1.connect(*s2.addr.values_at(3,1))
+  #     s1.send "aaa", 0
+  #     begin # emulate blocking recvfrom
+  #       p s2.recvfrom_nonblock(10)  #=> ["aaa", ["AF_INET", 33302, "localhost.localdomain", "127.0.0.1"]]
+  #     rescue IO::WaitReadable
+  #       IO.select([s2])
+  #       retry
+  #     end
+  #
+  # Refer to Socket#recvfrom for the exceptions that may be thrown if the call to
+  # *recvfrom_nonblock* fails.
+  #
+  # UDPSocket#recvfrom_nonblock may raise any error corresponding to recvfrom(2)
+  # failure, including Errno::EWOULDBLOCK.
+  #
+  # If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by
+  # IO::WaitReadable. So IO::WaitReadable can be used to rescue the exceptions for
+  # retrying recvfrom_nonblock.
+  #
+  # By specifying a keyword argument *exception* to `false`, you can indicate that
+  # recvfrom_nonblock should not raise an IO::WaitReadable exception, but return
+  # the symbol `:wait_readable` instead.
+  #
+  # ### See
+  # *   Socket#recvfrom
+  #
+  def recvfrom_nonblock: (Integer len, ?Integer flag, ?String outbuf, ?exception: boolish) -> [ String, [ String, Integer, String, String ] ]
+
+  # <!--
+  #   rdoc-file=ext/socket/udpsocket.c
+  #   - udpsocket.send(mesg, flags, host, port)  => numbytes_sent
+  #   - udpsocket.send(mesg, flags, sockaddr_to) => numbytes_sent
+  #   - udpsocket.send(mesg, flags)              => numbytes_sent
+  # -->
+  # Sends *mesg* via *udpsocket*.
+  #
+  # *flags* should be a bitwise OR of Socket::MSG_* constants.
+  #
+  #     u1 = UDPSocket.new
+  #     u1.bind("127.0.0.1", 4913)
+  #
+  #     u2 = UDPSocket.new
+  #     u2.send "hi", 0, "127.0.0.1", 4913
+  #
+  #     mesg, addr = u1.recvfrom(10)
+  #     u1.send mesg, 0, addr[3], addr[1]
+  #
+  #     p u2.recv(100) #=> "hi"
+  #
+  def send: (String msg, ?Integer flags, ?String host, ?Integer port) -> Integer
+
+  private
+
+  def __recvfrom_nonblock: (untyped, untyped, untyped, untyped) -> untyped
+
+  # <!--
+  #   rdoc-file=ext/socket/udpsocket.c
+  #   - UDPSocket.new([address_family]) => socket
+  # -->
+  # Creates a new UDPSocket object.
+  #
+  # *address_family* should be an integer, a string or a symbol: Socket::AF_INET,
+  # "AF_INET", :INET, etc.
+  #
+  #     require 'socket'
+  #
+  #     UDPSocket.new                   #=> #<UDPSocket:fd 3>
+  #     UDPSocket.new(Socket::AF_INET6) #=> #<UDPSocket:fd 4>
+  #
+  def initialize: (?Integer family) -> untyped
+end

data/stdlib/socket/0/unix_server.rbs

@@ -0,0 +1,169 @@
+# <!-- rdoc-file=ext/socket/unixserver.c -->
+# UNIXServer represents a UNIX domain stream server socket.
+#
+class UNIXServer < UNIXSocket
+  # <!--
+  #   rdoc-file=ext/socket/unixserver.c
+  #   - unixserver.accept => unixsocket
+  # -->
+  # Accepts an incoming connection. It returns a new UNIXSocket object.
+  #
+  #     UNIXServer.open("/tmp/sock") {|serv|
+  #       UNIXSocket.open("/tmp/sock") {|c|
+  #         s = serv.accept
+  #         s.puts "hi"
+  #         s.close
+  #         p c.read #=> "hi\n"
+  #       }
+  #     }
+  #
+  def accept: () -> UNIXSocket
+
+  # <!--
+  #   rdoc-file=ext/socket/lib/socket.rb
+  #   - unixserver.accept_nonblock([options]) => unixsocket
+  # -->
+  # Accepts an incoming connection using accept(2) after O_NONBLOCK is set for the
+  # underlying file descriptor. It returns an accepted UNIXSocket for the incoming
+  # connection.
+  #
+  # ### Example
+  #     require 'socket'
+  #     serv = UNIXServer.new("/tmp/sock")
+  #     begin # emulate blocking accept
+  #       sock = serv.accept_nonblock
+  #     rescue IO::WaitReadable, Errno::EINTR
+  #       IO.select([serv])
+  #       retry
+  #     end
+  #     # sock is an accepted socket.
+  #
+  # Refer to Socket#accept for the exceptions that may be thrown if the call to
+  # UNIXServer#accept_nonblock fails.
+  #
+  # UNIXServer#accept_nonblock may raise any error corresponding to accept(2)
+  # failure, including Errno::EWOULDBLOCK.
+  #
+  # If the exception is Errno::EWOULDBLOCK, Errno::EAGAIN, Errno::ECONNABORTED or
+  # Errno::EPROTO, it is extended by IO::WaitReadable. So IO::WaitReadable can be
+  # used to rescue the exceptions for retrying accept_nonblock.
+  #
+  # By specifying a keyword argument *exception* to `false`, you can indicate that
+  # accept_nonblock should not raise an IO::WaitReadable exception, but return the
+  # symbol `:wait_readable` instead.
+  #
+  # ### See
+  # *   UNIXServer#accept
+  # *   Socket#accept
+  #
+  def accept_nonblock: (?exception: boolish) -> (UNIXSocket | :wait_readable)
+
+  # <!--
+  #   rdoc-file=ext/socket/unixserver.c
+  #   - socket.listen( int ) => 0
+  # -->
+  # Listens for connections, using the specified `int` as the backlog. A call to
+  # *listen* only applies if the `socket` is of type SOCK_STREAM or
+  # SOCK_SEQPACKET.
+  #
+  # ### Parameter
+  # *   `backlog` - the maximum length of the queue for pending connections.
+  #
+  # ### Example 1
+  #     require 'socket'
+  #     include Socket::Constants
+  #     socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
+  #     sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
+  #     socket.bind( sockaddr )
+  #     socket.listen( 5 )
+  #
+  # ### Example 2 (listening on an arbitrary port, unix-based systems only):
+  #     require 'socket'
+  #     include Socket::Constants
+  #     socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
+  #     socket.listen( 1 )
+  #
+  # ### Unix-based Exceptions
+  # On unix based systems the above will work because a new `sockaddr` struct is
+  # created on the address ADDR_ANY, for an arbitrary port number as handed off by
+  # the kernel. It will not work on Windows, because Windows requires that the
+  # `socket` is bound by calling *bind* before it can *listen*.
+  #
+  # If the *backlog* amount exceeds the implementation-dependent maximum queue
+  # length, the implementation's maximum queue length will be used.
+  #
+  # On unix-based based systems the following system exceptions may be raised if
+  # the call to *listen* fails:
+  # *   Errno::EBADF - the *socket* argument is not a valid file descriptor
+  # *   Errno::EDESTADDRREQ - the *socket* is not bound to a local address, and
+  #     the protocol does not support listening on an unbound socket
+  # *   Errno::EINVAL - the *socket* is already connected
+  # *   Errno::ENOTSOCK - the *socket* argument does not refer to a socket
+  # *   Errno::EOPNOTSUPP - the *socket* protocol does not support listen
+  # *   Errno::EACCES - the calling process does not have appropriate privileges
+  # *   Errno::EINVAL - the *socket* has been shut down
+  # *   Errno::ENOBUFS - insufficient resources are available in the system to
+  #     complete the call
+  #
+  # ### Windows Exceptions
+  # On Windows systems the following system exceptions may be raised if the call
+  # to *listen* fails:
+  # *   Errno::ENETDOWN - the network is down
+  # *   Errno::EADDRINUSE - the socket's local address is already in use. This
+  #     usually occurs during the execution of *bind* but could be delayed if the
+  #     call to *bind* was to a partially wildcard address (involving ADDR_ANY)
+  #     and if a specific address needs to be committed at the time of the call to
+  #     *listen*
+  # *   Errno::EINPROGRESS - a Windows Sockets 1.1 call is in progress or the
+  #     service provider is still processing a callback function
+  # *   Errno::EINVAL - the `socket` has not been bound with a call to *bind*.
+  # *   Errno::EISCONN - the `socket` is already connected
+  # *   Errno::EMFILE - no more socket descriptors are available
+  # *   Errno::ENOBUFS - no buffer space is available
+  # *   Errno::ENOTSOC - `socket` is not a socket
+  # *   Errno::EOPNOTSUPP - the referenced `socket` is not a type that supports
+  #     the *listen* method
+  #
+  # ### See
+  # *   listen manual pages on unix-based systems
+  # *   listen function in Microsoft's Winsock functions reference
+  #
+  def listen: (Integer backlog) -> void
+
+  # <!--
+  #   rdoc-file=ext/socket/unixserver.c
+  #   - unixserver.sysaccept => file_descriptor
+  # -->
+  # Accepts a new connection. It returns the new file descriptor which is an
+  # integer.
+  #
+  #     UNIXServer.open("/tmp/sock") {|serv|
+  #       UNIXSocket.open("/tmp/sock") {|c|
+  #         fd = serv.sysaccept
+  #         s = IO.new(fd)
+  #         s.puts "hi"
+  #         s.close
+  #         p c.read #=> "hi\n"
+  #       }
+  #     }
+  #
+  def sysaccept: () -> Integer
+
+  private
+
+  def __accept_nonblock: (untyped) -> untyped
+
+  # <!--
+  #   rdoc-file=ext/socket/unixserver.c
+  #   - UNIXServer.new(path) => unixserver
+  # -->
+  # Creates a new UNIX server socket bound to *path*.
+  #
+  #     require 'socket'
+  #
+  #     serv = UNIXServer.new("/tmp/sock")
+  #     s = serv.accept
+  #     p s.read
+  #
+  def initialize: (untyped) -> untyped
+end