@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/internal/dual/actions.ts

@@ -0,0 +1,116 @@
+import type * as Action from "../../Action.ts";
+import type * as AuthMethod from "../../AuthMethod.ts";
+import type { PluginInstallation } from "../../DualRuntime.ts";
+import type * as Group from "../../Group.ts";
+import type * as Plugin from "../../Plugin.ts";
+import { walkCapabilities } from "../capabilities.ts";
+import type { MachineIdSeparator } from "../identifier.ts";
+import type { IsAny, IsGenericArray } from "../types.ts";
+
+interface ActionEntry<Id extends string = string, ActionDef extends Action.Any = Action.Any> {
+  readonly actionId: Id;
+  readonly action: ActionDef;
+}
+
+type ActionEntriesFromActions<Actions extends readonly Action.Any[], Prefix extends string> =
+  IsGenericArray<Actions> extends true
+    ? ActionEntry
+    : Actions[number] extends infer ActionDef
+      ? ActionDef extends Action.Any
+        ? ActionEntry<`${Prefix}${typeof MachineIdSeparator}${ActionDef["identifier"]}`, ActionDef>
+        : never
+      : never;
+
+type ActionEntriesFromGroups<Groups extends readonly Group.Any[], Prefix extends string> =
+  IsGenericArray<Groups> extends true
+    ? ActionEntry
+    : Groups[number] extends infer GroupDef
+      ? GroupDef extends Group.Any
+        ? GroupActionEntries<
+            GroupDef,
+            `${Prefix}${typeof MachineIdSeparator}${GroupDef["identifier"]}`
+          >
+        : never
+      : never;
+
+type GroupActionEntries<GroupDef extends Group.Any, Prefix extends string> =
+  | ActionEntriesFromActions<GroupDef["actions"], Prefix>
+  | ActionEntriesFromGroups<GroupDef["groups"], Prefix>;
+
+export type PluginActionEntries<P extends Plugin.Any> =
+  | ActionEntriesFromActions<P["actions"], P["identifier"]>
+  | ActionEntriesFromGroups<P["groups"], P["identifier"]>;
+
+export type AllActionEntries<Plugins extends readonly Plugin.Any[]> =
+  IsAny<Plugins> extends true
+    ? ActionEntry
+    : IsGenericArray<Plugins> extends true
+      ? ActionEntry
+      : Plugins[number] extends infer P
+        ? P extends Plugin.Any
+          ? PluginActionEntries<P>
+          : never
+        : never;
+
+type GroupActions<Groups extends readonly Group.Any[]> =
+  IsGenericArray<Groups> extends true
+    ? Action.Any
+    : Groups[number] extends infer GroupDef
+      ? GroupDef extends Group.Any
+        ? GroupDef["actions"][number] | GroupActions<GroupDef["groups"]>
+        : never
+      : never;
+
+export type PluginActions<P extends Plugin.Any> = P["actions"][number] | GroupActions<P["groups"]>;
+
+export interface RuntimeActionEntry<
+  out ActionId extends string = string,
+  out ProviderId extends string = string,
+  out ActionDef extends Action.Any = Action.Any,
+  out AllowedMethods extends readonly AuthMethod.Any[] = readonly AuthMethod.Any[],
+> {
+  readonly actionId: ActionId;
+  readonly providerId: ProviderId;
+  readonly localId: string;
+  readonly pluginVersion: string;
+  readonly action: ActionDef;
+  readonly authMethods: AllowedMethods;
+}
+
+const entriesOf = (installation: PluginInstallation): readonly RuntimeActionEntry[] =>
+  walkCapabilities(installation.plugin, owner => owner.actions).map(
+    ({ localId, canonicalId, node }) => ({
+      action: node,
+      actionId: canonicalId,
+      authMethods: installation.plugin.authMethods,
+      localId,
+      pluginVersion: installation.version,
+      providerId: installation.plugin.identifier,
+    }),
+  );
+
+export const collectActionEntries = (
+  installations: readonly PluginInstallation[],
+): readonly RuntimeActionEntry[] => installations.flatMap(entriesOf);
+
+const actionIndex = new WeakMap<
+  readonly PluginInstallation[],
+  ReadonlyMap<string, RuntimeActionEntry>
+>();
+
+/** An action of the installed releases, or of the exact `version` when the caller pins one. */
+export const resolveAction = (
+  installations: readonly PluginInstallation[],
+  actionId: string,
+  version?: string,
+): RuntimeActionEntry | undefined => {
+  let index = actionIndex.get(installations);
+  if (index === undefined) {
+    index = new Map(collectActionEntries(installations).map(entry => [entry.actionId, entry]));
+    actionIndex.set(installations, index);
+  }
+  const entry = index.get(actionId);
+  return entry === undefined || (version !== undefined && entry.pluginVersion !== version)
+    ? undefined
+    : entry;
+};

