space-data-module-sdk 0.1.0 → 0.2.0

package/src/host/abi.js

@@ -0,0 +1,282 @@
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+
+export const DEFAULT_HOSTCALL_IMPORT_MODULE = "sdn_host";
+export const HOSTCALL_STATUS_OK = 0;
+export const HOSTCALL_STATUS_ERROR = 1;
+
+export const NodeHostSyncHostcallOperations = Object.freeze([
+  "host.runtimeTarget",
+  "host.listCapabilities",
+  "host.listSupportedCapabilities",
+  "host.listOperations",
+  "host.hasCapability",
+  "clock.now",
+  "clock.monotonicNow",
+  "clock.nowIso",
+  "schedule.parse",
+  "schedule.matches",
+  "schedule.next",
+  "filesystem.resolvePath",
+]);
+
+function assertNonEmptyString(value, label) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    throw new TypeError(`${label} is required.`);
+  }
+  return normalized;
+}
+
+function getMemoryBuffer(getMemory) {
+  if (typeof getMemory !== "function") {
+    throw new TypeError("getMemory must be a function returning WebAssembly.Memory.");
+  }
+  const memory = getMemory();
+  if (!memory || typeof memory !== "object" || !("buffer" in memory)) {
+    throw new TypeError("getMemory must return a WebAssembly.Memory-like object.");
+  }
+  const buffer = memory.buffer;
+  if (!(buffer instanceof ArrayBuffer || buffer instanceof SharedArrayBuffer)) {
+    throw new TypeError("Hostcall memory buffer must be an ArrayBuffer or SharedArrayBuffer.");
+  }
+  return buffer;
+}
+
+function readMemoryBytes(getMemory, ptr, len, label) {
+  if (!Number.isInteger(ptr) || ptr < 0) {
+    throw new RangeError(`${label} pointer must be a non-negative integer.`);
+  }
+  if (!Number.isInteger(len) || len < 0) {
+    throw new RangeError(`${label} length must be a non-negative integer.`);
+  }
+
+  const buffer = getMemoryBuffer(getMemory);
+  if (ptr + len > buffer.byteLength) {
+    throw new RangeError(`${label} range exceeds guest memory bounds.`);
+  }
+  return new Uint8Array(buffer, ptr, len);
+}
+
+function writeMemoryBytes(getMemory, ptr, bytes, maxLen) {
+  if (!Number.isInteger(ptr) || ptr < 0) {
+    throw new RangeError("Response pointer must be a non-negative integer.");
+  }
+  if (!Number.isInteger(maxLen) || maxLen < 0) {
+    throw new RangeError("Response max length must be a non-negative integer.");
+  }
+
+  const payload = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  const buffer = getMemoryBuffer(getMemory);
+  const bytesToCopy = Math.min(payload.length, maxLen);
+  if (ptr + bytesToCopy > buffer.byteLength) {
+    throw new RangeError("Response range exceeds guest memory bounds.");
+  }
+  new Uint8Array(buffer, ptr, bytesToCopy).set(payload.subarray(0, bytesToCopy));
+  return bytesToCopy;
+}
+
+function parseJsonPayload(bytes) {
+  if (bytes.length === 0) {
+    return null;
+  }
+  const text = textDecoder.decode(bytes);
+  if (!text.trim()) {
+    return null;
+  }
+  return JSON.parse(text);
+}
+
+function serializeHostcallError(error, operation = null) {
+  return {
+    name: error?.name ?? "Error",
+    message: error?.message ?? String(error),
+    code: error?.code ?? null,
+    operation: error?.operation ?? operation,
+    capability: error?.capability ?? null,
+  };
+}
+
+function isPromiseLike(value) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof value.then === "function"
+  );
+}
+
+export function dispatchNodeHostSyncOperation(host, operation, params = null) {
+  const normalized = assertNonEmptyString(operation, "Hostcall operation");
+  switch (normalized) {
+    case "host.runtimeTarget":
+      return host.runtimeTarget;
+    case "host.listCapabilities":
+      return host.listCapabilities();
+    case "host.listSupportedCapabilities":
+      return host.listSupportedCapabilities();
+    case "host.listOperations":
+      return host.listOperations();
+    case "host.hasCapability":
+      return host.hasCapability(params?.capability);
+    case "clock.now":
+      return host.clock.now();
+    case "clock.monotonicNow":
+      return host.clock.monotonicNow();
+    case "clock.nowIso":
+      return host.clock.nowIso();
+    case "schedule.parse":
+      return host.schedule.parse(params?.expression);
+    case "schedule.matches":
+      return host.schedule.matches(params?.expression, params?.date);
+    case "schedule.next":
+      return host.schedule.next(params?.expression, params?.from);
+    case "filesystem.resolvePath":
+      return host.filesystem.resolvePath(params?.path);
+    default:
+      throw new Error(
+        `Operation "${normalized}" is not available in the synchronous hostcall ABI.`,
+      );
+  }
+}
+
+export function createNodeHostSyncDispatcher(host) {
+  if (!host || typeof host !== "object") {
+    throw new TypeError("createNodeHostSyncDispatcher requires a host object.");
+  }
+  return (operation, params = null) =>
+    dispatchNodeHostSyncOperation(host, operation, params);
+}
+
+export function createJsonHostcallBridge(options = {}) {
+  const dispatch = options.dispatch;
+  if (typeof dispatch !== "function") {
+    throw new TypeError("createJsonHostcallBridge requires a dispatch function.");
+  }
+
+  const getMemory = options.getMemory;
+  const moduleName = assertNonEmptyString(
+    options.moduleName ?? DEFAULT_HOSTCALL_IMPORT_MODULE,
+    "Hostcall import module name",
+  );
+  const maxRequestBytes = Number.isInteger(options.maxRequestBytes)
+    ? options.maxRequestBytes
+    : 64 * 1024;
+  const maxResponseBytes = Number.isInteger(options.maxResponseBytes)
+    ? options.maxResponseBytes
+    : 1024 * 1024;
+
+  let lastStatusCode = HOSTCALL_STATUS_OK;
+  let lastEnvelope = { ok: true, result: null };
+  let lastResponseBytes = textEncoder.encode(JSON.stringify(lastEnvelope));
+
+  function setEnvelope(statusCode, envelope) {
+    const encoded = textEncoder.encode(JSON.stringify(envelope));
+    if (encoded.length > maxResponseBytes) {
+      throw new Error(
+        `Hostcall response exceeds ${maxResponseBytes} byte limit.`,
+      );
+    }
+    lastStatusCode = statusCode;
+    lastEnvelope = envelope;
+    lastResponseBytes = encoded;
+  }
+
+  function callJson(operationPtr, operationLen, payloadPtr, payloadLen) {
+    try {
+      if (payloadLen > maxRequestBytes) {
+        throw new Error(
+          `Hostcall request exceeds ${maxRequestBytes} byte limit.`,
+        );
+      }
+      const operation = textDecoder.decode(
+        readMemoryBytes(getMemory, operationPtr, operationLen, "Operation"),
+      );
+      const params = parseJsonPayload(
+        readMemoryBytes(getMemory, payloadPtr, payloadLen, "Payload"),
+      );
+      const result = dispatch(operation, params);
+      if (isPromiseLike(result)) {
+        throw new Error(
+          `Operation "${operation}" returned a Promise. The synchronous hostcall ABI only supports synchronous operations.`,
+        );
+      }
+      setEnvelope(HOSTCALL_STATUS_OK, {
+        ok: true,
+        result,
+      });
+      return HOSTCALL_STATUS_OK;
+    } catch (error) {
+      try {
+        setEnvelope(HOSTCALL_STATUS_ERROR, {
+          ok: false,
+          error: serializeHostcallError(error),
+        });
+      } catch (serializationError) {
+        setEnvelope(HOSTCALL_STATUS_ERROR, {
+          ok: false,
+          error: serializeHostcallError(serializationError),
+        });
+      }
+      return HOSTCALL_STATUS_ERROR;
+    }
+  }
+
+  function responseLen() {
+    return lastResponseBytes.length;
+  }
+
+  function readResponse(dstPtr, dstLen) {
+    return writeMemoryBytes(getMemory, dstPtr, lastResponseBytes, dstLen);
+  }
+
+  function clearResponse() {
+    setEnvelope(HOSTCALL_STATUS_OK, {
+      ok: true,
+      result: null,
+    });
+    return HOSTCALL_STATUS_OK;
+  }
+
+  function lastStatus() {
+    return lastStatusCode;
+  }
+
+  return {
+    moduleName,
+    imports: {
+      [moduleName]: {
+        call_json: callJson,
+        response_len: responseLen,
+        read_response: readResponse,
+        clear_response: clearResponse,
+        last_status_code: lastStatus,
+      },
+    },
+    getLastEnvelope() {
+      return structuredClone(lastEnvelope);
+    },
+    getLastResponseBytes() {
+      return new Uint8Array(lastResponseBytes);
+    },
+    getLastResponseText() {
+      return textDecoder.decode(lastResponseBytes);
+    },
+    getLastResponseJson() {
+      return JSON.parse(this.getLastResponseText());
+    },
+  };
+}
+
+export function createNodeHostSyncHostcallBridge(options = {}) {
+  const host = options.host;
+  if (!host || typeof host !== "object") {
+    throw new TypeError(
+      "createNodeHostSyncHostcallBridge requires a host instance.",
+    );
+  }
+
+  return createJsonHostcallBridge({
+    ...options,
+    dispatch: createNodeHostSyncDispatcher(host),
+  });
+}

