@peanut-admin/admin 0.1.0-alpha.2

package/admin-core/src/module/contribution.ts

@@ -0,0 +1,124 @@
+import type { Component } from 'vue'
+
+export interface AdminRouteAccess {
+  moduleKey: string
+  permissionKeys: readonly string[]
+}
+
+export interface AdminModuleRoute {
+  name: string
+  path: string
+  component: () => Promise<{ default: Component }>
+  access: AdminRouteAccess
+}
+
+export interface AdminModuleStoreContribution {
+  key: string
+  dispose: () => void | Promise<void>
+}
+
+export interface AdminModuleLocaleContribution {
+  locale: string
+  load: () => Promise<Readonly<Record<string, string>>>
+}
+
+export type AdminModuleShellSlotName = 'header-context' | 'header-actions' | 'sidebar-footer' | 'page-tools'
+
+export interface AdminModuleShellSlotContribution {
+  name: AdminModuleShellSlotName
+  component: () => Promise<{ default: Component }>
+  access?: AdminRouteAccess
+}
+
+export interface AdminModuleContribution {
+  key: string
+  routes: readonly AdminModuleRoute[]
+  disposeOnTenantChange: boolean
+  stores?: readonly AdminModuleStoreContribution[]
+  locales?: readonly AdminModuleLocaleContribution[]
+  shellSlots?: readonly AdminModuleShellSlotContribution[]
+}
+
+const moduleKeyPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:-[a-z0-9]+)*)*$/
+const routeNamePattern = /^[a-z][a-z0-9]*(?:[.-][a-z][a-z0-9]*)+$/
+
+export const defineAdminModule = <T extends AdminModuleContribution>(contribution: T): T => {
+  if (!moduleKeyPattern.test(contribution.key)) {
+    throw new Error(`ADMIN_MODULE_KEY_INVALID: ${contribution.key}`)
+  }
+  const names = new Set<string>()
+  const paths = new Set<string>()
+  for (const route of contribution.routes) {
+    if (!routeNamePattern.test(route.name) || names.has(route.name)) {
+      throw new Error(`ADMIN_MODULE_ROUTE_NAME_INVALID: ${route.name}`)
+    }
+    if (!route.path.startsWith('/app/') || paths.has(route.path)) {
+      throw new Error(`ADMIN_MODULE_ROUTE_PATH_INVALID: ${route.path}`)
+    }
+    if (route.access.moduleKey !== contribution.key || route.access.permissionKeys.length === 0) {
+      throw new Error(`ADMIN_MODULE_ROUTE_ACCESS_INVALID: ${route.name}`)
+    }
+    names.add(route.name)
+    paths.add(route.path)
+  }
+  const storeKeys = new Set<string>()
+  for (const store of contribution.stores ?? []) {
+    if (!store.key.startsWith(`${contribution.key}.`) || storeKeys.has(store.key)) {
+      throw new Error(`ADMIN_MODULE_STORE_INVALID: ${store.key}`)
+    }
+    storeKeys.add(store.key)
+  }
+  const locales = new Set<string>()
+  for (const locale of contribution.locales ?? []) {
+    if (!/^[a-z]{2}(?:-[A-Z]{2})?$/.test(locale.locale) || locales.has(locale.locale)) {
+      throw new Error(`ADMIN_MODULE_LOCALE_INVALID: ${locale.locale}`)
+    }
+    locales.add(locale.locale)
+  }
+  const slots = new Set<AdminModuleShellSlotName>()
+  for (const slot of contribution.shellSlots ?? []) {
+    if (slots.has(slot.name) || (slot.access !== undefined && slot.access.moduleKey !== contribution.key)) {
+      throw new Error(`ADMIN_MODULE_SHELL_SLOT_INVALID: ${slot.name}`)
+    }
+    slots.add(slot.name)
+  }
+
+  return contribution
+}
+
+export interface MenuRouteRegistry {
+  resolve: (routeName: string) => AdminModuleRoute | null
+  diagnostics: () => readonly string[]
+  routes: () => readonly AdminModuleRoute[]
+}
+
+export const createMenuRouteRegistry = (
+  contributions: readonly AdminModuleContribution[],
+): MenuRouteRegistry => {
+  const routeMap = new Map<string, AdminModuleRoute>()
+  const paths = new Set<string>()
+  for (const rawContribution of contributions) {
+    const contribution = defineAdminModule(rawContribution)
+    for (const route of contribution.routes) {
+      if (routeMap.has(route.name) || paths.has(route.path)) {
+        throw new Error(`ADMIN_ROUTE_REGISTRY_CONFLICT: ${route.name}`)
+      }
+      routeMap.set(route.name, route)
+      paths.add(route.path)
+    }
+  }
+  const unknownRoutes = new Set<string>()
+
+  return {
+    resolve(routeName) {
+      const route = routeMap.get(routeName)
+      if (route === undefined) {
+        unknownRoutes.add(routeName)
+        return null
+      }
+      return route
+    },
+    diagnostics: () => [...unknownRoutes],
+    routes: () => [...routeMap.values()],
+  }
+}

