@pikku/core 0.12.107 → 0.12.112

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

@@ -1,5 +0,0 @@
-export * from './channel-rpc.types.js'
-export * from './channel-rpc-registry.js'
-export * from './channel-rpc-service.js'
-export * from './channel-rpc-responder.js'
-export * from './channel-rpc-validators.js'

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

@@ -1,160 +0,0 @@
-/**
- * Envelope actions for request/response RPC carried over an already-open
- * channel. Both directions share one socket, so every frame is tagged and
- * correlated by `id`.
- */
-export const CHANNEL_RPC_REQUEST = 'pikku-rpc-request'
-export const CHANNEL_RPC_RESPONSE = 'pikku-rpc-response'
-export const CHANNEL_RPC_PENDING = 'pikku-rpc-pending'
-
-export interface ChannelRPCRequest {
-  action: typeof CHANNEL_RPC_REQUEST
-  id: string
-  funcName: string
-  data: unknown
-  traceId?: string
-}
-
-export interface ChannelRPCResponse {
-  action: typeof CHANNEL_RPC_RESPONSE
-  id: string
-  ok: boolean
-  result?: unknown
-  error?: { name: string; message: string }
-}
-
-/**
- * "Still working on it — a human is being asked." Stops the caller's timeout,
- * which otherwise fails any approval slower than it and then discards the
- * answer when it arrives. Grants nothing: a peer that sends it dishonestly can
- * only keep its own call waiting.
- */
-export interface ChannelRPCPending {
-  action: typeof CHANNEL_RPC_PENDING
-  id: string
-  reason?: string
-}
-
-const isRecord = (message: unknown): message is Record<string, unknown> =>
-  typeof message === 'object' && message !== null
-
-/**
- * The guards check the whole envelope, not just the action tag: `id` is peer
- * input and is used as a map key, so a frame carrying one of the wrong type
- * must not reach `settle`.
- */
-export const isChannelRPCRequest = (
-  message: unknown
-): message is ChannelRPCRequest =>
-  isRecord(message) &&
-  message.action === CHANNEL_RPC_REQUEST &&
-  typeof message.id === 'string' &&
-  message.id.length > 0 &&
-  typeof message.funcName === 'string' &&
-  message.funcName.length > 0 &&
-  (message.traceId === undefined || typeof message.traceId === 'string')
-
-export const isChannelRPCResponse = (
-  message: unknown
-): message is ChannelRPCResponse =>
-  isRecord(message) &&
-  message.action === CHANNEL_RPC_RESPONSE &&
-  typeof message.id === 'string' &&
-  message.id.length > 0 &&
-  typeof message.ok === 'boolean'
-
-export const isChannelRPCPending = (
-  message: unknown
-): message is ChannelRPCPending =>
-  isRecord(message) &&
-  message.action === CHANNEL_RPC_PENDING &&
-  typeof message.id === 'string' &&
-  message.id.length > 0 &&
-  (message.reason === undefined || typeof message.reason === 'string')
-
-/** `reason` exists so a dropped socket cannot look like a resolved call. */
-export class ChannelRPCError extends Error {
-  constructor(
-    message: string,
-    public readonly reason:
-      'timeout' | 'closed' | 'remote' | 'invalid' | 'unsupported'
-  ) {
-    super(message)
-    this.name = 'ChannelRPCError'
-  }
-}
-
-/**
- * Whether a callable exposed to a remote decider needs a human to agree before
- * it runs, and how to describe the invocation while asking.
- *
- * Shared with `AgentToolDef`: both are an allowlist of named callables
- * invoked by something other than the code that wrote them. The runtime around
- * them is not shared — an agent suspends and resumes, a reverse call is a live
- * await.
- */
-export interface ApprovalPolicy {
-  needsApproval: boolean
-  approvalDescriptionFn?: (input: unknown) => Promise<string> | string
-}
-
-export type CapabilityHandler = (data: any) => Promise<unknown> | unknown
-
-/**
- * `needsApproval` is required here on purpose. On `AgentToolDef` the same
- * field is optional and absence means "do not ask"; here absence means the
- * opposite, so it must not be expressible — a bare function is the
- * unclassified form.
- */
-export interface CapabilityDef extends ApprovalPolicy {
-  execute: CapabilityHandler
-}
-
-export type Capability = CapabilityHandler | CapabilityDef
-
-export type Capabilities = Record<string, Capability>
-
-export const isCapabilityDef = (
-  capability: Capability
-): capability is CapabilityDef =>
-  typeof capability === 'object' &&
-  capability !== null &&
-  typeof (capability as CapabilityDef).execute === 'function'
-
-/**
- * A bare function is unclassified, which resolves to needing approval:
- * forgetting the annotation costs a prompt rather than costing a key.
- */
-export const resolveCapability = (
-  capability: Capability
-): { execute: CapabilityHandler } & ApprovalPolicy =>
-  isCapabilityDef(capability)
-    ? capability
-    : { execute: capability, needsApproval: true }
-
-/** Returning false refuses the call, and the peer is told so. */
-export type ApprovalRequester = (request: {
-  funcName: string
-  data: unknown
-  description?: string
-}) => Promise<boolean> | boolean
-
-/** Checks one end of a call — arguments going out, or the answer coming back. */
-export type ChannelRPCValidator = (
-  funcName: string,
-  value: unknown
-) => Promise<void> | void
-
-/**
- * `remote` for wires with no peer that answers — a server-sent stream, an
- * agent's output, a local CLI. Nothing is listening for a request on them, so
- * the call is refused rather than waiting out a timeout.
- */
-export const unsupportedChannelRemote = async (
-  funcName: string
-): Promise<never> => {
-  throw new ChannelRPCError(
-    `Cannot call "${funcName}" remotely: this channel has no peer that answers`,
-    'unsupported'
-  )
-}

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

