Check the config reference pages against config.json when the docs build

This commit is contained in:
Alan Grainger
2026-10-08 21:52:34 +13:00
parent 360c46fbc8
commit 19e10337b8
12 changed files with 656 additions and 35 deletions
+5
View File
@@ -1,4 +1,5 @@
import { defineConfigWithTheme, type DefaultTheme } from 'vitepress'
import { configSchemaPlugin } from './configSchema'
const REPO_URL = 'https://github.com/alangrainger/immich-public-proxy'
@@ -43,6 +44,10 @@ export default async () => defineConfigWithTheme<ThemeConfig>({
head: [
['link', { rel: 'icon', href: '/ipp.svg' }]
],
vite: {
// Fails the build when the config reference pages and the default config files disagree
plugins: [configSchemaPlugin()]
},
themeConfig: {
logo: '/ipp.svg',
stars: await fetchStars(),
+354
View File
@@ -0,0 +1,354 @@
import { readdirSync, readFileSync } from 'node:fs'
import { basename, join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { isDeepStrictEqual } from 'node:util'
import type { Plugin } from 'vite'
/*
Reads the config reference pages (docs/config/*.md) into a schema and checks
them against the default config files, both ways. The page format this
parser accepts is the contract in docs/README.md, "Config reference pages";
change the two together.
*/
/** Whether a config.json value is a plain JSON object (not an array or null). */
function isObject (value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
/** The types a `**Type:**` line can name, each with the check its default must pass. */
const TYPE_CHECKS = {
bool: (value: unknown) => typeof value === 'boolean',
int: (value: unknown) => Number.isInteger(value),
string: (value: unknown) => typeof value === 'string',
object: isObject,
'bool or string': (value: unknown) => typeof value === 'boolean' || typeof value === 'string',
various: () => true
}
export type ConfigType = keyof typeof TYPE_CHECKS
/** One allowed value of a key, from its enum list. */
export interface ConfigValue {
value: unknown
/** The item's text after the value, as markdown. */
description: string
}
/** One documented config key. */
export interface ConfigKey {
/** The full dotted path, e.g. `ipp.gallery.showTitle`. */
path: string
type: ConfigType
/** Absent only for an object key whose page gives none (a group or a free-form object). */
default?: unknown
/** The allowed values, when the section has an enum list. */
values?: ConfigValue[]
/** The section's first paragraph, or the table row's description, as markdown. */
description: string
/** The site path of the page, e.g. `/config/gallery`. */
page: string
/** The anchor of the key's section on that page. */
anchor: string
}
/** A default config file, named by its repo path for messages. */
export interface DefaultsFile {
name: string
config: Record<string, unknown>
}
/** The markdown structures the contract is made of. Everything else is `other`. */
type Block =
| { kind: 'heading', level: number, text: string }
| { kind: 'paragraph', text: string }
| { kind: 'list', items: string[] }
| { kind: 'table', rows: string[][] }
| { kind: 'other' }
/**
* Split a page body into blocks. Blocks are separated by blank lines;
* code fences and callouts become `other`, so a `##` or a list inside
* them is never mistaken for part of the contract.
*/
function toBlocks (markdown: string): Block[] {
const lines = markdown.split('\n')
const blocks: Block[] = []
for (let i = 0; i < lines.length; i++) {
const line = lines[i]
if (line.trim() === '') continue
if (line.trimStart().startsWith('```')) {
while (++i < lines.length && !lines[i].trimStart().startsWith('```'));
blocks.push({ kind: 'other' })
continue
}
const heading = /^(#{1,6})\s+(.*)$/.exec(line)
if (heading) {
blocks.push({ kind: 'heading', level: heading[1].length, text: heading[2].trim() })
continue
}
const group = [line]
while (i + 1 < lines.length && lines[i + 1].trim() !== '' && !/^(#{1,6}\s|\s*```)/.test(lines[i + 1])) {
group.push(lines[++i])
}
const previous = blocks[blocks.length - 1]
if (line.startsWith('|')) {
const rows = group.filter(row => !/^\|[\s:|-]+\|$/.test(row.trim()))
blocks.push({ kind: 'table', rows: rows.map(row => row.trim().slice(1, -1).split('|').map(cell => cell.trim())) })
} else if (line.startsWith('- ')) {
const items: string[] = []
for (const itemLine of group) {
if (itemLine.startsWith('- ')) items.push(itemLine.slice(2).trim())
else items[items.length - 1] += ' ' + itemLine.trim()
}
// A blank line between items doesn't end a markdown list
if (previous?.kind === 'list') previous.items.push(...items)
else blocks.push({ kind: 'list', items })
} else if (line.startsWith('>')) {
blocks.push({ kind: 'other' })
} else {
blocks.push({ kind: 'paragraph', text: group.map(text => text.trim()).join(' ') })
}
}
return blocks
}
/** The anchor VitePress gives a heading, under the docs/README.md rule for link-target headings. */
function toAnchor (heading: string): string {
return heading.replace(/`/g, '').trim().toLowerCase().replace(/\s+/g, '-')
}
/** JSON.parse without the throw, for values written on a page. */
function parseLiteral (text: string): { ok: true, value: unknown } | { ok: false } {
try {
return { ok: true, value: JSON.parse(text) }
} catch {
return { ok: false }
}
}
/** Whether a type name, backticks removed, is one the contract knows. */
function isConfigType (type: string): type is ConfigType {
return Object.hasOwn(TYPE_CHECKS, type)
}
/**
* Parse one reference page into the keys it documents. A page without a
* `prefix` in its frontmatter documents none. `page` is its site path, used
* in the keys and in problems.
*/
export function parsePage (markdown: string, page: string): { keys: ConfigKey[], problems: string[] } {
const keys: ConfigKey[] = []
const problems: string[] = []
const frontmatter = /^---\n([\s\S]*?)\n---\n/.exec(markdown)
const prefix = /^prefix:\s*(\S+)\s*$/m.exec(frontmatter?.[1] ?? '')?.[1]
if (!frontmatter || !prefix) return { keys, problems }
const where = 'docs' + page + '.md'
const blocks = toBlocks(markdown.slice(frontmatter[0].length))
for (let i = 0; i < blocks.length; i++) {
const heading = blocks[i]
if (heading.kind !== 'heading' || heading.level < 2 || heading.level > 3) continue
let end = i + 1
while (end < blocks.length && blocks[end].kind !== 'heading') end++
const section = blocks.slice(i + 1, end)
const anchor = toAnchor(heading.text)
const first = section[0]
if (first?.kind !== 'paragraph') continue
const key = /^`([^`]+)`$/.exec(heading.text)?.[1]
if (key && first.text.startsWith('**Type:**')) {
const path = prefix + '.' + key
const typeLine = /^\*\*Type:\*\* (.+?)(?: · \*\*Default:\*\* `(.*)`)?$/.exec(first.text)
const type = typeLine?.[1].replace(/`/g, '')
if (!typeLine || !type || !isConfigType(type)) {
problems.push(`${where}: the Type line of \`${path}\` has an unknown type or does not match the contract: ${first.text}`)
continue
}
const entry: ConfigKey = { path, type, description: '', page, anchor }
if (typeLine[2] !== undefined) {
const parsed = parseLiteral(typeLine[2])
if (parsed.ok) entry.default = parsed.value
else problems.push(`${where}: the default of \`${path}\` is not JSON: ${typeLine[2]}`)
}
const description = section[1]
if (description?.kind === 'paragraph') entry.description = description.text
else problems.push(`${where}: \`${path}\` has no description paragraph after its Type line`)
const list = section[2]
if (description?.kind === 'paragraph' && list?.kind === 'list' && list.items.every(item => item.startsWith('`'))) {
entry.values = []
for (const item of list.items) {
const [, literal, text] = /^`([^`]*)`\s*(?:-\s*)?(.*)$/.exec(item) ?? []
const parsed = parseLiteral(literal ?? '')
if (parsed.ok) entry.values.push({ value: parsed.value, description: text ?? '' })
else problems.push(`${where}: an allowed value of \`${path}\` is not JSON: ${item}`)
}
}
keys.push(entry)
continue
}
const under = /^Under `([^`]+)`\./.exec(first.text)?.[1]
const table = section.find(block => block.kind === 'table')
if (under && table?.kind === 'table') {
if (under !== prefix && !under.startsWith(prefix + '.')) {
problems.push(`${where}: \`${under}\` in "${heading.text}" is not under the page prefix \`${prefix}\``)
continue
}
const [header, ...rows] = table.rows
const column = (name: string) => header.indexOf(name)
const columns = { option: column('Option'), type: column('Type'), default: column('Default'), description: column('Description') }
if (Object.values(columns).includes(-1)) {
problems.push(`${where}: the table in "${heading.text}" needs Option, Type, Default and Description columns`)
continue
}
for (const row of rows) {
const path = under + '.' + row[columns.option].replace(/`/g, '')
const type = row[columns.type].replace(/`/g, '')
const parsed = parseLiteral(row[columns.default].replace(/`/g, ''))
if (!isConfigType(type)) problems.push(`${where}: \`${path}\` has an unknown type: ${row[columns.type]}`)
else if (!parsed.ok) problems.push(`${where}: the default of \`${path}\` is not JSON: ${row[columns.default]}`)
else keys.push({ path, type, default: parsed.value, description: row[columns.description], page, anchor })
}
}
}
return { keys, problems }
}
/**
* Every node of a config file by dotted path, objects included, so that
* both a leaf and a group can be looked up.
*/
function flatten (config: Record<string, unknown>, prefix = ''): Map<string, unknown> {
const nodes = new Map<string, unknown>()
for (const [name, value] of Object.entries(config)) {
const path = prefix + name
nodes.set(path, value)
if (isObject(value)) for (const [child, childValue] of flatten(value, path + '.')) nodes.set(child, childValue)
}
return nodes
}
/**
* Compare the documented keys with the default config files, both ways.
* Returns the keys a config can set (group keys dropped, and a free-form
* object without a default on its page given the one from its file) and one
* line per problem; no problems means the pages and files agree.
*/
export function checkKeys (keys: ConfigKey[], files: DefaultsFile[]): { keys: ConfigKey[], problems: string[] } {
const problems: string[] = []
const where = (key: ConfigKey) => `docs${key.page}.md`
const json = (value: unknown) => JSON.stringify(value)
// Every config node, and the file it was first found in
const nodes = new Map<string, { value: unknown, file: string }>()
for (const file of files) {
for (const [path, value] of flatten(file.config)) {
const seen = nodes.get(path)
if (!seen) nodes.set(path, { value, file: file.name })
else if (!isObject(seen.value) && !isDeepStrictEqual(seen.value, value)) {
problems.push(`\`${path}\` is ${json(seen.value)} in ${seen.file} but ${json(value)} in ${file.name}`)
}
}
}
const documented = new Map<string, ConfigKey>()
for (const key of keys) {
const twin = documented.get(key.path)
if (twin) problems.push(`\`${key.path}\` is documented twice, in ${where(twin)} and ${where(key)}`)
else documented.set(key.path, key)
}
// An object key with keys documented under it is a group; one without is free-form
const isGroup = (key: ConfigKey) => key.type === 'object' && keys.some(other => other.path.startsWith(key.path + '.'))
const isFreeForm = (key: ConfigKey) => key.type === 'object' && !isGroup(key)
const fields: ConfigKey[] = []
for (const key of documented.values()) {
const node = nodes.get(key.path)
if (!node) {
problems.push(`\`${key.path}\` is documented in ${where(key)} but is in neither ${files.map(file => file.name).join(' nor ')}`)
continue
}
if (!TYPE_CHECKS[key.type](node.value)) {
problems.push(`\`${key.path}\` is documented as \`${key.type}\` in ${where(key)} but is ${json(node.value)} in ${node.file}`)
continue
}
if (isGroup(key)) continue
if (key.default === undefined) {
if (!isFreeForm(key)) problems.push(`\`${key.path}\` has no default in ${where(key)}`)
} else if (!isDeepStrictEqual(key.default, node.value)) {
problems.push(`\`${key.path}\` defaults to ${json(key.default)} in ${where(key)} but to ${json(node.value)} in ${node.file}`)
}
if (key.values && !key.values.some(allowed => isDeepStrictEqual(allowed.value, node.value))) {
problems.push(`the allowed values of \`${key.path}\` in ${where(key)} do not include its default, ${json(node.value)}`)
}
for (const allowed of key.values ?? []) {
if (!TYPE_CHECKS[key.type](allowed.value)) {
problems.push(`the allowed value ${json(allowed.value)} of \`${key.path}\` in ${where(key)} is not a \`${key.type}\``)
}
}
fields.push(key.default === undefined ? { ...key, default: node.value } : key)
}
// The other direction: every leaf in the files is documented itself, or sits inside a free-form object
const covered = (path: string) => {
if (documented.has(path)) return true
const parts = path.split('.')
for (let length = parts.length - 1; length > 0; length--) {
const ancestor = documented.get(parts.slice(0, length).join('.'))
if (ancestor && isFreeForm(ancestor)) return true
}
return false
}
for (const [path, node] of nodes) {
const isLeaf = !isObject(node.value) || Object.keys(node.value).length === 0
if (isLeaf && !covered(path)) problems.push(`\`${path}\` in ${node.file} is not documented on any page in docs/config`)
}
return { keys: fields, problems }
}
const DOCS_CONFIG_DIR = fileURLToPath(new URL('../config/', import.meta.url))
const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url))
/** The default config files, as repo paths. Both containers can share one config, so they are checked as one. */
const DEFAULTS_FILES = ['app/config.json', 'upload-app/config.json']
/**
* Read every page in docs/config and both default config files, and check
* them against each other. Returns `checkKeys`' keys and problems, with the
* pages' own format problems first.
*/
export function readConfigSchema (): { keys: ConfigKey[], problems: string[] } {
const keys: ConfigKey[] = []
const problems: string[] = []
for (const file of readdirSync(DOCS_CONFIG_DIR).filter(name => name.endsWith('.md')).sort()) {
const page = parsePage(readFileSync(join(DOCS_CONFIG_DIR, file), 'utf8'), '/config/' + basename(file, '.md'))
keys.push(...page.keys)
problems.push(...page.problems)
}
const files = DEFAULTS_FILES.map(name => ({ name, config: JSON.parse(readFileSync(join(REPO_ROOT, name), 'utf8')) }))
const checked = checkKeys(keys, files)
return { keys: checked.keys, problems: [...problems, ...checked.problems] }
}
/**
* Fails `vitepress build` when the config reference pages and the default
* config files disagree, so a mismatch never deploys. `vitepress dev` only
* warns, so a half-edited page doesn't stop the server.
*/
export function configSchemaPlugin (): Plugin {
let isBuild = false
return {
name: 'ipp-config-schema',
configResolved (config) {
isBuild = config.command === 'build'
},
buildStart () {
const { problems } = readConfigSchema()
if (problems.length === 0) return
const message = 'The config reference pages (docs/config) and the default config files disagree. ' +
'See "Config reference pages" in docs/README.md.\n' + problems.map(problem => ' - ' + problem).join('\n')
if (isBuild) this.error(message)
else this.warn(message)
}
}
}
+39 -4
View File
@@ -10,6 +10,7 @@ Read it before adding or moving a page.
- [Structure](#structure)
- [Where new content goes](#where-new-content-goes)
- [Page conventions](#page-conventions)
- [Config reference pages](#config-reference-pages)
- [The README](#the-readme)
## Working on the site
@@ -18,7 +19,7 @@ Read it before adding or moving a page.
cd docs
npm install
npm run dev # live preview
npm run build # fails on dead internal links; run it before pushing
npm run build # fails on dead links and config pages that disagree with config.json; run it before pushing
```
The navbar's star count is fetched from the GitHub API when the site builds (`fetchStars` in `.vitepress/config.ts`)
@@ -30,8 +31,9 @@ Static files (images, favicon) live in `public/` and are referenced by absolute
`public/CNAME` holds the custom domain; it is copied to the root of the build and must stay there.
Publishing is automatic. Any push to `main` that touches `docs/` runs the `docs.yaml` workflow, which builds the
site and deploys it to GitHub Pages at [docs.ipp.nz](https://docs.ipp.nz). A dead link fails the build, so the
workflow fails and the live site stays on the previous version. Run `npm run build` yourself before pushing rather
site and deploys it to GitHub Pages at [docs.ipp.nz](https://docs.ipp.nz). A dead link, or a config page that
disagrees with `config.json` ([Config reference pages](#config-reference-pages)), fails the build, so the workflow
fails and the live site stays on the previous version. Run `npm run build` yourself before pushing rather
than finding out from a red tick.
## Structure
@@ -77,9 +79,42 @@ started because it is what people read first, not because it is a tutorial. If e
- Code fences are tagged `yaml`, `json` or `bash`. Caddyfiles use a plain fence; there is no highlighter for them.
- Images are `<img src="/name.webp" width="…" height="…" alt="…">` with real dimensions so the page does not shift
while loading.
- Types and defaults come from `app/config.json` and the code. Check, don't guess.
- Types and defaults come from `app/config.json` and `upload-app/config.json`. The build checks them; see
[Config reference pages](#config-reference-pages).
- British English, hyphens rather than dashes, and "IPP" after the first "Immich Public Proxy" on a page.
## Config reference pages
The pages in `config/` are the only description of the config keys, so the build checks them against
`app/config.json` and `upload-app/config.json`, both ways (`.vitepress/configSchema.ts`). A disagreement fails
`npm run build`, and `npm run dev` prints it as a warning. `npm test` at the repo root runs the same check without
building the site (`tests/configSchema.test.ts`). The check fails when:
- a key in either file is not documented, or is documented twice;
- a documented key is in neither file;
- a documented type or default differs from the file, or the allowed values leave out the default;
- a key in both files has a different default in each.
For the same reason the docs workflow also runs on a change to either `config.json`: a key or default changed on
`main` redeploys the site, and the deploy fails if the page was not updated in the same push.
The check reads only this format:
- **Prefix.** A reference page names its dotted prefix in frontmatter: `prefix: ipp.gallery`. Pages without one are
not read, so a key documented on such a page counts as undocumented.
- **Key section.** A `##` or `###` heading that is one inline-code key, such as `` ## `showTitle` ``, whose first
paragraph is the Type line. The key's path is the prefix plus the heading. A heading followed by anything else is
prose: `## Example` and the upload page's `` ### `PUBLIC_BASE_URL` `` are skipped.
- **Type line.** `` **Type:** `bool` · **Default:** `false` ``, on its own. The type is `bool`, `int`, `string`,
`object`, `` `bool` or `string` ``, or `various` (any JSON value), and the default is JSON. Leave the default out
only on an object key: a group whose keys are documented on their own page (`gallery` on General options), or a
free-form object such as `responseHeaders`, whose default is taken from `config.json`.
- **Description.** The paragraph after the Type line. It is the key's summary, so it should make sense on its own.
- **Allowed values.** A bullet list directly after the description whose every item starts with an inline-code JSON
value: `` - `"original"` - the full-resolution original file ``. Any other list is prose.
- **Flag tables.** A section whose first paragraph starts ``Under `ipp.showMetadata.exif`.`` and that has a table
with `Option`, `Type`, `Default` and `Description` columns documents one key per row, as on the Metadata page.
## The README
`README.md` at the repo root is the front door, not a second copy of the site: pitch, demo, screenshot, quick start
+4
View File
@@ -1,3 +1,7 @@
---
prefix: ipp.gallery
---
# Gallery
Options that control how the gallery page is rendered. Configured under `ipp.gallery`.
+5 -1
View File
@@ -1,3 +1,7 @@
---
prefix: ipp
---
# General options
Top-level options under `ipp.*` that don't belong to the [Gallery](/config/gallery), [Lightbox](/config/lightbox) or [Metadata](/config/metadata) groups.
@@ -174,6 +178,6 @@ Description / EXIF / location reveal controls. See [Metadata](/config/metadata).
## `customInvalidResponse`
**Type:** various
**Type:** `various` · **Default:** `false`
Send a custom response instead of the default 404. See [Error responses](/config/error-responses).
+4
View File
@@ -1,3 +1,7 @@
---
prefix: ipp.lightbox
---
# Lightbox
The gallery's lightbox is powered by [PhotoSwipe](https://photoswipe.com/). Configured under `ipp.lightbox`.
+29 -25
View File
@@ -1,3 +1,7 @@
---
prefix: ipp.showMetadata
---
# Metadata
Configured under `ipp.showMetadata`. The lightbox includes a slide-in info sidebar (toggle with the **i** key or the info button in the toolbar) that surfaces whatever metadata you opt into here.
@@ -46,10 +50,10 @@ The info sidebar and its toolbar button only appear when at least one field is t
Under `ipp.showMetadata.description`.
| Option | Type | Description |
|-----------|--------|-------------------------------------------------------------|
| `caption` | `bool` | Show the description below the photo as a lightbox caption. |
| `sidebar` | `bool` | Show the description at the top of the info sidebar. |
| Option | Type | Default | Description |
|-----------|--------|---------|-------------------------------------------------------------|
| `caption` | `bool` | `false` | Show the description below the photo as a lightbox caption. |
| `sidebar` | `bool` | `false` | Show the description at the top of the info sidebar. |
Set both to show in both places; set neither and the description is not included at all.
@@ -57,29 +61,29 @@ Set both to show in both places; set neither and the description is not included
Under `ipp.showMetadata.exif`. Every flag defaults to `false`.
| Option | Type | Description |
|--------------------|--------|------------------------------------------------------------------------------------------------------------------|
| `dateTimeOriginal` | `bool` | Show the date the photo was taken (per EXIF), in the photographer's local time - matching Immich's own sidebar. |
| `timeZone` | `bool` | Show and use the photo's timezone when formatting the date. Only applies when `dateTimeOriginal` is also enabled. |
| `fileName` | `bool` | Show the original filename. |
| `dimensions` | `bool` | Show width x height and megapixel count. |
| `fileSize` | `bool` | Show the file size. |
| `make` | `bool` | Camera manufacturer (e.g. "Canon"). |
| `model` | `bool` | Camera model (e.g. "EOS R5"). |
| `lensModel` | `bool` | Lens model. |
| `exposureTime` | `bool` | Shutter speed (e.g. "1/200"). |
| `iso` | `bool` | ISO sensitivity. |
| `fNumber` | `bool` | Aperture f-number. |
| `focalLength` | `bool` | Focal length in millimetres. |
| Option | Type | Default | Description |
|--------------------|--------|---------|-------------------------------------------------------------------------------------------------------------------|
| `dateTimeOriginal` | `bool` | `false` | Show the date the photo was taken (per EXIF), in the photographer's local time - matching Immich's own sidebar. |
| `timeZone` | `bool` | `false` | Show and use the photo's timezone when formatting the date. Only applies when `dateTimeOriginal` is also enabled. |
| `fileName` | `bool` | `false` | Show the original filename. |
| `dimensions` | `bool` | `false` | Show width x height and megapixel count. |
| `fileSize` | `bool` | `false` | Show the file size. |
| `make` | `bool` | `false` | Camera manufacturer (e.g. "Canon"). |
| `model` | `bool` | `false` | Camera model (e.g. "EOS R5"). |
| `lensModel` | `bool` | `false` | Lens model. |
| `exposureTime` | `bool` | `false` | Shutter speed (e.g. "1/200"). |
| `iso` | `bool` | `false` | ISO sensitivity. |
| `fNumber` | `bool` | `false` | Aperture f-number. |
| `focalLength` | `bool` | `false` | Focal length in millimetres. |
## Location group
Under `ipp.showMetadata.location`. Every flag defaults to `false`, except `webLink` which defaults to `true`.
| Option | Type | Description |
|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `city` | `bool` | Show city. |
| `state` | `bool` | Show state / region. |
| `country` | `bool` | Show country. |
| `gps` | `bool` | Show GPS coordinates. |
| `webLink` | `bool` | Show an "Open in OpenStreetMap" link below the coordinates. The link does not pass the share URL on to the map provider. Has no effect unless `gps` is also `true`. Default `true`. |
| Option | Type | Default | Description |
|-----------|--------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `city` | `bool` | `false` | Show city. |
| `state` | `bool` | `false` | Show state / region. |
| `country` | `bool` | `false` | Show country. |
| `gps` | `bool` | `false` | Show GPS coordinates. |
| `webLink` | `bool` | `true` | Show an "Open in OpenStreetMap" link below the coordinates. The link does not pass the share URL on to the map provider. Has no effect unless `gps` is also `true`. |
+4
View File
@@ -1,3 +1,7 @@
---
prefix: ipp.upload
---
# Upload service
Settings for the optional upload service, the `immich-public-proxy-upload` container, which lets visitors send photos
+204
View File
@@ -0,0 +1,204 @@
import { describe, it, expect } from 'vitest'
import { checkKeys, parsePage, readConfigSchema, type ConfigKey, type ConfigType } from '../.vitepress/configSchema'
/*
The first test is the one that matters: the same check `vitepress build`
runs, against the real pages and config files. The rest pin the contract
in docs/README.md, "Config reference pages".
*/
describe('the config reference pages', () => {
it('match app/config.json and upload-app/config.json', () => {
expect(readConfigSchema().problems).toEqual([])
})
})
/** A reference page with the given prefix and body. */
function page (prefix: string, body: string): string {
return `---\nprefix: ${prefix}\n---\n\n# Page\n\n${body}`
}
describe('parsePage', () => {
it('reads a key section: type, default, description and allowed values', () => {
const { keys, problems } = parsePage(page('ipp', [
'## `quality`',
'',
'**Type:** `string` · **Default:** `"preview"`',
'',
'Highest quality',
'served.',
'',
'- `"preview"` - the preview (default).',
'- `"original"` - the original',
' file.',
'',
'More prose.'
].join('\n')), '/config/test')
expect(problems).toEqual([])
expect(keys).toEqual([{
path: 'ipp.quality',
type: 'string',
default: 'preview',
description: 'Highest quality served.',
values: [
{ value: 'preview', description: 'the preview (default).' },
{ value: 'original', description: 'the original file.' }
],
page: '/config/test',
anchor: 'quality'
}])
})
it('treats a heading without a Type line as prose', () => {
const { keys } = parsePage(page('ipp', [
'## Example',
'',
'Some text.',
'',
'### `PUBLIC_BASE_URL`',
'',
'**Optional**',
'',
'```md',
'## `inFence`',
'',
'**Type:** `bool` · **Default:** `false`',
'```'
].join('\n')), '/config/test')
expect(keys).toEqual([])
})
it('reads nothing from a page without a prefix', () => {
const markdown = '# Page\n\n## `key`\n\n**Type:** `bool` · **Default:** `false`\n\nText.\n'
expect(parsePage(markdown, '/config/test')).toEqual({ keys: [], problems: [] })
})
it('treats a list as prose unless every item starts with an inline-code value', () => {
const { keys } = parsePage(page('ipp', [
'## `uploadUrl`',
'',
'**Type:** `string` · **Default:** `"/upload"`',
'',
'Where the service is.',
'',
'- **A path** means the same hostname.',
'- `""` never shows the button.'
].join('\n')), '/config/test')
expect(keys[0].values).toBeUndefined()
})
it('reports an allowed value that is not JSON, and an unknown type', () => {
const { problems } = parsePage(page('ipp', [
'## `quality`',
'',
'**Type:** `string` · **Default:** `"preview"`',
'',
'Highest quality.',
'',
'- `preview` - unquoted.',
'',
'## `count`',
'',
'**Type:** `number` · **Default:** `1`',
'',
'How many.'
].join('\n')), '/config/test')
expect(problems).toHaveLength(2)
expect(problems[0]).toContain('an allowed value of `ipp.quality` is not JSON')
expect(problems[1]).toContain('the Type line of `ipp.count`')
})
it('reads one key per row of a flag table', () => {
const { keys, problems } = parsePage(page('ipp.showMetadata', [
'## EXIF group',
'',
'Under `ipp.showMetadata.exif`. Every flag defaults to `false`.',
'',
'| Option | Type | Default | Description |',
'|--------|--------|---------|-----------------|',
'| `make` | `bool` | `false` | Camera make. |',
'| `iso` | `bool` | `true` | ISO sensitivity. |'
].join('\n')), '/config/metadata')
expect(problems).toEqual([])
expect(keys.map(key => [key.path, key.default, key.anchor])).toEqual([
['ipp.showMetadata.exif.make', false, 'exif-group'],
['ipp.showMetadata.exif.iso', true, 'exif-group']
])
})
})
/** A documented key with the parts `checkKeys` looks at. */
function key (path: string, type: ConfigType, extra: Partial<ConfigKey> = {}): ConfigKey {
return { path, type, description: 'Text.', page: '/config/test', anchor: 'anchor', ...extra }
}
const APP = 'app/config.json'
const UPLOAD = 'upload-app/config.json'
describe('checkKeys', () => {
it('passes when every key is documented with its default, both ways', () => {
const { problems } = checkKeys(
[key('ipp.showTitle', 'bool', { default: true }), key('ipp.upload.maxFileSize', 'int', { default: 500 })],
[{ name: APP, config: { ipp: { showTitle: true } } }, { name: UPLOAD, config: { ipp: { upload: { maxFileSize: 500 } } } }]
)
expect(problems).toEqual([])
})
it('reports a key in a file that no page documents', () => {
const { problems } = checkKeys([], [{ name: APP, config: { ipp: { showTitle: true } } }])
expect(problems).toEqual(['`ipp.showTitle` in app/config.json is not documented on any page in docs/config'])
})
it('reports a documented key that is in neither file', () => {
const { problems } = checkKeys([key('ipp.gone', 'bool', { default: false })], [{ name: APP, config: {} }])
expect(problems).toEqual(['`ipp.gone` is documented in docs/config/test.md but is in neither app/config.json'])
})
it('reports a default, type or allowed values that disagree with the file', () => {
const { problems } = checkKeys([
key('ipp.cacheTime', 'int', { default: 600 }),
key('ipp.uploadUrl', 'bool', { default: false }),
key('ipp.quality', 'string', { default: 'original', values: [{ value: 'preview', description: '' }] })
], [{ name: APP, config: { ipp: { cacheTime: 300, uploadUrl: '/upload', quality: 'original' } } }])
expect(problems).toEqual([
'`ipp.cacheTime` defaults to 600 in docs/config/test.md but to 300 in app/config.json',
'`ipp.uploadUrl` is documented as `bool` in docs/config/test.md but is "/upload" in app/config.json',
'the allowed values of `ipp.quality` in docs/config/test.md do not include its default, "original"'
])
})
it('reports a key documented twice', () => {
const twice = key('ipp.allowSlugLinks', 'bool', { default: true })
const { problems } = checkKeys([twice, twice], [{ name: APP, config: { ipp: { allowSlugLinks: true } } }])
expect(problems).toEqual(['`ipp.allowSlugLinks` is documented twice, in docs/config/test.md and docs/config/test.md'])
})
it('reports a key shared by both files with a different default in each', () => {
const { problems } = checkKeys(
[key('ipp.allowSlugLinks', 'bool', { default: true })],
[{ name: APP, config: { ipp: { allowSlugLinks: true } } }, { name: UPLOAD, config: { ipp: { allowSlugLinks: false } } }]
)
expect(problems).toEqual(['`ipp.allowSlugLinks` is true in app/config.json but false in upload-app/config.json'])
})
it('takes a free-form object\'s default from the file and leaves its children undocumented', () => {
const headers = { 'Cache-Control': 'no-store' }
const { keys, problems } = checkKeys([key('ipp.responseHeaders', 'object')], [{ name: APP, config: { ipp: { responseHeaders: headers } } }])
expect(problems).toEqual([])
expect(keys[0].default).toEqual(headers)
})
it('treats an object key with keys documented under it as a group, left out of the keys', () => {
const { keys, problems } = checkKeys(
[key('ipp.gallery', 'object'), key('ipp.gallery.showTitle', 'bool', { default: true })],
[{ name: APP, config: { ipp: { gallery: { showTitle: true, singleImage: false } } } }]
)
expect(problems).toEqual(['`ipp.gallery.singleImage` in app/config.json is not documented on any page in docs/config'])
expect(keys.map(field => field.path)).toEqual(['ipp.gallery.showTitle'])
})
it('reports a missing default on anything but an object key', () => {
const { problems } = checkKeys([key('ipp.showTitle', 'bool')], [{ name: APP, config: { ipp: { showTitle: true } } }])
expect(problems).toEqual(['`ipp.showTitle` has no default in docs/config/test.md'])
})
})