@ossy/platform 1.39.2 → 3.0.1

package/src/storage/local-storage.client.js

@@ -1,65 +1,2 @@
-import path from 'path'
-import os from 'os'
-import { mkdir, writeFile, readFile, stat } from 'fs/promises'
-import { existsSync } from 'fs'
-
-const LOCAL_STORAGE_DIR = path.join(os.tmpdir(), 'ossy-local-media')
-
-function normalizeKey(keyOrShape) {
-  const Key = typeof keyOrShape === 'string' ? keyOrShape : keyOrShape?.Key
-  if (!Key || typeof Key !== 'string') {
-    throw new Error('[LocalStorageClient] missing Key')
-  }
-  return Key
-}
-
-function keyToLocalPath(key) {
-  const resolved = path.resolve(LOCAL_STORAGE_DIR, key)
-  if (!resolved.startsWith(LOCAL_STORAGE_DIR)) {
-    throw new Error('[LocalStorageClient] invalid key: path traversal detected')
-  }
-  return resolved
-}
-
-function buildUrl(key) {
-  const base = (process.env.LOCAL_API_URL || 'http://localhost:3001').replace(/\/$/, '')
-  return `${base}/local-storage?key=${encodeURIComponent(key)}`
-}
-
-export class LocalStorageClient {
-
-  static createUploadUrl({ Key }) {
-    return Promise.resolve(buildUrl(Key))
-  }
-
-  static createPresignedDownloadUrl(keyOrShape) {
-    const Key = normalizeKey(keyOrShape)
-    return Promise.resolve(buildUrl(Key))
-  }
-
-  static createDownloadUrl(keyOrShape) {
-    const Key = normalizeKey(keyOrShape)
-    return buildUrl(Key)
-  }
-
-  static async save(key, body) {
-    const localPath = keyToLocalPath(key)
-    await mkdir(path.dirname(localPath), { recursive: true })
-    await writeFile(localPath, body)
-  }
-
-  static async load(key) {
-    const localPath = keyToLocalPath(key)
-    if (!existsSync(localPath)) return { buffer: null, exists: false }
-    const buffer = await readFile(localPath)
-    return { buffer, exists: true }
-  }
-
-  static async headObject({ Key }) {
-    const localPath = keyToLocalPath(Key)
-    const s = await stat(localPath).catch(() => null)
-    if (!s) throw Object.assign(new Error('Not Found'), { $metadata: { httpStatusCode: 404 } })
-    return { ContentLength: s.size }
-  }
-
-}
+/** @deprecated Import from filesystem-storage.client.js */
+export { LocalStorageClient, createFilesystemStorageClient, resolveFilesystemStorageRoot } from './filesystem-storage.client.js'

package/src/storage/resource-read-url.js