package/src/internal/dual/invoke.ts

@@ -0,0 +1,307 @@
+import { Effect, Schema, SchemaIssue } from "effect";
+
+import * as Action from "../../Action.ts";
+import type * as AuthMethod from "../../AuthMethod.ts";
+import type {
+  ConnectionError,
+  ConnectionResolutionContext,
+  Service as ConnectionResolverService,
+} from "../../ConnectionResolver.ts";
+import type * as Plugin from "../../Plugin.ts";
+import {
+  authRuntimeContext,
+  failConnectionIdNotAllowed,
+  noAuthRuntimeContext,
+  resolveRuntimeConnection,
+  type AuthResolutionRequirements,
+  type AuthSchemaRequirements,
+  toNonEmptyArray,
+} from "../auth-execution.ts";
+import { findHandler, mergeUnder } from "../handler-context.ts";
+import type { ActionHandlerServiceOf } from "../plugin-handlers.ts";
+import { decodeJsonMapError } from "../schema-runtime.ts";
+
+import type { PluginActionEntries } from "./actions.ts";
+
+export interface InvokeRequest {
+  readonly actionId: string;
+  /** The exact plugin release the caller pinned; another installed release does not run. */
+  readonly actionVersion?: string;
+  readonly pluginKey?: string;
+  readonly input: unknown;
+  readonly connectionId?: string;
+  readonly context?: ConnectionResolutionContext;
+}
+
+export interface InvokeMeta<ActionId extends string = string> {
+  readonly actionId: ActionId;
+  readonly providerId: string;
+  readonly pluginVersion: string;
+}
+
+export interface InvokeSuccess<ActionId extends string = string, Data = unknown> {
+  readonly data: Data;
+  readonly meta: InvokeMeta<ActionId>;
+}
+
+export class FieldIssue extends Schema.Class<FieldIssue>("FieldIssue")({
+  message: Schema.String,
+  path: Schema.String,
+}) {}
+
+export class ActionNotFoundError extends Schema.TaggedError<ActionNotFoundError>()(
+  "ActionNotFoundError",
+  { actionId: Schema.String },
+) {}
+
+export class InvalidActionInputError extends Schema.TaggedError<InvalidActionInputError>()(
+  "InvalidActionInputError",
+  { actionId: Schema.String, description: Schema.String, fields: Schema.Array(FieldIssue) },
+) {}
+
+export class ActionHandlerNotFoundError extends Schema.TaggedError<ActionHandlerNotFoundError>()(
+  "ActionHandlerNotFoundError",
+  { actionId: Schema.String },
+) {}
+
+export class InvalidActionOutputError extends Schema.TaggedError<InvalidActionOutputError>()(
+  "InvalidActionOutputError",
+  { actionId: Schema.String, description: Schema.String, fields: Schema.Array(FieldIssue) },
+) {}
+
+type InvokeResolvedActionError =
+  | InvalidActionInputError
+  | InvalidActionOutputError
+  | ActionHandlerNotFoundError
+  | Action.ActionHandlerFailure
+  | ConnectionError;
+
+export type InvokeError = ActionNotFoundError | InvokeResolvedActionError;
+
+export type InvokeRequirementsFor<
+  Plugins extends readonly Plugin.Any[],
+  ActionId extends string,
+> = Plugins[number] extends infer P
+  ? P extends Plugin.Any
+    ? PluginRequirements<
+        P,
+        Extract<PluginActionEntries<P>, { readonly actionId: ActionId }>["action"]
+      >
+    : never
+  : never;
+
+export type PluginRequirements<P extends Plugin.Any, ActionDef extends Action.Any> = [
+  ActionDef,
+] extends [never]
+  ? never
+  :
+      | ActionHandlerServiceOf<P>
+      | Action.InputSchema<ActionDef>["DecodingServices"]
+      | Action.OutputSchema<ActionDef>["EncodingServices"]
+      | ([P["authMethods"][number]] extends [never]
+          ? never
+          :
+              | ConnectionResolverService
+              | AuthSchemaRequirements<P["authMethods"]>
+              | AuthResolutionRequirements<P["authMethods"]>);
+
+const schemaIssueFormatter = SchemaIssue.makeFormatterStandardSchemaV1();
+
+const formatFieldPath = (path: readonly unknown[]): string => {
+  let current = "$";
+
+  for (const segment of path) {
+    if (typeof segment === "number") {
+      current += `[${segment}]`;
+      continue;
+    }
+
+    const key = String(segment);
+    current += /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`;
+  }
+
+  return current;
+};
+
+const schemaErrorFields = (error: Schema.SchemaError): readonly FieldIssue[] =>
+  schemaIssueFormatter(error.issue).issues.map(
+    issue => new FieldIssue({ message: issue.message, path: formatFieldPath(issue.path ?? []) }),
+  );
+
+const decodeActionInput = <Input extends Schema.Top>(
+  actionId: string,
+  schema: Input,
+  input: unknown,
+): Effect.Effect<Input["Type"], InvalidActionInputError, Input["DecodingServices"]> =>
+  decodeJsonMapError(
+    schema,
+    input,
+    error =>
+      new InvalidActionInputError({
+        actionId,
+        description: error.message,
+        fields: schemaErrorFields(error),
+      }),
+  );
+
+const validateActionOutput = <Output extends Schema.Top>(
+  actionId: string,
+  schema: Output,
+  output: Output["Type"],
+): Effect.Effect<Output["Type"], InvalidActionOutputError, Output["EncodingServices"]> =>
+  Schema.encodeEffect(schema)(output).pipe(
+    Effect.as(output),
+    Effect.mapError(
+      error =>
+        new InvalidActionOutputError({
+          actionId,
+          description: error.message,
+          fields: schemaErrorFields(error),
+        }),
+    ),
+  );
+
+const getActionHandler = <ActionId extends string>(
+  providerId: string,
+  actionId: ActionId,
+): Effect.Effect<Action.Handler<ActionId>, ActionHandlerNotFoundError, Action.Handler<ActionId>> =>
+  Effect.context<Action.Handler<ActionId>>().pipe(
+    Effect.flatMap(context => {
+      const handler = findHandler(context, providerId, Action.handlerKey(actionId)) as
+        | Action.Handler<ActionId>
+        | undefined;
+
+      return handler === undefined
+        ? Effect.fail(new ActionHandlerNotFoundError({ actionId }))
+        : Effect.succeed(handler);
+    }),
+  );
+
+const invokeResolvedActionWithOutput = <
+  ActionId extends string,
+  Input extends Schema.Top,
+  Output extends Schema.Top,
+  ActionAuthMethods extends readonly AuthMethod.Any[],
+  OutputValue,
+>(
+  providerId: string,
+  actionId: ActionId,
+  pluginVersion: string,
+  action: Action.Action<string, Input, Output>,
+  authMethods: ActionAuthMethods,
+  request: InvokeRequest,
+  finish: (
+    output: unknown,
+  ) => Effect.Effect<OutputValue, InvalidActionOutputError, Output["EncodingServices"]>,
+): Effect.Effect<
+  InvokeSuccess<ActionId, OutputValue>,
+  InvokeResolvedActionError,
+  | Action.Handler<ActionId>
+  | Input["DecodingServices"]
+  | Output["EncodingServices"]
+  | ([ActionAuthMethods[number]] extends [never]
+      ? never
+      :
+          | ConnectionResolverService
+          | AuthSchemaRequirements<ActionAuthMethods>
+          | AuthResolutionRequirements<ActionAuthMethods>)
+> => {
+  const requiredAuthMethods = toNonEmptyArray(authMethods);
+
+  if (requiredAuthMethods === undefined && request.connectionId !== undefined) {
+    return failConnectionIdNotAllowed(
+      "action",
+      actionId,
+      undefined,
+      providerId,
+      request.connectionId,
+    );
+  }
+
+  return getActionHandler(providerId, actionId).pipe(
+    Effect.flatMap(handler =>
+      decodeActionInput(actionId, action.input, request.input).pipe(
+        Effect.flatMap(decodedInput =>
+          requiredAuthMethods === undefined ||
+          // Only an explicit false skips auth for definitions built outside the SDK.
+          (action.requireAuth === false && request.connectionId === undefined)
+            ? Effect.suspend(() => handler.handler(decodedInput, noAuthRuntimeContext()))
+            : resolveRuntimeConnection(
+                "action",
+                actionId,
+                undefined,
+                providerId,
+                requiredAuthMethods,
+                request.connectionId,
+                request.context,
+              ).pipe(
+                Effect.flatMap(binding =>
+                  Effect.suspend(() => handler.handler(decodedInput, authRuntimeContext(binding))),
+                ),
+              ),
+        ),
+        Effect.updateContext(input => mergeUnder(handler.context, input)),
+      ),
+    ),
+    Effect.flatMap(finish),
+    Effect.map((data): InvokeSuccess<ActionId, OutputValue> => ({
+      data,
+      meta: { actionId, pluginVersion, providerId },
+    })),
+  );
+};
+
+export const invokeResolvedAction = <
+  ActionId extends string,
+  Input extends Schema.Top,
+  Output extends Schema.Top,
+  ActionAuthMethods extends readonly AuthMethod.Any[],
+>(
+  providerId: string,
+  actionId: ActionId,
+  pluginVersion: string,
+  action: Action.Action<string, Input, Output>,
+  authMethods: ActionAuthMethods,
+  request: InvokeRequest,
+) =>
+  invokeResolvedActionWithOutput(
+    providerId,
+    actionId,
+    pluginVersion,
+    action,
+    authMethods,
+    request,
+    data => validateActionOutput(actionId, action.output, data as Output["Type"]),
+  );
+
+export const invokeResolvedActionJson = <
+  ActionId extends string,
+  Input extends Schema.Top,
+  Output extends Schema.Top,
+  ActionAuthMethods extends readonly AuthMethod.Any[],
+>(
+  providerId: string,
+  actionId: ActionId,
+  pluginVersion: string,
+  action: Action.Action<string, Input, Output>,
+  authMethods: ActionAuthMethods,
+  request: InvokeRequest,
+) =>
+  invokeResolvedActionWithOutput(
+    providerId,
+    actionId,
+    pluginVersion,
+    action,
+    authMethods,
+    request,
+    data =>
+      Schema.encodeUnknownEffect(Schema.toCodecJson(action.output))(data).pipe(
+        Effect.mapError(error =>
+          InvalidActionOutputError.make({
+            actionId,
+            description: error.message,
+            fields: schemaErrorFields(error),
+          }),
+        ),
+      ),
+  );