@milaboratories/pl-middle-layer 1.74.19 → 1.76.0

package/src/mutator/template/render_block.ts

@@ -1,7 +1,7 @@
 import type { AnyRef, PlTransaction, ResourceRef, ResourceType } from "@milaboratories/pl-client";
 import { field, Pl } from "@milaboratories/pl-client";
 import { randomUUID } from "node:crypto";
-import { createRenderTemplate } from "./render_template";
+import { createRenderTemplateWithResource } from "./render_template";
 
 export const BContextEnd: ResourceType = { name: "BContextEnd", version: "1" };
 export const BContext: ResourceType = { name: "BContext", version: "1" };
@@ -30,12 +30,63 @@ export type HeavyBlockOutputs = {
 
 export const HeavyBlockOutputNames: (keyof HeavyBlockOutputs)[] = ["context", "result"];
 
+/** Baggage of the root action context of a block render. See the block action context spec. */
+export type BlockActionContextBaggage = {
+  /** Display name of the block. */
+  name: string;
+  /** JSON of the block pack spec. */
+  blockPack: string;
+  blockId: string;
+};
+
+/** Resource type of a block action context. See ActionContextV1Type in the backend. */
+export const ActionContextType: ResourceType = { name: "ActionContext", version: "1" };
+
+/** The capability under which the backend accepts the "actionContext" link on a render. */
+export const ActionContextLinkCapability = "optionalFieldsInSchemas:v1";
+
+/**
+ * Creates the root action context of a block render: an ActionContext resource carrying the
+ * baggage, with a new random `run-id`, since each render is one run of the block and the contexts
+ * the templates create copy it. Undefined without baggage, or on a backend that cannot take the link.
+ */
+function createBlockActionContext(
+  tx: PlTransaction,
+  baggage: BlockActionContextBaggage | undefined,
+): ResourceRef | undefined {
+  if (baggage === undefined || !tx.hasCapability(ActionContextLinkCapability)) return undefined;
+  return tx.createEphemeral(
+    ActionContextType,
+    JSON.stringify({
+      name: baggage.name,
+      "block-pack": baggage.blockPack,
+      "block-id": baggage.blockId,
+      "run-id": randomUUID(),
+    }),
+  );
+}
+
+/**
+ * Creates the heavy block render, and with `baggage` its root action context in the same
+ * transaction. Returns `actionContext`: the render is garbage collected after its outputs resolve,
+ * so the caller must hold the context to keep it.
+ */
 export function createRenderHeavyBlock(
   tx: PlTransaction,
   tpl: AnyRef,
   inputs: HeavyBlockInputs,
-): HeavyBlockOutputs {
-  return createRenderTemplate(tx, tpl, true, inputs, HeavyBlockOutputNames);
+  baggage?: BlockActionContextBaggage,
+): HeavyBlockOutputs & { actionContext?: ResourceRef } {
+  const actionContext = createBlockActionContext(tx, baggage);
+  const { outputs } = createRenderTemplateWithResource(
+    tx,
+    tpl,
+    true,
+    inputs,
+    HeavyBlockOutputNames,
+    actionContext,
+  );
+  return actionContext === undefined ? outputs : { ...outputs, actionContext };
 }
 
 export type LightBlockInputs = {
@@ -51,12 +102,26 @@ export type LightBlockOutput = {
 
 export const LightBlockOutputNames: (keyof LightBlockOutput)[] = ["result"];
 
+/**
+ * Creates the light block render, with the same action context as a heavy one, so template code
+ * of either kind knows its block and run.
+ */
 export function createRenderLightBlock(
   tx: PlTransaction,
   tpl: ResourceRef,
   inputs: LightBlockInputs,
-): LightBlockOutput {
-  return createRenderTemplate(tx, tpl, true, inputs, LightBlockOutputNames);
+  baggage?: BlockActionContextBaggage,
+): LightBlockOutput & { actionContext?: ResourceRef } {
+  const actionContext = createBlockActionContext(tx, baggage);
+  const { outputs } = createRenderTemplateWithResource(
+    tx,
+    tpl,
+    true,
+    inputs,
+    LightBlockOutputNames,
+    actionContext,
+  );
+  return actionContext === undefined ? outputs : { ...outputs, actionContext };
 }
 
 export function createBContextEnd(tx: PlTransaction): ResourceRef {

package/src/mutator/template/render_template.ts

@@ -1,4 +1,4 @@
-import type { AnyRef, FieldRef, PlTransaction } from "@milaboratories/pl-client";
+import type { AnyRef, FieldRef, PlTransaction, ResourceRef } from "@milaboratories/pl-client";
 import { field, Pl } from "@milaboratories/pl-client";
 import type { ResourceType } from "@platforma-sdk/model";
 
@@ -27,6 +27,24 @@ export function createRenderTemplate<O extends string>(
   inputs: Pl.PlRecord,
   outputNames: O[],
 ): Record<O, FieldRef> {
+  return createRenderTemplateWithResource(tx, tpl, ephemeral, inputs, outputNames).outputs;
+}
+
+/**
+ * Same as {@link createRenderTemplate}, and also returns the render resource itself.
+ *
+ * With `actionContext`, the render's "actionContext" service field points to it. The link is created
+ * before the inputs are locked: the backend accepts it only in the creating transaction, ahead of
+ * any explicit input lock.
+ */
+export function createRenderTemplateWithResource<O extends string>(
+  tx: PlTransaction,
+  tpl: AnyRef,
+  ephemeral: boolean,
+  inputs: Pl.PlRecord,
+  outputNames: O[],
+  actionContext?: AnyRef,
+): { render: ResourceRef; outputs: Record<O, FieldRef> } {
   if (outputNames.length === 0) throw new Error("Zero output names provided");
   const rId = ephemeral ? tx.createEphemeral(EphRenderTemplate) : tx.createStruct(RenderTemplate);
 
@@ -35,7 +53,9 @@ export function createRenderTemplate<O extends string>(
 
   tx.createField(tplField, "Input", tpl);
   tx.createField(inputsField, "Input", Pl.createPlMap(tx, inputs, ephemeral));
+  if (actionContext !== undefined)
+    tx.createField(field(rId, "actionContext"), "Service", actionContext);
   tx.lockInputs(rId);
 
-  return Pl.futureRecord(tx, rId, outputNames, "Output", "outputs/");
+  return { render: rId, outputs: Pl.futureRecord(tx, rId, outputNames, "Output", "outputs/") };
 }

package/src/test/fake_project.ts

@@ -0,0 +1,222 @@
+import {
+  createSignedResourceId,
+  DefaultFinalResourceDataPredicate,
+  NullSignedResourceId,
+  type FieldData,
+  type FieldType,
+  type SignedResourceId,
+} from "@milaboratories/pl-client";
+import type { PColumnSpec, ArgsIssue } from "@milaboratories/pl-model-common";
+import { PlTreeState, type ExtendedResourceData } from "@milaboratories/pl-tree";
+import { argsFingerprint, type ArgsErrorsRecord } from "../model/args_derivation";
+import {
+  projectFieldName,
+  ProjectStructureKey,
+  type ProjectField,
+  type ProjectStructure,
+} from "../model/project_model";
+
+/** What a project field holds: a resource, an error, or nothing yet. */
+export type FieldContent = SignedResourceId | { error: SignedResourceId } | "unresolved";
+
+/** Columns of a result list by name: the spec of each and the cells of its data. */
+export type Columns = Record<string, { spec: PColumnSpec; cells: string[] }>;
+
+/**
+ * State of a result list: `locked` — complete; `open` — more columns may come; `failed` — it has
+ * an error and will never lock.
+ */
+export type FrameState = { state: "locked" | "open" | "failed" };
+
+/** The block fields a {@link FakeProject} holds. */
+export type FakeProjectField = Extract<
+  ProjectField["fieldName"],
+  | "currentArgs"
+  | "inputsValid"
+  | "prodArgs"
+  | "prodCtx"
+  | "prodUiCtx"
+  | "stagingCtx"
+  | "stagingUiCtx"
+>;
+
+/** A project resource tree built in memory: its blocks, in project order, and their fields. */
+export class FakeProject {
+  private readonly nodes: ExtendedResourceData[] = [];
+  private sent = 0;
+  private readonly blocks = new Map<string, Partial<Record<FakeProjectField, FieldContent>>>();
+  private readonly frameFields = new Map<SignedResourceId, FieldData[]>();
+
+  /** Adds a block below the others, or replaces the fields of one already added. */
+  block(blockId: string, fields: Partial<Record<FakeProjectField, FieldContent>>): void {
+    this.blocks.set(blockId, fields);
+  }
+
+  /** Args of a block. */
+  args(args: unknown): SignedResourceId {
+    return this.value("json/object", args);
+  }
+
+  /** Args errors of a block found in the args `forArgs`, as its `inputsValid` field holds them. */
+  argsErrors(errors: readonly ArgsIssue[], forArgs: unknown): SignedResourceId {
+    const record: ArgsErrorsRecord = { argsFingerprint: argsFingerprint(forArgs), errors };
+    return this.value("json/object", record);
+  }
+
+  /** A ready value resource holding `json`. */
+  value(type: string, json: unknown): SignedResourceId {
+    const id = this.newId();
+    this.nodes.push({
+      ...READY,
+      id,
+      kind: "Value",
+      type: { name: type, version: "1" },
+      data: Buffer.from(JSON.stringify(json)),
+      fields: [],
+    });
+    return id;
+  }
+
+  /** An error a resource or field can hold. */
+  error(message: string): SignedResourceId {
+    return this.value("json/resourceError", { message });
+  }
+
+  /** A result list exporting the given columns, each with JSON data holding `cells`. */
+  frame(columns: Columns, state: FrameState = { state: "locked" }): SignedResourceId {
+    const id = this.newId();
+    this.frameFields.set(id, []);
+    this.extend(id, columns, state);
+    return id;
+  }
+
+  /** Adds columns to a result list made by {@link frame}, and moves it to `state`. */
+  extend(id: SignedResourceId, columns: Columns, { state }: FrameState): void {
+    const fields = this.frameFields.get(id);
+    if (fields === undefined) throw new Error("Not a result list of this project");
+    for (const [name, { spec, cells }] of Object.entries(columns)) {
+      const data = Object.fromEntries(cells.map((cell, i) => [`["s${i}"]`, cell]));
+      fields.push(field("Input", `${name}.spec`, this.value("PColumnSpec", spec)));
+      fields.push(
+        field("Input", `${name}.data`, this.value("PColumnData/Json", { keyLength: 1, data })),
+      );
+    }
+    const error = state === "failed" ? this.error("render failed") : NullSignedResourceId;
+    this.nodes.push({
+      ...READY,
+      id,
+      kind: "Structural",
+      type: { name: "PFrame", version: "1" },
+      inputsLocked: state === "locked",
+      resourceReady: state === "locked",
+      final: state === "locked",
+      error,
+      fields: [...fields],
+    });
+  }
+
+  /** The tree of the project as it is now. */
+  tree(): PlTreeState {
+    const tree = new PlTreeState(ROOT_ID, DefaultFinalResourceDataPredicate);
+    tree.updateFromResourceData(this.changes());
+    return tree;
+  }
+
+  /**
+   * The project resource and the resources added or changed since the last call: a final
+   * resource already in the tree is not sent again.
+   */
+  changes(): ExtendedResourceData[] {
+    const structure: ProjectStructure = {
+      groups: [
+        {
+          id: "main",
+          label: "Main",
+          blocks: [...this.blocks.keys()].map((id) => ({ id, label: id, renderingMode: "Heavy" })),
+        },
+      ],
+    };
+    const fields = [...this.blocks].flatMap(([blockId, contents]) =>
+      PROJECT_FIELDS.flatMap((name) => {
+        const content = contents[name];
+        return content === undefined
+          ? []
+          : [projectField(projectFieldName(blockId, name), content)];
+      }),
+    );
+    const root: ExtendedResourceData = {
+      ...READY,
+      final: false,
+      id: ROOT_ID,
+      kind: "Structural",
+      type: { name: "UserProject", version: "2" },
+      fields,
+      kv: [{ key: ProjectStructureKey, value: Buffer.from(JSON.stringify(structure)) }],
+    };
+    const added = this.nodes.slice(this.sent);
+    this.sent = this.nodes.length;
+    return [root, ...added];
+  }
+
+  private newId(): SignedResourceId {
+    return createSignedResourceId(nextResourceId++);
+  }
+}
+
+// Internals
+
+const ROOT_ID = createSignedResourceId(1_000_001n);
+
+/**
+ * Resource ids stay unique across tests, as they are on a backend: the middle layer caches the
+ * columns an args resource references by its id.
+ */
+let nextResourceId = 100n;
+
+const READY: Omit<ExtendedResourceData, "id" | "kind" | "type" | "fields"> = {
+  originalResourceId: NullSignedResourceId,
+  error: NullSignedResourceId,
+  inputsLocked: true,
+  outputsLocked: true,
+  resourceReady: true,
+  final: true,
+  kv: [],
+};
+
+const PROJECT_FIELDS: readonly FakeProjectField[] = [
+  "currentArgs",
+  "inputsValid",
+  "prodArgs",
+  "prodCtx",
+  "prodUiCtx",
+  "stagingCtx",
+  "stagingUiCtx",
+];
+
+function field(type: FieldType, name: string, value: SignedResourceId): FieldData {
+  return { name, type, value, error: NullSignedResourceId, status: "Resolved", valueIsFinal: true };
+}
+
+function projectField(name: string, content: FieldContent): FieldData {
+  if (content === "unresolved") {
+    return {
+      name,
+      type: "Dynamic",
+      value: NullSignedResourceId,
+      error: NullSignedResourceId,
+      status: "Empty",
+      valueIsFinal: false,
+    };
+  }
+  if (typeof content === "object" && "error" in content) {
+    return {
+      name,
+      type: "Dynamic",
+      value: NullSignedResourceId,
+      error: content.error,
+      status: "Resolved",
+      valueIsFinal: true,
+    };
+  }
+  return field("Dynamic", name, content);
+}