@hara-lang/hta 0.1.9

package/provider-browser.mjs

@@ -0,0 +1,259 @@
+import { decodeHta, encodeHta, HtaKeyword } from "./index.js";
+import {
+  createProviderLifecycle,
+  HTA_PROVIDER_EVENT,
+  providerError,
+  providerErrorCode,
+  toHta
+} from "./provider-common.mjs";
+
+function errorFrom(value) {
+  if (value instanceof Error) return value;
+  if (value instanceof Map) {
+    let code = "host/error";
+    let message = "HTA host call failed";
+    let data = value;
+    for (const [key, item] of value) {
+      const name = key instanceof HtaKeyword ? key.name : String(key);
+      if (name === "code") code = item instanceof HtaKeyword ? item.name : String(item);
+      if (name === "message") message = String(item);
+    }
+    const error = new Error(message);
+    error.code = code;
+    error.data = data;
+    return error;
+  }
+  return new Error(String(value));
+}
+
+/**
+ * Creates the provider side of the HTA transport.
+ *
+ * The provider receives a third argument with a cancellable signal and a
+ * manifest-authorized host-call bridge. Ordinary providers that only accept
+ * `(operation, args)` remain source compatible.
+ */
+export function createBrowserProvider(call, options = {}) {
+  const scope = options.scope ?? self;
+  const lifecycle = createProviderLifecycle({
+    origin: options.origin ?? "browser",
+    onEvent: options.onEvent
+  });
+  const cancelled = new Set();
+  const calls = new Map();
+  const hostCalls = new Map();
+  const releases = new Set();
+  let nextHostCall = 0;
+  let closing = false;
+  let closed = false;
+
+  lifecycle.emit(HTA_PROVIDER_EVENT.START);
+
+  function rejectHostCalls(error) {
+    for (const pending of hostCalls.values()) pending.reject(error);
+    hostCalls.clear();
+  }
+
+  function hostCall(service, method, args = [], metadata = {}) {
+    if (closed) return Promise.reject(new Error("hta/provider-closed"));
+    const id = ++nextHostCall;
+    const eventFields = {
+      ...(metadata.request === undefined ? {} : { request: Number(metadata.request) }),
+      ...(metadata.task === undefined ? {} : { task: Number(metadata.task) }),
+      call: id,
+      service: String(service),
+      method: String(method)
+    };
+    const signal = Object.hasOwn(metadata, "signal") ? metadata.signal : undefined;
+    return new Promise((resolve, reject) => {
+      let abort;
+      const cleanup = () => signal?.removeEventListener?.("abort", abort);
+      abort = () => {
+        if (!hostCalls.delete(id)) return;
+        cleanup();
+        const error = new Error("hta/host-call-cancelled");
+        error.code = "hta/host-call-cancelled";
+        lifecycle.emit(HTA_PROVIDER_EVENT.HOST_CALL, {
+          ...eventFields,
+          status: "error",
+          code: error.code
+        });
+        reject(error);
+      };
+      hostCalls.set(id, {
+        eventFields,
+        resolve(value) {
+          cleanup();
+          resolve(value);
+        },
+        reject(error) {
+          cleanup();
+          reject(error);
+        }
+      });
+      if (signal?.aborted) {
+        abort();
+        return;
+      }
+      signal?.addEventListener?.("abort", abort, { once: true });
+      scope.postMessage({
+        type: "host-call",
+        call: id,
+        service: String(service),
+        method: String(method),
+        session: metadata.session,
+        mount: metadata.mount,
+        task: metadata.task,
+        frame: encodeHta(toHta(args))
+      });
+      lifecycle.emit(HTA_PROVIDER_EVENT.HOST_CALL, { ...eventFields, status: "enter" });
+    });
+  }
+
+  async function closeProvider() {
+    if (closing) return;
+    closing = true;
+    const error = new Error("hta/provider-closed");
+    for (const controller of calls.values()) controller.abort(error);
+    calls.clear();
+    let failure = null;
+    try {
+      await Promise.all([...releases]);
+    } catch (releaseError) {
+      failure = releaseError;
+    }
+    try {
+      await options.close?.();
+    } catch (closeError) {
+      failure ??= closeError;
+    } finally {
+      rejectHostCalls(error);
+      closed = true;
+      if (failure) {
+        lifecycle.emit(HTA_PROVIDER_EVENT.FAILURE, {
+          status: "error",
+          code: providerErrorCode(failure, options.errorCode)
+        });
+      }
+      lifecycle.shutdown({
+        status: failure === null ? "ok" : "error",
+        ...(failure === null
+          ? {}
+          : { code: providerErrorCode(failure, options.errorCode) })
+      });
+    }
+    if (failure) {
+      scope.postMessage({
+        type: "fatal",
+        error: { message: String(failure?.message ?? failure) }
+      });
+    }
+  }
+
+  async function handle(message) {
+    try {
+      if (message.type === "delivery") {
+        const pending = hostCalls.get(message.call);
+        if (!pending) return;
+        hostCalls.delete(message.call);
+        try {
+          const value = decodeHta(message.frame);
+          const error = message.ok ? null : errorFrom(value);
+          lifecycle.emit(HTA_PROVIDER_EVENT.HOST_CALL, {
+            ...pending.eventFields,
+            status: message.ok ? "ok" : "error",
+            ...(error ? { code: providerErrorCode(error, options.errorCode) } : {})
+          });
+          message.ok ? pending.resolve(value) : pending.reject(error);
+        } catch (error) {
+          pending.reject(error);
+        }
+      } else if (message.type === "release") {
+        if (typeof options.release !== "function") {
+          throw new Error("hta/handle-release-unsupported");
+        }
+        const release = Promise.resolve().then(() => options.release(decodeHta(message.frame)));
+        releases.add(release);
+        try {
+          await release;
+          lifecycle.emit(HTA_PROVIDER_EVENT.RELEASE, { status: "ok" });
+        } catch (error) {
+          lifecycle.emit(HTA_PROVIDER_EVENT.RELEASE, {
+            status: "error",
+            code: providerErrorCode(error, options.errorCode)
+          });
+          throw error;
+        } finally {
+          releases.delete(release);
+        }
+      } else if (message.type === "cancel") {
+        const controller = calls.get(message.id);
+        if (controller) {
+          cancelled.add(message.id);
+          controller.abort(new Error("cancelled"));
+          lifecycle.emit(HTA_PROVIDER_EVENT.CANCEL, { request: Number(message.id) });
+        }
+      } else if (message.type === "close") {
+        await closeProvider();
+      } else if (message.type === "call") {
+        if (closing) throw new Error("hta/provider-closed");
+        const [operation, args] = decodeHta(message.frame);
+        lifecycle.emit(HTA_PROVIDER_EVENT.CALL_ENTER, {
+          request: Number(message.id),
+          operation: String(operation)
+        });
+        const controller = new AbortController();
+        calls.set(message.id, controller);
+        const context = Object.freeze({
+          signal: controller.signal,
+          hostCall(service, method, values = [], metadata = {}) {
+            return hostCall(service, method, values, {
+            ...metadata,
+            task: metadata.task ?? message.id,
+            request: metadata.request ?? message.id,
+            signal: Object.hasOwn(metadata, "signal") ? metadata.signal : controller.signal
+            });
+          }
+        });
+        try {
+          const value = await call(operation, args, context);
+          if (!cancelled.has(message.id) && !closing) {
+            scope.postMessage({
+              type: "result",
+              id: message.id,
+              ok: true,
+              frame: encodeHta(toHta(value))
+            });
+            lifecycle.emit(HTA_PROVIDER_EVENT.CALL_RETURN, {
+              request: Number(message.id),
+              operation: String(operation),
+              status: "ok"
+            });
+          }
+        } catch (error) {
+          if (!cancelled.has(message.id) && !closing) {
+            scope.postMessage({
+              type: "result",
+              id: message.id,
+              ok: false,
+              frame: encodeHta(providerError(error, "browser", options.errorCode))
+            });
+            lifecycle.emit(HTA_PROVIDER_EVENT.CALL_ERROR, {
+              request: Number(message.id),
+              operation: String(operation),
+              status: "error",
+              code: providerErrorCode(error, options.errorCode)
+            });
+          }
+        } finally {
+          calls.delete(message.id);
+          cancelled.delete(message.id);
+        }
+      }
+    } catch (error) {
+      scope.postMessage({ type: "fatal", error: { message: String(error?.message ?? error) } });
+    }
+  }
+
+  return Object.freeze({ close: closeProvider, handle });
+}

