hookd-client 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eeded85d2f08978163e752d64342ca5e52fd1cf1fcaade7da0305caeb53e03b5
-  data.tar.gz: 966b9eaf4f9d25549f0473471e446628af82c8ea160e5ebbefef518aa1a6fa08
+  metadata.gz: 5ff2c6d9ea446cd5631e2c3f4d3f27a0586a130acaf6bf9e10f9a7fb6613efc3
+  data.tar.gz: 38021e8c18baee9ff374c60d305cc6312cf024a2fff120e926cfa89d9d44ea52
 SHA512:
-  metadata.gz: 0224226f06a4996e6034caabb6182f31d9a7848262a44bd8ed0571fe898a7706f4b95c46bdb0e5617c0bc04f948fc5dc8e5bffbb46cd20de04d9bdcacbe0b2fe
-  data.tar.gz: 88e85eab06e2d351b6231f2769104b6d6a3320ae1cb2ccf68f432dad732a689ee5f50386ca69199534a76fb09425ddfd70f7d711b03b8e4d836e2b25415784ad
+  metadata.gz: 3cc77be594c69256a2de2e31a23a7654dddbf94c50f0402fa327e3865e2fa25af4c4c4dfab6e9ca641aa611b20da6e22760646d570676a4a87e92d08382f3af8
+  data.tar.gz: 1d2da85d42bfff6ba7bcf2e1211b418c7bc8944ce8119169388e1b51cec085d64a54ceb4372ea5b5869714c792836cd193b1600b526c40021ead72cf8a492d28

data/README.md

@@ -1,6 +1,6 @@
 # Hookd Ruby Client
 
