Class: UnixSocks::DomainSocketServer

Inherits:
Object
  • Object
show all
Includes:
FileUtils, ServerShared
Defined in:
lib/unix_socks/domain_socket_server.rb

Overview

Manages Unix socket-based communication, providing both server and client functionality.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ServerShared

#to_uri, #transmit_with_response

Constructor Details

#initialize(socket_name:, runtime_dir: default_runtime_dir) ⇒ DomainSocketServer

Initializes a new UnixSocks::DomainSocketServer instance.

Parameters:

  • socket_name (String) —

    The name of the server socket file.

  • runtime_dir (String, nil) (defaults to: default_runtime_dir) —

    The path to the runtime directory where the server socket will be created. If not provided, it defaults to the value returned by #default_runtime_dir.



13
14
15
 
# File 'lib/unix_socks/domain_socket_server.rb', line 13

def initialize(socket_name:, runtime_dir: default_runtime_dir)
  @socket_name, @runtime_dir = socket_name, runtime_dir
end

Class Method Details

.default_runtime_dir ⇒ String

Returns the default runtime directory path based on the XDG_RUNTIME_DIR environment variable.

If the XDG_RUNTIME_DIR environment variable is set, its value is used as the runtime directory path. Otherwise, the default path ‘~/.local/run’ is returned.

Returns:

  • (String) —

    The default runtime directory path.



48
49
50
 
# File 'lib/unix_socks/domain_socket_server.rb', line 48

def self.default_runtime_dir
  File.expand_path(ENV.fetch('XDG_RUNTIME_DIR',  '~/.local/run'))
end

Instance Method Details

#default_runtime_dir ⇒ String

Returns the default runtime directory path based on the XDG_RUNTIME_DIR environment variable.

If the XDG_RUNTIME_DIR environment variable is set, its value is used as the runtime directory path. Otherwise, the default path ‘~/.local/run’ is used.

Returns:

  • (String) —

    The default runtime directory path.



36
37
38
 
# File 'lib/unix_socks/domain_socket_server.rb', line 36

def default_runtime_dir
  self.class.default_runtime_dir
end

#receive(force: false, permission: 0600) {|UnixSocks::Message| ... } ⇒ Object

Receives messages from clients connected to the server socket.

This method establishes a connection to the server socket and listens for incoming messages. When a message is received, it is parsed as JSON and converted into a UnixSocks::Message object. The block provided to this method is then called with the message object as an argument.

If the ‘force` parameter is set to true, any existing server socket file will be overwritten without raising an error.

Parameters:

  • force (Boolean) (defaults to: false) —

    Whether to overwrite any existing server socket file.

Yields:



93
94
95
96
97
98
99
100
101
102
 
# File 'lib/unix_socks/domain_socket_server.rb', line 93

def receive(force: false, permission: 0600, &block)
  block or raise ArgumentError, 'require &block argument to receive messages'
  mkdir_p @runtime_dir
  if !force && socket_path_exist?
    raise UnixSocks::ServerError.build(
      Errno::EEXIST, "Path already exists #{server_socket_path.inspect}"
    )
  end
  loop_for_path(server_socket_path, permission:, &block)
end

#receive_in_background(force: false) {|UnixSocks::Message| ... } ⇒ Thread

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.

Parameters:

  • force (Boolean) (defaults to: false) —

    Whether to overwrite any existing server socket file

Yields:

Returns:

  • (Thread) —

    The background thread running the receiver



115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/unix_socks/domain_socket_server.rb', line 115

def receive_in_background(force: false, &block)
  if !force && socket_path_exist?
    raise UnixSocks::ServerError.build(
      Errno::EEXIST, "Path already exists #{server_socket_path.inspect}"
    )
  end
  Thread.new do
    receive(force:, &block)
  rescue Errno::ENOENT
  ensure
    at_exit { remove_socket_path }
  end
end

#remove_socket_path ⇒ Object

Safely removes the server socket file from the filesystem.



137
138
139
 
# File 'lib/unix_socks/domain_socket_server.rb', line 137

def remove_socket_path
  FileUtils.rm_f server_socket_path
end

#server_socket_path ⇒ String

Returns the path to the server socket file.

This method constructs the full path to the server socket by joining the runtime directory and the socket name.

Returns:

  • (String) —

    The path to the server socket file.



58
59
60
 
# File 'lib/unix_socks/domain_socket_server.rb', line 58

def server_socket_path
  File.expand_path(File.join(@runtime_dir, @socket_name))
end

#socket_path_exist? ⇒ Boolean

Checks if the server socket file exists.

Returns:

  • (Boolean) —

    True if the socket file exists, false otherwise.



132
133
134
 
# File 'lib/unix_socks/domain_socket_server.rb', line 132

def socket_path_exist?
  File.exist?(server_socket_path)
end

#to_url ⇒ String

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.

Returns:

  • (String) —

    A URL string in the format “unix://path”



24
25
26
 
# File 'lib/unix_socks/domain_socket_server.rb', line 24

def to_url
  "unix://#{server_socket_path}"
end

#transmit(message, close: false) ⇒ UNIXSocket

The transmit method sends a message over the Unix socket connection

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

Parameters:

  • message (Object) —

    The message to be sent over the Unix socket

  • close (TrueClass, FalseClass) (defaults to: false) —

    Whether to close the socket after sending

Returns:

  • (UNIXSocket) —

    The socket connection that was used to transmit the message



72
73
74
75
76
77
78
79
 
# File 'lib/unix_socks/domain_socket_server.rb', line 72

def transmit(message, close: false)
  mkdir_p @runtime_dir
  socket = UNIXSocket.new(server_socket_path)
  socket.puts JSON(message)
  socket
ensure
  close and socket&.close
end