@pikku/core 0.11.2 → 0.12.1

package/src/factory-functions.test.ts

@@ -1,6 +1,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert'
 import {
+  pikkuAuth,
   pikkuPermission,
   pikkuMiddleware,
   pikkuPermissionFactory,
@@ -21,8 +22,8 @@ test('pikkuMiddleware returns the same function', async () => {
 
 test('pikkuPermissionFactory creates a factory function', async () => {
   const factory = pikkuPermissionFactory<{ role: string }>(({ role }) => {
-    return pikkuPermission(async ({ logger }, data, { initialSession }) => {
-      return (initialSession as any)?.role === role
+    return pikkuPermission(async ({ logger }, data, { session }) => {
+      return (session as any)?.role === role
     })
   })
 
@@ -67,3 +68,42 @@ test('pikkuMiddlewareFactory returns the same factory', async () => {
   const wrappedFactory = pikkuMiddlewareFactory(originalFactory)
   assert.strictEqual(wrappedFactory, originalFactory)
 })
+
+test('pikkuAuth returns a 3-arg wrapper function', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth(authFn)
+  assert.strictEqual(typeof wrapped, 'function')
+  assert.strictEqual(wrapped.length, 3)
+})
+
+test('pikkuAuth wrapper extracts session from wire and calls auth function', async () => {
+  let receivedSession = null
+  const authFn = async (_services, session) => {
+    receivedSession = session
+    return session.role === 'admin'
+  }
+  const wrapped = pikkuAuth(authFn)
+  const result = await wrapped({}, null, { session: { role: 'admin' } })
+  assert.strictEqual(result, true)
+  assert.deepStrictEqual(receivedSession, { role: 'admin' })
+})
+
+test('pikkuAuth wrapper returns false when no session', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth(authFn)
+  const result = await wrapped({}, null, { session: null })
+  assert.strictEqual(result, false)
+})
+
+test('pikkuAuth config object syntax works', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth({
+    func: authFn,
+    name: 'Is Authenticated',
+    description: 'Checks if user has a session',
+  })
+  assert.strictEqual(typeof wrapped, 'function')
+  assert.strictEqual(wrapped.length, 3)
+  const result = await wrapped({}, null, { session: { id: '1' } })
+  assert.strictEqual(result, true)
+})

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()
@@ -22,7 +22,7 @@ const addTestFunction = (funcName: string, funcConfig: any) => {
     ? funcConfig.tags.map((tag: string) => ({ type: 'tag' as const, tag }))
     : undefined
   pikkuState(null, 'function', 'meta')[funcName] = {
-    pikkuFuncName: funcName,
+    pikkuFuncId: funcName,
     inputSchemaName: null,
     outputSchemaName: null,
     middleware,
@@ -152,14 +152,8 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Order: wiringTags → wiringPermissions → funcTags → funcPermissions
-    assert.deepEqual(executionOrder, [
-      'wiringTag',
-      'wiringPermission',
-      'funcTag',
-      'funcPermission',
-      'main',
-    ])
+    // Order: wiringTags → main (short-circuit on first passing group)
+    assert.deepEqual(executionOrder, ['wiringTag', 'main'])
   })
 
   test('should throw specific error for wiring tag permission failures', async () => {
@@ -340,11 +334,10 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Should execute tag permissions first, then function permissions
+    // Should execute tag permissions and short-circuit before function permissions
     assert.deepEqual(executionOrder, [
       'arrayPermission1',
       'arrayPermission2',
-      'objectPermission',
       'main',
     ])
   })

package/src/function/function-runner.ts

@@ -1,8 +1,12 @@
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js'
+import {
+  combineChannelMiddleware,
+  wrapChannelWithMiddleware,
+} from '../wirings/channel/channel-middleware-runner.js'
 import { runPermissions } from '../permissions.js'
 import { pikkuState } from '../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
-import {
+import type {
   CoreServices,
   CoreUserSession,
   CorePikkuMiddleware,
@@ -14,21 +18,24 @@ import {
   CreateWireServices,
   CoreConfig,
 } from '../types/core.types.js'
-import {
+import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
+import type {
   CorePermissionGroup,
   CorePikkuFunctionConfig,
   CorePikkuPermission,
 } from './functions.types.js'
-import { SessionService } from '../services/user-session-service.js'
-import { ForbiddenError } from '../errors/errors.js'
+import { parseVersionedId } from '../version.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
  */
@@ -75,6 +82,30 @@ export const addFunction = (
   pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig)
 }
 
+export const getFunctionNames = (
+  packageName: string | null = null
+): string[] => {
+  const functionsMeta = pikkuState(packageName, 'function', 'meta')
+  return Object.keys(functionsMeta)
+}
+
+export const getAllFunctionNames = (): string[] => {
+  const functions: string[] = []
+
+  const mainFunctionsMeta = pikkuState(null, 'function', 'meta')
+  functions.push(...Object.keys(mainFunctionsMeta))
+
+  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}`)
+    }
+  }
+
+  return functions
+}
+
 export const runPikkuFuncDirectly = async <In, Out>(
   funcName: string,
   allServices: CoreServices,
@@ -89,10 +120,9 @@ export const runPikkuFuncDirectly = async <In, Out>(
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
-  // Inject session into wire
   const wireWithSession = {
     ...wire,
-    session: userSession,
+    ...(userSession && createFunctionSessionWireProps(userSession)),
   }
   return (await funcConfig.func(allServices, data, wireWithSession)) as Out
 }
@@ -108,11 +138,14 @@ export const runPikkuFunc = async <In = any, Out = any>(
     auth: wiringAuth,
     inheritedMiddleware,
     wireMiddleware,
+    inheritedChannelMiddleware,
+    wireChannelMiddleware,
     inheritedPermissions,
     wirePermissions,
     coerceDataFromSchema,
     tags = [],
     wire,
+    sessionService,
     packageName = null,
   }: {
     singletonServices: CoreSingletonServices
@@ -121,27 +154,46 @@ export const runPikkuFunc = async <In = any, Out = any>(
     auth?: boolean
     inheritedMiddleware?: MiddlewareMetadata[]
     wireMiddleware?: CorePikkuMiddleware[]
+    inheritedChannelMiddleware?: MiddlewareMetadata[]
+    wireChannelMiddleware?: CorePikkuChannelMiddleware[]
     inheritedPermissions?: PermissionMetadata[]
     wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
     coerceDataFromSchema?: boolean
     tags?: string[]
     wire: PikkuWire
+    sessionService?: SessionService<CoreUserSession>
     packageName?: string | null
   }
 ): Promise<Out> => {
-  const funcConfig = pikkuState(packageName, 'function', 'functions').get(
-    funcName
-  )
+  wire.wireType ??= wireType
+  wire.wireId ??= wireId
+
+  const funcMap = pikkuState(packageName, 'function', 'functions')
+  let funcConfig = funcMap.get(funcName)
+  const allMeta = pikkuState(packageName, 'function', 'meta')
+  let funcMeta = allMeta[funcName]
+
+  if (!funcConfig || !funcMeta) {
+    const { baseName, version } = parseVersionedId(funcName)
+    if (version !== null) {
+      funcConfig = funcConfig || funcMap.get(baseName)
+      funcMeta = funcMeta || allMeta[baseName]
+      if (funcConfig && funcMeta) {
+        singletonServices.logger.warn(
+          `Version '${funcName}' not registered, resolved to '${baseName}'`
+        )
+      }
+    }
+  }
+
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
-  const allMeta = pikkuState(packageName, 'function', 'meta')
-  const funcMeta = allMeta[funcName]
   if (!funcMeta) {
     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
@@ -155,35 +207,73 @@ export const runPikkuFunc = async <In = any, Out = any>(
     }
   }
 
+  const allChannelMiddleware = combineChannelMiddleware(wireType, wireId, {
+    wireInheritedChannelMiddleware: inheritedChannelMiddleware,
+    wireChannelMiddleware,
+    packageName,
+  })
+
+  const resolvedWire =
+    allChannelMiddleware.length > 0 && wire.channel
+      ? wrapChannelWithMiddleware(
+          wire,
+          resolvedSingletonServices,
+          allChannelMiddleware
+        )
+      : 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 initialSession = wire.session?.freezeInitial()
-
-    const wireWithInitialSession: PikkuWire = {
-      ...wire,
-      initialSession,
+    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
     }
 
-    if (wiringAuth === true || funcConfig.auth === true) {
-      // This means it was explicitly enabled in either wiring or function and has to be respected
-      if (!initialSession) {
+    const session = resolvedWire.session
+
+    if (funcMeta.sessionless) {
+      if (wiringAuth === true || funcConfig.auth === true) {
+        if (!session) {
+          throw new ForbiddenError('Authentication required')
+        }
+      }
+    } else if (funcMeta.sessionless === false) {
+      if (wiringAuth === false || funcConfig.auth === false) {
+        resolvedSingletonServices.logger.warn(
+          `Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`
+        )
+      }
+      if (!session) {
         throw new ForbiddenError('Authentication required')
       }
-    }
-    if (wiringAuth === undefined && funcConfig.auth === undefined) {
-      // We always default to requiring auth unless explicitly disabled
-      if (!initialSession) {
-        // TODO: Critical, we need to figure out how to make this work with different wirings
-        // throw new ForbiddenError('Authentication required')
+    } else {
+      // TODO: Remove after a couple of releases — backward compat for
+      // generated metadata that doesn't include the `sessionless` field yet.
+      if (wiringAuth === true || funcConfig.auth === true) {
+        if (!session) {
+          throw new ForbiddenError('Authentication required')
+        }
       }
     }
 
+    if ((session as any)?.readonly && !funcMeta.readonly) {
+      throw new ReadonlySessionError()
+    }
+
     // Evaluate the data from the lazy function
     const actualData = await data()
 
@@ -204,33 +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: { ...wireWithInitialSession, 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,
-      wireWithInitialSession
+      resolvedWire
     )
     try {
-      const services = { ...resolvedSingletonServices, ...wireServices }
-      const rpc = rpcService.getContextRPCService(
-        services,
-        wireWithInitialSession
-      )
-      return await funcConfig.func(services, actualData, {
-        ...wireWithInitialSession,
-        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)
       }
     }
@@ -247,7 +355,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
   if (allMiddleware.length > 0) {
     return (await runMiddleware<CorePikkuMiddleware>(
       resolvedSingletonServices,
-      wire,
+      resolvedWire,
       allMiddleware,
       executeFunction
     )) as Out