Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
refactor: complete P1 package decoupling for self-hosted
HoshinoSuzumiBot9c3fda1af3fa
diff --git a/.dockerignore b/.dockerignoreindex 86f3a0c5..f1326253 100644--- a/.dockerignore+++ b/.dockerignore@@ -23,6 +23,9 @@ pnpm-debug.log*.env.test.env.production+# 构建产物+.output+# 缓存目录.cache.tempdiff --git a/Dockerfile b/Dockerfileindex bc8cc8e3..d63de48f 100644--- a/Dockerfile+++ b/Dockerfile@@ -8,13 +8,15 @@ WORKDIR /usr/src/appCOPY 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-lockfileFROM base AS buildWORKDIR /usr/src/appCOPY --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 ./packagesCOPY . .RUN pnpm exec nuxt prepareRUN NODE_OPTIONS="--max-old-space-size=4096" pnpm run build:depsdiff --git a/app/components/album/Listing.vue b/app/components/album/Listing.vueindex 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.vueindex 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?: booleanphotoCount?: numberphotoIds?: string[]coverPhoto?: Photo | nulldiff --git a/app/pages/dashboard/photos.vue b/app/pages/dashboard/photos.vueindex 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.tsindex 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 = nulltry {- 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.datathis.isInitialized = true@@ -113,10 +115,9 @@ export const useSettingsStore = defineStore('settings', {this.error = nulltry {- 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.datathis.isInitialized = truediff --git a/app/stores/viewer.ts b/app/stores/viewer.tsindex 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.jsonindex 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.mdindex 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 withDo not add database models, application aliases, Nuxt auto-imports, Node globals,or process-wide services here. Storage configuration contains credentials and isnot 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 2a1a061b..d8147aba 100644--- a/packages/contracts/src/upload.ts+++ b/packages/contracts/src/upload.ts@@ -27,3 +27,5 @@ export type UploadPlan =partSize: numberpartUrls: string[]}++export const UPLOAD_CHUNK_SIZE = 8 * 1024 * 1024diff --git a/packages/contracts/tsconfig.json b/packages/contracts/tsconfig.jsonindex 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.yamlindex 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.3version: 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:+ [email protected](@types/[email protected]):+ 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+[email protected](@types/[email protected]):dependencies:'@img/colour': 1.1.0diff --git a/scripts/check-package-boundaries.mjs b/scripts/check-package-boundaries.mjsnew file mode 100644index 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.tsindex 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() || nullconst {storageKey: _storageKey,@@ -76,12 +78,10 @@ export default eventHandler(async (event) => {: null,}})- : rows+ : photoDtosreturn {- ...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.tsindex 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.tsindex 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.tsindex 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 albumdiff --git a/server/api/auth/github.get.ts b/server/api/auth/github.get.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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].tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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?.accessTokenconst 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.$inferInsertdiff --git a/server/types/worker.d.ts b/server/types/worker.d.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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>"fixture-etag"</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>"fixture-etag"</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>"fixture-etag"</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()))+ }+ },+)