@picteus/extension-sdk 0.13.1 → 0.15.0

package/dist/picteusExtension.js

@@ -4,34 +4,40 @@ import { fileURLToPath } from "node:url";
 // We do not import the "process" package on purpose, otherwise we get the runtime error "process.on is not a function"
 import console from "node:console";
 import { io } from "socket.io-client";
-import { ApiSecretApi, Configuration, ExtensionApi, ImageApi, ImageAttachmentApi, ManifestFromJSON, MiscellaneousApi, RepositoryApi } from "./index.js";
-export var NotificationReturnedErrorCause;
-(function (NotificationReturnedErrorCause) {
-    NotificationReturnedErrorCause[NotificationReturnedErrorCause["Cancel"] = 0] = "Cancel";
-    NotificationReturnedErrorCause[NotificationReturnedErrorCause["Error"] = 1] = "Error";
-})(NotificationReturnedErrorCause || (NotificationReturnedErrorCause = {}));
-export class NotificationReturnedError extends Error {
+import { ApiSecretApi, CollectionApi, Configuration, ExtensionApi, ImageApi, ImageAttachmentApi, IntentToastType, ManifestFromJSON, MiscellaneousApi, RepositoryApi } from "./index.js";
+export const InstructionReturnedErrorCause = { Cancel: 0, Error: 1 };
+export class InstructionReturnedError extends Error {
     reason;
     constructor(message, reason) {
         super(message);
         this.reason = reason;
     }
 }
-export var NotificationEvent;
-(function (NotificationEvent) {
-    NotificationEvent["ProcessRunCommand"] = "process.runCommand";
-    NotificationEvent["ImageCreated"] = "image.created";
-    NotificationEvent["ImageUpdated"] = "image.updated";
-    NotificationEvent["ImageTagsUpdated"] = "image.tags.updated";
-    NotificationEvent["ImageFeaturesUpdated"] = "image.features.updated";
-    NotificationEvent["ImageDeleted"] = "image.deleted";
-    NotificationEvent["ImageComputeFeatures"] = "image.computeFeatures";
-    NotificationEvent["ImageComputeEmbeddings"] = "image.computeEmbeddings";
-    NotificationEvent["ImageComputeTags"] = "image.computeTags";
-    NotificationEvent["ImageRunCommand"] = "image.runCommand";
-    NotificationEvent["TextComputeEmbeddings"] = "text.computeEmbeddings";
-})(NotificationEvent || (NotificationEvent = {}));
-const extensionSettingsEvent = "extension.settings";
+export class CommandError extends Error {
+    static fromError(error) {
+        return new CommandError(error.message);
+    }
+    constructor(message) {
+        super(message);
+    }
+}
+export const EventName = {
+    ProcessRunCommand: "process.runCommand",
+    ImageCreated: "image.created",
+    ImageUpdated: "image.updated",
+    ImageTagsUpdated: "image.tags.updated",
+    ImageFeaturesUpdated: "image.features.updated",
+    ImageDeleted: "image.deleted",
+    ImageComputeFeatures: "image.computeFeatures",
+    ImageComputeEmbeddings: "image.computeEmbeddings",
+    ImageComputeTags: "image.computeTags",
+    ImageRunCommand: "image.runCommand",
+    TextComputeEmbeddings: "text.computeEmbeddings"
+};
+const extensionVersionsChannel = "extension.versions";
+const extensionReadyChannel = "extension.ready";
+const extensionSettingsChannel = "extension.settings";
+// noinspection JSUnusedGlobalSymbols
 export class Helper {
     static GENERATION_RECIPE_SCHEMA_VERSION = 1;
 }
@@ -77,7 +83,7 @@ const stringifyWithStrippedBuffers = (object) => {
     const bufferReplacement = "<bytes>";
     return JSON.stringify(object, (_key, value) => {
         // We check if the value is a Buffer
-        if (value !== undefined && value.type === "Buffer" && Array.isArray(value.data) === true) {
+        if (value !== undefined && value !== null && value.type === "Buffer" && Array.isArray(value.data) === true) {
             return bufferReplacement;
         }
         // We also check for native Buffer instances if they haven't been pre-processed
@@ -93,6 +99,7 @@ class MessageSender {
     socket;
     toString;
     contextId;
+    _maximumPayloadSizeInBytes;
     constructor(logger, parameters, socket, toString, contextId) {
         this.logger = logger;
         this.parameters = parameters;
@@ -100,9 +107,12 @@ class MessageSender {
         this.toString = toString;
         this.contextId = contextId;
     }
-    sendMessage(channel, body, callback) {
+    set maximumPayloadSizeInBytes(value) {
+        this._maximumPayloadSizeInBytes = value;
+    }
+    sendMessage(event, body, callback) {
         const contextId = this.contextId;
-        this.logger.debug(`Sending the message '${stringifyWithStrippedBuffers(body)}' on channel '${channel}' for ${this.toString()}${contextId === undefined ? "" : ` attached to the context with id '${contextId}'`}${callback === undefined ? "" : " and waiting for a callback"}`);
+        this.logger.debug(`Sending the message '${stringifyWithStrippedBuffers(body)}' through the '${event}' event for ${this.toString()}${contextId === undefined ? "" : ` attached to the context with id '${contextId}'`}${callback === undefined ? "" : " and waiting for a callback"}`);
         const value = {
             extensionId: this.parameters.extensionId,
             ...body
@@ -115,14 +125,14 @@ class MessageSender {
             value.contextId = contextId;
         }
         if (callback === undefined) {
-            this.socket.emit(channel, value);
+            this.socket.emit(event, value);
         }
         else {
-            this.socket.emit(channel, value, callback);
+            this.socket.emit(event, value, callback);
         }
     }
 }
-const notificationsChannel = "notifications";
+const instructionsEvent = "instructions";
 export class Communicator {
     logger;
     sender;
@@ -132,20 +142,21 @@ export class Communicator {
     }
     sendLog(message, level) {
         this.logger[level](message);
-        this.sendMessage(notificationsChannel, { log: { message, level } });
+        this.sendMessage(instructionsEvent, { log: { message, level } });
     }
+    // noinspection JSUnusedGlobalSymbols
     sendNotification(value) {
-        this.sendMessage(notificationsChannel, { notification: value });
+        this.sendMessage(instructionsEvent, { notification: value });
     }
     async launchIntent(intent) {
         return await new Promise((resolve, reject) => {
-            this.sendMessage(notificationsChannel, { intent }, async ({ value, cancel, error }) => {
+            this.sendMessage(instructionsEvent, { intent }, async ({ value, cancel, error }) => {
                 this.logger.debug(`Received a result related to the intent '${stringifyWithStrippedBuffers(intent)}' for ${this.sender.toString()}`);
                 if (cancel !== undefined) {
-                    reject(new NotificationReturnedError(cancel, NotificationReturnedErrorCause.Cancel));
+                    reject(new InstructionReturnedError(cancel, InstructionReturnedErrorCause.Cancel));
                 }
                 else if (error !== undefined) {
-                    reject(new NotificationReturnedError(error, NotificationReturnedErrorCause.Error));
+                    reject(new InstructionReturnedError(error, InstructionReturnedErrorCause.Error));
                 }
                 else {
                     resolve(value);
@@ -153,8 +164,8 @@ export class Communicator {
             });
         });
     }
-    sendMessage(channel, body, callback) {
-        this.sender.sendMessage(channel, body, callback);
+    sendMessage(event, body, callback) {
+        this.sender.sendMessage(event, body, callback);
     }
 }
 export class PicteusExtension {
@@ -164,6 +175,7 @@ export class PicteusExtension {
     static getSdkVersion() {
         return JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), { encoding: "utf8" })).version;
     }
+    // noinspection JSUnusedGlobalSymbols
     static getCacheDirectoryPath() {
         return path.join(PicteusExtension.getExtensionHomeDirectoryPath(), ".cache");
     }
@@ -178,7 +190,6 @@ export class PicteusExtension {
     apiKey;
     configuration;
     socket;
-    globalCommunicator;
     constructor() {
         this.logger.info(`Instantiating the ${this.toString()} through the process with id '${process.pid}' relying on the SDK version '${PicteusExtension.getSdkVersion()}'`);
         process.on("SIGTERM", async (signal) => {
@@ -205,8 +216,7 @@ export class PicteusExtension {
             result = await this.initialize();
         }
         catch (error) {
-            this.logger.error(`The initialization of the ${this.toString()} failed. Reason: '${error.message}'`, error);
-            process.exit(1);
+            this.exit(1, error, "the initialization failed");
         }
         try {
             if (result === true) {
@@ -214,8 +224,7 @@ export class PicteusExtension {
                     this.connectSocket();
                 }
                 catch (error) {
-                    this.logger.error(`The connection of the ${this.toString()} failed. Reason: '${error.message}'`, error);
-                    process.exit(2);
+                    this.exit(2, error, "the connection failed");
                 }
             }
             else {
@@ -227,39 +236,119 @@ export class PicteusExtension {
         }
     }
     toString() {
-        return `extension` + (this.extensionId === undefined ? "" : ` with id '${this.extensionId}'`) + ` of class '${this.constructor.name}'`;
+        return `extension${this.extensionId === undefined ? "" : ` with id '${this.extensionId}'`} of class '${this.constructor.name}'`;
     }
     async initialize() {
         return true;
     }
-    async onReady(communicator) {
+    async onUpgrade(_communicator, _versions) {
+    }
+    async onReady(_communicator) {
     }
     async onTerminate() {
     }
-    async onSettings(communicator, value) {
-        return Promise.resolve();
+    async onSettings(_communicator, _value) {
     }
-    // noinspection JSUnusedLocalSymbols
     async onEvent(communicator, event, value) {
+        if (event === EventName.ImageCreated) {
+            const imageId = value["id"];
+            return await this.onImageCreated(communicator, imageId);
+        }
+        else if (event === EventName.ImageUpdated) {
+            const imageId = value["id"];
+            return await this.onImageUpdated(communicator, imageId);
+        }
+        else if (event === EventName.ImageDeleted) {
+            const imageId = value["id"];
+            return await this.onImageDeleted(communicator, imageId);
+        }
+        else if (event === EventName.ImageTagsUpdated) {
+            const imageId = value["id"];
+            return await this.onImageTagsUpdated(communicator, imageId);
+        }
+        else if (event === EventName.ImageFeaturesUpdated) {
+            const imageId = value["id"];
+            return await this.onImageFeaturesUpdated(communicator, imageId);
+        }
+        else if (event === EventName.ImageComputeTags) {
+            const imageId = value["id"];
+            return await this.onComputeImageTags(communicator, imageId);
+        }
+        else if (event === EventName.ImageComputeFeatures) {
+            const imageId = value["id"];
+            return await this.onComputeImageFeatures(communicator, imageId);
+        }
+        else if (event === EventName.ImageComputeEmbeddings) {
+            const imageId = value["id"];
+            return await this.onComputeImageEmbeddings(communicator, imageId);
+        }
+        else if (event === EventName.ImageRunCommand) {
+            const commandId = value["commandId"];
+            const imageIds = value["imageIds"];
+            const parameters = value["parameters"] ?? {};
+            return await this.onImagesCommand(communicator, commandId, imageIds, parameters);
+        }
+        else if (event === EventName.ProcessRunCommand) {
+            const commandId = value["commandId"];
+            const parameters = value["parameters"] ?? {};
+            return await this.onProcessCommand(communicator, commandId, parameters);
+        }
+        else if (event === EventName.TextComputeEmbeddings) {
+            const text = value["text"];
+            return await this.onComputeTextEmbeddings(communicator, text);
+        }
+    }
+    async onImageCreated(_communicator, _imageId) {
+    }
+    async onImageUpdated(_communicator, _imageId) {
+    }
+    async onImageDeleted(_communicator, _imageId) {
     }
+    async onImageTagsUpdated(_communicator, _imageId) {
+    }
+    async onImageFeaturesUpdated(_communicator, _imageId) {
+    }
+    async onComputeImageTags(_communicator, _imageId) {
+    }
+    async onComputeImageFeatures(_communicator, _imageId) {
+    }
+    async onComputeImageEmbeddings(_communicator, _imageId) {
+    }
+    async onImagesCommand(_communicator, _commandId, _imageIds, _parameters) {
+    }
+    async onProcessCommand(_communicator, _commandId, _parameters) {
+    }
+    async onComputeTextEmbeddings(_communicator, _text) {
+        return [];
+    }
+    // noinspection JSUnusedGlobalSymbols
     getMiscellaneousApi() {
         return new MiscellaneousApi(this.configuration);
     }
+    // noinspection JSUnusedGlobalSymbols
     getApiSecretApi() {
         return new ApiSecretApi(this.configuration);
     }
+    // noinspection JSUnusedGlobalSymbols
     getExtensionApi() {
         return new ExtensionApi(this.configuration);
     }
+    // noinspection JSUnusedGlobalSymbols
     getRepositoryApi() {
         return new RepositoryApi(this.configuration);
     }
+    // noinspection JSUnusedGlobalSymbols
+    getCollectionApi() {
+        return new CollectionApi(this.configuration);
+    }
     getImageApi() {
         return new ImageApi(this.configuration);
     }
+    // noinspection JSUnusedGlobalSymbols
     getImageAttachmentApi() {
         return new ImageAttachmentApi(this.configuration);
     }
+    // noinspection JSUnusedGlobalSymbols
     async getSettings() {
         return (await new ExtensionApi(this.configuration).extensionGetSettings({ id: this.extensionId })).value;
     }
@@ -277,10 +366,17 @@ export class PicteusExtension {
         const globalSender = new MessageSender(this.logger, this.parameters, this.socket, () => {
             return this.toString();
         });
-        this.globalCommunicator = new Communicator(this.logger, globalSender);
         this.socket.on("connect", async () => {
             this.logger.info(`The ${this.toString()} socket is connected`);
-            await this.onReady(this.globalCommunicator);
+            globalSender.sendMessage("connection", {
+                isOpen: true,
+                sdkVersion: PicteusExtension.getSdkVersion(),
+                environment: "node"
+            }, async (result) => {
+                const maximumPayloadSizeInBytes = result.maximumPayloadSizeInBytes;
+                this.logger.debug(`The ${this.toString()} socket has a maximum payload size of ${maximumPayloadSizeInBytes} bytes`);
+                globalSender.maximumPayloadSizeInBytes = maximumPayloadSizeInBytes;
+            });
         });
         this.socket.on("connect_error", async () => {
             this.logger.warn(`The ${this.toString()} socket connection failed"`);
@@ -294,31 +390,58 @@ export class PicteusExtension {
             const sender = new MessageSender(this.logger, this.parameters, this.socket, () => {
                 return this.toString();
             }, contextId);
+            sender.maximumPayloadSizeInBytes = globalSender.maximumPayloadSizeInBytes;
             const communicator = new Communicator(this.logger, sender);
-            const isRegularEvent = channel !== extensionSettingsEvent;
+            const requiresResult = channel !== extensionSettingsChannel;
             let result;
             let success = false;
+            let eventName;
             try {
-                result = await (isRegularEvent === true ? this.onEvent(communicator, channel, value) : this.onSettings(communicator, value.value));
+                if (channel === extensionSettingsChannel) {
+                    result = await this.onSettings(communicator, value.value);
+                }
+                else if (channel === extensionVersionsChannel) {
+                    const { upgrade, ...versions } = value;
+                    if (upgrade === true) {
+                        await this.onUpgrade(communicator, versions);
+                        result = true;
+                    }
+                    else {
+                        result = true;
+                    }
+                }
+                else if (channel === extensionReadyChannel) {
+                    try {
+                        await this.onReady(communicator);
+                        result = true;
+                    }
+                    catch (error) {
+                        this.exit(3, error, "an error occurred during the execution of the 'onReady()' method: stopping the process");
+                    }
+                }
+                else {
+                    eventName = channel;
+                    result = await this.onEvent(communicator, eventName, value);
+                }
                 success = true;
             }
             catch (error) {
                 // We want the process to continue even if an exception occurs
                 this.logger.error(`An error occurred during the handling of the event on channel '${channel}'`, error);
-                communicator.sendLog(`The handling of the event failed for the ${this.toString()}. Reason: '${error.message}'`, "error");
+                if ((eventName === EventName.ImageRunCommand || eventName === EventName.ProcessRunCommand) && error instanceof CommandError) {
+                    void communicator.launchIntent({ toast: { type: IntentToastType.Error, subtitle: error.message } });
+                }
+                else {
+                    communicator.sendLog(`The handling of the event failed for the ${this.toString()}. Reason: '${error.message}'`, "error");
+                }
             }
             finally {
-                sender.sendMessage(notificationsChannel, { acknowledgment: { success } });
+                sender.sendMessage(instructionsEvent, { acknowledgment: { success } });
             }
-            if (isRegularEvent === true && onResult !== undefined) {
+            if (requiresResult === true && onResult !== undefined) {
                 onResult(result);
             }
         });
-        globalSender.sendMessage("connection", {
-            isOpen: true,
-            sdkVersion: PicteusExtension.getSdkVersion(),
-            environment: "node"
-        });
     }
     disconnectSocket() {
         if (this.socket !== undefined && this.socket.disconnected === false) {
@@ -327,6 +450,10 @@ export class PicteusExtension {
             this.socket = undefined;
         }
     }
+    exit(code, error, message) {
+        this.logger.error(`For the ${this.toString()}, ${message}. Reason: '${error.message}'`, error);
+        process.exit(code);
+    }
     getApiConfiguration() {
         if (this.parameters.webServicesBaseUrl.startsWith("https://localhost") == true) {
             // This enables to discard the warning log message, caused by the fact that we are issuing HTTPS request on the localhost exposing a self-served certificate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picteus/extension-sdk",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "productName": "Picteus TypeScript SDK",
   "description": "The Picteus extension TypeScript SDK.",
   "keywords": [