Class: Cybertrain::UploadedFile

Inherits:
Object
  • Object
show all
Defined in:
cybertrain/http/uploaded_file.rb

Overview

An uploaded file, immutable once built. Get one from params.nested(:post).upload(:cover); it is never put in permit’s result, so mass assignment cannot attach a file.

The names UploadedFile, Multipart and BlobStore are reserved: an app class must not reuse them (class names are global under Spinel).

Examples:

in a controller

file = params.nested(:post).upload(:cover)
if file && !file.empty? && file.image?
  File.binwrite("tmp/cover", file.body_bytes)
end

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.blank ⇒ UploadedFile

The sentinel for “no file”: empty name, type and body. Params#upload style code compares with empty?, not nil (NOTES rules 7/11).

Returns:



62
63
64
65
66
67
# File 'cybertrain/http/uploaded_file.rb', line 62

def self.blank
  name = ""
  declared = ""
  data = "".b
  UploadedFile.new(name, declared, data)
end

.content_disposition(disposition, filename) ⇒ String

A Content-Disposition header value for a download, ASCII only (the response is assembled with a binary body, and CRuby refuses to join a non-ASCII UTF-8 header to it):

attachment; filename="caf__.png"; filename*=UTF-8''caf%C3%A9.png

filename is a fallback with every byte outside [A-Za-z0-9._ -] replaced by “_” (so a quote, backslash, CR or LF can never reach the header); filename* is the RFC 5987 percent form of the real name.

Parameters:

  • disposition (String) —

    “inline” or “attachment”; anything else means “attachment”

  • filename (String)

Returns:

  • (String)


355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
# File 'cybertrain/http/uploaded_file.rb', line 355

def self.content_disposition(disposition, filename)
  kind = disposition == "inline" ? "inline" : "attachment"
  out = +""
  out << kind
  out << "; filename=\""
  n = filename.bytesize
  i = 0
  while i < n
    b = filename.getbyte(i)
    if (b >= 0x41 && b <= 0x5A) || (b >= 0x61 && b <= 0x7A) || (b >= 0x30 && b <= 0x39) || b == 0x2E || b == 0x5F || b == 0x20 || b == 0x2D
      out << filename.byteslice(i, 1)
    else
      out << "_"
    end
    i += 1
  end
  out << "\"; filename*=UTF-8''"
  i = 0
  while i < n
    b = filename.getbyte(i)
    if UploadedFile.attr_char?(b)
      out << filename.byteslice(i, 1)
    else
      out << "%"
      out << UPPER_HEX.byteslice((b >> 4) & 0xF, 1)
      out << UPPER_HEX.byteslice(b & 0xF, 1)
    end
    i += 1
  end
  out
end

.content_disposition_utf8(disposition, filename) ⇒ String

A Content-Disposition header value for a download, the way Rails’ send_data writes it (RFC 6266), ASCII only:

attachment; filename="r?sum?.csv"; filename*=UTF-8''r%C3%A9sum%C3%A9.csv

The quoted filename is a fallback for old clients: every non-ASCII character and every control character becomes one ?, and " and \ are escaped with a backslash. filename* is the RFC 5987 percent form of the real name, every byte outside the attr-char set encoded, so the original name survives. An empty filename gives the bare disposition. Unlike content_disposition the name is not sanitized: pass only a name the application chose.

Examples:

UploadedFile.content_disposition_utf8("attachment", "a b.txt") # => "attachment; filename=\"a b.txt\"; filename*=UTF-8''a%20b.txt"

Parameters:

  • disposition (String) —

    “inline” or “attachment”; anything else means “attachment”

  • filename (String) —

    may be empty

Returns:

  • (String)


406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
# File 'cybertrain/http/uploaded_file.rb', line 406

def self.content_disposition_utf8(disposition, filename)
  kind = disposition == "inline" ? "inline" : "attachment"
  s = filename.to_s # NOTES rule 62: a fresh local for the byte scans
  n = s.bytesize
  return kind if n == 0

  out = +""
  out << kind
  out << "; filename=\""
  i = 0
  high = false # the previous byte was part of a non-ASCII character
  while i < n
    b = s.getbyte(i)
    if b >= 0x80
      out << "?" if b >= 0xC0 || !high
      high = true
    else
      high = false
      if b < 0x20 || b == 0x7F
        out << "?"
      elsif b == 0x22 || b == 0x5C
        out << "\\"
        out << s.byteslice(i, 1)
      else
        out << s.byteslice(i, 1)
      end
    end
    i += 1
  end
  out << "\"; filename*=UTF-8''"
  i = 0
  while i < n
    b = s.getbyte(i)
    if UploadedFile.attr_char?(b)
      out << s.byteslice(i, 1)
    else
      out << "%"
      out << UPPER_HEX.byteslice((b >> 4) & 0xF, 1)
      out << UPPER_HEX.byteslice(b & 0xF, 1)
    end
    i += 1
  end
  out
