hookd-client 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ff2c6d9ea446cd5631e2c3f4d3f27a0586a130acaf6bf9e10f9a7fb6613efc3
-  data.tar.gz: 38021e8c18baee9ff374c60d305cc6312cf024a2fff120e926cfa89d9d44ea52
+  metadata.gz: 85c9d3bb1f54b986026f6815e255ecdb515ad9e9bae6a4c78708fcf0f5d133b2
+  data.tar.gz: a8a93a75b73de9eba86444c0104643388f64fb71969c19588465071a6aa2272a
 SHA512:
-  metadata.gz: 3cc77be594c69256a2de2e31a23a7654dddbf94c50f0402fa327e3865e2fa25af4c4c4dfab6e9ca641aa611b20da6e22760646d570676a4a87e92d08382f3af8
-  data.tar.gz: 1d2da85d42bfff6ba7bcf2e1211b418c7bc8944ce8119169388e1b51cec085d64a54ceb4372ea5b5869714c792836cd193b1600b526c40021ead72cf8a492d28
+  metadata.gz: fd9081da69578bdea39b76d8bedc0c6d71b1b2a82927b3fc07abadf345d20d10ad58797ea8689d0b84b0ea69d9609d23cb7bdcbd07b5f823fab0afb87eb2f8c7
+  data.tar.gz: caf8b630d270276df0d4a7b05b0bb30c5a96e446ff6b87f3eb9b2b5166789960a768c5545f733e91b58d6404ba5dcff1cf5b044b33798655df9dc5f186a0d1be

data/README.md

@@ -164,10 +164,39 @@ Raises:
 - `Hookd::ServerError` - Server error (5xx)
 - `Hookd::ConnectionError` - Connection failed
 
-##### `#activity`
+##### `#register_batch(specs)`
+
+Register one hook per spec in a single request — e.g. one per injectable field,
+each carrying its own context. Hooks come back in spec order; the server
+creates all of them or none (up to 500 per call).
+
+```ruby
+hooks = client.register_batch([
+  { ttl: "7d", metadata: { endpoint_id: "e_412", param: "bio" } },
+  { ttl: "7d", metadata: { endpoint_id: "e_413", param: "name" } }
+])
+# => [#<Hookd::Hook ...>, #<Hookd::Hook ...>]
+```
+
+##### `#hooks(metadata: nil)`
+
+List the long-lived hooks (without interactions) whose top-level metadata
+matches every key/value given; omit `metadata` to list all. Useful to rebuild
+your hook list after losing local state.
+
+```ruby
+client.hooks(metadata: { run_id: "0f3a" })
+```
+
+##### `#activity(metadata: nil)`
+
+Pass `metadata:` to keep only matching hooks, so workers sharing a server each
+see only their own.
+
 
 List the long-lived hooks that currently have pending interactions, so you can
-discover which fired without polling each one; drain the details with `#poll`.
+discover which fired without polling each one; fetch the details with `#read`
+(or `#poll` to drain). Skip hooks whose `last_seq` is not above your cursor.
 
 ```ruby
 client.activity.each do |a|
@@ -248,6 +277,39 @@ Raises:
 - **Efficiency**: Automatic connection reuse with HTTPX
 - **Atomic**: Consistent snapshot of all hooks
 
+##### `#read(hook_id, after:)` and `#ack(hook_id, through:)`
+
+`#poll` deletes what it returns, so a crash before you store the result loses
+it. `#read` leaves the interactions on the server; `#ack` them once your own
+write has committed. Keep the cursor (the last `seq` stored) on your side.
+
+```ruby
+read = client.read(hook_id, after: cursor)
+warn "interactions up to seq #{read.dropped_through} were evicted unread" if read.lost?(cursor)
+
+unless read.interactions.empty?
+  last = read.interactions.last.seq
+  store(read.interactions)          # raises: nothing acknowledged, read again later
+  client.ack(hook_id, through: last) # => number of interactions removed
+  cursor = last
+end
+```
+
+`#read` returns a `Hookd::CursorRead`; `#ack` returns the number removed. Both
+raise `Hookd::NotFoundError` for an unknown hook and `Hookd::ServerError` when
+the server fails, so a failed ack is never mistaken for success.
+
+##### `#read_batch(cursors)` and `#ack_batch(cursors)`
+
+The same for many hooks in one request, keyed by hook ID:
+
+```ruby
+client.read_batch("abc123" => 4, "def456" => 0)
+# => { "abc123" => { interactions: [...], dropped_through: 0, error: nil }, ... }
+client.ack_batch("abc123" => 6)
+# => { "abc123" => { acknowledged: 2, error: nil } }
+```
+
 ##### `#metrics`
 
 Get server metrics (requires authentication).
