space-data-module-sdk 0.5.22 → 0.6.1

package/src/host/isomorphicLoader.js

@@ -13,11 +13,26 @@ import {
   createBrowserModuleHarness,
   detectArtifactProfile,
 } from "../testing/browserModuleHarness.js";
+import { createAsyncHostDispatcher } from "./abi.js";
 
 const isBrowser =
   typeof globalThis.window !== "undefined" &&
   typeof globalThis.document !== "undefined";
 
+function attachHostDispatch(harness, host) {
+  if (!host || typeof host !== "object") {
+    return harness;
+  }
+  const dispatchHost = createAsyncHostDispatcher(host);
+  return {
+    ...harness,
+    host,
+    async callHost(operation, params = {}) {
+      return dispatchHost(operation, params);
+    },
+  };
+}
+
 async function createWasmEdgeCommandHarness(options = {}) {
   const [
     { spawn },
@@ -175,14 +190,18 @@ export async function loadModule(options = {}) {
         (inspection.profile === "standalone" || inspection.profile === "sdn-abi") &&
         inspection.exports.includes("_start")
       ) {
-        return createWasmEdgeCommandHarness(options);
+        return attachHostDispatch(
+          await createWasmEdgeCommandHarness(options),
+          options.host ?? null,
+        );
       }
     }
 
-    return createModuleHarness({
-      runtime: {
-        kind: "wasmedge",
-        wasmPath: source,
+    return attachHostDispatch(
+      await createModuleHarness({
+        runtime: {
+          kind: "wasmedge",
+          wasmPath: source,
         wasmEdgeBinary: options.wasmEdgeBinary,
         wasmEdgeRunnerBinary: options.wasmEdgeRunnerBinary,
         enableThreads: options.enableThreads,
@@ -191,23 +210,28 @@ export async function loadModule(options = {}) {
         hostProfile: options.hostProfile,
         modules: options.modules,
         defaultModuleId: options.defaultModuleId,
-        metadata: options.metadata,
-      },
-    });
+          metadata: options.metadata,
+        },
+      }),
+      options.host ?? null,
+    );
   }
 
-  return createModuleHarness({
-    runtime: {
-      kind: runtimeKind,
-      command: options.command ?? runtimeKind,
-      args: options.args ?? [source],
-      env: options.env,
-      cwd: options.cwd,
-      hostProfile: options.hostProfile,
-      modules: options.modules,
-      defaultModuleId: options.defaultModuleId,
-    },
-  });
+  return attachHostDispatch(
+    await createModuleHarness({
+      runtime: {
+        kind: runtimeKind,
+        command: options.command ?? runtimeKind,
+        args: options.args ?? [source],
+        env: options.env,
+        cwd: options.cwd,
+        hostProfile: options.hostProfile,
+        modules: options.modules,
+        defaultModuleId: options.defaultModuleId,
+      },
+    }),
+    options.host ?? null,
+  );
 }
 
 /**

package/src/host/nodeHost.js

@@ -46,10 +46,14 @@ export const NodeHostSupportedCapabilities = Object.freeze([
   "http",
   "websocket",
   "mqtt",
+  "network",
   "filesystem",
   "tcp",
   "udp",
   "tls",
+  "ipfs",
+  "protocol_handle",
+  "protocol_dial",
   "context_read",
   "context_write",
   "crypto_hash",
@@ -59,6 +63,7 @@ export const NodeHostSupportedCapabilities = Object.freeze([
   "crypto_decrypt",
   "crypto_key_agreement",
   "crypto_kdf",
+  "wallet_sign",
   "process_exec",
 ]);
 
@@ -75,6 +80,7 @@ export const NodeHostSupportedOperations = Object.freeze([
   "websocket.exchange",
   "mqtt.publish",
   "mqtt.subscribeOnce",
+  "network.request",
   "filesystem.resolvePath",
   "filesystem.readFile",
   "filesystem.writeFile",
@@ -87,6 +93,14 @@ export const NodeHostSupportedOperations = Object.freeze([
   "tcp.request",
   "udp.request",
   "tls.request",
+  "ipfs.invoke",
+  "ipfs.add",
+  "ipfs.cat",
+  "protocol_handle.register",
+  "protocol_handle.unregister",
+  "protocol_dial.dial",
+  "protocol.request",
+  "keyslot.get",
   "exec.execFile",
   "context.get",
   "context.set",
@@ -151,6 +165,34 @@ function normalizeGrantedCapabilities(options) {
   return normalized;
 }
 
+function resolveCapabilityAdapters(options = {}) {
+  const adapters =
+    options.capabilityAdapters && typeof options.capabilityAdapters === "object"
+      ? options.capabilityAdapters
+      : {};
+  return {
+    filesystem: options.filesystem ?? adapters.filesystem ?? null,
+    network: options.network ?? adapters.network ?? null,
+    ipfs: options.ipfs ?? adapters.ipfs ?? null,
+    walletSign:
+      options.walletSign ??
+      adapters.walletSign ??
+      adapters.wallet_sign ??
+      adapters.keyslot ??
+      null,
+    protocolHandle:
+      options.protocolHandle ??
+      adapters.protocolHandle ??
+      adapters.protocol_handle ??
+      null,
+    protocolDial:
+      options.protocolDial ??
+      adapters.protocolDial ??
+      adapters.protocol_dial ??
+      null,
+  };
+}
+
 function normalizeAllowedOrigins(origins) {
   if (origins === undefined || origins === null) {
     return null;
@@ -229,6 +271,45 @@ function normalizeAllowedPorts(ports, label, { allowZero = false } = {}) {
   return normalized;
 }
 
+function normalizeNetworkTransport(params = {}) {
+  const explicit = String(
+    params.transport ?? params.kind ?? params.request?.transport ?? "",
+  )
+    .trim()
+    .toLowerCase();
+  if (explicit) {
+    return explicit;
+  }
+  const candidateUrl = params.url ?? params.request?.url ?? null;
+  if (candidateUrl) {
+    const protocol = new URL(candidateUrl).protocol.toLowerCase();
+    if (protocol === "http:" || protocol === "https:") {
+      return "http";
+    }
+    if (protocol === "ws:" || protocol === "wss:") {
+      return "websocket";
+    }
+  }
+  throw new Error(
+    'network.request requires a transport value such as "http", "tcp", or "websocket".',
+  );
+}
+
+async function invokeAdapterMethod(adapter, methodName, params, label) {
+  if (!adapter || typeof adapter !== "object") {
+    throw new Error(`${label} adapter is not configured for this host.`);
+  }
+  if (typeof adapter[methodName] === "function") {
+    return adapter[methodName](params);
+  }
+  if (typeof adapter.invoke === "function") {
+    return adapter.invoke(methodName, params);
+  }
+  throw new Error(
+    `${label} adapter does not implement "${methodName}" or invoke().`,
+  );
+}
+
 function normalizeFilesystemRoot(rootPath) {
   return path.resolve(String(rootPath ?? process.cwd()));
 }
@@ -1397,6 +1478,13 @@ export class NodeHost {
     );
     this.fetch = options.fetch ?? globalThis.fetch;
     this.WebSocket = options.WebSocket ?? globalThis.WebSocket;
+    const capabilityAdapters = resolveCapabilityAdapters(options);
+    this._filesystemAdapter = capabilityAdapters.filesystem;
+    this._networkAdapter = capabilityAdapters.network;
+    this._ipfsAdapter = capabilityAdapters.ipfs;
+    this._walletSignAdapter = capabilityAdapters.walletSign;
+    this._protocolHandleAdapter = capabilityAdapters.protocolHandle;
+    this._protocolDialAdapter = capabilityAdapters.protocolDial;
     if (typeof this.fetch !== "function") {
       throw new TypeError(
         "A fetch implementation is required to create a Node host.",
@@ -1550,6 +1638,121 @@ export class NodeHost {
         }),
     });
 
+    this.network = Object.freeze({
+      request: async (params = {}) =>
+        this.#withCapability("network", "network.request", async () => {
+          const transport = normalizeNetworkTransport(params);
+          const request = params.request ?? params;
+          if (this._networkAdapter) {
+            return invokeAdapterMethod(this._networkAdapter, "request", {
+              ...request,
+              transport,
+            }, "network");
+          }
+          switch (transport) {
+            case "http":
+              return this.http.request(request);
+            case "websocket":
+              return this.websocket.exchange(request);
+            case "mqtt":
+              return request.subscribe === true
+                ? this.mqtt.subscribeOnce(request)
+                : this.mqtt.publish(request);
+            case "tcp":
+              return this.tcp.request(request);
+            case "udp":
+              return this.udp.request(request);
+            case "tls":
+              return this.tls.request(request);
+            default:
+              throw new Error(
+                `Node host does not support network transport "${transport}".`,
+              );
+          }
+        }),
+    });
+
+    const builtinFilesystem = {
+      resolvePath: (targetPath) => this.#resolveFilesystemPath(targetPath),
+      readFile: async (targetPath, options = {}) => {
+        const resolvedPath = this.#resolveFilesystemPath(targetPath);
+        const file = await readFile(resolvedPath);
+        if (options.encoding) {
+          return file.toString(options.encoding);
+        }
+        return new Uint8Array(file);
+      },
+      writeFile: async (targetPath, value, options = {}) => {
+        const resolvedPath = this.#resolveFilesystemPath(targetPath);
+        await mkdir(path.dirname(resolvedPath), { recursive: true });
+        await writeFile(
+          resolvedPath,
+          typeof value === "string" ? value : Buffer.from(toUint8Array(value)),
+          options.encoding && typeof value === "string" ? options.encoding : undefined,
+        );
+        return { path: resolvedPath };
+      },
+      appendFile: async (targetPath, value, options = {}) => {
+        const resolvedPath = this.#resolveFilesystemPath(targetPath);
+        await mkdir(path.dirname(resolvedPath), { recursive: true });
+        const existing = await readFile(resolvedPath).catch((error) => {
+          if (error?.code === "ENOENT") {
+            return Buffer.alloc(0);
+          }
+          throw error;
+        });
+        const nextChunk =
+          typeof value === "string"
+            ? Buffer.from(value, options.encoding ?? "utf8")
+            : Buffer.from(toUint8Array(value));
+        await writeFile(resolvedPath, Buffer.concat([existing, nextChunk]));
+        return { path: resolvedPath };
+      },
+      deleteFile: async (targetPath) => {
+        const resolvedPath = this.#resolveFilesystemPath(targetPath);
+        await rm(resolvedPath, { force: true });
+        return { path: resolvedPath };
+      },
+      mkdir: async (targetPath, options = {}) => {
+        const resolvedPath = this.#resolveFilesystemPath(targetPath);
+        await mkdir(resolvedPath, {
+          recursive: options.recursive ?? true,
+        });
+        return { path: resolvedPath };
+      },
+      readdir: async (targetPath = ".") => {
+        const resolvedPath = this.#resolveFilesystemPath(targetPath);
+        const entries = await readdir(resolvedPath, { withFileTypes: true });
+        return entries
+          .map((entry) => ({
+            name: entry.name,
+            isFile: entry.isFile(),
+            isDirectory: entry.isDirectory(),
+          }))
+          .sort((left, right) => left.name.localeCompare(right.name));
+      },
+      stat: async (targetPath) => {
+        const resolvedPath = this.#resolveFilesystemPath(targetPath);
+        const metadata = await stat(resolvedPath);
+        return {
+          path: resolvedPath,
+          size: metadata.size,
+          isFile: metadata.isFile(),
+          isDirectory: metadata.isDirectory(),
+          ctimeMs: metadata.ctimeMs,
+          mtimeMs: metadata.mtimeMs,
+        };
+      },
+      rename: async (fromPath, toPath) => {
+        const resolvedFrom = this.#resolveFilesystemPath(fromPath);
+        const resolvedTo = this.#resolveFilesystemPath(toPath);
+        await mkdir(path.dirname(resolvedTo), { recursive: true });
+        await rename(resolvedFrom, resolvedTo);
+        return { from: resolvedFrom, to: resolvedTo };
+      },
+    };
+    const filesystem = this._filesystemAdapter ?? builtinFilesystem;
+
     this.mqtt = Object.freeze({
       publish: async (mqttOptions = {}) =>
         this.#withCapability("mqtt", "mqtt.publish", async () => {
@@ -1601,91 +1804,39 @@ export class NodeHost {
     this.filesystem = Object.freeze({
       resolvePath: (targetPath) =>
         this.#withCapability("filesystem", "filesystem.resolvePath", () =>
-          this.#resolveFilesystemPath(targetPath),
+          filesystem.resolvePath(targetPath),
         ),
       readFile: async (targetPath, options = {}) =>
         this.#withCapability("filesystem", "filesystem.readFile", async () => {
-          const resolvedPath = this.#resolveFilesystemPath(targetPath);
-          const file = await readFile(resolvedPath);
-          if (options.encoding) {
-            return file.toString(options.encoding);
-          }
-          return new Uint8Array(file);
+          return filesystem.readFile(targetPath, options);
         }),
       writeFile: async (targetPath, value, options = {}) =>
         this.#withCapability("filesystem", "filesystem.writeFile", async () => {
-          const resolvedPath = this.#resolveFilesystemPath(targetPath);
-          await mkdir(path.dirname(resolvedPath), { recursive: true });
-          await writeFile(
-            resolvedPath,
-            typeof value === "string" ? value : Buffer.from(toUint8Array(value)),
-            options.encoding && typeof value === "string" ? options.encoding : undefined,
-          );
-          return { path: resolvedPath };
+          return filesystem.writeFile(targetPath, value, options);
         }),
       appendFile: async (targetPath, value, options = {}) =>
         this.#withCapability("filesystem", "filesystem.appendFile", async () => {
-          const resolvedPath = this.#resolveFilesystemPath(targetPath);
-          await mkdir(path.dirname(resolvedPath), { recursive: true });
-          const existing = await readFile(resolvedPath).catch((error) => {
-            if (error?.code === "ENOENT") {
-              return Buffer.alloc(0);
-            }
-            throw error;
-          });
-          const nextChunk =
-            typeof value === "string"
-              ? Buffer.from(value, options.encoding ?? "utf8")
-              : Buffer.from(toUint8Array(value));
-          await writeFile(resolvedPath, Buffer.concat([existing, nextChunk]));
-          return { path: resolvedPath };
+          return filesystem.appendFile(targetPath, value, options);
         }),
       deleteFile: async (targetPath) =>
         this.#withCapability("filesystem", "filesystem.deleteFile", async () => {
-          const resolvedPath = this.#resolveFilesystemPath(targetPath);
-          await rm(resolvedPath, { force: true });
-          return { path: resolvedPath };
+          return filesystem.deleteFile(targetPath);
         }),
       mkdir: async (targetPath, options = {}) =>
         this.#withCapability("filesystem", "filesystem.mkdir", async () => {
-          const resolvedPath = this.#resolveFilesystemPath(targetPath);
-          await mkdir(resolvedPath, {
-            recursive: options.recursive ?? true,
-          });
-          return { path: resolvedPath };
+          return filesystem.mkdir(targetPath, options);
         }),
       readdir: async (targetPath = ".") =>
         this.#withCapability("filesystem", "filesystem.readdir", async () => {
-          const resolvedPath = this.#resolveFilesystemPath(targetPath);
-          const entries = await readdir(resolvedPath, { withFileTypes: true });
-          return entries
-            .map((entry) => ({
-              name: entry.name,
-              isFile: entry.isFile(),
-              isDirectory: entry.isDirectory(),
-            }))
-            .sort((left, right) => left.name.localeCompare(right.name));
+          return filesystem.readdir(targetPath);
         }),
       stat: async (targetPath) =>
         this.#withCapability("filesystem", "filesystem.stat", async () => {
-          const resolvedPath = this.#resolveFilesystemPath(targetPath);
-          const metadata = await stat(resolvedPath);
-          return {
-            path: resolvedPath,
-            size: metadata.size,
-            isFile: metadata.isFile(),
-            isDirectory: metadata.isDirectory(),
-            ctimeMs: metadata.ctimeMs,
-            mtimeMs: metadata.mtimeMs,
-          };
+          return filesystem.stat(targetPath);
         }),
       rename: async (fromPath, toPath) =>
         this.#withCapability("filesystem", "filesystem.rename", async () => {
-          const resolvedFrom = this.#resolveFilesystemPath(fromPath);
-          const resolvedTo = this.#resolveFilesystemPath(toPath);
-          await mkdir(path.dirname(resolvedTo), { recursive: true });
-          await rename(resolvedFrom, resolvedTo);
-          return { from: resolvedFrom, to: resolvedTo };
+          return filesystem.rename(fromPath, toPath);
         }),
     });
 
@@ -1825,6 +1976,80 @@ export class NodeHost {
           this._contextStore.listScopes(),
         ),
     });
+
+    this.ipfs = Object.freeze({
+      invoke: async (params = {}) =>
+        this.#withCapability("ipfs", "ipfs.invoke", async () => {
+          const operation = String(params.operation ?? "invoke").trim();
+          if (!operation) {
+            throw new Error("ipfs.invoke requires a non-empty operation.");
+          }
+          return invokeAdapterMethod(this._ipfsAdapter, operation, params, "ipfs");
+        }),
+      add: async (params = {}) =>
+        this.#withCapability("ipfs", "ipfs.add", async () =>
+          invokeAdapterMethod(this._ipfsAdapter, "add", params, "ipfs"),
+        ),
+      cat: async (params = {}) =>
+        this.#withCapability("ipfs", "ipfs.cat", async () =>
+          invokeAdapterMethod(this._ipfsAdapter, "cat", params, "ipfs"),
+        ),
+    });
+
+    this.protocolHandle = Object.freeze({
+      register: async (params = {}) =>
+        this.#withCapability(
+          "protocol_handle",
+          "protocol_handle.register",
+          async () =>
+            invokeAdapterMethod(
+              this._protocolHandleAdapter,
+              "register",
+              params,
+              "protocol_handle",
+            ),
+        ),
+      unregister: async (params = {}) =>
+        this.#withCapability(
+          "protocol_handle",
+          "protocol_handle.unregister",
+          async () =>
+            invokeAdapterMethod(
+              this._protocolHandleAdapter,
+              "unregister",
+              params,
+              "protocol_handle",
+            ),
+        ),
+    });
+
+    this.protocolDial = Object.freeze({
+      dial: async (params = {}) =>
+        this.#withCapability("protocol_dial", "protocol_dial.dial", async () =>
+          invokeAdapterMethod(
+            this._protocolDialAdapter,
+            "dial",
+            params,
+            "protocol_dial",
+          ),
+        ),
+      request: async (params = {}) =>
+        this.#withCapability("protocol_dial", "protocol.request", async () =>
+          invokeAdapterMethod(
+            this._protocolDialAdapter,
+            "request",
+            params,
+            "protocol_dial",
+          ),
+        ),
+    });
+
+    this.keyslot = Object.freeze({
+      get: async (params = {}) =>
+        this.#withCapability("wallet_sign", "keyslot.get", async () =>
+          invokeAdapterMethod(this._walletSignAdapter, "get", params, "wallet_sign"),
+        ),
+    });
   }
 
   listCapabilities() {
@@ -1840,11 +2065,26 @@ export class NodeHost {
   }
 
   hasCapability(capability) {
-    return this._grantedCapabilities.has(String(capability ?? "").trim());
+    const normalized = String(capability ?? "").trim();
+    return (
+      this._grantedCapabilities.has(normalized) ||
+      (this._grantedCapabilities.has("network") &&
+        ["http", "websocket", "mqtt", "tcp", "udp", "tls"].includes(
+          normalized,
+        ))
+    );
   }
 
   assertCapability(capability, operation = null) {
     const normalized = assertNonEmptyString(capability, "Capability id");
+    const networkBackedCapabilities = new Set([
+      "http",
+      "websocket",
+      "mqtt",
+      "tcp",
+      "udp",
+      "tls",
+    ]);
     if (!this._supportedCapabilities.has(normalized)) {
       throw new HostCapabilityError(
         `Capability "${normalized}" is not supported by the reference Node host.`,
@@ -1855,7 +2095,13 @@ export class NodeHost {
         },
       );
     }
-    if (!this._grantedCapabilities.has(normalized)) {
+    if (
+      !this._grantedCapabilities.has(normalized) &&
+      !(
+        this._grantedCapabilities.has("network") &&
+        networkBackedCapabilities.has(normalized)
+      )
+    ) {
       throw new HostCapabilityError(
         `Capability "${normalized}" is not granted for this Node host.`,
         {
@@ -1871,6 +2117,16 @@ export class NodeHost {
   async invoke(operation, params = {}) {
     const normalized = assertNonEmptyString(operation, "Host operation");
     switch (normalized) {
+      case "host.runtimeTarget":
+        return this.runtimeTarget;
+      case "host.listCapabilities":
+        return this.listCapabilities();
+      case "host.listSupportedCapabilities":
+        return this.listSupportedCapabilities();
+      case "host.listOperations":
+        return this.listOperations();
+      case "host.hasCapability":
+        return this.hasCapability(params.capability);
       case "clock.now":
         return this.clock.now();
       case "clock.monotonicNow":
@@ -1897,6 +2153,8 @@ export class NodeHost {
         return this.mqtt.publish(params);
       case "mqtt.subscribeOnce":
         return this.mqtt.subscribeOnce(params);
+      case "network.request":
+        return this.network.request(params);
       case "filesystem.resolvePath":
         return this.filesystem.resolvePath(params.path);
       case "filesystem.readFile":
@@ -1929,6 +2187,22 @@ export class NodeHost {
         return this.udp.request(params);
       case "tls.request":
         return this.tls.request(params);
+      case "ipfs.invoke":
+        return this.ipfs.invoke(params);
+      case "ipfs.add":
+        return this.ipfs.add(params);
+      case "ipfs.cat":
+        return this.ipfs.cat(params);
+      case "protocol_handle.register":
+        return this.protocolHandle.register(params);
+      case "protocol_handle.unregister":
+        return this.protocolHandle.unregister(params);
+      case "protocol_dial.dial":
+        return this.protocolDial.dial(params);
+      case "protocol.request":
+        return this.protocolDial.request(params);
+      case "keyslot.get":
+        return this.keyslot.get(params);
       case "exec.execFile":
         return this.exec.execFile(params);
       case "context.get":