hookd-client 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba2b5b2434c982f13d1515e488d1bcc30056f66448fe34d9529004ae0ea1229a
-  data.tar.gz: 437ffa486b1a4bb37c6c3e89dc33ab9dbb927b831496435948b47039b0d91384
+  metadata.gz: 97edc24416cdc28af2b3e6506d598711705cfc948bbb24416256343ed07e70d9
+  data.tar.gz: '008e6b1dd48ea295b47551c1cf9182ea4beceacff62751db9ee0829157911378'
 SHA512:
-  metadata.gz: b3551c335feda2be9dfd807c1de65fe1f6f7e46698f193cb3112323c02c3b332e66aa9563caebdc3d24f730d5b8d49484099dfd7c0fd1e3f1370c9860350c79b
-  data.tar.gz: 4f162c429ea63559cac8749ffcdace2f80014317c30d2d06e6d8954a44a7c8cdd308222e9133bc292a16db9bddcd1283f25b5f762922b46a68eb130737f23432
+  metadata.gz: baefacc1c8e98030276e92c3ea4c7ab3e78bf8bef6465e0a99c4574ec221aae4070d3e5c10e353fb4b732532aa19031cc5697dab4e355fe984f730fcc46ecc97
+  data.tar.gz: c382ec4a08173ecead4a6334b095a112c3fce9eed944216b48634652dfc20b33d0a820d380920e6682c987f8ad718a0e906d015c94603ca87898da4c93ab83bd

data/README.md

@@ -39,7 +39,7 @@ puts "HTTPS endpoint: #{hook.https}"
 # Make a request to the HTTP endpoint to simulate an interaction
 Typhoeus.get(hook.http)
 
-# Poll for interactions
+# Poll for interactions (single hook)
 interactions = client.poll(hook.id)
 interactions.each do |interaction|
   if interaction.dns?
@@ -50,6 +50,60 @@ interactions.each do |interaction|
 end
 ```
 
+### Batch Polling Example
+
+When working with multiple hooks, use `poll_batch` for better performance:
+
+```ruby
+require 'hookd'
+require 'typhoeus'
+
+# Initialize the client
+client = Hookd::Client.new(
+  server: "https://hookd.example.com",
+  token: ENV['HOOKD_TOKEN']
+)
+
+# Register multiple hooks
+puts "Registering 5 hooks..."
+hooks = client.register(count: 5)
+
+hook_ids = hooks.map(&:id)
+puts "Created hooks: #{hook_ids.join(', ')}"
+
+# Simulate some interactions...
+# (make DNS queries, HTTP requests, etc.)
+
+# Simulate some interactions
+puts "\nSimulating HTTP requests..."
+hooks.each do |hook|
+  Typhoeus.get(hook.http)
+  puts "  ✓ GET #{hook.http}"
+end
+
+# Batch poll all hooks at once (1 HTTP request instead of 5)
+puts "Batch polling #{hook_ids.size} hooks..."
+results = client.poll_batch(hook_ids)
+
+# Display results
+results.each do |hook_id, result|
+  if result[:error]
+    puts "❌ Hook #{hook_id}: #{result[:error]}"
+  else
+    interactions = result[:interactions]
+    puts "✅ Hook #{hook_id}: #{interactions.size} interaction(s)"
+
+    interactions.each do |interaction|
+      if interaction.dns?
+        puts "   - DNS: #{interaction.data['qname']} (#{interaction.data['qtype']})"
+      elsif interaction.http?
+        puts "   - HTTP: #{interaction.data['method']} #{interaction.data['path']}"
+      end
+    end
+  end
+end
+```
+
 ### Configuration
 
 The client requires two configuration parameters:
@@ -94,7 +148,7 @@ Raises:
 
 ##### `#poll(hook_id)`
 