end

.inline_safe?(type) ⇒ Boolean

Exact match against INLINE_SAFE_TYPES (no parameters, no case folding).

Parameters:

  • type (String)

Returns:

  • (Boolean)


190
191
192
# File 'cybertrain/http/uploaded_file.rb', line 190

def self.inline_safe?(type)
  INLINE_SAFE_TYPES.include?(type)
end

.sanitize_filename(raw) ⇒ String

A display filename from whatever the client sent. The result is never a path and holds nothing that is dangerous in a header or a page:

  • everything up to the last “/” or “" is dropped (a traversal prefix or a Windows path);
  • control bytes, DEL and the characters " < > : * ? | are dropped;
  • bidi controls and zero-width characters (U+200B-U+200F, U+202A-U+202E, U+2066-U+2069, U+FEFF) are dropped, so a name cannot display reversed;
  • leading and trailing dots and spaces are stripped;
  • it is cut to 255 bytes on a character boundary;
  • a result that is empty or not valid UTF-8 becomes “upload”.

Parameters:

  • raw (String)

Returns:

  • (String)


208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
# File 'cybertrain/http/uploaded_file.rb', line 208

def self.sanitize_filename(raw)
  s = raw.dup.force_encoding("UTF-8")
  n = s.bytesize
  # 1. Everything after the last separator.
  start = 0
  i = 0
  while i < n
    b = s.getbyte(i)
    start = i + 1 if b == 0x2F || b == 0x5C
    i += 1
  end
  # 2. Copy runs of kept bytes; skip the dropped ones.
  out = +""
  run = start
  i = start
  while i < n
    skip = UploadedFile.dropped_length(s, i, n)
    if skip == 0
      i += 1
    else
      out << s.byteslice(run, i - run) if i > run
      i += skip
      run = i
    end
  end
  out << s.byteslice(run, i - run) if i > run
  # 3. Strip leading and trailing dots and spaces. 4. Cut to the limit.
  out = UploadedFile.trim_dots(out)
  if out.bytesize > MAX_FILENAME_BYTES
    cut = MAX_FILENAME_BYTES
    cut -= 1 while cut > 0 && (out.getbyte(cut) & 0xC0) == 0x80
    out = UploadedFile.trim_dots(out.byteslice(0, cut))
  end
  out.force_encoding("UTF-8")
  return FALLBACK_FILENAME if out.bytesize == 0 || !out.valid_encoding?

  out
end

.sanitize_type(raw) ⇒ String

