@m1kad0/hannah-grpc-lib 0.3.0 → 0.4.0

package/README.md

@@ -121,3 +121,30 @@ line.
   asynchronous, connection problems are reported once and retried with backoff.
 - **Process exit:** an open connection keeps Node's event loop alive. Call
   `shipper.close()` on shutdown.
+
+## Calling Hannah Core (`client`)
+
+Works with `hannah.v1` types and falls back to the previous, unversioned API when Hannah
+Core is too old for `hannah.v1`, so a component can be updated before Core.
+
+```ts
+import * as grpc from '@grpc/grpc-js';
+import { client } from '@m1kad0/hannah-grpc-lib';
+
+const hannah = new client.VersionedClient(address, grpc.credentials.createInsecure(), {
+    warn: message => log.warn(message),         // defaults to console.warn
+});
+const c = await hannah.resolve();               // a v1.hannah.HannahServiceClient
+c.submitText({ text: '...', sourceService: 'x', sourceUserId: '' }, (err, res) => { /* ... */ });
+// after a reconnect (e.g. a stream was lost):
+hannah.reset();
+// on shutdown:
+hannah.close();
+```
+
+- **Probe:** once per connection, `GetSatellites` on the `hannah.v1` path decides. If
+  Core answers `UNIMPLEMENTED`, all calls use the previous API and `warn` is called once.
+  Any other error isn't cached; the next `resolve()` probes again. A single method Core
+  doesn't know yet does not switch the connection.
+- **Headers:** `x-proto-version` and `x-compat-version` are attached by default
+  (`client.DEFAULT_INTERCEPTORS`); pass `clientOptions` to override.

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Calling Hannah Core across API generations (hannah.v1 with fallback to N−1).
+ * Exported as the `client` namespace of '@m1kad0/hannah-grpc-lib'. See versioned.ts.
+ */
+export { VersionedClient, legacyDefinition, protoVersionInterceptor, DEFAULT_INTERCEPTORS, DEFAULT_PROBE_TIMEOUT_MS, CURRENT_SERVICE, LEGACY_SERVICE, } from './versioned';
+export type { HannahServiceClient, VersionedClientOptions } from './versioned';

package/dist/client/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_SERVICE = exports.CURRENT_SERVICE = exports.DEFAULT_PROBE_TIMEOUT_MS = exports.DEFAULT_INTERCEPTORS = exports.protoVersionInterceptor = exports.legacyDefinition = exports.VersionedClient = void 0;
+/**
+ * Calling Hannah Core across API generations (hannah.v1 with fallback to N−1).
+ * Exported as the `client` namespace of '@m1kad0/hannah-grpc-lib'. See versioned.ts.
+ */
+var versioned_1 = require("./versioned");
+Object.defineProperty(exports, "VersionedClient", { enumerable: true, get: function () { return versioned_1.VersionedClient; } });
+Object.defineProperty(exports, "legacyDefinition", { enumerable: true, get: function () { return versioned_1.legacyDefinition; } });
+Object.defineProperty(exports, "protoVersionInterceptor", { enumerable: true, get: function () { return versioned_1.protoVersionInterceptor; } });
+Object.defineProperty(exports, "DEFAULT_INTERCEPTORS", { enumerable: true, get: function () { return versioned_1.DEFAULT_INTERCEPTORS; } });
+Object.defineProperty(exports, "DEFAULT_PROBE_TIMEOUT_MS", { enumerable: true, get: function () { return versioned_1.DEFAULT_PROBE_TIMEOUT_MS; } });
+Object.defineProperty(exports, "CURRENT_SERVICE", { enumerable: true, get: function () { return versioned_1.CURRENT_SERVICE; } });
+Object.defineProperty(exports, "LEGACY_SERVICE", { enumerable: true, get: function () { return versioned_1.LEGACY_SERVICE; } });

