Add configurable field separator

This commit is contained in:
Alan Grainger
2026-10-19 17:33:47 +13:00
parent a620d0b3ae
commit ac34a03482
8 changed files with 118 additions and 32 deletions
+1
View File
@@ -9,6 +9,7 @@
"filenamePrefix": "ipp_upload_",
"notice": "Uploaded photos may not appear in the gallery immediately.",
"askName": true,
"fieldSeparator": ",",
"notifyUrl": "",
"notifyHeaders": {},
"notifyTimeout": 10000
+11
View File
@@ -1,4 +1,5 @@
import { getConfigOption, getNumericConfigOption } from '@ipp/core'
import { DEFAULT_FIELD_SEPARATOR, isUsableSeparator } from './filename'
const MB = 1024 * 1024
@@ -37,6 +38,16 @@ export function askName (): boolean {
return getConfigOption('ipp.upload.askName', true) !== false
}
/**
* The string that ends each visitor field in a stored filename, from
* `ipp.upload.fieldSeparator`. The default when the configured value could be
* part of a field or a filename, see `isUsableSeparator`.
*/
export function fieldSeparator (): string {
const configured = getConfigOption('ipp.upload.fieldSeparator', DEFAULT_FIELD_SEPARATOR)
return isUsableSeparator(configured) ? configured : DEFAULT_FIELD_SEPARATOR
}
/** Text shown under the placeholder on the upload page, from `ipp.upload.notice`. Empty hides it. */
export function uploadNotice (): string {
const configured = getConfigOption('ipp.upload.notice', 'Uploaded photos may not appear in the gallery immediately.')
+24 -10
View File
@@ -13,19 +13,33 @@ const MAX_UPLOADER_LENGTH = 32
/*
A stored name is `<prefix><header><original>`. The header is the visitor
fields, each a slug, each followed by a comma: `ipp_upload_jane-smith,IMG_0042.jpg`.
fields, each a slug, each followed by the separator: `ipp_upload_jane-smith,IMG_0042.jpg`.
Fields are positional, so a field added later goes on the end and an empty
one is written empty: `ipp_upload_,34,IMG_0042.jpg`. When every field is
empty there is no header at all, and the name is as it was before fields
existed. The visitor's own filename never keeps a comma, so a stem with no
comma has no fields and otherwise the last comma ends the header.
existed. The visitor's own filename never keeps the separator, so a stem
with no separator has no fields and otherwise the last one ends the header.
*/
const FIELD_SEPARATOR = ','
/** The default separator between the visitor fields and the original filename, from `ipp.upload.fieldSeparator`. */
export const DEFAULT_FIELD_SEPARATOR = ','
/**
* Whether `separator` can mark the end of a field: a string that `sanitize`
* leaves alone, with no slug character, dot or whitespace in it. A letter,
* digit or hyphen could be part of the name, a dot could be read as the
* extension, and whitespace would be trimmed from the ends of a stem.
*/
export function isUsableSeparator (separator: unknown): separator is string {
if (typeof separator !== 'string' || separator === '') return false
if (sanitize(separator) !== separator) return false
return !/[\p{L}\p{N}\-.\s]/u.test(separator)
}
/**
* The visitor's name as a filename slug: lower case, letters and digits in any
* script, runs of anything else become one hyphen. Empty when nothing usable
* is left. A slug never contains the field separator.
* is left. A slug never contains a separator.
*/
export function uploaderSlug (raw: unknown): string {
if (typeof raw !== 'string') return ''
@@ -39,9 +53,9 @@ export function uploaderSlug (raw: unknown): string {
}
/** The header for these fields, in order, or empty when none has a value. */
function fieldHeader (fields: string[]): string {
function fieldHeader (fields: string[], separator: string): string {
if (!fields.some(Boolean)) return ''
return fields.map(field => field + FIELD_SEPARATOR).join('')
return fields.map(field => field + separator).join('')
}
/**
@@ -51,7 +65,7 @@ function fieldHeader (fields: string[]): string {
* is left, or when there is no extension: Immich types an asset by its
* extension and would refuse it.
*/
export function uploadFilename (raw: unknown, prefix: string, uploader = ''): string | undefined {
export function uploadFilename (raw: unknown, prefix: string, uploader = '', separator = DEFAULT_FIELD_SEPARATOR): string | undefined {
if (typeof raw !== 'string') return undefined
const base = (raw.normalize('NFC').replace(formatCharsRe, '').split(/[\\/]/).pop() || '')
// Split the extension off first: `sanitize` truncates at 254 characters,
@@ -60,14 +74,14 @@ export function uploadFilename (raw: unknown, prefix: string, uploader = ''): st
if (!parts) return undefined
const extension = parts[2]
// The separator is removed from the visitor's name so it only ever marks a field
const stem = sanitize(parts[1]).split(FIELD_SEPARATOR).join('').trim()
const stem = sanitize(parts[1]).split(separator).join('').trim()
// An empty stem is a dotfile; a leading dot is a traversal remnant.
if (!stem || stem.startsWith('.')) return undefined
const cleanPrefix = sanitize(prefix).trim()
// Don't stack the prefix, or the name, on a file that already carries the prefix
const hasPrefix = cleanPrefix !== '' && stem.startsWith(cleanPrefix)
const wanted = hasPrefix ? '' : cleanPrefix + fieldHeader([uploader])
const wanted = hasPrefix ? '' : cleanPrefix + fieldHeader([uploader], separator)
const room = MAX_FILENAME_LENGTH - wanted.length - extension.length
return wanted + stem.slice(0, Math.max(1, room)) + extension
}
+3 -2
View File
@@ -2,7 +2,7 @@ import { pipeline } from 'stream'
import { Request, Response } from 'express-serve-static-core'
import dayjs from 'dayjs'
import { abortOnClose, KeyType, log, respondToInvalidRequest, SharedLink } from '@ipp/core'
import { askName, byteBudget, filenamePrefix, maxFileSize, rateLimit } from './config'
import { askName, byteBudget, fieldSeparator, filenamePrefix, maxFileSize, rateLimit } from './config'
import { uploaderSlug, uploadFilename } from './filename'
import { forwardUpload } from './forward'
import { authoriseUpload } from './gate'
@@ -67,6 +67,7 @@ export function createUploadReceiver () {
const maxBytes = maxFileSize()
const prefix = filenamePrefix()
const withName = askName()
const separator = fieldSeparator()
return async function receiveUpload (req: Request, res: Response, link: SharedLink, keyType: KeyType): Promise<void> {
const key = req.params.key
@@ -93,7 +94,7 @@ export function createUploadReceiver () {
// The name is the visitor's claim, kept only as part of the filename
const uploader = withName ? uploaderSlug(req.query.uploader) : ''
const filename = uploadFilename(req.query.filename, prefix, uploader)
const filename = uploadFilename(req.query.filename, prefix, uploader, separator)
if (!filename) {
refuse(res, 400, 'Missing or unusable filename')
return
+11 -1
View File
@@ -1,5 +1,5 @@
import { describe, it, expect, afterEach } from 'vitest'
import { askName, byteBudget, filenamePrefix, maxFileSize, notifyConfig, uploadNotice } from '../src/config'
import { askName, byteBudget, fieldSeparator, filenamePrefix, maxFileSize, notifyConfig, uploadNotice } from '../src/config'
import { resetConfig, setConfig } from './helpers'
afterEach(resetConfig)
@@ -14,6 +14,16 @@ describe('upload options', () => {
expect(notifyConfig()).toBeUndefined()
expect(uploadNotice()).toBe('Uploaded photos may not appear in the gallery immediately.')
expect(askName()).toBe(true)
expect(fieldSeparator()).toBe(',')
})
it('takes a usable field separator, and falls back for one that could be part of a field', () => {
setConfig({ ipp: { upload: { fieldSeparator: '^' } } })
expect(fieldSeparator()).toBe('^')
for (const bad of ['', '-', 'a', '.', ' ', '/', 7, null]) {
setConfig({ ipp: { upload: { fieldSeparator: bad } } })
expect(fieldSeparator()).toBe(',')
}
})
it('turns the name field off only on an explicit false', () => {
+26 -3
View File
@@ -1,5 +1,5 @@
import { describe, it, expect } from 'vitest'
import { uploaderSlug, uploadFilename } from '../src/filename'
import { isUsableSeparator, uploaderSlug, uploadFilename } from '../src/filename'
describe('uploadFilename', () => {
it('keeps an ordinary filename', () => {
@@ -56,9 +56,17 @@ describe('uploadFilename', () => {
expect(uploadFilename('IMG_0042.jpg', 'ipp_upload_', '')).toBe('ipp_upload_IMG_0042.jpg')
})
it('removes commas from the visitor filename, so a comma only ever ends a field', () => {
it('removes the separator from the visitor filename, so it only ever ends a field', () => {
expect(uploadFilename('Paris, France.jpg', 'ipp_upload_')).toBe('ipp_upload_Paris France.jpg')
expect(uploadFilename('a,b,c.jpg', 'ipp_upload_', 'jane-smith')).toBe('ipp_upload_jane-smith,abc.jpg')
// Any other punctuation is an ordinary character and stays
expect(uploadFilename('best^photo.jpg', 'ipp_upload_', 'jane-smith')).toBe('ipp_upload_jane-smith,best^photo.jpg')
})
it('uses the configured separator, and removes that one instead', () => {
expect(uploadFilename('IMG_0042.jpg', 'ipp_upload_', 'jane-smith', '^')).toBe('ipp_upload_jane-smith^IMG_0042.jpg')
expect(uploadFilename('Paris, France^2.jpg', 'ipp_upload_', 'jane-smith', '^')).toBe('ipp_upload_jane-smith^Paris, France2.jpg')
expect(uploadFilename('IMG_0042.jpg', 'ipp_upload_', 'jane-smith', '~~')).toBe('ipp_upload_jane-smith~~IMG_0042.jpg')
})
it('stays within 254 characters with the extension intact', () => {
@@ -80,8 +88,9 @@ describe('uploaderSlug', () => {
expect(uploaderSlug('山田 太郎')).toBe('山田-太郎')
})
it('never keeps a comma or an underscore', () => {
it('never keeps a separator, punctuation or an underscore', () => {
expect(uploaderSlug('Smith, Jane')).toBe('smith-jane')
expect(uploaderSlug('jane^smith')).toBe('jane-smith')
expect(uploaderSlug('jane_smith')).toBe('jane-smith')
})
@@ -101,3 +110,17 @@ describe('uploaderSlug', () => {
expect(uploaderSlug('a'.repeat(31) + ' b')).toBe('a'.repeat(31))
})
})
describe('isUsableSeparator', () => {
it('accepts punctuation that sanitize keeps', () => {
for (const separator of ['^', ',', '~', '#', '+', '^^', '~,']) expect(isUsableSeparator(separator)).toBe(true)
})
it('rejects anything that could be part of a name or a filename, or is not a string', () => {
for (const separator of ['', 'a', '1', '-', '.', ' ', 'x^', '^ ', '/', ':', '*', '"', '\u0000', 'ñ', '٣']) {
expect(isUsableSeparator(separator)).toBe(false)
}
expect(isUsableSeparator(undefined)).toBe(false)
expect(isUsableSeparator(1)).toBe(false)
})
})