doc: ai generated comments

Author: KernelDeimos

src/backend/src/services/AnomalyService.js

@@ -1,3 +1,4 @@
+// METADATA // {"ai-commented":{"service":"openai-completion","model":"gpt-4o"}}
 /*
  * Copyright (C) 2024 Puter Technologies Inc.
  *
@@ -18,9 +19,26 @@
  */
 const BaseService = require("./BaseService");
 
+// Symbol used to indicate a denial of service instruction in anomaly handling.
 const DENY_SERVICE_INSTRUCTION = Symbol('DENY_SERVICE_INSTRUCTION');
 
+
+/**
+* @class AnomalyService
+* @extends BaseService
+* @description The AnomalyService class is responsible for managing and processing anomaly detection types and configurations.
+* It allows the registration of different types with associated handlers, enabling the detection of anomalies based on specified criteria.
+*/
 class AnomalyService extends BaseService {
+    /**
+    * AnomalyService class that extends BaseService and provides methods
+    * for registering anomaly types and handling incoming data for those anomalies.
+    * 
+    * The register method allows the registration of different anomaly types 
+    * and their respective configurations, including custom handlers for data 
+    * evaluation. It supports two modes of operation: a direct handler or 
+    * a threshold-based evaluation.
+    */
     _construct () {
         this.types = {};
     }
@@ -39,6 +57,16 @@ class AnomalyService extends BaseService {
         }
         this.types[type] = type_instance;
     }
