minitar 1.0.2 → 1.1.1

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 (57) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +326 -0
  3. data/CODE_OF_CONDUCT.md +167 -0
  4. data/CONTRIBUTING.md +312 -0
  5. data/CONTRIBUTORS.md +27 -0
  6. data/LICENCE.md +42 -0
  7. data/Manifest.txt +31 -8
  8. data/README.md +82 -0
  9. data/Rakefile +74 -20
  10. data/SECURITY.md +54 -0
  11. data/lib/minitar/input.rb +242 -189
  12. data/lib/minitar/output.rb +72 -64
  13. data/lib/minitar/pax_header.rb +111 -0
  14. data/lib/minitar/posix_header.rb +276 -239
  15. data/lib/minitar/reader.rb +226 -231
  16. data/lib/minitar/version.rb +5 -0
  17. data/lib/minitar/writer.rb +246 -299
  18. data/lib/minitar.rb +134 -115
  19. data/licenses/bsdl.txt +20 -0
  20. data/licenses/dco.txt +34 -0
  21. data/licenses/ruby.txt +52 -0
  22. data/test/fixtures/issue_46.tar.gz +0 -0
  23. data/test/fixtures/issue_62.tar.gz +0 -0
  24. data/test/fixtures/tar_input.tgz +0 -0
  25. data/test/fixtures/test_input_non_strict_octal.tgz +0 -0
  26. data/test/fixtures/test_input_relative.tgz +0 -0
  27. data/test/fixtures/test_input_space_octal.tgz +0 -0
  28. data/test/fixtures/test_minitar.tar.gz +0 -0
  29. data/test/minitest_helper.rb +12 -1
  30. data/test/support/minitar_test_helpers/fixtures.rb +38 -0
  31. data/test/support/minitar_test_helpers/header.rb +130 -0
  32. data/test/support/minitar_test_helpers/tarball.rb +324 -0
  33. data/test/support/minitar_test_helpers.rb +36 -0
  34. data/test/test_filename_boundary_conditions.rb +74 -0
  35. data/test/test_gnu_tar_compatibility.rb +92 -0
  36. data/test/test_integration_pack_unpack_cycle.rb +38 -0
  37. data/test/test_issue_46.rb +5 -23
  38. data/test/test_issue_62.rb +50 -0
  39. data/test/test_minitar.rb +168 -39
  40. data/test/test_path_normalization.rb +170 -0
  41. data/test/test_pax_header.rb +104 -0
  42. data/test/test_pax_support.rb +66 -0
  43. data/test/test_tar_header.rb +289 -75
  44. data/test/test_tar_input.rb +14 -61
  45. data/test/test_tar_output.rb +7 -9
  46. data/test/test_tar_reader.rb +17 -18
  47. data/test/test_tar_writer.rb +105 -126
  48. data/test/test_windows_extraction.rb +121 -0
  49. metadata +108 -95
  50. data/Code-of-Conduct.md +0 -128
  51. data/Contributing.md +0 -94
  52. data/History.md +0 -236
  53. data/Licence.md +0 -15
  54. data/README.rdoc +0 -92
  55. data/docs/bsdl.txt +0 -19
  56. data/docs/ruby.txt +0 -56
  57. data/test/support/tar_test_helpers.rb +0 -134