@@ -281,12 +343,27 @@ Attributes:
 - `hook` (`Hookd::Hook`) - The long-lived hook that fired
 - `pending_count` (Integer) - Number of interactions awaiting poll
 - `last_interaction_at` (String) - Timestamp of the most recent interaction
+- `last_seq` (Integer) - Seq of the most recent interaction
+
+#### `Hookd::CursorRead`
+
+Returned by `#read`.
+
+Attributes:
+- `interactions` (Array<`Hookd::Interaction`>) - Interactions past the cursor
+- `dropped_through` (Integer) - Highest seq evicted before acknowledgement
+- `metadata` (Hash, nil) - Metadata attached at registration
+
+Methods:
+- `#lost?(after)` - True if interactions past `after` were evicted unread
 
 #### `Hookd::Interaction`
 
 Represents a captured DNS, HTTP or SMTP interaction.
 
 Attributes:
+- `id` (String) - Interaction identifier
+- `seq` (Integer) - Per-hook sequence number, the cursor for `#read` / `#ack`
 - `type` (String) - Interaction type ("dns", "http" or "smtp")
 - `timestamp` (String) - When the interaction was captured
 - `data` (Hash) - Interaction details

data/lib/hookd/client.rb

@@ -2,6 +2,7 @@
 
 require 'httpx'
 require 'json'
+require 'uri'
 
 module Hookd
   # HTTP client for interacting with Hookd server
@@ -46,6 +47,26 @@ module Hookd
       parse_register_response(post('/register', register_body(count, ttl, metadata)))
     end
 
+    # Register one hook per spec in a single request, each with its own ttl and
+    # metadata. The server creates all of them or none.
+    # @param specs [Array<Hash>] entries of { ttl: String or nil, metadata: Hash or nil }
+    # @return [Array<Hookd::Hook>] hooks in spec order
+    # @raise [ArgumentError] if specs is empty or not an array
+    def register_batch(specs)
+      raise ArgumentError, 'specs must be a non-empty array' unless specs.is_a?(Array) && !specs.empty?
+
+      body = specs.map { |spec| register_body(nil, spec[:ttl], spec[:metadata]) || {} }
+      hook_list(post('/register', { hooks: body }))
+    end
+
+    # List long-lived hooks, without interactions, whose metadata matches every
+    # key/value of the filter
+    # @param metadata [Hash, nil] filter on top-level metadata keys
+    # @return [Array<Hookd::Hook>]
+    def hooks(metadata: nil)
+      hook_list(get("/hooks#{metadata_query(metadata)}"))
+    end
+
     # Poll for interactions on a hook
     # @param hook_id [String] the hook ID to poll
     # @return [Array<Hookd::Interaction>] array of interactions (may be empty)
@@ -86,6 +107,60 @@ module Hookd
       raise Error, "Invalid response format: #{e.message}"
     end
 