@@ -1,164 +0,0 @@
-import { NotFoundError } from '../../errors/errors.js'
-import { addFunction } from '../../function/function-runner.js'
-import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
-import { pikkuState, getSingletonServices } from '../../pikku-state.js'
-import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
-import type { SessionService } from '../../services/user-session-service.js'
-import { httpRouter } from '../http/routers/http-router.js'
-import type {
-  ChannelMeta,
-  CoreChannel,
-  RunChannelOptions,
-  RunChannelParams,
-} from './channel.types.js'
-
-type HandlerConfig = CorePikkuFunctionConfig<any, any>
-
-/**
- * The config to register for a channel handler: the handler itself when it is a
- * direct function config, or its inner `func` when it is a wrapper.
- *
- * knowledge: decisions/internals/channel-message-handlers-accept-three-config-shapes.md
- */
-const registeredHandler = (handler: unknown): HandlerConfig => {
-  const candidate = handler as { func?: unknown }
-  return typeof candidate.func === 'function'
-    ? (handler as HandlerConfig)
-    : (candidate.func as HandlerConfig)
-}
-
-export const wireChannel = <
-  In,
-  Channel extends string,
-  ChannelConnect,
-  ChannelDisconnect,
-  ChannelFunctionMessage,
->(
-  channel: CoreChannel<
-    In,
-    Channel,
-    ChannelConnect,
-    ChannelDisconnect,
-    ChannelFunctionMessage
-  >
-) => {
-  const channelsMeta = pikkuState(null, 'channel', 'meta')
-  const channelMeta = channelsMeta[channel.name]
-  if (!channelMeta) {
-    console.warn(
-      `[pikku] Skipping channel '${channel.name}' — metadata not found. Consider moving this wiring to its own file.`
-    )
-    return
-  }
-
-  if (channel.onConnect && channelMeta.connect) {
-    addFunction(
-      channelMeta.connect.pikkuFuncId,
-      registeredHandler(channel.onConnect)
-    )
-  }
-
-  if (channel.onDisconnect && channelMeta.disconnect) {
-    addFunction(
-      channelMeta.disconnect.pikkuFuncId,
-      registeredHandler(channel.onDisconnect)
-    )
-  }
-
-  if (channel.onMessage && channelMeta.message?.pikkuFuncId) {
-    addFunction(
-      channelMeta.message.pikkuFuncId,
-      registeredHandler(channel.onMessage)
-    )
-  }
-
-  if (channel.onMessageWiring && channelMeta.messageWirings) {
-    Object.entries(channel.onMessageWiring).forEach(([channelKey, wirings]) => {
-      const channelWirings = channelMeta.messageWirings[channelKey]
-      if (!channelWirings) return
-
-      Object.entries(wirings).forEach(([wiringKey, handler]) => {
-        const wiringMeta = channelWirings[wiringKey]
-        if (!wiringMeta) return
-
-        addFunction(wiringMeta.pikkuFuncId, registeredHandler(handler))
-      })
-    })
-  }
-
-  pikkuState(null, 'channel', 'channels').set(channel.name, channel)
-}
-
-const getMatchingChannelConfig = (path: string) => {
-  const matchedPath = httpRouter.match('get', path)
-  if (!matchedPath) {
-    return null
-  }
-
-  const meta = pikkuState(null, 'channel', 'meta')
-  const channelMeta = Object.values(meta).find(
-    (channelConfig) => channelConfig.route === matchedPath.route
-  )
-  if (!channelMeta) {
-    return null
-  }
-
-  const channels = pikkuState(null, 'channel', 'channels')
-  const channelConfig = channels.get(channelMeta.name)
-  if (!channelConfig) {
-    return null
-  }
-
-  return {
-    matchedPath,
-    params: matchedPath.params,
-    channelConfig,
-    schemaName: channelMeta.input,
-    meta: channelMeta,
-  }
-}
-
-export const openChannel = async ({
-  route,
-  coerceDataFromSchema = true,
-  request,
-}: Pick<CoreChannel<unknown, string>, 'route'> &
-  RunChannelParams<unknown> & {
-    userSession: SessionService<any>
-  } & RunChannelOptions): Promise<{
-  openingData: unknown
-  channelConfig: CoreChannel<unknown, any>
-  meta: ChannelMeta
-}> => {
-  const singletonServices = getSingletonServices()
-  const matchingChannel = getMatchingChannelConfig(route)
-  if (!matchingChannel) {
-    singletonServices.logger.info(`Channel not found: ${route}`)
-    throw new NotFoundError(`Channel not found: ${route}`)
-  }
-
-  const { params, channelConfig, schemaName, meta } = matchingChannel
-
-  const requiresSession = channelConfig.auth !== false
-  request?.setParams(params)
-
-  singletonServices.logger.info(
-    `Matched channel: ${channelConfig.name} | route: ${channelConfig.route} | auth: ${requiresSession.toString()}`
-  )
-
-  let openingData: any | undefined
-  if (request) {
-    openingData = await request.data()
-    if (coerceDataFromSchema && schemaName) {
-      coerceTopLevelDataFromSchema(schemaName, openingData)
-    }
-    await validateSchema(
-      singletonServices.logger,
-      singletonServices.schema,
-      schemaName,
-      openingData
-    )
-  }
-
-  return { openingData, channelConfig, meta }
-}

