angarium 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98d1d438861a4ff090327c932205c0e6345c8f079562a99ca6ab344fff93da10
-  data.tar.gz: 6b37af363e8a253db8f9e66feb549a56a2152fb4fc7536c76551f4daf61688de
+  metadata.gz: 29562789c5729a772541a473a348a0273921ea4e9a29e93a8a2de5ca58155610
+  data.tar.gz: 4297618824d834c783269cb16c7d05f2434bb1d7057e0617fc62742c89c2291b
 SHA512:
-  metadata.gz: 1675398932024d506e7338faa7b3585df46caf3f6f80090347ee029bb608dd859333eff198259eee769e466d9fbc4bee91be9994e971055659e44dd1d2f87d65
-  data.tar.gz: 44481ffed27e96af446720d475124536eb27e384ad2fe28c777bf4b9cadb9033bec49ec345dbb4abc1376deab3d9d7d24917cb283c4aa4d9f6742f34533239e8
+  metadata.gz: 4603bd4667fb265cae1eb433b3bb0077535cf7af2f313df2215a18d16f40f1464bf81ae4e5b2bf742470d5cdb5fb4e6720bc4e2f944a20a279729e7782e022f3
+  data.tar.gz: d6ba2088037d98660a7be54fcd87a051e923c6404e5d7bb1996512540b795a4f1678660cd6cd3170c6b6a1632b99c783aad9d70b3c7ec9002898ad84ee594d8b

data/CHANGELOG.md

@@ -5,6 +5,24 @@ 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

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 `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!
@@ -706,6 +707,7 @@ which documents every option inline. The delivery and retry settings:
 | `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,13 +2,13 @@
 
 ## Supported versions
 
-Angarium is pre-release. Security fixes are provided for the `0.2.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.2.x   | ✅        |
+| 0.3.x   | ✅        |
 
 ## Reporting a vulnerability
 

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/models/angarium/delivery.rb

@@ -90,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
@@ -103,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
@@ -129,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,
@@ -178,9 +178,18 @@ module Angarium
     # clean dirty baseline to persist the delivering -> succeeded/pending move).
     def claim_for_attempt!
       now = Time.current
-      claimed = self.class.where(id: id, state: "pending").update_all(
-        ["state = 'delivering', attempt_count = attempt_count + 1, last_attempt_at = ?, updated_at = ?", now, now]
-      )
+      # 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
@@ -200,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!

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,6 +37,12 @@ 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, length: {maximum: 255}
@@ -139,14 +145,14 @@ module Angarium
       transition_status!(:enabled, from: :unverified) { Angarium.notify(:on_endpoint_verified, self) }
     end
 
-    # Deliver a synthetic `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.
+    # 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: "ping", payload: payload)
+      event = Angarium::Event.create!(name: Angarium.config.ping_event_name, payload: payload)
       deliveries.create!(event: event, forced: force)
     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/db/angarium_migrate/20260704000001_create_angarium_endpoints.rb

@@ -8,9 +8,12 @@ class CreateAngariumEndpoints < ActiveRecord::Migration[7.1]
       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

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/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

@@ -7,6 +7,7 @@ module Angarium
       :max_retry_after, :retry_jitter, :signing_secret_grace_period,
       :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
 
@@ -60,6 +61,10 @@ module Angarium
       # 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/version.rb

@@ -1,3 +1,3 @@
 module Angarium
-  VERSION = "0.2.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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: angarium
 version: !ruby/object:Gem::Version
-  version: 0.2.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