@pikku/core 0.12.106 → 0.12.111

package/src/wirings/channel/channel-middleware-runner.ts

@@ -1,126 +0,0 @@
-import type {
-  CoreSingletonServices,
-  PikkuRawWire,
-} from '../../types/core.types.js'
-import type { MiddlewareMetadata } from '../../middleware/middleware.types.js'
-import type { CorePikkuChannelMiddleware } from './channel.types.js'
-import { pikkuState } from '../../pikku-state.js'
-import { freezeDedupe, getTagGroups } from '../../utils.js'
-
-export const addChannelMiddleware = (
-  tag: string,
-  middleware: CorePikkuChannelMiddleware[],
-  packageName: string | null = null
-): CorePikkuChannelMiddleware[] => {
-  const tagGroups = pikkuState(packageName, 'channelMiddleware', 'tagGroup')
-  tagGroups[tag] = middleware
-  return middleware
-}
-
-const getChannelMiddlewareByName = (
-  name: string
-): CorePikkuChannelMiddleware | undefined => {
-  const store = pikkuState(null, 'misc', 'channelMiddleware')
-  const middleware = store[name]
-  return middleware?.[0]
-}
-
-const channelMiddlewareCache: Record<
-  string,
-  readonly CorePikkuChannelMiddleware[]
-> = {}
-
-export const clearChannelMiddlewareCache = () => {
-  for (const key of Object.keys(channelMiddlewareCache)) {
-    delete channelMiddlewareCache[key]
-  }
-}
-
-export const combineChannelMiddleware = (
-  wireType: string,
-  uid: string,
-  {
-    wireInheritedChannelMiddleware,
-    wireChannelMiddleware,
-    packageName = null,
-  }: {
-    wireInheritedChannelMiddleware?: MiddlewareMetadata[]
-    wireChannelMiddleware?: CorePikkuChannelMiddleware[]
-    packageName?: string | null
-  } = {}
-): readonly CorePikkuChannelMiddleware[] => {
-  const cacheKey = `${wireType}:${uid}`
-  let inherited = channelMiddlewareCache[cacheKey]
-  if (!inherited) {
-    const resolved: CorePikkuChannelMiddleware[] = []
-    if (wireInheritedChannelMiddleware) {
-      for (const meta of wireInheritedChannelMiddleware) {
-        if (meta.type === 'tag') {
-          const groups = getTagGroups(
-            pikkuState(packageName, 'channelMiddleware', 'tagGroup'),
-            meta.tag
-          )
-          for (const group of groups) {
-            resolved.push(...group)
-          }
-        } else if (meta.type === 'wire') {
-          const middleware = getChannelMiddlewareByName(meta.name)
-          if (middleware) {
-            resolved.push(middleware)
-          }
-        }
-      }
-    }
-    inherited = channelMiddlewareCache[cacheKey] = freezeDedupe(
-      resolved
-    ) as readonly CorePikkuChannelMiddleware[]
-  }
-
-  if (!wireChannelMiddleware?.length) {
-    return inherited
-  }
-
-  return freezeDedupe([
-    ...inherited,
-    ...wireChannelMiddleware,
-  ]) as readonly CorePikkuChannelMiddleware[]
-}
-
-export function wrapChannelWithMiddleware<Out>(
-  wire: PikkuRawWire,
-  services: CoreSingletonServices,
-  middlewares: readonly CorePikkuChannelMiddleware[]
-): PikkuRawWire {
-  if (middlewares.length === 0 || !wire.channel) return wire
-
-  const channel = wire.channel
-  const originalSend = channel.send.bind(channel)
-
-  const dispatch = async (index: number, event: Out): Promise<void> => {
-    if (index >= middlewares.length) {
-      await originalSend(event)
-      return
-    }
-
-    const middleware = middlewares[index]!
-    await middleware(services, event, async (result: any) => {
-      if (result === null || result === undefined) return
-      if (Array.isArray(result)) {
-        for (const item of result) {
-          await dispatch(index + 1, item)
-        }
-      } else {
-        await dispatch(index + 1, result)
-      }
-    })
-  }
-
-  return {
-    ...wire,
-    channel: {
-      ...channel,
-      send: ((data: Out) => dispatch(0, data)) as typeof channel.send,
-      sendBinary: channel.sendBinary,
-    },
-  }
-}

package/src/wirings/channel/channel-rpc-registry.ts

