audioproxy-rails 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7ae5b13fb6a5adc46eb6e975cdc682cf27244c316624891072a31f2447a1257
-  data.tar.gz: fe648c6c0cc0552d30dfd4cdcdf7878ebf68fdb7961c7363b6bf2b62725c50bf
+  metadata.gz: 4de1340b2094f8154a8c5f02b45c5409fc7b0468967cbe9bf0bda9d836264f4d
+  data.tar.gz: 6a69838fa47da950bdd6a80880b31e2f2a75dad76991cfa52599dc01ea92925a
 SHA512:
-  metadata.gz: 2c46a5ef917dca8990e4d565cd14b283a0c0592b36ca95e4cd6e81cb4fe06d2bd3ac823353e22efb5486a0d41749f0631c32faf45f4fef18b3866dba182fedfa
-  data.tar.gz: 878b41e27ab71a8b4e69cc8d6d0f27c1a5d79e011307508f32d8a589e99397710a2bbca8fa71df979d42c09560690914fd5f8f188332ebea096a1c03c7402097
+  metadata.gz: 0c86091fd6f663dab0785223d5cc9a19d4396d04243363aa8d2ec9ddb94d631eb6c626319c8cd7ca40f0927c14abfdf436e498a9eeecaf5fb00e63e79b424a07
+  data.tar.gz: 966e160dfe9a51c1e3e47c0c6bcad259a7a4a829242917fbe2428d9f7f1c03f00132c5f753a1b1bceac06e1933689d3a9934f4e7cebdf4e4a7689fe9ebffc777

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.3.0
+
+* Probe metadata URLs. `Audioproxy.info_url(source)` and the `audioproxy_info_url` view helper
+  build the proxy's `/info` URL, which returns duration, sample rate, channels and tags as JSON. The
+  proxy's `/info` has no options segment, so `info_url` raises for any option or `raw:`, and ignores
+  `config.default_options` and `config.expires_in`. Info URLs therefore never expire, even when
+  every other URL your app builds does.
+
+* Waveform peaks URLs. `Audioproxy.peaks_url(source, **options)` and the `audioproxy_peaks_url`
+  view helper build a variant URL with `f:peaks` fixed. They accept only the options that change a
+  waveform (`pts`, `pk_fmt`, `pk_bits`, `ch`, `t`, `fade`, `gain`, `norm`, `dl`, `cb`) and raise on
+  the rest, since the proxy refuses encoding options on peaks. Of the configured defaults, only
+  `t`, `fade`, `gain`, `norm` and `cb` carry over, so the waveform follows normalized audio while an
+  audio default such as `br: 96` or `ch: 2` never reaches a peaks request.
+
+* `pk_bits` option, aliased as `peak_bits`: the width of each peaks value, 8 or 16. peaks.js reads
+  only 8-bit data, so a peaks.js client asks for `pk_bits: 8`. Requires audioproxy 0.8.0 or newer;
+  older proxies answer `pk_bits:` with a `422`.
+
+* `url_for` output is unchanged, byte for byte.
+
+## 0.2.0
+
+* Expiring URLs. `url_for` and every view helper accept `expires_in:` (a duration or Integer
+  seconds from now) and `expires_at:` (the instant itself), mutually exclusive, rendering the
+  proxy's `exp:` option. `config.expires_in` sets a global default; a per-call `expires_in: nil`
+  opts one URL out of it.
+
+  Because `exp` is a request option on the proxy rather than a variant option, it is signed but
+  excluded from the cache key: minting a fresh short-lived URL on every render costs no extra
+  render and no extra cached variant at the origin.
+
+  Every input that would produce a valid-looking URL the proxy refuses raises at the call site
+  instead: both keywords together, a non-positive window, an `expires_at` at or before now, a
+  fractional duration, a millisecond timestamp, a `Date`, and `exp:` written as a plain option key
+  or in `default_options`.
+
+  Requires audioproxy 0.6.0 or newer, the release that added the `exp` option. Older proxies
+  answer `exp:` with a `422`. Every other feature in this gem still works against 0.5.0.
+
+* `Audioproxy::Signer` is unchanged, and so is the isolation test that pins its extraction seam:
+  `exp` is ordinary path bytes to the signer.
+
 ## 0.1.0
 
 First release.

data/README.md

@@ -10,7 +10,9 @@ Full Rails is a development dependency only. `require "audioproxy"` works in a p
 
 ## Status
 
