@hla4ts/spacekit 0.1.0

package/src/env.ts

@@ -0,0 +1,168 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface SpacekitLogger {
+  debug(message: string, data?: Record<string, unknown>): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, data?: Record<string, unknown>): void;
+}
+
+export interface SpacekitEnvDefaults {
+  rtiHost?: string;
+  rtiPort?: number;
+  rtiUseTls?: boolean;
+  federationName?: string;
+  federateName?: string;
+  federateType?: string;
+  lookaheadMicros?: bigint;
+  updatePeriodMicros?: bigint;
+  referenceFrameTimeoutMs?: number;
+  logLevel?: LogLevel;
+  logEveryN?: number;
+  debug?: boolean;
+}
+
+export interface SpacekitEnvConfig {
+  rtiHost: string;
+  rtiPort: number;
+  rtiUseTls: boolean;
+  federationName: string;
+  federateName: string;
+  federateType: string;
+  lookaheadMicros: bigint;
+  updatePeriodMicros: bigint;
+  referenceFrameTimeoutMs: number;
+  logLevel: LogLevel;
+  logEveryN: number;
+  debug: boolean;
+}
+
+export interface SpacekitEnvParseOptions {
+  env?: Record<string, string | undefined>;
+  defaults?: SpacekitEnvDefaults;
+  logger?: SpacekitLogger;
+  logResolved?: boolean;
+  required?: Array<"federationName" | "federateName" | "federateType">;
+}
+
+const DEFAULTS: Required<SpacekitEnvDefaults> = {
+  rtiHost: "localhost",
+  rtiPort: 15164,
+  rtiUseTls: false,
+  federationName: "SpaceFederation",
+  federateName: `Federate-${Date.now()}`,
+  federateType: "Federate",
+  lookaheadMicros: 1_000_000n,
+  updatePeriodMicros: 1_000_000n,
+  referenceFrameTimeoutMs: 30_000,
+  logLevel: "info",
+  logEveryN: 1,
+  debug: false,
+};
+
+export function parseSpacekitEnv(options: SpacekitEnvParseOptions = {}): SpacekitEnvConfig {
+  const env = options.env ?? process.env;
+  const defaults = { ...DEFAULTS, ...(options.defaults ?? {}) };
+
+  const rtiHost = env.RTI_HOST ?? defaults.rtiHost;
+  const rtiPort = parseNumber(env.RTI_PORT, defaults.rtiPort, "RTI_PORT");
+  const rtiUseTls = parseBoolean(env.RTI_USE_TLS, defaults.rtiUseTls);
+  const federationName = env.FEDERATION_NAME ?? defaults.federationName;
+  const federateName = env.FEDERATE_NAME ?? defaults.federateName;
+  const federateType = env.FEDERATE_TYPE ?? defaults.federateType;
+  const lookaheadMicros = parseBigint(
+    env.LOOKAHEAD_MICROS,
+    defaults.lookaheadMicros,
+    "LOOKAHEAD_MICROS"
+  );
+  const updatePeriodMicros = parseBigint(
+    env.UPDATE_PERIOD_MICROS,
+    defaults.updatePeriodMicros,
+    "UPDATE_PERIOD_MICROS"
+  );
+  const referenceFrameTimeoutMs = parseNumber(
+    env.REFERENCE_FRAME_TIMEOUT_MS,
+    defaults.referenceFrameTimeoutMs,
+    "REFERENCE_FRAME_TIMEOUT_MS"
+  );
+  const debug = parseBoolean(env.DEBUG, defaults.debug);
+  const logEveryN = parseNumber(env.LOG_EVERY_N, defaults.logEveryN, "LOG_EVERY_N");
+  const logLevel = parseLogLevel(env.LOG_LEVEL, debug ? "debug" : defaults.logLevel);
+
+  const config: SpacekitEnvConfig = {
+    rtiHost,
+    rtiPort,
+    rtiUseTls,
+    federationName,
+    federateName,
+    federateType,
+    lookaheadMicros,
+    updatePeriodMicros,
+    referenceFrameTimeoutMs,
+    logLevel,
+    logEveryN,
+    debug,
+  };
+
+  validateRequired(config, options.required);
+
+  if (options.logResolved && options.logger) {
+    options.logger.info(
+      "Resolved Spacekit env config.",
+      redactConfig(config) as unknown as Record<string, unknown>
+    );
+  }
+
+  return config;
+}
+
+function validateRequired(
+  config: SpacekitEnvConfig,
+  required?: Array<"federationName" | "federateName" | "federateType">
+): void {
+  if (!required || required.length === 0) return;
+  const missing = required.filter((key) => !config[key]);
+  if (missing.length > 0) {
+    throw new Error(`Missing required env vars: ${missing.join(", ")}`);
+  }
+}
+
+function redactConfig(config: SpacekitEnvConfig): SpacekitEnvConfig {
+  return { ...config };
+}
+
+function parseBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined) return fallback;
+  const normalized = value.toLowerCase();
+  return normalized === "true" || normalized === "1" || normalized === "yes";
+}
+
+function parseNumber(value: string | undefined, fallback: number, label: string): number {
+  if (value === undefined || value === "") return fallback;
+  const parsed = Number(value);
+  if (Number.isFinite(parsed)) return parsed;
+  throw new Error(`Invalid number for ${label}: ${value}`);
+}
+
+function parseBigint(value: string | undefined, fallback: bigint, label: string): bigint {
+  if (value === undefined || value === "") return fallback;
+  try {
+    return BigInt(value);
+  } catch {
+    throw new Error(`Invalid bigint for ${label}: ${value}`);
+  }
+}
+
+function parseLogLevel(value: string | undefined, fallback: LogLevel): LogLevel {
+  if (!value) return fallback;
+  const normalized = value.toLowerCase() as LogLevel;
+  if (
+    normalized === "debug" ||
+    normalized === "info" ||
+    normalized === "warn" ||
+    normalized === "error"
+  ) {
+    return normalized;
+  }
+  return fallback;
+}

