@things-factory/figure-service 10.1.111 → 10.1.113

package/server/service/figure/figure-thumbnail-store.ts

@@ -0,0 +1,108 @@
+import { createHash } from 'crypto'
+import { Readable } from 'stream'
+
+import { Attachment, STORAGE } from '@things-factory/attachment-base'
+
+/*
+ * A figure's picture, kept by attachment-base and named by its content (ADR-0104 decision 6, chief architect's ruling
+ * 2026-10-02).
+ *
+ *   stored    by attachment-base's storage (file, S3, database -- whichever the install configures), one attachment
+ *             per (domain, content): refType `figure-thumbnail`, refBy the SHA-256 of the bytes. A figure, its
+ *             releases and the drafts a revert kept carry that hash, never the bytes.
+ *   served    only through `/figure-thumbnail/:id`, behind the figure query permission -- never through attachment-
+ *             base's public `/attachment/:path`, which checks nothing (a known gap, recorded in ADR-0104).
+ *   the same  content twice in one domain is one attachment, read by its hash. Two writers that both find none both
+ *             write one; either serves the same bytes, so the result is the same (ruling, condition 2).
+ *
+ * The file is written before the row that names it: a file cannot be rolled back, so it goes first, and a row that
+ * fails to commit leaves a file the next write of the same content writes again.
+ */
+
+export const THUMBNAIL_REF_TYPE = 'figure-thumbnail'
+
+/** `data:image/webp;base64,....` as its type and bytes; undefined when it is not one. */
+export function decodeDataUrl(dataUrl: string): { type: string; bytes: Buffer } | undefined {
+  const matched = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl)
+  return matched ? { type: matched[1]!, bytes: Buffer.from(matched[2]!, 'base64') } : undefined
+}
+
+export const sha256Of = (bytes: Buffer) => createHash('sha256').update(bytes).digest('hex')
+
+/** Where the bytes go: attachment-base's storage. Tests give another. */
+export interface ThumbnailFiles {
+  put(bytes: Buffer, mimetype: string, name: string, context: any): Promise<{ id: string; path: string; size: number; contents?: Buffer }>
+  send(koa: any, path: string, next: () => Promise<any>): Promise<void>
+}
+
+export const attachmentFiles: ThumbnailFiles = {
+  async put(bytes, mimetype, name, context) {
+    const file = Promise.resolve({
+      createReadStream: () => Readable.from([bytes]),
+      filename: name,
+      mimetype,
+      encoding: 'binary'
+    })
+    const { id, path, size, contents } = await STORAGE.uploadFile({ file, context })
+    return { id, path, size, contents }
+  },
+  send: (koa, path, next) => STORAGE.sendFile(koa, path, next)
+}
+
+/*
+ * The files in use: attachment-base's storage, unless a test gives its own. One seam for every writer and the router,
+ * so a test of a save or a revert need not reach into each.
+ */
+let inUse: ThumbnailFiles = attachmentFiles
+export const thumbnailFiles = (): ThumbnailFiles => inUse
+/** For tests: use these files until set back; returns the ones it replaced. */
+export function useThumbnailFiles(files: ThumbnailFiles): ThumbnailFiles {
+  const was = inUse
+  inUse = files
+  return was
+}
+
+type Tx = { getRepository: (target: any) => any }
+
+/** The attachment holding this content in this domain, or undefined. */
+export async function thumbnailAttachmentOf(tx: Tx, domainId: string, hash: string): Promise<Attachment | undefined> {
+  return (await tx.getRepository(Attachment).findOne({ where: { domain: { id: domainId }, refType: THUMBNAIL_REF_TYPE, refBy: hash } })) ?? undefined
+}
+
+/**
+ * Keeps a picture and gives its hash. Refused when it is not a data URL -- a picture the server cannot read is one it
+ * must not keep under a name.
+ */
+export async function keepThumbnail(
+  tx: Tx,
+  domain: { id: string },
+  user: unknown,
+  dataUrl: string,
+  files: ThumbnailFiles = thumbnailFiles()
+): Promise<string> {
+  const decoded = decodeDataUrl(dataUrl)
+  if (!decoded) throw new Error('썸네일은 data URL(data:image/...;base64,...) 이어야 한다')
+  const hash = sha256Of(decoded.bytes)
+  if (await thumbnailAttachmentOf(tx, domain.id, hash)) return hash
+  const ext = decoded.type.split('/')[1]?.split('+')[0] || 'bin'
+  const name = `${hash}.${ext}`
+  /* The file first: it cannot be rolled back. The row that names it comes after, in the caller's transaction. */
+  const put = await files.put(decoded.bytes, decoded.type, name, { state: { domain, user, tx } })
+  await tx.getRepository(Attachment).save({
+    domain,
+    creator: user,
+    updater: user,
+    id: put.id,
+    name,
+    mimetype: decoded.type,
+    encoding: 'binary',
+    refType: THUMBNAIL_REF_TYPE,
+    refBy: hash,
+    category: 'image',
+    size: String(put.size),
+    path: put.path,
+    ...(put.contents ? { contents: put.contents } : {})
+  })
+  return hash
+}
+