-Core signing and typed options work, in both the proxy's short spellings and their aliases, as do the Railtie's credentials/ENV wiring, the view helpers — URL, `<audio>` tag and preload hint — and ActiveStorage resolution for the S3 and Disk services. Blobs on any other service raise; see [ActiveStorage](#activestorage) for what to do about that.
+Core signing and typed options work, in both the proxy's short spellings and their aliases, as do [`info` and peaks URLs](#metadata-and-waveforms), the Railtie's credentials/ENV wiring, the view helpers — URL, `<audio>` tag and preload hint — and ActiveStorage resolution for the S3 and Disk services. Blobs on any other service raise; see [ActiveStorage](#activestorage) for what to do about that.
+
+[Expiring URLs](#expiring-urls) work too, against [audioproxy 0.6.0 or newer](#minimum-proxy-version), and `pk_bits` needs 0.8.0. Everything here is verified against the proxy's published signature vectors and its source, and CI also asks a running proxy to accept signed, unsigned, typed-option and expiring URLs. `info` and peaks URLs are not in that round-trip yet.
 
 ## Installation
 
@@ -63,17 +65,24 @@ Where to go from here:
 ```ruby
 Audioproxy.configure do |config|
   config.endpoint = "https://audio.example.com"   # absolute http(s) URL, path prefix allowed
-  config.key      = ENV["AUDIOPROXY_KEY"]         # hex string, decoded at assignment
-  config.salt     = ENV["AUDIOPROXY_SALT"]        # hex string, decoded at assignment
+  config.key      = ENV["AP_KEY"]                 # hex string, decoded at assignment
+  config.salt     = ENV["AP_SALT"]                # hex string, decoded at assignment
 end
 ```
 
+Writing this out is optional. Under Rails the railtie already reads `audioproxy:` from credentials
+and `AP_ENDPOINT`, `AP_KEY`, `AP_SALT` and `AP_ALLOW_INSECURE` from the environment, so an app that
+uses either needs no initializer at all; see [ENV parity with the proxy](#env-parity-with-the-proxy)
+and [Rails](#rails). Configure by hand when you want to override those, or when there is no Rails.
+
 `key` and `salt` are hex strings, validated eagerly: a typo raises `ArgumentError` at boot rather than in a mailer six hours later. The endpoint must be an absolute `http`/`https` URL. A path prefix (`https://cdn.example.com/audio`, for a CDN routing that prefix to the proxy) is supported and does not disturb signing, because the signature covers only the path after the signature segment. Userinfo, a query and a fragment are rejected: a base URL is scheme, host and optional path prefix, and `https://user:pass@host` would put credentials into every URL you generate.
 
 The gem is deliberately strict about input, because the alternative is not an exception but a 403 from the proxy at request time, far from the call that caused it. A `nil` or non-String source, a `default_options` value that is not a Hash, an unrecognized option key, and a `raw:` string bracketed by `/` all raise.
 
 In development, `config.unsigned = true` emits the literal `insecure` signature segment instead of an HMAC, matching the proxy's `AP_ALLOW_INSECURE` mode. No key or salt is needed in that mode.
 
+`config.default_options` sets options applied to every URL, and `config.expires_in` sets a global expiry; both are covered in [Options](#options) and [Expiring URLs](#expiring-urls).
+
 ## Generating URLs
 
 ```ruby
@@ -83,6 +92,24 @@ Audioproxy.url_for("s3://masters/2026/piece-final.wav", raw: "f:opus/br:96")
 
 The result is `{endpoint}/{signature}/{options}/{source}`. The source is always emitted in `enc/` form (unpadded base64url), so spaces, nested URLs, and already-escaped bytes need no special handling.
 
+### Metadata and waveforms
+
+The proxy answers two more things a player needs around playback, and each has its own entry point:
+
+```ruby
+Audioproxy.info_url("s3://masters/piece.wav")
+# => "https://audio.example.com/…/info/enc/czM6Ly9tYXN0ZXJz…"
+
+Audioproxy.peaks_url("s3://masters/piece.wav", pts: 800, pk_bits: 8)
+# => "https://audio.example.com/…/f:peaks/pts:800/pk_bits:8/enc/czM6Ly9tYXN0ZXJz…"
+```
+
+`info_url` builds the proxy's probe-metadata URL: duration, sample rate, channels and tags as JSON, which is how a player learns the duration it needs before it can write a sensible `t:`. It takes **no options**, because the proxy answers any options segment alongside `info` with a `422`. So it raises for a typed key or `raw:`, and it ignores `config.default_options`, the one entry point that does. It also ignores `config.expires_in` and raises for a per-call `expires_in:` or `expires_at:`, since `/info` has nowhere to carry `exp`: **info URLs never expire, even when every other URL your app builds does.** The proxy treats them as operator-facing rather than something handed to listeners, so keep them that way. Info responses are cached for an hour and are deliberately not `immutable`, because a re-upload changes the answer; do not memoize a response forever.
+
+`peaks_url` is a variant URL with the format fixed to `f:peaks`. It accepts only the options that change a waveform: `pts`, `pk_fmt`, `pk_bits`, `ch`, `t`, `fade`, `gain`, `norm`, `dl` and `cb`, in either spelling. Anything else raises, naming that list. The proxy refuses `br`, `q`, `sr` and `bd` on a peaks request, and an option it merely ignored would still enter its cache key and buy a second render of identical peaks. `raw:` is refused too, because a pre-rendered string cannot be checked; `url_for(source, raw: "f:peaks/…")` stays the escape hatch.
+
+Only some configured defaults carry over to peaks: `t`, `fade`, `gain` and `norm`, which change the samples, so the waveform matches the audio drawn above it, and the cache buster `cb`. The rest are skipped. `f:opus` or `br:96` would render into a `422`, and `ch` and `dl` mean something else as audio defaults: `ch: 2` is stereo output for audio but per-channel pairs for peaks, and an audio filename is the wrong name for peaks JSON. Pass either per call when you want it on the peaks. A `raw:` default is skipped entirely. Expiry works exactly as it does for `url_for`. The gem does not add `ch:1` for you even though peaks default to mono; the proxy fills in its own defaults.
+
 ## Options
 
 Describe the variant with the proxy's option keys as Ruby keyword arguments, either in the proxy's own short spelling or in the spelled-out alias next to it:
@@ -106,9 +133,12 @@ Audioproxy.url_for("s3://masters/piece.wav", f: :opus, br: 96, t: [12.5, 30])
 | `norm` | `normalize` | `norm: [:ebu, -16, -1.5, 11]` | loudness normalization: mode, then I, TP, LRA |
 | `pts` | `peak_count` | `pts: 800` | peak points, for waveform output |
 | `pk_fmt` | `peak_format` | `pk_fmt: :json` | peaks format |
+| `pk_bits` | `peak_bits` | `pk_bits: 8` | peaks value width, 8 or 16 |
 | `dl` | `download` | `dl: "piece.mp3"` | download filename |
 | `cb` | `cache_buster` | `cb: "v2"` | cache buster |
 
+If the peaks are for [peaks.js](https://github.com/bbc/peaks.js), ask for `pk_bits: 8`: peaks.js only loads 8-bit waveform data, and the proxy's default width is 16. The alias is `peak_bits` rather than `bit_depth`, because `bit_depth` already means `bd`, the sample format of encoded audio.
+
 Segments render in the order you write the keywords. The gem does not sort them and does not materialize defaults; that is the proxy's normalization, and a half-normalization here would only invent a third spelling. If you want URLs to stay stable across a codebase, keep the argument order stable.
 
 `t`, `fade` and `norm` take colon-separated parts, so they take arrays: `t: [12.5, 30]` renders `t:12.5:30`. A single part can be written as a scalar: `t: 12.5` renders `t:12.5`. Symbols and strings render alike, so `f: :opus` and `f: "opus"` are the same URL.
@@ -207,6 +237,70 @@ Audioproxy.url_for("local://a.wav", unsigned: true)
 
 `Audioproxy.url_for` is Rails-free: it works in jobs, mailers, serializers, and plain Ruby scripts.
 
+## Expiring URLs
+
+A signed URL is otherwise an eternal bearer capability: the signature covers the path and nothing else, so a leaked URL works forever and the only revocation is rotating the key, which kills every URL you ever issued. `expires_in:` and `expires_at:` time-box one URL without touching any other.
+
+```ruby
+Audioproxy.url_for(source, format: "opus", expires_in: 1.hour)
+# => ".../f:opus/exp:1767229200/enc/..."
+
+Audioproxy.url_for(source, format: "opus", expires_at: 1.day.from_now)
+```
+
+`expires_in:` takes an ActiveSupport duration or a positive Integer of seconds, added to the current time when the URL is built. `expires_at:` takes a `Time`, `DateTime`, `ActiveSupport::TimeWithZone`, or an Integer unix timestamp, used as the instant itself. They are mutually exclusive. Past the expiry the proxy answers `410 Gone`, checked after the signature and before it touches your storage, so an expired URL costs a render of nothing.
+
+Every view helper forwards both keywords:
+
+```erb
+<%= audioproxy_audio_tag @recording.audio, format: "opus", expires_in: 30.minutes, html: { controls: true } %>
+```
+
+### Rotation is free at the origin
+
+On the proxy's side `exp` is a *request* option: it is signed as part of the path, but excluded from the cache key and from the ffmpeg arguments. Two URLs that differ only in their expiry are one variant and one render, so minting a fresh short-lived URL on every page render costs nothing at the origin. Each user can carry their own URL while all of them share one cached variant.
+
+That guarantee is origin-side only. Two URLs differing in `exp` are still two distinct URLs to a CDN, which stores them separately, so a short expiry on a heavily shared page trades edge cache entries for revocability. That is the trade whichever syntax carries the expiry, not a cost of this spelling.
+
+### A global default
+
+```ruby
+Audioproxy.configure { |c| c.expires_in = 1.hour }
+```
+
+`config.expires_in` is `nil` by default, and `nil` means URLs carry no expiry at all. When it is set, every URL this process builds carries one, measured from each call rather than from boot. A per-call `expires_in:`/`expires_at:` overrides it, and a per-call `expires_in: nil` opts a single URL out:
+
+```ruby
+Audioproxy.url_for(source, expires_in: 5.minutes)   # overrides the default
+Audioproxy.url_for(source, expires_in: nil)         # no expiry on this one
+```
+
+It is a duration rather than an instant on purpose: an absolute timestamp applied process-globally would expire every URL the app will ever mint at the same second. There is no `config.expires_at`, and `exp:` is refused in `default_options` for the same reason.
+
+### What raises, and why
+
+An expiry the proxy will not accept produces a URL that looks perfectly valid and fails at request time, far from the call that built it. So every one of these raises `ArgumentError` at the call site instead:
+
+```ruby
+Audioproxy.url_for(source, expires_in: 1.hour, expires_at: 1.day.from_now)  # both keywords
+Audioproxy.url_for(source, expires_in: 0)                                   # non-positive window
+Audioproxy.url_for(source, expires_at: 1.hour.ago)                          # already dead
+Audioproxy.url_for(source, expires_in: 1.5.seconds)                         # not whole seconds
+Audioproxy.url_for(source, expires_at: 1.hour.from_now.to_i * 1000)         # milliseconds
+Audioproxy.url_for(source, expires_at: Date.tomorrow)                       # local midnight, not an instant
+Audioproxy.url_for(source, exp: 1767229200)                                 # use the keywords
+```
+
+An expiry composes with `raw:` rather than replacing it, since `exp` is not a variant option: `url_for(source, raw: "f:opus/br:96", expires_in: 1.hour)` renders `f:opus/br:96/exp:…`. A `raw:` string that already spells out its own `exp:` raises when an expiry is also in force, because the proxy rejects a duplicated option and, under a global default, that is a failure you never wrote.
+
+### Minimum proxy version
+
+Expiring URLs need **audioproxy 0.6.0 or newer**, the release that added the `exp` option. `0.5.0` and earlier answer `exp:` with a `422 invalid option`. That failure is loud and server-side, so pointing this gem at an older proxy breaks visibly rather than silently ignoring the expiry.
+
+`pk_bits` needs **audioproxy 0.8.0 or newer**, the release that added it. Older proxies answer `pk_bits:` with a `422` for an unknown key.
+
+Every other feature here works against `0.5.0` unchanged. This gem does not version-sniff.
+
 ## Rails
 
 In a Rails app there is nothing to mount and, usually, nothing to write: a railtie reads your configuration and mixes the view helpers into ActionView.
@@ -282,6 +376,8 @@ Nothing is validated at boot. An app with no credentials and no ENV boots fine
 
 The `html:` bucket is not ceremony. Without it, proxy option names and HTML attribute names would share one namespace, and the gem would have to guess which one you meant for any key it did not recognize — so a mistyped `bitrat: 96` would land silently on the `<audio>` element as an attribute and quietly ship the default format instead. With the bucket, the two never mix in either direction: an unknown proxy option raises, and an `html:` entry never reaches the proxy. Proxy options never appear as tag attributes.
 
+`audioproxy_info_url` and `audioproxy_peaks_url` are [`info_url` and `peaks_url`](#metadata-and-waveforms) under view names, as `audioproxy_url` is `url_for`. There are no tag helpers for either: both return JSON (or peaks' binary `.dat`) for a script to fetch, and there is no HTML element to hand them to.
+
 #### Preloading a variant
 
 `audioproxy_preload_link_tag` emits a resource hint for a variant you are about to play. Because the first request for a variant is a render, the hint overlaps that render with page load rather than leaving someone waiting for it after a click:
@@ -378,6 +474,63 @@ It boots the dummy Rails app in `test/dummy` for the integration tests. Style ch
 bin/rubocop
 ```
 
+### Round-trip tests against a real proxy
+
+`bin/test` checks the bytes this gem produces. It cannot check that a real proxy *accepts* them, and
+some things are not expressible as a byte comparison at all: whether an expired URL is refused with
+`410`, and whether the second `exp` names is still served, are questions only a running proxy
+answers.
+
+Those tests live in `test/server/`, and they are skipped unless you tell them where a proxy is. The
+gem does not start one for you — start it yourself:
+
+```bash
+mkdir -p /tmp/audioproxy-fixtures
+
+docker run --rm -d --name audioproxy-test \
+  --platform linux/amd64 \
+  -p 4000:4000 \
+  -e AP_KEY=00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF \
+  -e AP_SALT=FFEEDDCCBBAA99887766554433221100 \
+  -e AP_ALLOW_INSECURE=true \
+  -e AP_LOCAL_ROOT=/srv/audio \
+  -v /tmp/audioproxy-fixtures:/srv/audio \
+  ghcr.io/audioproxy/audioproxy:0.6.0
+```
+
+Then point the suite at it:
+
+```bash
+AUDIOPROXY_PROXY_URL=http://127.0.0.1:4000 bin/test test/server
+```
+
+Drop the path to run everything, unit tests included. Stop it with
+`docker rm -f audioproxy-test` when you are done.
+
+The key and salt above are the published known-answer test vectors — not secrets, and the same ones
+in `test/fixtures/signature_vectors.rb`, so the round-trips exercise the bytes those vectors pin.
+The suite writes a generated WAV into `/tmp/audioproxy-fixtures` (override with
+`AUDIOPROXY_FIXTURE_ROOT`), so there is nothing to fetch and you need no ffmpeg on your side.
+`--platform linux/amd64` is there because the published image is amd64-only; on Apple Silicon it
+runs under emulation, and on an amd64 host the flag does nothing.
+
+A few things worth knowing:
+
+- **`AUDIOPROXY_PROXY_URL` unset means skip; set means fail if nothing answers.** Setting it is a
+  claim that a proxy is there, so an unreachable one is an error rather than a quiet pass. That
+  keeps `bin/test` a fast, Docker-free unit run for anyone who cannot pull an image, without
+  letting a broken round-trip environment look like a green one.
+- **The proxy version is checked, not assumed.** The suite asks `/health` what it is talking to and
+  refuses to run against anything but the pinned release, so a mismatch is a named failure rather
+  than a confusing one.
+- **The pin is advanced by hand, as part of the proxy's release checklist.** A pinned tag nobody
+  advances stops testing anything interesting, and it fails silently — by passing. When the proxy
+  releases, bump `PROXY_VERSION` in `test/support/server_roundtrip.rb` and the image in
+  `.github/workflows/ci.yml`. Forgetting one of the two is caught by the version check above.
+- **In CI the proxy is a service container**, and the round-trip job is **visible but not required**:
+  it goes red on failure, but putting it in branch protection would make every merge depend on ghcr
+  being up, and the unit suite is the real safety net.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/audioproxy/config.rb

@@ -1,6 +1,7 @@
 require "uri"
 require "active_support/core_ext/hash/keys"
 require "audioproxy/options"
+require "audioproxy/expiry"
 
 module Audioproxy
   # Raised when a URL is requested but the configuration cannot produce one the
@@ -18,9 +19,16 @@ module Audioproxy
     # spelled-out aliases, plus the pre-rendered +raw:+ escape hatch. An
     # unrecognized key is a typo, and a typo that is silently dropped emits a
     # valid URL for the wrong variant.
-    OPTION_KEYS = ([ :raw ] + Options::KEYS + Options::ALIASES.values).uniq.freeze
-
-    attr_reader :endpoint, :key, :salt, :default_options
+    #
+    # exp is subtracted deliberately (D1). It is an absolute instant, so a
+    # default would expire every URL the process ever mints at one second, and
+    # it would skip the validation the keywords run. +expires_in+ below is the
+    # default that makes sense.
+    EXPIRY_KEYS = (Options::REQUEST_KEYS + Options::REQUEST_KEYS.filter_map { |key| Options::ALIASES[key] })
+      .uniq.freeze
+    OPTION_KEYS = (([ :raw ] + Options::KEYS + Options::ALIASES.values).uniq - EXPIRY_KEYS).freeze
+
+    attr_reader :endpoint, :key, :salt, :default_options, :expires_in
     attr_accessor :unsigned
 
     def initialize
@@ -29,6 +37,18 @@ module Audioproxy
       @salt = nil
       @unsigned = false
       @default_options = {}
+      @expires_in = nil
+    end
+
+    # How long a URL stays valid, applied to every URL this process builds.
+    # nil — the default — means URLs carry no expiry and remain the eternal
+    # bearer capabilities they have always been.
+    #
+    # A duration rather than an instant, and validated here so a typo fails at
+    # boot rather than in a mailer. A call site overrides it with its own
+    # +expires_in:+/+expires_at:+, or opts one URL out with +expires_in: nil+.
+    def expires_in=(value)
+      @expires_in = value.nil? ? nil : Expiry.seconds(value, source: "config expires_in")
     end
 
     # Full base URL of the proxy: scheme + host, optionally with a path prefix
@@ -128,6 +148,15 @@ module Audioproxy
 
         normalized = value.symbolize_keys
 
+        # Before the generic unknown-key message, which would report exp as a
+        # typo when it is a real option reached a different way (D1).
+        unless (expiry = normalized.keys & EXPIRY_KEYS).empty?
+          raise ArgumentError,
+            "Audioproxy config default_options must not carry #{expiry.first.inspect}: it is an " \
+            "absolute instant, so every URL this process builds would expire at the same second. " \
+            "Set config.expires_in to a duration instead, or pass expires_in:/expires_at: per call"
+        end
+
         # Not assert_valid_keys: its message lists the aliases among the valid
         # keys without saying they are aliases, so a caller who guessed
         # bit_rate: sees :bitrate in a flat list and cannot tell the two
@@ -135,7 +164,7 @@ module Audioproxy
         unless (unknown = normalized.keys - OPTION_KEYS).empty?
           raise ArgumentError,
             "unknown Audioproxy option #{unknown.first.inspect} in default_options; known keys are " \
-            "#{([ :raw ] + Options::KEYS).join(", ")}, each also accepted as its spelled-out alias " \
+            "#{([ :raw ] + Options::KEYS - EXPIRY_KEYS).join(", ")}, each also accepted as its spelled-out alias " \
             "(#{Options::ALIASES[:br]}, #{Options::ALIASES[:sr]}, #{Options::ALIASES[:pk_fmt]}, …)"
         end
 

data/lib/audioproxy/expiry.rb

@@ -0,0 +1,160 @@
+require "date"
+require "active_support/duration"
+require "audioproxy/options"
+
+module Audioproxy
+  # Turns the two Rails-shaped expiry spellings — +expires_in: 1.hour+ and
+  # +expires_at: some_time+ — into the single Integer of unix seconds the
+  # proxy's +exp+ option takes.
+  #
+  # Every method here raises rather than coercing. The proxy answers a URL whose
+  # +exp+ has passed with 410 and one out of bounds with 422, both at request
+  # time and neither anywhere near the call that built it, so an input this
+  # module cannot read exactly is an error at the call site (D5).
+  module Expiry
+    # Sentinel for "this keyword was not passed". nil cannot do the job: it is
+    # the documented per-call opt-out from a configured default (D6).
+    UNSET = Object.new.freeze
+
+    class << self
+      # The +exp+ value for one URL, or nil for no expiry at all. +now+ is
+      # supplied by the caller and read once per URL, so the arithmetic below
+      # and the past-check cannot straddle a second boundary (D4).
+      def timestamp(expires_in:, expires_at:, default_expires_in:, now:)
+        if given?(expires_in) && given?(expires_at)
+          raise ArgumentError,
+            "Audioproxy url_for takes either expires_in: or expires_at:, not both; " \
+            "expires_in: is a window from now, expires_at: is the instant itself"
+        end
+
+        return at(expires_at, now: now) if given?(expires_at)
+        return within(expires_in, now: now, source: "url_for expires_in:") if given?(expires_in)
+        return nil if default_expires_in.nil?
+
+        # Already validated at assignment, so this is arithmetic and nothing
+        # else — but it still goes through the bound check that `within` runs.
+        within(default_expires_in, now: now, source: "config expires_in")
+      end
+
+      # A window of whole positive seconds, as an Integer. Shared by the keyword
+      # and by Config#expires_in= so that a value accepted at boot is exactly a
+      # value accepted per call.
+      def seconds(value, source:)
+        case value
+        # #value is the exact number of seconds the Duration stands for (3600
+        # for 1.hour), and it stays an Integer where the caller wrote one, so a
+        # far-future window does not lose digits to a double on the way past.
+        when ActiveSupport::Duration then whole_seconds(value, value.value, source: source)
+        when Integer then value
+        else
+          raise ArgumentError,
+            "Audioproxy #{source} must be an ActiveSupport::Duration or an Integer of seconds, " \
+            "got #{value.inspect}"
+        end.tap do |seconds|
+          unless seconds.positive?
+            raise ArgumentError,
+              "Audioproxy #{source} must be a positive number of seconds, got #{value.inspect}; " \
+              "a window of #{seconds} mints a URL that is already expired"
+          end
+        end
+      end
+
+      private
+        def given?(value)
+          !value.equal?(UNSET)
+        end
+
+        def within(value, now:, source:)
+          return nil if value.nil?
+
+          window = seconds(value, source: source)
+
+          bounded(now + window, source: source, window: window)
+        end
+
+        def at(value, now:)
+          return nil if value.nil?
+
+          seconds = bounded(unix_seconds(value), source: "url_for expires_at:")
+
+          # The proxy's own check is `now > exp`, so the second exp names is
+          # still served and only a strictly-past value is dead on arrival.
+          # Refusing equality too costs one second and makes the rule statable
+          # as "expires_at: must be in the future" (D5).
+          unless seconds > now
+            raise ArgumentError,
+              "Audioproxy url_for expires_at: must be in the future, got #{value.inspect} " \
+              "(#{seconds}, and it is now #{now}); the proxy would answer that URL with 410"
+          end
+
+          seconds
+        end
+
+        # Time, DateTime and ActiveSupport::TimeWithZone, or an Integer already
+        # in unix seconds.
+        #
+        # is_a? rather than case/when, and the reason is narrower than the one
+        # Options gives for Duration. TimeWithZone overrides is_a? to answer
+        # truthfully about what it stands for, and Module#=== ignores that
+        # override — but ActiveSupport patches Time.=== to cover the gap
+        # (core_ext/time/calculations.rb), so under full Rails a case/when Time
+        # matches a TimeWithZone after all.
+        #
+        # It matches only where that core_ext is loaded, and this file does not
+        # require it: after a bare `require "audioproxy"`, Time.=== is still
+        # Module's. Since url_for is documented as usable with no Rails loaded,
+        # case/when here would accept a TimeWithZone in an app and reject it in
+        # a plain Ruby script. is_a? is TimeWithZone's own override and needs
+        # nothing else loaded, so it answers the same in both.
+        #
+        # Date is not on the list. Date#to_time is local midnight, so the same
+        # `expires_at: Date.tomorrow` means a different instant on every machine
+        # that renders it.
+        def unix_seconds(value)
+          return value if value.is_a?(Integer)
+
+          unless value.is_a?(Time) || value.is_a?(DateTime)
+            raise ArgumentError,
+              "Audioproxy url_for expires_at: must be a Time, DateTime, " \
+              "ActiveSupport::TimeWithZone or an Integer of unix seconds, got #{value.class}" \
+              "#{" (a Date is local midnight, which is a different instant per machine; pass a Time)" if value.is_a?(Date)}"
+          end
+
+          # Truncates sub-second, which moves the expiry at most one second
+          # earlier — the fail-safe direction.
+          value.to_time.to_i
+        end
+
+        # The proxy caps exp and 422s past it, which is where the millisecond
+        # typo (`some_time.to_i * 1000`) lands: a clean-looking URL that never
+        # works.
+        #
+        # +window+ is set only on the expires_in: path, where the caller wrote a
+        # duration rather than a timestamp — advising them about milliseconds
+        # there would name a mistake they did not make.
+        def bounded(seconds, source:, window: nil)
+          if seconds > Options::MAX_EXPIRES_AT
+            raise ArgumentError,
+              "Audioproxy #{source} produced #{seconds}, past the proxy's limit of " \
+              "#{Options::MAX_EXPIRES_AT} (9999-12-31T23:59:59Z); " \
+              "#{window ? "a window of #{window} seconds reaches past the year 9999" : "unix seconds, not milliseconds"}"
+          end
+
+          seconds
+        end
+
+        # A Duration whose total is not a whole number of seconds has no exact
+        # rendering here, and truncating one silently is the class of thing this
+        # gem raises about everywhere else — see Options.format_decimal.
+        def whole_seconds(value, total, source:)
+          unless total == total.to_i
+            raise ArgumentError,
+              "Audioproxy #{source} must be a whole number of seconds, got #{value.inspect} " \
+              "(#{total}); round explicitly at the call site if that is what you mean"
+          end
+
+          total.to_i
+        end
+    end
+  end
+end

data/lib/audioproxy/options.rb

@@ -11,15 +11,24 @@ module Audioproxy
   # 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
+    # The proxy's sixteen option keys, canonical short spellings.
+    KEYS = %i[bd br cb ch dl exp f fade gain norm pk_bits pk_fmt pts q sr t].freeze
+
+    # The one *request* option in the grammar: signed as path bytes, but
+    # excluded from the proxy's canonical options string, its cache key and its
+    # ffmpeg args, so two URLs differing only here are one variant and one
+    # render. Nothing in this module treats it specially beyond D1b below; the
+    # distinction is the proxy's, and it is recorded here because it is the
+    # reason exp may be appended to a raw: string that variant options may not.
+    REQUEST_KEYS = %i[exp].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).
+    # struct calls pts +peak_count+, pk_fmt +peak_format+ and pk_bits
+    # +peak_bits+ — so this is one vocabulary spelled twice, not a second
+    # vocabulary (D2). peak_bits is deliberately not bit_depth, which bd owns.
     ALIASES = {
       f: :format,
       br: :bitrate,
@@ -33,8 +42,10 @@ module Audioproxy
       norm: :normalize,
       pts: :peak_count,
       pk_fmt: :peak_format,
+      pk_bits: :peak_bits,
       dl: :download,
-      cb: :cache_buster
+      cb: :cache_buster,
+      exp: :expires_at
     }.freeze
 
     # Every accepted spelling to the canonical key it renders as. Canonical
@@ -44,6 +55,22 @@ module Audioproxy
       .merge(KEYS.to_h { |key| [ key, key ] })
       .freeze
 
+    # The keys that reach the proxy's peaks renderer (API v1 §3.3): the peaks
+    # keys themselves, and the ones peaks follow so a waveform matches the
+    # audio drawn under it. A positive list on purpose (D4): an ignored option
+    # still enters the proxy's cache key, so one that slips through buys a
+    # second render of byte-identical peaks, and a key added to the proxy later
+    # is refused here until someone checks it belongs.
+    PEAKS_KEYS = %i[pts pk_fmt pk_bits ch t fade gain norm dl cb].freeze
+
+    # The configured defaults that carry over to peaks (D10): the ones that
+    # change the samples, so a waveform matches the audio drawn above it, and
+    # the cache buster. Narrower than PEAKS_KEYS because a default was written
+    # for audio: ch:2 there means stereo output, but on peaks it means
+    # per-channel pairs instead of the mono downmix, and a dl: filename for the
+    # audio is never the right name for peaks JSON.
+    PEAKS_DEFAULT_KEYS = %i[t fade gain norm cb].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
@@ -60,6 +87,13 @@ module Audioproxy
     # normalized options string into its cache key.
     MAX_DECIMALS = 3
 
+    # The proxy's own bound on exp (@max_expires_at in its Options module):
+    # 9999-12-31T23:59:59Z. Past it, the proxy answers 422 invalid-option. The
+    # grammar fact lives here; UrlBuilder is what checks a caller's value
+    # against it, because that is where an out-of-range timestamp can still be
+    # reported against the keyword the caller actually wrote.
+    MAX_EXPIRES_AT = 253_402_300_799
+
     # 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
@@ -186,6 +220,7 @@ module Audioproxy
           # 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 render_expiry(value) if key == :exp
           return format_number(value) unless OPAQUE_KEYS.include?(key)
 
           case value
@@ -196,6 +231,23 @@ module Audioproxy
           end
         end
 
+        # exp is unix seconds, and the proxy's grammar has no decimal there:
+        # exp:1.5 parses as an invalid option and 422s. So this is one of the
+        # values the module cannot render faithfully, and it raises rather than
+        # emitting a segment that looks like a timestamp and is not one (D1b).
+        # Integer only — not a numeric String, because the two inputs that reach
+        # this key in practice are Time#to_i and an arithmetic result, and both
+        # are Integers.
+        def render_expiry(value)
+          unless value.is_a?(Integer)
+            raise ArgumentError,
+              "Audioproxy option exp: must be an Integer of unix seconds, got #{value.inspect}; " \
+              "pass expires_in: or expires_at: to url_for and let it do the arithmetic"
+          end
+
+          value.to_s
+        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

data/lib/audioproxy/rails/helpers.rb

@@ -11,6 +11,18 @@ module Audioproxy
         Audioproxy.url_for(source, **options)
       end
 
+      # URL helpers only, with no tag counterparts on purpose (D7): info is
+      # JSON and peaks are JSON or a binary .dat, both fetched by a script, so
+      # there is no element to hand them to. A <div data-peaks-url> convention
+      # would make this gem the keeper of some JavaScript library's markup.
+      def audioproxy_info_url(source, **options)
+        Audioproxy.info_url(source, **options)
+      end
+
+      def audioproxy_peaks_url(source, **options)
+        Audioproxy.peaks_url(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

data/lib/audioproxy/url_builder.rb

@@ -1,5 +1,6 @@
 require "base64"
 require "active_support/core_ext/object/blank"
+require "audioproxy/expiry"
 
 module Audioproxy
   # Assembles +{endpoint}/{signature}/{options}/{source}+ URLs, byte-compatible
@@ -18,6 +19,11 @@ module Audioproxy
     # always-valid options string is its default format spelled out.
     FALLBACK_OPTIONS = "f:mp3".freeze
 
+    INFO_SEGMENT = "info".freeze
+
+    # Builder keywords that carry an expiry, which /info cannot hold (D9).
+    EXPIRY_KEYWORDS = %i[expires_in expires_at].freeze
+
     attr_reader :config
 
     def initialize(config = Audioproxy.config)
@@ -29,14 +35,38 @@ module Audioproxy
     # 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?
+    #
+    # +expires_in:+ (a duration or Integer seconds from now) and +expires_at:+
+    # (the instant itself) are mutually exclusive and time-box this one URL,
+    # overriding +config.expires_in+; either given as nil opts out of it (D6).
+    def url_for(source, raw: nil, endpoint: nil, unsigned: nil,
+                expires_in: Expiry::UNSET, expires_at: Expiry::UNSET, **typed)
+      assemble(source, endpoint: endpoint, unsigned: unsigned) do
+        expiry = expiry_for(expires_in, expires_at)
+        with_expiry(variant_segment(raw, typed), expiry)
+      end
+    end
+
+    # The proxy's probe-metadata endpoint, +/{sig}/info/{source}+. API v1 §4:
+    # any options segment alongside +info+ is a 422, and the grammar therefore
+    # cannot carry +exp+ either. So neither +config.default_options+ (D2) nor
+    # +config.expires_in+ (D9) is consulted here — the one entry point that
+    # ignores them, because honouring them would break every info request.
+    def info_url(source, endpoint: nil, unsigned: nil, **options)
+      reject_info_options!(options)
 
-      rest_of_path = "/#{options_segment(raw, typed)}/#{source_segment(source)}"
-      insecure = unsigned.nil? ? config.unsigned : unsigned
+      assemble(source, endpoint: endpoint, unsigned: unsigned) { INFO_SEGMENT }
+    end
 
-      "#{base}/#{insecure ? INSECURE_SEGMENT : sign(rest_of_path)}#{rest_of_path}"
+    # A variant URL with the format fixed to +f:peaks+. Peaks are a format, not
+    # an endpoint, so this is url_for's grammar with a screened vocabulary: only
+    # Options::PEAKS_KEYS pass, per call and from the defaults (D4, D10).
+    def peaks_url(source, raw: nil, endpoint: nil, unsigned: nil,
+                  expires_in: Expiry::UNSET, expires_at: Expiry::UNSET, **typed)
+      assemble(source, endpoint: endpoint, unsigned: unsigned) do
+        expiry = expiry_for(expires_in, expires_at)
+        with_expiry(peaks_segment(raw, typed), expiry)
+      end
     end
 
     # Signs via Audioproxy::Signer. Whether the config *can* sign is this
@@ -51,11 +81,32 @@ module Audioproxy
     end
 
     private
+      # The block yields the segment between signature and source, and runs
+      # after the endpoint check, so a missing endpoint is reported first.
+      def assemble(source, endpoint:, unsigned:)
+        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 = "/#{yield}/#{source_segment(source)}"
+        insecure = unsigned.nil? ? config.unsigned : unsigned
+
+        "#{base}/#{insecure ? INSECURE_SEGMENT : sign(rest_of_path)}#{rest_of_path}"
+      end
+
+      # Once per URL, so the window arithmetic and the past-check cannot
+      # straddle a second boundary (D4).
+      def expiry_for(expires_in, expires_at)
+        Expiry.timestamp(
+          expires_in: expires_in, expires_at: expires_at,
+          default_expires_in: config.expires_in, now: Time.now.to_i
+        )
+      end
+
       # 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)
+      def variant_segment(raw, typed)
         unless raw.nil? || typed.empty?
           raise ArgumentError,
             "Audioproxy url_for takes either raw: or typed option keys, not both " \
@@ -69,6 +120,7 @@ module Audioproxy
         # overrides rather than two segments that both render (D3). Defaults
         # were resolved at assignment.
         typed = Options.resolve(typed)
+        reject_expiry_option!(typed)
 
         defaults = config.default_options
         typed_defaults = defaults.except(:raw)
@@ -80,6 +132,96 @@ module Audioproxy
         FALLBACK_OPTIONS
       end
 
+      # Screened on the keys as written, so an error echoes the spelling the
+      # caller typed rather than a canonical key they never saw.
+      def peaks_segment(raw, typed)
+        unless raw.nil?
+          raise ArgumentError,
+            "Audioproxy peaks_url does not take raw:, because a pre-rendered string cannot be checked " \
+            "against the options peaks accept; use url_for(source, raw: \"f:peaks/…\") to write it whole"
+        end
+
+        written = typed.keys
+        typed = Options.resolve(typed)
+        reject_expiry_option!(typed, "peaks_url")
+
+        if typed.key?(:f)
+          format = typed.delete(:f)
+          unless format == :peaks || format == "peaks"
+            key = written.find { |spelling| Options::CANONICAL[spelling.to_sym] == :f }
+            raise ArgumentError,
+              "Audioproxy peaks_url fixes the format to peaks, but was also given #{key}: #{format.inspect}; " \
+              "use url_for for any other format"
+          end
+        end
+
+        refused = written.reject { |key| [ :f, *Options::PEAKS_KEYS ].include?(Options::CANONICAL[key.to_sym]) }
+        unless refused.empty?
+          raise ArgumentError,
+            "Audioproxy peaks_url does not take #{refused.join(", ")}; peaks accept only " \
+            "#{Options::PEAKS_KEYS.join(", ")}, each also accepted spelled out. Any other option still " \
+            "enters the proxy's cache key, so it would buy a second render of identical peaks, or a 422"
+        end
+
+        # Defaults were written for audio variants, so only the ones that mean
+        # the same thing for peaks carry over; f:opus or br:96 beside f:peaks is
+        # a 422 (D10). f:peaks leads regardless, so a redundant format: cannot
+        # move it (D3). select, not slice: slice reorders by its arguments, and
+        # defaults keep the order they were written in, as they do for url_for.
+        defaults = config.default_options.select { |key, _| Options::PEAKS_DEFAULT_KEYS.include?(key) }
+        Options.render({ f: :peaks }.merge(defaults).merge(typed))
+      end
+
+      def reject_info_options!(options)
+        expiry = options.slice(*EXPIRY_KEYWORDS).compact
+        unless expiry.empty?
+          raise ArgumentError,
+            "Audioproxy info_url cannot carry an expiry (got #{expiry.keys.join(" and ")}:): the proxy's " \
+            "/info has no options segment, so there is nowhere to put exp. Info URLs do not expire"
+        end
+
+        rest = options.except(*EXPIRY_KEYWORDS)
+        return if rest.empty?
+
+        raise ArgumentError,
+          "Audioproxy info_url takes no proxy options (got #{rest.keys.join(", ")}): the proxy answers " \
+          "any options segment alongside /info with a 422. Use url_for or peaks_url to describe a variant"
+      end
+
+      # exp is a *request* option: signed as path bytes, but excluded from the
+      # proxy's cache key, so it is orthogonal to the variant options that
+      # raw: and the typed keys describe and composes with either (D3). It goes
+      # last, which leaves the variant prefix byte-identical to the same call
+      # without an expiry.
+      def with_expiry(segment, expiry)
+        return segment if expiry.nil?
+
+        # A raw: string that already spells out exp: would give the proxy two of
+        # them and a duplicate-option 422 — a failure the caller never wrote if
+        # the second one came from config.expires_in.
+        prefixes = Options::REQUEST_KEYS.map { |key| "#{key}:" }
+        if segment.split("/").any? { |part| prefixes.any? { |prefix| part.start_with?(prefix) } }
+          raise ArgumentError,
+            "Audioproxy url_for was given raw options that already carry an exp: segment " \
+            "(#{segment.inspect}) and an expiry to apply; the proxy rejects a duplicated option. " \
+            "Drop the exp: from raw:, or pass expires_in: nil to opt this URL out"
+        end
+
+        "#{segment}/#{Options.segment(:exp, expiry)}"
+      end
+
+      # exp: written as an ordinary option skips every check in Expiry, and the
+      # two mistakes it invites — a timestamp already past, a millisecond
+      # timestamp — both render a URL that looks right and never works (D1).
+      def reject_expiry_option!(typed, entry = "url_for")
+        return unless typed.key?(:exp)
+
+        raise ArgumentError,
+          "Audioproxy #{entry} does not take exp: as an option key; " \
+          "pass expires_in: (a duration from now) or expires_at: (the instant), " \
+          "which validate the value and do the arithmetic"
+      end
+
       def raw_segment(raw)
         segment = String.try_convert(raw)
         if segment.nil?

data/lib/audioproxy/version.rb

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

data/lib/audioproxy.rb

@@ -19,12 +19,23 @@ module Audioproxy
       config
     end
 
-    # Single public entry point: usable from jobs, mailers and serializers of
-    # any Ruby program, Rails or not.
+    # Usable from jobs, mailers and serializers of any Ruby program, Rails or
+    # not, as are the two below.
     def url_for(source, **options)
       UrlBuilder.new(config).url_for(source, **options)
     end
 
+    # Probe metadata as JSON. Takes no proxy options and ignores the configured
+    # defaults and expiry, because /info can carry neither.
+    def info_url(source, **options)
+      UrlBuilder.new(config).info_url(source, **options)
+    end
+
+    # Waveform peaks: f:peaks fixed, and only the options peaks read.
+    def peaks_url(source, **options)
+      UrlBuilder.new(config).peaks_url(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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: audioproxy-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Julian Rubisch
 bindir: bin
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -70,6 +70,7 @@ files:
 - README.md
 - lib/audioproxy.rb
 - lib/audioproxy/config.rb
+- lib/audioproxy/expiry.rb
 - lib/audioproxy/options.rb
 - lib/audioproxy/rails.rb
 - lib/audioproxy/rails/blob_resolver.rb