@peanut-admin/admin 0.1.0-alpha.2

package/task-job/src/contracts.ts

@@ -0,0 +1,117 @@
+export type TaskStatus = 'queued' | 'running' | 'succeeded' | 'dead' | 'cancelled'
+
+export interface TaskJob {
+  readonly jobKey: string
+  readonly taskType: string
+  readonly status: TaskStatus
+  readonly attemptCount: number
+  readonly maxAttempts: number
+  readonly revision: number
+  readonly lastErrorCode: string | null
+  readonly availableAt: string
+  readonly createdAt: string
+  readonly updatedAt: string
+  readonly completedAt: string | null
+}
+
+export interface TaskJobList {
+  readonly items: readonly TaskJob[]
+  readonly page: number
+  readonly pageSize: number
+  readonly total: number
+}
+
+export interface TaskTransportResult {
+  readonly body: unknown
+  readonly headers: Headers
+  readonly status: number
+}
+
+export interface TaskJobTransport {
+  list: (status: TaskStatus, page: number, pageSize: number, signal: AbortSignal) => Promise<TaskTransportResult>
+  cancel: (jobKey: string, revision: number, signal: AbortSignal) => Promise<TaskTransportResult>
+  retry: (jobKey: string, revision: number, signal: AbortSignal) => Promise<TaskTransportResult>
+}
+
+const jobKeyPattern = /^job_[0-9a-f]{32}$/
+const taskTypePattern = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
+const errorCodePattern = /^[A-Z][A-Z0-9_]{2,63}$/
+const statuses: readonly TaskStatus[] = ['queued', 'running', 'succeeded', 'dead', 'cancelled']
+
+const record = (value: unknown): Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('TASK_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('TASK_RESPONSE_INVALID')
+  }
+}
+
+const timestamp = (value: unknown): value is string => typeof value === 'string'
+  && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+  && Number.isFinite(Date.parse(value))
+
+export const parseTaskJob = (value: unknown): TaskJob => {
+  const item = record(value)
+  exactKeys(item, [
+    'job_key', 'task_type', 'status', 'attempt_count', 'max_attempts', 'revision',
+    'last_error_code', 'available_at', 'created_at', 'updated_at', 'completed_at',
+  ])
+  if (
+    typeof item.job_key !== 'string' || !jobKeyPattern.test(item.job_key)
+    || typeof item.task_type !== 'string' || !taskTypePattern.test(item.task_type)
+    || typeof item.status !== 'string' || !statuses.includes(item.status as TaskStatus)
+    || typeof item.attempt_count !== 'number' || !Number.isSafeInteger(item.attempt_count) || item.attempt_count < 0
+    || typeof item.max_attempts !== 'number' || !Number.isSafeInteger(item.max_attempts) || item.max_attempts < 1 || item.max_attempts > 10
+    || item.attempt_count > item.max_attempts
+    || typeof item.revision !== 'number' || !Number.isSafeInteger(item.revision) || item.revision < 1
+    || (item.last_error_code !== null && (typeof item.last_error_code !== 'string' || !errorCodePattern.test(item.last_error_code)))
+    || !timestamp(item.available_at) || !timestamp(item.created_at) || !timestamp(item.updated_at)
+    || (item.completed_at !== null && !timestamp(item.completed_at))
+    || (['succeeded', 'dead', 'cancelled'].includes(item.status) !== (item.completed_at !== null))
+  ) throw new Error('TASK_RESPONSE_INVALID')
+  return {
+    jobKey: item.job_key,
+    taskType: item.task_type,
+    status: item.status as TaskStatus,
+    attemptCount: item.attempt_count,
+    maxAttempts: item.max_attempts,
+    revision: item.revision,
+    lastErrorCode: item.last_error_code,
+    availableAt: item.available_at,
+    createdAt: item.created_at,
+    updatedAt: item.updated_at,
+    completedAt: item.completed_at,
+  }
+}
+
+export const parseTaskResponse = (value: unknown): TaskJob => {
+  const body = record(value)
+  exactKeys(body, ['data', 'meta'])
+  record(body.meta)
+  return parseTaskJob(body.data)
+}
+
+export const parseTaskList = (value: unknown): TaskJobList => {
+  const body = record(value)
+  exactKeys(body, ['data', 'meta'])
+  const data = record(body.data)
+  const meta = record(body.meta)
+  exactKeys(data, ['items'])
+  if (!Array.isArray(data.items)) throw new Error('TASK_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('TASK_RESPONSE_INVALID')
+    }
+  }
+  return {
+    items: data.items.map(parseTaskJob),
+    page: meta.page as number,
+    pageSize: meta.page_size as number,
+    total: meta.total as number,
+  }
+}

