unix_socks 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 215ee14acc29cc75bc5bd6005d4b73afbc6612c0147e28362ccad7fb4d72694d
-  data.tar.gz: '05698df412aab41c8b546c96576d9d99ec5ede18e968166ba8d710f909e47927'
+  metadata.gz: d67e7734f17aa0c0215570741c0d28c24a977e4d5468e35b35b8b51fda5ce3ce
+  data.tar.gz: 2aec1808e4c26b8b3948d9aa7d51ed25a641cd72aca74cf4dc611e5a951cf95a
 SHA512:
-  metadata.gz: 7ab4adacdbe6eed5c3c9e8f8df41cf10589901c77e8f7d7f8a29866ddb826f22825a76a07884a2739b088f0aac9449cd2ad32f5c0bb6ceb0ef4ebaa1526b071e
-  data.tar.gz: f5141f414e1962c7cf6d8881ccadad9003daff74da2b21a74fa18a24bab16e03ea3a8ae29e511596acc8bebd44503ede98238b218e1caa48f0462e65a1c79c11
+  metadata.gz: 41f9a5ca91d3f57866b204174f1c95c91c56345a040d3cd59513144081a6cfe39124a3dc0e42646b3d9983eff59c139c7d5ec29a89c708b70f6aa688225420f0
+  data.tar.gz: 198eccdfe7d548b9c0bbd161afde90e2aa526bdb7540c804998f804177aa212da37429cd1979de56a47ba1e5df178f7e5b79bcf1010048b91965472129cc7519

data/CHANGES.md

@@ -1,5 +1,23 @@
 # Changes
 
+## 2025-12-24 v0.3.0
+
+- Refactored socket server architecture by splitting `UnixSocks::Server` into
+  `UnixSocks::DomainSocketServer` and `UnixSocks::TCPSocketServer`
+- Added `UnixSocks::ServerShared` module to encapsulate common functionality
+  shared between socket server implementations
+- Implemented `to_url` method for both server types to generate `unix://path`
+  and `tcp://host:port` URLs
+- Introduced `UnixSocks::ServerError` marker module for consistent error
+  handling across the library
+- Updated all documentation and tests to reflect the new dual socket server
+  architecture
+- Maintained backward compatibility for core communication patterns
+- Added comprehensive test coverage for both `UnixSocks::DomainSocketServer`
+  and `UnixSocks::TCPSocketServer` implementations
+- Added `.rspec` file to configure RSpec with detailed output format (`--format
+  d`) for improved test output readability
+
 ## 2025-12-23 v0.2.3
 
 - Handle `Errno::ENOENT` errors in the background socket server thread to
@@ -7,7 +25,7 @@
 - Add test case to verify background thread execution and `ENOENT` error
   handling
 - Maintain existing `at_exit` cleanup behavior to ensure socket file removal
-- Update `UnixSocks::Server` to be more resilient to temporary file system
+- Update `UnixSocks::DomainSocketServer` to be more resilient to temporary file system
   conditions
 - Update `gem_hadar` development dependency to version **2.16.0**
 
@@ -47,7 +65,7 @@
 
 ## 2025-09-07 v0.1.0
 
-- Introduced `UnixSocks::Server.default_runtime_dir` class method
+- Introduced `UnixSocks::DomainSocketServer.default_runtime_dir` class method
 - Simplified coverage configuration by using `GemHadar::SimpleCov.start`
 
 ## 2025-07-13 v0.0.1

data/README.md

@@ -2,14 +2,22 @@
 
 ## Description
 
-A Ruby library for handling Unix socket-based communication.
+A Ruby library for handling inter-process communication via Unix sockets and
+TCP sockets.
 
 ## Features
 
-- **Message Handling**: Simplify sending and receiving messages over Unix sockets.
-- **Dynamic Method Access**: Access message body values using method names (e.g., `message.key`).
-- **Background Processing**: Run the server in a background thread to avoid blocking main execution.
-- **Robust Error Handling**: Gracefully handle socket disconnections and JSON parsing errors.
+- **Dual Socket Support**: Handle both Unix domain sockets and TCP sockets with
+  a consistent API
+- **Message Handling**: Simplify sending and receiving messages over sockets
+- **Dynamic Method Access**: Access message body values using method names
+  (e.g., `message.key`)
+- **Background Processing**: Run servers in background threads to avoid
+  blocking main execution
+- **Robust Error Handling**: Gracefully handle socket disconnections and JSON
+  parsing errors
+- **URL Interface**: Servers can be represented as URL strings for easy
+  configuration and discovery
 
 ## Installation
 
@@ -40,10 +48,14 @@ Create a server instance and start listening for connections:
 ```ruby
 require 'unix_socks'
 
-server = UnixSocks::Server.new(socket_name: 'my_socket')
+# For Unix sockets
+server = UnixSocks::DomainSocketServer.new(socket_name: 'my_socket')
+
+# For TCP sockets  
+server = UnixSocks::TCPSocketServer.new(hostname: 'localhost', port: 8080)
 
 # Run the server in the background to avoid blocking
-thread = server.receive_in_background(force: true) do |message|
+thread = server.receive_in_background do |message|
   puts "Received message: #{message.inspect}"
 end
 
@@ -55,7 +67,11 @@ thread.join
 Transmit messages to connected clients:
 
 ```ruby
-client = UnixSocks::Server.new(socket_name: 'my_socket')
+# For Unix sockets
+client = UnixSocks::DomainSocketServer.new(socket_name: 'my_socket')
+
+# For TCP sockets
+client = UnixSocks::TCPSocketServer.new(hostname: 'localhost', port: 8080)
 
 # Prepare your message
 message = { status: 'success', data: [1, 2, 3] }
