angarium 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b7cf3c384477b5808150336685e858b28eff1e9590f9ec454569019ec8d10bf
-  data.tar.gz: 6756a2b028c09b72146f5624e50d08a9ff9f062b4aa7030859548e68d02a5c8d
+  metadata.gz: 29562789c5729a772541a473a348a0273921ea4e9a29e93a8a2de5ca58155610
+  data.tar.gz: 4297618824d834c783269cb16c7d05f2434bb1d7057e0617fc62742c89c2291b
 SHA512:
-  metadata.gz: e291f504be94a517d8276d00f0089aec942d104b134ea7a6d907fffe55c7a0914bb38766fc005ac0c6c1faab0bf05e873ee13fa6fcf20b8b558996224cbc9ec2
-  data.tar.gz: 676568e4ac7bae762dfc517ba3e3183d2f13a0e8022f8419ed54ded2e0566f2bfb2510c476b4fe3cc84dd150d6f5f0ffdc9d68c3a582272f34e8d0e3e9d4a50b
+  metadata.gz: 4603bd4667fb265cae1eb433b3bb0077535cf7af2f313df2215a18d16f40f1464bf81ae4e5b2bf742470d5cdb5fb4e6720bc4e2f944a20a279729e7782e022f3
+  data.tar.gz: d6ba2088037d98660a7be54fcd87a051e923c6404e5d7bb1996512540b795a4f1678660cd6cd3170c6b6a1632b99c783aad9d70b3c7ec9002898ad84ee594d8b