@@ -0,0 +1,36 @@
+import { assertStorageKey } from './storage-keys.js'
+
+function normalizeLogicalKey (keyOrShape) {
+  const Key = typeof keyOrShape === 'string' ? keyOrShape : keyOrShape?.Key
+  assertStorageKey(Key)
+  return Key
+}
+
+/**
+ * Predictable app-relative read path for a storage key.
+ * Original: `/r/{resourceId}` — derivative: `/r/{resourceId}/{variant}`.
+ *
+ * @param {string | { Key?: string }} keyOrShape
+ * @returns {string}
+ */
+export function storageKeyToReadPath (keyOrShape) {
+  const key = normalizeLogicalKey(keyOrShape)
+  const colon = key.indexOf(':')
+  if (colon === -1) return `/r/${key}`
+  const resourceId = key.slice(0, colon)
+  const variant = key.slice(colon + 1)
+  return `/r/${resourceId}/${variant}`
+}
+
+/**
+ * Absolute resource read URL (same shape for filesystem and S3 backends).
+ *
+ * @param {string | { Key?: string }} keyOrShape
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function createResourceReadUrl (keyOrShape, env = process.env) {
+  const path = storageKeyToReadPath(keyOrShape)
+  const base = (env.WEB_CLIENT_DOMAIN || env.LOCAL_API_URL || '').replace(/\/$/, '')
+  return base ? `${base}${path}` : path
+}

package/src/storage/resource-read-url.spec.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from '@jest/globals'
+import { createResourceReadUrl, storageKeyToReadPath } from './resource-read-url.js'
+
+describe('resource-read-url', () => {
+  it('maps original key to /r/{resourceId}', () => {
+    expect(storageKeyToReadPath('abc123XYZ')).toBe('/r/abc123XYZ')
+  })
+
+  it('maps derivative key to /r/{resourceId}/{variant}', () => {
+    expect(storageKeyToReadPath('abc123:galleryLarge')).toBe('/r/abc123/galleryLarge')
+  })
+
+  it('builds absolute URL from WEB_CLIENT_DOMAIN', () => {
+    expect(createResourceReadUrl('abc123', { WEB_CLIENT_DOMAIN: 'https://app.example.com' }))
+      .toBe('https://app.example.com/r/abc123')
+  })
+
+  it('falls back to LOCAL_API_URL', () => {
+    expect(createResourceReadUrl('abc123', { LOCAL_API_URL: 'http://localhost:3006' }))
+      .toBe('http://localhost:3006/r/abc123')
+  })
+})

package/src/storage/s3-storage.client.js

@@ -0,0 +1,102 @@
+import { S3, PutObjectCommand, GetObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3'
+import { S3RequestPresigner } from '@aws-sdk/s3-request-presigner'
+import { createRequest } from '@aws-sdk/util-create-request'
+import { formatUrl } from '@aws-sdk/util-format-url'
+import { createLogger } from '@ossy/observability'
+import { assertStorageKey } from './storage-keys.js'
+import { createResourceReadUrl } from './resource-read-url.js'
+
+const log = createLogger('storage')
+
+const REGION = 'eu-north-1'
+
+/** S3/CloudFront origin uses `/media` — flat keys become `media/{resourceId}`. */
+const S3_KEY_PREFIX = 'media/'
+
+function normalizeLogicalKey (keyOrShape) {
+  const Key = typeof keyOrShape === 'string' ? keyOrShape : keyOrShape?.Key
+  assertStorageKey(Key)
+  return Key
+}
+
+function toS3Key (logicalKey) {
+  return `${S3_KEY_PREFIX}${logicalKey}`
+}
+
+export function createS3StorageClient ({
+  bucket,
+  cdnDomainName,
+  accessKeyId,
+  secretAccessKey,
+  region = REGION,
+} = {}) {
+  if (!bucket) {
+    throw new Error('[S3Storage] bucket is required')
+  }
+
+  function createAwsClient () {
+    return new S3({
+      region,
+      credentials: {
+        accessKeyId,
+        secretAccessKey,
+      },
+    })
+  }
+
+  return {
+    backend: 's3',
+    bucket,
+
+    createDownloadUrl (keyOrShape) {
+      return createResourceReadUrl(normalizeLogicalKey(keyOrShape))
+    },
+
+    createPresignedDownloadUrl (keyOrShape) {
+      return Promise.resolve(createResourceReadUrl(normalizeLogicalKey(keyOrShape)))
+    },
+
+    createUploadUrl ({ ContentType, ContentLength, Key, expiresIn = 60 * 60 * 24 }) {
+      log.info('[S3Storage][createUploadUrl] Creating upload URL')
+
+      const clientParams = {
+        Bucket: bucket,
+        Key: toS3Key(normalizeLogicalKey({ Key })),
+        ContentType,
+        ContentLength,
+      }
+
+      const s3Client = createAwsClient()
+      const signedRequest = new S3RequestPresigner(s3Client.config)
+
+      return createRequest(s3Client, new PutObjectCommand(clientParams))
+        .then(request => signedRequest.presign(request, { expiresIn }))
+        .then(formatUrl)
+        .catch(error => {
+          log.error('S3Storage.createUploadUrl error', undefined, error)
+          return Promise.reject(error)
+        })
+    },
+
+    headObject ({ Key }) {
+      const s3Client = createAwsClient()
+      return s3Client.send(new HeadObjectCommand({ Bucket: bucket, Key: toS3Key(normalizeLogicalKey({ Key })) }))
+    },
+
+    async load (keyOrShape) {
+      const Key = toS3Key(normalizeLogicalKey(keyOrShape))
+      const s3Client = createAwsClient()
+      try {
+        const response = await s3Client.send(new GetObjectCommand({ Bucket: bucket, Key }))
+        const bytes = await response.Body?.transformToByteArray?.()
+        if (!bytes) return { buffer: null, exists: false }
+        return { buffer: Buffer.from(bytes), exists: true }
+      } catch (err) {
+        if (err?.$metadata?.httpStatusCode === 404 || err?.name === 'NoSuchKey') {
+          return { buffer: null, exists: false }
+        }
+        throw err
+      }
+    },
+  }
+}

