gubbins-fs 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +3 -0
  3. data/LICENSE +289 -0
  4. data/README.md +128 -0
  5. data/lib/fs/atomic_write.rb +121 -0
  6. data/lib/fs/concerns/argument_validation.rb +140 -0
  7. data/lib/fs/concerns/file_dsl_methods.rb +471 -0
  8. data/lib/fs/concerns/required_arguments.rb +141 -0
  9. data/lib/fs/directory/accessibility_check.rb +89 -0
  10. data/lib/fs/directory.rb +497 -0
  11. data/lib/fs/errors.rb +491 -0
  12. data/lib/fs/file.rb +1524 -0
  13. data/lib/fs/file_variant_builder.rb +269 -0
  14. data/lib/fs/file_variant_proxy.rb +253 -0
  15. data/lib/fs/files/csv.rb +26 -0
  16. data/lib/fs/files/gif.rb +10 -0
  17. data/lib/fs/files/image.rb +390 -0
  18. data/lib/fs/files/jpg.rb +36 -0
  19. data/lib/fs/files/json.rb +24 -0
  20. data/lib/fs/files/pdf.rb +231 -0
  21. data/lib/fs/files/pdf_collection.rb +64 -0
  22. data/lib/fs/files/png.rb +10 -0
  23. data/lib/fs/files/text.rb +13 -0
  24. data/lib/fs/files/tiff.rb +24 -0
  25. data/lib/fs/files/zip.rb +123 -0
  26. data/lib/fs/lockfile_sweeper.rb +70 -0
  27. data/lib/fs/tempfile_sweeper.rb +79 -0
  28. data/lib/fs/testing/mock/fs/configurator.rb +223 -0
  29. data/lib/fs/testing/mock/fs/dirs/directory.rb +41 -0
  30. data/lib/fs/testing/mock/fs/dsl.rb +81 -0
  31. data/lib/fs/testing/mock/fs/file.rb +60 -0
  32. data/lib/fs/testing/mock/fs/file_klass_mock.rb +350 -0
  33. data/lib/fs/testing/mock/fs/files/jpg.rb +14 -0
  34. data/lib/fs/testing/mock/fs/files/pdf.rb +19 -0
  35. data/lib/fs/testing/mock/fs/files/png.rb +12 -0
  36. data/lib/fs/testing/mock/fs/files/tiff.rb +12 -0
  37. data/lib/fs/testing/mock/fs/files/zip.rb +23 -0
  38. data/lib/fs/testing.rb +17 -0
  39. data/lib/fs/version.rb +3 -0
  40. data/lib/fs.rb +26 -0
  41. data/lib/gubbins/fs.rb +4 -0
  42. metadata +124 -0
