hls 0.1.0 → 0.2.0

data/lib/hls/state.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "time"
+
+module HLS
+  # Sidecar state for an encoded bundle. Records the input digest,
+  # rendition list, and per-file upload status so a re-run can skip work
+  # that's already done and a crashed run can resume from the last
+  # successful upload.
+  #
+  # Lives at `<output>/.hls-state.json` next to the encoded bundle.
+  class State
+    FILENAME = ".hls-state.json"
+
+    class CorruptError < HLS::Error; end
+
+    def self.load(output_dir)
+      path = Pathname.new(output_dir).join(FILENAME)
+      new(path: path, data: read(path))
+    end
+
+    # Reads state JSON from disk. Returns `default_data` for a missing
+    # file (the common first-run case). Raises CorruptError when the
+    # file exists but isn't parseable — silently re-encoding on
+    # corruption would be expensive and surprising; explicit failure
+    # lets the caller decide whether to delete the sidecar and retry.
+    def self.read(path)
+      return default_data unless path.exist?
+
+      raw = JSON.parse(path.read, symbolize_names: true)
+      default_data.merge(raw)
+    rescue JSON::ParserError => e
+      raise CorruptError, "state file at #{path} is not valid JSON: #{e.message}"
+    end
+
+    def self.default_data
+      {
+        input_digest: nil,
+        config_digest: nil,
+        profile: nil,
+        renditions: [],
+        encoded_at: nil,
+        uploads: {}
+      }
+    end
+
+    attr_reader :path
+
+    def initialize(path:, data:)
+      @path = Pathname.new(path)
+      @data = data
+    end
+
+    def input_digest  = @data[:input_digest]
+    def config_digest = @data[:config_digest]
+    def profile       = @data[:profile]
+    def renditions    = @data[:renditions]
+    def encoded_at    = @data[:encoded_at]
+    def uploads       = @data[:uploads]
+
+    # Has this output already been encoded for the given input AND
+    # profile config? A change to either invalidates the encode —
+    # bumping `audio_bitrate` or adding a rendition has to re-run
+    # ffmpeg even if the input file is byte-identical.
+    def encoded?(input_digest:, config_digest:)
+      !@data[:encoded_at].nil? &&
+        @data[:input_digest]  == input_digest &&
+        @data[:config_digest] == config_digest
+    end
+
+    # Has the file at relative_key already been uploaded with the given digest?
+    def uploaded?(relative_key:, digest:)
+      upload = @data[:uploads][relative_key.to_sym]
+      !upload.nil? && upload[:digest] == digest
+    end
+
+    def record_encode(input_digest:, config_digest:, profile:, renditions:)
+      @data[:input_digest]  = input_digest
+      @data[:config_digest] = config_digest
+      @data[:profile]       = profile
+      @data[:renditions]    = renditions
+      @data[:encoded_at]    = Time.now.utc.iso8601
+      # Content has changed; previous upload records are stale.
+      @data[:uploads]       = {}
+    end
+
+    def record_upload(relative_key:, digest:, etag: nil)
+      @data[:uploads][relative_key.to_sym] = {
+        digest: digest,
+        etag: etag,
+        uploaded_at: Time.now.utc.iso8601
+      }
+    end
+
+    def save
+      path.parent.mkpath
+      path.write(JSON.pretty_generate(@data))
+    end
+
+    def to_h
+      @data.dup
+    end
+  end
+end

