@pikku/core 0.12.0 → 0.12.1

package/src/function/function-runner.test.ts

@@ -3,8 +3,8 @@ import * as assert from 'node:assert'
 import { addFunction, runPikkuFunc } from './function-runner.js'
 import { addMiddleware, addPermission } from '../index.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
-import { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
-import { CorePermissionGroup } from './functions.types.js'
+import type { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
+import type { CorePermissionGroup } from './functions.types.js'
 
 beforeEach(() => {
   resetPikkuState()

package/src/function/function-runner.ts

@@ -6,7 +6,7 @@ import {
 import { runPermissions } from '../permissions.js'
 import { pikkuState } from '../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
-import {
+import type {
   CoreServices,
   CoreUserSession,
   CorePikkuMiddleware,
@@ -19,25 +19,23 @@ import {
   CoreConfig,
 } from '../types/core.types.js'
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
-import {
+import type {
   CorePermissionGroup,
   CorePikkuFunctionConfig,
   CorePikkuPermission,
 } from './functions.types.js'
 import { parseVersionedId } from '../version.js'
-import {
-  SessionService,
-  createFunctionSessionWireProps,
-} from '../services/user-session-service.js'
-import { ForbiddenError } from '../errors/errors.js'
+import type { SessionService } from '../services/user-session-service.js'
+import { createFunctionSessionWireProps } from '../services/user-session-service.js'
+import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
 /**
- * Get or create singleton services for an external package.
+ * Get or create singleton services for an addon package.
  * Services are cached in pikkuState to avoid recreation on each call.
  *
- * @param packageName - The external package name
+ * @param packageName - The addon package name
  * @param parentServices - The parent/caller's singleton services (used as base)
  * @returns The package's singleton services
  */
@@ -97,8 +95,8 @@ export const getAllFunctionNames = (): string[] => {
   const mainFunctionsMeta = pikkuState(null, 'function', 'meta')
   functions.push(...Object.keys(mainFunctionsMeta))
 
-  const externalPackages = pikkuState(null, 'rpc', 'externalPackages')
-  for (const [namespace, config] of externalPackages) {
+  const addons = pikkuState(null, 'rpc', 'addons')
+  for (const [namespace, config] of addons) {
     const packageFunctionsMeta = pikkuState(config.package, 'function', 'meta')
     for (const funcName of Object.keys(packageFunctionsMeta)) {
       functions.push(`${namespace}:${funcName}`)
@@ -167,11 +165,8 @@ export const runPikkuFunc = async <In = any, Out = any>(
     packageName?: string | null
   }
 ): Promise<Out> => {
-  wire = {
-    ...wire,
-    wireType: wire.wireType ?? wireType,
-    wireId: wire.wireId ?? wireId,
-  }
+  wire.wireType ??= wireType
+  wire.wireId ??= wireId
 
   const funcMap = pikkuState(packageName, 'function', 'functions')
   let funcConfig = funcMap.get(funcName)
@@ -198,7 +193,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     throw new Error(`Function meta not found: ${funcName}`)
   }
 
-  // For external packages, get or create their singleton services
+  // For addon packages, get or create their singleton services
   const resolvedSingletonServices = packageName
     ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
     : singletonServices
@@ -228,23 +223,27 @@ export const runPikkuFunc = async <In = any, Out = any>(
       : wire
 
   // Convert tags to PermissionMetadata and merge with inheritedPermissions
-  const mergedInheritedPermissions: PermissionMetadata[] = [
-    ...(inheritedPermissions || []),
-    ...(tags?.map((tag) => ({ type: 'tag' as const, tag })) || []),
-  ]
+  let mergedInheritedPermissions: PermissionMetadata[]
+  if (tags && tags.length > 0) {
+    mergedInheritedPermissions = [
+      ...(inheritedPermissions || []),
+      ...tags.map((tag) => ({ type: 'tag' as const, tag })),
+    ]
+  } else {
+    mergedInheritedPermissions = inheritedPermissions || []
+  }
 
   // Helper function to run permissions and execute the function
   const executeFunction = async () => {
-    const functionWireProps = sessionService
-      ? createFunctionSessionWireProps(sessionService)
-      : undefined
-
-    const wireWithSession: PikkuWire = {
-      ...resolvedWire,
-      ...functionWireProps,
+    if (sessionService) {
+      resolvedWire.session = sessionService.freezeInitial()
+      resolvedWire.setSession = (s: any) => sessionService.set(s)
+      resolvedWire.clearSession = () => sessionService.clear()
+      resolvedWire.getSession = () => sessionService.get()
+      resolvedWire.hasSessionChanged = () => sessionService.sessionChanged
     }
 
-    const session = wireWithSession.session
+    const session = resolvedWire.session
 
     if (funcMeta.sessionless) {
       if (wiringAuth === true || funcConfig.auth === true) {
@@ -257,7 +256,8 @@ export const runPikkuFunc = async <In = any, Out = any>(
         resolvedSingletonServices.logger.warn(
           `Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`
         )
-      } else if (!session) {
+      }
+      if (!session) {
         throw new ForbiddenError('Authentication required')
       }
     } else {
@@ -270,6 +270,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
       }
     }
 
+    if ((session as any)?.readonly && !funcMeta.readonly) {
+      throw new ReadonlySessionError()
+    }
+
     // Evaluate the data from the lazy function
     const actualData = await data()
 
@@ -290,32 +294,51 @@ export const runPikkuFunc = async <In = any, Out = any>(
       }
     }
 
-    await runPermissions(wireType, wireId, {
-      wireInheritedPermissions: mergedInheritedPermissions,
-      wirePermissions: wirePermissions,
-      funcInheritedPermissions: funcMeta.permissions,
-      funcPermissions: funcConfig.permissions,
-      services: resolvedSingletonServices,
-      wire: { ...wireWithSession, rpc: undefined } as any,
-      data: actualData,
-      packageName,
-    })
+    if (
+      mergedInheritedPermissions.length > 0 ||
+      wirePermissions ||
+      funcMeta.permissions ||
+      funcConfig.permissions
+    ) {
+      await runPermissions(wireType, wireId, {
+        wireInheritedPermissions: mergedInheritedPermissions,
+        wirePermissions: wirePermissions,
+        funcInheritedPermissions: funcMeta.permissions,
+        funcPermissions: funcConfig.permissions,
+        services: resolvedSingletonServices,
+        wire: resolvedWire as any,
+        data: actualData,
+        packageName,
+      })
+    }
 
     const wireServices = await resolvedCreateWireServices?.(
       resolvedSingletonServices,
-      wireWithSession
+      resolvedWire
     )
     try {
-      const services = { ...resolvedSingletonServices, ...wireServices }
-      const rpc = rpcService.getContextRPCService(services, wireWithSession, {
-        sessionService,
-      })
-      return await funcConfig.func(services, actualData, {
-        ...wireWithSession,
-        rpc,
+      const services =
+        wireServices && Object.keys(wireServices).length > 0
+          ? { ...resolvedSingletonServices, ...wireServices }
+          : resolvedSingletonServices
+      Object.defineProperty(resolvedWire, 'rpc', {
+        get() {
+          const rpc = rpcService.getContextRPCService(services, resolvedWire, {
+            sessionService,
+          })
+          Object.defineProperty(resolvedWire, 'rpc', {
+            value: rpc,
+            writable: true,
+            configurable: true,
+          })
+          return rpc
+        },
+        configurable: true,
+        enumerable: true,
       })
+      return await funcConfig.func(services, actualData, resolvedWire)
     } finally {
-      if (wireServices) {
+      if (wireServices && Object.keys(wireServices).length > 0) {
         await closeWireServices(resolvedSingletonServices.logger, wireServices)
       }
     }

package/src/function/functions.types.ts

@@ -255,6 +255,7 @@ export type CorePikkuFunctionConfig<
   expose?: boolean
   remote?: boolean
   mcp?: boolean
+  readonly?: boolean
   requiresApproval?: boolean
   func: PikkuFunction
   auth?: boolean

package/src/handle-error.test.ts

@@ -0,0 +1,361 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { handleHTTPError } from './handle-error.js'
+import { addError } from './errors/error-handler.js'
+import {
+  NotFoundError,
+  BadRequestError,
+  ForbiddenError,
+} from './errors/errors.js'
+import { resetPikkuState } from './pikku-state.js'
+
+const createMockLogger = () => {
+  const logs: { level: string; args: any[] }[] = []
+  return {
+    info: (...args: any[]) => logs.push({ level: 'info', args }),
+    warn: (...args: any[]) => logs.push({ level: 'warn', args }),
+    error: (...args: any[]) => logs.push({ level: 'error', args }),
+    debug: (...args: any[]) => logs.push({ level: 'debug', args }),
+    _logs: logs,
+  }
+}
+
+const createMockHTTP = () => {
+  const state = {
+    statusCode: undefined as number | undefined,
+    jsonBody: undefined as any,
+    closed: false,
+  }
+  return {
+    request: {},
+    response: {
+      status: (code: number) => {
+        state.statusCode = code
+        return {
+          json: (body: any) => {
+            state.jsonBody = body
+          },
+        }
+      },
+      json: (body: any) => {
+        state.jsonBody = body
+      },
+      close: () => {
+        state.closed = true
+      },
+    },
+    _state: state,
+  }
+}
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+describe('handleHTTPError', () => {
+  test('should skip NotFoundError when respondWith404 is false', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new NotFoundError()
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-1',
+      logger as any,
+      [],
+      false,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, undefined)
+    assert.strictEqual(http._state.jsonBody, undefined)
+  })
+
+  test('should handle NotFoundError when respondWith404 is true', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new NotFoundError()
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-1',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 404)
+    assert.deepStrictEqual(http._state.jsonBody, {
+      message: 'The server cannot find the requested resource.',
+      payload: undefined,
+      traceId: 'tracker-1',
+    })
+  })
+
+  test('should set correct status and message for known errors', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('Invalid input')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-2',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 400)
+    assert.ok(http._state.jsonBody.message.includes('client error'))
+    assert.strictEqual(http._state.jsonBody.traceId, 'tracker-2')
+  })
+
+  test('should set status 403 for ForbiddenError', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new ForbiddenError()
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-3',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 403)
+  })
+
+  test('should log warning when status code is in logWarningsForStatusCodes', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-4',
+      logger as any,
+      [400],
+      true,
+      false
+    )
+
+    const warns = logger._logs.filter((l) => l.level === 'warn')
+    assert.ok(warns.length >= 1)
+    assert.ok(warns.some((w) => w.args[0].includes('tracker-4')))
+  })
+
+  test('should not log warning when status code is not in logWarningsForStatusCodes', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-5',
+      logger as any,
+      [500],
+      true,
+      false
+    )
+
+    const warns = logger._logs.filter((l) => l.level === 'warn')
+    assert.strictEqual(warns.length, 0)
+  })
+
+  test('should handle unknown errors with 500 status', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new Error('something unexpected')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-6',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.deepStrictEqual(http._state.jsonBody, { errorId: 'tracker-6' })
+  })
+
+  test('should log unknown errors with error level', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new Error('unexpected')
+
+    handleHTTPError(
+      error,
+      http as any,
+      undefined,
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    const errors = logger._logs.filter((l) => l.level === 'error')
+    assert.ok(errors.length >= 1)
+    assert.ok(errors.some((e) => e.args[0] === 'unexpected'))
+  })
+
+  test('should not include errorId in response when trackerId is undefined for unknown errors', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new Error('unexpected')
+
+    handleHTTPError(
+      error,
+      http as any,
+      undefined,
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.strictEqual(http._state.jsonBody, undefined)
+  })
+
+  test('should bubble error when bubbleError is true', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    assert.throws(
+      () =>
+        handleHTTPError(
+          error,
+          http as any,
+          'tracker',
+          logger as any,
+          [],
+          true,
+          true
+        ),
+      (e: any) => e === error
+    )
+  })
+
+  test('should not bubble error when bubbleError is false', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker',
+      logger as any,
+      [],
+      true,
+      false
+    )
+    // Should not throw
+  })
+
+  test('should call response.close when available', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.closed, true)
+  })
+
+  test('should handle undefined http gracefully', () => {
+    const logger = createMockLogger()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(error, undefined, 'tracker', logger as any, [], true, false)
+    // Should not throw
+  })
+
+  test('should include payload from error in known error response', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad') as any
+    error.payload = { field: 'email', reason: 'invalid' }
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.deepStrictEqual(http._state.jsonBody.payload, {
+      field: 'email',
+      reason: 'invalid',
+    })
+  })
+
+  test('should handle non-Error objects as errors', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = 'just a string error'
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    const errors = logger._logs.filter((l) => l.level === 'error')
+    assert.ok(errors.some((e) => e.args[0] === 'just a string error'))
+  })
+
+  test('should handle warning log without trackerId', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new BadRequestError('bad')
+
+    handleHTTPError(
+      error,
+      http as any,
+      undefined,
+      logger as any,
+      [400],
+      true,
+      false
+    )
+
+    const warns = logger._logs.filter((l) => l.level === 'warn')
+    assert.ok(warns.length >= 1)
+    assert.ok(
+      !warns.some(
+        (w) => typeof w.args[0] === 'string' && w.args[0].includes('Warning id')
+      )
+    )
+  })
+})

