@qlever-llc/trellis 0.8.4 → 0.9.0-rc.10

package/src/generate.ts

@@ -0,0 +1,329 @@
+import "./_dnt.polyfills.js";
+import * as dntShim from "./_dnt.shims.js";
+const REPO_OWNER = "qlever-llc";
+const REPO_NAME = "trellis";
+const BIN_NAME = "trellis-generate";
+const SUPPORTED_TARGETS = new Set([
+  "x86_64-unknown-linux-gnu",
+  "aarch64-unknown-linux-gnu",
+  "x86_64-apple-darwin",
+  "aarch64-apple-darwin",
+]);
+
+type PackageManifest = {
+  version?: unknown;
+};
+
+type CommandStatus = {
+  success: boolean;
+  code: number;
+};
+
+async function main(): Promise<void> {
+  const localRepoRoot = await findLocalTrellisRepoRoot();
+  if (localRepoRoot) {
+    await runLocalGenerator(localRepoRoot, denoRuntime().args);
+    return;
+  }
+
+  const packageVersion = await readPackageVersion();
+  const binary = denoRuntime().env.get("TRELLIS_GENERATE_BIN")?.trim() ||
+    await ensureCachedReleaseBinary(packageVersion);
+  await verifyBinaryVersion(binary, packageVersion);
+  await runBinary(binary, denoRuntime().args);
+}
+
+function denoRuntime(): typeof dntShim.Deno {
+  const getGlobalThis = Function("return globalThis") as () => {
+    Deno?: typeof dntShim.Deno;
+  };
+  const deno = getGlobalThis().Deno;
+  if (!deno) {
+    throw new Error("@qlever-llc/trellis/generate requires the Deno runtime");
+  }
+  return deno;
+}
+
+async function findLocalTrellisRepoRoot(): Promise<string | undefined> {
+  let current = urlDirname(import.meta.url);
+  while (current !== dirname(current)) {
+    if (
+      await pathExists(joinPath(current, "rust/tools/generate/Cargo.toml")) &&
+      await pathExists(joinPath(current, "js/deno.json"))
+    ) {
+      return current;
+    }
+    current = dirname(current);
+  }
+  return undefined;
+}
+
+async function runLocalGenerator(
+  repoRoot: string,
+  args: string[],
+): Promise<void> {
+  return await runCommand("cargo", [
+    "run",
+    "--manifest-path",
+    joinPath(repoRoot, "rust/tools/generate/Cargo.toml"),
+    "--bin",
+    BIN_NAME,
+    "--",
+    ...args,
+  ]);
+}
+
+async function readPackageVersion(): Promise<string> {
+  const manifest = await readFirstManifest([
+    new URL("./deno.json", import.meta.url),
+    new URL("../../../package.json", import.meta.url),
+  ]);
+  if (typeof manifest.version !== "string" || !manifest.version.trim()) {
+    throw new Error(
+      "@qlever-llc/trellis package manifest does not declare a version",
+    );
+  }
+  return manifest.version.trim();
+}
+
+async function readFirstManifest(urls: URL[]): Promise<PackageManifest> {
+  const deno = denoRuntime();
+  for (const url of urls) {
+    try {
+      return JSON.parse(await deno.readTextFile(url)) as PackageManifest;
+    } catch (error) {
+      if (error instanceof deno.errors.NotFound) {
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error("@qlever-llc/trellis package manifest was not found");
+}
+
+async function ensureCachedReleaseBinary(version: string): Promise<string> {
+  const target = releaseTarget();
+  const cacheDir = joinPath(cacheRoot(), version, target);
+  const binary = joinPath(cacheDir, BIN_NAME);
+  if (await pathExists(binary)) {
+    return binary;
+  }
+
+  const deno = denoRuntime();
+  await deno.mkdir(cacheDir, { recursive: true });
+  const tag = `v${version}`;
+  const archiveName = `${BIN_NAME}-${tag}-${target}.tar.gz`;
+  const archiveUrl =
+    `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${tag}/${archiveName}`;
+  const checksumName = `checksum-${tag}-${target}-${BIN_NAME}.sha256`;
+  const checksumUrl =
+    `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${tag}/${checksumName}`;
+
+  const [archive, checksumText] = await Promise.all([
+    downloadBytes(archiveUrl),
+    downloadText(checksumUrl),
+  ]);
+  await verifyChecksum(archive, checksumText, archiveUrl);
+
+  const archivePath = joinPath(cacheDir, archiveName);
+  await deno.writeFile(archivePath, archive);
+  await runCommandChecked("tar", ["-xzf", archivePath, "-C", cacheDir]);
+  await deno.chmod(binary, 0o755);
+  return binary;
+}
+
+function releaseTarget(): string {
+  const deno = denoRuntime();
+  if (SUPPORTED_TARGETS.has(deno.build.target)) {
+    return deno.build.target;
+  }
+
+  const buildArch: string = deno.build.arch;
+  const arch = buildArch === "x86_64" || buildArch === "x64"
+    ? "x86_64"
+    : buildArch;
+  const os = deno.build.os === "darwin"
+    ? "apple-darwin"
+    : deno.build.os === "linux"
+    ? "unknown-linux-gnu"
+    : undefined;
+  const target = os ? `${arch}-${os}` : undefined;
+  if (target && SUPPORTED_TARGETS.has(target)) {
+    return target;
+  }
+
+  throw new Error(
+    `no ${BIN_NAME} release binary is available for ${deno.build.target}`,
+  );
+}
+
+function cacheRoot(): string {
+  const deno = denoRuntime();
+  const explicit = deno.env.get("TRELLIS_GENERATE_CACHE")?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const xdg = deno.env.get("XDG_CACHE_HOME")?.trim();
+  if (xdg) {
+    return joinPath(xdg, "trellis", BIN_NAME);
+  }
+  const home = deno.env.get("HOME")?.trim();
+  if (!home) {
+    throw new Error(
+      "HOME or TRELLIS_GENERATE_CACHE must be set to cache trellis-generate",
+    );
+  }
+  return joinPath(home, ".cache", "trellis", BIN_NAME);
+}
+
+async function downloadBytes(url: string): Promise<Uint8Array> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`failed to download ${url}: HTTP ${response.status}`);
+  }
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+async function downloadText(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`failed to download ${url}: HTTP ${response.status}`);
+  }
+  return await response.text();
+}
+
+async function verifyChecksum(
+  bytes: Uint8Array,
+  checksumText: string,
+  label: string,
+): Promise<void> {
+  const expected = checksumText.trim().split(/\s+/)[0]?.toLowerCase();
+  if (!expected || !/^[0-9a-f]{64}$/.test(expected)) {
+    throw new Error("release checksum asset did not contain a SHA-256 digest");
+  }
+
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  const digest = await crypto.subtle.digest("SHA-256", buffer);
+  const actual = Array.from(new Uint8Array(digest))
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+  if (actual !== expected) {
+    throw new Error(
+      `checksum mismatch for ${label}: expected ${expected}, got ${actual}`,
+    );
+  }
+}
+
+async function verifyBinaryVersion(
+  binary: string,
+  expectedVersion: string,
+): Promise<void> {
+  const Command = denoRuntime().Command;
+  const output = await new Command(binary, {
+    args: ["--version"],
+    stdout: "piped",
+    stderr: "piped",
+  }).output();
+  if (!output.success) {
+    throw new Error(`failed to run ${binary} --version`);
+  }
+  const text = new TextDecoder().decode(output.stdout).trim();
+  const actualVersion = text.split(/\s+/).find((part) =>
+    /^v?\d+\.\d+\.\d+/.test(part)
+  );
+  if (
+    !actualVersion ||
+    normalizeVersion(actualVersion) !== normalizeVersion(expectedVersion)
+  ) {
+    throw new Error(
+      `${binary} is ${
+        text || "unknown version"
+      }; expected ${BIN_NAME} ${expectedVersion}`,
+    );
+  }
+}
+
+function normalizeVersion(version: string): string {
+  return version.trim().replace(/^v/, "").split("+")[0];
+}
+
+async function runBinary(binary: string, args: string[]): Promise<void> {
+  return await runCommand(binary, args);
+}
+
+async function runCommand(
+  command: string,
+  args: string[],
+  options: { cwd?: string } = {},
+): Promise<void> {
+  const status = await spawnCommand(command, args, options);
+  denoRuntime().exit(status.code);
+}
+
+async function runCommandChecked(
+  command: string,
+  args: string[],
+  options: { cwd?: string } = {},
+): Promise<void> {
+  const status = await spawnCommand(command, args, options);
+  if (!status.success) {
+    throw new Error(`${command} failed with exit code ${status.code}`);
+  }
+}
+
+async function spawnCommand(
+  command: string,
+  args: string[],
+  options: { cwd?: string } = {},
+): Promise<CommandStatus> {
+  const Command = denoRuntime().Command;
+  const status = await new Command(command, {
+    args,
+    cwd: options.cwd,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  }).spawn().status;
+  return status;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  const deno = denoRuntime();
+  try {
+    await deno.stat(path);
+    return true;
+  } catch (error) {
+    if (error instanceof deno.errors.NotFound) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function urlDirname(url: string): string {
+  return dirname(decodeURIComponent(new URL(url).pathname));
+}
+
+function dirname(path: string): string {
+  const normalized = path.replace(/\/+$/, "");
+  const index = normalized.lastIndexOf("/");
+  if (index <= 0) {
+    return "/";
+  }
+  return normalized.slice(0, index);
+}
+
+function joinPath(...parts: string[]): string {
+  return parts
+    .filter((part) => part.length > 0)
+    .join("/")
+    .replace(/\/+/g, "/");
+}
+
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error(error);
+    denoRuntime().exit(1);
+  });
+}