@@ -1,267 +1,304 @@
1
- class Minitar
2
- # Implements the POSIX tar header as a Ruby class. The structure of
3
- # the POSIX tar header is:
4
- #
5
- # struct tarfile_entry_posix
6
- # { // pack/unpack
7
- # char name[100]; // ASCII (+ Z unless filled) a100/Z100
8
- # char mode[8]; // 0 padded, octal, null a8 /A8
9
- # char uid[8]; // 0 padded, octal, null a8 /A8
10
- # char gid[8]; // 0 padded, octal, null a8 /A8
11
- # char size[12]; // 0 padded, octal, null a12 /A12
12
- # char mtime[12]; // 0 padded, octal, null a12 /A12
13
- # char checksum[8]; // 0 padded, octal, null, space a8 /A8
14
- # char typeflag[1]; // see below a /a
15
- # char linkname[100]; // ASCII + (Z unless filled) a100/Z100
16
- # char magic[6]; // "ustar\0" a6 /A6
17
- # char version[2]; // "00" a2 /A2
18
- # char uname[32]; // ASCIIZ a32 /Z32
19
- # char gname[32]; // ASCIIZ a32 /Z32
20
- # char devmajor[8]; // 0 padded, octal, null a8 /A8
21
- # char devminor[8]; // 0 padded, octal, null a8 /A8
22
- # char prefix[155]; // ASCII (+ Z unless filled) a155/Z155
23
- # };
24
- #
25
- # The #typeflag is one of several known values.
26
- #
27
- # POSIX indicates that "A POSIX-compliant implementation must treat any
28
- # unrecognized typeflag value as a regular file."
29
- class PosixHeader
30
- BLOCK_SIZE = 512
31
- MAGIC_BYTES = "ustar".freeze
32
-
33
- GNU_EXT_LONG_LINK = "././@LongLink"
34
-
35
- # Fields that must be set in a POSIX tar(1) header.
36
- REQUIRED_FIELDS = [:name, :size, :prefix, :mode].freeze
37
- # Fields that may be set in a POSIX tar(1) header.
38
- OPTIONAL_FIELDS = [
39
- :uid, :gid, :mtime, :checksum, :typeflag, :linkname, :magic, :version,
40
- :uname, :gname, :devmajor, :devminor
41
- ].freeze
1
+ # frozen_string_literal: true
2
+
3
+ # Implements the POSIX tar header as a Ruby class. The structure of
4
+ # the POSIX tar header is:
5
+ #
6
+ # ```c
7
+ # struct tarfile_entry_posix
8
+ # { // pack unpack
9
+ # char name[100]; // ASCII (+ Z unless filled) a100 Z100
10
+ # char mode[8]; // 0 padded, octal, null a8 A8
11
+ # char uid[8]; // 0 padded, octal, null a8 A8
12
+ # char gid[8]; // 0 padded, octal, null a8 A8
13
+ # char size[12]; // 0 padded, octal, null a12 A12
14
+ # char mtime[12]; // 0 padded, octal, null a12 A12
15
+ # char checksum[8]; // 0 padded, octal, null, space a8 A8
16
+ # char typeflag[1]; // see below a a
17
+ # char linkname[100]; // ASCII + (Z unless filled) a100 Z100
18
+ # char magic[6]; // "ustar\0" a6 A6
19
+ # char version[2]; // "00" a2 A2
20
+ # char uname[32]; // ASCIIZ a32 Z32
21
+ # char gname[32]; // ASCIIZ a32 Z32
22
+ # char devmajor[8]; // 0 padded, octal, null a8 A8
23
+ # char devminor[8]; // 0 padded, octal, null a8 A8
24
+ # char prefix[155]; // ASCII (+ Z unless filled) a155 Z155
25
+ # };
26
+ # ```
27
+ #
28
+ # The #typeflag is one of several known values. POSIX indicates that "A POSIX-compliant
29
+ # implementation must treat any unrecognized typeflag value as a regular file."
30
+ class Minitar::PosixHeader
31
+ BLOCK_SIZE = 512
32
+ MAGIC_BYTES = "ustar"
33
+
34
+ GNU_EXT_LONG_LINK = "././@LongLink"
35
+
36
+ # Fields that must be set in a POSIX tar(1) header.
37
+ REQUIRED_FIELDS = [:name, :size, :prefix, :mode].freeze
38
+ # Fields that may be set in a POSIX tar(1) header.
39
+ OPTIONAL_FIELDS = [
40
+ :uid, :gid, :mtime, :checksum, :typeflag, :linkname, :magic, :version, :uname,
41
+ :gname, :devmajor, :devminor
42
+ ].freeze
43
+
44
+ # All fields available in a POSIX tar(1) header.
45
+ FIELDS = (REQUIRED_FIELDS + OPTIONAL_FIELDS).freeze
46
+
47
+ FIELDS.each do |f|
48
+ attr_reader f.to_sym
49
+ end
42
50
 
43
- # All fields available in a POSIX tar(1) header.
44
- FIELDS = (REQUIRED_FIELDS + OPTIONAL_FIELDS).freeze
51
+ ##
52
+ def name=(value)
53
+ valid_name!(value)
54
+ @name = value
55
+ end
45
56
 