data/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project are documented here. The format is based on
 follow [Semantic Versioning](https://semver.org). While on 0.x, a minor release
 may include breaking changes; patch releases stay backward compatible.
 
+## [0.3.0] - 2026-07-08
+
+### Bug Fixes
+
+- Persist delivery attempts without stranding on receiver text
+- Require the retry schedule to be due before claiming
+- Treat an echoed boolean network control as a no-op
+- Report swallowed callback errors to Rails.error
+- Set JSON column defaults at the model layer for MySQL
+
+### Features
+
+- Make the ping event name configurable
+
+### Ci
+
+- Run the suite against PostgreSQL and MySQL
+
+## [0.2.0] - 2026-07-07
+
+### Bug Fixes
+
+- Harden delivery concurrency and endpoint validation
+- Block special-use ranges and bound DNS resolution
+- Robust pagination, JSON error contract, event preload
+
+### Documentation
+
+- Add email reporting channel and auto-bump SECURITY.md version
+- Document new config options and SSRF special-use hardening
+
+### Features
+
+- Expose endpoint owner in the API behind a policy gate
+- Add dns_timeout, hosts-file toggle, and input limits
+- Add hot-path indexes, persisted forced flag, text url column
+
+### Performance
+
+- Memoize the record-less API policy per request
+- Load only the columns subscription matching needs
+
+### Refactoring
+
+- Rename ping event and message to plain "ping"
+
 ## [0.1.0] - 2026-07-07
 
 ### Bug Fixes
@@ -26,6 +72,7 @@ may include breaking changes; patch releases stay backward compatible.
 - Close the last README review nits
 - Include unverified in the ping status lists
 - Document ActiveSupport::Notifications instrumentation
+- Add RubyGems version badge to README
 
 ### Features
 

data/README.md

@@ -351,9 +351,10 @@ redelivery is at-least-once-safe either way. Set it to `nil` to disable reaping.
 
 ### Pinging an endpoint
 
-Verify an endpoint end-to-end by delivering a synthetic `angarium.ping` event
-(subscription matching is bypassed, so a ping is always sent). Returns the
-`Angarium::Delivery`, so you can reload it to inspect the outcome:
+Verify an endpoint end-to-end by delivering a synthetic `ping` event (the name
+is `config.ping_event_name`, default `"ping"` — change it if your app already
+uses `"ping"`). Subscription matching is bypassed, so a ping is always sent.
+Returns the `Angarium::Delivery`, so you can reload it to inspect the outcome:
 
 ```ruby
 delivery = endpoint.ping!
@@ -443,6 +444,7 @@ methods:
 | `create_unverified?` | `false` | Whether endpoints created through the API start `unverified` (no deliveries until a successful ping verifies them) instead of live. |
 | `permit_allow_private_network?` | `false` | Whether `allow_private_network` (relax the private-IP block) is API-writable. Dangerous; trusted operators only. |
 | `permit_allowed_networks?` | `false` | Whether `allowed_networks` (a restrictive CIDR allowlist) is API-writable. |
+| `expose_owner?` | `false` | Whether serialized endpoints include `owner_type`/`owner_id`. Off by default (the owner is the tenancy boundary, resolved server-side). Turn on for a cross-owner console that must tell endpoints apart. |
 | `index?` `show?` `create?` `update?` `destroy?` | `true` | Whether each action is allowed. |
 | `rotate_secret?` `pause?` `enable?` `verify?` `ping?` `redeliver?` | `update?` | Member actions; default to the `update?` capability. |
 
@@ -455,6 +457,11 @@ class WebhookEndpointPolicy < Angarium::Api::Policy
   # Multi-tenant visibility: compose on top of the relation you're given.
   def scope(relation) = relation.where(owner_id: current_user.account.owner_ids)
 
+  # A console spanning owners needs owner_type/owner_id on each endpoint to tell
+  # them apart. Pair this with a scope (above) that actually spans owners —
+  # expose_owner? only affects serialization, not what the caller can see.
+  def expose_owner? = current_user.admin?
+
   # Admins may create for any owner in their account (via an owner_id param);
   # everyone else creates for themselves.
   def owner
@@ -514,6 +521,9 @@ included (see the note below):
 
 - **Secrets are never echoed.** `signing_secret` is returned only by `create` and
   `rotate_secret`; `custom_headers` (which may hold a credential) is write-only.
+- **Owner is opt-in.** The endpoint object omits `owner_type`/`owner_id` unless the
+  policy's `expose_owner?` returns true; `owner_id` is a string (a polymorphic
+  owner may have any primary-key type).
 - **Pagination.** List endpoints take `?limit=` (default 50, max 200) and
   `?offset=`, and each list response carries a `pagination` object (`limit`,
   `offset`, `count` in this page, `total` overall); there are more when
@@ -582,7 +592,12 @@ at delivery time:
 - **`config.block_private_ips`** (default `true`) blocks delivery to
   private, loopback, and link-local addresses (e.g. `127.0.0.1`, `10.0.0.0/8`,
   `169.254.169.254`), including IPv4-mapped IPv6 forms (e.g. `::ffff:127.0.0.1`)
-  and the unspecified address (`0.0.0.0` / `::`).
+  and the unspecified address (`0.0.0.0` / `::`). It also blocks IANA special-use
+  ranges that aren't flagged as "private" but are still unsafe targets —
+  `0.0.0.0/8` (routes to localhost on Linux), CGNAT (`100.64.0.0/10`), reserved
+  space (`240.0.0.0/4`), and the NAT64 prefix (`64:ff9b::/96`, which can embed the
+  metadata IP). Resolution is re-checked at delivery time and the connection is
+  pinned to the validated IP, so DNS rebinding can't slip past.
 - **`endpoint.allow_private_network`** (default `false`) is the per-endpoint opt-in
   required to deliver to a private address. An allowlist entry alone does **not**
   unlock a private address.
@@ -687,7 +702,12 @@ which documents every option inline. The delivery and retry settings:
 | `max_retry_after` | `3600` | Cap (seconds) on a honored `Retry-After`; `nil` is uncapped. |
 | `auto_disable_endpoint_after` | `nil` | Deactivate an endpoint after N consecutive failures; `nil` never does. |
 | `signing_secret_grace_period` | `24.hours` | How long a rotated endpoint's previous secret stays valid. |
-| `block_private_ips` | `true` | Reject endpoint URLs resolving to private/loopback addresses (SSRF). |
+| `block_private_ips` | `true` | Reject endpoint URLs resolving to private/loopback/special-use addresses (SSRF). |
+| `dns_timeout` | `[1, 3]` | Per-try timeout(s) in seconds for resolving an endpoint host; `nil` uses the resolver default. |
+| `resolve_dns_with_hosts_file` | `true` | Also resolve endpoint hosts via the system hosts file (e.g. `/etc/hosts`), not DNS only. Set `false` to harden to DNS-only. |
+| `max_url_length` | `2048` | Maximum length of an endpoint URL. |
+| `max_subscribed_events` | `100` | Maximum number of event patterns an endpoint may subscribe to. |
+| `ping_event_name` | `"ping"` | Event name for the synthetic event `endpoint.ping!` emits; change it to avoid colliding with your own events. |
 | `max_response_body_bytes` | `65_536` | Truncate the stored response body; `nil` stores it whole. |
 | `delivery_attempt_retention` | `nil` | Age past which `angarium:prune` deletes attempts; `nil` keeps all. |
 | `delivering_timeout` | `15.minutes` | Age after which `angarium:reap` requeues a stuck `delivering` delivery. |

data/SECURITY.md

@@ -2,23 +2,27 @@
 
 ## Supported versions
 
-Angarium is pre-release. Security fixes are provided for the `0.1.x` series
+Angarium is pre-release. Security fixes are provided for the `0.3.x` series
 during this phase. Once a stable line is released, this policy will be updated to
 list the versions that receive security updates.
 
 | Version | Supported |
 | ------- | --------- |
-| 0.1.x   | ✅        |
+| 0.3.x   | ✅        |
 
 ## Reporting a vulnerability
 
 Please report security vulnerabilities **privately**. Do **not** open a public
 issue, pull request, or discussion for a suspected vulnerability.
 
-Use GitHub's private vulnerability reporting for the
-[`radioactive-labs/angarium`](https://github.com/radioactive-labs/angarium)
-repository: go to the **Security** tab and choose **Report a vulnerability**
-(this opens a private draft advisory visible only to the maintainers).
+Use one of the following private channels:
+
+- **Preferred:** GitHub's private vulnerability reporting for the
+  [`radioactive-labs/angarium`](https://github.com/radioactive-labs/angarium)
+  repository — go to the **Security** tab and choose **Report a vulnerability**
+  (this opens a private draft advisory visible only to the maintainers).
+- **Email:** [sfroelich01@gmail.com](mailto:sfroelich01@gmail.com) with the
+  subject line `[SECURITY] Angarium`.
 
 We aim to acknowledge new reports within a few business days, and we'll keep you
 informed as we investigate and prepare a fix. Please give us a reasonable window

data/app/controllers/angarium/api/base_controller.rb

@@ -15,6 +15,7 @@ module Angarium
       rescue_from ActiveRecord::RecordInvalid, with: :angarium_render_invalid
       rescue_from Angarium::Api::NotAuthorized, with: :angarium_render_forbidden
       rescue_from Angarium::Api::UnpermittedParameter, with: :angarium_render_unpermitted
+      rescue_from ActionController::ParameterMissing, with: :angarium_render_bad_request
 
       # Resolved current user (via config.current_user). Public so policies can
       # read it as `controller.angarium_current_user`.
@@ -31,8 +32,19 @@ module Angarium
       end
 
       # The policy for this request (config.policy_class), holding scope,
-      # create-owner, and per-action permissions.
+      # create-owner, and per-action permissions. The record-less policy is
+      # memoized: scope/owner/expose_owner? and friends are request-global and
+      # get called repeatedly (expose_owner? runs once per serialized row), so a
+      # list response would otherwise allocate a fresh policy per endpoint. A
+      # record-bound policy (member authorize!) still constructs fresh, since it
+      # varies by record.
       def angarium_policy(record = nil)
+        return build_angarium_policy(record) if record
+
+        @angarium_policy ||= build_angarium_policy
+      end
+
+      def build_angarium_policy(record = nil)
         Angarium.config.policy_class.to_s.constantize.new(self, record)
       end
 
@@ -41,9 +53,10 @@ module Angarium
         angarium_policy.scope(Angarium::Endpoint.all)
       end
 
-      # A delivery whose endpoint is within the caller's scope, or 404.
+      # A delivery whose endpoint is within the caller's scope, or 404. Eager-load
+      # :event since delivery_json serializes event.name (avoids a follow-up query).
       def scoped_delivery(id)
-        Angarium::Delivery.where(endpoint_id: endpoint_scope.select(:id)).find(id)
+        Angarium::Delivery.includes(:event).where(endpoint_id: endpoint_scope.select(:id)).find(id)
       end
 
       # Guard the current action with the policy's `<action>?` predicate.
@@ -55,8 +68,8 @@ module Angarium
       # and advertises the window with a `pagination` object so clients can page
       # (there's more when offset + count < total).
       def render_collection(key, relation, &serializer)
-        limit = params.fetch(:limit, 50).to_i.clamp(1, 200)
-        offset = [params.fetch(:offset, 0).to_i, 0].max
+        limit = pagination_param(:limit, 50).clamp(1, 200)
+        offset = [pagination_param(:offset, 0), 0].max
         records = relation.limit(limit).offset(offset).to_a
         render json: {
           key => records.map(&serializer),
@@ -64,6 +77,15 @@ module Angarium
         }
       end
 
+      # Coerce a pagination query param to an integer, ignoring non-scalar input.
+      # A hostile `?limit[]=1` makes params[:limit] an Array/Parameters, which
+      # has no #to_i and would otherwise raise an uncaught 500; fall back to the
+      # default for anything that isn't a plain string.
+      def pagination_param(key, default)
+        raw = params[key]
+        raw.is_a?(String) ? raw.to_i : default
+      end
+
       def render_error(status, message, **extra)
         render json: {error: message, **extra}, status: status
       end
@@ -71,6 +93,7 @@ module Angarium
       def angarium_render_unauthorized = render_error(:unauthorized, "authentication required")
       def angarium_render_forbidden = render_error(:forbidden, "not authorized")
       def angarium_render_not_found = render_error(:not_found, "not found")
+      def angarium_render_bad_request(error) = render_error(:bad_request, "bad request", details: [error.message])
 
       def angarium_render_invalid(error)
         render_error(:unprocessable_entity, "validation failed", details: error.record.errors.full_messages)
@@ -99,6 +122,12 @@ module Angarium
           created_at: endpoint.created_at.iso8601,
           updated_at: endpoint.updated_at.iso8601
         }
+        if angarium_policy.expose_owner?
+          # Raw columns off the row (no owner fetch, so no cross-database hit);
+          # the caller reassembles the owner via its own type/id convention.
+          json[:owner_type] = endpoint.owner_type
+          json[:owner_id] = endpoint.owner_id
+        end
         json[:signing_secret] = endpoint.signing_secret if include_secret
         json
       end

data/app/controllers/angarium/api/endpoints_controller.rb

@@ -107,8 +107,18 @@ module Angarium
         return unless body.key?(attr)
 
         current = (@endpoint || Angarium::Endpoint.new).public_send(attr)
-        submitted = body[attr]
-        submitted = Array(submitted).map(&:to_s) if attr == :allowed_networks
+        # Compare like-for-like against the typed attribute, so echoing the
+        # serialized endpoint back is a no-op regardless of wire representation:
+        # allowed_networks is an array of strings, while allow_private_network is a
+        # boolean a form/JSON client may send as "true"/"false"/"0"/"1". Without
+        # the cast, a stringly-typed "false" wouldn't == the boolean false and a
+        # semantic no-op would raise a spurious 422.
+        submitted =
+          if attr == :allowed_networks
+            Array(body[attr]).map(&:to_s)
+          else
+            ActiveModel::Type::Boolean.new.cast(body[attr])
+          end
 
         raise Angarium::Api::UnpermittedParameter, attr unless submitted == current
       end

data/app/jobs/angarium/deliver_job.rb

@@ -1,11 +1,14 @@
 module Angarium
   class DeliverJob < ApplicationJob
-    def perform(delivery_id, force = false)
+    # The second positional arg is accepted only for backward compatibility with
+    # jobs enqueued by an older version (force is now persisted on the delivery as
+    # `forced` and read by #deliver!); new enqueues pass just the id.
+    def perform(delivery_id, _legacy_force = nil)
       delivery = Delivery.find_by(id: delivery_id)
       return unless delivery
       return unless delivery.pending?
 
-      delivery.deliver!(force: force)
+      delivery.deliver!
     end
   end
 end

data/app/models/angarium/delivery.rb

@@ -13,12 +13,7 @@ module Angarium
     belongs_to :endpoint, class_name: "Angarium::Endpoint"
     has_many :delivery_attempts, class_name: "Angarium::DeliveryAttempt", dependent: :destroy
 
-    # Transient: set on a delivery built for a manual, forced send (e.g.
-    # endpoint.ping!(force: true)) so its first attempt bypasses the endpoint
-    # status guard. Not persisted; only the enqueued job carries it forward.
-    attr_accessor :force_send
-
-    after_create_commit { force_send ? DeliverJob.perform_later(id, true) : DeliverJob.perform_later(id) }
+    after_create_commit { DeliverJob.perform_later(id) }
 
     # Recover deliveries stranded in "delivering": a worker set the state to
     # "delivering" (in #deliver!) but died (crash, deploy, OOM) before
@@ -34,14 +29,30 @@ module Angarium
       ids = where(state: "delivering").where(last_attempt_at: ..older_than.ago).pluck(:id)
       return 0 if ids.empty?
 
-      where(id: ids).update_all(state: "pending", next_attempt_at: Time.current, updated_at: Time.current)
-      ids.each { |id| DeliverJob.perform_later(id) }
-      ids.size
+      # Reset each id with a state-scoped compare-and-swap, not a blanket
+      # `where(id: ids)`: a delivery can leave `delivering` (succeed, be marked
+      # gone, etc.) between the pluck above and this reset. Re-asserting
+      # `state: "delivering"` means we never drag a completed delivery back to
+      # pending, and — since only the reaper that actually flipped the row
+      # enqueues — two reapers racing the same snapshot can't double-enqueue.
+      requeued = 0
+      ids.each do |id|
+        changed = where(id: id, state: "delivering")
+          .update_all(state: "pending", next_attempt_at: Time.current, updated_at: Time.current)
+        next if changed.zero?
+
+        DeliverJob.perform_later(id)
+        requeued += 1
+      end
+      requeued
     end
 
     # Performs one attempt. Records a DeliveryAttempt, then transitions to
-    # succeeded, blocked (SSRF), schedules a retry, or exhausts. Returns the attempt.
-    def deliver!(client: Client.new, force: false)
+    # succeeded, blocked (SSRF), schedules a retry, or exhausts. Returns the
+    # attempt. `force` defaults to the persisted `forced` flag so a reaped or
+    # redelivered forced attempt keeps bypassing the guard; pass it explicitly
+    # only to override in tests.
+    def deliver!(client: Client.new, force: forced)
       payload = {delivery_id: id, endpoint_id: endpoint_id, event: event.name, force: force}
       ActiveSupport::Notifications.instrument("deliver.angarium", payload) do
         # An endpoint's status can change after a delivery is queued: auto-disable
@@ -62,7 +73,12 @@ module Angarium
           end
         end
 
-        update!(state: "delivering", attempt_count: attempt_count + 1, last_attempt_at: Time.current)
+        # Atomically claim this delivery (pending -> delivering) so only one
+        # worker ever attempts it. Without the compare-and-swap, two jobs for the
+        # same id (a reaper requeue racing a stale enqueue, an adapter retry, etc.)
+        # would both pass the guard above, both POST, and both read the same stale
+        # attempt_count. If the CAS changes no row, another worker owns it: bail.
+        return nil unless claim_for_attempt!
         payload[:attempt] = attempt_count
 
         # Re-resolve at delivery time (rather than trusting the save-time check)
@@ -74,7 +90,7 @@ module Angarium
         if addresses.any? { |ip| !AddressPolicy.ip_allowed?(ip, endpoint) }
           payload[:outcome] = :blocked
           payload[:error] = "blocked: destination address not permitted"
-          attempt = delivery_attempts.create!(error: payload[:error])
+          attempt = record_attempt!(error: payload[:error])
           update!(state: "blocked", next_attempt_at: nil)
           endpoint.record_delivery_failure!
           return attempt
@@ -87,7 +103,7 @@ module Angarium
         if addresses.empty?
           payload[:outcome] = :unresolvable
           payload[:error] = "unresolvable host: #{destination_host}"
-          attempt = delivery_attempts.create!(error: payload[:error])
+          attempt = record_attempt!(error: payload[:error])
           handle_failure!
           return attempt
         end
@@ -113,7 +129,7 @@ module Angarium
           addresses: addresses.map(&:to_s)
         )
 
-        attempt = delivery_attempts.create!(
+        attempt = record_attempt!(
           response_code: result.code,
           response_body: result.body,
           error: result.error,
@@ -144,15 +160,42 @@ module Angarium
 
     # Reset the retry cycle and re-enqueue immediately. Keeps prior
     # DeliveryAttempt history. `force: true` sends even if the endpoint is no
-    # longer enabled (for the re-enqueued attempt). Returns self.
+    # longer enabled (for the re-enqueued attempt); it is persisted so the reaper
+    # honors it too. Returns self.
     def redeliver!(force: false)
-      update!(state: "pending", next_attempt_at: nil, attempt_count: 0)
-      force ? DeliverJob.perform_later(id, true) : DeliverJob.perform_later(id)
+      update!(state: "pending", next_attempt_at: nil, attempt_count: 0, forced: force)
+      DeliverJob.perform_later(id)
       self
     end
 
     private
 
+    # Atomic pending -> delivering claim: the single writer gate for an attempt.
+    # Returns true if THIS caller won the row (and bumps attempt_count in the same
+    # statement so concurrent claimers can't both read a stale count), false if
+    # another worker already claimed it. Reload so in-memory state matches the
+    # CAS (the rest of #deliver! reads attempt_count, and later update!s need a
+    # clean dirty baseline to persist the delivering -> succeeded/pending move).
+    def claim_for_attempt!
+      now = Time.current
+      # Also require the schedule to be due. Without this, a duplicate or stale
+      # enqueue (an at-least-once adapter re-running a job whose retry is scheduled
+      # for later) would claim and attempt EARLIER than next_attempt_at, defeating
+      # the backoff the Retry-After defenses exist to protect. New, held, and
+      # redelivered rows carry next_attempt_at: nil and so are always due; a
+      # scheduled retry becomes claimable only once its time arrives; the reaper
+      # stamps next_attempt_at = now on requeue, so a reaped row is due immediately.
+      claimed = self.class.where(id: id, state: "pending")
+        .where("next_attempt_at IS NULL OR next_attempt_at <= ?", now)
+        .update_all(
+          ["state = 'delivering', attempt_count = attempt_count + 1, last_attempt_at = ?, updated_at = ?", now, now]
+        )
+      return false if claimed.zero?
+
+      reload
+      true
+    end
+
     # Endpoint was paused after this delivery was queued. Park it (no attempt
     # consumed, no failure recorded) by clearing the schedule and leaving it
     # pending; Endpoint#enable! re-enqueues parked deliveries so a pause/resume
@@ -166,11 +209,36 @@ module Angarium
     # queued. Stop retrying and log why. Recover with redeliver! if the endpoint is
     # later re-enabled. Returns the logged attempt.
     def cancel!(reason:)
-      attempt = delivery_attempts.create!(error: "canceled: endpoint #{reason}")
+      attempt = record_attempt!(error: "canceled: endpoint #{reason}")
       update!(state: "canceled", next_attempt_at: nil)
       attempt
     end
 
+    # Persist a DeliveryAttempt. A raise here lands after the row is already
+    # `delivering`, which would strand it for the reaper to redeliver forever (the
+    # exact failure F1 exists to prevent), so this must not raise on anything the
+    # receiver can influence. DeliveryAttempt#normalizes sanitizes the body and
+    # error at assignment (UTF-8 scrub, NUL strip, length cap), so the create!
+    # below should succeed; the rescue is a last-resort net for anything that slips
+    # through (a transient DB error, a MySQL limit we cannot reproduce on SQLite).
+    # We rescue broadly on purpose because any escape means a permanent loop.
+    def record_attempt!(attributes)
+      delivery_attempts.create!(attributes)
+    rescue => e
+      # The attempt's `error` is served to the webhook owner via the API, so we
+      # must not leak the internal exception there: store a generic marker for
+      # them, and surface the real cause internally so we can actually fix it.
+      # Reported to Rails.error because a delivery we can't record is a correctness
+      # problem, not a transient hiccup.
+      Rails.logger.error { "[Angarium] failed to persist delivery attempt for delivery ##{id}: #{e.class}: #{e.message}" }
+      Rails.error.report(e, handled: true, severity: :error, source: "angarium", context: {delivery_id: id})
+      delivery_attempts.create!(
+        response_code: attributes[:response_code],
+        duration: attributes[:duration],
+        error: "delivery attempt could not be recorded"
+      )
+    end
+
     def succeed!
       update!(state: "succeeded", next_attempt_at: nil)
       endpoint.record_delivery_success!
@@ -203,7 +271,9 @@ module Angarium
         # misconfigured receiver could send a tiny Retry-After to defeat our
         # backoff and make us hammer it. Retry-After can delay, never expedite.
         wait = [wait, retry_after].max if retry_after
-        update!(state: "pending", next_attempt_at: Time.current + wait)
+        # Drop force: a recorded failure means the forced first attempt is spent,
+        # and per the deliver! contract any scheduled retry follows normal rules.
+        update!(state: "pending", next_attempt_at: Time.current + wait, forced: false)
         DeliverJob.set(wait: wait).perform_later(id)
       end
     end

data/app/models/angarium/delivery_attempt.rb

@@ -2,6 +2,28 @@ module Angarium
   class DeliveryAttempt < ApplicationRecord
     belongs_to :delivery, class_name: "Angarium::Delivery"
 
+    # response_body and error are partly receiver-controlled. Sanitize them on
+    # assignment (so every write path is covered, not just the delivery happy
+    # path) into something a text column always accepts — otherwise the INSERT
+    # raises, and mid-#deliver! that raise lands after the row is already
+    # `delivering`, stranding the delivery for the reaper to redeliver forever.
+    # For each: coerce to UTF-8 and scrub invalid bytes (an upstream byte cap can
+    # split a multibyte char; a receiver may return non-UTF-8 outright), then drop
+    # NUL — it is valid UTF-8 (so scrub keeps it) but PostgreSQL rejects it in text
+    # columns, surfacing via the pg driver as an ArgumentError, not even a
+    # StatementInvalid. `error` is additionally capped to its column limit (only
+    # MySQL sets one) since a client error message can overflow varchar(255).
+    normalizes :response_body, with: ->(value) { sanitize_text(value) }
+    normalizes :error, with: ->(value) {
+      text = sanitize_text(value)
+      limit = columns_hash["error"]&.limit
+      limit ? text.truncate(limit) : text
+    }
+
+    def self.sanitize_text(value)
+      value.dup.force_encoding(Encoding::UTF_8).scrub.delete("\u0000")
+    end
+
     # Delete delivery attempts older than the cutoff. `older_than` may be a
     # duration (e.g. 90.days) or an absolute Time. Returns the number deleted.
     # (A Time also responds to #ago but requires an argument, so branch on the

data/app/models/angarium/endpoint.rb

@@ -37,13 +37,21 @@ module Angarium
     # here keeps behavior correct on every supported Rails version.
     attribute :allow_private_network, :boolean, default: false
 
+    # Defaults at the model layer, not the column: both are JSON columns and MySQL
+    # forbids a DB default there. Procs yield a fresh object per record so the
+    # empty default is never shared/mutated across instances.
+    attribute :subscribed_events, default: -> { [] }
+    attribute :allowed_networks, default: -> { [] }
+
     before_validation :ensure_signing_secret, on: :create
 
-    validates :name, presence: true
+    validates :name, presence: true, length: {maximum: 255}
     validates :url, presence: true
     validates :url, "angarium/endpoint_url": true, if: :verify_url_address?
+    validate :url_within_length_limit
     validate :allowed_networks_are_valid_cidrs
     validate :custom_headers_are_strings
+    validate :subscribed_events_are_bounded
 
     def self.generate_signing_secret
       "whsec_#{Base64.strict_encode64(SecureRandom.bytes(32))}"
@@ -120,8 +128,10 @@ module Angarium
     def enable!
       return false unless transition_status!(:enabled, consecutive_failures: 0)
       # Resume deliveries parked while this endpoint was paused (pending with no
-      # scheduled attempt). Dispatch creates none while paused, so this only
-      # re-enqueues the held ones.
+      # scheduled attempt). This predicate can also match a delivery that already
+      # has an in-flight job (a forced ping, a just-redelivered row), but a stray
+      # re-enqueue is harmless: the atomic pending->delivering claim in
+      # Delivery#deliver! guarantees only one worker ever sends a given delivery.
       deliveries.where(state: "pending", next_attempt_at: nil).find_each { |d| DeliverJob.perform_later(d.id) }
       true
     end
@@ -135,15 +145,15 @@ module Angarium
       transition_status!(:enabled, from: :unverified) { Angarium.notify(:on_endpoint_verified, self) }
     end
 
-    # Deliver a synthetic `angarium.ping` event to this endpoint, bypassing
-    # subscription matching (a ping is always sent). By default a ping also
-    # ignores the endpoint's status, so you can test an endpoint that is paused,
-    # disabled, or not yet enabled; pass `force: false` to respect the status
-    # guard instead. Returns the created Angarium::Delivery, whose
-    # after_create_commit enqueues the DeliverJob; reload it to inspect the outcome.
-    def ping!(payload = {message: "Angarium ping"}, force: true)
-      event = Angarium::Event.create!(name: "angarium.ping", payload: payload)
-      deliveries.create!(event: event) { |d| d.force_send = force }
+    # Deliver a synthetic ping event (name from config.ping_event_name, default
+    # "ping") to this endpoint, bypassing subscription matching (a ping is always
+    # sent). By default a ping also ignores the endpoint's status, so you can test
+    # an endpoint that is paused, disabled, or not yet enabled; pass `force: false`
+    # to respect the status guard instead. Returns the created Angarium::Delivery,
+    # whose after_create_commit enqueues the DeliverJob; reload it to inspect the outcome.
+    def ping!(payload = {message: "ping"}, force: true)
+      event = Angarium::Event.create!(name: Angarium.config.ping_event_name, payload: payload)
+      deliveries.create!(event: event, forced: force)
     end
 
     private
@@ -200,6 +210,31 @@ module Angarium
       end
     end
 
+    def url_within_length_limit
+      max = Angarium.config.max_url_length
+      return if url.blank? || max.nil? || url.length <= max
+
+      errors.add(:url, "is too long (maximum is #{max} characters)")
+    end
+
+    def subscribed_events_are_bounded
+      return if subscribed_events.blank?
+
+      unless subscribed_events.is_a?(Array)
+        errors.add(:subscribed_events, "must be an array of event patterns")
+        return
+      end
+
+      max = Angarium.config.max_subscribed_events
+      if max && subscribed_events.length > max
+        errors.add(:subscribed_events, "cannot have more than #{max} subscribed events")
+      end
+
+      unless subscribed_events.all? { |e| e.is_a?(String) && !e.empty? && e.length <= 255 }
+        errors.add(:subscribed_events, "must be non-empty strings of at most 255 characters")
+      end
+    end
+
     def custom_headers_are_strings
       return if custom_headers.blank?
 
@@ -212,6 +247,14 @@ module Angarium
       if custom_headers.keys.any? { |k| RESERVED_HEADERS.include?(k.downcase) }
         errors.add(:custom_headers, "cannot override reserved or transport headers (#{RESERVED_HEADERS.join(", ")})")
       end
+
+      # Reject CR/LF/NUL in any key or value. The outbound HTTP client writes
+      # headers verbatim, so a CRLF in a value would inject an extra header line
+      # — smuggling e.g. a forged webhook-signature past the RESERVED_HEADERS
+      # denylist (which only guards whole keys). Fail closed instead.
+      if custom_headers.any? { |k, v| k.match?(/[\r\n\0]/) || v.match?(/[\r\n\0]/) }
+        errors.add(:custom_headers, "must not contain control characters (CR, LF, or NUL)")
+      end
     end
   end
 end

data/app/models/angarium/event.rb

@@ -2,6 +2,10 @@ module Angarium
   class Event < ApplicationRecord
     has_many :deliveries, class_name: "Angarium::Delivery", dependent: :destroy
 
+    # Default at the model layer, not the column: the payload column is JSON and
+    # MySQL forbids a DB default there. A proc yields a fresh hash per record.
+    attribute :payload, default: -> { {} }
+
     validates :name, presence: true
   end
 end

data/app/policies/angarium/api/policy.rb

@@ -61,6 +61,16 @@ module Angarium
         false
       end
 
+      # Should serialized endpoints include their owner (owner_type/owner_id)?
+      # Default: no. The owner is the tenancy boundary, resolved server-side, so
+      # the single-owner default has no reason to echo it back. Override for an
+      # admin/multi-tenant console that lists endpoints across owners and needs
+      # to tell them apart. The raw columns are exposed (already loaded on the
+      # row), not the owner record, so this adds no per-row database fetch.
+      def expose_owner?
+        false
+      end
+
       def index? = true
       def show? = true
       def create? = true

data/db/angarium_migrate/20260704000001_create_angarium_endpoints.rb

@@ -1,14 +1,19 @@
 class CreateAngariumEndpoints < ActiveRecord::Migration[7.1]
   def change
     create_table :angarium_endpoints, id: Angarium.primary_key_type do |t|
-      t.references :owner, polymorphic: true, null: false, type: :string
+      # index: false — the owner scope also orders by created_at, so the
+      # composite index below covers both the tenancy filter and the list order.
+      t.references :owner, polymorphic: true, null: false, type: :string, index: false
       t.string :name, null: false
-      t.string :url, null: false
+      t.text :url, null: false
       t.string :status, null: false, default: "enabled"
       t.text :signing_secret, null: false
-      t.json :subscribed_events, null: false, default: []
+      # No DB-level default on the JSON columns: MySQL forbids defaults on
+      # JSON/TEXT/BLOB. The defaults are set on the model (Endpoint#subscribed_events
+      # / #allowed_networks) so the null: false constraints hold on every adapter.
+      t.json :subscribed_events, null: false
       t.boolean :allow_private_network, null: false, default: false
-      t.json :allowed_networks, null: false, default: []
+      t.json :allowed_networks, null: false
       # Encrypted at rest (may hold a receiver credential), so it's nullable with
       # no DB default — an unencrypted default would fail to decrypt on read.
       t.json :custom_headers
@@ -17,6 +22,9 @@ class CreateAngariumEndpoints < ActiveRecord::Migration[7.1]
       t.datetime :secret_rotated_at
       t.datetime :status_changed_at
       t.timestamps
+      # Serves the owner-scoped list endpoint (WHERE owner_type/owner_id ORDER BY
+      # created_at DESC) in a single index scan.
+      t.index [:owner_type, :owner_id, :created_at], name: "idx_angarium_endpoints_on_owner_created_at"
     end
   end
 end

data/db/angarium_migrate/20260704000002_create_angarium_events.rb

@@ -2,7 +2,9 @@ class CreateAngariumEvents < ActiveRecord::Migration[7.1]
   def change
     create_table :angarium_events, id: Angarium.primary_key_type do |t|
       t.string :name, null: false
-      t.json :payload, null: false, default: {}
+      # No DB-level default: MySQL forbids defaults on JSON/TEXT/BLOB columns. The
+      # default is set on the model (Event#payload) so null: false holds everywhere.
+      t.json :payload, null: false
       t.timestamps
     end
   end

data/db/angarium_migrate/20260704000003_create_angarium_deliveries.rb

@@ -2,12 +2,23 @@ class CreateAngariumDeliveries < ActiveRecord::Migration[7.1]
   def change
     create_table :angarium_deliveries, id: Angarium.primary_key_type do |t|
       t.references :event, null: false, type: Angarium.primary_key_type, foreign_key: {to_table: :angarium_events}
-      t.references :endpoint, null: false, type: Angarium.primary_key_type, foreign_key: {to_table: :angarium_endpoints}
+      # index: false — the endpoint-scoped delivery list orders by created_at, so
+      # the composite index below covers both the FK lookup and the list order.
+      t.references :endpoint, index: false, null: false, type: Angarium.primary_key_type, foreign_key: {to_table: :angarium_endpoints}
       t.string :state, null: false, default: "pending"
       t.integer :attempt_count, null: false, default: 0
+      # A manual ping!/redeliver! delivery whose next attempt bypasses the
+      # endpoint status guard. Persisted (not just a job arg) so the reaper can
+      # honor it when re-running an attempt that was stranded before completing;
+      # cleared once a recorded failure schedules a retry.
+      t.boolean :forced, null: false, default: false
       t.datetime :last_attempt_at
       t.datetime :next_attempt_at
       t.timestamps
+      # Endpoint-scoped list endpoint (WHERE endpoint_id ORDER BY created_at DESC).
+      t.index [:endpoint_id, :created_at], name: "idx_angarium_deliveries_on_endpoint_created_at"
+      # Stalled-delivery reaper: WHERE state = 'delivering' AND last_attempt_at < ?.
+      t.index [:state, :last_attempt_at], name: "idx_angarium_deliveries_on_state_last_attempt"
     end
   end
 end

data/db/angarium_migrate/20260704000004_create_angarium_delivery_attempts.rb

@@ -1,12 +1,18 @@
 class CreateAngariumDeliveryAttempts < ActiveRecord::Migration[7.1]
   def change
     create_table :angarium_delivery_attempts, id: Angarium.primary_key_type do |t|
-      t.references :delivery, null: false, type: Angarium.primary_key_type, foreign_key: {to_table: :angarium_deliveries}
+      # index: false — the delivery-scoped attempt list orders by created_at, so
+      # the composite index below covers both the FK lookup and the list order.
+      t.references :delivery, index: false, null: false, type: Angarium.primary_key_type, foreign_key: {to_table: :angarium_deliveries}
       t.integer :response_code
       t.text :response_body
       t.string :error
       t.float :duration
       t.timestamps
+      # Delivery-scoped attempt list (WHERE delivery_id ORDER BY created_at DESC).
+      t.index [:delivery_id, :created_at], name: "idx_angarium_attempts_on_delivery_created_at"
+      # Retention prune: DELETE WHERE created_at < cutoff over the largest table.
+      t.index :created_at, name: "idx_angarium_attempts_on_created_at"
     end
   end
 end

data/lib/angarium/address_policy.rb

@@ -45,17 +45,50 @@ module Angarium
       literal = to_ipaddr(host)
       return [literal] if literal
 
-      Resolv.getaddresses(host).filter_map { |a| to_ipaddr(a) }
+      # Bound DNS with config.dns_timeout via an explicit Resolv::DNS — an
+      # unbounded lookup lets a host with a deliberately slow authoritative
+      # nameserver tie up a delivery worker well past our HTTP timeouts. With the
+      # hosts file enabled (default), wrap it in a Resolv that consults
+      # /etc/hosts first (so an internally-pinned endpoint resolves, and a hosts
+      # hit short-circuits DNS); otherwise resolve DNS-only.
+      dns = Resolv::DNS.new
+      dns.timeouts = Angarium.config.dns_timeout if Angarium.config.dns_timeout
+      resolvers = Angarium.config.resolve_dns_with_hosts_file ? [Resolv::Hosts.new, dns] : [dns]
+      Resolv.new(resolvers).getaddresses(host).filter_map { |a| to_ipaddr(a.to_s) }
     rescue
       []
+    ensure
+      dns&.close
     end
 
+    # IANA special-use ranges that are unsafe webhook destinations but that
+    # Ruby's IPAddr predicates (loopback?/private?/link_local?/unique_local?) do
+    # NOT flag. Without these, e.g. `https://0.0.0.1/` (routes to localhost on
+    # Linux) or `https://[64:ff9b::a9fe:a9fe]/` (NAT64 of the cloud metadata IP)
+    # would pass validation and be delivered to. Documentation ranges
+    # (192.0.2.0/24, 2001:db8::/32, etc.) are intentionally omitted: they aren't
+    # an SSRF vector and blocking them would reject the TEST-NET fixtures.
+    SPECIAL_USE_RANGES = [
+      "0.0.0.0/8",      # "this host" — routes to localhost on Linux
+      "100.64.0.0/10",  # CGNAT (RFC 6598)
+      "192.0.0.0/24",   # IETF protocol assignments (RFC 6890)
+      "198.18.0.0/15",  # benchmarking (RFC 2544)
+      "240.0.0.0/4",    # reserved / future use, incl. 255.255.255.255 broadcast
+      "64:ff9b::/96",   # NAT64 well-known prefix (RFC 6052)
+      "64:ff9b:1::/48"  # NAT64 local-use prefix (RFC 8215)
+    ].map { |cidr| IPAddr.new(cidr) }.freeze
+
     def private?(ip)
       ip = normalize(ip)
       return true if ip.to_i.zero? # 0.0.0.0 / :: (unspecified -> localhost on Linux)
 
       ip.loopback? || ip.private? || ip.link_local? ||
-        (ip.respond_to?(:unique_local?) && ip.unique_local?)
+        (ip.respond_to?(:unique_local?) && ip.unique_local?) ||
+        special_use?(ip)
+    end
+
+    def special_use?(ip)
+      SPECIAL_USE_RANGES.any? { |range| range.family == ip.family && range.include?(ip) }
     end
 
     # Collapse IPv4-mapped IPv6 (::ffff:x.x.x.x) to native IPv4 so the predicates

data/lib/angarium/client.rb

@@ -25,6 +25,10 @@ module Angarium
           headers: {})
       end
 
