@pikku/core 0.12.106 → 0.12.111

package/src/wirings/queue/queue-runner.ts

@@ -1,181 +0,0 @@
-import type { PikkuRawWire } from '../../types/core.types.js'
-import type { CoreQueueWorker, QueueJob, PikkuQueue } from './queue.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionSessionless,
-} from '../../function/functions.types.js'
-import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
-import { PikkuMissingMetaError } from '../../errors/errors.js'
-import {
-  getSingletonServices,
-  getCreateWireServices,
-  pikkuState,
-} from '../../pikku-state.js'
-import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { resolveQueueJobIdentity } from './queue-identity.js'
-
-class QueueWorkerNotFoundError extends PikkuError {
-  constructor(name: string) {
-    super(`Queue processor not found: ${name}`)
-  }
-}
-
-export class QueueJobFailedError extends PikkuError {
-  constructor(jobId: string, reason?: string) {
-    super(`Queue job ${jobId} failed${reason ? `: ${reason}` : ''}`)
-    this.name = 'QueueJobFailedError'
-  }
-}
-
-export class QueueJobDiscardedError extends PikkuError {
-  constructor(jobId: string, reason?: string) {
-    super(`Queue job ${jobId} discarded${reason ? `: ${reason}` : ''}`)
-    this.name = 'QueueJobDiscardedError'
-  }
-}
-
-export const wireQueueWorker = <
-  InputData = any,
-  OutputData = any,
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<InputData, OutputData>
-  > = CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<InputData, OutputData>
-  >,
->(
-  queueWorker: CoreQueueWorker<PikkuFunctionConfig>
-) => {
-  const meta = pikkuState(null, 'queue', 'meta')
-  const processorMeta = meta[queueWorker.name]
-  if (!processorMeta) {
-    console.warn(
-      `[pikku] Skipping queue worker '${queueWorker.name}' — metadata not found. Consider moving this wiring to its own file.`
-    )
-    return
-  }
-
-  addFunction(processorMeta.pikkuFuncId, {
-    func: queueWorker.func.func,
-    auth: queueWorker.func.auth,
-    permissions: queueWorker.func.permissions,
-    middleware: queueWorker.func.middleware,
-    tags: queueWorker.func.tags,
-  })
-
-  const registrations = pikkuState(null, 'queue', 'registrations')
-  registrations.set(queueWorker.name, queueWorker)
-}
-
-export function getQueueWorkers(): Map<string, CoreQueueWorker> {
-  return pikkuState(null, 'queue', 'registrations')
-}
-
-export async function removeQueueWorker(name: string): Promise<void> {
-  const registrations = pikkuState(null, 'queue', 'registrations')
-  const registration = registrations.get(name)
-
-  if (!registration) {
-    throw new QueueWorkerNotFoundError(name)
-  }
-
-  registrations.delete(name)
-}
-
-export async function runQueueJob({
-  job,
-  updateProgress,
-  traceId,
-}: {
-  job: QueueJob
-  updateProgress?: (progress: number | string | object) => Promise<void>
-  traceId?: string
-}): Promise<void> {
-  const singletonServices = getSingletonServices()
-  const createWireServices = getCreateWireServices()
-  const resolvedTraceId = traceId ?? `q-${job.id}`
-  const logger =
-    singletonServices.logger.scope?.(resolvedTraceId) ??
-    singletonServices.logger
-
-  const meta = pikkuState(null, 'queue', 'meta')
-  const processorMeta = meta[job.queueName]
-  if (!processorMeta) {
-    throw new PikkuMissingMetaError(
-      `Missing generated metadata for queue worker '${job.queueName}'`
-    )
-  }
-
-  const registrations = pikkuState(null, 'queue', 'registrations')
-  const queueWorker = registrations.get(job.queueName)
-  if (!queueWorker) {
-    throw new Error(`Queue worker registration not found for: ${job.queueName}`)
-  }
-
-  // knowledge: decisions/security/queue-job-identities-are-signed-at-enqueue.md
-  const pikkuUserId = await resolveQueueJobIdentity({
-    claimedIdentity: job.pikkuUserId,
-    binding: { queueName: job.queueName, jobId: job.id, data: job.data },
-    secrets: singletonServices.secrets,
-    logger,
-  })
-
-  const queue: PikkuQueue = {
-    queueName: job.queueName,
-    jobId: job.id,
-    pikkuUserId,
-    updateProgress:
-      updateProgress ||
-      (async (progress: number | string | object) => {
-        logger.info(`Job ${job.id} progress: ${progress}`)
-      }),
-    fail: async (reason?: string) => {
-      throw new QueueJobFailedError(job.id, reason)
-    },
-    discard: async (reason?: string) => {
-      throw new QueueJobDiscardedError(job.id, reason)
-    },
-  }
-
-  try {
-    logger.info(`Processing job ${job.id} in queue ${job.queueName}`)
-
-    const wire: PikkuRawWire = {
-      traceId: resolvedTraceId,
-      queue,
-    }
-
-    const result = await runPikkuFunc(
-      'queue',
-      job.queueName,
-      processorMeta.pikkuFuncId,
-      {
-        singletonServices,
-        createWireServices,
-        auth: false,
-        data: () => job.data,
-        inheritedMiddleware: processorMeta.middleware,
-        wireMiddleware: queueWorker.middleware,
-        tags: queueWorker.tags,
-        wire,
-      }
-    )
-
-    logger.debug(
-      `Successfully processed job ${job.id} in queue ${job.queueName}`
-    )
-
-    return result
-  } catch (error: any) {
-    logger.error(
-      `Error processing job ${job.id} in queue ${job.queueName}:`,
-      error
-    )
-
-    const errorResponse = getErrorResponse(error)
-    if (errorResponse != null) {
-      logger.error('Processed error response:', errorResponse)
-    }
-
-    throw error
-  }
-}

