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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +3 -0
- data/LICENSE +289 -0
- data/README.md +128 -0
- data/lib/fs/atomic_write.rb +121 -0
- data/lib/fs/concerns/argument_validation.rb +140 -0
- data/lib/fs/concerns/file_dsl_methods.rb +471 -0
- data/lib/fs/concerns/required_arguments.rb +141 -0
- data/lib/fs/directory/accessibility_check.rb +89 -0
- data/lib/fs/directory.rb +497 -0
- data/lib/fs/errors.rb +491 -0
- data/lib/fs/file.rb +1524 -0
- data/lib/fs/file_variant_builder.rb +269 -0
- data/lib/fs/file_variant_proxy.rb +253 -0
- data/lib/fs/files/csv.rb +26 -0
- data/lib/fs/files/gif.rb +10 -0
- data/lib/fs/files/image.rb +390 -0
- data/lib/fs/files/jpg.rb +36 -0
- data/lib/fs/files/json.rb +24 -0
- data/lib/fs/files/pdf.rb +231 -0
- data/lib/fs/files/pdf_collection.rb +64 -0
- data/lib/fs/files/png.rb +10 -0
- data/lib/fs/files/text.rb +13 -0
- data/lib/fs/files/tiff.rb +24 -0
- data/lib/fs/files/zip.rb +123 -0
- data/lib/fs/lockfile_sweeper.rb +70 -0
- data/lib/fs/tempfile_sweeper.rb +79 -0
- data/lib/fs/testing/mock/fs/configurator.rb +223 -0
- data/lib/fs/testing/mock/fs/dirs/directory.rb +41 -0
- data/lib/fs/testing/mock/fs/dsl.rb +81 -0
- data/lib/fs/testing/mock/fs/file.rb +60 -0
- data/lib/fs/testing/mock/fs/file_klass_mock.rb +350 -0
- data/lib/fs/testing/mock/fs/files/jpg.rb +14 -0
- data/lib/fs/testing/mock/fs/files/pdf.rb +19 -0
- data/lib/fs/testing/mock/fs/files/png.rb +12 -0
- data/lib/fs/testing/mock/fs/files/tiff.rb +12 -0
- data/lib/fs/testing/mock/fs/files/zip.rb +23 -0
- data/lib/fs/testing.rb +17 -0
- data/lib/fs/version.rb +3 -0
- data/lib/fs.rb +26 -0
- data/lib/gubbins/fs.rb +4 -0
- 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
|