package/src/federate.ts

@@ -0,0 +1,205 @@
+import {
+  RTIAmbassador,
+  type RTIAmbassadorOptions,
+  type FederateAmbassador,
+  type JoinResult,
+  ResignAction,
+} from "@hla4ts/hla-api";
+import type { FomModuleSet } from "@hla4ts/hla-api";
+import { renderFomXml } from "@hla4ts/fom-codegen";
+import type { SpacekitFederateConfig, FederateHandlers, SpacekitFomConfig } from "./types.ts";
+
+function createCompositeFederateAmbassador(
+  handlerChain: FederateHandlers[]
+): FederateAmbassador {
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (typeof prop !== "string") return undefined;
+        const callbacks = handlerChain
+          .map((handler) => {
+            const fn = handler[prop as keyof FederateHandlers];
+            if (typeof fn !== "function") return null;
+            return { handler, fn };
+          })
+          .filter(
+            (entry): entry is { handler: FederateHandlers; fn: (...args: unknown[]) => void } =>
+              entry !== null
+          );
+        if (callbacks.length === 0) {
+          return undefined;
+        }
+        return (...args: unknown[]) => {
+          for (const callback of callbacks) {
+            callback.fn.call(callback.handler, ...args);
+          }
+        };
+      },
+    }
+  ) as FederateAmbassador;
+}
+
+export class SpacekitFederate {
+  private readonly _config: SpacekitFederateConfig;
+  private readonly _handlerChain: FederateHandlers[];
+  private readonly _ambassador: FederateAmbassador;
+  private _rti: RTIAmbassador | null = null;
+  private _joinResult: JoinResult | null = null;
+
+  constructor(config: SpacekitFederateConfig, handlers: FederateHandlers = {}) {
+    this._config = config;
+    this._handlerChain = [handlers];
+    this._ambassador = createCompositeFederateAmbassador(this._handlerChain);
+  }
+
+  get rtiAmbassador(): RTIAmbassador | null {
+    return this._rti;
+  }
+
+  get joinResult(): JoinResult | null {
+    return this._joinResult;
+  }
+
+  async start(): Promise<JoinResult> {
+    const rti = new RTIAmbassador(this._config.rti as RTIAmbassadorOptions);
+    this._rti = rti;
+
+    await rti.connect(this._ambassador, this._config.connection);
+
+    const modules = await buildFomModules(this._config.fom);
+    const { federateName, federateType, federationName } = this._config;
+
+    let joinResult: JoinResult;
+    if (modules && modules.length > 0) {
+      if (federateName) {
+        joinResult = await rti.joinFederationExecutionWithNameAndModules(
+          federateName,
+          federateType,
+          federationName,
+          modules
+        );
+      } else {
+        joinResult = await rti.joinFederationExecutionWithModules(
+          federateType,
+          federationName,
+          modules
+        );
+      }
+    } else if (federateName) {
+      joinResult = await rti.joinFederationExecutionWithName(
+        federateName,
+        federateType,
+        federationName
+      );
+    } else {
+      joinResult = await rti.joinFederationExecution(federateType, federationName);
+    }
+
+    this._joinResult = joinResult;
+    return joinResult;
+  }
+
+  async stop(options: {
+    resignTimeoutMs?: number;
+    disconnectTimeoutMs?: number;
+    force?: boolean;
+    onError?: (phase: "resign" | "disconnect" | "force-disconnect", error: Error) => void;
+  } = {}): Promise<void> {
+    if (!this._rti) return;
+    const resignAction = this._config.resignAction ?? ResignAction.DELETE_OBJECTS_THEN_DIVEST;
+    const resignTimeoutMs = options.resignTimeoutMs ?? 5000;
+    const disconnectTimeoutMs = options.disconnectTimeoutMs ?? 5000;
+    const force = options.force ?? true;
+    let forceDisconnect = false;
+
+    try {
+      await withTimeout(
+        this._rti.resignFederationExecution(resignAction),
+        resignTimeoutMs,
+        "Resign timed out"
+      );
+    } catch (err) {
+      forceDisconnect = true;
+      options.onError?.(
+        "resign",
+        err instanceof Error ? err : new Error(String(err))
+      );
+    }
+
+    try {
+      await withTimeout(
+        this._rti.disconnect(),
+        disconnectTimeoutMs,
+        "Disconnect timed out"
+      );
+    } catch (err) {
+      forceDisconnect = true;
+      options.onError?.(
+        "disconnect",
+        err instanceof Error ? err : new Error(String(err))
+      );
+    }
+
+    if (force && forceDisconnect) {
+      try {
+        await this._rti.disconnectNow();
+      } catch (err) {
+        options.onError?.(
+          "force-disconnect",
+          err instanceof Error ? err : new Error(String(err))
+        );
+      }
+    }
+
+    this._rti = null;
+    this._joinResult = null;
+  }
+
+  addHandlers(extra: FederateHandlers): void {
+    this._handlerChain.push(extra);
+  }
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
+  if (timeoutMs <= 0) {
+    return promise;
+  }
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutHandle = setTimeout(() => reject(new Error(message)), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  }
+}
+
+async function buildFomModules(config?: SpacekitFomConfig): Promise<FomModuleSet | undefined> {
+  if (!config) return undefined;
+  const modules: FomModuleSet = [];
+  if (config.baseModules) {
+    modules.push(...config.baseModules);
+  }
+  const extension = config.extension;
+  if (extension) {
+    let xml = extension.xml;
+    if (!xml && extension.registry) {
+      xml = extension.registry.toXml({
+        format: extension.format ?? "omt",
+        ...extension.outputOptions,
+      });
+    }
+    if (!xml && extension.model) {
+      xml = renderFomXml(extension.model, {
+        format: extension.format ?? "omt",
+        ...extension.outputOptions,
+      });
+    }
+    if (xml) {
+      modules.push({ type: "inline", content: xml });
+    }
+  }
+  return modules.length > 0 ? modules : undefined;
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @hla4ts/spacekit
+ *
+ * SEE-first lifecycle + declarative helpers for HLA federates.
+ */
+
+export { SpacekitFederate } from "./federate.ts";
+export type { SpacekitFederateConfig, SpacekitFomConfig, FederateHandlers } from "./types.ts";
+export * from "./object-model.ts";
+export * from "./declarative.ts";
+export * from "./declarative-runtime.ts";
+export * from "./decorators.ts";
+export * from "./entity.ts";
+export {
+  SpacekitApp as BaseSpacekitApp,
+} from "./app.ts";
+export type {
+  SpacekitBootstrapper,
+  SpacekitAppConfig as BaseSpacekitAppConfig,
+  RegisterObjectOptions,
+  TrackOptions,
+  TrackRecord,
+} from "./app.ts";
+export { SpacekitApp } from "./see-app.ts";
+export type { MissingReferenceFrameMode, SpacekitAppOptions } from "./see-app.ts";
+export * from "./time-advance.ts";
+export * from "./env.ts";
+export * from "./logger.ts";
+export * from "./spacefom-entities.ts";
+export * from "./spacefom-interactions.ts";
+export * from "./spacefom-bootstrap.ts";
+export * from "./spacefom-config.ts";
+export * from "./declare-spacefom.ts";
+export {
+  HLAunicodeStringCoder,
+  SpaceFomExecutionMode,
+  SpaceFomMtrMode,
+  SpaceFomSyncPointLabels,
+  loadSpaceFomModules,
+  SpaceFomBaseModules,
+} from "@hla4ts/spacefom";
+export type {
+  SpaceFomBaseModuleName,
+  SpaceFomModuleFormat,
+  SpaceFomCoder,
+  AttitudeQuaternion,
+  Matrix3,
+  SpaceTimeCoordinateState,
+  Vector3,
+} from "@hla4ts/spacefom";
+export * from "@hla4ts/spacefom";

package/src/logger.ts

@@ -0,0 +1,45 @@
+import type { LogLevel, SpacekitLogger } from "./env.ts";
+
+const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+export interface CreateLoggerOptions {
+  level: LogLevel;
+  scope?: string;
+}
+
+export function createConsoleLogger(options: CreateLoggerOptions): SpacekitLogger {
+  const threshold = LOG_LEVEL_ORDER[options.level];
+  const scope = options.scope ?? "spacekit";
+
+  function emit(level: LogLevel, message: string, data?: Record<string, unknown>) {
+    if (LOG_LEVEL_ORDER[level] < threshold) return;
+    const prefix = `[${scope}] ${new Date().toISOString()} ${level.toUpperCase()}:`;
+    if (data) {
+      console.log(prefix, message, data);
+    } else {
+      console.log(prefix, message);
+    }
+  }
+
+  const logger: SpacekitLogger = {
+    debug: (message: string, data?: Record<string, unknown>) => emit("debug", message, data),
+    info: (message: string, data?: Record<string, unknown>) => emit("info", message, data),
+    warn: (message: string, data?: Record<string, unknown>) => emit("warn", message, data),
+    error: (message: string, data?: Record<string, unknown>) => emit("error", message, data),
+  };
+  return withDebugEnabled(logger, options.level === "debug");
+}
+
+export function isDebugEnabled(logger: SpacekitLogger): boolean {
+  return (logger as { __debugEnabled?: boolean }).__debugEnabled === true;
+}
+
+export function withDebugEnabled(logger: SpacekitLogger, enabled: boolean): SpacekitLogger {
+  (logger as { __debugEnabled?: boolean }).__debugEnabled = enabled;
+  return logger;
+}