-Ruby client library for [Hookd](https://github.com/JoshuaMart/hookd/server), a DNS/HTTP interaction server for security testing and debugging.
+Ruby client library for [Hookd](https://github.com/JoshuaMart/hookd/server), a DNS/HTTP/SMTP interaction server for security testing and debugging.
 
 ## Installation
 
@@ -35,6 +35,7 @@ hook = client.register
 puts "DNS endpoint: #{hook.dns}"
 puts "HTTP endpoint: #{hook.http}"
 puts "HTTPS endpoint: #{hook.https}"
+puts "Mail endpoint: #{hook.smtp}" if hook.smtp
 
 # Make a request to the HTTP endpoint to simulate an interaction
 Typhoeus.get(hook.http)
@@ -46,6 +47,8 @@ interactions.each do |interaction|
     puts "DNS query: #{interaction.data}"
   elsif interaction.http?
     puts "HTTP request: #{interaction.data}"
+  elsif interaction.smtp?
+    puts "Mail from #{interaction.data['mail_from']}: #{interaction.data['subject']}"
   end
 end
 ```
@@ -95,6 +98,8 @@ results.each do |hook_id, result|
         puts "   - DNS: #{interaction.data['qname']} (#{interaction.data['qtype']})"
       elsif interaction.http?
         puts "   - HTTP: #{interaction.data['method']} #{interaction.data['path']}"
+      elsif interaction.smtp?
+        puts "   - SMTP: #{interaction.data['mail_from']} (#{interaction.data['subject']})"
       end
     end
   end
@@ -108,6 +113,10 @@ The client requires two configuration parameters:
 - `server`: The Hookd server URL (e.g., `https://hookd.example.com`)
 - `token`: Authentication token for API access
 
+An optional `max_response_bytes:` caps the response payload the client will read
+(64 MiB by default; zero or less disables it). Exceeding it raises
+`Hookd::ResponseTooLargeError`.
+
 ### API Reference
 
 #### `Hookd::Client`
@@ -116,7 +125,7 @@ Main client class for interacting with the Hookd server.
 
 ##### `#register(count: nil)`
 
-Register one or more hooks and get DNS/HTTP endpoints.
+Register one or more hooks and get their DNS, HTTP and (when the server runs a mail listener) SMTP endpoints.
 
 **Single hook (default):**
 ```ruby
@@ -259,6 +268,7 @@ Attributes:
 - `dns` (String) - DNS endpoint
 - `http` (String) - HTTP endpoint
 - `https` (String) - HTTPS endpoint
+- `smtp` (String, nil) - Mail address (nil unless the server runs a mail listener)
 - `created_at` (String) - Creation timestamp
 - `expires_at` (String, nil) - Expiry timestamp (long-lived hooks)
 - `metadata` (Hash, nil) - Metadata attached at registration
@@ -274,16 +284,17 @@ Attributes:
 
 #### `Hookd::Interaction`
 
-Represents a captured DNS or HTTP interaction.
+Represents a captured DNS, HTTP or SMTP interaction.
 
 Attributes:
-- `type` (String) - Interaction type ("dns" or "http")
+- `type` (String) - Interaction type ("dns", "http" or "smtp")
 - `timestamp` (String) - When the interaction was captured
 - `data` (Hash) - Interaction details
 
 Methods:
 - `#dns?` - Returns true if this is a DNS interaction
 - `#http?` - Returns true if this is an HTTP interaction
+- `#smtp?` - Returns true if this is an SMTP interaction
 
 ### Error Handling
 
@@ -307,3 +318,4 @@ Exception hierarchy:
   - `Hookd::NotFoundError` - 404 Not Found
   - `Hookd::ServerError` - 5xx Server Error
   - `Hookd::ConnectionError` - Network/connection errors
+  - `Hookd::ResponseTooLargeError` - Response above `max_response_bytes`

data/lib/hookd/client.rb

@@ -6,11 +6,19 @@ require 'json'
 module Hookd
   # HTTP client for interacting with Hookd server
   class Client
-    attr_reader :server, :token
+    # Caps the payload materialised as a String. Generous, since a poll can
+    # return many interactions with full bodies. Zero or less disables it.
+    DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024 * 1024
 
-    def initialize(server:, token:)
+    # How much of an error response is quoted back in the raised message.
+    ERROR_BODY_EXCERPT_BYTES = 1024
+
+    attr_reader :server, :token, :max_response_bytes
+
+    def initialize(server:, token:, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
       @server = server
       @token = token
+      @max_response_bytes = max_response_bytes
       @http = HTTPX.with(
         headers: { 'X-API-Key' => token },
         timeout: {
@@ -170,24 +178,49 @@ module Hookd
         raise ConnectionError, "Connection failed: #{error.message}"
       end
 
-      body = response.body.to_s
-
       case response.status
       when 200, 201
-        raise Error, 'Empty response body from server' if body.nil? || body.empty?
-
-        JSON.parse(body)
+        parse_body(response)
       when 401
-        raise AuthenticationError, "Authentication failed: #{body}"
+        raise AuthenticationError, "Authentication failed: #{error_excerpt(response)}"
       when 404
-        raise NotFoundError, "Resource not found: #{body}"
+        raise NotFoundError, "Resource not found: #{error_excerpt(response)}"
       when 500..599
-        raise ServerError, "Server error (#{response.status}): #{body}"
+        raise ServerError, "Server error (#{response.status}): #{error_excerpt(response)}"
       else
-        raise Error, "Unexpected response (#{response.status}): #{body}"
+        raise Error, "Unexpected response (#{response.status}): #{error_excerpt(response)}"
       end
+    end
+
+    def parse_body(response)
+      body = read_body(response, @max_response_bytes)
+      raise Error, 'Empty response body from server' if body.empty?
+
+      JSON.parse(body)
     rescue JSON::ParserError => e
       raise Error, "Invalid JSON response: #{e.message}"
     end
+
+    # Accumulates chunk by chunk and stops at the ceiling, raising unless
+    # truncate is set, in which case it returns the bounded slice.
+    def read_body(response, limit, truncate: false)
+      return response.body.to_s if limit <= 0
+
+      body = nil
+      response.body.each do |chunk|
+        # Seed from the first chunk to keep the payload's own encoding.
+        body = body ? body << chunk : chunk.dup
+        next if body.bytesize <= limit
+        return body.byteslice(0, limit).scrub if truncate
+
+        raise ResponseTooLargeError, "Response exceeds the #{limit} byte limit"
+      end
+      body || ''
+    end
+
+    # A large error page must not become a large exception message.
+    def error_excerpt(response)
+      read_body(response, ERROR_BODY_EXCERPT_BYTES, truncate: true)
+    end
   end
 end

data/lib/hookd/error.rb

@@ -15,4 +15,7 @@ module Hookd
 
   # Raised when the server returns a 5xx error
   class ServerError < Error; end
+
+  # Raised when a response exceeds the client's size limit
+  class ResponseTooLargeError < Error; end
 end

data/lib/hookd/hook.rb

@@ -1,17 +1,18 @@
 # frozen_string_literal: true
 
 module Hookd
-  # Represents a registered hook with DNS and HTTP endpoints. expires_at and
-  # metadata are populated for long-lived hooks (registered with a ttl) and nil
-  # otherwise.
+  # Represents a registered hook with its endpoints. smtp is set only when the
+  # server runs a mail listener. expires_at and metadata are populated for
+  # long-lived hooks (registered with a ttl) and nil otherwise.
   class Hook
-    attr_reader :id, :dns, :http, :https, :created_at, :expires_at, :metadata
+    attr_reader :id, :dns, :http, :https, :smtp, :created_at, :expires_at, :metadata
 
-    def initialize(id:, dns:, http:, https:, created_at:, expires_at: nil, metadata: nil)
+    def initialize(id:, dns:, http:, https:, created_at:, smtp: nil, expires_at: nil, metadata: nil)
       @id = id
       @dns = dns
       @http = http
       @https = https
+      @smtp = smtp
       @created_at = created_at
       @expires_at = expires_at
       @metadata = metadata
@@ -26,6 +27,7 @@ module Hookd
         dns: hash['dns'],
         http: hash['http'],
         https: hash['https'],
+        smtp: hash['smtp'],
         created_at: hash['created_at'],
         expires_at: hash['expires_at'],
         metadata: hash['metadata']

data/lib/hookd/interaction.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Hookd
-  # Represents a captured DNS or HTTP interaction
+  # Represents a captured DNS, HTTP or SMTP interaction
   class Interaction
     attr_reader :type, :timestamp, :source_ip, :data
 
@@ -32,6 +32,11 @@ module Hookd
       type == 'http'
     end
 
+    # Check if this is an SMTP interaction
+    def smtp?
+      type == 'smtp'
+    end
+
     def to_s
       "#<Hookd::Interaction type=#{type} timestamp=#{timestamp} source_ip=#{source_ip}>"
     end

data/lib/hookd/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hookd-client
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Joshua MARTINELLE
@@ -23,8 +23,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Ruby client library for Hookd, a DNS/HTTP interaction server for security
-  testing and debugging
+description: Ruby client library for Hookd, a DNS/SMTP/HTTP interaction server for
+  security testing and debugging
 email:
 - contact@jomar.fr
 executables: []