package/src/wirings/channel/channel-store.ts

@@ -1,35 +0,0 @@
-export type Channel<ChannelType = unknown, OpeningData = unknown> = {
-  channelId: string
-  channelName: string
-  channelObject?: ChannelType
-  openingData?: OpeningData
-}
-
-export abstract class ChannelStore<
-  ChannelType = unknown,
-  OpeningData = unknown,
-  TypedChannel = Channel<ChannelType, OpeningData>,
-> {
-  public abstract addChannel(
-    channel: Channel<ChannelType, OpeningData>
-  ): Promise<void> | void
-  public abstract removeChannels(channelId: string[]): Promise<void> | void
-  public abstract setPikkuUserId(
-    channelId: string,
-    pikkuUserId: string | null
-  ): Promise<void> | void
-  public abstract getChannel(
-    channelId: string
-  ):
-    | Promise<TypedChannel & { pikkuUserId?: string }>
-    | (TypedChannel & { pikkuUserId?: string })
-
-  public abstract setState(
-    channelId: string,
-    state: unknown
-  ): Promise<void> | void
-  public abstract getState(
-    channelId: string
-  ): Promise<unknown | undefined> | unknown | undefined
-  public abstract clearState(channelId: string): Promise<void> | void
-}

package/src/wirings/channel/channel.types.ts