package/src/handle-error.ts

@@ -1,7 +1,7 @@
 import { getErrorResponse } from './errors/error-handler.js'
 import { NotFoundError } from './errors/errors.js'
-import { Logger } from './services/logger.js'
-import { PikkuHTTP } from './wirings/http/http.types.js'
+import type { Logger } from './services/logger.js'
+import type { PikkuHTTP } from './wirings/http/http.types.js'
 
 /**
  * Handle errors that occur during route processing
@@ -44,11 +44,11 @@ export const handleHTTPError = (
       if (trackerId) {
         logger.warn(`Warning id: ${trackerId}`)
       }
-      logger.warn(e)
+      logger.warn(e instanceof Error ? e.message : e)
     }
   } else {
     // Handle unexpected errors
-    logger.error(e)
+    logger.error(e instanceof Error ? e.message : e)
     http?.response?.status(500)
 
     if (trackerId) {

package/src/index.ts

@@ -12,8 +12,6 @@ export type {
   CoreSingletonServices,
   CoreUserSession,
   CreateConfig,
-  CreateSingletonServices,
-  CreateWireServices,
   FunctionMeta,
   FunctionRuntimeMeta,
   FunctionServicesMeta,
@@ -69,13 +67,6 @@ export {
   isVersionedId,
   parseVersionedId,
 } from './version.js'
-export {
-  pikkuState,
-  initializePikkuState,
-  resetPikkuState,
-  addPackageServiceFactories,
-  getPikkuMetaDir,
-} from './pikku-state.js'
 export { runPikkuFunc } from './function/function-runner.js'
 export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js'
 export { fetch } from './wirings/http/http-runner.js'
@@ -99,13 +90,15 @@ export type { HTTPMethod } from './wirings/http/http.types.js'
 export type { GraphNodeConfig } from './wirings/workflow/graph/workflow-graph.types.js'
 export { createGraph } from './wirings/workflow/graph/graph-node.js'
 export { workflow as wireWorkflow } from './wirings/workflow/workflow-helpers.js'
+export { wireAddon } from './wirings/rpc/wire-addon.js'
+export type { WireAddonConfig } from './wirings/rpc/wire-addon.js'
 export type { PikkuPackageState } from './types/state.types.js'
 export { runMiddleware, addMiddleware } from './middleware-runner.js'
 export { addPermission } from './permissions.js'
 export { isSerializable, stopSingletonServices } from './utils.js'
+export { getSingletonServices, getCreateWireServices } from './pikku-state.js'
 export {
   type ScheduledTaskInfo,
   type ScheduledTaskSummary,
-  type SchedulerRuntimeHandlers,
 } from './services/scheduler-service.js'
 export { SchedulerService } from './services/scheduler-service.js'

package/src/internal.ts

@@ -0,0 +1,6 @@
+export { pikkuState, resetPikkuState } from './pikku-state.js'
+export { httpRouter } from './wirings/http/routers/http-router.js'
+export type {
+  CreateSingletonServices,
+  CreateWireServices,
+} from './types/core.types.js'

package/src/middleware/auth-apikey.test.ts

@@ -2,7 +2,7 @@ import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 import { authAPIKey } from './auth-apikey.js'
 import { resetPikkuState } from '../pikku-state.js'
-import { CoreUserSession } from '../types/core.types.js'
+import type { CoreUserSession } from '../types/core.types.js'
 import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,

package/src/middleware/auth-bearer.test.ts

@@ -2,7 +2,7 @@ import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 import { authBearer } from './auth-bearer.js'
 import { resetPikkuState } from '../pikku-state.js'
-import { CoreUserSession } from '../types/core.types.js'
+import type { CoreUserSession } from '../types/core.types.js'
 import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,

package/src/middleware/auth-bearer.ts

@@ -1,9 +1,6 @@
 import { InvalidSessionError } from '../errors/errors.js'
-import {
-  CoreUserSession,
-  pikkuMiddleware,
-  pikkuMiddlewareFactory,
-} from '../types/core.types.js'
+import type { CoreUserSession } from '../types/core.types.js'
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
 /**
  * Bearer token middleware that extracts and validates tokens from the Authorization header.