Class: TLQClient

Inherits:
Object
  • Object
show all
Defined in:
lib/tlq_client.rb,
lib/tlq_client/version.rb

Overview

A client library for communicating with a TLQ (Tiny Little Queue) server.

TLQClient provides a simple interface for message queue operations including adding, retrieving, deleting, and retrying messages.

Examples:

Basic usage

client = TLQClient.new(host: 'localhost', port: 1337)

# Add a message
message = client.add_message("Hello, TLQ!")

# Retrieve messages
messages = client.get_messages(5)

# Process and delete
ids = messages.map { |m| m['id'] }
client.delete_messages(ids)

See Also:

Constant Summary collapse

VERSION =

The current version of the TLQClient gem.

Returns:

  • (String) —

    the semantic version string

"0.2.1"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host: 'localhost', port: 1337) ⇒ TLQClient

Creates a new TLQClient instance.

Examples:

Connect to default server

client = TLQClient.new

Connect to custom server

client = TLQClient.new(host: 'tlq.skyak.tech', port: 8080)

Parameters:

  • host (String) (defaults to: 'localhost') —

    the hostname of the TLQ server (default: ‘localhost’)

  • port (Integer) (defaults to: 1337) —

    the port number of the TLQ server (default: 1337)



47
48
49
50
51
 
# File 'lib/tlq_client.rb', line 47

def initialize(host: 'localhost', port: 1337)
  @host = host
  @port = port
  @base_uri = "http://#{@host}:#{@port}"
end

Instance Attribute Details

#base_uri ⇒ String (readonly)

Returns the base URI for API requests.

Returns:

  • (String) —

    the base URI for API requests



35
36
37
 
# File 'lib/tlq_client.rb', line 35

def base_uri
  @base_uri
end

#host ⇒ String (readonly)

Returns the hostname of the TLQ server.

Returns:

  • (String) —

    the hostname of the TLQ server



29
30
31
 
# File 'lib/tlq_client.rb', line 29

def host
  @host
end

#port ⇒ Integer (readonly)

Returns the port number of the TLQ server.

Returns:

  • (Integer) —

    the port number of the TLQ server



32
33
34
 
# File 'lib/tlq_client.rb', line 32

def port
  @port
end

Instance Method Details

#add_message(body) ⇒ Hash

Adds a message to the queue.

Examples:

Add a simple string message

message = client.add_message("Hello, World!")
puts message['id']  # => "abc123"

Add a hash message

message = client.add_message({ event: 'user_signup', user_id: 42 })

Parameters:

  • body (String, Hash, Array) —

    the message body to add to the queue. Can be a string or any JSON-serializable object.

Returns:

  • (Hash) —

    the created message object containing ‘id’, ‘body’, and metadata

Raises:

  • (RuntimeError) —

    if the server response cannot be parsed as JSON

  • (RuntimeError) —

    if the HTTP request fails



69
70
71
72
73
74
75
76
 
# File 'lib/tlq_client.rb', line 69

def add_message(body)
  response = post('/add', { body: body })
  JSON.parse(response.body)
rescue JSON::ParserError => e
  raise "Failed to parse response: #{e.message}"
rescue StandardError => e
  raise "HTTP request failed: #{e.message}"
end

#delete_messages(ids) ⇒ Boolean

Deletes messages from the queue permanently.

Use this method to acknowledge successful processing of messages. Once deleted, messages cannot be recovered.

Examples:

Delete a single message

client.delete_messages("abc123")

Delete multiple messages

client.delete_messages(["abc123", "def456", "ghi789"])

Parameters:

  • ids (String, Array<String>) —

    a single message ID or array of message IDs to delete

Returns:

  • (Boolean) —

    true if the deletion was successful

Raises:

  • (RuntimeError) —

    if the HTTP request fails



124
125
126
127
128
129
 
# File 'lib/tlq_client.rb', line 124

def delete_messages(ids)
  response = post('/delete', { ids: Array(ids) })
  response.body == '"Success"'
rescue StandardError => e
  raise "HTTP request failed: #{e.message}"
end

#get_messages(count = 1) ⇒ Array<Hash>

Retrieves messages from the queue.

Messages are leased to the client and must be either deleted (to acknowledge successful processing) or retried (to return them to the queue).

Examples:

Get a single message

messages = client.get_messages
message = messages.first
puts message['body']

Get multiple messages

messages = client.get_messages(10)
messages.each { |m| process(m) }

Parameters:

  • count (Integer) (defaults to: 1) —

    the number of messages to retrieve (default: 1)

Returns:

  • (Array<Hash>) —

    an array of message objects, each containing ‘id’ and ‘body’

Raises:

  • (RuntimeError) —

    if the server response cannot be parsed as JSON

  • (RuntimeError) —

    if the HTTP request fails



98
99
100
101
102
103
104
105
106
 
# File 'lib/tlq_client.rb', line 98

def get_messages(count = 1)
  response = post('/get', { count: count })
  parsed = JSON.parse(response.body)
  parsed.is_a?(Array) ? parsed : Array(parsed['messages'] || parsed)
rescue JSON::ParserError => e
  raise "Failed to parse response: #{e.message}"
rescue StandardError => e
  raise "HTTP request failed: #{e.message}"
end

#health_check ⇒ Boolean

Checks if the TLQ server is reachable and responding.

Examples:

Check server status

if client.health_check
  puts "Server is running"
end

Returns:

  • (Boolean) —

    true if the server is healthy and responding

Raises:

  • (RuntimeError) —

    if the health check request fails



181
182
183
184
185
186
187
 
# File 'lib/tlq_client.rb', line 181

def health_check
  uri = URI("#{@base_uri}/hello")
  response = Net::HTTP.get_response(uri)
  response.body == '"Hello World"'
rescue StandardError => e
  raise "Health check failed: #{e.message}"
end

#purge_queue ⇒ Boolean

Note:

This operation is irreversible. All messages will be permanently deleted.

Purges all messages from the queue.

Examples:

Clear the queue

client.purge_queue

Returns:

  • (Boolean) —

    true if the purge was successful

Raises:

  • (RuntimeError) —

    if the HTTP request fails



164
165
166
167
168
169
 
# File 'lib/tlq_client.rb', line 164

def purge_queue
  response = post('/purge', {})
  response.body == '"Success"'
rescue StandardError => e
  raise "HTTP request failed: #{e.message}"
end

#retry_messages(ids) ⇒ Boolean

Returns messages to the queue for reprocessing.

Use this method when message processing fails and you want to retry later. The messages will be returned to the queue and can be retrieved again.

Examples:

Retry a single message

client.retry_messages("abc123")

Retry multiple messages

client.retry_messages(["abc123", "def456"])

Parameters:

  • ids (String, Array<String>) —

    a single message ID or array of message IDs to retry

Returns:

  • (Boolean) —

    true if the retry was successful

Raises:

  • (RuntimeError) —

    if the HTTP request fails



147
148
149
150
151
152
 
# File 'lib/tlq_client.rb', line 147

def retry_messages(ids)
  response = post('/retry', { ids: Array(ids) })
  response.body == '"Success"'
rescue StandardError => e
  raise "HTTP request failed: #{e.message}"
end