package/src/wirings/queue/queue.types.ts

@@ -1,161 +0,0 @@
-import type { CommonWireMeta } from '../../types/core.types.js'
-import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
-import type { QueueConfigMapping } from './validate-worker-config.js'
-import type { Safe } from '../../classification/secret-value.js'
-
-export interface PikkuWorkerConfig {
-  name?: string
-  /** Total worker concurrency. */
-  batchSize?: number
-  prefetch?: number
-  /** Milliseconds. */
-  pollInterval?: number
-  /** Seconds. */
-  visibilityTimeout?: number
-  /** Milliseconds. */
-  lockDuration?: number
-  /** Seconds. */
-  drainDelay?: number
-  /** Number of completed jobs to retain, not an age. */
-  removeOnComplete?: number
-  /** Number of failed jobs to retain, not an age. */
-  removeOnFail?: number
-  maxStalledCount?: number
-  autorun?: boolean
-  /** Must not exceed {@link batchSize}. */
-  groupConcurrency?: number | GroupConcurrencyConfig
-}
-
-export interface GroupConcurrencyConfig {
-  /** Limit applied to any group without a matching tier. */
-  default: number
-  /** Keyed by {@link JobGroup.tier}. */
-  tiers?: Record<string, number>
-}
-
-export interface JobGroup {
-  id: string
-  tier?: string
-}
-
-export interface PikkuJobConfig {
-  retryAttempts?: number
-  /** Milliseconds. */
-  retryDelay?: number
-  retryBackoff?: 'linear' | 'exponential' | 'fixed'
-  deadLetterQueue?: string
-  /** Seconds. */
-  messageRetention?: number
-  /** Higher numbers run first. */
-  priority?: number
-  fifo?: boolean
-  /** Milliseconds. */
-  timeout?: number
-  /** Milliseconds. */
-  delay?: number
-}
-
-export interface ConfigValidationResult {
-  applied: Partial<PikkuWorkerConfig>
-  ignored: Partial<PikkuWorkerConfig>
-  warnings: string[]
-  fallbacks: { [key: string]: any }
-}
-
-export type QueueJobStatus =
-  'waiting' | 'active' | 'completed' | 'failed' | 'delayed'
-
-export type QueueJobMetadata = {
-  progress?: number | string | object | undefined | boolean
-  attemptsMade?: number
-  maxAttempts?: number
-  processedAt?: Date
-  completedAt?: Date
-  failedAt?: Date
-  error?: string
-  createdAt: Date
-}
-
-export interface QueueJob<T = any, R = any> {
-  id: string
-  queueName: string
-  status: () => Promise<QueueJobStatus> | QueueJobStatus
-  data: T
-  result?: R
-  waitForCompletion?: (ttl?: number) => Promise<R>
-  metadata?: () => Promise<QueueJobMetadata> | QueueJobMetadata
-  pikkuUserId?: string
-}
-
-export interface JobOptions {
-  priority?: number
-  delay?: number
-  attempts?: number
-  backoff?: string | { type: string; delay?: number }
-  removeOnComplete?: number
-  removeOnFail?: number
-  jobId?: string
-  // knowledge: decisions/security/queue-jobs-carry-the-producers-pikku-user-id.md
-  pikkuUserId?: string
-  /** Counts against the worker's {@link PikkuWorkerConfig.groupConcurrency}. */
-  group?: JobGroup
-}
-
-export interface QueueService {
-  readonly supportsResults: boolean
-
-  add<T>(
-    queueName: string,
-    data: Safe<T>,
-    options?: JobOptions
-  ): Promise<string>
-
-  getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>
-}
-
-export interface QueueWorkers {
-  name: string
-
-  supportsResults: boolean
-
-  configMappings: QueueConfigMapping
-
-  registerQueues(): Promise<Record<string, ConfigValidationResult[]>>
-}
-
-export type QueueWorkersMeta = Record<
-  string,
-  CommonWireMeta & {
-    name: string
-    config?: PikkuWorkerConfig
-  }
->
-
-export type CoreQueueWorker<
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> =
-    CorePikkuFunctionConfig<any, any, any>,
-> = {
-  /** The queue this worker consumes. Whoever enqueues a job names the same string, so it is the contract between producer and consumer. */
-  name: string
-  /** The function to run per job. Its `input` schema is the job payload's schema — a job that does not match is rejected before the body runs. */
-  func: PikkuFunctionConfig
-  /** Concurrency, retry and backoff, passed through to the queue service backing this worker. Defaults come from the service, not from here. */
-  config?: PikkuWorkerConfig
-  /** Names of error classes that mean the job is bad rather than the run — thrown, they fail the job permanently instead of being retried. */
-  errors?: string[]
-  /** Filters this worker in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-  /** Wraps every job. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
-  middleware?: PikkuFunctionConfig['middleware']
-}
-
-export interface PikkuQueue {
-  queueName: string
-  jobId: string
-  pikkuUserId?: string
-  updateProgress: (progress: number | string | object) => Promise<void>
-  /** Never returns — throws QueueJobFailedError. */
-  fail: (reason?: string) => Promise<void>
-  /** Never returns — throws QueueJobDiscardedError. */
-  discard: (reason?: string) => Promise<void>
-}

