@m1kad0/hannah-proto 2.1.0 → 3.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Protobuf/gRPC schema definitions for the Hannah voice assistant ecosystem (Core, satellites, WebUI, ioBroker adapter, Telegram bot, and other consumers). This repo is the single source of truth for the wire protocol shared across all of them.
 
-The `.proto` files live flat at the repo root, one per functional area — satellite control, event streaming, the ioBroker agent bridge, user registry, timers, automations, and so on. Nothing here is application code, just schema.
+The `.proto` files live under `hannah/`, one per functional area — satellite control, event streaming, the ioBroker agent bridge, user registry, timers, automations, and so on. Nothing here is application code, just schema.
 
 ## Distribution
 
@@ -20,6 +20,29 @@ Go has no separate package registry, so that tagged GitHub repo *is* the package
 
 Alongside the semver package/tag version, every release carries a single-integer `PROTO_VERSION` (see the `PROTO_VERSION` file). Hannah Core and its clients exchange this value on every call and reject a mismatch at runtime — that's the actual compatibility gate, not the semver tag. A breaking schema change requires bumping `PROTO_VERSION`; CI enforces this on every merge request via `buf breaking`.
 
+## Per-message compatibility: compat_version
+
+`PROTO_VERSION` is repo-wide — any breaking change anywhere bumps it, forcing every consumer to reject, even ones that never call the affected RPC. `compat_version` (`options.proto`) is a finer-grained, independent counter set on an individual message:
+
+```proto
+message Foo {
+  option (compat_version) = 2;
+  ...
+}
+```
+
+Bump a message's `compat_version` only when *that specific message* has an actual breaking change. A message with no `compat_version` option carries an implicit value of `1` — don't backfill the option onto messages that have never had a breaking change. This lets a consumer-side interceptor check only the messages a given RPC call actually uses instead of rejecting on any unrelated proto change.
+
+## Deprecating fields and RPCs
+
+Don't remove a field or RPC the moment it's unused — that forces every consumer to bump immediately, even ones that never touched it (see the `SetGroupRooms` incident that forced 9 unrelated components to bump, `hannah-proto#9`). Instead:
+
+1. Mark it `deprecated = true` (protobuf's built-in field/method option) and note why + what replaces it in a comment.
+2. Leave it in place until the next planned major cleanup, not the next release.
+3. Actually remove it (a breaking change, `PROTO_VERSION` bump) only during that cleanup, batched with other accumulated deprecations rather than one at a time.
+
+Go/TypeScript/Python codegen surface `deprecated = true` automatically (Go doc comment, TS `@deprecated` JSDoc) — no extra tooling or config needed.
+
 ## Compatibility checks
 
 CI runs `buf lint` and `buf breaking` (against `origin/master`) on every MR. To check a local branch against a specific released version:

package/dist/agent.js

@@ -3,7 +3,7 @@
 // versions:
 //   protoc-gen-ts_proto  v2.12.0
 //   protoc               unknown
-// source: agent.proto
+// source: hannah/agent.proto
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentSensorUpdate = exports.AgentBleUpdate = exports.AgentResidentAnswered = exports.AgentAskResident = exports.AgentResidentSnapshot = exports.AgentResident = exports.AgentRoomSnapshot = exports.AgentRoom_DisplayNamesEntry = exports.AgentRoom = exports.AgentDeviceSnapshot = exports.AgentDevice_RoomNamesEntry = exports.AgentDevice = exports.AgentStateValue = exports.AgentNotification = exports.AgentTextAnswer = exports.AgentSatelliteDeleted = exports.AgentSatelliteUpdate = exports.AgentSetResidentMood = exports.AgentSetResident = exports.AgentWatchMore = exports.AgentSetState = exports.AgentFirmwareEvent = exports.AgentCommand = exports.AgentTextCommand = exports.AgentStateUpdate = exports.AgentSatelliteControl = exports.AgentMessage = exports.ResidentType = exports.protobufPackage = void 0;
 /* eslint-disable */

package/dist/automation.js

@@ -3,7 +3,7 @@
 // versions:
 //   protoc-gen-ts_proto  v2.12.0
 //   protoc               unknown
-// source: automation.proto
+// source: hannah/automation.proto
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AutomationStateChanged = exports.AutomationSnapshot = exports.AutomationCommand = exports.AutomationRegister = exports.AutomationMessage = exports.protobufPackage = void 0;
 /* eslint-disable */

package/dist/car_state.js

@@ -3,7 +3,7 @@
 // versions:
 //   protoc-gen-ts_proto  v2.12.0
 //   protoc               unknown
-// source: car_state.proto
+// source: hannah/car_state.proto
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CarStateProto_WindowsEntry = exports.CarStateProto_DoorsEntry = exports.CarStateProto = exports.GetAllCarStatesResponse = exports.CarStateResponse = exports.protobufPackage = void 0;
 /* eslint-disable */

package/dist/compat_interceptor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-message compatibility check (hannah-proto#9, hannah#217).
+ *
+ * DRAFT / template — not wired into anything consuming it yet, needs
+ * review before use. See python/hannah_proto/compat_interceptor.py for the
+ * full design rationale (kept there as the canonical explanation, not
+ * repeated here to avoid drift between copies).
+ *
+ * REQUIRED_COMPAT_VERSIONS comes from generated `./compat_versions`
+ * (scripts/gen-compat-versions.js, run by generate.sh) rather than from
+ * runtime reflection on the generated message types — ts-proto is
+ * configured without `outputSchema`, so there is no descriptor/options
+ * data available on the generated types to read compat_version off of
+ * directly (unlike the Python/Go versions). See gen-compat-versions.js's
+ * header comment for what's unverified there.
+ */
+import type { Interceptor } from "@grpc/grpc-js";
+import { DEFAULT_COMPAT_VERSION } from "./compat_versions";
+export declare const COMPAT_VERSION_METADATA_KEY = "x-compat-version";
+export { DEFAULT_COMPAT_VERSION };
+/**
+ * grpc-js client interceptor: attaches x-compat-version metadata to every
+ * outgoing call, derived from the RPC method being invoked — so the server
+ * only has to reject calls genuinely affected by a breaking change, not
+ * every call after any unrelated schema change anywhere (see
+ * hannah-proto#9, the SetGroupRooms incident).
+ */
+export declare const compatVersionInterceptor: Interceptor;

package/dist/compat_interceptor.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compatVersionInterceptor = exports.DEFAULT_COMPAT_VERSION = exports.COMPAT_VERSION_METADATA_KEY = void 0;
+const grpc_js_1 = require("@grpc/grpc-js");
+const compat_versions_1 = require("./compat_versions");
+Object.defineProperty(exports, "DEFAULT_COMPAT_VERSION", { enumerable: true, get: function () { return compat_versions_1.DEFAULT_COMPAT_VERSION; } });
+exports.COMPAT_VERSION_METADATA_KEY = "x-compat-version";
+/** `methodName` is the bare RPC name (e.g. "SubmitText"), matching the keys
+ * gen-compat-versions.js writes into REQUIRED_COMPAT_VERSIONS. */
+function getRequiredCompatVersion(methodName) {
+    return compat_versions_1.REQUIRED_COMPAT_VERSIONS[methodName] ?? compat_versions_1.DEFAULT_COMPAT_VERSION;
+}
+/**
+ * grpc-js client interceptor: attaches x-compat-version metadata to every
+ * outgoing call, derived from the RPC method being invoked — so the server
+ * only has to reject calls genuinely affected by a breaking change, not
+ * every call after any unrelated schema change anywhere (see
+ * hannah-proto#9, the SetGroupRooms incident).
+ */
+const compatVersionInterceptor = (options, nextCall) => {
+    const methodName = options.method_definition.path.split("/").pop() ?? "";
+    const required = getRequiredCompatVersion(methodName);
+    return new grpc_js_1.InterceptingCall(nextCall(options), {
+        start(metadata, listener, next) {
+            metadata.set(exports.COMPAT_VERSION_METADATA_KEY, String(required));
+            next(metadata, listener);
+        },
+    });
+};
+exports.compatVersionInterceptor = compatVersionInterceptor;

package/dist/compat_versions.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_COMPAT_VERSION = 1;
+export declare const REQUIRED_COMPAT_VERSIONS: Record<string, number>;

package/dist/compat_versions.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRED_COMPAT_VERSIONS = exports.DEFAULT_COMPAT_VERSION = void 0;
+// Generated by scripts/gen-compat-versions.js — do not edit by hand.
+exports.DEFAULT_COMPAT_VERSION = 1;
+exports.REQUIRED_COMPAT_VERSIONS = {
+    "GetUsers": 1,
+    "GetUser": 1,
+    "LinkAccount": 1,
+    "UnlinkAccount": 1,
+    "SetTrustLevel": 1,
+    "SetSystemMessages": 1,
+    "SetAutomation": 1,
+    "Login": 1,
+    "CreateUser": 1,
+    "UpdateUser": 1,
+    "DeleteUser": 1,
+    "GetResidents": 1,
+    "GetDevices": 1,
+    "ControlDevice": 1,
+    "SubmitText": 1,
+    "SubmitVoice": 1,
+    "Announce": 1,
+    "Notify": 1,
+    "GetSatellites": 1,
+    "SetSatelliteRoom": 1,
+    "SetSatelliteDisplayName": 1,
+    "SetSatelliteOwner": 1,
+    "SetSatelliteSmalltalkFollowup": 1,
+    "DeleteSatellite": 1,
+    "GetRooms": 1,
+    "GetGroups": 1,
+    "CreateGroup": 1,
+    "UpdateGroup": 1,
+    "DeleteGroup": 1,
+    "SetGroupSatellites": 1,
+    "GetTriggers": 1,
+    "CreateTrigger": 1,
+    "UpdateTrigger": 1,
+    "DeleteTrigger": 1,
+    "GetAlarms": 1,
+    "CreateAlarm": 1,
+    "UpdateAlarm": 1,
+    "DeleteAlarm": 1,
+    "GetSettings": 1,
+    "UpdateConfig": 1,
+    "GetBleTags": 1,
+    "CreateBleTag": 1,
+    "UpdateBleTag": 1,
+    "DeleteBleTag": 1,
+    "GetCars": 1,
+    "CreateCar": 1,
+    "UpdateCar": 1,
+    "DeleteCar": 1,
+    "GetCarState": 1,
+    "GetAllCarStates": 1,
+    "SubscribeEvents": 1,
+    "TriggerFirmwareUpdate": 1,
+    "TriggerSatelliteRestart": 1,
+    "RequestSatelliteCapture": 1,
+    "ReleaseSatelliteCapture": 1,
+    "StreamSatelliteAudio": 1,
+    "TriggerPlink": 1,
+    "RegisterProxy": 1,
+    "SubmitSatelliteAudio": 1,
+    "NotifySatelliteRegistered": 1,
+    "NotifySatelliteGone": 1,
+    "ProvisionSatellite": 1,
+    "EnrollVoiceprint": 1,
+    "TimerConnect": 1,
+    "GetTimers": 1,
+    "DeleteTimer": 1,
+    "AgentConnect": 1,
+    "AutomationConnect": 1
+};

package/dist/control.d.ts

@@ -46,70 +46,6 @@ export interface AnnounceRequest {
     /** 0 = not set */
     userId: number;
 }
-export interface Satellite {
-    deviceId: string;
-    /** live-reported room (UDP/proxy registration); empty if not connected */
-    room: string;
-    /** IP:port of the UDP satellite; empty if not connected */
-    address: string;
-    /** human-readable name from Core DB (empty if not provisioned) */
-    displayName: string;
-    /** room assigned in Core DB, "" = unassigned */
-    roomId: string;
-    /** display name of room_id */
-    roomDisplayName: string;
-    /** UTC "YYYY-MM-DD HH:MM:SS" from Core DB, "" = never seen */
-    lastSeen: string;
-    /** true if currently live (UDP or proxy) */
-    connected: boolean;
-    /** true if connected and live room differs from room_id */
-    roomMismatch: boolean;
-    /** Person (User) assigned as owner in Core DB, 0 = unassigned. #31 */
-    ownerUserId: number;
-    /** display name of owner_user_id, "" if unassigned */
-    ownerDisplayName: string;
-    /** firmware_version of the satellite */
-    firmwareVersion: string;
-    /** true if the device has a new firmware available */
-    updateAvailable: boolean;
-    newVersion?: string | undefined;
-    /** #158: mic reopens after a Smalltalk answer instead of waiting for wake-word/PTT again */
-    smalltalkFollowupListen: boolean;
-}
-export interface GetSatellitesResponse {
-    satellites: Satellite[];
-}
-export interface SetSatelliteRoomRequest {
-    deviceId: string;
-    /** "" = unassign */
-    roomId: string;
-    /** requestor */
-    requestorId: number;
-}
-export interface SetSatelliteDisplayNameRequest {
-    deviceId: string;
-    displayName: string;
-    /** requestor */
-    requestorId: number;
-}
-export interface SetSatelliteOwnerRequest {
-    deviceId: string;
-    /** 0 = unassign */
-    userId: number;
-    /** requestor */
-    requestorId: number;
-}
-export interface SetSatelliteSmalltalkFollowupRequest {
-    deviceId: string;
-    enabled: boolean;
-    /** requestor */
-    requestorId: number;
-}
-export interface DeleteSatelliteRequest {
-    deviceId: string;
-    /** requestor */
-    requestorId: number;
-}
 export interface Room {
     roomId: string;
     displayName: string;
@@ -341,13 +277,6 @@ export declare const SubmitTextResponse: MessageFns<SubmitTextResponse>;
 export declare const SubmitVoiceRequest: MessageFns<SubmitVoiceRequest>;
 export declare const SubmitVoiceResponse: MessageFns<SubmitVoiceResponse>;
 export declare const AnnounceRequest: MessageFns<AnnounceRequest>;
-export declare const Satellite: MessageFns<Satellite>;
-export declare const GetSatellitesResponse: MessageFns<GetSatellitesResponse>;
-export declare const SetSatelliteRoomRequest: MessageFns<SetSatelliteRoomRequest>;
-export declare const SetSatelliteDisplayNameRequest: MessageFns<SetSatelliteDisplayNameRequest>;
-export declare const SetSatelliteOwnerRequest: MessageFns<SetSatelliteOwnerRequest>;
-export declare const SetSatelliteSmalltalkFollowupRequest: MessageFns<SetSatelliteSmalltalkFollowupRequest>;
-export declare const DeleteSatelliteRequest: MessageFns<DeleteSatelliteRequest>;
 export declare const Room: MessageFns<Room>;
 export declare const GetRoomsResponse: MessageFns<GetRoomsResponse>;
 export declare const GroupSatellite: MessageFns<GroupSatellite>;