hookd-client 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea1070dc0c7ba33c48d14a8e0f15bfa8eebb0d0ce2760c163705edaa80ef523e
-  data.tar.gz: c9908f45314c965d5b8038945fe3b7000c966bc62169e089cb772845feedfc30
+  metadata.gz: 34ae0dd926717518a70cad0cb175f770147117b2154e758d4c2923d365d1b38a
+  data.tar.gz: 879aef64cc1a3bdae6c98c8206bd975f1352a03dc56b1267951445a37edc0e3f
 SHA512:
-  metadata.gz: 4a6675e6a729a717c565d580537063e8c11b6149d4b2da879439e0b762d97c0df87076f9d9e48e4ca507487b6460f8a0cb0e0bf0a2a43ea39ea6e379a1561762
-  data.tar.gz: 994aee67d64f6331efcfac36ddf54fd9a56c1c558140a9720ab99e7a3362fcd8f2ea7dcbf35887f1a0224dec0e9262c7671de3ca14e7635698493cbaade18cbf
+  metadata.gz: c2ee6ea4abf3dd624ec309c0c8a59b0245ba4f630504f4a2e3fb9d06c7c9449a6e057ee6aa0907a55b988f567ae6c93addb2c6f4c2a2762ac353c1d96814d46e
+  data.tar.gz: f11ab8a0431425559449126b85a87d158257c56f7714f6a67fd0b70862e6ffae561ec04d74d7ff72fec69f41ecd8647f272f0b8bf6330e5f3f4ff8cf799f1e13

data/README.md

@@ -110,13 +110,40 @@ end
 
 The client requires two configuration parameters:
 
-- `server`: The Hookd server URL (e.g., `https://hookd.example.com`)
+- `server`: The Hookd server URL (e.g., `https://hookd.example.com`). When the server runs its private API listener (`server.api.listener`), use that listener's address instead, e.g. `https://hookd.example.com:8443`
 - `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`.
 
+### Owner Secrets
+
+When the server enables owner secrets (`server.api.owner_secret.enabled`), each
+hook is readable only with the secret it was registered under, sent as the
+`X-Hookd-Secret` header. Without a `secret:`, the first registration adopts the
+one the server generates; every later request, registrations included, sends
+it, so all the client's hooks share one owner. Store it to read them later:
+
+```ruby
+hook = client.register
+secret = client.secret # generated by the server, returned only once
+
+# Later, or from another process:
+client = Hookd::Client.new(server: server, token: token, secret: secret)
+client.poll(hook.id)
+```
+
+Every hook `#register` and `#register_batch` return also carries its owner
+secret in `hook.secret`, so it is never lost, even if the client's secret
+changes in the meantime.
+
+To use your own secret (32 to 256 visible ASCII characters, at least 128 random
+bits), pass `secret:` or set `client.secret =` before registering. For one owner
+per hook, set `client.secret = nil` before each registration and keep each
+`hook.secret`. On a server without owner secrets, nothing changes and
+`client.secret` stays `nil`.
+
 ### API Reference
 
 #### `Hookd::Client`

data/lib/hookd/client.rb

@@ -7,6 +7,8 @@ require 'uri'
 module Hookd
   # HTTP client for interacting with Hookd server
   class Client
+    include OwnerSecret
+
     # 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
@@ -16,10 +18,13 @@ module Hookd
 
     attr_reader :server, :token, :max_response_bytes
 