@@ -1,116 +0,0 @@
-import {
-  ChannelRPCError,
-  type ChannelRPCResponse,
-} from './channel-rpc.types.js'
-
-interface PendingCall {
-  resolve: (value: unknown) => void
-  reject: (error: Error) => void
-  timer?: ReturnType<typeof setTimeout>
-  awaitingHuman?: boolean
-}
-
-/**
- * Tracks in-flight reverse RPC calls for one channel. One registry per
- * connection: ids are only unique within a socket, and a dropped socket must
- * reject exactly the calls that were riding on it.
- */
-export class ChannelRPCRegistry {
-  private pending = new Map<string, PendingCall>()
-  private nextId = 0
-  private closed = false
-
-  constructor(private readonly timeoutMs: number = 30_000) {}
-
-  public get inFlight(): number {
-    return this.pending.size
-  }
-
-  public register(): { id: string; promise: Promise<unknown> } {
-    if (this.closed) {
-      return {
-        id: '',
-        promise: Promise.reject(
-          new ChannelRPCError('Channel is closed', 'closed')
-        ),
-      }
-    }
-
-    const id = `${++this.nextId}`
-    const promise = new Promise<unknown>((resolve, reject) => {
-      const timer =
-        this.timeoutMs > 0
-          ? setTimeout(() => {
-              this.pending.delete(id)
-              reject(
-                new ChannelRPCError(
-                  `Channel RPC ${id} timed out after ${this.timeoutMs}ms`,
-                  'timeout'
-                )
-              )
-            }, this.timeoutMs)
-          : undefined
-      // Never hold the process open waiting on a peer that may not answer.
-      timer?.unref?.()
-      this.pending.set(id, { resolve, reject, timer })
-    })
-
-    return { id, promise }
-  }
-
-  /**
-   * Stops the clock on a call whose peer is asking a human. The timeout exists
-   * to bound a peer that has gone away, and a person reading a prompt is not
-   * that; `rejectAll` still fails the call the moment the socket drops.
-   *
-   * Returns false for an unknown id — a pending frame for a call that already
-   * timed out is stale, not an error.
-   */
-  public hold(id: string): boolean {
-    const call = this.pending.get(id)
-    if (!call || call.awaitingHuman) {
-      return false
-    }
-    clearTimeout(call.timer)
-    call.timer = undefined
-    call.awaitingHuman = true
-    return true
-  }
-
-  /** Returns false for an unknown id, so a late reply is dropped. */
-  public settle(response: ChannelRPCResponse): boolean {
-    const call = this.pending.get(response.id)
-    if (!call) {
-      return false
-    }
-    this.pending.delete(response.id)
-    clearTimeout(call.timer)
-
-    if (response.ok) {
-      call.resolve(response.result)
-    } else {
-      // Peer input: a non-string name or message falls back rather than being
-      // attached to an Error, where it would surface as `[object Object]`.
-      const { name, message } = response.error ?? {}
-      const error = new ChannelRPCError(
-        typeof message === 'string' ? message : 'Remote channel RPC failed',
-        'remote'
-      )
-      if (typeof name === 'string' && name.length > 0) {
-        error.name = name
-      }
-      call.reject(error)
-    }
-    return true
-  }
-
-  /** Without this a caller awaits the full timeout on a connection that is gone. */
-  public rejectAll(reason: string = 'Channel closed'): void {
-    this.closed = true
-    for (const [, call] of this.pending) {
-      clearTimeout(call.timer)
-      call.reject(new ChannelRPCError(reason, 'closed'))
-    }
-    this.pending.clear()
-  }
-}

package/src/wirings/channel/channel-rpc-responder.ts