package/provider-common.mjs

@@ -0,0 +1,91 @@
+import { HtaKeyword, HtaMapEntry } from "./index.js";
+
+export const HTA_PROVIDER_EVENT_SCHEMA = "hara.hta.provider.event/0-alpha";
+
+export const HTA_PROVIDER_EVENT = Object.freeze({
+  START: "start",
+  CALL_ENTER: "call-enter",
+  CALL_RETURN: "call-return",
+  CALL_ERROR: "call-error",
+  HOST_CALL: "host-call",
+  CALLBACK: "callback",
+  CANCEL: "cancel",
+  RELEASE: "release",
+  FAILURE: "failure",
+  TERMINAL: "terminal",
+  SHUTDOWN: "shutdown"
+});
+
+/**
+ * Creates the host-neutral lifecycle trace used by every HTA provider
+ * runner. The trace deliberately contains request/operation identity and
+ * terminal status, but never provider values or opaque handle identities.
+ */
+export function createProviderLifecycle(options = {}) {
+  const origin = options.origin === undefined ? "provider" : String(options.origin);
+  let sequence = 0;
+  let closed = false;
+
+  function emit(event, fields = {}) {
+    const record = Object.freeze({
+      schema: HTA_PROVIDER_EVENT_SCHEMA,
+      sequence: ++sequence,
+      origin,
+      event,
+      ...fields
+    });
+    try {
+      options.onEvent?.(record);
+    } catch {
+      // Instrumentation must not change provider semantics.
+    }
+    return record;
+  }
+
+  return Object.freeze({
+    emit,
+    isClosed() {
+      return closed;
+    },
+    shutdown(fields = {}) {
+      if (closed) return null;
+      closed = true;
+      return emit(HTA_PROVIDER_EVENT.SHUTDOWN, fields);
+    }
+  });
+}
+
+export function providerErrorCode(error, fallback = "provider/error") {
+  const message = String(error?.message ?? error);
+  const separator = message.indexOf(":");
+  return separator > 0 ? message.slice(0, separator) : fallback;
+}
+
+export function toHta(value) {
+  if (value === null || value === undefined || typeof value !== "object") {
+    return value ?? null;
+  }
+  if (value instanceof HtaKeyword || value instanceof HtaMapEntry || value instanceof Uint8Array) return value;
+  if (Array.isArray(value)) return value.map(toHta);
+  if (value instanceof Map) {
+    const result = new Map();
+    for (const [key, item] of value) result.set(key, toHta(item));
+    return result;
+  }
+  const result = new Map();
+  for (const [key, item] of Object.entries(value)) {
+    result.set(new HtaKeyword(key), toHta(item));
+  }
+  return result;
+}
+
+export function providerError(error, origin, fallbackCode = "provider/error") {
+  const message = String(error?.message ?? error);
+  const code = providerErrorCode(error, fallbackCode);
+  return new Map([
+    [new HtaKeyword("code"), new HtaKeyword(code)],
+    [new HtaKeyword("message"), message],
+    [new HtaKeyword("origin"), new HtaKeyword(origin)],
+    [new HtaKeyword("retryable"), false]
+  ]);
+}

