@kwirthmagnify/kwirth-common-back 0.5.50 → 0.5.52

package/dist/IProvider.d.ts

@@ -7,6 +7,38 @@ import { IExtension } from './IExtension';
 export interface IProviderSubscriber {
     processProviderEvent(providerId: string, obj: any): void;
 }
+/**
+ * How a channel subscribes to a producer. The core hands one of these out already bound to the two
+ * ends — the producer and the channel asking for it — with 'clusterInfo.getProvider(id, this)'.
+ *
+ * It exists because a channel used to receive the provider OBJECT and call 'addSubscriber' on it,
+ * which meant the core could be bypassed without doing anything wrong, and therefore that its
+ * registry of who consumes what — the one the status graph is drawn from — was incomplete by
+ * construction. Going through the handle is what makes that registry true.
+ *
+ * ⚠️ The handle is NOT in the path of the data. It hands the provider the very same subscriber it
+ * was given, so events still travel straight from the producer to the consumer: no wrapper, no extra
+ * call, nothing per event. What runs is two functions per SUBSCRIPTION, which happens once when a tab
+ * opens. That is the whole reason it is shaped like this.
+ *
+ * One subscription per handle call, so a channel serving several instances subscribes once per
+ * instance with its own subscriber, and each one is unsubscribed on its own. The edge in the graph
+ * survives until the last of them is gone.
+ */
+export interface IProviderHandle {
+    /** Who produces: a provider ('events') or a pluvider ('plugin:agora'). */
+    readonly id: string;
+    /**
+     * Returns whatever the producer returned — normally a promise. It is handed back instead of
+     * swallowed because a provider that fails while taking a subscriber on board leaves an unhandled
+     * rejection, and that takes the whole core down. A consumer that wants to survive third-party
+     * providers wraps this in Promise.resolve().catch(); one that does not care ignores it.
+     */
+    subscribe(subscriber: IProviderSubscriber, data?: any): unknown;
+    /** Changes what this subscriber wants. Providers may not implement it; then nothing happens. */
+    updateSubscription(subscriber: IProviderSubscriber, data?: any): unknown;
+    unsubscribe(subscriber: IProviderSubscriber): unknown;
+}
 /**
  * Persistencia que el core inyecta al provider (mismo mecanismo que reciben los canales).
  * El booleano 'secret' decide el destino: true -> Secret de Kubernetes, false -> ConfigMap.
@@ -64,6 +96,39 @@ export type IProviderFieldDef = IConfigFieldDef;
 export interface IProviderStats {
     /** Cuantos suscriptores tiene AHORA. Cero significa que esta emitiendo para nadie. */
     subscribers: number;
+    /**
+     * ENTREGAS hechas desde que el provider arranco: una por cada vez que se llama a
+     * processProviderEvent, no una por evento producido. OPCIONAL: quien no lo lleve se muestra como
+     * "no informa", igual que el resto.
+     *
+     * Se cuentan entregas y no eventos a proposito. Un provider que produce mil eventos y los filtra
+     * todos no esta moviendo nada, y el numero util para quien opera es el trabajo que SE HACE. Ademas
+     * el sitio donde incrementar es inequivoco —justo donde ya se llama al suscriptor—, y eso hace que
+     * cablearlo en dieciseis providers no dependa de interpretar el codigo de cada uno.
+     *
+     * Es un ACUMULADO, no una tasa: quien lo lea resta dos lecturas y divide por el tiempo. El provider
+     * no debe saber nada de ventanas ni de medias — eso obligaria a guardar historia en el camino
+     * caliente, que es justo lo que no puede pasar.
+     *
+     * ⚠️ El incremento va JUNTO a la llamada al suscriptor, y es un entero. Nada
+     * de timestamps por evento, nada de arrays que crezcan, nada de objetos nuevos: lo que duele en
+     * Node no es el contador, es la basura que genera.
+     */
+    events?: number;
+    /** Errores al entregar, con el mismo criterio: acumulado y barato. */
+    errors?: number;
+}
+/**
+ * What a provider writes its log with. The core builds it and hands it over with 'setLogger', so the
+ * id is already in place and the provider only writes the message.
+ *
+ * Three levels and no more: an 'info' that nobody can filter out is what buries a log, and a failure
+ * that goes out as 'info' is a failure nobody sees.
+ */
+export interface IProviderLogger {
+    info(message: unknown): void;
+    warning(message: unknown): void;
+    error(message: unknown): void;
 }
 /**
  * Interface that all provider plugins must implement.
@@ -114,6 +179,20 @@ export interface IProvider extends IExtension {
      * estructuras aqui convierte una consulta en trabajo para todos.
      */
     getStats?(): IProviderStats;
+    /**
+     * The core hands the provider a logger that already knows who it is, right after building it.
+     *
+     * OPTIONAL, like everything in this block: a provider that does not implement it keeps writing
+     * wherever it was writing, and an older core that never calls it leaves the provider on its own
+     * fallback. Neither side needs the other to be up to date.
+     *
+     * Why it exists: channels get a 'backChannelObject' to log with, providers got nothing, so the
+     * only thing left to them was 'console.log'. That comes out with no timestamp, no level and no
+     * component — an error from a provider looks exactly like an informational line, and nothing can
+     * be filtered. With this, a provider's line reads '[provider] [ERROR] [longhorn] ...' and the
+     * provider does not even have to write its own id: the core puts it there.
+     */
+    setLogger?(logger: IProviderLogger): void;
     startProvider(): Promise<void>;
     stopProvider(): Promise<void>;
     router: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kwirthmagnify/kwirth-common-back",
-  "version": "0.5.50",
+  "version": "0.5.52",
   "description": "Backend interfaces for building Kwirth provider and channel plugins",
   "scripts": {
     "build": "tsc",