@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-frontend/src/runtime/browser/services/BrowserSubServiceUI.tsx

@@ -0,0 +1,187 @@
+import { ReactNode, useCallback, useEffect, useState } from "react";
+import { ServiceInstance, ServiceUIProps } from "hkp-frontend/src/types";
+import ServiceUI from "hkp-frontend/src/ui-components/service/ServiceUI";
+import SubServicePipelineUI from "../../ui/SubServicePipelineUI";
+import { findServiceUI } from "../UIRegistry";
+import { BrowserSubService } from "./BrowserSubService";
+import ScopeOutput from "../../ui/ScopeOutput";
+import ScopeSlots from "../../ui/ScopeSlots";
+import { usePanelBlockLock } from "../../ui/BlockUse";
+
+type Props = ServiceUIProps & {
+  /**
+   * What a service built on this scope has to say beside it — an Iterator's
+   * items, a Gather's limits — shown above the scope's own controls.
+   */
+  children?: ReactNode;
+  /** That service's state as it arrives, for whatever `children` shows. */
+  onState?: (state: any) => void;
+};
+
+function BrowserSubServiceUI(props: Props): JSX.Element {
+  const { children, onState, ...serviceProps } = props;
+  // Incremented whenever the inner scope finishes (re)building so that
+  // getActualInstance picks up the newly created service instances.
+  const [, setScopeVersion] = useState(0);
+
+  const onNotification = useCallback((notification: any) => {
+    onState?.(notification);
+    // `scope` and `stopPropagation` because what a scope declares about
+    // itself is applied without rebuilding anything: nothing else would tell
+    // the panel that what it is showing has changed.
+    if (
+      notification?.__innerScopeReady ||
+      notification?.scope ||
+      notification?.stopPropagation !== undefined
+    ) {
+      setScopeVersion((v) => v + 1);
+    }
+  }, [onState]);
+
+  const getActualInstance = useCallback(
+    (instanceId: string): ServiceInstance | null => {
+      const svc = props.service as unknown as BrowserSubService;
+      return svc.getInnerInstance?.(instanceId) ?? null;
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [props.service],
+  );
+
+  return (
+    <ServiceUI {...serviceProps} onInit={onState} onNotification={onNotification}>
+      <ScopeBody service={props.service} getActualInstance={getActualInstance}>
+        {children}
+      </ScopeBody>
+    </ServiceUI>
+  );
+}
+
+/**
+ * The panel inside its frame.
+ *
+ * It takes the lock of a block's use over from the frame rather than being
+ * kept out of reach whole, because a nested pipeline is something to look
+ * into: folding it open here and opening it as a level of its own only read,
+ * and the panels inside lock themselves. What writes — the scope's two
+ * declarations, and whatever the service built on it shows — is kept out of
+ * reach here instead.
+ */
+function ScopeBody({
+  service,
+  getActualInstance,
+  children,
+}: {
+  service: ServiceInstance;
+  getActualInstance: (instanceId: string) => ServiceInstance | null;
+  children?: ReactNode;
+}) {
+  const locked = usePanelBlockLock();
+  return (
+    <>
+      {children && <div inert={locked}>{children}</div>}
+      {/* Above the pipeline because they are about the scope rather than
+          about any one service in it, and because the pipeline below can be
+          long. What leaves first, then where what is held is kept: the one is
+          about this service's place in the flow, the other about what the
+          services inside it can reach. */}
+      <ScopeOutput
+        stops={
+          (service as unknown as BrowserSubService).state?.stopPropagation ===
+          true
+        }
+        onChange={
+          locked
+            ? undefined
+            : (stops) => service.configure({ stopPropagation: stops })
+        }
+      />
+      <BrowserScopeSlots service={service} locked={locked} />
+      <div className="pb-2">
+        <SubServicePipelineUI
+          service={service}
+          findServiceUI={findServiceUI}
+          getActualInstance={getActualInstance}
+        />
+      </div>
+    </>
+  );
+}
+
+/**
+ * What this scope is holding, read straight off the live store.
+ *
+ * Only the browser runtime can do this: the store is an object in the same
+ * process as the panel, so there is nothing to serialise and no round trip.
+ * A scope on a REST runtime would have to report its cells in its state first.
+ */
+function BrowserScopeSlots({
+  service,
+  locked,
+}: {
+  service: ServiceInstance;
+  /** Inside a use of a block: the cells can be read, not changed. */
+  locked: boolean;
+}) {
+  const svc = service as unknown as BrowserSubService;
+  const { store, inherited } = svc.slotsInUse?.() ?? {
+    store: null,
+    inherited: false,
+  };
+
+  const [open, setOpen] = useState(false);
+  const [cells, setCells] = useState<[string, unknown][]>([]);
+
+  useEffect(() => {
+    if (!store) {
+      setCells([]);
+      return;
+    }
+    const read = () => {
+      setCells((previous) => {
+        const next = store.entries();
+        // Closed, only the names are on screen, and a cell written on a timer
+        // would otherwise re-render this panel every tick for a value nobody
+        // is looking at. Same names, same array: React draws nothing.
+        return !open && sameNames(previous, next) ? previous : next;
+      });
+    };
+    // Read once on arrival as well as on every write: the cells a scope
+    // inherits were very likely written before this panel existed.
+    read();
+    return store.watch(read);
+  }, [store, open]);
+
+  if (svc.state?.mode === "source") {
+    return null;
+  }
+
+  return (
+    <ScopeSlots
+      cells={cells}
+      slots={svc.state?.scope?.slots ?? "own"}
+      inherited={inherited}
+      open={open}
+      onOpenChange={setOpen}
+      onSlotsChange={
+        locked
+          ? undefined
+          : (next) => service.configure({ scope: { slots: next } })
+      }
+      // Straight at the store, because that is where a cell is: a slot is
+      // named by the Holds at either end and owned by neither, so there is no
+      // service whose configure this could be. The store reports the removal,
+      // which is what takes it off the screen here and in any other panel
+      // showing these same cells.
+      onRemove={locked ? undefined : (name) => store?.remove(name)}
+    />
+  );
+}
+
+/** Whether two readings of a store hold the same cells, whatever is in them. */
+function sameNames(a: [string, unknown][], b: [string, unknown][]): boolean {
+  return (
+    a.length === b.length && a.every(([name], index) => name === b[index][0])
+  );
+}
+
+export default BrowserSubServiceUI;

package/bundle/hkp-frontend/src/runtime/browser/services/BrowserTracks.tsx

@@ -0,0 +1,477 @@
+/**
+ * Service Documentation
+ * Service ID: tracks
+ * Service Name: Tracks
+ * Modes: serial | parallel
+ * Key Config: tracks, reduce, run, bypass
+ *
+ * Several pipelines over one input, and one answer out.
+ *
+ * `iterator` runs one pipeline over many items; this is the other half of that
+ * pair. A board that has to do two unrelated things with the same value has
+ * otherwise to put them in a row and teach each of them to pass its input
+ * through — which works, and records nothing: not that they are siblings rather
+ * than a sequence, not in which order they may run, not which answer matters.
+ *
+ *     input ──┬── track ── answer ──┬── reduce ── output
+ *             ├── track ── answer ──┤
+ *             └── track ── answer ──┘
+ *
+ * Every track is given the same input and none can see another's answer. The
+ * answers come back as an array with one element per track, in declaration
+ * order, nulls included — a track that stopped leaves a hole, so position still
+ * names the track that produced it.
+ *
+ * `run` says whether that happens one at a time (the default) or all at once.
+ * Two tracks writing to the same place are a race the moment they overlap, so
+ * concurrency is asked for rather than discovered.
+ *
+ * `reduce` is a pipeline, given `{ input, results }` — the value the tracks ran
+ * on and what they answered. Carrying on as though the tracks were side effects
+ * is `{"=": "params.input"}`. With no reducer the answers travel on as they
+ * are, and a reducer returning null stops the pipeline as any service does.
+ *
+ * Matches `tracks` in hkp-node, hkp-python and hkp-rt.
+ */
+
+import {
+  AppImpl,
+  ProcessContext,
+  RuntimeClassType,
+  ServiceClass,
+  ServiceInstance,
+} from "hkp-frontend/src/types";
+import { nestedRun } from "hkp-frontend/src/runtime/processContext";
+import ServiceBase from "./ServiceBase";
+import BrowserRegistry from "../BrowserRegistry";
+import BrowserRuntimeScope from "../BrowserRuntimeScope";
+import { addService, configureService } from "../BrowserRuntimeApi";
+import { joinAddress, splitAddress } from "../../board/address";
+
+const serviceId = "tracks";
+const serviceName = "Tracks";
+
+/** The name the reducer answers to; a track may not take it. */
+const REDUCE = "reduce";
+
+type PipelineEntry = {
+  serviceId: string;
+  instanceId: string;
+  serviceName?: string;
+  state?: Record<string, any>;
+};
+
+type TrackState = {
+  name: string;
+  bypass?: boolean;
+  pipeline: PipelineEntry[];
+};
+
+type State = {
+  run: "serial" | "parallel";
+  tracks: TrackState[];
+  reduce: PipelineEntry[];
+};
+
+export class BrowserTracks extends ServiceBase<State> {
+  /** One live scope per track, plus the reducer's, keyed by track name. */
+  private _scopes = new Map<string, BrowserRuntimeScope>();
+  /** Guards against a stale build finishing after a newer configure. */
+  private _generation = 0;
+  private _building: Promise<void> | null = null;
+
+  constructor(app: AppImpl, board: string, descriptor: ServiceClass, id: string) {
+    super(app, board, descriptor, id, { run: "serial", tracks: [], reduce: [] });
+  }
+
+  configure(
+    config: Partial<State> & {
+      bypass?: boolean;
+      track?: string;
+      pipeline?: PipelineEntry[];
+      appendService?: PipelineEntry;
+      removeService?: string;
+      configureService?: { instanceId: string; state: Record<string, any> };
+    },
+  ): void {
+    // An edit naming a track is about one pipeline under this service rather
+    // than about the service; without it there is no way to say which.
+    if (typeof config.track === "string") {
+      this._configureTrack(config.track, config);
+      return;
+    }
+
+    let changed = false;
+
+    if (config.run === "serial" || config.run === "parallel") {
+      this.state.run = config.run;
+      changed = true;
+    }
+    if (Array.isArray(config.tracks)) {
+      this.state.tracks = config.tracks.map((track, index) => ({
+        name: typeof track?.name === "string" && track.name ? track.name : `${index}`,
+        ...(track?.bypass ? { bypass: true } : {}),
+        pipeline: normalize(track?.pipeline),
+      }));
+      changed = true;
+    }
+    if (Array.isArray(config.reduce)) {
+      this.state.reduce = normalize(config.reduce);
+      changed = true;
+    }
+    if (typeof config.bypass === "boolean") {
+      this.setBypass(config.bypass);
+    }
+
+    if (changed) {
+      this._rebuild();
+      this.app.notify(this as any, {
+        tracks: this.state.tracks,
+        reduce: this.state.reduce,
+        run: this.state.run,
+      });
+    }
+  }
+
+  async process(input: any): Promise<any> {
+    if (this.bypass || this.state.tracks.length === 0) {
+      return input;
+    }
+    // Before anything is awaited: the run this call is in is only this call's
+    // until it gives up control.
+    const run = this.app.currentContext?.(this);
+    if (this._building) {
+      await this._building;
+    }
+
+    const results =
+      this.state.run === "parallel"
+        ? await Promise.all(
+            this.state.tracks.map((track) => this._runTrack(track, input, run)),
+          )
+        : await this._serially(input, run);
+
+    const reducer = this._scopes.get(REDUCE);
+    if (!reducer || this.state.reduce.length === 0) {
+      return results;
+    }
+    return reducer.next(null, { input, results }, nestedRun(run), false, false);
+  }
+
+  /** Ends every pass running inside any track or the reduce. */
+  cancelInFlight(): void {
+    for (const scope of this._scopes.values()) {
+      scope.cancelInFlight();
+    }
+  }
+
+  /**
+   * The live instance of a nested service, wherever it sits.
+   *
+   * Asked by instance id alone, because that is what a panel has: which track a
+   * service belongs to is this service's business, not the panel's.
+   */
+  getInnerInstance(instanceId: string): ServiceInstance | null {
+    for (const scope of this._scopes.values()) {
+      const found = scope.findServiceInstance(instanceId)[0];
+      if (found) {
+        return found;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Whether every track and the reduce have been built, so that what runs
+   * inside them can be found — and listened to — by its scoped address.
+   */
+  isScopeBuilt(): boolean {
+    const declared = [
+      ...this.state.tracks
+        .filter((track) => track.pipeline.length > 0)
+        .map((track) => track.name),
+      ...(this.state.reduce.length > 0 ? [REDUCE] : []),
+    ];
+    return declared.every((name) => this._scopes.has(name));
+  }
+
+  /**
+   * The service a scoped address names inside one of the tracks or the
+   * reduce, however deep.
+   *
+   * The address runs through services, not tracks — `<tracks>.<instanceId>`,
+   * the same address this service's notifications are forwarded under — so a
+   * facade reading a request inside a track listens where it reports.
+   */
+  findNested(address: string): ServiceInstance | null {
+    const segments = splitAddress(address);
+    if (segments.length === 0) {
+      return null;
+    }
+    const here = this.getInnerInstance(segments[0]);
+    if (!here || segments.length === 1) {
+      return segments.length === 1 ? here : null;
+    }
+    const deeper = here as unknown as BrowserTracks;
+    return typeof deeper.findNested === "function"
+      ? deeper.findNested(segments.slice(1).join("."))
+      : null;
+  }
+
+  /**
+   * What a board keeps of the tracks: each pipeline as its services are now.
+   *
+   * A service inside can be configured by its scoped address without going
+   * through this one, so the stored pipelines alone would save what the
+   * services were built with rather than what they were changed to since.
+   * Each entry is read from its own track's scope: two tracks may hold a
+   * service under the same id, and one must not be saved with the other's.
+   */
+  getConfiguration = async (): Promise<Partial<State> & { bypass: boolean }> => {
+    const current = (scopeName: string, pipeline: PipelineEntry[]) =>
+      Promise.all(
+        pipeline.map(async (entry) => {
+          const live = this._scopes
+            .get(scopeName)
+            ?.findServiceInstance(entry.instanceId)[0] as any;
+          if (!live?.getConfiguration) {
+            return entry;
+          }
+          return { ...entry, state: await live.getConfiguration() };
+        }),
+      );
+    const tracks = await Promise.all(
+      this.state.tracks.map(async (track) => ({
+        ...track,
+        pipeline: await current(track.name, track.pipeline),
+      })),
+    );
+    return {
+      ...this.state,
+      tracks,
+      reduce: await current(REDUCE, this.state.reduce),
+      bypass: this.bypass,
+    };
+  };
+
+  destroy(): void {
+    // Ends what runs inside, not only the references: see dispose.
+    this._scopes.forEach((scope) => void scope.dispose());
+    this._scopes.clear();
+    this._generation++;
+    this._building = null;
+  }
+
+  // -------------------------------------------------------------------------
+
+  /** Applies a pipeline edit to one track, or to the reducer. */
+  private _configureTrack(
+    name: string,
+    config: {
+      bypass?: boolean;
+      pipeline?: PipelineEntry[];
+      appendService?: PipelineEntry;
+      removeService?: string;
+      configureService?: { instanceId: string; state: Record<string, any> };
+    },
+  ): void {
+    const track =
+      name === REDUCE ? null : this.state.tracks.find((t) => t.name === name);
+    if (name !== REDUCE && !track) {
+      return;
+    }
+    const current = () => (track ? track.pipeline : this.state.reduce);
+    const replace = (pipeline: PipelineEntry[]) => {
+      if (track) {
+        track.pipeline = pipeline;
+      } else {
+        this.state.reduce = pipeline;
+      }
+    };
+
+    if (typeof config.bypass === "boolean" && track) {
+      track.bypass = config.bypass;
+    }
+
+    if (Array.isArray(config.pipeline)) {
+      replace(normalize(config.pipeline));
+    } else if (config.appendService) {
+      replace([...current(), ...normalize([config.appendService])]);
+    } else if (typeof config.removeService === "string") {
+      replace(current().filter((e) => e.instanceId !== config.removeService));
+    } else if (config.configureService) {
+      const { instanceId, state } = config.configureService;
+      const live = this.getInnerInstance(instanceId);
+      if (live?.configure) {
+        // The instance is running: hand it the raw config so command-shaped
+        // edits keep their meaning instead of being merged in as inert state.
+        live.configure(state);
+        Promise.resolve(
+          live.getConfiguration ? live.getConfiguration() : (live as any).state,
+        ).then((updated) => {
+          replace(
+            current().map((e) =>
+              e.instanceId === instanceId ? { ...e, state: updated } : e,
+            ),
+          );
+          this.app.notify(this as any, { __innerScopeReady: true });
+        });
+        return;
+      }
+      replace(
+        current().map((e) =>
+          e.instanceId === instanceId
+            ? { ...e, state: { ...e.state, ...state } }
+            : e,
+        ),
+      );
+    }
+
+    this._rebuild();
+    this.app.notify(this as any, {
+      tracks: this.state.tracks,
+      reduce: this.state.reduce,
+      run: this.state.run,
+    });
+  }
+
+  private async _serially(
+    input: any,
+    run: ProcessContext | undefined,
+  ): Promise<any[]> {
+    const results: any[] = [];
+    for (const track of this.state.tracks) {
+      results.push(await this._runTrack(track, input, run));
+    }
+    return results;
+  }
+
+  /**
+   * One track's answer, or null where it has none. A track that throws is
+   * reported and leaves a hole rather than taking the others down with it.
+   */
+  private async _runTrack(
+    track: TrackState,
+    input: any,
+    run: ProcessContext | undefined,
+  ): Promise<any> {
+    const scope = this._scopes.get(track.name);
+    if (track.bypass || !scope || track.pipeline.length === 0) {
+      return null;
+    }
+    try {
+      // Collected for the reduce, so not reported through onResult as well.
+      return await scope.next(null, input, nestedRun(run), false, false);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.pushErrorNotification(`track '${track.name}' failed: ${message}`);
+      return null;
+    }
+  }
+
+  private _rebuild(): void {
+    const generation = ++this._generation;
+    this._scopes.forEach((scope) => void scope.dispose());
+    this._scopes.clear();
+
+    this._building = (async () => {
+      const built = new Map<string, BrowserRuntimeScope>();
+      for (const track of this.state.tracks) {
+        built.set(track.name, await this._buildScope(track.name, track.pipeline));
+      }
+      if (this.state.reduce.length > 0) {
+        built.set(REDUCE, await this._buildScope(REDUCE, this.state.reduce));
+      }
+      if (generation !== this._generation) {
+        // Superseded by a newer configure().
+        built.forEach((scope) => void scope.dispose());
+        return;
+      }
+      this._scopes = built;
+      this.app.notify(this as any, { __innerScopeReady: true });
+    })();
+  }
+
+  private async _buildScope(
+    label: string,
+    pipeline: PipelineEntry[],
+  ): Promise<BrowserRuntimeScope> {
+    const scope = new BrowserRuntimeScope(
+      {
+        id: `${this.uuid}:${label}`,
+        name: `${serviceName}:${label}`,
+        type: "browser" as RuntimeClassType,
+      },
+      new BrowserRegistry(),
+    );
+    // The board's assets, as the runtime around this pipeline sees them.
+    scope.assets = () => this.app.assets?.() ?? [];
+    // And whoever is signed in to the app around it is signed in here.
+    scope.delegateIdentity(() => this.app.getAuthenticatedUser?.() ?? null);
+
+    // A service inside a track that emits without being called — a Timer tick,
+    // a socket — has its own answer to give; it leaves by the same door this
+    // service's output does.
+    scope.onResult = async (_instanceId, result, context) => {
+      if (result !== null && result !== undefined) {
+        // In the run it was produced in, as a SubService hands it on.
+        this.app.next(this, result, { run: context });
+      }
+    };
+
+    // Notifications from inside reach the outer app under a scoped address,
+    // as a SubService forwards them: an instanceId is unique only inside its
+    // own pipeline, so outside it names nothing — and whoever listens for a
+    // nested service (the overview) listens at `<tracks>.<instanceId>`. The
+    // track's name is not part of the path; an address runs through services,
+    // and a track is a pipeline of this one. An inner scope has already
+    // prefixed its own, so nesting deeper composes the same way.
+    const outerNotify = this.app.notify.bind(this.app);
+    const innerNotify = scope.app.notify.bind(scope.app);
+    scope.app.notify = (svc: any, notification: any) => {
+      innerNotify(svc, notification);
+      // A scope being let go of says nothing more outside; see dispose.
+      if (scope.isDisposing) {
+        return;
+      }
+      outerNotify(
+        { ...svc, address: joinAddress(this.uuid, svc.address ?? svc.uuid) },
+        notification,
+      );
+    };
+
+    for (const entry of pipeline) {
+      const descriptor = await addService(
+        scope,
+        { serviceId: entry.serviceId, serviceName: entry.serviceName ?? entry.serviceId },
+        entry.instanceId,
+      );
+      if (descriptor && entry.state) {
+        await configureService(scope, descriptor, entry.state);
+      }
+    }
+
+    return scope;
+  }
+}
+
+function normalize(pipeline: unknown): PipelineEntry[] {
+  if (!Array.isArray(pipeline)) {
+    return [];
+  }
+  return pipeline.map((entry: any) => ({
+    serviceId: entry.serviceId,
+    instanceId: entry.instanceId || entry.uuid || crypto.randomUUID(),
+    ...(entry.serviceName ? { serviceName: entry.serviceName } : {}),
+    ...(entry.state ? { state: entry.state } : {}),
+  }));
+}
+
+const descriptor = {
+  serviceName,
+  serviceId,
+  create: (app: AppImpl, board: string, cls: ServiceClass, id: string) =>
+    new BrowserTracks(app, board, cls, id),
+};
+
+export default descriptor;

package/bundle/hkp-frontend/src/runtime/browser/services/Buffer.ts

@@ -0,0 +1,11 @@
+import BufferDescriptor from "hkp-frontend/src/runtime/browser/services/base/Buffer";
+import { AppImpl, ServiceClass } from "hkp-frontend/src/types";
+
+const descriptor = {
+  serviceName: BufferDescriptor.serviceName,
+  serviceId: BufferDescriptor.serviceId,
+  create: (app: AppImpl, board: string, service: ServiceClass, id: string) =>
+    new BufferDescriptor.service(app, board, service, id),
+};
+
+export default descriptor;