Class: Solis::OverlayFS

Inherits:
Object
  • Object
show all
Defined in:
lib/solis/overlay_fs.rb

Defined Under Namespace

Classes: Entry, Error, Hooks, LayerError, OverlayIO, OverlayStat, ReadOnlyError

Constant Summary collapse

WHITEOUT_PREFIX = 
'.wh.'
OPAQUE_MARKER = 
'.wh..wh..opq'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(cache: true) ⇒ OverlayFS 



166
167
168
169
170
171
172
173
 
# File 'lib/solis/overlay_fs.rb', line 166

def initialize(cache: true)
  @layers = []
  @cache_enabled = cache
  @resolve_cache = {}
  @stat_cache = {}
  @monitor = Monitor.new
  @hooks = Hooks.new
end

Instance Attribute Details

#hooks ⇒ Object (readonly)

Returns the value of attribute hooks.



164
165
166
 
# File 'lib/solis/overlay_fs.rb', line 164

def hooks
  @hooks
end

#layers ⇒ Object (readonly)

Returns the value of attribute layers.



164
165
166
 
# File 'lib/solis/overlay_fs.rb', line 164

def layers
  @layers
end

Instance Method Details

#[](relative_path) ⇒ Object 



971
972
973
 
# File 'lib/solis/overlay_fs.rb', line 971

def [](relative_path)
  resolve(relative_path)
end

#add_layer(path, writable: false, label: nil) ⇒ Object

— Layer Management —



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/solis/overlay_fs.rb', line 177

def add_layer(path, writable: false, label: nil)
  @monitor.synchronize do
    path = Pathname.new(path).expand_path

    layer = {
      path: path,
      writable: writable,
      label: label || path.basename.to_s
    }

    writable ? @layers.unshift(layer) : @layers.push(layer)
    clear_cache
  end
  self
end

#all_versions(relative_path) ⇒ Object 



948
949
950
951
952
953
954
955
956
957
958
959
960
961
 
# File 'lib/solis/overlay_fs.rb', line 948

def all_versions(relative_path)
  relative_path = normalize_path(relative_path)

  @layers.filter_map do |layer|
    full_path = layer[:path] / relative_path
    next unless full_path.exist?

    {
      layer: layer[:label],
      path: full_path,
      writable: layer[:writable]
    }
  end
end

#append(relative_path, content) ⇒ Object 



281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/solis/overlay_fs.rb', line 281

def append(relative_path, content)
  if exist?(relative_path)
    copy_up(relative_path)
  end

  path = writable_path(relative_path)
  ensure_directory(path.dirname)
  File.open(path, 'a') { |f| f.write(content) }
  clear_cache_for(relative_path)
  path
end

#atime(relative_path) ⇒ Object 



463
464
465
 
# File 'lib/solis/overlay_fs.rb', line 463

def atime(relative_path)
  stat(relative_path)&.atime || raise(Errno::ENOENT, relative_path)
end

#atomic_write(relative_path, content, **options) ⇒ Object 



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/solis/overlay_fs.rb', line 293

def atomic_write(relative_path, content, **options)
  relative_path = normalize_path(relative_path)
  path = writable_path(relative_path)
  ensure_directory(path.dirname)

  temp_path = "#{path}.tmp.#{Process.pid}.#{Thread.current.object_id}"
  begin
    File.write(temp_path, content, **options)
    File.rename(temp_path, path)
    remove_whiteout(relative_path)
    clear_cache_for(relative_path)
    hooks.trigger(:after_write, path: relative_path, real_path: path)
    path
  rescue
    File.unlink(temp_path) if File.exist?(temp_path)
    raise
  end
end

#basename(relative_path, suffix = nil) ⇒ Object 



481
482
483
 
# File 'lib/solis/overlay_fs.rb', line 481

def basename(relative_path, suffix = nil)
  suffix ? File.basename(relative_path, suffix) : File.basename(relative_path)
end

#cache_stats ⇒ Object 



