Initial work on upload app server

This commit is contained in:
Alan Grainger
2026-10-06 10:07:20 +13:00
parent 9e6c00da35
commit 95ac498cf0
38 changed files with 1493 additions and 40 deletions
+1
View File
@@ -7,3 +7,4 @@ app/public/js/
/app/config.dev.json /app/config.dev.json
.npm-cache/ .npm-cache/
*.tsbuildinfo *.tsbuildinfo
upload-app/public/js/
+22 -5
View File
@@ -26,26 +26,27 @@ Request flow for a typical share URL like `https://proxy.example.com/share/<key>
### Repository layout ### Repository layout
The repo is an npm workspace with two packages: `shared/` is `@ipp/core`, the read-side code that IPP shares with the planned upload service, and `app/` is IPP itself. Run `npm install` at the root; there is one lockfile. The repo is an npm workspace with three packages: `shared/` is `@ipp/core`, the read-side code both apps share; `app/` is IPP itself; and `upload-app/` is the optional upload service, the only code that writes to Immich. Run `npm install` at the root; there is one lockfile.
``` ```
.github/workflows/ CI: builds and pushes Docker image on v* tags .github/workflows/ CI: builds and pushes Docker image on v* tags
package.json Workspace root: scripts that delegate to the workspaces; no dependencies package.json Workspace root: scripts that delegate to the workspaces; no dependencies
package-lock.json The one lockfile for every workspace package-lock.json The one lockfile for every workspace
.eslintrc Lint config for both workspaces .eslintrc Lint config for every workspace
shared/ @ipp/core - read-side only, knows nothing about galleries shared/ @ipp/core - read-side only, knows nothing about galleries
src/ src/
index.ts Barrel: everything the apps import comes from '@ipp/core' index.ts Barrel: everything the apps import comes from '@ipp/core'
types.ts Share-level types (SharedLink, Asset, KeyType, ...) types.ts Share-level types (SharedLink, Asset, KeyType, ...)
immich/client.ts Immich API request helper, URL building, key/id checks, version guard immich/client.ts Immich API request helper, URL building, key/id checks, version guard
immich/share.ts fetchSharedLink, password login + token cache, auth headers, title immich/share.ts fetchSharedLink, password login + token cache, auth headers, title, slug-link gate
config/loader.ts loadConfig() reads env / file; the app passes its default path config/loader.ts loadConfig() reads env / file; the app passes its default path
config/access.ts getConfigOption() reads the loaded config config/access.ts getConfigOption() reads the loaded config
http.ts Operator-configured and no-store response headers, abortOnClose, asyncHandler, CORE_PUBLIC_DIR http.ts Operator-configured and no-store response headers, abortOnClose, asyncHandler, CORE_PUBLIC_DIR
invalidRequest.ts The 404 policy (never cached), errorHandler, and setInvalidRequestHandler for the app's own handler file invalidRequest.ts The 404 policy (never cached), errorHandler, and setInvalidRequestHandler for the app's own handler file
session.ts Cookie session, decodeCookie, unlock handler, invalid-password response session.ts Cookie session, decodeCookie, unlock handler, invalid-password response
encrypt.ts Cookie-session encryption for password-protected shares encrypt.ts Cookie-session encryption for password-protected shares
utils/ log, sanitize (filenames), text (escaping), ttlLruCache, webStream version.ts App version from APP_VERSION or the app's package.json
utils/ log, sanitize (filenames), text (escaping), ttlLruCache, webStream (incl. streaming request bodies)
view/ Page renderer, theme script, password page view/ Page renderer, theme script, password page
public/ Static assets both apps serve: pico, Inter font, favicon, theme.css (tokens and page base) public/ Static assets both apps serve: pico, Inter font, favicon, theme.css (tokens and page base)
tests/ Vitest unit tests for core tests/ Vitest unit tests for core
@@ -77,6 +78,22 @@ app/
thumbhash/, images/ thumbhash/, images/
style.css, photoswipe-overrides.css style.css, photoswipe-overrides.css
tests/ Vitest unit tests for IPP tests/ Vitest unit tests for IPP
upload-app/ immich-public-proxy-upload - one page per share; streams visitor files to Immich's POST /assets
config.json Default ipp.upload.* options; no responseHeaders
src/
index.ts Express setup and routes, mounted under PUBLIC_BASE_URL's path
config.ts Env and ipp.upload.* readers, base path
share.ts Share lookup through core, cached 60 s
gate.ts The upload permit: the share's Immich toggle and the slug-link gate
receive.ts Validates one upload request: rate limit, length, filename, type, byte budget
forward.ts The only Immich write call: multipart POST /assets under the share key
limits.ts Fixed-window budgets for the rate limit and the byte budget
filename.ts Stored filename: sanitised, prefixed, extension kept
notify.ts Optional JSON webhook per stored file
idleTimeoutStream.ts Drops a request body that stalls
view/upload.tsx The upload page
shared/ Rules and types shared by the server and the page client
tests/ Vitest unit tests for the upload app
docs/ User docs site (VitePress); docs/README.md explains its structure docs/ User docs site (VitePress); docs/README.md explains its structure
Dockerfile Multi-stage build; IPP runs from /app as the non-root `node` user Dockerfile Multi-stage build; IPP runs from /app as the non-root `node` user
docker-compose.yml Reference deployment docker-compose.yml Reference deployment
@@ -128,7 +145,7 @@ At the repo root:
```bash ```bash
npm run build # core, then IPP's server and client; output to dist/ and app/public/js/ npm run build # core, then IPP's server and client; output to dist/ and app/public/js/
npm test # vitest run in every workspace (unit tests on pure functions) npm test # vitest run in every workspace (unit tests on pure functions)
npm run lint # ESLint over both workspaces npm run lint # ESLint over every workspace
npm run bump -- 4.0.1 # set the version in every workspace manifest and the lockfile npm run bump -- 4.0.1 # set the version in every workspace manifest and the lockfile
``` ```
+3 -13
View File
@@ -4,7 +4,6 @@ import 'dotenv/config'
import express from 'express' import express from 'express'
import { resolve } from 'path' import { resolve } from 'path'
import { import {
accessible,
addNoStoreHeaders, addNoStoreHeaders,
addResponseHeaders, addResponseHeaders,
Asset, Asset,
@@ -16,6 +15,7 @@ import {
errorHandler, errorHandler,
getConfigOption, getConfigOption,
getKeyTypeFromShare, getKeyTypeFromShare,
healthcheck,
isId, isId,
isKey, isKey,
KeyType, KeyType,
@@ -25,6 +25,7 @@ import {
sessionMiddleware, sessionMiddleware,
setInvalidRequestHandler, setInvalidRequestHandler,
SharedLink, SharedLink,
slugLinksDisabled,
unlockHandler unlockHandler
} from '@ipp/core' } from '@ipp/core'
import { fetchAssetDetail, getShareByKey, handleShareRequest } from './immich' import { fetchAssetDetail, getShareByKey, handleShareRequest } from './immich'
@@ -97,11 +98,6 @@ type SharedAssetResolution =
| { ok: true, link: SharedLink, asset: Asset } | { ok: true, link: SharedLink, asset: Asset }
| { ok: false, status: number, reason: string, passwordRequired?: boolean } | { ok: false, status: number, reason: string, passwordRequired?: boolean }
/** Whether this is a slug link and the operator has turned slug links off. */
function slugLinksDisabled (keyType: KeyType): boolean {
return keyType === KeyType.slug && !getConfigOption('ipp.allowSlugLinks', true)
}
async function resolveShare (req: Request, keyType: KeyType): Promise<ShareResolution> { async function resolveShare (req: Request, keyType: KeyType): Promise<ShareResolution> {
if (slugLinksDisabled(keyType)) { if (slugLinksDisabled(keyType)) {
return { ok: false, status: 404, reason: 'Slug links are disabled in config.json' } return { ok: false, status: 404, reason: 'Slug links are disabled in config.json' }
@@ -152,13 +148,7 @@ async function resolveSharedAsset (req: Request, keyType: KeyType, allowMotion =
* [ROUTE] Healthcheck * [ROUTE] Healthcheck
* The path matches for /share/healthcheck, and also the legacy /healthcheck * The path matches for /share/healthcheck, and also the legacy /healthcheck
*/ */
app.get(/^(|\/share)\/healthcheck$/, asyncHandler(async (_req, res) => { app.get(/^(|\/share)\/healthcheck$/, asyncHandler(healthcheck))
if (await accessible()) {
res.send('ok')
} else {
res.status(503).send()
}
}))
/* /*
* [ROUTE] This is the main URL that someone would visit if they are opening a shared link * [ROUTE] This is the main URL that someone would visit if they are opening a shared link
+2 -17
View File
@@ -1,22 +1,7 @@
import { readFileSync } from 'fs'
import { join } from 'path' import { join } from 'path'
import { resolveAppVersion } from '@ipp/core'
/** export const APP_VERSION = resolveAppVersion(join(__dirname, '..', 'package.json'))
* Resolve the running application version. Prefers the APP_VERSION env var
* baked in at Docker build time (see Dockerfile); falls back to package.json
* for local dev (`npm run dev`), and finally to 'dev' if neither is readable.
*/
function resolveVersion (): string {
if (process.env.APP_VERSION) return process.env.APP_VERSION
try {
const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'))
return pkg.version || 'dev'
} catch {
return 'dev'
}
}
export const APP_VERSION = resolveVersion()
/** URL-safe cache-busting segment for static asset paths. */ /** URL-safe cache-busting segment for static asset paths. */
export const ASSET_VERSION = encodeURIComponent(APP_VERSION) export const ASSET_VERSION = encodeURIComponent(APP_VERSION)
+32 -1
View File
@@ -8,7 +8,8 @@
"name": "immich-public-proxy-workspace", "name": "immich-public-proxy-workspace",
"workspaces": [ "workspaces": [
"shared", "shared",
"app" "app",
"upload-app"
] ]
}, },
"app": { "app": {
@@ -4115,6 +4116,10 @@
"resolved": "app", "resolved": "app",
"link": true "link": true
}, },
"node_modules/immich-public-proxy-upload": {
"resolved": "upload-app",
"link": true
},
"node_modules/import-fresh": { "node_modules/import-fresh": {
"version": "3.3.0", "version": "3.3.0",
"resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz", "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz",
@@ -7582,6 +7587,32 @@
"typescript": "^5.6.2", "typescript": "^5.6.2",
"vitest": "^4" "vitest": "^4"
} }
},
"upload-app": {
"name": "immich-public-proxy-upload",
"version": "3.4.1",
"license": "AGPL-3.0",
"dependencies": {
"@ipp/core": "*",
"dayjs": "^1.11.13",
"dotenv": "^16.4.5",
"express": "^4.21.1",
"preact": "^10.29.2",
"tslib": "^2.8.1"
},
"devDependencies": {
"@types/cookie-session": "^2.0.49",
"@types/express": "^4.17.21",
"@types/node": "^22",
"@typescript-eslint/eslint-plugin": "^7",
"@typescript-eslint/parser": "^7",
"concurrently": "^10.0.3",
"eslint": "^8.57.0",
"eslint-config-standard": "^17.1.0",
"tsx": "^4",
"typescript": "^5.6.2",
"vitest": "^4"
}
} }
} }
} }
+3 -2
View File
@@ -3,12 +3,13 @@
"private": true, "private": true,
"workspaces": [ "workspaces": [
"shared", "shared",
"app" "app",
"upload-app"
], ],
"scripts": { "scripts": {
"build": "npm run build --workspaces", "build": "npm run build --workspaces",
"test": "npm test --workspaces", "test": "npm test --workspaces",
"lint": "eslint shared app --ext .ts,.tsx", "lint": "eslint shared app upload-app --ext .ts,.tsx",
"dev": "npm run dev --workspace=app", "dev": "npm run dev --workspace=app",
"bump": "npm version --no-git-tag-version --workspaces" "bump": "npm version --no-git-tag-version --workspaces"
} }
+10
View File
@@ -1,6 +1,7 @@
import { NextFunction, Request, Response } from 'express-serve-static-core' import { NextFunction, Request, Response } from 'express-serve-static-core'
import { resolve } from 'path' import { resolve } from 'path'
import { getConfigOption } from './config/access' import { getConfigOption } from './config/access'
import { accessible } from './immich/client'
/** Static assets both apps serve from core: pico, the Inter font, the favicon and theme.css. */ /** Static assets both apps serve from core: pico, the Inter font, the favicon and theme.css. */
export const CORE_PUBLIC_DIR = resolve(__dirname, '../public') export const CORE_PUBLIC_DIR = resolve(__dirname, '../public')
@@ -36,6 +37,15 @@ export function abortOnClose (res: Response): AbortSignal {
return controller.signal return controller.signal
} }
/** `GET /healthcheck`: `ok` while Immich answers, else 503. */
export async function healthcheck (_req: Request, res: Response): Promise<void> {
if (await accessible()) {
res.send('ok')
} else {
res.status(503).send()
}
}
/** /**
* Wrap an async route handler so a rejected promise is passed to Express's * Wrap an async route handler so a rejected promise is passed to Express's
* error chain (and on to `errorHandler`). * error chain (and on to `errorHandler`).
+6
View File
@@ -1,5 +1,6 @@
import dayjs from 'dayjs' import dayjs from 'dayjs'
import { KeyType, SharedLink, SharedLinkResult } from '../types' import { KeyType, SharedLink, SharedLinkResult } from '../types'
import { getConfigOption } from '../config/access'
import { log } from '../utils/log' import { log } from '../utils/log'
import { cachedPromise, TtlLruCache } from '../utils/ttlLruCache' import { cachedPromise, TtlLruCache } from '../utils/ttlLruCache'
import { apiUrl, buildUrl } from './client' import { apiUrl, buildUrl } from './client'
@@ -16,6 +17,11 @@ import { apiUrl, buildUrl } from './client'
*/ */
const tokenCache = new TtlLruCache<Promise<string | null>>({ ttlMs: 120_000, max: 100 }) const tokenCache = new TtlLruCache<Promise<string | null>>({ ttlMs: 120_000, max: 100 })
/** Whether this is a slug link and the operator has turned slug links off. */
export function slugLinksDisabled (keyType: KeyType): boolean {
return keyType === KeyType.slug && !getConfigOption('ipp.allowSlugLinks', true)
}
/** /**
* Display title for a shared link. Prefers the user-set link description, * Display title for a shared link. Prefers the user-set link description,
* falls back to the album name (for album shares), or a generic placeholder. * falls back to the album name (for album shares), or a generic placeholder.
+1
View File
@@ -10,6 +10,7 @@ export * from './config/access'
export * from './http' export * from './http'
export * from './invalidRequest' export * from './invalidRequest'
export * from './session' export * from './session'
export * from './version'
export * from './encrypt' export * from './encrypt'
export * from './utils/log' export * from './utils/log'
export * from './utils/webStream' export * from './utils/webStream'
+16
View File
@@ -12,3 +12,19 @@ export function readableFromWeb (body: ReadableStream<Uint8Array>): Readable {
// eslint-disable-next-line @typescript-eslint/no-explicit-any // eslint-disable-next-line @typescript-eslint/no-explicit-any
return Readable.fromWeb(body as any) return Readable.fromWeb(body as any)
} }
/**
* Build a `fetch` init that streams `body` as the request body.
*
* Node's fetch refuses a stream body unless `duplex: 'half'` is set, but that
* option is absent from the DOM `RequestInit` the project's `lib` resolves
* to, so it has to go on behind a cast.
*/
export function streamingRequestInit (init: RequestInit, body: Readable): RequestInit {
return {
...init,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
body: Readable.toWeb(body) as any,
duplex: 'half'
} as RequestInit
}
+15
View File
@@ -0,0 +1,15 @@
import { readFileSync } from 'fs'
/**
* Resolve the running application version. Prefers the APP_VERSION env var
* baked in at Docker build time (see the Dockerfiles); falls back to the
* app's package.json for local dev, and finally to 'dev' if neither is readable.
*/
export function resolveAppVersion (packageJsonPath: string): string {
if (process.env.APP_VERSION) return process.env.APP_VERSION
try {
return JSON.parse(readFileSync(packageJsonPath, 'utf-8')).version || 'dev'
} catch {
return 'dev'
}
}
+15
View File
@@ -0,0 +1,15 @@
{
"ipp": {
"allowSlugLinks": true,
"customInvalidResponse": false,
"upload": {
"maxFileSize": 500,
"rateLimit": 60,
"byteBudget": 10240,
"filenamePrefix": "ipp_upload_",
"notifyUrl": "",
"notifyHeaders": {},
"notifyTimeout": 10000
}
}
}
+42
View File
@@ -0,0 +1,42 @@
{
"name": "immich-public-proxy-upload",
"version": "3.4.1",
"private": true,
"scripts": {
"predev": "tsc -b ../shared",
"dev": "concurrently -n core,server,client -c magenta,blue,green \"tsc -b -w --preserveWatchOutput ../shared\" \"tsx watch src/index.ts\" \"tsc -w -p tsconfig.client.json\"",
"build": "tsc -b && tsc -p tsconfig.client.json",
"test": "vitest run",
"test:watch": "vitest",
"start": "node dist/index.js"
},
"author": "Alan Grainger",
"license": "AGPL-3.0",
"description": "Lets visitors of an Immich Public Proxy share send photos and videos back to it.",
"repository": {
"type": "git",
"url": "https://github.com/alangrainger/immich-public-proxy.git"
},
"main": "dist/index.js",
"dependencies": {
"@ipp/core": "*",
"dayjs": "^1.11.13",
"dotenv": "^16.4.5",
"express": "^4.21.1",
"preact": "^10.29.2",
"tslib": "^2.8.1"
},
"devDependencies": {
"@types/cookie-session": "^2.0.49",
"@types/express": "^4.17.21",
"@types/node": "^22",
"@typescript-eslint/eslint-plugin": "^7",
"@typescript-eslint/parser": "^7",
"concurrently": "^10.0.3",
"eslint": "^8.57.0",
"eslint-config-standard": "^17.1.0",
"tsx": "^4",
"typescript": "^5.6.2",
"vitest": "^4"
}
}
+56
View File
@@ -0,0 +1,56 @@
import { getConfigOption, getNumericConfigOption } from '@ipp/core'
const MB = 1024 * 1024
/**
* Path the share routes are mounted under, from `PUBLIC_BASE_URL`: `''` for
* an own-hostname deployment, `/upload` for `https://photos.example.com/upload`.
*/
export function basePathFrom (publicBaseUrl: string | undefined): string {
if (!publicBaseUrl) return ''
try {
return new URL(publicBaseUrl).pathname.replace(/\/+$/, '')
} catch {
return ''
}
}
/** IPP's public URL from `GALLERY_URL`, without a trailing slash, or undefined when unset. */
export function galleryUrl (): string | undefined {
return (process.env.GALLERY_URL || '').replace(/\/+$/, '') || undefined
}
/** Largest single file accepted, in bytes, from `ipp.upload.maxFileSize` (MB). */
export function maxFileSize (): number {
return Math.max(1, getNumericConfigOption('ipp.upload.maxFileSize', 500)) * MB
}
/** Files per minute per visitor address and share, from `ipp.upload.rateLimit`. `0` is no limit. */
export function rateLimit (): number {
return getNumericConfigOption('ipp.upload.rateLimit', 60)
}
/** Bytes accepted per share per hour, from `ipp.upload.byteBudget` (MB). `0` is no limit. */
export function byteBudget (): number {
return Math.max(0, getNumericConfigOption('ipp.upload.byteBudget', 10240)) * MB
}
/** Prefix for every stored filename, from `ipp.upload.filenamePrefix`. */
export function filenamePrefix (): string {
const configured = getConfigOption('ipp.upload.filenamePrefix', 'ipp_upload_')
return typeof configured === 'string' ? configured : ''
}
/** Notification webhook settings from `ipp.upload.notify*`, or undefined when no URL is set. */
export function notifyConfig (): { url: string, headers: Record<string, string>, timeoutMs: number } | undefined {
const url = getConfigOption('ipp.upload.notifyUrl', '')
if (typeof url !== 'string' || !url) return undefined
const headers: Record<string, string> = {}
const configured = getConfigOption('ipp.upload.notifyHeaders', {})
if (configured && typeof configured === 'object' && !Array.isArray(configured)) {
for (const [name, value] of Object.entries(configured as Record<string, unknown>)) {
if (typeof value === 'string') headers[name] = value
}
}
return { url, headers, timeoutMs: getNumericConfigOption('ipp.upload.notifyTimeout', 10_000) }
}
+28
View File
@@ -0,0 +1,28 @@
import { sanitize } from '@ipp/core'
const MAX_FILENAME_LENGTH = 254
/**
* Turn the visitor-supplied filename into the name Immich will store, with
* `prefix` applied once. Returns undefined when nothing usable 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): string | undefined {
if (typeof raw !== 'string') return undefined
const base = raw.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})$/)
if (!parts) return undefined
const extension = parts[2]
const stem = sanitize(parts[1]).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 on a file that already carries it
const wanted = stem.startsWith(cleanPrefix) ? '' : cleanPrefix
const room = MAX_FILENAME_LENGTH - wanted.length - extension.length
return wanted + stem.slice(0, Math.max(1, room)) + extension
}
+134
View File
@@ -0,0 +1,134 @@
import { Readable } from 'stream'
import crypto from 'crypto'
import { apiUrl, authHeaders, buildUrl, log, streamingRequestInit } from '@ipp/core'
import { UploadPermit, assertPermit } from './gate'
/**
* Everything forwarded about one file, already validated by `receive.ts`.
* `filename` is sanitised and carries an extension; `mimeType` is the bare
* type with no parameters.
*/
export interface IncomingUpload {
filename: string
mimeType: string
fileCreatedAt: string
fileModifiedAt: string
/** Raw file bytes, streamed straight through and never buffered. */
body: Readable
/** The declared `Content-Length`; the upload aborts past it. */
maxBytes: number
}
export type ForwardResult =
| { ok: true, status: 'created' | 'duplicate', id: string, bytes: number }
| { ok: false, status: number, reason: string }
export const NOT_ACCEPTING_UPLOADS = 'This share does not accept uploads'
/** Thrown by the body generator when an upload runs past `maxBytes`. */
class UploadTooLargeError extends Error {}
/**
* Serialise one multipart/form-data body for Immich's `POST /assets`. The
* field set is fixed, so it is written by hand. The async generator pulls a
* chunk only when the socket to Immich is ready for it.
*
* Only the two timestamps and the file are sent, so fields Immich would
* otherwise honour (`visibility`, `livePhotoVideoId`, `metadata`,
* `sidecarData`) cannot be set by a visitor. The filename rides on the
* part's own Content-Disposition, which is where Immich reads it from.
*/
function multipartBody (boundary: string, upload: IncomingUpload, counter: { bytes: number }): Readable {
const fields: Record<string, string> = {
fileCreatedAt: upload.fileCreatedAt,
fileModifiedAt: upload.fileModifiedAt
}
const part = (headers: string) => Buffer.from(`--${boundary}\r\n${headers}\r\n\r\n`)
async function * generate () {
for (const [name, value] of Object.entries(fields)) {
yield part(`Content-Disposition: form-data; name="${name}"`)
yield Buffer.from(value + '\r\n')
}
yield part(
`Content-Disposition: form-data; name="assetData"; filename="${upload.filename}"\r\n` +
`Content-Type: ${upload.mimeType}`
)
for await (const chunk of upload.body) {
counter.bytes += chunk.length
if (counter.bytes > upload.maxBytes) throw new UploadTooLargeError()
yield chunk
}
yield Buffer.from(`\r\n--${boundary}--\r\n`)
}
return Readable.from(generate())
}
/**
* Map Immich's answer to an upload onto the reply the visitor gets. 201 is a
* new asset; 200 is a checksum match with an asset the owner already has,
* which Immich still adds to the album or link. 400 is Immich refusing the
* file itself. 401 and 403 mean the share no longer accepts uploads.
*/
export function replyForImmichStatus (status: number, body?: { id?: string, status?: string } | null): ForwardResult {
if (status === 200 || status === 201) {
return { ok: true, status: body?.status === 'duplicate' ? 'duplicate' : 'created', id: body?.id || '', bytes: 0 }
}
if (status === 400) return { ok: false, status: 400, reason: 'Immich would not accept this file' }
if (status === 401 || status === 403) return { ok: false, status: 403, reason: NOT_ACCEPTING_UPLOADS }
return { ok: false, status: 502, reason: 'Immich rejected the upload' }
}
/**
* Send one upload to Immich as the share, and report what Immich made of it.
* Authentication is the visitor's share key (plus the password token for a
* password share); Immich files the asset into the album or the link itself.
* Errors are returned, except a permit failure, which is a bug.
*/
export async function forwardUpload (permit: UploadPermit, upload: IncomingUpload, signal: AbortSignal): Promise<ForwardResult> {
assertPermit(permit)
const boundary = '----IPPUpload' + crypto.randomBytes(16).toString('hex')
const counter = { bytes: 0 }
const url = buildUrl(apiUrl() + '/assets', { [permit.keyType]: permit.key })
let res: globalThis.Response
try {
res = await fetch(url, streamingRequestInit({
method: 'POST',
headers: {
'Content-Type': 'multipart/form-data; boundary=' + boundary,
...(await authHeaders(permit.keyType, permit.key, permit.password))
},
signal
}, multipartBody(boundary, upload, counter)))
} catch (e) {
// The generator's throw surfaces here as the fetch rejecting
if (causedBy(e, UploadTooLargeError)) return { ok: false, status: 413, reason: 'File is larger than declared' }
if (signal.aborted) return { ok: false, status: 499, reason: 'Visitor cancelled the upload' }
log.warn('Upload to Immich failed for ' + upload.filename + ': ' + errorText(e))
return { ok: false, status: 502, reason: 'Could not reach Immich' }
}
const body = await res.json().catch(() => null) as { id?: string, status?: string, message?: string } | null
const result = replyForImmichStatus(res.status, body)
if (result.ok) return { ...result, bytes: counter.bytes }
log.warn('Immich refused upload ' + upload.filename + ' with status ' + res.status +
(body?.message ? ': ' + body.message : ''))
return result
}
/** Walk the `cause` chain: fetch wraps the body generator's error. */
function causedBy (e: unknown, type: new () => Error): boolean {
let current: unknown = e
while (current instanceof Error) {
if (current instanceof type) return true
current = (current as { cause?: unknown }).cause
}
return false
}
function errorText (e: unknown): string {
return e instanceof Error ? e.message : String(e)
}
+60
View File
@@ -0,0 +1,60 @@
/*
The upload authorisation gate. The upload is the only place this codebase
writes to Immich, so the check is not left to a caller remembering it:
1. `authoriseUpload()` - per request, once the share is resolved. Returns
an `UploadPermit`, which `forwardUpload` cannot be called without.
2. `assertPermit()` - immediately before the request to Immich is built.
The gate is the owner's "Allow public user to upload" toggle on the share,
read from a share lookup at most 60 s old. Immich enforces the same toggle
on every upload, so a mistake here still cannot upload to a share whose
owner said no.
*/
import { KeyType, SharedLink, slugLinksDisabled } from '@ipp/core'
/*
A real symbol rather than a type-only brand, so `assertPermit` has
something to test once types are erased. Not exported and not in the
global registry, so a permit cannot be built outside this file.
*/
const permitBrand: unique symbol = Symbol('ipp.uploadPermit')
/**
* Proof that a share passed the upload gate, plus the share-scoped
* credentials the forwarder needs. Obtainable only from `authoriseUpload`.
*/
export interface UploadPermit {
readonly [permitBrand]: true
readonly link: SharedLink
/** The key exactly as the visitor's URL carried it (a key or a slug). */
readonly key: string
readonly keyType: KeyType
/** Share password from the session cookie, for password-protected shares. */
readonly password?: string
}
/** Whether this share accepts uploads through this key type right now. */
export function uploadAllowed (link: SharedLink, keyType: KeyType): boolean {
return link.allowUpload === true && !slugLinksDisabled(keyType)
}
/** Issue a permit, or null when this share does not accept uploads. */
export function authoriseUpload (link: SharedLink, key: string, keyType: KeyType, password?: string): UploadPermit | null {
if (!uploadAllowed(link, keyType)) return null
return { [permitBrand]: true, link, key, keyType, password } as UploadPermit
}
/**
* Re-check the gate at the point of use. Throws, because reaching here
* without a valid permit is a bug, not a visitor error.
*/
export function assertPermit (permit: UploadPermit): void {
if (!permit || permit[permitBrand] !== true) {
throw new Error('Upload attempted without a permit')
}
if (!uploadAllowed(permit.link, permit.keyType)) {
throw new Error('Upload attempted for a share that does not allow uploads')
}
}
@@ -1,5 +1,8 @@
import { Transform } from 'stream' import { Transform } from 'stream'
/** The error an idle stream is destroyed with. */
export class IdleTimeoutError extends Error {}
/** /**
* A pass-through Transform that destroys itself if no data flows through for * 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 * `idleMs`. The timer is set when the transform is created and reset on every
@@ -11,7 +14,7 @@ export function createIdleTimeoutStream (idleMs: number): Transform {
const transform: Transform = new Transform({ const transform: Transform = new Transform({
transform (chunk, _, cb) { transform (chunk, _, cb) {
if (timer) clearTimeout(timer) if (timer) clearTimeout(timer)
timer = setTimeout(() => transform.destroy(new Error(`No data received for ${idleMs}ms`)), idleMs) timer = setTimeout(() => transform.destroy(new IdleTimeoutError(`No data received for ${idleMs}ms`)), idleMs)
cb(null, chunk) cb(null, chunk)
}, },
flush (cb) { flush (cb) {
@@ -21,6 +24,6 @@ export function createIdleTimeoutStream (idleMs: number): Transform {
}) })
// Arm the timer immediately so a response that returns headers but never // Arm the timer immediately so a response that returns headers but never
// sends a body also times out. // sends a body also times out.
timer = setTimeout(() => transform.destroy(new Error(`No data received for ${idleMs}ms`)), idleMs) timer = setTimeout(() => transform.destroy(new IdleTimeoutError(`No data received for ${idleMs}ms`)), idleMs)
return transform return transform
} }
+161
View File
@@ -0,0 +1,161 @@
#!/usr/bin/env node
import 'dotenv/config'
import express, { Router } from 'express'
import { Request } from 'express-serve-static-core'
import { resolve } from 'path'
import dayjs from 'dayjs'
import { h } from 'preact'
import {
addNoStoreHeaders,
asyncHandler,
CORE_PUBLIC_DIR,
decodeCookie,
enforceMinimumImmichVersion,
errorHandler,
getKeyTypeFromShare,
healthcheck,
invalidPasswordResponse,
isKey,
KeyType,
loadConfig,
Password,
renderPage,
respondToInvalidRequest,
sessionMiddleware,
SharedLink,
slugLinksDisabled,
title,
unlockHandler
} from '@ipp/core'
import { basePathFrom, galleryUrl, maxFileSize } from './config'
import { uploadAllowed } from './gate'
import { createUploadReceiver } from './receive'
import { getShare } from './share'
import { ASSET_VERSION } from './version'
import { UploadPage } from './view/upload'
// Must run before any code that calls getConfigOption. The bundled
// config.json sits one level above this file, which is /app/config.json in
// the image.
loadConfig({ defaultPath: resolve(__dirname, '../config.json') })
const basePath = basePathFrom(process.env.PUBLIC_BASE_URL)
const receiveUpload = createUploadReceiver()
const inProduction = process.env.NODE_ENV === 'production'
const app = express()
app.disable('x-powered-by')
// Reachable at the root whatever the mount prefix, so one compose healthcheck fits both routing shapes
app.get(['/healthcheck', '/share/healthcheck'], asyncHandler(healthcheck))
const router = Router()
for (const dir of ['public', CORE_PUBLIC_DIR]) {
router.use('/share/static/' + ASSET_VERSION, express.static(dir, { immutable: inProduction, maxAge: inProduction ? '365d' : 0 }))
router.use('/share/static', express.static(dir))
}
// Everything past the static assets is never cached
router.use((_req, res, next) => {
addNoStoreHeaders(res)
next()
})
router.use(sessionMiddleware({ name: 'upload-session', path: basePath || '/' }))
type ShareResolution =
| { ok: true, link: SharedLink, keyType: KeyType }
| { ok: false, reason: string, passwordRequired?: boolean }
/** Validate the share in the URL against Immich, with the password from the session cookie. */
async function resolveShare (req: Request): Promise<ShareResolution> {
const keyType = getKeyTypeFromShare(req.params.shareType)
if (slugLinksDisabled(keyType)) return { ok: false, reason: 'Slug links are disabled in config.json' }
if (!isKey(req.params.key)) return { ok: false, reason: 'Invalid key for ' + req.path }
const share = await getShare(req.params.key, keyType, req.password)
if (!share.valid) return { ok: false, reason: 'Invalid share link' }
if (share.passwordRequired || !share.link) return { ok: false, reason: 'Password required', passwordRequired: true }
return { ok: true, link: share.link, keyType }
}
/*
* [ROUTE] Upload page, or the password page for a locked share
*/
router.get('/:shareType(share|s)/:key', decodeCookie, asyncHandler(async (req, res) => {
const key = req.params.key
const resolved = await resolveShare(req)
if (!resolved.ok && resolved.passwordRequired) {
if (req.password) invalidPasswordResponse(req, res, key)
res.send(renderPage(h(Password, { shareKey: key, notifyInvalidPassword: !!req.password, basePath })))
return
}
if (!resolved.ok || !uploadAllowed(resolved.link, resolved.keyType)) {
respondToInvalidRequest(res, 404, resolved.ok ? 'Share does not accept uploads' : resolved.reason)
return
}
const gallery = galleryUrl()
res.send(renderPage(h(UploadPage, {
config: {
uploadUrl: `${basePath}/${req.params.shareType}/${encodeURIComponent(key)}/upload`,
maxFileSize: maxFileSize(),
title: title(resolved.link)
},
basePath,
galleryLink: gallery && `${gallery}/${req.params.shareType}/${encodeURIComponent(key)}`
})))
}))
/*
* [ROUTE] Password unlock from the password page
*/
router.post('/share/unlock', express.json({ limit: '10kb' }), unlockHandler)
/*
* [ROUTE] One file from a visitor, streamed to Immich
*/
router.post('/:shareType(share|s)/:key/upload', decodeCookie, asyncHandler(async (req, res) => {
const resolved = await resolveShare(req)
if (!resolved.ok) {
res.set('Connection', 'close')
respondToInvalidRequest(res, 404, resolved.reason)
return
}
await receiveUpload(req, res, resolved.link, resolved.keyType)
}))
router.get(['/healthcheck', '/share/healthcheck'], asyncHandler(healthcheck))
app.use(basePath || '/', router)
/*
* Everything else, including `/`, gets the 404 policy
*/
app.all('*', (req, res) => {
addNoStoreHeaders(res)
respondToInvalidRequest(res, 404, 'Invalid route ' + req.path)
})
app.use(errorHandler)
process.on('uncaughtException', (err) => {
console.error('There was an uncaught error', err)
server.close()
process.exit(1)
})
process.on('unhandledRejection', (reason, promise) => {
console.error('Unhandled Rejection at:', promise, 'reason:', reason)
})
process.on('SIGTERM', () => {
console.log('Received SIGTERM. Gracefully shutting down...')
server.close()
process.exit(0)
})
const port = Number(process.env.IPP_PORT) || 3000
const server = app.listen(port, () => {
console.log(dayjs().format() + ' Upload service started on port ' + port + (basePath ? ' under ' + basePath : ''))
enforceMinimumImmichVersion().catch(() => {})
})
// A large video on a phone uplink outlasts any whole-request limit; the body has an idle timeout instead
server.requestTimeout = 0
+54
View File
@@ -0,0 +1,54 @@
import { TtlLruCache } from '@ipp/core'
export type Admission =
| { ok: true, release: () => void }
| { ok: false, retryAfterSeconds: number }
interface Window {
used: number
resetAt: number
}
/**
* Fixed-window budget: each key may admit up to `limit` units per window.
* The rate limit admits one unit per file; the byte budget admits a file's
* declared length, and releases it if the upload then fails.
*
* Backed by TtlLruCache, so a flood of distinct keys evicts instead of
* growing without limit. The window lives on the entry rather than on the
* cache TTL, so admitting inside a window never extends it. A `limit` of 0
* or less means no limit.
*/
export function createWindowBudget (opts: { limit: number, windowMs: number, maxKeys?: number }): (key: string, amount?: number) => Admission {
const windows = new TtlLruCache<Window>({
// Twice the window, so the cache never drops an entry while its window is open
ttlMs: opts.windowMs * 2,
max: opts.maxKeys ?? 5000
})
const unlimited: Admission = { ok: true, release: () => {} }
return function admit (key: string, amount = 1): Admission {
if (opts.limit <= 0) return unlimited
const now = Date.now()
let window = windows.get(key)
if (!window || window.resetAt <= now) {
window = { used: 0, resetAt: now + opts.windowMs }
windows.set(key, window)
}
if (window.used + amount > opts.limit) {
return { ok: false, retryAfterSeconds: Math.max(1, Math.ceil((window.resetAt - now) / 1000)) }
}
window.used += amount
const admitted = window
let released = false
return {
ok: true,
release: () => {
// A release after its window closed has nothing left to give back
if (released || admitted.resetAt <= Date.now()) return
released = true
admitted.used -= amount
}
}
}
}
+80
View File
@@ -0,0 +1,80 @@
import { AlbumType, log, SharedLink, title } from '@ipp/core'
import { formatSize } from './shared/upload'
import { notifyConfig } from './config'
/*
Optional upload notification: one JSON POST per stored file to
`ipp.upload.notifyUrl`, for ntfy, Gotify, Home Assistant and the like.
The payload never carries the share key, slug or password.
*/
export interface UploadNotification {
title: string
message: string
data: {
event: 'upload'
time: string
share: { type: 'album' | 'individual', id: string, title: string }
file: { name: string, size: number, type: string }
asset: { id: string, status: 'created' | 'duplicate' }
}
}
/**
* Build the notification body for one stored file. `title` and `message` are
* top level so a receiver expecting a flat shape shows something readable
* with no mapping; everything structured lives under `data`.
*/
export function buildNotification (
share: SharedLink,
file: { name: string, size: number, type: string },
asset: { id: string, status: 'created' | 'duplicate' }
): UploadNotification {
const isAlbum = share.type === AlbumType.album
const shareTitle = title(share)
return {
title: 'Photo sent to ' + shareTitle,
message: `${file.name} (${formatSize(file.size)}) was uploaded to ${shareTitle}.`,
data: {
event: 'upload',
time: new Date().toISOString(),
share: {
type: isAlbum ? 'album' : 'individual',
// An album share is named by its album, an individual share by the link
id: (isAlbum ? share.album?.id : share.id) || '',
title: shareTitle
},
file,
asset
}
}
}
/**
* Post the notification, if one is configured. Fire and forget: a timeout,
* no retry, failures logged and swallowed. Only the URL's host is logged,
* because ntfy topics and Gotify tokens live in the URL.
*/
export async function sendNotification (notification: UploadNotification): Promise<void> {
const config = notifyConfig()
if (!config) return
try {
const res = await fetch(config.url, {
method: 'POST',
headers: { 'Content-Type': 'application/json', ...config.headers },
body: JSON.stringify(notification),
signal: AbortSignal.timeout(config.timeoutMs)
})
if (!res.ok) log.warn('Upload notification to ' + hostOf(config.url) + ' answered ' + res.status)
} catch (e) {
log.warn('Upload notification to ' + hostOf(config.url) + ' failed: ' + (e instanceof Error ? e.message : String(e)))
}
}
function hostOf (url: string): string {
try {
return new URL(url).host
} catch {
return 'an invalid URL'
}
}
+141
View File
@@ -0,0 +1,141 @@
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 { byteBudget, filenamePrefix, maxFileSize, rateLimit } from './config'
import { uploadFilename } from './filename'
import { forwardUpload } from './forward'
import { authoriseUpload } from './gate'
import { createIdleTimeoutStream, IdleTimeoutError } from './idleTimeoutStream'
import { createWindowBudget } from './limits'
import { buildNotification, sendNotification } from './notify'
import { formatSize, isUploadableType } from './shared/upload'
/*
The visitor-facing half of the upload path: validate one request, then
hand it to `forward.ts` with a permit from `gate.ts`.
Each file is its own POST whose body is the raw bytes, with the name and
timestamps in the query string. The app re-encodes for Immich anyway, so
it runs no multipart parser on visitor input, and nothing is buffered or
written to disk.
*/
// A body that sends nothing for this long is dropped
const BODY_IDLE_MS = 60_000
/**
* Answer an upload the server will not take, in the shape the page reads.
* `Connection: close` stops a body still in flight costing its full bandwidth.
*/
function refuse (res: Response, status: number, reason: string): void {
res.set('Connection', 'close')
res.status(status).json({ error: reason })
}
/** The declared `Content-Length`, or undefined when absent or malformed. */
export function declaredLength (header: string | undefined): number | undefined {
return header && /^\d+$/.test(header) ? Number(header) : undefined
}
/**
* Parse a visitor-supplied timestamp, falling back to now. Only a starting
* point: Immich replaces it from EXIF when the file carries a better date.
*/
export function uploadTimestamp (raw: unknown): string {
const parsed = typeof raw === 'string' && raw ? dayjs(raw) : undefined
return (parsed?.isValid() ? parsed : dayjs()).toISOString()
}
/**
* Build the handler for `POST <share>/upload`, with its rate limit and byte
* budget read from config. Called once, after the config has loaded.
*
* Once the share has passed the gate, failures a visitor can act on answer
* with a status and a short JSON reason rather than the 404 policy.
*/
export function createUploadReceiver () {
// Keyed on address and share; behind a reverse proxy every visitor has the proxy's address
const rate = createWindowBudget({ limit: rateLimit(), windowMs: 60_000 })
const budget = createWindowBudget({ limit: byteBudget(), windowMs: 60 * 60_000 })
const maxBytes = maxFileSize()
const prefix = filenamePrefix()
return async function receiveUpload (req: Request, res: Response, link: SharedLink, keyType: KeyType): Promise<void> {
const key = req.params.key
const permit = authoriseUpload(link, key, keyType, req.password)
if (!permit) {
res.set('Connection', 'close')
respondToInvalidRequest(res, 404, 'Share does not accept uploads')
return
}
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 > maxBytes) {
refuse(res, 413, 'Larger than the ' + formatSize(maxBytes) + ' limit')
return
}
const filename = uploadFilename(req.query.filename, prefix)
if (!filename) {
refuse(res, 400, 'Missing or unusable filename')
return
}
const mimeType = (req.headers['content-type'] || '').split(';')[0].trim().toLowerCase()
if (!isUploadableType(mimeType)) {
refuse(res, 415, 'Only photos and videos can be sent')
return
}
// Reserved before streaming, so parallel uploads cannot overshoot the budget together
const reserved = budget(shareId, length)
if (!reserved.ok) {
res.set('Retry-After', String(reserved.retryAfterSeconds))
refuse(res, 413, 'This share has received its limit for the hour. Try again later.')
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 result = await forwardUpload(permit, {
filename,
mimeType,
fileCreatedAt: uploadTimestamp(req.query.fileCreatedAt),
fileModifiedAt: uploadTimestamp(req.query.fileModifiedAt),
body,
maxBytes: length
}, abortOnClose(res))
if (!result.ok) {
reserved.release()
// The visitor hung up; there is nobody left to answer
if (result.status === 499) return
refuse(res, result.status, result.reason)
return
}
log('Received upload ' + filename + ' for share ' + (link.slug || link.id) + ' (' + result.status + ')')
res.json({ status: result.status })
// After the reply, so a slow webhook never holds up the visitor
sendNotification(buildNotification(
link,
{ name: filename, size: result.bytes, type: mimeType },
{ id: result.id, status: result.status }
))
}
}
+13
View File
@@ -0,0 +1,13 @@
import { cachedPromise, fetchSharedLink, KeyType, SharedLinkResult, TtlLruCache } from '@ipp/core'
/*
Share lookups, cached for 60 s per (key type, key, password). The cache
bounds how stale the `allowUpload` check can be when an owner turns the
toggle off; Immich enforces the toggle on every upload regardless.
*/
const shareCache = new TtlLruCache<Promise<SharedLinkResult>>({ ttlMs: 60_000, max: 100 })
/** Look up a share through `@ipp/core`, sharing one Immich call across concurrent requests. */
export function getShare (key: string, keyType: KeyType, password?: string): Promise<SharedLinkResult> {
return cachedPromise(shareCache, `${keyType}:${key}:${password || ''}`, () => fetchSharedLink(key, keyType, password), result => result.valid)
}
+21
View File
@@ -0,0 +1,21 @@
/**
* Returns a function that runs at most `limit` async tasks concurrently.
* Tasks queue when the limit is reached and resume in FIFO order.
*/
export function createLimiter (limit: number) {
let active = 0
const queue: Array<() => void> = []
return async function run<T> (fn: () => Promise<T>): Promise<T> {
if (active >= limit) {
await new Promise<void>(resolve => queue.push(resolve))
}
active++
try {
return await fn()
} finally {
active--
const next = queue.shift()
if (next) next()
}
}
}
+82
View File
@@ -0,0 +1,82 @@
/*
Upload rules the page client and the server both apply: the client filters
with them before anything leaves the browser, the server decides with them.
*/
/** `accept` attribute for the file picker: the camera roll on a phone. */
export const UPLOAD_ACCEPT = 'image/*,video/*'
/**
* Whether a file of this media type may be sent. Any image or video except
* SVG, the one image type a browser may execute. Immich types an asset by its
* extension and refuses anything outside its own list, so the finer check is
* left to Immich.
*/
export function isUploadableType (mimeType: string): boolean {
const type = (mimeType || '').split(';')[0].trim().toLowerCase()
if (type === 'image/svg+xml') return false
return type.startsWith('image/') || type.startsWith('video/')
}
/*
Types for files a desktop browser reports with an empty `File.type`: HEIC,
HEIF, camera RAW and some video containers. Immich types the asset by its
extension, so these only need to pass `isUploadableType`.
*/
const TYPE_BY_EXTENSION: Record<string, string> = {
heic: 'image/heic',
heif: 'image/heif',
hif: 'image/heif',
avif: 'image/avif',
jxl: 'image/jxl',
dng: 'image/x-adobe-dng',
cr2: 'image/x-canon-cr2',
cr3: 'image/x-canon-cr3',
nef: 'image/x-nikon-nef',
nrw: 'image/x-nikon-nrw',
arw: 'image/x-sony-arw',
raf: 'image/x-fuji-raf',
orf: 'image/x-olympus-orf',
rw2: 'image/x-panasonic-rw2',
pef: 'image/x-pentax-pef',
srw: 'image/x-samsung-srw',
mts: 'video/mp2t',
m2ts: 'video/mp2t',
mkv: 'video/x-matroska',
insv: 'video/mp4'
}
/** The browser's type for a file, or one derived from its extension when the browser gives none. */
export function fileType (name: string, browserType: string): string {
if (browserType) return browserType
const extension = name.split('.').pop()?.toLowerCase() || ''
return TYPE_BY_EXTENSION[extension] || ''
}
/** Bytes as a short human-readable string. */
export function formatSize (bytes: number): string {
if (bytes >= 1024 * 1024 * 1024) return (bytes / (1024 * 1024 * 1024)).toFixed(1) + ' GB'
if (bytes >= 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(1) + ' MB'
if (bytes >= 1024) return Math.round(bytes / 1024) + ' KB'
return bytes + ' bytes'
}
/** Page settings the server renders into the init JSON for the client. */
export interface UploadPageConfig {
/** Path of this share's upload endpoint, including any mount prefix. */
uploadUrl: string
/** Largest single file the server accepts, in bytes. */
maxFileSize: number
/** Share title, for the drop overlay and the completion message. */
title: string
}
/** Success body of `POST <share>/upload`. */
export interface UploadResponse {
status: 'created' | 'duplicate'
}
/** Failure body of `POST <share>/upload`. */
export interface UploadErrorResponse {
error: string
}
+5
View File
@@ -0,0 +1,5 @@
import { join } from 'path'
import { resolveAppVersion } from '@ipp/core'
/** URL-safe cache-busting segment for static asset paths. */
export const ASSET_VERSION = encodeURIComponent(resolveAppVersion(join(__dirname, '..', 'package.json')))
+47
View File
@@ -0,0 +1,47 @@
import { jsonForInlineScript, ThemeScript } from '@ipp/core'
import { UPLOAD_ACCEPT, UploadPageConfig } from '../shared/upload'
import { ASSET_VERSION } from '../version'
export interface UploadPageProps {
config: UploadPageConfig
/** Path prefix the app is mounted under, without a trailing slash. Empty at the root. */
basePath: string
/** This share's gallery on IPP, when `GALLERY_URL` is set. */
galleryLink?: string
}
/** The upload page for one share: the share title, the picker, and the list the client fills. */
export function UploadPage ({ config, basePath, galleryLink }: UploadPageProps) {
const staticPath = `${basePath}/share/static/${ASSET_VERSION}`
return (
<html lang="en">
<head>
<ThemeScript/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="robots" content="noindex"/>
<title>{'Send photos to ' + config.title}</title>
<link rel="icon" href={basePath + '/share/static/favicon.ico'} type="image/x-icon"/>
<link type="text/css" rel="stylesheet" href={staticPath + '/pico.min.css'}/>
<link type="text/css" rel="stylesheet" href={staticPath + '/theme.css'}/>
<link type="text/css" rel="stylesheet" href={staticPath + '/style.css'}/>
</head>
<body>
<main class="container upload-page">
<h1>Send photos to <em>{config.title}</em></h1>
<button id="upload-choose" type="button" class="upload-choose">Choose photos</button>
<input id="upload-input" type="file" multiple accept={UPLOAD_ACCEPT} hidden/>
{galleryLink && <p><a class="upload-back" href={galleryLink}>Back to gallery</a></p>}
<section id="upload-batch" hidden aria-live="polite">
<h2 id="upload-status"></h2>
<ul id="upload-list"></ul>
</section>
</main>
<div id="upload-drop" hidden>
<p>Drop to send photos to <em>{config.title}</em></p>
</div>
<script type="application/json" id="upload-init" dangerouslySetInnerHTML={{ __html: jsonForInlineScript(config) }}/>
<script type="module" src={staticPath + '/js/client/upload.js'}></script>
</body>
</html>
)
}
+43
View File
@@ -0,0 +1,43 @@
import { describe, it, expect, afterEach } from 'vitest'
import { basePathFrom, byteBudget, filenamePrefix, maxFileSize, notifyConfig } from '../src/config'
import { resetConfig, setConfig } from './helpers'
afterEach(resetConfig)
const MB = 1024 * 1024
describe('basePathFrom', () => {
it('is empty for an own-hostname deployment', () => {
expect(basePathFrom('https://upload.example.com')).toBe('')
expect(basePathFrom('https://upload.example.com/')).toBe('')
expect(basePathFrom(undefined)).toBe('')
})
it('is the URL path for a path-prefix deployment, without a trailing slash', () => {
expect(basePathFrom('https://photos.example.com/upload')).toBe('/upload')
expect(basePathFrom('https://photos.example.com/a/b/')).toBe('/a/b')
})
it('is empty for a value that is not a URL', () => {
expect(basePathFrom('not a url')).toBe('')
})
})
describe('upload options', () => {
it('has the documented defaults', () => {
expect(maxFileSize()).toBe(500 * MB)
expect(byteBudget()).toBe(10240 * MB)
expect(filenamePrefix()).toBe('ipp_upload_')
expect(notifyConfig()).toBeUndefined()
})
it('never lets maxFileSize reach zero, which would refuse every file', () => {
setConfig({ ipp: { upload: { maxFileSize: 0 } } })
expect(maxFileSize()).toBe(MB)
})
it('keeps only string notification headers', () => {
setConfig({ ipp: { upload: { notifyUrl: 'https://ntfy.example.com/topic', notifyHeaders: { Authorization: 'Bearer x', Bad: 1 } } } })
expect(notifyConfig()).toEqual({ url: 'https://ntfy.example.com/topic', headers: { Authorization: 'Bearer x' }, timeoutMs: 10_000 })
})
})
+44
View File
@@ -0,0 +1,44 @@
import { describe, it, expect } from 'vitest'
import { uploadFilename } from '../src/filename'
describe('uploadFilename', () => {
it('keeps an ordinary filename', () => {
expect(uploadFilename('IMG_0042.jpg', '')).toBe('IMG_0042.jpg')
})
it('strips path components so traversal cannot survive', () => {
expect(uploadFilename('../../etc/passwd.jpg', '')).toBe('passwd.jpg')
expect(uploadFilename('C:\\Users\\bob\\holiday.png', '')).toBe('holiday.png')
})
it('removes characters that are illegal in a filename or would break the multipart header', () => {
expect(uploadFilename('we"rd:na*me.jpg', '')).toBe('werdname.jpg')
})
it('rejects a name with no extension', () => {
expect(uploadFilename('photo', '')).toBeUndefined()
})
it('rejects dotfiles and non-string input', () => {
expect(uploadFilename('.htaccess', '')).toBeUndefined()
expect(uploadFilename('', '')).toBeUndefined()
expect(uploadFilename(undefined, '')).toBeUndefined()
expect(uploadFilename(['a.jpg'], '')).toBeUndefined()
})
it('applies the prefix once', () => {
expect(uploadFilename('IMG_0042.jpg', 'ipp_upload_')).toBe('ipp_upload_IMG_0042.jpg')
expect(uploadFilename('ipp_upload_IMG_0042.jpg', 'ipp_upload_')).toBe('ipp_upload_IMG_0042.jpg')
})
it('sanitises an operator prefix that would break the filename', () => {
expect(uploadFilename('IMG_0042.jpg', '../ev"il/')).toBe('..evilIMG_0042.jpg')
})
it('stays within 254 characters with the extension intact', () => {
const result = uploadFilename('x'.repeat(400) + '.jpg', 'ipp_upload_') || ''
expect(result.startsWith('ipp_upload_')).toBe(true)
expect(result.endsWith('.jpg')).toBe(true)
expect(result.length).toBeLessThanOrEqual(254)
})
})
+23
View File
@@ -0,0 +1,23 @@
import { describe, it, expect } from 'vitest'
import { NOT_ACCEPTING_UPLOADS, replyForImmichStatus } from '../src/forward'
describe('replyForImmichStatus', () => {
it('reports a new asset and a duplicate as success', () => {
expect(replyForImmichStatus(201, { id: 'a1', status: 'created' })).toMatchObject({ ok: true, status: 'created', id: 'a1' })
expect(replyForImmichStatus(200, { id: 'a1', status: 'duplicate' })).toMatchObject({ ok: true, status: 'duplicate', id: 'a1' })
})
it('passes Immich refusing the file through as 400', () => {
expect(replyForImmichStatus(400)).toMatchObject({ ok: false, status: 400 })
})
it('reads 401 and 403 as the share no longer accepting uploads', () => {
expect(replyForImmichStatus(401)).toEqual({ ok: false, status: 403, reason: NOT_ACCEPTING_UPLOADS })
expect(replyForImmichStatus(403)).toEqual({ ok: false, status: 403, reason: NOT_ACCEPTING_UPLOADS })
})
it('reports anything else as an upstream failure', () => {
expect(replyForImmichStatus(500)).toMatchObject({ ok: false, status: 502 })
expect(replyForImmichStatus(413)).toMatchObject({ ok: false, status: 502 })
})
})
+38
View File
@@ -0,0 +1,38 @@
import { describe, it, expect, afterEach } from 'vitest'
import { KeyType } from '@ipp/core'
import { assertPermit, authoriseUpload, UploadPermit } from '../src/gate'
import { resetConfig, setConfig, share } from './helpers'
afterEach(resetConfig)
describe('authoriseUpload', () => {
it('issues a permit only when the share\'s Immich toggle is on', () => {
expect(authoriseUpload(share(), 'k', KeyType.key)).not.toBeNull()
expect(authoriseUpload(share({ allowUpload: false }), 'k', KeyType.key)).toBeNull()
expect(authoriseUpload(share({ allowUpload: undefined }), 'k', KeyType.key)).toBeNull()
})
it('refuses slug links when the operator has turned them off', () => {
setConfig({ ipp: { allowSlugLinks: false } })
expect(authoriseUpload(share(), 'my-slug', KeyType.slug)).toBeNull()
expect(authoriseUpload(share(), 'k', KeyType.key)).not.toBeNull()
})
})
describe('assertPermit', () => {
it('passes a permit from authoriseUpload', () => {
expect(() => assertPermit(authoriseUpload(share(), 'k', KeyType.key)!)).not.toThrow()
})
it('throws for a permit built by hand', () => {
const forged = { link: share(), key: 'k', keyType: KeyType.key } as unknown as UploadPermit
expect(() => assertPermit(forged)).toThrow('without a permit')
})
it('throws when the share stopped accepting uploads after the permit was issued', () => {
const link = share()
const permit = authoriseUpload(link, 'k', KeyType.key)!
link.allowUpload = false
expect(() => assertPermit(permit)).toThrow('does not allow uploads')
})
})
+26
View File
@@ -0,0 +1,26 @@
import { AlbumType, KeyType, loadConfig, SharedLink } from '@ipp/core'
/** Load `config` as if it came from the `CONFIG` env var. */
export function setConfig (config: Record<string, unknown>) {
process.env.CONFIG = JSON.stringify(config)
loadConfig()
}
export function resetConfig () {
delete process.env.CONFIG
loadConfig()
}
export function share (overrides: Partial<SharedLink> = {}): SharedLink {
return {
id: 'ffffffff-0000-0000-0000-000000000001',
key: 'share-key',
keyType: KeyType.key,
type: AlbumType.album,
assets: [],
expiresAt: null,
allowUpload: true,
album: { id: 'aaaaaaaa-0000-0000-0000-000000000002', albumName: 'Holiday 2025' },
...overrides
}
}
+69
View File
@@ -0,0 +1,69 @@
import { describe, it, expect, vi, afterEach } from 'vitest'
import { createWindowBudget } from '../src/limits'
afterEach(() => {
vi.useRealTimers()
})
describe('createWindowBudget as a rate limit', () => {
it('admits up to the limit, then refuses with the seconds left in the window', () => {
vi.useFakeTimers()
const rate = createWindowBudget({ limit: 3, windowMs: 60_000 })
expect([1, 2, 3].map(() => rate('ip:share').ok)).toEqual([true, true, true])
vi.advanceTimersByTime(20_000)
expect(rate('ip:share')).toEqual({ ok: false, retryAfterSeconds: 40 })
})
it('counts only admitted requests', () => {
const rate = createWindowBudget({ limit: 1, windowMs: 60_000 })
rate('a')
rate('a')
rate('a')
expect(rate('b').ok).toBe(true)
})
it('starts a fresh window once the old one has passed', () => {
vi.useFakeTimers()
const rate = createWindowBudget({ limit: 1, windowMs: 60_000 })
expect(rate('a').ok).toBe(true)
expect(rate('a').ok).toBe(false)
vi.advanceTimersByTime(60_000)
expect(rate('a').ok).toBe(true)
})
it('treats a limit of 0 as no limit', () => {
const rate = createWindowBudget({ limit: 0, windowMs: 60_000 })
expect([1, 2, 3, 4].every(() => rate('a').ok)).toBe(true)
})
})
describe('createWindowBudget as a byte budget', () => {
it('reserves on admission, so parallel uploads cannot overshoot together', () => {
const budget = createWindowBudget({ limit: 100, windowMs: 3_600_000 })
expect(budget('share', 60).ok).toBe(true)
expect(budget('share', 60).ok).toBe(false)
expect(budget('share', 40).ok).toBe(true)
})
it('gives a failed upload\'s reservation back, once', () => {
const budget = createWindowBudget({ limit: 100, windowMs: 3_600_000 })
const first = budget('share', 80)
expect(budget('share', 80).ok).toBe(false)
if (first.ok) {
first.release()
first.release()
}
expect(budget('share', 80).ok).toBe(true)
expect(budget('share', 80).ok).toBe(false)
})
it('ignores a release after its window has closed', () => {
vi.useFakeTimers()
const budget = createWindowBudget({ limit: 100, windowMs: 1000 })
const old = budget('share', 100)
vi.advanceTimersByTime(1000)
expect(budget('share', 100).ok).toBe(true)
if (old.ok) old.release()
expect(budget('share', 1).ok).toBe(false)
})
})
+39
View File
@@ -0,0 +1,39 @@
import { describe, it, expect } from 'vitest'
import { AlbumType } from '@ipp/core'
import { buildNotification } from '../src/notify'
import { share } from './helpers'
const file = { name: 'ipp_upload_IMG_0042.jpg', size: 3145728, type: 'image/jpeg' }
const asset = { id: 'bbbbbbbb-0000-0000-0000-000000000003', status: 'created' as const }
describe('buildNotification', () => {
it('names an album share by its album id', () => {
expect(buildNotification(share(), file, asset).data.share).toEqual({
type: 'album',
id: 'aaaaaaaa-0000-0000-0000-000000000002',
title: 'Holiday 2025'
})
})
it('names an individual share by the link id', () => {
const payload = buildNotification(share({ type: AlbumType.individual, album: undefined, description: 'Some photos' }), file, asset)
expect(payload.data.share).toEqual({
type: 'individual',
id: 'ffffffff-0000-0000-0000-000000000001',
title: 'Some photos'
})
})
it('carries a flat title and message for simple receivers', () => {
const payload = buildNotification(share(), file, asset)
expect(payload.title).toBe('Photo sent to Holiday 2025')
expect(payload.message).toBe('ipp_upload_IMG_0042.jpg (3.0 MB) was uploaded to Holiday 2025.')
})
it('never carries the share key, slug or password', () => {
const payload = JSON.stringify(buildNotification(share({ key: 'secret-key', slug: 'secret-slug', password: 'hunter2' }), file, asset))
expect(payload).not.toContain('secret-key')
expect(payload).not.toContain('secret-slug')
expect(payload).not.toContain('hunter2')
})
})
+75
View File
@@ -0,0 +1,75 @@
import { describe, it, expect } from 'vitest'
import { fileType, formatSize, isUploadableType } from '../src/shared/upload'
import { declaredLength, uploadTimestamp } from '../src/receive'
describe('isUploadableType', () => {
it('accepts photos and videos, with or without parameters', () => {
expect(isUploadableType('image/jpeg')).toBe(true)
expect(isUploadableType('video/quicktime')).toBe(true)
expect(isUploadableType('IMAGE/HEIC')).toBe(true)
expect(isUploadableType('image/jpeg; charset=binary')).toBe(true)
})
it('refuses SVG, the one image type a browser may execute', () => {
expect(isUploadableType('image/svg+xml')).toBe(false)
expect(isUploadableType('IMAGE/SVG+XML; charset=utf-8')).toBe(false)
})
it('refuses anything else', () => {
expect(isUploadableType('application/octet-stream')).toBe(false)
expect(isUploadableType('text/html')).toBe(false)
expect(isUploadableType('')).toBe(false)
})
})
describe('fileType', () => {
it('keeps the type the browser gave', () => {
expect(fileType('IMG_0042.HEIC', 'image/heic')).toBe('image/heic')
})
it('derives a type from the extension when the browser gives none', () => {
expect(fileType('IMG_0042.HEIC', '')).toBe('image/heic')
expect(fileType('DSC_0001.NEF', '')).toBe('image/x-nikon-nef')
expect(isUploadableType(fileType('clip.mts', ''))).toBe(true)
})
it('gives up on an unknown extension, so the client refuses the file', () => {
expect(fileType('notes.txt', '')).toBe('')
})
})
describe('formatSize', () => {
it('picks a readable unit', () => {
expect(formatSize(512)).toBe('512 bytes')
expect(formatSize(3 * 1024)).toBe('3 KB')
expect(formatSize(3145728)).toBe('3.0 MB')
expect(formatSize(2.5 * 1024 * 1024 * 1024)).toBe('2.5 GB')
})
})
describe('declaredLength', () => {
it('reads a plain decimal Content-Length', () => {
expect(declaredLength('3145728')).toBe(3145728)
expect(declaredLength('0')).toBe(0)
})
it('rejects a missing or malformed header', () => {
expect(declaredLength(undefined)).toBeUndefined()
expect(declaredLength('')).toBeUndefined()
expect(declaredLength('12abc')).toBeUndefined()
expect(declaredLength('-1')).toBeUndefined()
expect(declaredLength('1e9')).toBeUndefined()
})
})
describe('uploadTimestamp', () => {
it('passes through a valid timestamp as ISO 8601', () => {
expect(uploadTimestamp('2026-09-14T07:18:00.000Z')).toBe('2026-09-14T07:18:00.000Z')
})
it('falls back to now for junk or missing input', () => {
for (const input of ['not a date', '', undefined, 42]) {
expect(Number.isNaN(Date.parse(uploadTimestamp(input)))).toBe(false)
}
})
})
+27
View File
@@ -0,0 +1,27 @@
{
"compilerOptions": {
"rootDir": "src",
"outDir": "public/js",
"module": "esnext",
"moduleResolution": "bundler",
"target": "ES2022",
"lib": [
"DOM",
"DOM.Iterable",
"ES2022"
],
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true,
"isolatedModules": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"skipLibCheck": true,
"inlineSourceMap": true,
"inlineSources": true
},
"include": [
"src/client/**/*.ts",
"src/shared/**/*.ts"
]
}
+41
View File
@@ -0,0 +1,41 @@
{
"compilerOptions": {
"baseUrl": "src",
"outDir": "dist",
"inlineSourceMap": true,
"inlineSources": true,
"module": "CommonJS",
"target": "ES6",
"allowJs": true,
"noImplicitAny": true,
"esModuleInterop": true,
"moduleResolution": "node",
"importHelpers": true,
"isolatedModules": true,
"strictNullChecks": true,
"lib": [
"DOM",
"ES5",
"ES6",
"ES7"
],
"allowSyntheticDefaultImports": true,
"skipLibCheck": true,
"jsx": "react-jsx",
"jsxImportSource": "preact"
},
"include": [
"**/*.ts",
"**/*.tsx"
],
"exclude": [
"node_modules",
"dist",
"tests",
"vitest.config.ts",
"src/client"
],
"references": [
{ "path": "../shared" }
]
}
+13
View File
@@ -0,0 +1,13 @@
import { resolve } from 'path'
import { defineConfig } from 'vitest/config'
export default defineConfig({
resolve: {
// Test against core's source, so `npm test` needs no build of shared/
alias: { '@ipp/core': resolve(__dirname, '../shared/src/index.ts') }
},
test: {
include: ['tests/**/*.test.ts'],
environment: 'node'
}
})