tlq-client 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23e82549788eabfb735a5035d8b8f478df7e570a6b1c43338ea28714f2ef0824
-  data.tar.gz: 584f2eb0f74e20b8df96401630c5843184c15b31f48e693739f159f5ba22f42a
+  metadata.gz: '0888c52bfd5c94d767673f92efe410094daa86fa50d844408e4830cee364130a'
+  data.tar.gz: 796ed9252ce96e44464f39b99296d09ce7a3763cb2d0eb62594e40fad98c3a41
 SHA512:
-  metadata.gz: a2da29977ea8ea209bcd448c8928b59e58ef76c3bf0b55ce0f8008edd9a12070832eb3af46c1c5c350cefee41484a43f41dc279ab7b78effa0c928e84de05645
-  data.tar.gz: 44d102142b0750efca0db88d4f7fba9f9cf8891117c8456bf852604a0eb59d65f63b6e590b6b9a4da8ffd034449e771d230a19423a4d4a813f46f13c05684c4d
+  metadata.gz: c986e9700b352ebb948511e61fdb48a5cf92387456c5e1e40bad75f9a7d03bd2b852f985439c9662c91e92ffa28a530d2aef2d60ab3882555a9b76ae09563148
+  data.tar.gz: c9aabb8ad51cf2e4e70b072c6fe42291506bef4ef556a240be2529df03f8599cb1cf2ea0826d6586f912fa7b9cc8273fe7c48cce442743c5031fa0ba666c300b

data/README.md

@@ -30,7 +30,7 @@ require 'tlq_client'
 # Initialize client (defaults to localhost:1337)
 client = TLQClient.new
 # or with custom host/port
-client = TLQClient.new(host: 'queue.example.com', port: 8080)
+client = TLQClient.new(host: 'tlq.skyak.tech', port: 8080)
 
 # Add messages to the queue
 message = client.add_message("Process order #123")

data/lib/tlq_client/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 class TLQClient
-  VERSION = "0.2.0"
+  # The current version of the TLQClient gem.
+  # @return [String] the semantic version string
+  VERSION = "0.2.1"
 end

data/lib/tlq_client.rb

@@ -5,16 +5,67 @@ require 'net/http'
 require 'uri'
 require_relative 'tlq_client/version'
 
+# 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.
+#
+# @example 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 https://github.com/robinbakker/tiny-little-queue TLQ Server
 class TLQClient
-  attr_reader :host, :port, :base_uri
+  # @return [String] the hostname of the TLQ server
+  attr_reader :host
 
+  # @return [Integer] the port number of the TLQ server
+  attr_reader :port
+
+  # @return [String] the base URI for API requests
+  attr_reader :base_uri
+
+  # Creates a new TLQClient instance.
+  #
+  # @param host [String] the hostname of the TLQ server (default: 'localhost')
+  # @param port [Integer] the port number of the TLQ server (default: 1337)
+  #
+  # @example Connect to default server
+  #   client = TLQClient.new
+  #
+  # @example Connect to custom server
+  #   client = TLQClient.new(host: 'tlq.skyak.tech', port: 8080)
   def initialize(host: 'localhost', port: 1337)
     @host = host
     @port = port
     @base_uri = "http://#{@host}:#{@port}"
   end
 
-  # Add a message to the queue
+  # Adds a message to the queue.
+  #
+  # @param body [String, Hash, Array] the message body to add to the queue.
+  #   Can be a string or any JSON-serializable object.
+  #
+  # @return [Hash] the created message object containing 'id', 'body', and metadata
+  #
+  # @raise [RuntimeError] if the server response cannot be parsed as JSON
+  # @raise [RuntimeError] if the HTTP request fails
+  #
+  # @example Add a simple string message
+  #   message = client.add_message("Hello, World!")
+  #   puts message['id']  # => "abc123"
+  #
+  # @example Add a hash message
+  #   message = client.add_message({ event: 'user_signup', user_id: 42 })
   def add_message(body)
     response = post('/add', { body: body })
     JSON.parse(response.body)
@@ -24,7 +75,26 @@ class TLQClient
     raise "HTTP request failed: #{e.message}"
   end
 