+    # Read interactions past a cursor without deleting them; acknowledge them
+    # with #ack once stored.
+    # @param hook_id [String] the hook ID to read
+    # @param after [Integer] return interactions with a seq above this
+    # @return [Hookd::CursorRead]
+    # @raise [Hookd::NotFoundError] if hook not found
+    # @raise [Hookd::ServerError] if server returns 5xx
+    # @raise [ArgumentError] if after is invalid
+    def read(hook_id, after:)
+      validate_cursor(after, 'after')
+      response = get("/poll/#{hook_id}?after=#{after}")
+
+      CursorRead.new(
+        interactions: map_interactions(response['interactions']),
+        dropped_through: response['dropped_through'] || 0,
+        metadata: response['metadata']
+      )
+    end
+
+    # Delete interactions up to and including a seq
+    # @param hook_id [String] the hook ID
+    # @param through [Integer] the last seq stored by the caller
+    # @return [Integer] number of interactions removed
+    # @raise [Hookd::NotFoundError] if hook not found
+    # @raise [Hookd::ServerError] if server returns 5xx
+    # @raise [ArgumentError] if through is invalid
+    def ack(hook_id, through:)
+      validate_cursor(through, 'through')
+      handle_response(@http.delete("#{@server}/poll/#{hook_id}?through=#{through}"))['acknowledged']
+    end
+
+    # Read several hooks past their cursors in one request
+    # @param cursors [Hash<String, Integer>] hook ID to seq
+    # @return [Hash<String, Hash>] hook ID to
+    #   { interactions: [...], dropped_through: Integer, error: String or nil }
+    def read_batch(cursors)
+      cursor_batch('/read', 'after', cursors).transform_values do |result|
+        {
+          interactions: map_interactions(result['interactions']),
+          dropped_through: result['dropped_through'] || 0,
+          error: result['error']
+        }
+      end
+    end
+
+    # Acknowledge several hooks in one request
+    # @param cursors [Hash<String, Integer>] hook ID to seq
+    # @return [Hash<String, Hash>] hook ID to { acknowledged: Integer, error: String or nil }
+    def ack_batch(cursors)
+      cursor_batch('/ack', 'through', cursors).transform_values do |result|
+        { acknowledged: result['acknowledged'] || 0, error: result['error'] }
+      end
+    end
+
     # Get server metrics (requires authentication)
     # @return [Hash] metrics data
     # @raise [Hookd::AuthenticationError] if authentication fails
@@ -97,14 +172,15 @@ module Hookd
 
     # List long-lived hooks that currently have pending interactions, so you can
     # discover which of your long-lived hooks fired without polling each one.
-    # Drain the details with #poll. Returns an empty array when none have fired
+    # Fetch the details with #read (or #poll to drain). Returns an empty array when none have fired
     # (or the server has long-lived hooks disabled).
     # @return [Array<Hookd::HookActivity>]
     # @raise [Hookd::AuthenticationError] if authentication fails
     # @raise [Hookd::ServerError] if server returns 5xx
     # @raise [Hookd::ConnectionError] if connection fails
-    def activity
-      response = get('/activity')
+    # @param metadata [Hash, nil] keep only hooks whose metadata matches
+    def activity(metadata: nil)
+      response = get("/activity#{metadata_query(metadata)}")
 
       hooks = response['hooks']
       return [] if hooks.nil? || hooks.empty? || !hooks.is_a?(Array)
@@ -149,6 +225,33 @@ module Hookd
       handle_response(response)
     end
 
+    def metadata_query(metadata)
+      return '' if metadata.nil? || metadata.empty?
+
+      "?#{URI.encode_www_form(metadata.to_h { |k, v| ["metadata.#{k}", v.to_s] })}"
+    end
+
+    def hook_list(response)
+      hooks = response['hooks']
+      raise Error, 'Invalid response format: missing hooks' unless hooks.is_a?(Array)
+
+      hooks.map { |h| Hook.from_hash(h) }
+    end
+
+    def validate_cursor(seq, name)
+      raise ArgumentError, "#{name} must be a non-negative integer" unless seq.is_a?(Integer) && seq >= 0
+    end
+
+    def cursor_batch(path, field, cursors)
+      raise ArgumentError, "#{field} must be a non-empty hash" unless cursors.is_a?(Hash) && !cursors.empty?
+
+      cursors.each_value { |seq| validate_cursor(seq, field) }
+      results = post(path, { field => cursors })['results']
+      raise Error, 'Invalid response format: missing results' unless results.is_a?(Hash)
+
+      results
+    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?

