@peanut-admin/admin 0.1.0-alpha.11

package/file-media/src/FileMediaPage.vue

@@ -0,0 +1,158 @@
+<script setup lang="ts">
+import { EmptyState, ForbiddenState, ModuleUnavailableState, PageContent, PageHeader, PageToolbar, SessionExpiredState } from '@peanut-admin/admin/shell'
+import { ElButton } from 'element-plus'
+import { computed, onMounted, ref } from 'vue'
+import FileAssetSelector from './FileAssetSelector.vue'
+import { useFileMediaRuntime } from './runtime'
+
+const runtime = useFileMediaRuntime()
+const state = runtime.state
+const input = ref<HTMLInputElement | null>(null)
+const canCreate = computed(runtime.canCreate)
+const canDelete = computed(runtime.canDelete)
+const selectedAssetKey = ref<string | null>(null)
+
+const upload = async (event: Event): Promise<void> => {
+  const target = event.currentTarget
+  if (!(target instanceof HTMLInputElement) || target.files?.length !== 1) return
+  const file = target.files.item(0)
+  if (file !== null) await runtime.upload(file)
+  target.value = ''
+}
+
+onMounted(() => Promise.all([runtime.load(), runtime.loadAssets()]))
+</script>
+
+<template>
+  <PageContent class="file-media-page">
+    <PageHeader>
+      Files
+      <template #actions>
+        <input
+          ref="input"
+          class="file-input"
+          type="file"
+          aria-label="Choose private file"
+          @change="upload"
+        >
+        <ElButton
+          :disabled="!canCreate || state.mutating"
+          type="primary"
+          @click="input?.click()"
+        >
+          Upload
+        </ElButton>
+        <ElButton
+          :loading="state.loading"
+          :disabled="state.mutating"
+          @click="runtime.load"
+        >
+          Reload
+        </ElButton>
+      </template>
+    </PageHeader>
+    <PageToolbar label="File status">
+      <ElButton
+        :type="state.status === 'ready' ? 'primary' : 'default'"
+        @click="runtime.setStatus('ready')"
+      >
+        Ready
+      </ElButton>
+      <ElButton
+        :type="state.status === 'archived' ? 'primary' : 'default'"
+        @click="runtime.setStatus('archived')"
+      >
+        Archived
+      </ElButton>
+    </PageToolbar>
+
+    <FileAssetSelector
+      :items="state.assets"
+      :selected-file-key="selectedAssetKey"
+      :loading="state.assetsLoading"
+      :error="state.assetsError?.message ?? null"
+      :disabled="state.mutating"
+      @select="selectedAssetKey = $event.fileKey"
+      @retry="runtime.loadAssets"
+    />
+
+    <SessionExpiredState
+      v-if="state.error?.status === 401"
+      :message="state.error.message"
+    />
+    <ForbiddenState
+      v-else-if="state.error?.status === 403"
+      :message="state.error.message"
+    />
+    <ModuleUnavailableState
+      v-else-if="state.error?.status === 503"
+      :message="state.error.message"
+      @action="runtime.load"
+    />
+    <section
+      v-else-if="state.error"
+      role="alert"
+      class="file-state"
+    >
+      <h2>Unable to complete the file request</h2>
+      <p>{{ state.error.message }}</p>
+      <p v-if="state.error.requestId">
+        Request ID: {{ state.error.requestId }}
+      </p>
+    </section>
+    <div
+      v-else-if="state.loading"
+      class="file-state"
+      role="status"
+    >
+      Loading files...
+    </div>
+    <EmptyState
+      v-else-if="state.items.length === 0"
+      title="No files"
+      message="No private files match this status."
+    />
+    <div
+      v-else
+      class="file-table-wrap"
+    >
+      <table class="file-table">
+        <thead><tr><th>Name</th><th>Type</th><th>Size</th><th>Status</th><th>Revision</th><th>Actions</th></tr></thead>
+        <tbody>
+          <tr
+            v-for="file in state.items"
+            :key="file.fileKey"
+          >
+            <td>{{ file.originalName }}</td><td>{{ file.mediaType }}</td><td>{{ file.sizeBytes }}</td>
+            <td>{{ file.status }}</td><td>{{ file.revision }}</td>
+            <td>
+              <ElButton
+                v-if="file.status === 'ready'"
+                text
+                @click="runtime.download(file)"
+              >
+                Download
+              </ElButton>
+              <ElButton
+                v-if="file.status === 'ready'"
+                text
+                :disabled="!canDelete || state.mutating"
+                @click="runtime.archive(file)"
+              >
+                Archive
+              </ElButton>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  </PageContent>
+</template>
+
+<style scoped>
+.file-input { display: none; }
+.file-state { padding: 24px 0; }
+.file-table-wrap { overflow-x: auto; }
+.file-table { width: 100%; border-collapse: collapse; }
+.file-table th, .file-table td { padding: 10px 8px; border-bottom: 1px solid var(--el-border-color); text-align: left; }
+</style>