package/src/wirings/queue/register-queue-helper.ts

@@ -1,46 +0,0 @@
-import type { ConfigValidationResult, CoreQueueWorker } from './queue.types.js'
-import { getQueueWorkers } from './queue-runner.js'
-import type { QueueConfigMapping } from './validate-worker-config.js'
-import { validateWorkerConfig } from './validate-worker-config.js'
-import type { Logger } from '../../services/logger.js'
-
-export type QueueRegistrationCallback<T = any> = (
-  queueName: string,
-  processor: CoreQueueWorker
-) => Promise<T>
-
-export async function registerQueueWorkers<T = any>(
-  configMappings: QueueConfigMapping,
-  logger: Logger,
-  registerCallback: QueueRegistrationCallback<T>
-): Promise<Record<string, ConfigValidationResult[]>> {
-  const configValidation: Record<string, ConfigValidationResult[]> = {}
-  const queueWorkers = getQueueWorkers()
-
-  for (const [queueName, processor] of queueWorkers) {
-    logger?.info(`Registering queue processor: ${queueName}`)
-    const validationResult = validateWorkerConfig(
-      configMappings,
-      processor.config
-    )
-
-    configValidation[queueName] = configValidation[queueName] || []
-    configValidation[queueName].push(validationResult)
-
-    if (validationResult.warnings.length > 0) {
-      logger?.warn(
-        `Configuration warnings for queue ${queueName}:`,
-        validationResult.warnings
-      )
-    }
-
-    try {
-      await registerCallback(queueName, processor)
-      logger?.info(`Successfully registered queue processor: ${queueName}`)
-    } catch (error) {
-      logger?.error(`Failed to register queue processor ${queueName}:`, error)
-    }
-  }
-
-  return configValidation
-}