-    def initialize(server:, token:, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
+    # @param secret [String, nil] owner secret sent with every request; when nil,
+    #   the first registration adopts the one the server generates
+    def initialize(server:, token:, secret: nil, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
       @server = server
       @token = token
       @max_response_bytes = max_response_bytes
+      init_secret(secret)
       @http = HTTPX.with(
         headers: { 'X-API-Key' => token },
         timeout: {
@@ -44,7 +49,7 @@ module Hookd
     def register(count: nil, ttl: nil, metadata: nil)
       raise ArgumentError, 'count must be a positive integer' if count && (!count.is_a?(Integer) || count < 1)
 
-      parse_register_response(post('/register', register_body(count, ttl, metadata)))
+      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
@@ -56,7 +61,7 @@ module Hookd
       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 }))
+      hook_list(*post_register({ hooks: body }))
     end
 
     # List long-lived hooks, without interactions, whose metadata matches every
@@ -98,7 +103,7 @@ module Hookd
       validate_hook_ids(hook_ids)
 
       url = "#{@server}/poll"
-      options = { headers: { 'Content-Type' => 'application/json' }, json: hook_ids }
+      options = { headers: { 'Content-Type' => 'application/json' }.merge(secret_headers), json: hook_ids }
       response = @http.post(url, **options)
       response_data = handle_response(response)
 
@@ -135,7 +140,8 @@ module Hookd
     # @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']
+      url = "#{@server}/poll/#{hook_id}?through=#{through}"
+      handle_response(@http.delete(url, headers: secret_headers))['acknowledged']
     end
 
     # Read several hooks past their cursors in one request
@@ -200,25 +206,25 @@ module Hookd
       body.empty? ? nil : body
     end
 
-    def parse_register_response(response)
+    def parse_register_response(response, secret)
       # Single hook response (backward compatible)
-      return Hook.from_hash(response) if response.key?('id')
+      return Hook.from_hash(response, secret: secret) if response.key?('id')
 
       # Multiple hooks response
       return [] if response['hooks'].nil? || response['hooks'].empty?
 
-      response['hooks'].map { |h| Hook.from_hash(h) }
+      response['hooks'].map { |h| Hook.from_hash(h, secret: secret) }
     end
 
     def get(path)
       url = "#{@server}#{path}"
-      response = @http.get(url)
+      response = @http.get(url, headers: secret_headers)
       handle_response(response)
     end
 
-    def post(path, body = nil)
+    def post(path, body = nil, as: secret)
       url = "#{@server}#{path}"
-      options = { headers: { 'Content-Type' => 'application/json' } }
+      options = { headers: { 'Content-Type' => 'application/json' }.merge(secret_headers(as)) }
       options[:json] = body if body
 
       response = @http.post(url, **options)
@@ -231,11 +237,11 @@ module Hookd
       "?#{URI.encode_www_form(metadata.to_h { |k, v| ["metadata.#{k}", v.to_s] })}"
     end
 
-    def hook_list(response)
+    def hook_list(response, secret = nil)
       hooks = response['hooks']
       raise Error, 'Invalid response format: missing hooks' unless hooks.is_a?(Array)
 
-      hooks.map { |h| Hook.from_hash(h) }
+      hooks.map { |h| Hook.from_hash(h, secret: secret) }
     end
 
     def validate_cursor(seq, name)

data/lib/hookd/hook.rb

@@ -3,11 +3,12 @@
 module Hookd
   # 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.
+  # long-lived hooks (registered with a ttl) and nil otherwise. secret is the
+  # owner secret a registered hook belongs to, on servers with owner secrets.
   class Hook
-    attr_reader :id, :dns, :http, :https, :smtp, :created_at, :expires_at, :metadata
+    attr_reader :id, :dns, :http, :https, :smtp, :created_at, :expires_at, :metadata, :secret
 
-    def initialize(id:, dns:, http:, https:, created_at:, smtp: nil, expires_at: nil, metadata: nil)
+    def initialize(id:, dns:, http:, https:, created_at:, smtp: nil, expires_at: nil, metadata: nil, secret: nil)
       @id = id
       @dns = dns
       @http = http
@@ -16,10 +17,11 @@ module Hookd
       @created_at = created_at
       @expires_at = expires_at
       @metadata = metadata
+      @secret = secret
     end
 
     # Create a Hook from API response hash
-    def self.from_hash(hash)
+    def self.from_hash(hash, secret: nil)
       raise ArgumentError, "Invalid hash: expected Hash, got #{hash.class}" unless hash.is_a?(Hash)
 
       new(
@@ -30,7 +32,8 @@ module Hookd
         smtp: hash['smtp'],
         created_at: hash['created_at'],
         expires_at: hash['expires_at'],
-        metadata: hash['metadata']
+        metadata: hash['metadata'],
+        secret: secret
       )
     end
 

data/lib/hookd/owner_secret.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hookd
+  # Owner secret handling for servers with owner secrets enabled, where each
+  # hook is readable only with the secret it was registered under.
+  module OwnerSecret
+    # Header carrying the owner secret.
+    SECRET_HEADER = 'X-Hookd-Secret'
+
+    # The owner secret in use, possibly generated by the server on the first
+    # registration. Store it to read the hooks later.
+    # @return [String, nil]
+    def secret
+      @secret_lock.synchronize { @secret }
+    end
+
+    # Set the owner secret; nil lets the next registration adopt a new one.
+    # @param value [String, nil]
+    def secret=(value)
+      value = nil if value == ''
+      @secret_lock.synchronize do
+        @secret = value
+        @settled = !value.nil?
+      end
+    end
+
+    private
+
+    def init_secret(value)
+      @secret_lock = Mutex.new
+      @register_lock = Mutex.new
+      self.secret = value
+    end
+
+    # Registers and returns the response with the secret its hooks belong to:
+    # the one sent, or the one the server generated, adopted when the client
+    # has none. Until a secret is known, registrations run one at a time, so
+    # concurrent first calls end up under the same owner.
+    def post_register(body)
+      return register_as(body) if @secret_lock.synchronize { @settled }
+
+      @register_lock.synchronize { register_as(body) }
+    end
+
+    def register_as(body)
+      sent = secret
+      response = post('/register', body, as: sent)
+      owner = (response['secret'] if response.is_a?(Hash)) || sent
+      @secret_lock.synchronize do
+        @secret ||= owner
+        @settled = true
+      end
+      [response, owner]
+    end
+
+    def secret_headers(value = secret)
+      value ? { SECRET_HEADER => value } : {}
+    end
+  end
+end

data/lib/hookd/version.rb

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

data/lib/hookd.rb

@@ -6,6 +6,7 @@ require_relative 'hookd/hook'
 require_relative 'hookd/hook_activity'
 require_relative 'hookd/interaction'
 require_relative 'hookd/cursor_read'
+require_relative 'hookd/owner_secret'
 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.5.1
+  version: 1.6.0
 platform: ruby
 authors:
 - Joshua MARTINELLE
@@ -39,6 +39,7 @@ files:
 - lib/hookd/hook.rb
 - lib/hookd/hook_activity.rb
 - lib/hookd/interaction.rb
+- lib/hookd/owner_secret.rb
 - lib/hookd/version.rb
 homepage: https://github.com/JoshuaMart/Hookd
 licenses: