audioproxy-rails 0.1.0

data/lib/audioproxy/options.rb

@@ -0,0 +1,274 @@
+require "active_support/duration"
+
+module Audioproxy
+  # Renders the proxy's option grammar: +/+-separated +key:value+ segments,
+  # with colon-separated parts for the multi-part keys.
+  #
+  # This layer renders, it does not validate (D1). Value domains and cross-key
+  # rules belong to the proxy, which versions them with the server and returns
+  # structured 422s. The exceptions are values this module cannot render
+  # faithfully — an unknown key, a number that does not fit the grammar, a value
+  # carrying a separator — because a mangled segment is a valid-looking URL for
+  # the wrong variant, and it fails at request time, far from here.
+  module Options
+    # The proxy's fourteen option keys, canonical short spellings.
+    KEYS = %i[bd br cb ch dl f fade gain norm pk_fmt pts q sr t].freeze
+
+    # A spelled-out spelling for each canonical key, for call sites that would
+    # rather read than decode. Total over KEYS, so "does this key have an alias"
+    # never has two answers: +fade+ and +gain+ are already words and alias to
+    # themselves. The names are the proxy's own where it has one — its Options
+    # struct calls pts +peak_count+ and pk_fmt +peak_format+ — so this is one
+    # vocabulary spelled twice, not a second vocabulary (D2).
+    ALIASES = {
+      f: :format,
+      br: :bitrate,
+      q: :quality,
+      sr: :sample_rate,
+      ch: :channels,
+      bd: :bit_depth,
+      t: :trim,
+      fade: :fade,
+      gain: :gain,
+      norm: :normalize,
+      pts: :peak_count,
+      pk_fmt: :peak_format,
+      dl: :download,
+      cb: :cache_buster
+    }.freeze
+
+    # Every accepted spelling to the canonical key it renders as. Canonical
+    # keys map to themselves, so resolution is one lookup rather than a
+    # conditional.
+    CANONICAL = ALIASES.each_with_object({}) { |(key, spelled), table| table[spelled] = key }
+      .merge(KEYS.to_h { |key| [ key, key ] })
+      .freeze
+
+    # Keys whose grammar takes colon-separated parts: +t:START[:DURATION]+,
+    # +fade:IN[:OUT]+, +norm:ebu[:I[:TP[:LRA]]]+.
+    MULTI_PART_KEYS = %i[t fade norm].freeze
+
+    # Keys whose values *are* a number of seconds, and so may be written as an
+    # ActiveSupport::Duration (D6).
+    TIME_KEYS = %i[t fade].freeze
+
+    # Keys the proxy treats as opaque payloads (download filename, cache
+    # buster), rendered verbatim rather than number-formatted.
+    OPAQUE_KEYS = %i[cb dl].freeze
+
+    # The proxy caps decimals at 3 places when it parses, and hashes the
+    # normalized options string into its cache key.
+    MAX_DECIMALS = 3
+
+    # Characters a rendered value may not carry. The builder supplies '/' and
+    # ':', so a value containing either silently invents a segment or a part.
+    # '?' and '#' end the path as far as a browser is concerned, which truncates
+    # what the proxy receives below what was signed: a 403 at request time, far
+    # from the call. Whitespace and control characters are not URL bytes at all.
+    SEPARATORS = %r{[/:?#\s]|[[:cntrl:]]}
+
+    class << self
+      # Renders an ordered key => value Hash into an options segment. Caller
+      # order is preserved (D4); normalization is the proxy's business.
+      def render(options)
+        resolve(options).map { |key, value| segment(key, value) }.join("/")
+      end
+
+      # Rewrites a key => value Hash onto the canonical short keys, so that
+      # everything downstream — rendering, ordering, the defaults merge — sees
+      # one vocabulary and is unaware aliases exist (D1). Insertion order is
+      # preserved, so an aliased key keeps its slot. Unrecognized keys pass
+      # through untouched, to be reported by +segment+ against the key table
+      # rather than by a second, thinner error here.
+      def resolve(options)
+        spellings = {}
+
+        options.each_with_object({}) do |(key, value), resolved|
+          canonical = CANONICAL.fetch(symbolize(key), key)
+
+          # Ruby's keyword collection keeps both spellings, and picking a winner
+          # by position would make the URL depend on argument order in a way
+          # nothing else here does (D4).
+          # inspect, not interpolation: the two spellings are often identical as
+          # text — "fade" and :fade, or a self-aliasing key given both ways —
+          # and "as fade and fade" tells the caller nothing.
+          if (first = spellings[canonical])
+            raise ArgumentError,
+              "Audioproxy option #{canonical} was given twice, as #{first.inspect} and #{key.inspect}; " \
+              "each option takes one spelling per call"
+          end
+          spellings[canonical] = key
+
+          resolved[canonical] = value
+        end
+      end
+
+      # Renders one +key:value+ segment. The key may be canonical or an alias.
+      def segment(key, value)
+        key = CANONICAL.fetch(symbolize(key)) do |unknown|
+          raise ArgumentError,
+            "unknown Audioproxy option #{unknown.inspect}; known keys are #{KEYS.join(", ")}, " \
+            "each also accepted as its spelled-out alias (#{ALIASES[:br]}, #{ALIASES[:sr]}, #{ALIASES[:pk_fmt]}, …)"
+        end
+
+        "#{key}:#{render_value(key, value)}"
+      end
+
+      # The proxy's canonical minimal number spelling. Strings and symbols pass
+      # through untouched — the caller opted out of formatting.
+      def format_number(value)
+        case value
+        when String then value
+        when Symbol then value.to_s
+        when Integer then value.to_s
+        when Complex
+          # Numeric, but Complex#round is undefined and Complex#to_r silently
+          # drops a zero imaginary part. Neither is a number this grammar has.
+          raise ArgumentError, "Audioproxy option values must be real numbers, got #{value.inspect}"
+        when Numeric then format_decimal(value)
+        else
+          raise ArgumentError, "Audioproxy option values must be numbers, strings or symbols, got #{value.class}"
+        end
+      end
+
+      private
+        def symbolize(key)
+          case key
+          when Symbol then key
+          when String then key.to_sym
+          else
+            raise ArgumentError, "Audioproxy option keys must be Symbols or Strings, got #{key.class}"
+          end
+        end
+
+        def render_value(key, value)
+          return render_parts(key, value) if value.is_a?(Array)
+
+          format_part(key, value)
+        end
+
+        def render_parts(key, value)
+          unless MULTI_PART_KEYS.include?(key)
+            raise ArgumentError,
+              "Audioproxy option #{key}: takes a single value, got #{value.inspect}; " \
+              "only #{MULTI_PART_KEYS.join(", ")} take colon-separated parts"
+          end
+          if value.empty?
+            raise ArgumentError, "Audioproxy option #{key}: was given an empty Array"
+          end
+
+          value.map { |part| format_part(key, part) }.join(":")
+        end
+
+        def format_part(key, value)
+          rendered = render_part(key, value)
+
+          # Every part is validated on its own, not the assembled segment: an
+          # empty part between two separators (t::30) reads as a whole value.
+          if rendered.empty?
+            raise ArgumentError, "Audioproxy option #{key}: has an empty value"
+          end
+          if (offender = rendered[SEPARATORS])
+            raise ArgumentError,
+              "Audioproxy option #{key}: must not contain #{offender.inspect}, got #{rendered.inspect}. " \
+              "The builder supplies the separators; pre-encode the value, or use raw: to write the whole options string."
+          end
+
+          rendered
+        end
+
+        # dl: and cb: are opaque to the proxy, so they are opaque here too: a
+        # filename or cache buster is whatever the caller wrote.
+        def render_part(key, value)
+          # An explicit clause, because +case value when Numeric+ does not match
+          # a Duration: it overrides is_a? to answer true for Numeric, but
+          # Module#=== performs the real type check and ignores the override.
+          # Without this, t: 30.seconds is rejected as "not a number" by
+          # something that says it is one.
+          return render_duration(key, value) if value.is_a?(ActiveSupport::Duration)
+          return format_number(value) unless OPAQUE_KEYS.include?(key)
+
+          case value
+          when String then value
+          when Symbol, Numeric then format_number(value)
+          else
+            raise ArgumentError, "Audioproxy option #{key}: must be a String, Symbol or number, got #{value.class}"
+          end
+        end
+
+        # A Duration is the Rails spelling of a number of seconds, so it is
+        # accepted where the value *is* seconds and refused everywhere else:
+        # br: 3.seconds rendering br:3 would be a valid-looking URL for the
+        # wrong variant, which is the failure this gem exists to prevent (D6).
+        def render_duration(key, value)
+          unless TIME_KEYS.include?(key)
+            raise ArgumentError,
+              "Audioproxy option #{key}: does not take a duration, got #{value.inspect}; " \
+              "only #{TIME_KEYS.join(", ")} take an ActiveSupport::Duration, because only their values are seconds"
+          end
+
+          # #value is the number the caller wrote (30 for 30.seconds, 0.3 for
+          # 0.3.seconds, 60 for 1.minute), so it goes through exactly the
+          # formatting that number would and renders the same bytes. #to_r is
+          # the wrong door: for 0.3.seconds it yields the double's true value,
+          # which the three-decimal cap then rejects, while a plain t: 0.3
+          # renders — Float goes through Rational(value.to_s) for that reason.
+          format_number(value.value)
+        end
+
+        # Rendering is exact integer arithmetic on the value's decimal form.
+        # Neither Float#to_s nor format("%.3f") can do this job alone: the
+        # former emits the +1.0e-05+ exponent shapes the grammar rejects, and
+        # the latter re-reads the underlying binary value, so it renders
+        # 12345678901234.56 as "12345678901234.561" and truncates a BigDecimal
+        # to a double on the way past.
+        def format_decimal(value)
+          scaled = exact_decimal(value) * (10 ** MAX_DECIMALS)
+          unless scaled.denominator == 1
+            raise ArgumentError,
+              "Audioproxy option value #{value.inspect} needs more than #{MAX_DECIMALS} decimal places; " \
+              "the proxy caps decimals at #{MAX_DECIMALS} and rejects the rest as excessive precision. " \
+              "Round explicitly at the call site if that is what you mean."
+          end
+
+          render_scaled(scaled.numerator)
+        end
+
+        # The exact decimal the caller meant, as a Rational.
+        def exact_decimal(value)
+          assert_finite!(value)
+
+          case value
+          when Float
+            # Float#to_s is the shortest decimal that round-trips to this
+            # double, which is the spelling the caller wrote. The double's own
+            # expansion is another number entirely — 0.001 is really
+            # 0.001000000000000000020816…, and rendering *that* would reject
+            # every fractional float as excessive precision.
+            Rational(value.to_s)
+          when Rational then value
+          else
+            # BigDecimal and any other real Numeric: to_r is exact, which is
+            # what a value carrying more digits than a double can hold needs.
+            value.to_r
+          end
+        end
+
+        def assert_finite!(value)
+          return if value.is_a?(Rational) || value.finite?
+
+          raise ArgumentError, "Audioproxy option value #{value} is not a finite number"
+        end
+
+        # scaled is the value times 10**MAX_DECIMALS, exactly. Negative zero
+        # collapses on the way in: -0.0 scales to plain 0.
+        def render_scaled(scaled)
+          sign = scaled.negative? ? "-" : ""
+          whole, fraction = scaled.abs.divmod(10 ** MAX_DECIMALS)
+          return "#{sign}#{whole}" if fraction.zero?
+
+          "#{sign}#{whole}.#{format("%0#{MAX_DECIMALS}d", fraction).sub(/0+\z/, "")}"
+        end
+    end
+  end
+end

data/lib/audioproxy/rails/blob_resolver.rb

@@ -0,0 +1,174 @@
+require "pathname"
+require "audioproxy"
+
+module Audioproxy
+  # Raised when a blob lives on a storage service this gem cannot express as a
+  # proxy source string. Carries the way forward, because the person reading it
+  # is the demand signal for the upstream slice that would fix it (D4).
+  class UnsupportedServiceError < StandardError; end
+
+  # Raised when an attachment has no blob behind it. Deliberately its own class:
+  # "you attached nothing" and "your storage service is unsupported" are
+  # different problems with different fixes.
+  class UnattachedError < StandardError; end
+
+  module Rails
+    # Turns ActiveStorage objects into the source strings the proxy speaks.
+    # Registered with the core by the railtie; the core itself never names an
+    # ActiveStorage constant (D5).
+    module BlobResolver
+      # Dispatch is on the blob's *service class*, never on the configured
+      # service name — :amazon and :local are labels an app picks, and an app
+      # may well call its S3 service :local (D1).
+      #
+      # Matched by class name rather than by constant, because naming
+      # ActiveStorage::Service::S3Service here would load its file, and that
+      # file requires aws-sdk-s3 — a gem an app storing on disk has no reason to
+      # bundle. Ancestor names, so an app's own subclass of a supported service
+      # resolves the way its parent does.
+      #
+      # A Mirror service is not in this table and is not unwrapped to its
+      # primary (non-goal): it raises, naming the mirror, so the operator makes
+      # the choice of which service to point at rather than the gem guessing.
+      SERVICES = {
+        "ActiveStorage::Service::S3Service" => :s3,
+        "ActiveStorage::Service::DiskService" => :disk
+      }.freeze
+
+      SUPPORTED = "S3 and Disk".freeze
+
+      class << self
+        def call(source)
+          blob = unwrap(source)
+          service = blob.service
+
+          case kind_of_service(service)
+          when :s3   then "s3://#{bucket_for(service)}/#{blob.key}"
+          when :disk then "local://#{DiskLayout.relative_path_for(blob.key)}"
+          else
+            raise UnsupportedServiceError, unsupported_message(service)
+          end
+        end
+
+        private
+          def unwrap(source)
+            case source
+            when ::ActiveStorage::Blob
+              source
+            when ::ActiveStorage::Attachment
+              source.blob || raise(UnattachedError, "#{describe(source)} has no blob")
+            when ::ActiveStorage::Attached::One
+              source.blob || raise(UnattachedError, "nothing is attached to #{describe(source)}")
+            else
+              raise ArgumentError,
+                "source must be a String, an ActiveStorage::Blob, or an attachment, got #{source.class}"
+            end
+          end
+
+          # Both an Attachment and an Attached::One know the record and the
+          # attachment name, which is the only part of the error a caller can
+          # act on: it says *which* attachment was empty.
+          def describe(source)
+            "#{source.record.class}##{source.name}"
+          rescue NoMethodError
+            source.class.name
+          end
+
+          def kind_of_service(service)
+            service.class.ancestors.each do |ancestor|
+              kind = SERVICES[ancestor.name]
+              return kind if kind
+            end
+
+            nil
+          end
+
+          # service.bucket is an Aws::S3::Bucket the service builds from its own
+          # configuration; its #name is the bucket string. The one place this
+          # accessor chain is spelled out, so an aws-sdk change lands here.
+          def bucket_for(service)
+            name = String.try_convert(service.bucket.name)
+
+            # ConfigurationError, not UnsupportedServiceError: S3 *is* supported,
+            # and telling someone their S3 service is unsupported because its
+            # bucket is unset sends them to fix the wrong thing.
+            if name.nil? || name.empty?
+              raise ConfigurationError,
+                "the S3 service behind this blob reports no bucket name; set a bucket on the " \
+                "#{service.class} in config/storage.yml"
+            end
+
+            name
+          end
+
+          def unsupported_message(service)
+            "Audioproxy cannot resolve blobs on #{service.class}; it supports #{SUPPORTED} services. " \
+            "Serve this blob through ActiveStorage's rails_storage_proxy mode (which answers 200 " \
+            "directly instead of redirecting) behind an https:// source on the proxy — that source " \
+            "backend is parked upstream on demand, and this error is the demand."
+          end
+      end
+
+      # The Disk service hides its layout behind DiskService#path_for: a file
+      # for key "wxyz9876" lives at {root}/wx/yz/wxyz9876, under two
+      # subdirectories hashed out of the key itself. The proxy is handed the
+      # path relative to its own AP_LOCAL_ROOT, so the gem has to reproduce that
+      # rule — which makes it the one piece of private-ish Rails API this gem
+      # depends on, and the reason it lives alone in a module with a contract
+      # test against the real DiskService (D3).
+      module DiskLayout
+        class << self
+          def relative_path_for(key)
+            string = String.try_convert(key)
+
+            if string.nil? || string.empty?
+              raise ArgumentError, "an ActiveStorage blob key must be a non-empty String, got #{key.inspect}"
+            end
+
+            reject_unsafe(string)
+
+            # folder_for can produce an empty middle segment ("ab" gives "ab/"),
+            # and a key may carry its own separators. DiskService never sees
+            # either, because it hands the join to File.expand_path, which
+            # collapses them; reproducing the layout means reproducing that
+            # normalization too, or a key like "ab" resolves to "ab//ab" here
+            # and "ab/ab" on disk. cleanpath is the collapse without expand_path's
+            # trip through the actual filesystem root.
+            Pathname.new(File.join(folder_for(string), string)).cleanpath.to_s.delete_prefix("/")
+          end
+
+          private
+            # Mirrors DiskService#folder_for exactly.
+            def folder_for(key)
+              [ key[0..1], key[2..3] ].join("/")
+            end
+
+            # DiskService#path_for rejects these before touching the filesystem
+            # and calls it defense in depth. The same keys have to be rejected
+            # here, and for a sharper reason: this side does not touch a
+            # filesystem at all, so nothing downstream would catch them. A key
+            # of "../evil" would otherwise resolve to local://..//e/../evil and
+            # send the proxy climbing out of its AP_LOCAL_ROOT — a valid-looking
+            # URL for a file that is not the blob, which is the one thing this
+            # gem may not emit.
+            def reject_unsafe(key)
+              if key.include?("\0")
+                raise ArgumentError, "an ActiveStorage blob key must not contain null bytes, got #{key.inspect}"
+              end
+
+              traversal = begin
+                key.split("/").intersect?(%w[. ..])
+              rescue Encoding::CompatibilityError
+                raise ArgumentError, "an ActiveStorage blob key must be a valid, comparable String, got #{key.inspect}"
+              end
+
+              if traversal
+                raise ArgumentError,
+                  "an ActiveStorage blob key must not contain . or .. path segments, got #{key.inspect}"
+              end
+            end
+        end
+      end
+    end
+  end
+end

data/lib/audioproxy/rails/helpers.rb

@@ -0,0 +1,66 @@
+require "audioproxy"
+
+module Audioproxy
+  module Rails
+    # Mixed into ActionView by the railtie. Thin on purpose: URL construction is
+    # the core's job, and these only carry it into views.
+    module Helpers
+      # Every option goes through to Audioproxy.url_for untouched, so views and
+      # jobs share one vocabulary.
+      def audioproxy_url(source, **options)
+        Audioproxy.url_for(source, **options)
+      end
+
+      # The html: bucket is the seam between proxy options and tag attributes
+      # (D4). Without it, proxy option keys and HTML attribute names share one
+      # namespace, and a typoed option lands silently on the <audio> element
+      # instead of raising.
+      def audioproxy_audio_tag(source, html: {}, **options)
+        unless html.is_a?(Hash)
+          raise ArgumentError, "audioproxy_audio_tag html: must be a Hash of tag attributes, got #{html.class}"
+        end
+
+        audio_tag(audioproxy_url(source, **options), **html)
+      end
+
+      # `as` is supplied rather than inferred: ActionView reads it off the
+      # source's file extension, and a proxy URL ends in an encoded source
+      # segment that has none, so the inference always fails here. A preload
+      # with no `as` has no fetch destination and browsers decline to act on it.
+      #
+      # No crossorigin, matching what audioproxy_audio_tag emits. A preload
+      # whose crossorigin disagrees with the element consuming it downloads the
+      # whole variant twice; a caller who sets one on the tag sets the same one
+      # here.
+      def audioproxy_preload_link_tag(source, html: {}, **options)
+        unless html.is_a?(Hash)
+          raise ArgumentError, "audioproxy_preload_link_tag html: must be a Hash of tag attributes, got #{html.class}"
+        end
+
+        attributes = { as: "audio" }.merge(html.symbolize_keys)
+
+        # A blank `as` is not an override, it is the destination-less tag this
+        # helper exists to prevent: ActionView falls through to its extension
+        # inference, which has nothing to work with, and the attribute is
+        # dropped entirely.
+        if attributes[:as].blank?
+          raise ArgumentError,
+            "audioproxy_preload_link_tag as: must name a fetch destination, got #{attributes[:as].inspect} " \
+            "(a rel=preload without one is ignored by browsers; pass as: \"audio\" or omit it)"
+        end
+
+        # ActionView renders crossorigin: true as "anonymous" here and audio_tag
+        # renders it as "true", so the pair disagrees and the browser fetches the
+        # variant twice — the one failure this helper's crossorigin default (D3)
+        # exists to avoid.
+        if attributes[:crossorigin] == true
+          raise ArgumentError,
+            "audioproxy_preload_link_tag crossorigin: must be a String, got true " \
+            "(it would render as \"anonymous\" here and \"true\" on the audio tag, fetching the variant twice)"
+        end
+
+        preload_link_tag(audioproxy_url(source, **options), attributes)
+      end
+    end
+  end
+end

data/lib/audioproxy/rails/railtie.rb

@@ -0,0 +1,163 @@
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/hash/keys"
+require "audioproxy/rails/helpers"
+
+module Audioproxy
+  module Rails
+    # Wires an app's configuration and view helpers. Not an engine: there are no
+    # routes, views or migrations to mount.
+    class Railtie < ::Rails::Railtie
+      # Attribute -> environment variable. The names are the proxy's own, so a
+      # dev docker-compose can feed the app and the proxy from one env file
+      # (D2). AP_ALLOW_INSECURE maps to +unsigned+, which is only the *client's*
+      # flag — the proxy enforces its own independently.
+      ENV_VARIABLES = {
+        endpoint: "AP_ENDPOINT",
+        key: "AP_KEY",
+        salt: "AP_SALT",
+        unsigned: "AP_ALLOW_INSECURE"
+      }.freeze
+
+      # The literals Go's strconv.ParseBool accepts, which is what the proxy
+      # parses AP_ALLOW_INSECURE with. Deliberately *not* ActiveModel's boolean
+      # cast: that reads every unrecognized string as true, so a stray
+      # AP_ALLOW_INSECURE=flase would quietly ship unsigned URLs.
+      TRUE_VALUES = %w[1 t true].freeze
+      FALSE_VALUES = %w[0 f false].freeze
+
+      initializer "audioproxy.config" do
+        Railtie.apply_configuration(
+          Audioproxy.config,
+          credentials: ::Rails.application.credentials.audioproxy,
+          env: ENV
+        )
+      end
+
+      initializer "audioproxy.helpers" do
+        ActiveSupport.on_load(:action_view) { include Audioproxy::Rails::Helpers }
+      end
+
+      # Teaches the core to accept blobs and attachments. ActiveStorage ships no
+      # load hook to hang this on, so it is a plain initializer guarded on the
+      # constant: railties are all loaded before any initializer runs, so an app
+      # that has ActiveStorage has it defined by now, and an app that dropped
+      # active_storage/engine from its requires never registers a resolver and
+      # keeps the core's plain "source must be a String".
+      #
+      # Requiring here rather than at the top of the file keeps the resolver —
+      # and its ActiveStorage constants — out of the load path of apps without
+      # it. The file itself names no service class, so nothing is loaded that
+      # would drag in aws-sdk-s3.
+      initializer "audioproxy.active_storage" do
+        if defined?(::ActiveStorage)
+          require "audioproxy/rails/blob_resolver"
+          Audioproxy.register_source_resolver(Audioproxy::Rails::BlobResolver)
+        end
+      end
+
+      class << self
+        # Sources each attribute independently: credentials first, ENV where
+        # credentials are silent, nothing at all where both are. Absent
+        # configuration is not an error here — a signed +url_for+ later raises
+        # the core's ConfigurationError, while an app running unsigned in
+        # development never needs a key (D3). Validating at boot would break
+        # `assets:precompile` and friends in apps that never generate a URL.
+        #
+        # Runs in a railtie initializer, so an app's own
+        # `config/initializers/*.rb` gets the last word for free.
+        def apply_configuration(config, credentials:, env:)
+          credentials = normalize_credentials(credentials)
+
+          ENV_VARIABLES.each do |attribute, variable|
+            value = credentials[attribute]
+            source = :credentials
+
+            if value.nil?
+              # Blank is absent: an env file that carries AP_KEY= with nothing
+              # after it should fall through, not hand Config an empty string.
+              value = env[variable].presence
+              source = variable
+            end
+
+            next if value.nil?
+
+            value = coerce_boolean(value, attribute, source) if attribute == :unsigned
+            config.public_send(:"#{attribute}=", value)
+          end
+
+          config
+        end
+
+        private
+          # Credentials reach us deep-symbolized in current Rails, but a stub or
+          # an older shape can hand over strings; normalizing in one place is
+          # what keeps the rest of this indifferent.
+          #
+          # An unrecognized key under `audioproxy:` raises, the same as in
+          # default_options. It is tempting to be permissive here on the grounds
+          # that a typo simply leaves a setting unconfigured and the core then
+          # raises at url_for — true of endpoint, key and salt, whose default is
+          # nil. It is false of unsigned, whose default is a working value:
+          # `unsinged: true` leaves unsigned at false and emits a signed URL
+          # where the insecure segment was meant. That is a valid-looking URL
+          # for the wrong variant, which is the one thing this gem may not do.
+          def normalize_credentials(credentials)
+            return {} if credentials.nil?
+
+            # Converts rather than type-checks, because credentials arrive as
+            # an OrderedOptions. Array is excluded by hand: it answers to to_h
+            # too, and letting one through would raise TypeError from inside
+            # each_key below or, for [], silently configure nothing.
+            hash = credentials.to_h if credentials.respond_to?(:to_h) && !credentials.is_a?(Array)
+
+            unless hash.is_a?(Hash)
+              raise ArgumentError,
+                "Audioproxy credentials must be a Hash of endpoint/key/salt/unsigned, got #{credentials.class}"
+            end
+
+            hash.each_key do |key|
+              unless key.is_a?(String) || key.is_a?(Symbol)
+                raise ArgumentError, "Audioproxy credentials keys must be Strings or Symbols, got #{key.class}"
+              end
+            end
+
+            duplicate = hash.keys.group_by(&:to_sym).find { |_, spellings| spellings.size > 1 }
+            if duplicate
+              key, spellings = duplicate
+              raise ArgumentError,
+                "Audioproxy credentials give #{key} twice, as " \
+                "#{spellings.map(&:inspect).join(" and ")}; each setting takes one spelling"
+            end
+
+            normalized = hash.symbolize_keys
+
+            unless (unknown = normalized.keys - ENV_VARIABLES.keys).empty?
+              raise ArgumentError,
+                "unknown Audioproxy credential #{unknown.first.inspect} under audioproxy:; " \
+                "known keys are #{ENV_VARIABLES.keys.join(", ")}"
+            end
+
+            normalized
+          end
+
+          def coerce_boolean(value, attribute, source)
+            return value if value == true || value == false
+
+            # to_s, not String.try_convert: YAML reads `unsigned: 1` as an
+            # Integer, and try_convert would reject it with a message listing 1
+            # among the accepted literals. The same value spelled in the
+            # environment is a String and is accepted, so rejecting it here
+            # would make the two sources disagree over one written character.
+            case value.to_s.downcase
+            when *TRUE_VALUES then true
+            when *FALSE_VALUES then false
+            else
+              raise ArgumentError,
+                "Audioproxy #{attribute} from #{source} must be one of " \
+                "#{(TRUE_VALUES + FALSE_VALUES).join(", ")} (or a YAML boolean), got #{value.inspect}"
+            end
+          end
+      end
+    end
+  end
+end

data/lib/audioproxy/rails.rb

@@ -0,0 +1,9 @@
+require "audioproxy"
+
+module Audioproxy
+  # Rails integration layer. Loaded by Bundler under the gem name
+  # "audioproxy-rails"; the railtie itself is required from lib/audioproxy.rb
+  # whenever Rails is present.
+  module Rails
+  end
+end