m3u8 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a4ef59c0103a519f686f38d7eb24e99286f698bfbee43d7e8ad48827dfd00e5
-  data.tar.gz: b776355294c670836ecc6598ad169d71eedc40e017a686c28042828bf724e805
+  metadata.gz: df37c1a4cc89e0bd918c6137c5bc86682d61638b407697240e76f40acb8983e7
+  data.tar.gz: e19fd10c1b3f732057285247f08bb235573fa6434085295b53a76be22f1a53aa
 SHA512:
-  metadata.gz: e2f761adbf62244f9f175fc28f7f00f0d77d78acb5af19906f70fff656777e97bbbe787454ce47accd0e72f4e702baeda20dde763a72ac87174cb9ccd24dca15
-  data.tar.gz: bf19a4de08cc5216b939c77eedc147e93e134bc284a90464f138f3a31f0d679d88e5bd6e306db63dbf0e26ce7a40fba618bb67d41c15443899a2824b6fd4776c
+  metadata.gz: c4ff8a727525925718fcb0ff7fed0b8bb758556d8e262c97ebacaca4fe96550b4494817ce5d8f4a0525d961a274a1905b16af6b5a85b8ac57235254f54392f8a
+  data.tar.gz: 19ae07aa8cd202846254983b823973c4b7d0a9d4bde50e5cc8be7e1e4d91182205bec84731f628298f2659085434716120135a074656e1c9c2aa2c1988415b4f

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+**1.5.0**
+
+* Added `Playlist#freeze` for deep-freezing playlists, items, nested objects, and playlist-level objects. `Playlist.build` and `Playlist.read` now return frozen playlists. `Playlist.new` remains mutable until `freeze` is called explicitly.
+
+***
+
 **1.4.0**
 
 * Added `Playlist#errors` method returning an array of validation error messages. `Playlist#valid?` now delegates to `errors.empty?`. Validates mixed item types, target duration, segment items, playlist items, media items, encryption keys, session keys, session data, and LL-HLS part items.

data/README.md