911
912
913
914
915
916
917
 
# File 'lib/solis/overlay_fs.rb', line 911

def cache_stats
  {
    resolve_cache_size: @resolve_cache.size,
    stat_cache_size: @stat_cache.size,
    cache_enabled: @cache_enabled
  }
end

#checksum(relative_path, algorithm: :sha256) ⇒ Object 



489
490
491
492
493
494
495
496
497
498
 
# File 'lib/solis/overlay_fs.rb', line 489

def checksum(relative_path, algorithm: :sha256)
  content = read_binary(relative_path)
  case algorithm
  when :md5    then Digest::MD5.hexdigest(content)
  when :sha1   then Digest::SHA1.hexdigest(content)
  when :sha256 then Digest::SHA256.hexdigest(content)
  when :sha512 then Digest::SHA512.hexdigest(content)
  else raise ArgumentError, "Unknown algorithm: #{algorithm}"
  end
end

#children(relative_path = '.') ⇒ Object 



589
590
591
 
# File 'lib/solis/overlay_fs.rb', line 589

def children(relative_path = '.')
  entries(relative_path).map(&:name)
end

#chmod(mode, relative_path) ⇒ Object

— Permissions —



820
821
822
823
824
825
 
# File 'lib/solis/overlay_fs.rb', line 820

def chmod(mode, relative_path)
  relative_path = normalize_path(relative_path)
  copy_up(relative_path) unless in_writable_layer?(relative_path)
  FileUtils.chmod(mode, writable_path(relative_path))
  clear_cache_for(relative_path)
end

#chown(user, group, relative_path) ⇒ Object 



827
828
829
830
831
832
 
# File 'lib/solis/overlay_fs.rb', line 827

def chown(user, group, relative_path)
  relative_path = normalize_path(relative_path)
  copy_up(relative_path) unless in_writable_layer?(relative_path)
  FileUtils.chown(user, group, writable_path(relative_path))
  clear_cache_for(relative_path)
end

#clear_cache ⇒ Object

— Cache Management —



888
889
890
891
892
893
 
# File 'lib/solis/overlay_fs.rb', line 888

def clear_cache
  @monitor.synchronize do
    @resolve_cache.clear
    @stat_cache.clear
  end
end

#clear_cache_for(relative_path) ⇒ Object 



895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
 
# File 'lib/solis/overlay_fs.rb', line 895

def clear_cache_for(relative_path)
  @monitor.synchronize do
    relative_path = normalize_path(relative_path)
    @resolve_cache.delete(relative_path)
    @stat_cache.delete(relative_path)

    # Also clear parent directories
    parts = relative_path.split('/')
    parts.length.times do |i|
      parent = parts[0...i].join('/')
      @resolve_cache.delete(parent)
      @stat_cache.delete(parent)
    end
  end
end

#copy(source, destination, preserve: true) ⇒ Object

Raises:

  • (Errno::ENOENT) 


666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
 
# File 'lib/solis/overlay_fs.rb', line 666

def copy(source, destination, preserve: true)
  source = normalize_path(source)
  destination = normalize_path(destination)

  source_path = resolve(source)
  raise Errno::ENOENT, source unless source_path

  dest_path = writable_path(destination)
  ensure_directory(dest_path.dirname)
  remove_whiteout(destination)

  if source_path.directory?
    copy_directory(source, destination, preserve: preserve)
  else
    FileUtils.cp(source_path, dest_path, preserve: preserve)
  end

  clear_cache_for(destination)
  dest_path
end

#copy_up(relative_path) ⇒ Object

— File Manipulation —

Raises:

  • (Errno::ENOENT) 


640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
 
# File 'lib/solis/overlay_fs.rb', line 640

