@kwirthmagnify/kwirth-common-back 0.5.52 → 0.5.54

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.
@@ -8,8 +8,13 @@ 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)'.
+ * How a consumer subscribes to a producer. The core hands one of these out already bound to the two
+ * ends — the producer and whoever asked for it — with 'clusterInfo.getProvider(id, this)'.
+ *
+ * The consumer is usually a channel, but it does NOT have to be: a PROVIDER may consume another
+ * provider, which is how a provider that owns shared configuration — cloud credentials, say — reaches
+ * the providers that need it. A provider subscribes from onProvidersReady(), never from
+ * startProvider(); see that method for why.
  *
  * 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
@@ -118,18 +123,6 @@ export interface IProviderStats {
     /** 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.
  * Use 'any' for clusterInfo to avoid pulling in kubernetes/docker dependencies.
@@ -189,10 +182,26 @@ export interface IProvider extends IExtension {
      * 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
+     * be filtered. With this, a provider's line reads '[prov] [ERRO] [longhorn] ...' and the
      * provider does not even have to write its own id: the core puts it there.
      */
-    setLogger?(logger: IProviderLogger): void;
+    setLogger?(logger: IExtensionLogger): void;
+    /**
+     * Called once, after EVERY provider and pluvider is registered and started. This is where a
+     * provider that CONSUMES another one subscribes to it.
+     *
+     * ⚠️ Do not subscribe from startProvider(). Whether the producer is registered by then depends on
+     * which startup loop instantiated it and on the order within that loop, so it would work or not
+     * for reasons you cannot see from your own code.
+     *
+     * 🔴 Whatever you subscribe to here, unsubscribe in stopProvider(). Skipping it does not leak one
+     * object: the producer keeps feeding an instance nobody uses any more, and every hot reload
+     * leaves another ghost behind holding whatever that instance held.
+     *
+     * OPTIONAL, like the rest of this block: a provider that does not implement it is never called,
+     * and an older core that does not know about it simply never calls anyone.
+     */
+    onProvidersReady?(): void | Promise<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.52",
+  "version": "0.5.54",
   "description": "Backend interfaces for building Kwirth provider and channel plugins",
   "scripts": {
     "build": "tsc",