package/admin-core/src/runtime/config.ts

@@ -0,0 +1,55 @@
+export interface AdminAudienceHostConfig {
+  baseUrl: string
+  allowedOrigin: string
+  clientKey: string
+}
+
+export interface AdminHostConfig {
+  tenant: AdminAudienceHostConfig
+  platform: AdminAudienceHostConfig
+}
+
+const clientKeyPattern = /^[a-z][a-z0-9-]{0,63}$/
+
+const parseAuthority = (value: string): URL => {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error('ADMIN_HOST_ORIGIN_INVALID')
+  }
+
+  if (!['http:', 'https:'].includes(url.protocol)
+    || url.origin === 'null'
+    || url.username !== ''
+    || url.password !== ''
+    || url.pathname !== '/'
+    || url.search !== ''
+    || url.hash !== '') {
+    throw new Error('ADMIN_HOST_ORIGIN_INVALID')
+  }
+
+  return url
+}
+
+const defineAudienceConfig = (config: AdminAudienceHostConfig): AdminAudienceHostConfig => {
+  const baseUrl = parseAuthority(config.baseUrl)
+  const allowedOrigin = parseAuthority(config.allowedOrigin)
+  if (baseUrl.origin !== allowedOrigin.origin) {
+    throw new Error('ADMIN_HOST_ORIGIN_MISMATCH')
+  }
+  if (!clientKeyPattern.test(config.clientKey)) {
+    throw new Error('ADMIN_HOST_CLIENT_KEY_INVALID')
+  }
+
+  return {
+    baseUrl: baseUrl.origin,
+    allowedOrigin: allowedOrigin.origin,
+    clientKey: config.clientKey,
+  }
+}
+
+export const defineAdminHostConfig = (config: AdminHostConfig): AdminHostConfig => ({
+  tenant: defineAudienceConfig(config.tenant),
+  platform: defineAudienceConfig(config.platform),
+})

package/admin-core/src/runtime/errors.ts

