@kwirthmagnify/kwirth-common-back 0.5.51 → 0.5.53

package/dist/IExtension.d.ts

@@ -1,4 +1,22 @@
 import { IExtensionExportOptions, IExtensionImportResult } from '@kwirthmagnify/kwirth-common';
+/**
+ * What an extension writes its log with. The core builds it knowing who the extension is, so the
+ * line comes out identified — '[prov] [ERRO] [longhorn] ...' — and the extension only writes the
+ * message.
+ *
+ * It lives here, and not next to one family's contract, because the need is the same for all of
+ * them: before this, anything that was not a channel had only `console.log`, which comes out with no
+ * timestamp, no level and no component, and turns a failure into something that reads like a routine
+ * trace.
+ *
+ * Three levels and no more. An `info` nobody can filter out is what buries a log, and a failure that
+ * goes out as `info` is a failure nobody sees.
+ */
+export interface IExtensionLogger {
+    info(message: unknown): void;
+    warning(message: unknown): void;
+    error(message: unknown): void;
+}
 export interface IExtension {
     exportConfig?(options: IExtensionExportOptions): Promise<unknown>;
     importConfig?(config: unknown): Promise<IExtensionImportResult>;

package/dist/IProvider.d.ts

@@ -1,5 +1,5 @@
 import { KwirthData, IConfigFieldDef } from '@kwirthmagnify/kwirth-common';
-import { IExtension } from './IExtension';
+import { IExtension, IExtensionLogger } from './IExtension';
 /**
  * Minimal interface representing the channel side that providers interact with.
  * Providers only need to call processProviderEvent on their subscribers.
@@ -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.
@@ -86,6 +118,12 @@ export interface IProviderStats {
     /** Errores al entregar, con el mismo criterio: acumulado y barato. */
     errors?: number;
 }
+/**
+ * What a provider writes its log with. It is the common extension logger — the need turned out to be
+ * the same for senders, so it lives in IExtension. Kept as a name of its own because it is already
+ * published and providers compile against it.
+ */
+export type IProviderLogger = IExtensionLogger;
 /**
  * Interface that all provider plugins must implement.
  * Use 'any' for clusterInfo to avoid pulling in kubernetes/docker dependencies.
@@ -135,6 +173,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/dist/ISender.d.ts

@@ -1,5 +1,5 @@
 import { ISenderMessage, ISenderConfig, ISenderAccess, ISenderStoredConfig, ISenderResult, TConfigFieldType, IConfigFieldDef, IExtensionNodeMeta } from '@kwirthmagnify/kwirth-common';
-import { IExtension } from './IExtension';
+import { IExtension, IExtensionLogger } from './IExtension';
 export { ISenderMessage, ISenderConfig, ISenderAccess, ISenderStoredConfig, ISenderResult };
 /** @deprecated usa TConfigFieldType, comun a todas las extensiones. */
 export type SenderFieldType = TConfigFieldType;
@@ -17,6 +17,18 @@ export interface ISender extends IExtension {
     getConfigSchema?(): ISenderFieldDef[];
     getNodeMeta?(): ISenderNodeMeta;
     send(configName: string, message: ISenderMessage): Promise<ISenderResult | void>;
+    /**
+     * The core hands the sender a logger that already knows who it is, as soon as it builds it.
+     *
+     * OPTIONAL and read defensively, like the rest: a sender that does not implement it keeps writing
+     * wherever it was writing, and an older core that never calls it leaves the sender on its own
+     * fallback.
+     *
+     * ⚠️ This is for what the sender says ABOUT ITSELF — a delivery that failed, a configuration it
+     * could not read. It is not the place for what it delivers: a sender's job is to put a message
+     * somewhere, and that somewhere is decided by its configuration, not by this.
+     */
+    setLogger?(logger: IExtensionLogger): void;
     sendBatch?(configName: string, messages: ISenderMessage[]): Promise<ISenderResult | void>;
     fetchStatus?(configName: string, externalId: string): Promise<string | undefined>;
     evalFilter?(configName: string, message: ISenderMessage, forward: () => Promise<void>): Promise<void>;

package/package.json

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