package/task-job/src/index.ts

@@ -0,0 +1,2 @@
+export * from './contracts'
+export * from './runtime'

package/task-job/src/runtime.ts

@@ -0,0 +1,105 @@
+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 { parseTaskList, parseTaskResponse } from './contracts'
+import type { TaskJob, TaskJobTransport, TaskStatus, TaskTransportResult } from './contracts'
+
+export const TASK_JOB_MODULE_KEY = 'peanut.task-job' as const
+export const TASK_JOB_ROUTE_NAME = 'peanut.task-job.list' as const
+export const TASK_JOB_ROUTE_PATH = '/app/tasks' as const
+export const TASK_JOB_READ_PERMISSION = 'peanut.task-job.read' as const
+export const TASK_JOB_MANAGE_PERMISSION = 'peanut.task-job.manage' as const
+export const TASK_JOB_STORE_KEY = 'peanut.task-job.runtime' as const
+
+export interface TaskJobError { readonly message: string; readonly requestId: string | null; readonly status: number | null }
+export interface TaskJobState {
+  items: TaskJob[]; status: TaskStatus; page: number; pageSize: number; total: number
+  loading: boolean; mutating: boolean; error: TaskJobError | null
+}
+export interface TaskJobRuntime {
+  readonly state: TaskJobState
+  readonly canManage: () => boolean
+  load: () => Promise<void>
+  setStatus: (status: TaskStatus) => Promise<void>
+  cancel: (job: TaskJob) => Promise<void>
+  retry: (job: TaskJob) => Promise<void>
+  dispose: () => void
+}
+export interface TaskJobRuntimeOptions {
+  readonly transport: TaskJobTransport
+  readonly canRead: () => boolean
+  readonly canManage: () => boolean
+}
+
+const failure = (result: TaskTransportResult): TaskJobError => {
+  const body = typeof result.body === 'object' && result.body !== null && !Array.isArray(result.body)
+    ? result.body as Record<string, unknown> : {}
+  const id = body.request_id ?? result.headers.get('X-Request-Id')
+  return {
+    message: typeof body.detail === 'string' && body.detail !== '' ? body.detail : `Task request failed (${result.status}).`,
+    requestId: typeof id === 'string' && id !== '' ? id : null,
+    status: result.status,
+  }
+}
+
+export const createTaskJobRuntime = (options: TaskJobRuntimeOptions): TaskJobRuntime => {
+  const state = reactive<TaskJobState>({
+    items: [], status: 'queued', page: 1, pageSize: 20, total: 0,
+    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('TASK_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 = parseTaskList(result.body)
+      state.items = [...list.items]; state.page = list.page; state.pageSize = list.pageSize; state.total = list.total
+    } catch {
+      if (current === generation) state.error = { message: 'The task service could not be reached.', requestId: null, status: null }
+    } finally { if (current === generation) state.loading = false }
+  }
+  const mutate = async (job: TaskJob, operation: 'cancel' | 'retry'): Promise<void> => {
+    if (!options.canManage() || state.mutating) return
+    state.mutating = true; state.error = null
+    try {
+      const result = await run(signal => options.transport[operation](job.jobKey, job.revision, signal))
+      if (result.status !== 200) { state.error = failure(result); return }
+      parseTaskResponse(result.body); await load()
+    } catch { state.error = { message: 'The task action could not be completed.', requestId: null, status: null } }
+    finally { state.mutating = false }
+  }
+  return {
+    state, canManage: options.canManage, load,
+    async setStatus(status) { state.status = status; state.page = 1; await load() },
+    cancel: job => mutate(job, 'cancel'),
+    retry: job => mutate(job, 'retry'),
+    dispose() { generation += 1; for (const controller of controllers) controller.abort(); controllers.clear() },
+  }
+}
+
+export const taskJobRuntimeKey: InjectionKey<TaskJobRuntime> = Symbol(TASK_JOB_STORE_KEY)
+export const useTaskJobRuntime = (): TaskJobRuntime => {
+  const runtime = inject(taskJobRuntimeKey)
+  if (runtime === undefined) throw new Error('TASK_JOB_RUNTIME_MISSING')
+  return runtime
+}
+export const createTaskJobModuleContribution = (runtime: TaskJobRuntime): AdminModuleContribution => defineAdminModule({
+  key: TASK_JOB_MODULE_KEY,
+  routes: [{
+    name: TASK_JOB_ROUTE_NAME, path: TASK_JOB_ROUTE_PATH,
+    component: async () => ({ default: (await import('./TaskJobPage.vue')).default }),
+    access: { moduleKey: TASK_JOB_MODULE_KEY, permissionKeys: [TASK_JOB_READ_PERMISSION] },
+  }],
+  disposeOnTenantChange: true,
+  stores: [{ key: TASK_JOB_STORE_KEY, dispose: runtime.dispose }],
+})

package/testing/src/index.ts

@@ -0,0 +1,141 @@
+import type {
+  PlatformContextData,
+  ProblemDetails,
+  TenantContextData,
+} from '@peanut-admin/admin/core'
+
+export const WEB_TESTING_PACKAGE = '@peanut-admin/admin/testing' as const
+export const WEB_TESTING_VERSION = '0.1.0' as const
+
+export const mockTenantContext = (
+  overrides: Partial<TenantContextData> = {},
+): TenantContextData => ({
+  audience: 'tenant',
+  accountId: '1',
+  tenantId: '10',
+  memberId: '20',
+  moduleKeys: ['core'],
+  permissionKeys: ['core.member.read'],
+  authorizationRevision: '1',
+  ...overrides,
+})
+
+export const mockPlatformContext = (
+  overrides: Partial<PlatformContextData> = {},
+): PlatformContextData => ({
+  audience: 'platform',
+  accountId: '1',
+  operatorId: '30',
+  permissionKeys: ['platform.tenant.read'],
+  authorizationRevision: '1',
+  ...overrides,
+})
+
+export interface MockProblemOptions extends Partial<ProblemDetails> {
+  code: string
+  status: number
+}
+
+export const mockProblemDetails = (options: MockProblemOptions): ProblemDetails => {
+  const { code, status, ...overrides } = options
+
+  return {
+    type: `/docs/problems/${code.toLowerCase().replaceAll('_', '-')}`,
+    title: 'Request rejected',
+    status,
+    detail: 'The request was rejected by the test fixture.',
+    code,
+    request_id: 'req_web_testing_fixture',
+    ...overrides,
+  }
+}
+
+export interface MockAccessState {
+  permissionKeys: ReadonlySet<string>
+  moduleKeys: ReadonlySet<string>
+  hasPermission: (permission: string) => boolean
+  hasModule: (moduleKey: string) => boolean
+}
+
+export const mockAccessState = (options: {
+  permissionKeys?: readonly string[]
+  moduleKeys?: readonly string[]
+} = {}): MockAccessState => {
+  const permissionKeys = new Set(options.permissionKeys ?? [])
+  const moduleKeys = new Set(options.moduleKeys ?? [])
+
+  return {
+    permissionKeys,
+    moduleKeys,
+    hasPermission: permission => permission !== '*' && permissionKeys.has(permission),
+    hasModule: moduleKey => moduleKeys.has(moduleKey),
+  }
+}
+
+export type GuardResult = boolean | Promise<boolean>
+export type AudienceGuard = (path: string) => GuardResult
+
+export interface RouteGuardHarness {
+  navigate: (path: string) => Promise<'allowed' | 'denied'>
+}
+
+export const createRouteGuardHarness = (guards: {
+  tenant: AudienceGuard
+  platform: AudienceGuard
+}): RouteGuardHarness => ({
+  async navigate(path) {
+    const pathname = new URL(path, 'https://peanut-admin.test').pathname
+    if (pathname === '/app' || pathname.startsWith('/app/')) {
+      return await guards.tenant(pathname) ? 'allowed' : 'denied'
+    }
+    if (pathname === '/platform' || pathname.startsWith('/platform/')) {
+      return await guards.platform(pathname) ? 'allowed' : 'denied'
+    }
+
+    return 'allowed'
+  },
+})
+
+const containsTenantState = (value: unknown): boolean => {
+  if (value === null || value === undefined || value === false || value === '' || value === 0) {
+    return false
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0
+  }
+  if (value instanceof Map || value instanceof Set) {
+    return value.size > 0
+  }
+  if (typeof value === 'object') {
+    return Object.values(value).some(containsTenantState)
+  }
+
+  return true
+}
+
+export const assertTenantStateDisposed = async (
+  inspect: () => unknown,
+  switchTenant: () => void | Promise<void>,
+): Promise<void> => {
+  await switchTenant()
+  if (containsTenantState(inspect())) {
+    throw new Error('TENANT_STATE_LEAK')
+  }
+}
+
+export interface Deferred<T> {
+  promise: Promise<T>
+  resolve: (value: T | PromiseLike<T>) => void
+  reject: (reason?: unknown) => void
+}
+
+export const createDeferred = <T>(): Deferred<T> => {
+  let resolve!: Deferred<T>['resolve']
+  let reject!: Deferred<T>['reject']
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise
+    reject = rejectPromise
+  })
+
+  return { promise, resolve, reject }
+}