package/dist/client/versioned.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Client side of the N/N−1 API generations (hannah-proto#11).
+ *
+ * The caller works with the current generation's types (hannah.v1) only. Which method path
+ * goes out on the wire is decided once per connection by a probe:
+ *
+ * - `/hannah.v1.HannahService/<Method>` if Core serves the current generation,
+ * - `/hannah.HannahService/<Method>` (N−1) if the probe gets UNIMPLEMENTED, i.e. Core is
+ *   too old to know v1. A warning says so once per connection.
+ *
+ * Both paths use the current generation's (de)serializers, mirroring Core's N−1 servicer:
+ * the packages are wire-identical, only the package name in the path differs.
+ *
+ * Only the probe decides. UNIMPLEMENTED on an ordinary call can also mean that just this one
+ * method is newer than the Core, which must not switch the whole connection. Any other probe
+ * failure (Core down, ...) is no version signal: nothing is cached, the next call probes
+ * again. Call `reset()` when a connection is re-established (e.g. a stream reconnects).
+ */
+import * as grpc from '@grpc/grpc-js';
+import { v1 } from '@m1kad0/hannah-proto';
+export declare const CURRENT_SERVICE = "hannah.v1.HannahService";
+export declare const LEGACY_SERVICE = "hannah.HannahService";
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 5000;
+export type HannahServiceClient = v1.hannah.HannahServiceClient;
+/** Attaches x-proto-version to every call (diagnostics only since hannah#359). */
+export declare const protoVersionInterceptor: grpc.Interceptor;
+/**
+ * x-proto-version and x-compat-version. hannah-proto's compat interceptor is keyed by the
+ * full method path across both packages, so the N−1 path gets its own schema's value.
+ */
+export declare const DEFAULT_INTERCEPTORS: grpc.Interceptor[];
+type ServiceDefinition = typeof v1.hannah.HannahServiceService;
+/** The v1 service definition with every path moved to the unversioned (N−1) service. */
+export declare function legacyDefinition(definition?: ServiceDefinition): ServiceDefinition;
+export interface VersionedClientOptions {
+    /** Passed to both clients; `interceptors` defaults to DEFAULT_INTERCEPTORS. */
+    clientOptions?: Partial<grpc.ClientOptions>;
+    probeTimeoutMs?: number;
+    /** Where the "Core is outdated" warning goes. Defaults to console.warn. */
+    warn?: (message: string) => void;
+}
+/**
+ * v1 client that falls back to N−1 when Core is too old. Both clients share one channel.
+ *
+ *     const clients = new VersionedClient(address, grpc.credentials.createInsecure());
+ *     const client = await clients.resolve();
+ *     client.submitText({ text: '...' }, (err, res) => ...);
+ */
+export declare class VersionedClient {
+    private readonly current;
+    private readonly legacyClient;
+    private readonly probeTimeoutMs;
+    private readonly warn;
+    private useLegacy;
+    private probing;
+    constructor(address: string, credentials: grpc.ChannelCredentials, options?: VersionedClientOptions);
+    /** True while calls go to the N−1 path. */
+    get legacy(): boolean;
+    /** Name of the service whose path is in use. */
+    get service(): string;
+    /** Forget the probe result; the next `resolve()` probes again. */
+    reset(): void;
+    /** The client for the path to use, probing first if that isn't known yet. */
+    resolve(): Promise<HannahServiceClient>;
+    close(): void;
+    private probe;
+}
+export {};

package/dist/client/versioned.js

@@ -0,0 +1,155 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionedClient = exports.DEFAULT_INTERCEPTORS = exports.protoVersionInterceptor = exports.DEFAULT_PROBE_TIMEOUT_MS = exports.LEGACY_SERVICE = exports.CURRENT_SERVICE = void 0;
+exports.legacyDefinition = legacyDefinition;
+/**
+ * Client side of the N/N−1 API generations (hannah-proto#11).
+ *
+ * The caller works with the current generation's types (hannah.v1) only. Which method path
+ * goes out on the wire is decided once per connection by a probe:
+ *
+ * - `/hannah.v1.HannahService/<Method>` if Core serves the current generation,
+ * - `/hannah.HannahService/<Method>` (N−1) if the probe gets UNIMPLEMENTED, i.e. Core is
+ *   too old to know v1. A warning says so once per connection.
+ *
+ * Both paths use the current generation's (de)serializers, mirroring Core's N−1 servicer:
+ * the packages are wire-identical, only the package name in the path differs.
+ *
+ * Only the probe decides. UNIMPLEMENTED on an ordinary call can also mean that just this one
+ * method is newer than the Core, which must not switch the whole connection. Any other probe
+ * failure (Core down, ...) is no version signal: nothing is cached, the next call probes
+ * again. Call `reset()` when a connection is re-established (e.g. a stream reconnects).
+ */
+const grpc = __importStar(require("@grpc/grpc-js"));
+const hannah_proto_1 = require("@m1kad0/hannah-proto");
+exports.CURRENT_SERVICE = 'hannah.v1.HannahService';
+exports.LEGACY_SERVICE = 'hannah.HannahService';
+exports.DEFAULT_PROBE_TIMEOUT_MS = 5000;
+/** Attaches x-proto-version to every call (diagnostics only since hannah#359). */
+const protoVersionInterceptor = (options, nextCall) => new grpc.InterceptingCall(nextCall(options), {
+    start(metadata, listener, next) {
+        metadata.set('x-proto-version', String(hannah_proto_1.PROTO_VERSION));
+        next(metadata, listener);
+    },
+});
+exports.protoVersionInterceptor = protoVersionInterceptor;
+/**
+ * x-proto-version and x-compat-version. hannah-proto's compat interceptor is keyed by the
+ * full method path across both packages, so the N−1 path gets its own schema's value.
+ */
+exports.DEFAULT_INTERCEPTORS = [
+    exports.protoVersionInterceptor,
+    hannah_proto_1.compat_interceptor.compatVersionInterceptor,
+];
+/** The v1 service definition with every path moved to the unversioned (N−1) service. */
+function legacyDefinition(definition = hannah_proto_1.v1.hannah.HannahServiceService) {
+    const prefix = `/${exports.CURRENT_SERVICE}/`;
+    const legacy = {};
+    for (const [name, method] of Object.entries(definition)) {
+        legacy[name] = { ...method, path: method.path.replace(prefix, `/${exports.LEGACY_SERVICE}/`) };
+    }
+    return legacy;
+}
+const LegacyHannahServiceClient = grpc.makeGenericClientConstructor(legacyDefinition(), 'HannahService');
+/**
+ * v1 client that falls back to N−1 when Core is too old. Both clients share one channel.
+ *
+ *     const clients = new VersionedClient(address, grpc.credentials.createInsecure());
+ *     const client = await clients.resolve();
+ *     client.submitText({ text: '...' }, (err, res) => ...);
+ */
+class VersionedClient {
+    current;
+    legacyClient;
+    probeTimeoutMs;
+    warn;
+    useLegacy = null; // null = not probed yet (or probe failed)
+    probing = null;
+    constructor(address, credentials, options = {}) {
+        const clientOptions = { interceptors: exports.DEFAULT_INTERCEPTORS, ...options.clientOptions };
+        this.current = new hannah_proto_1.v1.hannah.HannahServiceClient(address, credentials, clientOptions);
+        this.legacyClient = new LegacyHannahServiceClient(address, credentials, {
+            ...clientOptions,
+            channelOverride: this.current.getChannel(),
+        });
+        this.probeTimeoutMs = options.probeTimeoutMs ?? exports.DEFAULT_PROBE_TIMEOUT_MS;
+        this.warn = options.warn ?? ((message) => console.warn(message));
+    }
+    /** True while calls go to the N−1 path. */
+    get legacy() {
+        return this.useLegacy === true;
+    }
+    /** Name of the service whose path is in use. */
+    get service() {
+        return this.useLegacy ? exports.LEGACY_SERVICE : exports.CURRENT_SERVICE;
+    }
+    /** Forget the probe result; the next `resolve()` probes again. */
+    reset() {
+        this.useLegacy = null;
+    }
+    /** The client for the path to use, probing first if that isn't known yet. */
+    async resolve() {
+        if (this.useLegacy === null) {
+            this.probing ??= this.probe().finally(() => {
+                this.probing = null;
+            });
+            await this.probing;
+        }
+        return this.useLegacy ? this.legacyClient : this.current;
+    }
+    close() {
+        this.legacyClient.close();
+        this.current.close();
+    }
+    probe() {
+        return new Promise(resolve => {
+            const deadline = new Date(Date.now() + this.probeTimeoutMs);
+            this.current.getSatellites({}, new grpc.Metadata(), { deadline }, (err) => {
+                if (!err) {
+                    this.useLegacy = false;
+                }
+                else if (err.code === grpc.status.UNIMPLEMENTED) {
+                    this.useLegacy = true;
+                    this.warn(`Hannah Core doesn't serve ${exports.CURRENT_SERVICE} yet — falling back to ${exports.LEGACY_SERVICE}. Please update Hannah Core.`);
+                }
+                // Any other error is no version signal: stay undecided, the caller's own call
+                // fails the same way and its retry logic applies.
+                resolve();
+            });
+        });
+    }
+}
+exports.VersionedClient = VersionedClient;

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * Shared gRPC client code for Hannah components.
  *
- *     import { logging } from '@m1kad0/hannah-grpc-lib';
+ *     import { client, logging } from '@m1kad0/hannah-grpc-lib';
  *     const shipper = new logging.LogShipper({ component: 'msteams', version });
+ *     const hannah = new client.VersionedClient(address, credentials);
  */
+export * as client from './client';
 export * as logging from './logging';

package/dist/index.js

@@ -33,11 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logging = void 0;
+exports.logging = exports.client = void 0;
 /**
  * Shared gRPC client code for Hannah components.
  *
- *     import { logging } from '@m1kad0/hannah-grpc-lib';
+ *     import { client, logging } from '@m1kad0/hannah-grpc-lib';
  *     const shipper = new logging.LogShipper({ component: 'msteams', version });
+ *     const hannah = new client.VersionedClient(address, credentials);
  */
+exports.client = __importStar(require("./client"));
 exports.logging = __importStar(require("./logging"));

package/dist/logging/shipper.js

@@ -39,6 +39,7 @@ exports.formatAddress = formatAddress;
 const node_events_1 = require("node:events");
 const grpc = __importStar(require("@grpc/grpc-js"));
 const hannah_proto_1 = require("@m1kad0/hannah-proto");
+const versioned_1 = require("../client/versioned");
 const buffer_1 = require("./buffer");
 const instance_1 = require("./instance");
 const secrets_1 = require("./secrets");
@@ -68,14 +69,12 @@ const LEVELS = {
 function toLogLevel(level) {
     return typeof level === 'number' ? level : (LEVELS[level] ?? hannah_proto_1.logging.LogLevel.LOG_LEVEL_INFO);
 }
-const protocolVersionInterceptor = (options, nextCall) => new grpc.InterceptingCall(nextCall(options), {
-    start(metadata, listener, next) {
-        metadata.set('x-proto-version', String(hannah_proto_1.PROTO_VERSION));
-        next(metadata, listener);
-    },
-});
+// Discovery talks to Hannah Core, over hannah.v1 with fallback to N−1 (../client). The
+// collector's LogService stays on the unversioned package: that API is served by the
+// collector, not Core, and moves to a versioned one together with the collector.
+var infrastructure = hannah_proto_1.v1.infrastructure;
 const CLIENT_OPTIONS = {
-    interceptors: [protocolVersionInterceptor, hannah_proto_1.compat_interceptor.compatVersionInterceptor],
+    interceptors: versioned_1.DEFAULT_INTERCEPTORS,
 };
 function formatAddress(host, port) {
     if (host.includes(':') && !host.startsWith('[')) {
@@ -256,11 +255,16 @@ class LogShipper {
             backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
         }
     }
-    subscribeOnce(address, collectors, onMessage) {
+    async subscribeOnce(address, collectors, onMessage) {
+        // A new client per connection, so a reconnect probes the API generation again.
+        const clients = new versioned_1.VersionedClient(address, grpc.credentials.createInsecure(), {
+            clientOptions: CLIENT_OPTIONS,
+            warn: message => this.report('warn', message),
+        });
+        const client = await clients.resolve();
         return new Promise(resolve => {
-            const client = new hannah_proto_1.hannah.HannahServiceClient(address, grpc.credentials.createInsecure(), CLIENT_OPTIONS);
             const call = client.subscribeInfrastructure({
-                kinds: [hannah_proto_1.infrastructure.ServiceKind.SERVICE_KIND_LOG_COLLECTOR],
+                kinds: [infrastructure.ServiceKind.SERVICE_KIND_LOG_COLLECTOR],
             });
             this.discoveryCall = call;
             let settled = false;
@@ -270,7 +274,7 @@ class LogShipper {
                 }
                 settled = true;
                 this.discoveryCall = null;
-                client.close();
+                clients.close();
                 resolve(reason);
             };
             call.on('data', (msg) => {
@@ -398,7 +402,7 @@ class LogShipper {
 exports.LogShipper = LogShipper;
 /** Applies `msg` to `collectors` and reports whether it was relevant. */
 function applyInfrastructure(msg, collectors) {
-    const LOG_COLLECTOR = hannah_proto_1.infrastructure.ServiceKind.SERVICE_KIND_LOG_COLLECTOR;
+    const LOG_COLLECTOR = infrastructure.ServiceKind.SERVICE_KIND_LOG_COLLECTOR;
     if (msg.snapshot) {
         collectors.clear();
         for (const s of msg.snapshot.services) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1kad0/hannah-grpc-lib",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared gRPC client code for Hannah components (log shipping to the Hannah log collector)",
   "license": "UNLICENSED",
   "repository": {
@@ -25,11 +25,11 @@
   },
   "peerDependencies": {
     "@grpc/grpc-js": "^1.14.4",
-    "@m1kad0/hannah-proto": "^4.5.0"
+    "@m1kad0/hannah-proto": "^4.6.0"
   },
   "devDependencies": {
     "@grpc/grpc-js": "1.14.4",
-    "@m1kad0/hannah-proto": "4.5.0",
+    "@m1kad0/hannah-proto": "4.6.0",
     "@types/node": "^22.0.0",
     "typescript": "~6.0.3"
   }