Warn on partial UDP send failure, raise SendError when all fail (#23)

* Log UDP send failures as warnings, not errors

A host with both A and AAAA records on a network with no route for one
family (e.g. v4-only network with AAAA record) will fail the send for
the unreachable family while the other family succeeds. The previous
"Sparoid error sending ..." wording made the partial failure look
fatal; reword to "Sparoid warn: skip <ip>: <reason>" to make clear it
is recoverable, mirroring sparoid.rb#20.

* Include hostname in UDP send warning

* Suppress per-address UDP send errors when one family succeeds

When a host resolves to both A and AAAA addresses but the network only
routes one family, the unreachable family's send raises EHOSTUNREACH.
Previously every per-addr failure was logged, which is noisy when the
other family's send succeeded and the call as a whole worked. Collect
errors and only log them if every address failed; include the original
hostname alongside the IP for easier triage.

* Extract send_errors_to_report helper and unit-test it

The previous integration tests relied on "send to 0.0.0.0 fails with
EHOSTUNREACH" to exercise the all-failed branch, which is true on
macOS but not on the Linux CI runners where the kernel accepts the
send. Extract the error-reporting decision into a pure helper that can
be unit-tested with synthetic inputs, independent of OS networking
behavior.

* Raise SendError when no UDP send succeeds, warn on partial failure

- Per-address failure with at least one success: STDERR warn line
  ("Sparoid warn: skip <host> (<ip>): <reason>") so v4-only networks
  don't make AAAA-resolved hosts log catastrophically.
- Every address failed: raise Sparoid::Client::SendError with all
  per-address details. The CLI already catches and exits 1, so this
  surfaces a clear actionable failure instead of returning quietly and
  failing later in fdpass.

* Emit partial-failure warnings via Log.warn instead of raw STDERR

Apps embedding sparoid as a shard at scale (15k+ servers) need partial
UDP send failures classified as WARN-level by their monitoring, not as
ERROR-level (which most aggregators infer from STDERR by default).

- Sparoid::Client::Log = ::Log.for(self) declares a log source so apps
  can filter sparoid output specifically.
- udp_send emits per-address skips via Log.warn { ... }.
- client-cli configures Log.setup_from_env with an STDERR backend (in
  :connect mode STDOUT is the unix-domain FD-passing channel and isn't
  safe for free-form output).

* Address PR review: drop redundant prefix, test send-result branching

- SendError no longer prepends 'Sparoid:' to the message — the CLI's
  rescue clause already prefixes 'Sparoid error:', so the previous
  format produced 'Sparoid error: Sparoid: failed to send...'.
- Replace the format_send_errors formatting helper with a
  process_send_results helper that owns the partial-vs-total decision.
  This raises SendError directly when every send failed and returns
  the per-address partial-failure errors otherwise.
- Specs now cover both branches plus the all-succeeded and
  empty-input cases, exercising the actual control flow rather than
  just message formatting.

Author: oskgu360

spec/sparoid_spec.cr

@@ -142,3 +142,43 @@ describe Sparoid::Server do
     s.try &.close
   end
 end
+
+describe Sparoid::Client do
+  describe ".process_send_results" do
+    it "raises SendError when every send failed" do
+      ip1 = Socket::IPAddress.new("1.1.1.1", 1)
+      ip2 = Socket::IPAddress.new("2.2.2.2", 2)
+      results = [
+        {ip1, Exception.new("no route").as(Exception?)},
+        {ip2, Exception.new("network down").as(Exception?)},
+      ]
+      ex = expect_raises(Sparoid::Client::SendError) do
+        Sparoid::Client.process_send_results("example.com", results)
+      end
+      ex.message.to_s.should contain("example.com")
+      ex.message.to_s.should contain("1.1.1.1:1: no route")
+      ex.message.to_s.should contain("2.2.2.2:2: network down")
+    end
+
+    it "returns partial-failure errors when at least one send succeeded" do
+      ip1 = Socket::IPAddress.new("1.1.1.1", 1)
+      ip2 = Socket::IPAddress.new("2.2.2.2", 2)
+      err = Exception.new("oops")
+      results = [
+        {ip1, nil.as(Exception?)},
+        {ip2, err.as(Exception?)},
+      ]
+      Sparoid::Client.process_send_results("example.com", results).should eq [{ip2, err}]
+    end
+
+    it "returns nothing when all sends succeeded" do
+      ip = Socket::IPAddress.new("1.1.1.1", 1)
+      results = [{ip, nil.as(Exception?)}]
+      Sparoid::Client.process_send_results("example.com", results).should be_empty
+    end
+
+    it "returns nothing when there were no addresses" do
+      Sparoid::Client.process_send_results("example.com", [] of {Socket::IPAddress, Exception?}).should be_empty
+    end
+  end
+end

src/client-cli.cr

@@ -1,7 +1,11 @@
+require "log"
 require "option_parser"
 require "./client"
 require "./version"
 
+# Route logs to STDERR (in :connect mode STDOUT is the unix-domain socket used for FD passing).
+Log.setup_from_env(default_level: :info, backend: Log::IOBackend.new(STDERR))
+
 subcommand = :none
 host = "0.0.0.0"
 port = 8484

src/client.cr

@@ -1,3 +1,4 @@
+require "log"
 require "socket"
 require "random/secure"
 require "openssl/cipher"
@@ -11,6 +12,10 @@ require "wait_group"
 
 module Sparoid
   class Client
+    Log = ::Log.for(self)
+
+    class SendError < Exception; end
+
     def self.new(config_path = "~/.sparoid.ini")
       key = ENV.fetch("SPAROID_KEY", "")
       hmac_key = ENV.fetch("SPAROID_HMAC_KEY", "")
@@ -70,25 +75,43 @@ module Sparoid
       exit 1 # only if all connects fails
     end
 
-    # Send to all resolved IPs for the hostname
+    # Send to all resolved IPs for the hostname.
+    # Per-address failures are logged as warnings if at least one address succeeded.
+    # If every address fails, raises SendError.
     private def self.udp_send(host, port, key : String, hmac_key : String, public_ip : String? = nil) : Array(String)
       host_addresses = Socket::Addrinfo.udp(host, port)
-      host_addresses.each do |addrinfo|
+      results = host_addresses.map do |addrinfo|
         packages = generate_messages(addrinfo.ip_address, public_ip).map { |message| generate_package(key, hmac_key, message) }
         socket = UDPSocket.new(addrinfo.family)
+        error = nil.as(Exception?)
         begin
           packages.each do |data|
             socket.send data, to: addrinfo.ip_address
           end
         rescue ex
-          STDERR << "Sparoid error sending " << ex.inspect << "\n"
+          error = ex
         ensure
           socket.close
         end
+        {addrinfo.ip_address, error}
+      end
+      process_send_results(host, results).each do |ip, ex|
+        Log.warn { "skip #{host} (#{ip}): #{ex.message}" }
       end
       host_addresses.map &.ip_address.address
     end
 
+    # Decide whether per-address send failures are partial (warn) or total (raise).
+    # Returns the per-address errors to warn about. Raises SendError when every send failed.
+    def self.process_send_results(host : String, results : Array({Socket::IPAddress, Exception?})) : Array({Socket::IPAddress, Exception})
+      errors = results.compact_map { |ip, err| err.try { |e| {ip, e} } }
+      if !results.empty? && errors.size == results.size
+        details = errors.map { |ip, ex| "#{ip}: #{ex.message}" }.join("; ")
+        raise SendError.new("failed to send to any address for #{host}: #{details}")
+      end
+      errors
+    end
+
     private def self.encrypt(key, hmac_key, data) : Bytes
       cipher = OpenSSL::Cipher.new("aes-256-cbc")
       cipher.encrypt