46
- FIELDS.each do |f|
47
- attr_reader f.to_sym unless f.to_sym == :name
57
+ attr_writer :size
58
+
59
+ # The pack format passed to Array#pack for encoding a header.
60
+ HEADER_PACK_FORMAT = "a100a8a8a8a12a12a7aaa100a6a2a32a32a8a8a155"
61
+ # The unpack format passed to String#unpack for decoding a header.
62
+ HEADER_UNPACK_FORMAT = "Z100A8A8A8a12A12A8aZ100A6A2Z32Z32A8A8Z155"
63
+
64
+ class << self
65
+ # Creates a new PosixHeader from a data stream.
66
+ def from_stream(stream) = from_data(stream.read(BLOCK_SIZE))
67
+
68
+ # Creates a new PosixHeader from a BLOCK_SIZE-byte data buffer.
69
+ def from_data(data)
70
+ fields = data.unpack(HEADER_UNPACK_FORMAT)
71
+ name = fields.shift
72
+ mode = fields.shift.oct
73
+ uid = fields.shift.oct
74
+ gid = fields.shift.oct
75
+ size = parse_numeric_field(fields.shift)
76
+ mtime = fields.shift.oct
77
+ checksum = fields.shift.oct
78
+ typeflag = fields.shift
79
+ linkname = fields.shift
80
+ magic = fields.shift
81
+ version = fields.shift.oct
82
+ uname = fields.shift
83
+ gname = fields.shift
84
+ devmajor = fields.shift.oct
85
+ devminor = fields.shift.oct
86
+ prefix = fields.shift
87
+
88
+ empty = !data.each_byte.any?(&:nonzero?)
89
+
90
+ new(
91
+ name: name,
92
+ mode: mode,
93
+ uid: uid,
94
+ gid: gid,
95
+ size: size,
96
+ mtime: mtime,
97
+ checksum: checksum,
98
+ typeflag: typeflag,
99
+ magic: magic,
100
+ version: version,
101
+ uname: uname,
102
+ gname: gname,
103
+ devmajor: devmajor,
104
+ devminor: devminor,
105
+ prefix: prefix,
106
+ empty: empty,
107
+ linkname: linkname
108
+ )
48
109
  end
49
110
 
50
- # The name of the file. By default, limited to 100 bytes. Required. May be
51
- # longer (up to BLOCK_SIZE bytes) if using the GNU long name tar extension.
52
- attr_accessor :name
53
-
54
- # The pack format passed to Array#pack for encoding a header.
55
- HEADER_PACK_FORMAT = "a100a8a8a8a12a12a7aaa100a6a2a32a32a8a8a155".freeze
56
- # The unpack format passed to String#unpack for decoding a header.
57
- HEADER_UNPACK_FORMAT = "Z100A8A8A8A12A12A8aZ100A6A2Z32Z32A8A8Z155".freeze
111
+ private
58
112
 
59
- class << self
60
- # Creates a new PosixHeader from a data stream.
61
- def from_stream(stream)
62
- from_data(stream.read(BLOCK_SIZE))
63
- end
113
+ def parse_numeric_field(string)
114
+ return string.oct if /\A[0-7 \0]*\z/.match?(string) # \0 appears as a padding
115
+ return parse_base256(string) if string.bytes.first == 0x80 || string.bytes.first == 0xff
116
+ raise ArgumentError, "#{string.inspect} is not a valid numeric field"
117
+ end
64
118
 
65
- # Creates a new PosixHeader from a data stream. Deprecated; use
66
- # PosixHeader.from_stream instead.
67
- def new_from_stream(stream)
68
- warn "#{__method__} has been deprecated; use from_stream instead."
69
- from_stream(stream)
119
+ def parse_base256(string)
120
+ # https://www.gnu.org/software/tar/manual/html_node/Extensions.html
121
+ bytes = string.bytes
122
+ case bytes.first
123
+ when 0x80 # Positive number: *non-leading* bytes, number in big-endian order
124
+ bytes[1..].inject(0) { |r, byte| (r << 8) | byte }
125
+ when 0xff # Negative number: *all* bytes, two's complement in big-endian order
126
+ result = bytes.inject(0) { |r, byte| (r << 8) | byte }
127
+ bit_length = bytes.size * 8
128
+ result - (1 << bit_length)
129
+ else
130
+ raise ArgumentError, "Invalid binary field format"
70
131
  end
