Class: Cybertrain::UploadedFile
- Inherits:
-
Object
- Object
- Cybertrain::UploadedFile
- 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).
Class Method Summary collapse
-
.blank ⇒ UploadedFile
The sentinel for “no file”: empty name, type and body.
-
.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):.
-
.content_disposition_utf8(disposition, filename) ⇒ String
A Content-Disposition header value for a download, the way Rails’
send_datawrites it (RFC 6266), ASCII only:. -
.inline_safe?(type) ⇒ Boolean
Exact match against INLINE_SAFE_TYPES (no parameters, no case folding).
-
.sanitize_filename(raw) ⇒ String
A display filename from whatever the client sent.
-
.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. -
.sniff(data) ⇒ String
The type of a file from its leading bytes.
Instance Method Summary collapse
-
#body_bytes ⇒ String
The file’s bytes, as an ASCII-8BIT String.
-
#byte_size ⇒ Integer
The size in bytes.
-
#declared_content_type ⇒ String
The client’s part Content-Type (media type only, lowercased, “” when absent).
-
#detected_content_type ⇒ String
The type decided from the file’s own bytes (see UploadedFile.sniff), computed once.
-
#empty? ⇒ Boolean
True for a zero-byte file (and for UploadedFile.blank).
-
#image? ⇒ Boolean
True when the detected type is one of INLINE_SAFE_TYPES: PNG, JPEG, GIF or WebP.
-
#inspect ⇒ String
Name and size only.
-
#original_filename ⇒ String
The client’s filename, sanitized.
-
#sha256_hex ⇒ String
The lowercase hex SHA-256 of the bytes, computed once.
-
#to_s ⇒ String
Same as #inspect.
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).
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.
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.
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).
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”.
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).
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.
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).
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.
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.
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.
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).
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.
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.
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.
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.
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.
148 149 150 |
# File 'cybertrain/http/uploaded_file.rb', line 148 def to_s inspect end |