@pikku/core 0.12.71 → 0.12.74

package/src/function/abort-scope.test.ts

@@ -0,0 +1,97 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  AbandonedError,
+  beginChanges,
+  getAbortScope,
+  runInAbortScope,
+  type AbortScope,
+} from './abort-scope.js'
+
+describe('beginChanges', () => {
+  test('is a no-op outside a scope, so a function need not know how it was called', async () => {
+    await beginChanges()
+    assert.equal(getAbortScope(), undefined)
+  })
+
+  test('lets the mutation proceed while the caller is still there', async () => {
+    let declared = false
+    const scope: AbortScope = {
+      abandoned: false,
+      onBeginChanges: () => {
+        declared = true
+      },
+    }
+
+    let mutated = false
+    await runInAbortScope(scope, async () => {
+      await beginChanges()
+      mutated = true
+    })
+
+    assert.equal(mutated, true)
+    assert.equal(declared, true)
+  })
+
+  test('stops the mutation when the caller has gone, and reports why', async () => {
+    let mutated = false
+    const scope: AbortScope = { abandoned: true, reason: 'speech' }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          await beginChanges()
+          mutated = true
+        }),
+      (error: unknown) => {
+        assert.ok(error instanceof AbandonedError)
+        assert.match(error.message, /speech/)
+        return true
+      }
+    )
+
+    // The whole point: the irreversible line never ran.
+    assert.equal(mutated, false)
+  })
+
+  test('survives the await boundaries a real function has', async () => {
+    // AsyncLocalStorage is the reason this works — the checkpoint is usually
+    // several awaits deep inside helpers that never took the scope as an
+    // argument.
+    const scope: AbortScope = { abandoned: true }
+    const nestedHelper = async () => {
+      await new Promise((resolve) => setImmediate(resolve))
+      await beginChanges()
+    }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          await new Promise((resolve) => setImmediate(resolve))
+          return nestedHelper()
+        }),
+      AbandonedError
+    )
+  })
+
+  test('reads the scope live, so an interrupt mid-function is still caught', async () => {
+    let aborted = false
+    const scope: AbortScope = {
+      get abandoned() {
+        return aborted
+      },
+    }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          // Plenty of interruptible work happens before the checkpoint.
+          await new Promise((resolve) => setImmediate(resolve))
+          aborted = true
+          await beginChanges()
+        }),
+      AbandonedError
+    )
+  })
+})

package/src/function/abort-scope.ts

@@ -0,0 +1,80 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/**
+ * Raised by {@link beginChanges} when the caller has gone away before anything
+ * was changed. Distinct from a failure: nothing happened, so there is nothing
+ * to report, retry or apologise for.
+ */
+export class AbandonedError extends Error {
+  constructor(reason?: string) {
+    super(
+      reason
+        ? `Aborted before making changes: ${reason}`
+        : 'Aborted before making changes'
+    )
+    this.name = 'AbandonedError'
+  }
+}
+
+export interface AbortScope {
+  /** Whether whatever asked for this work has gone away. */
+  readonly abandoned: boolean
+  /** Why, when known — an interrupt reason, a disconnect, a cancellation. */
+  readonly reason?: string
+  /** Called by `beginChanges()` once a function commits to mutating. */
+  onBeginChanges?: () => void
+}
+
+/**
+ * The ambient "is my caller still there?" signal.
+ *
+ * Ambient rather than a parameter because the question is the same one for
+ * every wiring — an agent run that was interrupted, an HTTP request whose
+ * client disconnected, a cancelled workflow — and threading it through every
+ * signature would mean changing every function that merely sits between the
+ * wiring and the mutation.
+ */
+const scopeStorage = new AsyncLocalStorage<AbortScope>()
+
+/** Run `fn` with an abort scope that `beginChanges()` will observe. */
+export const runInAbortScope = <T>(scope: AbortScope, fn: () => T): T =>
+  scopeStorage.run(scope, fn)
+
+/** The current scope, if the caller is running inside one. */
+export const getAbortScope = (): AbortScope | undefined =>
+  scopeStorage.getStore()
+
+/**
+ * Declare that everything after this line changes something.
+ *
+ * ```ts
+ * const plan = await computePlan(input)   // interruptible, costs nothing to redo
+ * await beginChanges()
+ * await db.deleteProject(input.projectId) // past the point of no return
+ * ```
+ *
+ * Two things happen here. If the caller has already gone away it throws, so the
+ * mutation never runs and the interrupt is clean — nothing happened, and the
+ * user is told nothing because there is nothing to tell. If the caller is still
+ * there it marks this call as mutating, so an interrupt landing *after* this
+ * point produces an `undelivered` note on the thread rather than silently
+ * discarding work that did happen.
+ *
+ * It throws rather than returning a boolean on purpose: `if (await ...)` invites
+ * ignoring the answer, and the failure mode of ignoring it is a mutation nobody
+ * asked for.
+ *
+ * Entirely cooperative, and safe to call anywhere — outside a scope it is a
+ * no-op, so a function does not need to know how it was invoked. A function
+ * that never calls it keeps the conservative default: if it is not marked
+ * `readonly`, an interrupt assumes it changed something and says so. The tool
+ * that forgot to call this is exactly the one that cannot be assumed harmless.
+ */
+export const beginChanges = async (): Promise<void> => {
+  const scope = scopeStorage.getStore()
+  if (!scope) return
+  if (scope.abandoned) {
+    throw new AbandonedError(scope.reason)
+  }
+  scope.onBeginChanges?.()
+}

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