@@ -1,117 +0,0 @@
-import {
-  CHANNEL_RPC_PENDING,
-  CHANNEL_RPC_RESPONSE,
-  isCapabilityDef,
-  isChannelRPCRequest,
-  resolveCapability,
-  type ApprovalRequester,
-  type Capabilities,
-  type ChannelRPCPending,
-  type ChannelRPCResponse,
-} from './channel-rpc.types.js'
-
-/**
- * Answers reverse RPC requests arriving on a channel.
- *
- * `capabilities` is the authorisation boundary, not a convenience: the peer is
- * asking this process to execute code, so only listed names run. An absent
- * name is refused exactly like an unknown one, so the caller cannot probe for
- * what this end can do.
- */
-export const createChannelRPCResponder = ({
-  capabilities,
-  send,
-  approve,
-}: {
-  capabilities: Capabilities
-  send: (data: unknown) => Promise<void> | void
-  /** Omitted means there is nobody to ask, which refuses rather than runs. */
-  approve?: ApprovalRequester
-}) => {
-  return async (message: unknown): Promise<boolean> => {
-    if (!isChannelRPCRequest(message)) {
-      return false
-    }
-
-    const refuse = (name: string, why: string): ChannelRPCResponse => ({
-      action: CHANNEL_RPC_RESPONSE,
-      id: message.id,
-      ok: false,
-      error: { name, message: why },
-    })
-
-    // Own properties only: an object literal inherits from `Object.prototype`,
-    // so a peer asking for `toString` would otherwise resolve a real function.
-    const entry = Object.prototype.hasOwnProperty.call(
-      capabilities,
-      message.funcName
-    )
-      ? capabilities[message.funcName]
-      : undefined
-
-    if (
-      entry === undefined ||
-      (typeof entry !== 'function' && !isCapabilityDef(entry))
-    ) {
-      await send(
-        refuse(
-          'RPCNotFoundError',
-          `Capability not exposed: ${message.funcName}`
-        )
-      )
-      return true
-    }
-
-    const { execute, needsApproval, approvalDescriptionFn } =
-      resolveCapability(entry)
-
-    let response: ChannelRPCResponse
-    try {
-      if (needsApproval) {
-        if (!approve) {
-          await send(
-            refuse(
-              'RPCNotApprovedError',
-              `"${message.funcName}" needs approval and there is nobody to ask`
-            )
-          )
-          return true
-        }
-
-        // Before the asking, not after: an answer arriving past the caller's
-        // timeout is dropped, silently discarding the human's decision.
-        const description = await approvalDescriptionFn?.(message.data)
-        await send({
-          action: CHANNEL_RPC_PENDING,
-          id: message.id,
-          reason: description ?? `approval for ${message.funcName}`,
-        } satisfies ChannelRPCPending)
-
-        const approved = await approve({
-          funcName: message.funcName,
-          data: message.data,
-          description,
-        })
-        if (!approved) {
-          await send(
-            refuse('RPCDeniedError', `"${message.funcName}" was not approved`)
-          )
-          return true
-        }
-      }
-
-      response = {
-        action: CHANNEL_RPC_RESPONSE,
-        id: message.id,
-        ok: true,
-        result: await execute(message.data),
-      }
-    } catch (e: unknown) {
-      const error = e as Error
-      response = refuse(error?.name ?? 'Error', error?.message ?? String(e))
-    }
-
-    await send(response)
-    return true
-  }
-}

package/src/wirings/channel/channel-rpc-service.ts