package/src/globals.ts

@@ -0,0 +1,26 @@
+export type LoggerLike = {
+  child(bindings: Record<string, unknown>): LoggerLike;
+  trace(...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+};
+
+function createNoopLogger(): LoggerLike {
+  const noop = () => {};
+  const logger: LoggerLike = {
+    child: () => logger,
+    trace: noop,
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+  };
+  return logger;
+}
+
+// Keep the root package browser-safe: importing `@qlever-llc/trellis` must not
+// pull in `pino` or Node-only side effects. Server-only entrypoints can inject
+// a real logger, while the shared runtime defaults to a no-op logger here.
+export const logger: LoggerLike = createNoopLogger();

package/src/health.ts

@@ -0,0 +1,28 @@
+import "./_dnt.polyfills.js";
+export type {
+  HealthCheckFn,
+  HealthCheckResult,
+  HealthHeartbeat,
+  HealthResponse,
+  ServiceHealthCheck,
+  ServiceHealthCheckFn,
+  ServiceHealthInfo,
+  ServiceHealthInfoFn,
+} from "./server/health.js";
+export {
+  createHealthHeartbeat,
+  runAllHealthChecks,
+  runAllServiceHealthChecks,
+  runHealthCheck,
+  runServiceHealthCheck,
+  ServiceHealth,
+} from "./server/health.js";
+export {
+  HealthCheckResultSchema,
+  HealthHeartbeatHeaderSchema,
+  HealthHeartbeatSchema,
+  HealthHeartbeatServiceSchema,
+  HealthInfoSchema,
+  HealthResponseSchema,
+  HealthRpcSchema,
+} from "./server/health_schemas.js";

package/src/helpers.ts

@@ -0,0 +1,63 @@
+import { Pointer } from "typebox/value";
+
+/**
+ * Compute the subject template from the message itself
+ */
+export function template(
+  template: string,
+  data: Record<string, string | number | boolean>,
+  opts: { allowWildcards: boolean } = { allowWildcards: false },
+): string {
+  return template.replace(/\{([^}]+)\}/g, (_, key) => {
+    const token = Pointer.Get(data, key);
+    const v = token ? escapeNats(`${token}`) : "*";
+
+    if (!opts.allowWildcards && v === "*") {
+      throw new Error("All option templates must have values at runtime.");
+    }
+
+    return v;
+  });
+}
+
+const NATS_SUBJECT_TOKEN_FORBIDDEN = /[\u0000\s.*>~]/gu;
+export function escapeNats(token: string): string {
+  const out = token.replace(
+    NATS_SUBJECT_TOKEN_FORBIDDEN,
+    (ch) => `~${ch.codePointAt(0)!.toString(16).toUpperCase()}~`,
+  );
+
+  // Protect start with $ due to NATS internal use of it
+  if (out.length === 0 || out.startsWith("$")) {
+    return `_${out}`;
+  }
+
+  return out;
+}
+
+const NATS_KV_KEY_FORBIDDEN = /[\u0000\s*>~]/gu;
+export function escapeKvKey(key: string): string {
+  const out = key.replace(
+    NATS_KV_KEY_FORBIDDEN,
+    (ch) => `~${ch.codePointAt(0)!.toString(16).toUpperCase()}~`,
+  );
+
+  if (out.length === 0 || out.startsWith("$")) {
+    return `_${out}`;
+  }
+
+  return out;
+}
+
+export function decodeSubject(token: string): string {
+  const out = token.replace(
+    /~([0-9A-F]{1,6})~/g,
+    (_, hex: string) => String.fromCodePoint(Number.parseInt(hex, 16)),
+  );
+
+  if (out.startsWith("_$")) {
+    return out.slice(1);
+  }
+
+  return out;
+}