package/file-media/src/contracts.ts

@@ -0,0 +1,220 @@
+export type FileStatus = 'ready' | 'archived'
+
+export interface FileObject {
+  readonly fileKey: string
+  readonly originalName: string
+  readonly mediaType: string
+  readonly sizeBytes: number
+  readonly sha256: string
+  readonly status: FileStatus
+  readonly revision: number
+  readonly createdAt: string
+  readonly updatedAt: string
+  readonly archivedAt: string | null
+}
+
+export interface FileList {
+  readonly items: readonly FileObject[]
+  readonly page: number
+  readonly pageSize: number
+  readonly total: number
+}
+
+export interface FileTransportResult {
+  readonly body: unknown
+  readonly headers: Headers
+  readonly status: number
+}
+
+export interface FileMediaTransport {
+  list: (status: FileStatus, page: number, pageSize: number, signal: AbortSignal) => Promise<FileTransportResult>
+  assets: (page: number, pageSize: number, signal: AbortSignal) => Promise<FileTransportResult>
+  upload: (file: File, signal: AbortSignal) => Promise<FileTransportResult>
+  download: (fileKey: string, signal: AbortSignal) => Promise<Response>
+  archive: (fileKey: string, etag: string, signal: AbortSignal) => Promise<FileTransportResult>
+}
+
+export interface ImageVariant {
+  readonly variantKey: string
+  readonly width: number
+  readonly height: number
+  readonly mediaType: 'image/jpeg' | 'image/png'
+  readonly deliveryUri: string | null
+}
+
+export interface AssetCandidate {
+  readonly fileKey: string
+  readonly originalName: string
+  readonly mediaType: 'image/jpeg' | 'image/png'
+  readonly width: number
+  readonly height: number
+  readonly previewUri: string | null
+  readonly variants: readonly ImageVariant[]
+}
+
+export interface AssetList {
+  readonly items: readonly AssetCandidate[]
+  readonly page: number
+  readonly pageSize: number
+  readonly total: number
+}
+
+const fileKeyPattern = /^file_[0-9a-f]{32}$/
+const shaPattern = /^[0-9a-f]{64}$/
+
+const record = (value: unknown): Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  return value as Record<string, unknown>
+}
+
+const exactKeys = (value: Record<string, unknown>, keys: readonly string[]): void => {
+  const actual = Object.keys(value).sort()
+  const expected = [...keys].sort()
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  }
+}
+
+const deliveryUri = (value: unknown): string | null => {
+  if (value === null) return null
+  if (typeof value !== 'string' || value === '' || value.length > 2048 || value.includes('#')) {
+    throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  }
+  if (value.startsWith('/')) {
+    if (value.startsWith('//') || !value.startsWith('/api/')) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+    return value
+  }
+  let parsed: URL
+  try { parsed = new URL(value) } catch { throw new Error('FILE_MEDIA_RESPONSE_INVALID') }
+  if (parsed.protocol !== 'https:' || parsed.username !== '' || parsed.password !== '') {
+    throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  }
+  return value
+}
+
+export const parseFileObject = (value: unknown): FileObject => {
+  const item = record(value)
+  exactKeys(item, [
+    'file_key', 'original_name', 'media_type', 'size_bytes', 'sha256', 'status',
+    'revision', 'created_at', 'updated_at', 'archived_at',
+  ])
+  if (
+    typeof item.file_key !== 'string' || !fileKeyPattern.test(item.file_key)
+    || typeof item.original_name !== 'string' || item.original_name === '' || [...item.original_name].length > 255
+    || typeof item.media_type !== 'string' || item.media_type === '' || item.media_type.length > 127
+    || typeof item.size_bytes !== 'number' || !Number.isSafeInteger(item.size_bytes) || item.size_bytes < 1
+    || typeof item.sha256 !== 'string' || !shaPattern.test(item.sha256)
+    || (item.status !== 'ready' && item.status !== 'archived')
+    || typeof item.revision !== 'number' || !Number.isSafeInteger(item.revision) || item.revision < 1
+    || typeof item.created_at !== 'string' || !Number.isFinite(Date.parse(item.created_at))
+    || typeof item.updated_at !== 'string' || !Number.isFinite(Date.parse(item.updated_at))
+    || (item.archived_at !== null && (typeof item.archived_at !== 'string' || !Number.isFinite(Date.parse(item.archived_at))))
+    || (item.status === 'ready') !== (item.archived_at === null)
+  ) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+
+  return {
+    fileKey: item.file_key,
+    originalName: item.original_name,
+    mediaType: item.media_type,
+    sizeBytes: item.size_bytes,
+    sha256: item.sha256,
+    status: item.status,
+    revision: item.revision,
+    createdAt: item.created_at,
+    updatedAt: item.updated_at,
+    archivedAt: item.archived_at,
+  }
+}
+
+export const parseFileResponse = (value: unknown): FileObject => {
+  const body = record(value)
+  exactKeys(body, ['data', 'meta'])
+  record(body.meta)
+  return parseFileObject(body.data)
+}
+
+export const parseFileList = (value: unknown): FileList => {
+  const body = record(value)
+  exactKeys(body, ['data', 'meta'])
+  const data = record(body.data)
+  exactKeys(data, ['items'])
+  const meta = record(body.meta)
+  if (!Array.isArray(data.items)) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  for (const key of ['page', 'page_size', 'total'] as const) {
+    if (typeof meta[key] !== 'number' || !Number.isSafeInteger(meta[key]) || meta[key] < (key === 'total' ? 0 : 1)) {
+      throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+    }
+  }
+  return {
+    items: data.items.map(parseFileObject),
+    page: meta.page as number,
+    pageSize: meta.page_size as number,
+    total: meta.total as number,
+  }
+}
+
+export const parseAssetCandidate = (value: unknown): AssetCandidate => {
+  const item = record(value)
+  exactKeys(item, ['file_key', 'original_name', 'media_type', 'width', 'height', 'preview_uri', 'variants'])
+  if (
+    typeof item.file_key !== 'string' || !fileKeyPattern.test(item.file_key)
+    || typeof item.original_name !== 'string' || item.original_name === '' || [...item.original_name].length > 255
+    || (item.media_type !== 'image/jpeg' && item.media_type !== 'image/png')
+    || typeof item.width !== 'number' || !Number.isSafeInteger(item.width) || item.width < 1 || item.width > 50000
+    || typeof item.height !== 'number' || !Number.isSafeInteger(item.height) || item.height < 1 || item.height > 50000
+    || item.width * item.height > 100_000_000
+    || !Array.isArray(item.variants) || item.variants.length > 16
+  ) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  const keys = new Set<string>()
+  const variants = item.variants.map((value): ImageVariant => {
+    const variant = record(value)
+    exactKeys(variant, ['variant_key', 'width', 'height', 'media_type', 'delivery_uri'])
+    if (
+      typeof variant.variant_key !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(variant.variant_key)
+      || keys.has(variant.variant_key)
+      || typeof variant.width !== 'number' || !Number.isSafeInteger(variant.width) || variant.width < 1 || variant.width > 4096
+      || typeof variant.height !== 'number' || !Number.isSafeInteger(variant.height) || variant.height < 1 || variant.height > 4096
+      || (variant.media_type !== 'image/jpeg' && variant.media_type !== 'image/png')
+    ) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+    keys.add(variant.variant_key)
+    return {
+      variantKey: variant.variant_key,
+      width: variant.width,
+      height: variant.height,
+      mediaType: variant.media_type,
+      deliveryUri: deliveryUri(variant.delivery_uri),
+    }
+  })
+  return {
+    fileKey: item.file_key,
+    originalName: item.original_name,
+    mediaType: item.media_type,
+    width: item.width,
+    height: item.height,
+    previewUri: deliveryUri(item.preview_uri),
+    variants,
+  }
+}
+
+export const parseAssetList = (value: unknown): AssetList => {
+  const body = record(value)
+  exactKeys(body, ['data', 'meta'])
+  const data = record(body.data)
+  const meta = record(body.meta)
+  exactKeys(data, ['items'])
+  exactKeys(meta, ['request_id', 'page', 'page_size', 'total'])
+  if (!Array.isArray(data.items) || typeof meta.request_id !== 'string' || meta.request_id === '') {
+    throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  }
+  for (const key of ['page', 'page_size', 'total'] as const) {
+    if (typeof meta[key] !== 'number' || !Number.isSafeInteger(meta[key]) || meta[key] < (key === 'total' ? 0 : 1)) {
+      throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+    }
+  }
+  return {
+    items: data.items.map(parseAssetCandidate),
+    page: meta.page as number,
+    pageSize: meta.page_size as number,
+    total: meta.total as number,
+  }
+}