+      # Cap the response we hold in memory. The body is receiver-controlled and
+      # may not be persistable text (non-UTF-8 bytes, a NUL, or a multibyte char
+      # this byte cap splits); DeliveryAttempt#normalizes sanitizes it at
+      # persistence time, so this stays a pure transport concern.
       max = Angarium.config.max_response_body_bytes
       body = response.body.to_s
       body = body.byteslice(0, max) if max

data/lib/angarium/configuration.rb

@@ -5,7 +5,9 @@ module Angarium
       :primary_key_type, :database, :connects_to, :max_response_body_bytes,
       :auto_disable_endpoint_after, :respect_retry_after,
       :max_retry_after, :retry_jitter, :signing_secret_grace_period,
-      :delivery_attempt_retention, :delivering_timeout,
+      :delivery_attempt_retention, :delivering_timeout, :dns_timeout,
+      :resolve_dns_with_hosts_file, :max_url_length, :max_subscribed_events,
+      :ping_event_name,
       :on_delivery_exhausted, :on_endpoint_deactivated, :on_endpoint_verified,
       :parent_controller, :current_user, :policy_class
 
@@ -34,6 +36,10 @@ module Angarium
       # Takes precedence over @database for the connection.
       @connects_to = nil
       @max_response_body_bytes = 65_536