package/src/host/mod.ts

@@ -0,0 +1,9 @@
+/**
+ * Legacy service host entry point.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+
+
+export * from "../service/mod.js";

package/src/host/node.ts

@@ -0,0 +1,9 @@
+/**
+ * Legacy Node service host entry point.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+
+
+export * from "../service/node.js";

package/src/index.ts

@@ -0,0 +1,233 @@
+import "./_dnt.polyfills.js";
+export {
+  bindFlow,
+  clearSessionKey,
+  createAuth,
+  createRpcProof,
+  generateSessionKey,
+  getOrCreateSessionKey,
+  getPublicSessionKey,
+  hasSessionKey,
+  isBindSuccessResponse,
+  loadSessionKey,
+  signBytes,
+} from "./auth.js";
+export type {
+  BindResponse,
+  BindSuccessResponse,
+  NatsConnectOptions,
+  SessionKeyHandle,
+} from "./auth.js";
+export {
+  canonicalizeJson,
+  CATALOG_FORMAT_V1,
+  CONTRACT_FORMAT_V1,
+  digestJson,
+  isJsonValue,
+  schema,
+  unwrapSchema,
+} from "./contracts.js";
+export type { InferSchemaType, JsonValue, TrellisAPI } from "./contracts.js";
+export { TrellisConnection } from "./connection.js";
+export type { TrellisConnectionStatus } from "./connection.js";
+export type {
+  HealthCheckFn,
+  HealthCheckResult,
+  HealthHeartbeat,
+  HealthResponse,
+  ServiceHealthCheck,
+  ServiceHealthCheckFn,
+  ServiceHealthInfo,
+  ServiceHealthInfoFn,
+} from "./health.js";
+export {
+  createHealthHeartbeat,
+  HealthCheckResultSchema,
+  HealthHeartbeatHeaderSchema,
+  HealthHeartbeatSchema,
+  HealthHeartbeatServiceSchema,
+  HealthInfoSchema,
+  HealthResponseSchema,
+  HealthRpcSchema,
+  runAllHealthChecks,
+  runAllServiceHealthChecks,
+  runHealthCheck,
+  runServiceHealthCheck,
+  ServiceHealth,
+} from "./health.js";
+export { defineError } from "./contract_support/mod.js";
+export {
+  PageRequestSchema,
+  PageResponseSchema,
+} from "./contract_support/mod.js";
+export type {
+  ErrorClass,
+  InferRuntimeRpcError,
+  PageRequest,
+  PageResponse,
+  RpcErrorClass,
+  RuntimeRpcErrorDesc,
+  SerializableErrorData,
+} from "./contract_support/mod.js";
+export {
+  defineAgentContract,
+  defineAppContract,
+  defineDeviceContract,
+  defineServiceContract,
+} from "./contract.js";
+export type {
+  ContractApiViews,
+  ContractDependencyUse,
+  ContractModule,
+  ContractUseFn,
+  DefineContractInput,
+  EmptyApi,
+  SdkContractModule,
+  TrellisApiLike,
+  TrellisContractV1,
+  UseSpec,
+} from "./contract.js";
+export {
+  AsyncResult,
+  BaseError,
+  err,
+  isErr,
+  isOk,
+  ok,
+  Result,
+} from "@qlever-llc/result";
+export type { MaybeAsync } from "@qlever-llc/result";
+export type { ClientOpts } from "./client.js";
+export type {
+  ClientAuthContinuation,
+  ClientAuthOptions,
+  ClientAuthRequiredContext,
+  TrellisClientConnectArgs,
+} from "./client_connect.js";
+export { ClientAuthHandledError, TrellisClient } from "./client_connect.js";
+export { TrellisDevice } from "./device.js";
+export type { TrellisErrorInstance } from "./errors/index.js";
+export {
+  AuthError,
+  KVError,
+  RemoteError,
+  StoreError,
+  TransferError,
+  TransportError,
+  TrellisError,
+  UnexpectedError,
+  ValidationError,
+} from "./errors/index.js";
+export {
+  ActiveJob,
+  JobLogEntrySchema,
+  JobProgressSchema,
+  JobQueue,
+  JobRef,
+  JobWorkerHostAdapter,
+} from "./jobs.js";
+export type {
+  Job,
+  JobFilter,
+  JobIdentity,
+  JobLogEntry,
+  JobProgress,
+  JobsFacade,
+  JobsFacadeOf,
+  JobsHealth,
+  JobSnapshot,
+  JobState,
+  JobTypeMetadata,
+  JobWorkerHost,
+  ServiceInfo,
+  TerminalJob,
+  WorkerInfo,
+} from "./jobs.js";
+export { TypedKV, TypedKVEntry } from "./kv.js";
+export type { WatchEvent, WatchOptions } from "./kv.js";
+export { TypedStore, TypedStoreEntry } from "./store.js";
+export type {
+  StoreBody,
+  StoreInfo,
+  StoreOpenOptions,
+  StorePutOptions,
+  StoreStatus,
+  StoreWaitOptions,
+} from "./store.js";
+export { createTransferHandle, FileInfoSchema } from "./transfer.js";
+export type {
+  FileInfo,
+  ReceiveTransferGrant,
+  ReceiveTransferHandle,
+  SendTransferGrant,
+  SendTransferHandle,
+  TransferBody,
+  TransferGrant,
+} from "./transfer.js";
+export type {
+  AcceptedOperationEvent,
+  CancelledOperationEvent,
+  CompletedOperationEvent,
+  CompletedTransfer,
+  FailedOperationEvent,
+  OperationEvent,
+  OperationInputBuilder,
+  OperationObserverCallbacks,
+  OperationRef,
+  OperationRefData,
+  OperationSignalAck,
+  OperationSnapshot,
+  OperationState,
+  OperationTransferProgress,
+  ProgressOperationEvent,
+  ProgressOperationSnapshot,
+  StartedOperationEvent,
+  StartedTransfer,
+  TerminalOperation,
+  TransferCapableOperationInputBuilder,
+  TransferOperationBuilder,
+  TransferOperationEvent,
+  TransferOperationSnapshot,
+} from "./operations.js";
+export { controlSubject, OperationInvoker } from "./operations.js";
+export type {
+  AcceptedOperation,
+  ClientTrellis,
+  ConnectedTrellisClient,
+  EventHandler,
+  EventName,
+  EventOpts,
+  EventPayload,
+  EventType,
+  FeedInputBuilder,
+  FeedSubscribeOpts,
+  FeedSubscription,
+  HandlerJobQueue,
+  HandlerJobsFacade,
+  HandlerKvFacade,
+  HandlerStoreHandle,
+  HandlerTrellis,
+  HandlerTrellisForContract,
+  MapStateStoreClient,
+  OperationHandlerContext,
+  OperationRegistration,
+  OperationTransferContextOf,
+  OperationTransferHandle,
+  RequestOpts,
+  RpcArgs,
+  RpcHandlerContext,
+  RpcHandlerErrorOf,
+  RpcHandlerFn,
+  RpcInputOf,
+  RpcMethodNameOf,
+  RpcOutputOf,
+  RpcRequestErrorOf,
+  RpcResult,
+  RuntimeStateStoresForContract,
+  RuntimeStateStoreShape,
+  StateFacade,
+  TrellisFor,
+  ValueStateStoreClient,
+} from "./trellis.js";
+export { Trellis } from "./trellis.js";
+export type { TrellisDeviceConnection } from "./device.js";