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,471 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "active_support"
4
+ require "active_support/core_ext/class/attribute"
5
+ require "active_support/core_ext/object/try"
6
+
7
+ module Fs
8
+ module Concerns
9
+ # Contains the DSL macro methods used to build a subclass of {Fs::File}
10
+ #
11
+ # They are extracted into this concern for the purpose of readability -
12
+ # this way, they are separate from the regular `Fs::File` class methods.
13
+ module FileDslMethods
14
+ extend ActiveSupport::Concern
15
+
16
+ included do
17
+ # Inherited by subclasses unless they set their own, and looked up through the
18
+ # superclass chain on every read, so that setting them on `Fs::File` itself (eg. in an
19
+ # initializer) configures them globally, no matter when the subclasses were defined.
20
+ # Use {ClassMethods#temp_directory} and {ClassMethods#atomic_write_directory} to read
21
+ # and write them.
22
+ class_attribute :temp_directory_setting, instance_accessor: false, instance_predicate: false,
23
+ default: :system
24
+ class_attribute :atomic_write_directory_setting, instance_accessor: false, instance_predicate: false,
25
+ default: :alongside
26
+
27
+ # Here we define our _class instance variables_ the DSL macros use to
28
+ # store their settings.
29
+ #
30
+ # Why class instance variables? We want something that
31
+ #
32
+ # a) is shared by all instances (unlike regular instance variables), so it
33
+ # must exist on the class
34
+ # b) can be overridden by subclasses without affecting the parent (unlike
35
+ # class variables, eg. `@@directory_subdir`)
36
+ class << self
37
+ attr_reader :content_proc
38
+ attr_reader :directory_subdir
39
+ attr_reader :directory_args_proc
40
+ attr_reader :get_path_proc
41
+ attr_reader :variants
42
+ attr_reader :standard_variants
43
+ attr_reader :legacy_klass
44
+ attr_reader :legacy_safely_delete_directory
45
+ end
46
+ end
47
+
48
+ class_methods do
49
+ # `create_with_content_from {}` blocks allow you to define a block handler that
50
+ # returns the content that will be written to a new file on `#create`. The block
51
+ # is executed in the scope of the `File` instance and receives all parameters
52
+ # passed into `#create`.
53
+ #
54
+ # @example
55
+ # ```ruby
56
+ # create_with_content_from do
57
+ # content.upcase
58
+ # end
59
+ # ```
60
+ #
61
+ # @yieldparam kargs your block receives all other parameters passed
62
+ # into `variant(name).load` or `variant(name).create`
63
+ # @yieldreturn [Pathname, String] your block is expected to return the files content
64
+ def create_with_content_from(&block)
65
+ @content_proc = block
66
+ end
67
+
68
+ # Set a {Fs::Directory} where files of this class are to be located. Optional.
69
+ #
70
+ # The keyword arguments passed into `Fs::File.new` will be passed long to
71
+ # the {Directory}. To change that, provide a Proc via `:arguments` that
72
+ # returns an arguments Hash; the Proc will be executed in `Fs::File` instance
73
+ # scope.
74
+ #
75
+ # @example
76
+ # class Fs::Files::PDFUpload < Fs::Files::PDF
77
+ # directory Fs::Dirs::Uploads,
78
+ # subdir: "pdfs",
79
+ # arguments: -> {
80
+ # { upload: client.upload }
81
+ # }
82
+ # end
83
+ #
84
+ # @param klass [Fs::Directory] an {Fs::Directory} or any subclass
85
+ # @param subdir [String] an optional sub-directory below the given directory
86
+ # @param arguments [Proc] an optional Proc to provide the arguments the
87
+ # Directory requires
88
+ # @return [Fs::Directory, nil]
89
+ def directory(klass = nil, subdir: nil, arguments: nil)
90
+ if klass
91
+ @directory_klass = klass
92
+ @directory_subdir = subdir
93
+ @directory_args_proc = arguments
94
+ else
95
+ @directory_klass
96
+ end
97
+ end
98
+
99
+ # Configure whether this class treats files with a size of zero
100
+ # as an error or not
101
+ #
102
+ # @param value [Boolean]
103
+ # @return [Boolean]
104
+ def allows_empty_files(value = nil)
105
+ if value.nil?
106
+ @allows_empty_files
107
+ else
108
+ @allows_empty_files = value
109
+ end
110
+ end
111
+
112
+ # Configure whether this class' {.create}/{.load_or_create} calls
113
+ # serialize concurrent creators of the same path (see
114
+ # {Fs::File.with_creation_lock}). Optional, defaults to false.
115
+ #
116
+ # Atomic writes (see {#use_atomic_writes}) already keep anybody from reading a
117
+ # half-written file, and cost nothing. Locks are for files which are expensive
118
+ # to create: concurrent creators wait for the first one instead of all doing the
119
+ # work. They need an NFSv4 mount with `local_lock=none`, and leave a lockfile
120
+ # behind (see {Fs::LockfileSweeper}).
121
+ #
122
+ # Inherited by subclasses, which may override it. The variants of a file default to
123
+ # the setting of their own class; see {Fs::FileVariantBuilder#use_locks}.
124
+ #
125
+ # @example
126
+ # class Fs::Files::PDFUpload < Fs::Files::PDF
127
+ # use_locks true
128
+ # end
129
+ #
130
+ # @param value [Boolean]
131
+ # @return [Boolean]
132
+ def use_locks(value = nil)
133
+ if value.nil?
134
+ @use_locks.nil? ? false : @use_locks
135
+ else
136
+ @use_locks = value
137
+ end
138
+ end
139
+
140
+ # Configure where {Fs::File#create_temp} and {Fs::File.create_temp} put their files.
141
+ # Optional, defaults to `:system`.
142
+ #
143
+ # These are working copies, deleted when the block returns: they never become the real
144
+ # file, so they do not have to be on any particular file system. The system's temporary
145
+ # directory is usually a local disk, which is what tools working on them want.
146
+ #
147
+ # * `:system` uses the system's temporary directory.
148
+ # * An {Fs::Directory} subclass, or its name (resolved when first needed, so it may be
149
+ # autoloaded). It must not require arguments.
150
+ #
151
+ # For where files are put before they are moved into place, see {#atomic_write_directory}.
152
+ #
153
+ # Inherited by subclasses unless they set their own. Set it on `Fs::File` itself to
154
+ # configure it globally.
155
+ #
156
+ # @example
157
+ # class Fs::Files::Scan < Fs::Files::TIFF
158
+ # temp_directory "Fs::Dirs::LocalScratchDisk"
159
+ # end
160
+ #
161
+ # @param value [Symbol, Class, String, nil]
162
+ # @raise [ArgumentError]
163
+ # @return [Symbol, Class, String]
164
+ def temp_directory(value = nil)
165
+ return temp_directory_setting if value.nil?
166
+
167
+ ensure_directory_setting(:temp_directory, value, modes: Fs::File::TEMP_DIRECTORY_MODES)
168
+
169
+ self.temp_directory_setting = value
170
+ end
171
+
172
+ # Configure where files of this class are written to before they are moved into
173
+ # place (see {Fs::AtomicWrite}). Optional, defaults to `:alongside`.
174
+ #
175
+ # Unlike {#temp_directory}, these files do become the real file, so the file system
176
+ # they are on matters.
177
+ #
178
+ # * `:alongside` puts them next to the file, hidden by a leading dot. Always on the
179
+ # right file system, but visible to anything listing the directory in the meantime.
180
+ # * `:system` uses the system's temporary directory. Handy to let a tool work on a local
181
+ # disk, but on another device than the target, so the finished file is copied once more.
182
+ # * An {Fs::Directory} subclass, or its name (resolved when first needed, so it may be
183
+ # autoloaded). Put it on the same file system as your files, and a rename is all it takes.
184
+ # It must not require arguments.
185
+ #
186
+ # Inherited by subclasses unless they set their own. Set it on `Fs::File` itself to
187
+ # configure it globally.
188
+ #
189
+ # @example
190
+ # Fs::File.atomic_write_directory "Fs::Dirs::Tmp"
191
+ #
192
+ # class Fs::Files::PDFUpload < Fs::Files::PDF
193
+ # atomic_write_directory :system
194
+ # end
195
+ #
196
+ # @param value [Symbol, Class, String, nil]
197
+ # @raise [ArgumentError]
198
+ # @return [Symbol, Class, String]
199
+ def atomic_write_directory(value = nil)
200
+ return atomic_write_directory_setting if value.nil?
201
+
202
+ ensure_directory_setting(:atomic_write_directory, value, modes: Fs::File::ATOMIC_WRITE_DIRECTORY_MODES)
203
+
204
+ self.atomic_write_directory_setting = value
205
+ end
206
+
207
+ # Configure whether this class' files are written through a temporary file, which is
208
+ # moved into place once complete (see {Fs::AtomicWrite}). Optional, defaults to true.
209
+ #
210
+ # Only disable this for files which have to be written in place, eg. because something
211
+ # else is already watching their path.
212
+ #
213
+ # {Fs::File.load_or_create} relies on it: a file it finds is taken to be complete, without
214
+ # waiting for anybody still writing it. A `#create` of your own has to write through
215
+ # {Fs::File#write_atomically}, or the class has to turn this off.
216
+ #
217
+ # @example
218
+ # class Fs::Files::Upload < Fs::File
219
+ # use_atomic_writes false
220
+ # end
221
+ #
222
+ # @param value [Boolean]
223
+ # @return [Boolean]
224
+ def use_atomic_writes(value = nil)
225
+ if value.nil?
226
+ @use_atomic_writes.nil? ? true : @use_atomic_writes
227
+ else
228
+ @use_atomic_writes = value
229
+ end
230
+ end
231
+
232
+ # Set one or more file extensions. Optional.
233
+ #
234
+ # @example
235
+ # class Fs::Files::PDFUpload < Fs::Files::PDF
236
+ # extension :pdf
237
+ # end
238
+ #
239
+ # If you do provide multiple extensions, the first one will be used when creating
240
+ # new files.
241
+ #
242
+ # @param *values [Array<Symbol,String>] one or more file extensions without leading dot
243
+ # @return [Array<Symbol,String>, nil]
244
+ def extension(*values)
245
+ if values.any?
246
+ @extensions =
247
+ values.map { |value| value.to_s.delete(".") }
248
+ else
249
+ @extensions
250
+ end
251
+ end
252
+ alias_method :extensions, :extension
253
+
254
+ # Set one or more MIME types that are valid for this file. Optional.
255
+ #
256
+ # @example
257
+ # class Fs::Files::PDFUpload < Fs::Files::PDF
258
+ # mime_type "application/pdf", /^application\//
259
+ # end
260
+ #
261
+ # The MIME will be checked when validating a file.
262
+ #
263
+ # @param *values [Array<String, Regexp>] one or more MIME types
264
+ # @return [Array<String, Regexp>, nil]
265
+ def mime_type(*values)
266
+ if values.any?
267
+ @mime_types = values
268
+ else
269
+ @mime_types
270
+ end
271
+ end
272
+ alias_method :mime_types, :mime_type
273
+
274
+ # Set one or more encodings that are valid for this file. Optional.
275
+ #
276
+ # @example
277
+ # class Fs::Files::PDFUpload < Fs::Files::PDF
278
+ # encoding "utf-8", "us-ascii", /^iso-/
279
+ # end
280
+ #
281
+ # The encoding will be checked when validating a file.
282
+ #
283
+ # @param *values [Array<String,Regexp>] one or more encoding strings
284
+ # @return [Array<String,Regexp>, nil]
285
+ def encoding(*values)
286
+ if values.any?
287
+ @encodings = values
288
+ else
289
+ @encodings
290
+ end
291
+ end
292
+ alias_method :encodings, :encoding
293
+
294
+ # Set an identifying label for this file class
295
+ #
296
+ # This is useful as a definite identifier when having to distinguish
297
+ # between multiple `Fs::File classes`, eg. in `ProjectFile#file_type`.
298
+ #
299
+ # Note that identifiers are only expected to be unique within the same
300
+ # namespace, eg. no two classes below `Fs::Files::Project::` should
301
+ # share one. It is fine if, say, both `Fs::Files::Upload::Pdf` and
302
+ # `Fs::Files::Project::Pdf` share `:pdf` as their `file_type`.
303
+ #
304
+ # If no `file_type` is set manually, the first file extension is returned
305
+ # instead.
306
+ #
307
+ # @param value [Symbol]
308
+ # @return [Symbol, nil]
309
+ def file_type(value = nil)
310
+ if value
311
+ @file_type = value.to_sym
312
+ else
313
+ @file_type || extensions.try(:first).try(:to_sym)
314
+ end
315
+ end
316
+
317
+ # Define a block that returns the path for this file. Optional.
318
+ #
319
+ # The block is executed in the scope of your {Fs::File} instance,
320
+ # so it has access to all its methods and `required_arguments`.
321
+ #
322
+ # @example
323
+ # class Fs::Files::PDFUpload < Fs::Files::PDF
324
+ # required_arguments id: Integer
325
+ #
326
+ # get_path_from do
327
+ # "some/path/#{id}"
328
+ # end
329
+ # end
330
+ #
331
+ # @yield
332
+ # @yieldreturn [String, Pathname, #to_s] the path for this file instance
333
+ # @return [void]
334
+ def get_path_from(&block)
335
+ @get_path_proc = block
336
+ end
337
+
338
+ # Define a variant this file can be converted into, and how it can be
339
+ # converted. Optional.
340
+ #
341
+ # The block is executed in the scope of a {Fs::FileVariantBuilder}; see that
342
+ # class for information on the available DSL methods.
343
+ #
344
+ # @example
345
+ # class Fs::Files::PDFUpload < Fs::Files::PDF
346
+ # # Variant inheriting from `Fs::File`
347
+ # variant :text_file do
348
+ # create_with_content_from :some_method
349
+ # end
350
+ #
351
+ # # Variant inheriting from `Fs::Files::Text`
352
+ # variant(:other_text_file, Fs::Files::Text) do
353
+ # create_with_content_from :some_method
354
+ # end
355
+ #
356
+ # def some_method
357
+ # "content for the text variant"
358
+ # end
359
+ # end
360
+ #
361
+ # @param name [Symbol] the name under which the variant can be called
362
+ # @param klass [Class, String] the Fs::File subclass the variant should inherit from,
363
+ # or its fully qualified name (eg, `klass: "Fs::Files::JPG"`)
364
+ # @yield
365
+ # @return [void]
366
+ def variant(name, klass = nil, &block)
367
+ instance = Fs::FileVariantBuilder.new(name)
368
+
369
+ instance.klass = klass if klass
370
+
371
+ instance.instance_eval(&block)
372
+
373
+ (@variants ||= {})[name] = instance
374
+
375
+ @standard_variants << name if instance.standard
376
+ end
377
+
378
+ # Declare where this file used to live before some past
379
+ # reorganization, so the first access after such a change can
380
+ # transparently relocate the pre-existing file instead of
381
+ # treating it as newly missing. See {Fs::Directory.legacy} for
382
+ # the equivalent on the Directory side, and the shared design
383
+ # rationale.
384
+ #
385
+ # The block is used to build an anonymous subclass of the
386
+ # current class (same pattern as `variant`'s `define`) - override
387
+ # `#path` using plain Ruby and the class's own inherited
388
+ # `directory`/`extension`/`requires_arguments`/etc. If this
389
+ # class's old location differed only by *directory* (not by
390
+ # basename/extension), it's usually simpler to not override
391
+ # `#path` at all and instead just point `directory` at the
392
+ # associated {Fs::Directory}'s own `legacy_klass` - see
393
+ # {Fs::Directory.legacy}.
394
+ #
395
+ # If you do override `#path` here, avoid `super`: the legacy
396
+ # klass's superclass is *this* class, not `Fs::File`, so `super`
397
+ # re-applies this class's own `#path` logic instead of the base
398
+ # implementation.
399
+ #
400
+ # @param safely_delete_directory [Boolean] after migrating the
401
+ # file, also remove its now-presumably-empty legacy directory
402
+ # via `rmdir` - which only ever removes an actually-empty
403
+ # directory, so this never destroys content left behind by
404
+ # something else still sharing it (eg. `Fs::Dirs::Projects`
405
+ # also houses Pages, SourceFiles, DocumentExports, ...; their
406
+ # shared legacy directory only disappears once the last of
407
+ # them has migrated). Off by default since it's an extra
408
+ # filesystem operation most callers don't need, not because
409
+ # it's unsafe.
410
+ # @yield class-eval'd to build the anonymous subclass
411
+ # @return [void]
412
+ def legacy(safely_delete_directory: false, &block)
413
+ @legacy_klass = Class.new(self, &block)
414
+ @legacy_safely_delete_directory = safely_delete_directory
415
+ end
416
+
417
+ # This is a hook Ruby calls whenever a subclass is created. We use the opportunity
418
+ # to copy our class instance variables over to the new class.
419
+ #
420
+ # For example, when we subclass:
421
+ #
422
+ # class Fs::Files::SpecialPdf < Fs::Files::PDF
423
+ # end
424
+ #
425
+ # we want `SpecialPdf` to inherit all the settings from `PDFFile`, but still be able
426
+ # to override them without affecting the parent. For this we could also have used
427
+ # Rails `Class#class_attribute`, but that does not allow us to use the combined
428
+ # getter/setter methods we use here.
429
+ def inherited(subclass)
430
+ subclass.instance_variable_set(:@required_arguments, required_arguments.dup)
431
+ subclass.instance_variable_set(:@content_proc, content_proc.dup)
432
+ subclass.instance_variable_set(:@directory_klass, directory)
433
+ subclass.instance_variable_set(:@directory_subdir, directory_subdir)
434
+ subclass.instance_variable_set(:@directory_args_proc, directory_args_proc)
435
+ subclass.instance_variable_set(:@allows_empty_files, allows_empty_files)
436
+ subclass.instance_variable_set(:@use_locks, @use_locks)
437
+ subclass.instance_variable_set(:@use_atomic_writes, @use_atomic_writes)
438
+ subclass.instance_variable_set(:@extensions, extensions.dup)
439
+ subclass.instance_variable_set(:@mime_types, mime_types.dup)
440
+ subclass.instance_variable_set(:@encodings, encodings.dup)
441
+ subclass.instance_variable_set(:@file_type, file_type.dup)
442
+ subclass.instance_variable_set(:@get_path_proc, @get_path_proc.dup)
443
+ subclass.instance_variable_set(:@variants, variants.dup)
444
+ subclass.instance_variable_set(:@standard_variants, @standard_variants.dup)
445
+ end
446
+
447
+ private
448
+
449
+ # @param name [Symbol] the setting, for the error message
450
+ # @param value [Object]
451
+ # @param modes [Array<Symbol>] the settings which are not an {Fs::Directory}
452
+ # @raise [ArgumentError]
453
+ # @return [void]
454
+ def ensure_directory_setting(name, value, modes:)
455
+ valid =
456
+ case value
457
+ when Symbol then modes.include?(value)
458
+ when String then true
459
+ when Class then value <= Fs::Directory
460
+ else false
461
+ end
462
+
463
+ return if valid
464
+
465
+ raise ArgumentError, "#{name} must be one of #{modes.inspect}, an Fs::Directory subclass or its name, " \
466
+ "not #{value.inspect}"
467
+ end
468
+ end
469
+ end
470
+ end
471
+ end
@@ -0,0 +1,141 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Fs
4
+ module Concerns
5
+ # This concern provides the including class with a `required_arguments`
6
+ # DSL class macro, plus a `#process_required_arguments` method for persisting
7
+ # the given arguments in attributes.
8
+ #
9
+ # This allows subclasses to declare their arguments without having to overload
10
+ # `#initialize`
11
+ #
12
+ # @example
13
+ # class Test
14
+ # include Fs::Concerns::RequiredArguments
15
+ #
16
+ # requires_arguments foo: "String", bar: "Integer"
17
+ #
18
+ # def initialize(**kargs)
19
+ # process_required_arguments(**kargs)
20
+ # end
21
+ # end
22
+ #
23
+ # Test.new
24
+ # # => ArgumentError: expected nil to be String, got NilClass
25
+ #
26
+ # t = Test.new foo: "foo", bar: 1
27
+ # t.foo
28
+ # # => "foo"
29
+ # t.bar
30
+ # # => 1
31
+ module RequiredArguments
32
+ extend ActiveSupport::Concern
33
+
34
+ included do
35
+ class << self
36
+ # @return [Hash{Symbol=>Class}]
37
+ attr_reader :required_arguments
38
+ # @return [Proc, nil]
39
+ attr_reader :required_argument_validator
40
+ end
41
+ end
42
+
43
+ class_methods do
44
+ # DSL class macro for defining the arguments the including class
45
+ # requires on `#new`
46
+ #
47
+ # @param **arguments [Hash{Symbol=>Class}] a list of keyword argument names
48
+ # and the value type they expect, eg. `id: Integer, label: String`
49
+ # @return [void]
50
+ def requires_arguments(**arguments)
51
+ @required_arguments = arguments
52
+
53
+ arguments.keys.each do |argument_name|
54
+ class_eval { attr_reader argument_name }
55
+ end
56
+ end
57
+
58
+ # DSL class macro for validating required arguments
59
+ #
60
+ # Your block will receive the arguments as keyword arguments and
61
+ # should raise a RuntimeError if it is not satisfied
62
+ #
63
+ # @return [void]
64
+ def validate_arguments(&block)
65
+ @required_argument_validator = block
66
+ end
67
+ end
68
+
69
+ private
70
+
71
+ # Takes the given keyword argument hash, type-checks the parameters and
72
+ # persists the values in instance variables of the same name.
73
+ #
74
+ # If a validator has been specified with `validate_arguments do .. end`,
75
+ # it is called.
76
+ #
77
+ # More than one type can be given in form of an array: `[TrueClass, FalseClass]`
78
+ #
79
+ # Type specs must be given as String class names, resolved via +constantize+
80
+ # at call time. This avoids the load-order problems that arise when a class
81
+ # constant is referenced at class-definition time.
82
+ #
83
+ # More than one type can be given as an Array of Strings: +["TrueClass", "FalseClass"]+
84
+ #
85
+ # @param kargs [Hash{Symbol=>}] a keyword argument hash
86
+ # @return [void]
87
+ def process_required_arguments(**kargs)
88
+ (self.class.required_arguments || {}).each do |argument_name, argument_type|
89
+ argument_value = kargs[argument_name]
90
+ argument_types = [*argument_type]
91
+
92
+ argument_types.each do |t|
93
+ next if t.is_a?(String)
94
+
95
+ raise ArgumentError, "#{self.class.name}: type spec for :#{argument_name} must be " \
96
+ "a String class name (e.g. \"#{t.name}\"), got #{t.inspect}"
97
+ end
98
+
99
+ resolved_types = argument_types.map(&:constantize)
100
+
101
+ unless resolved_types.any? { |klass| argument_value.is_a?(klass) }
102
+ raise ArgumentError, "#{self.class.name}: expected #{argument_value.inspect} to be "\
103
+ "#{resolved_types.map(&:name).join(', ')}, "\
104
+ "got #{argument_value.class.name}"
105
+ end
106
+
107
+ instance_variable_set(:"@#{argument_name}", argument_value)
108
+ end
109
+
110
+ if self.class.required_argument_validator
111
+ required_kargs =
112
+ (self.class.required_arguments || {}).keys
113
+ .then do |required_argument_names|
114
+ kargs.slice(*required_argument_names)
115
+ end
116
+
117
+ self.class
118
+ .required_argument_validator
119
+ .call(**required_kargs)
120
+ end
121
+ end
122
+
123
+ # Returns a Hash of all required arguments and their values
124
+ # provided to this instance
125
+ #
126
+ # @return [Hash{Symbol=>Object}]
127
+ def required_arguments_given
128
+ if self.class.required_arguments&.any?
129
+ self.class
130
+ .required_arguments
131
+ .keys
132
+ .each_with_object({}) do |argument_name, hash|
133
+ hash[argument_name] = send(argument_name)
134
+ end
135
+ else
136
+ {}
137
+ end
138
+ end
139
+ end
140
+ end
141
+ end
@@ -0,0 +1,89 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "active_support"
4
+ require "active_support/core_ext/string/inflections"
5
+
6
+ module Fs
7
+ class Directory
8
+ # Makes sure a directory exists, creating it if allowed to, and can be read and written
9
+ #
10
+ # A configured base directory is hardcoded and supposed to be there, so trouble with
11
+ # one raises {Errors::Fs::BaseDirectory} exceptions. Any other directory is part of a
12
+ # file's path, and fails with {Errors::Fs::ReadWrite} like the file itself would.
13
+ class AccessibilityCheck
14
+ # @param path [Pathname]
15
+ # @param when_missing [Symbol] `:create` or `:raise`
16
+ # @param base [Boolean] is `path` a configured base directory?
17
+ def initialize(path, when_missing:, base:)
18
+ @path = path
19
+ @when_missing = when_missing
20
+ @base = base
21
+ end
22
+
23
+ # @return [true]
24
+ # @raise [Errors::Fs::BaseDirectory, Errors::Fs::ReadWrite] see {Errors::Fs::BaseDirectory}
25
+ # for the ways in which a directory can be unusable
26
+ def run
27
+ ensure_existence unless directory?
28
+
29
+ raise_unusable(:unreadable, "is not readable") unless path.readable?
30
+ raise_unusable(:unwriteable, "is not writable") unless path.writable?
31
+
32
+ true
33
+ end
34
+
35
+ private
36
+
37
+ attr_reader :path, :when_missing
38
+
39
+ # @return [Boolean]
40
+ def base?
41
+ @base
42
+ end
43
+
44
+ # Tells a missing path from one that cannot be inspected at all. `File.directory?` reports
45
+ # both as `false`, which sent a stale NFS mount down the "missing, so create it" path.
46
+ #
47
+ # @return [Boolean]
48
+ # @raise [Errors::Fs::BaseDirectory::Inaccessible] if `stat` fails for any reason but absence
49
+ # (permissions, stale NFS handle, I/O error)
50
+ def directory?
51
+ path.stat.directory?
52
+ rescue Errno::ENOENT, Errno::ENOTDIR
53
+ false
54
+ rescue SystemCallError
55
+ raise_unusable(:inaccessible, "cannot be accessed")
56
+ end
57
+
58
+ # Creates the directory, or raises if we are not allowed to or something else is there
59
+ #
60
+ # Expects {#directory?} to have found no directory at `path`.
61
+ #
62
+ # @return [void]
63
+ def ensure_existence
64
+ # A file or dangling symlink in the way would otherwise surface as a cryptic EEXIST/ENOTDIR from mkdir_p
65
+ raise_unusable(:is_file, "exists, but is not a directory") if path.exist? || path.symlink?
66
+ raise_unusable(:missing, "does not exist") if when_missing == :raise
67
+
68
+ create
69
+ end
70
+
71
+ # @return [void]
72
+ def create
73
+ path.mkpath
74
+ rescue SystemCallError
75
+ raise_unusable(:create_failed, "could not be created")
76
+ end
77
+
78
+ # @param kind [Symbol] the underscored name of one of the {Errors::Fs::BaseDirectory} children
79
+ # @param message [String] with the path as its implicit subject
80
+ # @raise [Errors::Fs::BaseDirectory, Errors::Fs::ReadWrite]
81
+ def raise_unusable(kind, message)
82
+ error_class =
83
+ base? ? Errors::Fs::BaseDirectory.const_get(kind.to_s.camelize) : Errors::Fs::ReadWrite
84
+
85
+ error_class.raise(message, label: path.to_s)
86
+ end
87
+ end
88
+ end
89
+ end