package/file-media/src/index.ts

@@ -0,0 +1,19 @@
+export const FILE_MEDIA_PACKAGE = '@peanut-admin/admin/file-media' as const
+export const FILE_MEDIA_VERSION = '0.1.0' as const
+export { default as FileAssetSelector } from './FileAssetSelector.vue'
+export { parseAssetCandidate, parseFileList, parseFileObject, parseFileResponse } from './contracts'
+export type { AssetCandidate, AssetList, FileList, FileMediaTransport, FileObject, FileStatus, FileTransportResult, ImageVariant } from './contracts'
+export {
+  createFileMediaModuleContribution,
+  createFileMediaRuntime,
+  FILE_MEDIA_CREATE_PERMISSION,
+  FILE_MEDIA_DELETE_PERMISSION,
+  FILE_MEDIA_MODULE_KEY,
+  FILE_MEDIA_READ_PERMISSION,
+  FILE_MEDIA_ROUTE_NAME,
+  FILE_MEDIA_ROUTE_PATH,
+  FILE_MEDIA_STORE_KEY,
+  fileMediaRuntimeKey,
+  useFileMediaRuntime,
+} from './runtime'
+export type { FileMediaError, FileMediaRuntime, FileMediaRuntimeOptions, FileMediaState } from './runtime'