data/lib/hls/storage.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "digest"
+require "stringio"
+
+module HLS
+  # The storage protocol the gem talks through to put/get objects and
+  # produce signed URLs. Profile classes attach an instance of one of
+  # these to themselves via `storage`.
+  #
+  # # Protocol
+  #
+  #   storage.signing_ttl     -> Integer (default TTL for presigned URLs)
+  #   storage.object(key)     -> Object  (no I/O)
+  #
+  #   object.get              -> response with .body (IO-like)
+  #   object.put(body:, content_type:, cache_control:) -> response with .etag
+  #   object.presigned_url(:get, expires_in:) -> URL string
+  #
+  # # Built-in adapters
+  #
+  # - `HLS::Storage::S3`     — default. Wraps an `Aws::S3::Bucket`.
+  # - `HLS::Storage::Memory` — in-process bucket for tests. Signed URLs
+  #   are non-browser `memory://` strings but round-trip through a
+  #   Manifest so you can assert on them.
+  module Storage
+    # Default storage backend: an Aws::S3::Bucket plus a signing TTL.
+    # Constructed with either a bucket name (resolved through
+    # HLS.s3_resource at first use) or a pre-built Aws::S3::Bucket
+    # (useful in tests or when the host already built one).
+    #
+    #   HLS::Storage::S3.new(bucket_name: "videos", signing_ttl: 1.hour)
+    #   HLS::Storage::S3.new(bucket: my_aws_bucket, signing_ttl: 60)
+    class S3
+      DEFAULT_SIGNING_TTL = 3600
+
+      attr_accessor :signing_ttl
+      attr_reader :bucket_name
+
+      def initialize(bucket_name: nil, bucket: nil, s3_resource: nil, signing_ttl: DEFAULT_SIGNING_TTL)
+        @bucket_name = bucket_name
+        @bucket = bucket
+        @s3_resource = s3_resource
+        @signing_ttl = signing_ttl
+      end
+
+      def object(key)
+        bucket.object(key)
+      end
+
+      # The underlying Aws::S3::Bucket. Resolved lazily so a profile
+      # can declare `def self.storage = HLS::Storage::S3.new(bucket_name:
+      # ENV.fetch("..."))` without forcing an SDK lookup at class-load
+      # time.
+      def bucket
+        @bucket ||= begin
+          if bucket_name.to_s.empty?
+            raise ArgumentError,
+              "HLS::Storage::S3 needs either a bucket_name or a pre-built bucket"
+          end
+          (@s3_resource || HLS.s3_resource).bucket(bucket_name)
+        end
+      end
+    end
+
+    # In-memory bucket for tests. Backed by a hash protected by a
+    # single mutex — concurrent puts and gets across threads are safe.
+    class Memory
+      DEFAULT_SIGNING_TTL = 3600
+
+      def self.build(name: "memory", signing_ttl: DEFAULT_SIGNING_TTL, objects: {})
+        bucket = new(name: name, signing_ttl: signing_ttl)
+        objects.each { |key, body| bucket.object(key).put(body: body) }
+        bucket
+      end
+
+      attr_reader :name
+      attr_accessor :signing_ttl
+
+      def initialize(name:, signing_ttl: DEFAULT_SIGNING_TTL)
+        @name = name
+        @signing_ttl = signing_ttl
+        @store = {}
+        @mutex = Mutex.new
+      end
+
+      def object(key)
+        Object.new(store: @store, mutex: @mutex, key: key, signing_ttl: @signing_ttl)
+      end
+
+      def keys
+        @mutex.synchronize { @store.keys }
+      end
+
+      class Object
+        attr_reader :key
+
+        def initialize(store:, mutex:, key:, signing_ttl:)
+          @store = store
+          @mutex = mutex
+          @key = key
+          @signing_ttl = signing_ttl
+        end
+
+        def get
+          entry = @mutex.synchronize { @store[@key] }
+          raise KeyError, "no object at #{@key}" if entry.nil?
+          Response.new(body: StringIO.new(entry[:body].to_s), content_type: entry[:content_type])
+        end
+
+        def put(body:, content_type: "application/octet-stream", cache_control: nil)
+          body_str = body.respond_to?(:read) ? body.read : body.to_s
+          @mutex.synchronize do
+            @store[@key] = {
+              body: body_str,
+              content_type: content_type,
+              cache_control: cache_control
+            }
+          end
+          PutResponse.new(etag: %("#{Digest::MD5.hexdigest(body_str)}"))
+        end
+
+        def presigned_url(_verb = :get, expires_in: @signing_ttl, **_)
+          "memory://#{@key}?expires_in=#{expires_in}"
+        end
+      end
+
+      Response = Struct.new(:body, :content_type, keyword_init: true)
+      PutResponse = Struct.new(:etag, keyword_init: true)
+    end
+  end
+end