@@ -1,193 +0,0 @@
-import type {
-  HTTPFunctionMetaInputTypes,
-  PikkuHTTPRequest,
-  PikkuHTTPResponse,
-} from '../http/http.types.js'
-import type {
-  CorePikkuMiddleware,
-  MiddlewareMetadata,
-} from '../../middleware/middleware.types.js'
-export type BinaryData = ArrayBuffer | Uint8Array
-
-export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (
-  services: Services,
-  event: Event,
-  next: (event: Event | Event[] | null) => Promise<void> | void
-) => Promise<void> | void
-
-export type CorePikkuChannelMiddlewareFactory<
-  In = any,
-  Services = any,
-  Event = unknown,
-> = (input: In) => CorePikkuChannelMiddleware<Services, Event>
-import type {
-  CorePikkuFunction,
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionSessionless,
-  CorePikkuPermission,
-} from '../../function/functions.types.js'
-
-export type RunChannelOptions = Partial<{
-  skipUserSession: boolean
-  respondWith404: boolean
-  coerceDataFromSchema: boolean
-  logWarningsForStatusCodes: number[]
-  bubbleErrors: boolean
-}>
-
-export type RunChannelParams<ChannelData> = {
-  channelId: string
-  request?: PikkuHTTPRequest<ChannelData>
-  response?: PikkuHTTPResponse
-}
-
-export interface ChannelMessageMeta {
-  pikkuFuncId: string
-  packageName?: string
-  summary?: string
-  description?: string
-  errors?: string[]
-  tags?: string[]
-  middleware?: MiddlewareMetadata[]
-}
-
-export interface ChannelMeta {
-  name: string
-  route: string
-  params?: string[]
-  query?: string[]
-  input: string | null
-  inputTypes?: HTTPFunctionMetaInputTypes
-  connect: ChannelMessageMeta | null
-  disconnect: ChannelMessageMeta | null
-  message: ChannelMessageMeta | null
-  messageWirings: Record<string, Record<string, ChannelMessageMeta>>
-  binary?: boolean | null
-  /** Set when the channel was wired by a gateway rather than declared directly. */
-  gateway?: boolean
-  summary?: string
-  description?: string
-  errors?: string[]
-  tags?: string[]
-  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
-  channelMiddleware?: MiddlewareMetadata[]
-}
-
-export type ChannelsMeta = Record<string, ChannelMeta>
-
-export type CoreChannel<
-  ChannelData,
-  Channel extends string,
-  ChannelConnect = CorePikkuFunctionConfig<
-    | CorePikkuFunction<void, unknown>
-    | CorePikkuFunctionSessionless<void, unknown>,
-    CorePikkuPermission<void>,
-    CorePikkuMiddleware
-  >,
-  ChannelDisconnect = CorePikkuFunctionConfig<
-    CorePikkuFunction<void, void> | CorePikkuFunctionSessionless<void, void>,
-    CorePikkuPermission<void>,
-    CorePikkuMiddleware
-  >,
-  ChannelFunctionMessage = CorePikkuFunctionConfig<
-    | CorePikkuFunction<unknown, unknown>
-    | CorePikkuFunctionSessionless<unknown, unknown>,
-    CorePikkuPermission<unknown>,
-    CorePikkuMiddleware
-  >,
-  PikkuPermission = CorePikkuPermission<ChannelData>,
-  PikkuMiddleware = CorePikkuMiddleware,
-> = {
-  /** Unique across the project. It is how the channel is addressed in `pikku meta` and by the generated client. */
-  name: string
-  /** The path a client opens the socket on. */
-  route: Channel
-  /** Runs once when a client connects, before any message. Its return value is sent as the first message. */
-  onConnect?:
-    | ChannelConnect
-    | {
-        func?: ChannelConnect
-        middleware?: PikkuMiddleware[]
-      }
-  onDisconnect?:
-    | ChannelDisconnect
-    | {
-        func?: ChannelDisconnect
-        middleware?: PikkuMiddleware[]
-      }
-  /** Handles any message that no `onMessageWiring` entry claimed. Without one, an unrouted message is dropped. */
-  onMessage?: ChannelFunctionMessage
-  /** Routes messages by a key in their payload: the outer key is the field to switch on, the inner key its value. This is how one socket carries many operations. */
-  onMessageWiring?: Record<
-    string,
-    Record<
-      string,
-      | ChannelFunctionMessage
-      | {
-          func: ChannelFunctionMessage
-          auth?: boolean
-          middleware?: PikkuMiddleware[]
-        }
-    >
-  >
-  /** Wraps the connection: it runs on connect, where the session is established, not on every message. */
-  middleware?: PikkuMiddleware[]
-  /** Wraps every message, which is where per-message concerns like rate limiting belong. */
-  channelMiddleware?: Array<
-    CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory
-  >
-  /** Whether opening the channel requires a session. Defaults to true — a channel is closed unless it says otherwise. */
-  auth?: boolean
-  /** Whether this channel carries binary frames. Text frames are still parsed as JSON. */
-  binary?: boolean | null
-  /** Handles binary frames, which never reach `onMessage` because they are not JSON. Return a value to reply in kind. */
-  onBinaryMessage?: (
-    services: any,
-    data: BinaryData,
-    channel: PikkuChannel<ChannelData, any>
-  ) => Promise<BinaryData | void> | BinaryData | void
-  /** Filters this channel in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-}
-
-/**
- * The shape of `channel.remote` before generated types narrow it to the app's
- * own functions. Loose on purpose: core cannot know the names.
- */
-export type ChannelRemote = (funcName: string, data?: any) => Promise<any>
-
-export interface PikkuChannel<
-  OpeningData,
-  out Out,
-  Remote extends (...args: any[]) => any = ChannelRemote,
-> {
-  channelId: string
-  // Query parameters or url parameters the channel was created with.
-  openingData: OpeningData
-  // Fails once the stream has been closed.
-  send(data: Out, isBinary?: boolean): Promise<void> | void
-  sendBinary(data: BinaryData): Promise<void> | void
-  close(): Promise<void> | void
-  state: 'initial' | 'open' | 'closed'
-  setState<T>(state: T): Promise<void> | void
-  getState<T>(): Promise<T | undefined> | T | undefined
-  clearState(): Promise<void> | void
-  /**
-   * Calls a function on the peer at the other end of this connection and waits
-   * for its answer — the only way to reach a peer with no address of its own.
-   * The peer decides what it answers to; an unregistered name is refused.
-   */
-  remote: Remote
-}
-
-export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
-  send(message: Out, isBinary?: boolean): Promise<void> | void
-  sendBinary(data: BinaryData): Promise<void> | void
-  getChannel(): PikkuChannel<OpeningData, Out>
-}
-
-export type PikkuChannelHandlerFactory<OpeningData = unknown, Out = unknown> = (
-  channelId: string,
-  channelName: string,
-  openingData: OpeningData
-) => PikkuChannelHandler<OpeningData, Out>

