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
data/lib/fs/file.rb ADDED
@@ -0,0 +1,1524 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+ require "tempfile"
5
+ require "active_support"
6
+ require "active_support/core_ext/module/delegation"
7
+ require "active_support/core_ext/object/blank"
8
+ require "active_support/core_ext/string/inflections"
9
+ require "shell/base_64"
10
+ require "shell/clam_av"
11
+ require "shell/file"
12
+ require "shell/open_ssl"
13
+ require_relative "file_variant_builder"
14
+ require_relative "file_variant_proxy"
15
+ require_relative "concerns/file_dsl_methods"
16
+ require_relative "concerns/required_arguments"
17
+
18
+ module Fs
19
+ # `Fs::File` represents a file on disk and provides methods to operate on it.
20
+ #
21
+ # Create subclasses for specific file types such as `Fs::Files::Text`, `Fs::Files::JPG`
22
+ # or `Fs::Files::PDF` to provide capabilities for these file types, such as thumbnailing
23
+ # for images or text extraction for PDFs.
24
+ #
25
+ # You can then subclass these file types into context-specific files, such as a
26
+ # `Fs::Files::ProjectPdf` that inherits from `Fs::Files::PDF`, to encode their
27
+ # directory locations, naming schemes and so on.
28
+ #
29
+ # Basic interface
30
+ # ---------------
31
+ #
32
+ # The basic interface is the same for all `Fs::File` classes:
33
+ #
34
+ # ```ruby
35
+ # # Initialize a new object for a file that does or does not yet exist on disk
36
+ # file = Fs::File.new(path: "/path/to/file")
37
+ #
38
+ # # Use #load for a file that should already exist
39
+ # file = Fs::File.load(path: "/path/to/file")
40
+ #
41
+ # # Use #create for a file that does not yet exist
42
+ # content = "lorem ipsum dolor"
43
+ # file =
44
+ # Fs::File.create(path: "/path/to/file") do |f|
45
+ # f << content
46
+ # end
47
+ #
48
+ # # or alternatively:
49
+ # file = Fs::File.create(path: "/path/to/file", content: content)
50
+ # ```
51
+ #
52
+ # Creating basic subclasses with the DSL
53
+ # --------------------------------------
54
+ #
55
+ # Let's assume our application creates a report CSV file for every {Project} and
56
+ # stores it in `#{Fs::Directory.root_path}/project_reports/<project id>/report_<project id>.csv`.
57
+ #
58
+ # In this example we will create three classes:
59
+ #
60
+ # 1. a `Fs::CsvFile` class to represent CSV files in general
61
+ # 2. `Fs::Dirs::ProjectReports` to represent the directory our reports are stored in
62
+ # 3. `Fs::Files::ProjectReportCsv` to represent our report files specifically
63
+ #
64
+ # We begin by subclassing `Fs::File` for our general CSV class:
65
+ #
66
+ # ```ruby
67
+ # require 'csv'
68
+ #
69
+ # module Fs
70
+ # module Files
71
+ # class Csv < Fs::File
72
+ # extension :csv
73
+ # end
74
+ # end
75
+ # end
76
+ # ```
77
+ #
78
+ # Our class now knows its expected file type:
79
+ #
80
+ # ```ruby
81
+ # Fs::Files::Csv.load(path: "/some/test.csv")
82
+ # # => Fs::Files::Csv
83
+ #
84
+ # Fs::Files::Csv.load(path: "/some/image.jpg")
85
+ # # => Errors::Fs::Validation::UnsupportedExtension
86
+ # ```
87
+ #
88
+ # By the way, you can pass multiple extensions to `extension`. When validating existing
89
+ # files, all of them will be accepted; when creating a new file, the first extension will
90
+ # be used. You can also skip `extension` completely.
91
+ #
92
+ # Additional options for validating files are `mime_type` and `encoding`:
93
+ #
94
+ # ```ruby
95
+ # require 'csv'
96
+ #
97
+ # module Fs
98
+ # module Files
99
+ # class CsvFile < Fs::File
100
+ # extension :csv
101
+ # mime_type "application/csv", /^text\//
102
+ # encoding "utf-8", /ascii/
103
+ # end
104
+ # end
105
+ # end
106
+ # ```
107
+ #
108
+ # Both settings accept strings as well as regular expressions.
109
+ #
110
+ # Lets give it a method for parsing the CSV. We have access to {Fs::File#path}, which is
111
+ # all we really need:
112
+ #
113
+ # ```ruby
114
+ # require 'csv'
115
+ #
116
+ # module Fs
117
+ # module Files
118
+ # class CsvFile < Fs::File
119
+ # extension :csv
120
+ #
121
+ # def content(**parser_options)
122
+ # CSV.read(path, **parser_options)
123
+ # end
124
+ # end
125
+ # end
126
+ # end
127
+ # ```
128
+ #
129
+ # Now we have something that reads CSV files; we ignore writing for the moment.
130
+ #
131
+ # ```ruby
132
+ # Fs::Files::Csv.load(path: "/some/test.csv").content
133
+ # # => Array
134
+ # ```
135
+ #
136
+ # Step 2 is our `Fs::Directory` subclass to represent the storage location at `project_reports/`.
137
+ #
138
+ # ```ruby
139
+ # module Fs
140
+ # module Dirs
141
+ # class ProjectReports < Fs::Directory
142
+ # base_path "project_reports"
143
+ # end
144
+ # end
145
+ # end
146
+ # ```
147
+ #
148
+ # Note that relative paths are anchored at `Fs::Directory.root_path` (default `/`); absolute ones,
149
+ # ie. `base_path "/project_reports"`, ignore it.
150
+ #
151
+ # This gives us a class that knows where project reports are stored in general:
152
+ #
153
+ # ```ruby
154
+ # Fs::Dirs::ProjectReports.base_path
155
+ # # => #<Pathname:/app/storage/project_reports>
156
+ #
157
+ # # We can also instantiate our directory class, but the path remains the same so far:
158
+ # Fs::Dirs::ProjectReports.new.path
159
+ # # => #<Pathname:/app/storage/project_reports>
160
+ # ```
161
+ #
162
+ # But what about the directory for a _specific_ report, ie. `project_reports/15/`?
163
+ # That's easily done - someone just needs to pass in the {Project} so that we can
164
+ # get the ID:
165
+ #
166
+ # ```ruby
167
+ # module Fs
168
+ # module Dirs
169
+ # class ProjectReports < Fs::Directory
170
+ # base_path "project_reports"
171
+ # requires_arguments project: "Project"
172
+ #
173
+ # def path
174
+ # super/project.id.to_s
175
+ # end
176
+ # end
177
+ # end
178
+ # end
179
+ # ```
180
+ #
181
+ # We configured it to require a `:project` parameter of type `Project`. We then
182
+ # use that passed-in project to overload the default `path`. Now `base_path` and our
183
+ # instances `#path` differ:
184
+ #
185
+ # ```ruby
186
+ # Fs::Dirs::ProjectReports.base_path
187
+ # # => #<Pathname:/app/storage/project_reports>
188
+ #
189
+ # Fs::Dirs::ProjectReports.new(project: Project.last).path
190
+ # # => #<Pathname:/app/storage/project_reports/15>
191
+ # ```
192
+ #
193
+ # We are now ready to create our `ProjectReportCsv` and configure it with our new directory:
194
+ #
195
+ # ```ruby
196
+ # module Fs
197
+ # module Files
198
+ # class ProjectReportCsv < Fs::Files::Csv
199
+ # directory Fs::Dirs::ProjectReports
200
+ # end
201
+ # end
202
+ # end
203
+ # ```
204
+ #
205
+ # Something is missing: the directory requires the `:project` parameter for `#new`, so our file
206
+ # needs it as well:
207
+ #
208
+ # ```ruby
209
+ # module Fs
210
+ # module Files
211
+ # class ProjectReportCsv < Fs::Files::Csv
212
+ # directory Fs::Dirs::ProjectReports
213
+ # requires_arguments project: "Project"
214
+ # end
215
+ # end
216
+ # end
217
+ # ```
218
+ #
219
+ # The `:project` parameter is passed along automatically. Our class now knows the path from the
220
+ # directory, and the file extension from its parent class `Fs::CsvFile` - all that is missing is the
221
+ # basename (filename without extension):
222
+ #
223
+ # ```ruby
224
+ # project = Project.last
225
+ # Fs::Files::ProjectReportCsv.load(project: project,
226
+ # basename: "report_#{project.id}")
227
+ # ```
228
+ #
229
+ # But since we already have everything to determine the basename ourselves, lets provide a `get_path_from`
230
+ # block to do so:
231
+ #
232
+ # ```ruby
233
+ # module Fs
234
+ # module Files
235
+ # class ProjectReportCsv < Fs::CsvFile
236
+ # directory Fs::Dirs::ProjectReports
237
+ # requires_arguments project: "Project"
238
+ #
239
+ # get_path_from do
240
+ # directory_path/"report_#{project.id}"
241
+ # end
242
+ # end
243
+ # end
244
+ # end
245
+ # ```
246
+ #
247
+ # We now have a class that represents a specific kind of CSV, where it is located, how it
248
+ # should be named and provides a method for reading it:
249
+ #
250
+ # ```ruby
251
+ # file = Fs::Files::ProjectReportCsv.load(project: Project.last)
252
+ #
253
+ # file.path
254
+ # # => #<Pathname:/app/storage/project_reports/15/report_15.csv>
255
+ # file.content
256
+ # # => Array
257
+ # ```
258
+ #
259
+ # `.copy_from` and `.move_from`
260
+ # -----------------------------
261
+ #
262
+ # If the file you want to create already exists elsewhere in your filesystem, you can use
263
+ # `.copy_from` or `.move_from` to create it.
264
+ #
265
+ # Imagine the project report CSV for `Project.last` was created by some external process
266
+ # at the location `/var/tmp/reports/last_report.csv`, and you now wish to import it into your
267
+ # well-defined directory structure.
268
+ #
269
+ # ```ruby
270
+ # Fs::Files::ProjectReportCsv.exists?(project: Project.last)
271
+ # # => false
272
+ #
273
+ # file =
274
+ # Fs::Files::ProjectReportCsv.copy_from("/var/tmp/reports/last_report.csv", project: Project.last)
275
+ #
276
+ # file.path
277
+ # # => #<Pathname:/app/storage/project_reports/15/report_15.csv>
278
+ # ```
279
+ #
280
+ # Advanced subclasses: file conversions with variants
281
+ # ---------------------------------------------------
282
+ #
283
+ # We regularly need file contents in different forms or formats — PNGs as JPEGs, JPEGS as thumbnails,
284
+ # PDFs as text files. To that end, we can provide _variants_.
285
+ #
286
+ # Lets take an unspecific text file class called `SomeTextFile` as an example. Each variant you define
287
+ # must have at minimum a name:
288
+ #
289
+ # ```ruby
290
+ # module Fs
291
+ # module Files
292
+ # class SomeTextFile < Fs::Files::Text
293
+ # variant :loud_text do
294
+ # end
295
+ # end
296
+ # end
297
+ # end
298
+ # ```
299
+ #
300
+ # For any `SomeTextFile` instance, we can now create and load this `:loud_text` variant:
301
+ #
302
+ # ```ruby
303
+ # some_text_file =
304
+ # Fs::Files::SomeTextFile.create(path: "/some/path/text.txt", content: "lorem ipsum")
305
+ # # => Fs::Files::SomeTextFile
306
+ #
307
+ # some_text_file.variant(:loud_text)
308
+ # .create(path: "/some/path/loud_text.txt", content: "Loud file content")
309
+ # # => Fs::File
310
+ #
311
+ # some_text_file.variant(:loud_text)
312
+ # .load(path: "/some/path/loud_text.txt")
313
+ # # => Fs::File
314
+ # ```
315
+ #
316
+ # So far this didn't do anything useful - we had to provide everything from the file path to the
317
+ # content for the new variant ourselves. What's interesting to note is that the type of the variant
318
+ # is `Fs::File`, the base class:
319
+ #
320
+ # ```ruby
321
+ # some_text_file.content
322
+ # # => "lorem ipsum"
323
+ #
324
+ # some_text_file.variant(:loud_text)
325
+ # .load(path: "/some/path/loud_text.txt")
326
+ # .content
327
+ # # => NoMethodError: undefined method `content` for Fs::File:Class
328
+ # ```
329
+ #
330
+ # Let's change that:
331
+ #
332
+ # ```ruby
333
+ # module Fs
334
+ # module Files
335
+ # class SomeTextFile < Fs::Files::Text
336
+ # variant(:loud_text, Fs::Files::Text) do
337
+ # end
338
+ # end
339
+ # end
340
+ # end
341
+ #
342
+ # some_text_file.variant(:loud_text)
343
+ # .load(path: "/some/path/loud_text.txt")
344
+ # .content
345
+ # # => "Loud file content"
346
+ # ```
347
+ #
348
+ # Great. Now lets provide the path to the file and the file content automatically; we do this
349
+ # with `get_path_from {}` and `create_with_content_from {}`. Both blocks are executed in the
350
+ # scope of the variants parent - in the above example, that's `some_text_file`. So we have
351
+ # access to all its methods:
352
+ #
353
+ # ```ruby
354
+ # module Fs
355
+ # module Files
356
+ # class SomeTextFile < Fs::Files::Text
357
+ # variant(:loud_text, Fs::Files::Text) do
358
+ # get_path_from do |klass:|
359
+ # # `path.dirname` = `some_text_file.dirname` from the example above
360
+ # path.dirname / "loud_#{basename}.#{klass.extension}"
361
+ # end
362
+ #
363
+ # create_with_content_from do
364
+ # # `content` = `some_text_file.content` from the example above
365
+ # content.upcase
366
+ # end
367
+ # end
368
+ # end
369
+ # end
370
+ # end
371
+ #
372
+ # some_text_file.variant(:loud_text)
373
+ # .create
374
+ # .content
375
+ # # => "LOREM IPSUM"
376
+ # ```
377
+ #
378
+ # `get_path_from` receives the variant class, plus all parameters passed into
379
+ # `#load` or `#create` as arguments. `create_with_content_from` receives all parameters
380
+ # passed into `#create` as arguments.
381
+ #
382
+ # These two hooks are not always sufficient, for example if you create the content by shelling
383
+ # out to a command like `gs` or `convert` in order to create your variant. For those cases,
384
+ # provide `create_with {}` and `load_with {}` hooks instead:
385
+ #
386
+ # ```ruby
387
+ # module Fs
388
+ # module Files
389
+ # class SomeTextFile < Fs::Files::Text
390
+ # variant(:loud_text, Fs::Files::Text) do
391
+ # get_path_from do |klass:|
392
+ # path.dirname / "loud_#{basename}.#{klass.extension}"
393
+ # end
394
+ #
395
+ # create_with do |klass:, path:|
396
+ # # the path passed in here automatically is the return value from `get_path_from`
397
+ #
398
+ # # we take our parents content. `self` here is our instance of `SomeTextFile`
399
+ # new_content = content.upcase
400
+ #
401
+ # # The `:klass` argument our block received as an argument is the anonymous
402
+ # # class for the loud_text variant, subclassed from `Fs::Files::Text`
403
+ # klass.create(path: path, content: new_content)
404
+ # end
405
+ #
406
+ # load_with do |klass:, path:|
407
+ # klass.load(path: path)
408
+ # end
409
+ # end
410
+ # end
411
+ # end
412
+ # end
413
+ # ```
414
+ #
415
+ # Note that if we had created the file by shelling out to a command like `gs`, we would have
416
+ # ended with `klass.load` instead of `klass.create`, since our Fs::File class did not have to
417
+ # create a file anymore.
418
+ #
419
+ # You have one other extremely powerful capability at your disposal: the ability to dynamically
420
+ # configure the variants class with `define`. Inside a `define {}` block you can do everything
421
+ # you can do in a regular class body and have the full DSL available - if for example you want
422
+ # to change the variants file extension, you can just do so:
423
+ #
424
+ # ```ruby
425
+ # module Fs
426
+ # module Files
427
+ # class SomeTextFile < Fs::Files::Text
428
+ # variant(:loud_text, Fs::Files::Text) do
429
+ # define do
430
+ # extension :loud_text
431
+ #
432
+ # def is_this_loud?
433
+ # "YEAH!"
434
+ # end
435
+ # end
436
+ #
437
+ # get_path_from do |klass:|
438
+ # path.dirname / "loud_#{basename}.#{klass.extension}"
439
+ # end
440
+ #
441
+ # create_with_content_from do
442
+ # content.upcase
443
+ # end
444
+ # end
445
+ # end
446
+ # end
447
+ # end
448
+ #
449
+ # variant = some_text_file.variant(:loud_text)
450
+ # .load
451
+ # variant.path
452
+ # # => #<Pathname:/some/path/loud_text.loud_txt>
453
+ # variant.is_this_loud?
454
+ # # => "YEAH!"
455
+ # ```
456
+ class File
457
+ include Fs::Concerns::RequiredArguments
458
+ include Fs::Concerns::FileDslMethods
459
+
460
+ # The default number of seconds {.with_creation_lock} will wait to
461
+ # acquire a path's creation lock before giving up.
462
+ #
463
+ # Long enough to comfortably cover a real {.create} (eg. an image
464
+ # conversion plus a Tesseract rotation detection call), short enough to
465
+ # fail well before an NFSv4 lease expiry (90s on our mounts) would, so a
466
+ # stuck lock doesn't tie up a whole request/job for that long.
467
+ CREATION_LOCK_TIMEOUT = 20
468
+
469
+ # How often to retry acquiring the lock while waiting
470
+ CREATION_LOCK_POLL_INTERVAL = 0.1
471
+
472
+ # The extension given to a path's creation lockfile. Shared with
473
+ # {Fs::LockfileSweeper}, which needs to find the same files this class
474
+ # creates.
475
+ CREATION_LOCK_EXTENSION = "lock"
476
+
477
+ # The settings of {.atomic_write_directory} which are not an {Fs::Directory}
478
+ ATOMIC_WRITE_DIRECTORY_MODES = %i(alongside system).freeze
479
+
480
+ # The settings of {.temp_directory} which are not an {Fs::Directory}
481
+ TEMP_DIRECTORY_MODES = %i(system).freeze
482
+
483
+ # @return [Fs::Directory, nil] an instance of the `Fs::Directory` configured
484
+ # for this File, if any
485
+ attr_reader :directory
486
+ # @return [Pathname] the full path for this File
487
+ attr_reader :path
488
+ # For compatibility with {Pathname} objects
489
+ alias_method :to_path, :path
490
+
491
+ delegate :size, :delete, :mtime,
492
+ to: :path
493
+
494
+ # Instantiate a new File object and validate that its path exists on disk
495
+ # and is usable.
496
+ #
497
+ # Use this for creating File objects for files that already exist.
498
+ #
499
+ # @see #initialize
500
+ # @param validate [Boolean] raise an exception if file is not valid
501
+ # @param skip_extension_validation [Boolean] ignored if `validate: false`
502
+ # @param skip_mime_type_validation [Boolean] ignored if `validate: false`
503
+ # @param skip_encoding_validation [Boolean] ignored if `validate: false`
504
+ def self.load(validate: true, skip_extension_validation: false, skip_mime_type_validation: false,
505
+ skip_encoding_validation: false, **kargs)
506
+ new(**kargs).tap do |instance|
507
+ instance.validate!(
508
+ skip_extension_validation: skip_extension_validation,
509
+ skip_mime_type_validation: skip_mime_type_validation,
510
+ skip_encoding_validation: skip_encoding_validation
511
+ ) if validate
512
+
513
+ instance.load
514
+ end
515
+ end
516
+
517
+ # Test whether a path exists on disk and is usable.
518
+ #
519
+ # @see #initialize
520
+ # @param skip_extension_validation [Boolean] ignored if `validate: false`
521
+ # @param skip_mime_type_validation [Boolean] ignored if `validate: false`
522
+ # @param skip_encoding_validation [Boolean] ignored if `validate: false`
523
+ # @return [Boolean]
524
+ def self.exists?(skip_extension_validation: false, skip_mime_type_validation: false,
525
+ skip_encoding_validation: false, **kargs)
526
+ load(validate: false, **kargs).valid?(
527
+ skip_extension_validation: skip_extension_validation,
528
+ skip_mime_type_validation: skip_mime_type_validation,
529
+ skip_encoding_validation: skip_encoding_validation
530
+ )
531
+ end
532
+
533
+ # Test whether this file class would accept a file with MIME type
534
+ # `mime_type` and/or extension `extension` and/or encoding `encoding`
535
+ #
536
+ # @param mime_type [String, nil]
537
+ # @param extension [String, nil]
538
+ # @param encoding [String, nil]
539
+ # @return [Boolean]
540
+ def self.accepts?(mime_type: nil, extension: nil, encoding: nil)
541
+ if mime_type
542
+ return false unless string_matches_config?(mime_type, within: mime_types)
543
+ end
544
+
545
+ if extension
546
+ return false unless string_matches_config?(extension, within: extensions)
547
+ end
548
+
549
+ if encoding
550
+ return false unless string_matches_config?(encoding, within: encodings)
551
+ end
552
+
553
+ true
554
+ end
555
+
556
+ # Instantiate a new File object and create its file on disk.
557
+ #
558
+ # Use this for creating File objects for files that do not yet exist.
559
+ #
560
+ # @example
561
+ # Fs::File.create(path: "/some/path/file.txt") do |f|
562
+ # f << "file content"
563
+ # end
564
+ #
565
+ # #or alternatively:
566
+ # Fs::File.create(path: "/some/path/file.txt", content: "file content")
567
+ #
568
+ # @see #initialize
569
+ # @param overwrite [Boolean] overwrite the file if it already exists on disk
570
+ # @param content [#to_s] content to be written to the file
571
+ # @param lock [Boolean] serialize concurrent creators of the same path
572
+ # (see {.with_creation_lock}); defaults to this class' {.use_locks}
573
+ # setting, which is off unless creating the file is expensive
574
+ # @param lock_timeout [Numeric] see {.with_creation_lock}
575
+ # @yield [IO]
576
+ def self.create(overwrite: false, content: nil, lock: use_locks, lock_timeout: CREATION_LOCK_TIMEOUT, **kargs, &block)
577
+ with_creation_lock(new(**kargs).path, lock: lock, timeout: lock_timeout) do
578
+ create_without_lock(overwrite: overwrite, content: content, **kargs, &block)
579
+ end
580
+ end
581
+
582
+ # Instantiate and write to disk
583
+ #
584
+ # This is the lockless plumbing, not to be used externally
585
+ #
586
+ # @return [Fs::File]
587
+ def self.create_without_lock(overwrite:, content:, **kargs, &block)
588
+ new(**kargs).tap do |instance|
589
+ instance.create(overwrite: overwrite, content: content, &block)
590
+ end
591
+ end
592
+ private_class_method :create_without_lock
593
+
594
+ # Instantiate a new File object and create it as a tempfile on disk
595
+ #
596
+ # Use this to temporarily create File objects for files that do not
597
+ # yet exist.
598
+ #
599
+ # @see #initialize
600
+ # @param overwrite [Boolean] ignored
601
+ # @param content [#to_s] content to be written to the file
602
+ # @yield [Fs::File]
603
+ # @return the return value of the given block
604
+ def self.create_temp(**kargs, &block)
605
+ unless block_given?
606
+ raise ArgumentError, "create_temp requires a block to yield the temporary Fs::File object to"
607
+ end
608
+
609
+ Tempfile.create([name, "." + (extensions&.first || "temp")], resolve_temp_directory(temp_directory).to_s) do |tempfile|
610
+ yield create(path: tempfile.path, overwrite: true, **kargs)
611
+ end
612
+ end
613
+
614
+ # Instantiate a new File object and validate that its path exists on disk
615
+ # and is usable, otherwise create it on disk.
616
+ #
617
+ # Use this for creating File objects for files that may or may not exist.
618
+ #
619
+ # @example
620
+ # Fs::File.load_or_create(path: "/some/path/file.txt") do |f|
621
+ # f << "file content"
622
+ # end
623
+ #
624
+ # #or alternatively:
625
+ # Fs::File.load_or_create(path: "/some/path/file.txt", content: "file content")
626
+ #
627
+ # A file which is written atomically, see {.use_atomic_writes}, is either there complete or not
628
+ # there at all. If it is there, we load it without taking the lock, which would otherwise be
629
+ # taken, and a lockfile left, for every file we merely look at.
630
+ #
631
+ # @see #initialize
632
+ # @param overwrite [Boolean] overwrite the file if it already exists on disk
633
+ # @param content [#to_s] content to be written to the file
634
+ # @param lock [Boolean] see {.create}
635
+ # @param lock_timeout [Numeric] see {.with_creation_lock}
636
+ # @option **kargs [Boolean] validate (true) load only: raise an exception if file is not valid
637
+ # @option **kargs [Boolean] skip_extension_validation (false) load only: ignored if `validate: false`
638
+ # @option **kargs [Boolean] skip_mime_type_validation (false) load only: ignored if `validate: false`
639
+ # @option **kargs [Boolean] skip_encoding_validation (false) load only: ignored if `validate: false`
640
+ # @yield [IO]
641
+ def self.load_or_create(overwrite: false, content: nil, lock: use_locks, lock_timeout: CREATION_LOCK_TIMEOUT, **kargs, &block)
642
+ existing = load_if_present(**kargs) if use_atomic_writes
643
+
644
+ return existing if existing
645
+
646
+ with_creation_lock(new(**kargs).path, lock: lock, timeout: lock_timeout) do
647
+ # Somebody else may have created it while we were waiting for the lock
648
+ load_if_present(**kargs) || create_without_lock(overwrite: overwrite, content: content, **kargs, &block)
649
+ end
650
+ end
651
+
652
+ # @return [Fs::File, nil] nil if there is no file; an invalid one raises, as with {.load}
653
+ def self.load_if_present(**kargs)
654
+ load(**kargs)
655
+
656
+ rescue Errors::Fs::Validation::FileDoesNotExist
657
+ nil
658
+ end
659
+ private_class_method :load_if_present
660
+
661
+ # Serializes concurrent {.create}/{.load_or_create} calls for the same
662
+ # +path+
663
+ #
664
+ # Prevents a second concurrent writer to corrupt an ongoing write
665
+ # process, or a reader to access an unfinished ongoing write operation.
666
+ #
667
+ # Uses a separate lock file instead of locking the resource itself in
668
+ # order to be able to signal locking state before the file exists.
669
+ #
670
+ # Keeps the lockfile around after use in order to prevent the following
671
+ # scenario:
672
+ #
673
+ # * writer 1 creates the lock file (inode = 100), acquires the lock on it
674
+ # * writer 2 sees the existing lock, polls until it can get lock on it
675
+ # * writer 1 releases the lock, deletes the file
676
+ # * writer 2 has retained access to the deleted lock file (inode = 100),
677
+ # acquires the lock
678
+ # * writer 3 arrives, sees no lockfile, creates one and begins work
679
+ # immediately, colliding with the ongoing work of writer 2
680
+ #
681
+ # Does not use a double-locking approach (advisory shared "interest" lock
682
+ # plus exclusive write lock) instead of the above, because from what I
683
+ # can see that doesn't work reliably on NFS mounts, which is my current
684
+ # use case.
685
+ #
686
+ # Requires an NFSv4 mount, configured with `local_lock=none` so that
687
+ # locks are actually forwarded to the NFS server instead of being
688
+ # simulated locally.
689
+ #
690
+ # @param path [Pathname, Fs::File, Fs::Directory, String]
691
+ # @param lock [Boolean] whether to lock at all; see {.use_locks}
692
+ # @param timeout [Numeric] seconds to wait for the lock before raising
693
+ # {Errors::Fs::LockTimeout} - most likely to trigger if whoever is
694
+ # holding the lock crashed without releasing it and the underlying
695
+ # filesystem hasn't noticed yet (eg. an unexpired NFS lease)
696
+ # @raise [Errors::Fs::LockTimeout]
697
+ # @yield
698
+ # @return the block's return value
699
+ def self.with_creation_lock(path, lock:, timeout: CREATION_LOCK_TIMEOUT)
700
+ return yield unless lock
701
+
702
+ path = normalize_path_input(path)
703
+
704
+ ::File.open("#{path}.#{CREATION_LOCK_EXTENSION}", ::File::CREAT | ::File::RDWR) do |lockfile|
705
+ deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
706
+
707
+ until lockfile.flock(::File::LOCK_EX | ::File::LOCK_NB)
708
+ if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
709
+ raise Errors::Fs::LockTimeout, "could not acquire creation lock for #{path} within #{timeout}s"
710
+ end
711
+
712
+ sleep CREATION_LOCK_POLL_INTERVAL
713
+ end
714
+
715
+ yield
716
+ end
717
+ end
718
+
719
+ # Create a new `Fs::File` object by copying an existing file from `source`.
720
+ #
721
+ # The source file must be valid according to the current `Fs::File` subclass.
722
+ #
723
+ # Validation of the source file can be disabled either completely through
724
+ # `validate_source: false`, or selectively through the three `skip_` arguments.
725
+ #
726
+ # Provide the same `**kargs` you would provide to {.load}:
727
+ #
728
+ # @example
729
+ # # load an existing ProjectFile
730
+ # Fs::Files::ProjectJPG.load(project_file: ProjectFile.last)
731
+ #
732
+ # # create a new instance by copying an existing file
733
+ # Fs::Files::ProjectJPG.copy_from("/some/file.jpg", project_file: ProjectFile.last)
734
+ #
735
+ # @param source [Fs::File, Pathname, String]
736
+ # @param overwrite [Boolean] overwrite an existing destination file
737
+ # @option **kargs [Boolean] validate_source perform Fs::File validations on the source file
738
+ # @option **kargs [Boolean] skip_extension_validation (false) source validation: ignored if `validate_source: false`
739
+ # @option **kargs [Boolean] skip_mime_type_validation (false) source validation: ignored if `validate_source: false`
740
+ # @option **kargs [Boolean] skip_encoding_validation (false) source validation: ignored if `validate_source: false`
741
+ # The copy is made through a temporary file, see {.use_atomic_writes}: nobody sees the new
742
+ # file before it is complete.
743
+ #
744
+ # @see #initialize
745
+ # @raise [Errors::Fs::ReadWrite]
746
+ # @return [Fs::File]
747
+ def self.copy_from(source, overwrite: false, **kargs)
748
+ with_existing_file(source, overwrite: overwrite, **kargs) do |source_path, instance|
749
+ FileUtils.cp(source_path, instance.path)
750
+ end
751
+ end
752
+
753
+ # Create a new `Fs::File` object by moving an existing file from `source`.
754
+ #
755
+ # The source file must be valid according to the current `Fs::File` subclass.
756
+ #
757
+ # Validation of the source file can be disabled either completely through
758
+ # `validate_source: false`, or selectively through the three `skip_` arguments.
759
+ #
760
+ # Provide the same `**kargs` you would provide to {.load}:
761
+ #
762
+ # @example
763
+ # # load an existing ProjectFile
764
+ # Fs::Files::ProjectJPG.load(project_file: ProjectFile.last)
765
+ #
766
+ # # create a new instance by moving an existing file
767
+ # Fs::Files::ProjectJPG.move_from("/some/file.jpg", project_file: ProjectFile.last)
768
+ #
769
+ # @param source [Fs::File, Pathname, String]
770
+ # @param overwrite [Boolean] overwrite an existing destination file
771
+ # @option **kargs [Boolean] validate_source perform Fs::File validations on the source file
772
+ # @option **kargs [Boolean] skip_extension_validation (false) source validation: ignored if `validate_source: false`
773
+ # @option **kargs [Boolean] skip_mime_type_validation (false) source validation: ignored if `validate_source: false`
774
+ # @option **kargs [Boolean] skip_encoding_validation (false) source validation: ignored if `validate_source: false`
775
+ # A move is a rename wherever the two paths are on the same file system, which nobody can
776
+ # see half done. Across file systems the file is copied as {.copy_from} does, and the source
777
+ # is only removed once the copy is complete, so that being interrupted loses nothing.
778
+ #
779
+ # @see #initialize
780
+ # @raise [Errors::Fs::ReadWrite]
781
+ # @return [Fs::File]
782
+ def self.move_from(source, overwrite: false, **kargs)
783
+ with_existing_file(source, overwrite: overwrite, atomically: false, **kargs) do |source_path, instance|
784
+ ::File.rename(source_path, instance.path)
785
+
786
+ rescue Errno::EXDEV
787
+ if use_atomic_writes
788
+ instance.write_atomically(overwrite: true) { |staged| FileUtils.cp(source_path, staged.path) }
789
+ else
790
+ FileUtils.cp(source_path, instance.path)
791
+ end
792
+
793
+ ::File.delete(source_path)
794
+ end
795
+ end
796
+
797
+ # Delete an `Fs::File` object from disk
798
+ #
799
+ # @param quiet [Boolean] ignore if the file already
800
+ # does not exist
801
+ # @return [Boolean]
802
+ def self.delete(quiet: true, **kargs)
803
+ instance = new(**kargs)
804
+
805
+ return false if quiet && !instance.exists?
806
+
807
+ instance.delete
808
+
809
+ true
810
+ end
811
+
812
+ # Create a new `Fs::File` object by copying or moving an existing file from `source`.
813
+ #
814
+ # Tests the source file for validity according to this `Fs::File` instances validation
815
+ # rules, calls the given block with the source path and an instance of the target file to
816
+ # put it into, and afterwards `.load`s and returns a fresh target instance after the block
817
+ # returns.
818
+ #
819
+ # If the class writes atomically, the target instance is at a temporary path, and replaces
820
+ # the real file once the block returns. If not, it is at the real path, and the block writes
821
+ # to it in place.
822
+ #
823
+ # Validation of the source file can be disabled either completely through
824
+ # `validate_source: false`, or selectively through the three `skip_` arguments.
825
+ #
826
+ # @param source [Fs::File, Pathname, String]
827
+ # @param validate_source [Boolean] perform Fs::File validations on the source file
828
+ # @param overwrite [Boolean] overwrite an existing destination file
829
+ # @param atomically [Boolean] hand the block a temporary target, which replaces the real
830
+ # file once the block returns; for blocks which put the file in place by themselves
831
+ # @option **kargs [Boolean] skip_extension_validation (false) source validation: ignored if `validate_source: false`
832
+ # @option **kargs [Boolean] skip_mime_type_validation (false) source validation: ignored if `validate_source: false`
833
+ # @option **kargs [Boolean] skip_encoding_validation (false) source validation: ignored if `validate_source: false`
834
+ # @see #initialize
835
+ # @yieldparam source_path [Pathname] the path to the source file
836
+ # @yieldparam instance [Fs::File] where the block is to put the file; it does not exist yet
837
+ # (and is not the one returned to the caller!)
838
+ # @raise [Errors::Fs::ReadWrite]
839
+ # @return [Fs::File]
840
+ def self.with_existing_file(source, validate_source: true, overwrite: false, atomically: use_atomic_writes, **kargs)
841
+ source_path = normalize_path_input(source)
842
+
843
+ # We load and discard the source file just to validate it by the target
844
+ # classes' rules. No reason to start copying if it's the wrong type or
845
+ # otherwise broken.
846
+ begin
847
+ load(path: source_path, validate: validate_source, **kargs)
848
+ rescue Errors::Fs::ReadWrite
849
+ raise Errors::Fs::ReadWrite, "unsuitable source: #{source_path}"
850
+ end
851
+
852
+ instance = new(**kargs)
853
+
854
+ # We're not using Fs::File.exists?, because here we
855
+ # are only interested if something physically exists
856
+ # in the filesystem location we are about to write to,
857
+ # not whether anything existing there is otherwise valid.
858
+ if !overwrite && instance.exists?
859
+ raise Errors::Fs::ReadWrite, "#{instance.path} already exists"
860
+ end
861
+
862
+ begin
863
+ if atomically
864
+ instance.write_atomically(overwrite: true) { |staged| yield source_path, staged }
865
+ else
866
+ yield source_path, instance
867
+ end
868
+ rescue Errors::Fs::BaseDirectory
869
+ # Not the block's doing, and not ours to explain away: pass it on as it is
870
+ raise
871
+ rescue StandardError
872
+ raise Errors::Fs::ReadWrite
873
+ end
874
+
875
+ load(**kargs)
876
+ end
877
+ private_class_method :with_existing_file
878
+
879
+ # Determines a match between a String and a list of Strings
880
+ # or regular expressions
881
+ #
882
+ # @example
883
+ # string_config_match?("yes", within: ["no", "maybe", /yes/])
884
+ # # => true
885
+ #
886
+ # Returns default `true` when the `within` config is `nil`.
887
+ #
888
+ # Consider this method to be private; it cannot be made
889
+ # explicitely so, because we need to reuse it in instance
890
+ # context, and at least I for one have no idea how to do so
891
+ # without resorting to idiotic contortions.
892
+ #
893
+ # @private
894
+ # @param value [String, Symbol, #to_s]
895
+ # @param within [Array<String,Symbol,#to_s,Regexp>, nil]
896
+ # @return [Boolean]
897
+ def self.string_matches_config?(value, within:)
898
+ return true unless within
899
+
900
+ within.find do |match|
901
+ case match
902
+ when String
903
+ value.to_s == match
904
+ when Symbol
905
+ value.to_s == match.to_s
906
+ when Regexp
907
+ value.to_s
908
+ .match?(match)
909
+ end
910
+ end || false
911
+ end
912
+
913
+ # Converts a variety of inputs to a {Pathname}, such as
914
+ # {Fs::File}, {Fs::Directory} or {String}
915
+ #
916
+ # @private
917
+ # @param input [Pathname, Fs::File, Fs::Directory, String]
918
+ # @return [Pathname, nil]
919
+ def self.normalize_path_input(input)
920
+ return input if input.is_a?(Pathname)
921
+ return input.path if input.respond_to?(:path)
922
+ return input.to_path if input.respond_to?(:to_path)
923
+ return Pathname.new(input) if input.is_a?(String)
924
+ end
925
+
926
+ # The directory a {.temp_directory} or {.atomic_write_directory} setting stands for
927
+ #
928
+ # @private
929
+ # @param setting [Symbol, Class, String] `:system`, `:alongside`, an {Fs::Directory}
930
+ # subclass or its name
931
+ # @param alongside [Pathname, nil] what `:alongside` stands for, if anything
932
+ # @raise [ArgumentError] if the setting is not one of the above
933
+ # @return [Pathname]
934
+ def self.resolve_temp_directory(setting, alongside: nil)
935
+ case setting
936
+ when :alongside then alongside || raise(ArgumentError, "there is nothing to be alongside of")
937
+ when :system then Pathname.new(Dir.tmpdir)
938
+ when String then setting.constantize.new.path
939
+ when Class then setting.new.path
940
+ else
941
+ raise ArgumentError, "expected :system, :alongside, an Fs::Directory subclass or its name, not #{setting.inspect}"
942
+ end
943
+ end
944
+
945
+ # You need to pass in either a full path, or all parameters required
946
+ # for the class to build the path itself. Which parameters those are
947
+ # depends on the specific subclass:
948
+ #
949
+ # * a full `:path` always works: `new(path: "/some/file.txt")`
950
+ # * for subclasses that have a `directory` configured, just the
951
+ # `:filename` is sufficient: `new(filename: "file.txt")`
952
+ # * for subclasses that have a `directory` and an `extension` configured,
953
+ # just the `basename` is sufficient: `new(basename: "file")`
954
+ # * for subclasses that take care of basename and extension, just pass
955
+ # in a `directory`: `new(directory: "/foo")`
956
+ # * some subclasses handle naming themselves and require you to only pass
957
+ # in a related object instead: `new(project: Project.last)`
958
+ #
959
+ # @param path [String, Pathname, Fs::File] the full path to the file on disk
960
+ # @param filename [String, Pathname] the full filename with file extension
961
+ # @param basename [String] the filename without file extension
962
+ # @param directory [String, Pathname] the directory path in which the file will
963
+ # be stored
964
+ # @param kargs any other parameters as required by the File subclass
965
+ def initialize(path: nil, filename: nil, basename: nil, directory: nil, **kargs)
966
+ process_required_arguments(**kargs)
967
+
968
+ if directory
969
+ @directory = Fs::Directory.new(base_path: directory)
970
+
971
+ elsif self.class.directory
972
+ directory_kargs =
973
+ self.class.directory_args_proc ? instance_exec(&self.class.directory_args_proc) : kargs
974
+
975
+ @directory =
976
+ self.class
977
+ .directory
978
+ .new(**directory_kargs)
979
+ end
980
+
981
+ basename = basename || self.basename
982
+
983
+ @path =
984
+ case
985
+ when path && normalize_path_input(path)
986
+ normalize_path_input(path)
987
+
988
+ when directory_path && self.class.extensions && basename
989
+ directory_path / "#{basename}.#{self.class.extensions.first}"
990
+
991
+ when directory_path && filename
992
+ directory_path / filename
993
+
994
+ when self.class.get_path_proc
995
+ Pathname.new(
996
+ instance_eval(&self.class.get_path_proc)
997
+ )
998
+
999
+ else
1000
+ raise ArgumentError, "provide either a :path, a `get_path_from` block, "\
1001
+ "or set `directory` and `extension` and provide a basename"
1002
+ end
1003
+ end
1004
+
1005
+ # The directory path as configured by the `Fs::Directory` instance
1006
+ # associated to this `File` instance, if any
1007
+ #
1008
+ # @return [Pathname, nil]
1009
+ def directory_path
1010
+ return nil unless directory.present?
1011
+
1012
+ if self.class.directory_subdir
1013
+ directory.path / self.class.directory_subdir
1014
+ else
1015
+ directory.path
1016
+ end
1017
+ end
1018
+
1019
+ # The directory containing the file
1020
+ #
1021
+ # @example
1022
+ # Fs::File.new(path: "/home/example.txt").dirname
1023
+ # # => #<Pathname:/home>
1024
+ #
1025
+ # @return [Pathname]
1026
+ def dirname
1027
+ path&.dirname
1028
+ end
1029
+
1030
+ # The full filename including file extension
1031
+ #
1032
+ # @example
1033
+ # Fs::File.new(path: "/home/example.txt").filename
1034
+ # # => #<Pathname:example.txt>
1035
+ #
1036
+ # @return [Pathname]
1037
+ def filename
1038
+ path&.basename
1039
+ end
1040
+
1041
+ # The filename excluding file extension
1042
+ #
1043
+ # @example
1044
+ # Fs::File.new(path: "/home/example.txt").basename
1045
+ # # => #<Pathname:example>
1046
+ #
1047
+ # @return [Pathname]
1048
+ def basename
1049
+ path&.basename(".*")
1050
+ end
1051
+
1052
+ # The file extension
1053
+ #
1054
+ # @example
1055
+ # Fs::File.new(path: "/home/example.txt").extension
1056
+ # # => "txt"
1057
+ #
1058
+ # @return [String]
1059
+ def extension
1060
+ path&.extname[1..-1]
1061
+ end
1062
+
1063
+ def exists?
1064
+ path.exist?
1065
+ end
1066
+ alias_method :exist?, :exists?
1067
+
1068
+ # Copies this file to `destination`; returns a new Fs::File instance
1069
+ #
1070
+ # If the destination is a directory, the copied file will
1071
+ # retain its current filename.
1072
+ #
1073
+ # Please note that you'll receive a generic `Fs::File`
1074
+ # object back, even if `self` is some other subclass.
1075
+ #
1076
+ # This is due to the fact that `target_path` might not
1077
+ # be compatible with the configuration and expectations
1078
+ # of `self`.
1079
+ #
1080
+ # @param destination [Pathname, Fs::File, Fs::Directory, String]
1081
+ # @return [Fs::File]
1082
+ def copy_to(destination)
1083
+ destination =
1084
+ normalize_path_input(destination)
1085
+
1086
+ if destination.directory?
1087
+ destination = destination/filename
1088
+ end
1089
+
1090
+ FileUtils.cp(path, destination)
1091
+
1092
+ File.new(path: destination)
1093
+ end
1094
+
1095
+ # Moves this file to `destination`; returns a new Fs::File instance
1096
+ #
1097
+ # If the destination is a directory, the copied file will
1098
+ # retain its current filename.
1099
+ #
1100
+ # @param destination [Pathname, Fs::File, Fs::Directory, String]
1101
+ # @return [Fs::File]
1102
+ def move_to(destination)
1103
+ destination =
1104
+ normalize_path_input(destination)
1105
+
1106
+ if destination.directory?
1107
+ destination = destination/filename
1108
+ end
1109
+
1110
+ FileUtils.mv(path, destination)
1111
+
1112
+ self.class.load(path: destination, **required_arguments_given)
1113
+ end
1114
+
1115
+ # Ensure the file is present, readable, writable, non-zero in size and of the
1116
+ # expected file extension, MIME type and encoding
1117
+ #
1118
+ # @param skip_extension_validation [Boolean]
1119
+ # @param skip_mime_type_validation [Boolean]
1120
+ # @param skip_encoding_validation [Boolean]
1121
+ # @raise [Errors::Fs::Validation::FileDoesNotExist, Errors::Fs::Validation::FileEmpty]
1122
+ # @raise [Errors::Fs::Validation::FileNotReadable, Errors::Fs::Validation::FileNotWriteable]
1123
+ # @raise [Errors::Fs::Validation::UnsupportedExtension, Errors::Fs::Validation::UnsupportedMimeType]
1124
+ # @raise [Errors::Fs::Validation::UnsupportedEncoding]
1125
+ # @return [void]
1126
+ def validate!(skip_extension_validation: false, skip_mime_type_validation: false,
1127
+ skip_encoding_validation: false)
1128
+ migrate_from_legacy_location! if self.class.legacy_klass
1129
+
1130
+ # These errors reach users, so they carry no message: the path is their label, and
1131
+ # whoever translates them decides what to tell. For the `Unsupported*` ones the offending
1132
+ # value is the subject.
1133
+ Errors::Fs::Validation::FileDoesNotExist.raise(label: path.to_s) unless path.exist?
1134
+ Errors::Fs::Validation::FileEmpty.raise(label: path.to_s) unless self.class.allows_empty_files || path.size?
1135
+ Errors::Fs::Validation::FileNotReadable.raise(label: path.to_s) unless path.readable?
1136
+ Errors::Fs::Validation::FileNotWriteable.raise(label: path.to_s) unless path.writable?
1137
+
1138
+ unless skip_extension_validation
1139
+ unless string_matches_config?(extension, within: self.class.extensions)
1140
+ Errors::Fs::Validation::UnsupportedExtension.raise(label: path.to_s, subject: extension)
1141
+ end
1142
+ end
1143
+
1144
+ unless skip_mime_type_validation
1145
+ unless string_matches_config?(mime_type, within: self.class.mime_types)
1146
+ Errors::Fs::Validation::UnsupportedMimeType.raise(label: path.to_s, subject: mime_type)
1147
+ end
1148
+ end
1149
+
1150
+ unless skip_encoding_validation
1151
+ unless string_matches_config?(encoding, within: self.class.encodings)
1152
+ Errors::Fs::Validation::UnsupportedEncoding.raise(label: path.to_s, subject: encoding)
1153
+ end
1154
+ end
1155
+
1156
+ custom_validations
1157
+ end
1158
+
1159
+ # Is this file present, readable, writable, non-zero in size and of the
1160
+ # expected file extension?
1161
+ #
1162
+ # @see validate!
1163
+ # @return [Boolean]
1164
+ def valid?(**kargs)
1165
+ begin
1166
+ validate!(**kargs)
1167
+ true
1168
+ rescue Errors::Fs::ReadWrite
1169
+ false
1170
+ end
1171
+ end
1172
+
1173
+ # Hook to be called after {File.load} or {File.load_or_create}
1174
+ # has been called for a file that exists on disk
1175
+ #
1176
+ # In here, you can for example fetch the existing file's content
1177
+ # into instance variables.
1178
+ #
1179
+ # @return [void]
1180
+ def load
1181
+ end
1182
+
1183
+ # Create this file on disk
1184
+ #
1185
+ #
1186
+ # @example
1187
+ # file Fs::File.new(path: "/some/path/file.txt")
1188
+ #
1189
+ # file.create(path: "/some/path/file.txt") do |f|
1190
+ # f << "file content"
1191
+ # end
1192
+ #
1193
+ # #or alternatively:
1194
+ # file.create(path: "/some/path/file.txt", content: "file content")
1195
+ #
1196
+ # @see #initialize
1197
+ # @param overwrite [Boolean] overwrite the file if it already exists on disk
1198
+ # @param content [#to_s] content to be written to the file
1199
+ # @yield [IO] optionally yields an IO object, similar to `File.open`
1200
+ # @return [void]
1201
+ def create(overwrite: false, content: nil, &block)
1202
+ if self.class.use_atomic_writes
1203
+ write_atomically(overwrite: overwrite) do |temp_file|
1204
+ write_content_to(temp_file.path, content: content, &block)
1205
+ end
1206
+
1207
+ else
1208
+ validate_writeability(overwrite: overwrite)
1209
+
1210
+ write_content_to(path, content: content, &block)
1211
+ end
1212
+
1213
+ rescue IOError, EOFError, SystemCallError
1214
+ raise Errors::Fs::ReadWrite
1215
+ end
1216
+
1217
+ # Writes this file through a temporary one, so that nobody ever sees it half-written.
1218
+ #
1219
+ # Yields an instance of our class, with our arguments, at a temporary path. The block
1220
+ # writes to that, and once it returns, the result is moved to our path. If the block raises,
1221
+ # nothing is left behind and an existing file stays as it was. Use this in your own `#create`,
1222
+ # wherever you would otherwise write to `path`.
1223
+ #
1224
+ # The yielded instance does not exist on disk yet, and is not validated. It is meant for
1225
+ # whatever the block needs a file object for, such as `png.rotate` or `output: png`.
1226
+ #
1227
+ # Does not keep concurrent writers from doing the work twice, see {.with_creation_lock}.
1228
+ #
1229
+ # @example
1230
+ # def create(overwrite: false, **kargs)
1231
+ # write_atomically(overwrite: overwrite) do |temp_file|
1232
+ # Shell::Convert.exec(input: original, output: temp_file, **kargs).raise_failures
1233
+ # temp_file.rotate(degrees: 90)
1234
+ # end
1235
+ # end
1236
+ #
1237
+ # @see Fs::AtomicWrite
1238
+ # @see .atomic_write_directory
1239
+ # @param overwrite [Boolean] overwrite an existing file instead of raising an exception
1240
+ # @yieldparam temp_file [Fs::File] an instance of our class at the temporary path
1241
+ # @raise [Errors::Fs::ReadWrite]
1242
+ # @return [void]
1243
+ def write_atomically(overwrite: false)
1244
+ validate_writeability(overwrite: overwrite)
1245
+
1246
+ Fs::AtomicWrite.perform(path, directory: self.class.atomic_write_directory) do |temp_path|
1247
+ yield instance_at(temp_path)
1248
+ end
1249
+ end
1250
+
1251
+ # Opens the file, optionally yielding it to a block.
1252
+ #
1253
+ # With a block, behaves like +::File.open+: yields the open +::File+ to
1254
+ # the block, closes it on exit, and returns the block's value.
1255
+ # Without a block, returns an open +::File+; caller is responsible for
1256
+ # closing it.
1257
+ #
1258
+ # @param binary [Boolean] open in binary mode (+rb+ vs +r+)
1259
+ # @yieldparam file [::File]
1260
+ # @yieldreturn [Object]
1261
+ # @return [::File, Object] open +::File+ without a block, or block return value
1262
+ def open(binary: false, &block)
1263
+ mode = binary ? "rb" : "r"
1264
+
1265
+ ::File.open(path, mode, &block)
1266
+ end
1267
+
1268
+ # Read the on-disk content
1269
+ #
1270
+ # @option **kargs see File.read
1271
+ # @return [String]
1272
+ def read(**kargs)
1273
+ ::File.read(path, mode: "r", **kargs)
1274
+ end
1275
+
1276
+ # Read the on-disk content as binary
1277
+ #
1278
+ # @option **kargs see File.read
1279
+ # @return [String]
1280
+ def read_binary(**kargs)
1281
+ ::File.read(path, mode: "rb", **kargs)
1282
+ end
1283
+
1284
+ # Returns a proxy for the `variant_name` variant
1285
+ #
1286
+ # @see FileVariantProxy
1287
+ #
1288
+ # @param variant_name [Symbol]
1289
+ # @return [FileVariantProxy] an instance of FileVariantProxy
1290
+ def variant(variant_name)
1291
+ return nil unless self.class.variants[variant_name]
1292
+
1293
+ self.class
1294
+ .variants[variant_name]
1295
+ .to_proxy(parent: self)
1296
+ end
1297
+
1298
+ # Ensure all variants marked as _standard_ exist on disk
1299
+ #
1300
+ # All variants marked as _standard_ by calling
1301
+ # {Fs::FileVariantBuilder#include_in_standard_set} will be created
1302
+ # on disk in one go.
1303
+ #
1304
+ # @return [void]
1305
+ def prepare_standard_variants
1306
+ standard_variants.each(&:load_or_create)
1307
+ end
1308
+
1309
+ # All variants marked as _standard_ for easy iteration
1310
+ #
1311
+ # If you call {Fs::FileVariantBuilder#include_in_standard_set} while
1312
+ # defining a variant, it will be included in this set. Its purpose
1313
+ # is to allow you to iterate over them yourself when creating
1314
+ # them is too resource-intensive to create them synchronously via
1315
+ # {#prepare_standard_variants}.
1316
+ #
1317
+ # When given a block, yields both the variant name and the variant
1318
+ # once for every standard variant.
1319
+ #
1320
+ # @yieldparam name [Symbol] the current standard variants name
1321
+ # @yieldparam variant [FileVariantProxy] an instance of the current
1322
+ # FileVariantProxy
1323
+ # @return [Array<FileVariantProxy>, void] `void` if given a block
1324
+ def standard_variants
1325
+ return [] unless self.class.standard_variants
1326
+
1327
+ if block_given?
1328
+ self.class
1329
+ .standard_variants
1330
+ .each { |variant_name| yield(variant_name, variant(variant_name)) }
1331
+ else
1332
+ self.class
1333
+ .standard_variants
1334
+ .map { |variant_name| variant(variant_name) }
1335
+ end
1336
+ end
1337
+
1338
+ # Create and yield a temporary instance of this file
1339
+ #
1340
+ # The instance will be yielded to a provided block and automatically
1341
+ # removed after the block has returned.
1342
+ #
1343
+ # It is not recommended to retain a reference to the instance outside
1344
+ # of the block, because the underlying file will be gone.
1345
+ #
1346
+ # @param content [#to_s] optional: content to be written to the file
1347
+ # @yield [Fs::File] yields an instance of this variants class
1348
+ # @return the return value of the given block
1349
+ def create_temp(content: nil, **kargs)
1350
+ unless exist?
1351
+ raise RuntimeError, "cannot create_temp for a file that does not exist"
1352
+ end
1353
+
1354
+ unless block_given?
1355
+ raise ArgumentError, "create_temp requires a block to yield the temporary Fs::File object to"
1356
+ end
1357
+
1358
+ Tempfile.create([basename.to_s, "." + extension], Fs::File.resolve_temp_directory(self.class.temp_directory).to_s) do |tempfile|
1359
+ copy_to(tempfile.path)
1360
+
1361
+ yield self.class.load(path: tempfile.path, **required_arguments_given)
1362
+ end
1363
+ end
1364
+
1365
+ # The files MIME type
1366
+ #
1367
+ # @raise [Shell::Errors::CommandUnsuccessful]
1368
+ # @return [String]
1369
+ def mime_type
1370
+ Shell::File.mime_type(self)
1371
+ .raise_failures
1372
+ .value
1373
+ end
1374
+
1375
+ # The files content in Base64
1376
+ #
1377
+ # @raise [Shell::Errors::CommandUnsuccessful]
1378
+ # @return [String]
1379
+ def base64
1380
+ Shell::Base64.encode(self)
1381
+ .raise_failures
1382
+ .value
1383
+ end
1384
+
1385
+ # The files MIME encoding
1386
+ #
1387
+ # @raise [Shell::Errors::CommandUnsuccessful]
1388
+ # @return [String]
1389
+ def encoding
1390
+ Shell::File.mime_encoding(self)
1391
+ .raise_failures
1392
+ .value
1393
+ end
1394
+
1395
+ # Do we pass a ClamAV virus scan?
1396
+ #
1397
+ # @return [Boolean]
1398
+ def clamav_safe?
1399
+ Shell::ClamAv.safe?(self)
1400
+ end
1401
+
1402
+ # The files SHA512 hash in hex
1403
+ #
1404
+ # @raise [Shell::Errors::CommandUnsuccessful]
1405
+ # @return [String]
1406
+ def sha512_hexdigest
1407
+ Shell::OpenSsl.sha512_hexdigest(self)
1408
+ .raise_failures
1409
+ .value
1410
+ end
1411
+
1412
+ # The file size in bytes
1413
+ #
1414
+ # @return [Integer]
1415
+ def size
1416
+ ::File.size(path)
1417
+ end
1418
+
1419
+ # The files modification time
1420
+ #
1421
+ # @return [Time]
1422
+ def mtime
1423
+ ::File.mtime(path)
1424
+ end
1425
+
1426
+ private
1427
+
1428
+ # @see self.string_matches_config
1429
+ def string_matches_config?(value, within:)
1430
+ self.class.string_matches_config?(value, within: within)
1431
+ end
1432
+
1433
+ # No-op, to be overloaded in subclasses
1434
+ #
1435
+ # Overloads are expected to raise in case of validation failures
1436
+ def custom_validations
1437
+ end
1438
+
1439
+ # No-op in the overwhelming majority of cases where nothing needs
1440
+ # migrating - runs on every `#validate!` call for a class with a
1441
+ # `legacy` block, so it must stay cheap and silent when there's
1442
+ # nothing to do. See {Fs::Directory#migrate_from_legacy_location!}
1443
+ # for the equivalent on the Directory side.
1444
+ #
1445
+ # @return [void]
1446
+ def migrate_from_legacy_location!
1447
+ return if path.exist?
1448
+
1449
+ legacy_path = self.class.legacy_klass.new(when_missing: :ignore, **required_arguments_given).path
1450
+
1451
+ return unless legacy_path.exist? && legacy_path != path
1452
+
1453
+ path.dirname.mkpath
1454
+ FileUtils.mv(legacy_path.to_s, path.to_s)
1455
+
1456
+ delete_legacy_directory(legacy_path.dirname) if self.class.legacy_safely_delete_directory
1457
+ rescue Errno::ENOENT
1458
+ # Lost a race with another process/thread doing the same migration
1459
+ # concurrently - fine, the presence checks above will find `path`
1460
+ # already present.
1461
+ end
1462
+
1463
+ # `rmdir`, not `rm_rf` - only removes `directory` if it is genuinely
1464
+ # empty, so an unexpected extra file left behind by something else
1465
+ # sharing this legacy directory is never destroyed, just kept.
1466
+ #
1467
+ # @param directory [Pathname]
1468
+ # @return [void]
1469
+ def delete_legacy_directory(directory)
1470
+ directory.rmdir
1471
+ rescue Errno::ENOTEMPTY, Errno::ENOENT
1472
+ end
1473
+
1474
+ # @see {Fs::File.normalize_path_input}
1475
+ def normalize_path_input(input)
1476
+ self.class.normalize_path_input(input)
1477
+ end
1478
+
1479
+ # @param path [Pathname]
1480
+ # @return [Fs::File] an instance of our class and with our arguments, at `path`
1481
+ def instance_at(path)
1482
+ self.class.new(path: path, **required_arguments_given)
1483
+ end
1484
+
1485
+ # Writes our content, as given or as configured, to `destination`
1486
+ #
1487
+ # @param destination [Pathname] our path, or a temporary one
1488
+ # @param content [#to_s, nil]
1489
+ # @yield [IO] optionally yields an IO object, similar to `File.open`
1490
+ # @return [void]
1491
+ def write_content_to(destination, content: nil, &block)
1492
+ if content
1493
+ ::File.open(destination, "wb") { |f| f << content }
1494
+
1495
+ elsif block
1496
+ ::File.open(destination, "wb", &block)
1497
+
1498
+ elsif self.class.content_proc
1499
+ content = instance_eval(&self.class.content_proc)
1500
+ ::File.open(destination, "wb") { |f| f << content }
1501
+
1502
+ else
1503
+ ::File.open(destination, "wb").close
1504
+ end
1505
+ end
1506
+
1507
+ # @param overwrite [Boolean] ignore the existence of an
1508
+ # existing file
1509
+ # @raise [Errors::Fs::ReadWrite] if a file exists at our path
1510
+ # and `overwrite` is not set
1511
+ # @raise [Errors::Fs::ReadWrite] if something other than a file
1512
+ # exists at our path, such as a directory
1513
+ # @raise [Errors::Fs::ReadWrite] if our path is not writeable, eg.
1514
+ # due to a lack of permissions
1515
+ def validate_writeability(overwrite: false)
1516
+ if path.exist?
1517
+ raise Errors::Fs::ReadWrite, "File #{path} already exists" if path.file? && !overwrite
1518
+ raise Errors::Fs::ReadWrite, "Path #{path} already exists and is of type #{path.ftype}" if !path.file?
1519
+ end
1520
+
1521
+ raise Errors::Fs::ReadWrite, "Cannot write to #{path.dirname}" unless path.dirname.writable?
1522
+ end
1523
+ end
1524
+ end