Update docs

This commit is contained in:
Alan Grainger
2026-10-07 18:04:57 +13:00
parent 7a9ff2e6ee
commit 172f247418
14 changed files with 243 additions and 37 deletions
+2 -2
View File
@@ -7,7 +7,7 @@
// to the request body.
import { createLimiter } from '../shared/limiter.js'
import { fileType, formatSize, isUploadableType } from '../shared/upload.js'
import { fileType, formatSize, isUploadableName, isUploadableType } from '../shared/upload.js'
import type { UploadErrorResponse, UploadPageConfig, UploadResponse } from '../shared/upload.js'
import {
ICON_ALERT_CIRCLE,
@@ -305,7 +305,7 @@ function queueFiles (files: File[]) {
const type = fileType(file.name, file.type)
const row = addRow(file, type)
stats.total++
if (!isUploadableType(type)) {
if (!isUploadableType(type) || !isUploadableName(file.name)) {
finish(row, 'error', 'Only photos and videos can be sent')
} else if (file.size > config.maxFileSize) {
finish(row, 'error', 'Larger than the ' + formatSize(config.maxFileSize) + ' limit')
+8 -1
View File
@@ -2,6 +2,13 @@ import { sanitize } from '@ipp/core'
const MAX_FILENAME_LENGTH = 254
/*
Zero-width and bidirectional format characters: invisible in Immich and in a
notification, or able to make `holiday\u202Egpj.mp4` read as `holiday4pm.jpg`.
`sanitize` strips C0/C1 controls only.
*/
const formatCharsRe = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g
/**
* Turn the visitor-supplied filename into the name Immich will store, with
* `prefix` applied once. Returns undefined when nothing usable is left, or
@@ -10,7 +17,7 @@ const MAX_FILENAME_LENGTH = 254
*/
export function uploadFilename (raw: unknown, prefix: string): string | undefined {
if (typeof raw !== 'string') return undefined
const base = raw.split(/[\\/]/).pop() || ''
const base = (raw.normalize('NFC').replace(formatCharsRe, '').split(/[\\/]/).pop() || '')
// Split the extension off first: `sanitize` truncates at 254 characters,
// which on a very long name would cut the extension away.
const parts = base.match(/^(.*)(\.[A-Za-z0-9]{1,16})$/)
+24 -13
View File
@@ -1,29 +1,40 @@
import { Transform } from 'stream'
/** The error an idle stream is destroyed with. */
/** The error a stalled stream is destroyed with. */
export class IdleTimeoutError extends Error {}
/**
* A pass-through Transform that destroys itself if no data flows through for
* `idleMs`. The timer is set when the transform is created and reset on every
* chunk, so a slow-but-steady download (large video over a slow link) keeps
* going, while a genuinely stalled connection still fails fast.
* A pass-through Transform that destroys itself when fewer than `minBytes`
* flow through it in any `idleMs` interval. The check is armed when the
* transform is created, so a body that never starts also times out.
*
* With `minBytes` left at 1 this is a plain idle timeout: a slow-but-steady
* stream keeps going, a stalled one fails. A higher `minBytes` is a floor on
* throughput, which stops a trickle of one byte a minute holding the
* resources an upload reserved for as long as the sender likes.
*/
export function createIdleTimeoutStream (idleMs: number): Transform {
let timer: NodeJS.Timeout | undefined
export function createIdleTimeoutStream (idleMs: number, minBytes = 1): Transform {
let received = 0
const check = () => {
if (received < minBytes) {
transform.destroy(new IdleTimeoutError(`Fewer than ${minBytes} bytes received in ${idleMs}ms`))
}
received = 0
}
const timer = setInterval(check, idleMs)
const transform: Transform = new Transform({
transform (chunk, _, cb) {
if (timer) clearTimeout(timer)
timer = setTimeout(() => transform.destroy(new IdleTimeoutError(`No data received for ${idleMs}ms`)), idleMs)
received += chunk.length
cb(null, chunk)
},
flush (cb) {
if (timer) clearTimeout(timer)
clearInterval(timer)
cb()
},
destroy (err, cb) {
clearInterval(timer)
cb(err)
}
})
// Arm the timer immediately so a response that returns headers but never
// sends a body also times out.
timer = setTimeout(() => transform.destroy(new IdleTimeoutError(`No data received for ${idleMs}ms`)), idleMs)
return transform
}
+3 -1
View File
@@ -56,9 +56,11 @@ for (const dir of ['public', CORE_PUBLIC_DIR]) {
router.use('/share/static', express.static(dir))
}
// Everything past the static assets is never cached
// Everything past the static assets is never cached, and no page may be framed
router.use((_req, res, next) => {
addNoStoreHeaders(res)
res.set('X-Frame-Options', 'DENY')
res.set('Content-Security-Policy', "frame-ancestors 'none'")
next()
})
router.use(sessionMiddleware({ name: 'upload-session' }))
+24 -12
View File
@@ -9,7 +9,7 @@ import { authoriseUpload } from './gate'
import { createIdleTimeoutStream, IdleTimeoutError } from './idleTimeoutStream'
import { createWindowBudget } from './limits'
import { buildNotification, sendNotification } from './notify'
import { formatSize, isUploadableType } from './shared/upload'
import { formatSize, isUploadableName, isUploadableType } from './shared/upload'
/*
The visitor-facing half of the upload path: validate one request, then
@@ -21,8 +21,14 @@ import { formatSize, isUploadableType } from './shared/upload'
written to disk.
*/
// A body that sends nothing for this long is dropped
/*
A body that delivers less than this in any one-minute interval is dropped.
The floor is far below any phone uplink (8 KB/s is 64 kbit/s), yet it means
a connection that trickles bytes to keep its byte-budget reservation alive
has to keep spending real bandwidth to do so.
*/
const BODY_IDLE_MS = 60_000
const BODY_MIN_BYTES_PER_INTERVAL = 8 * 1024 * BODY_IDLE_MS / 1000
/**
* Answer an upload the server will not take, in the shape the page reads.
@@ -71,18 +77,15 @@ export function createUploadReceiver () {
}
const shareId = link.id || key
const rated = rate(req.ip + ':' + shareId)
if (!rated.ok) {
res.set('Retry-After', String(rated.retryAfterSeconds))
refuse(res, 429, 'Too many uploads. Wait a moment and try again.')
return
}
const length = declaredLength(req.headers['content-length'])
if (length === undefined) {
refuse(res, 411, 'The upload has no Content-Length')
return
}
if (length === 0) {
refuse(res, 400, 'The file is empty')
return
}
if (length > maxBytes) {
refuse(res, 413, 'Larger than the ' + formatSize(maxBytes) + ' limit')
return
@@ -95,11 +98,20 @@ export function createUploadReceiver () {
}
const mimeType = (req.headers['content-type'] || '').split(';')[0].trim().toLowerCase()
if (!isUploadableType(mimeType)) {
if (!isUploadableType(mimeType) || !isUploadableName(filename)) {
refuse(res, 415, 'Only photos and videos can be sent')
return
}
// Charged only once the request is one the service would take, so a
// stream of malformed requests cannot use up everyone's allowance
const rated = rate(req.ip + ':' + shareId)
if (!rated.ok) {
res.set('Retry-After', String(rated.retryAfterSeconds))
refuse(res, 429, 'Too many uploads. Wait a moment and try again.')
return
}
// Reserved before streaming, so parallel uploads cannot overshoot the budget together
const reserved = budget(shareId, length)
if (!reserved.ok) {
@@ -108,8 +120,8 @@ export function createUploadReceiver () {
return
}
const body = pipeline(req, createIdleTimeoutStream(BODY_IDLE_MS), err => {
if (err instanceof IdleTimeoutError) log('Dropped upload ' + filename + ': nothing received for ' + BODY_IDLE_MS / 1000 + ' s')
const body = pipeline(req, createIdleTimeoutStream(BODY_IDLE_MS, BODY_MIN_BYTES_PER_INTERVAL), err => {
if (err instanceof IdleTimeoutError) log('Dropped upload ' + filename + ': too little received in ' + BODY_IDLE_MS / 1000 + ' s')
})
const result = await forwardUpload(permit, {
filename,
+13
View File
@@ -18,6 +18,19 @@ export function isUploadableType (mimeType: string): boolean {
return type.startsWith('image/') || type.startsWith('video/')
}
// Extensions Immich stores as SVG, whatever media type the request declares
const REFUSED_EXTENSIONS = new Set(['svg', 'svgz'])
/**
* Whether a file with this name may be sent. The media type is the sender's
* claim and Immich types the stored asset by its extension, so the SVG rule
* has to hold on the name as well or `evil.svg` sent as `image/jpeg` gets in.
*/
export function isUploadableName (filename: string): boolean {
const extension = filename.split('.').pop()?.toLowerCase() || ''
return !REFUSED_EXTENSIONS.has(extension)
}
/*
Types for files a desktop browser reports with an empty or generic `File.type`: HEIC,
HEIF, camera RAW and some video containers. Immich types the asset by its