package/src/wirings/queue/signed-queue-service.ts

@@ -1,60 +0,0 @@
-import type { Safe } from '../../classification/secret-value.js'
-import type { Logger } from '../../services/logger.js'
-import type { SecretService } from '../../services/secret-service.js'
-import {
-  getQueueIdentitySecret,
-  signQueueIdentity,
-  warnQueueIdentitySecretMissing,
-} from './queue-identity.js'
-import type { JobOptions, QueueJob, QueueService } from './queue.types.js'
-
-/**
- * Wraps any {@link QueueService} so `JobOptions.pikkuUserId` leaves the process
- * as a signed claim that `runQueueJob` can verify.
- */
-export class SignedQueueService implements QueueService {
-  constructor(
-    private readonly queueService: QueueService,
-    private readonly secrets: SecretService,
-    private readonly logger: Logger
-  ) {}
-
-  get supportsResults(): boolean {
-    return this.queueService.supportsResults
-  }
-
-  public async add<T>(
-    queueName: string,
-    data: Safe<T>,
-    options?: JobOptions
-  ): Promise<string> {
-    const pikkuUserId = options?.pikkuUserId
-    if (!pikkuUserId) {
-      return this.queueService.add(queueName, data, options)
-    }
-
-    const secret = await getQueueIdentitySecret(this.secrets)
-    if (!secret) {
-      warnQueueIdentitySecretMissing(this.logger)
-      const { pikkuUserId: _unsigned, ...rest } = options as JobOptions
-      return this.queueService.add(queueName, data, rest)
-    }
-
-    const signed = await signQueueIdentity(secret, pikkuUserId, {
-      queueName,
-      jobId: undefined,
-      data,
-    })
-    return this.queueService.add(queueName, data, {
-      ...options,
-      pikkuUserId: signed,
-    })
-  }
-
-  public async getJob<T, R>(
-    queueName: string,
-    jobId: string
-  ): Promise<QueueJob<T, R> | null> {
-    return this.queueService.getJob<T, R>(queueName, jobId)
-  }
-}

package/src/wirings/queue/validate-worker-config.test.ts