@@ -71,7 +87,11 @@ Handle incoming messages and send responses:
 ```ruby
 require 'unix_socks'
 
-server = UnixSocks::Server.new(socket_name: 'my_socket')
+# For Unix sockets
+server = UnixSocks::DomainSocketServer.new(socket_name: 'my_socket')
+
+# For TCP sockets
+server = UnixSocks::TCPSocketServer.new(hostname: 'localhost', port: 8080)
 
 def handle_message(message)
   # Access message body values using method names
@@ -82,7 +102,7 @@ def handle_message(message)
 end
 
 # Use in your server setup
-thread = server.receive_in_background(force: true) do |message|
+thread = server.receive_in_background do |message|
   handle_message(message)
 end
 
@@ -91,23 +111,69 @@ thread.join
 
 And in the client:
 ```ruby
-client = UnixSocks::Server.new(socket_name: 'my_socket')
+# For Unix sockets
+client = UnixSocks::DomainSocketServer.new(socket_name: 'my_socket')
+
+# For TCP sockets
+client = UnixSocks::TCPSocketServer.new(hostname: 'localhost', port: 8080)
 
 # Prepare your message
 message = { status: 'success', data: [1, 2, 3] }
 
-# Send the message
+# Send the message and get a response
 response = client.transmit_with_response(message)
 
 # Receive the response
 puts "Received server response status: #{response.status}"
 ```
 
-### 4. Message Object Features
+### 4. Force Parameter Behavior
+
+The `force` parameter is only applicable to Unix domain socket servers and
+controls whether existing socket files should be overwritten:
+
+- **Unix Socket Servers**: When `force: true` is specified, existing socket
+  files will be overwritten without raising an error. Otherwise a
+  `UnixSocks::ServerError` is raised.
+- **TCP Socket Servers**: The `force` parameter is accepted for interface
+  compatibility but has no effect since TCP sockets don't use filesystem-based
+  socket files
+
+```ruby
+# Unix socket - force parameter works
+server = UnixSocks::DomainSocketServer.new(socket_name: 'my.sock')
+server.receive(force: true)  # Overwrites existing socket file if it exists
+
+# TCP socket - force parameter is ignored
+server = UnixSocks::TCPSocketServer.new(hostname: 'localhost', port: 8080)
+server.receive(force: true)  # Parameter has no effect
+```
+
+### 5. Server URL Interface
+
+Both server types support URL representation for easy configuration and discovery:
+
+```ruby
+# Unix socket server URL
+unix_server = UnixSocks::DomainSocketServer.new(socket_name: 'my.sock')
+unix_url = unix_server.to_url  # => "unix:///full/path/to/my.sock"
+
+# TCP socket server URL  
+tcp_server = UnixSocks::TCPSocketServer.new(hostname: 'localhost', port: 8080)
+tcp_url = tcp_server.to_url  # => "tcp://localhost:8080"
+
+# Use URLs for configuration
+server = UnixSocks.from_url(tcp_url)
+```
+
+### 6. Message Object Features
 
-- **Dynamic Access**: Methods like `message.status` automatically map to the message body.
-- **Disconnect Handling**: Safely close socket connections using `disconnect`.
-- **Error Resilience**: The `respond` method handles disconnections gracefully.
+- **Dynamic Access**: Methods like `message.status` automatically map to the
+  message body
+- **Disconnect Handling**: Safely close socket connections using `disconnect`
+- **Error Resilience**: The `respond` method handles disconnections gracefully
+- **Consistent Error Handling**: All server errors are wrapped in
+  `UnixSocks::ServerError`
 
 ## Author
 
@@ -115,4 +181,4 @@ puts "Received server response status: #{response.status}"
 
 ## License
 
-[MIT License](./LICENSE)
+[MIT License](LICENSE)

data/lib/unix_socks/{server.rb → domain_socket_server.rb}

@@ -1,9 +1,10 @@
 # Manages Unix socket-based communication, providing both server and client
 # functionality.
-class UnixSocks::Server
+class UnixSocks::DomainSocketServer
   include FileUtils
+  include UnixSocks::ServerShared
 
-  # Initializes a new UnixSocks::Server instance.
+  # Initializes a new UnixSocks::DomainSocketServer instance.
   #
   # @param socket_name [ String ] The name of the server socket file.
   # @param runtime_dir [ String, nil ] The path to the runtime directory where
@@ -13,6 +14,17 @@ class UnixSocks::Server
     @socket_name, @runtime_dir = socket_name, runtime_dir
   end
 
+  # Returns the URL representation of the server socket configuration.
+  #
+  # This method constructs and returns a URL string in the format "unix://path"
+  # that represents the Unix socket server's file path
+  # configuration.
+  #
+  # @return [ String ] A URL string in the format "unix://path"
+  def to_url
+    "unix://#{server_socket_path}"
+  end
+
   # Returns the default runtime directory path based on the XDG_RUNTIME_DIR
   # environment variable.
   #
@@ -47,29 +59,23 @@ class UnixSocks::Server
     File.expand_path(File.join(@runtime_dir, @socket_name))
   end
 
-  # The transmit method sends a message over the Unix socket connection.
+  # The transmit method sends a message over the Unix socket connection
   #
-  # It first prepares the message by converting it to JSON format, and then
-  # establishes a connection to the server socket using UNIXSocket.new.
+  # This method prepares a message by converting it to JSON format, establishes
+  # a connection to the server socket using UNIXSocket.new, writes the
+  # prepared message to the socket, and then returns the created socket
   #
-  # Finally, it writes the prepared message to the socket using socket.puts,
-  # ensuring that the socket is properly closed after use.
+  # @param message [ Object ] The message to be sent over the Unix socket
+  # @param close [ TrueClass, FalseClass ] Whether to close the socket after sending
   #
-  # @param message [ Message ] The message to be sent over the Unix socket.
-  def transmit(message)
+  # @return [ UNIXSocket ] The socket connection that was used to transmit the message
+  def transmit(message, close: false)
     mkdir_p @runtime_dir
     socket = UNIXSocket.new(server_socket_path)
     socket.puts JSON(message)
     socket
-  end
-
-  # Sends a message and returns the parsed JSON response.
-  #
-  # @param message [Object] The message to be sent as JSON.
-  # @return [Hash, nil] The parsed JSON response or nil if parsing fails.
-  def transmit_with_response(message)
-    socket = transmit(message)
-    parse_json_message(socket.gets, socket)
+  ensure
+    close and socket.close
   end
 
   # Receives messages from clients connected to the server socket.
@@ -87,7 +93,9 @@ class UnixSocks::Server
   def receive(force: false, &block)
     mkdir_p @runtime_dir
     if !force && socket_path_exist?
-      raise Errno::EEXIST, "Path already exists #{server_socket_path.inspect}"
+      raise UnixSocks::ServerError.build(
+        Errno::EEXIST, "Path already exists #{server_socket_path.inspect}"
+      )
     end
     Socket.unix_server_loop(server_socket_path) do |socket, client_addrinfo|
       message = pop_message(socket) and block.(message)
@@ -107,7 +115,9 @@ class UnixSocks::Server
   # @return [Thread] The background thread running the receiver
   def receive_in_background(force: false, &block)
     if !force && socket_path_exist?
-      raise Errno::EEXIST, "Path already exists #{server_socket_path.inspect}"
+      raise UnixSocks::ServerError.build(
+        Errno::EEXIST, "Path already exists #{server_socket_path.inspect}"
+      )
     end
     Thread.new do
       receive(force:, &block)
@@ -128,47 +138,4 @@ class UnixSocks::Server
   def remove_socket_path
     FileUtils.rm_f server_socket_path
   end
-
-  private
-
-  # Parses a JSON message from the socket and associates it with the socket
-  # connection
-  #
-  # This method retrieves a line of data from the socket, strips whitespace,
-  # and attempts to parse it as JSON. If successful, it creates a
-  # UnixSocks::Message object with the parsed data and assigns the socket
-  # connection to the message. If parsing fails, it logs a warning and
-  # returns nil.
-  #
-  # @param socket [ Socket ] the socket connection to read from
-  #
-  # @return [ UnixSocks::Message, nil ] the parsed message object or nil if
-  #   parsing fails
-  def pop_message(socket)
-    parse_json_message(socket.gets, socket)
-  end
-
-  # Parses a JSON message from the given data and associates it with the
-  # provided socket connection.
-  #
-  # This method processes the input data by stripping whitespace and attempting
-  # to parse it as JSON. If parsing is successful, it creates a
-  # UnixSocks::Message object with the parsed data and assigns the socket
-  # connection to the message. In case of a JSON parsing error, it
-  # logs a warning and returns nil.
-  #
-  # @param data [ String ] The raw data string to be parsed as JSON.
-  # @param socket [ Socket ] The socket connection associated with the message.
-  #
-  # @return [ UnixSocks::Message, nil ] The parsed message object or nil if
-  #   parsing fails.
-  def parse_json_message(data, socket)
-    data = data.strip
-    data.empty? and return nil
-    obj = JSON.parse(data, object_class: UnixSocks::Message)
-    obj.socket = socket
-    obj
-  rescue JSON::ParserError => e
-    warn "Caught #{e.class}: #{e} for #{data[0, 512].inspect}"
-  end
 end

data/lib/unix_socks/server_error.rb

@@ -0,0 +1,40 @@
+# Marker module for UnixSocks server-related errors.
+#
+# This module is mixed into exceptions raised by UnixSocks server
+# implementations to provide a common rescue clause for server-related
+# errors.
+#
+# @example Handling server errors
+#   begin
+#     server.receive { |message| process_message(message) }
+#   rescue UnixSocks::ServerError
+#     # Handle all UnixSocks server errors consistently
+#   end
+module UnixSocks::ServerError
+  # Builds a server error exception with the given exception class and message.
+  #
+  # This method creates a new exception instance of the specified exception
+  # class with the provided message, marks it with the ServerError module, and
+  # returns the marked exception.
+  #
+  # @param exception [ Class ] The exception class to be instantiated
+  # @param message [ String ] The error message for the exception
+  #
+  # @return [ Exception ] A new exception instance marked with ServerError module
+  def self.build(exception, message)
+    mark(exception.new(message))
+  end
+
+  # Marks the given exception with the ServerError module.
+  #
+  # This method extends the provided exception object with the ServerError
+  # module, effectively tagging it as a server-related error for consistent
+  # handling.
+  #
+  # @param e [ Exception ] The exception object to be marked
+  #
+  # @return [ Exception ] The same exception object, now extended with ServerError
+  def self.mark(e)
+    e.extend(self)
+  end
+end

data/lib/unix_socks/server_shared.rb

@@ -0,0 +1,70 @@
+# Shared server functionality for UnixSocks implementations
+#
+# This module provides common methods for transmitting messages and parsing
+# JSON responses that are used by both Unix domain socket and TCP socket
+# server implementations.
+module UnixSocks::ServerShared
+  # Sends a message and returns the parsed JSON response.
+  #
+  # @param message [Object] The message to be sent as JSON.
+  # @return [Hash, nil] The parsed JSON response or nil if parsing fails.
+  def transmit_with_response(message, close: true)
+    socket = transmit(message, close: false)
+    parse_json_message(socket.gets, socket)
+  ensure
+    close and socket.close
+  end
+
+  # Converts the server's URL representation into a URI object.
+  #
+  # This method takes the URL string returned by #to_url and parses it into
+  # a URI object for convenient access to the server's address components.
+  #
+  # @return [ URI ] A URI object representing the server's address configuration.
+  def to_uri
+    URI.parse(to_url)
+  end
+
+  private
+
+  # Parses a JSON message from the socket and associates it with the socket
+  # connection
+  #
+  # This method retrieves a line of data from the socket, strips whitespace,
+  # and attempts to parse it as JSON. If successful, it creates a
+  # UnixSocks::Message object with the parsed data and assigns the socket
+  # connection to the message. If parsing fails, it logs a warning and
+  # returns nil.
+  #
+  # @param socket [ Socket ] the socket connection to read from
+  #
+  # @return [ UnixSocks::Message, nil ] the parsed message object or nil if
+  #   parsing fails
+  def pop_message(socket)
+    parse_json_message(socket.gets, socket)
+  end
+
+  # Parses a JSON message from the given data and associates it with the
+  # provided socket connection.
+  #
+  # This method processes the input data by stripping whitespace and attempting
+  # to parse it as JSON. If parsing is successful, it creates a
+  # UnixSocks::Message object with the parsed data and assigns the socket
+  # connection to the message. In case of a JSON parsing error, it
+  # logs a warning and returns nil.
+  #
+  # @param data [ String ] The raw data string to be parsed as JSON.
+  # @param socket [ Socket ] The socket connection associated with the message.
+  #
+  # @return [ UnixSocks::Message, nil ] The parsed message object or nil if
+  #   parsing fails.
+  def parse_json_message(data, socket)
+    data = data.strip
+    data.empty? and return nil
+    obj = JSON.parse(data, object_class: UnixSocks::Message)
+    obj.socket = socket
+    obj
+  rescue JSON::ParserError => e
+    warn "Caught #{e.class}: #{e} for #{data[0, 512].inspect}"
+  end
+end

data/lib/unix_socks/tcp_socket_server.rb

@@ -0,0 +1,109 @@
+# Provides TCP socket-based communication for inter-process messaging.
+#
+# This class enables sending and receiving messages over TCP connections,
+# supporting both client and server functionality for network-based
+# communication.
+#
+# @example
+#   server = UnixSocks::TCPSocketServer.new(hostname: 'localhost', port: 8080)
+#   server.receive { |message| puts message.inspect }
+#   server.transmit({ message: 'hello' })
+class UnixSocks::TCPSocketServer
+  include UnixSocks::ServerShared
+
+  # Initializes a new UnixSocks::TCPSocketServer instance.
+  #
+  # Sets up the server with the specified hostname and port for TCP
+  # communication.
+  #
+  # @param hostname [ String ] The hostname to bind to, defaults to 'localhost'
+  # @param port [ Integer ] The port number to bind to
+  def initialize(hostname: 'localhost', port:)
+    @hostname, @port = hostname, port
+  end
+
+  # Returns the hostname associated with this TCP socket server instance.
+  #
+  # @return [ String ] The hostname that the server binds to for TCP communication.
+  attr_reader :hostname
+
+  # Returns the port number associated with this TCP socket server instance.
+  #
+  # @return [ Integer ] The port number that the server binds to for TCP communication.
+  attr_reader :port
+
+  # Returns the URL representation of the TCP socket server configuration.
+  #
+  # This method constructs and returns a URL string in the format
+  # "tcp://hostname:port" that represents the TCP socket server's address and
+  # port configuration.
+  #
+  # @return [ String ] A URL string in the format "tcp://hostname:port"
+  def to_url
+    "tcp://#@hostname:#@port"
+  end
+
+  # Sends a message over a TCP connection to the configured hostname and port.
+  #
+  # This method establishes a TCP socket connection to the specified hostname
+  # and port, serializes the provided message to JSON format, and writes it to
+  # the socket. The socket connection is returned after the message is sent.
+  #
+  # @param message [Object] The message to be sent, which will be converted to JSON
+  # @param close [TrueClass, FalseClass] Whether to close the socket after sending
+  #
+  # @return [TCPSocket] The socket connection that was used to transmit the message
+  def transmit(message, close: false)
+    socket = TCPSocket.new(@hostname, @port)
+    socket.puts JSON(message)
+    socket
+  ensure
+    close and socket.close
+  end
+
+  # Receives messages from clients connected to the TCP socket.
+  #
+  # This method binds to the configured hostname and port, listens for incoming
+  # connections, and processes messages from connected clients. It accepts a
+  # single connection at a time and handles each message by parsing it from
+  # JSON and yielding it to the provided block. The socket connection is closed
+  # after processing each message.
+  #
+  # @param force [ nil ] This parameter is accepted for interface compatibility
+  #   but is unused in the TCP implementation.
+  # @yield [ UnixSocks::Message ] The received message parsed from JSON.
+  #
+  # @raise [ Errno::EADDRINUSE ] If the address is already in use.
+  def receive(force: nil, &block)
+    Addrinfo.tcp(@hostname, @port).bind do |server|
+      server.listen(1)
+      loop do
+        socket, = server.accept
+        message = pop_message(socket) and block.(message)
+        socket.close
+      end
+    end
+  rescue Errno::EADDRINUSE => e
+    raise UnixSocks::ServerError.mark(e)
+  end
+
+  # Runs the message receiver in a background thread to prevent blocking.
+  #
+  # This method starts a new thread that continuously listens for incoming
+  # messages from connected clients. The server socket is created in the
+  # background, allowing the main execution flow to continue without
+  # waiting for messages.
+  #
+  # @param force [ nil ] This parameter is accepted for interface compatibility
+  #   but is unused in the TCP implementation.
+  # @yield [UnixSocks::Message] The received message
+  #
+  # @return [Thread] The background thread running the receiver
+  def receive_in_background(force: nil, &block)
+    Thread.new do
+      receive(&block)
+    rescue Errno::EADDRINUSE => e
+      raise UnixSocks::ServerError.mark(e)
+    end
+  end
+end

data/lib/unix_socks/version.rb

@@ -1,6 +1,6 @@
 module UnixSocks
   # UnixSocks version
-  VERSION         = '0.2.3'
+  VERSION         = '0.3.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/unix_socks.rb

@@ -1,14 +1,48 @@
 require 'json'
 require 'fileutils'
 require 'socket'
+require 'uri'
 require 'tins'
 
 # Provides classes for handling inter-process communication via Unix 🧦🧦.
 # Supports dynamic message handling, background processing, and robust error
 # management.
 module UnixSocks
+  # Creates a server instance from a URL string.
+  #
+  # This method parses a URL and constructs the appropriate server instance
+  # based on the scheme. For 'unix' URLs, it creates a DomainSocketServer,
+  # and for 'tcp' URLs, it creates a TCPSocketServer.
+  #
+  # @param url [String, URI] The URL string or URI object representing the
+  #   server configuration
+  #
+  # @return [UnixSocks::DomainSocketServer, UnixSocks::TCPSocketServer] The
+  #   constructed server instance
+  #
+  # @raise [ArgumentError] If the URL scheme is not 'unix' or 'tcp'
+  def self.from_url(url)
+    uri = url.is_a?(URI) ? url : URI.parse(url.to_s)
+    case uri.scheme
+    when 'unix'
+      DomainSocketServer.new(
+        socket_name: File.basename(uri.path),
+        runtime_dir: File.dirname(uri.path)
+      )
+    when 'tcp'
+      TCPSocketServer.new(
+        hostname: uri.host,
+        port:     uri.port
+      )
+    else
+      raise ArgumentError, "Invalid URL #{url.to_s.inspect} for UnixSocks"
+    end
+  end
 end
 
 require 'unix_socks/version'
+require 'unix_socks/server_error'
 require 'unix_socks/message'
-require 'unix_socks/server'
+require 'unix_socks/server_shared'
+require 'unix_socks/domain_socket_server'
+require 'unix_socks/tcp_socket_server'

data/spec/unix_socks/{server_spec.rb → domain_socket_server_spec.rb}

@@ -1,10 +1,12 @@
 require 'spec_helper'
 require 'tins/xt/expose'
 
-describe UnixSocks::Server do
+describe UnixSocks::DomainSocketServer do
   let(:socket_name) { 'test_socket' }
   let(:runtime_dir) { './tmp' }
-  let(:server) { UnixSocks::Server.new(socket_name: socket_name, runtime_dir: runtime_dir).expose }
+  let(:server) {
+    described_class.new(socket_name: socket_name, runtime_dir: runtime_dir).expose
+  }
 
   describe '#initialize' do
     it 'sets the socket name and runtime directory' do
@@ -46,9 +48,18 @@ describe UnixSocks::Server do
     it 'sends a message over the Unix socket' do
       expect(server).to receive(:mkdir_p).with(runtime_dir)
       expect(UNIXSocket).to receive(:new).with(server.server_socket_path).
-        and_return(double('socket', puts: nil, close: nil))
+        and_return(double('socket', puts: nil))
       server.transmit(message)
     end
+
+    it 'sends a message over the Unix socket and close' do
+      expect(server).to receive(:mkdir_p).with(runtime_dir)
+      socket = double('socket', puts: nil)
+      expect(UNIXSocket).to receive(:new).with(server.server_socket_path).
+        and_return(socket)
+      expect(socket).to receive(:close)
+      server.transmit(message, close: true)
+    end
   end
 
   describe '#transmit_with_response' do
@@ -56,7 +67,12 @@ describe UnixSocks::Server do
 
     it 'parses a valid JSON response' do
       allow(server).to receive(:mkdir_p)
-      mock_socket = double('socket', puts: nil, gets: '{"status": "success"}')
+      mock_socket = double(
+        'socket',
+        puts: nil,
+        gets: '{"status": "success"}',
+        close: true
+      )
       expect(UNIXSocket).to receive(:new).and_return(mock_socket)
 
       response = server.transmit_with_response(message)
@@ -66,7 +82,12 @@ describe UnixSocks::Server do
 
     it 'handles JSON parsing errors' do
       allow(server).to receive(:mkdir_p)
-      mock_socket = double('socket', puts: nil, gets: 'invalid_json')
+      mock_socket = double(
+        'socket',
+        puts: nil,
+        gets: 'invalid_json',
+        close: true
+      )
       expect(server).to receive(:warn).
         with(/Caught JSON::ParserError: unexpected character: 'invalid_json'/)
       expect(UNIXSocket).to receive(:new).and_return(mock_socket)
@@ -77,7 +98,12 @@ describe UnixSocks::Server do
 
     it 'handles empty responses' do
       allow(server).to receive(:mkdir_p)
-      mock_socket = double('socket', puts: nil, gets: '')
+      mock_socket = double(
+        'socket',
+        puts: nil,
+        gets: '',
+        close: true
+      )
       expect(UNIXSocket).to receive(:new).and_return(mock_socket)
 
       response = server.transmit_with_response(message)
@@ -89,7 +115,7 @@ describe UnixSocks::Server do
     it 'raises an error if the socket already exists and force is false' do
       allow(server).to receive(:socket_path_exist?).and_return(true)
       expect { server.receive(force: false) }.to\
-        raise_error(Errno::EEXIST, /Path already exists/)
+        raise_error(UnixSocks::ServerError, /Path already exists/)
     end
 
     it 'does not raise an error if force is true' do
@@ -120,15 +146,15 @@ describe UnixSocks::Server do
 
   describe '#receive_in_background' do
     it 'runs the receiver in a background thread' do
-      expect(Thread).to receive(:new).and_yield
+      expect(Thread).to receive(:new).and_yield.and_return(double(join: true))
       expect(FileUtils).to receive(:rm_f).with(server.server_socket_path)
       expect(server).to receive(:at_exit) { |&block| block.call }
       expect(server).to receive(:receive).with(force: true)
 
-      server.receive_in_background(force: true)
+      server.receive_in_background(force: true).join
     end
 
-    it 'it raises Errno::EEXIST if socket already exists' do
+    it 'it raises UnixSocks::ServerError if socket already exists' do
       expect(Thread).not_to receive(:new).and_yield
       expect(FileUtils).not_to receive(:rm_f).with(server.server_socket_path)
       expect(server).to receive(:socket_path_exist?).and_return true
@@ -136,22 +162,28 @@ describe UnixSocks::Server do
       expect(server).not_to receive(:receive).with(force: false)
 
       expect {
-        server.receive_in_background(force: false)
-      }.to raise_error(Errno::EEXIST)
+        server.receive_in_background(force: false).join
+      }.to raise_error(UnixSocks::ServerError)
     end
 
-    it 'runs the receiver in a background thread' do
-      expect(Thread).to receive(:new).and_yield
+    it 'runs the receiver in a background thread ignoring existing sockets' do
+      expect(Thread).to receive(:new).and_yield.and_return(double(join: true))
       expect(FileUtils).to receive(:rm_f).with(server.server_socket_path)
       expect(server).to receive(:at_exit) { |&block| block.call }
       expect(server).to receive(:receive).and_raise Errno::ENOENT
 
       expect {
-        server.receive_in_background(force: true)
+        server.receive_in_background(force: true).join
       }.not_to raise_error
     end
   end
 
+  describe '#to_uri' do
+    it 'displays address' do
+      expect(server.to_url).to match %r(\Aunix://.*test_socket\z)
+    end
+  end
+
   describe '#socket_path_exist?' do
     it 'returns false if the socket file does not exist' do
       FileUtils.rm_f(server.server_socket_path)

data/spec/unix_socks/server_interface_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe 'UnixSocks::Server Interface' do
+  shared_examples 'sufficient interface' do
+    it 'supports transmit' do
+      expect(described_class).to be_method_defined :transmit
+    end
+
+    it 'supports transmit_with_response' do
+      expect(described_class).to be_method_defined :transmit_with_response
+    end
+
+    it 'supports receive' do
+      expect(described_class).to be_method_defined :receive
+    end
+
+    it 'supports receive_in_background' do
+      expect(described_class).to be_method_defined :receive_in_background
+    end
+
+    it 'supports to_uri' do
+      expect(described_class).to be_method_defined :to_url
+    end
+  end
+
+  context UnixSocks::DomainSocketServer do
+    it_behaves_like 'sufficient interface'
+  end
+
+  context UnixSocks::TCPSocketServer do
+    it_behaves_like 'sufficient interface'
+  end
+end

data/spec/unix_socks/tcp_socket_server_spec.rb

@@ -0,0 +1,137 @@
+require 'spec_helper'
+require 'tins/xt/expose'
+
+describe UnixSocks::TCPSocketServer do
+  let(:server) { described_class.new(hostname: 'localhost', port: 1234).expose }
+
+  describe '#initialize' do
+    it 'sets the socket name and runtime directory' do
+      expect(server.instance_variable_get(:@hostname)).to eq('localhost')
+      expect(server.instance_variable_get(:@port)).to eq(1234)
+    end
+  end
+
+  describe '#transmit' do
+    let(:message) { { test: 'message' } }
+
+    it 'sends a message over the Unix socket' do
+      expect(TCPSocket).to receive(:new).with(server.hostname, server.port).
+        and_return(double('socket', puts: nil))
+      server.transmit(message)
+    end
+
+    it 'sends a message over the Unix socket and close' do
+      socket = double('socket', puts: nil)
+      expect(TCPSocket).to receive(:new).with(server.hostname, server.port).
+        and_return(socket)
+      expect(socket).to receive(:close)
+      server.transmit(message, close: true)
+    end
+  end
+
+  describe '#transmit_with_response' do
+    let(:message) { { test: 'message' } }
+
+    it 'parses a valid JSON response' do
+      allow(server).to receive(:mkdir_p)
+      socket = double(
+        'socket',
+        puts: nil,
+        gets: '{"status": "success"}',
+        close: true
+      )
+      expect(TCPSocket).to receive(:new).and_return(socket)
+
+      response = server.transmit_with_response(message)
+      expect(response).to be_a UnixSocks::Message
+      expect(response.status).to eq 'success'
+    end
+
+    it 'handles JSON parsing errors' do
+      allow(server).to receive(:mkdir_p)
+      socket = double(
+        'socket',
+        puts: nil,
+        gets: 'invalid_json',
+        close: true
+      )
+      expect(server).to receive(:warn).
+        with(/Caught JSON::ParserError: unexpected character: 'invalid_json'/)
+      expect(TCPSocket).to receive(:new).and_return(socket)
+
+      response = server.transmit_with_response(message)
+      expect(response).to be nil
+    end
+
+    it 'handles empty responses' do
+      allow(server).to receive(:mkdir_p)
+      socket = double(
+        'socket',
+        puts: nil,
+        gets: '',
+        close: true
+      )
+      expect(TCPSocket).to receive(:new).and_return(socket)
+
+      response = server.transmit_with_response(message)
+      expect(response).to be nil
+    end
+  end
+
+  describe '#receive' do
+    it 'does bind to hostname:port' do
+      expect(Addrinfo).to receive(:tcp).with(server.hostname, server.port).
+        and_return(double(bind: true))
+      server.receive
+    end
+
+    it 'raises UnixSocks::ServerError if already bound' do
+      socket = double('socket')
+      expect(Addrinfo).to receive(:tcp).with(server.hostname, server.port).
+        and_return(socket)
+      expect(socket).to receive(:bind).and_raise Errno::EADDRINUSE
+      expect { server.receive }.to raise_error(UnixSocks::ServerError)
+    end
+  end
+
+  describe 'pop_message' do
+    it 'parses a valid JSON message' do
+      socket = double('socket')
+      allow(socket).to receive(:gets).and_return('{"test": "message"}')
+
+      message = server.pop_message(socket)
+      expect(message).to be_a(UnixSocks::Message)
+      expect(message.test).to eq 'message'
+    end
+
+    it 'handles a JSON parsing error' do
+      socket = double('socket')
+      allow(socket).to receive(:gets).and_return('invalid_json')
+      expect(server).to receive(:warn).
+        with(/Caught JSON::ParserError: unexpected character: 'invalid_json'/)
+      expect(server.pop_message(socket)).to be nil
+    end
+  end
+
+  describe '#receive_in_background' do
+    it 'runs the receiver in a background thread' do
+      expect(Thread).to receive(:new).and_yield.and_return(double(join: true))
+      expect(server).to receive(:receive)
+
+      server.receive_in_background.join
+    end
+
+    it 'it raises UnixSocks::ServerError if socket already exists' do
+      expect(server).to receive(:receive).and_raise(Errno::EADDRINUSE)
+      expect {
+        server.receive_in_background.join
+      }.to raise_error(UnixSocks::ServerError)
+    end
+  end
+
+  describe '#to_uri' do
+    it 'displays address' do
+      expect(server.to_url).to eq 'tcp://localhost:1234'
+    end
+  end
+end

data/spec/unix_socks_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+describe UnixSocks do
+  describe '.from_url' do
+    context 'with unix URL' do
+      it 'creates a DomainSocketServer' do
+        server = UnixSocks.from_url('unix:///tmp/my.sock')
+        expect(server).to be_a(UnixSocks::DomainSocketServer)
+      end
+
+      it 'sets correct socket name and runtime directory' do
+        server = UnixSocks.from_url('unix:///tmp/my.sock')
+        expect(server.instance_variable_get(:@socket_name)).to eq('my.sock')
+        expect(server.instance_variable_get(:@runtime_dir)).to eq('/tmp')
+      end
+
+      it 'handles unix URL with different runtime directory' do
+        server = UnixSocks.from_url('unix:///var/run/my.sock')
+        expect(server.instance_variable_get(:@socket_name)).to eq('my.sock')
+        expect(server.instance_variable_get(:@runtime_dir)).to eq('/var/run')
+      end
+
+      it 'works with URI objects' do
+        uri = URI.parse('unix:///tmp/test.sock')
+        server = UnixSocks.from_url(uri)
+        expect(server).to be_a(UnixSocks::DomainSocketServer)
+        expect(server.instance_variable_get(:@socket_name)).to eq('test.sock')
+      end
+    end
+
+    context 'with tcp URL' do
+      it 'creates a TCPSocketServer' do
+        server = UnixSocks.from_url('tcp://localhost:8080')
+        expect(server).to be_a(UnixSocks::TCPSocketServer)
+      end
+
+      it 'sets correct hostname and port' do
+        server = UnixSocks.from_url('tcp://example.com:9000')
+        expect(server.instance_variable_get(:@hostname)).to eq('example.com')
+        expect(server.instance_variable_get(:@port)).to eq(9000)
+      end
+
+      it 'works with default port' do
+        server = UnixSocks.from_url('tcp://localhost:80')
+        expect(server.instance_variable_get(:@hostname)).to eq('localhost')
+        expect(server.instance_variable_get(:@port)).to eq(80)
+      end
+
+      it 'works with URI objects' do
+        uri = URI.parse('tcp://localhost:8080')
+        server = UnixSocks.from_url(uri)
+        expect(server).to be_a(UnixSocks::TCPSocketServer)
+        expect(server.instance_variable_get(:@hostname)).to eq('localhost')
+        expect(server.instance_variable_get(:@port)).to eq(8080)
+      end
+    end
+
+    context 'with invalid URL' do
+      it 'raises ArgumentError for unsupported scheme' do
+        expect {
+          UnixSocks.from_url('ftp://example.com/file')
+        }.to raise_error(ArgumentError, /Invalid URL.*ftp/)
+      end
+
+      it 'raises ArgumentError for invalid URL format' do
+        expect {
+          UnixSocks.from_url('not_a_url')
+        }.to raise_error(ArgumentError)
+      end
+    end
+
+    context 'with edge cases' do
+      it 'handles URLs with query parameters' do
+        server = UnixSocks.from_url('unix:///tmp/test.sock?param=value')
+        expect(server).to be_a(UnixSocks::DomainSocketServer)
+        expect(server.instance_variable_get(:@socket_name)).to eq('test.sock')
+      end
+
+      it 'handles URLs with fragments' do
+        server = UnixSocks.from_url('tcp://localhost:8080#fragment')
+        expect(server).to be_a(UnixSocks::TCPSocketServer)
+        expect(server.instance_variable_get(:@hostname)).to eq('localhost')
+        expect(server.instance_variable_get(:@port)).to eq(8080)
+      end
+    end
+  end
+
+  describe 'integration test' do
+    it 'can create and use unix server from URL' do
+      server = UnixSocks.from_url('unix:///tmp/test.sock')
+      expect(server).to be_a(UnixSocks::DomainSocketServer)
+      expect(server.to_url).to match(%r{^unix://.*test\.sock$})
+    end
+
+    it 'can create and use tcp server from URL' do
+      server = UnixSocks.from_url('tcp://localhost:8080')
+      expect(server).to be_a(UnixSocks::TCPSocketServer)
+      expect(server.to_url).to eq('tcp://localhost:8080')
+    end
+  end
+end

data/unix_socks.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: unix_socks 0.2.3 ruby lib
+# stub: unix_socks 0.3.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "unix_socks".freeze
-  s.version = "0.2.3".freeze
+  s.version = "0.3.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -11,15 +11,15 @@ Gem::Specification.new do |s|
   s.date = "1980-01-02"
   s.description = "This library enables communication between processes using Unix sockets. It\nhandles message transmission, socket management, and cleanup, supporting\nboth synchronous and asynchronous operations while providing error handling\nfor robust development.\n".freeze
   s.email = "flori@ping.de".freeze
-  s.extra_rdoc_files = ["README.md".freeze, "lib/unix_socks.rb".freeze, "lib/unix_socks/message.rb".freeze, "lib/unix_socks/server.rb".freeze, "lib/unix_socks/version.rb".freeze]
-  s.files = ["CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "lib/unix_socks.rb".freeze, "lib/unix_socks/message.rb".freeze, "lib/unix_socks/server.rb".freeze, "lib/unix_socks/version.rb".freeze, "spec/spec_helper.rb".freeze, "spec/unix_socks/message_spec.rb".freeze, "spec/unix_socks/server_spec.rb".freeze, "unix_socks.gemspec".freeze]
+  s.extra_rdoc_files = ["README.md".freeze, "lib/unix_socks.rb".freeze, "lib/unix_socks/domain_socket_server.rb".freeze, "lib/unix_socks/message.rb".freeze, "lib/unix_socks/server_error.rb".freeze, "lib/unix_socks/server_shared.rb".freeze, "lib/unix_socks/tcp_socket_server.rb".freeze, "lib/unix_socks/version.rb".freeze]
+  s.files = ["CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "lib/unix_socks.rb".freeze, "lib/unix_socks/domain_socket_server.rb".freeze, "lib/unix_socks/message.rb".freeze, "lib/unix_socks/server_error.rb".freeze, "lib/unix_socks/server_shared.rb".freeze, "lib/unix_socks/tcp_socket_server.rb".freeze, "lib/unix_socks/version.rb".freeze, "spec/spec_helper.rb".freeze, "spec/unix_socks/domain_socket_server_spec.rb".freeze, "spec/unix_socks/message_spec.rb".freeze, "spec/unix_socks/server_interface_spec.rb".freeze, "spec/unix_socks/tcp_socket_server_spec.rb".freeze, "spec/unix_socks_spec.rb".freeze, "unix_socks.gemspec".freeze]
   s.homepage = "https://github.com/flori/unix_socks".freeze
   s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "UnixSocks - A Ruby library for inter-process communication via Unix sockets with\ndynamic message handling\n".freeze, "--main".freeze, "README.md".freeze]
   s.required_ruby_version = Gem::Requirement.new(">= 3.1".freeze)
   s.rubygems_version = "4.0.2".freeze
   s.summary = "A Ruby library for inter-process communication via Unix sockets with dynamic message handling".freeze
-  s.test_files = ["spec/spec_helper.rb".freeze, "spec/unix_socks/message_spec.rb".freeze, "spec/unix_socks/server_spec.rb".freeze]
+  s.test_files = ["spec/spec_helper.rb".freeze, "spec/unix_socks/domain_socket_server_spec.rb".freeze, "spec/unix_socks/message_spec.rb".freeze, "spec/unix_socks/server_interface_spec.rb".freeze, "spec/unix_socks/tcp_socket_server_spec.rb".freeze, "spec/unix_socks_spec.rb".freeze]
 
   s.specification_version = 4
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: unix_socks
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Florian Frank
@@ -132,8 +132,11 @@ extensions: []
 extra_rdoc_files:
 - README.md
 - lib/unix_socks.rb
+- lib/unix_socks/domain_socket_server.rb
 - lib/unix_socks/message.rb
-- lib/unix_socks/server.rb
+- lib/unix_socks/server_error.rb
+- lib/unix_socks/server_shared.rb
+- lib/unix_socks/tcp_socket_server.rb
 - lib/unix_socks/version.rb
 files:
 - CHANGES.md
@@ -142,12 +145,18 @@ files:
 - README.md
 - Rakefile
 - lib/unix_socks.rb
+- lib/unix_socks/domain_socket_server.rb
 - lib/unix_socks/message.rb
-- lib/unix_socks/server.rb
+- lib/unix_socks/server_error.rb
+- lib/unix_socks/server_shared.rb
+- lib/unix_socks/tcp_socket_server.rb
 - lib/unix_socks/version.rb
 - spec/spec_helper.rb
+- spec/unix_socks/domain_socket_server_spec.rb
 - spec/unix_socks/message_spec.rb
-- spec/unix_socks/server_spec.rb
+- spec/unix_socks/server_interface_spec.rb
+- spec/unix_socks/tcp_socket_server_spec.rb
+- spec/unix_socks_spec.rb
 - unix_socks.gemspec
 homepage: https://github.com/flori/unix_socks
 licenses:
@@ -179,5 +188,8 @@ summary: A Ruby library for inter-process communication via Unix sockets with dy
   message handling
 test_files:
 - spec/spec_helper.rb
+- spec/unix_socks/domain_socket_server_spec.rb
 - spec/unix_socks/message_spec.rb
-- spec/unix_socks/server_spec.rb
+- spec/unix_socks/server_interface_spec.rb
+- spec/unix_socks/tcp_socket_server_spec.rb
+- spec/unix_socks_spec.rb