package/src/storage/s3.client.js

@@ -2,8 +2,9 @@ import { S3, PutObjectCommand, GetObjectCommand, HeadObjectCommand } from '@aws-
 import { S3RequestPresigner } from '@aws-sdk/s3-request-presigner'
 import { createRequest } from '@aws-sdk/util-create-request'
 import { formatUrl } from '@aws-sdk/util-format-url'
-import { ConfigService } from '../config.service.js'
 import { createLogger } from '@ossy/observability'
+import { createResourceReadUrl } from './resource-read-url.js'
+import { ConfigService } from '../config.service.js'
 
 const log = createLogger('storage')
 
@@ -30,35 +31,18 @@ function normalizeKey(keyOrShape) {
 export class S3Client {
 
   /**
-   * Public CDN URL (CloudFront) for objects under `media/` — use only when `access === 'public'`.
+   * App read URL — same shape as local filesystem (`/r/{resourceId}`).
    */
   static createDownloadUrl(keyOrShape) {
     const Key = normalizeKey(keyOrShape)
-    const pathAfterMedia = Key.includes('media/') ? Key.split('media/')[1] : Key
-    const base = ConfigService.MediaCdnDomainName || ''
-    return `${base.replace(/\/$/, '')}/${pathAfterMedia}`
+    return createResourceReadUrl(Key)
   }
 
   /**
-   * Short-lived presigned GET for private bucket reads (restricted resources, workspace members).
+   * Same as createDownloadUrl — auth is enforced by `/r/` route handlers.
    */
-  static createPresignedDownloadUrl(keyOrShape, { expiresIn = 15 * 60 } = {}) {
-    const Key = normalizeKey(keyOrShape)
-    const Bucket = ConfigService.MediaRepository
-    if (!Bucket) {
-      return Promise.reject(new Error('[S3Client] MEDIA_REPOSITORY is not configured'))
-    }
-
-    const s3Client = createS3Client()
-    const signedRequest = new S3RequestPresigner(s3Client.config)
-
-    return createRequest(s3Client, new GetObjectCommand({ Bucket, Key }))
-      .then(request => signedRequest.presign(request, { expiresIn }))
-      .then(formatUrl)
-      .catch(error => {
-        log.error('S3Client.createPresignedDownloadUrl error', undefined, error)
-        return Promise.reject(error)
-      })
+  static createPresignedDownloadUrl(keyOrShape) {
+    return Promise.resolve(S3Client.createDownloadUrl(keyOrShape))
   }
 
   static createUploadUrl({ ContentType, ContentLength, Key, Bucket, expiresIn = 60 * 60 * 24 }) {
@@ -97,4 +81,24 @@ export class S3Client {
     return s3Client.send(new HeadObjectCommand({ Bucket: bucket, Key }))
   }
 
+  static async load(keyOrShape) {
+    const Key = normalizeKey(keyOrShape)
+    const Bucket = ConfigService.MediaRepository
+    if (!Bucket) {
+      return { buffer: null, exists: false }
+    }
+    const s3Client = createS3Client()
+    try {
+      const response = await s3Client.send(new GetObjectCommand({ Bucket, Key }))
+      const bytes = await response.Body?.transformToByteArray?.()
+      if (!bytes) return { buffer: null, exists: false }
+      return { buffer: Buffer.from(bytes), exists: true }
+    } catch (err) {
+      if (err?.$metadata?.httpStatusCode === 404 || err?.name === 'NoSuchKey') {
+        return { buffer: null, exists: false }
+      }
+      throw err
+    }
+  }
+
 }

package/src/storage/storage-keys.js

@@ -0,0 +1,37 @@
+/**
+ * Flat blob keys — folder hierarchy lives in Mongo resource metadata (`location`), not in storage.
+ *
+ * Original binary: `{resourceId}`
+ * Derivatives (thumbnails, etc.): `{resourceId}:{variant}`
+ */
+
+const KEY_PATTERN = /^[A-Za-z0-9_-]+(:[A-Za-z0-9_-]+)?$/
+
+export function originalObjectKey (resourceId) {
+  assertResourceId(resourceId)
+  return resourceId
+}
+
+export function derivativeObjectKey (resourceId, variant) {
+  assertResourceId(resourceId)
+  if (!variant || typeof variant !== 'string') {
+    throw new Error('[storage-keys] variant is required')
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(variant)) {
+    throw new Error('[storage-keys] invalid variant')
+  }
+  return `${resourceId}:${variant}`
+}
+
+export function assertStorageKey (key) {
+  if (!key || typeof key !== 'string' || !KEY_PATTERN.test(key)) {
+    throw new Error(`[storage-keys] invalid storage key: ${key}`)
+  }
+  return key
+}
+
+function assertResourceId (resourceId) {
+  if (!resourceId || typeof resourceId !== 'string' || !/^[A-Za-z0-9_-]+$/.test(resourceId)) {
+    throw new Error(`[storage-keys] invalid resourceId: ${resourceId}`)
+  }
+}

package/src/storage/storage-keys.spec.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from '@jest/globals'
+import { originalObjectKey, derivativeObjectKey, assertStorageKey } from './storage-keys.js'
+
+describe('storage-keys', () => {
+  it('originalObjectKey returns flat resourceId', () => {
+    expect(originalObjectKey('abc123XYZ')).toBe('abc123XYZ')
+  })
+
+  it('derivativeObjectKey uses resourceId:variant', () => {
+    expect(derivativeObjectKey('abc123', 'galleryMedium')).toBe('abc123:galleryMedium')
+  })
+
+  it('rejects path-like keys', () => {
+    expect(() => assertStorageKey('media/ws/file')).toThrow()
+  })
+})

package/src/storage/storage.client.js

@@ -1,12 +1,56 @@
-import { S3Client } from './s3.client.js'
-import { LocalStorageClient } from './local-storage.client.js'
+import { IntegrationService } from '../integration.service.js'
 import { ConfigService } from '../config.service.js'
+import { createFilesystemStorageClient } from './filesystem-storage.client.js'
+import { createS3StorageClient } from './s3-storage.client.js'
+
+/** @type {import('./filesystem-storage.client.js').createFilesystemStorageClient extends (...args: any) => infer R ? R : never | null} */
+let fallbackClient = null
+
+function getFallbackClient () {
+  if (!fallbackClient) {
+    if (ConfigService.MediaRepository && ConfigService.awsAccessKeyId && ConfigService.awsSecretAccessKey) {
+      fallbackClient = createS3StorageClient({
+        bucket: ConfigService.MediaRepository,
+        cdnDomainName: ConfigService.MediaCdnDomainName,
+        accessKeyId: ConfigService.awsAccessKeyId,
+        secretAccessKey: ConfigService.awsSecretAccessKey,
+      })
+    } else {
+      fallbackClient = createFilesystemStorageClient()
+    }
+  }
+  return fallbackClient
+}
+
+function getStorageClient () {
+  return IntegrationService.get('storage') ?? getFallbackClient()
+}
+
+function bindMethod (name) {
+  return (...args) => {
+    const client = getStorageClient()
+    const fn = client[name]
+    if (typeof fn !== 'function') {
+      throw new Error(`[StorageClient] storage backend missing method "${name}"`)
+    }
+    return fn.apply(client, args)
+  }
+}
 
 /**
- * Active storage backend.
- *
- * - When `MEDIA_REPOSITORY` is set (production): delegates to S3.
- * - When `MEDIA_REPOSITORY` is unset (local dev): delegates to LocalStorageClient,
- *   which stores files in /tmp/ossy-local-media/ and serves them via GET /local-storage.
+ * Active primary storage backend (filesystem or S3 via `storage` integration).
  */
-export const StorageClient = ConfigService.MediaRepository ? S3Client : LocalStorageClient
+export const StorageClient = {
+  get backend () {
+    return getStorageClient().backend
+  },
+  createUploadUrl: bindMethod('createUploadUrl'),
+  createPresignedDownloadUrl: bindMethod('createPresignedDownloadUrl'),
+  createDownloadUrl: bindMethod('createDownloadUrl'),
+  load: bindMethod('load'),
+  headObject: bindMethod('headObject'),
+  save: bindMethod('save'),
+}
+
+export { LocalStorageClient } from './filesystem-storage.client.js'
+export { S3Client } from './s3.client.js'

package/src/storage/storage.integration.js

@@ -0,0 +1,40 @@
+import { createLogger } from '@ossy/observability'
+import { createFilesystemStorageClient } from './filesystem-storage.client.js'
+import { createS3StorageClient } from './s3-storage.client.js'
+
+const log = createLogger('storage')
+
+export const id = 'storage'
+
+/** Always connect — filesystem when S3 is not configured. */
+export const credentials = []
+
+/**
+ * Primary blob storage: S3 when MEDIA_REPOSITORY is set, otherwise local filesystem.
+ *
+ * Logical keys are flat resource ids (see storage-keys.js). Mongo holds folder paths.
+ *
+ * @param {{ env: NodeJS.ProcessEnv }} opts
+ */
+export async function connect ({ env }) {
+  const bucket = env.MEDIA_REPOSITORY
+
+  if (bucket) {
+    const missing = ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY'].filter((key) => !(key in env))
+    if (missing.length) {
+      log.warn(`[storage] MEDIA_REPOSITORY set but missing ${missing.join(', ')} — using filesystem fallback`)
+    } else {
+      log.info('[storage] Using S3 backend')
+      return createS3StorageClient({
+        bucket,
+        cdnDomainName: env.MEDIA_CDN_DOMAIN_NAME,
+        accessKeyId: env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+      })
+    }
+  }
+
+  const client = createFilesystemStorageClient({ env })
+  log.info(`[storage] Using filesystem backend at ${client.root}`)
+  return client
+}

package/src/tasks/change-stream.js

@@ -1,6 +1,6 @@
 import { TaskService } from './task-service.js'
 import { createLogger } from '@ossy/observability'
-import { resolveMongoUrl } from '@ossy/event-store'
+import { ProjectionRebuild, PushInvalidation, resolveMongoUrl } from '@ossy/event-store'
 
 const log = createLogger('platform')
 
@@ -17,6 +17,10 @@ export class ChangeStream {
   static _reconnectAttempts = 0
   static _dbUrl = null
   static _client = null
+  /** @type {import('mongodb').ChangeStream | null} */
+  static _changeStream = null
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  static _reconnectTimer = null
 
   /**
    * Opens the MongoDB changestream and wires up reconnect logic.
@@ -33,12 +37,35 @@ export class ChangeStream {
     })
   }
 
-  static stop() {
+  static async stop () {
     ChangeStream._stopped = true
-    if (ChangeStream._client) {
-      ChangeStream._client.close().catch(() => {})
-      ChangeStream._client = null
+
+    if (ChangeStream._reconnectTimer) {
+      clearTimeout(ChangeStream._reconnectTimer)
+      ChangeStream._reconnectTimer = null
+    }
+
+    const stream = ChangeStream._changeStream
+    ChangeStream._changeStream = null
+    if (stream) {
+      try {
+        await stream.close()
+      } catch {
+        // ignore — stream may already be closed
+      }
+    }
+
+    const client = ChangeStream._client
+    ChangeStream._client = null
+    if (client) {
+      try {
+        await client.close()
+      } catch {
+        // ignore
+      }
     }
+
+    log.info('[ChangeStream] Stopped')
   }
 
   static async _getMongoClient() {
@@ -46,7 +73,10 @@ export class ChangeStream {
     return MongoClient
   }
 
-  static async _getClient() {
+  static async _getClient () {
+    if (ChangeStream._stopped) {
+      throw new Error('ChangeStream stopped')
+    }
     if (!ChangeStream._client) {
       const MongoClient = await ChangeStream._getMongoClient()
       ChangeStream._client = new MongoClient(ChangeStream._dbUrl, {
@@ -56,7 +86,8 @@ export class ChangeStream {
     return ChangeStream._client
   }
 
-  static async _resetClient() {
+  static async _resetClient () {
+    if (ChangeStream._stopped) return
     const MongoClient = await ChangeStream._getMongoClient()
     const prev = ChangeStream._client
     ChangeStream._client = new MongoClient(ChangeStream._dbUrl, {
@@ -68,7 +99,7 @@ export class ChangeStream {
     log.info('[ChangeStream] New MongoClient instance created')
   }
 
-  static _scheduleReconnect() {
+  static _scheduleReconnect () {
     if (ChangeStream._stopped) return
 
     const delaySecs = Math.min(Math.pow(2, ChangeStream._reconnectAttempts), 30)
@@ -76,7 +107,12 @@ export class ChangeStream {
 
     log.info(`[ChangeStream] Reconnecting in ${delaySecs}s...`)
 
-    setTimeout(() => {
+    if (ChangeStream._reconnectTimer) {
+      clearTimeout(ChangeStream._reconnectTimer)
+    }
+
+    ChangeStream._reconnectTimer = setTimeout(() => {
+      ChangeStream._reconnectTimer = null
       if (ChangeStream._stopped) return
       ChangeStream._open().catch((error) => {
         log.error('[ChangeStream] Change stream could not be opened', undefined, error)
@@ -85,16 +121,30 @@ export class ChangeStream {
     }, delaySecs * 1000)
   }
 
-  static async _open() {
+  static async _open () {
+    if (ChangeStream._stopped) return
+
     log.info('[ChangeStream] Watching for changes')
 
     const dbName = process.env.DB_NAME || 'test'
     const client = await ChangeStream._getClient()
+    if (ChangeStream._stopped) return
+
     const collection = client.db(dbName).collection('eventstore')
 
+    if (ChangeStream._changeStream) {
+      try {
+        await ChangeStream._changeStream.close()
+      } catch {
+        // ignore
+      }
+      ChangeStream._changeStream = null
+    }
+
     const changeStream = collection.watch([
       { $match: { operationType: 'insert' } },
     ])
+    ChangeStream._changeStream = changeStream
 
     const wasReconnecting = ChangeStream._reconnectAttempts > 0
     ChangeStream._reconnectAttempts = 0
@@ -105,6 +155,7 @@ export class ChangeStream {
     // Ensures only one reconnect is scheduled if both 'error' and 'close' fire for the same failure.
     let reconnectScheduled = false
     const scheduleOnce = () => {
+      if (ChangeStream._stopped) return
       if (!reconnectScheduled) {
         reconnectScheduled = true
         ChangeStream._scheduleReconnect()
@@ -112,6 +163,7 @@ export class ChangeStream {
     }
 
     changeStream.on('error', (error) => {
+      if (ChangeStream._stopped) return
       log.error('[ChangeStream] Change stream error (server keeps running)', undefined, error)
       if (isMongoTopologyClosedError(error)) {
         ChangeStream._resetClient().catch(() => {})
@@ -121,15 +173,30 @@ export class ChangeStream {
 
     changeStream.on('change', (change) => {
       log.info('[ChangeStream] Change detected')
-      TaskService.dispatch(change.fullDocument)
+      const event = change.fullDocument
+      if (event) {
+        ProjectionRebuild.dispatch(event).catch((error) => {
+          log.error('[ChangeStream] Projection rebuild failed', undefined, error)
+        })
+        PushInvalidation.publish(event)
+      }
+      TaskService.dispatch(event)
     })
 
     changeStream.on('close', () => {
+      if (ChangeStream._changeStream === changeStream) {
+        ChangeStream._changeStream = null
+      }
+      if (ChangeStream._stopped) return
       log.info('[ChangeStream] close detected')
       scheduleOnce()
     })
 
     changeStream.on('end', () => {
+      if (ChangeStream._changeStream === changeStream) {
+        ChangeStream._changeStream = null
+      }
+      if (ChangeStream._stopped) return
       log.info('[ChangeStream] end detected')
       scheduleOnce()
     })