package/provider-node.mjs

@@ -0,0 +1,236 @@
+import { decodeHta, encodeHta } from "./index.js";
+import {
+  createProviderLifecycle,
+  HTA_PROVIDER_EVENT,
+  providerError,
+  providerErrorCode,
+  toHta
+} from "./provider-common.mjs";
+
+/**
+ * Serves a provider module over the Node process framing used by the Rust
+ * loader. The framing is Node-specific; lifecycle, cancellation, release,
+ * and provider context semantics are shared with the browser runner.
+ */
+export function serveNodeProvider(call, options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const exit = options.exit ?? (code => process.exit(code));
+  const maxFrameSize = options.maxFrameSize ?? 64 * 1024 * 1024;
+  const lifecycle = createProviderLifecycle({
+    origin: options.origin ?? "node",
+    onEvent: options.onEvent
+  });
+  const cancelled = new Set();
+  const controllers = new Map();
+  const inFlight = new Map();
+  let nextHostCall = 0;
+  let buffered = new Uint8Array();
+  let expected = null;
+  let closing = false;
+  let closePromise = null;
+  let exited = false;
+
+  if (options.redirectConsole !== false) {
+    console.log = (...values) => console.error(...values);
+    console.info = (...values) => console.error(...values);
+  }
+
+  input.on("data", chunk => {
+    try {
+      const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+      const next = new Uint8Array(buffered.length + bytes.length);
+      next.set(buffered);
+      next.set(bytes, buffered.length);
+      buffered = next;
+      drain();
+    } catch (error) {
+      reportFatal(error);
+    }
+  });
+  input.on("end", () => {
+    void closeProvider().catch(() => {}).finally(finish);
+  });
+
+  function drain() {
+    while (true) {
+      if (expected === null) {
+        if (buffered.length < 4) return;
+        expected = new DataView(buffered.buffer, buffered.byteOffset, 4).getUint32(0, false);
+        buffered = buffered.slice(4);
+        if (expected === 0 || expected > maxFrameSize) {
+          throw new Error("hta/process-frame-size");
+        }
+      }
+      if (buffered.length < expected) return;
+      const frame = buffered.slice(0, expected);
+      buffered = buffered.slice(expected);
+      expected = null;
+      void dispatch(decodeHta(frame)).catch(reportFatal);
+    }
+  }
+
+  async function dispatch(frame) {
+    const [kind, id, operation, args] = frame;
+    if (kind === "handshake") {
+      lifecycle.emit(HTA_PROVIDER_EVENT.START, {
+        namespace: typeof operation === "string" ? operation : undefined
+      });
+      write(["ready", 1]);
+      return;
+    }
+    if (kind === "shutdown") {
+      await closeProvider();
+      finish();
+      return;
+    }
+    if (kind === "cancel") {
+      const requestId = Number(id);
+      const controller = controllers.get(requestId);
+      if (controller) {
+        cancelled.add(requestId);
+        controller.abort(new Error("cancelled"));
+        lifecycle.emit(HTA_PROVIDER_EVENT.CANCEL, { request: requestId });
+      }
+      return;
+    }
+    if (kind === "release") {
+      if (typeof options.release !== "function") {
+        throw new Error("hta/handle-release-unsupported");
+      }
+      try {
+        await options.release(id);
+        lifecycle.emit(HTA_PROVIDER_EVENT.RELEASE, { status: "ok" });
+      } catch (error) {
+        lifecycle.emit(HTA_PROVIDER_EVENT.RELEASE, {
+          status: "error",
+          code: providerErrorCode(error, options.errorCode)
+        });
+        throw error;
+      }
+      return;
+    }
+    if (kind !== "call") throw new Error(`hta/process-event-unknown: ${kind}`);
+    if (closing) throw new Error("hta/provider-closed");
+
+    const requestId = Number(id);
+    const controller = new AbortController();
+    controllers.set(requestId, controller);
+    lifecycle.emit(HTA_PROVIDER_EVENT.CALL_ENTER, {
+      request: requestId,
+      operation: String(operation)
+    });
+    const context = Object.freeze({
+      signal: controller.signal,
+      hostCall(service, method, values = [], metadata = {}) {
+        if (typeof options.hostCall !== "function") {
+          return Promise.reject(new Error("hta/host-call-unsupported: node provider has no host bridge"));
+        }
+        const call = ++nextHostCall;
+        const fields = {
+          request: requestId,
+          call,
+          service: String(service),
+          method: String(method)
+        };
+        lifecycle.emit(HTA_PROVIDER_EVENT.HOST_CALL, { ...fields, status: "enter" });
+        return Promise.resolve()
+          .then(() => options.hostCall(service, method, values, {
+            ...metadata,
+            request: requestId,
+            call,
+            signal: controller.signal
+          }))
+          .then(value => {
+            lifecycle.emit(HTA_PROVIDER_EVENT.HOST_CALL, { ...fields, status: "ok" });
+            return value;
+          }, error => {
+            lifecycle.emit(HTA_PROVIDER_EVENT.HOST_CALL, {
+              ...fields,
+              status: "error",
+              code: providerErrorCode(error, options.errorCode)
+            });
+            throw error;
+          });
+      }
+    });
+    const pending = invoke(requestId, operation, args, context, controller);
+    inFlight.set(requestId, pending);
+    try {
+      await pending;
+    } finally {
+      inFlight.delete(requestId);
+    }
+  }
+
+  async function invoke(requestId, operation, args, context, controller) {
+    try {
+      const value = await call(operation, args, context);
+      if (!controller.signal.aborted && !cancelled.has(requestId) && !closing) {
+        write(["result", requestId, toHta(value)]);
+        lifecycle.emit(HTA_PROVIDER_EVENT.CALL_RETURN, {
+          request: requestId,
+          operation: String(operation),
+          status: "ok"
+        });
+      }
+    } catch (error) {
+      if (!controller.signal.aborted && !cancelled.has(requestId) && !closing) {
+        write(["error", requestId, providerError(error, "node", options.errorCode)]);
+        lifecycle.emit(HTA_PROVIDER_EVENT.CALL_ERROR, {
+          request: requestId,
+          operation: String(operation),
+          status: "error",
+          code: providerErrorCode(error, options.errorCode)
+        });
+      }
+    } finally {
+      controllers.delete(requestId);
+      cancelled.delete(requestId);
+    }
+  }
+
+  async function closeProvider() {
+    if (closePromise) return closePromise;
+    closing = true;
+    closePromise = (async () => {
+      const error = new Error("hta/provider-closed");
+      for (const controller of controllers.values()) controller.abort(error);
+      await Promise.allSettled([...inFlight.values()]);
+      let failure = null;
+      try {
+        await options.close?.();
+      } catch (closeError) {
+        failure = closeError;
+      }
+      lifecycle.shutdown({
+        status: failure === null ? "ok" : "error",
+        ...(failure === null
+          ? {}
+          : { code: providerErrorCode(failure, options.errorCode) })
+      });
+      if (failure) throw failure;
+    })();
+    return closePromise;
+  }
+
+  function finish() {
+    if (exited) return;
+    exited = true;
+    exit(0);
+  }
+
+  function reportFatal(error) {
+    console.error(String(error?.message ?? error));
+    void closeProvider().catch(() => {}).finally(finish);
+  }
+
+  function write(value) {
+    if (closing) return;
+    const frame = encodeHta(value);
+    const header = new Uint8Array(4);
+    new DataView(header.buffer).setUint32(0, frame.length, false);
+    output.write(header);
+    output.write(frame);
+  }
+}