data/lib/hookd/cursor_read.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hookd
+  # Result of a non-destructive Client#read
+  class CursorRead
+    attr_reader :interactions, :dropped_through, :metadata
+
+    def initialize(interactions:, dropped_through:, metadata: nil)
+      @interactions = interactions
+      @dropped_through = dropped_through
+      @metadata = metadata
+    end
+
+    # True when the server evicted interactions past the cursor before they
+    # were acknowledged.
+    def lost?(after)
+      dropped_through > after
+    end
+
+    def to_s
+      "#<Hookd::CursorRead interactions=#{interactions.size} dropped_through=#{dropped_through}>"
+    end
+  end
+end

data/lib/hookd/hook_activity.rb

@@ -4,12 +4,14 @@ module Hookd
   # Summarises a long-lived hook that currently has pending interactions,
   # returned by Client#activity.
   class HookActivity
-    attr_reader :hook, :pending_count, :last_interaction_at
+    # last_seq is the newest seq held: at or below a cursor, nothing is new.
+    attr_reader :hook, :pending_count, :last_interaction_at, :last_seq
 
-    def initialize(hook:, pending_count:, last_interaction_at:)
+    def initialize(hook:, pending_count:, last_interaction_at:, last_seq: nil)
       @hook = hook
       @pending_count = pending_count
       @last_interaction_at = last_interaction_at
+      @last_seq = last_seq
     end
 
     # Create a HookActivity from an API response hash
@@ -19,7 +21,8 @@ module Hookd
       new(
         hook: Hook.from_hash(hash['hook']),
         pending_count: hash['pending_count'],
-        last_interaction_at: hash['last_interaction_at']
+        last_interaction_at: hash['last_interaction_at'],
+        last_seq: hash['last_seq']
       )
     end
 

data/lib/hookd/interaction.rb

@@ -3,9 +3,12 @@
 module Hookd
   # Represents a captured DNS, HTTP or SMTP interaction
   class Interaction
-    attr_reader :type, :timestamp, :source_ip, :data
+    # seq increases per hook and is the cursor for Client#read and #ack.
+    attr_reader :id, :seq, :type, :timestamp, :source_ip, :data
 
-    def initialize(type:, timestamp:, source_ip:, data:)
+    def initialize(type:, timestamp:, source_ip:, data:, id: nil, seq: nil)
+      @id = id
+      @seq = seq
       @type = type
       @timestamp = timestamp
       @source_ip = source_ip
@@ -15,6 +18,8 @@ module Hookd
     # Create an Interaction from API response hash
     def self.from_hash(hash)
       new(
+        id: hash['id'],
+        seq: hash['seq'],
         type: hash['type'],
         timestamp: hash['timestamp'],
         source_ip: hash['source_ip'],
@@ -38,11 +43,12 @@ module Hookd
     end
 
     def to_s
-      "#<Hookd::Interaction type=#{type} timestamp=#{timestamp} source_ip=#{source_ip}>"
+      "#<Hookd::Interaction seq=#{seq} type=#{type} timestamp=#{timestamp} source_ip=#{source_ip}>"
     end
 
     def inspect
-      "#<Hookd::Interaction:#{object_id.to_s(16)} @type=#{type.inspect}, @timestamp=#{timestamp.inspect}, " \
+      "#<Hookd::Interaction:#{object_id.to_s(16)} @id=#{id.inspect}, @seq=#{seq.inspect}, " \
+        "@type=#{type.inspect}, @timestamp=#{timestamp.inspect}, " \
         "@source_ip=#{source_ip.inspect}, @data=#{data.inspect}>"
     end
   end

data/lib/hookd/version.rb

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

data/lib/hookd.rb

@@ -5,6 +5,7 @@ require_relative 'hookd/error'
 require_relative 'hookd/hook'
 require_relative 'hookd/hook_activity'
 require_relative 'hookd/interaction'
+require_relative 'hookd/cursor_read'
 require_relative 'hookd/client'
 
 # Hookd client library for interacting with Hookd DNS/HTTP interaction server

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hookd-client
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Joshua MARTINELLE
@@ -34,6 +34,7 @@ files:
 - README.md
 - lib/hookd.rb
 - lib/hookd/client.rb
+- lib/hookd/cursor_read.rb
 - lib/hookd/error.rb
 - lib/hookd/hook.rb
 - lib/hookd/hook_activity.rb