def copy_up(relative_path)
  relative_path = normalize_path(relative_path)

  return writable_path(relative_path) if in_writable_layer?(relative_path)

  source = resolve(relative_path)
  raise Errno::ENOENT, relative_path unless source

  dest = writable_path(relative_path)
  ensure_directory(dest.dirname)

  if source.directory?
    FileUtils.mkdir_p(dest)
    # Copy directory metadata
    FileUtils.chmod(source.stat.mode, dest)
  elsif source.symlink?
    FileUtils.ln_s(File.readlink(source), dest)
  else
    FileUtils.cp(source, dest, preserve: true)
  end

  clear_cache_for(relative_path)
  hooks.trigger(:after_copy_up, path: relative_path, from: source, to: dest)
  dest
end

#create_whiteout(relative_path) ⇒ Object 



779
780
781
782
783
784
785
 
# File 'lib/solis/overlay_fs.rb', line 779

def create_whiteout(relative_path)
  relative_path = normalize_path(relative_path)
  whiteout = writable_path(whiteout_name(relative_path))
  ensure_directory(whiteout.dirname)
  FileUtils.touch(whiteout)
  clear_cache_for(relative_path)
end

#ctime(relative_path) ⇒ Object 



467
468
469
 
# File 'lib/solis/overlay_fs.rb', line 467

def ctime(relative_path)
  stat(relative_path)&.ctime || raise(Errno::ENOENT, relative_path)
end

#delete(relative_path, force: false) ⇒ Object Also known as: rm, unlink 



698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
 
# File 'lib/solis/overlay_fs.rb', line 698

def delete(relative_path, force: false)
  relative_path = normalize_path(relative_path)

  unless exist?(relative_path)
    raise Errno::ENOENT, relative_path unless force
    return
  end

  hooks.trigger(:before_delete, path: relative_path)

  if in_writable_layer?(relative_path)
    full_path = writable_path(relative_path)
    if full_path.directory?
      FileUtils.rm_rf(full_path)
    else
      FileUtils.rm(full_path)
    end
  end

  # Create whiteout if exists in lower layers
  if exists_in_lower_layers?(relative_path)
    create_whiteout(relative_path)
  end

  clear_cache_for(relative_path)
  hooks.trigger(:after_delete, path: relative_path)
end

#delete_recursive(relative_path) ⇒ Object Also known as: rm_rf 



728
729
730
731
732
733
734
735
736
737
738
 
# File 'lib/solis/overlay_fs.rb', line 728

def delete_recursive(relative_path)
  relative_path = normalize_path(relative_path)

  if directory?(relative_path)
    entries(relative_path).each do |entry|
      delete_recursive(entry.relative_path)
    end
  end

  delete(relative_path)
end

#diff(relative_path) ⇒ Object 



866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
 
# File 'lib/solis/overlay_fs.rb', line 866

def diff(relative_path)
  relative_path = normalize_path(relative_path)
  versions = []

  @layers.each do |layer|
    full_path = layer[:path] / relative_path
    if full_path.exist? && full_path.file?
      versions << {
        layer: layer[:label],
        path: full_path,
        content: full_path.read,
        mtime: full_path.mtime,
        size: full_path.size
      }
    end
  end

  versions
end

#directory?(relative_path) ⇒ Boolean 



362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/solis/overlay_fs.rb', line 362

def directory?(relative_path)
  relative_path = normalize_path(relative_path)

  @layers.any? do |layer|
    whiteout = layer[:path] / whiteout_name(relative_path)
    next false if whiteout.exist?

    dir_path = layer[:path] / relative_path
    dir_path.directory?
  end
end

#dirname(relative_path) ⇒ Object 



485
486
487
 
# File 'lib/solis/overlay_fs.rb', line 485

def dirname(relative_path)
  File.dirname(relative_path)
end

#each_directory(relative_path = '.', &block) ⇒ Object 



630
631
632
633
634
635
636
 
# File 'lib/solis/overlay_fs.rb', line 630

def each_directory(relative_path = '.', &block)
  return enum_for(:each_directory, relative_path) unless block_given?

  entries(relative_path).each do |entry|
    yield entry if entry.directory?
  end
end