-Poll for interactions captured by a hook.
+Poll for interactions captured by a single hook.
 
 ```ruby
 interactions = client.poll("abc123")
@@ -112,6 +166,55 @@ Raises:
 - `Hookd::ServerError` - Server error (5xx)
 - `Hookd::ConnectionError` - Connection failed
 
+##### `#poll_batch(hook_ids)`
+
+**Batch poll** - Poll for interactions from multiple hooks in a single request.
+
+```ruby
+# Register multiple hooks
+hooks = client.register(count: 3)
+hook_ids = hooks.map(&:id)
+
+# Batch poll all hooks at once (1 HTTP request instead of 3)
+results = client.poll_batch(hook_ids)
+# => {
+#   "abc123" => { interactions: [...], error: nil },
+#   "def456" => { interactions: [...], error: nil },
+#   "ghi789" => { interactions: [], error: nil }
+# }
+
+# Process results
+results.each do |hook_id, result|
+  if result[:error]
+    puts "Error for #{hook_id}: #{result[:error]}"
+  else
+    puts "Hook #{hook_id}: #{result[:interactions].size} interactions"
+    result[:interactions].each do |interaction|
+      puts "  - #{interaction.type}: #{interaction.data}"
+    end
+  end
+end
+```
+
+Parameters:
+- `hook_ids` (Array<String>) - Array of hook IDs to poll
+
+Returns: Hash mapping hook IDs to results
+- Each result contains:
+  - `interactions` (Array<Hookd::Interaction>) - Array of interactions
+  - `error` (String, nil) - Error message if hook not found
+
+Raises:
+- `ArgumentError` - Invalid hook_ids (not an array or empty)
+- `Hookd::AuthenticationError` - Authentication failed
+- `Hookd::ServerError` - Server error (5xx)
+- `Hookd::ConnectionError` - Connection failed
+
+**Benefits:**
+- **Performance**: Reduced latency with single HTTP request
+- **Efficiency**: Automatic connection reuse with HTTPX
+- **Atomic**: Consistent snapshot of all hooks
+
 ##### `#metrics`
 
 Get server metrics (requires authentication).

data/lib/hookd/client.rb

@@ -62,6 +62,27 @@ module Hookd
       raise Error, "Invalid response format: #{e.message}"
     end
 
+    # Poll for interactions on multiple hooks (batch)
+    # @param hook_ids [Array<String>] the hook IDs to poll
+    # @return [Hash<String, Hash>] hash mapping hook_id to results
+    #   Results format: { "hook_id" => { interactions: [...], error: "..." } }
+    # @raise [Hookd::AuthenticationError] if authentication fails
+    # @raise [Hookd::ServerError] if server returns 5xx
+    # @raise [Hookd::ConnectionError] if connection fails
+    # @raise [ArgumentError] if hook_ids is invalid
+    def poll_batch(hook_ids)
+      validate_hook_ids(hook_ids)
+
+      url = "#{@server}/poll"
+      options = { headers: { 'Content-Type' => 'application/json' }, json: hook_ids }
+      response = @http.post(url, **options)
+      response_data = handle_response(response)
+
+      transform_batch_results(response_data['results'])
+    rescue NoMethodError => e
+      raise Error, "Invalid response format: #{e.message}"
+    end
+
     # Get server metrics (requires authentication)
     # @return [Hash] metrics data
     # @raise [Hookd::AuthenticationError] if authentication fails
@@ -88,6 +109,25 @@ module Hookd
       handle_response(response)
     end
 
+    def validate_hook_ids(hook_ids)
+      raise ArgumentError, 'hook_ids must be an array' unless hook_ids.is_a?(Array)
+      raise ArgumentError, 'hook_ids cannot be empty' if hook_ids.empty?
+    end
+
+    def transform_batch_results(results)
+      return {} if results.nil? || !results.is_a?(Hash)
+
+      results.transform_values do |result|
+        next result if result['error']
+
+        interactions = result['interactions']
+        {
+          interactions: interactions&.map { |i| Interaction.from_hash(i) } || [],
+          error: result['error']
+        }
+      end
+    end
+
     def handle_response(response)
       # HTTPX returns HTTPX::ErrorResponse for connection/timeout errors
       if response.is_a?(HTTPX::ErrorResponse)

data/lib/hookd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hookd
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hookd-client
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Joshua MARTINELLE