package/src/host/cron.js

@@ -0,0 +1,247 @@
+const MONTH_ALIASES = Object.freeze({
+  JAN: 1,
+  FEB: 2,
+  MAR: 3,
+  APR: 4,
+  MAY: 5,
+  JUN: 6,
+  JUL: 7,
+  AUG: 8,
+  SEP: 9,
+  OCT: 10,
+  NOV: 11,
+  DEC: 12,
+});
+
+const DAY_OF_WEEK_ALIASES = Object.freeze({
+  SUN: 0,
+  MON: 1,
+  TUE: 2,
+  WED: 3,
+  THU: 4,
+  FRI: 5,
+  SAT: 6,
+});
+
+function coerceDate(value, label) {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new TypeError(`${label} must be a valid date.`);
+    }
+    return new Date(value.getTime());
+  }
+  const date = new Date(value ?? Date.now());
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError(`${label} must be a valid date.`);
+  }
+  return date;
+}
+
+function parsePositiveInteger(value, label) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function parseFieldValue(value, label, min, max, aliases = null) {
+  const normalized = String(value ?? "").trim().toUpperCase();
+  if (!normalized) {
+    throw new Error(`${label} contains an empty value.`);
+  }
+
+  let parsedValue = null;
+  if (/^\d+$/.test(normalized)) {
+    parsedValue = Number(normalized);
+  } else if (aliases && Object.hasOwn(aliases, normalized)) {
+    parsedValue = aliases[normalized];
+  }
+
+  if (!Number.isInteger(parsedValue) || parsedValue < min || parsedValue > max) {
+    throw new Error(
+      `${label} value "${value}" must be between ${min} and ${max}.`,
+    );
+  }
+
+  return parsedValue;
+}
+
+function expandFieldPart(part, label, min, max, aliases = null) {
+  const trimmed = String(part ?? "").trim();
+  if (!trimmed) {
+    throw new Error(`${label} contains an empty list entry.`);
+  }
+
+  const [rangeSpec, stepSpec, extraStep] = trimmed.split("/");
+  if (extraStep !== undefined) {
+    throw new Error(`${label} contains too many "/" step delimiters.`);
+  }
+
+  const step = stepSpec === undefined ? 1 : parsePositiveInteger(stepSpec, label);
+  let start = min;
+  let end = max;
+
+  if (rangeSpec !== "*") {
+    const [startSpec, endSpec, extraRange] = rangeSpec.split("-");
+    if (extraRange !== undefined) {
+      throw new Error(`${label} contains too many "-" range delimiters.`);
+    }
+    start = parseFieldValue(startSpec, label, min, max, aliases);
+    end =
+      endSpec === undefined
+        ? start
+        : parseFieldValue(endSpec, label, min, max, aliases);
+    if (end < start) {
+      throw new Error(`${label} range "${rangeSpec}" is reversed.`);
+    }
+  }
+
+  const values = [];
+  for (let value = start; value <= end; value += step) {
+    values.push(value);
+  }
+  return values;
+}
+
+function buildValueSet(field, label, min, max, aliases = null) {
+  const values = new Set();
+  for (const part of String(field ?? "").split(",")) {
+    for (const value of expandFieldPart(part, label, min, max, aliases)) {
+      values.add(value);
+    }
+  }
+  return values;
+}
+
+function sortNumeric(values) {
+  return Array.from(values).sort((left, right) => left - right);
+}
+
+function normalizeDayOfWeekValues(values) {
+  const normalized = new Set();
+  for (const value of values) {
+    normalized.add(value === 7 ? 0 : value);
+  }
+  return normalized;
+}
+
+function buildFullValueSet(min, max, normalize = (values) => values) {
+  const values = new Set();
+  for (let value = min; value <= max; value += 1) {
+    values.add(value);
+  }
+  return normalize(values);
+}
+
+function buildCronField(name, source, min, max, aliases = null, normalize = null) {
+  const rawValues = buildValueSet(source, name, min, max, aliases);
+  const normalizedValues = normalize ? normalize(rawValues) : rawValues;
+  const fullDomain = buildFullValueSet(min, max, normalize ?? ((values) => values));
+  return {
+    source: String(source ?? "").trim(),
+    values: sortNumeric(normalizedValues),
+    hasWildcard: normalizedValues.size === fullDomain.size,
+  };
+}
+
+function normalizeCronInput(expressionOrSchedule) {
+  if (
+    expressionOrSchedule &&
+    typeof expressionOrSchedule === "object" &&
+    !Array.isArray(expressionOrSchedule) &&
+    typeof expressionOrSchedule.expression === "string" &&
+    expressionOrSchedule.minute &&
+    expressionOrSchedule.hour &&
+    expressionOrSchedule.dayOfMonth &&
+    expressionOrSchedule.month &&
+    expressionOrSchedule.dayOfWeek
+  ) {
+    return expressionOrSchedule;
+  }
+  return parseCronExpression(expressionOrSchedule);
+}
+
+export function parseCronExpression(expression) {
+  const normalized = String(expression ?? "").trim();
+  if (!normalized) {
+    throw new Error("Cron expression is required.");
+  }
+
+  const fields = normalized.split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(
+      "Cron expression must contain exactly 5 fields: minute hour day-of-month month day-of-week.",
+    );
+  }
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = fields;
+  return {
+    expression: normalized,
+    minute: buildCronField("minute", minute, 0, 59),
+    hour: buildCronField("hour", hour, 0, 23),
+    dayOfMonth: buildCronField("day-of-month", dayOfMonth, 1, 31),
+    month: buildCronField("month", month, 1, 12, MONTH_ALIASES),
+    dayOfWeek: buildCronField(
+      "day-of-week",
+      dayOfWeek,
+      0,
+      7,
+      DAY_OF_WEEK_ALIASES,
+      normalizeDayOfWeekValues,
+    ),
+  };
+}
+
+export function matchesCronExpression(expressionOrSchedule, date = Date.now()) {
+  const schedule = normalizeCronInput(expressionOrSchedule);
+  const candidate = coerceDate(date, "Cron candidate date");
+  const minute = candidate.getMinutes();
+  const hour = candidate.getHours();
+  const dayOfMonth = candidate.getDate();
+  const month = candidate.getMonth() + 1;
+  const dayOfWeek = candidate.getDay();
+
+  if (!schedule.minute.values.includes(minute)) {
+    return false;
+  }
+  if (!schedule.hour.values.includes(hour)) {
+    return false;
+  }
+  if (!schedule.month.values.includes(month)) {
+    return false;
+  }
+
+  const dayOfMonthMatches = schedule.dayOfMonth.values.includes(dayOfMonth);
+  const dayOfWeekMatches = schedule.dayOfWeek.values.includes(dayOfWeek);
+
+  if (!schedule.dayOfMonth.hasWildcard && !schedule.dayOfWeek.hasWildcard) {
+    return dayOfMonthMatches || dayOfWeekMatches;
+  }
+  if (!schedule.dayOfMonth.hasWildcard) {
+    return dayOfMonthMatches;
+  }
+  if (!schedule.dayOfWeek.hasWildcard) {
+    return dayOfWeekMatches;
+  }
+  return true;
+}
+
+export function nextCronOccurrence(expressionOrSchedule, from = Date.now()) {
+  const schedule = normalizeCronInput(expressionOrSchedule);
+  const cursor = coerceDate(from, "Cron start date");
+  cursor.setSeconds(0, 0);
+  cursor.setMinutes(cursor.getMinutes() + 1);
+
+  const maxIterations = 60 * 24 * 366 * 5;
+  for (let index = 0; index < maxIterations; index += 1) {
+    if (matchesCronExpression(schedule, cursor)) {
+      return new Date(cursor.getTime());
+    }
+    cursor.setMinutes(cursor.getMinutes() + 1);
+  }
+
+  throw new Error(
+    `No cron occurrence found for "${schedule.expression}" within the next 5 years.`,
+  );
+}

package/src/host/index.js

@@ -0,0 +1,3 @@
+export * from "./cron.js";
+export * from "./nodeHost.js";
+export * from "./abi.js";