package/file-media/src/runtime.ts

@@ -0,0 +1,210 @@
+import { defineAdminModule } from '@peanut-admin/admin/core'
+import { inject, reactive } from 'vue'
+import type { AdminModuleContribution } from '@peanut-admin/admin/core'
+import type { InjectionKey } from 'vue'
+
+import { parseAssetList, parseFileList, parseFileResponse } from './contracts'
+import type { AssetCandidate, FileMediaTransport, FileObject, FileStatus, FileTransportResult } from './contracts'
+
+export const FILE_MEDIA_MODULE_KEY = 'peanut.file-media' as const
+export const FILE_MEDIA_ROUTE_NAME = 'peanut.file-media.list' as const
+export const FILE_MEDIA_ROUTE_PATH = '/app/files' as const
+export const FILE_MEDIA_READ_PERMISSION = 'peanut.file-media.read' as const
+export const FILE_MEDIA_CREATE_PERMISSION = 'peanut.file-media.create' as const
+export const FILE_MEDIA_DELETE_PERMISSION = 'peanut.file-media.delete' as const
+export const FILE_MEDIA_STORE_KEY = 'peanut.file-media.runtime' as const
+
+export interface FileMediaError {
+  readonly message: string
+  readonly requestId: string | null
+  readonly status: number | null
+}
+
+export interface FileMediaState {
+  items: FileObject[]
+  status: FileStatus
+  page: number
+  pageSize: number
+  total: number
+  assets: AssetCandidate[]
+  assetsLoading: boolean
+  assetsError: FileMediaError | null
+  loading: boolean
+  mutating: boolean
+  error: FileMediaError | null
+}
+
+export interface FileMediaRuntime {
+  readonly state: FileMediaState
+  readonly canCreate: () => boolean
+  readonly canDelete: () => boolean
+  load: () => Promise<void>
+  loadAssets: () => Promise<void>
+  setStatus: (status: FileStatus) => Promise<void>
+  upload: (file: File) => Promise<void>
+  download: (file: FileObject) => Promise<void>
+  archive: (file: FileObject) => Promise<void>
+  dispose: () => void
+}
+
+export interface FileMediaRuntimeOptions {
+  readonly transport: FileMediaTransport
+  readonly canRead: () => boolean
+  readonly canCreate: () => boolean
+  readonly canDelete: () => boolean
+  readonly saveDownload?: (response: Response, file: FileObject) => Promise<void>
+}
+
+const requestId = (result: FileTransportResult): string | null => {
+  const body = typeof result.body === 'object' && result.body !== null && !Array.isArray(result.body)
+    ? result.body as Record<string, unknown>
+    : {}
+  const value = body.request_id ?? result.headers.get('X-Request-Id')
+  return typeof value === 'string' && value !== '' ? value : null
+}
+
+const failure = (result: FileTransportResult): FileMediaError => {
+  const body = typeof result.body === 'object' && result.body !== null && !Array.isArray(result.body)
+    ? result.body as Record<string, unknown>
+    : {}
+  return {
+    message: typeof body.detail === 'string' && body.detail !== '' ? body.detail : `File request failed (${result.status}).`,
+    requestId: requestId(result),
+    status: result.status,
+  }
+}
+
+const defaultSave = async (response: Response, file: FileObject): Promise<void> => {
+  const blob = await response.blob()
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = file.originalName
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+
+export const createFileMediaRuntime = (options: FileMediaRuntimeOptions): FileMediaRuntime => {
+  const state = reactive<FileMediaState>({
+    items: [], status: 'ready', page: 1, pageSize: 20, total: 0,
+    assets: [], assetsLoading: false, assetsError: null,
+    loading: false, mutating: false, error: null,
+  })
+  const controllers = new Set<AbortController>()
+  let generation = 0
+  const run = async <T>(operation: (signal: AbortSignal) => Promise<T>): Promise<T> => {
+    const controller = new AbortController()
+    controllers.add(controller)
+    try { return await operation(controller.signal) } finally { controllers.delete(controller) }
+  }
+
+  const load = async (): Promise<void> => {
+    const current = ++generation
+    state.loading = true
+    state.error = null
+    try {
+      if (!options.canRead()) throw new Error('FILE_MEDIA_PERMISSION_DENIED')
+      const result = await run(signal => options.transport.list(state.status, state.page, state.pageSize, signal))
+      if (current !== generation) return
+      if (result.status !== 200) { state.error = failure(result); return }
+      const list = parseFileList(result.body)
+      state.items = [...list.items]
+      state.page = list.page
+      state.pageSize = list.pageSize
+      state.total = list.total
+    } catch (error) {
+      if (current === generation && !(error instanceof DOMException && error.name === 'AbortError')) {
+        state.error = { message: 'The file service could not be reached.', requestId: null, status: null }
+      }
+    } finally {
+      if (current === generation) state.loading = false
+    }
+  }
+
+  const loadAssets = async (): Promise<void> => {
+    const current = generation
+    state.assetsLoading = true
+    state.assetsError = null
+    try {
+      if (!options.canRead()) throw new Error('FILE_MEDIA_PERMISSION_DENIED')
+      const result = await run(signal => options.transport.assets(1, 50, signal))
+      if (current !== generation) return
+      if (result.status !== 200) { state.assetsError = failure(result); return }
+      state.assets = [...parseAssetList(result.body).items]
+    } catch (error) {
+      if (current === generation && !(error instanceof DOMException && error.name === 'AbortError')) {
+        state.assetsError = { message: 'The media asset service could not be reached.', requestId: null, status: null }
+      }
+    } finally {
+      if (current === generation) state.assetsLoading = false
+    }
+  }
+
+  return {
+    state,
+    canCreate: options.canCreate,
+    canDelete: options.canDelete,
+    load,
+    loadAssets,
+    async setStatus(status) { state.status = status; state.page = 1; await load() },
+    async upload(file) {
+      if (!options.canCreate() || state.mutating) return
+      state.mutating = true
+      state.error = null
+      try {
+        const result = await run(signal => options.transport.upload(file, signal))
+        if (result.status !== 201) { state.error = failure(result); return }
+        parseFileResponse(result.body)
+        state.status = 'ready'
+        await Promise.all([load(), loadAssets()])
+      } catch { state.error = { message: 'The upload could not be completed.', requestId: null, status: null } }
+      finally { state.mutating = false }
+    },
+    async download(file) {
+      state.error = null
+      try {
+        const response = await run(signal => options.transport.download(file.fileKey, signal))
+        if (!response.ok) {
+          let body: unknown = null
+          try { body = await response.json() } catch { body = null }
+          state.error = failure({ body, headers: response.headers, status: response.status })
+          return
+        }
+        await (options.saveDownload ?? defaultSave)(response, file)
+      } catch { state.error = { message: 'The download could not be completed.', requestId: null, status: null } }
+    },
+    async archive(file) {
+      if (!options.canDelete() || state.mutating) return
+      state.mutating = true
+      state.error = null
+      try {
+        const result = await run(signal => options.transport.archive(file.fileKey, `"rev-${file.revision}"`, signal))
+        if (result.status !== 200) { state.error = failure(result); return }
+        parseFileResponse(result.body)
+        await load()
+      } catch { state.error = { message: 'The file could not be archived.', requestId: null, status: null } }
+      finally { state.mutating = false }
+    },
+    dispose() { generation += 1; for (const controller of controllers) controller.abort(); controllers.clear(); state.assets = [] },
+  }
+}
+
+export const fileMediaRuntimeKey: InjectionKey<FileMediaRuntime> = Symbol(FILE_MEDIA_STORE_KEY)
+
+export const useFileMediaRuntime = (): FileMediaRuntime => {
+  const runtime = inject(fileMediaRuntimeKey)
+  if (runtime === undefined) throw new Error('FILE_MEDIA_RUNTIME_MISSING')
+  return runtime
+}
+
+export const createFileMediaModuleContribution = (runtime: FileMediaRuntime): AdminModuleContribution => defineAdminModule({
+  key: FILE_MEDIA_MODULE_KEY,
+  routes: [{
+    name: FILE_MEDIA_ROUTE_NAME,
+    path: FILE_MEDIA_ROUTE_PATH,
+    component: async () => ({ default: (await import('./FileMediaPage.vue')).default }),
+    access: { moduleKey: FILE_MEDIA_MODULE_KEY, permissionKeys: [FILE_MEDIA_READ_PERMISSION] },
+  }],
+  disposeOnTenantChange: true,
+  stores: [{ key: FILE_MEDIA_STORE_KEY, dispose: runtime.dispose }],
+})