@@ -1,132 +0,0 @@
-import type { DeploymentService } from '../../services/deployment-service.js'
-import { ChannelRPCRegistry } from './channel-rpc-registry.js'
-import {
-  CHANNEL_RPC_REQUEST,
-  CHANNEL_RPC_RESPONSE,
-  ChannelRPCError,
-  isChannelRPCPending,
-  isChannelRPCResponse,
-  type ChannelRPCRequest,
-  type ChannelRPCValidator,
-} from './channel-rpc.types.js'
-
-/**
- * A `DeploymentService` whose transport is an open channel rather than an
- * address, so a server-side function can call back into a peer that has no
- * inbound route of its own.
- *
- * It slots into the existing `services.deploymentService` hole, leaving
- * `rpc.remote` resolution, session propagation and traceId plumbing unchanged.
- */
-export class ChannelDeploymentService implements DeploymentService {
-  public readonly registry: ChannelRPCRegistry
-  private readonly validateInput?: ChannelRPCValidator
-  private readonly validateResult?: ChannelRPCValidator
-
-  constructor(
-    private readonly send: (data: unknown) => Promise<void> | void,
-    options: {
-      timeoutMs?: number
-      validateInput?: ChannelRPCValidator
-      validateResult?: ChannelRPCValidator
-    } = {}
-  ) {
-    this.registry = new ChannelRPCRegistry(options.timeoutMs)
-    this.validateInput = options.validateInput
-    this.validateResult = options.validateResult
-  }
-
-  public async init(): Promise<void> {}
-
-  public async start(): Promise<void> {}
-
-  public async stop(): Promise<void> {
-    this.registry.rejectAll('Deployment service stopped')
-  }
-
-  /** The channel owner must call this — the service has no read side. */
-  public handleResponse(message: unknown): boolean {
-    if (isChannelRPCPending(message)) {
-      return this.registry.hold(message.id)
-    }
-    return isChannelRPCResponse(message) ? this.registry.settle(message) : false
-  }
-
-  /**
-   * `session` is accepted to satisfy `DeploymentService` and deliberately not
-   * sent: the peer runs the capability as itself, on its own machine, so a
-   * session on the wire would carry the caller's credentials while authorising
-   * nothing.
-   */
-  public async invoke(
-    funcName: string,
-    data: unknown,
-    _session?: unknown,
-    traceId?: string
-  ): Promise<unknown> {
-    // Not a security control — the peer must check what it is handed, and a
-    // hostile caller would send arguments that pass. It catches version drift
-    // and fails it here rather than inside the peer's process.
-    if (this.validateInput) {
-      try {
-        await this.validateInput(funcName, data)
-      } catch (e: unknown) {
-        throw new ChannelRPCError(
-          `Invalid arguments for "${funcName}": ${(e as Error)?.message ?? String(e)}`,
-          'invalid'
-        )
-      }
-    }
-
-    const { id, promise } = this.registry.register()
-    // A closed registry answers with an already-rejected promise and no id.
-    // Returning it before the send keeps that rejection from sitting unobserved.
-    if (!id) {
-      return promise
-    }
-
-    const request: ChannelRPCRequest = {
-      action: CHANNEL_RPC_REQUEST,
-      id,
-      funcName,
-      data,
-      traceId,
-    }
-
-    try {
-      await this.send(request)
-    } catch (e: unknown) {
-      // The call is registered before the request goes out, so a failed send
-      // would otherwise leave an entry whose timeout rejects into an unhandled
-      // rejection with nobody waiting on it.
-      this.registry.settle({
-        action: CHANNEL_RPC_RESPONSE,
-        id,
-        ok: false,
-        error: {
-          name: (e as Error)?.name ?? 'Error',
-          message: (e as Error)?.message ?? String(e),
-        },
-      })
-      promise.catch(() => {})
-      throw e
-    }
-
-    const result = await promise
-    if (!this.validateResult) {
-      return result
-    }
-
-    // The peer answers with whatever it likes, so this is where a value that
-    // has been through nothing enters a server-side command.
-    try {
-      await this.validateResult(funcName, result)
-    } catch (e: unknown) {
-      throw new ChannelRPCError(
-        `Invalid result from "${funcName}": ${(e as Error)?.message ?? String(e)}`,
-        'invalid'
-      )
-    }
-    return result
-  }
-}

package/src/wirings/channel/channel-rpc-validators.ts

@@ -1,65 +0,0 @@
-import type { CoreSingletonServices } from '../../types/core.types.js'
-import { pikkuState } from '../../pikku-state.js'
-import { validateSchema } from '../../schema.js'
-import type { ChannelRPCValidator } from './channel-rpc.types.js'
-
-/**
- * A name with no function metadata is left alone: it is a capability this app
- * never declared a contract for, and failing it would break callers that
- * deliberately treat the value as opaque.
- */
-const createChannelRPCSchemaValidator =
-  (
-    key: 'inputSchemaName' | 'outputSchemaName',
-    singletonServices: Pick<CoreSingletonServices, 'logger' | 'schema'>,
-    packageName: string | null = null
-  ): ChannelRPCValidator =>
-  async (funcName: string, value: unknown): Promise<void> => {
-    const pikkuFuncId = pikkuState(packageName, 'rpc', 'meta')[funcName]
-    if (!pikkuFuncId) {
-      return
-    }
-    const schemaName = pikkuState(packageName, 'function', 'meta')[
-      pikkuFuncId
-    ]?.[key]
-    if (!schemaName) {
-      return
-    }
-    await validateSchema(
-      singletonServices.logger,
-      singletonServices.schema,
-      schemaName,
-      value,
-      packageName
-    )
-  }
-
-/**
- * Checks a capability's answer against the schema codegen generated from its
- * declared return type — the same one an agent tool or an HTTP response is
- * checked against.
- */
-export const createChannelRPCResultValidator = (
-  singletonServices: Pick<CoreSingletonServices, 'logger' | 'schema'>,
-  packageName: string | null = null
-): ChannelRPCValidator =>
-  createChannelRPCSchemaValidator(
-    'outputSchemaName',
-    singletonServices,
-    packageName
-  )
-
-/**
- * Checks outbound arguments against the declared input type. Unlike the result
- * check this is not a boundary — it catches version drift, where a server built
- * against a newer capability signature calls a client that predates it.
- */
-export const createChannelRPCInputValidator = (
-  singletonServices: Pick<CoreSingletonServices, 'logger' | 'schema'>,
-  packageName: string | null = null
-): ChannelRPCValidator =>
-  createChannelRPCSchemaValidator(
-    'inputSchemaName',
-    singletonServices,
-    packageName
-  )