tlq-client 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23e82549788eabfb735a5035d8b8f478df7e570a6b1c43338ea28714f2ef0824
-  data.tar.gz: 584f2eb0f74e20b8df96401630c5843184c15b31f48e693739f159f5ba22f42a
+  metadata.gz: 40f40f39e20c3a46bb0d6cc6a5517fbb2d581e4996893307bffc84582f90bb15
+  data.tar.gz: 0f1686b89b1306f27866738e029709ec1e58d736ae87363f67660a1e7edcad1a
 SHA512:
-  metadata.gz: a2da29977ea8ea209bcd448c8928b59e58ef76c3bf0b55ce0f8008edd9a12070832eb3af46c1c5c350cefee41484a43f41dc279ab7b78effa0c928e84de05645
-  data.tar.gz: 44d102142b0750efca0db88d4f7fba9f9cf8891117c8456bf852604a0eb59d65f63b6e590b6b9a4da8ffd034449e771d230a19423a4d4a813f46f13c05684c4d
+  metadata.gz: 0da8db4deaf928c53ebd6f2caf1973054efe290b556253bfe022a4c2f8eaa3e27eabd64e474a18f83922ffb56c3ec50bd6b9ffd9151c32064f7e62f0fc86f578
+  data.tar.gz: 3863fa188edd2a85f074a9da0cf7e219f3c5528f4b4c3a1fcb41fb0ae74aab0d62b564044d419591a0bebee9f2f34ad2ec5f2459a9955b26b517aaea189bb157

data/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-03-21
+
+### Added
+
+- `stats` - Get queue statistics (ready, processing, dead counts)
+
 ## [0.2.0] - 2025-11-26
 
 ### Added

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")
@@ -58,6 +58,10 @@ ids = messages.map { |m| m['id'] }
 client.delete_messages(ids)  # Delete multiple
 client.retry_messages(ids)   # Retry multiple
 
+# Queue statistics
+stats = client.stats
+puts stats  # => {"ready" => 10, "processing" => 2, "dead" => 0}
+
 # Health check
 client.health_check  # => true
 
@@ -100,13 +104,17 @@ Returns messages to the queue for reprocessing. Increments `retry_count`. Accept
 
 Removes all messages from the queue. Cannot be undone.
 
+### `stats → Hash`
+
+Returns queue statistics with `ready`, `processing`, and `dead` counts.
+
 ### `health_check → Boolean`
 
 Returns `true` if the TLQ server is reachable.
 
 ## Requirements
 
-- Ruby >= 2.6
+- Ruby >= 3.1
 - Running [TLQ server](https://github.com/skyaktech/tlq)
 
 ## Development

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.4.0"
 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,36 @@ class TLQClient
     raise "HTTP request failed: #{e.message}"
   end
 
-  # Check server health
+  # Returns queue statistics from the TLQ server.
+  #
+  # @return [Hash] queue statistics containing 'ready', 'processing', and 'dead' counts
+  #
+  # @raise [RuntimeError] if the server response cannot be parsed as JSON
+  # @raise [RuntimeError] if the HTTP request fails
+  #
+  # @example Get queue stats
+  #   stats = client.stats
+  #   puts "Ready: #{stats['ready']}, Processing: #{stats['processing']}, Dead: #{stats['dead']}"
+  def stats
+    uri = URI("#{@base_uri}/stats")
+    response = Net::HTTP.get_response(uri)
+    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
+
+  # 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 +208,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.4.0
 platform: ruby
 authors:
 - Nebojsa Jakovljevic
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-26 00:00:00.000000000 Z
+date: 2026-03-21 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: []