-  # Get messages from the queue
+  # 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).
+  #
+  # @param count [Integer] the number of messages to retrieve (default: 1)
+  #
+  # @return [Array<Hash>] an array of message objects, each containing 'id' and 'body'
+  #
+  # @raise [RuntimeError] if the server response cannot be parsed as JSON
+  # @raise [RuntimeError] if the HTTP request fails
+  #
+  # @example Get a single message
+  #   messages = client.get_messages
+  #   message = messages.first
+  #   puts message['body']
+  #
+  # @example Get multiple messages
+  #   messages = client.get_messages(10)
+  #   messages.each { |m| process(m) }
   def get_messages(count = 1)
     response = post('/get', { count: count })
     parsed = JSON.parse(response.body)
@@ -35,7 +105,22 @@ class TLQClient
     raise "HTTP request failed: #{e.message}"
   end
 
-  # Delete messages from the queue
+  # Deletes messages from the queue permanently.
+  #
+  # Use this method to acknowledge successful processing of messages.
+  # Once deleted, messages cannot be recovered.
+  #
+  # @param ids [String, Array<String>] a single message ID or array of message IDs to delete
+  #
+  # @return [Boolean] true if the deletion was successful
+  #
+  # @raise [RuntimeError] if the HTTP request fails
+  #
+  # @example Delete a single message
+  #   client.delete_messages("abc123")
+  #
+  # @example Delete multiple messages
+  #   client.delete_messages(["abc123", "def456", "ghi789"])
   def delete_messages(ids)
     response = post('/delete', { ids: Array(ids) })
     response.body == '"Success"'
@@ -43,7 +128,22 @@ class TLQClient
     raise "HTTP request failed: #{e.message}"
   end
 
-  # Retry messages (return to queue)
+  # 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.
+  #
+  # @param ids [String, Array<String>] a single message ID or array of message IDs to retry
+  #
+  # @return [Boolean] true if the retry was successful
+  #
+  # @raise [RuntimeError] if the HTTP request fails
+  #
+  # @example Retry a single message
+  #   client.retry_messages("abc123")
+  #
+  # @example Retry multiple messages
+  #   client.retry_messages(["abc123", "def456"])
   def retry_messages(ids)
     response = post('/retry', { ids: Array(ids) })
     response.body == '"Success"'
@@ -51,7 +151,16 @@ class TLQClient
     raise "HTTP request failed: #{e.message}"
   end
 
-  # Purge all messages from the queue
+  # Purges all messages from the queue.
+  #
+  # @note This operation is irreversible. All messages will be permanently deleted.
+  #
+  # @return [Boolean] true if the purge was successful
+  #
+  # @raise [RuntimeError] if the HTTP request fails
+  #
+  # @example Clear the queue
+  #   client.purge_queue
   def purge_queue
     response = post('/purge', {})
     response.body == '"Success"'
@@ -59,7 +168,16 @@ class TLQClient
     raise "HTTP request failed: #{e.message}"
   end
 
-  # Check server health
+  # Checks if the TLQ server is reachable and responding.
+  #
+  # @return [Boolean] true if the server is healthy and responding
+  #
+  # @raise [RuntimeError] if the health check request fails
+  #
+  # @example Check server status
+  #   if client.health_check
+  #     puts "Server is running"
+  #   end
   def health_check
     uri = URI("#{@base_uri}/hello")
     response = Net::HTTP.get_response(uri)
@@ -70,6 +188,14 @@ class TLQClient
 
   private
 
+  # Sends a POST request to the TLQ server.
+  #
+  # @param path [String] the API endpoint path
+  # @param data [Hash] the request body data to send as JSON
+  #
+  # @return [Net::HTTPResponse] the HTTP response object
+  #
+  # @api private
   def post(path, data)
     uri = URI("#{@base_uri}#{path}")
     http = Net::HTTP.new(uri.host, uri.port)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tlq-client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Nebojsa Jakovljevic
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-26 00:00:00.000000000 Z
+date: 2025-11-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: A Ruby client library to interact with TLQ message queue
 email:
 - nebojsa@skyak.tech
@@ -71,7 +85,8 @@ metadata:
   homepage_uri: https://tinylittlequeue.app/
   source_code_uri: https://github.com/skyaktech/tlq-client-ruby
   changelog_uri: https://github.com/skyaktech/tlq-client-ruby/blob/main/CHANGELOG.md
-post_install_message: 
+  documentation_uri: https://rubydoc.info/gems/tlq-client
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -79,15 +94,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Ruby client for TLQ (Tiny Little Queue)
 test_files: []