package/server/service/figure/figure-thumbnail-upgrade.pg.test.ts

@@ -0,0 +1,93 @@
+import { join } from 'path'
+
+/**
+ * Two starts moving the same install's pictures at once, on postgres (chief architect's ruling 2026-10-02, condition 2:
+ * the same hash written twice must come to the same result). sqlite holds one connection and cannot show this. Runs
+ * only when FIGURE_PG_URL names a server:
+ *
+ *   docker run -d --name fig-revert-pg -e POSTGRES_PASSWORD=figrv -e POSTGRES_USER=figrv -e POSTGRES_DB=figrv \
+ *     -p 55441:5432 postgres:14-alpine
+ *   yarn workspace @things-factory/figure-service build:server
+ *   FIGURE_PG_URL=postgres://figrv:figrv@localhost:55441/figrv \
+ *     node_modules/.bin/jest --selectProjects figure-service-ts --coverage=false figure-thumbnail-upgrade
+ *
+ * Every round must end with every picture moved exactly as it was: each row names its own content's hash, no base64
+ * is left, and every hash has an attachment holding those bytes. A row emptied without its hash, or a hash with no
+ * file, is the defect.
+ */
+
+const url = process.env.FIGURE_PG_URL
+const maybe = url ? describe : describe.skip
+const ROUNDS = 6
+const ROWS = 24
+
+maybe('two starts moving pictures at once, on postgres', () => {
+  /*
+   * attachment-base picks its `contents` column type from `ormconfig.type` when it is loaded; the test process has no
+   * ormconfig, which reads as sqlite's blob. This file alone sees postgres, before anything loads attachment-base.
+   */
+  jest.doMock('@things-factory/env', () => {
+    const real = jest.requireActual('@things-factory/env')
+    return { ...real, config: { ...real.config, get: (key: string, fallback?: unknown) => (key === 'ormconfig' ? { type: 'postgres' } : real.config.get(key, fallback)) } }
+  })
+  const { DataSource } = require('typeorm')
+  const { entityClosure } = require(join(__dirname, '..', '..', '..', '..', 'ops-master', 'test', 'support', 'database.cjs'))
+  const { NamingStrategy } = require('@things-factory/shell/dist-server/initializers/naming-strategy.js')
+  const { Domain } = require('@things-factory/shell')
+  const { Attachment } = require('@things-factory/attachment-base')
+  const DIST = join(__dirname, '..', '..', '..', 'dist-server', 'service', 'figure')
+  const { Figure } = require(join(DIST, 'figure.js'))
+  const { FigureHistory } = require(join(DIST, 'figure-history.js'))
+  const { FigureReplacedDraft } = require(join(DIST, 'figure-replaced-draft.js'))
+  const { moveBase64Thumbnails } = require(join(DIST, 'figure-thumbnail-upgrade.js'))
+  const { sha256Of } = require(join(DIST, 'figure-thumbnail-store.js'))
+
+  const kept = new Map<string, Buffer>()
+  let n = 0
+  const files = {
+    async put(bytes: Buffer, _m: string, name: string) {
+      const id = require('crypto').randomUUID()
+      const path = `${id}.${name.split('.').pop()}`
+      kept.set(path, bytes)
+      n++
+      return { id, path, size: bytes.length }
+    },
+    async send() {}
+  }
+  const open = async (dropSchema: boolean) => {
+    const db = new DataSource({ type: 'postgres', url, synchronize: true, dropSchema, entities: entityClosure([Figure, FigureHistory, FigureReplacedDraft, Attachment]), namingStrategy: new NamingStrategy() })
+    await db.initialize()
+    return db
+  }
+  let one: any, two: any
+  beforeAll(async () => {
+    one = await open(true)
+    two = await open(false)
+  }, 60000)
+  afterAll(async () => {
+    await one?.destroy()
+    await two?.destroy()
+  })
+
+  const picture = (k: number) => `data:image/webp;base64,${Buffer.from([0x52, 0x49, k % 7, k % 5, 9]).toString('base64')}`
+
+  it('every round: each row moved once, to its own hash, with its bytes kept', async () => {
+    for (let round = 0; round < ROUNDS; round++) {
+      const domain = await one.getRepository(Domain).save({ name: `pg-${round}`, subdomain: `pg-${round}` })
+      const ids: string[] = []
+      for (let k = 0; k < ROWS; k++) {
+        const r = await one.createQueryBuilder().insert().into(Figure).values({ type: `T${round}_${k}`, name: 'x', source: '{}', state: 'draft', version: 0, thumbnail: picture(k), domain: { id: domain.id } }).callListeners(false).execute()
+        ids.push(r.identifiers[0].id)
+      }
+      await Promise.all([moveBase64Thumbnails(one, files), moveBase64Thumbnails(two, files)])
+      for (const [k, id] of ids.entries()) {
+        const row = await one.getRepository(Figure).findOneOrFail({ where: { id } })
+        const want = sha256Of(Buffer.from(picture(k).split(',')[1], 'base64'))
+        expect([row.thumbnail, row.thumbnailHash]).toEqual([null, want])
+        const holders = await one.getRepository(Attachment).find({ where: { domain: { id: domain.id }, refType: 'figure-thumbnail', refBy: want } })
+        expect(holders.length).toBeGreaterThan(0)
+        for (const h of holders) expect(sha256Of(kept.get(h.path)!)).toBe(want)
+      }
+    }
+  }, 120000)
+})