#each_file(pattern = '**/*', &block) ⇒ Object 



621
622
623
624
625
626
627
628
 
# File 'lib/solis/overlay_fs.rb', line 621

def each_file(pattern = '**/*', &block)
  return enum_for(:each_file, pattern) unless block_given?

  glob(pattern).each do |relative_path|
    next unless file?(relative_path)
    yield relative_path, resolve(relative_path)
  end
end

#empty?(relative_path) ⇒ Boolean 



399
400
401
402
403
404
405
406
407
 
# File 'lib/solis/overlay_fs.rb', line 399

def empty?(relative_path)
  if directory?(relative_path)
    entries(relative_path).empty?
  elsif file?(relative_path)
    size(relative_path) == 0
  else
    raise Errno::ENOENT, relative_path
  end
end

#entries(relative_path = '.') ⇒ Object 



544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
 
# File 'lib/solis/overlay_fs.rb', line 544

def entries(relative_path = '.')
  relative_path = normalize_path(relative_path)
  seen = Set.new
  whiteouts = Set.new
  result = []

  @layers.each do |layer|
    dir_path = layer[:path] / relative_path
    next unless dir_path.directory?

    # Check if this directory is opaque - if so, don't descend to lower layers
    opaque = (dir_path / OPAQUE_MARKER).exist?

    dir_path.children.each do |child|
      name = child.basename.to_s

      # Track whiteouts
      if name.start_with?(WHITEOUT_PREFIX)
        if name == OPAQUE_MARKER
          next
        else
          whiteouts << name.sub(WHITEOUT_PREFIX, '')
          next
        end
      end

      next if seen.include?(name)
      next if whiteouts.include?(name)

      seen << name
      result << Entry.new(
        name: name,
        path: child,
        relative_path: "#{relative_path}/#{name}".sub(%r{^\.?/}, ''),
        layer: layer[:label],
        type: entry_type(child)
      )
    end

    break if opaque
  end

  result.sort_by(&:name)
end

#executable?(relative_path) ⇒ Boolean 



394
395
396
397
 
# File 'lib/solis/overlay_fs.rb', line 394

def executable?(relative_path)
  path = resolve(relative_path)
  path&.executable?
end

#exist?(relative_path) ⇒ Boolean Also known as: exists?

— Existence & Type Checks —



352
353
354
 
# File 'lib/solis/overlay_fs.rb', line 352

def exist?(relative_path)
  !resolve(relative_path).nil?
end

#exists_in_lower_layers?(relative_path) ⇒ Boolean 



940
941
942
943
944
945
946
 
# File 'lib/solis/overlay_fs.rb', line 940

def exists_in_lower_layers?(relative_path)
  relative_path = normalize_path(relative_path)

  readonly_layers.any? do |layer|
    (layer[:path] / relative_path).exist?
  end
end

#extname(relative_path) ⇒ Object 



477
478
479
 
# File 'lib/solis/overlay_fs.rb', line 477

def extname(relative_path)
  File.extname(relative_path)
end

#file?(relative_path) ⇒ Boolean 



357
358
359
360
 
# File 'lib/solis/overlay_fs.rb', line 357

def file?(relative_path)
  path = resolve(relative_path)
  path&.file?
end

#find(relative_path = '.', &block) ⇒ Object 



615
616
617
618
619
 
# File 'lib/solis/overlay_fs.rb', line 615

def find(relative_path = '.', &block)
  results = []
  _find_recursive(normalize_path(relative_path), results, &block)
  results
end

#ftype(relative_path) ⇒ Object

Raises:

  • (Errno::ENOENT) 


471
472
473
474
475
 
# File 'lib/solis/overlay_fs.rb', line 471

def ftype(relative_path)
  path = resolve(relative_path)
  raise Errno::ENOENT, relative_path unless path
  path.ftype
end

#glob(pattern, flags: 0) ⇒ Object 



593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
 
# File 'lib/solis/overlay_fs.rb', line 593