@@ -1,108 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import { validateWorkerConfig } from './validate-worker-config.js'
-import type { QueueConfigMapping } from './validate-worker-config.js'
-
-const createTestMapping = (): QueueConfigMapping => ({
-  supported: {
-    concurrency: {
-      queueProperty: 'concurrency',
-      description: 'Number of concurrent workers',
-    },
-    maxRetries: {
-      queueProperty: 'maxRetries',
-      description: 'Maximum retry attempts',
-    },
-  },
-  unsupported: {
-    rateLimitMax: {
-      reason: 'Not supported',
-      explanation: 'This queue does not support rate limiting',
-    },
-  },
-  fallbacks: {
-    retryDelay: {
-      reason: 'Partial support',
-      explanation: 'Uses fixed delay instead of exponential',
-      fallbackValue: '1000ms fixed',
-    },
-  },
-})
-
-describe('validateWorkerConfig', () => {
-  test('should return empty results for empty config', () => {
-    const mapping = createTestMapping()
-    const result = validateWorkerConfig(mapping, {})
-    assert.deepStrictEqual(result.applied, {})
-    assert.deepStrictEqual(result.ignored, {})
-    assert.deepStrictEqual(result.warnings, [])
-    assert.deepStrictEqual(result.fallbacks, {})
-  })
-
-  test('should return empty results for undefined config', () => {
-    const mapping = createTestMapping()
-    const result = validateWorkerConfig(mapping)
-    assert.deepStrictEqual(result.applied, {})
-    assert.deepStrictEqual(result.ignored, {})
-  })
-
-  test('should apply supported configurations', () => {
-    const mapping = createTestMapping()
-    const result = validateWorkerConfig(mapping, { concurrency: 5 } as any)
-    assert.deepStrictEqual(result.applied, { concurrency: 5 })
-    assert.deepStrictEqual(result.ignored, {})
-    assert.strictEqual(result.warnings.length, 0)
-  })
-
-  test('should ignore unsupported configurations with warning', () => {
-    const mapping = createTestMapping()
-    const result = validateWorkerConfig(mapping, { rateLimitMax: 100 } as any)
-    assert.deepStrictEqual(result.ignored, { rateLimitMax: 100 })
-    assert.strictEqual(result.warnings.length, 1)
-    assert.ok(result.warnings[0].includes('Not supported'))
-  })
-
-  test('should handle fallback configurations', () => {
-    const mapping = createTestMapping()
-    const result = validateWorkerConfig(mapping, { retryDelay: 2000 } as any)
-    assert.deepStrictEqual(result.applied, { retryDelay: 2000 })
-    assert.deepStrictEqual(result.fallbacks, { retryDelay: '1000ms fixed' })
-    assert.strictEqual(result.warnings.length, 1)
-    assert.ok(result.warnings[0].includes('Partial support'))
-  })
-
-  test('should warn about unknown configurations', () => {
-    const mapping = createTestMapping()
-    const result = validateWorkerConfig(mapping, {
-      unknownOption: 'val',
-    } as any)
-    assert.deepStrictEqual(result.ignored, { unknownOption: 'val' })
-    assert.strictEqual(result.warnings.length, 1)
-    assert.ok(result.warnings[0].includes('Unknown configuration'))
-  })
-
-  test('should skip undefined values', () => {
-    const mapping = createTestMapping()
-    const result = validateWorkerConfig(mapping, {
-      concurrency: undefined,
-    } as any)
-    assert.deepStrictEqual(result.applied, {})
-  })
-
-  test('should handle mixed supported and unsupported configs', () => {
-    const mapping = createTestMapping()
-    const result = validateWorkerConfig(mapping, {
-      concurrency: 3,
-      maxRetries: 5,
-      rateLimitMax: 100,
-      retryDelay: 1000,
-    } as any)
-    assert.deepStrictEqual(result.applied, {
-      concurrency: 3,
-      maxRetries: 5,
-      retryDelay: 1000,
-    })
-    assert.deepStrictEqual(result.ignored, { rateLimitMax: 100 })
-    assert.strictEqual(result.warnings.length, 2)
-  })
-})

package/src/wirings/queue/validate-worker-config.ts