132
+ end
133
+ end
71
134
 
72
- # Creates a new PosixHeader from a BLOCK_SIZE-byte data buffer.
73
- def from_data(data)
74
- fields = data.unpack(HEADER_UNPACK_FORMAT)
75
- name = fields.shift
76
- mode = fields.shift.oct
77
- uid = fields.shift.oct
78
- gid = fields.shift.oct
79
- size = strict_oct(fields.shift)
80
- mtime = fields.shift.oct
81
- checksum = fields.shift.oct
82
- typeflag = fields.shift
83
- linkname = fields.shift
84
- magic = fields.shift
85
- version = fields.shift.oct
86
- uname = fields.shift
87
- gname = fields.shift
88
- devmajor = fields.shift.oct
89
- devminor = fields.shift.oct
90
- prefix = fields.shift
91
-
92
- empty = !data.each_byte.any?(&:nonzero?)
93
-
94
- new(
95
- name: name,
96
- mode: mode,
97
- uid: uid,
98
- gid: gid,
99
- size: size,
100
- mtime: mtime,
101
- checksum: checksum,
102
- typeflag: typeflag,
103
- magic: magic,
104
- version: version,
105
- uname: uname,
106
- gname: gname,
107
- devmajor: devmajor,
108
- devminor: devminor,
109
- prefix: prefix,
110
- empty: empty,
111
- linkname: linkname
112
- )
113
- end
135
+ # Creates a new PosixHeader from a Hash. A PosixHeader cannot be created unless `name`,
136
+ # `size`, `prefix`, and `mode` are provided.
137
+ def initialize(v)
138
+ REQUIRED_FIELDS.each do |f|
139
+ raise ArgumentError, "Field #{f} is required." unless v.key?(f)
140
+ end
114
141
 
115
- private
142
+ v[:mtime] = v[:mtime].to_i
143
+ v[:checksum] ||= ""
144
+ v[:typeflag] ||= "0"
145
+ v[:magic] ||= MAGIC_BYTES
146
+ v[:version] ||= "00"
116
147
 
117
- def strict_oct(string)
118
- return string.oct if /\A[0-7 ]*\z/.match?(string)
119
- raise ArgumentError, "#{string.inspect} is not a valid octal string"
120
- end
148
+ FIELDS.each do |f|
149
+ instance_variable_set(:"@#{f}", v[f])
121
150
  end
122
151
 
123
- # Creates a new PosixHeader. A PosixHeader cannot be created unless
124
- # +name+, +size+, +prefix+, and +mode+ are provided.
125
- def initialize(v)
126
- REQUIRED_FIELDS.each do |f|
127
- raise ArgumentError, "Field #{f} is required." unless v.key?(f)
128
- end
152
+ @empty = v[:empty]
129
153
 
130
- v[:mtime] = v[:mtime].to_i
131
- v[:checksum] ||= ""
132
- v[:typeflag] ||= "0"
133
- v[:magic] ||= MAGIC_BYTES
134
- v[:version] ||= "00"
154
+ valid_name!(v[:name]) unless v[:empty]
155
+ end
135
156
 
136
- FIELDS.each do |f|
137
- instance_variable_set(:"@#{f}", v[f])
138
- end
157
+ # Indicates if the header was an empty header.
158
+ def empty? = @empty
139
159
 
140
- @empty = v[:empty]
141
- end
160
+ # Indicates if the header has a valid magic value.
161
+ def valid? = empty? || @magic == MAGIC_BYTES
142
162
 
143
- # Indicates if the header was an empty header.
144
- def empty?
145
- @empty
146
- end
163
+ # Returns `true` if the header is a long name special header which indicates
164
+ # that the next block of data is the filename.
165
+ def long_name? = typeflag == "L" && name == GNU_EXT_LONG_LINK
147
166
 