def glob(pattern, flags: 0)
  pattern = normalize_path(pattern)
  seen = Set.new
  whiteouts = collect_whiteouts
  results = []

  @layers.each do |layer|
    Dir.glob(layer[:path] / pattern, flags).each do |full_path|
      relative = Pathname.new(full_path).relative_path_from(layer[:path]).to_s

      next if seen.include?(relative)
      next if whiteouts.include?(relative)
      next if File.basename(relative).start_with?(WHITEOUT_PREFIX)

      seen << relative
      results << relative
    end
  end

  results.sort
end

#identical?(path1, path2) ⇒ Boolean

— Comparison —



858
859
860
861
862
863
864
 
# File 'lib/solis/overlay_fs.rb', line 858

def identical?(path1, path2)
  resolved1 = resolve(path1)
  resolved2 = resolve(path2)

  return false unless resolved1 && resolved2
  FileUtils.identical?(resolved1, resolved2)
end

#in_writable_layer?(relative_path) ⇒ Boolean 



934
935
936
937
938
 
# File 'lib/solis/overlay_fs.rb', line 934

def in_writable_layer?(relative_path)
  layer = writable_layer
  return false unless layer
  (layer[:path] / normalize_path(relative_path)).exist?
end

#lstat(relative_path) ⇒ Object 



435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/solis/overlay_fs.rb', line 435

def lstat(relative_path)
  relative_path = normalize_path(relative_path)

  @layers.each do |layer|
    whiteout = layer[:path] / whiteout_name(relative_path)
    return nil if whiteout.exist?

    full_path = layer[:path] / relative_path
    if full_path.exist? || full_path.symlink?
      return OverlayStat.new(
        full_path.lstat,
        layer: layer[:label],
        real_path: full_path,
        relative_path: relative_path
      )
    end
  end
  nil
end

#make_opaque(relative_path) ⇒ Object 



794
795
796
797
798
799
800
801
 
# File 'lib/solis/overlay_fs.rb', line 794

def make_opaque(relative_path)
  relative_path = normalize_path(relative_path)
  dir_path = writable_path(relative_path)

  ensure_directory(dir_path)
  FileUtils.touch(dir_path / OPAQUE_MARKER)
  clear_cache_for(relative_path)
end

#mkdir(relative_path, mode: 0755) ⇒ Object

— Directory Operations —

Raises:

  • (Errno::EEXIST) 


502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'lib/solis/overlay_fs.rb', line 502

def mkdir(relative_path, mode: 0755)
  relative_path = normalize_path(relative_path)
  path = writable_path(relative_path)

  raise Errno::EEXIST, relative_path if directory?(relative_path)

  remove_whiteout(relative_path)
  FileUtils.mkdir_p(path, mode: mode)
  clear_cache_for(relative_path)
  hooks.trigger(:after_mkdir, path: relative_path)
  path
end

#mkdir_p(relative_path, mode: 0755) ⇒ Object 



515
516
517
518
519
520
521
522
523
 
# File 'lib/solis/overlay_fs.rb', line 515

def mkdir_p(relative_path, mode: 0755)
  relative_path = normalize_path(relative_path)
  path = writable_path(relative_path)

  remove_whiteout(relative_path)
  FileUtils.mkdir_p(path, mode: mode)
  clear_cache_for(relative_path)
  path
end

#move(source, destination) ⇒ Object Also known as: rename 



687
688
689
690
691
692
693
694
695
 
# File 'lib/solis/overlay_fs.rb', line 687

def move(source, destination)
  source = normalize_path(source)
  destination = normalize_path(destination)

  copy(source, destination, preserve: true)
  delete(source)

  writable_path(destination)
end

#mtime(relative_path) ⇒ Object 



459
460
461
 
# File 'lib/solis/overlay_fs.rb', line 459

def mtime(relative_path)
  stat(relative_path)&.mtime || raise(Errno::ENOENT, relative_path)
end

#opaque?(relative_path) ⇒ Boolean 



