@axa-fr/slimfaas-planet-saver 0.37.0-pr.1061102 → 0.37.0-pr.1111153

package/README.md

@@ -4,7 +4,7 @@
 
 ![SlimFaas.png](https://github.com/AxaFrance/SlimFaas/blob/main/documentation/SlimFaas.png)
 
-A Vanilla JS project to save the planet. SlimFaas (https://github.com/SlimPlanet/slimfaas) is the slimest and simplest Function As A Service on Kubernetes.
+A Vanilla JS project to save the planet. SlimFaas (https://github.com/SlimPlanet/slimfaas) is the slimmest and simplest Function As A Service on Kubernetes.
 It works as a proxy that you can be deployed in your namespace.
 
 SlimFaas API can give to the frontend information about the infrastructure state. **It is a mind changer !**
@@ -12,7 +12,7 @@ SlimFaas API can give to the frontend information about the infrastructure state
 **Why?**
 
 Because in production instead of setting up 2 replicas of your API backend, you can set up 0 replicas and use an UX that will show the user that the backend is down instead !
-**@axa-fr/slimfaas-planet-saver** is here to for doing that easily.
+**@axa-fr/slimfaas-planet-saver** is here to for doing that easy.
 
 ![SlimFaasPlanetSaver.gif](https://github.com/AxaFrance/SlimFaas/blob/main/documentation/SlimfaasPlanetSaver.gif)
 
@@ -25,9 +25,9 @@ npm install @axa-fr/slimfaas-planet-saver
 Example usage with react :
 ```javascript
 import React, { useState, useEffect, useRef } from 'react';
-import { SlimFaasPlanetSaver } from "@axa-fr/slimfaas-planet-saver";
+import { SlimFaasPlanetSaver } from '@axa-fr/slimfaas-planet-saver';
 
-const PlanetSaver = ({ children, baseUrl, fetch }) => {
+const PlanetSaver = ({ children, baseUrl, fetch, noActivityTimeout=60000, behavior={} }) => {
     const [isFirstStart, setIsFirstStart] = useState(true);
     const environmentStarterRef = useRef(null);
 
@@ -39,9 +39,18 @@ const PlanetSaver = ({ children, baseUrl, fetch }) => {
         const instance = new SlimFaasPlanetSaver(baseUrl, {
             interval: 2000,
             fetch,
+            behavior,
             updateCallback: (data) => {
-                const allReady = data.every((item) => item.NumberReady >= 1);
-                if (allReady && isFirstStart) {
+                // Filter only the items that block the UI (WakeUp+BlockUI)
+                const blockingItems = data.filter(
+                    (item) => instance.getBehavior(item.Name) === 'WakeUp+BlockUI'
+                );
+
+                // If all blocking items are ready, set isFirstStart to false
+                const allBlockingReady = blockingItems.every(
+                    (item) => item.NumberReady >= 1
+                );
+                if (allBlockingReady && isFirstStart) {
                     setIsFirstStart(false);
                 }
             },
@@ -53,7 +62,8 @@ const PlanetSaver = ({ children, baseUrl, fetch }) => {
             overlayErrorMessage: 'An error occurred when starting environment. Please contact an administrator.',
             overlaySecondaryMessage: 'Startup should be fast, but if no machines are available it can take several minutes.',
             overlayLoadingIcon: '🌍',
-            overlayErrorSecondaryMessage: 'If the error persists, please contact an administrator.'
+            overlayErrorSecondaryMessage: 'If the error persists, please contact an administrator.',
+            noActivityTimeout
         });
 
         environmentStarterRef.current = instance;
@@ -78,8 +88,25 @@ const PlanetSaver = ({ children, baseUrl, fetch }) => {
 export default PlanetSaver;
 
 
+
+```
+
+### Usage:
+
+```jsx
+const behavior: {
+    "api-speech-to-text": "WakeUp",
+    "heavy-pdf-service": "WakeUp+BlockUI",
+    "deprecated-service": "None"
+}
+
+<PlanetSaver baseUrl="http://slimfaas.mycompany.com" fetch={window.fetch} behavior={behavior}>
+  <App />
+</PlanetSaver>
 ```
 
+---
+
 ## Run the demo
 
 ```javascript
@@ -88,3 +115,43 @@ cd slimfaas/src/SlimFaasPlanetSaver
 npm i
 npm run dev
 ```
+This will launch a local dev server, letting you see `SlimFaasPlanetSaver` in action.
+
+---
+
+## Configuration Options
+When you create a `new SlimFaasPlanetSaver(baseUrl, options)`, you can provide the following optional properties in the `options` object:
+
+| Property                  | Type                                                                 | Default                                                                                   | Description                                                                                                                                                                                                                     |
+|---------------------------|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| updateCallback            | `(data: any[]) => void`                                              | `() => {}`                                                                                | Function called after a successful fetch of the functions’ status. The array data includes objects with info about each function, for example: `[{ Name: 'myFunc', NumberReady: 1 }, ...]`.                                     |
+| errorCallback             | `(errorMessage: string) => void`                                     | `() => {}`                                                                                | Function called if an error occurs during the status fetch (e.g., network error). Receives an errorMessage string.                                                                                                              |
+| interval                  | `number`                                                             | `5000`                                                                                    | How frequently (in ms) the polling should run.                                                                                                                                                                                  |
+| overlayStartingMessage    | `string`                                                             | `"🌳 Starting the environment.... 🌳"`                                                    | Main message shown on the overlay when the environment is waking up.                                                                                                                                                            |
+| overlayNoActivityMessage  | `string`                                                             | `"Waiting activity to start environment..."`                                              | Message shown if there is no user activity (mouse movement) for too long, but the environment is not ready yet.                                                                                                                 |
+| overlayErrorMessage       | `string`                                                             | `"An error occurred while starting the environment."`                                     | Main message shown on the overlay if an error occurs (e.g., network error).                                                                                                                                                     |
+| overlaySecondaryMessage   | `string`                                                             | `"Startup should be fast, but if no machines are available it can take several minutes."` | Secondary message shown on the overlay when the environment is waking up.                                                                                                                                                       |
+| overlayErrorSecondaryMessage | `string`                                                             | `"If the error persists, please contact an administrator."`                               | Secondary message shown on the overlay when an error occurs.                                                                                                                                                                    |
+| overlayLoadingIcon        | `string`                                                             | `"🌍"`                                                                                    | Text or icon shown on the overlay. By default, it is animated to spin.                                                                                                                                                          |
+| noActivityTimeout         | `number`                                                             | `60000`                                                                                   | How long (in ms) to wait for mouse movement before concluding there is no activity. If no activity is detected, a different overlay message is displayed.                                                                       |
+| wakeUpTimeout             | `number`                                                             | `60000`                                                                                   | If a function was recently “woken up,” we’ll skip re-calling wake-up for that function within this timeout window (in ms).                                                                                                      |
+| fetch                     | `typeof fetch`                                                       | Global fetch                                                                              | Custom fetch function if you want to provide your own (e.g., for SSR, or if your environment doesn't have a global fetch).                                                                                                      |
+| behavior                  | `{ [functionName: string]: 'WakeUp+BlockUI' \| 'WakeUp' \| 'None' }` | *Not set; defaults each function to "WakeUp+BlockUI" if unspecified*                      | Allows you to override how each function is handled: 1. `"WakeUp+BlockUI"`: wakes the function and blocks the UI with the overlay until it’s ready. 2. `"WakeUp"`: wakes without blocking the UI. 3. `"None"`: no wake-up call. |
+
+### Notes on Behavior
+If a function is **not** specified in the behavior map, it defaults to `"WakeUp+BlockUI"`.
+
+- `"WakeUp+BlockUI"` means the overlay will be shown until that function is `NumberReady >= 1`.
+- `"WakeUp"` means we attempt to wake up the function, but do not keep the overlay shown specifically for that function.
+- `"None"` means the function will neither be woken up nor block the UI.
+
+### Lifecycle
+
+1. **Initialize**
+Call `instance.initialize()` to create the overlay elements, inject styles, and bind event listeners (e.g., for mouse movement).
+
+2. **Start Polling**
+Call `instance.startPolling()` to begin the periodic checks of the environment. If the environment is not ready, the overlay will appear.
+
+3. **Stop Polling / Cleanup**
+When your component unmounts or you no longer need to monitor the environment, call `instance.cleanup()`. This removes the overlay, styles, and any timers or event listeners.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@axa-fr/slimfaas-planet-saver",
   "private": false,
-  "version": "0.37.0-pr.1061102",
+  "version": "0.37.0-pr.1111153",
   "type": "module",
   "main": "./src/SlimFaasPlanetSaver.js",
   "module": "./src/SlimFaasPlanetSaver.js",

package/src/SlimFaasPlanetSaver.d.ts

@@ -1,56 +1,37 @@
-declare class SlimFaasPlanetSaver {
-    private baseUrl: string;
-    private updateCallback: (data: any) => void;
-    private errorCallback: (error: any) => void;
-    private interval: number;
-    private overlayStartingMessage: string;
-    private overlayNoActivityMessage: string;
-    private overlayErrorMessage: string;
-    private overlaySecondaryMessage: string;
-    private overlayErrorSecondaryMessage: string;
-    private overlayLoadingIcon: string;
-    private noActivityTimeout: number;
-    private wakeUpTimeout: number;
-    private fetch: typeof fetch;
-    private intervalId: number | null;
-    private isDocumentVisible: boolean;
-    private overlayElement: HTMLElement | null;
-    private spanElement: HTMLElement | null;
-    private styleElement: HTMLElement | null;
-    private isReady: boolean;
-    private id: number;
-    private cleanned: boolean;
-    private lastMouseMoveTime: number;
-    private handleMouseMove: () => void;
-    private handleVisibilityChange: () => void;
+export type BehaviorValue = 'WakeUp+BlockUI' | 'WakeUp' | 'None';
 
-    constructor(baseUrl: string, options?: {
-    updateCallback?: (data: any) => void,
-    errorCallback?: (error: any) => void,
-    interval?: number,
-    overlayStartingMessage?: string,
-    overlayNoActivityMessage?: string,
-    overlayErrorMessage?: string,
-    overlaySecondaryMessage?: string,
-    overlayErrorSecondaryMessage?: string,
-    overlayLoadingIcon?: string,
-    fetch?: typeof fetch
-    noActivityTimeout?: number
-    wakeUpTimeout?: number
-});
+export interface BehaviorMap {
+    [functionName: string]: BehaviorValue;
+}
 
-initialize(): void;
-wakeUpPods(data: Array<{ Name: string, NumberReady: number }>): Promise<void>;
-fetchStatus(): Promise<void>;
-setReadyState(isReady: boolean): void;
-startPolling(): void;
-stopPolling(): void;
-injectStyles(): void;
-createOverlay(): void;
-showOverlay(): void;
-hideOverlay(): void;
-updateOverlayMessage(newMessage: string, status?: 'waiting' | 'waiting-action' | 'error', secondaryMessage?: string | null): void;
-cleanup(): void;
+export interface SlimFaasPlanetSaverOptions {
+    updateCallback?: (data: any[]) => void;
+    errorCallback?: (errorMessage: string) => void;
+    interval?: number;
+    overlayStartingMessage?: string;
+    overlayNoActivityMessage?: string;
+    overlayErrorMessage?: string;
+    overlaySecondaryMessage?: string;
+    overlayErrorSecondaryMessage?: string;
+    overlayLoadingIcon?: string;
+    noActivityTimeout?: number;
+    wakeUpTimeout?: number;
+    fetch?: typeof fetch;
+    behavior?: BehaviorMap;
 }
 
-export default SlimFaasPlanetSaver;
+export default class SlimFaasPlanetSaver {
+    constructor(baseUrl: string, options?: SlimFaasPlanetSaverOptions);
+    initialize(): void;
+    startPolling(): void;
+    stopPolling(): void;
+    protected fetchStatus(): Promise<void>;
+    protected wakeUpPods(data: any[], lastWakeUpTime: number | null): Promise<boolean>;
+    protected setReadyState(isReady: boolean): void;
+    protected createOverlay(): void;
+    protected injectStyles(): void;
+    protected showOverlay(): void;
+    protected hideOverlay(): void;
+    protected updateOverlayMessage(newMessage: string, status?: string, secondaryMessage?: string | null): void;
+    cleanup(): void;
+}

package/src/SlimFaasPlanetSaver.js

@@ -4,7 +4,7 @@
     return tempUrl;
 }
 
-let id =1;
+let id = 1;
 
 export default class SlimFaasPlanetSaver {
     constructor(baseUrl, options = {}) {
@@ -21,6 +21,11 @@ export default class SlimFaasPlanetSaver {
         this.noActivityTimeout = options.noActivityTimeout || 60000;
         this.wakeUpTimeout = options.wakeUpTimeout || 60000;
         this.fetch = options.fetch || fetch;
+
+        // Ajout de la configuration de comportement
+        // Les valeurs possibles sont "WakeUp+BlockUI", "WakeUp", "None"
+        this.behavior = options.behavior || {};
+
         this.intervalId = null;
         this.isDocumentVisible = !document.hidden;
         this.overlayElement = null;
@@ -32,6 +37,14 @@ export default class SlimFaasPlanetSaver {
         this.lastWakeUpTime = null;
     }
 
+    /**
+     * Retourne le comportement à appliquer pour une fonction donnée
+     * S'il n'est pas renseigné, renvoie "WakeUp+BlockUI" par défaut
+     */
+    getBehavior(name) {
+        return this.behavior[name] || 'WakeUp+BlockUI';
+    }
+
     initialize() {
         this.cleanned = false;
         this.lastMouseMoveTime = Date.now();
@@ -43,8 +56,8 @@ export default class SlimFaasPlanetSaver {
 
         this.createOverlay();
         this.injectStyles();
-
     }
+
     handleMouseMove() {
         this.lastMouseMoveTime = Date.now();
     }
@@ -53,11 +66,21 @@ export default class SlimFaasPlanetSaver {
         this.isDocumentVisible = !document.hidden;
     }
 
+    /**
+     * Appelle le wake-up sur les fonctions dont le comportement n'est pas "None"
+     * et qui ne sont pas prêtes (NumberReady === 0), sauf si on a déjà fait
+     * un wake-up trop récemment (selon wakeUpTimeout).
+     */
     async wakeUpPods(data, lastWakeUpTime) {
         const currentTime = Date.now();
         let isWakeUpCallMade = false;
+
+        // On évite de rappeler trop souvent la même fonction
         const shouldFilter = lastWakeUpTime && (currentTime - lastWakeUpTime) <= this.wakeUpTimeout;
+
+        // On ne fait un wake-up que pour les fonctions dont le comportement est "WakeUp" ou "WakeUp+BlockUI"
         const wakePromises = data
+            .filter((item) => this.getBehavior(item.Name) !== 'None')
             .filter((item) => item.NumberReady === 0 || !shouldFilter)
             .map(async (item) => {
                 const response = await this.fetch(`${this.baseUrl}/wake-function/${item.Name}`, {
@@ -66,7 +89,7 @@ export default class SlimFaasPlanetSaver {
                 if (response.status >= 400) {
                     throw new Error(`HTTP Error! status: ${response.status} for function ${item.Name}`);
                 }
-                isWakeUpCallMade = true
+                isWakeUpCallMade = true;
                 return response;
             });
 
@@ -79,6 +102,9 @@ export default class SlimFaasPlanetSaver {
         return isWakeUpCallMade;
     }
 
+    /**
+     * Récupère le status de chaque fonction et met à jour l'UI et l'overlay
+     */
     async fetchStatus() {
         try {
             const response = await this.fetch(`${this.baseUrl}/status-functions`);
@@ -87,38 +113,48 @@ export default class SlimFaasPlanetSaver {
             }
             const data = await response.json();
 
-            const allReady = data.every((item) => item.NumberReady >= 1);
-            this.setReadyState(allReady);
+            // On ne considère comme bloquantes que les fonctions dont le comportement est "WakeUp+BlockUI"
+            const blockingItems = data.filter((item) => this.getBehavior(item.Name) === 'WakeUp+BlockUI');
+            const allBlockingReady = blockingItems.every((item) => item.NumberReady >= 1);
+
+            // Si toutes les fonctions "bloquantes" sont prêtes, on estime que c'est "ready".
+            this.setReadyState(allBlockingReady);
 
+            // Callback pour l'extérieur
             this.updateCallback(data);
 
+            // On vérifie l'activité de la souris pour "réveiller" (wakeUp) les fonctions
             const now = Date.now();
-            const mouseMovedRecently = now - this.lastMouseMoveTime <= this.noActivityTimeout; // 1 minute
+            const mouseMovedRecently = now - this.lastMouseMoveTime <= this.noActivityTimeout;
 
-            if (!allReady && this.isDocumentVisible && !mouseMovedRecently) {
+            if (!allBlockingReady && this.isDocumentVisible && !mouseMovedRecently) {
+                // Pas de mouvement de souris, document visible => message "no activity"
                 this.updateOverlayMessage(this.overlayNoActivityMessage, 'waiting-action');
-            } else if (mouseMovedRecently && this.isDocumentVisible) {
-                if(!allReady) {
+            } else if (mouseMovedRecently) {
+                // Il y a une activité de souris
+                if (!allBlockingReady && this.isDocumentVisible) {
                     this.updateOverlayMessage(this.overlayStartingMessage, 'waiting');
                 }
-                if(!this.lastWakeUpTime) {
+                if (!this.lastWakeUpTime) {
                     this.lastWakeUpTime = Date.now();
                 }
                 const isWakeUpCallMade = await this.wakeUpPods(data, this.lastWakeUpTime);
-                if(isWakeUpCallMade) {
+                if (isWakeUpCallMade) {
                     this.lastWakeUpTime = Date.now();
                 }
-            } else if(!this.isDocumentVisible && !allReady) {
+            } else if (!this.isDocumentVisible && !allBlockingReady) {
+                // Document caché, pas prêt => message "no activity"
                 this.updateOverlayMessage(this.overlayNoActivityMessage, 'waiting');
             }
         } catch (error) {
             const errorMessage = error.message;
+            // On garde l'état précédent de readiness en cas d'erreur
             this.setReadyState(this.isReady);
             this.updateOverlayMessage(this.overlayErrorMessage, 'error', this.overlayErrorSecondaryMessage);
             this.errorCallback(errorMessage);
             console.error('Error fetching slimfaas data:', errorMessage);
         } finally {
-            if(this.intervalId)  {
+            if (this.intervalId) {
                 this.intervalId = setTimeout(() => {
                     this.fetchStatus();
                 }, this.interval);
@@ -126,6 +162,9 @@ export default class SlimFaasPlanetSaver {
         }
     }
 
+    /**
+     * Met à jour l'état ready. Si ready = true => on cache l'overlay
+     */
     setReadyState(isReady) {
         this.isReady = isReady;
         if (isReady) {
@@ -135,16 +174,20 @@ export default class SlimFaasPlanetSaver {
         }
     }
 
+    /**
+     * Lance le polling régulier
+     */
     startPolling() {
         if (this.intervalId || !this.baseUrl || this.cleanned) return;
-
         this.fetchStatus();
-
         this.intervalId = setTimeout(() => {
             this.fetchStatus();
         }, this.interval);
     }
 
+    /**
+     * Arrête le polling
+     */
     stopPolling() {
         if (this.intervalId) {
             clearTimeout(this.intervalId);
@@ -152,6 +195,9 @@ export default class SlimFaasPlanetSaver {
         }
     }
 
+    /**
+     * Injecte dans le DOM le style pour l'overlay
+     */
     injectStyles() {
         const cssString = `
             .slimfaas-environment-overlay {
@@ -222,48 +268,57 @@ export default class SlimFaasPlanetSaver {
         document.head.appendChild(this.styleElement);
     }
 
+    /**
+     * Crée dans le DOM l'overlay en lui-même (sans l'ajouter encore)
+     */
     createOverlay() {
         this.overlayElement = document.createElement('div');
         this.overlayElement.className = 'slimfaas-environment-overlay';
         this.overlayElement.id = `slimfaas-environment-overlay-${this.id}`;
 
-        // Créer l'élément icône
+        // Élément icône
         this.iconElement = document.createElement('div');
         this.iconElement.className = 'slimfaas-environment-overlay__icon';
         this.iconElement.innerText = this.overlayLoadingIcon;
 
-        // Créer l'élément du message principal
+        // Message principal
         this.spanElement = document.createElement('span');
         this.spanElement.className = 'slimfaas-environment-overlay__main-message';
         this.spanElement.innerHTML = `${this.overlayStartingMessage}`;
 
-        // Créer l'élément du message secondaire
+        // Message secondaire
         this.secondarySpanElement = document.createElement('span');
         this.secondarySpanElement.className = 'slimfaas-environment-overlay__secondary-message';
         this.secondarySpanElement.innerText = this.overlaySecondaryMessage;
 
-        // Ajouter les éléments à l'overlay
+        // Ajout à l'overlay
         this.overlayElement.appendChild(this.iconElement);
         this.overlayElement.appendChild(this.spanElement);
         this.overlayElement.appendChild(this.secondarySpanElement);
-
-        // Ne pas ajouter l'overlay au DOM ici
-        // document.body.appendChild(this.overlayElement);
     }
 
+    /**
+     * Affiche l'overlay dans la page si nécessaire
+     */
     showOverlay() {
-        if(this.cleanned) return;
+        if (this.cleanned) return;
         if (this.overlayElement && !document.body.contains(this.overlayElement)) {
             document.body.appendChild(this.overlayElement);
         }
     }
 
+    /**
+     * Cache l'overlay
+     */
     hideOverlay() {
         if (this.overlayElement && document.body.contains(this.overlayElement)) {
             document.body.removeChild(this.overlayElement);
         }
     }
 
+    /**
+     * Met à jour le message affiché dans l'overlay
+     */
     updateOverlayMessage(newMessage, status = 'waiting', secondaryMessage = null) {
         if (this.spanElement) {
             this.spanElement.innerHTML = `${newMessage}`;
@@ -283,6 +338,9 @@ export default class SlimFaasPlanetSaver {
         }
     }
 
+    /**
+     * Nettoie le composant : retire listeners, styles et overlay
+     */
     cleanup() {
         this.cleanned = true;
         this.stopPolling();