Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

refactor: complete P1 package decoupling for self-hosted

HoshinoSuzumiBot9c3fda1af3fa
diff --git a/.dockerignore b/.dockerignore
index 86f3a0c5..f1326253 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -23,6 +23,9 @@ pnpm-debug.log*
.env.test
.env.production
+# 构建产物
+.output
+
# 缓存目录
.cache
.temp
diff --git a/Dockerfile b/Dockerfile
index bc8cc8e3..d63de48f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -8,13 +8,15 @@ WORKDIR /usr/src/app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY packages/webgl-image/package.json ./packages/webgl-image/
COPY packages/contracts/package.json ./packages/contracts/
+COPY packages/storage/package.json ./packages/storage/
+COPY packages/media/package.json ./packages/media/
+COPY packages/geocoding/package.json ./packages/geocoding/
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
FROM base AS build
WORKDIR /usr/src/app
COPY --from=deps /usr/src/app/node_modules ./node_modules
-COPY --from=deps /usr/src/app/packages/webgl-image/node_modules ./packages/webgl-image/node_modules
-COPY --from=deps /usr/src/app/packages/contracts/node_modules ./packages/contracts/node_modules
+COPY --from=deps /usr/src/app/packages ./packages
COPY . .
RUN pnpm exec nuxt prepare
RUN NODE_OPTIONS="--max-old-space-size=4096" pnpm run build:deps
diff --git a/app/components/album/Listing.vue b/app/components/album/Listing.vue
index e0cabf41..54720859 100644
--- a/app/components/album/Listing.vue
+++ b/app/components/album/Listing.vue
@@ -2,10 +2,9 @@
import { motion } from 'motion-v'
import { getAlbumListState } from '~/utils/albumListState'
import { sampleWaterfallPhotos } from '~/utils/sampleWaterfallPhotos'
-import type { Album } from '~~/server/utils/db'
+import type { Album } from '@chronoframe/contracts/resources'
interface AlbumWithPhotos extends Album {
photoIds?: string[]
- hasPassword?: boolean
}
const appSlogan = useSettingRef('app:slogan')
const { homeView, photoWallPath } = useHomeView()
diff --git a/app/pages/dashboard/albums.vue b/app/pages/dashboard/albums.vue
index 2706c05b..306fcfeb 100644
--- a/app/pages/dashboard/albums.vue
+++ b/app/pages/dashboard/albums.vue
@@ -1,5 +1,5 @@
<script lang="ts" setup>
-import type { Album, Photo } from '~~/server/utils/db'
+import type { Album, Photo } from '@chronoframe/contracts/resources'
import type { FormSubmitEvent, FormError } from '@nuxt/ui'
import {
ALBUM_PASSWORD_MAX_LENGTH,
@@ -16,7 +16,6 @@ useHead({
})
interface AlbumItem extends Album {
- hasPassword?: boolean
photoCount?: number
photoIds?: string[]
coverPhoto?: Photo | null
diff --git a/app/pages/dashboard/photos.vue b/app/pages/dashboard/photos.vue
index d9c4517c..5dfafbdc 100644
--- a/app/pages/dashboard/photos.vue
+++ b/app/pages/dashboard/photos.vue
@@ -1,6 +1,6 @@
<script lang="ts" setup>
import type { FormSubmitEvent, TableColumn } from '@nuxt/ui'
-import type { Album, Photo } from '~~/server/utils/db'
+import type { Album, Photo } from '@chronoframe/contracts/resources'
import type { UploadingFile } from '~~/shared/types/uploading-file'
import { QueueWarningCode } from '~~/shared/utils/queue-warning'
import {
diff --git a/app/stores/settings.ts b/app/stores/settings.ts
index 9462c676..94dfcb92 100644
--- a/app/stores/settings.ts
+++ b/app/stores/settings.ts
@@ -1,6 +1,9 @@
import { defineStore } from 'pinia'
-type SettingValue = string | number | boolean | null | Record<string, any>
+import type {
+ SettingValue,
+ PublicSettingsResponse,
+} from '@chronoframe/contracts/settings'
interface SettingsState {
data: Record<string, Record<string, SettingValue>>
@@ -58,10 +61,9 @@ export const useSettingsStore = defineStore('settings', {
this.error = null
try {
- const response = await $fetch<{
- timestamp: number
- data: Record<string, Record<string, SettingValue>>
- }>('/api/system/settings/all')
+ const response = await $fetch<PublicSettingsResponse>(
+ '/api/system/settings/all',
+ )
this.data = response.data
this.isInitialized = true
@@ -113,10 +115,9 @@ export const useSettingsStore = defineStore('settings', {
this.error = null
try {
- const response = await $fetch<{
- timestamp: number
- data: Record<string, Record<string, SettingValue>>
- }>('/api/system/settings/all')
+ const response = await $fetch<PublicSettingsResponse>(
+ '/api/system/settings/all',
+ )
this.data = response.data
this.isInitialized = true
diff --git a/app/stores/viewer.ts b/app/stores/viewer.ts
index 649914dd..55dd019f 100644
--- a/app/stores/viewer.ts
+++ b/app/stores/viewer.ts
@@ -1,4 +1,4 @@
-import type { Photo } from '~~/server/utils/db'
+import type { Photo } from '@chronoframe/contracts/resources'
export const useViewerState = defineStore('photo-viewer-state', () => {
const currentPhotoIndex = ref(0)
diff --git a/package.json b/package.json
index 006a33e9..4a13abad 100644
--- a/package.json
+++ b/package.json
@@ -32,7 +32,9 @@
"postinstall": "nuxt prepare",
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
- "docs:preview": "vitepress preview docs"
+ "docs:preview": "vitepress preview docs",
+ "check:packages": "node scripts/check-package-boundaries.mjs && pnpm --filter @chronoframe/contracts --filter @chronoframe/storage --filter @chronoframe/media --filter @chronoframe/geocoding type-check",
+ "test": "node --experimental-strip-types --test tests/*.test.ts"
},
"dependencies": {
"@aws-sdk/client-s3": "^3.1149.0",
@@ -81,7 +83,10 @@
"vue": "^3.5.43",
"vue-router": "^4.6.4",
"wait-on": "^9.5.1",
- "zod": "^4.6.6"
+ "zod": "^4.6.6",
+ "@chronoframe/storage": "workspace:*",
+ "@chronoframe/media": "workspace:*",
+ "@chronoframe/geocoding": "workspace:*"
},
"packageManager": "[email protected]",
"devDependencies": {
diff --git a/packages/contracts/README.md b/packages/contracts/README.md
index 58e47120..36bcf69c 100644
--- a/packages/contracts/README.md
+++ b/packages/contracts/README.md
@@ -15,3 +15,12 @@ It requires no separate build step. Check it independently with
Do not add database models, application aliases, Nuxt auto-imports, Node globals,
or process-wide services here. Storage configuration contains credentials and is
not a public API response; existing server-side redaction remains required.
+
+Resource, settings, location and EXIF contracts are exported through their named
+subpaths. Resource response dates are ISO strings. Photo storage keys may be
+omitted from protected responses. UserSummary never includes password material;
+Album exposes hasPassword, never passwordHash. The server maps database rows at
+API boundaries and keeps persistence-only types under server/types.
+
+Settings field descriptors retain existing default/optional semantics. Storage
+configuration responses are authenticated management data, not public site DTOs.
diff --git a/packages/contracts/package.json b/packages/contracts/package.json
index afa65464..5f268d5b 100644
--- a/packages/contracts/package.json
+++ b/packages/contracts/package.json
@@ -6,7 +6,11 @@
"exports": {
".": "./src/index.ts",
"./storage": "./src/storage.ts",
- "./upload": "./src/upload.ts"
+ "./upload": "./src/upload.ts",
+ "./photo": "./src/photo.ts",
+ "./location": "./src/location.ts",
+ "./resources": "./src/resources.ts",
+ "./settings": "./src/settings.ts"
},
"scripts": {
"type-check": "tsc --noEmit"
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 27c9e38d..cceac9cf 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -1,2 +1,6 @@
export * from './storage.ts'
export * from './upload.ts'
+export * from './photo.ts'
+export * from './location.ts'
+export * from './resources.ts'
+export * from './settings.ts'
diff --git a/packages/contracts/src/location.ts b/packages/contracts/src/location.ts
new file mode 100644
index 00000000..5343f5b2
--- /dev/null
+++ b/packages/contracts/src/location.ts
@@ -0,0 +1,38 @@
+export const locationLevels = [
+ 'country',
+ 'region',
+ 'subregion',
+ 'city',
+ 'district',
+ 'locality',
+ 'neighborhood',
+] as const
+
+export type LocationLevel = (typeof locationLevels)[number]
+
+export interface LocationComponent {
+ name: string
+ sourceField: string
+}
+
+export interface NormalizedLocation {
+ version: 1
+ provider: 'mapbox' | 'nominatim'
+ language: string
+ countryCode?: string
+ components: Partial<Record<LocationLevel, LocationComponent>>
+ formattedAddress?: string
+}
+
+export function hasValidCoordinates(lat: unknown, lon: unknown): boolean {
+ return (
+ typeof lat === 'number' &&
+ Number.isFinite(lat) &&
+ Math.abs(lat) <= 90 &&
+ typeof lon === 'number' &&
+ Number.isFinite(lon) &&
+ Math.abs(lon) <= 180 &&
+ // Exact (0, 0) is treated as a missing-GPS placeholder.
+ !(lat === 0 && lon === 0)
+ )
+}
diff --git a/packages/contracts/src/photo.ts b/packages/contracts/src/photo.ts
new file mode 100644
index 00000000..3f1973f9
--- /dev/null
+++ b/packages/contracts/src/photo.ts
@@ -0,0 +1,101 @@
+export interface NeededExif {
+ Title?: string
+ XPTitle?: string
+ Subject?: string[]
+ Keywords?: string[]
+ XPKeywords?: string
+
+ Description?: string | undefined
+ ImageDescription?: string | undefined
+ CaptionAbstract?: string | undefined
+ XPComment?: string | undefined
+ UserComment?: string | undefined
+
+ zone?: string
+ tz?: string
+ tzSource?: string
+
+ Orientation?: number
+ Make?: string
+ Model?: string
+ Software?: string
+ Artist?: string
+ Copyright?: string
+
+ ExposureTime?: string | number
+ FNumber?: number
+ ExposureProgram?: string
+ ISO?: number
+ ShutterSpeedValue?: string | number
+ ApertureValue?: number
+ BrightnessValue?: number
+ ExposureCompensation?: number
+ MaxApertureValue?: number
+
+ OffsetTime?: string
+ OffsetTimeOriginal?: string
+ OffsetTimeDigitized?: string
+
+ LightSource?: string
+ Flash?: string
+
+ FocalLength?: string
+ FocalLengthIn35mmFormat?: string
+
+ LensMake?: string
+ LensModel?: string
+
+ ColorSpace?: string
+
+ ExposureMode?: string
+ SceneCaptureType?: string
+
+ Aperture?: number
+ ScaleFactor35efl?: number
+ ShutterSpeed?: string | number
+ LightValue?: number
+
+ DateTimeOriginal?: string
+ DateTimeDigitized?: string
+
+ ImageWidth?: number
+ ImageHeight?: number
+
+ MeteringMode: string | number | undefined
+ WhiteBalance: string | number | undefined
+ WBShiftAB: number | undefined
+ WBShiftGM: number | undefined
+ WhiteBalanceBias: number | undefined
+ WhiteBalanceFineTune: unknown
+ FlashMeteringMode: string | undefined
+ SensingMethod: string | undefined
+ FocalPlaneXResolution: number | undefined
+ FocalPlaneYResolution: number | undefined
+ GPSAltitude: number | undefined
+ GPSLatitude: string | number | undefined
+ GPSLongitude: string | number | undefined
+ GPSAltitudeRef: number | undefined
+ GPSLatitudeRef: string | undefined
+ GPSLongitudeRef: string | undefined
+
+ // HDR Type
+ MPImageType?: string | undefined
+
+ Rating?: number
+
+ // Motion Photo (XMP) related fields
+ MotionPhoto?: number | undefined
+ MotionPhotoVersion?: number | undefined
+ MotionPhotoPresentationTimestampUs?: number | undefined
+ MicroVideo?: number | undefined
+ MicroVideoVersion?: number | undefined
+ MicroVideoOffset?: number | undefined
+ MicroVideoPresentationTimestampUs?: number | undefined
+}
+
+export interface PhotoInfo {
+ title: string
+ dateTaken: string
+ tags: string[]
+ description: string
+}
diff --git a/packages/contracts/src/resources.ts b/packages/contracts/src/resources.ts
new file mode 100644
index 00000000..84b48fc1
--- /dev/null
+++ b/packages/contracts/src/resources.ts
@@ -0,0 +1,64 @@
+import type { NeededExif } from './photo.ts'
+import type { NormalizedLocation } from './location.ts'
+
+/** JSON response contract; dates are serialized strings. */
+export interface Photo {
+ id: string
+ title: string | null
+ description: string | null
+ width: number | null
+ height: number | null
+ aspectRatio: number | null
+ dateTaken: string | null
+ storageKey?: string | null
+ thumbnailKey?: string | null
+ fileSize: number | null
+ lastModified: string | null
+ originalUrl: string | null
+ thumbnailUrl: string | null
+ thumbnailHash: string | null
+ tags: string[] | null
+ exif: NeededExif | null
+ latitude: number | null
+ longitude: number | null
+ country: string | null
+ city: string | null
+ locationName: string | null
+ geocoding: NormalizedLocation | null
+ isLivePhoto: number
+ livePhotoVideoUrl: string | null
+ livePhotoVideoKey?: string | null
+ fileName?: string | null
+}
+
+export interface Album {
+ id: number
+ title: string
+ description: string | null
+ coverPhotoId: string | null
+ isHidden: boolean
+ position: number
+ createdAt: string
+ updatedAt: string
+ hasPassword: boolean
+}
+
+export interface UserSummary {
+ id: number
+ username: string
+ email: string
+ avatar: string | null
+ createdAt: string
+ isAdmin: number
+}
+
+export interface ListResponse<T> {
+ items: T[]
+ total: number
+}
+
+export interface ApiError {
+ statusCode: number
+ statusMessage?: string
+ message?: string
+}
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
new file mode 100644
index 00000000..b2643459
--- /dev/null
+++ b/packages/contracts/src/settings.ts
@@ -0,0 +1,135 @@
+import type { StorageConfig } from './storage.ts'
+
+export type SettingType = 'string' | 'number' | 'boolean' | 'json'
+export type SettingValue =
+ | string
+ | number
+ | boolean
+ | Record<string, any>
+ | null
+
+export interface SettingConfig {
+ namespace?: string
+ key: string
+ type: SettingType
+ value?: SettingValue
+ defaultValue: SettingValue
+ label?: string | null
+ description?: string | null
+ isPublic?: boolean
+ isReadonly?: boolean
+ isSecret?: boolean
+ enum?: ReadonlyArray<string>
+ hidden?: boolean
+}
+
+/** Authenticated management response; not public site configuration. */
+export interface SettingStorageProvider {
+ id: number
+ name: string
+ provider: StorageConfig['provider']
+ config: StorageConfig
+ createdAt: string
+ updatedAt: string
+}
+
+export interface StorageProviderInput {
+ name: string
+ provider: StorageConfig['provider']
+ config: StorageConfig
+}
+
+/**
+ * UI 字段类型枚举
+ * 定义在 shared 中以便前端使用
+ */
+export type FieldUIType =
+ | 'input' // 文本输入
+ | 'password' // 密码输入
+ | 'url' // URL 输入
+ | 'textarea' // 文本域
+ | 'select' // 下拉选择
+ | 'radio' // 单选按钮
+ | 'tabs' // 标签页选择
+ | 'toggle' // 开关
+ | 'number' // 数字输入
+ | 'avatar' // 头像上传/外链
+ | 'custom' // 自定义组件
+
+/**
+ * 字段 UI 配置
+ * 定义前端如何展示和交互一个设置字段
+ */
+export interface FieldUIConfig {
+ // 基础 UI 类型
+ type: FieldUIType
+
+ // 输入相关
+ placeholder?: string
+ help?: string
+
+ // 条件展示 - 根据其他字段的值来决定是否显示这个字段
+ visibleIf?: {
+ fieldKey: string
+ value: SettingValue
+ }
+
+ // 可选项(用于 select/radio/tabs)
+ options?: ReadonlyArray<{
+ label: string
+ value: SettingValue
+ icon?: string
+ description?: string
+ }>
+
+ // 验证规则(前端 UX 提示)
+ required?: boolean
+ minLength?: number
+ maxLength?: number
+ min?: number // 最小值(用于 number 类型)
+ max?: number // 最大值(用于 number 类型)
+ pattern?: string // 正则表达式
+
+ // 样式和尺寸
+ size?: 'sm' | 'md' | 'lg'
+ variant?: 'soft' | 'outline'
+ icon?: string
+
+ // 行数(仅用于 textarea 类型,可选)
+ // SettingField.vue 默认值为 3
+ rows?: number
+}
+
+/**
+ * 完整的字段描述符
+ * 包含后端配置和前端 UI 信息
+ * 由 API 返回给前端,前端可直接渲染
+ */
+export interface FieldDescriptor extends SettingConfig {
+ ui: FieldUIConfig
+}
+
+/**
+ * Settings 字段获取响应
+ */
+export interface SettingsFieldsResponse {
+ namespace: string
+ fields: FieldDescriptor[]
+}
+
+/**
+ * Settings 批量更新请求
+ */
+export interface SettingsBatchUpdateRequest {
+ updates: Array<{
+ namespace: string
+ key: string
+ value: SettingValue
+ }>
+}
+
+/** Public, serialized site settings; secret fields are excluded by the server. */
+export interface PublicSettingsResponse {
+ timestamp: number
+ data: Record<string, Record<string, SettingValue>>
+}
diff --git a/packages/contracts/src/upload.ts b/packages/contracts/src/upload.ts
index 2a1a061b..d8147aba 100644
--- a/packages/contracts/src/upload.ts
+++ b/packages/contracts/src/upload.ts
@@ -27,3 +27,5 @@ export type UploadPlan =
partSize: number
partUrls: string[]
}
+
+export const UPLOAD_CHUNK_SIZE = 8 * 1024 * 1024
diff --git a/packages/contracts/tsconfig.json b/packages/contracts/tsconfig.json
index 89eb0f7d..5d435f61 100644
--- a/packages/contracts/tsconfig.json
+++ b/packages/contracts/tsconfig.json
@@ -8,7 +8,8 @@
"allowImportingTsExtensions": true,
"types": [],
"lib": ["ES2022", "DOM"],
- "skipLibCheck": true
+ "skipLibCheck": true,
+ "noUncheckedIndexedAccess": true
},
"include": ["src/**/*.ts"]
}
diff --git a/packages/geocoding/README.md b/packages/geocoding/README.md
new file mode 100644
index 00000000..4e6ae3ab
--- /dev/null
+++ b/packages/geocoding/README.md
@@ -0,0 +1,11 @@
+# @chronoframe/geocoding
+
+Framework-independent geocoding providers and normalization.
+
+`createGeocodingServices` receives language lookup, HTTP transport, shared rate
+limiter, retry implementation/policy and logger. It never reads application
+settings. Create one limiter per process and reuse it across provider instances;
+it does not coordinate limits across processes. Distributed quotas belong to the
+later worker/queue stages. The application selects credentials and providers.
+
+Run `pnpm check:packages` and `pnpm test` from the workspace root.
diff --git a/packages/geocoding/package.json b/packages/geocoding/package.json
new file mode 100644
index 00000000..5a40ea0e
--- /dev/null
+++ b/packages/geocoding/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "@chronoframe/geocoding",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts",
+ "./normalize": "./src/normalize.ts",
+ "./rate-limit": "./src/rate-limit.ts"
+ },
+ "scripts": {
+ "type-check": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@chronoframe/contracts": "workspace:*"
+ },
+ "devDependencies": {
+ "@types/node": "^22.20.5",
+ "typescript": "^5.9.3"
+ }
+}
diff --git a/packages/geocoding/src/coordinates.ts b/packages/geocoding/src/coordinates.ts
new file mode 100644
index 00000000..1ef83dde
--- /dev/null
+++ b/packages/geocoding/src/coordinates.ts
@@ -0,0 +1 @@
+export { hasValidCoordinates } from '@chronoframe/contracts/location'
diff --git a/packages/geocoding/src/index.ts b/packages/geocoding/src/index.ts
new file mode 100644
index 00000000..372eac0d
--- /dev/null
+++ b/packages/geocoding/src/index.ts
@@ -0,0 +1,276 @@
+import type { NormalizedLocation } from '@chronoframe/contracts/location'
+import { hasValidCoordinates } from './coordinates.ts'
+import { normalizeMapbox, normalizeNominatim } from './normalize.ts'
+export interface LocationInfo {
+ latitude: number
+ longitude: number
+ country?: string
+ city?: string
+ geocoding: NormalizedLocation
+ locationName?: string
+}
+
+export interface GeocodingProvider {
+ reverseGeocode(lat: number, lon: number): Promise<LocationInfo | null>
+}
+
+export interface GeocodingLogger {
+ success(...args: any[]): void
+ info(...args: any[]): void
+ warn(...args: any[]): void
+ error(...args: any[]): void
+}
+export interface RetryOptions {
+ maxAttempts?: number
+ baseDelay?: number
+ maxDelay?: number
+ timeout?: number
+ retryCondition?: (error: Error) => boolean
+ delayStrategy?: 'exponential' | 'linear' | 'fixed'
+}
+export interface GeocodingDependencies {
+ getLanguage(): Promise<string>
+ request: typeof fetch
+ waitForGeocodingSlot(
+ key: string,
+ intervalMs: number,
+ signal?: AbortSignal,
+ ): Promise<void>
+ withRetry<T>(
+ operation: (signal: AbortSignal) => Promise<T>,
+ options?: RetryOptions,
+ logger?: GeocodingLogger,
+ ): Promise<T>
+ retryOptions: RetryOptions
+ logger: GeocodingLogger
+}
+
+export function createGeocodingServices({
+ getLanguage,
+ request,
+ waitForGeocodingSlot,
+ withRetry,
+ retryOptions,
+ logger,
+}: GeocodingDependencies) {
+ /**
+ * Mapbox 地理编码提供者
+ * 高精度商业地理编码服务,支持全球范围和多语言
+ */
+ class MapboxGeocodingProvider implements GeocodingProvider {
+ private accessToken: string
+ private readonly baseUrl = 'https://api.mapbox.com'
+ private readonly rateLimitMs = 100 // Mapbox 默认速率限制为 1000/分钟,约60ms间隔
+
+ constructor(accessToken: string) {
+ this.accessToken = accessToken
+ }
+
+ async reverseGeocode(
+ lat: number,
+ lon: number,
+ ): Promise<LocationInfo | null> {
+ try {
+ return await withRetry(
+ async (signal) => {
+ // 应用速率限制
+ await waitForGeocodingSlot(this.baseUrl, this.rateLimitMs, signal)
+
+ // 获取设置的地理编码语言,默认 'en'
+ const language = (await getLanguage()) || 'en'
+
+ const url = new URL('/search/geocode/v6/reverse', this.baseUrl)
+ url.searchParams.set('access_token', this.accessToken)
+ url.searchParams.set('longitude', lon.toString())
+ url.searchParams.set('latitude', lat.toString())
+ url.searchParams.set(
+ 'types',
+ 'address,place,locality,neighborhood,district,region,country',
+ )
+
+ // 映射 Mapbox 首选语言格式
+ let mapboxLang = language
+ if (language === 'zh-CN') {
+ mapboxLang = 'zh-Hans'
+ } else if (language === 'zh-TW') {
+ mapboxLang = 'zh-Hant'
+ }
+ url.searchParams.set('language', mapboxLang)
+
+ logger.info('Requesting Mapbox reverse geocoding')
+
+ const response = await request(url.toString(), { signal })
+
+ if (!response.ok) {
+ throw new Error(
+ `Mapbox API error: ${response.status} ${response.statusText}`,
+ )
+ }
+
+ const data = await response.json()
+
+ if (!data || !data.features || data.features.length === 0) {
+ logger.warn('Mapbox API returned no features')
+ return null
+ }
+
+ const geocoding = normalizeMapbox(data, language)
+ if (!geocoding) return null
+ return {
+ latitude: lat,
+ longitude: lon,
+ geocoding,
+ country: geocoding.components.country?.name,
+ city: geocoding.components.city?.name,
+ locationName: geocoding.formattedAddress,
+ }
+ },
+ {
+ ...retryOptions,
+ timeout: 10000,
+ delayStrategy: 'exponential',
+ },
+ logger,
+ )
+ } catch (error) {
+ logger.error(
+ 'Mapbox reverse geocoding failed after all retries:',
+ error,
+ )
+ return null
+ }
+ }
+ }
+
+ /**
+ * OpenStreetMap Nominatim API 地理编码提供者
+ * 免费的地理编码服务,适合开发和小规模使用
+ */
+ class NominatimGeocodingProvider implements GeocodingProvider {
+ private readonly baseUrl: string
+ private readonly userAgent = 'chronoframe/1.0'
+ private readonly rateLimitMs = 1000 // Nominatim 要求至少1秒间隔
+
+ constructor(baseUrl?: string) {
+ this.baseUrl = baseUrl || 'https://nominatim.openstreetmap.org'
+ }
+
+ async reverseGeocode(
+ lat: number,
+ lon: number,
+ ): Promise<LocationInfo | null> {
+ try {
+ return await withRetry(
+ async (signal) => {
+ // 应用速率限制
+ await waitForGeocodingSlot(this.baseUrl, this.rateLimitMs, signal)
+
+ // 获取设置的地理编码语言,默认 'en'
+ const language = (await getLanguage()) || 'en'
+
+ const url = new URL('/reverse', this.baseUrl)
+ url.searchParams.set('lat', lat.toString())
+ url.searchParams.set('lon', lon.toString())
+ url.searchParams.set('format', 'json')
+ url.searchParams.set('addressdetails', '1')
+ url.searchParams.set('accept-language', `${language},en`)
+
+ const response = await request(url.toString(), {
+ signal,
+ headers: {
+ 'User-Agent': this.userAgent,
+ },
+ })
+
+ if (!response.ok) {
+ throw new Error(
+ `Nominatim API error: ${response.status} ${response.statusText}`,
+ )
+ }
+
+ const data = await response.json()
+
+ if (!data || data.error) {
+ throw new Error(`Nominatim API returned error: ${data?.error}`)
+ }
+
+ const geocoding = normalizeNominatim(data, language)
+ if (!geocoding) return null
+ return {
+ latitude: lat,
+ longitude: lon,
+ geocoding,
+ country: geocoding.components.country?.name,
+ city: geocoding.components.city?.name,
+ locationName: geocoding.formattedAddress,
+ }
+ },
+ {
+ ...retryOptions,
+ timeout: 15000, // Nominatim 可能比较慢
+ delayStrategy: 'linear', // 线性退避,避免过快重试
+ },
+ logger,
+ )
+ } catch (error) {
+ logger.error(
+ 'Nominatim reverse geocoding failed after all retries:',
+ error,
+ )
+ return null
+ }
+ }
+ }
+
+ function parseGPSCoordinates(exifData: any): {
+ latitude?: number
+ longitude?: number
+ } {
+ try {
+ let latitude: number | undefined
+ let longitude: number | undefined
+
+ // 尝试从GPSLatitude和GPSLongitude获取
+ if (exifData.GPSLatitude != null && exifData.GPSLongitude != null) {
+ latitude = parseFloat(exifData.GPSLatitude.toString())
+ longitude = parseFloat(exifData.GPSLongitude.toString())
+ }
+
+ // 如果上面的方法失败,尝试从GPSCoordinates获取
+ if (
+ !hasValidCoordinates(latitude, longitude) &&
+ exifData.GPSCoordinates
+ ) {
+ const coords = exifData.GPSCoordinates.toString()
+ const match = coords.match(/([-+]?\d+\.?\d*)[°,\s]+([-+]?\d+\.?\d*)/)
+ if (match) {
+ latitude = parseFloat(match[1])
+ longitude = parseFloat(match[2])
+ }
+ }
+
+ // 应用GPS参考(南纬为负,西经为负)
+ if (latitude && exifData.GPSLatitudeRef === 'S') {
+ latitude = -Math.abs(latitude)
+ }
+ if (longitude && exifData.GPSLongitudeRef === 'W') {
+ longitude = -Math.abs(longitude)
+ }
+
+ if (!hasValidCoordinates(latitude, longitude)) return {}
+ return { latitude, longitude }
+ } catch (error) {
+ logger.error('Failed to parse GPS coordinates:', error)
+ return {}
+ }
+ }
+
+ return {
+ MapboxGeocodingProvider,
+ NominatimGeocodingProvider,
+ parseGPSCoordinates,
+ }
+}
+export * from './normalize.ts'
+export * from './coordinates.ts'
+export * from './rate-limit.ts'
diff --git a/packages/geocoding/src/normalize.ts b/packages/geocoding/src/normalize.ts
new file mode 100644
index 00000000..96395660
--- /dev/null
+++ b/packages/geocoding/src/normalize.ts
@@ -0,0 +1,110 @@
+import type {
+ LocationLevel,
+ NormalizedLocation,
+} from '@chronoframe/contracts/location'
+
+type ObjectValue = Record<string, any>
+const name = (value: unknown): string | undefined =>
+ typeof value === 'string' && value.trim() ? value.trim() : undefined
+
+const municipalityCodes = new Set(['CN-BJ', 'CN-TJ', 'CN-SH', 'CN-CQ'])
+
+function applyMunicipality(result: NormalizedLocation, code: unknown) {
+ // A direct-administered municipality also acts as the city. Use the explicit
+ // ISO subdivision code, rather than guessing from translated name suffixes.
+ if (
+ result.countryCode === 'CN' &&
+ typeof code === 'string' &&
+ municipalityCodes.has(code.toUpperCase()) &&
+ !result.components.city
+ ) {
+ result.components.city = result.components.region
+ }
+}
+
+function put(
+ result: NormalizedLocation,
+ level: LocationLevel,
+ value: unknown,
+ sourceField: string,
+) {
+ const text = name(value)
+ if (text && !result.components[level])
+ result.components[level] = { name: text, sourceField }
+}
+
+export function normalizeMapbox(
+ data: ObjectValue,
+ language: string,
+): NormalizedLocation | null {
+ if (!Array.isArray(data?.features) || !data.features.length) return null
+ const result: NormalizedLocation = {
+ version: 1,
+ provider: 'mapbox',
+ language,
+ components: {},
+ }
+ const mapping: Record<string, LocationLevel> = {
+ country: 'country',
+ region: 'region',
+ district: 'subregion',
+ place: 'city',
+ locality: 'district',
+ neighborhood: 'neighborhood',
+ }
+ for (const feature of data.features) {
+ const p = feature.properties || {}
+ const context = p.context || {}
+ // A country/place response may carry its own name only on the feature.
+ const level = mapping[p.feature_type]
+ if (level) put(result, level, p.name, `feature.${p.feature_type}`)
+ for (const [field, target] of Object.entries(mapping)) {
+ put(result, target, context[field]?.name, `context.${field}`)
+ }
+ result.countryCode ||= name(context.country?.country_code)?.toUpperCase()
+ if (p.feature_type === 'country')
+ result.countryCode ||= name(p.country_code)?.toUpperCase()
+ result.formattedAddress ||=
+ name(p.full_address) || name(p.place_formatted) || name(p.name)
+ }
+ for (const feature of data.features) {
+ const p = feature.properties || {}
+ applyMunicipality(
+ result,
+ p.context?.region?.region_code_full ||
+ (p.feature_type === 'region' ? p.region_code_full : undefined),
+ )
+ }
+ return Object.keys(result.components).length ? result : null
+}
+
+export function normalizeNominatim(
+ data: ObjectValue,
+ language: string,
+): NormalizedLocation | null {
+ if (!data || data.error) return null
+ const result: NormalizedLocation = {
+ version: 1,
+ provider: 'nominatim',
+ language,
+ components: {},
+ countryCode: name(data.address?.country_code)?.toUpperCase(),
+ formattedAddress: name(data.display_name),
+ }
+ // Preserve source tags: county/state_district must not be treated as city districts.
+ const mapping: Array<[LocationLevel, string[]]> = [
+ ['country', ['country']],
+ ['region', ['state', 'region']],
+ ['subregion', ['state_district', 'county']],
+ ['city', ['city', 'town', 'municipality', 'village', 'hamlet']],
+ ['district', ['city_district', 'district', 'borough']],
+ ['locality', ['suburb', 'subdivision']],
+ ['neighborhood', ['neighbourhood', 'quarter']],
+ ]
+ for (const [level, fields] of mapping) {
+ for (const field of fields)
+ put(result, level, data.address?.[field], `address.${field}`)
+ }
+ applyMunicipality(result, data.address?.['ISO3166-2-lvl4'])
+ return Object.keys(result.components).length ? result : null
+}
diff --git a/packages/geocoding/src/rate-limit.ts b/packages/geocoding/src/rate-limit.ts
new file mode 100644
index 00000000..a5f428bc
--- /dev/null
+++ b/packages/geocoding/src/rate-limit.ts
@@ -0,0 +1,20 @@
+import { setTimeout } from 'node:timers/promises'
+
+export function createGeocodingRateLimiter() {
+ const nextRequestAt = new Map<string, number>()
+
+ // Reserve synchronously before waiting so separate providers/workers cannot
+ // start together after the same delay. Providers are recreated for each photo.
+ async function waitForGeocodingSlot(
+ key: string,
+ intervalMs: number,
+ signal?: AbortSignal,
+ ) {
+ const now = Date.now()
+ const start = Math.max(now, nextRequestAt.get(key) || 0)
+ nextRequestAt.set(key, start + intervalMs)
+ if (start > now) await setTimeout(start - now, undefined, { signal })
+ }
+
+ return waitForGeocodingSlot
+}
diff --git a/packages/geocoding/tsconfig.json b/packages/geocoding/tsconfig.json
new file mode 100644
index 00000000..e79cde15
--- /dev/null
+++ b/packages/geocoding/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "noEmit": true,
+ "allowImportingTsExtensions": true,
+ "types": ["node"],
+ "lib": ["ES2022", "DOM"],
+ "skipLibCheck": true,
+ "noUncheckedIndexedAccess": true
+ },
+ "include": ["src/**/*.ts"]
+}
diff --git a/packages/media/README.md b/packages/media/README.md
new file mode 100644
index 00000000..0aeab135
--- /dev/null
+++ b/packages/media/README.md
@@ -0,0 +1,19 @@
+# @chronoframe/media
+
+Framework-independent image and motion-photo processing.
+
+`createImageProcessor(logger)` provides conversion and metadata operations.
+`createExifService({ exiftool, tempDir, logger })` accepts an application-owned
+ExifTool instance and work directory; its owner must close ExifTool on shutdown.
+Thumbnail, histogram and motion-photo helpers accept explicit inputs and optional
+logging. Motion-photo extraction accepts a storage provider. Database updates,
+upload orchestration, settings and global services remain in the application.
+
+The private workspace exports TypeScript source for Nuxt/Nitro and Node with type
+stripping. Sharp and ExifTool require their native/runtime tools. ImageProcessorOptions accepts a byte cap, Sharp pixel limit and cooperative
+cancellation signal. Defaults preserve existing behavior; the application chooses
+production limits. Native operations settle before retry/resource-slot release.
+Cross-process resource policy remains work for the processing/worker stages. `retry` is a reusable subpath used by the
+application compatibility entry and injected into geocoding.
+
+Run `pnpm check:packages` and `pnpm test` from the workspace root.
diff --git a/packages/media/package.json b/packages/media/package.json
new file mode 100644
index 00000000..a35fc165
--- /dev/null
+++ b/packages/media/package.json
@@ -0,0 +1,35 @@
+{
+ "name": "@chronoframe/media",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts",
+ "./processor": "./src/processor.ts",
+ "./thumbnail": "./src/thumbnail.ts",
+ "./blurhash": "./src/blurhash.ts",
+ "./histogram": "./src/histogram.ts",
+ "./exif": "./src/exif.ts",
+ "./motion-photo": "./src/motion-photo.ts",
+ "./livephoto": "./src/livephoto.ts",
+ "./retry": "./src/retry.ts"
+ },
+ "scripts": {
+ "type-check": "tsc --noEmit"
+ },
+ "dependencies": {
+ "sharp": "^0.35.5",
+ "@vingle/bmp-js": "^0.2.5",
+ "heic-convert": "^2.1.0",
+ "exiftool-vendored": "^35.21.0",
+ "es-toolkit": "^1.52.0",
+ "thumbhash": "^0.1.1",
+ "@chronoframe/contracts": "workspace:*",
+ "@chronoframe/storage": "workspace:*"
+ },
+ "devDependencies": {
+ "@types/node": "^22.20.5",
+ "@types/heic-convert": "^2.1.1",
+ "typescript": "^5.9.3"
+ }
+}
diff --git a/packages/media/src/blurhash.ts b/packages/media/src/blurhash.ts
new file mode 100644
index 00000000..44fa6832
--- /dev/null
+++ b/packages/media/src/blurhash.ts
@@ -0,0 +1,24 @@
+import type { MediaLogger } from './logger.ts'
+import sharp from 'sharp'
+import { rgbaToThumbHash } from 'thumbhash'
+
+export const generateBlurHash = async (
+ buffer: Buffer,
+ logger?: MediaLogger,
+) => {
+ try {
+ const { data, info } = await sharp(buffer)
+ .resize(100, 100, { fit: 'inside' })
+ .raw()
+ .ensureAlpha()
+ .toBuffer({
+ resolveWithObject: true,
+ })
+
+ const thumbHash = rgbaToThumbHash(info.width, info.height, data)
+ return thumbHash
+ } catch (error) {
+ logger?.error('Generate thumbhash failed', error)
+ return null
+ }
+}
diff --git a/packages/media/src/exif.ts b/packages/media/src/exif.ts
new file mode 100644
index 00000000..085c3c7a
--- /dev/null
+++ b/packages/media/src/exif.ts
@@ -0,0 +1,553 @@
+import type { MediaLogger } from './logger.ts'
+import type { ExifTool } from 'exiftool-vendored'
+import { randomUUID } from 'node:crypto'
+import path from 'node:path'
+import { mkdir, unlink, writeFile } from 'node:fs/promises'
+import type { Metadata } from 'sharp'
+import sharp from 'sharp'
+import type { NeededExif, PhotoInfo } from '@chronoframe/contracts/photo'
+import type { ExifDateTime, Tags } from 'exiftool-vendored'
+import { noop } from 'es-toolkit'
+import { withRetry, RetryPresets, RetryConditions } from './retry.ts'
+
+export function createExifService({
+ exiftool,
+ tempDir,
+ logger: serviceLogger,
+}: {
+ exiftool: Pick<ExifTool, 'read'>
+ tempDir: string
+ logger?: MediaLogger
+}) {
+ const neededKeys: Array<keyof Tags | (string & {})> = [
+ 'Title',
+ 'XPTitle',
+ 'Subject',
+ 'Keywords',
+ 'XPKeywords',
+
+ 'Description',
+ 'ImageDescription',
+ 'Caption-Abstract',
+ 'XPComment',
+ 'UserComment',
+
+ 'tz',
+ 'tzSource',
+ 'Orientation',
+ 'Make',
+ 'Model',
+ 'Software',
+ 'Artist',
+ 'Copyright',
+ 'ExposureTime',
+
+ 'FNumber',
+ 'ExposureProgram',
+ 'ISO',
+ 'OffsetTime',
+ 'OffsetTimeOriginal',
+ 'OffsetTimeDigitized',
+ 'ShutterSpeedValue',
+ 'ApertureValue',
+ 'BrightnessValue',
+ 'ExposureCompensationSet',
+ 'ExposureCompensationMode',
+ 'ExposureCompensationSetting',
+
+ 'ExposureCompensation',
+ 'MaxApertureValue',
+ 'LightSource',
+ 'Flash',
+ 'FocalLength',
+
+ 'ColorSpace',
+ 'ExposureMode',
+ 'FocalLengthIn35mmFormat',
+ 'SceneCaptureType',
+ 'LensMake',
+ 'LensModel',
+ 'MeteringMode',
+ 'WhiteBalance',
+ 'WBShiftAB',
+ 'WBShiftGM',
+ 'WhiteBalanceBias',
+ 'WhiteBalanceFineTune',
+ 'FlashMeteringMode',
+ 'SensingMethod',
+ 'FocalPlaneXResolution',
+ 'FocalPlaneYResolution',
+
+ 'Aperture',
+ 'ScaleFactor35efl',
+ 'ShutterSpeed',
+ 'LightValue',
+ 'Rating',
+
+ 'GPSAltitude',
+ 'GPSCoordinates',
+ 'GPSAltitudeRef',
+ 'GPSLatitude',
+ 'GPSLatitudeRef',
+ 'GPSLongitude',
+ 'GPSLongitudeRef',
+
+ 'MPImageType',
+
+ // Motion Photo (XMP) related keys
+ 'MotionPhoto',
+ 'MotionPhotoVersion',
+ 'MotionPhotoPresentationTimestampUs',
+ 'MicroVideo',
+ 'MicroVideoVersion',
+ 'MicroVideoOffset',
+ 'MicroVideoPresentationTimestampUs',
+ ]
+
+ /**
+ * Convert a date-like value to an ISO string, returning undefined instead of
+ * throwing `RangeError: Invalid time value` when the value cannot be parsed.
+ */
+ const toValidISOString = (
+ value: string | number | Date,
+ ): string | undefined => {
+ const date = value instanceof Date ? value : new Date(value)
+ return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
+ }
+
+ const formatExifDate = (date: string | ExifDateTime | undefined) => {
+ if (!date) {
+ return
+ }
+
+ // exiftool returns the raw string when it cannot parse a date
+ // (e.g. "0000:00:00 00:00:00"), which `new Date()` cannot parse either.
+ if (typeof date === 'string') {
+ return toValidISOString(date)
+ }
+
+ return date.toISOString()
+ }
+
+ /**
+ * 从 Sharp metadata 中推断颜色空间信息
+ */
+ const inferColorSpaceFromMetadata = (
+ metadata: Metadata,
+ ): string | undefined => {
+ // 优先使用 ICC 配置文件信息
+ if (metadata.icc) {
+ const colorSpace = parseICCProfile(metadata.icc)
+ if (colorSpace) {
+ return colorSpace
+ }
+ }
+
+ // 根据图片格式和通道数推断
+ if (metadata.space) {
+ const colorSpace = mapSharpSpaceToColorSpace(metadata.space)
+ if (colorSpace) {
+ return colorSpace
+ }
+ }
+
+ // 根据图片类型的默认颜色空间
+ if (metadata.format) {
+ const colorSpace = getDefaultColorSpaceForFormat(metadata.format)
+ if (colorSpace) {
+ return colorSpace
+ }
+ }
+
+ return undefined
+ }
+
+ /**
+ * 解析 ICC 配置文件以确定颜色空间
+ */
+ const parseICCProfile = (iccBuffer: Buffer): string | undefined => {
+ try {
+ const iccString = iccBuffer.toString('latin1')
+
+ // 常见的颜色空间标识符
+ if (iccString.includes('sRGB') || iccString.includes('IEC61966-2.1')) {
+ return 'sRGB'
+ }
+ if (iccString.includes('Adobe RGB') || iccString.includes('ADOBERGB')) {
+ return 'Adobe RGB'
+ }
+ if (iccString.includes('Display P3') || iccString.includes('P3')) {
+ return 'Display P3'
+ }
+ if (iccString.includes('ProPhoto') || iccString.includes('ROMM')) {
+ return 'ProPhoto RGB'
+ }
+ if (iccString.includes('Wide Gamut') || iccString.includes('WideGamut')) {
+ return 'Wide Gamut RGB'
+ }
+ if (
+ iccString.includes('Rec2020') ||
+ iccString.includes('ITU-R BT.2020')
+ ) {
+ return 'Rec. 2020'
+ }
+ if (iccString.includes('DCI-P3') || iccString.includes('DCI')) {
+ return 'DCI-P3'
+ }
+ if (iccString.includes('Rec709') || iccString.includes('ITU-R BT.709')) {
+ return 'Rec. 709'
+ }
+
+ // 检查 ICC 配置文件头部的颜色空间签名(偏移量 16-19)
+ if (iccBuffer.length >= 20) {
+ const colorSpaceSignature = iccBuffer.toString('ascii', 16, 20)
+ switch (colorSpaceSignature) {
+ case 'RGB ':
+ return 'RGB'
+ case 'CMYK':
+ return 'CMYK'
+ case 'GRAY':
+ return 'Grayscale'
+ case 'LAB ':
+ return 'Lab'
+ case 'XYZ ':
+ return 'XYZ'
+ default:
+ break
+ }
+ }
+ } catch {
+ // 忽略解析错误,继续尝试其他方法
+ }
+
+ return undefined
+ }
+
+ /**
+ * 将 Sharp 的 space 映射到标准颜色空间名称
+ */
+ const mapSharpSpaceToColorSpace = (space: string): string | undefined => {
+ switch (space) {
+ case 'srgb':
+ return 'sRGB'
+ case 'rgb16':
+ return 'RGB'
+ case 'cmyk':
+ return 'CMYK'
+ case 'lab':
+ return 'Lab'
+ case 'xyz':
+ return 'XYZ'
+ case 'grey16':
+ case 'b-w':
+ return 'Grayscale'
+ default:
+ return undefined
+ }
+ }
+
+ /**
+ * 根据图片格式获取默认颜色空间
+ */
+ const getDefaultColorSpaceForFormat = (
+ format: string,
+ ): string | undefined => {
+ const formatLower = format.toLowerCase()
+ switch (formatLower) {
+ case 'jpeg':
+ case 'jpg':
+ return 'sRGB' // JPEG 默认使用 sRGB
+ case 'png':
+ return 'sRGB' // PNG 通常使用 sRGB
+ case 'webp':
+ return 'sRGB' // WebP 通常使用 sRGB
+ case 'tiff':
+ case 'tif':
+ return 'sRGB' // TIFF 可能使用各种颜色空间,默认 sRGB
+ case 'heif':
+ case 'heic':
+ return 'Display P3' // HEIC 通常支持 Display P3
+ case 'avif':
+ return 'sRGB' // AVIF 通常使用 sRGB,但也可能支持其他
+ case 'gif':
+ return 'sRGB' // GIF 使用 sRGB
+ case 'bmp':
+ return 'sRGB' // BMP 通常使用 sRGB
+ default:
+ return undefined
+ }
+ }
+
+ const processExifData = (exifData: Tags, metadata: Metadata): NeededExif => {
+ const date = {
+ DateTimeOriginal: formatExifDate(exifData.DateTimeOriginal),
+ DateTimeDigitized: formatExifDate(exifData.DateTimeDigitized),
+ OffsetTime: exifData.OffsetTime,
+ OffsetTimeOriginal: exifData.OffsetTimeOriginal,
+ OffsetTimeDigitized: exifData.OffsetTimeDigitized,
+ }
+
+ const size = {
+ ImageWidth: exifData.ExifImageWidth || metadata.width,
+ ImageHeight: exifData.ExifImageHeight || metadata.height,
+ }
+
+ const result: any = structuredClone(exifData)
+ for (const key in result) {
+ Reflect.deleteProperty(result, key)
+ }
+ for (const key of neededKeys) {
+ result[key] = (exifData as any)[key]
+ }
+
+ // 优先从 metadata 推断颜色空间
+ const inferredColorSpace = inferColorSpaceFromMetadata(metadata)
+ if (inferredColorSpace) {
+ result.ColorSpace = inferredColorSpace
+ } else if (!result.ColorSpace) {
+ // 推断失败且 exif 中也没有 ColorSpace
+ // ignore
+ }
+
+ return {
+ ...date,
+ ...size,
+ ...result,
+ }
+ }
+
+ const extractExifData = async (
+ imageBuffer: Buffer,
+ rawImageBuffer?: Buffer,
+ logger?: MediaLogger,
+ ): Promise<NeededExif | null> => {
+ try {
+ return await withRetry(
+ async () => {
+ let tempImagePath: string | null = null
+
+ try {
+ // 提取基础元数据
+ let metadata = await sharp(imageBuffer).metadata()
+
+ // 如果主buffer没有EXIF,尝试原始buffer
+ if (!metadata.exif && rawImageBuffer) {
+ try {
+ metadata = await sharp(rawImageBuffer).metadata()
+ } catch (err) {
+ logger?.warn(
+ 'Error extracting EXIF data from raw image buffer:',
+ err,
+ )
+ }
+ }
+
+ if (!metadata.exif) {
+ logger?.warn('No EXIF data found in image metadata')
+ return null
+ }
+
+ logger?.info('Extracting EXIF data using exiftool...')
+
+ // 创建临时工作目录
+ // The application owns the work directory and ExifTool lifecycle.
+ await mkdir(tempDir, { recursive: true })
+ tempImagePath = path.resolve(tempDir, `${randomUUID()}.jpg`)
+
+ // 写入临时文件
+ await writeFile(tempImagePath, rawImageBuffer || imageBuffer)
+
+ // 使用 exiftool 读取详细 EXIF 数据
+ const exifData = await exiftool.read(tempImagePath)
+ const result = processExifData(exifData, metadata)
+
+ // 记录颜色空间信息
+ if (result.ColorSpace) {
+ logger?.success(`Inferred ColorSpace: ${result.ColorSpace}`)
+ } else {
+ logger?.info('ColorSpace could not be determined')
+ }
+
+ return result
+ } finally {
+ // 确保清理临时文件
+ if (tempImagePath) {
+ await unlink(tempImagePath).catch(noop)
+ }
+ }
+ },
+ {
+ ...RetryPresets.standard,
+ timeout: 15000, // EXIF 处理可能需要更长时间
+ retryCondition: (error) => {
+ // 组合多种重试条件
+ return (
+ RetryConditions.fileSystemErrors(error) ||
+ RetryConditions.resourceErrors(error) ||
+ error.message.includes('timeout')
+ )
+ },
+ },
+ logger,
+ )
+ } catch (error) {
+ logger?.error('EXIF extraction failed after all retries:', error)
+ return null
+ }
+ }
+
+ const normalizeText = (value: unknown): string | undefined => {
+ if (value === null || value === undefined) {
+ return undefined
+ }
+
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ const normalized = normalizeText(item)
+ if (normalized) {
+ return normalized
+ }
+ }
+ return undefined
+ }
+
+ const text = String(value).trim()
+ return text.length > 0 ? text : undefined
+ }
+
+ const collectTextValues = (
+ value: unknown,
+ options?: { splitDelimited?: boolean },
+ ): string[] => {
+ const splitDelimited = options?.splitDelimited ?? false
+ const results: string[] = []
+
+ const append = (input: string) => {
+ if (splitDelimited) {
+ for (const part of input.split(/[;,]/)) {
+ const chunk = part.trim()
+ if (chunk.length > 0) {
+ results.push(chunk)
+ }
+ }
+ } else if (input.length > 0) {
+ results.push(input)
+ }
+ }
+
+ if (value === null || value === undefined) {
+ return results
+ }
+
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ const normalized = normalizeText(item)
+ if (normalized) {
+ append(normalized)
+ }
+ }
+ return results
+ }
+
+ const normalized = normalizeText(value)
+ if (normalized) {
+ append(normalized)
+ }
+
+ return results
+ }
+
+ const pickFirstText = (...values: Array<unknown>): string | undefined => {
+ for (const value of values) {
+ const normalized = normalizeText(value)
+ if (normalized) {
+ return normalized
+ }
+ }
+
+ return undefined
+ }
+
+ const extractPhotoInfo = (
+ s3key: string,
+ exifData?: NeededExif | null,
+ ): PhotoInfo => {
+ const fileName = path.basename(s3key, path.extname(s3key))
+
+ let dateTaken = new Date().toISOString()
+ const tagsSet = new Set<string>()
+
+ for (const tag of collectTextValues(exifData?.Subject)) {
+ tagsSet.add(tag)
+ }
+
+ for (const tag of collectTextValues(exifData?.Keywords)) {
+ tagsSet.add(tag)
+ }
+
+ for (const tag of collectTextValues(exifData?.XPKeywords, {
+ splitDelimited: true,
+ })) {
+ tagsSet.add(tag)
+ }
+
+ if (exifData?.DateTimeOriginal) {
+ const dateTimeOriginal = toValidISOString(exifData.DateTimeOriginal)
+
+ if (dateTimeOriginal) {
+ dateTaken = dateTimeOriginal
+ } else {
+ serviceLogger?.warn(
+ `Parse EXIF DateTimeOriginal failed: ${exifData.DateTimeOriginal}`,
+ )
+ }
+ } else {
+ // The match may be a false positive inside a longer digit run
+ // (e.g. "9101-28-18" in "IMG119101-28-18.jpg"), so validate before use.
+ const dateMatch = fileName.match(/(\d{4}-\d{2}-\d{2})/)
+ const dateFromFileName = dateMatch
+ ? toValidISOString(dateMatch[1]!)
+ : undefined
+ if (dateFromFileName) {
+ dateTaken = dateFromFileName
+ }
+ }
+
+ const titleFromExif = pickFirstText(
+ exifData?.Title,
+ exifData?.XPTitle,
+ exifData?.Description,
+ exifData?.ImageDescription,
+ exifData?.CaptionAbstract,
+ )
+
+ let title = titleFromExif
+ const cleanedFileName = fileName
+ .replaceAll(/\d{4}-\d{2}-\d{2}[_-]?/g, '')
+ .replaceAll(/[_-]?\d+views?/gi, '')
+ .replaceAll(/[_-]+/g, ' ')
+ .trim()
+
+ if (!title) {
+ title = cleanedFileName || path.basename(s3key, path.extname(s3key))
+ }
+
+ const description =
+ pickFirstText(
+ exifData?.Description,
+ exifData?.ImageDescription,
+ exifData?.CaptionAbstract,
+ exifData?.XPComment,
+ exifData?.UserComment,
+ ) || ''
+
+ return {
+ title,
+ dateTaken,
+ tags: [...tagsSet],
+ description,
+ }
+ }
+
+ return { extractExifData, extractPhotoInfo }
+}
diff --git a/packages/media/src/histogram.ts b/packages/media/src/histogram.ts
new file mode 100644
index 00000000..ebc2872a
--- /dev/null
+++ b/packages/media/src/histogram.ts
@@ -0,0 +1,81 @@
+import type { MediaLogger } from './logger.ts'
+import sharp, { type Sharp } from 'sharp'
+
+export interface HistogramData {
+ r: number[]
+ g: number[]
+ b: number[]
+ gray: number[]
+}
+
+/**
+ * 使用现有的 Sharp 实例计算图片的直方图数据
+ * @param sharpInst Sharp 实例
+ * @returns 直方图数据,包含 RGB 和灰度通道的 256 个值
+ */
+export const calculateHistogram = async (
+ sharpInst: Sharp,
+ logger?: MediaLogger,
+): Promise<HistogramData> => {
+ try {
+ // 获取原始像素数据,确保是 RGB 格式
+ const { data, info } = await sharpInst
+ .clone() // 克隆 Sharp 实例以避免影响原实例
+ .toColourspace('srgb')
+ .removeAlpha() // 移除 alpha 通道
+ .raw()
+ .toBuffer({ resolveWithObject: true })
+
+ const { width, height, channels } = info
+ const totalPixels = width * height
+ // 初始化直方图数组(256个bin,对应0-255的像素值)
+ const histogramR = Array<number>(256).fill(0)
+ const histogramG = Array<number>(256).fill(0)
+ const histogramB = Array<number>(256).fill(0)
+ const histogramGray = Array<number>(256).fill(0)
+
+ // 遍历像素数据计算直方图
+ for (let i = 0; i < data.length; i += channels) {
+ const r = data.readUInt8(i)
+ const g = data.readUInt8(i + 1)
+ const b = data.readUInt8(i + 2)
+
+ // 累计 RGB 通道直方图
+ histogramR[r] = (histogramR[r] ?? 0) + 1
+ histogramG[g] = (histogramG[g] ?? 0) + 1
+ histogramB[b] = (histogramB[b] ?? 0) + 1
+
+ // 计算灰度值(使用 ITU-R BT.709 标准)
+ const gray = Math.round(0.299 * r + 0.587 * g + 0.114 * b)
+ histogramGray[gray] = (histogramGray[gray] ?? 0) + 1
+ }
+
+ // 归一化直方图(转换为百分比)
+ const normalizeHistogram = (hist: number[]) => {
+ return hist.map((count) => count / totalPixels)
+ }
+
+ return {
+ r: normalizeHistogram(histogramR),
+ g: normalizeHistogram(histogramG),
+ b: normalizeHistogram(histogramB),
+ gray: normalizeHistogram(histogramGray),
+ }
+ } catch (error) {
+ logger?.error('Failed to calculate histogram', error)
+ throw error
+ }
+}
+
+/**
+ * 使用图片缓冲区计算直方图数据
+ * @param buffer 图片缓冲区
+ * @returns 直方图数据
+ */
+export const calculateHistogramFromBuffer = async (
+ buffer: Buffer,
+ logger?: MediaLogger,
+): Promise<HistogramData> => {
+ const sharpInst = sharp(buffer)
+ return calculateHistogram(sharpInst, logger)
+}
diff --git a/packages/media/src/index.ts b/packages/media/src/index.ts
new file mode 100644
index 00000000..f6a8ca62
--- /dev/null
+++ b/packages/media/src/index.ts
@@ -0,0 +1,9 @@
+export * from './processor.ts'
+export * from './thumbnail.ts'
+export * from './blurhash.ts'
+export * from './histogram.ts'
+export * from './exif.ts'
+export * from './motion-photo.ts'
+export * from './livephoto.ts'
+export * from './retry.ts'
+export type { MediaLogger } from './logger.ts'
diff --git a/packages/media/src/livephoto.ts b/packages/media/src/livephoto.ts
new file mode 100644
index 00000000..33e00ad3
--- /dev/null
+++ b/packages/media/src/livephoto.ts
@@ -0,0 +1,15 @@
+import path from 'node:path'
+export const isLivePhotoVideo = (
+ fileName: string,
+ fileSize: number,
+): boolean => {
+ const extName = path.extname(fileName).toLowerCase()
+
+ // 检查是否为 MOV 格式
+ if (extName !== '.mov') {
+ return false
+ }
+
+ const maxLivePhotoSize = 12 * 1024 * 1024 // 12MB
+ return fileSize <= maxLivePhotoSize
+}
diff --git a/packages/media/src/logger.ts b/packages/media/src/logger.ts
new file mode 100644
index 00000000..a9077961
--- /dev/null
+++ b/packages/media/src/logger.ts
@@ -0,0 +1,7 @@
+export interface MediaLogger {
+ info(...args: any[]): void
+ warn(...args: any[]): void
+ error(...args: any[]): void
+ debug(...args: any[]): void
+ success(...args: any[]): void
+}
diff --git a/packages/media/src/motion-photo.ts b/packages/media/src/motion-photo.ts
new file mode 100644
index 00000000..cc93546c
--- /dev/null
+++ b/packages/media/src/motion-photo.ts
@@ -0,0 +1,307 @@
+import type { MediaLogger } from './logger.ts'
+import type { NeededExif } from '@chronoframe/contracts/photo'
+import type { StorageProvider } from '@chronoframe/storage/interfaces'
+
+interface MotionPhotoProcessParams {
+ photoId: string
+ storageKey: string
+ rawImageBuffer: Buffer
+ exifData?: NeededExif | null
+ storageProvider: StorageProvider
+ logger?: MediaLogger
+}
+
+export interface MotionPhotoProcessResult {
+ isMotionPhoto: boolean
+ livePhotoVideoKey?: string
+ livePhotoVideoUrl?: string
+ offset?: number
+ presentationTimestampUs?: number
+}
+
+const MAX_XMP_SCAN_BYTES = 512 * 1024 // 512KB should cover standard XMP blocks
+const MIN_VIDEO_SIZE_BYTES = 8 * 1024 // 8KB minimal sanity check
+const MP4_FTYP = Buffer.from('ftyp')
+
+const toBoolean = (value: unknown): boolean => {
+ if (value === null || value === undefined) return false
+ if (typeof value === 'boolean') return value
+ if (typeof value === 'number') return value !== 0
+ if (typeof value === 'bigint') return value !== BigInt(0)
+ if (typeof value === 'string') {
+ const normalized = value.trim().toLowerCase()
+ return normalized === '1' || normalized === 'true' || normalized === 'yes'
+ }
+ return false
+}
+
+const toNumber = (value: unknown): number | null => {
+ if (value === null || value === undefined) return null
+ if (typeof value === 'number' && Number.isFinite(value)) return value
+ if (typeof value === 'bigint') return Number(value)
+ if (typeof value === 'string') {
+ const parsed = Number.parseInt(value.trim(), 10)
+ return Number.isFinite(parsed) ? parsed : null
+ }
+ return null
+}
+
+const extractXmpSegment = (buffer: Buffer): string | null => {
+ const scanSize = Math.min(buffer.length, MAX_XMP_SCAN_BYTES)
+ if (scanSize === 0) {
+ return null
+ }
+
+ const header = buffer.toString('utf8', 0, scanSize)
+ const startIndex = header.indexOf('<x:xmpmeta')
+ if (startIndex === -1) {
+ return null
+ }
+
+ const endIndex = header.indexOf('</x:xmpmeta>')
+ if (endIndex === -1) {
+ return null
+ }
+
+ return header.slice(startIndex, endIndex + '</x:xmpmeta>'.length)
+}
+
+const extractXmpBoolean = (xmp: string, tagName: string): boolean | null => {
+ const regex = new RegExp(`<[^:>]*:${tagName}>([^<]+)</[^>]+>`, 'i')
+ const match = xmp.match(regex)
+ if (!match) return null
+ return toBoolean(match[1])
+}
+
+const extractXmpNumber = (xmp: string, tagName: string): number | null => {
+ const regex = new RegExp(`<[^:>]*:${tagName}>([^<]+)</[^>]+>`, 'i')
+ const match = xmp.match(regex)
+ if (!match) return null
+ return toNumber(match[1])
+}
+
+const escapeRegExp = (value: string) =>
+ value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const buildAttrPattern = (attrName: string) => {
+ const escaped = escapeRegExp(attrName)
+ if (attrName.includes(':')) {
+ return escaped
+ }
+ return `(?:[\\w-]+:)?${escaped}`
+}
+
+const extractXmpAttributeBoolean = (
+ xmp: string,
+ attrName: string,
+): boolean | null => {
+ const regex = new RegExp(`${buildAttrPattern(attrName)}="([^"]+)"`, 'i')
+ const match = xmp.match(regex)
+ if (!match) return null
+ return toBoolean(match[1])
+}
+
+const extractXmpAttributeNumber = (
+ xmp: string,
+ attrName: string,
+): number | null => {
+ const regex = new RegExp(`${buildAttrPattern(attrName)}="([^"]+)"`, 'i')
+ const match = xmp.match(regex)
+ if (!match) return null
+ return toNumber(match[1])
+}
+
+const validateMp4Buffer = (buffer: Buffer): boolean => {
+ if (buffer.length < MIN_VIDEO_SIZE_BYTES) {
+ return false
+ }
+
+ // MP4 should contain 'ftyp' brand within the first few bytes
+ const searchWindow = buffer.subarray(0, 32)
+ return searchWindow.indexOf(MP4_FTYP) !== -1
+}
+
+export const processMotionPhotoFromXmp = async ({
+ photoId,
+ storageKey,
+ rawImageBuffer,
+ exifData,
+ storageProvider,
+ logger,
+}: MotionPhotoProcessParams): Promise<MotionPhotoProcessResult | null> => {
+ try {
+ const rawLength = rawImageBuffer.length
+
+ const exifIndicatesMotion =
+ toBoolean(exifData?.MotionPhoto) || toBoolean(exifData?.MicroVideo)
+ let detectedMotion = exifIndicatesMotion
+
+ let presentationTimestampUs = toNumber(
+ exifData?.MotionPhotoPresentationTimestampUs ??
+ exifData?.MicroVideoPresentationTimestampUs,
+ )
+
+ const offsetCandidates = new Set<number>()
+ const addOffsetCandidate = (value: number | null | undefined) => {
+ if (value === null || value === undefined) return
+ if (!Number.isFinite(value)) return
+ const numeric = Number(value)
+ if (numeric <= 0) return
+ offsetCandidates.add(numeric)
+ }
+
+ addOffsetCandidate(toNumber(exifData?.MicroVideoOffset))
+
+ const xmpSegment = extractXmpSegment(rawImageBuffer)
+ if (xmpSegment) {
+ if (!detectedMotion) {
+ const motionFlags = [
+ extractXmpBoolean(xmpSegment, 'MotionPhoto'),
+ extractXmpBoolean(xmpSegment, 'GCamera:MotionPhoto'),
+ extractXmpBoolean(xmpSegment, 'MicroVideo'),
+ extractXmpBoolean(xmpSegment, 'GCamera:MicroVideo'),
+ extractXmpAttributeBoolean(xmpSegment, 'MotionPhoto'),
+ extractXmpAttributeBoolean(xmpSegment, 'GCamera:MotionPhoto'),
+ extractXmpAttributeBoolean(xmpSegment, 'MicroVideo'),
+ extractXmpAttributeBoolean(xmpSegment, 'GCamera:MicroVideo'),
+ ].filter((flag) => flag !== null) as boolean[]
+
+ if (motionFlags.some(Boolean)) {
+ detectedMotion = true
+ logger?.info(
+ `[motion-photo] XMP detected MotionPhoto flags for ${storageKey}`,
+ )
+ }
+ }
+
+ ;[
+ extractXmpNumber(xmpSegment, 'MicroVideoOffset'),
+ extractXmpNumber(xmpSegment, 'GCamera:MicroVideoOffset'),
+ extractXmpAttributeNumber(xmpSegment, 'MicroVideoOffset'),
+ extractXmpAttributeNumber(xmpSegment, 'GCamera:MicroVideoOffset'),
+ ].forEach((candidate) => addOffsetCandidate(candidate))
+
+ if (presentationTimestampUs === null) {
+ presentationTimestampUs =
+ extractXmpNumber(xmpSegment, 'MotionPhotoPresentationTimestampUs') ??
+ extractXmpNumber(xmpSegment, 'MicroVideoPresentationTimestampUs') ??
+ extractXmpAttributeNumber(
+ xmpSegment,
+ 'MotionPhotoPresentationTimestampUs',
+ ) ??
+ extractXmpAttributeNumber(
+ xmpSegment,
+ 'MicroVideoPresentationTimestampUs',
+ ) ??
+ null
+ }
+ }
+
+ if (!detectedMotion && offsetCandidates.size === 0) {
+ return null
+ }
+
+ let resolvedOffset: number | null = null
+ let videoBuffer: Buffer | null = null
+
+ const candidateList = Array.from(offsetCandidates)
+ for (const candidate of candidateList) {
+ const possibleStarts = new Set<number>()
+ possibleStarts.add(candidate)
+ if (candidate < rawLength) {
+ possibleStarts.add(rawLength - candidate)
+ }
+
+ for (const start of possibleStarts) {
+ if (start <= 0 || start >= rawLength - MIN_VIDEO_SIZE_BYTES) {
+ continue
+ }
+
+ const chunk = rawImageBuffer.subarray(start)
+ if (validateMp4Buffer(chunk)) {
+ resolvedOffset = start
+ videoBuffer = chunk
+ if (start !== candidate && logger?.debug) {
+ logger.debug(
+ `[motion-photo] Interpreted offset ${candidate} as start ${start} from file end for ${storageKey}`,
+ )
+ }
+ break
+ }
+ }
+
+ if (videoBuffer) {
+ break
+ }
+ }
+
+ if (!videoBuffer) {
+ const searchWindowStart = Math.max(0, rawLength - 8 * 1024 * 1024)
+ let cursor = rawImageBuffer.indexOf(MP4_FTYP, searchWindowStart)
+ while (cursor !== -1) {
+ const potentialStart = cursor - 4
+ if (
+ potentialStart > 0 &&
+ potentialStart < rawLength - MIN_VIDEO_SIZE_BYTES
+ ) {
+ const chunk = rawImageBuffer.subarray(potentialStart)
+ if (validateMp4Buffer(chunk)) {
+ resolvedOffset = potentialStart
+ videoBuffer = chunk
+ logger?.info(
+ `[motion-photo] Located MP4 via fallback scan at offset ${potentialStart} for ${storageKey}`,
+ )
+ break
+ }
+ }
+ cursor = rawImageBuffer.indexOf(MP4_FTYP, cursor + 1)
+ }
+ }
+
+ if (!videoBuffer || resolvedOffset === null) {
+ logger?.warn(
+ `[motion-photo] Unable to extract MP4 after trying offsets ${candidateList.join(', ') || 'none'} for ${storageKey}`,
+ )
+ return null
+ }
+
+ // todo: consider storing in a dedicated subfolder
+ // const targetKey = `motion-videos/${photoId}.mp4`
+ const targetKey = `${photoId}.mp4`
+ let storedObject
+ try {
+ storedObject = await storageProvider.create(
+ targetKey,
+ videoBuffer,
+ 'video/mp4',
+ )
+ } catch (error) {
+ logger?.error(
+ `[motion-photo] Failed to persist extracted video for ${storageKey}`,
+ error,
+ )
+ return null
+ }
+
+ const livePhotoVideoKey = storedObject.key || targetKey
+ const livePhotoVideoUrl = storageProvider.getPublicUrl(livePhotoVideoKey)
+
+ logger?.success(
+ `[motion-photo] Extracted Motion Photo video for ${storageKey} at offset ${resolvedOffset}, saved as ${livePhotoVideoKey}`,
+ )
+
+ return {
+ isMotionPhoto: true,
+ livePhotoVideoKey,
+ livePhotoVideoUrl,
+ offset: resolvedOffset,
+ presentationTimestampUs: presentationTimestampUs ?? undefined,
+ }
+ } catch (error) {
+ logger?.error(
+ `[motion-photo] Unexpected error while processing ${storageKey}`,
+ error,
+ )
+ return null
+ }
+}
diff --git a/packages/media/src/processor.ts b/packages/media/src/processor.ts
new file mode 100644
index 00000000..bf460003
--- /dev/null
+++ b/packages/media/src/processor.ts
@@ -0,0 +1,286 @@
+import type { MediaLogger } from './logger.ts'
+import path from 'path'
+import bmp from '@vingle/bmp-js'
+import heicConvert from 'heic-convert'
+import sharp, { type Sharp } from 'sharp'
+import { withRetry, RetryPresets, RetryConditions } from './retry.ts'
+
+export interface ProcessedImageData {
+ sharpInst: Sharp
+ imageBuffer: Buffer
+ metadata: ImageMeta
+}
+
+export interface ImageMeta {
+ width: number
+ height: number
+ format: string
+}
+
+export interface ImageProcessorOptions {
+ /** Defaults preserve existing Self-hosted behavior. */
+ limitInputPixels?: number | boolean
+ maxInputBytes?: number
+ /** Cooperative cancellation; native work must settle before its slot is released. */
+ signal?: AbortSignal
+}
+
+export function createImageProcessor(
+ logger: MediaLogger,
+ options: ImageProcessorOptions = {},
+) {
+ const checkInput = (buffer: Buffer) => {
+ options.signal?.throwIfAborted()
+ if (
+ options.maxInputBytes !== undefined &&
+ buffer.length > options.maxInputBytes
+ ) {
+ throw new RangeError('Media input exceeds configured byte limit')
+ }
+ }
+
+ // Minimal JPEG size extractor as last-resort fallback
+ const tryExtractJpegSize = (
+ buffer: Buffer,
+ ): { width: number; height: number } | null => {
+ // JPEG starts with 0xFFD8
+ if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8)
+ return null
+ let offset = 2
+ while (offset + 9 < buffer.length) {
+ if (buffer[offset] !== 0xff) {
+ offset++
+ continue
+ }
+ const marker = buffer.readUInt8(offset + 1)
+ offset += 2
+ // Skip padding FFs
+ if (marker === 0xff) continue
+ // Standalone markers without length
+ if (marker === 0xd8 || marker === 0xd9) continue
+ const length = buffer.readUInt16BE(offset)
+ if (length < 2) break
+ // SOF0..SOF3 and SOF5..SOF7 indicate dimensions
+ if (
+ (marker >= 0xc0 && marker <= 0xc3) ||
+ (marker >= 0xc5 && marker <= 0xc7)
+ ) {
+ if (offset + 7 >= buffer.length) break
+ const height = buffer.readUInt16BE(offset + 3)
+ const width = buffer.readUInt16BE(offset + 5)
+ if (width > 0 && height > 0) return { width, height }
+ break
+ }
+ offset += length
+ }
+ return null
+ }
+
+ const isBitmap = (buffer: Buffer) => {
+ if (buffer.length < 2) return false
+ const header = buffer.toString('hex', 0, 2)
+ return header === '424d'
+ }
+
+ const getMetadataWithSharp = async (
+ sharpInst: Sharp,
+ ): Promise<ImageMeta | null> => {
+ try {
+ return await withRetry(
+ async () => {
+ options.signal?.throwIfAborted()
+ let metadata = await sharpInst.metadata()
+ options.signal?.throwIfAborted()
+
+ // Fallback 1: try rotate() which can populate dimensions for some orientations
+ if (!metadata.height || !metadata.width || !metadata.format) {
+ try {
+ metadata = await sharpInst.clone().rotate().metadata()
+ } catch {
+ /* empty */
+ }
+ }
+
+ // Fallback 2: re-instantiate sharp from a fresh buffer
+ if (!metadata.height || !metadata.width || !metadata.format) {
+ try {
+ const buf = await sharpInst.clone().toBuffer()
+ metadata = await sharp(buf).metadata()
+ } catch {
+ /* empty */
+ }
+ }
+
+ // Fallback 3: force re-encode to JPEG then read metadata
+ if (!metadata.height || !metadata.width || !metadata.format) {
+ try {
+ const jpegBuf = await sharpInst.clone().jpeg().toBuffer()
+ metadata = await sharp(jpegBuf).metadata()
+ if (!metadata.height || !metadata.width) {
+ const dims = tryExtractJpegSize(jpegBuf)
+ if (dims) {
+ metadata.width = dims.width
+ metadata.height = dims.height
+ metadata.format = metadata.format || 'jpeg'
+ }
+ }
+ } catch {
+ /* empty */
+ }
+ }
+
+ if (!metadata.height || !metadata.width || !metadata.format) {
+ logger.warn('Incomplete metadata received:', {
+ hasHeight: !!metadata.height,
+ hasWidth: !!metadata.width,
+ hasFormat: !!metadata.format,
+ })
+ return null
+ }
+
+ const { orientation } = metadata
+ let { width, height } = metadata
+
+ if (orientation && [5, 6, 7, 8].includes(orientation)) {
+ ;[width, height] = [height, width]
+ }
+
+ logger.info(
+ `Successfully extracted metadata: ${width}x${height} ${metadata.format}`,
+ )
+ return {
+ width: width,
+ height: height,
+ format: metadata.format,
+ }
+ },
+ {
+ ...RetryPresets.fast,
+ timeout: 10000,
+ retryCondition: RetryConditions.resourceErrors,
+ },
+ logger,
+ )
+ } catch (error) {
+ logger.error('All metadata extraction attempts failed:', error)
+ return null
+ }
+ }
+
+ const convertHeicToJpeg = async (heicBuffer: Buffer) => {
+ checkInput(heicBuffer)
+ return await withRetry(
+ async () => {
+ // 检查文件大小,如果太大则降低质量
+ const fileSizeMB = heicBuffer.length / (1024 * 1024)
+ const quality = fileSizeMB > 10 ? 0.8 : 0.95
+
+ const jpegBuffer = await heicConvert({
+ buffer: heicBuffer,
+ format: 'JPEG',
+ quality,
+ })
+
+ logger.info(`Successfully converted HEIC to JPEG (quality: ${quality})`)
+ options.signal?.throwIfAborted()
+ return Buffer.from(jpegBuffer)
+ },
+ {
+ ...RetryPresets.slow, // HEIC 转换是重量级操作
+ timeout: 30000,
+ retryCondition: (error) => {
+ // HEIC 转换错误通常是资源相关的
+ return (
+ RetryConditions.resourceErrors(error) ||
+ error.message.includes('memory') ||
+ error.message.includes('timeout')
+ )
+ },
+ },
+ logger,
+ )
+ }
+
+ const convertBitmapToSharpInst = async (bitmapBuffer: Buffer) => {
+ checkInput(bitmapBuffer)
+ logger.info('Converting Bitmap to JPEG...')
+ const bmpImage = bmp.decode(bitmapBuffer, true)
+ if (!bmpImage) {
+ throw new Error('Failed to decode BMP image')
+ }
+
+ const channels = bmpImage.data.length / (bmpImage.width * bmpImage.height)
+ if (channels !== 3 && channels !== 4) {
+ throw new Error(`Unsupported BMP channel count: ${channels}`)
+ }
+
+ return sharp(bmpImage.data, {
+ raw: { width: bmpImage.width, height: bmpImage.height, channels },
+ }).jpeg()
+ }
+
+ const preprocessImageBuffer = async (
+ buffer: Buffer,
+ key: string,
+ ): Promise<Buffer> => {
+ checkInput(buffer)
+ const extName = path.extname(key).toLowerCase()
+
+ if (['.heic', '.heif', '.hif'].includes(extName)) {
+ logger.info('HEIC image detected', key)
+ return await convertHeicToJpeg(buffer)
+ }
+
+ return buffer
+ }
+
+ const processImageMetadataAndSharp = async (
+ buffer: Buffer,
+ s3key: string,
+ ): Promise<ProcessedImageData | null> => {
+ try {
+ // Preserve the legacy default unless the caller supplies a pixel limit.
+ checkInput(buffer)
+ let sharpInst = sharp(buffer, {
+ limitInputPixels: options.limitInputPixels ?? false,
+ })
+ let convertedBuffer = buffer
+
+ if (isBitmap(buffer)) {
+ logger.info('Bitmap image detected, converting to JPEG...', s3key)
+ try {
+ sharpInst = await convertBitmapToSharpInst(buffer)
+ convertedBuffer = await sharpInst.toBuffer()
+ } catch (err) {
+ logger.error(`Bitmap conversion failed: ${s3key}`, err)
+ return null
+ }
+ }
+
+ const metadata = await getMetadataWithSharp(sharpInst)
+ if (!metadata) {
+ logger.error(
+ 'Metadata extraction returned null (after fallbacks):',
+ s3key,
+ )
+ return null
+ }
+
+ return {
+ sharpInst,
+ imageBuffer: convertedBuffer,
+ metadata,
+ }
+ } catch (err) {
+ logger.error(`Image processing with Sharp failed: ${s3key}`, err)
+ return null
+ }
+ }
+
+ return {
+ convertHeicToJpeg,
+ convertBitmapToSharpInst,
+ preprocessImageBuffer,
+ processImageMetadataAndSharp,
+ }
+}
diff --git a/packages/media/src/retry.ts b/packages/media/src/retry.ts
new file mode 100644
index 00000000..de9a093c
--- /dev/null
+++ b/packages/media/src/retry.ts
@@ -0,0 +1,250 @@
+import type { MediaLogger } from './logger.ts'
+/**
+ * 重试配置选项
+ */
+export interface RetryOptions {
+ /** 最大重试次数,默认 3 */
+ maxAttempts?: number
+ /** 基础延迟时间(毫秒),默认 1000ms */
+ baseDelay?: number
+ /** 最大延迟时间(毫秒),默认 30000ms */
+ maxDelay?: number
+ /** 协作式操作超时(毫秒),默认 30000ms;操作需响应 AbortSignal,否则等待其结束 */
+ timeout?: number
+ /** 重试条件判断函数,返回 true 表示应该重试 */
+ retryCondition?: (error: Error) => boolean
+ /** 延迟策略:'exponential' 指数退避,'linear' 线性增长,'fixed' 固定延迟 */
+ delayStrategy?: 'exponential' | 'linear' | 'fixed'
+}
+
+/**
+ * 通用重试工具函数
+ *
+ * @param operation 要执行的异步操作;应响应 AbortSignal 以支持取消。无法取消的操作会等待结束再重试,避免重叠执行。
+ * @param options 重试配置选项
+ * @param logger 可选的日志记录器
+ * @returns 操作结果
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ * () => fetchDataFromAPI(),
+ * {
+ * maxAttempts: 3,
+ * timeout: 5000,
+ * retryCondition: (error) => !error.message.includes('400')
+ * },
+ * logger.api
+ * )
+ * ```
+ */
+export async function withRetry<T>(
+ operation: (signal: AbortSignal) => Promise<T>,
+ options: RetryOptions = {},
+ logger?: MediaLogger,
+): Promise<T> {
+ const {
+ maxAttempts = 3,
+ baseDelay = 1000,
+ maxDelay = 30000,
+ timeout = 30000,
+ retryCondition = () => true,
+ delayStrategy = 'exponential',
+ } = options
+
+ let lastError: Error
+
+ for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+ const controller = new AbortController()
+ let timer: ReturnType<typeof setTimeout> | undefined
+ try {
+ logger?.info(`Operation attempt ${attempt}/${maxAttempts}`)
+
+ // 应用超时机制
+ const timeoutError = new Error(`Operation timeout after ${timeout}ms`)
+ timer = setTimeout(() => {
+ controller.abort(timeoutError)
+ logger?.warn(
+ `Operation exceeded ${timeout}ms; cancellation requested. Waiting for it to settle before releasing the resource slot or retrying.`,
+ )
+ }, timeout)
+ // Keep the resource slot until non-cancellable operations settle. Racing
+ // them against a timer would allow retries to overlap the original work.
+ const result = await operation(controller.signal)
+ if (controller.signal.aborted) throw timeoutError
+
+ if (attempt > 1) {
+ logger?.success(`Operation succeeded on attempt ${attempt}`)
+ }
+ return result
+ } catch (error) {
+ if (timer) clearTimeout(timer)
+ lastError = controller.signal.aborted
+ ? controller.signal.reason
+ : error instanceof Error
+ ? error
+ : new Error(String(error))
+ logger?.warn(`Attempt ${attempt} failed:`, error)
+
+ const shouldRetry = attempt < maxAttempts && retryCondition(lastError)
+ if (!shouldRetry) {
+ logger?.error(`Operation failed after ${attempt} attempt(s)`)
+ throw lastError
+ }
+ const delay = calculateDelay(attempt, baseDelay, maxDelay, delayStrategy)
+ logger?.info(`Retrying in ${delay}ms...`)
+ await new Promise((resolve) => setTimeout(resolve, delay))
+ } finally {
+ if (timer) clearTimeout(timer)
+ }
+ }
+
+ logger?.error(`All ${maxAttempts} attempts failed`)
+ throw lastError!
+}
+
+/**
+ * 计算延迟时间
+ */
+function calculateDelay(
+ attempt: number,
+ baseDelay: number,
+ maxDelay: number,
+ strategy: 'exponential' | 'linear' | 'fixed',
+): number {
+ let delay: number
+
+ switch (strategy) {
+ case 'exponential':
+ // 指数退避:1s, 2s, 4s, 8s...
+ delay = baseDelay * Math.pow(2, attempt - 1)
+ break
+ case 'linear':
+ // 线性增长:1s, 2s, 3s, 4s...
+ delay = baseDelay * attempt
+ break
+ case 'fixed':
+ // 固定延迟:1s, 1s, 1s, 1s...
+ delay = baseDelay
+ break
+ default:
+ delay = baseDelay
+ }
+
+ return Math.min(delay, maxDelay)
+}
+
+/**
+ * 常见错误的重试条件预设
+ */
+export const RetryConditions = {
+ /** 网络错误重试(排除 4xx 客户端错误) */
+ networkErrors: (error: Error) => {
+ const message = error.message.toLowerCase()
+ // 不重试客户端错误 (4xx)
+ if (
+ message.includes('400') ||
+ message.includes('401') ||
+ message.includes('403') ||
+ message.includes('404')
+ ) {
+ return false
+ }
+ // 重试网络相关错误
+ return (
+ message.includes('timeout') ||
+ message.includes('network') ||
+ message.includes('fetch') ||
+ message.includes('econnreset') ||
+ message.includes('enotfound') ||
+ message.includes('502') ||
+ message.includes('503') ||
+ message.includes('504')
+ )
+ },
+
+ /** 文件系统错误重试(排除权限和不存在错误) */
+ fileSystemErrors: (error: Error) => {
+ const message = error.message.toLowerCase()
+ // 不重试权限和文件不存在错误
+ if (
+ message.includes('eacces') ||
+ message.includes('enoent') ||
+ message.includes('permission denied')
+ ) {
+ return false
+ }
+ // 重试临时性文件系统错误
+ return (
+ message.includes('ebusy') ||
+ message.includes('emfile') ||
+ message.includes('enfile') ||
+ message.includes('eagain')
+ )
+ },
+
+ /** 资源竞争错误重试 */
+ resourceErrors: (error: Error) => {
+ const message = error.message.toLowerCase()
+ return (
+ message.includes('busy') ||
+ message.includes('locked') ||
+ message.includes('resource') ||
+ message.includes('memory') ||
+ message.includes('cpu')
+ )
+ },
+
+ /** 始终重试 */
+ always: () => true,
+
+ /** 从不重试 */
+ never: () => false,
+}
+
+/**
+ * 重试配置预设
+ */
+export const RetryPresets = {
+ /** 快速重试:适用于轻量级操作 */
+ fast: {
+ maxAttempts: 3,
+ baseDelay: 500,
+ timeout: 5000,
+ delayStrategy: 'exponential' as const,
+ },
+
+ /** 标准重试:适用于一般操作 */
+ standard: {
+ maxAttempts: 3,
+ baseDelay: 1000,
+ timeout: 10000,
+ delayStrategy: 'exponential' as const,
+ },
+
+ /** 网络重试:适用于网络请求 */
+ network: {
+ maxAttempts: 3,
+ baseDelay: 1000,
+ timeout: 30000,
+ delayStrategy: 'exponential' as const,
+ retryCondition: RetryConditions.networkErrors,
+ },
+
+ /** 文件操作重试:适用于文件系统操作 */
+ fileSystem: {
+ maxAttempts: 5,
+ baseDelay: 500,
+ timeout: 15000,
+ delayStrategy: 'linear' as const,
+ retryCondition: RetryConditions.fileSystemErrors,
+ },
+
+ /** 慢速重试:适用于重量级操作 */
+ slow: {
+ maxAttempts: 3,
+ baseDelay: 2000,
+ timeout: 60000,
+ delayStrategy: 'exponential' as const,
+ },
+}
diff --git a/packages/media/src/thumbnail.ts b/packages/media/src/thumbnail.ts
new file mode 100644
index 00000000..5cd0d2dc
--- /dev/null
+++ b/packages/media/src/thumbnail.ts
@@ -0,0 +1,40 @@
+import type { MediaLogger } from './logger.ts'
+import sharp from 'sharp'
+import { generateBlurHash } from './blurhash.ts'
+import { withRetry, RetryPresets } from './retry.ts'
+
+export const generateThumbnailAndHash = async (
+ buffer: Buffer,
+ logger?: MediaLogger,
+) => {
+ return await withRetry(
+ async () => {
+ const sharpInst = sharp(buffer).rotate()
+
+ // 根据文件大小调整缩略图质量
+ const fileSizeMB = buffer.length / (1024 * 1024)
+ const quality = fileSizeMB > 5 ? 85 : 100
+
+ const thumbnailBuffer = await sharpInst
+ .resize(600, null, {
+ withoutEnlargement: true,
+ fastShrinkOnLoad: false, // 提高质量
+ })
+ .webp({ quality })
+ .toBuffer()
+
+ logger?.info(`Successfully generated thumbnail (quality: ${quality})`)
+
+ // 生成BlurHash
+ const thumbnailHash = await generateBlurHash(thumbnailBuffer, logger)
+
+ return { thumbnailBuffer, thumbnailHash }
+ },
+ {
+ ...RetryPresets.standard,
+ timeout: 15000,
+ delayStrategy: 'linear', // 图像处理适合线性退避
+ },
+ logger,
+ )
+}
diff --git a/packages/media/tsconfig.json b/packages/media/tsconfig.json
new file mode 100644
index 00000000..e79cde15
--- /dev/null
+++ b/packages/media/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "noEmit": true,
+ "allowImportingTsExtensions": true,
+ "types": ["node"],
+ "lib": ["ES2022", "DOM"],
+ "skipLibCheck": true,
+ "noUncheckedIndexedAccess": true
+ },
+ "include": ["src/**/*.ts"]
+}
diff --git a/packages/storage/README.md b/packages/storage/README.md
new file mode 100644
index 00000000..a87ea02a
--- /dev/null
+++ b/packages/storage/README.md
@@ -0,0 +1,13 @@
+# @chronoframe/storage
+
+Instance-scoped storage providers for Self-hosted and future cloud entry points.
+
+Import from `@chronoframe/storage` or its declared provider/interface subpaths.
+Construct `StorageManager` with explicit configuration and an optional structural
+logger. The application owns global instances, configuration reloads and Nitro
+lifecycle. Local, S3 and OpenList retain their existing behavior and capabilities.
+Configuration and errors may contain sensitive information: only trusted server
+code should instantiate providers or access configuration. Upload lifecycle logs
+keep the existing sanitized metadata policy.
+
+Run `pnpm check:packages` and `pnpm test` from the workspace root.
diff --git a/packages/storage/package.json b/packages/storage/package.json
new file mode 100644
index 00000000..849c96ea
--- /dev/null
+++ b/packages/storage/package.json
@@ -0,0 +1,26 @@
+{
+ "name": "@chronoframe/storage",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts",
+ "./interfaces": "./src/interfaces.ts",
+ "./manager": "./src/manager.ts",
+ "./providers/local": "./src/providers/local.ts",
+ "./providers/s3": "./src/providers/s3.ts",
+ "./providers/openlist": "./src/providers/openlist.ts"
+ },
+ "scripts": {
+ "type-check": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@chronoframe/contracts": "workspace:*",
+ "@aws-sdk/client-s3": "^3.1149.0",
+ "@aws-sdk/s3-request-presigner": "^3.1149.0"
+ },
+ "devDependencies": {
+ "@types/node": "^22.20.5",
+ "typescript": "^5.9.3"
+ }
+}
diff --git a/packages/storage/src/index.ts b/packages/storage/src/index.ts
new file mode 100644
index 00000000..b621e4f7
--- /dev/null
+++ b/packages/storage/src/index.ts
@@ -0,0 +1,7 @@
+export * from './interfaces.ts'
+export * from './manager.ts'
+export type { StorageLogger } from './logger.ts'
+export * from '@chronoframe/contracts/storage'
+export * from './providers/local.ts'
+export * from './providers/s3.ts'
+export * from './providers/openlist.ts'
diff --git a/packages/storage/src/interfaces.ts b/packages/storage/src/interfaces.ts
new file mode 100644
index 00000000..a422fe5f
--- /dev/null
+++ b/packages/storage/src/interfaces.ts
@@ -0,0 +1,56 @@
+import type { StorageConfig } from '@chronoframe/contracts/storage'
+import type { UploadPart, UploadPlan } from '@chronoframe/contracts/upload'
+
+export type DirectUploadSetup =
+ | Extract<UploadPlan, { mode: 'single' | 'range' }>
+ | {
+ mode: 'multipart'
+ partSize: number
+ partUrls: string[]
+ complete(parts: UploadPart[]): Promise<void>
+ abort(): Promise<void>
+ }
+
+export interface StorageObject {
+ key: string
+ size?: number
+ etag?: string
+ lastModified?: Date
+}
+
+export interface UploadOptions {
+ contentType?: string
+ metadata?: Record<string, string>
+ encryption?: boolean
+ ttl?: number
+}
+
+export interface StorageProvider {
+ config?: StorageConfig
+ prepareDirectUpload?(
+ key: string,
+ size: number,
+ contentType: string,
+ ): Promise<DirectUploadSetup | null>
+ createFromFile(
+ key: string,
+ filePath: string,
+ contentType: string,
+ ): Promise<StorageObject>
+ create(
+ key: string,
+ fileBuffer: Buffer,
+ contentType?: string,
+ ): Promise<StorageObject>
+ delete(key: string): Promise<void>
+ get(key: string): Promise<Buffer | null>
+ getPublicUrl(key: string): string
+ getSignedUrl?(
+ key: string,
+ expiresIn?: number,
+ options?: UploadOptions,
+ ): Promise<string>
+ getFileMeta(key: string): Promise<StorageObject | null>
+ listAll(): Promise<StorageObject[]>
+ listImages(): Promise<StorageObject[]>
+}
diff --git a/packages/storage/src/logger.ts b/packages/storage/src/logger.ts
new file mode 100644
index 00000000..5a194278
--- /dev/null
+++ b/packages/storage/src/logger.ts
@@ -0,0 +1,9 @@
+/** Structural logger: applications own sinks, tags and credentials redaction. */
+export interface StorageLogger {
+ info(...args: any[]): void
+ warn(...args: any[]): void
+ error(...args: any[]): void
+ debug(...args: any[]): void
+ success(...args: any[]): void
+ log(...args: any[]): void
+}
diff --git a/packages/storage/src/manager.ts b/packages/storage/src/manager.ts
new file mode 100644
index 00000000..cc8d0149
--- /dev/null
+++ b/packages/storage/src/manager.ts
@@ -0,0 +1,173 @@
+import type { StorageLogger } from './logger.ts'
+import type { StorageConfig } from '@chronoframe/contracts/storage'
+import type { StorageProvider } from './interfaces.ts'
+import { S3StorageProvider } from './providers/s3.ts'
+import { LocalStorageProvider } from './providers/local.ts'
+import { OpenListStorageProvider } from './providers/openlist.ts'
+
+export type StorageManagerEventType = 'provider-changed' | 'provider-error'
+
+export interface StorageManagerEventListener {
+ (event: StorageManagerEvent): void | Promise<void>
+}
+
+export interface StorageManagerEvent {
+ type: StorageManagerEventType
+ provider?: string
+ oldProvider?: string
+ error?: Error
+ timestamp: number
+}
+
+export class StorageProviderFactory {
+ static createProvider(
+ config: StorageConfig,
+ logger?: StorageLogger,
+ ): StorageProvider {
+ switch (config.provider) {
+ case 's3':
+ return new S3StorageProvider(config, logger)
+ case 'local':
+ return new LocalStorageProvider(config, logger)
+ case 'openlist':
+ return new OpenListStorageProvider(config as any, logger)
+ default:
+ throw new Error(`Unknown storage provider`)
+ }
+ }
+}
+
+export class StorageManager {
+ private provider: StorageProvider
+ private logger?: StorageLogger
+ private eventListeners: Map<
+ StorageManagerEventType,
+ StorageManagerEventListener[]
+ > = new Map()
+ private currentProviderName?: string
+
+ constructor(config: StorageConfig, logger?: StorageLogger) {
+ this.logger = logger
+ this.logger?.info(`Creating storage provider: ${config.provider}`)
+ this.currentProviderName = config.provider
+ this.provider = StorageProviderFactory.createProvider(config, logger)
+ }
+
+ /**
+ * Register event listener for storage manager events
+ * @param eventType Type of event to listen for
+ * @param listener Event listener callback
+ */
+ public on(
+ eventType: StorageManagerEventType,
+ listener: StorageManagerEventListener,
+ ): void {
+ if (!this.eventListeners.has(eventType)) {
+ this.eventListeners.set(eventType, [])
+ }
+ this.eventListeners.get(eventType)!.push(listener)
+ this.logger?.debug(`Event listener registered for: ${eventType}`)
+ }
+
+ /**
+ * Unregister event listener
+ * @param eventType Type of event
+ * @param listener Event listener callback
+ */
+ public off(
+ eventType: StorageManagerEventType,
+ listener: StorageManagerEventListener,
+ ): void {
+ const listeners = this.eventListeners.get(eventType)
+ if (listeners) {
+ const index = listeners.indexOf(listener)
+ if (index > -1) {
+ listeners.splice(index, 1)
+ this.logger?.debug(`Event listener unregistered for: ${eventType}`)
+ }
+ }
+ }
+
+ /**
+ * Emit event to all registered listeners
+ * @param event Event to emit
+ */
+ private async emitEvent(event: StorageManagerEvent): Promise<void> {
+ const listeners = this.eventListeners.get(event.type) || []
+ for (const listener of listeners) {
+ try {
+ await listener(event)
+ } catch (error) {
+ this.logger?.error(`Error in event listener for ${event.type}:`, error)
+ }
+ }
+ }
+
+ /**
+ * Register/switch storage provider
+ * @param config New storage configuration
+ * @param logger Optional logger instance
+ */
+ async registerProvider(
+ config: StorageConfig,
+ logger?: StorageLogger,
+ ): Promise<void> {
+ try {
+ const oldProviderName = this.currentProviderName
+ this.logger = logger || this.logger
+
+ this.logger?.info(
+ `Switching storage provider from ${oldProviderName} to ${config.provider}`,
+ )
+
+ const newProvider = StorageProviderFactory.createProvider(
+ config,
+ this.logger,
+ )
+ this.provider = newProvider
+ this.currentProviderName = config.provider
+
+ this.logger?.success(`Storage provider switched to: ${config.provider}`)
+
+ // Emit provider-changed event
+ await this.emitEvent({
+ type: 'provider-changed',
+ provider: config.provider,
+ oldProvider: oldProviderName,
+ timestamp: Date.now(),
+ })
+ } catch (error) {
+ this.logger?.error(
+ `Failed to register storage provider: ${config.provider}`,
+ error,
+ )
+
+ // Emit provider-error event
+ await this.emitEvent({
+ type: 'provider-error',
+ provider: config.provider,
+ error: error as Error,
+ timestamp: Date.now(),
+ })
+
+ throw error
+ }
+ }
+
+ /**
+ * Get current storage provider
+ */
+ getProvider<T extends StorageProvider>(): T {
+ if (!this.provider) {
+ throw new Error(`Storage provider not registered`)
+ }
+ return this.provider as T
+ }
+
+ /**
+ * Get current provider name
+ */
+ getCurrentProviderName(): string | undefined {
+ return this.currentProviderName
+ }
+}
diff --git a/packages/storage/src/providers/local.ts b/packages/storage/src/providers/local.ts
new file mode 100644
index 00000000..5496378e
--- /dev/null
+++ b/packages/storage/src/providers/local.ts
@@ -0,0 +1,148 @@
+import type { LocalStorageConfig } from '@chronoframe/contracts/storage'
+import type { StorageLogger } from '../logger.ts'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import type { StorageObject, StorageProvider } from '../interfaces.ts'
+
+const ensureDir = async (dirPath: string) => {
+ await fs.mkdir(dirPath, { recursive: true })
+}
+
+const sanitizeKey = (key: string) =>
+ key.replace(/\\/g, '/').replace(/\/+/g, '/').replace(/^\/+/, '')
+
+const combinePrefixAndKey = (prefix: string | undefined, key: string) => {
+ const cleanPrefix = (prefix || '').replace(/^\/+|\/+$/g, '')
+ const cleanKey = key.replace(/^\/+/, '')
+ if (!cleanPrefix) return cleanKey
+ return cleanKey.startsWith(cleanPrefix + '/')
+ ? cleanKey
+ : `${cleanPrefix}/${cleanKey}`
+}
+
+export class LocalStorageProvider implements StorageProvider {
+ config: LocalStorageConfig
+ private logger?: StorageLogger
+
+ constructor(config: LocalStorageConfig, logger?: StorageLogger) {
+ this.config = config
+ this.logger = logger
+ }
+
+ private resolveAbsoluteKey(key: string): { absFile: string; relKey: string } {
+ const relKey = sanitizeKey(combinePrefixAndKey(this.config.prefix, key))
+ const absFile = path.resolve(this.config.basePath, relKey)
+ return { absFile, relKey }
+ }
+
+ async create(key: string, fileBuffer: Buffer): Promise<StorageObject> {
+ const { absFile, relKey } = this.resolveAbsoluteKey(key)
+ await ensureDir(path.dirname(absFile))
+ // 原子写入:写到临时文件再重命名
+ const tempFile = `${absFile}.tmp-${Date.now()}`
+ await fs.writeFile(tempFile, fileBuffer)
+ await fs.rename(tempFile, absFile)
+ const stat = await fs.stat(absFile)
+ this.logger?.success?.(`Saved file: ${absFile}`)
+ return {
+ key: relKey,
+ size: stat.size,
+ lastModified: stat.mtime,
+ }
+ }
+
+ async createFromFile(key: string, filePath: string): Promise<StorageObject> {
+ const { absFile, relKey } = this.resolveAbsoluteKey(key)
+ await ensureDir(path.dirname(absFile))
+ const tempFile = `${absFile}.tmp-${crypto.randomUUID()}`
+ try {
+ await fs.copyFile(filePath, tempFile)
+ await fs.rename(tempFile, absFile)
+ const stat = await fs.stat(absFile)
+ return { key: relKey, size: stat.size, lastModified: stat.mtime }
+ } finally {
+ await fs.rm(tempFile, { force: true })
+ }
+ }
+
+ async delete(key: string): Promise<void> {
+ const { absFile } = this.resolveAbsoluteKey(key)
+ try {
+ await fs.unlink(absFile)
+ this.logger?.success?.(`Deleted file: ${absFile}`)
+ } catch (err) {
+ // ignore if not exists
+ if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+ }
+ }
+
+ async get(key: string): Promise<Buffer | null> {
+ const { absFile } = this.resolveAbsoluteKey(key)
+ try {
+ return await fs.readFile(absFile)
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
+ throw err
+ }
+ }
+
+ getPublicUrl(key: string): string {
+ const relKey = sanitizeKey(combinePrefixAndKey(this.config.prefix, key))
+ const base = (this.config.baseUrl || '/storage').replace(/\/+$/, '')
+ return `${base}/${relKey}`
+ }
+
+ async listAll(): Promise<StorageObject[]> {
+ const results: StorageObject[] = []
+ const baseDir = this.config.prefix
+ ? path.resolve(this.config.basePath, this.config.prefix)
+ : this.config.basePath
+
+ const walk = async (dir: string, relBase: string) => {
+ const entries = await fs.readdir(dir, { withFileTypes: true })
+ for (const entry of entries) {
+ const abs = path.join(dir, entry.name)
+ const rel = sanitizeKey(path.join(relBase, entry.name))
+ if (entry.isDirectory()) {
+ await walk(abs, rel)
+ } else if (entry.isFile()) {
+ const stat = await fs.stat(abs)
+ results.push({ key: rel, size: stat.size, lastModified: stat.mtime })
+ }
+ }
+ }
+
+ await ensureDir(baseDir)
+ await walk(baseDir, this.config.prefix || '')
+ return results
+ }
+
+ async listImages(): Promise<StorageObject[]> {
+ const all = await this.listAll()
+ return all.filter((o) => /\.(png|jpe?g|webp|gif|bmp|tiff?)$/i.test(o.key))
+ }
+
+ async getFileMeta(key: string): Promise<StorageObject | null> {
+ // First try with combined prefix
+ const { absFile, relKey } = this.resolveAbsoluteKey(key)
+ try {
+ const stat = await fs.stat(absFile)
+ if (!stat.isFile()) return null
+ return { key: relKey, size: stat.size, lastModified: stat.mtime }
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+ }
+
+ // Fallback: try without adding prefix (in case key already contains it or was stored raw)
+ const rawRel = sanitizeKey(key)
+ const rawAbs = path.resolve(this.config.basePath, rawRel)
+ try {
+ const stat = await fs.stat(rawAbs)
+ if (!stat.isFile()) return null
+ return { key: rawRel, size: stat.size, lastModified: stat.mtime }
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
+ throw err
+ }
+ }
+}
diff --git a/packages/storage/src/providers/openlist.ts b/packages/storage/src/providers/openlist.ts
new file mode 100644
index 00000000..90ed702f
--- /dev/null
+++ b/packages/storage/src/providers/openlist.ts
@@ -0,0 +1,393 @@
+import type { OpenListStorageConfig } from '@chronoframe/contracts/storage'
+import type { StorageLogger } from '../logger.ts'
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import type {
+ StorageProvider,
+ StorageObject,
+ DirectUploadSetup,
+} from '../interfaces.ts'
+import path from 'node:path'
+
+/**
+ * OpenListStorageProvider implements StorageProvider for OpenList API.
+ * Since OpenList API endpoints may vary by deployment, we keep them configurable.
+ */
+export class OpenListStorageProvider implements StorageProvider {
+ config: OpenListStorageConfig
+ private logger?: StorageLogger
+ private token?: string
+
+ constructor(config: OpenListStorageConfig, logger?: StorageLogger) {
+ this.config = config
+ this.logger = logger
+ }
+
+ private get baseUrl() {
+ return this.config.baseUrl.replace(/\/$/, '')
+ }
+
+ private get pathField(): string {
+ return this.config.pathField || 'path'
+ }
+
+ private async ensureAuthToken(): Promise<string> {
+ if (this.token) return this.token
+ if (this.config.token) {
+ this.token = this.config.token
+ return this.token
+ }
+
+ throw new Error(
+ 'OpenList auth requires a token. Please configure NUXT_PROVIDER_OPENLIST_TOKEN.',
+ )
+ }
+
+ private async request(
+ path: string,
+ init: RequestInit = {},
+ ): Promise<Response> {
+ const token = await this.ensureAuthToken()
+ const url = `${this.baseUrl}${path}`
+ const headers: Record<string, string> = {
+ ...(init.headers as Record<string, string> | undefined),
+ Authorization: token,
+ }
+ return fetch(url, { ...init, headers })
+ }
+
+ private normalizedRoot(): string {
+ return (this.config.rootPath || '').replace(/\/+$/g, '').replace(/^\/+/, '')
+ }
+
+ private withRoot(key: string): string {
+ const root = this.normalizedRoot()
+ const trimmedKey = key.replace(/^\/+/, '')
+ if (!root) {
+ return trimmedKey
+ }
+ if (trimmedKey === root || trimmedKey.startsWith(`${root}/`)) {
+ return trimmedKey
+ }
+ return `${root}/${trimmedKey}`
+ }
+
+ private toAbsolutePath(key: string): string {
+ if (!key || key === '/') {
+ return '/'
+ }
+ return key.startsWith('/') ? key : `/${key}`
+ }
+
+ async create(
+ key: string,
+ fileBuffer: Buffer,
+ contentType?: string,
+ ): Promise<StorageObject> {
+ const rootedKey = this.withRoot(key)
+ const absoluteKey = this.toAbsolutePath(rootedKey)
+ const uploadPath = this.config.uploadEndpoint || '/api/fs/put'
+
+ const resp = await this.request(uploadPath, {
+ method: 'PUT',
+ headers: {
+ 'Content-Type': contentType || 'application/octet-stream',
+ 'Content-Length': String(fileBuffer.length),
+ 'File-Path': encodeURIComponent(absoluteKey),
+ },
+ body: new Uint8Array(fileBuffer),
+ })
+
+ if (!resp.ok) {
+ const text = await resp.text().catch(() => '')
+ this.logger?.error('OpenList upload failed', {
+ status: resp.status,
+ body: text,
+ })
+ throw new Error(`OpenList upload failed: ${resp.status}`)
+ }
+
+ this.logger?.success(`Uploaded object: ${absoluteKey}`)
+ this.logger?.debug?.('OpenList upload details', {
+ originalKey: key,
+ rootedKey,
+ absoluteKey,
+ rootPath: this.normalizedRoot(),
+ })
+
+ const meta = await this.getFileMeta(rootedKey).catch((error) => {
+ this.logger?.warn('Uploaded object metadata lookup failed:', error)
+ return null
+ })
+ return (
+ meta || {
+ key: rootedKey,
+ size: fileBuffer.length,
+ lastModified: new Date(),
+ }
+ )
+ }
+
+ async delete(key: string): Promise<void> {
+ const deletePath = this.config.deleteEndpoint || '/api/fs/remove'
+ const urlPath = `${deletePath}`
+ const rootedKey = this.withRoot(key)
+ const normalized = rootedKey.replace(/^\/+/, '')
+ const slashIdx = normalized.lastIndexOf('/')
+ const dir = this.toAbsolutePath(
+ slashIdx >= 0 ? normalized.slice(0, slashIdx) : this.normalizedRoot(),
+ )
+ const name = slashIdx >= 0 ? normalized.slice(slashIdx + 1) : normalized
+ const body = { dir, names: [name] }
+
+ const resp = await this.request(urlPath, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ })
+ if (!resp.ok) {
+ const text = await resp.text().catch(() => '')
+ this.logger?.error('OpenList delete failed', {
+ status: resp.status,
+ body: text,
+ })
+ throw new Error(`OpenList delete failed: ${resp.status}`)
+ }
+ this.logger?.success(`Deleted object: ${key}`)
+ }
+
+ async createFromFile(
+ key: string,
+ filePath: string,
+ contentType: string,
+ ): Promise<StorageObject> {
+ const { size } = await stat(filePath)
+ const body = createReadStream(filePath)
+ try {
+ const init = {
+ method: 'PUT',
+ duplex: 'half',
+ headers: {
+ 'Content-Type': contentType,
+ 'Content-Length': String(size),
+ 'File-Path': encodeURIComponent(
+ this.toAbsolutePath(this.withRoot(key)),
+ ),
+ },
+ body,
+ }
+ const response = await this.request(
+ this.config.uploadEndpoint || '/api/fs/put',
+ init as unknown as RequestInit,
+ )
+ if (!response.ok)
+ throw new Error(`OpenList upload failed: ${response.status}`)
+ const result = (await response.json()) as {
+ code?: number
+ message?: string
+ }
+ if (result.code !== undefined && result.code !== 200)
+ throw new Error(result.message || 'OpenList upload failed')
+ return { key: this.withRoot(key), size }
+ } finally {
+ body.destroy()
+ }
+ }
+
+ async prepareDirectUpload(
+ key: string,
+ size: number,
+ ): Promise<DirectUploadSetup | null> {
+ const absoluteKey = this.toAbsolutePath(this.withRoot(key))
+ const response = await this.request('/api/fs/get_direct_upload_info', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ path: path.posix.dirname(absoluteKey),
+ file_name: path.posix.basename(absoluteKey),
+ file_size: size,
+ tool: 'HttpDirect',
+ }),
+ })
+ if ([404, 405, 501].includes(response.status)) return null
+ if (!response.ok)
+ throw new Error(
+ `OpenList direct upload preparation failed: ${response.status}`,
+ )
+ const result = (await response.json()) as {
+ code: number
+ message?: string
+ data?: {
+ upload_url?: string
+ chunk_size?: number
+ method?: string
+ headers?: Record<string, string>
+ } | null
+ }
+ if (result.code !== 200) {
+ if (
+ [404, 405, 501].includes(result.code) ||
+ /not supported|unsupported|not implement/i.test(result.message || '')
+ )
+ return null
+ throw new Error(
+ result.message || 'OpenList direct upload preparation failed',
+ )
+ }
+ const info = result.data
+ if (!info?.upload_url) return null
+ if (info.method && !['PUT', 'POST'].includes(info.method.toUpperCase()))
+ return null
+ const url = new URL(info.upload_url)
+ if (!['http:', 'https:'].includes(url.protocol))
+ throw new Error('Invalid OpenList upload URL')
+ const token = await this.ensureAuthToken()
+ if (
+ info.upload_url.includes(token) ||
+ Object.values(info.headers || {}).some((value) => value.includes(token))
+ ) {
+ throw new Error('OpenList direct upload returned the server credential')
+ }
+ const common = {
+ url: info.upload_url,
+ method: (info.method?.toUpperCase() || 'PUT') as 'PUT' | 'POST',
+ headers: info.headers,
+ }
+ if ((info.chunk_size ?? 0) > 0) {
+ if (!Number.isSafeInteger(info.chunk_size))
+ throw new Error('Invalid OpenList upload chunk size')
+ // OpenList's HttpDirect protocol uses sequential Content-Range requests.
+ // It does not advertise random-order/concurrent writes to this URL.
+ return { mode: 'range', partSize: info.chunk_size!, ...common }
+ }
+ return { mode: 'single', ...common }
+ }
+
+ async get(key: string): Promise<Buffer | null> {
+ // If download endpoint is not provided, try to resolve raw_url via meta and fetch it
+ const downloadPath = this.config.downloadEndpoint
+ if (!downloadPath) {
+ const info = await this.getFileMeta(this.withRoot(key))
+ const rawUrl = (info as any)?.raw_url || undefined
+ if (!rawUrl) return null
+ const resp = await fetch(rawUrl)
+ if (!resp.ok) return null
+ const arrayBuffer = await resp.arrayBuffer().catch(() => null)
+ if (!arrayBuffer) return null
+ return Buffer.from(arrayBuffer)
+ }
+
+ const rootedKey = this.withRoot(key)
+ const urlPath = `${downloadPath}?${encodeURIComponent(this.pathField)}=${encodeURIComponent(rootedKey)}`
+ const resp = await this.request(urlPath, { method: 'GET' })
+ if (!resp.ok) return null
+ const arrayBuffer = await resp.arrayBuffer().catch(() => null)
+ if (!arrayBuffer) return null
+ return Buffer.from(arrayBuffer)
+ }
+
+ getPublicUrl(key: string): string {
+ const rootedKey = this.withRoot(key)
+ const { cdnUrl, baseUrl } = this.config
+ const base = cdnUrl || (baseUrl ? `${baseUrl.replace(/\/$/, '')}/d` : '')
+ if (!base) {
+ return ''
+ }
+ return `${base.replace(/\/$/, '')}/${rootedKey}`
+ }
+
+ async getFileMeta(key: string): Promise<StorageObject | null> {
+ const metaPath =
+ this.config.metaEndpoint || this.config.downloadEndpoint || '/api/fs/get'
+ const rootedKey = this.withRoot(key)
+ const urlPath = metaPath
+ const payload: Record<string, any> = {
+ [this.pathField]: this.toAbsolutePath(rootedKey),
+ password: '',
+ page: 1,
+ per_page: 0,
+ refresh: false,
+ }
+ const resp = await this.request(urlPath, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+ })
+ if (!resp.ok) {
+ const text = await resp.text().catch(() => '')
+ this.logger?.error('OpenList get file meta failed', {
+ status: resp.status,
+ body: text,
+ })
+ if (resp.status === 404) return null
+ throw new Error(`OpenList metadata request failed: ${resp.status}`)
+ }
+
+ const data = (await resp.json().catch(() => null)) as any
+ if (!data) throw new Error('Invalid OpenList metadata response')
+ if (typeof data.code === 'number' && data.code !== 200) {
+ if (data.code === 404) return null
+ throw new Error(`OpenList metadata error: ${data.code}`)
+ }
+ const node = data?.data || {}
+ const size = node?.size
+ const modified = node?.modified || node?.lastModified
+ const etag = node?.etag
+ const rawUrl = node?.raw_url
+ const result: StorageObject = {
+ key: rootedKey,
+ size: typeof size === 'number' ? size : undefined,
+ lastModified: modified ? new Date(modified) : undefined,
+ etag: typeof etag === 'string' ? etag : undefined,
+ }
+ // Attach raw_url as non-standard property for internal usage
+ ;(result as any).raw_url = typeof rawUrl === 'string' ? rawUrl : undefined
+ return result
+ }
+
+ async listAll(): Promise<StorageObject[]> {
+ // Listing API not provided explicitly; return empty array by default.
+ // You can configure custom list endpoint and parsing later.
+ const listPath = this.config.listEndpoint
+ if (!listPath) return []
+
+ const payload: Record<string, any> = {
+ [this.pathField]: this.toAbsolutePath(this.normalizedRoot()),
+ password: '',
+ page: 1,
+ per_page: 0,
+ refresh: false,
+ }
+ const resp = await this.request(listPath, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+ })
+ if (!resp.ok) return []
+ const data = (await resp.json().catch(() => null)) as any
+ const items: any[] = data?.data || data || []
+ return items
+ .map((item) => {
+ const rawKey = item?.path || item?.key || item?.name
+ if (!rawKey) return null
+ const rootedKey = this.withRoot(rawKey)
+ const size = item?.size
+ const lastModified = item?.modified || item?.lastModified || item?.mtime
+ const etag = item?.etag
+ return {
+ key: rootedKey,
+ size: typeof size === 'number' ? size : undefined,
+ lastModified: lastModified ? new Date(lastModified) : undefined,
+ etag: typeof etag === 'string' ? etag : undefined,
+ } as StorageObject
+ })
+ .filter(Boolean) as StorageObject[]
+ }
+
+ async listImages(): Promise<StorageObject[]> {
+ const all = await this.listAll()
+ return all.filter((obj) =>
+ /\.(jpe?g|png|webp|gif|bmp|tiff?|heic|heif)$/i.test(obj.key),
+ )
+ }
+}
diff --git a/packages/storage/src/providers/s3.ts b/packages/storage/src/providers/s3.ts
new file mode 100644
index 00000000..965ec595
--- /dev/null
+++ b/packages/storage/src/providers/s3.ts
@@ -0,0 +1,480 @@
+import type { S3StorageConfig } from '@chronoframe/contracts/storage'
+import type { StorageLogger } from '../logger.ts'
+import type { _Object, S3ClientConfig } from '@aws-sdk/client-s3'
+import {
+ DeleteObjectCommand,
+ GetObjectCommand,
+ HeadObjectCommand,
+ ListObjectsCommand,
+ PutObjectCommand,
+ S3Client,
+ CreateMultipartUploadCommand,
+ UploadPartCommand,
+ CompleteMultipartUploadCommand,
+ AbortMultipartUploadCommand,
+ ListPartsCommand,
+} from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import type {
+ StorageObject,
+ StorageProvider,
+ UploadOptions,
+ DirectUploadSetup,
+} from '../interfaces.ts'
+import { UPLOAD_CHUNK_SIZE } from '@chronoframe/contracts/upload'
+import { logUpload } from '../upload-log.ts'
+
+const createClient = (config: S3StorageConfig): S3Client => {
+ if (config.provider !== 's3') {
+ throw new Error('Invalid provider for S3 client creation')
+ }
+
+ const { accessKeyId, secretAccessKey, region, endpoint } = config
+ if (!accessKeyId || !secretAccessKey) {
+ throw new Error('Missing required accessKeyId or secretAccessKey')
+ }
+
+ const clientConfig: S3ClientConfig = {
+ endpoint,
+ region,
+ forcePathStyle: config.forcePathStyle,
+ responseChecksumValidation: 'WHEN_REQUIRED',
+ requestChecksumCalculation: 'WHEN_REQUIRED',
+ credentials: {
+ accessKeyId,
+ secretAccessKey,
+ },
+ }
+
+ return new S3Client(clientConfig)
+}
+
+const convertToStorageObject = (s3object: _Object): StorageObject => {
+ return {
+ key: s3object.Key || '',
+ size: s3object.Size,
+ lastModified: s3object.LastModified,
+ etag: s3object.ETag,
+ }
+}
+
+export class S3StorageProvider implements StorageProvider {
+ config: S3StorageConfig
+ private logger?: StorageLogger
+ private client: S3Client
+
+ constructor(config: S3StorageConfig, logger?: StorageLogger) {
+ this.config = config
+ this.logger = logger
+ this.client = createClient(config)
+ }
+
+ async create(
+ key: string,
+ data: Buffer,
+ contentType?: string,
+ ): Promise<StorageObject> {
+ try {
+ const absoluteKey =
+ `${(this.config.prefix || '').replace(/\/+$/, '')}/${key}`.replace(
+ /^\/+/,
+ '',
+ )
+ const cmd = new PutObjectCommand({
+ Bucket: this.config.bucket,
+ Key: absoluteKey,
+ Body: data,
+ ContentType: contentType || 'application/octet-stream',
+ })
+
+ const resp = await this.client.send(cmd)
+
+ this.logger?.success(`Created object with key: ${absoluteKey}`)
+
+ return {
+ key: absoluteKey,
+ size: data.length,
+ lastModified: new Date(),
+ etag: resp.ETag,
+ }
+ } catch (error) {
+ this.logger?.error(`Failed to create object with key: ${key}`, error)
+ throw error
+ }
+ }
+
+ async delete(key: string): Promise<void> {
+ try {
+ const cmd = new DeleteObjectCommand({
+ Bucket: this.config.bucket,
+ Key: key,
+ })
+
+ await this.client.send(cmd)
+ this.logger?.success(`Deleted object with key: ${key}`)
+ } catch (error) {
+ this.logger?.error(`Failed to delete object with key: ${key}`, error)
+ throw error
+ }
+ }
+
+ async createFromFile(
+ key: string,
+ filePath: string,
+ contentType: string,
+ ): Promise<StorageObject> {
+ const { size } = await stat(filePath)
+ const body = createReadStream(filePath)
+ try {
+ const result = await this.client.send(
+ new PutObjectCommand({
+ Bucket: this.config.bucket,
+ Key: key,
+ Body: body,
+ ContentLength: size,
+ ContentType: contentType,
+ }),
+ )
+ return { key, size, etag: result.ETag }
+ } finally {
+ body.destroy()
+ }
+ }
+
+ async get(key: string): Promise<Buffer | null> {
+ try {
+ const cmd = new GetObjectCommand({
+ Bucket: this.config.bucket,
+ Key: key,
+ })
+
+ const resp = await this.client.send(cmd)
+
+ if (!resp.Body) {
+ return null
+ }
+
+ if (resp.Body instanceof Buffer) {
+ return resp.Body
+ }
+
+ const chunks: Uint8Array[] = []
+ const stream = resp.Body as NodeJS.ReadableStream
+
+ return new Promise<Buffer>((resolve, reject) => {
+ stream.on('data', (chunk: Uint8Array) => {
+ chunks.push(chunk)
+ })
+
+ stream.on('end', () => {
+ resolve(Buffer.concat(chunks))
+ })
+
+ stream.on('error', (err) => {
+ reject(err)
+ })
+ })
+ } catch {
+ return null
+ }
+ }
+
+ getPublicUrl(key: string): string {
+ const { cdnUrl, bucket, region, endpoint } = this.config
+
+ // CDN URL
+ if (cdnUrl) {
+ return `${cdnUrl.replace(/\/$/, '')}/${key}`
+ }
+
+ // Default AWS S3 endpoint
+ if (!endpoint) {
+ return `https://${bucket}.s3.${region}.amazonaws.com/${key}`
+ } else if (endpoint.includes('amazonaws.com')) {
+ return `https://${bucket}.s3.${region}.amazonaws.com/${key}`
+ }
+
+ // Alibaba Cloud OSS
+ if (endpoint.includes('aliyuncs.com')) {
+ const baseUrl = endpoint.replace(/\/$/, '')
+ if (baseUrl.indexOf('//') === -1) {
+ throw new Error('Invalid endpoint URL')
+ }
+ const protocol = baseUrl.split('//')[0]
+ const remainder = baseUrl.split('//')[1]
+ return `${protocol}//${bucket}.${remainder}/${key}`
+ }
+
+ // Custom endpoint
+ return `${endpoint.replace(/\/$/, '')}/${bucket}/${key}`
+ }
+
+ async getSignedUrl(
+ key: string,
+ expiresIn: number = 3600,
+ options?: UploadOptions,
+ ): Promise<string> {
+ const cmd = new PutObjectCommand({
+ Bucket: this.config.bucket,
+ Key: key,
+ ContentType: options?.contentType || 'application/octet-stream',
+ })
+
+ const url = await getSignedUrl(this.client, cmd, {
+ expiresIn,
+ // 为了更好的 CORS 支持,添加一些额外参数
+ unhoistableHeaders: new Set(['Content-Type']),
+ })
+ return url
+ }
+
+ async prepareDirectUpload(
+ key: string,
+ size: number,
+ contentType: string,
+ ): Promise<DirectUploadSetup> {
+ const single = async (): Promise<DirectUploadSetup> => ({
+ mode: 'single',
+ url: await this.getSignedUrl(key, 3600, { contentType }),
+ })
+ if (size <= UPLOAD_CHUNK_SIZE) return single()
+ const base = { Bucket: this.config.bucket, Key: key }
+ const startedAt = Date.now()
+ logUpload(this.logger, 's3.multipart.initialize.started', {
+ key,
+ size,
+ bucket: this.config.bucket,
+ })
+ let uploadId: string | undefined
+ try {
+ uploadId = (
+ await this.client.send(
+ new CreateMultipartUploadCommand({
+ ...base,
+ ContentType: contentType,
+ }),
+ )
+ ).UploadId
+ } catch (error) {
+ logUpload(
+ this.logger,
+ 's3.multipart.initialize.failed',
+ {
+ key,
+ size,
+ bucket: this.config.bucket,
+ durationMs: Date.now() - startedAt,
+ },
+ error,
+ )
+ const unsupported = error as {
+ name?: string
+ Code?: string
+ $metadata?: { httpStatusCode?: number }
+ }
+ if (
+ [405, 501].includes(unsupported.$metadata?.httpStatusCode ?? 0) ||
+ [
+ 'NotImplemented',
+ 'NotSupported',
+ 'UnsupportedOperation',
+ 'AccessDenied',
+ ].includes(unsupported.name || unsupported.Code || '')
+ ) {
+ // A provider can allow ordinary PUT uploads while denying multipart
+ // initiation. Keep the file on the direct path in that case.
+ logUpload(this.logger, 's3.multipart.fallback.single', {
+ key,
+ size,
+ reason:
+ unsupported.name ||
+ unsupported.Code ||
+ String(unsupported.$metadata?.httpStatusCode),
+ })
+ return single()
+ }
+ throw error
+ }
+ if (!uploadId) throw new Error('S3 did not return a multipart upload ID')
+ logUpload(this.logger, 's3.multipart.initialize.succeeded', {
+ key,
+ uploadId,
+ durationMs: Date.now() - startedAt,
+ })
+ const params = { ...base, UploadId: uploadId }
+ const abort = async () => {
+ logUpload(this.logger, 's3.multipart.abort.started', { key, uploadId })
+ try {
+ await this.client.send(new AbortMultipartUploadCommand(params))
+ logUpload(this.logger, 's3.multipart.abort.succeeded', {
+ key,
+ uploadId,
+ })
+ } catch (error) {
+ logUpload(
+ this.logger,
+ 's3.multipart.abort.failed',
+ { key, uploadId },
+ error,
+ )
+ throw error
+ }
+ }
+ const partSize = Math.max(
+ UPLOAD_CHUNK_SIZE,
+ Math.ceil(size / 10_000 / 1024 / 1024) * 1024 * 1024,
+ )
+ const count = Math.ceil(size / partSize)
+ try {
+ const partUrls = await Promise.all(
+ Array.from({ length: count }, (_, index) =>
+ getSignedUrl(
+ this.client,
+ new UploadPartCommand({ ...params, PartNumber: index + 1 }),
+ { expiresIn: 3600 },
+ ),
+ ),
+ )
+ logUpload(this.logger, 's3.multipart.parts.signed', {
+ key,
+ uploadId,
+ partSize,
+ partCount: count,
+ })
+ return {
+ mode: 'multipart',
+ partSize,
+ partUrls,
+ abort,
+ complete: async (parts) => {
+ logUpload(this.logger, 's3.multipart.verify.started', {
+ key,
+ uploadId,
+ partCount: count,
+ size,
+ })
+ // Verify remote part sizes before publishing the object. Presigned
+ // upload URLs alone do not enforce the declared total file size.
+ const remote = new Map<number, { size?: number; etag?: string }>()
+ let marker: string | undefined
+ do {
+ const result = await this.client.send(
+ new ListPartsCommand({ ...params, PartNumberMarker: marker }),
+ )
+ for (const part of result.Parts || []) {
+ if (part.PartNumber !== undefined)
+ remote.set(part.PartNumber, {
+ size: part.Size,
+ etag: part.ETag,
+ })
+ }
+ marker = result.IsTruncated
+ ? result.NextPartNumberMarker
+ : undefined
+ } while (marker)
+ if (
+ remote.size !== count ||
+ parts.some((part) => {
+ const uploaded = remote.get(part.partNumber)
+ return (
+ uploaded?.etag !== part.etag ||
+ uploaded?.size !==
+ Math.min(partSize, size - (part.partNumber - 1) * partSize)
+ )
+ })
+ )
+ throw new Error('S3 multipart upload size or ETag mismatch')
+ for (const [partNumber, part] of remote) {
+ logUpload(this.logger, 's3.multipart.part.verified', {
+ key,
+ uploadId,
+ partNumber,
+ bytes: part.size,
+ })
+ }
+ logUpload(this.logger, 's3.multipart.complete.started', {
+ key,
+ uploadId,
+ partCount: count,
+ })
+ await this.client.send(
+ new CompleteMultipartUploadCommand({
+ ...params,
+ MultipartUpload: {
+ Parts: parts.map((part) => ({
+ PartNumber: part.partNumber,
+ ETag: part.etag,
+ })),
+ },
+ }),
+ )
+ logUpload(this.logger, 's3.multipart.complete.succeeded', {
+ key,
+ uploadId,
+ size,
+ durationMs: Date.now() - startedAt,
+ })
+ },
+ }
+ } catch (error) {
+ logUpload(
+ this.logger,
+ 's3.multipart.signing.failed',
+ { key, uploadId },
+ error,
+ )
+ await abort().catch(() => {})
+ throw error
+ }
+ }
+
+ async getFileMeta(key: string): Promise<StorageObject | null> {
+ try {
+ const cmd = new HeadObjectCommand({
+ Bucket: this.config.bucket,
+ Key: key,
+ })
+
+ const resp = await this.client.send(cmd)
+
+ return {
+ key,
+ size: resp.ContentLength,
+ lastModified: resp.LastModified,
+ etag: resp.ETag,
+ }
+ } catch (error) {
+ if ((error as any).$metadata?.httpStatusCode === 404) {
+ return null
+ }
+ this.logger?.error(`Failed to get metadata for key: ${key}`, error)
+ throw error
+ }
+ }
+
+ async listAll(): Promise<StorageObject[]> {
+ const cmd = new ListObjectsCommand({
+ Bucket: this.config.bucket,
+ Prefix: this.config.prefix,
+ MaxKeys: this.config.maxKeys,
+ })
+
+ const resp = await this.client.send(cmd)
+ this.logger?.log(resp.Contents?.map(convertToStorageObject))
+ return resp.Contents?.map(convertToStorageObject) || []
+ }
+
+ async listImages(): Promise<StorageObject[]> {
+ const cmd = new ListObjectsCommand({
+ Bucket: this.config.bucket,
+ Prefix: this.config.prefix,
+ MaxKeys: this.config.maxKeys,
+ })
+
+ const resp = await this.client.send(cmd)
+ // TODO: filter supported image format
+ return resp.Contents?.map(convertToStorageObject) || []
+ }
+}
diff --git a/packages/storage/src/upload-log.ts b/packages/storage/src/upload-log.ts
new file mode 100644
index 00000000..e9bf9fc1
--- /dev/null
+++ b/packages/storage/src/upload-log.ts
@@ -0,0 +1,28 @@
+import type { StorageLogger } from './logger.ts'
+
+// Log lifecycle metadata only: never URLs, headers, credentials or file bodies.
+export function logUpload(
+ logger: StorageLogger | undefined,
+ event: string,
+ details: Record<string, string | number | boolean | undefined>,
+ error?: unknown,
+) {
+ if (error !== undefined) {
+ const failure = error as {
+ name?: string
+ Code?: string
+ statusCode?: number
+ statusMessage?: string
+ $metadata?: { httpStatusCode?: number }
+ } | null
+ logger?.warn(`[upload] ${event}`, {
+ ...details,
+ errorName: failure?.name,
+ errorCode: failure?.Code,
+ statusCode: failure?.statusCode ?? failure?.$metadata?.httpStatusCode,
+ reason: failure?.statusMessage,
+ })
+ } else {
+ logger?.info(`[upload] ${event}`, details)
+ }
+}
diff --git a/packages/storage/tsconfig.json b/packages/storage/tsconfig.json
new file mode 100644
index 00000000..e79cde15
--- /dev/null
+++ b/packages/storage/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "noEmit": true,
+ "allowImportingTsExtensions": true,
+ "types": ["node"],
+ "lib": ["ES2022", "DOM"],
+ "skipLibCheck": true,
+ "noUncheckedIndexedAccess": true
+ },
+ "include": ["src/**/*.ts"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f1ef95c6..7c933c7f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -20,6 +20,15 @@ importers:
'@chronoframe/contracts':
specifier: workspace:*
version: link:packages/contracts
+ '@chronoframe/geocoding':
+ specifier: workspace:*
+ version: link:packages/geocoding
+ '@chronoframe/media':
+ specifier: workspace:*
+ version: link:packages/media
+ '@chronoframe/storage':
+ specifier: workspace:*
+ version: link:packages/storage
'@chronoframe/webgl-image':
specifier: workspace:*
version: link:packages/webgl-image
@@ -236,6 +245,75 @@ importers:
specifier: ^5.9.3
version: 5.9.3
+ packages/geocoding:
+ dependencies:
+ '@chronoframe/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ devDependencies:
+ '@types/node':
+ specifier: ^22.20.5
+ version: 22.20.5
+ typescript:
+ specifier: ^5.9.3
+ version: 5.9.3
+
+ packages/media:
+ dependencies:
+ '@chronoframe/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@chronoframe/storage':
+ specifier: workspace:*
+ version: link:../storage
+ '@vingle/bmp-js':
+ specifier: ^0.2.5
+ version: 0.2.5
+ es-toolkit:
+ specifier: ^1.52.0
+ version: 1.52.0
+ exiftool-vendored:
+ specifier: ^35.21.0
+ version: 35.21.0
+ heic-convert:
+ specifier: ^2.1.0
+ version: 2.1.0
+ sharp:
+ specifier: 0.35.5
+ version: 0.35.5(@types/[email protected])
+ thumbhash:
+ specifier: ^0.1.1
+ version: 0.1.1
+ devDependencies:
+ '@types/heic-convert':
+ specifier: ^2.1.1
+ version: 2.1.1
+ '@types/node':
+ specifier: ^22.20.5
+ version: 22.20.5
+ typescript:
+ specifier: ^5.9.3
+ version: 5.9.3
+
+ packages/storage:
+ dependencies:
+ '@aws-sdk/client-s3':
+ specifier: ^3.1149.0
+ version: 3.1149.0
+ '@aws-sdk/s3-request-presigner':
+ specifier: ^3.1149.0
+ version: 3.1149.0
+ '@chronoframe/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ devDependencies:
+ '@types/node':
+ specifier: ^22.20.5
+ version: 22.20.5
+ typescript:
+ specifier: ^5.9.3
+ version: 5.9.3
+
packages/webgl-image:
dependencies:
vue:
@@ -15770,6 +15848,39 @@ snapshots:
+ dependencies:
+ '@img/colour': 1.1.0
+ detect-libc: 2.1.2
+ semver: 7.8.5
+ optionalDependencies:
+ '@img/sharp-darwin-arm64': 0.35.5
+ '@img/sharp-darwin-x64': 0.35.5
+ '@img/sharp-freebsd-wasm32': 0.35.5
+ '@img/sharp-libvips-darwin-arm64': 1.3.4
+ '@img/sharp-libvips-darwin-x64': 1.3.4
+ '@img/sharp-libvips-linux-arm': 1.3.4
+ '@img/sharp-libvips-linux-arm64': 1.3.4
+ '@img/sharp-libvips-linux-ppc64': 1.3.4
+ '@img/sharp-libvips-linux-riscv64': 1.3.4
+ '@img/sharp-libvips-linux-s390x': 1.3.4
+ '@img/sharp-libvips-linux-x64': 1.3.4
+ '@img/sharp-libvips-linuxmusl-arm64': 1.3.4
+ '@img/sharp-libvips-linuxmusl-x64': 1.3.4
+ '@img/sharp-linux-arm': 0.35.5
+ '@img/sharp-linux-arm64': 0.35.5
+ '@img/sharp-linux-ppc64': 0.35.5
+ '@img/sharp-linux-riscv64': 0.35.5
+ '@img/sharp-linux-s390x': 0.35.5
+ '@img/sharp-linux-x64': 0.35.5
+ '@img/sharp-linuxmusl-arm64': 0.35.5
+ '@img/sharp-linuxmusl-x64': 0.35.5
+ '@img/sharp-webcontainers-wasm32': 0.35.5
+ '@img/sharp-win32-arm64': 0.35.5
+ '@img/sharp-win32-ia32': 0.35.5
+ '@img/sharp-win32-x64': 0.35.5
+ '@types/node': 22.20.5
+
dependencies:
'@img/colour': 1.1.0
diff --git a/scripts/check-package-boundaries.mjs b/scripts/check-package-boundaries.mjs
new file mode 100644
index 00000000..3dfdf69b
--- /dev/null
+++ b/scripts/check-package-boundaries.mjs
@@ -0,0 +1,90 @@
+import { readFile, readdir } from 'node:fs/promises'
+import path from 'node:path'
+import { builtinModules } from 'node:module'
+import ts from 'typescript'
+
+const packageNames = ['contracts', 'storage', 'media', 'geocoding']
+const builtins = new Set(
+ builtinModules.map((name) => name.replace(/^node:/, '')),
+)
+const failures = []
+
+async function files(directory) {
+ const entries = await readdir(directory, { withFileTypes: true })
+ return (
+ await Promise.all(
+ entries.map((entry) =>
+ entry.isDirectory()
+ ? files(path.join(directory, entry.name))
+ : entry.name.endsWith('.ts')
+ ? [path.join(directory, entry.name)]
+ : [],
+ ),
+ )
+ ).flat()
+}
+
+for (const name of packageNames) {
+ const root = path.resolve('packages', name)
+ const manifest = JSON.parse(
+ await readFile(path.join(root, 'package.json'), 'utf8'),
+ )
+ const allowed = new Set(
+ Object.keys({
+ ...manifest.dependencies,
+ ...manifest.devDependencies,
+ ...manifest.peerDependencies,
+ }),
+ )
+ for (const file of await files(path.join(root, 'src'))) {
+ const source = ts.createSourceFile(
+ file,
+ await readFile(file, 'utf8'),
+ ts.ScriptTarget.Latest,
+ true,
+ )
+ function inspect(node) {
+ const specifier =
+ ts.isImportDeclaration(node) || ts.isExportDeclaration(node)
+ ? node.moduleSpecifier
+ : ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)
+ ? node.argument.literal
+ : ts.isCallExpression(node) &&
+ node.expression.kind === ts.SyntaxKind.ImportKeyword
+ ? node.arguments[0]
+ : undefined
+ if (specifier && ts.isStringLiteral(specifier)) {
+ const value = specifier.text
+ const fail = (reason) =>
+ failures.push(
+ `${path.relative(process.cwd(), file)}: ${value}: ${reason}`,
+ )
+ if (value.startsWith('.')) {
+ if (
+ !path.resolve(path.dirname(file), value).startsWith(root + path.sep)
+ )
+ fail('relative import leaves package')
+ } else if (
+ value.startsWith('~') ||
+ value.startsWith('#') ||
+ value.startsWith('/')
+ ) {
+ fail('application aliases and absolute imports are forbidden')
+ } else if (builtins.has(value.replace(/^node:/, ''))) {
+ if (name === 'contracts') fail('contracts must be browser-compatible')
+ } else {
+ const dependency = value.startsWith('@')
+ ? value.split('/').slice(0, 2).join('/')
+ : value.split('/')[0]
+ if (!allowed.has(dependency)) fail('dependency is not declared')
+ }
+ }
+ ts.forEachChild(node, inspect)
+ }
+ inspect(source)
+ }
+}
+if (failures.length) {
+ console.error(failures.join('\n'))
+ process.exitCode = 1
+} else console.log(`Package boundaries passed (${packageNames.join(', ')}).`)
diff --git a/server/api/albums/[albumId]/index.get.ts b/server/api/albums/[albumId]/index.get.ts
index eb7721ad..c4225226 100644
--- a/server/api/albums/[albumId]/index.get.ts
+++ b/server/api/albums/[albumId]/index.get.ts
@@ -1,3 +1,4 @@
+import { toAlbumDto, toPhotoDto } from '../../../utils/dto'
import { eq } from 'drizzle-orm'
import z from 'zod'
@@ -57,8 +58,9 @@ export default eventHandler(async (event) => {
isLoggedIn,
isLoggedIn || Boolean(album.passwordHash),
)
+ const photoDtos = rows.map(toPhotoDto)
const photos = album.passwordHash
- ? rows.map((photo) => {
+ ? photoDtos.map((photo) => {
const fileName = photo.storageKey?.split(/[\\/]/).pop() || null
const {
storageKey: _storageKey,
@@ -76,12 +78,10 @@ export default eventHandler(async (event) => {
: null,
}
})
- : rows
+ : photoDtos
return {
- ...album,
- passwordHash: undefined,
- hasPassword: Boolean(album.passwordHash),
+ ...toAlbumDto(album),
photos,
}
})
diff --git a/server/api/albums/[albumId]/index.put.ts b/server/api/albums/[albumId]/index.put.ts
index c4655093..8a26d50e 100644
--- a/server/api/albums/[albumId]/index.put.ts
+++ b/server/api/albums/[albumId]/index.put.ts
@@ -1,3 +1,4 @@
+import { toAlbumDto } from '../../../utils/dto'
import { z } from 'zod'
import {
ALBUM_PASSWORD_MAX_LENGTH,
@@ -128,9 +129,7 @@ export default eventHandler(async (event) => {
.get()
})
- return {
- ...updatedAlbum,
- passwordHash: undefined,
- hasPassword: Boolean(updatedAlbum?.passwordHash),
- }
+ if (!updatedAlbum)
+ throw createError({ statusCode: 404, statusMessage: 'Album not found' })
+ return toAlbumDto(updatedAlbum)
})
diff --git a/server/api/albums/index.get.ts b/server/api/albums/index.get.ts
index 78aa7dd4..1472498b 100644
--- a/server/api/albums/index.get.ts
+++ b/server/api/albums/index.get.ts
@@ -1,3 +1,4 @@
+import { toAlbumDto } from '../../utils/dto'
import { asc, desc, or, isNotNull, eq } from 'drizzle-orm'
import { albumAccess } from '../../utils/album-access'
@@ -47,9 +48,7 @@ export default eventHandler(async (event) => {
.orderBy(tables.albumPhotos.position)
return {
- ...album,
- passwordHash: undefined,
- hasPassword: Boolean(album.passwordHash),
+ ...toAlbumDto(album),
coverPhotoId:
admin ||
(accessible && !restrictedPhotoIds.has(album.coverPhotoId || ''))
diff --git a/server/api/albums/index.post.ts b/server/api/albums/index.post.ts
index 1da5b206..ce609eb8 100644
--- a/server/api/albums/index.post.ts
+++ b/server/api/albums/index.post.ts
@@ -1,3 +1,4 @@
+import { toAlbumDto } from '../../utils/dto'
import { min } from 'drizzle-orm'
import z from 'zod'
import {
@@ -74,11 +75,7 @@ export default eventHandler(async (event) => {
}
}
- return {
- ...newAlbum,
- passwordHash: undefined,
- hasPassword: Boolean(newAlbum.passwordHash),
- }
+ return toAlbumDto(newAlbum)
})
return album
diff --git a/server/api/auth/github.get.ts b/server/api/auth/github.get.ts
index f3b95c1b..06636be6 100644
--- a/server/api/auth/github.get.ts
+++ b/server/api/auth/github.get.ts
@@ -1,3 +1,4 @@
+import { toUserSummary } from '~~/server/utils/dto'
import { settingsManager } from '~~/server/services/settings/settingsManager'
const _accessDeniedError = createError({
@@ -38,7 +39,7 @@ async function onGithubOAuthSuccess(event: any, { user }: { user: any }) {
} else {
await setUserSession(
event,
- { user: userFromEmail },
+ { user: toUserSummary(userFromEmail) },
{
cookie: {
// secure: !useRuntimeConfig().allowInsecureCookie,
diff --git a/server/api/login.post.ts b/server/api/login.post.ts
index 26185e0c..8a63cf97 100644
--- a/server/api/login.post.ts
+++ b/server/api/login.post.ts
@@ -1,3 +1,4 @@
+import { toUserSummary } from '~~/server/utils/dto'
import { z } from 'zod'
const _invalidCredentialsError = createError({
@@ -31,7 +32,7 @@ export default eventHandler(async (event) => {
await setUserSession(
event,
- { user },
+ { user: toUserSummary(user) },
{
cookie: {
// secure: !useRuntimeConfig().allowInsecureCookie,
diff --git a/server/api/photos/[photoId]/albums.get.ts b/server/api/photos/[photoId]/albums.get.ts
index d5add816..ca94cf0d 100644
--- a/server/api/photos/[photoId]/albums.get.ts
+++ b/server/api/photos/[photoId]/albums.get.ts
@@ -34,6 +34,9 @@ export default eventHandler(async (event) => {
.all()
return albums.filter(canAccess).map(({ passwordHash, ...album }) => ({
- ...album, hasPassword: Boolean(passwordHash),
+ ...album,
+ createdAt: album.createdAt.toISOString(),
+ updatedAt: album.updatedAt.toISOString(),
+ hasPassword: Boolean(passwordHash),
}))
})
diff --git a/server/api/photos/[photoId]/index.put.ts b/server/api/photos/[photoId]/index.put.ts
index ad00390a..9a30aafb 100644
--- a/server/api/photos/[photoId]/index.put.ts
+++ b/server/api/photos/[photoId]/index.put.ts
@@ -1,3 +1,5 @@
+import type {} from '../../../types/worker'
+import { toPhotoDto } from '../../../utils/dto'
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
@@ -268,7 +270,7 @@ export default eventHandler(async (event) => {
return {
success: true,
- photo: updatedPhoto,
+ photo: updatedPhoto ? toPhotoDto(updatedPhoto) : undefined,
}
} catch (error) {
logger.image.error('Failed to update photo metadata', error)
diff --git a/server/api/photos/index.get.ts b/server/api/photos/index.get.ts
index 16827cbe..910bb5b1 100644
--- a/server/api/photos/index.get.ts
+++ b/server/api/photos/index.get.ts
@@ -1,3 +1,4 @@
+import { toPhotoDto } from '../../utils/dto'
import { desc } from 'drizzle-orm'
export default eventHandler(async (_event) => {
@@ -7,4 +8,5 @@ export default eventHandler(async (_event) => {
.from(tables.photos)
.orderBy(desc(tables.photos.dateTaken))
.all()
+ .map(toPhotoDto)
})
diff --git a/server/api/photos/status.get.ts b/server/api/photos/status.get.ts
index e6b44531..51752eb0 100644
--- a/server/api/photos/status.get.ts
+++ b/server/api/photos/status.get.ts
@@ -1,3 +1,4 @@
+import { toPhotoDto } from '../../utils/dto'
import { photos } from '~~/server/database/schema'
export default eventHandler(async (event) => {
@@ -15,7 +16,7 @@ export default eventHandler(async (event) => {
.all()
return {
- recentPhotos,
+ recentPhotos: recentPhotos.map(toPhotoDto),
timestamp: new Date().toISOString(),
}
} else {
diff --git a/server/api/photos/visible.get.ts b/server/api/photos/visible.get.ts
index 4cd041e0..21950f27 100644
--- a/server/api/photos/visible.get.ts
+++ b/server/api/photos/visible.get.ts
@@ -1,3 +1,4 @@
+import { toPhotoDto } from '../../utils/dto'
import { desc, notInArray, or, isNotNull } from 'drizzle-orm'
export default eventHandler(async (_event) => {
@@ -10,7 +11,12 @@ export default eventHandler(async (_event) => {
})
.from(tables.albumPhotos)
.innerJoin(tables.albums, eq(tables.albumPhotos.albumId, tables.albums.id))
- .where(or(eq(tables.albums.isHidden, true), isNotNull(tables.albums.passwordHash)))
+ .where(
+ or(
+ eq(tables.albums.isHidden, true),
+ isNotNull(tables.albums.passwordHash),
+ ),
+ )
.all()
const hiddenPhotoIds = hiddenAlbumPhotos.map((row) => row.photoId)
@@ -23,6 +29,7 @@ export default eventHandler(async (_event) => {
.where(notInArray(tables.photos.id, hiddenPhotoIds))
.orderBy(desc(tables.photos.dateTaken))
.all()
+ .map(toPhotoDto)
}
// 如果没有隐藏的照片,直接返回所有照片
@@ -31,4 +38,5 @@ export default eventHandler(async (_event) => {
.from(tables.photos)
.orderBy(desc(tables.photos.dateTaken))
.all()
+ .map(toPhotoDto)
})
diff --git a/server/api/queue/add-task.post.ts b/server/api/queue/add-task.post.ts
index 2bb6b6fb..39552e2b 100644
--- a/server/api/queue/add-task.post.ts
+++ b/server/api/queue/add-task.post.ts
@@ -1,3 +1,4 @@
+import type {} from '../../types/worker'
import { z } from 'zod'
import {
photoTaskAlbumExists,
diff --git a/server/api/queue/add-tasks.post.ts b/server/api/queue/add-tasks.post.ts
index a2f213dc..9927ac76 100644
--- a/server/api/queue/add-tasks.post.ts
+++ b/server/api/queue/add-tasks.post.ts
@@ -1,3 +1,4 @@
+import type {} from '../../types/worker'
import { z } from 'zod'
import {
createPhotoTaskAlbumChecker,
diff --git a/server/api/queue/stats/[taskId].get.ts b/server/api/queue/stats/[taskId].get.ts
index 839d5930..03ca64cd 100644
--- a/server/api/queue/stats/[taskId].get.ts
+++ b/server/api/queue/stats/[taskId].get.ts
@@ -1,3 +1,4 @@
+import type {} from '../../../types/worker'
import z from 'zod'
export default defineEventHandler(async (event) => {
diff --git a/server/api/queue/stats/index.ts b/server/api/queue/stats/index.ts
index 234c7c87..5ddb7412 100644
--- a/server/api/queue/stats/index.ts
+++ b/server/api/queue/stats/index.ts
@@ -1,3 +1,4 @@
+import type {} from '../../../types/worker'
export default defineEventHandler(async (event) => {
await requireUserSession(event)
diff --git a/server/api/system/settings/all.get.ts b/server/api/system/settings/all.get.ts
index ff611126..58d4261f 100644
--- a/server/api/system/settings/all.get.ts
+++ b/server/api/system/settings/all.get.ts
@@ -1,3 +1,4 @@
+import type { PublicSettingsResponse } from '@chronoframe/contracts/settings'
import { useDB, tables, eq, or, and } from '~~/server/utils/db'
/**
@@ -14,7 +15,10 @@ export default eventHandler(async () => {
.from(tables.settings)
.where(
or(
- eq(tables.settings.isPublic, true),
+ and(
+ eq(tables.settings.isPublic, true),
+ eq(tables.settings.isSecret, false),
+ ),
and(
eq(tables.settings.namespace, 'system'),
eq(tables.settings.key, 'firstLaunch'),
@@ -51,5 +55,5 @@ export default eventHandler(async () => {
return {
timestamp: Date.now(),
data: grouped,
- }
+ } satisfies PublicSettingsResponse
})
diff --git a/server/api/system/settings/fields.get.ts b/server/api/system/settings/fields.get.ts
index 763e28e3..8641f524 100644
--- a/server/api/system/settings/fields.get.ts
+++ b/server/api/system/settings/fields.get.ts
@@ -36,7 +36,7 @@ export default eventHandler(async (event) => {
try {
// 获取该命名空间的所有设置
const schema = await settingsManager.getSchema()
- const allowedKeys = new Set(
+ const allowedKeys = new Set<string>(
DEFAULT_SETTINGS.filter((s) => s.namespace === query.namespace).map(
(s) => s.key,
),
diff --git a/server/api/system/settings/storage-config/[id].ts b/server/api/system/settings/storage-config/[id].ts
index cad304ed..2ab60774 100644
--- a/server/api/system/settings/storage-config/[id].ts
+++ b/server/api/system/settings/storage-config/[id].ts
@@ -1,3 +1,4 @@
+import { toStorageProviderDto } from '../../../../utils/dto'
import { z } from 'zod'
import { settingsManager } from '~~/server/services/settings/settingsManager'
import {
@@ -34,7 +35,7 @@ export default eventHandler(async (event) => {
switch (event.method) {
case 'GET':
- return storageConfig
+ return toStorageProviderDto(storageConfig)
case 'PUT': {
const updatedStorageConfig = await readValidatedBody(
event,
diff --git a/server/api/system/settings/storage-config/index.ts b/server/api/system/settings/storage-config/index.ts
index 1fb9d17a..e6915fb3 100644
--- a/server/api/system/settings/storage-config/index.ts
+++ b/server/api/system/settings/storage-config/index.ts
@@ -1,3 +1,4 @@
+import { toStorageProviderDto } from '../../../../utils/dto'
import { z } from 'zod'
import { settingsManager } from '~~/server/services/settings/settingsManager'
import {
@@ -17,7 +18,9 @@ export default eventHandler(async (event) => {
switch (event.method) {
case 'GET': {
- return await settingsManager.storage.getProviders()
+ return (await settingsManager.storage.getProviders()).map(
+ toStorageProviderDto,
+ )
}
case 'POST': {
const newStorageConfig = await readValidatedBody(
diff --git a/server/api/system/stats.get.ts b/server/api/system/stats.get.ts
index fa3975da..45a0e549 100644
--- a/server/api/system/stats.get.ts
+++ b/server/api/system/stats.get.ts
@@ -1,3 +1,4 @@
+import type {} from '../../types/worker'
import { getLocationMigrationStatus } from '../../services/pipeline-queue/location-migration'
import { settingsManager } from '~~/server/services/settings/settingsManager'
import { sql, gte } from 'drizzle-orm'
diff --git a/server/api/wizard/submit.post.ts b/server/api/wizard/submit.post.ts
index aa268051..b7fb8037 100644
--- a/server/api/wizard/submit.post.ts
+++ b/server/api/wizard/submit.post.ts
@@ -1,3 +1,4 @@
+import { toUserSummary } from '~~/server/utils/dto'
import { z } from 'zod'
import { settingsManager } from '~~/server/services/settings/settingsManager'
import { storageConfigSchema } from '~~/shared/types/storage'
@@ -46,7 +47,11 @@ export default eventHandler(async (event) => {
})
.where(eq(tables.users.id, existingUser.id))
.run()
- adminUser = db.select().from(tables.users).where(eq(tables.users.id, existingUser.id)).get()
+ adminUser = db
+ .select()
+ .from(tables.users)
+ .where(eq(tables.users.id, existingUser.id))
+ .get()
} else {
throw createError({
statusCode: 400,
@@ -64,7 +69,11 @@ export default eventHandler(async (event) => {
createdAt: new Date(),
})
.run()
- adminUser = db.select().from(tables.users).where(eq(tables.users.email, body.admin.email)).get()
+ adminUser = db
+ .select()
+ .from(tables.users)
+ .where(eq(tables.users.email, body.admin.email))
+ .get()
}
// 2. Handle Site Settings
@@ -90,13 +99,11 @@ export default eventHandler(async (event) => {
await settingsManager.set('map', 'provider', body.map.provider)
const mapToken = body.map.token.trim()
if (body.map.provider === 'mapbox') {
- if (mapToken)
- await settingsManager.set('map', 'mapbox.token', mapToken)
+ if (mapToken) await settingsManager.set('map', 'mapbox.token', mapToken)
if (body.map.style)
await settingsManager.set('map', 'mapbox.style', body.map.style)
} else {
- if (mapToken)
- await settingsManager.set('map', 'maplibre.token', mapToken)
+ if (mapToken) await settingsManager.set('map', 'maplibre.token', mapToken)
if (body.map.style)
await settingsManager.set('map', 'maplibre.style', body.map.style)
}
@@ -108,7 +115,7 @@ export default eventHandler(async (event) => {
if (adminUser) {
await setUserSession(
event,
- { user: adminUser },
+ { user: toUserSummary(adminUser) },
{
cookie: {
secure: false,
diff --git a/server/plugins/4.pipeline-queue.ts b/server/plugins/4.pipeline-queue.ts
index 3b20366a..9b2dad3b 100644
--- a/server/plugins/4.pipeline-queue.ts
+++ b/server/plugins/4.pipeline-queue.ts
@@ -1,3 +1,4 @@
+import type {} from '../types/worker'
import { WorkerPool } from '../services/pipeline-queue'
import { settingsManager } from '../services/settings/settingsManager'
import { DEFAULT_QUEUE_WORKER_COUNT } from '~~/shared/utils/queue-config'
diff --git a/server/services/image/blurhash.ts b/server/services/image/blurhash.ts
index 6d71e1e6..dbbf92da 100644
--- a/server/services/image/blurhash.ts
+++ b/server/services/image/blurhash.ts
@@ -1,23 +1 @@
-import sharp from 'sharp'
-import { rgbaToThumbHash } from 'thumbhash'
-
-export const generateBlurHash = async (
- buffer: Buffer,
- logger?: Logger[keyof Logger],
-) => {
- try {
- const { data, info } = await sharp(buffer)
- .resize(100, 100, { fit: 'inside' })
- .raw()
- .ensureAlpha()
- .toBuffer({
- resolveWithObject: true,
- })
-
- const thumbHash = rgbaToThumbHash(info.width, info.height, data)
- return thumbHash
- } catch (error) {
- logger?.error('Generate thumbhash failed', error)
- return null
- }
-}
+export * from '@chronoframe/media/blurhash'
diff --git a/server/services/image/exif.ts b/server/services/image/exif.ts
index 11c29bef..330b2291 100644
--- a/server/services/image/exif.ts
+++ b/server/services/image/exif.ts
@@ -1,532 +1,9 @@
import path from 'node:path'
-import { mkdir, unlink, writeFile } from 'node:fs/promises'
-import type { Metadata } from 'sharp'
-import sharp from 'sharp'
-import type { NeededExif, PhotoInfo } from '../../../shared/types/photo'
-import type { ExifDateTime, Tags } from 'exiftool-vendored'
import { exiftool } from 'exiftool-vendored'
-import { noop } from 'es-toolkit'
-import { withRetry, RetryPresets, RetryConditions } from '../../utils/retry'
-
-const neededKeys: Array<keyof Tags | (string & {})> = [
- 'Title',
- 'XPTitle',
- 'Subject',
- 'Keywords',
- 'XPKeywords',
-
- 'Description',
- 'ImageDescription',
- 'Caption-Abstract',
- 'XPComment',
- 'UserComment',
-
- 'tz',
- 'tzSource',
- 'Orientation',
- 'Make',
- 'Model',
- 'Software',
- 'Artist',
- 'Copyright',
- 'ExposureTime',
-
- 'FNumber',
- 'ExposureProgram',
- 'ISO',
- 'OffsetTime',
- 'OffsetTimeOriginal',
- 'OffsetTimeDigitized',
- 'ShutterSpeedValue',
- 'ApertureValue',
- 'BrightnessValue',
- 'ExposureCompensationSet',
- 'ExposureCompensationMode',
- 'ExposureCompensationSetting',
-
- 'ExposureCompensation',
- 'MaxApertureValue',
- 'LightSource',
- 'Flash',
- 'FocalLength',
-
- 'ColorSpace',
- 'ExposureMode',
- 'FocalLengthIn35mmFormat',
- 'SceneCaptureType',
- 'LensMake',
- 'LensModel',
- 'MeteringMode',
- 'WhiteBalance',
- 'WBShiftAB',
- 'WBShiftGM',
- 'WhiteBalanceBias',
- 'WhiteBalanceFineTune',
- 'FlashMeteringMode',
- 'SensingMethod',
- 'FocalPlaneXResolution',
- 'FocalPlaneYResolution',
-
- 'Aperture',
- 'ScaleFactor35efl',
- 'ShutterSpeed',
- 'LightValue',
- 'Rating',
-
- 'GPSAltitude',
- 'GPSCoordinates',
- 'GPSAltitudeRef',
- 'GPSLatitude',
- 'GPSLatitudeRef',
- 'GPSLongitude',
- 'GPSLongitudeRef',
-
- 'MPImageType',
-
- // Motion Photo (XMP) related keys
- 'MotionPhoto',
- 'MotionPhotoVersion',
- 'MotionPhotoPresentationTimestampUs',
- 'MicroVideo',
- 'MicroVideoVersion',
- 'MicroVideoOffset',
- 'MicroVideoPresentationTimestampUs',
-]
-
-/**
- * Convert a date-like value to an ISO string, returning undefined instead of
- * throwing `RangeError: Invalid time value` when the value cannot be parsed.
- */
-const toValidISOString = (value: string | number | Date): string | undefined => {
- const date = value instanceof Date ? value : new Date(value)
- return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
-}
-
-const formatExifDate = (date: string | ExifDateTime | undefined) => {
- if (!date) {
- return
- }
-
- // exiftool returns the raw string when it cannot parse a date
- // (e.g. "0000:00:00 00:00:00"), which `new Date()` cannot parse either.
- if (typeof date === 'string') {
- return toValidISOString(date)
- }
-
- return date.toISOString()
-}
-
-/**
- * 从 Sharp metadata 中推断颜色空间信息
- */
-const inferColorSpaceFromMetadata = (
- metadata: Metadata,
-): string | undefined => {
- // 优先使用 ICC 配置文件信息
- if (metadata.icc) {
- const colorSpace = parseICCProfile(metadata.icc)
- if (colorSpace) {
- return colorSpace
- }
- }
-
- // 根据图片格式和通道数推断
- if (metadata.space) {
- const colorSpace = mapSharpSpaceToColorSpace(metadata.space)
- if (colorSpace) {
- return colorSpace
- }
- }
-
- // 根据图片类型的默认颜色空间
- if (metadata.format) {
- const colorSpace = getDefaultColorSpaceForFormat(metadata.format)
- if (colorSpace) {
- return colorSpace
- }
- }
-
- return undefined
-}
-
-/**
- * 解析 ICC 配置文件以确定颜色空间
- */
-const parseICCProfile = (iccBuffer: Buffer): string | undefined => {
- try {
- const iccString = iccBuffer.toString('latin1')
-
- // 常见的颜色空间标识符
- if (iccString.includes('sRGB') || iccString.includes('IEC61966-2.1')) {
- return 'sRGB'
- }
- if (iccString.includes('Adobe RGB') || iccString.includes('ADOBERGB')) {
- return 'Adobe RGB'
- }
- if (iccString.includes('Display P3') || iccString.includes('P3')) {
- return 'Display P3'
- }
- if (iccString.includes('ProPhoto') || iccString.includes('ROMM')) {
- return 'ProPhoto RGB'
- }
- if (iccString.includes('Wide Gamut') || iccString.includes('WideGamut')) {
- return 'Wide Gamut RGB'
- }
- if (iccString.includes('Rec2020') || iccString.includes('ITU-R BT.2020')) {
- return 'Rec. 2020'
- }
- if (iccString.includes('DCI-P3') || iccString.includes('DCI')) {
- return 'DCI-P3'
- }
- if (iccString.includes('Rec709') || iccString.includes('ITU-R BT.709')) {
- return 'Rec. 709'
- }
-
- // 检查 ICC 配置文件头部的颜色空间签名(偏移量 16-19)
- if (iccBuffer.length >= 20) {
- const colorSpaceSignature = iccBuffer.toString('ascii', 16, 20)
- switch (colorSpaceSignature) {
- case 'RGB ':
- return 'RGB'
- case 'CMYK':
- return 'CMYK'
- case 'GRAY':
- return 'Grayscale'
- case 'LAB ':
- return 'Lab'
- case 'XYZ ':
- return 'XYZ'
- default:
- break
- }
- }
- } catch {
- // 忽略解析错误,继续尝试其他方法
- }
-
- return undefined
-}
-
-/**
- * 将 Sharp 的 space 映射到标准颜色空间名称
- */
-const mapSharpSpaceToColorSpace = (space: string): string | undefined => {
- switch (space) {
- case 'srgb':
- return 'sRGB'
- case 'rgb16':
- return 'RGB'
- case 'cmyk':
- return 'CMYK'
- case 'lab':
- return 'Lab'
- case 'xyz':
- return 'XYZ'
- case 'grey16':
- case 'b-w':
- return 'Grayscale'
- default:
- return undefined
- }
-}
-
-/**
- * 根据图片格式获取默认颜色空间
- */
-const getDefaultColorSpaceForFormat = (format: string): string | undefined => {
- const formatLower = format.toLowerCase()
- switch (formatLower) {
- case 'jpeg':
- case 'jpg':
- return 'sRGB' // JPEG 默认使用 sRGB
- case 'png':
- return 'sRGB' // PNG 通常使用 sRGB
- case 'webp':
- return 'sRGB' // WebP 通常使用 sRGB
- case 'tiff':
- case 'tif':
- return 'sRGB' // TIFF 可能使用各种颜色空间,默认 sRGB
- case 'heif':
- case 'heic':
- return 'Display P3' // HEIC 通常支持 Display P3
- case 'avif':
- return 'sRGB' // AVIF 通常使用 sRGB,但也可能支持其他
- case 'gif':
- return 'sRGB' // GIF 使用 sRGB
- case 'bmp':
- return 'sRGB' // BMP 通常使用 sRGB
- default:
- return undefined
- }
-}
-
-const processExifData = (exifData: Tags, metadata: Metadata): NeededExif => {
- const date = {
- DateTimeOriginal: formatExifDate(exifData.DateTimeOriginal),
- DateTimeDigitized: formatExifDate(exifData.DateTimeDigitized),
- OffsetTime: exifData.OffsetTime,
- OffsetTimeOriginal: exifData.OffsetTimeOriginal,
- OffsetTimeDigitized: exifData.OffsetTimeDigitized,
- }
-
- const size = {
- ImageWidth: exifData.ExifImageWidth || metadata.width,
- ImageHeight: exifData.ExifImageHeight || metadata.height,
- }
-
- const result: any = structuredClone(exifData)
- for (const key in result) {
- Reflect.deleteProperty(result, key)
- }
- for (const key of neededKeys) {
- result[key] = (exifData as any)[key]
- }
-
- // 优先从 metadata 推断颜色空间
- const inferredColorSpace = inferColorSpaceFromMetadata(metadata)
- if (inferredColorSpace) {
- result.ColorSpace = inferredColorSpace
- } else if (!result.ColorSpace) {
- // 推断失败且 exif 中也没有 ColorSpace
- // ignore
- }
-
- return {
- ...date,
- ...size,
- ...result,
- }
-}
-
-export const extractExifData = async (
- imageBuffer: Buffer,
- rawImageBuffer?: Buffer,
- logger?: Logger[keyof Logger],
-): Promise<NeededExif | null> => {
- try {
- return await withRetry(
- async () => {
- let tempImagePath: string | null = null
-
- try {
- // 提取基础元数据
- let metadata = await sharp(imageBuffer).metadata()
-
- // 如果主buffer没有EXIF,尝试原始buffer
- if (!metadata.exif && rawImageBuffer) {
- try {
- metadata = await sharp(rawImageBuffer).metadata()
- } catch (err) {
- logger?.warn(
- 'Error extracting EXIF data from raw image buffer:',
- err,
- )
- }
- }
-
- if (!metadata.exif) {
- logger?.warn('No EXIF data found in image metadata')
- return null
- }
-
- logger?.info('Extracting EXIF data using exiftool...')
-
- // 创建临时工作目录
- const tempDir = path.resolve(process.cwd(), 'data/.exif_workdir')
- await mkdir(tempDir, { recursive: true })
- tempImagePath = path.resolve(tempDir, `${crypto.randomUUID()}.jpg`)
-
- // 写入临时文件
- await writeFile(tempImagePath, rawImageBuffer || imageBuffer)
-
- // 使用 exiftool 读取详细 EXIF 数据
- const exifData = await exiftool.read(tempImagePath)
- const result = processExifData(exifData, metadata)
-
- // 记录颜色空间信息
- if (result.ColorSpace) {
- logger?.success(`Inferred ColorSpace: ${result.ColorSpace}`)
- } else {
- logger?.info('ColorSpace could not be determined')
- }
-
- return result
- } finally {
- // 确保清理临时文件
- if (tempImagePath) {
- await unlink(tempImagePath).catch(noop)
- }
- }
- },
- {
- ...RetryPresets.standard,
- timeout: 15000, // EXIF 处理可能需要更长时间
- retryCondition: (error) => {
- // 组合多种重试条件
- return (
- RetryConditions.fileSystemErrors(error) ||
- RetryConditions.resourceErrors(error) ||
- error.message.includes('timeout')
- )
- },
- },
- logger,
- )
- } catch (error) {
- logger?.error('EXIF extraction failed after all retries:', error)
- return null
- }
-}
-
-const normalizeText = (value: unknown): string | undefined => {
- if (value === null || value === undefined) {
- return undefined
- }
-
- if (Array.isArray(value)) {
- for (const item of value) {
- const normalized = normalizeText(item)
- if (normalized) {
- return normalized
- }
- }
- return undefined
- }
-
- const text = String(value).trim()
- return text.length > 0 ? text : undefined
-}
-
-const collectTextValues = (
- value: unknown,
- options?: { splitDelimited?: boolean },
-): string[] => {
- const splitDelimited = options?.splitDelimited ?? false
- const results: string[] = []
-
- const append = (input: string) => {
- if (splitDelimited) {
- for (const part of input.split(/[;,]/)) {
- const chunk = part.trim()
- if (chunk.length > 0) {
- results.push(chunk)
- }
- }
- } else if (input.length > 0) {
- results.push(input)
- }
- }
-
- if (value === null || value === undefined) {
- return results
- }
-
- if (Array.isArray(value)) {
- for (const item of value) {
- const normalized = normalizeText(item)
- if (normalized) {
- append(normalized)
- }
- }
- return results
- }
-
- const normalized = normalizeText(value)
- if (normalized) {
- append(normalized)
- }
-
- return results
-}
-
-const pickFirstText = (...values: Array<unknown>): string | undefined => {
- for (const value of values) {
- const normalized = normalizeText(value)
- if (normalized) {
- return normalized
- }
- }
-
- return undefined
-}
-
-export const extractPhotoInfo = (
- s3key: string,
- exifData?: NeededExif | null,
-): PhotoInfo => {
- const fileName = path.basename(s3key, path.extname(s3key))
-
- let dateTaken = new Date().toISOString()
- const tagsSet = new Set<string>()
-
- for (const tag of collectTextValues(exifData?.Subject)) {
- tagsSet.add(tag)
- }
-
- for (const tag of collectTextValues(exifData?.Keywords)) {
- tagsSet.add(tag)
- }
-
- for (const tag of collectTextValues(exifData?.XPKeywords, {
- splitDelimited: true,
- })) {
- tagsSet.add(tag)
- }
-
- if (exifData?.DateTimeOriginal) {
- const dateTimeOriginal = toValidISOString(exifData.DateTimeOriginal)
-
- if (dateTimeOriginal) {
- dateTaken = dateTimeOriginal
- } else {
- logger.image.warn(
- `Parse EXIF DateTimeOriginal failed: ${exifData.DateTimeOriginal}`,
- )
- }
- } else {
- // The match may be a false positive inside a longer digit run
- // (e.g. "9101-28-18" in "IMG119101-28-18.jpg"), so validate before use.
- const dateMatch = fileName.match(/(\d{4}-\d{2}-\d{2})/)
- const dateFromFileName = dateMatch
- ? toValidISOString(dateMatch[1]!)
- : undefined
- if (dateFromFileName) {
- dateTaken = dateFromFileName
- }
- }
-
- const titleFromExif = pickFirstText(
- exifData?.Title,
- exifData?.XPTitle,
- exifData?.Description,
- exifData?.ImageDescription,
- exifData?.CaptionAbstract,
- )
-
- let title = titleFromExif
- const cleanedFileName = fileName
- .replaceAll(/\d{4}-\d{2}-\d{2}[_-]?/g, '')
- .replaceAll(/[_-]?\d+views?/gi, '')
- .replaceAll(/[_-]+/g, ' ')
- .trim()
-
- if (!title) {
- title = cleanedFileName || path.basename(s3key, path.extname(s3key))
- }
-
- const description =
- pickFirstText(
- exifData?.Description,
- exifData?.ImageDescription,
- exifData?.CaptionAbstract,
- exifData?.XPComment,
- exifData?.UserComment,
- ) || ''
-
- return {
- title,
- dateTaken,
- tags: [...tagsSet],
- description,
- }
-}
+import { logger } from '../../utils/logger'
+import { createExifService } from '@chronoframe/media/exif'
+export const { extractExifData, extractPhotoInfo } = createExifService({
+ exiftool,
+ tempDir: path.resolve(process.cwd(), 'data/.exif_workdir'),
+ logger: logger.image,
+})
diff --git a/server/services/image/histogram.ts b/server/services/image/histogram.ts
index e62d4b27..d7adc32e 100644
--- a/server/services/image/histogram.ts
+++ b/server/services/image/histogram.ts
@@ -1,77 +1,10 @@
-import sharp from 'sharp'
-
-export interface HistogramData {
- r: number[]
- g: number[]
- b: number[]
- gray: number[]
-}
-
-/**
- * 使用现有的 Sharp 实例计算图片的直方图数据
- * @param sharpInst Sharp 实例
- * @returns 直方图数据,包含 RGB 和灰度通道的 256 个值
- */
-export const calculateHistogram = async (
- sharpInst: sharp.Sharp,
-): Promise<HistogramData> => {
- try {
- // 获取原始像素数据,确保是 RGB 格式
- const { data, info } = await sharpInst
- .clone() // 克隆 Sharp 实例以避免影响原实例
- .removeAlpha() // 移除 alpha 通道
- .raw()
- .toBuffer({ resolveWithObject: true })
-
- const { width, height, channels } = info
- const totalPixels = width * height
- // 初始化直方图数组(256个bin,对应0-255的像素值)
- const histogramR = zeroArray(256)
- const histogramG = zeroArray(256)
- const histogramB = zeroArray(256)
- const histogramGray = zeroArray(256)
-
- // 遍历像素数据计算直方图
- for (let i = 0; i < data.length; i += channels) {
- const r = data[i]
- const g = data[i + 1]
- const b = data[i + 2]
-
- // 累计 RGB 通道直方图
- histogramR[r]++
- histogramG[g]++
- histogramB[b]++
-
- // 计算灰度值(使用 ITU-R BT.709 标准)
- const gray = Math.round(0.299 * r + 0.587 * g + 0.114 * b)
- histogramGray[gray]++
- }
-
- // 归一化直方图(转换为百分比)
- const normalizeHistogram = (hist: number[]) => {
- return hist.map((count) => count / totalPixels)
- }
-
- return {
- r: normalizeHistogram(histogramR),
- g: normalizeHistogram(histogramG),
- b: normalizeHistogram(histogramB),
- gray: normalizeHistogram(histogramGray),
- }
- } catch (error) {
- logger.image.error('Failed to calculate histogram', error)
- throw error
- }
-}
-
-/**
- * 使用图片缓冲区计算直方图数据
- * @param buffer 图片缓冲区
- * @returns 直方图数据
- */
-export const calculateHistogramFromBuffer = async (
- buffer: Buffer,
-): Promise<HistogramData> => {
- const sharpInst = sharp(buffer)
- return calculateHistogram(sharpInst)
-}
+import { logger } from '../../utils/logger'
+import {
+ calculateHistogram as histogram,
+ calculateHistogramFromBuffer as histogramFromBuffer,
+} from '@chronoframe/media/histogram'
+export type { HistogramData } from '@chronoframe/media/histogram'
+export const calculateHistogram = (image: Parameters<typeof histogram>[0]) =>
+ histogram(image, logger.image)
+export const calculateHistogramFromBuffer = (buffer: Buffer) =>
+ histogramFromBuffer(buffer, logger.image)
diff --git a/server/services/image/processor.ts b/server/services/image/processor.ts
index cbb24559..5f6f12a8 100644
--- a/server/services/image/processor.ts
+++ b/server/services/image/processor.ts
@@ -1,212 +1,17 @@
-import path from 'path'
-import bmp from '@vingle/bmp-js'
-import heicConvert from 'heic-convert'
-import { getStorageManager } from '~~/server/plugins/3.storage'
-import sharp from 'sharp'
-import { withRetry, RetryPresets, RetryConditions } from '../../utils/retry'
-
-export interface ProcessedImageData {
- sharpInst: sharp.Sharp
- imageBuffer: Buffer
- metadata: ImageMeta
-}
-
-export interface ImageMeta {
- width: number
- height: number
- format: string
-}
-// Minimal JPEG size extractor as last-resort fallback
-const tryExtractJpegSize = (
- buffer: Buffer,
-): { width: number; height: number } | null => {
- // JPEG starts with 0xFFD8
- if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return null
- let offset = 2
- while (offset + 9 < buffer.length) {
- if (buffer[offset] !== 0xff) {
- offset++
- continue
- }
- const marker = buffer[offset + 1]
- offset += 2
- // Skip padding FFs
- if (marker === 0xff) continue
- // Standalone markers without length
- if (marker === 0xd8 || marker === 0xd9) continue
- const length = (buffer[offset] << 8) + buffer[offset + 1]
- if (length < 2) break
- // SOF0..SOF3 and SOF5..SOF7 indicate dimensions
- if (
- (marker >= 0xc0 && marker <= 0xc3) ||
- (marker >= 0xc5 && marker <= 0xc7)
- ) {
- if (offset + 7 >= buffer.length) break
- const height = (buffer[offset + 3] << 8) + buffer[offset + 4]
- const width = (buffer[offset + 5] << 8) + buffer[offset + 6]
- if (width > 0 && height > 0) return { width, height }
- break
- }
- offset += length
- }
- return null
-}
-
-const isBitmap = (buffer: Buffer) => {
- if (buffer.length < 2) return false
- const header = buffer.toString('hex', 0, 2)
- return header === '424d'
-}
-
-const getMetadataWithSharp = async (
- sharpInst: sharp.Sharp,
-): Promise<ImageMeta | null> => {
- try {
- return await withRetry(
- async () => {
- let metadata = await sharpInst.metadata()
-
- // Fallback 1: try rotate() which can populate dimensions for some orientations
- if (!metadata.height || !metadata.width || !metadata.format) {
- try {
- metadata = await sharpInst.clone().rotate().metadata()
- } catch {
- /* empty */
- }
- }
-
- // Fallback 2: re-instantiate sharp from a fresh buffer
- if (!metadata.height || !metadata.width || !metadata.format) {
- try {
- const buf = await sharpInst.clone().toBuffer()
- metadata = await sharp(buf).metadata()
- } catch {
- /* empty */
- }
- }
-
- // Fallback 3: force re-encode to JPEG then read metadata
- if (!metadata.height || !metadata.width || !metadata.format) {
- try {
- const jpegBuf = await sharpInst.clone().jpeg().toBuffer()
- metadata = await sharp(jpegBuf).metadata()
- if (!metadata.height || !metadata.width) {
- const dims = tryExtractJpegSize(jpegBuf)
- if (dims) {
- metadata.width = dims.width
- metadata.height = dims.height
- metadata.format = metadata.format || 'jpeg'
- }
- }
- } catch {
- /* empty */
- }
- }
-
- if (!metadata.height || !metadata.width || !metadata.format) {
- logger.image.warn('Incomplete metadata received:', {
- hasHeight: !!metadata.height,
- hasWidth: !!metadata.width,
- hasFormat: !!metadata.format,
- })
- return null
- }
-
- const { orientation } = metadata
- let { width, height } = metadata
-
- if (orientation && [5, 6, 7, 8].includes(orientation)) {
- ;[width, height] = [height, width]
- }
-
- logger.image.info(
- `Successfully extracted metadata: ${width}x${height} ${metadata.format}`,
- )
- return {
- width: width,
- height: height,
- format: metadata.format,
- }
- },
- {
- ...RetryPresets.fast,
- timeout: 10000,
- retryCondition: RetryConditions.resourceErrors,
- },
- logger.image,
- )
- } catch (error) {
- logger.image.error('All metadata extraction attempts failed:', error)
- return null
- }
-}
-
-export const convertHeicToJpeg = async (heicBuffer: Buffer) => {
- return await withRetry(
- async () => {
- // 检查文件大小,如果太大则降低质量
- const fileSizeMB = heicBuffer.length / (1024 * 1024)
- const quality = fileSizeMB > 10 ? 0.8 : 0.95
-
- const jpegBuffer = await heicConvert({
- // @ts-expect-error idk why there is a type error here
- buffer: heicBuffer,
- format: 'JPEG',
- quality,
- })
-
- logger.image.info(
- `Successfully converted HEIC to JPEG (quality: ${quality})`,
- )
- return Buffer.from(jpegBuffer as ArrayBuffer)
- },
- {
- ...RetryPresets.slow, // HEIC 转换是重量级操作
- timeout: 30000,
- retryCondition: (error) => {
- // HEIC 转换错误通常是资源相关的
- return (
- RetryConditions.resourceErrors(error) ||
- error.message.includes('memory') ||
- error.message.includes('timeout')
- )
- },
- },
- logger.image,
- )
-}
-
-export const convertBitmapToSharpInst = async (bitmapBuffer: Buffer) => {
- logger.image.info('Converting Bitmap to JPEG...')
- const bmpImage = bmp.decode(bitmapBuffer, true)
- if (!bmpImage) {
- throw new Error('Failed to decode BMP image')
- }
-
- const channels = bmpImage.data.length / (bmpImage.width * bmpImage.height)
- if (channels !== 3 && channels !== 4) {
- throw new Error(`Unsupported BMP channel count: ${channels}`)
- }
-
- return sharp(bmpImage.data, {
- raw: { width: bmpImage.width, height: bmpImage.height, channels },
- }).jpeg()
-}
-
-export const preprocessImageBuffer = async (
- buffer: Buffer,
- key: string,
-): Promise<Buffer> => {
- const extName = path.extname(key).toLowerCase()
-
- if (['.heic', '.heif', '.hif'].includes(extName)) {
- logger.image.info('HEIC image detected', key)
- return await convertHeicToJpeg(buffer)
- }
-
- return buffer
-}
-
+import path from 'node:path'
+import { getStorageManager } from '../../plugins/3.storage'
+import { logger } from '../../utils/logger'
+import { createImageProcessor } from '@chronoframe/media/processor'
+export type {
+ ImageMeta,
+ ProcessedImageData,
+} from '@chronoframe/media/processor'
+export const {
+ convertHeicToJpeg,
+ convertBitmapToSharpInst,
+ preprocessImageBuffer,
+ processImageMetadataAndSharp,
+} = createImageProcessor(logger.image)
export const preprocessImageWithJpegUpload = async (
s3key: string,
): Promise<{
@@ -299,43 +104,3 @@ export const preprocessImage = async (
return null
}
}
-
-export const processImageMetadataAndSharp = async (
- buffer: Buffer,
- s3key: string,
-): Promise<ProcessedImageData | null> => {
- try {
- // Disable input pixel limit to avoid failures on very large images
- let sharpInst = sharp(buffer, { limitInputPixels: false })
- let convertedBuffer = buffer
-
- if (isBitmap(buffer)) {
- logger.image.info('Bitmap image detected, converting to JPEG...', s3key)
- try {
- sharpInst = await convertBitmapToSharpInst(buffer)
- convertedBuffer = await sharpInst.toBuffer()
- } catch (err) {
- logger.image.error(`Bitmap conversion failed: ${s3key}`, err)
- return null
- }
- }
-
- const metadata = await getMetadataWithSharp(sharpInst)
- if (!metadata) {
- logger.image.error(
- 'Metadata extraction returned null (after fallbacks):',
- s3key,
- )
- return null
- }
-
- return {
- sharpInst,
- imageBuffer: convertedBuffer,
- metadata,
- }
- } catch (err) {
- logger.image.error(`Image processing with Sharp failed: ${s3key}`, err)
- return null
- }
-}
diff --git a/server/services/image/thumbnail.ts b/server/services/image/thumbnail.ts
index ad98b0ec..a0aafc59 100644
--- a/server/services/image/thumbnail.ts
+++ b/server/services/image/thumbnail.ts
@@ -1,39 +1 @@
-import sharp from 'sharp'
-import { generateBlurHash } from './blurhash'
-import { withRetry, RetryPresets } from '../../utils/retry'
-
-export const generateThumbnailAndHash = async (
- buffer: Buffer,
- logger?: Logger[keyof Logger],
-) => {
- return await withRetry(
- async () => {
- const sharpInst = sharp(buffer).rotate()
-
- // 根据文件大小调整缩略图质量
- const fileSizeMB = buffer.length / (1024 * 1024)
- const quality = fileSizeMB > 5 ? 85 : 100
-
- const thumbnailBuffer = await sharpInst
- .resize(600, null, {
- withoutEnlargement: true,
- fastShrinkOnLoad: false, // 提高质量
- })
- .webp({ quality })
- .toBuffer()
-
- logger?.info(`Successfully generated thumbnail (quality: ${quality})`)
-
- // 生成BlurHash
- const thumbnailHash = await generateBlurHash(thumbnailBuffer, logger)
-
- return { thumbnailBuffer, thumbnailHash }
- },
- {
- ...RetryPresets.standard,
- timeout: 15000,
- delayStrategy: 'linear', // 图像处理适合线性退避
- },
- logger,
- )
-}
+export * from '@chronoframe/media/thumbnail'
diff --git a/server/services/location/geocoding.ts b/server/services/location/geocoding.ts
index 9833996b..7997a569 100644
--- a/server/services/location/geocoding.ts
+++ b/server/services/location/geocoding.ts
@@ -1,192 +1,24 @@
+import { createGeocodingServices } from '@chronoframe/geocoding'
+import type { GeocodingProvider, LocationInfo } from '@chronoframe/geocoding'
+export type { GeocodingProvider, LocationInfo } from '@chronoframe/geocoding'
import { waitForGeocodingSlot } from './rate-limit'
-import type { NormalizedLocation } from '../../../shared/types/location'
import { hasValidCoordinates } from '../../../shared/utils/location'
-import { normalizeMapbox, normalizeNominatim } from './normalize'
import { withRetry, RetryPresets } from '../../utils/retry'
import { settingsManager } from '../settings/settingsManager'
-
-export interface LocationInfo {
- latitude: number
- longitude: number
- country?: string
- city?: string
- geocoding: NormalizedLocation
- locationName?: string
-}
-
-export interface GeocodingProvider {
- reverseGeocode(lat: number, lon: number): Promise<LocationInfo | null>
-}
-
-/**
- * Mapbox 地理编码提供者
- * 高精度商业地理编码服务,支持全球范围和多语言
- */
-export class MapboxGeocodingProvider implements GeocodingProvider {
- private accessToken: string
- private readonly baseUrl = 'https://api.mapbox.com'
- private readonly rateLimitMs = 100 // Mapbox 默认速率限制为 1000/分钟,约60ms间隔
-
- constructor(accessToken: string) {
- this.accessToken = accessToken
- }
-
- async reverseGeocode(lat: number, lon: number): Promise<LocationInfo | null> {
- try {
- return await withRetry(
- async (signal) => {
- // 应用速率限制
- await waitForGeocodingSlot(this.baseUrl, this.rateLimitMs, signal)
-
- // 获取设置的地理编码语言,默认 'en'
- const language =
- (await settingsManager.get<string>('location', 'language')) || 'en'
-
- const url = new URL('/search/geocode/v6/reverse', this.baseUrl)
- url.searchParams.set('access_token', this.accessToken)
- url.searchParams.set('longitude', lon.toString())
- url.searchParams.set('latitude', lat.toString())
- url.searchParams.set(
- 'types',
- 'address,place,locality,neighborhood,district,region,country',
- )
-
- // 映射 Mapbox 首选语言格式
- let mapboxLang = language
- if (language === 'zh-CN') {
- mapboxLang = 'zh-Hans'
- } else if (language === 'zh-TW') {
- mapboxLang = 'zh-Hant'
- }
- url.searchParams.set('language', mapboxLang)
-
- logger.location.info('Requesting Mapbox reverse geocoding')
-
- const response = await fetch(url.toString(), { signal })
-
- if (!response.ok) {
- throw new Error(
- `Mapbox API error: ${response.status} ${response.statusText}`,
- )
- }
-
- const data = await response.json()
-
- if (!data || !data.features || data.features.length === 0) {
- logger.location.warn('Mapbox API returned no features')
- return null
- }
-
- const geocoding = normalizeMapbox(data, language)
- if (!geocoding) return null
- return {
- latitude: lat,
- longitude: lon,
- geocoding,
- country: geocoding.components.country?.name,
- city: geocoding.components.city?.name,
- locationName: geocoding.formattedAddress,
- }
- },
- {
- ...RetryPresets.network,
- timeout: 10000,
- delayStrategy: 'exponential',
- },
- logger.location,
- )
- } catch (error) {
- logger.location.error(
- 'Mapbox reverse geocoding failed after all retries:',
- error,
- )
- return null
- }
- }
-}
-
-/**
- * OpenStreetMap Nominatim API 地理编码提供者
- * 免费的地理编码服务,适合开发和小规模使用
- */
-export class NominatimGeocodingProvider implements GeocodingProvider {
- private readonly baseUrl: string
- private readonly userAgent = 'chronoframe/1.0'
- private readonly rateLimitMs = 1000 // Nominatim 要求至少1秒间隔
-
- constructor(baseUrl?: string) {
- this.baseUrl = baseUrl || 'https://nominatim.openstreetmap.org'
- }
-
- async reverseGeocode(lat: number, lon: number): Promise<LocationInfo | null> {
- try {
- return await withRetry(
- async (signal) => {
- // 应用速率限制
- await waitForGeocodingSlot(this.baseUrl, this.rateLimitMs, signal)
-
- // 获取设置的地理编码语言,默认 'en'
- const language =
- (await settingsManager.get<string>('location', 'language')) || 'en'
-
- const url = new URL('/reverse', this.baseUrl)
- url.searchParams.set('lat', lat.toString())
- url.searchParams.set('lon', lon.toString())
- url.searchParams.set('format', 'json')
- url.searchParams.set('addressdetails', '1')
- url.searchParams.set('accept-language', `${language},en`)
-
- const response = await fetch(url.toString(), {
- signal,
- headers: {
- 'User-Agent': this.userAgent,
- },
- })
-
- if (!response.ok) {
- throw new Error(
- `Nominatim API error: ${response.status} ${response.statusText}`,
- )
- }
-
- const data = await response.json()
-
- if (!data || data.error) {
- throw new Error(`Nominatim API returned error: ${data?.error}`)
- }
-
- const geocoding = normalizeNominatim(data, language)
- if (!geocoding) return null
- return {
- latitude: lat,
- longitude: lon,
- geocoding,
- country: geocoding.components.country?.name,
- city: geocoding.components.city?.name,
- locationName: geocoding.formattedAddress,
- }
- },
- {
- ...RetryPresets.network,
- timeout: 15000, // Nominatim 可能比较慢
- delayStrategy: 'linear', // 线性退避,避免过快重试
- },
- logger.location,
- )
- } catch (error) {
- logger.location.error(
- 'Nominatim reverse geocoding failed after all retries:',
- error,
- )
- return null
- }
- }
-}
-
-/**
- * 创建地理编码提供者实例
- * @description 优先使用 Mapbox,如果没有配置则回退到 Nominatim
- */
+import { logger } from '../../utils/logger'
+export const {
+ MapboxGeocodingProvider,
+ NominatimGeocodingProvider,
+ parseGPSCoordinates,
+} = createGeocodingServices({
+ getLanguage: async () =>
+ (await settingsManager.get<string>('location', 'language')) || 'en',
+ request: (input, init) => fetch(input, init),
+ waitForGeocodingSlot,
+ withRetry,
+ retryOptions: RetryPresets.network,
+ logger: logger.location,
+})
async function createGeocodingProvider(): Promise<GeocodingProvider> {
// const mapboxToken = useRuntimeConfig().mapbox?.accessToken
const mapboxToken = await settingsManager.get<string>(
@@ -253,42 +85,3 @@ export async function extractLocationFromGPS(
/**
* 解析EXIF GPS数据为十进制度数
*/
-export function parseGPSCoordinates(exifData: any): {
- latitude?: number
- longitude?: number
-} {
- try {
- let latitude: number | undefined
- let longitude: number | undefined
-
- // 尝试从GPSLatitude和GPSLongitude获取
- if (exifData.GPSLatitude != null && exifData.GPSLongitude != null) {
- latitude = parseFloat(exifData.GPSLatitude.toString())
- longitude = parseFloat(exifData.GPSLongitude.toString())
- }
-
- // 如果上面的方法失败,尝试从GPSCoordinates获取
- if (!hasValidCoordinates(latitude, longitude) && exifData.GPSCoordinates) {
- const coords = exifData.GPSCoordinates.toString()
- const match = coords.match(/([-+]?\d+\.?\d*)[°,\s]+([-+]?\d+\.?\d*)/)
- if (match) {
- latitude = parseFloat(match[1])
- longitude = parseFloat(match[2])
- }
- }
-
- // 应用GPS参考(南纬为负,西经为负)
- if (latitude && exifData.GPSLatitudeRef === 'S') {
- latitude = -Math.abs(latitude)
- }
- if (longitude && exifData.GPSLongitudeRef === 'W') {
- longitude = -Math.abs(longitude)
- }
-
- if (!hasValidCoordinates(latitude, longitude)) return {}
- return { latitude, longitude }
- } catch (error) {
- logger.location.error('Failed to parse GPS coordinates:', error)
- return {}
- }
-}
diff --git a/server/services/location/normalize.ts b/server/services/location/normalize.ts
index bd2cf34a..d0c2611f 100644
--- a/server/services/location/normalize.ts
+++ b/server/services/location/normalize.ts
@@ -1,110 +1 @@
-import type {
- LocationLevel,
- NormalizedLocation,
-} from '../../../shared/types/location'
-
-type ObjectValue = Record<string, any>
-const name = (value: unknown): string | undefined =>
- typeof value === 'string' && value.trim() ? value.trim() : undefined
-
-const municipalityCodes = new Set(['CN-BJ', 'CN-TJ', 'CN-SH', 'CN-CQ'])
-
-function applyMunicipality(result: NormalizedLocation, code: unknown) {
- // A direct-administered municipality also acts as the city. Use the explicit
- // ISO subdivision code, rather than guessing from translated name suffixes.
- if (
- result.countryCode === 'CN' &&
- typeof code === 'string' &&
- municipalityCodes.has(code.toUpperCase()) &&
- !result.components.city
- ) {
- result.components.city = result.components.region
- }
-}
-
-function put(
- result: NormalizedLocation,
- level: LocationLevel,
- value: unknown,
- sourceField: string,
-) {
- const text = name(value)
- if (text && !result.components[level])
- result.components[level] = { name: text, sourceField }
-}
-
-export function normalizeMapbox(
- data: ObjectValue,
- language: string,
-): NormalizedLocation | null {
- if (!Array.isArray(data?.features) || !data.features.length) return null
- const result: NormalizedLocation = {
- version: 1,
- provider: 'mapbox',
- language,
- components: {},
- }
- const mapping: Record<string, LocationLevel> = {
- country: 'country',
- region: 'region',
- district: 'subregion',
- place: 'city',
- locality: 'district',
- neighborhood: 'neighborhood',
- }
- for (const feature of data.features) {
- const p = feature.properties || {}
- const context = p.context || {}
- // A country/place response may carry its own name only on the feature.
- const level = mapping[p.feature_type]
- if (level) put(result, level, p.name, `feature.${p.feature_type}`)
- for (const [field, target] of Object.entries(mapping)) {
- put(result, target, context[field]?.name, `context.${field}`)
- }
- result.countryCode ||= name(context.country?.country_code)?.toUpperCase()
- if (p.feature_type === 'country')
- result.countryCode ||= name(p.country_code)?.toUpperCase()
- result.formattedAddress ||=
- name(p.full_address) || name(p.place_formatted) || name(p.name)
- }
- for (const feature of data.features) {
- const p = feature.properties || {}
- applyMunicipality(
- result,
- p.context?.region?.region_code_full ||
- (p.feature_type === 'region' ? p.region_code_full : undefined),
- )
- }
- return Object.keys(result.components).length ? result : null
-}
-
-export function normalizeNominatim(
- data: ObjectValue,
- language: string,
-): NormalizedLocation | null {
- if (!data || data.error) return null
- const result: NormalizedLocation = {
- version: 1,
- provider: 'nominatim',
- language,
- components: {},
- countryCode: name(data.address?.country_code)?.toUpperCase(),
- formattedAddress: name(data.display_name),
- }
- // Preserve source tags: county/state_district must not be treated as city districts.
- const mapping: Array<[LocationLevel, string[]]> = [
- ['country', ['country']],
- ['region', ['state', 'region']],
- ['subregion', ['state_district', 'county']],
- ['city', ['city', 'town', 'municipality', 'village', 'hamlet']],
- ['district', ['city_district', 'district', 'borough']],
- ['locality', ['suburb', 'subdivision']],
- ['neighborhood', ['neighbourhood', 'quarter']],
- ]
- for (const [level, fields] of mapping) {
- for (const field of fields)
- put(result, level, data.address?.[field], `address.${field}`)
- }
- applyMunicipality(result, data.address?.['ISO3166-2-lvl4'])
- return Object.keys(result.components).length ? result : null
-}
+export * from '@chronoframe/geocoding/normalize'
diff --git a/server/services/location/rate-limit.ts b/server/services/location/rate-limit.ts
index 840190cc..2b30db7a 100644
--- a/server/services/location/rate-limit.ts
+++ b/server/services/location/rate-limit.ts
@@ -1,16 +1,2 @@
-import { setTimeout } from 'node:timers/promises'
-
-const nextRequestAt = new Map<string, number>()
-
-// Reserve synchronously before waiting so separate providers/workers cannot
-// start together after the same delay. Providers are recreated for each photo.
-export async function waitForGeocodingSlot(
- key: string,
- intervalMs: number,
- signal?: AbortSignal,
-) {
- const now = Date.now()
- const start = Math.max(now, nextRequestAt.get(key) || 0)
- nextRequestAt.set(key, start + intervalMs)
- if (start > now) await setTimeout(start - now, undefined, { signal })
-}
+import { createGeocodingRateLimiter } from '@chronoframe/geocoding/rate-limit'
+export const waitForGeocodingSlot = createGeocodingRateLimiter()
diff --git a/server/services/settings/settingsManager.ts b/server/services/settings/settingsManager.ts
index a21b6308..27501754 100644
--- a/server/services/settings/settingsManager.ts
+++ b/server/services/settings/settingsManager.ts
@@ -1,7 +1,10 @@
+import type {} from '../../types/worker'
+import type {
+ NewStorageProviderRow as NewSettingStorageProvider,
+ StorageProviderRow as SettingStorageProvider,
+} from '../../types/settings'
import type {
- NewSettingStorageProvider,
SettingConfig,
- SettingStorageProvider,
SettingType,
SettingValue,
} from '~~/shared/types/settings'
diff --git a/server/services/storage/index.ts b/server/services/storage/index.ts
index 07e1ce40..f1ea432d 100644
--- a/server/services/storage/index.ts
+++ b/server/services/storage/index.ts
@@ -1,31 +1,4 @@
-export type { StorageProvider, StorageObject } from './interfaces'
-
-export {
- s3StorageConfigSchema,
- localStorageConfigSchema,
- openListStorageConfigSchema,
- storageConfigSchema,
-} from '@chronoframe/contracts/storage'
-
-export type {
- S3StorageConfig,
- LocalStorageConfig,
- OpenListStorageConfig,
- StorageConfig,
-} from '@chronoframe/contracts/storage'
-
-export { StorageProviderFactory, StorageManager } from './manager'
-
-export type {
- StorageManagerEventType,
- StorageManagerEventListener,
- StorageManagerEvent,
-} from './manager'
-
-export { S3StorageProvider } from './providers/s3'
-export { LocalStorageProvider } from './providers/local'
-export { OpenListStorageProvider } from './providers/openlist'
-
+export * from '@chronoframe/storage'
export {
setGlobalStorageManager,
getGlobalStorageManager,
diff --git a/server/services/storage/interfaces.ts b/server/services/storage/interfaces.ts
index 38abc2cc..d49800fe 100644
--- a/server/services/storage/interfaces.ts
+++ b/server/services/storage/interfaces.ts
@@ -1,56 +1 @@
-import type { StorageConfig } from '.'
-import type { UploadPart, UploadPlan } from '@chronoframe/contracts/upload'
-
-export type DirectUploadSetup =
- | Extract<UploadPlan, { mode: 'single' | 'range' }>
- | {
- mode: 'multipart'
- partSize: number
- partUrls: string[]
- complete(parts: UploadPart[]): Promise<void>
- abort(): Promise<void>
- }
-
-export interface StorageObject {
- key: string
- size?: number
- etag?: string
- lastModified?: Date
-}
-
-export interface UploadOptions {
- contentType?: string
- metadata?: Record<string, string>
- encryption?: boolean
- ttl?: number
-}
-
-export interface StorageProvider {
- config?: StorageConfig
- prepareDirectUpload?(
- key: string,
- size: number,
- contentType: string,
- ): Promise<DirectUploadSetup | null>
- createFromFile(
- key: string,
- filePath: string,
- contentType: string,
- ): Promise<StorageObject>
- create(
- key: string,
- fileBuffer: Buffer,
- contentType?: string,
- ): Promise<StorageObject>
- delete(key: string): Promise<void>
- get(key: string): Promise<Buffer | null>
- getPublicUrl(key: string): string
- getSignedUrl?(
- key: string,
- expiresIn?: number,
- options?: UploadOptions,
- ): Promise<string>
- getFileMeta(key: string): Promise<StorageObject | null>
- listAll(): Promise<StorageObject[]>
- listImages(): Promise<StorageObject[]>
-}
+export * from '@chronoframe/storage/interfaces'
diff --git a/server/services/storage/manager.ts b/server/services/storage/manager.ts
index 6478985b..b6b14abf 100644
--- a/server/services/storage/manager.ts
+++ b/server/services/storage/manager.ts
@@ -1,172 +1 @@
-import type { StorageConfig, StorageProvider } from '.'
-import { S3StorageProvider } from '.'
-import type { Logger } from '../../utils/logger'
-import { LocalStorageProvider } from './providers/local'
-import { OpenListStorageProvider } from './providers/openlist'
-
-export type StorageManagerEventType = 'provider-changed' | 'provider-error'
-
-export interface StorageManagerEventListener {
- (event: StorageManagerEvent): void | Promise<void>
-}
-
-export interface StorageManagerEvent {
- type: StorageManagerEventType
- provider?: string
- oldProvider?: string
- error?: Error
- timestamp: number
-}
-
-export class StorageProviderFactory {
- static createProvider(
- config: StorageConfig,
- logger?: Logger['storage'],
- ): StorageProvider {
- switch (config.provider) {
- case 's3':
- return new S3StorageProvider(config, logger)
- case 'local':
- return new LocalStorageProvider(config, logger)
- case 'openlist':
- return new OpenListStorageProvider(config as any, logger)
- default:
- throw new Error(`Unknown storage provider`)
- }
- }
-}
-
-export class StorageManager {
- private provider: StorageProvider
- private logger?: Logger['storage']
- private eventListeners: Map<
- StorageManagerEventType,
- StorageManagerEventListener[]
- > = new Map()
- private currentProviderName?: string
-
- constructor(config: StorageConfig, logger?: Logger['storage']) {
- this.logger = logger
- this.logger?.info(`Creating storage provider: ${config.provider}`)
- this.currentProviderName = config.provider
- this.provider = StorageProviderFactory.createProvider(config, logger)
- }
-
- /**
- * Register event listener for storage manager events
- * @param eventType Type of event to listen for
- * @param listener Event listener callback
- */
- public on(
- eventType: StorageManagerEventType,
- listener: StorageManagerEventListener,
- ): void {
- if (!this.eventListeners.has(eventType)) {
- this.eventListeners.set(eventType, [])
- }
- this.eventListeners.get(eventType)!.push(listener)
- this.logger?.debug(`Event listener registered for: ${eventType}`)
- }
-
- /**
- * Unregister event listener
- * @param eventType Type of event
- * @param listener Event listener callback
- */
- public off(
- eventType: StorageManagerEventType,
- listener: StorageManagerEventListener,
- ): void {
- const listeners = this.eventListeners.get(eventType)
- if (listeners) {
- const index = listeners.indexOf(listener)
- if (index > -1) {
- listeners.splice(index, 1)
- this.logger?.debug(`Event listener unregistered for: ${eventType}`)
- }
- }
- }
-
- /**
- * Emit event to all registered listeners
- * @param event Event to emit
- */
- private async emitEvent(event: StorageManagerEvent): Promise<void> {
- const listeners = this.eventListeners.get(event.type) || []
- for (const listener of listeners) {
- try {
- await listener(event)
- } catch (error) {
- this.logger?.error(`Error in event listener for ${event.type}:`, error)
- }
- }
- }
-
- /**
- * Register/switch storage provider
- * @param config New storage configuration
- * @param logger Optional logger instance
- */
- async registerProvider(
- config: StorageConfig,
- logger?: Logger['storage'],
- ): Promise<void> {
- try {
- const oldProviderName = this.currentProviderName
- this.logger = logger || this.logger
-
- this.logger?.info(
- `Switching storage provider from ${oldProviderName} to ${config.provider}`,
- )
-
- const newProvider = StorageProviderFactory.createProvider(
- config,
- this.logger,
- )
- this.provider = newProvider
- this.currentProviderName = config.provider
-
- this.logger?.success(`Storage provider switched to: ${config.provider}`)
-
- // Emit provider-changed event
- await this.emitEvent({
- type: 'provider-changed',
- provider: config.provider,
- oldProvider: oldProviderName,
- timestamp: Date.now(),
- })
- } catch (error) {
- this.logger?.error(
- `Failed to register storage provider: ${config.provider}`,
- error,
- )
-
- // Emit provider-error event
- await this.emitEvent({
- type: 'provider-error',
- provider: config.provider,
- error: error as Error,
- timestamp: Date.now(),
- })
-
- throw error
- }
- }
-
- /**
- * Get current storage provider
- */
- getProvider<T extends StorageProvider>(): T {
- if (!this.provider) {
- throw new Error(`Storage provider not registered`)
- }
- return this.provider as T
- }
-
- /**
- * Get current provider name
- */
- getCurrentProviderName(): string | undefined {
- return this.currentProviderName
- }
-}
+export * from '@chronoframe/storage/manager'
diff --git a/server/services/storage/providers/local.ts b/server/services/storage/providers/local.ts
index 4d0f5167..9d5000ed 100644
--- a/server/services/storage/providers/local.ts
+++ b/server/services/storage/providers/local.ts
@@ -1,146 +1 @@
-import { promises as fs } from 'node:fs'
-import path from 'node:path'
-import type { StorageObject, StorageProvider } from '../interfaces'
-
-const ensureDir = async (dirPath: string) => {
- await fs.mkdir(dirPath, { recursive: true })
-}
-
-const sanitizeKey = (key: string) =>
- key.replace(/\\/g, '/').replace(/\/+/g, '/').replace(/^\/+/, '')
-
-const combinePrefixAndKey = (prefix: string | undefined, key: string) => {
- const cleanPrefix = (prefix || '').replace(/^\/+|\/+$/g, '')
- const cleanKey = key.replace(/^\/+/, '')
- if (!cleanPrefix) return cleanKey
- return cleanKey.startsWith(cleanPrefix + '/')
- ? cleanKey
- : `${cleanPrefix}/${cleanKey}`
-}
-
-export class LocalStorageProvider implements StorageProvider {
- config: LocalStorageConfig
- private logger?: Logger['storage']
-
- constructor(config: LocalStorageConfig, logger?: Logger['storage']) {
- this.config = config
- this.logger = logger
- }
-
- private resolveAbsoluteKey(key: string): { absFile: string; relKey: string } {
- const relKey = sanitizeKey(combinePrefixAndKey(this.config.prefix, key))
- const absFile = path.resolve(this.config.basePath, relKey)
- return { absFile, relKey }
- }
-
- async create(key: string, fileBuffer: Buffer): Promise<StorageObject> {
- const { absFile, relKey } = this.resolveAbsoluteKey(key)
- await ensureDir(path.dirname(absFile))
- // 原子写入:写到临时文件再重命名
- const tempFile = `${absFile}.tmp-${Date.now()}`
- await fs.writeFile(tempFile, fileBuffer)
- await fs.rename(tempFile, absFile)
- const stat = await fs.stat(absFile)
- this.logger?.success?.(`Saved file: ${absFile}`)
- return {
- key: relKey,
- size: stat.size,
- lastModified: stat.mtime,
- }
- }
-
- async createFromFile(key: string, filePath: string): Promise<StorageObject> {
- const { absFile, relKey } = this.resolveAbsoluteKey(key)
- await ensureDir(path.dirname(absFile))
- const tempFile = `${absFile}.tmp-${crypto.randomUUID()}`
- try {
- await fs.copyFile(filePath, tempFile)
- await fs.rename(tempFile, absFile)
- const stat = await fs.stat(absFile)
- return { key: relKey, size: stat.size, lastModified: stat.mtime }
- } finally {
- await fs.rm(tempFile, { force: true })
- }
- }
-
- async delete(key: string): Promise<void> {
- const { absFile } = this.resolveAbsoluteKey(key)
- try {
- await fs.unlink(absFile)
- this.logger?.success?.(`Deleted file: ${absFile}`)
- } catch (err) {
- // ignore if not exists
- if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
- }
- }
-
- async get(key: string): Promise<Buffer | null> {
- const { absFile } = this.resolveAbsoluteKey(key)
- try {
- return await fs.readFile(absFile)
- } catch (err) {
- if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
- throw err
- }
- }
-
- getPublicUrl(key: string): string {
- const relKey = sanitizeKey(combinePrefixAndKey(this.config.prefix, key))
- const base = (this.config.baseUrl || '/storage').replace(/\/+$/, '')
- return `${base}/${relKey}`
- }
-
- async listAll(): Promise<StorageObject[]> {
- const results: StorageObject[] = []
- const baseDir = this.config.prefix
- ? path.resolve(this.config.basePath, this.config.prefix)
- : this.config.basePath
-
- const walk = async (dir: string, relBase: string) => {
- const entries = await fs.readdir(dir, { withFileTypes: true })
- for (const entry of entries) {
- const abs = path.join(dir, entry.name)
- const rel = sanitizeKey(path.join(relBase, entry.name))
- if (entry.isDirectory()) {
- await walk(abs, rel)
- } else if (entry.isFile()) {
- const stat = await fs.stat(abs)
- results.push({ key: rel, size: stat.size, lastModified: stat.mtime })
- }
- }
- }
-
- await ensureDir(baseDir)
- await walk(baseDir, this.config.prefix || '')
- return results
- }
-
- async listImages(): Promise<StorageObject[]> {
- const all = await this.listAll()
- return all.filter((o) => /\.(png|jpe?g|webp|gif|bmp|tiff?)$/i.test(o.key))
- }
-
- async getFileMeta(key: string): Promise<StorageObject | null> {
- // First try with combined prefix
- const { absFile, relKey } = this.resolveAbsoluteKey(key)
- try {
- const stat = await fs.stat(absFile)
- if (!stat.isFile()) return null
- return { key: relKey, size: stat.size, lastModified: stat.mtime }
- } catch (err) {
- if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
- }
-
- // Fallback: try without adding prefix (in case key already contains it or was stored raw)
- const rawRel = sanitizeKey(key)
- const rawAbs = path.resolve(this.config.basePath, rawRel)
- try {
- const stat = await fs.stat(rawAbs)
- if (!stat.isFile()) return null
- return { key: rawRel, size: stat.size, lastModified: stat.mtime }
- } catch (err) {
- if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
- throw err
- }
- }
-}
+export * from '@chronoframe/storage/providers/local'
diff --git a/server/services/storage/providers/openlist.ts b/server/services/storage/providers/openlist.ts
index 4d9479a7..d3a2e8d9 100644
--- a/server/services/storage/providers/openlist.ts
+++ b/server/services/storage/providers/openlist.ts
@@ -1,392 +1 @@
-import type { Logger } from '../../../utils/logger'
-import { createReadStream } from 'node:fs'
-import { stat } from 'node:fs/promises'
-import type {
- StorageProvider,
- StorageObject,
- DirectUploadSetup,
-} from '../interfaces'
-import path from 'node:path'
-
-/**
- * OpenListStorageProvider implements StorageProvider for OpenList API.
- * Since OpenList API endpoints may vary by deployment, we keep them configurable.
- */
-export class OpenListStorageProvider implements StorageProvider {
- config: OpenListStorageConfig
- private logger?: Logger['storage']
- private token?: string
-
- constructor(config: OpenListStorageConfig, logger?: Logger['storage']) {
- this.config = config
- this.logger = logger
- }
-
- private get baseUrl() {
- return this.config.baseUrl.replace(/\/$/, '')
- }
-
- private get pathField(): string {
- return this.config.pathField || 'path'
- }
-
- private async ensureAuthToken(): Promise<string> {
- if (this.token) return this.token
- if (this.config.token) {
- this.token = this.config.token
- return this.token
- }
-
- throw new Error(
- 'OpenList auth requires a token. Please configure NUXT_PROVIDER_OPENLIST_TOKEN.',
- )
- }
-
- private async request(
- path: string,
- init: RequestInit = {},
- ): Promise<Response> {
- const token = await this.ensureAuthToken()
- const url = `${this.baseUrl}${path}`
- const headers: Record<string, string> = {
- ...(init.headers as Record<string, string> | undefined),
- Authorization: token,
- }
- return fetch(url, { ...init, headers })
- }
-
- private normalizedRoot(): string {
- return (this.config.rootPath || '').replace(/\/+$/g, '').replace(/^\/+/, '')
- }
-
- private withRoot(key: string): string {
- const root = this.normalizedRoot()
- const trimmedKey = key.replace(/^\/+/, '')
- if (!root) {
- return trimmedKey
- }
- if (trimmedKey === root || trimmedKey.startsWith(`${root}/`)) {
- return trimmedKey
- }
- return `${root}/${trimmedKey}`
- }
-
- private toAbsolutePath(key: string): string {
- if (!key || key === '/') {
- return '/'
- }
- return key.startsWith('/') ? key : `/${key}`
- }
-
- async create(
- key: string,
- fileBuffer: Buffer,
- contentType?: string,
- ): Promise<StorageObject> {
- const rootedKey = this.withRoot(key)
- const absoluteKey = this.toAbsolutePath(rootedKey)
- const uploadPath = this.config.uploadEndpoint || '/api/fs/put'
-
- const resp = await this.request(uploadPath, {
- method: 'PUT',
- headers: {
- 'Content-Type': contentType || 'application/octet-stream',
- 'Content-Length': String(fileBuffer.length),
- 'File-Path': encodeURIComponent(absoluteKey),
- },
- body: new Uint8Array(fileBuffer),
- })
-
- if (!resp.ok) {
- const text = await resp.text().catch(() => '')
- this.logger?.error('OpenList upload failed', {
- status: resp.status,
- body: text,
- })
- throw new Error(`OpenList upload failed: ${resp.status}`)
- }
-
- this.logger?.success(`Uploaded object: ${absoluteKey}`)
- this.logger?.debug?.('OpenList upload details', {
- originalKey: key,
- rootedKey,
- absoluteKey,
- rootPath: this.normalizedRoot(),
- })
-
- const meta = await this.getFileMeta(rootedKey).catch((error) => {
- this.logger?.warn('Uploaded object metadata lookup failed:', error)
- return null
- })
- return (
- meta || {
- key: rootedKey,
- size: fileBuffer.length,
- lastModified: new Date(),
- }
- )
- }
-
- async delete(key: string): Promise<void> {
- const deletePath = this.config.deleteEndpoint || '/api/fs/remove'
- const urlPath = `${deletePath}`
- const rootedKey = this.withRoot(key)
- const normalized = rootedKey.replace(/^\/+/, '')
- const slashIdx = normalized.lastIndexOf('/')
- const dir = this.toAbsolutePath(
- slashIdx >= 0 ? normalized.slice(0, slashIdx) : this.normalizedRoot(),
- )
- const name = slashIdx >= 0 ? normalized.slice(slashIdx + 1) : normalized
- const body = { dir, names: [name] }
-
- const resp = await this.request(urlPath, {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify(body),
- })
- if (!resp.ok) {
- const text = await resp.text().catch(() => '')
- this.logger?.error('OpenList delete failed', {
- status: resp.status,
- body: text,
- })
- throw new Error(`OpenList delete failed: ${resp.status}`)
- }
- this.logger?.success(`Deleted object: ${key}`)
- }
-
- async createFromFile(
- key: string,
- filePath: string,
- contentType: string,
- ): Promise<StorageObject> {
- const { size } = await stat(filePath)
- const body = createReadStream(filePath)
- try {
- const init = {
- method: 'PUT',
- duplex: 'half',
- headers: {
- 'Content-Type': contentType,
- 'Content-Length': String(size),
- 'File-Path': encodeURIComponent(
- this.toAbsolutePath(this.withRoot(key)),
- ),
- },
- body,
- }
- const response = await this.request(
- this.config.uploadEndpoint || '/api/fs/put',
- init as unknown as RequestInit,
- )
- if (!response.ok)
- throw new Error(`OpenList upload failed: ${response.status}`)
- const result = (await response.json()) as {
- code?: number
- message?: string
- }
- if (result.code !== undefined && result.code !== 200)
- throw new Error(result.message || 'OpenList upload failed')
- return { key: this.withRoot(key), size }
- } finally {
- body.destroy()
- }
- }
-
- async prepareDirectUpload(
- key: string,
- size: number,
- ): Promise<DirectUploadSetup | null> {
- const absoluteKey = this.toAbsolutePath(this.withRoot(key))
- const response = await this.request('/api/fs/get_direct_upload_info', {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify({
- path: path.posix.dirname(absoluteKey),
- file_name: path.posix.basename(absoluteKey),
- file_size: size,
- tool: 'HttpDirect',
- }),
- })
- if ([404, 405, 501].includes(response.status)) return null
- if (!response.ok)
- throw new Error(
- `OpenList direct upload preparation failed: ${response.status}`,
- )
- const result = (await response.json()) as {
- code: number
- message?: string
- data?: {
- upload_url?: string
- chunk_size?: number
- method?: string
- headers?: Record<string, string>
- } | null
- }
- if (result.code !== 200) {
- if (
- [404, 405, 501].includes(result.code) ||
- /not supported|unsupported|not implement/i.test(result.message || '')
- )
- return null
- throw new Error(
- result.message || 'OpenList direct upload preparation failed',
- )
- }
- const info = result.data
- if (!info?.upload_url) return null
- if (info.method && !['PUT', 'POST'].includes(info.method.toUpperCase()))
- return null
- const url = new URL(info.upload_url)
- if (!['http:', 'https:'].includes(url.protocol))
- throw new Error('Invalid OpenList upload URL')
- const token = await this.ensureAuthToken()
- if (
- info.upload_url.includes(token) ||
- Object.values(info.headers || {}).some((value) => value.includes(token))
- ) {
- throw new Error('OpenList direct upload returned the server credential')
- }
- const common = {
- url: info.upload_url,
- method: (info.method?.toUpperCase() || 'PUT') as 'PUT' | 'POST',
- headers: info.headers,
- }
- if ((info.chunk_size ?? 0) > 0) {
- if (!Number.isSafeInteger(info.chunk_size))
- throw new Error('Invalid OpenList upload chunk size')
- // OpenList's HttpDirect protocol uses sequential Content-Range requests.
- // It does not advertise random-order/concurrent writes to this URL.
- return { mode: 'range', partSize: info.chunk_size!, ...common }
- }
- return { mode: 'single', ...common }
- }
-
- async get(key: string): Promise<Buffer | null> {
- // If download endpoint is not provided, try to resolve raw_url via meta and fetch it
- const downloadPath = this.config.downloadEndpoint
- if (!downloadPath) {
- const info = await this.getFileMeta(this.withRoot(key))
- const rawUrl = (info as any)?.raw_url || undefined
- if (!rawUrl) return null
- const resp = await fetch(rawUrl)
- if (!resp.ok) return null
- const arrayBuffer = await resp.arrayBuffer().catch(() => null)
- if (!arrayBuffer) return null
- return Buffer.from(arrayBuffer)
- }
-
- const rootedKey = this.withRoot(key)
- const urlPath = `${downloadPath}?${encodeURIComponent(this.pathField)}=${encodeURIComponent(rootedKey)}`
- const resp = await this.request(urlPath, { method: 'GET' })
- if (!resp.ok) return null
- const arrayBuffer = await resp.arrayBuffer().catch(() => null)
- if (!arrayBuffer) return null
- return Buffer.from(arrayBuffer)
- }
-
- getPublicUrl(key: string): string {
- const rootedKey = this.withRoot(key)
- const { cdnUrl, baseUrl } = this.config
- const base = cdnUrl || (baseUrl ? `${baseUrl.replace(/\/$/, '')}/d` : '')
- if (!base) {
- return ''
- }
- return `${base.replace(/\/$/, '')}/${rootedKey}`
- }
-
- async getFileMeta(key: string): Promise<StorageObject | null> {
- const metaPath =
- this.config.metaEndpoint || this.config.downloadEndpoint || '/api/fs/get'
- const rootedKey = this.withRoot(key)
- const urlPath = metaPath
- const payload: Record<string, any> = {
- [this.pathField]: this.toAbsolutePath(rootedKey),
- password: '',
- page: 1,
- per_page: 0,
- refresh: false,
- }
- const resp = await this.request(urlPath, {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify(payload),
- })
- if (!resp.ok) {
- const text = await resp.text().catch(() => '')
- this.logger?.error('OpenList get file meta failed', {
- status: resp.status,
- body: text,
- })
- if (resp.status === 404) return null
- throw new Error(`OpenList metadata request failed: ${resp.status}`)
- }
-
- const data = (await resp.json().catch(() => null)) as any
- if (!data) throw new Error('Invalid OpenList metadata response')
- if (typeof data.code === 'number' && data.code !== 200) {
- if (data.code === 404) return null
- throw new Error(`OpenList metadata error: ${data.code}`)
- }
- const node = data?.data || {}
- const size = node?.size
- const modified = node?.modified || node?.lastModified
- const etag = node?.etag
- const rawUrl = node?.raw_url
- const result: StorageObject = {
- key: rootedKey,
- size: typeof size === 'number' ? size : undefined,
- lastModified: modified ? new Date(modified) : undefined,
- etag: typeof etag === 'string' ? etag : undefined,
- }
- // Attach raw_url as non-standard property for internal usage
- ;(result as any).raw_url = typeof rawUrl === 'string' ? rawUrl : undefined
- return result
- }
-
- async listAll(): Promise<StorageObject[]> {
- // Listing API not provided explicitly; return empty array by default.
- // You can configure custom list endpoint and parsing later.
- const listPath = this.config.listEndpoint
- if (!listPath) return []
-
- const payload: Record<string, any> = {
- [this.pathField]: this.toAbsolutePath(this.normalizedRoot()),
- password: '',
- page: 1,
- per_page: 0,
- refresh: false,
- }
- const resp = await this.request(listPath, {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify(payload),
- })
- if (!resp.ok) return []
- const data = (await resp.json().catch(() => null)) as any
- const items: any[] = data?.data || data || []
- return items
- .map((item) => {
- const rawKey = item?.path || item?.key || item?.name
- if (!rawKey) return null
- const rootedKey = this.withRoot(rawKey)
- const size = item?.size
- const lastModified = item?.modified || item?.lastModified || item?.mtime
- const etag = item?.etag
- return {
- key: rootedKey,
- size: typeof size === 'number' ? size : undefined,
- lastModified: lastModified ? new Date(lastModified) : undefined,
- etag: typeof etag === 'string' ? etag : undefined,
- } as StorageObject
- })
- .filter(Boolean) as StorageObject[]
- }
-
- async listImages(): Promise<StorageObject[]> {
- const all = await this.listAll()
- return all.filter((obj) =>
- /\.(jpe?g|png|webp|gif|bmp|tiff?|heic|heif)$/i.test(obj.key),
- )
- }
-}
+export * from '@chronoframe/storage/providers/openlist'
diff --git a/server/services/storage/providers/s3.ts b/server/services/storage/providers/s3.ts
index 160b5605..a78a29ec 100644
--- a/server/services/storage/providers/s3.ts
+++ b/server/services/storage/providers/s3.ts
@@ -1,464 +1 @@
-import type { _Object, S3ClientConfig } from '@aws-sdk/client-s3'
-import {
- DeleteObjectCommand,
- GetObjectCommand,
- HeadObjectCommand,
- ListObjectsCommand,
- PutObjectCommand,
- S3Client,
- CreateMultipartUploadCommand,
- UploadPartCommand,
- CompleteMultipartUploadCommand,
- AbortMultipartUploadCommand,
- ListPartsCommand,
-} from '@aws-sdk/client-s3'
-import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
-import { createReadStream } from 'node:fs'
-import { stat } from 'node:fs/promises'
-import type {
- StorageObject,
- StorageProvider,
- UploadOptions,
- DirectUploadSetup,
-} from '../interfaces'
-import { UPLOAD_CHUNK_SIZE } from '../../../../shared/utils/upload'
-import { logUpload } from '../../../utils/upload-log'
-
-const createClient = (config: S3StorageConfig): S3Client => {
- if (config.provider !== 's3') {
- throw new Error('Invalid provider for S3 client creation')
- }
-
- const { accessKeyId, secretAccessKey, region, endpoint } = config
- if (!accessKeyId || !secretAccessKey) {
- throw new Error('Missing required accessKeyId or secretAccessKey')
- }
-
- const clientConfig: S3ClientConfig = {
- endpoint,
- region,
- forcePathStyle: config.forcePathStyle,
- responseChecksumValidation: 'WHEN_REQUIRED',
- requestChecksumCalculation: 'WHEN_REQUIRED',
- credentials: {
- accessKeyId,
- secretAccessKey,
- },
- }
-
- return new S3Client(clientConfig)
-}
-
-const convertToStorageObject = (s3object: _Object): StorageObject => {
- return {
- key: s3object.Key || '',
- size: s3object.Size,
- lastModified: s3object.LastModified,
- etag: s3object.ETag,
- }
-}
-
-export class S3StorageProvider implements StorageProvider {
- config: S3StorageConfig
- private logger?: Logger['storage']
- private client: S3Client
-
- constructor(config: S3StorageConfig, logger?: Logger['storage']) {
- this.config = config
- this.logger = logger
- this.client = createClient(config)
- }
-
- async create(
- key: string,
- data: Buffer,
- contentType?: string,
- ): Promise<StorageObject> {
- try {
- const absoluteKey =
- `${(this.config.prefix || '').replace(/\/+$/, '')}/${key}`.replace(
- /^\/+/,
- '',
- )
- const cmd = new PutObjectCommand({
- Bucket: this.config.bucket,
- Key: absoluteKey,
- Body: data,
- ContentType: contentType || 'application/octet-stream',
- })
-
- const resp = await this.client.send(cmd)
-
- this.logger?.success(`Created object with key: ${absoluteKey}`)
-
- return {
- key: absoluteKey,
- size: data.length,
- lastModified: new Date(),
- etag: resp.ETag,
- }
- } catch (error) {
- this.logger?.error(`Failed to create object with key: ${key}`, error)
- throw error
- }
- }
-
- async delete(key: string): Promise<void> {
- try {
- const cmd = new DeleteObjectCommand({
- Bucket: this.config.bucket,
- Key: key,
- })
-
- await this.client.send(cmd)
- this.logger?.success(`Deleted object with key: ${key}`)
- } catch (error) {
- this.logger?.error(`Failed to delete object with key: ${key}`, error)
- throw error
- }
- }
-
- async createFromFile(
- key: string,
- filePath: string,
- contentType: string,
- ): Promise<StorageObject> {
- const { size } = await stat(filePath)
- const body = createReadStream(filePath)
- try {
- const result = await this.client.send(
- new PutObjectCommand({
- Bucket: this.config.bucket,
- Key: key,
- Body: body,
- ContentLength: size,
- ContentType: contentType,
- }),
- )
- return { key, size, etag: result.ETag }
- } finally {
- body.destroy()
- }
- }
-
- async get(key: string): Promise<Buffer | null> {
- try {
- const cmd = new GetObjectCommand({
- Bucket: this.config.bucket,
- Key: key,
- })
-
- const resp = await this.client.send(cmd)
-
- if (!resp.Body) {
- return null
- }
-
- if (resp.Body instanceof Buffer) {
- return resp.Body
- }
-
- const chunks: Uint8Array[] = []
- const stream = resp.Body as NodeJS.ReadableStream
-
- return new Promise<Buffer>((resolve, reject) => {
- stream.on('data', (chunk: Uint8Array) => {
- chunks.push(chunk)
- })
-
- stream.on('end', () => {
- resolve(Buffer.concat(chunks))
- })
-
- stream.on('error', (err) => {
- reject(err)
- })
- })
- } catch {
- return null
- }
- }
-
- getPublicUrl(key: string): string {
- const { cdnUrl, bucket, region, endpoint } = this.config
-
- // CDN URL
- if (cdnUrl) {
- return `${cdnUrl.replace(/\/$/, '')}/${key}`
- }
-
- // Default AWS S3 endpoint
- if (!endpoint) {
- return `https://${bucket}.s3.${region}.amazonaws.com/${key}`
- } else if (endpoint.includes('amazonaws.com')) {
- return `https://${bucket}.s3.${region}.amazonaws.com/${key}`
- }
-
- // Alibaba Cloud OSS
- if (endpoint.includes('aliyuncs.com')) {
- const baseUrl = endpoint.replace(/\/$/, '')
- if (baseUrl.indexOf('//') === -1) {
- throw new Error('Invalid endpoint URL')
- }
- const protocol = baseUrl.split('//')[0]
- const remainder = baseUrl.split('//')[1]
- return `${protocol}//${bucket}.${remainder}/${key}`
- }
-
- // Custom endpoint
- return `${endpoint.replace(/\/$/, '')}/${bucket}/${key}`
- }
-
- async getSignedUrl(
- key: string,
- expiresIn: number = 3600,
- options?: UploadOptions,
- ): Promise<string> {
- const cmd = new PutObjectCommand({
- Bucket: this.config.bucket,
- Key: key,
- ContentType: options?.contentType || 'application/octet-stream',
- })
-
- const url = await getSignedUrl(this.client, cmd, {
- expiresIn,
- // 为了更好的 CORS 支持,添加一些额外参数
- unhoistableHeaders: new Set(['Content-Type']),
- })
- return url
- }
-
- async prepareDirectUpload(
- key: string,
- size: number,
- contentType: string,
- ): Promise<DirectUploadSetup> {
- const single = async (): Promise<DirectUploadSetup> => ({
- mode: 'single',
- url: await this.getSignedUrl(key, 3600, { contentType }),
- })
- if (size <= UPLOAD_CHUNK_SIZE) return single()
- const base = { Bucket: this.config.bucket, Key: key }
- const startedAt = Date.now()
- logUpload('s3.multipart.initialize.started', {
- key,
- size,
- bucket: this.config.bucket,
- })
- let uploadId: string | undefined
- try {
- uploadId = (
- await this.client.send(
- new CreateMultipartUploadCommand({
- ...base,
- ContentType: contentType,
- }),
- )
- ).UploadId
- } catch (error) {
- logUpload(
- 's3.multipart.initialize.failed',
- {
- key,
- size,
- bucket: this.config.bucket,
- durationMs: Date.now() - startedAt,
- },
- error,
- )
- const unsupported = error as {
- name?: string
- Code?: string
- $metadata?: { httpStatusCode?: number }
- }
- if (
- [405, 501].includes(unsupported.$metadata?.httpStatusCode ?? 0) ||
- [
- 'NotImplemented',
- 'NotSupported',
- 'UnsupportedOperation',
- 'AccessDenied',
- ].includes(unsupported.name || unsupported.Code || '')
- ) {
- // A provider can allow ordinary PUT uploads while denying multipart
- // initiation. Keep the file on the direct path in that case.
- logUpload('s3.multipart.fallback.single', {
- key,
- size,
- reason:
- unsupported.name ||
- unsupported.Code ||
- String(unsupported.$metadata?.httpStatusCode),
- })
- return single()
- }
- throw error
- }
- if (!uploadId) throw new Error('S3 did not return a multipart upload ID')
- logUpload('s3.multipart.initialize.succeeded', {
- key,
- uploadId,
- durationMs: Date.now() - startedAt,
- })
- const params = { ...base, UploadId: uploadId }
- const abort = async () => {
- logUpload('s3.multipart.abort.started', { key, uploadId })
- try {
- await this.client.send(new AbortMultipartUploadCommand(params))
- logUpload('s3.multipart.abort.succeeded', { key, uploadId })
- } catch (error) {
- logUpload('s3.multipart.abort.failed', { key, uploadId }, error)
- throw error
- }
- }
- const partSize = Math.max(
- UPLOAD_CHUNK_SIZE,
- Math.ceil(size / 10_000 / 1024 / 1024) * 1024 * 1024,
- )
- const count = Math.ceil(size / partSize)
- try {
- const partUrls = await Promise.all(
- Array.from({ length: count }, (_, index) =>
- getSignedUrl(
- this.client,
- new UploadPartCommand({ ...params, PartNumber: index + 1 }),
- { expiresIn: 3600 },
- ),
- ),
- )
- logUpload('s3.multipart.parts.signed', {
- key,
- uploadId,
- partSize,
- partCount: count,
- })
- return {
- mode: 'multipart',
- partSize,
- partUrls,
- abort,
- complete: async (parts) => {
- logUpload('s3.multipart.verify.started', {
- key,
- uploadId,
- partCount: count,
- size,
- })
- // Verify remote part sizes before publishing the object. Presigned
- // upload URLs alone do not enforce the declared total file size.
- const remote = new Map<number, { size?: number; etag?: string }>()
- let marker: string | undefined
- do {
- const result = await this.client.send(
- new ListPartsCommand({ ...params, PartNumberMarker: marker }),
- )
- for (const part of result.Parts || []) {
- if (part.PartNumber !== undefined)
- remote.set(part.PartNumber, {
- size: part.Size,
- etag: part.ETag,
- })
- }
- marker = result.IsTruncated
- ? result.NextPartNumberMarker
- : undefined
- } while (marker)
- if (
- remote.size !== count ||
- parts.some((part) => {
- const uploaded = remote.get(part.partNumber)
- return (
- uploaded?.etag !== part.etag ||
- uploaded?.size !==
- Math.min(partSize, size - (part.partNumber - 1) * partSize)
- )
- })
- )
- throw new Error('S3 multipart upload size or ETag mismatch')
- for (const [partNumber, part] of remote) {
- logUpload('s3.multipart.part.verified', {
- key,
- uploadId,
- partNumber,
- bytes: part.size,
- })
- }
- logUpload('s3.multipart.complete.started', {
- key,
- uploadId,
- partCount: count,
- })
- await this.client.send(
- new CompleteMultipartUploadCommand({
- ...params,
- MultipartUpload: {
- Parts: parts.map((part) => ({
- PartNumber: part.partNumber,
- ETag: part.etag,
- })),
- },
- }),
- )
- logUpload('s3.multipart.complete.succeeded', {
- key,
- uploadId,
- size,
- durationMs: Date.now() - startedAt,
- })
- },
- }
- } catch (error) {
- logUpload('s3.multipart.signing.failed', { key, uploadId }, error)
- await abort().catch(() => {})
- throw error
- }
- }
-
- async getFileMeta(key: string): Promise<StorageObject | null> {
- try {
- const cmd = new HeadObjectCommand({
- Bucket: this.config.bucket,
- Key: key,
- })
-
- const resp = await this.client.send(cmd)
-
- return {
- key,
- size: resp.ContentLength,
- lastModified: resp.LastModified,
- etag: resp.ETag,
- }
- } catch (error) {
- if ((error as any).$metadata?.httpStatusCode === 404) {
- return null
- }
- this.logger?.error(`Failed to get metadata for key: ${key}`, error)
- throw error
- }
- }
-
- async listAll(): Promise<StorageObject[]> {
- const cmd = new ListObjectsCommand({
- Bucket: this.config.bucket,
- Prefix: this.config.prefix,
- MaxKeys: this.config.maxKeys,
- })
-
- const resp = await this.client.send(cmd)
- this.logger?.log(resp.Contents?.map(convertToStorageObject))
- return resp.Contents?.map(convertToStorageObject) || []
- }
-
- async listImages(): Promise<StorageObject[]> {
- const cmd = new ListObjectsCommand({
- Bucket: this.config.bucket,
- Prefix: this.config.prefix,
- MaxKeys: this.config.maxKeys,
- })
-
- const resp = await this.client.send(cmd)
- // TODO: filter supported image format
- return resp.Contents?.map(convertToStorageObject) || []
- }
-}
+export * from '@chronoframe/storage/providers/s3'
diff --git a/server/services/video/livephoto.ts b/server/services/video/livephoto.ts
index fd28e042..4624c7c3 100644
--- a/server/services/video/livephoto.ts
+++ b/server/services/video/livephoto.ts
@@ -1,3 +1,4 @@
+import { isLivePhotoVideo } from '@chronoframe/media/livephoto'
import path from 'path'
import { eq } from 'drizzle-orm'
import { getStorageManager } from '~~/server/plugins/3.storage'
@@ -157,17 +158,4 @@ export const isVideoFile = (fileName: string): boolean => {
* 检查文件是否可能是 LivePhoto 的 MOV 文件
* LivePhoto 的 MOV 文件通常很小(几MB以内)
*/
-export const isLivePhotoVideo = (
- fileName: string,
- fileSize: number,
-): boolean => {
- const extName = path.extname(fileName).toLowerCase()
-
- // 检查是否为 MOV 格式
- if (extName !== '.mov') {
- return false
- }
-
- const maxLivePhotoSize = 12 * 1024 * 1024 // 12MB
- return fileSize <= maxLivePhotoSize
-}
+export { isLivePhotoVideo }
diff --git a/server/services/video/motion-photo.ts b/server/services/video/motion-photo.ts
index 6a35a055..99104ad4 100644
--- a/server/services/video/motion-photo.ts
+++ b/server/services/video/motion-photo.ts
@@ -1,307 +1 @@
-import type { ConsolaInstance } from 'consola'
-import type { NeededExif } from '~~/shared/types/photo'
-import type { StorageProvider } from '../storage'
-
-interface MotionPhotoProcessParams {
- photoId: string
- storageKey: string
- rawImageBuffer: Buffer
- exifData?: NeededExif | null
- storageProvider: StorageProvider
- logger?: ConsolaInstance
-}
-
-export interface MotionPhotoProcessResult {
- isMotionPhoto: boolean
- livePhotoVideoKey?: string
- livePhotoVideoUrl?: string
- offset?: number
- presentationTimestampUs?: number
-}
-
-const MAX_XMP_SCAN_BYTES = 512 * 1024 // 512KB should cover standard XMP blocks
-const MIN_VIDEO_SIZE_BYTES = 8 * 1024 // 8KB minimal sanity check
-const MP4_FTYP = Buffer.from('ftyp')
-
-const toBoolean = (value: unknown): boolean => {
- if (value === null || value === undefined) return false
- if (typeof value === 'boolean') return value
- if (typeof value === 'number') return value !== 0
- if (typeof value === 'bigint') return value !== BigInt(0)
- if (typeof value === 'string') {
- const normalized = value.trim().toLowerCase()
- return normalized === '1' || normalized === 'true' || normalized === 'yes'
- }
- return false
-}
-
-const toNumber = (value: unknown): number | null => {
- if (value === null || value === undefined) return null
- if (typeof value === 'number' && Number.isFinite(value)) return value
- if (typeof value === 'bigint') return Number(value)
- if (typeof value === 'string') {
- const parsed = Number.parseInt(value.trim(), 10)
- return Number.isFinite(parsed) ? parsed : null
- }
- return null
-}
-
-const extractXmpSegment = (buffer: Buffer): string | null => {
- const scanSize = Math.min(buffer.length, MAX_XMP_SCAN_BYTES)
- if (scanSize === 0) {
- return null
- }
-
- const header = buffer.toString('utf8', 0, scanSize)
- const startIndex = header.indexOf('<x:xmpmeta')
- if (startIndex === -1) {
- return null
- }
-
- const endIndex = header.indexOf('</x:xmpmeta>')
- if (endIndex === -1) {
- return null
- }
-
- return header.slice(startIndex, endIndex + '</x:xmpmeta>'.length)
-}
-
-const extractXmpBoolean = (xmp: string, tagName: string): boolean | null => {
- const regex = new RegExp(`<[^:>]*:${tagName}>([^<]+)</[^>]+>`, 'i')
- const match = xmp.match(regex)
- if (!match) return null
- return toBoolean(match[1])
-}
-
-const extractXmpNumber = (xmp: string, tagName: string): number | null => {
- const regex = new RegExp(`<[^:>]*:${tagName}>([^<]+)</[^>]+>`, 'i')
- const match = xmp.match(regex)
- if (!match) return null
- return toNumber(match[1])
-}
-
-const escapeRegExp = (value: string) =>
- value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-
-const buildAttrPattern = (attrName: string) => {
- const escaped = escapeRegExp(attrName)
- if (attrName.includes(':')) {
- return escaped
- }
- return `(?:[\\w-]+:)?${escaped}`
-}
-
-const extractXmpAttributeBoolean = (
- xmp: string,
- attrName: string,
-): boolean | null => {
- const regex = new RegExp(`${buildAttrPattern(attrName)}="([^"]+)"`, 'i')
- const match = xmp.match(regex)
- if (!match) return null
- return toBoolean(match[1])
-}
-
-const extractXmpAttributeNumber = (
- xmp: string,
- attrName: string,
-): number | null => {
- const regex = new RegExp(`${buildAttrPattern(attrName)}="([^"]+)"`, 'i')
- const match = xmp.match(regex)
- if (!match) return null
- return toNumber(match[1])
-}
-
-const validateMp4Buffer = (buffer: Buffer): boolean => {
- if (buffer.length < MIN_VIDEO_SIZE_BYTES) {
- return false
- }
-
- // MP4 should contain 'ftyp' brand within the first few bytes
- const searchWindow = buffer.subarray(0, 32)
- return searchWindow.indexOf(MP4_FTYP) !== -1
-}
-
-export const processMotionPhotoFromXmp = async ({
- photoId,
- storageKey,
- rawImageBuffer,
- exifData,
- storageProvider,
- logger,
-}: MotionPhotoProcessParams): Promise<MotionPhotoProcessResult | null> => {
- try {
- const rawLength = rawImageBuffer.length
-
- const exifIndicatesMotion =
- toBoolean(exifData?.MotionPhoto) || toBoolean(exifData?.MicroVideo)
- let detectedMotion = exifIndicatesMotion
-
- let presentationTimestampUs = toNumber(
- exifData?.MotionPhotoPresentationTimestampUs ??
- exifData?.MicroVideoPresentationTimestampUs,
- )
-
- const offsetCandidates = new Set<number>()
- const addOffsetCandidate = (value: number | null | undefined) => {
- if (value === null || value === undefined) return
- if (!Number.isFinite(value)) return
- const numeric = Number(value)
- if (numeric <= 0) return
- offsetCandidates.add(numeric)
- }
-
- addOffsetCandidate(toNumber(exifData?.MicroVideoOffset))
-
- const xmpSegment = extractXmpSegment(rawImageBuffer)
- if (xmpSegment) {
- if (!detectedMotion) {
- const motionFlags = [
- extractXmpBoolean(xmpSegment, 'MotionPhoto'),
- extractXmpBoolean(xmpSegment, 'GCamera:MotionPhoto'),
- extractXmpBoolean(xmpSegment, 'MicroVideo'),
- extractXmpBoolean(xmpSegment, 'GCamera:MicroVideo'),
- extractXmpAttributeBoolean(xmpSegment, 'MotionPhoto'),
- extractXmpAttributeBoolean(xmpSegment, 'GCamera:MotionPhoto'),
- extractXmpAttributeBoolean(xmpSegment, 'MicroVideo'),
- extractXmpAttributeBoolean(xmpSegment, 'GCamera:MicroVideo'),
- ].filter((flag) => flag !== null) as boolean[]
-
- if (motionFlags.some(Boolean)) {
- detectedMotion = true
- logger?.info(
- `[motion-photo] XMP detected MotionPhoto flags for ${storageKey}`,
- )
- }
- }
-
- ;[
- extractXmpNumber(xmpSegment, 'MicroVideoOffset'),
- extractXmpNumber(xmpSegment, 'GCamera:MicroVideoOffset'),
- extractXmpAttributeNumber(xmpSegment, 'MicroVideoOffset'),
- extractXmpAttributeNumber(xmpSegment, 'GCamera:MicroVideoOffset'),
- ].forEach((candidate) => addOffsetCandidate(candidate))
-
- if (presentationTimestampUs === null) {
- presentationTimestampUs =
- extractXmpNumber(xmpSegment, 'MotionPhotoPresentationTimestampUs') ??
- extractXmpNumber(xmpSegment, 'MicroVideoPresentationTimestampUs') ??
- extractXmpAttributeNumber(
- xmpSegment,
- 'MotionPhotoPresentationTimestampUs',
- ) ??
- extractXmpAttributeNumber(
- xmpSegment,
- 'MicroVideoPresentationTimestampUs',
- ) ??
- null
- }
- }
-
- if (!detectedMotion && offsetCandidates.size === 0) {
- return null
- }
-
- let resolvedOffset: number | null = null
- let videoBuffer: Buffer | null = null
-
- const candidateList = Array.from(offsetCandidates)
- for (const candidate of candidateList) {
- const possibleStarts = new Set<number>()
- possibleStarts.add(candidate)
- if (candidate < rawLength) {
- possibleStarts.add(rawLength - candidate)
- }
-
- for (const start of possibleStarts) {
- if (start <= 0 || start >= rawLength - MIN_VIDEO_SIZE_BYTES) {
- continue
- }
-
- const chunk = rawImageBuffer.subarray(start)
- if (validateMp4Buffer(chunk)) {
- resolvedOffset = start
- videoBuffer = chunk
- if (start !== candidate && logger?.debug) {
- logger.debug(
- `[motion-photo] Interpreted offset ${candidate} as start ${start} from file end for ${storageKey}`,
- )
- }
- break
- }
- }
-
- if (videoBuffer) {
- break
- }
- }
-
- if (!videoBuffer) {
- const searchWindowStart = Math.max(0, rawLength - 8 * 1024 * 1024)
- let cursor = rawImageBuffer.indexOf(MP4_FTYP, searchWindowStart)
- while (cursor !== -1) {
- const potentialStart = cursor - 4
- if (
- potentialStart > 0 &&
- potentialStart < rawLength - MIN_VIDEO_SIZE_BYTES
- ) {
- const chunk = rawImageBuffer.subarray(potentialStart)
- if (validateMp4Buffer(chunk)) {
- resolvedOffset = potentialStart
- videoBuffer = chunk
- logger?.info(
- `[motion-photo] Located MP4 via fallback scan at offset ${potentialStart} for ${storageKey}`,
- )
- break
- }
- }
- cursor = rawImageBuffer.indexOf(MP4_FTYP, cursor + 1)
- }
- }
-
- if (!videoBuffer || resolvedOffset === null) {
- logger?.warn(
- `[motion-photo] Unable to extract MP4 after trying offsets ${candidateList.join(', ') || 'none'} for ${storageKey}`,
- )
- return null
- }
-
- // todo: consider storing in a dedicated subfolder
- // const targetKey = `motion-videos/${photoId}.mp4`
- const targetKey = `${photoId}.mp4`
- let storedObject
- try {
- storedObject = await storageProvider.create(
- targetKey,
- videoBuffer,
- 'video/mp4',
- )
- } catch (error) {
- logger?.error(
- `[motion-photo] Failed to persist extracted video for ${storageKey}`,
- error,
- )
- return null
- }
-
- const livePhotoVideoKey = storedObject.key || targetKey
- const livePhotoVideoUrl = storageProvider.getPublicUrl(livePhotoVideoKey)
-
- logger?.success(
- `[motion-photo] Extracted Motion Photo video for ${storageKey} at offset ${resolvedOffset}, saved as ${livePhotoVideoKey}`,
- )
-
- return {
- isMotionPhoto: true,
- livePhotoVideoKey,
- livePhotoVideoUrl,
- offset: resolvedOffset,
- presentationTimestampUs: presentationTimestampUs ?? undefined,
- }
- } catch (error) {
- logger?.error(
- `[motion-photo] Unexpected error while processing ${storageKey}`,
- error,
- )
- return null
- }
-}
+export * from '@chronoframe/media/motion-photo'
diff --git a/server/types/settings.ts b/server/types/settings.ts
new file mode 100644
index 00000000..a5d3a7fb
--- /dev/null
+++ b/server/types/settings.ts
@@ -0,0 +1,5 @@
+import type * as schema from '../database/schema'
+export type StorageProviderRow =
+ typeof schema.settings_storage_providers.$inferSelect
+export type NewStorageProviderRow =
+ typeof schema.settings_storage_providers.$inferInsert
diff --git a/server/types/worker.d.ts b/server/types/worker.d.ts
new file mode 100644
index 00000000..c5517991
--- /dev/null
+++ b/server/types/worker.d.ts
@@ -0,0 +1,5 @@
+import type { WorkerPool } from '../services/pipeline-queue'
+declare global {
+ var __workerPool: WorkerPool | undefined
+}
+export {}
diff --git a/server/utils/dto.ts b/server/utils/dto.ts
new file mode 100644
index 00000000..19d436ca
--- /dev/null
+++ b/server/utils/dto.ts
@@ -0,0 +1,78 @@
+import type {
+ Photo,
+ Album,
+ UserSummary,
+} from '@chronoframe/contracts/resources'
+import type {
+ Photo as PhotoRow,
+ Album as AlbumRow,
+ User as UserRow,
+} from './db'
+
+export function toPhotoDto(photo: PhotoRow): Photo {
+ return {
+ id: photo.id,
+ title: photo.title,
+ description: photo.description,
+ width: photo.width,
+ height: photo.height,
+ aspectRatio: photo.aspectRatio,
+ dateTaken: photo.dateTaken,
+ storageKey: photo.storageKey,
+ thumbnailKey: photo.thumbnailKey,
+ fileSize: photo.fileSize,
+ lastModified: photo.lastModified,
+ originalUrl: photo.originalUrl,
+ thumbnailUrl: photo.thumbnailUrl,
+ thumbnailHash: photo.thumbnailHash,
+ tags: photo.tags,
+ exif: photo.exif,
+ latitude: photo.latitude,
+ longitude: photo.longitude,
+ country: photo.country,
+ city: photo.city,
+ locationName: photo.locationName,
+ geocoding: photo.geocoding,
+ isLivePhoto: photo.isLivePhoto,
+ livePhotoVideoUrl: photo.livePhotoVideoUrl,
+ livePhotoVideoKey: photo.livePhotoVideoKey,
+ }
+}
+
+export function toAlbumDto(album: AlbumRow): Album {
+ return {
+ id: album.id,
+ title: album.title,
+ description: album.description,
+ coverPhotoId: album.coverPhotoId,
+ isHidden: album.isHidden,
+ position: album.position,
+ createdAt: album.createdAt.toISOString(),
+ updatedAt: album.updatedAt.toISOString(),
+ hasPassword: Boolean(album.passwordHash),
+ }
+}
+
+export function toUserSummary(user: UserRow): UserSummary {
+ return {
+ id: user.id,
+ username: user.username,
+ email: user.email,
+ avatar: user.avatar,
+ createdAt: user.createdAt.toISOString(),
+ isAdmin: user.isAdmin,
+ }
+}
+
+export function toStorageProviderDto(
+ provider: import('../types/settings').StorageProviderRow,
+): import('@chronoframe/contracts/settings').SettingStorageProvider {
+ return {
+ id: provider.id,
+ name: provider.name,
+ provider: provider.provider,
+ config: provider.config,
+ createdAt: provider.createdAt.toISOString(),
+ updatedAt: provider.updatedAt.toISOString(),
+ }
+}
diff --git a/server/utils/retry.ts b/server/utils/retry.ts
index 1340a22f..bf42b2e0 100644
--- a/server/utils/retry.ts
+++ b/server/utils/retry.ts
@@ -1,249 +1 @@
-/**
- * 重试配置选项
- */
-export interface RetryOptions {
- /** 最大重试次数,默认 3 */
- maxAttempts?: number
- /** 基础延迟时间(毫秒),默认 1000ms */
- baseDelay?: number
- /** 最大延迟时间(毫秒),默认 30000ms */
- maxDelay?: number
- /** 协作式操作超时(毫秒),默认 30000ms;操作需响应 AbortSignal,否则等待其结束 */
- timeout?: number
- /** 重试条件判断函数,返回 true 表示应该重试 */
- retryCondition?: (error: Error) => boolean
- /** 延迟策略:'exponential' 指数退避,'linear' 线性增长,'fixed' 固定延迟 */
- delayStrategy?: 'exponential' | 'linear' | 'fixed'
-}
-
-/**
- * 通用重试工具函数
- *
- * @param operation 要执行的异步操作;应响应 AbortSignal 以支持取消。无法取消的操作会等待结束再重试,避免重叠执行。
- * @param options 重试配置选项
- * @param logger 可选的日志记录器
- * @returns 操作结果
- *
- * @example
- * ```typescript
- * const result = await withRetry(
- * () => fetchDataFromAPI(),
- * {
- * maxAttempts: 3,
- * timeout: 5000,
- * retryCondition: (error) => !error.message.includes('400')
- * },
- * logger.api
- * )
- * ```
- */
-export async function withRetry<T>(
- operation: (signal: AbortSignal) => Promise<T>,
- options: RetryOptions = {},
- logger?: Logger[keyof Logger],
-): Promise<T> {
- const {
- maxAttempts = 3,
- baseDelay = 1000,
- maxDelay = 30000,
- timeout = 30000,
- retryCondition = () => true,
- delayStrategy = 'exponential',
- } = options
-
- let lastError: Error
-
- for (let attempt = 1; attempt <= maxAttempts; attempt++) {
- const controller = new AbortController()
- let timer: ReturnType<typeof setTimeout> | undefined
- try {
- logger?.info(`Operation attempt ${attempt}/${maxAttempts}`)
-
- // 应用超时机制
- const timeoutError = new Error(`Operation timeout after ${timeout}ms`)
- timer = setTimeout(() => {
- controller.abort(timeoutError)
- logger?.warn(
- `Operation exceeded ${timeout}ms; cancellation requested. Waiting for it to settle before releasing the resource slot or retrying.`,
- )
- }, timeout)
- // Keep the resource slot until non-cancellable operations settle. Racing
- // them against a timer would allow retries to overlap the original work.
- const result = await operation(controller.signal)
- if (controller.signal.aborted) throw timeoutError
-
- if (attempt > 1) {
- logger?.success(`Operation succeeded on attempt ${attempt}`)
- }
- return result
- } catch (error) {
- if (timer) clearTimeout(timer)
- lastError = controller.signal.aborted
- ? controller.signal.reason
- : error instanceof Error
- ? error
- : new Error(String(error))
- logger?.warn(`Attempt ${attempt} failed:`, error)
-
- const shouldRetry = attempt < maxAttempts && retryCondition(lastError)
- if (!shouldRetry) {
- logger?.error(`Operation failed after ${attempt} attempt(s)`)
- throw lastError
- }
- const delay = calculateDelay(attempt, baseDelay, maxDelay, delayStrategy)
- logger?.info(`Retrying in ${delay}ms...`)
- await new Promise((resolve) => setTimeout(resolve, delay))
- } finally {
- if (timer) clearTimeout(timer)
- }
- }
-
- logger?.error(`All ${maxAttempts} attempts failed`)
- throw lastError!
-}
-
-/**
- * 计算延迟时间
- */
-function calculateDelay(
- attempt: number,
- baseDelay: number,
- maxDelay: number,
- strategy: 'exponential' | 'linear' | 'fixed',
-): number {
- let delay: number
-
- switch (strategy) {
- case 'exponential':
- // 指数退避:1s, 2s, 4s, 8s...
- delay = baseDelay * Math.pow(2, attempt - 1)
- break
- case 'linear':
- // 线性增长:1s, 2s, 3s, 4s...
- delay = baseDelay * attempt
- break
- case 'fixed':
- // 固定延迟:1s, 1s, 1s, 1s...
- delay = baseDelay
- break
- default:
- delay = baseDelay
- }
-
- return Math.min(delay, maxDelay)
-}
-
-/**
- * 常见错误的重试条件预设
- */
-export const RetryConditions = {
- /** 网络错误重试(排除 4xx 客户端错误) */
- networkErrors: (error: Error) => {
- const message = error.message.toLowerCase()
- // 不重试客户端错误 (4xx)
- if (
- message.includes('400') ||
- message.includes('401') ||
- message.includes('403') ||
- message.includes('404')
- ) {
- return false
- }
- // 重试网络相关错误
- return (
- message.includes('timeout') ||
- message.includes('network') ||
- message.includes('fetch') ||
- message.includes('econnreset') ||
- message.includes('enotfound') ||
- message.includes('502') ||
- message.includes('503') ||
- message.includes('504')
- )
- },
-
- /** 文件系统错误重试(排除权限和不存在错误) */
- fileSystemErrors: (error: Error) => {
- const message = error.message.toLowerCase()
- // 不重试权限和文件不存在错误
- if (
- message.includes('eacces') ||
- message.includes('enoent') ||
- message.includes('permission denied')
- ) {
- return false
- }
- // 重试临时性文件系统错误
- return (
- message.includes('ebusy') ||
- message.includes('emfile') ||
- message.includes('enfile') ||
- message.includes('eagain')
- )
- },
-
- /** 资源竞争错误重试 */
- resourceErrors: (error: Error) => {
- const message = error.message.toLowerCase()
- return (
- message.includes('busy') ||
- message.includes('locked') ||
- message.includes('resource') ||
- message.includes('memory') ||
- message.includes('cpu')
- )
- },
-
- /** 始终重试 */
- always: () => true,
-
- /** 从不重试 */
- never: () => false,
-}
-
-/**
- * 重试配置预设
- */
-export const RetryPresets = {
- /** 快速重试:适用于轻量级操作 */
- fast: {
- maxAttempts: 3,
- baseDelay: 500,
- timeout: 5000,
- delayStrategy: 'exponential' as const,
- },
-
- /** 标准重试:适用于一般操作 */
- standard: {
- maxAttempts: 3,
- baseDelay: 1000,
- timeout: 10000,
- delayStrategy: 'exponential' as const,
- },
-
- /** 网络重试:适用于网络请求 */
- network: {
- maxAttempts: 3,
- baseDelay: 1000,
- timeout: 30000,
- delayStrategy: 'exponential' as const,
- retryCondition: RetryConditions.networkErrors,
- },
-
- /** 文件操作重试:适用于文件系统操作 */
- fileSystem: {
- maxAttempts: 5,
- baseDelay: 500,
- timeout: 15000,
- delayStrategy: 'linear' as const,
- retryCondition: RetryConditions.fileSystemErrors,
- },
-
- /** 慢速重试:适用于重量级操作 */
- slow: {
- maxAttempts: 3,
- baseDelay: 2000,
- timeout: 60000,
- delayStrategy: 'exponential' as const,
- },
-}
+export * from '@chronoframe/media/retry'
diff --git a/shared/types/auth.d.ts b/shared/types/auth.d.ts
index a9e737ef..52985ebc 100644
--- a/shared/types/auth.d.ts
+++ b/shared/types/auth.d.ts
@@ -1,7 +1,5 @@
-import type { User as DBUser } from '../../server/utils/db'
-
+import type { UserSummary } from '@chronoframe/contracts/resources'
declare module '#auth-utils' {
- interface User extends DBUser {}
+ interface User extends UserSummary {}
}
-
export {}
diff --git a/shared/types/config.ts b/shared/types/config.ts
index 5f0031d5..1f934d4c 100644
--- a/shared/types/config.ts
+++ b/shared/types/config.ts
@@ -1,5 +1,6 @@
-import type { StorageConfig } from '../../server/services/storage'
+import type { StorageConfig } from '@chronoframe/contracts/storage'
+/** Server configuration containing credentials; not a public response. */
export interface ChronoConfig {
storage: StorageConfig
}
diff --git a/shared/types/global.d.ts b/shared/types/global.d.ts
index e1e839ba..9f0980ae 100644
--- a/shared/types/global.d.ts
+++ b/shared/types/global.d.ts
@@ -1,11 +1,5 @@
-import type { Photo as DatabasePhoto } from '../../server/utils/db'
-import type { WorkerPool } from '../../server/services/pipeline-queue'
-
+import type { Photo as PhotoDto } from '@chronoframe/contracts/resources'
declare global {
- var __workerPool: WorkerPool | undefined
- interface Photo extends DatabasePhoto {
- fileName?: string | null
- }
+ interface Photo extends PhotoDto {}
}
-
export {}
diff --git a/shared/types/location.ts b/shared/types/location.ts
index 1e0af031..03514820 100644
--- a/shared/types/location.ts
+++ b/shared/types/location.ts
@@ -1,25 +1,6 @@
-export const locationLevels = [
- 'country',
- 'region',
- 'subregion',
- 'city',
- 'district',
- 'locality',
- 'neighborhood',
-] as const
-
-export type LocationLevel = (typeof locationLevels)[number]
-
-export interface LocationComponent {
- name: string
- sourceField: string
-}
-
-export interface NormalizedLocation {
- version: 1
- provider: 'mapbox' | 'nominatim'
- language: string
- countryCode?: string
- components: Partial<Record<LocationLevel, LocationComponent>>
- formattedAddress?: string
-}
+export { locationLevels } from '@chronoframe/contracts/location'
+export type {
+ LocationLevel,
+ LocationComponent,
+ NormalizedLocation,
+} from '@chronoframe/contracts/location'
diff --git a/shared/types/photo.ts b/shared/types/photo.ts
index fad8827b..56fa3c8f 100644
--- a/shared/types/photo.ts
+++ b/shared/types/photo.ts
@@ -1,103 +1 @@
-import type { Tags } from 'exiftool-vendored'
-
-export interface NeededExif {
- Title?: string
- XPTitle?: string
- Subject?: string[]
- Keywords?: string[]
- XPKeywords?: string
-
- Description?: Tags['Description']
- ImageDescription?: Tags['ImageDescription']
- CaptionAbstract?: Tags['Caption-Abstract']
- XPComment?: Tags['XPComment']
- UserComment?: Tags['UserComment']
-
- zone?: string
- tz?: string
- tzSource?: string
-
- Orientation?: number
- Make?: string
- Model?: string
- Software?: string
- Artist?: string
- Copyright?: string
-
- ExposureTime?: string | number
- FNumber?: number
- ExposureProgram?: string
- ISO?: number
- ShutterSpeedValue?: string | number
- ApertureValue?: number
- BrightnessValue?: number
- ExposureCompensation?: number
- MaxApertureValue?: number
-
- OffsetTime?: string
- OffsetTimeOriginal?: string
- OffsetTimeDigitized?: string
-
- LightSource?: string
- Flash?: string
-
- FocalLength?: string
- FocalLengthIn35mmFormat?: string
-
- LensMake?: string
- LensModel?: string
-
- ColorSpace?: string
-
- ExposureMode?: string
- SceneCaptureType?: string
-
- Aperture?: number
- ScaleFactor35efl?: number
- ShutterSpeed?: string | number
- LightValue?: number
-
- DateTimeOriginal?: string
- DateTimeDigitized?: string
-
- ImageWidth?: number
- ImageHeight?: number
-
- MeteringMode: Tags['MeteringMode']
- WhiteBalance: Tags['WhiteBalance']
- WBShiftAB: Tags['WBShiftAB']
- WBShiftGM: Tags['WBShiftGM']
- WhiteBalanceBias: Tags['WhiteBalanceBias']
- WhiteBalanceFineTune: Tags['WhiteBalanceFineTune']
- FlashMeteringMode: Tags['FlashMeteringMode']
- SensingMethod: Tags['SensingMethod']
- FocalPlaneXResolution: Tags['FocalPlaneXResolution']
- FocalPlaneYResolution: Tags['FocalPlaneYResolution']
- GPSAltitude: Tags['GPSAltitude']
- GPSLatitude: Tags['GPSLatitude']
- GPSLongitude: Tags['GPSLongitude']
- GPSAltitudeRef: Tags['GPSAltitudeRef']
- GPSLatitudeRef: Tags['GPSLatitudeRef']
- GPSLongitudeRef: Tags['GPSLongitudeRef']
-
- // HDR Type
- MPImageType?: Tags['MPImageType']
-
- Rating?: number
-
- // Motion Photo (XMP) related fields
- MotionPhoto?: Tags['MotionPhoto']
- MotionPhotoVersion?: Tags['MotionPhotoVersion']
- MotionPhotoPresentationTimestampUs?: Tags['MotionPhotoPresentationTimestampUs']
- MicroVideo?: Tags['MicroVideo']
- MicroVideoVersion?: Tags['MicroVideoVersion']
- MicroVideoOffset?: Tags['MicroVideoOffset']
- MicroVideoPresentationTimestampUs?: Tags['MicroVideoPresentationTimestampUs']
-}
-
-export interface PhotoInfo {
- title: string
- dateTaken: string
- tags: string[]
- description: string
-}
+export * from '@chronoframe/contracts/photo'
diff --git a/shared/types/settings.ts b/shared/types/settings.ts
index d41830ed..5b014596 100644
--- a/shared/types/settings.ts
+++ b/shared/types/settings.ts
@@ -1,117 +1 @@
-import type * as schema from '../../server/database/schema'
-
-export type SettingType = typeof schema.settings.$inferSelect.type
-export type SettingValue =
- | string
- | number
- | boolean
- | Record<string, any>
- | null
-
-export type SettingConfig = Omit<
- typeof schema.settings.$inferInsert,
- 'value' | 'defaultValue' | 'id' | 'updatedAt' | 'updatedBy' | 'enum'
-> & {
- value?: SettingValue
- defaultValue: SettingValue
- enum?: ReadonlyArray<string>
- /**
- * Internal settings that are never rendered in the settings UI. They are
- * still stored and readable server-side, but excluded from the fields API.
- */
- hidden?: boolean
-}
-
-export type SettingStorageProvider =
- typeof schema.settings_storage_providers.$inferSelect
-export type NewSettingStorageProvider =
- typeof schema.settings_storage_providers.$inferInsert
-
-/**
- * UI 字段类型枚举
- * 定义在 shared 中以便前端使用
- */
-export type FieldUIType =
- | 'input' // 文本输入
- | 'password' // 密码输入
- | 'url' // URL 输入
- | 'textarea' // 文本域
- | 'select' // 下拉选择
- | 'radio' // 单选按钮
- | 'tabs' // 标签页选择
- | 'toggle' // 开关
- | 'number' // 数字输入
- | 'avatar' // 头像上传/外链
- | 'custom' // 自定义组件
-
-/**
- * 字段 UI 配置
- * 定义前端如何展示和交互一个设置字段
- */
-export interface FieldUIConfig {
- // 基础 UI 类型
- type: FieldUIType
-
- // 输入相关
- placeholder?: string
- help?: string
-
- // 条件展示 - 根据其他字段的值来决定是否显示这个字段
- visibleIf?: {
- fieldKey: string
- value: SettingValue
- }
-
- // 可选项(用于 select/radio/tabs)
- options?: ReadonlyArray<{
- label: string
- value: SettingValue
- icon?: string
- description?: string
- }>
-
- // 验证规则(前端 UX 提示)
- required?: boolean
- minLength?: number
- maxLength?: number
- min?: number // 最小值(用于 number 类型)
- max?: number // 最大值(用于 number 类型)
- pattern?: string // 正则表达式
-
- // 样式和尺寸
- size?: 'sm' | 'md' | 'lg'
- variant?: 'soft' | 'outline'
- icon?: string
-
- // 行数(仅用于 textarea 类型,可选)
- // SettingField.vue 默认值为 3
- rows?: number
-}
-
-/**
- * 完整的字段描述符
- * 包含后端配置和前端 UI 信息
- * 由 API 返回给前端,前端可直接渲染
- */
-export interface FieldDescriptor extends SettingConfig {
- ui: FieldUIConfig
-}
-
-/**
- * Settings 字段获取响应
- */
-export interface SettingsFieldsResponse {
- namespace: string
- fields: FieldDescriptor[]
-}
-
-/**
- * Settings 批量更新请求
- */
-export interface SettingsBatchUpdateRequest {
- updates: Array<{
- namespace: string
- key: string
- value: SettingValue
- }>
-}
+export * from '@chronoframe/contracts/settings'
diff --git a/shared/types/upload.ts b/shared/types/upload.ts
index 2739e7f5..9dd082d3 100644
--- a/shared/types/upload.ts
+++ b/shared/types/upload.ts
@@ -1,2 +1,2 @@
-// Compatibility entry point for the existing Self-hosted application.
-export * from '@chronoframe/contracts/upload'
+// Browser upload protocol; constants are exposed by shared/utils/upload.
+export type { UploadPart, UploadPlan } from '@chronoframe/contracts/upload'
diff --git a/shared/utils/location.ts b/shared/utils/location.ts
index e2fe3967..a9fa0544 100644
--- a/shared/utils/location.ts
+++ b/shared/utils/location.ts
@@ -26,15 +26,4 @@ export function resolveLocationLabel(
return { label: '' }
}
-export function hasValidCoordinates(lat: unknown, lon: unknown): boolean {
- return (
- typeof lat === 'number' &&
- Number.isFinite(lat) &&
- Math.abs(lat) <= 90 &&
- typeof lon === 'number' &&
- Number.isFinite(lon) &&
- Math.abs(lon) <= 180 &&
- // Exact (0, 0) is treated as a missing-GPS placeholder.
- !(lat === 0 && lon === 0)
- )
-}
+export { hasValidCoordinates } from '@chronoframe/contracts/location'
diff --git a/shared/utils/upload.ts b/shared/utils/upload.ts
index f4e535d1..1476fd35 100644
--- a/shared/utils/upload.ts
+++ b/shared/utils/upload.ts
@@ -1 +1 @@
-export const UPLOAD_CHUNK_SIZE = 8 * 1024 * 1024
+export { UPLOAD_CHUNK_SIZE } from '@chronoframe/contracts/upload'
diff --git a/tests/geocoding-package.test.ts b/tests/geocoding-package.test.ts
new file mode 100644
index 00000000..7e158552
--- /dev/null
+++ b/tests/geocoding-package.test.ts
@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { createGeocodingServices } from '@chronoframe/geocoding'
+import { withRetry, RetryPresets } from '@chronoframe/media/retry'
+
+const logger = { info() {}, warn() {}, error() {}, success() {} }
+
+test('geocoding injects transport, language, retry and rate limiting without application settings', async () => {
+ let language = 'fr'
+ const requests: URL[] = []
+ const slots: string[] = []
+ const services = createGeocodingServices({
+ getLanguage: async () => language,
+ request: async (input) => {
+ requests.push(new URL(String(input)))
+ return new Response(
+ JSON.stringify({
+ address: { city: 'Paris', country: 'France', country_code: 'fr' },
+ display_name: 'Paris, France',
+ }),
+ { status: 200 },
+ )
+ },
+ waitForGeocodingSlot: async (key) => {
+ slots.push(key)
+ },
+ withRetry,
+ retryOptions: { ...RetryPresets.network, maxAttempts: 1 },
+ logger,
+ })
+ const provider = new services.NominatimGeocodingProvider(
+ 'https://geo.example.com',
+ )
+ assert.equal((await provider.reverseGeocode(48.85, 2.35))?.city, 'Paris')
+ language = 'de'
+ assert.equal(
+ (await provider.reverseGeocode(48.85, 2.35))?.geocoding.language,
+ 'de',
+ )
+ assert.deepEqual(
+ requests.map((url) => url.searchParams.get('accept-language')),
+ ['fr,en', 'de,en'],
+ )
+ assert.deepEqual(slots, [
+ 'https://geo.example.com',
+ 'https://geo.example.com',
+ ])
+ assert.deepEqual(
+ services.parseGPSCoordinates({
+ GPSLatitude: 48,
+ GPSLongitude: 2,
+ GPSLongitudeRef: 'W',
+ }),
+ { latitude: 48, longitude: -2 },
+ )
+ assert.deepEqual(
+ services.parseGPSCoordinates({ GPSLatitude: 999, GPSLongitude: 2 }),
+ {},
+ )
+})
diff --git a/tests/media-package.test.ts b/tests/media-package.test.ts
new file mode 100644
index 00000000..0fbb4624
--- /dev/null
+++ b/tests/media-package.test.ts
@@ -0,0 +1,154 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { mkdtemp, rm, readdir, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import sharp from 'sharp'
+import { ExifTool } from 'exiftool-vendored'
+import { createImageProcessor } from '@chronoframe/media/processor'
+import { createExifService } from '@chronoframe/media/exif'
+import { generateThumbnailAndHash } from '@chronoframe/media/thumbnail'
+import { calculateHistogramFromBuffer } from '@chronoframe/media/histogram'
+import { processMotionPhotoFromXmp } from '@chronoframe/media/motion-photo'
+import { LocalStorageProvider } from '@chronoframe/storage'
+
+const logger = { info() {}, warn() {}, error() {}, success() {}, debug() {} }
+
+test('media runs outside Nuxt: orientation, thumbnail, hash and histogram', async () => {
+ const image = await sharp({
+ create: { width: 1200, height: 800, channels: 3, background: '#ff0000' },
+ })
+ .jpeg()
+ .withMetadata({ orientation: 6 })
+ .toBuffer()
+ const processor = createImageProcessor(logger)
+ const result = await processor.processImageMetadataAndSharp(
+ image,
+ 'portrait.jpg',
+ )
+ assert.ok(result)
+ assert.equal(result.metadata.width, 800)
+ assert.equal(result.metadata.height, 1200)
+ const { thumbnailBuffer, thumbnailHash } = await generateThumbnailAndHash(
+ image,
+ logger,
+ )
+ const thumbnail = await sharp(thumbnailBuffer).metadata()
+ assert.equal(thumbnail.format, 'webp')
+ assert.equal(thumbnail.width, 600)
+ assert.equal(thumbnail.height, 900)
+ assert.ok(thumbnailHash?.length)
+ const histogram = await calculateHistogramFromBuffer(image, logger)
+ assert.equal(histogram.r.length, 256)
+ assert.ok(Math.abs(histogram.r.reduce((a, b) => a + b, 0) - 1) < 1e-8)
+})
+
+test('ExifTool extraction receives an explicit work directory and cleans temporary files', async () => {
+ const directory = await mkdtemp(path.join(tmpdir(), 'chronoframe-exif-'))
+ const tool = new ExifTool({ maxProcs: 1 })
+ try {
+ const service = createExifService({
+ exiftool: tool,
+ tempDir: directory,
+ logger,
+ })
+ const image = await sharp({
+ create: { width: 16, height: 12, channels: 3, background: '#112233' },
+ })
+ .jpeg()
+ .withExif({ IFD0: { Make: 'ChronoFrame', Model: 'Test Camera' } })
+ .toBuffer()
+ const exif = await service.extractExifData(image, undefined, logger)
+ assert.ok(exif)
+ assert.equal(exif.Make, 'ChronoFrame')
+ assert.deepEqual(await readdir(directory), [])
+ assert.equal(
+ service.extractPhotoInfo('album/2025-04-03.jpeg', exif).dateTaken,
+ '2025-04-03T00:00:00.000Z',
+ )
+ } finally {
+ await tool.end()
+ await rm(directory, { recursive: true, force: true })
+ }
+})
+
+test('motion photo extracts an embedded MP4 to an injected storage provider', async () => {
+ const directory = await mkdtemp(path.join(tmpdir(), 'chronoframe-motion-'))
+ try {
+ const storage = new LocalStorageProvider({
+ provider: 'local',
+ basePath: directory,
+ })
+ const video = Buffer.alloc(9000)
+ video.writeUInt32BE(24, 0)
+ video.write('ftypisom', 4)
+ const xmp = Buffer.from(
+ `<x:xmpmeta><rdf:Description GCamera:MicroVideo="1" GCamera:MicroVideoOffset="${video.length}" /></x:xmpmeta>`,
+ )
+ const result = await processMotionPhotoFromXmp({
+ photoId: 'motion-1',
+ storageKey: 'motion.jpg',
+ rawImageBuffer: Buffer.concat([xmp, video]),
+ storageProvider: storage,
+ logger,
+ })
+ assert.equal(result.isMotionPhoto, true)
+ assert.ok(result.livePhotoVideoKey)
+ assert.deepEqual(await storage.get(result.livePhotoVideoKey!), video)
+ } finally {
+ await rm(directory, { recursive: true, force: true })
+ }
+})
+
+test(
+ 'HEIC conversion produces a readable JPEG outside Nuxt',
+ { skip: !process.env.CHRONOFRAME_HEIC_FIXTURE },
+ async () => {
+ const input = await readFile(process.env.CHRONOFRAME_HEIC_FIXTURE!)
+ const processor = createImageProcessor(logger)
+ const jpeg = await processor.preprocessImageBuffer(input, 'sample.heic')
+ const result = await sharp(jpeg).metadata()
+ assert.equal(result.format, 'jpeg')
+ assert.ok(result.width && result.width > 0)
+ assert.ok(result.height && result.height > 0)
+ },
+)
+
+test('media input limits and cancellation are explicit and leave defaults unchanged', async () => {
+ const buffer = Buffer.alloc(16)
+ await assert.rejects(
+ createImageProcessor(logger, { maxInputBytes: 8 }).preprocessImageBuffer(
+ buffer,
+ 'input.jpg',
+ ),
+ /byte limit/,
+ )
+ const controller = new AbortController()
+ controller.abort()
+ await assert.rejects(
+ createImageProcessor(logger, {
+ signal: controller.signal,
+ }).preprocessImageBuffer(buffer, 'input.jpg'),
+ { name: 'AbortError' },
+ )
+ assert.equal(
+ await createImageProcessor(logger).preprocessImageBuffer(
+ buffer,
+ 'input.jpg',
+ ),
+ buffer,
+ )
+ const image = await sharp({
+ create: { width: 8, height: 8, channels: 3, background: '#999999' },
+ })
+ .greyscale()
+ .png()
+ .toBuffer()
+ const histogram = await calculateHistogramFromBuffer(image)
+ for (const channel of Object.values(histogram)) {
+ assert.ok(channel.every(Number.isFinite))
+ assert.ok(
+ Math.abs(channel.reduce((sum, value) => sum + value, 0) - 1) < 1e-8,
+ )
+ }
+})
diff --git a/tests/resource-contracts.test.ts b/tests/resource-contracts.test.ts
new file mode 100644
index 00000000..cdbf6861
--- /dev/null
+++ b/tests/resource-contracts.test.ts
@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { toAlbumDto, toPhotoDto, toUserSummary } from '../server/utils/dto.ts'
+import type { Album, Photo, User } from '../server/utils/db.ts'
+
+test('user and album boundaries remove password material and serialize dates', () => {
+ const date = new Date('2026-01-02T03:04:05Z')
+ const user: User = {
+ id: 1,
+ username: 'owner',
+ email: '[email protected]',
+ avatar: null,
+ password: 'password-hash',
+ isAdmin: 1,
+ createdAt: date,
+ }
+ const summary = toUserSummary(user)
+ assert.equal(summary.createdAt, date.toISOString())
+ assert.equal('password' in summary, false)
+ const album: Album = {
+ id: 1,
+ title: 'Test',
+ description: null,
+ coverPhotoId: null,
+ isHidden: false,
+ passwordHash: 'album-hash',
+ position: 0,
+ createdAt: date,
+ updatedAt: date,
+ }
+ const dto = toAlbumDto(album)
+ assert.equal(dto.hasPassword, true)
+ assert.equal('passwordHash' in dto, false)
+ assert.equal(dto.createdAt, date.toISOString())
+ assert.deepEqual(JSON.parse(JSON.stringify(dto)), dto)
+})
+
+test('photo boundary excludes future internal columns without changing nullable fields', () => {
+ const nullable = [
+ 'title',
+ 'description',
+ 'width',
+ 'height',
+ 'aspectRatio',
+ 'dateTaken',
+ 'storageKey',
+ 'thumbnailKey',
+ 'fileSize',
+ 'lastModified',
+ 'originalUrl',
+ 'thumbnailUrl',
+ 'thumbnailHash',
+ 'tags',
+ 'exif',
+ 'latitude',
+ 'longitude',
+ 'country',
+ 'city',
+ 'locationName',
+ 'geocoding',
+ 'livePhotoVideoUrl',
+ 'livePhotoVideoKey',
+ ]
+ const photo = {
+ ...Object.fromEntries(nullable.map((key) => [key, null])),
+ id: 'photo-1',
+ isLivePhoto: 0,
+ internalSecret: 'not-an-api-field',
+ } as unknown as Photo
+ const dto = toPhotoDto(photo)
+ assert.equal(dto.id, 'photo-1')
+ assert.equal(dto.exif, null)
+ assert.equal('internalSecret' in dto, false)
+ assert.deepEqual(JSON.parse(JSON.stringify(dto)), dto)
+})
diff --git a/tests/storage-package.test.ts b/tests/storage-package.test.ts
new file mode 100644
index 00000000..925f71e5
--- /dev/null
+++ b/tests/storage-package.test.ts
@@ -0,0 +1,294 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { createServer } from 'node:http'
+import { once } from 'node:events'
+import {
+ StorageManager,
+ LocalStorageProvider,
+ S3StorageProvider,
+ OpenListStorageProvider,
+} from '@chronoframe/storage'
+
+test('Local provider reads, lists, streams and deletes through an isolated manager', async () => {
+ const directory = await mkdtemp(path.join(tmpdir(), 'chronoframe-storage-'))
+ try {
+ const manager = new StorageManager({
+ provider: 'local',
+ basePath: directory,
+ prefix: 'photos',
+ baseUrl: '/storage',
+ })
+ const provider = manager.getProvider<LocalStorageProvider>()
+ const body = Buffer.from('image-body')
+ const object = await provider.create('album/pic.jpg', body)
+ assert.equal(object.key, 'photos/album/pic.jpg')
+ assert.deepEqual(await provider.get(object.key), body)
+ assert.equal((await provider.getFileMeta(object.key))?.size, body.length)
+ assert.equal(
+ provider.getPublicUrl(object.key),
+ '/storage/photos/album/pic.jpg',
+ )
+ const source = path.join(directory, 'source.bin')
+ await writeFile(source, body)
+ await provider.createFromFile('copy.webp', source)
+ assert.deepEqual((await provider.listImages()).map((o) => o.key).sort(), [
+ 'photos/album/pic.jpg',
+ 'photos/copy.webp',
+ ])
+ await provider.delete(object.key)
+ assert.equal(await provider.get(object.key), null)
+ assert.equal(await provider.getFileMeta(object.key), null)
+ const events: string[] = []
+ manager.on('provider-changed', (event) => {
+ events.push(event.type)
+ })
+ await manager.registerProvider({
+ provider: 'local',
+ basePath: directory,
+ prefix: 'other',
+ })
+ assert.deepEqual(events, ['provider-changed'])
+ assert.equal(await manager.getProvider().get('copy.webp'), null)
+ assert.deepEqual(
+ await provider.get('copy.webp'),
+ body,
+ 'existing instance retains its configuration',
+ )
+ } finally {
+ await rm(directory, { recursive: true, force: true })
+ }
+})
+
+test('S3 exports sign browser direct uploads without Nuxt globals or a network call', async () => {
+ const provider = new S3StorageProvider({
+ provider: 's3',
+ bucket: 'photos',
+ region: 'auto',
+ endpoint: 'https://s3.example.com',
+ accessKeyId: 'fixture-key',
+ secretAccessKey: 'fixture-secret',
+ forcePathStyle: true,
+ })
+ const plan = await provider.prepareDirectUpload(
+ 'album/test.jpg',
+ 1024,
+ 'image/jpeg',
+ )
+ assert.equal(plan.mode, 'single')
+ if (plan.mode !== 'single') throw new Error('Expected single upload')
+ const url = new URL(plan.url)
+ assert.equal(url.pathname, '/photos/album/test.jpg')
+ assert.ok(url.searchParams.get('X-Amz-Signature'))
+ assert.equal(
+ provider.getPublicUrl('album/test.jpg'),
+ 'https://s3.example.com/photos/album/test.jpg',
+ )
+})
+
+test('OpenList preserves its HTTP upload, metadata, download and delete protocol', async () => {
+ let stored: Buffer | null = null
+ const received: string[] = []
+ const server = createServer(async (req, res) => {
+ const chunks: Buffer[] = []
+ for await (const chunk of req) chunks.push(Buffer.from(chunk))
+ const body = Buffer.concat(chunks)
+ const address = server.address() as { port: number }
+ if (req.url === '/raw') {
+ res.end(stored)
+ return
+ }
+ assert.equal(req.headers.authorization, 'fixture-token')
+ received.push(req.url || '')
+ res.setHeader('content-type', 'application/json')
+ if (req.url === '/api/fs/put') {
+ assert.equal(
+ decodeURIComponent(String(req.headers['file-path'])),
+ '/photos/test.jpg',
+ )
+ stored = body
+ res.end(JSON.stringify({ code: 200 }))
+ } else if (req.url === '/api/fs/get') {
+ assert.equal(JSON.parse(body.toString()).path, '/photos/test.jpg')
+ res.end(
+ JSON.stringify(
+ stored
+ ? {
+ code: 200,
+ data: {
+ size: stored.length,
+ modified: '2026-01-02T00:00:00Z',
+ raw_url: `http://127.0.0.1:${address.port}/raw`,
+ },
+ }
+ : { code: 404 },
+ ),
+ )
+ } else if (req.url === '/api/fs/remove') {
+ assert.deepEqual(JSON.parse(body.toString()), {
+ dir: '/photos',
+ names: ['test.jpg'],
+ })
+ stored = null
+ res.end(JSON.stringify({ code: 200 }))
+ } else {
+ res.statusCode = 404
+ res.end('{}')
+ }
+ })
+ server.listen(0, '127.0.0.1')
+ await once(server, 'listening')
+ try {
+ const address = server.address() as { port: number }
+ const provider = new OpenListStorageProvider({
+ provider: 'openlist',
+ baseUrl: `http://127.0.0.1:${address.port}`,
+ rootPath: '/photos',
+ token: 'fixture-token',
+ })
+ const body = Buffer.from('fixture-image')
+ const object = await provider.create('test.jpg', body, 'image/jpeg')
+ assert.equal(object.key, 'photos/test.jpg')
+ assert.equal(object.size, body.length)
+ assert.deepEqual(await provider.get(object.key), body)
+ await provider.delete(object.key)
+ assert.equal(await provider.getFileMeta(object.key), null)
+ assert.ok(received.includes('/api/fs/remove'))
+ } finally {
+ server.closeAllConnections()
+ await new Promise<void>((resolve) => server.close(() => resolve()))
+ }
+})
+
+test(
+ 'S3 SDK operations and multipart size/ETag validation survive package extraction',
+ { timeout: 20000 },
+ async () => {
+ const objects = new Map<string, Buffer>()
+ const parts = new Map<number, Buffer>()
+ const etag = '"fixture-etag"'
+ const server = createServer(async (req, res) => {
+ try {
+ const url = new URL(req.url || '/', 'http://localhost')
+ const chunks: Buffer[] = []
+ for await (const chunk of req) chunks.push(Buffer.from(chunk))
+ const body = Buffer.concat(chunks)
+ const key = url.pathname.replace('/photos/', '')
+ res.setHeader('content-type', 'application/xml')
+ if (req.method === 'POST' && url.searchParams.has('uploads')) {
+ parts.clear()
+ res.end(
+ '<InitiateMultipartUploadResult><Bucket>photos</Bucket><Key>large.jpg</Key><UploadId>fixture-upload</UploadId></InitiateMultipartUploadResult>',
+ )
+ } else if (req.method === 'PUT' && url.searchParams.has('partNumber')) {
+ parts.set(Number(url.searchParams.get('partNumber')), body)
+ res.setHeader('etag', etag)
+ res.end()
+ } else if (req.method === 'GET' && url.searchParams.has('uploadId')) {
+ res.end(
+ `<ListPartsResult><IsTruncated>false</IsTruncated>${[...parts].map(([number, value]) => `<Part><PartNumber>${number}</PartNumber><ETag>&quot;fixture-etag&quot;</ETag><Size>${value.length}</Size></Part>`).join('')}</ListPartsResult>`,
+ )
+ } else if (req.method === 'POST' && url.searchParams.has('uploadId')) {
+ objects.set(
+ key,
+ Buffer.concat(
+ [...parts.entries()]
+ .sort(([a], [b]) => a - b)
+ .map(([, value]) => value),
+ ),
+ )
+ res.end(
+ '<CompleteMultipartUploadResult><Bucket>photos</Bucket><Key>large.jpg</Key><ETag>&quot;fixture-etag&quot;</ETag></CompleteMultipartUploadResult>',
+ )
+ } else if (req.method === 'GET' && url.pathname === '/photos/') {
+ res.end(
+ `<ListBucketResult><IsTruncated>false</IsTruncated>${[...objects].map(([name, value]) => `<Contents><Key>${name}</Key><Size>${value.length}</Size><ETag>&quot;fixture-etag&quot;</ETag></Contents>`).join('')}</ListBucketResult>`,
+ )
+ } else if (req.method === 'PUT') {
+ objects.set(key, body)
+ res.setHeader('etag', etag)
+ res.end()
+ } else if (req.method === 'DELETE') {
+ objects.delete(key)
+ res.statusCode = 204
+ res.end()
+ } else if (objects.has(key)) {
+ const value = objects.get(key)!
+ res.setHeader('content-length', value.length)
+ res.setHeader('etag', etag)
+ res.end(req.method === 'HEAD' ? undefined : value)
+ } else {
+ res.statusCode = 404
+ res.end('<Error><Code>NoSuchKey</Code></Error>')
+ }
+ } catch (error) {
+ res.statusCode = 500
+ res.end(String(error))
+ }
+ })
+ server.listen(0, '127.0.0.1')
+ await once(server, 'listening')
+ try {
+ const { port } = server.address() as { port: number }
+ const provider = new S3StorageProvider({
+ provider: 's3',
+ bucket: 'photos',
+ region: 'us-east-1',
+ endpoint: `http://127.0.0.1:${port}`,
+ accessKeyId: 'fixture-key',
+ secretAccessKey: 'fixture-secret',
+ forcePathStyle: true,
+ })
+ const image = Buffer.from('fixture-image')
+ await provider.create('small.jpg', image, 'image/jpeg')
+ assert.deepEqual(await provider.get('small.jpg'), image)
+ assert.equal(
+ (await provider.getFileMeta('small.jpg'))?.size,
+ image.length,
+ )
+ assert.ok(
+ (await provider.listAll()).some((object) => object.key === 'small.jpg'),
+ )
+ const size = 8 * 1024 * 1024 + 5
+ const plan = await provider.prepareDirectUpload(
+ 'large.jpg',
+ size,
+ 'image/jpeg',
+ )
+ assert.equal(plan.mode, 'multipart')
+ if (plan.mode !== 'multipart')
+ throw new Error('Expected multipart upload')
+ const uploadedParts = []
+ for (const [index, url] of plan.partUrls.entries()) {
+ const response = await fetch(url, {
+ method: 'PUT',
+ body: Buffer.alloc(
+ Math.min(plan.partSize, size - index * plan.partSize),
+ index + 1,
+ ),
+ })
+ assert.equal(response.status, 200)
+ uploadedParts.push({
+ partNumber: index + 1,
+ etag: response.headers.get('etag')!,
+ })
+ }
+ await assert.rejects(
+ plan.complete(
+ uploadedParts.map((part) => ({ ...part, etag: 'wrong' })),
+ ),
+ /ETag mismatch/,
+ )
+ assert.equal(await provider.getFileMeta('large.jpg'), null)
+ await plan.complete(uploadedParts)
+ assert.equal((await provider.getFileMeta('large.jpg'))?.size, size)
+ await provider.delete('small.jpg')
+ assert.equal(await provider.get('small.jpg'), null)
+ } finally {
+ server.closeAllConnections()
+ await new Promise<void>((resolve) => server.close(() => resolve()))
+ }
+ },
+)