@@ -7,6 +7,7 @@ import {
   runPikkuFunc,
 } from './function-runner.js'
 import { addGlobalPermission, addTagMiddleware } from '../index.js'
+import { addSchema } from '../schema.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
 import type { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
 import type { CorePermissionGroup } from './functions.types.js'
@@ -18,7 +19,6 @@ beforeEach(() => {
   resetPikkuState()
 })
 
-// Helper function to add function with metadata for tests
 const addTestFunction = (funcName: string, funcConfig: any) => {
   addFunction(funcName, funcConfig)
   // Convert tags to middleware metadata (tags are organizational only; they no
@@ -61,7 +61,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     addTagMiddleware('wiringTag', [createMiddleware('wiringTag')])
     addTagMiddleware('funcTag', [createMiddleware('funcTag')])
 
-    // Register function with middleware and tags
     addTestFunction('testFunc', {
       func: async () => {
         executionOrder.push('main')
@@ -234,7 +233,6 @@ describe('runPikkuFunc - Integration Tests', () => {
       await next()
     }
 
-    // Add same middleware to tag and directly
     addTagMiddleware('testTag', [duplicatedMiddleware])
 
     addTestFunction('testFunc', {
@@ -251,7 +249,6 @@ describe('runPikkuFunc - Integration Tests', () => {
       wire: {},
     })
 
-    // Should only execute once due to deduplication
     assert.equal(executionCount, 1)
   })
 
@@ -401,7 +398,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Permissions run after middleware (middleware can set/modify session)
     assert.deepEqual(executionOrder, [
       'funcMiddleware',
       'funcPermission',
@@ -434,7 +430,6 @@ describe('runPikkuFunc - Integration Tests', () => {
 
     assert.deepEqual(receivedServices, mockServices)
     assert.equal(receivedData, testData)
-    // Check that wire has rpc service and session
     assert.ok(receivedWire.rpc)
     assert.equal(receivedWire.session, undefined)
   })
@@ -451,7 +446,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     })
 
     const asyncCreateWireServices = async () => {
-      // Simulate async service creation
       await new Promise((resolve) => setTimeout(resolve, 1))
       return wireServices
     }
@@ -1494,4 +1488,78 @@ describe('runPikkuFunc - scopes', () => {
       MissingScopeError
     )
   })
+
+  describe('schema defaults', () => {
+    const addPagedFunction = (funcName: string, seen: { data?: any }) => {
+      addSchema('PagedInput', {
+        properties: {
+          page: { type: 'number', default: 1 },
+          limit: { type: 'number', default: 50 },
+        },
+      })
+      addTestFunction(funcName, {
+        func: async (_services: any, data: any) => {
+          seen.data = data
+          return 'ok'
+        },
+      })
+      pikkuState(null, 'function', 'meta')[funcName]!.inputSchemaName =
+        'PagedInput'
+    }
+
+    // The whole point of the fix: `{}` validates because a defaulted property
+    // is not `required`, so without this the body reads `undefined` for a value
+    // its generated type declares as a number.
+    test('a function called with {} receives its schema defaults', async () => {
+      const seen: { data?: any } = {}
+      addPagedFunction('paged', seen)
+
+      await runPikkuFunc('rpc', Math.random().toString(), 'paged', {
+        singletonServices: mockSingletonServices,
+        getAllServices: () => mockServices,
+        data: () => ({}),
+        auth: false,
+        wire: {},
+      })
+
+      assert.equal(seen.data.page, 1)
+      assert.equal(seen.data.limit, 50)
+    })
+
+    // `coerceDataFromSchema` is not passed here, exactly as a direct RPC
+    // invocation leaves it. Defaults belong to the schema rather than to the
+    // transport, so they must not ride on that flag — and a call made with no
+    // arguments at all still has to get them.
+    test('defaults apply with coercion off and no data', async () => {
+      const seen: { data?: any } = {}
+      addPagedFunction('pagedNoCoerce', seen)
+
+      await runPikkuFunc('rpc', Math.random().toString(), 'pagedNoCoerce', {
+        singletonServices: mockSingletonServices,
+        getAllServices: () => mockServices,
+        data: () => undefined,
+        auth: false,
+        wire: {},
+      })
+
+      assert.equal(seen.data.page, 1)
+      assert.equal(seen.data.limit, 50)
+    })
+
+    test('a supplied value survives', async () => {
+      const seen: { data?: any } = {}
+      addPagedFunction('pagedSupplied', seen)
+
+      await runPikkuFunc('rpc', Math.random().toString(), 'pagedSupplied', {
+        singletonServices: mockSingletonServices,
+        getAllServices: () => mockServices,
+        data: () => ({ page: 3 }),
+        auth: false,
+        wire: {},
+      })
+
+      assert.equal(seen.data.page, 3)
+      assert.equal(seen.data.limit, 50)
+    })
+  })
 })

package/src/function/function-runner.ts

@@ -1,11 +1,17 @@
+import { beginChanges } from './abort-scope.js'
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js'
 import {
   combineChannelMiddleware,
   wrapChannelWithMiddleware,
 } from '../wirings/channel/channel-middleware-runner.js'
 import { runPermissions } from '../permissions.js'
+import { withoutSecrets } from '../services/secretless.js'
 import { pikkuState } from '../pikku-state.js'
-import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
+import {
+  applyDefaultsFromSchema,
+  coerceTopLevelDataFromSchema,
+  validateSchema,
+} from '../schema.js'
 import type {
   CoreUserSession,
   CorePikkuMiddleware,
@@ -35,6 +41,11 @@ import {
 } from '../services/audit-service.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { getOrCreatePackageSingletonServices } from '../wirings/rpc/addon-runner.js'
+import {
+  resolveAddonAuth,
+  resolveAddonScopes,
+  resolveAddonTagMiddleware,
+} from '../wirings/rpc/wire-addon.js'
 import type { AddonInstance } from '../wirings/rpc/addon-runner.js'
 import { closeWireServices } from '../utils.js'
 
@@ -166,7 +177,8 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   const resolvedFunctionId = funcMeta.pikkuFuncId ?? funcName
 
-  // For addon packages, get or create their singleton services
+  const keepsSecrets = funcMeta.secretBroker === true
+
   const resolvedSingletonServices = packageName
     ? await getOrCreatePackageSingletonServices(
         packageName,
@@ -175,7 +187,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
       )
     : singletonServices
 
-  // Get the package's createWireServices if available
   let resolvedCreateWireServices = createWireServices
   if (packageName) {
     const factories = pikkuState(packageName, 'package', 'factories')
@@ -199,11 +210,9 @@ export const runPikkuFunc = async <In = any, Out = any>(
         )
       : wire
 
-  // Set up credential wire service early so middleware can use setCredential.
-  // An addon instance with credentialOverrides always gets a fresh alias-aware
-  // service so its logical credential names resolve to instance-specific ones,
-  // even when a parent credential service is already present on the wire.
-  // Otherwise skip if already set up (e.g. addon functions reuse the parent wire).
+  // Set up early so middleware can use setCredential. An addon instance with
+  // credentialOverrides always gets a fresh alias-aware service, even when a
+  // parent credential service is already present on the wire.
   if (addonInstance?.credentialOverrides) {
     // Credentials belong to the consuming project, so resolve them via the
     // project's credentialService (the addon's own singletons may not carry it).
@@ -247,7 +256,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
     invocationWire.addonNamespace = addonInstance.namespace
   }
 
-  // Helper function to run permissions and execute the function
   const executeFunction = async () => {
     await resolveSession(
       invocationWire,
@@ -266,7 +274,11 @@ export const runPikkuFunc = async <In = any, Out = any>(
     const session = invocationWire.session
 
     if (funcMeta.sessionless) {
-      if (wiringAuth === true || funcConfig.auth === true) {
+      if (
+        wiringAuth === true ||
+        funcConfig.auth === true ||
+        resolveAddonAuth(packageName, addonInstance?.namespace)
+      ) {
         if (!session) {
           throw new ForbiddenError('Authentication required')
         }
@@ -286,23 +298,38 @@ export const runPikkuFunc = async <In = any, Out = any>(
       throw new ReadonlySessionError()
     }
 
-    // Scopes gate before the data is evaluated: they depend only on the
-    // session, so a denied request never pays to parse or validate its body.
-    // Scopes are an AND gate and stay separate from runPermissions, which
-    // evaluates the function's own OR-groups against request data.
-    verifyScopes(funcConfig.scopes ?? funcMeta.scopes, session)
+    // Only mutating functions get a checkpoint. A read has nothing to declare,
+    // and offering it there would invite the contradiction of a `readonly`
+    // function announcing where its changes begin.
+    if (!funcMeta.readonly) {
+      invocationWire.beginChanges = beginChanges
+    }
+
+    // knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+    const addonScopes = resolveAddonScopes(
+      packageName,
+      addonInstance?.namespace
+    )
+    const functionScopes = funcConfig.scopes ?? funcMeta.scopes
+    verifyScopes(
+      addonScopes.length > 0
+        ? [...addonScopes, ...(functionScopes ?? [])]
+        : functionScopes,
+      session
+    )
 
-    // Evaluate the data from the lazy function
-    const actualData = await data()
+    let actualData = await data()
 
-    // Validate and coerce data if schema is defined
     const inputSchemaName = funcMeta.inputSchemaName
     if (inputSchemaName) {
-      // Coerce (top level) data types before validation (e.g. string→array, string→date)
+      actualData = applyDefaultsFromSchema(
+        inputSchemaName,
+        actualData,
+        packageName
+      )
       if (coerceDataFromSchema) {
         coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
       }
-      // Validate request data against the defined schema, if any
       await validateSchema(
         resolvedSingletonServices.logger,
         resolvedSingletonServices.schema,
@@ -314,7 +341,12 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
     await runPermissions({
       funcPermissions: funcConfig.permissions,
-      services: resolvedSingletonServices,
+      services: keepsSecrets
+        ? resolvedSingletonServices
+        : (withoutSecrets(
+            resolvedSingletonServices,
+            'a permission'
+          ) as CoreSingletonServices),
       wire: invocationWire as any,
       data: actualData,
       packageName,
@@ -331,13 +363,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         wireServices && Object.keys(wireServices).length > 0
           ? { ...resolvedSingletonServices, ...wireServices }
           : resolvedSingletonServices
-      // The audit gate is per-function, but the auditLog wire service is
-      // created per-transport-invocation — a nested/exposed-RPC call would
-      // otherwise inherit an auditLog constructed while the OUTER wire's
-      // audit was unset (e.g. the generated rpcCaller has no audit config),
-      // silently dropping every write. Re-gate here: if this function
-      // declares audit and the inherited auditLog wasn't built for this
-      // invocation (config identity check), bind a fresh one to this wire.
+      // knowledge: decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md
       if (
         resolvedAuditConfig &&
         resolvedSingletonServices.audit &&
@@ -370,7 +396,11 @@ export const runPikkuFunc = async <In = any, Out = any>(
         configurable: true,
         enumerable: true,
       })
-      return await funcConfig.func(services, actualData, invocationWire)
+      return await funcConfig.func(
+        keepsSecrets ? services : withoutSecrets(services, 'a pikku function'),
+        actualData,
+        invocationWire
+      )
     } finally {
       // Flush the runner-installed audit buffer before wire services close.
       await invocationAuditLog?.close()
@@ -380,9 +410,17 @@ export const runPikkuFunc = async <In = any, Out = any>(
     }
   }
 
+  const addonTagMiddleware = resolveAddonTagMiddleware(
+    packageName,
+    addonInstance?.namespace
+  )
+
   const allMiddleware = combineMiddleware(wireType, wireId, {
     wireInheritedMiddleware: inheritedMiddleware,
-    wireMiddleware,
+    wireMiddleware:
+      addonTagMiddleware.length > 0
+        ? [...addonTagMiddleware, ...(wireMiddleware ?? [])]
+        : wireMiddleware,
     funcInheritedMiddleware: funcMeta.middleware,
     funcMiddleware: funcConfig.middleware,
     packageName,
@@ -434,5 +472,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
     } else {
       invocationWire.audit = previousAudit
     }
+    if (previousAddonNamespace === undefined) {
+      delete (invocationWire as any).addonNamespace
+    } else {
+      invocationWire.addonNamespace = previousAddonNamespace
+    }
   }
 }