hookd-client 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eade8cb3959a4a3792d6bf6c7db1cc9ea04fe6d1890ff895fe9400e823d720bf
-  data.tar.gz: b49e156b95cac1a65897f3dfc8f85f55e96e8de9181885b9399357e1c8dbcc96
+  metadata.gz: 97edc24416cdc28af2b3e6506d598711705cfc948bbb24416256343ed07e70d9
+  data.tar.gz: '008e6b1dd48ea295b47551c1cf9182ea4beceacff62751db9ee0829157911378'
 SHA512:
-  metadata.gz: 2fc01eb61437a52f4ed20cec5a9af0b4c408427da54fe87e8186163254f41105a6026970bb96bb32a886761fdb12bc329e99aa38a77f6d2f498573fbb0511b16
-  data.tar.gz: 3f40e48b70f0ac245125382fc9ff5150f4fdfdae1439b8436bf22ce31e852bea9f36d033014f94d4dc61b66c91eea18d26dc8e9ccb13371462069d13977f0b37
+  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

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require 'net/http'
+require 'httpx'
 require 'json'
-require 'uri'
 
 module Hookd
   # HTTP client for interacting with Hookd server
@@ -12,7 +11,13 @@ module Hookd
     def initialize(server:, token:)
       @server = server
       @token = token
-      @uri = URI.parse(server)
+      @http = HTTPX.with(
+        headers: { 'X-API-Key' => token },
+        timeout: {
+          connect_timeout: 10,
+          read_timeout: 30
+        }
+      )
     end
 
     # Register one or more hooks
@@ -25,9 +30,7 @@ module Hookd
     def register(count: nil)
       body = count.nil? ? nil : { count: count }
 
-      if count && (!count.is_a?(Integer) || count < 1)
-        raise ArgumentError, 'count must be a positive integer'
-      end
+      raise ArgumentError, 'count must be a positive integer' if count && (!count.is_a?(Integer) || count < 1)
 
       response = post('/register', body)
 
@@ -59,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
@@ -71,43 +95,62 @@ module Hookd
     private
 
     def get(path)
-      request = Net::HTTP::Get.new(path)
-      request['X-API-Key'] = token
-      execute_request(request)
+      url = "#{@server}#{path}"
+      response = @http.get(url)
+      handle_response(response)
     end
 
     def post(path, body = nil)
-      request = Net::HTTP::Post.new(path)
-      request['X-API-Key'] = token
-      request['Content-Type'] = 'application/json'
-      request.body = body.to_json if body
-      execute_request(request)
+      url = "#{@server}#{path}"
+      options = { headers: { 'Content-Type' => 'application/json' } }
+      options[:json] = body if body
+
+      response = @http.post(url, **options)
+      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 execute_request(request)
-      http = Net::HTTP.new(@uri.host, @uri.port)
-      http.use_ssl = @uri.scheme == 'https'
-      http.open_timeout = 10
-      http.read_timeout = 30
+    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)
+        error = response.error
+        raise ConnectionError, "Connection failed: #{error.message}"
+      end
 
-      response = http.request(request)
+      body = response.body.to_s
 
-      case response.code.to_i
+      case response.status
       when 200, 201
-        raise Error, 'Empty response body from server' if response.body.nil? || response.body.empty?
+        raise Error, 'Empty response body from server' if body.nil? || body.empty?
 
-        JSON.parse(response.body)
+        JSON.parse(body)
       when 401
-        raise AuthenticationError, "Authentication failed: #{response.body}"
+        raise AuthenticationError, "Authentication failed: #{body}"
       when 404
-        raise NotFoundError, "Resource not found: #{response.body}"
+        raise NotFoundError, "Resource not found: #{body}"
       when 500..599
-        raise ServerError, "Server error (#{response.code}): #{response.body}"
+        raise ServerError, "Server error (#{response.status}): #{body}"
       else
-        raise Error, "Unexpected response (#{response.code}): #{response.body}"
+        raise Error, "Unexpected response (#{response.status}): #{body}"
       end
-    rescue SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
-      raise ConnectionError, "Connection failed: #{e.message}"
     rescue JSON::ParserError => e
       raise Error, "Invalid JSON response: #{e.message}"
     end

data/lib/hookd/version.rb

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

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: hookd-client
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Joshua MARTINELLE
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httpx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: Ruby client library for Hookd, a DNS/HTTP interaction server for security
   testing and debugging
 email: