feat: Support instance context [fixes DXJ-541] (#392)

* Support context

* Update doc

* Refactor

* Cover by doc

* Fix lint

Author: Akim

README.md

@@ -164,6 +164,18 @@ localStorage.debug = "fluence:*";
 In Chromium-based web browsers (e.g. Brave, Chrome, and Electron), the JavaScript console will be default—only to show
 messages logged by debug if the "Verbose" log level is enabled.
 
+## Low level usage
+
+JS client also has an API for low level interaction with AVM and Marine JS.
+It could be handy in advanced scenarios when a user fetches AIR dynamically or generates AIR without default Aqua compiler.
+
+`callAquaFunction` Allows to call aqua function without schema.
+
+`registerService` Gives an ability to register service without schema. Passed `service` could be
+
+- Plain object. In this case all function properties will be registered as AIR service functions.
+- Class instance. All class methods without inherited ones will be registered as AIR service functions.
+
 ## Development
 
 To hack on the Fluence JS Client itself, please refer to the [development page](./DEVELOPING.md).

packages/core/js-client/aqua/calc.aqua

@@ -0,0 +1,16 @@
+service Calc("calc"):
+    add(n: f32)
+    subtract(n: f32)
+    multiply(n: f32)
+    divide(n: f32)
+    reset()
+    getResult() -> f32
+
+
+func demoCalc() -> f32:
+    Calc.add(10)
+    Calc.multiply(5)
+    Calc.subtract(8)
+    Calc.divide(6)
+    res <- Calc.getResult()
+    <- res

packages/core/js-client/src/api.spec.ts

@@ -0,0 +1,84 @@
+/**
+ * Copyright 2023 Fluence Labs Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { fileURLToPath } from "url";
+
+import { compileFromPath } from "@fluencelabs/aqua-api";
+import { ServiceDef } from "@fluencelabs/interfaces";
+import { describe, expect, it } from "vitest";
+
+import { v5_registerService } from "./api.js";
+import { callAquaFunction } from "./compilerSupport/callFunction.js";
+import { withPeer } from "./util/testUtils.js";
+
+class CalcParent {
+  protected _state: number = 0;
+
+  add(n: number) {
+    this._state += n;
+  }
+
+  subtract(n: number) {
+    this._state -= n;
+  }
+}
+
+class Calc extends CalcParent {
+  multiply(n: number) {
+    this._state *= n;
+  }
+
+  divide(n: number) {
+    this._state /= n;
+  }
+
+  reset() {
+    this._state = 0;
+  }
+
+  getResult() {
+    return this._state;
+  }
+}
+
+describe("User API methods", () => {
+  it("registers user class service and calls own and inherited methods correctly", async () => {
+    await withPeer(async (peer) => {
+      const calcService: Record<never, unknown> = new Calc();
+
+      const { functions, services } = await compileFromPath({
+        filePath: fileURLToPath(new URL("../aqua/calc.aqua", import.meta.url)),
+      });
+
+      const typedServices: Record<string, ServiceDef> = services;
+
+      const { script } = functions["demoCalc"];
+
+      v5_registerService([peer, "calc", calcService], {
+        defaultServiceId: "calc",
+        functions: typedServices["Calc"].functions,
+      });
+
+      const res = await callAquaFunction({
+        args: {},
+        peer,
+        script,
+      });
+
+      expect(res).toBe(7);
+    });
+  });
+});

packages/core/js-client/src/api.ts

@@ -202,10 +202,16 @@ export const v5_registerService = (
   // Schema for every function in service
   const serviceSchema = def.functions.tag === "nil" ? {} : def.functions.fields;
 
-  // Wrapping service impl to convert their args ts -> aqua and backwards
+  // Wrapping service functions, selecting only those listed in schema, to convert their args js -> aqua and backwards
   const wrappedServiceImpl = Object.fromEntries(
-    Object.entries(serviceImpl).map(([name, func]) => {
-      return [name, wrapJsFunction(func, serviceSchema[name])];
+    Object.keys(serviceSchema).map((schemaKey) => {
+      return [
+        schemaKey,
+        wrapJsFunction(
+          serviceImpl[schemaKey].bind(serviceImpl),
+          serviceSchema[schemaKey],
+        ),
+      ] as const;
     }),
   );
 

packages/core/js-client/src/compilerSupport/callFunction.ts

@@ -46,7 +46,7 @@ const log = logger("aqua");
 
 export type CallAquaFunctionArgs = {
   script: string;
-  config: CallAquaFunctionConfig | undefined;
+  config?: CallAquaFunctionConfig | undefined;
   peer: FluencePeer;
   args: { [key: string]: JSONValue | ArgCallbackFunction };
 };

packages/core/js-client/src/compilerSupport/registerService.ts

@@ -28,27 +28,22 @@ interface RegisterServiceArgs {
   service: ServiceImpl;
 }
 
+// This function iterates on plain object or class instance functions ignoring inherited functions and prototype chain.
 const findAllPossibleRegisteredServiceFunctions = (
   service: ServiceImpl,
-): Set<string> => {
-  let prototype: Record<string, unknown> = service;
-  const serviceMethods = new Set<string>();
+): Array<string> => {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const prototype = Object.getPrototypeOf(service) as ServiceImpl;
 
-  do {
-    Object.getOwnPropertyNames(prototype)
-      .filter((prop) => {
-        return typeof prototype[prop] === "function" && prop !== "constructor";
-      })
-      .forEach((prop) => {
-        return serviceMethods.add(prop);
-      });
+  const isClassInstance = prototype.constructor !== Object;
 
-    // coercing 'any' type to 'Record' bcs object prototype is actually an object
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    prototype = Object.getPrototypeOf(prototype) as Record<string, unknown>;
-  } while (prototype.constructor !== Object);
+  if (isClassInstance) {
+    service = prototype;
+  }
 
-  return serviceMethods;
+  return Object.getOwnPropertyNames(service).filter((prop) => {
+    return typeof service[prop] === "function" && prop !== "constructor";
+  });
 };
 
 export const registerService = ({

packages/core/js-client/src/ephemeral/__test__/ephemeral.spec.ts

@@ -14,13 +14,15 @@
  * limitations under the License.
  */
 
-import { it, describe, expect, beforeEach, afterEach } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { DEFAULT_CONFIG, FluencePeer } from "../../jsPeer/FluencePeer.js";
 import { ResultCodes } from "../../jsServiceHost/interfaces.js";
 import { KeyPair } from "../../keypair/index.js";
+import { loadMarineDeps } from "../../marine/loader.js";
+import { MarineBackgroundRunner } from "../../marine/worker/index.js";
 import { EphemeralNetworkClient } from "../client.js";
-import { EphemeralNetwork, defaultConfig } from "../network.js";
+import { defaultConfig, EphemeralNetwork } from "../network.js";
 
 let en: EphemeralNetwork;
 let client: FluencePeer;
@@ -33,7 +35,11 @@ describe.skip("Ephemeral networks tests", () => {
     await en.up();
 
     const kp = await KeyPair.randomEd25519();
-    client = new EphemeralNetworkClient(DEFAULT_CONFIG, kp, en, relay);
+
+    const marineDeps = await loadMarineDeps("/");
+    const marine = new MarineBackgroundRunner(...marineDeps);
+
+    client = new EphemeralNetworkClient(DEFAULT_CONFIG, kp, marine, en, relay);
     await client.start();
   });
 

packages/core/js-client/src/ephemeral/client.ts

@@ -15,13 +15,11 @@
  */
 
 import { PeerIdB58 } from "@fluencelabs/interfaces";
-import { fetchResource } from "@fluencelabs/js-client-isomorphic/fetcher";
-import { getWorker } from "@fluencelabs/js-client-isomorphic/worker-resolver";
 
 import { FluencePeer, PeerConfig } from "../jsPeer/FluencePeer.js";
 import { JsServiceHost } from "../jsServiceHost/JsServiceHost.js";
 import { KeyPair } from "../keypair/index.js";
-import { MarineBackgroundRunner } from "../marine/worker/index.js";
+import { IMarineHost } from "../marine/interfaces.js";
 
 import { EphemeralNetwork } from "./network.js";
 
@@ -32,63 +30,12 @@ export class EphemeralNetworkClient extends FluencePeer {
   constructor(
     config: PeerConfig,
     keyPair: KeyPair,
+    marine: IMarineHost,
     network: EphemeralNetwork,
     relay: PeerIdB58,
   ) {
     const conn = network.getRelayConnection(keyPair.getPeerId(), relay);
 
-    let marineJsWasm: ArrayBuffer;
-    let avmWasm: ArrayBuffer;
-
-    const marine = new MarineBackgroundRunner(
-      {
-        async getValue() {
-          // TODO: load worker in parallel with avm and marine, test that it works
-          return getWorker("@fluencelabs/marine-worker", "/");
-        },
-        start() {
-          return Promise.resolve(undefined);
-        },
-        stop() {
-          return Promise.resolve(undefined);
-        },
-      },
-      {
-        getValue() {
-          return marineJsWasm;
-        },
-        async start(): Promise<void> {
-          marineJsWasm = await fetchResource(
-            "@fluencelabs/marine-js",
-            "/dist/marine-js.wasm",
-            "/",
-          ).then((res) => {
-            return res.arrayBuffer();
-          });
-        },
-        stop(): Promise<void> {
-          return Promise.resolve(undefined);
-        },
-      },
-      {
-        getValue() {
-          return avmWasm;
-        },
-        async start(): Promise<void> {
-          avmWasm = await fetchResource(
-            "@fluencelabs/avm",
-            "/dist/avm.wasm",
-            "/",
-          ).then((res) => {
-            return res.arrayBuffer();
-          });
-        },
-        stop(): Promise<void> {
-          return Promise.resolve(undefined);
-        },
-      },
-    );
-
     super(config, keyPair, marine, new JsServiceHost(), conn);
   }
 }

packages/core/js-client/src/ephemeral/network.ts

@@ -15,15 +15,14 @@
  */
 
 import { PeerIdB58 } from "@fluencelabs/interfaces";
-import { fetchResource } from "@fluencelabs/js-client-isomorphic/fetcher";
-import { getWorker } from "@fluencelabs/js-client-isomorphic/worker-resolver";
 import { Subject } from "rxjs";
 
 import { IConnection } from "../connection/interfaces.js";
 import { DEFAULT_CONFIG, FluencePeer } from "../jsPeer/FluencePeer.js";
 import { JsServiceHost } from "../jsServiceHost/JsServiceHost.js";
 import { fromBase64Sk, KeyPair } from "../keypair/index.js";
 import { IMarineHost } from "../marine/interfaces.js";
+import { loadMarineDeps } from "../marine/loader.js";
 import { MarineBackgroundRunner } from "../marine/worker/index.js";
 import { Particle } from "../particle/Particle.js";
 import { logger } from "../util/logger.js";
@@ -233,55 +232,8 @@ export class EphemeralNetwork {
     const promises = this.config.peers.map(async (x) => {
       const kp = await fromBase64Sk(x.sk);
 
-      const [marineJsWasm, avmWasm] = await Promise.all([
-        fetchResource(
-          "@fluencelabs/marine-js",
-          "/dist/marine-js.wasm",
-          "/",
-        ).then((res) => {
-          return res.arrayBuffer();
-        }),
-        fetchResource("@fluencelabs/avm", "/dist/avm.wasm", "/").then((res) => {
-          return res.arrayBuffer();
-        }),
-      ]);
-
-      const marine = new MarineBackgroundRunner(
-        {
-          async getValue() {
-            // TODO: load worker in parallel with avm and marine, test that it works
-            return getWorker("@fluencelabs/marine-worker", "/");
-          },
-          start() {
-            return Promise.resolve(undefined);
-          },
-          stop() {
-            return Promise.resolve(undefined);
-          },
-        },
-        {
-          getValue() {
-            return marineJsWasm;
-          },
-          start(): Promise<void> {
-            return Promise.resolve(undefined);
-          },
-          stop(): Promise<void> {
-            return Promise.resolve(undefined);
-          },
-        },
-        {
-          getValue() {
-            return avmWasm;
-          },
-          start(): Promise<void> {
-            return Promise.resolve(undefined);
-          },
-          stop(): Promise<void> {
-            return Promise.resolve(undefined);
-          },
-        },
-      );
+      const marineDeps = await loadMarineDeps("/");
+      const marine = new MarineBackgroundRunner(...marineDeps);
 
       const peerId = kp.getPeerId();