package/server/service/figure/figure-thumbnail-upgrade.ts

@@ -0,0 +1,70 @@
+import { IsNull, Not } from 'typeorm'
+
+import { Figure } from './figure.js'
+import { FigureHistory } from './figure-history.js'
+import { FigureReplacedDraft } from './figure-replaced-draft.js'
+import { keepThumbnail, thumbnailFiles, type ThumbnailFiles } from './figure-thumbnail-store.js'
+
+/*
+ * Moves the pictures an install kept as base64 into attachment-base, by their content (ADR-0104 decision 6; chief
+ * architect's ruling 2026-10-02, condition 3). Run at start, in the boot's one line (`inBootTurn`).
+ *
+ *   per row   the file first -- it cannot be rolled back -- then, in one transaction, the attachment row, the hash,
+ *             and the base64 emptied. The update only takes a row whose base64 is still the one read, so two starts
+ *             at once, or a save in between, never empty a picture that was not moved.
+ *   again     safe: a row already moved has no base64 and is not read; a picture already kept is found by its hash.
+ *   kept      a picture that is not a data URL, or a row whose domain cannot be found, keeps its base64 and is
+ *             counted -- nothing is emptied that was not moved.
+ */
+
+type Moved = { table: string; moved: number; kept: number }
+
+const TABLES = [
+  { table: 'figure', entity: Figure },
+  { table: 'figure_history', entity: FigureHistory },
+  { table: 'figure_replaced_draft', entity: FigureReplacedDraft }
+] as const
+
+export async function moveBase64Thumbnails(dataSource: any, files: ThumbnailFiles = thumbnailFiles()): Promise<Moved[]> {
+  const out: Moved[] = []
+  for (const { table, entity } of TABLES) {
+    const rows: any[] = await dataSource.getRepository(entity).find({
+      where: { thumbnail: Not(IsNull()) },
+      relations: { domain: true },
+      select: { id: true, thumbnail: true, domain: { id: true }, ...(entity === FigureHistory ? { originalId: true } : {}) },
+      withDeleted: true
+    })
+    let moved = 0,
+      kept = 0
+    for (const row of rows) {
+      /* A release written before releases carried their domain names it through the figure it belongs to. */
+      const domainId: string | undefined =
+        row.domain?.id ??
+        (entity === FigureHistory && row.originalId
+          ? (await dataSource.getRepository(Figure).findOne({ where: { id: row.originalId }, relations: { domain: true }, select: { id: true, domain: { id: true } }, withDeleted: true }))?.domain?.id
+          : undefined)
+      if (!domainId) {
+        kept++
+        continue
+      }
+      try {
+        await dataSource.transaction(async (tx: any) => {
+          const hash = await keepThumbnail(tx, { id: domainId }, undefined, row.thumbnail, files)
+          await tx
+            .createQueryBuilder()
+            .update(entity)
+            .set({ thumbnailHash: hash, thumbnail: null })
+            .where('id = :id AND thumbnail = :was', { id: row.id, was: row.thumbnail })
+            .callListeners(false)
+            .execute()
+        })
+        moved++
+      } catch (error) {
+        console.error(`[figure-service] ${table} ${row.id} 의 썸네일을 옮기지 못했다 — base64 를 그대로 둔다: ${(error as Error)?.message ?? error}`)
+        kept++
+      }
+    }
+    out.push({ table, moved, kept })
+  }
+  return out
+}