+      # Disable an endpoint after this many consecutive *failed deliveries* (a
+      # delivery that exhausts its whole retry schedule, or is blocked by the SSRF
+      # guard) — NOT individual failed HTTP attempts. A single delivery that
+      # retries and eventually gives up counts as one. nil disables auto-disable.
       @auto_disable_endpoint_after = nil
       @respect_retry_after = true
       @max_retry_after = 3600
@@ -41,6 +47,24 @@ module Angarium
       @signing_secret_grace_period = 24.hours
       @delivery_attempt_retention = nil
       @delivering_timeout = 15.minutes
+      # Per-try timeout(s), in seconds, for resolving an endpoint host before
+      # delivery. Bounds how long a hostile or misconfigured slow-resolving host
+      # can stall a delivery worker (Resolv::DNS retries across the array). Set to
+      # nil to use the resolver's own defaults.
+      @dns_timeout = [1, 3]
+      # Whether host resolution also consults the system hosts file (/etc/hosts),
+      # not just DNS. Default true, so an internal endpoint pinned via /etc/hosts
+      # resolves as expected. Set false to harden a deployment to DNS-only.
+      @resolve_dns_with_hosts_file = true
+      # Max length of an endpoint URL and the cap on how many event patterns an
+      # endpoint may subscribe to (each pattern is replayed by EventMatcher on
+      # every dispatch). Both bound user-supplied input.
+      @max_url_length = 2048
+      @max_subscribed_events = 100
+      # Event name of the synthetic event emitted by Endpoint#ping!. Configurable
+      # so it won't collide with an application that already uses "ping" for its
+      # own events (and so pings can be routed/filtered distinctly).
+      @ping_event_name = "ping"
       @on_delivery_exhausted = nil # ->(delivery) { ... }
       @on_endpoint_deactivated = nil # ->(endpoint, reason) { ... } reason: :consecutive_failures | :gone
       @on_endpoint_verified = nil # ->(endpoint) { ... } fired when an unverified endpoint is verified