810
811
812
813
814
815
816
 
# File 'lib/solis/overlay_fs.rb', line 810

def opaque?(relative_path)
  relative_path = normalize_path(relative_path)

  @layers.any? do |layer|
    (layer[:path] / relative_path / OPAQUE_MARKER).exist?
  end
end

#open(relative_path, mode = 'r', **options, &block) ⇒ Object 



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/solis/overlay_fs.rb', line 312

def open(relative_path, mode = 'r', **options, &block)
  relative_path = normalize_path(relative_path)
  writing = mode_writable?(mode)

  if writing
    if exist?(relative_path) && !in_writable_layer?(relative_path)
      # Copy-up needed, but defer until actual write
      path = resolve(relative_path)
      io = OverlayIO.new(
        File.open(path, readable_mode(mode), **options),
        overlay_fs: self,
        relative_path: relative_path,
        mode: mode
      )
    else
      path = writable_path(relative_path)
      ensure_directory(path.dirname)
      remove_whiteout(relative_path)
      io = OverlayIO.new(File.open(path, mode, **options))
    end
  else
    path = resolve(relative_path)
    raise Errno::ENOENT, relative_path unless path
    io = OverlayIO.new(File.open(path, mode, **options))
  end

  if block_given?
    begin
      yield io
    ensure
      io.close unless io.closed?
      clear_cache_for(relative_path) if writing
    end
  else
    io
  end
end

#read(relative_path, **options) ⇒ Object

— File Operations —

Raises:

  • (Errno::ENOENT) 


249
250
251
252
253
254
255
256
 
# File 'lib/solis/overlay_fs.rb', line 249

def read(relative_path, **options)
  path = resolve(relative_path)
  raise Errno::ENOENT, relative_path unless path
  hooks.trigger(:before_read, path: relative_path)
  content = File.read(path, **options)
  hooks.trigger(:after_read, path: relative_path, content: content)
  content
end

#read_binary(relative_path) ⇒ Object 



258
259
260
 
# File 'lib/solis/overlay_fs.rb', line 258

def read_binary(relative_path)
  read(relative_path, mode: 'rb')
end

#readable?(relative_path) ⇒ Boolean 



379
380
381
382
 
# File 'lib/solis/overlay_fs.rb', line 379

def readable?(relative_path)
  path = resolve(relative_path)
  path&.readable?
end

#readlink(relative_path) ⇒ Object

Raises:

  • (Errno::ENOENT) 


756
757
758
759
760
761
 
# File 'lib/solis/overlay_fs.rb', line 756

def readlink(relative_path)
  path = resolve(relative_path)
  raise Errno::ENOENT, relative_path unless path
  raise Errno::EINVAL, relative_path unless path.symlink?
  File.readlink(path)
end

#readonly_layers ⇒ Object 



207
208
209
 
# File 'lib/solis/overlay_fs.rb', line 207

def readonly_layers
  @layers.reject { |l| l[:writable] }
end

#real_path(relative_path) ⇒ Object 



243
244
245
 
# File 'lib/solis/overlay_fs.rb', line 243

def real_path(relative_path)
  resolve(relative_path)&.realpath
end

#realpath(relative_path) ⇒ Object

Raises:

  • (Errno::ENOENT) 


763
764
765
766
767
 
# File 'lib/solis/overlay_fs.rb', line 763

def realpath(relative_path)
  path = resolve(relative_path)
  raise Errno::ENOENT, relative_path unless path
  path.realpath
end

#remove_layer(label_or_path) ⇒ Object 



193
194
195
196
197
198
199
200
201
 
# File 'lib/solis/overlay_fs.rb', line 193

def remove_layer(label_or_path)
  @monitor.synchronize do
    @layers.reject! do |layer|
      layer[:label] == label_or_path || layer[:path].to_s == label_or_path.to_s
    end
    clear_cache
  end
  self
end

#remove_opaque(relative_path) ⇒ Object 



803
804
805
806
807
808
 