The media type of a part’s Content-Type header, or “” when it is not a plain type/subtype: parameters (after “;”) are cut, surrounding whitespace is trimmed, the rest is lowercased, and it must be 1 to 127 bytes of [a-z0-9!#$&^_.+-] around exactly one “/” with something on both sides. Informational only (see #declared_content_type).

Parameters:

  • raw (String)

Returns:

  • (String)


291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
# File 'cybertrain/http/uploaded_file.rb', line 291

def self.sanitize_type(raw)
  n = raw.bytesize
  i = 0
  while i < n && (raw.getbyte(i) == 0x20 || raw.getbyte(i) == 0x09)
    i += 1
  end
  first = i
  slashes = 0
  slash_at = -1
  last = first   # one past the last byte that is not trailing whitespace
  while i < n
    b = raw.getbyte(i)
    break if b == 0x3B
    if b == 0x20 || b == 0x09
      i += 1
      next
    end
    if b >= 0x41 && b <= 0x5A
      b += 32
    end
    if b == 0x2F
      slashes += 1
      slash_at = i
    elsif !UploadedFile.type_byte?(b)
      return ""
    end
    i += 1
    last = i
  end
  len = last - first
  return "" if len < 3 || len > 127 || slashes != 1
  return "" if slash_at == first || slash_at == last - 1
  # Whitespace inside the type ("image /png") is a malformed value.
  j = first
  while j < last
    bj = raw.getbyte(j)
    return "" if bj == 0x20 || bj == 0x09
    j += 1
  end
  raw.byteslice(first, len).downcase
end

.sniff(data) ⇒ String

The type of a file from its leading bytes. Only PNG, JPEG, GIF, WebP and PDF are recognised; SVG, HTML, XML and scripts are never reported as such (they come back as “application/octet-stream”), so a sniffed type cannot be turned into an executable one. Input shorter than a signature simply does not match.

Parameters:

  • data (String) —

    the bytes (any encoding; only getbyte is used)

Returns:

  • (String) —

    a media type



160
161
162
163
164
165
166
167
168
169
170
# File 'cybertrain/http/uploaded_file.rb', line 160

def self.sniff(data)
  n = data.bytesize
  # 89 50 4E 47 0D 0A 1A 0A, as integers: no binary literal to build.
  return "image/png" if n >= 8 && data.getbyte(0) == 0x89 && data.getbyte(1) == 0x50 && data.getbyte(2) == 0x4E && data.getbyte(3) == 0x47 && data.getbyte(4) == 0x0D && data.getbyte(5) == 0x0A && data.getbyte(6) == 0x1A && data.getbyte(7) == 0x0A
  return "image/jpeg" if n >= 3 && data.getbyte(0) == 0xFF && data.getbyte(1) == 0xD8 && data.getbyte(2) == 0xFF
  return "image/gif" if n >= 6 && (UploadedFile.bytes_at?(data, 0, "GIF87a") || UploadedFile.bytes_at?(data, 0, "GIF89a"))
  return "image/webp" if n >= 12 && UploadedFile.bytes_at?(data, 0, "RIFF") && UploadedFile.bytes_at?(data, 8, "WEBP")
  return "application/pdf" if n >= 5 && UploadedFile.bytes_at?(data, 0, "%PDF-")

  UNKNOWN_TYPE
end

Instance Method Details

#body_bytes ⇒ String

The file’s bytes, as an ASCII-8BIT String. Compare with a.b == b.b, bytesize or #sha256_hex, not == on the raw value (NOTES rule 27).

Returns:

  • (String)


89
90
91
# File 'cybertrain/http/uploaded_file.rb', line 89

def body_bytes
  @body_bytes
end

#byte_size ⇒ Integer

Returns the size in bytes.

Returns:



95
96
97
# File 'cybertrain/http/uploaded_file.rb', line 95

def byte_size
  @body_bytes.bytesize
end

#declared_content_type ⇒ String

The client’s part Content-Type (media type only, lowercased, “” when absent). Informational only: the client chooses it, so decisions use #detected_content_type.

Returns:

  • (String)


81
82
83
# File 'cybertrain/http/uploaded_file.rb', line 81

def declared_content_type
  @declared_content_type
end

#detected_content_type ⇒ String

The type decided from the file’s own bytes (see sniff), computed once. “application/octet-stream” when nothing matches.

Returns:

  • (String)


109
110
111
112
113
114
115
116
# File 'cybertrain/http/uploaded_file.rb', line 109

def detected_content_type
  d = @detected
  return d unless d.empty?

  d = UploadedFile.sniff(@body_bytes)
  @detected = d
  d
end

#empty? ⇒ Boolean

Returns true for a zero-byte file (and for blank).

Returns:

  • (Boolean) —

    true for a zero-byte file (and for blank)



101
102
103
# File 'cybertrain/http/uploaded_file.rb', line 101

def empty?
  @body_bytes.bytesize == 0
end

#image? ⇒ Boolean

Returns true when the detected type is one of INLINE_SAFE_TYPES: PNG, JPEG, GIF or WebP.

Returns:

  • (Boolean) —

    true when the detected type is one of INLINE_SAFE_TYPES: PNG, JPEG, GIF or WebP



121
122
123
# File 'cybertrain/http/uploaded_file.rb', line 121

def image?
  UploadedFile.inline_safe?(detected_content_type)
end

#inspect ⇒ String

Name and size only. Never the bytes: this is what ends up in logs and in Params#inspect.

Returns:

  • (String)


141
142
143
# File 'cybertrain/http/uploaded_file.rb', line 141

def inspect
  "#<Cybertrain::UploadedFile #{@original_filename.inspect} #{@body_bytes.bytesize} bytes>"
end

#original_filename ⇒ String

The client’s filename, sanitized. For display only: it is NEVER a path.

Returns:

  • (String)


72
73
74
# File 'cybertrain/http/uploaded_file.rb', line 72

def original_filename
  @original_filename
end

#sha256_hex ⇒ String

The lowercase hex SHA-256 of the bytes, computed once.

Returns:

  • (String) —

    64 hex characters



128
129
130
131
132
133
134
135
# File 'cybertrain/http/uploaded_file.rb', line 128

def sha256_hex
  h = @sha256
  return h unless h.empty?

  h = Digest::SHA256.hexdigest(@body_bytes)
  @sha256 = h
  h
end

#to_s ⇒ String

Same as #inspect.

Returns:

  • (String)


148
149
150
# File 'cybertrain/http/uploaded_file.rb', line 148

def to_s
  inspect
end