package/server/service/figure/figure-write.ts

@@ -1,3 +1,4 @@
+import { keepThumbnail, type ThumbnailFiles } from './figure-thumbnail-store.js'
 import { GraphQLError } from 'graphql'
 import { parseFigureAsset, serializeFigureAsset, compileFigureAsset, figureCostOf, figureScoreOf } from '@hatiolab/figure-model'
 
@@ -48,13 +49,23 @@ export function prepareFigureWrite(source: string, existing?: { source?: string
 }
 
 /**
- * The picture a card shows, when the modeller sent one.
+ * The picture a card shows, when the modeller sent one: kept by its content (`keepThumbnail`) and named on the row by
+ * its hash.
  *
  * Absent means the author saved without one — a tab in the background cannot draw, and the source matters more
  * than the picture, so the save goes on and the modeller fills it in next time. The timestamp moves only when
  * the picture itself is new, so renaming a figure does not make every card look freshly drawn.
  */
-export function pictureOf(thumbnail?: string, existing?: { thumbnail?: string }) {
-  if (thumbnail === undefined || thumbnail === existing?.thumbnail) return {}
-  return { thumbnail, thumbnailUpdatedAt: new Date() }
+export async function pictureOf(
+  tx: { getRepository: (target: any) => any },
+  domain: { id: string },
+  user: unknown,
+  thumbnail?: string,
+  existing?: { thumbnailHash?: string | null },
+  files?: ThumbnailFiles
+): Promise<{ thumbnailHash?: string; thumbnail?: null; thumbnailUpdatedAt?: Date }> {
+  if (thumbnail === undefined) return {}
+  const thumbnailHash = await keepThumbnail(tx, domain, user, thumbnail, files)
+  if (thumbnailHash === existing?.thumbnailHash) return {}
+  return { thumbnailHash, thumbnail: null, thumbnailUpdatedAt: new Date() }
 }

package/server/service/figure/figure.ts

@@ -176,6 +176,15 @@ export class Figure {
   @Field({ nullable: true, description: 'A base64 encoded thumbnail image of the figure.' })
   thumbnail?: string
 
+  /*
+   * 그림의 내용 해시(SHA-256). 그림 자체는 attachment-base 가 갖고(refType `figure-thumbnail`, refBy 이 해시),
+   * `/figure-thumbnail/:id` 가 권한을 본 뒤 내준다(ADR-0104 결정 6). `thumbnail` 칸은 옛 base64 가 남은 행을
+   * 기동 때 옮기기 위한 칸이다 — 옮긴 뒤에는 비어 있고, 새 그림은 그 칸에 쓰지 않는다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'SHA-256 of the thumbnail picture; the picture is served by /figure-thumbnail/:id.' })
+  thumbnailHash?: string
+
   /**
    * 썸네일이 **썸네일로서** 마지막으로 갱신된 시각. `updatedAt` 과는 별개 도메인이다 —
    * 이름·설명만 고쳤을 때는 갱신되지 않는다. `Board` 와 같은 방식.