@@ -0,0 +1,81 @@
+import type { ApiAudience } from '../api/client'
+import type { ProblemDetails } from '../api/problem'
+
+export type AdminRuntimeErrorKind =
+  | 'login'
+  | 'forbidden'
+  | 'not-found'
+  | 'conflict'
+  | 'rate-limited'
+  | 'unavailable'
+  | 'configuration'
+
+export interface AdminRuntimeErrorState {
+  kind: AdminRuntimeErrorKind
+  audience: ApiAudience
+  code: string
+  requestId: string | null
+  retryAfter: string | null
+}
+
+interface ProblemErrorSource {
+  problem: ProblemDetails
+  retryAfter?: string | null
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => (
+  typeof value === 'object' && value !== null
+)
+
+const problemSource = (value: unknown): ProblemErrorSource | null => {
+  if (!isRecord(value) || !isRecord(value.problem)) return null
+  const problem = value.problem
+  if (typeof problem.status !== 'number'
+    || typeof problem.code !== 'string'
+    || typeof problem.request_id !== 'string') return null
+
+  return {
+    problem: problem as unknown as ProblemDetails,
+    retryAfter: typeof value.retryAfter === 'string' ? value.retryAfter : null,
+  }
+}
+
+const kindForStatus = (status: number): AdminRuntimeErrorKind => {
+  if (status === 401) return 'login'
+  if (status === 403) return 'forbidden'
+  if (status === 404) return 'not-found'
+  if (status === 409 || status === 412) return 'conflict'
+  if (status === 429) return 'rate-limited'
+  return 'unavailable'
+}
+
+export const mapAdminRuntimeError = (
+  error: unknown,
+  audience: ApiAudience,
+): AdminRuntimeErrorState => {
+  const source = problemSource(error)
+  if (source !== null) {
+    return {
+      kind: kindForStatus(source.problem.status),
+      audience,
+      code: source.problem.code,
+      requestId: source.problem.request_id,
+      retryAfter: source.retryAfter ?? null,
+    }
+  }
+
+  const code = error instanceof Error ? error.message : 'CLIENT_BOOT_FAILED'
+  if (code === 'API_ORIGIN_INVALID'
+    || code === 'API_ORIGIN_MISMATCH'
+    || code.startsWith('API_AUDIENCE_MISMATCH')) {
+    return { kind: 'configuration', audience, code, requestId: null, retryAfter: null }
+  }
+
+  return {
+    kind: 'unavailable',
+    audience,
+    code: code === '' ? 'CLIENT_BOOT_FAILED' : code,
+    requestId: null,
+    retryAfter: null,
+  }
+}

package/admin-core/src/runtime/guard.ts

@@ -0,0 +1,40 @@
+import type { ApiAudience } from '../api/client'
+
+export interface AdminRouteGuardInput {
+  audience: ApiAudience
+  moduleKey?: string
+  permissionKeys?: readonly string[]
+}
+
+export interface AdminRouteGuardDependencies {
+  enterAudience: (audience: ApiAudience) => Promise<void>
+  ensureContext: (audience: ApiAudience) => Promise<void>
+  loadNavigation: (audience: ApiAudience) => Promise<void>
+  hasModule: (moduleKey: string) => boolean
+  hasPermissions: (permissionKeys: readonly string[]) => boolean
+}
+
+export type AdminRouteGuardResult =
+  | { status: 'allowed' }
+  | { status: 'module-unavailable', code: 'MODULE_TENANT_DISABLED' }
+  | { status: 'forbidden', code: 'AUTHZ_FUNCTIONAL_DENIED' }
+
+export const runAdminRouteGuard = async (
+  route: AdminRouteGuardInput,
+  dependencies: AdminRouteGuardDependencies,
+): Promise<AdminRouteGuardResult> => {
+  await dependencies.enterAudience(route.audience)
+  await dependencies.ensureContext(route.audience)
+  await dependencies.loadNavigation(route.audience)
+
+  if (route.moduleKey !== undefined && !dependencies.hasModule(route.moduleKey)) {
+    return { status: 'module-unavailable', code: 'MODULE_TENANT_DISABLED' }
+  }
+  if (route.permissionKeys !== undefined
+    && route.permissionKeys.length > 0
+    && !dependencies.hasPermissions(route.permissionKeys)) {
+    return { status: 'forbidden', code: 'AUTHZ_FUNCTIONAL_DENIED' }
+  }
+
+  return { status: 'allowed' }
+}

package/admin-core/src/runtime/navigation.ts

@@ -0,0 +1,105 @@
+import type { ApiAudience } from '../api/client'
+import type { AdminModuleContribution } from '../module/contribution'
+import { defineAdminModule } from '../module/contribution'
+
+export interface AdminNavigationRoute {
+  name: string
+  path: string
+  audience: ApiAudience
+  permission?: string
+  permissionKeys?: readonly string[]
+  moduleKey?: string
+}
+
+export interface AdminNavigationMenuInput {
+  route_name?: unknown
+  route_path?: unknown
+  component?: unknown
+}
+
+export interface AdminNavigationRegistry {
+  resolveMenu: (menu: AdminNavigationMenuInput) => AdminNavigationRoute | null
+  diagnostics: () => readonly string[]
+  clearDiagnostics: () => void
+  routes: () => readonly AdminNavigationRoute[]
+  disposeTenantState: () => Promise<void>
+}
+
+export interface AdminNavigationRegistryInput {
+  routes: readonly AdminNavigationRoute[]
+  modules: readonly AdminModuleContribution[]
+}
+
+const throwRegistryConflict = (name: string): never => {
+  throw new Error(`ADMIN_ROUTE_REGISTRY_CONFLICT: ${name}`)
+}
+
+const matchesAudience = (route: AdminNavigationRoute): boolean => route.audience === 'tenant'
+  ? route.path === '/app' || route.path.startsWith('/app/')
+  : route.path === '/platform' || route.path.startsWith('/platform/')
+
+const runDisposers = async (disposers: readonly (() => void | Promise<void>)[]): Promise<void> => {
+  const results = await Promise.allSettled(disposers.map(async dispose => dispose()))
+  const failure = results.find((result): result is PromiseRejectedResult => result.status === 'rejected')
+  if (failure !== undefined) throw failure.reason
+}
+
+export const createAdminNavigationRegistry = (
+  input: AdminNavigationRegistryInput,
+): AdminNavigationRegistry => {
+  const routeMap = new Map<string, AdminNavigationRoute>()
+  const paths = new Set<string>()
+  const moduleKeys = new Set<string>()
+  const tenantDisposers: Array<() => void | Promise<void>> = []
+
+  const registerRoute = (route: AdminNavigationRoute): void => {
+    if (route.name === ''
+      || !matchesAudience(route)
+      || routeMap.has(route.name)
+      || paths.has(route.path)) {
+      throwRegistryConflict(route.name)
+    }
+    routeMap.set(route.name, {
+      ...route,
+      ...(route.permissionKeys === undefined ? {} : { permissionKeys: [...route.permissionKeys] }),
+    })
+    paths.add(route.path)
+  }
+
+  for (const route of input.routes) registerRoute(route)
+  for (const rawModule of input.modules) {
+    const module = defineAdminModule(rawModule)
+    if (moduleKeys.has(module.key)) throwRegistryConflict(module.key)
+    moduleKeys.add(module.key)
+    for (const route of module.routes) {
+      registerRoute({
+        name: route.name,
+        path: route.path,
+        audience: 'tenant',
+        moduleKey: module.key,
+        permissionKeys: route.access.permissionKeys,
+      })
+    }
+    if (module.disposeOnTenantChange) {
+      tenantDisposers.push(...(module.stores ?? []).map(store => store.dispose))
+    }
+  }
+
+  const unknownRoutes = new Set<string>()
+
+  return {
+    resolveMenu(menu) {
+      if (typeof menu.route_name !== 'string') return null
+      const route = routeMap.get(menu.route_name)
+      if (route === undefined) {
+        unknownRoutes.add(menu.route_name)
+        return null
+      }
+      return route
+    },
+    diagnostics: () => [...unknownRoutes],
+    clearDiagnostics: () => unknownRoutes.clear(),
+    routes: () => [...routeMap.values()],
+    disposeTenantState: () => runDisposers(tenantDisposers),
+  }
+}

package/admin-core/src/runtime/overrides.ts

@@ -0,0 +1,214 @@
+export type AdminOverrideKind = 'service' | 'component' | 'page' | 'route'
+
+export type AdminOverrideSource = 'default' | 'application'
+
+export interface AdminOverrideSlot<Value = unknown> {
+  readonly key: string
+  readonly kind: AdminOverrideKind
+  readonly contractVersion: string
+  readonly defaultValue: Value
+  readonly validate?: (value: unknown) => value is Value
+}
+
+export interface AdminOverride<Value = unknown> {
+  readonly key: string
+  readonly kind: AdminOverrideKind
+  readonly contractVersion: string
+  readonly value: Value
+}
+
+export interface AdminOverrideResolution<Value = unknown> {
+  readonly key: string
+  readonly kind: AdminOverrideKind
+  readonly contractVersion: string
+  readonly value: Value
+  readonly source: AdminOverrideSource
+}
+
+export type AdminOverrideResolutionMetadata = Omit<AdminOverrideResolution, 'value'>
+
+export interface AdminOverrideRegistryInput<
+  Slots extends readonly AdminOverrideSlot[] = readonly AdminOverrideSlot[],
+> {
+  readonly slots: Slots
+  readonly overrides?: readonly AdminOverride[]
+}
+
+type SlotValue<Slots extends readonly AdminOverrideSlot[], Key extends string> =
+  Extract<Slots[number], { readonly key: Key }> extends infer Slot
+    ? Slot extends AdminOverrideSlot<infer Value> ? Value : unknown
+    : unknown
+
+type SlotKey<Slots extends readonly AdminOverrideSlot[]> = Slots[number]['key'] & string
+
+export interface AdminOverrideRegistry<
+  Slots extends readonly AdminOverrideSlot[] = readonly AdminOverrideSlot[],
+> {
+  resolve<Key extends SlotKey<Slots>>(key: Key): AdminOverrideResolution<SlotValue<Slots, Key>>
+  get<Key extends SlotKey<Slots>>(key: Key): SlotValue<Slots, Key>
+  diagnostics(): readonly AdminOverrideResolutionMetadata[]
+}
+
+const overrideKinds: readonly AdminOverrideKind[] = ['service', 'component', 'page', 'route']
+const overrideKindSet = new Set<AdminOverrideKind>(overrideKinds)
+const overrideKeyPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:-[a-z0-9]+)*){2,}$/
+const contractVersionPattern = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/
+
+const isRecord = (value: unknown): value is Record<string, unknown> => (
+  typeof value === 'object' && value !== null
+)
+
+const hasOwn = (value: object, key: PropertyKey): boolean => (
+  Object.prototype.hasOwnProperty.call(value, key)
+)
+
+const fail = (code: string, detail?: string): never => {
+  throw new Error(detail === undefined ? code : `${code}: ${detail}`)
+}
+
+const validateKey = (value: unknown, kind: unknown): string => {
+  if (typeof value !== 'string' || !overrideKeyPattern.test(value)) {
+    return fail('ADMIN_OVERRIDE_SLOT_KEY_INVALID', typeof value === 'string' ? value : 'unknown')
+  }
+  if (typeof kind !== 'string' || !overrideKindSet.has(kind as AdminOverrideKind)) {
+    return fail('ADMIN_OVERRIDE_KIND_INVALID', String(kind))
+  }
+  if (!value.split('.').includes(kind)) {
+    return fail('ADMIN_OVERRIDE_SLOT_KEY_KIND_INVALID', value)
+  }
+  return value
+}
+
+const validateVersion = (value: unknown): string => {
+  if (typeof value !== 'string' || !contractVersionPattern.test(value)) {
+    return fail('ADMIN_OVERRIDE_CONTRACT_VERSION_INVALID', typeof value === 'string' ? value : 'unknown')
+  }
+  return value
+}
+
+const validatorAccepts = (validator: (value: unknown) => boolean, value: unknown): boolean => {
+  try {
+    return validator(value) === true
+  } catch {
+    return false
+  }
+}
+
+const freezeMetadata = (
+  metadata: AdminOverrideResolutionMetadata,
+): AdminOverrideResolutionMetadata => Object.freeze({ ...metadata })
+
+const freezeResolution = <Value>(
+  resolution: AdminOverrideResolution<Value>,
+): AdminOverrideResolution<Value> => Object.freeze({ ...resolution })
+
+const copyMetadata = (
+  metadata: readonly AdminOverrideResolutionMetadata[],
+): readonly AdminOverrideResolutionMetadata[] => Object.freeze(
+  metadata.map(entry => freezeMetadata(entry)),
+)
+
+export const defineAdminOverrideSlot = <Value, Slot extends AdminOverrideSlot<Value>>(
+  slot: Slot,
+): Slot => slot
+
+export const createAdminOverrideRegistry = <
+  Slots extends readonly AdminOverrideSlot[],
+>(input: AdminOverrideRegistryInput<Slots>): AdminOverrideRegistry<Slots> => {
+  if (!isRecord(input) || !Array.isArray(input.slots)) {
+    fail('ADMIN_OVERRIDE_SLOTS_INVALID')
+  }
+  if (input.overrides !== undefined && !Array.isArray(input.overrides)) {
+    fail('ADMIN_OVERRIDE_OVERRIDES_INVALID')
+  }
+
+  const slots = new Map<string, AdminOverrideSlot>()
+  for (const rawSlot of input.slots) {
+    if (!isRecord(rawSlot)) fail('ADMIN_OVERRIDE_SLOT_INVALID')
+
+    const key = validateKey(rawSlot.key, rawSlot.kind)
+    if (slots.has(key)) fail('ADMIN_OVERRIDE_SLOT_KEY_DUPLICATE', key)
+
+    if (!hasOwn(rawSlot, 'contractVersion')) {
+      fail('ADMIN_OVERRIDE_CONTRACT_VERSION_INVALID', key)
+    }
+    const contractVersion = validateVersion(rawSlot.contractVersion)
+    if (!hasOwn(rawSlot, 'defaultValue')) {
+      fail('ADMIN_OVERRIDE_DEFAULT_INVALID', key)
+    }
+    if (rawSlot.validate !== undefined && typeof rawSlot.validate !== 'function') {
+      fail('ADMIN_OVERRIDE_VALIDATOR_INVALID', key)
+    }
+    const slot = rawSlot as unknown as AdminOverrideSlot
+    if (slot.validate !== undefined && !validatorAccepts(slot.validate, slot.defaultValue)) {
+      fail('ADMIN_OVERRIDE_DEFAULT_INVALID', key)
+    }
+
+    slots.set(key, Object.freeze({
+      key,
+      kind: rawSlot.kind as AdminOverrideKind,
+      contractVersion,
+      defaultValue: slot.defaultValue,
+      ...(slot.validate === undefined ? {} : { validate: slot.validate }),
+    }))
+  }
+
+  const values = new Map<string, AdminOverrideResolution>()
+  for (const [key, slot] of slots) {
+    values.set(key, freezeResolution({
+      key,
+      kind: slot.kind,
+      contractVersion: slot.contractVersion,
+      value: slot.defaultValue,
+      source: 'default',
+    }))
+  }
+
+  const seenOverrides = new Set<string>()
+  for (const rawOverride of input.overrides ?? []) {
+    if (!isRecord(rawOverride) || typeof rawOverride.key !== 'string') {
+      fail('ADMIN_OVERRIDE_OVERRIDE_KEY_INVALID')
+    }
+    const key = rawOverride.key
+    if (seenOverrides.has(key)) fail('ADMIN_OVERRIDE_KEY_DUPLICATE', key)
+    seenOverrides.add(key)
+
+    const slot = slots.get(key) ?? fail('ADMIN_OVERRIDE_KEY_UNKNOWN', key)
+    if (rawOverride.kind !== slot.kind) {
+      fail('ADMIN_OVERRIDE_KIND_MISMATCH', key)
+    }
+    if (rawOverride.contractVersion !== slot.contractVersion) {
+      fail('ADMIN_OVERRIDE_CONTRACT_VERSION_MISMATCH', key)
+    }
+    if (!hasOwn(rawOverride, 'value')) fail('ADMIN_OVERRIDE_VALUE_INVALID', key)
+
+    const value = rawOverride.value
+    if (slot.validate !== undefined && !validatorAccepts(slot.validate, value)) {
+      fail('ADMIN_OVERRIDE_VALUE_INVALID', key)
+    }
+
+    values.set(key, freezeResolution({
+      key,
+      kind: slot.kind,
+      contractVersion: slot.contractVersion,
+      value,
+      source: 'application',
+    }))
+  }
+
+  const metadata = [...values.values()].map(({ key, kind, contractVersion, source }) => (
+    freezeMetadata({ key, kind, contractVersion, source })
+  ))
+
+  const resolve = <Value>(key: string): AdminOverrideResolution<Value> => {
+    const resolution = values.get(key)
+    if (resolution === undefined) fail('ADMIN_OVERRIDE_SLOT_UNKNOWN', key)
+    return resolution as AdminOverrideResolution<Value>
+  }
+
+  return {
+    resolve,
+    get: <Value>(key: string): Value => resolve<Value>(key).value,
+    diagnostics: () => copyMetadata(metadata),
+  } as AdminOverrideRegistry<Slots>
+}