audioproxy-rails 0.1.0

data/lib/audioproxy/signer.rb

@@ -0,0 +1,40 @@
+require "base64"
+require "openssl"
+
+module Audioproxy
+  # Signature building — the one piece that must stay liftable into a standalone
+  # gem. It therefore depends on stdlib and base64 only: no ActiveSupport, no
+  # Rails, and nothing else in this gem. Everything it needs arrives through the
+  # constructor, so extracting it is a `git mv` plus a gemspec, not a rewrite.
+  #
+  # Byte contract, mirroring the proxy's reference signer:
+  #
+  #   base64url(HMAC-SHA256(key, salt ‖ rest_of_path))   — unpadded
+  #
+  # where key and salt are the decoded binary values and +rest_of_path+ is the
+  # exact byte sequence after the signature segment, leading "/" included.
+  class Signer
+    DIGEST = "SHA256".freeze
+
+    attr_reader :key, :salt
+
+    def initialize(key:, salt:)
+      @key = key
+      @salt = salt
+    end
+
+    def sign(rest_of_path)
+      unless rest_of_path.start_with?("/")
+        raise ArgumentError, "rest_of_path must begin with '/' to be verifiable at the proxy, got #{rest_of_path.inspect}"
+      end
+
+      # .b so a non-ASCII path cannot raise Encoding::CompatibilityError against
+      # the binary salt.
+      digest = OpenSSL::HMAC.digest(DIGEST, key, salt + rest_of_path.b)
+
+      # Unpadded: the proxy accepts both spellings, but emitting exactly one
+      # keeps URLs and CDN cache keys stable.
+      Base64.urlsafe_encode64(digest, padding: false)
+    end
+  end
+end

data/lib/audioproxy/url_builder.rb

@@ -0,0 +1,141 @@
+require "base64"
+require "active_support/core_ext/object/blank"
+
+module Audioproxy
+  # Assembles +{endpoint}/{signature}/{options}/{source}+ URLs, byte-compatible
+  # with the proxy's reference signer.
+  #
+  # The signature covers everything after itself (leading +/+ included), so an
+  # endpoint path prefix cannot disturb it.
+  #
+  # This is the Rails-facing half and may use ActiveSupport freely. The HMAC
+  # itself lives in Audioproxy::Signer, which may not — see D1.
+  class UrlBuilder
+    # Literal signature segment the proxy accepts under AP_ALLOW_INSECURE.
+    INSECURE_SEGMENT = "insecure".freeze
+
+    # The proxy's path grammar has no optionless form, so the minimal
+    # always-valid options string is its default format spelled out.
+    FALLBACK_OPTIONS = "f:mp3".freeze
+
+    attr_reader :config
+
+    def initialize(config = Audioproxy.config)
+      @config = config
+    end
+
+    # Typed option keys (+f:+, +br:+, +t:+ …) arrive as keyword arguments and
+    # render in the order they were written. Each is also accepted as its
+    # spelled-out alias (+format:+, +bitrate:+, +trim:+ …), resolved to the
+    # canonical key before anything is rendered. A keyword that is neither a
+    # builder option nor a proxy option key raises rather than being ignored.
+    def url_for(source, raw: nil, endpoint: nil, unsigned: nil, **typed)
+      base = endpoint.nil? ? config.endpoint : Config.new.tap { |c| c.endpoint = endpoint }.endpoint
+      raise ConfigurationError, "Audioproxy has no endpoint configured" if base.nil?
+
+      rest_of_path = "/#{options_segment(raw, typed)}/#{source_segment(source)}"
+      insecure = unsigned.nil? ? config.unsigned : unsigned
+
+      "#{base}/#{insecure ? INSECURE_SEGMENT : sign(rest_of_path)}#{rest_of_path}"
+    end
+
+    # Signs via Audioproxy::Signer. Whether the config *can* sign is this
+    # class's problem; how the bytes are produced is the signer's.
+    def sign(rest_of_path)
+      missing = [ (:key unless config.key), (:salt unless config.salt) ].compact
+      unless missing.empty?
+        raise ConfigurationError, "Audioproxy cannot sign a URL: #{missing.join(" and ")} not configured (set them, or use unsigned: true)"
+      end
+
+      Signer.new(key: config.key, salt: config.salt).sign(rest_of_path)
+    end
+
+    private
+      # Precedence, per D4: an explicit per-call source of options replaces the
+      # configured defaults entirely; typed per-call keys merge over typed
+      # defaults key-by-key, keeping the defaults' position and appending the
+      # rest in caller order.
+      def options_segment(raw, typed)
+        unless raw.nil? || typed.empty?
+          raise ArgumentError,
+            "Audioproxy url_for takes either raw: or typed option keys, not both " \
+            "(got raw: and #{typed.keys.join(", ")})"
+        end
+
+        return raw_segment(raw) unless raw.nil?
+
+        # Onto the canonical keys before anything else, so that a default
+        # written as bitrate: and a per-call br: are one key the merge
+        # overrides rather than two segments that both render (D3). Defaults
+        # were resolved at assignment.
+        typed = Options.resolve(typed)
+
+        defaults = config.default_options
+        typed_defaults = defaults.except(:raw)
+
+        return Options.render(typed_defaults.merge(typed)) unless typed.empty?
+        return raw_segment(defaults[:raw]) unless defaults[:raw].nil?
+        return Options.render(typed_defaults) unless typed_defaults.empty?
+
+        FALLBACK_OPTIONS
+      end
+
+      def raw_segment(raw)
+        segment = String.try_convert(raw)
+        if segment.nil?
+          raise ArgumentError, "raw options must be a String, got #{raw.class}"
+        end
+
+        return FALLBACK_OPTIONS if segment.blank?
+        segment = segment.strip
+
+        # The builder supplies the separators. A bracketing slash would sign a
+        # path with an empty segment, which the proxy rejects — and it would do
+        # so at request time, nowhere near this call.
+        if segment.start_with?("/") || segment.end_with?("/")
+          raise ArgumentError, "raw options must not begin or end with '/', got #{segment.inspect}"
+        end
+
+        segment
+      end
+
+      # The proxy accepts padded and unpadded enc/ payloads; emitting exactly
+      # one spelling keeps URLs (and CDN cache keys) stable.
+      def source_segment(source)
+        string = String.try_convert(source) || resolved_source(source)
+        if string.empty?
+          raise ArgumentError, "source must not be empty"
+        end
+
+        "enc/#{base64url(string)}"
+      end
+
+      # Non-String sources go through the registered resolver, or nowhere. The
+      # core names no ActiveStorage constant; it only knows that something else
+      # may have claimed the job of turning objects into source strings.
+      def resolved_source(source)
+        resolver = Audioproxy.source_resolver
+        if resolver.nil?
+          raise ArgumentError,
+            "source must be a String, got #{source.class} (ActiveStorage blobs " \
+            "and attachments resolve only where the Rails integration is loaded)"
+        end
+
+        resolved = resolver.call(source)
+        string = String.try_convert(resolved)
+        if string.nil?
+          raise ArgumentError,
+            "the registered Audioproxy source resolver returned #{resolved.class} " \
+            "for #{source.class}, not a source String"
+        end
+
+        string
+      end
+
+      # Unpadded, per D3/D4: the proxy accepts both spellings, but emitting one
+      # keeps URLs and CDN cache keys stable.
+      def base64url(bytes)
+        Base64.urlsafe_encode64(bytes, padding: false)
+      end
+  end
+end