# File 'lib/solis/overlay_fs.rb', line 803

def remove_opaque(relative_path)
  relative_path = normalize_path(relative_path)
  opaque = writable_path(relative_path) / OPAQUE_MARKER
  FileUtils.rm(opaque) if opaque.exist?
  clear_cache_for(relative_path)
end

#remove_whiteout(relative_path) ⇒ Object 



787
788
789
790
791
792
 
# File 'lib/solis/overlay_fs.rb', line 787

def remove_whiteout(relative_path)
  relative_path = normalize_path(relative_path)
  whiteout = writable_path(whiteout_name(relative_path))
  FileUtils.rm(whiteout) if whiteout.exist?
  clear_cache_for(relative_path)
end

#resolve(relative_path) ⇒ Object

— Path Resolution —



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/solis/overlay_fs.rb', line 213

def resolve(relative_path)
  relative_path = normalize_path(relative_path)

  return @resolve_cache[relative_path] if @cache_enabled && @resolve_cache.key?(relative_path)

  result = @monitor.synchronize do
    @layers.each do |layer|
      # Check for whiteout first
      whiteout_path = layer[:path] / whiteout_name(relative_path)
      return nil if whiteout_path.exist?

      # Check for opaque parent directory
      return nil if opaque_parent?(layer, relative_path)

      full_path = layer[:path] / relative_path
      return full_path if full_path.exist? || full_path.symlink?
    end
    nil
  end

  @resolve_cache[relative_path] = result if @cache_enabled
  result
end

#rmdir(relative_path) ⇒ Object

Raises:

  • (Errno::ENOENT) 


525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
 
# File 'lib/solis/overlay_fs.rb', line 525

def rmdir(relative_path)
  relative_path = normalize_path(relative_path)

  raise Errno::ENOENT, relative_path unless directory?(relative_path)
  raise Errno::ENOTEMPTY, relative_path unless empty?(relative_path)

  if in_writable_layer?(relative_path)
    FileUtils.rmdir(writable_path(relative_path))
  end

  # If exists in lower layers, create whiteout
  if exists_in_lower_layers?(relative_path)
    create_whiteout(relative_path)
  end

  clear_cache_for(relative_path)
  hooks.trigger(:after_rmdir, path: relative_path)
end

#size(relative_path) ⇒ Object 



455
456
457
 
# File 'lib/solis/overlay_fs.rb', line 455

def size(relative_path)
  stat(relative_path)&.size || raise(Errno::ENOENT, relative_path)
end

#stat(relative_path) ⇒ Object

— File Info —



411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
 
# File 'lib/solis/overlay_fs.rb', line 411

def stat(relative_path)
  relative_path = normalize_path(relative_path)

  return @stat_cache[relative_path] if @cache_enabled && @stat_cache.key?(relative_path)

  @layers.each do |layer|
    whiteout = layer[:path] / whiteout_name(relative_path)
    return nil if whiteout.exist?

    full_path = layer[:path] / relative_path
    if full_path.exist? || full_path.symlink?
      stat = OverlayStat.new(
        full_path.stat,
        layer: layer[:label],
        real_path: full_path,
        relative_path: relative_path
      )
      @stat_cache[relative_path] = stat if @cache_enabled
      return stat
    end
  end
  nil
end

#symlink(target, link_path) ⇒ Object Also known as: ln_s

— Symlinks —



743
744
745
746
747
748
749
750
751
752
753
 
# File 'lib/solis/overlay_fs.rb', line 743

def symlink(target, link_path)
  link_path = normalize_path(link_path)
  path = writable_path(link_path)

  ensure_directory(path.dirname)
  remove_whiteout(link_path)

  FileUtils.ln_s(target, path)
  clear_cache_for(link_path)
  path
end

#symlink?(relative_path) ⇒ Boolean 



374
375
376
377
 
# File 'lib/solis/overlay_fs.rb', line 374

def symlink?(relative_path)
  path = resolve(relative_path)
  path&.symlink?