package/src/wirings/channel/define-channel-routes.ts

@@ -1,5 +0,0 @@
-export function defineChannelRoutes<T extends Record<string, any>>(
-  routes: T
-): T {
-  return routes
-}

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

@@ -1,16 +0,0 @@
-export interface EventHubService<Topics extends Record<string, any>> {
-  subscribe<T extends keyof Topics>(
-    topic: T,
-    channelId: string
-  ): Promise<void> | void
-  unsubscribe<T extends keyof Topics>(
-    topic: T,
-    channelId: string
-  ): Promise<void> | void
-  publish<T extends keyof Topics>(
-    topic: T,
-    channelId: string | null,
-    data: Topics[T],
-    isBinary?: boolean
-  ): Promise<void> | void
-}

package/src/wirings/channel/eventhub-store.ts

@@ -1,13 +0,0 @@
-export abstract class EventHubStore<
-  EventTopics extends Record<string, any> = {},
-> {
-  public abstract getChannelIdsForTopic(topic: string): Promise<string[]>
-  public abstract subscribe<T extends keyof EventTopics>(
-    topic: T,
-    channelId: string
-  ): Promise<boolean>
-  public abstract unsubscribe<T extends keyof EventTopics>(
-    topic: T,
-    channelId: string
-  ): Promise<boolean>
-}

package/src/wirings/channel/index.ts

@@ -1,40 +0,0 @@
-export { wireChannel } from './channel-runner.js'
-export {
-  addChannelMiddleware,
-  combineChannelMiddleware,
-} from './channel-middleware-runner.js'
-export { logChannels } from './log-channels.js'
-export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js'
-export type { EventHubService } from './eventhub-service.js'
-export { ChannelStore } from './channel-store.js'
-export type { Channel } from './channel-store.js'
-export { EventHubStore } from './eventhub-store.js'
-export type {
-  BinaryData,
-  ChannelsMeta,
-  CoreChannel,
-  CorePikkuChannelMiddleware,
-  CorePikkuChannelMiddlewareFactory,
-  ChannelMessageMeta,
-  ChannelMeta,
-  PikkuChannel,
-  PikkuChannelHandlerFactory,
-} from './channel.types.js'
-export { defineChannelRoutes } from './define-channel-routes.js'
-export {
-  ChannelDeploymentService,
-  ChannelRPCError,
-  ChannelRPCRegistry,
-  unsupportedChannelRemote,
-} from './channel-rpc.js'
-export type {
-  ApprovalPolicy,
-  ApprovalRequester,
-  Capabilities,
-  Capability,
-  CapabilityHandler,
-  ChannelRPCPending,
-  ChannelRPCRequest,
-  ChannelRPCResponse,
-  ChannelRPCValidator,
-} from './channel-rpc.js'

package/src/wirings/channel/local/index.ts

@@ -1,3 +0,0 @@
-export { PikkuLocalChannelHandler } from './local-channel-handler.js'
-export { runLocalChannel } from './local-channel-runner.js'
-export { LocalEventHubService } from './local-eventhub-service.js'