Extract @ipp/core npm workspace package

This commit is contained in:
Alan Grainger
2026-10-05 15:55:18 +13:00
parent 54c0f91c4e
commit d03a77f691
65 changed files with 1056 additions and 746 deletions
+55 -33
View File
@@ -19,33 +19,50 @@ Immich Public Proxy (IPP) exists to share Immich photos publicly without exposin
Request flow for a typical share URL like `https://proxy.example.com/share/<key>`:
1. Express routes in `app/src/index.ts` receive the request.
2. `app/src/immich.ts` fetches the share metadata from Immich over the local network, validates it, and returns the asset list.
2. `app/src/immich.ts` fetches the share metadata from Immich over the local network (through `fetchSharedLink` in `@ipp/core`), validates it, and returns the asset list.
3. For a gallery, `app/src/gallery/builder.ts` builds the view-model and `app/src/view/gallery.tsx` renders it server-side with Preact. The page embeds a JSON init block consumed by the client.
4. The client gallery lives in `app/src/client/` (TypeScript ES modules, compiled file-for-file by `tsc` into `app/public/js/`). It wires PhotoSwipe v5 with a virtualized justified-rows layout. There is no client-side framework hydration.
5. For individual assets (image, video, thumbnail, download, zip), Express streams bytes from Immich back to the client without touching disk via `app/src/stream/`.
### 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.
```
.github/workflows/ CI: builds and pushes Docker image on v* tags
package.json Workspace root: scripts that delegate to the workspaces; no dependencies
package-lock.json The one lockfile for every workspace
.eslintrc Lint config for both workspaces
shared/ @ipp/core - read-side only, knows nothing about galleries
src/
index.ts Barrel: everything the apps import comes from '@ipp/core'
types.ts Share-level types (SharedLink, Asset, KeyType, ...)
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
config/loader.ts loadConfig() reads env / file; the app passes its default path and migrations
config/access.ts getConfigOption() reads the loaded config
http.ts Operator-configured response headers, asyncHandler, errorHandler
invalidRequest.ts The 404 policy, with setInvalidRequestHandler for the app's own handler file
session.ts Cookie session, decodeCookie, unlock handler, invalid-password response
encrypt.ts Cookie-session encryption for password-protected shares
utils/ log, sanitize (filenames), text (escaping), ttlLruCache, webStream
view/ Page renderer, theme script, password page
tests/ Vitest unit tests for core
app/
config.json Runtime configuration, overrideable via volume or inline
package.json Node project manifest
tsconfig.json Server TypeScript config (compiles src/ to dist/)
package.json IPP's manifest; its version is the release version
tsconfig.json Server TypeScript config (compiles src/ to dist/; references shared/)
tsconfig.client.json Client TypeScript config (compiles src/client/ + src/shared/ to public/js/)
vitest.config.ts Unit-test runner config
vitest.config.ts Unit-test runner config; aliases @ipp/core to its source
src/
index.ts Express setup and routes
immich.ts Upstream Immich API calls, share + token caches
encrypt.ts Cookie-session encryption for password-protected shares
invalidRequestHandler.ts Centralised 404 / custom-response handling
http.ts Operator-configured HTTP response headers
share.ts Share-level info + policy (title, canDownload)
types.ts Server-only TypeScript types
immich.ts Share lookup with album enumeration and cache, asset detail, IPP URLs
invalidRequestHandler.ts IPP's 404 handler; operators may replace the compiled file by a mount
share.ts Share-level policy (canDownload, expiry date, motion photos)
types.ts Gallery-only server types
version.ts Release version and the static-asset cache-busting segment
config/
loader.ts loadConfig() reads env / file, applies migrations
migrations.ts Backward-compat shims for legacy config-key shapes
access.ts getConfigOption() reads the loaded config
gallery/
builder.ts Gallery view-model construction
exif.ts EXIF / location whitelisting for the sidebar
@@ -53,23 +70,21 @@ app/
stream/
asset.ts Single-asset stream (image / video / thumbnail)
download.ts Zip pipeline (concurrency-bounded, retry, abort)
utils/
log.ts Timestamped log.info / log.warn / log.error
sanitize.ts Filename-character sanitization
text.ts escapeHtml + toString narrowing
view/ Preact SSR templates (.tsx)
view/ Gallery and home page Preact SSR templates (.tsx)
shared/types.ts Types shared between server SSR and client (GalleryItem, etc.)
client/ Client gallery, virtualisation, lightbox, sidebar
public/ Static assets served as-is
photoswipe/ Vendored PhotoSwipe v5
thumbhash/, fonts/, images/
style.css, photoswipe-overrides.css
tests/ Vitest unit tests for pure functions
tests/ Vitest unit tests for IPP
docs/ User docs site (VitePress); docs/README.md explains its structure
Dockerfile Multi-stage build, runs 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
```
**What goes in `@ipp/core`.** A module belongs in core when it is about Immich shares, HTTP plumbing, config, sessions, utilities or page rendering, and does not know what a gallery is. Core is read-side only: its one POST to Immich is the shared-link password login. The browser client shares no code with core; `app/src/shared/` is the separate server-and-client type folder.
The server tsconfig excludes `src/client/`; the client tsconfig only includes `src/client/` and `src/shared/`. Compiled client output (`app/public/js/`) is gitignored.
## Tech stack
@@ -92,9 +107,8 @@ The server tsconfig excludes `src/client/`; the client tsconfig only includes `s
## Development setup
```bash
cd app
npm install
npm run dev
npm install # at the repo root, for every workspace
npm run dev # builds @ipp/core once, then watches core, server and client
```
Required environment variables (set in `app/.env` or your shell):
@@ -110,17 +124,25 @@ Configuration overrides go in `app/config.json` or inline via env (see `docs/con
## Build, lint, test
At the repo root:
```bash
npm run build # both server and client tsc; output to dist/ and public/js/
npm run build:server # server only
npm run build:client # client only
npm test # vitest run (unit tests on pure functions)
npm run test:watch # vitest in watch mode
npm run test:container # build a podman image and run it locally
npx eslint src/ # lint
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 run lint # ESLint over both workspaces
npm run bump -- 4.0.1 # set the version in every workspace manifest and the lockfile
```
`npm test` runs the pure-function unit tests in `app/tests/`. Today the suite covers `escapeHtml` only; the other shipped pure-function areas (filename derivation, layout math, EXIF whitelisting) deserve coverage too. Add tests as you touch those areas, and for any new pure logic you introduce. Skip HTTP plumbing.
In `app/`:
```bash
npm run build:server # core and IPP's server only
npm run build:client # client only
npm run test:watch # vitest in watch mode
npm run test:container # build a podman image and run it locally
```
`npm test` runs the pure-function unit tests in `shared/tests/` and `app/tests/`. IPP's tests import `@ipp/core` from its source, so they need no build. Today the suite covers `escapeHtml` only; the other shipped pure-function areas (filename derivation, layout math, EXIF whitelisting) deserve coverage too. Add tests as you touch those areas, and for any new pure logic you introduce. Skip HTTP plumbing.
Beyond unit tests, exercise the gallery end-to-end against a real Immich instance: happy path plus failure paths (expired share, trashed asset, password protection, very large albums, video range requests).
@@ -128,9 +150,9 @@ Beyond unit tests, exercise the gallery end-to-end against a real Immich instanc
**Configuration.** New options go in `app/config.json` under the appropriate `ipp.*` namespace, read via `getConfigOption`, and documented on the page for their group under `docs/config/` (see `docs/README.md` for the conventions). Prefer a group toggle plus per-field overrides over a single flat boolean when several related toggles cluster, following the `ipp.showMetadata` pattern. Existing keys keep working; if you rename one, add a backward-compat shim with a startup deprecation warning, as was done for the v2.0 gallery key rename.
**Privacy of responses.** Always return 404 for invalid or upstream-failed requests. Use `invalidRequestHandler` rather than crafting ad-hoc error responses. Do not surface Immich status codes or error bodies to the client.
**Privacy of responses.** Always return 404 for invalid or upstream-failed requests. Use `respondToInvalidRequest` from `@ipp/core` rather than crafting ad-hoc error responses; it calls IPP's `invalidRequestHandler`, which index.ts registers at startup. Do not surface Immich status codes or error bodies to the client.
**Escaping.** Any string that originates from Immich and is embedded into HTML by the SSR templates must be escaped (use `escapeHtml` from `utils/text.ts`). Strings that cross to the client via the init JSON block stay as plain text and are rendered with `textContent`, not `innerHTML` - that retired the "pre-escaped HTML over the wire" contract that the early gallery shipped with.
**Escaping.** Any string that originates from Immich and is embedded into HTML by the SSR templates must be escaped (use `escapeHtml` from `@ipp/core`). Strings that cross to the client via the init JSON block stay as plain text and are rendered with `textContent`, not `innerHTML` - that retired the "pre-escaped HTML over the wire" contract that the early gallery shipped with.
**Third-party links.** Any anchor the client renders that points to a third-party origin (the "Open in OpenStreetMap" link is the current example) must set `rel="noopener noreferrer"`. The `noreferrer` part is the load-bearing one: without it, the browser sends the share URL as the `Referer` header, and the share URL *is* the capability token for the album - it ends up in the third party's webserver logs. `noopener` prevents the new tab from touching `window.opener`. Embedding a third-party widget (map tile, oEmbed, etc.) instead of a click-through link reintroduces the same leak silently on every render - that's a design decision that needs more than a code change.
@@ -140,7 +162,7 @@ Beyond unit tests, exercise the gallery end-to-end against a real Immich instanc
**File organisation.** Group functions by cohesion, not by file count. A file deserves its own name when it carries a coherent concept worth a separate filename - "filename sanitization" or "config loader" pass; "narrow unknown to string" does not. When several small helpers share a theme, group them in one file (`utils/text.ts` for escaping + narrowing; `share.ts` for share-level info + policy). When a single concern is substantial enough to dominate a file on its own, give it its own name (`config/migrations.ts`, `stream/download.ts`). IPP optimises for audit reading rather than tree-shakeable reuse, so fewer cohesive files beat many one-export micro-modules. Same lens applies on the client (`app/src/client/`): each module is a viewport-of-code that earns its name.
Where to put a new function: ask what category of thing it is, not where it gets called from. Share-level policy decisions and share-derived info go in `share.ts`. Per-asset view-model transforms (filename derivation, EXIF whitelisting) go alongside `gallery/builder.ts`. HTTP response setup driven by operator config goes in `http.ts`. Streaming pipelines go in `stream/`. If a new function doesn't fit any existing category, prefer adding to the closest existing file over creating a new single-function module - revisit when a real second member of the category appears.
Where to put a new function: ask what category of thing it is, not where it gets called from. Share-level policy decisions and share-derived info go in `share.ts`. Per-asset view-model transforms (filename derivation, EXIF whitelisting) go alongside `gallery/builder.ts`. HTTP response setup driven by operator config goes in core's `http.ts`. Streaming pipelines go in `stream/`. If a new function doesn't fit any existing category, prefer adding to the closest existing file over creating a new single-function module - revisit when a real second member of the category appears.
**No client framework, no bundler.** The client is TypeScript compiled file-for-file by `tsc` into plain ES modules served by Express static. Do not introduce a frontend framework (React / Svelte / Vue / Solid) or a bundler (Webpack / Rollup / Vite / Parcel). PhotoSwipe is loaded as ESM directly. Inter-module imports inside `app/src/client/` use `.js` extensions in the source: with no bundler, the browser fetches the compiled `.js` files directly, so the extension has to be present in the import path at runtime. `moduleResolution: bundler` is permissive about extensions in TypeScript-land; the constraint comes from the browser, not the TS config.