@projectqai/proto 0.0.25 → 0.0.26

package/device.ts

@@ -0,0 +1,256 @@
+import { createClient, type Client, ConnectError, Code } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import { create, clone } from "@bufbuild/protobuf";
+import {
+	WorldService,
+	EntitySchema,
+	EntityFilterSchema,
+	ListEntitiesRequestSchema,
+	EntityChangeRequestSchema,
+	ConfigurableComponentSchema,
+	ConfigurableState,
+	EntityChange,
+	LifetimeSchema,
+	DeviceComponentSchema,
+	DeviceState,
+	ControllerSchema,
+	InteractivityComponentSchema,
+	type Entity,
+} from "./dist/world_pb.js";
+import { TimestampSchema } from "@bufbuild/protobuf/wkt";
+import {
+	MetricComponentSchema,
+	MetricSchema,
+	MetricKind,
+	MetricUnit,
+} from "./dist/metrics_pb.js";
+
+export type WorldClient = Client<typeof WorldService>;
+
+export { create } from "@bufbuild/protobuf";
+export {
+	EntitySchema,
+	EntityFilterSchema,
+	ListEntitiesRequestSchema,
+	EntityChangeRequestSchema,
+	EntityChange,
+	type Entity,
+} from "./dist/world_pb.js";
+
+export function connect(serverURL?: string): WorldClient {
+	const base = serverURL ?? process.env.HYDRIS_SERVER ?? "http://localhost:50051";
+	const transport = createGrpcTransport({ baseUrl: base, httpVersion: "2" });
+	return createClient(WorldService, transport);
+}
+
+export function push(client: WorldClient, ...entities: Entity[]) {
+	return client.push(create(EntityChangeRequestSchema, { changes: entities }));
+}
+
+// Schema → typed config inference
+
+type SchemaProperty = { readonly type: string; readonly default?: unknown; readonly [key: string]: unknown };
+type SchemaProperties = Readonly<Record<string, SchemaProperty>>;
+
+type InferProperty<P extends SchemaProperty> =
+	P extends { type: "string" } ? string :
+	P extends { type: "boolean" } ? boolean :
+	P extends { type: "number" | "integer" } ? number :
+	unknown;
+
+export type InferConfig<S extends SchemaProperties> = {
+	[K in keyof S]?: InferProperty<S[K]>;
+};
+
+function extractConfig<S extends SchemaProperties>(entity: Entity, schema: S): InferConfig<S> {
+	const raw = entity.config?.value ?? {};
+	const result: Record<string, unknown> = {};
+	for (const [key, prop] of Object.entries(schema)) {
+		const val = raw[key];
+		result[key] = (val !== undefined && val !== null && typeof val === prop.type) ? val : prop.default;
+	}
+	return result as InferConfig<S>;
+}
+
+// Attach options
+
+export type HealthResult = boolean | Record<number, { label: string; value: number | bigint }>;
+
+export interface AttachOptions<S extends SchemaProperties> {
+	id: string;
+	label?: string;
+	controller?: string;
+	device?: { category?: string };
+	icon?: string;
+	schema: S;
+	run: (client: WorldClient, config: InferConfig<S>, signal: AbortSignal) => Promise<void>;
+	health?: () => HealthResult | Promise<HealthResult>;
+	interval?: number;
+	signal?: AbortSignal;
+}
+
+// Internals
+
+const DEFAULT_INTERVAL = 10_000;
+
+function isCanceled(err: unknown): boolean {
+	return err instanceof ConnectError && err.code === Code.Canceled;
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+	return new Promise((resolve) => {
+		if (signal.aborted) return resolve();
+		const timer = setTimeout(resolve, ms);
+		signal.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+	});
+}
+
+/**
+ * Attach to a single device entity. Registers the entity, starts a heartbeat
+ * with TTL, watches for config changes, and runs the provided function.
+ *
+ * The health callback is polled every `interval` ms. Return `true` for healthy,
+ * `false` to skip the heartbeat (device expires via TTL), or a metrics map
+ * to push metrics alongside the heartbeat.
+ */
+export async function attach<S extends SchemaProperties>(opts: AttachOptions<S>) {
+	const client = connect();
+	const entityID = opts.id;
+	const interval = opts.interval ?? DEFAULT_INTERVAL;
+	const health = opts.health ?? (() => true);
+
+	const entity = create(EntitySchema, {
+		id: entityID,
+		...(opts.label && { label: opts.label }),
+		...(opts.controller && { controller: create(ControllerSchema, { id: opts.controller }) }),
+		...(opts.device && { device: create(DeviceComponentSchema, opts.device) }),
+		...(opts.icon && { interactivity: create(InteractivityComponentSchema, { icon: opts.icon }) }),
+		configurable: create(ConfigurableComponentSchema, {
+			schema: { type: "object", properties: opts.schema as Record<string, unknown> },
+		}),
+	});
+
+	// Register entity without device — device is managed by heartbeat
+	await push(client, create(EntitySchema, { ...entity, device: undefined }));
+	console.log(`attached entity=${entityID}`);
+
+	// Heartbeat
+
+	let heartbeatId: ReturnType<typeof setInterval> | null = null;
+
+	const pushHeartbeat = (result?: Record<number, { label: string; value: number | bigint }>) => {
+		const e = create(EntitySchema, {
+			id: entityID,
+			device: create(DeviceComponentSchema, { ...entity.device, state: DeviceState.DeviceStateActive }),
+			lifetime: create(LifetimeSchema, {
+				until: create(TimestampSchema, { seconds: BigInt(Math.floor((Date.now() + interval + 1_000) / 1000)) }),
+			}),
+		});
+		if (result) {
+			e.metric = create(MetricComponentSchema, {
+				metrics: Object.entries(result).map(([idStr, { label, value }]) =>
+					typeof value === "bigint"
+						? create(MetricSchema, { id: Number(idStr), label, kind: MetricKind.MetricKindCount, unit: MetricUnit.MetricUnitCount, val: { case: "uint64", value } })
+						: create(MetricSchema, { id: Number(idStr), label, kind: MetricKind.MetricKindGauge, unit: MetricUnit.MetricUnitNone, val: { case: "float", value } }),
+				),
+			});
+		}
+		return push(client, e);
+	};
+
+	const outerAbort = new AbortController();
+	const tick = async () => {
+		if (outerAbort.signal.aborted) return;
+		try {
+			const r = await health();
+			if (r !== false) await pushHeartbeat(r === true ? undefined : r);
+		} catch { /* health check failed */ }
+	};
+	tick();
+	heartbeatId = setInterval(tick, interval);
+
+	// Config state management
+
+	const pushState = async (entity: Entity, state: ConfigurableState, error?: string) => {
+		const cfg = entity.configurable
+			? clone(ConfigurableComponentSchema, entity.configurable)
+			: create(ConfigurableComponentSchema);
+		cfg.state = state;
+		cfg.error = error;
+		if (entity.config && state === ConfigurableState.ConfigurableStateActive) {
+			cfg.appliedVersion = entity.config.version;
+		}
+		await push(client, create(EntitySchema, { id: entityID, configurable: cfg })).catch(() => { });
+	};
+
+	let runningAbort: AbortController | null = null;
+	let currentConfigVersion = 0n;
+	let currentEntity: Entity | null = null;
+
+	const stop = () => {
+		if (runningAbort) {
+			const e = currentEntity;
+			runningAbort.abort();
+			runningAbort = null;
+			currentEntity = null;
+			console.log(`stopped entity=${entityID}`);
+			if (e) pushState(e, ConfigurableState.ConfigurableStateInactive);
+		}
+	};
+
+	const start = (e: Entity) => {
+		runningAbort = new AbortController();
+		currentEntity = e;
+		const childSignal = runningAbort.signal;
+
+		(async () => {
+			while (!childSignal.aborted) {
+				await pushState(e, ConfigurableState.ConfigurableStateStarting);
+				await pushState(e, ConfigurableState.ConfigurableStateActive);
+
+				try {
+					await opts.run(client, extractConfig(e, opts.schema), childSignal);
+				} catch (err) {
+					if (childSignal.aborted || isCanceled(err)) return;
+					console.error(`error, restarting entity=${entityID}`, err);
+					await pushState(e, ConfigurableState.ConfigurableStateFailed, String(err));
+				}
+
+				await sleep(5_000, childSignal);
+			}
+		})();
+	};
+
+	// Watch for config changes
+
+	const stream = client.watchEntities(
+		create(ListEntitiesRequestSchema, { filter: create(EntityFilterSchema, { id: entityID }) }),
+		...(opts.signal ? [{ signal: opts.signal }] : []),
+	);
+
+	try {
+		for await (const event of stream) {
+			if (!event.entity) continue;
+
+			if (event.t === EntityChange.EntityChangeExpired || event.t === EntityChange.EntityChangeUnobserved) {
+				stop();
+				continue;
+			}
+			if (event.t !== EntityChange.EntityChangeUpdated) continue;
+
+			const e = event.entity;
+			if (!e.config) { stop(); continue; }
+			if (e.config.version === currentConfigVersion && runningAbort) continue;
+
+			stop();
+			currentConfigVersion = e.config.version;
+			start(e);
+		}
+	} catch (err) {
+		if (!isCanceled(err)) throw err;
+	} finally {
+		stop();
+		outerAbort.abort();
+		if (heartbeatId) clearInterval(heartbeatId);
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projectqai/proto",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "author": "projectq-release-bot",
   "type": "module",
   "exports": {
@@ -8,15 +8,24 @@
       "types": "./dist/*_pb.d.ts",
       "import": "./dist/*_pb.js",
       "default": "./dist/*_pb.js"
+    },
+    "./device": {
+      "import": "./device.ts",
+      "default": "./device.ts"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "device.ts"
   ],
   "license": "Apache-2.0",
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.10.1"
   },
+  "dependencies": {
+    "@connectrpc/connect": "^2.0.0",
+    "@connectrpc/connect-node": "^2.0.0"
+  },
   "devDependencies": {
     "@bufbuild/protoc-gen-es": "^2.10.1"
   },

package/dist/controller_pb.d.ts

@@ -1,154 +0,0 @@
-// @generated by protoc-gen-es v2.10.2 with parameter "target=js+dts,import_extension=.js"
-// @generated from file controller.proto (package world, syntax proto3)
-/* eslint-disable */
-
-import type { GenEnum, GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
-import type { Message } from "@bufbuild/protobuf";
-import type { Entity } from "./world_pb.js";
-
-/**
- * Describes the file controller.proto.
- */
-export declare const file_controller: GenFile;
-
-/**
- * @generated from message world.ControllerReconciliationRequest
- */
-export declare type ControllerReconciliationRequest = Message<"world.ControllerReconciliationRequest"> & {
-  /**
-   * @generated from field: string controller = 1;
-   */
-  controller: string;
-};
-
-/**
- * Describes the message world.ControllerReconciliationRequest.
- * Use `create(ControllerReconciliationRequestSchema)` to create a new message.
- */
-export declare const ControllerReconciliationRequestSchema: GenMessage<ControllerReconciliationRequest>;
-
-/**
- * An entity with Config on this controller was added, changed, or removed.
- *
- * @generated from message world.ControllerDeviceConfigurationEvent
- */
-export declare type ControllerDeviceConfigurationEvent = Message<"world.ControllerDeviceConfigurationEvent"> & {
-  /**
-   * @generated from field: world.ControllerDeviceConfigurationEventType t = 1;
-   */
-  t: ControllerDeviceConfigurationEventType;
-
-  /**
-   * @generated from field: world.Entity config = 2;
-   */
-  config?: Entity;
-};
-
-/**
- * Describes the message world.ControllerDeviceConfigurationEvent.
- * Use `create(ControllerDeviceConfigurationEventSchema)` to create a new message.
- */
-export declare const ControllerDeviceConfigurationEventSchema: GenMessage<ControllerDeviceConfigurationEvent>;
-
-/**
- * @generated from message world.ControllerReconciliationEvent
- */
-export declare type ControllerReconciliationEvent = Message<"world.ControllerReconciliationEvent"> & {
-  /**
-   * @generated from oneof world.ControllerReconciliationEvent.event
-   */
-  event: {
-    /**
-     * @generated from field: world.ControllerDeviceConfigurationEvent config = 2;
-     */
-    value: ControllerDeviceConfigurationEvent;
-    case: "config";
-  } | { case: undefined; value?: undefined };
-};
-
-/**
- * Describes the message world.ControllerReconciliationEvent.
- * Use `create(ControllerReconciliationEventSchema)` to create a new message.
- */
-export declare const ControllerReconciliationEventSchema: GenMessage<ControllerReconciliationEvent>;
-
-/**
- * @generated from message world.RestartConnectorRequest
- */
-export declare type RestartConnectorRequest = Message<"world.RestartConnectorRequest"> & {
-  /**
-   * @generated from field: string controller = 1;
-   */
-  controller: string;
-
-  /**
-   * @generated from field: string entity_id = 2;
-   */
-  entityId: string;
-};
-
-/**
- * Describes the message world.RestartConnectorRequest.
- * Use `create(RestartConnectorRequestSchema)` to create a new message.
- */
-export declare const RestartConnectorRequestSchema: GenMessage<RestartConnectorRequest>;
-
-/**
- * @generated from message world.RestartConnectorResponse
- */
-export declare type RestartConnectorResponse = Message<"world.RestartConnectorResponse"> & {
-};
-
-/**
- * Describes the message world.RestartConnectorResponse.
- * Use `create(RestartConnectorResponseSchema)` to create a new message.
- */
-export declare const RestartConnectorResponseSchema: GenMessage<RestartConnectorResponse>;
-
-/**
- * @generated from enum world.ControllerDeviceConfigurationEventType
- */
-export enum ControllerDeviceConfigurationEventType {
-  /**
-   * @generated from enum value: ControllerDeviceConfigurationEventNew = 0;
-   */
-  ControllerDeviceConfigurationEventNew = 0,
-
-  /**
-   * @generated from enum value: ControllerDeviceConfigurationEventChanged = 1;
-   */
-  ControllerDeviceConfigurationEventChanged = 1,
-
-  /**
-   * @generated from enum value: ControllerDeviceConfigurationEventRemoved = 2;
-   */
-  ControllerDeviceConfigurationEventRemoved = 2,
-}
-
-/**
- * Describes the enum world.ControllerDeviceConfigurationEventType.
- */
-export declare const ControllerDeviceConfigurationEventTypeSchema: GenEnum<ControllerDeviceConfigurationEventType>;
-
-/**
- * @generated from service world.ControllerService
- */
-export declare const ControllerService: GenService<{
-  /**
-   * @generated from rpc world.ControllerService.Reconcile
-   */
-  reconcile: {
-    methodKind: "server_streaming";
-    input: typeof ControllerReconciliationRequestSchema;
-    output: typeof ControllerReconciliationEventSchema;
-  },
-  /**
-   * @generated from rpc world.ControllerService.RestartConnector
-   */
-  restartConnector: {
-    methodKind: "unary";
-    input: typeof RestartConnectorRequestSchema;
-    output: typeof RestartConnectorResponseSchema;
-  },
-}>;
-

package/dist/controller_pb.js

@@ -1,66 +0,0 @@
-// @generated by protoc-gen-es v2.10.2 with parameter "target=js+dts,import_extension=.js"
-// @generated from file controller.proto (package world, syntax proto3)
-/* eslint-disable */
-
-import { enumDesc, fileDesc, messageDesc, serviceDesc, tsEnum } from "@bufbuild/protobuf/codegenv2";
-import { file_world } from "./world_pb.js";
-
-/**
- * Describes the file controller.proto.
- */
-export const file_controller = /*@__PURE__*/
-  fileDesc("ChBjb250cm9sbGVyLnByb3RvEgV3b3JsZCI1Ch9Db250cm9sbGVyUmVjb25jaWxpYXRpb25SZXF1ZXN0EhIKCmNvbnRyb2xsZXIYASABKAkifQoiQ29udHJvbGxlckRldmljZUNvbmZpZ3VyYXRpb25FdmVudBI4CgF0GAEgASgOMi0ud29ybGQuQ29udHJvbGxlckRldmljZUNvbmZpZ3VyYXRpb25FdmVudFR5cGUSHQoGY29uZmlnGAIgASgLMg0ud29ybGQuRW50aXR5ImUKHUNvbnRyb2xsZXJSZWNvbmNpbGlhdGlvbkV2ZW50EjsKBmNvbmZpZxgCIAEoCzIpLndvcmxkLkNvbnRyb2xsZXJEZXZpY2VDb25maWd1cmF0aW9uRXZlbnRIAEIHCgVldmVudCJAChdSZXN0YXJ0Q29ubmVjdG9yUmVxdWVzdBISCgpjb250cm9sbGVyGAEgASgJEhEKCWVudGl0eV9pZBgCIAEoCSIaChhSZXN0YXJ0Q29ubmVjdG9yUmVzcG9uc2UqsQEKJkNvbnRyb2xsZXJEZXZpY2VDb25maWd1cmF0aW9uRXZlbnRUeXBlEikKJUNvbnRyb2xsZXJEZXZpY2VDb25maWd1cmF0aW9uRXZlbnROZXcQABItCilDb250cm9sbGVyRGV2aWNlQ29uZmlndXJhdGlvbkV2ZW50Q2hhbmdlZBABEi0KKUNvbnRyb2xsZXJEZXZpY2VDb25maWd1cmF0aW9uRXZlbnRSZW1vdmVkEAIyxQEKEUNvbnRyb2xsZXJTZXJ2aWNlElsKCVJlY29uY2lsZRImLndvcmxkLkNvbnRyb2xsZXJSZWNvbmNpbGlhdGlvblJlcXVlc3QaJC53b3JsZC5Db250cm9sbGVyUmVjb25jaWxpYXRpb25FdmVudDABElMKEFJlc3RhcnRDb25uZWN0b3ISHi53b3JsZC5SZXN0YXJ0Q29ubmVjdG9yUmVxdWVzdBofLndvcmxkLlJlc3RhcnRDb25uZWN0b3JSZXNwb25zZUIgWh5naXRodWIuY29tL3Byb2plY3RxYWkvcHJvdG8vZ29iBnByb3RvMw", [file_world]);
-
-/**
- * Describes the message world.ControllerReconciliationRequest.
- * Use `create(ControllerReconciliationRequestSchema)` to create a new message.
- */
-export const ControllerReconciliationRequestSchema = /*@__PURE__*/
-  messageDesc(file_controller, 0);
-
-/**
- * Describes the message world.ControllerDeviceConfigurationEvent.
- * Use `create(ControllerDeviceConfigurationEventSchema)` to create a new message.
- */
-export const ControllerDeviceConfigurationEventSchema = /*@__PURE__*/
-  messageDesc(file_controller, 1);
-
-/**
- * Describes the message world.ControllerReconciliationEvent.
- * Use `create(ControllerReconciliationEventSchema)` to create a new message.
- */
-export const ControllerReconciliationEventSchema = /*@__PURE__*/
-  messageDesc(file_controller, 2);
-
-/**
- * Describes the message world.RestartConnectorRequest.
- * Use `create(RestartConnectorRequestSchema)` to create a new message.
- */
-export const RestartConnectorRequestSchema = /*@__PURE__*/
-  messageDesc(file_controller, 3);
-
-/**
- * Describes the message world.RestartConnectorResponse.
- * Use `create(RestartConnectorResponseSchema)` to create a new message.
- */
-export const RestartConnectorResponseSchema = /*@__PURE__*/
-  messageDesc(file_controller, 4);
-
-/**
- * Describes the enum world.ControllerDeviceConfigurationEventType.
- */
-export const ControllerDeviceConfigurationEventTypeSchema = /*@__PURE__*/
-  enumDesc(file_controller, 0);
-
-/**
- * @generated from enum world.ControllerDeviceConfigurationEventType
- */
-export const ControllerDeviceConfigurationEventType = /*@__PURE__*/
-  tsEnum(ControllerDeviceConfigurationEventTypeSchema);
-
-/**
- * @generated from service world.ControllerService
- */
-export const ControllerService = /*@__PURE__*/
-  serviceDesc(file_controller, 0);
-