@@ -344,6 +344,27 @@ options = { width: 1920, height: 1080, codecs: 'avc1.66.30,mp4a.40.2',
 item = M3u8::PlaylistItem.new(options)
 ```
 
+## Frozen playlists
+
+Playlists returned by `Playlist.build` and `Playlist.read` are frozen (deeply immutable). Items, nested objects, and the items array are all frozen, preventing accidental mutation after construction:
+
+```ruby
+playlist = M3u8::Playlist.read(File.open('master.m3u8'))
+playlist.frozen?          # => true
+playlist.items.frozen?    # => true
+playlist.items.first.frozen? # => true
+```
+
+Playlists created with `Playlist.new` remain mutable. Call `freeze` explicitly when ready:
+
+```ruby
+playlist = M3u8::Playlist.new
+playlist.items << M3u8::SegmentItem.new(duration: 10.0, segment: 'test.ts')
+playlist.freeze
+```
+
+Frozen playlists still support `to_s` and `write` for output.
+
 ## Validation
 
 Check whether a playlist is valid and inspect specific errors:

data/lib/m3u8/playlist.rb

@@ -22,7 +22,7 @@ module M3u8
       else
         builder.instance_eval(&block)
       end
-      playlist
+      playlist.freeze
     end
 
     def self.codecs(options = {})
@@ -53,6 +53,14 @@ module M3u8
       playlist_size.positive?
     end
 
+    def freeze
+      items.each { |item| freeze_item(item) }
+      items.freeze
+      part_inf&.freeze
+      server_control&.freeze
+      super
+    end
+
     def to_s
       output = StringIO.open
       write(output)
@@ -119,6 +127,13 @@ module M3u8
 
     private
 
+    def freeze_item(item)
+      item.byterange&.freeze if item.respond_to?(:byterange)
+      item.program_date_time&.freeze if item.respond_to?(:program_date_time)
+      item.client_attributes&.freeze if item.respond_to?(:client_attributes)
+      item.freeze
+    end
+
     def assign_options(options)
       options = defaults.merge(options)
 

data/lib/m3u8/reader.rb

@@ -25,7 +25,7 @@ module M3u8
         parse_line(line)
       end
       playlist.live = !@has_endlist unless master
-      playlist
+      playlist.freeze
     end
 
     private

data/lib/m3u8/version.rb

@@ -2,5 +2,5 @@
 
 # M3u8 provides parsing, generation, and validation of m3u8 playlists
 module M3u8
-  VERSION = '1.4.0'
+  VERSION = '1.5.0'
 end

data/spec/lib/m3u8/builder_spec.rb

@@ -191,6 +191,20 @@ describe M3u8::Builder do
       expect(playlist.target).to eq(12)
     end
 
+    it 'returns a frozen playlist' do
+      playlist = M3u8::Playlist.build do
+        segment duration: 10.0, segment: 'test.ts'
+      end
+      expect(playlist).to be_frozen
+    end
+
+    it 'returns a frozen playlist with yielded form' do
+      playlist = M3u8::Playlist.build do |b|
+        b.segment duration: 10.0, segment: 'test.ts'
+      end
+      expect(playlist).to be_frozen
+    end
+
     it 'supports yielded builder form' do
       files = %w[seg1.ts seg2.ts]
       playlist = M3u8::Playlist.build(version: 4) do |b|

data/spec/lib/m3u8/playlist_spec.rb

@@ -654,6 +654,108 @@ describe M3u8::Playlist do
     end
   end
 
+  describe '#freeze' do
+    it 'freezes the playlist' do
+      playlist.freeze
+      expect(playlist).to be_frozen
+    end
+
+    it 'freezes the items array' do
+      playlist.freeze
+      expect(playlist.items).to be_frozen
+    end
+
+    it 'freezes each item' do
+      item = M3u8::SegmentItem.new(duration: 10.0, segment: 'test.ts')
+      playlist.items << item
+      playlist.freeze
+      expect(item).to be_frozen
+    end
+
+    it 'freezes nested byterange on items' do
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts',
+        byterange: { length: 4500, start: 600 }
+      )
+      playlist.items << item
+      playlist.freeze
+      expect(item.byterange).to be_frozen
+    end
+
+    it 'freezes nested program_date_time on items' do
+      time = M3u8::TimeItem.new(time: '2024-06-01T12:00:00Z')
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts',
+        program_date_time: time
+      )
+      playlist.items << item
+      playlist.freeze
+      expect(item.program_date_time).to be_frozen
+    end
+
+    it 'freezes nested client_attributes on items' do
+      item = M3u8::DateRangeItem.new(
+        id: 'ad-1', start_date: '2024-01-01T00:00:00Z',
+        client_attributes: { 'X-AD-ID' => '"foo"' }
+      )
+      playlist.items << item
+      playlist.freeze
+      expect(item.client_attributes).to be_frozen
+    end
+
+    it 'freezes part_inf' do
+      playlist.part_inf = M3u8::PartInfItem.new(part_target: 0.5)
+      playlist.freeze
+      expect(playlist.part_inf).to be_frozen
+    end
+
+    it 'freezes server_control' do
+      playlist.server_control = M3u8::ServerControlItem.new(
+        can_skip_until: 24.0
+      )
+      playlist.freeze
+      expect(playlist.server_control).to be_frozen
+    end
+
+    it 'raises FrozenError on attribute set' do
+      playlist.freeze
+      expect { playlist.version = 7 }
+        .to raise_error(FrozenError)
+    end
+
+    it 'raises FrozenError on items append' do
+      playlist.freeze
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts'
+      )
+      expect { playlist.items << item }
+        .to raise_error(FrozenError)
+    end
+
+    it 'raises FrozenError on item mutation' do
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts'
+      )
+      playlist.items << item
+      playlist.freeze
+      expect { item.duration = 5.0 }
+        .to raise_error(FrozenError)
+    end
+
+    it 'still supports to_s' do
+      item = M3u8::SegmentItem.new(
+        duration: 10.0, segment: 'test.ts'
+      )
+      playlist.items << item
+      playlist.freeze
+      expect(playlist.to_s).to include('#EXTM3U')
+    end
+
+    it 'returns self' do
+      expect(playlist.freeze).to equal(playlist)
+    end
+  end
+
   describe '#write' do
     context 'when playlist is valid' do
       it 'returns playlist text' do

data/spec/lib/m3u8/reader_spec.rb

@@ -590,6 +590,20 @@ describe M3u8::Reader do
       expect(item.segment).to eq('segment0.ts')
     end
 
+    it 'returns a frozen master playlist' do
+      playlist = reader.read(
+        File.read('spec/fixtures/master.m3u8')
+      )
+      expect(playlist).to be_frozen
+    end
+
+    it 'returns a frozen media playlist' do
+      playlist = reader.read(
+        File.read('spec/fixtures/playlist.m3u8')
+      )
+      expect(playlist).to be_frozen
+    end
+
     context 'when playlist source is invalid' do
       it 'raises error with message' do
         message = 'Playlist must start with a #EXTM3U tag, line read ' \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: m3u8
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Seth Deckard