@@ -1,90 +0,0 @@
-import type {
-  PikkuWorkerConfig,
-  ConfigValidationResult,
-} from './queue.types.js'
-
-export interface QueueConfigMapping {
-  supported: Partial<
-    Record<
-      keyof PikkuWorkerConfig,
-      {
-        queueProperty?: string
-        transform?: (value: any) => any
-        description: string
-      }
-    >
-  >
-
-  /** Rejected: the value is dropped and a warning raised. */
-  unsupported: Partial<
-    Record<
-      keyof PikkuWorkerConfig,
-      {
-        reason: string
-        explanation: string
-      }
-    >
-  >
-
-  /** Applied anyway, but with a warning describing the substituted behaviour. */
-  fallbacks: Partial<
-    Record<
-      keyof PikkuWorkerConfig,
-      {
-        reason: string
-        explanation: string
-        fallbackValue: string
-      }
-    >
-  >
-}
-
-export function validateWorkerConfig(
-  configMapping: QueueConfigMapping,
-  config: PikkuWorkerConfig = {}
-): ConfigValidationResult {
-  const applied: Partial<PikkuWorkerConfig> = {}
-  const ignored: Partial<PikkuWorkerConfig> = {}
-  const warnings: string[] = []
-  const fallbacks: { [key: string]: any } = {}
-
-  for (const [key, value] of Object.entries(config)) {
-    if (value === undefined) continue
-
-    const configKey = key as keyof PikkuWorkerConfig
-
-    if (configKey in configMapping.supported) {
-      applied[configKey] = value
-      continue
-    }
-
-    if (configKey in configMapping.fallbacks) {
-      const fallbackMapping = configMapping.fallbacks[configKey]!
-      applied[configKey] = value
-      fallbacks[key] = fallbackMapping.fallbackValue
-      warnings.push(
-        `${key}: ${fallbackMapping.reason}. ${fallbackMapping.explanation}`
-      )
-      continue
-    }
-
-    if (configKey in configMapping.unsupported) {
-      ignored[configKey] = value
-      const mapping = configMapping.unsupported[configKey]!
-      warnings.push(`${key}: ${mapping.reason}. ${mapping.explanation}`)
-      continue
-    }
-
-    ignored[configKey] = value
-    warnings.push(
-      `${key}: Unknown configuration option for this queue implementation`
-    )
-  }
-
-  return {
-    applied,
-    ignored,
-    warnings,
-    fallbacks,
-  }
-}

package/src/wirings/role/define-system-role.ts

@@ -1,33 +0,0 @@
-import type { CoreSystemRoles } from './role.types.js'
-
-/**
- * No-op function for declaring system roles.
- * This exists purely for TypeScript type checking and will be tree-shaken.
- * The CLI extracts metadata via AST parsing and generates a `SystemRoleName`
- * union, so a persona naming an undeclared role fails the build.
- *
- * A system role is a role that ships with the product: the console may grant
- * it, but cannot rename, re-scope or delete it. Roles an admin composes in the
- * console are unaffected and are not declared here.
- *
- * Removal is deliberately not destructive. Deleting a declaration leaves the
- * row in the store, marked undeclared and inert, until `pikku roles prune` —
- * the same additive contract `defineScope` has, and for the same reason: a
- * mid-deploy revocation is not something a code edit should be able to cause.
- *
- * @example
- * ```typescript
- * defineSystemRole({
- *   buyer: {
- *     displayName: 'Buyer',
- *     description: 'Can browse the catalogue and place orders',
- *     scopes: ['catalogue:read', 'orders:create'],
- *   },
- *   admin: {
- *     description: 'Everything',
- *     scopes: ['admin'],
- *   },
- * })
- * ```
- */
-export const defineSystemRole = (_config: CoreSystemRoles): void => {}

package/src/wirings/role/index.ts

@@ -1,13 +0,0 @@
-export { defineSystemRole } from './define-system-role.js'
-export {
-  flattenSystemRoleDefinitions,
-  validateAndBuildSystemRoleDefinitionsMeta,
-} from './validate-role-definitions.js'
-export type {
-  CoreSystemRole,
-  CoreSystemRoles,
-  SystemRole,
-  SystemRoleDefinitionMeta,
-  SystemRoleDefinitions,
-  SystemRoleDefinitionsMeta,
-} from './role.types.js'