end

#to_s ⇒ Object Also known as: inspect

— Utility —



965
966
967
968
 
# File 'lib/solis/overlay_fs.rb', line 965

def to_s
  layers_desc = @layers.map { |l| "#{l[:label]}#{l[:writable] ? ' (rw)' : ''}" }
  "#<OverlayFS layers=[#{layers_desc.join(' -> ')}]>"
end

#touch(relative_path, mtime: nil) ⇒ Object 



834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
 
# File 'lib/solis/overlay_fs.rb', line 834

def touch(relative_path, mtime: nil)
  relative_path = normalize_path(relative_path)

  if exist?(relative_path)
    copy_up(relative_path) unless in_writable_layer?(relative_path)
    path = writable_path(relative_path)
  else
    path = writable_path(relative_path)
    ensure_directory(path.dirname)
    remove_whiteout(relative_path)
  end

  if mtime
    FileUtils.touch(path, mtime: mtime)
  else
    FileUtils.touch(path)
  end

  clear_cache_for(relative_path)
  path
end

#tree(relative_path = '.', depth: nil, prefix: '') ⇒ Object 



975
976
977
978
979
 
# File 'lib/solis/overlay_fs.rb', line 975

def tree(relative_path = '.', depth: nil, prefix: '')
  output = []
  _tree_recursive(normalize_path(relative_path), output, depth, prefix, 0)
  output.join("\n")
end

#which_layer(relative_path) ⇒ Object

— Layer Inspection —



921
922
923
924
925
926
927
928
929
930
931
932
 
# File 'lib/solis/overlay_fs.rb', line 921

def which_layer(relative_path)
  relative_path = normalize_path(relative_path)

  @layers.each do |layer|
    whiteout = layer[:path] / whiteout_name(relative_path)
    return nil if whiteout.exist?

    full_path = layer[:path] / relative_path
    return layer[:label] if full_path.exist?
  end
  nil
end

#whiteout?(relative_path) ⇒ Boolean

— Whiteouts & Opaque Directories —



771
772
773
774
775
776
777
 
# File 'lib/solis/overlay_fs.rb', line 771

def whiteout?(relative_path)
  relative_path = normalize_path(relative_path)

  @layers.any? do |layer|
    (layer[:path] / whiteout_name(relative_path)).exist?
  end
end

#writable?(relative_path) ⇒ Boolean 



384
385
386
387
388
389
390
391
392
 
# File 'lib/solis/overlay_fs.rb', line 384

def writable?(relative_path)
  return false unless writable_layer

  if exist?(relative_path)
    in_writable_layer?(relative_path) || copy_up_possible?(relative_path)
  else
    true  # Can create new file
  end
end

#writable_layer ⇒ Object 



203
204
205
 
# File 'lib/solis/overlay_fs.rb', line 203

def writable_layer
  @layers.find { |l| l[:writable] }
end

#writable_path(relative_path) ⇒ Object

Raises:



237
238
239
240
241
 
# File 'lib/solis/overlay_fs.rb', line 237

def writable_path(relative_path)
  layer = writable_layer
  raise ReadOnlyError, "No writable layer configured" unless layer
  layer[:path] / normalize_path(relative_path)
end

#write(relative_path, content, **options) ⇒ Object 



262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/solis/overlay_fs.rb', line 262

def write(relative_path, content, **options)
  relative_path = normalize_path(relative_path)
  hooks.trigger(:before_write, path: relative_path, content: content)

  path = writable_path(relative_path)
  ensure_directory(path.dirname)
  remove_whiteout(relative_path)

  File.write(path, content, **options)
  clear_cache_for(relative_path)

  hooks.trigger(:after_write, path: relative_path, real_path: path)
  path
end

#write_binary(relative_path, content) ⇒ Object 



277
278
279
 
# File 'lib/solis/overlay_fs.rb', line 277

def write_binary(relative_path, content)
  write(relative_path, content, mode: 'wb')
end