data/lib/audioproxy/version.rb

@@ -0,0 +1,3 @@
+module Audioproxy
+  VERSION = "0.1.0"
+end

data/lib/audioproxy.rb

@@ -0,0 +1,50 @@
+require "audioproxy/version"
+require "audioproxy/signer"
+require "audioproxy/options"
+require "audioproxy/config"
+require "audioproxy/url_builder"
+
+# Nothing in this namespace may reference Rails constants; ActiveSupport is
+# fair game except inside Audioproxy::Signer, which stays liftable. See D1.
+module Audioproxy
+  class << self
+    attr_writer :config
+
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    # Single public entry point: usable from jobs, mailers and serializers of
+    # any Ruby program, Rails or not.
+    def url_for(source, **options)
+      UrlBuilder.new(config).url_for(source, **options)
+    end
+
+    # Anything that is not already a source String is handed to this resolver.
+    # The Rails layer registers one for ActiveStorage objects; the core stays
+    # ignorant of what a blob is, which is what keeps +url_for+ usable with no
+    # Rails loaded at all (D5).
+    attr_reader :source_resolver
+
+    def register_source_resolver(resolver = nil, &block)
+      resolver ||= block
+
+      unless resolver.respond_to?(:call)
+        raise ArgumentError, "an Audioproxy source resolver must respond to #call, got #{resolver.class}"
+      end
+
+      @source_resolver = resolver
+    end
+
+    def reset_source_resolver
+      @source_resolver = nil
+    end
+  end
+end
+
+require "audioproxy/rails/railtie" if defined?(::Rails::Railtie)

data/lib/tasks/audioproxy/rails_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :audioproxy_rails do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: audioproxy-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Julian Rubisch
+bindir: bin
+cert_chain: []
+date: 2026-08-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3.1
+description: Builds signed, option-carrying URLs for the audioproxy media server,
+  with a Rails integration layer on top of a Rails-free core.
+email:
+- julian@julianrubisch.at
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- lib/audioproxy.rb
+- lib/audioproxy/config.rb
+- lib/audioproxy/options.rb
+- lib/audioproxy/rails.rb
+- lib/audioproxy/rails/blob_resolver.rb
+- lib/audioproxy/rails/helpers.rb
+- lib/audioproxy/rails/railtie.rb
+- lib/audioproxy/signer.rb
+- lib/audioproxy/url_builder.rb
+- lib/audioproxy/version.rb
+- lib/tasks/audioproxy/rails_tasks.rake
+homepage: https://github.com/audioproxy/audioproxy-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/audioproxy/audioproxy-rails
+  bug_tracker_uri: https://github.com/audioproxy/audioproxy-rails/issues
+  changelog_uri: https://github.com/audioproxy/audioproxy-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Signed variant URLs for the audioproxy server.
+test_files: []