148
- # Indicates if the header has a valid magic value.
149
- def valid?
150
- empty? || @magic == MAGIC_BYTES
151
- end
167
+ # Returns `true` if the header is a PAX extended header which contains
168
+ # metadata for the next file entry.
169
+ def pax_header? = typeflag == "x"
152
170
 
153
- # Returns +true+ if the header is a long name special header which indicates
154
- # that the next block of data is the filename.
155
- def long_name?
156
- typeflag == "L" && name == GNU_EXT_LONG_LINK
157
- end
171
+ # Sets the `name` to the `value` provided and clears `prefix`.
172
+ #
173
+ # Used by Minitar::Reader#each_entry to set the long name when processing GNU long
174
+ # filename extensions.
175
+ #
176
+ # The `value` must be the complete name, including leading directory components.
177
+ def long_name=(value)
178
+ valid_name!(value)
158
179
 
159
- # A string representation of the header.
160
- def to_s
161
- update_checksum
162
- header(@checksum)
163
- end
164
- alias_method :to_str, :to_s
180
+ @prefix = ""
181
+ @name = value
182
+ end
165
183
 
166
- # Update the checksum field.
167
- def update_checksum
168
- hh = header(" " * 8)
169
- @checksum = oct(calculate_checksum(hh), 6)
170
- end
184
+ # A string representation of the header.
185
+ def to_s
186
+ update_checksum
187
+ header(@checksum)
188
+ end
189
+ alias_method :to_str, :to_s
171
190
 
172
- private
191
+ # TODO: In Minitar 2, PosixHeader#to_str will be removed.
173
192
 
174
- def oct(num, len)
175
- if num.nil?
176
- "\0" * (len + 1)
177
- else
178
- "%0#{len}o" % num
179
- end
180
- end
193
+ # Update the checksum field.
194
+ def update_checksum
195
+ hh = header(" " * 8)
196
+ @checksum = oct(calculate_checksum(hh), 6)
197
+ end
198
+ ##
199
+ # :attr_accessor: name
200
+ # The name of the file. Required.
201
+ #
202
+ # By default, limited to 100 bytes, but may be up to BLOCK_SIZE bytes if using the
203
+ # GNU long name tar extension.
204
+
205
+ ##
206
+ # :attr_accessor: size
207
+ # The size of the file. Required.
208
+
209
+ ##
210
+ # :attr_reader: prefix
211
+ # The prefix of the file; the path before #name. Limited to 155 bytes.
212
+ # Required.
213
+
214
+ ##
215
+ # :attr_reader: mode
216
+ # The Unix file mode of the file. Stored as an octal integer. Required.
217
+
218
+ ##
219
+ # :attr_reader: uid
220
+ # The Unix owner user ID of the file. Stored as an octal integer.
221
+
222
+ ##
223
+ # :attr_reader: uname
224
+ # The user name of the Unix owner of the file.
225
+
226
+ ##
227
+ # :attr_reader: gid
228
+ # The Unix owner group ID of the file. Stored as an octal integer.
229
+
230
+ ##
231
+ # :attr_reader: gname
232
+ # The group name of the Unix owner of the file.
233
+
234
+ ##
235
+ # :attr_reader: mtime
236
+ # The modification time of the file in epoch seconds. Stored as an
237
+ # octal integer.
238
+
239
+ ##
240
+ # :attr_reader: checksum
241
+ # The checksum of the file. Stored as an octal integer. Calculated
242
+ # before encoding the header as a string.
243
+
244
+ ##
245
+ # :attr_reader: typeflag
246
+ # The type of record in the file.
247
+ #
248
+ # - `0`: Regular file. NULL should be treated as a synonym, for compatibility purposes.
249
+ # - `1`: Hard link.
250
+ # - `2`: Symbolic link.
251
+ # - `3`: Character device node.
252
+ # - `4`: Block device node.
253
+ # - `5`: Directory.
254
+ # - `6`: FIFO node.
255
+ # - `7`: Reserved.
256
+ # - `L`: GNU extension for long filenames when #name is `././@LongLink`.
257
+
258
+ ##
259
+ # :attr_reader: linkname
260
+ # The target of the symbolic link.
261
+
262
+ ##
263
+ # :attr_reader: magic
264
+ # Always "ustar\0".
265
+
266
+ ##
267
+ # :attr_reader: version
268
+ # Always "00"
269
+
270
+ ##
271
+ # :attr_reader: devmajor
272
+ # The major device ID. Not currently used.
273
+
274
+ ##
275
+ # :attr_reader: devminor
276
+ # The minor device ID. Not currently used.
277
+
278
+ private
279
+
280
+ def valid_name!(value)
281
+ return if value.is_a?(String) && !value.empty?
282
+ raise ArgumentError, "Field name must be a non-empty string"
283
+ end
181
284
 