@@ -0,0 +1,497 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "pathname"
4
+ require "fileutils"
5
+ require "active_support/concern"
6
+ require "active_support/core_ext/class/attribute"
7
+ require "active_support/core_ext/module/delegation"
8
+ require "active_support/core_ext/object/blank"
9
+ require "shell/zip"
10
+ require_relative "errors"
11
+ require_relative "concerns/argument_validation"
12
+ require_relative "concerns/required_arguments"
13
+ require_relative "directory/accessibility_check"
14
+
15
+ module Fs
16
+ class Directory
17
+ include Fs::Concerns::RequiredArguments
18
+ include Fs::Concerns::ArgumentValidation
19
+
20
+ WHEN_MISSING_MODES = %i[create raise ignore].freeze
21
+
22
+ attr_reader :parent
23
+ attr_reader :dynamic_base_path
24
+
25
+ delegate :exist?, :directory?, :glob, :symlink?, :children, :rmdir, :rmtree, :join,
26
+ to: :path
27
+
28
+ class << self
29
+ # @return [Class] the class of the parent {Directory}, if given
30
+ attr_reader :parent_klass
31
+ # @return [Proc] a Proc responsible for assembling the arguments
32
+ # to the parent {Directory}, if there is one and if it requires
33
+ # arguments. Is executed in the instance scope of the current
34
+ # {Directory}.
35
+ attr_reader :parent_klass_argument_proc
36
+ # @return [Symbol] setting for how to handle missing base paths
37
+ attr_reader :on_base_path_missing
38
+ # @return [Symbol] setting for how to handle missing instance paths
39
+ attr_reader :on_instance_path_missing
40
+ # @return [Class, nil] an anonymous subclass of `self` used to
41
+ # locate this directory at a legacy location, if configured
42
+ attr_reader :legacy_klass
43
+ # @return [Boolean] whether instantiating this Directory should
44
+ # itself relocate content found via `legacy_klass` - see {.legacy}
45
+ attr_reader :legacy_migrate
46
+
47
+ # This is a hook Ruby calls whenever a subclass is created. We use
48
+ # the opportunity to copy our class instance variables over to the
49
+ # new class, mirroring `Fs::Concerns::FileDslMethods#inherited`.
50
+ #
51
+ # Without this, a concrete subclass's `base_path`/`requires_arguments`/
52
+ # etc. would not be visible on a further subclass of it - which
53
+ # `legacy` (below) relies on: its block builds an anonymous
54
+ # subclass of the current, already-configured class.
55
+ #
56
+ # @return [void]
57
+ def inherited(subclass)
58
+ subclass.instance_variable_set(:@raw_base_path, @raw_base_path)
59
+ subclass.instance_variable_set(:@parent_klass, @parent_klass)
60
+ subclass.instance_variable_set(:@parent_klass_argument_proc, @parent_klass_argument_proc)
61
+ subclass.instance_variable_set(:@on_base_path_missing, @on_base_path_missing)
62
+ subclass.instance_variable_set(:@on_instance_path_missing, @on_instance_path_missing)
63
+ subclass.instance_variable_set(:@required_arguments, required_arguments)
64
+
65
+ # `root_path` is deliberately not copied: it is a `class_attribute`, looked up
66
+ # through the superclass chain on every read. A copy made here would freeze the
67
+ # value at class-definition time, ie. before an initializer had a chance to set it.
68
+ end
69
+
70
+ # Declare where this directory used to live before some past
71
+ # reorganization (eg. before a Teams::Merger reassigned a
72
+ # Member to a different Team).
73
+ #
74
+ # The block is used to build an anonymous subclass of the current
75
+ # class (same pattern as `Fs::File`'s `variant`'s `define`) -
76
+ # override `#path` using plain Ruby and the class's own inherited
77
+ # `base_path`/`requires_arguments`.
78
+ #
79
+ # Careful with `super` inside that `#path` override: the legacy
80
+ # klass's superclass is *this* class, not `Fs::Directory` - if this
81
+ # class itself already overrides `#path` (the usual case), `super`
82
+ # calls that override rather than `Fs::Directory#path`, applying
83
+ # its logic a second time. Build the full path from `base_path`
84
+ # directly instead.
85
+ #
86
+ # By default, declaring `legacy` here does *not* make instantiating
87
+ # this Directory relocate anything - it only makes `legacy_klass`
88
+ # available, typically so a {Fs::File} stored in this Directory can
89
+ # point its own `legacy` block at it (see {Fs::File.legacy}) and
90
+ # migrate exactly the one file being accessed. Migrating a whole
91
+ # Directory is wrong whenever its legacy location was shared by
92
+ # several records that must move independently (eg. one directory
93
+ # per Member used to hold every one of that Member's files, each
94
+ # now belonging in its own, per-record Directory) - File-level
95
+ # migration handles that correctly, Directory-level does not.
96
+ #
97
+ # Pass `migrate: true` to opt into Directory-level self-healing
98
+ # anyway - appropriate when the legacy and current locations are
99
+ # genuinely both directory-shaped 1:1 (eg. a directory that only
100
+ # changed its base path, not what it groups together), where
101
+ # relocating the whole thing at once is a worthwhile perf win over
102
+ # migrating file-by-file.
103
+ #
104
+ # @param migrate [Boolean] automatically relocate the whole
105
+ # directory to its current location on first instantiation
106
+ # @yield class-eval'd to build the anonymous subclass
107
+ # @return [void]
108
+ def legacy(migrate: false, &block)
109
+ @legacy_klass = Class.new(self, &block)
110
+ @legacy_migrate = migrate
111
+ end
112
+
113
+ # Combined getter/setter for an optional parent {Directory}
114
+ #
115
+ # @param klass [Class] Fs::Directory-subclass of the parent {Directory}
116
+ def below(klass = nil)
117
+ if klass
118
+ if klass.required_arguments
119
+ raise ArgumentError, "You cannot nest a Directory below another that takes arguments"
120
+ end
121
+
122
+ @parent_klass = klass
123
+ else
124
+ @parent_klass
125
+ end
126
+ end
127
+
128
+ # Combined getter/setter
129
+ #
130
+ # Resolved on every read, so that {Fs::Directory.root_path} may be
131
+ # configured after the subclasses have been defined.
132
+ def base_path(value = nil)
133
+ if value
134
+ @raw_base_path = value
135
+ # `to_s`: for a Pathname, `present?` asks the file system unless ActiveSupport 7.1's
136
+ # `pathname/blank` is loaded, and a path to an empty directory or file counts as "blank"
137
+ elsif @raw_base_path.to_s.present?
138
+ parent_klass.present? ? parent_klass.base_path + @raw_base_path : Pathname(root_path).join(@raw_base_path)
139
+ end
140
+ end
141
+
142
+ # @param value [Symbol] `:create`, `:raise` or `:ignore`
143
+ def on_base_path_missing(value = nil)
144
+ if value
145
+ ensure_value_is_one_of value => WHEN_MISSING_MODES
146
+ @on_base_path_missing = value
147
+ else
148
+ @on_base_path_missing || :create
149
+ end
150
+ end
151
+
152
+ # @param value [Symbol] `:create`, `:raise` or `:ignore`
153
+ def on_instance_path_missing(value = nil)
154
+ if value
155
+ ensure_value_is_one_of value => WHEN_MISSING_MODES
156
+ @on_instance_path_missing = value
157
+ else
158
+ @on_instance_path_missing || :create
159
+ end
160
+ end
161
+ end
162
+
163
+ # The directory relative `base_path`s are anchored at; absolute ones
164
+ # ignore it. Defaults to the file system root, so that relative paths
165
+ # are never silently tied to a particular application layout.
166
+ #
167
+ # Inherited by subclasses unless they set their own, which then applies
168
+ # to that subclass and its descendants only. Set it on `Fs::Directory`
169
+ # itself to configure it globally.
170
+ #
171
+ # @!scope class
172
+ # @return [Pathname, String]
173
+ class_attribute :root_path, instance_accessor: false, instance_predicate: false,
174
+ default: Pathname.new("/")
175
+
176
+ def self.to_s
177
+ base_path.to_s
178
+ end
179
+
180
+ # Does the base path exist?
181
+ #
182
+ # `on_base_path_missing` settings do not apply
183
+ #
184
+ # @return [Boolean]
185
+ def self.exist?
186
+ base_path.exist?
187
+ end
188
+
189
+ # Remove all contents from base_path
190
+ #
191
+ # @return [void]
192
+ def self.empty!
193
+ return unless exist?
194
+
195
+ Dir.each_child(base_path) do |entry|
196
+ FileUtils.rm_rf(::File.join(base_path, entry))
197
+ end
198
+ end
199
+
200
+ # Does the instance path exist?
201
+ #
202
+ # `on_base_path_missing` and `on_instance_path_missing` settings
203
+ # do not apply
204
+ #
205
+ # @return [Boolean]
206
+ def self.instance_path_exist?(**kargs)
207
+ new(when_missing: :ignore, **kargs).exist?
208
+ end
209
+
210
+ # Takes a block and creates a directory instance for the duration
211
+ # of that block
212
+ #
213
+ # When the given block returns, the directory and its contents
214
+ # are removed.
215
+ #
216
+ # If configured, the base_path is ignored and replaced by a
217
+ # temporary base directory managed by `Dir.mktmpdir`.
218
+ #
219
+ # @param kargs which arguments are required dependeds on the
220
+ # `Fs::Directory` subclass configuration
221
+ # @return [void]
222
+ def self.temp_dir_for(**kargs)
223
+ if block_given?
224
+ Dir.mktmpdir do |tmp_base_path|
225
+ dir = new(base_path: tmp_base_path, **kargs)
226
+ yield dir
227
+ end
228
+ else
229
+ new(base_path: Dir.mktmpdir, **kargs)
230
+ end
231
+ end
232
+
233
+ # @param when_missing [Symbol] when base or instance path do not
234
+ # exist, `:create`, `:raise` or `:ignore`. Overrides class settings
235
+ # for `on_base_path_missing` and `on_instance_path_missing`
236
+ # @param base_path [String, #to_s] a dynamic base_path; useful for
237
+ # one-off wrappings of directory paths in a generic Fs::Directory
238
+ # @option **kargs which arguments are required dependeds on the
239
+ # `Fs::Directory` subclass configuration
240
+ def initialize(when_missing: nil, base_path: nil, **kargs)
241
+ @parent = self.class.parent_klass.new if self.class.parent_klass
242
+ @dynamic_base_path = base_path ? Pathname.new(base_path.to_s) : nil
243
+
244
+ process_required_arguments(**kargs)
245
+
246
+ # A directory wrapped via `base_path:` is not one of our configured base directories
247
+ ensure_accessibility_of(self.base_path,
248
+ when_missing: when_missing || self.class.on_base_path_missing,
249
+ base: dynamic_base_path.nil?)
250
+
251
+ instance_path_when_missing = when_missing || self.class.on_instance_path_missing
252
+
253
+ if self.class.legacy_klass && self.class.legacy_migrate && instance_path_when_missing != :ignore
254
+ migrate_from_legacy_location!
255
+ end
256
+
257
+ ensure_accessibility_of(path, when_missing: instance_path_when_missing)
258
+ end
259
+
260
+ # @return [Pathname]
261
+ def base_path
262
+ @dynamic_base_path || self.class.base_path
263
+ end
264
+
265
+ # Remove all contents from this directory
266
+ #
267
+ # @return [void]
268
+ def empty!
269
+ return unless exist?
270
+
271
+ Dir.each_child(path) do |entry|
272
+ FileUtils.rm_rf(::File.join(path, entry))
273
+ end
274
+ end
275
+
276
+ # Creates a subdirectory
277
+ #
278
+ # @param dirpath [String]
279
+ # @return [Fs::Directory]
280
+ def mkdir(dirpath)
281
+ path.join(dirpath).mkdir
282
+
283
+ Fs::Directory.new(base_path: path.join(dirpath))
284
+ end
285
+
286
+ # Creates a subdirectory, plus any missing intermediate subdirectories
287
+ #
288
+ # @param dirpath [String]
289
+ # @return [Fs::Directory]
290
+ def mkpath(dirpath)
291
+ path.join(dirpath).mkpath
292
+
293
+ Fs::Directory.new(base_path: path.join(dirpath))
294
+ end
295
+
296
+ # @return [Pathname]
297
+ def parent_path
298
+ parent.present? ? parent.path : Pathname.new("")
299
+ end
300
+
301
+ # @return [Pathname]
302
+ def path
303
+ parent_path + base_path
304
+ end
305
+
306
+ # @return [Array<Pathname>]
307
+ def subdirectories
308
+ path.children.select(&:directory?)
309
+ end
310
+
311
+ # @return [Pathname]
312
+ def to_path
313
+ path
314
+ end
315
+
316
+ # @return [String]
317
+ def to_s
318
+ path.to_s
319
+ end
320
+
321
+ # Overload for adding paths and alikes
322
+ #
323
+ # Note that you will receive back a generic `Fs::Directory`
324
+ # instance, even when called on a specific subclass.
325
+ #
326
+ # @param other [Path, #to_path]
327
+ # @return [Fs::Directory]
328
+ def +(other)
329
+ other = other.to_path if other.respond_to?(:to_path)
330
+
331
+ Fs::Directory.new(base_path: path + other)
332
+ end
333
+
334
+ alias_method :/, :+
335
+
336
+ # Recursively copy this directory at `path` to `to`
337
+ #
338
+ # The behaviour depends on whether `to` exists. If
339
+ # you copy `reports` to `/foo`:
340
+ #
341
+ # * if `/foo` is an existing directory, `/foo/reports`
342
+ # will be created
343
+ # * if `/foo` does not exist, `/foo` will be created
344
+ #
345
+ # @param to [String, Pathname, #to_path]
346
+ def copy_to(to)
347
+ FileUtils.cp_r(path, get_path_from(to))
348
+ end
349
+
350
+ # Move this directory at `path` to `to`
351
+ #
352
+ # The behaviour depends on whether `to` exists. If
353
+ # you move `reports` to `/foo`:
354
+ #
355
+ # * if `/foo` is an existing directory, `/foo/reports`
356
+ # will be created
357
+ # * if `/foo` does not exist, `/foo` will be created
358
+ #
359
+ # @param to [String, Pathname, #to_path]
360
+ def move_to(to)
361
+ FileUtils.mv(path, get_path_from(to))
362
+ end
363
+
364
+ # Create a symlink here at our `path` that points to
365
+ # the existing source at `source`
366
+ #
367
+ # @param source [String, Pathname, #to_path]
368
+ def symlink_from(source)
369
+ FileUtils.ln_s(get_path_from(source), path)
370
+ end
371
+
372
+ # Create a symlink at `to` that points to us as the
373
+ # existing source.
374
+ #
375
+ # @param from [String, Pathname, #to_path]
376
+ def symlink_to(to)
377
+ FileUtils.ln_s(path, get_path_from(to))
378
+ end
379
+
380
+ # Creates this directory, if it does not already exist, and
381
+ # tests r/w permissions
382
+ #
383
+ # Useful for directories which were initialized with
384
+ # `on_instance_path_missing :ignore` and might not exist
385
+ #
386
+ # @raise [Errors::Fs::ReadWrite]
387
+ # @return [Boolean]
388
+ def create
389
+ ensure_accessibility_of(path, when_missing: :create)
390
+ end
391
+
392
+ # Create a zipfile at `path` from the current `Fs::Directory`
393
+ # contents
394
+ #
395
+ # @param path [Pathname, String, Fs::File]
396
+ # @param relative_to [Pathname, String, Fs::File, Symbol] store
397
+ # subdirectories and files relative to this path instead of the
398
+ # current working directory. Set to `:target` to use `directory_path`
399
+ # @option **kargs passed on to {Shell::Zip.from_directory}
400
+ # @return [Shell::Command::Result]
401
+ def to_zip(path, relative_to: :target, **kargs)
402
+ Shell::Zip.from_directory(self, to: path, relative_to: relative_to, **kargs)
403
+ end
404
+
405
+ # Create a temporary zipfile from the current `Fs::Directory`
406
+ # contents and yields it to a given block
407
+ #
408
+ # @param relative_to [Pathname, String, Fs::File, Symbol] store
409
+ # subdirectories and files relative to this path instead of the
410
+ # current working directory. Set to `:target` to use `directory_path`
411
+ # @option **kargs passed on to {Shell::Zip.from_directory}
412
+ # @yield [Fs::File]
413
+ # @return the return value of the given block
414
+ def to_temp_zip(relative_to: :target, **kargs)
415
+ Fs::File.create_temp do |temp_file|
416
+ # `zip` does not like it if a 0-byte target file already exists;
417
+ # it complains about an invalid target.
418
+ temp_file.delete
419
+
420
+ to_zip(temp_file, relative_to: relative_to, **kargs)
421
+
422
+ yield(temp_file)
423
+ end
424
+ end
425
+
426
+ # Year / month / day
427
+ #
428
+ # Helper for producing the common subdirectory pattern
429
+ #
430
+ # @param date_or_time [Date, Time]
431
+ # @return [String]
432
+ def ymd(date_or_time = Time.now)
433
+ "#{date_or_time.year}/#{date_or_time.month}/#{date_or_time.day}"
434
+ end
435
+
436
+ private
437
+
438
+ # Makes sure `path` is a directory we can read and write, creating it if told to
439
+ #
440
+ # @param path [Pathname]
441
+ # @param when_missing [Symbol] one of {WHEN_MISSING_MODES}: what to do if `path` does not
442
+ # exist. With `:ignore`, nothing is checked at all.
443
+ # @param base [Boolean] is `path` a configured base directory? Decides which
444
+ # exceptions are raised, see {AccessibilityCheck}.
445
+ # @return [true, nil] `nil` if `when_missing` is `:ignore`
446
+ # @raise [Errors::Fs::BaseDirectory, Errors::Fs::ReadWrite]
447
+ # @raise [ArgumentError] on an unknown `when_missing`
448
+ def ensure_accessibility_of(path, when_missing: :raise, base: false)
449
+ ensure_value_is_one_of when_missing => WHEN_MISSING_MODES
450
+ return nil if when_missing == :ignore
451
+
452
+ AccessibilityCheck.new(path, when_missing: when_missing, base: base).run
453
+ end
454
+
455
+ # @param arg [#to_path, Object]
456
+ # @return [String, Object] `arg.to_path` if `arg` responds to it, else `arg` unchanged
457
+ def get_path_from(arg)
458
+ arg.respond_to?(:to_path) ? arg.to_path : arg
459
+ end
460
+
461
+ # No-op in the overwhelming majority of cases where nothing needs
462
+ # migrating - runs on every instantiation of a class with a
463
+ # `legacy(migrate: true)` block, so it must stay cheap and silent
464
+ # when there's nothing to do.
465
+ #
466
+ # Checks for a non-empty `path`, not merely an existing one: this
467
+ # method itself always runs before `ensure_accessibility_of(path)`
468
+ # (below), but that guarantee only covers the current call -
469
+ # `ensure_accessibility_of` auto-creates a missing directory as a
470
+ # side effect of *any* prior instantiation of this class, migration
471
+ # or not (eg. simply checking whether a not-yet-attached record has
472
+ # a directory). Treating mere existence as "already migrated" would
473
+ # permanently wedge the migration behind such an empty directory.
474
+ #
475
+ # @return [void]
476
+ def migrate_from_legacy_location!
477
+ return if path.exist? && !Dir.empty?(path.to_s)
478
+
479
+ legacy_path = self.class.legacy_klass.new(when_missing: :ignore, **required_arguments_given).path
480
+
481
+ return unless legacy_path.exist? && legacy_path != path
482
+
483
+ # `path` may already exist as an empty, auto-vivified directory
484
+ # (see above) - if left in place, `FileUtils.mv` would move
485
+ # `legacy_path` *into* it (nesting) rather than renaming it, since
486
+ # `mv` targets an existing directory by nesting. `rmdir` only
487
+ # succeeds on an empty directory, matching the guard above.
488
+ path.rmdir if path.exist?
489
+ path.dirname.mkpath
490
+ FileUtils.mv(legacy_path.to_s, path.to_s)
491
+ rescue Errno::ENOENT
492
+ # Lost a race with another process/thread doing the same migration
493
+ # concurrently - fine, ensure_accessibility_of below finds `path`
494
+ # already present.
495
+ end
496
+ end
497
+ end