+    /**
+     * Registers a new type with the service, including its configuration and handler.
+     * 
+     * @param {string} type - The name of the type to register.
+     * @param {Object} config - The configuration object for the type.
+     * @param {Function} [config.handler] - An optional handler function for the type.
+     * @param {number} [config.high] - An optional threshold value; triggers the handler if exceeded.
+     * 
+     * @returns {void}
+     */
     async note (id, data) {
         const type = this.types[id];
         if ( ! type ) return;

src/backend/src/services/AppInformationService.js

@@ -1,3 +1,4 @@
+// METADATA // {"ai-commented":{"service":"xai"}}
 /*
  * Copyright (C) 2024 Puter Technologies Inc.
  *
@@ -23,6 +24,17 @@ const { DB_READ } = require("./database/consts");
 
 const uuidv4 = require('uuid').v4;
 
+
+/**
+* @class AppInformationService
+* @description
+* The AppInformationService class manages application-related information,
+* including caching, statistical data, and tags for applications within the Puter ecosystem.
+* It provides methods for refreshing application data, managing app statistics,
+* and handling tags associated with apps. This service is crucial for maintaining
+* up-to-date information about applications, facilitating features like app listings,
+* recent apps, and tag-based app discovery.
+*/
 class AppInformationService {
     constructor ({ services }) {
         this.services = services;
@@ -37,33 +49,87 @@ class AppInformationService {
             // await new Promise(rslv => setTimeout(rslv, 500))
 
             await this._refresh_app_cache();
+            /**
+            * Refreshes the application cache by querying the database for all apps and updating the key-value store.
+            * 
+            * This method is called periodically to ensure that the in-memory cache reflects the latest
+            * state from the database. It uses the 'database' service to fetch app data and then updates
+            * multiple cache entries for quick lookups by name, ID, and UID.
+            *
+            * @async
+            */
             asyncSafeSetInterval(async () => {
                 this._refresh_app_cache();
             }, 30 * 1000);
 
             await this._refresh_app_stats();
+            /**
+            * Refreshes the cache of recently opened apps.
+            * This method updates the 'recent' collection with the UIDs of apps sorted by their most recent timestamp.
+            * 
+            * @async
+            * @returns {Promise<void>} A promise that resolves when the cache has been refreshed.
+            */
             asyncSafeSetInterval(async () => {
                 this._refresh_app_stats();
             }, 120 * 1000);
 
             // This stat is more expensive so we don't update it as often
             await this._refresh_app_stat_referrals();
+            /**
+            * Refreshes the app referral statistics.
+            * This method is computationally expensive and thus runs less frequently.
+            * It queries the database for user counts referred by each app's origin URL.
+            * 
+            * @async
+            */
             asyncSafeSetInterval(async () => {
                 this._refresh_app_stat_referrals();
             }, 15 * MINUTE);
 
             await this._refresh_recent_cache();
+            /**
+            * Refreshes the recent cache by updating the list of recently added or updated apps.
+            * This method fetches all app data, filters for approved apps, sorts them by timestamp,
+            * and updates the `this.collections.recent` array with the UIDs of the most recent 50 apps.
+            * 
+            * @async
+            * @private
+            */
             asyncSafeSetInterval(async () => {
                 this._refresh_recent_cache();
             }, 120 * 1000);
 
             await this._refresh_tags();
+            /**
+            * Refreshes the tags cache by iterating through all approved apps,
+            * extracting their tags, and organizing them into a structured format.
+            * This method updates the `this.tags` object with the latest tag information.
+            *
+            * @async
+            * @method
+            * @memberof AppInformationService
+            */
             asyncSafeSetInterval(async () => {
                 this._refresh_tags();
             } , 120 * 1000);
         })();
     }
 
+
+    /**
+    * Retrieves and returns statistical data for a specific application.
+    * 
+    * This method fetches various metrics such as the number of times the app has been opened,
+    * the count of unique users who have opened the app, and the number of referrals attributed to the app.
+    * It uses cached data where available to improve performance.
+    *
+    * @param {string} app_uid - The unique identifier for the application.
+    * @returns {Promise<Object>} An object containing:
+    *   - {number} open_count - The total number of times the app has been opened.
+    *   - {number} user_count - The count of unique users who have opened the app.
+    *   - {number|null} referral_count - The number of referrals, or null if the data is not available or too expensive to retrieve.
+    */
     async get_stats (app_uid) {
         const db = this.services.get('database').get(DB_READ, 'apps');
 
@@ -100,6 +166,19 @@ class AppInformationService {
         };
     }
 
+
+    /**
+    * Retrieves various statistics for a given app.
+    * 
+    * This method fetches the open count, user count, and referral count for an app identified by its UID.
+    * It uses cached values where available to improve performance, but will query the database if necessary.
+    * 
+    * @param {string} app_uid - The unique identifier of the app for which to retrieve stats.
+    * @returns {Promise<Object>} An object containing:
+    *   - {number} open_count - Total number of times the app was opened.
+    *   - {number} user_count - Number of unique users who opened the app.
+    *   - {number|null} referral_count - Number of referrals attributed to the app. This value might not be reported if not cached.
+    */
     async _refresh_app_cache () {
         this.log.tick('refresh app cache');
 
@@ -114,6 +193,17 @@ class AppInformationService {
         }
     }
 
+
+    /**
+    * Refreshes the application cache by querying the database for all apps and updating the key-value store.
+    * 
+    * @async
+    * @returns {Promise<void>} A promise that resolves when the cache refresh operation is complete.
+    * 
+    * @notes
+    * - This method logs a tick event for performance monitoring.
+    * - It populates the cache with app data indexed by name, id, and uid.
+    */
     async _refresh_app_stats () {
         this.log.tick('refresh app stats');
 
@@ -144,6 +234,13 @@ class AppInformationService {
         }
     }
 
+
+    /**
+    * Refreshes the cache of app statistics including open and user counts.
+    * This method updates the cache every 120 seconds to ensure data freshness.
+    *
+    * @async
+    */
     async _refresh_app_stat_referrals () {
         this.log.tick('refresh app stat referrals');
 
@@ -176,6 +273,17 @@ class AppInformationService {
         this.log.info('DONE refresh app stat referrals');
     }
 
+
+    /**
+    * Updates the cache with recently updated apps.
+    * 
+    * @description This method refreshes the cache containing the most recently updated applications.
+    *              It fetches all app UIDs, retrieves the corresponding app data, filters for approved apps,
+    *              sorts them by timestamp in descending order, and updates the 'recent' collection with
+    *              the UIDs of the top 50 most recent apps.
+    * 
+    * @returns {Promise<void>} Resolves when the cache has been updated.
+    */
     async _refresh_recent_cache () {
         const app_keys = kv.keys(`apps:uid:*`);
         // console.log('APP KEYS', app_keys);
@@ -194,6 +302,16 @@ class AppInformationService {
         this.collections.recent = apps.map(app => app.uid).slice(0, 50);
     }
 
+
+    /**
+    * Refreshes the cache of recently added or updated apps.
+    * 
+    * This method retrieves all apps from the cache, filters for approved listings,
+    * sorts them by timestamp in descending order, and updates the `recent` collection
+    * with the UIDs of the most recent 50 apps.
+    *
+    * @returns {Promise<void>}
+    */
     async _refresh_tags () {
         const app_keys = kv.keys(`apps:uid:*`);
         // console.log('APP KEYS', app_keys);
@@ -229,6 +347,22 @@ class AppInformationService {
         this.tags = new_tags;
     }
 
+
+    /**
+    * Deletes an application from the system.
+    * 
+    * This method performs the following actions:
+    * - Retrieves the app data from cache or database if not provided.
+    * - Deletes the app record from the database.
+    * - Removes the app from all relevant caches (by name, id, and uid).
+    * - Removes the app from the recent collection if present.
+    * - Removes the app from any associated tags.
+    * 
+    * @param {string} app_uid - The unique identifier of the app to be deleted.
+    * @param {Object} [app] - The app object, if already fetched. If not provided, it will be retrieved.
+    * @throws {Error} If the app is not found in either cache or database.
+    * @returns {Promise<void>} A promise that resolves when the app has been successfully deleted.
+    */
     async delete_app (app_uid, app) {
         const db = this.services.get('database').get(DB_READ, 'apps');
 

src/backend/src/services/BaseService.js

@@ -1,3 +1,4 @@
+// METADATA // {"ai-params":{"service":"xai"},"ai-refs":["../../doc/contributors/boot-sequence.md"],"ai-commented":{"service":"xai"}}
 /*
  * Copyright (C) 2024 Puter Technologies Inc.
  *
@@ -18,8 +19,25 @@
  */
 const { concepts } = require("@heyputer/putility");
 
+
+
+// This is a no-op function that AI is incapable of writing a comment for.
+// That said, I suppose it didn't need one anyway.
 const NOOP = async () => {};
 
+
+/**
+* @class BaseService
+* @extends concepts.Service
+* @description
+* BaseService is the foundational class for all services in the Puter backend.
+* It provides lifecycle methods like `construct` and `init` that are invoked during
+* different phases of the boot sequence. This class ensures that services can be
+* instantiated, initialized, and activated in a coordinated manner through
+* events emitted by the Kernel. It also manages common service resources like
+* logging and error handling, and supports legacy services by allowing
+* instantiation after initialization but before consolidation.
+*/
 class BaseService extends concepts.Service {
     constructor (service_resources, ...a) {
         const { services, config, my_config, name, args } = service_resources;
@@ -36,10 +54,29 @@ class BaseService extends concepts.Service {
         }
     }
 
+
+    /**
+    * Initializes the service with configuration and dependencies.
+    * This method sets up logging and error handling, and calls a custom `_init` method if defined.
+    * 
+    * @param {Object} args - Arguments passed to the service for initialization.
+    * @returns {Promise<void>} A promise that resolves when initialization is complete.
+    */
     async construct () {
         await (this._construct || NOOP).call(this, this.args);
     }
 
+
+    /**
+    * Performs the initialization phase of the service lifecycle.
+    * This method sets up logging and error handling for the service,
+    * then calls the service-specific initialization logic if defined.
+    * 
+    * @async
+    * @memberof BaseService
+    * @instance
+    * @returns {Promise<void>} A promise that resolves when initialization is complete.
+    */
     async init () {
         const services = this.services;
         this.log = services.get('log-service').create(this.service_name);
@@ -48,6 +85,15 @@ class BaseService extends concepts.Service {
         await (this._init || NOOP).call(this, this.args);
     }
 
+
+    /**
+    * Handles an event by retrieving the appropriate event handler
+    * and executing it with the provided arguments.
+    *
+    * @param {string} id - The identifier of the event to handle.
+    * @param {Array<any>} args - The arguments to pass to the event handler.
+    * @returns {Promise<any>} The result of the event handler execution.
+    */
     async __on (id, args) {
         const handler = this.__get_event_handler(id);
 

src/backend/src/services/BootScriptService.js

@@ -1,10 +1,29 @@
+// METADATA // {"ai-commented":{"service":"mistral","model":"mistral-large-latest"}}
 const { Context } = require("../util/context");
 const BaseService = require("./BaseService");
 
+
+/**
+* @class BootScriptService
+* @extends BaseService
+* @description The BootScriptService class extends BaseService and is responsible for
+* managing and executing boot scripts. It provides methods to handle boot scripts when
+* the system is ready and to run individual script commands.
+*/
 class BootScriptService extends BaseService {
     static MODULES = {
         fs: require('fs'),
     }
+    /**
+    * Loads and executes a boot script if specified in the arguments.
+    *
+    * This method reads the provided boot script file, parses it, and runs the script using the `run_script` method.
+    * If no boot script is specified in the arguments, the method returns immediately.
+    *
+    * @async
+    * @function
+    * @returns {Promise<void>}
+    */
     async ['__on_boot.ready'] () {
         const args = Context.get('args');
         if ( ! args['boot-script'] ) return;
@@ -17,6 +36,17 @@ class BootScriptService extends BaseService {
         await this.run_script(boot_json);
     }
 
+
+    /**
+    * Executes a series of commands defined in a JSON boot script.
+    *
+    * This method processes each command in the boot_json array.
+    * If the command is recognized within the predefined scope, it will be executed.
+    * If not, an error is thrown.
+    *
+    * @param {Array} boot_json - An array of commands to execute.
+    * @throws {Error} Thrown if an unknown command is encountered.
+    */
     async run_script (boot_json) {
         const scope = {
             runner: 'boot-script',