182
- def calculate_checksum(hdr)
183
- hdr.unpack("C*").inject { |a, e| a + e }
285
+ def oct(num, len)
286
+ if num.nil?
287
+ "\0" * (len + 1)
288
+ else
289
+ "%0#{len}o" % num
184
290
  end
291
+ end
185
292
 
186
- def header(chksum)
187
- arr = [name, oct(mode, 7), oct(uid, 7), oct(gid, 7), oct(size, 11),
188
- oct(mtime, 11), chksum, " ", typeflag, linkname, magic, version,
189
- uname, gname, oct(devmajor, 7), oct(devminor, 7), prefix]
190
- str = arr.pack(HEADER_PACK_FORMAT)
191
- str + "\0" * ((BLOCK_SIZE - str.bytesize) % BLOCK_SIZE)
192
- end
293
+ def calculate_checksum(hdr)
294
+ hdr.unpack("C*").inject(:+)
295
+ end
193
296
 
194
- ##
195
- # :attr_reader: size
196
- # The size of the file. Required.
197
-
198
- ##
199
- # :attr_reader: prefix
200
- # The prefix of the file; the path before #name. Limited to 155 bytes.
201
- # Required.
202
-
203
- ##
204
- # :attr_reader: mode
205
- # The Unix file mode of the file. Stored as an octal integer. Required.
206
-
207
- ##
208
- # :attr_reader: uid
209
- # The Unix owner user ID of the file. Stored as an octal integer.
210
-
211
- ##
212
- # :attr_reader: uname
213
- # The user name of the Unix owner of the file.
214
-
215
- ##
216
- # :attr_reader: gid
217
- # The Unix owner group ID of the file. Stored as an octal integer.
218
-
219
- ##
220
- # :attr_reader: gname
221
- # The group name of the Unix owner of the file.
222
-
223
- ##
224
- # :attr_reader: mtime
225
- # The modification time of the file in epoch seconds. Stored as an
226
- # octal integer.
227
-
228
- ##
229
- # :attr_reader: checksum
230
- # The checksum of the file. Stored as an octal integer. Calculated
231
- # before encoding the header as a string.
232
-
233
- ##
234
- # :attr_reader: typeflag
235
- # The type of record in the file.
236
- #
237
- # +0+:: Regular file. NULL should be treated as a synonym, for compatibility
238
- # purposes.
239
- # +1+:: Hard link.
240
- # +2+:: Symbolic link.
241
- # +3+:: Character device node.
242
- # +4+:: Block device node.
243
- # +5+:: Directory.
244
- # +6+:: FIFO node.
245
- # +7+:: Reserved.
246
-
247
- ##
248
- # :attr_reader: linkname
249
- # The name of the link stored. Not currently used.
250
-
251
- ##
252
- # :attr_reader: magic
253
- # Always "ustar\0".
254
-
255
- ##
256
- # :attr_reader: version
257
- # Always "00"
258
-
259
- ##
260
- # :attr_reader: devmajor
261
- # The major device ID. Not currently used.
262
-
263
- ##
264
- # :attr_reader: devminor
265
- # The minor device ID. Not currently used.
297
+ def header(chksum)
298
+ arr = [name, oct(mode, 7), oct(uid, 7), oct(gid, 7), oct(size, 11),
299
+ oct(mtime, 11), chksum, " ", typeflag, linkname, magic, version,
300
+ uname, gname, oct(devmajor, 7), oct(devminor, 7), prefix]
301
+ str = arr.pack(HEADER_PACK_FORMAT)
302
+ str + "\0" * ((BLOCK_SIZE - str.bytesize) % BLOCK_SIZE)
266
303
  end
267
304
  end