data/lib/hls/testing.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "pathname"
+require "tmpdir"
+require "uri"
+require "m3u8"
+
+module HLS
+  # Public test helpers for verifying that an HLS profile actually
+  # produces a correct bundle when run against ffmpeg. Users of the gem
+  # can include this module in their own spec suites to write integration
+  # tests against their `app/videos/*.rb` profile classes:
+  #
+  #   require "hls/testing"
+  #
+  #   RSpec.describe CourseVideo do
+  #     include HLS::Testing
+  #
+  #     it "encodes a valid HLS bundle" do
+  #       video = generate_test_video(duration: 12)
+  #       output = Pathname.new(Dir.mktmpdir)
+  #
+  #       profile = CourseVideo.new(input: HLS::Input.new(video), output: output)
+  #       silence_ffmpeg do
+  #         profile.encode!
+  #         profile.poster!
+  #       end
+  #
+  #       expect(output).to be_a_valid_hls_bundle.with_variants(3)
+  #     end
+  #   end
+  #
+  # All helpers shell out to ffmpeg/ffprobe (already a hard dep of the
+  # gem), so any environment that can run the gem can run these helpers.
+  module Testing
+    # Generates a deterministic test video at `path` (or a tmpdir-backed
+    # path if not given). Returns the path. The video uses ffmpeg's
+    # `testsrc` filter for video and `sine` for audio — fully
+    # self-contained, no external assets.
+    def generate_test_video(path: nil, duration: 12, width: 640, height: 360, framerate: 30, frequency: 440)
+      path = Pathname.new(path || Dir::Tmpname.create(["hls-fixture", ".mp4"]) {})
+
+      cmd = [
+        "ffmpeg", "-y", "-loglevel", "error",
+        "-f", "lavfi", "-i", "testsrc=duration=#{duration}:size=#{width}x#{height}:rate=#{framerate}",
+        "-f", "lavfi", "-i", "sine=frequency=#{frequency}:duration=#{duration}",
+        "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p",
+        "-c:a", "aac", "-b:a", "64k",
+        "-shortest",
+        path.to_s
+      ]
+      unless system(*cmd, out: File::NULL, err: File::NULL)
+        raise HLS::Error, "ffmpeg failed to generate test fixture at #{path}"
+      end
+
+      path
+    end
+
+    # Probes a media file with ffprobe and returns its parsed metadata.
+    def probe(path)
+      stdout, _stderr, status = Open3.capture3(
+        "ffprobe", "-v", "error",
+        "-select_streams", "v:0",
+        "-show_entries", "stream=width,height,codec_name",
+        "-of", "json",
+        path.to_s
+      )
+      raise HLS::Error, "ffprobe failed for #{path}" unless status.success?
+      JSON.parse(stdout)
+    end
+
+    # Returns [width, height] for an image or video file.
+    def probe_dimensions(path)
+      stream = probe(path).fetch("streams").first or
+        raise HLS::Error, "no video stream in #{path}"
+      [stream["width"], stream["height"]]
+    end
+
+    # Parses an m3u8 file and returns the M3u8::Playlist.
+    def parse_playlist(path)
+      M3u8::Reader.new.read(File.read(path))
+    end
+
+    # Silences stdout/stderr inside the block. Useful for hiding ffmpeg's
+    # noisy progress output during test runs. Restores streams even on
+    # exception.
+    def silence_ffmpeg
+      original_stdout = $stdout.dup
+      original_stderr = $stderr.dup
+      $stdout.reopen(File::NULL, "w")
+      $stderr.reopen(File::NULL, "w")
+      yield
+    ensure
+      $stdout.reopen(original_stdout) if original_stdout
+      $stderr.reopen(original_stderr) if original_stderr
+    end
+
+    # RSpec matchers. Loaded automatically when RSpec is defined.
+    if defined?(RSpec::Matchers)
+      RSpec::Matchers.define :be_a_valid_hls_bundle do
+        match do |dir|
+          @dir = Pathname.new(dir)
+          @failures = []
+
+          unless @dir.directory?
+            @failures << "#{@dir} is not a directory"
+            next false
+          end
+
+          master_path = @dir.join("index.m3u8")
+          unless master_path.exist?
+            @failures << "missing master playlist at #{master_path}"
+            next false
+          end
+
+          @master = M3u8::Reader.new.read(master_path.read)
+          if @master.items.empty?
+            @failures << "master playlist has no streams"
+            next false
+          end
+
+          # Expected variant count, if specified.
+          if @expected_variant_count && @master.items.size != @expected_variant_count
+            @failures << "expected #{@expected_variant_count} variants, found #{@master.items.size}"
+            next false
+          end
+
+          # Each variant playlist must exist on disk.
+          @master.items.each do |item|
+            variant_path = @dir.join(item.uri)
+            unless variant_path.exist?
+              @failures << "variant playlist missing on disk: #{item.uri}"
+            end
+          end
+
+          # Each variant must have segment files.
+          @master.items.each do |item|
+            variant_path = @dir.join(item.uri)
+            next unless variant_path.exist?
+
+            playlist = M3u8::Reader.new.read(variant_path.read)
+            playlist.items.each do |segment|
+              segment_path = variant_path.dirname.join(segment.segment)
+              unless segment_path.exist? && segment_path.size > 0
+                @failures << "segment missing or empty: #{item.uri} → #{segment.segment}"
+              end
+            end
+          end
+
+          # Posters, if specified.
+          (@expected_posters || []).each do |name|
+            poster_path = @dir.join("#{name}.jpg")
+            unless poster_path.exist? && poster_path.size > 0
+              @failures << "expected poster missing or empty: #{name}.jpg"
+            end
+          end
+
+          @failures.empty?
+        end
+
+        chain :with_variants do |count|
+          @expected_variant_count = count
+        end
+
+        chain :with_posters do |*names|
+          @expected_posters = names
+        end
+
+        failure_message do |dir|
+          "expected #{dir} to be a valid HLS bundle, but:\n  - " + @failures.join("\n  - ")
+        end
+
+        failure_message_when_negated do |dir|
+          "expected #{dir} not to be a valid HLS bundle, but it was"
+        end
+      end
+
+      # Asserts that the variant URIs in a master playlist resolve to
+      # clean URLs when a player fetches the master at the given URL.
+      # Catches the path-prefix-included-twice bug class:
+      #
+      #   it "rewrites variant URIs correctly" do
+      #     manifest = CourseVideo.manifest("phlex/forms/overview")
+      #     expect(manifest.master_playlist).to resolve_variants_under(
+      #       "https://app.example.com/videos/phlex/forms/overview.m3u8"
+      #     )
+      #   end
+      #
+      # The rule: a *relative* variant URI must resolve to a URL whose
+      # path extends the master URL's path-without-extension. If a
+      # variant URI accidentally includes the master path as a prefix,
+      # resolution against the master's parent directory loses that
+      # prefix and the resolved URL no longer starts with the master
+      # path — that's the doubling bug.
+      #
+      # Absolute variant URIs (different scheme/host) and path-absolute
+      # URIs (starting with /) are skipped — those are intentional
+      # routing decisions, not doubling.
+      #
+      # Pass `.matching(<regexp>)` to additionally assert the resolved
+      # URLs match a specific shape:
+      #
+      #   .resolve_variants_under(url).matching(%r{/videos/.+/\d+\.m3u8\z})
+      RSpec::Matchers.define :resolve_variants_under do |master_url|
+        match do |playlist|
+          @master_uri  = URI(master_url)
+          @master_path_without_ext = @master_uri.path.sub(/\.m3u8\z/, "")
+          @failures    = []
+
+          unless playlist.respond_to?(:items)
+            @failures << "expected an M3u8::Playlist, got #{playlist.class}"
+            next false
+          end
+
+          if playlist.items.empty?
+            @failures << "master playlist has no variant streams"
+            next false
+          end
+
+          playlist.items.each_with_index do |item, i|
+            variant_uri = URI(item.uri)
+            resolved = (@master_uri + item.uri)
+
+            # Skip checks for absolute URIs (different host or scheme)
+            # and path-absolute URIs (starting with /). Those are
+            # explicit routing choices, not bugs.
+            relative = !variant_uri.absolute? && !item.uri.start_with?("/")
+
+            if relative && !resolved.path.start_with?(@master_path_without_ext)
+              @failures << "variant ##{i} URI #{item.uri.inspect} resolved to " \
+                "#{resolved} — its path #{resolved.path.inspect} should " \
+                "extend the master path #{@master_path_without_ext.inspect} " \
+                "but does not. This usually means the variant URI " \
+                "incorrectly includes a path prefix."
+            end
+
+            if @expected_pattern && !resolved.to_s.match?(@expected_pattern)
+              @failures << "variant ##{i} resolved URL #{resolved.to_s.inspect} " \
+                "did not match #{@expected_pattern.inspect}"
+            end
+          end
+
+          @failures.empty?
+        end
+
+        chain :matching do |pattern|
+          @expected_pattern = pattern
+        end
+
+        failure_message do
+          "expected variant URIs to resolve cleanly under #{@master_uri}, but:\n  - " +
+            @failures.join("\n  - ")
+        end
+
+        failure_message_when_negated do
+          "expected variant URIs NOT to resolve cleanly under #{@master_uri}, but they did"
+        end
+      end
+    end
+  end
+end