data/lib/angarium/dispatch.rb

@@ -5,9 +5,13 @@ module Angarium
     def call(event_name, payload, owner:)
       notify_payload = {event: event_name, event_id: nil, deliveries: 0}
       ActiveSupport::Notifications.instrument("dispatch.angarium", notify_payload) do
-        endpoints = Endpoint.enabled.where(owner: owner).select do |endpoint|
-          endpoint.subscribed_to?(event_name)
-        end
+        # Load only the columns subscription matching needs. Endpoints carry
+        # large encrypted blobs (signing_secret, previous_signing_secret,
+        # custom_headers); pulling them for every candidate — most of which may
+        # not even match — is wasted I/O. The matched endpoints' secrets are
+        # loaded later, at delivery time, from the delivery's own association.
+        candidates = Endpoint.enabled.where(owner: owner).select(:id, :subscribed_events)
+        endpoints = candidates.to_a.select { |endpoint| endpoint.subscribed_to?(event_name) }
         next nil if endpoints.empty?
 
         Event.transaction do

data/lib/angarium/version.rb

@@ -1,3 +1,3 @@
 module Angarium
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/angarium.rb

@@ -38,7 +38,11 @@ module Angarium
 
       callback.call(*args)
     rescue => e
+      # A raising callback must never break the pipeline, but swallowing it with
+      # only a log hides a real bug from error tracking. Log and report it (handled,
+      # so delivery continues) so it surfaces where the operator will see it.
       Rails.logger.error { "[Angarium] #{callback_name} callback raised: #{e.class}: #{e.message}" }
+      Rails.error.report(e, handled: true, severity: :error, source: "angarium", context: {callback: callback_name})
     end
   end
 end

data/lib/generators/angarium/policy/templates/policy.rb

@@ -23,6 +23,10 @@ class <%= class_name %> < Angarium::Api::Policy
   # def permit_allow_private_network? = current_user.admin?
   # def permit_allowed_networks? = true
 
+  # Include owner_type/owner_id in serialized endpoints (default off). Turn on
+  # for an admin/multi-tenant console that lists endpoints across owners.
+  # def expose_owner? = current_user.admin?
+
   # Per-action permissions. rotate_secret?/pause?/enable?/ping?/redeliver? all
   # default to update?.
   # def index?   = true

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: angarium
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - TheDumbTechGuy
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-07 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails