From 0fb05309c24439d95bb3adaa6a95a739f1984a21 Mon Sep 17 00:00:00 2001 From: KernelDeimos Date: Mon, 6 Jan 2025 11:24:18 -0500 Subject: [PATCH] doc: miscellaneous comment fixes --- .../src/modules/apps/AppInformationService.js | 54 ++++++++++--------- .../src/modules/web/WebServerService.js | 13 ++--- src/backend/src/services/AnomalyService.js | 22 +++++--- src/backend/src/services/BaseService.js | 7 ++- src/backend/src/services/CleanEmailService.js | 20 +++---- .../src/services/EntityStoreService.js | 41 ++++++-------- .../src/services/PuterHomepageService.js | 4 +- src/backend/src/services/SessionService.js | 7 ++- .../src/services/TrackSpendingService.js | 26 ++++----- .../abuse-prevention/IdentificationService.js | 7 --- .../src/services/auth/PermissionService.js | 53 +++++------------- .../database/SqliteDatabaseAccessService.js | 21 +++----- .../periodic/FSEntryMigrateService.js | 5 +- 13 files changed, 121 insertions(+), 159 deletions(-) diff --git a/src/backend/src/modules/apps/AppInformationService.js b/src/backend/src/modules/apps/AppInformationService.js index 515e938b..6e7bd49e 100644 --- a/src/backend/src/modules/apps/AppInformationService.js +++ b/src/backend/src/modules/apps/AppInformationService.js @@ -522,16 +522,14 @@ class AppInformationService extends BaseService { } /** - * Retrieves various statistics for a given app. + * Refreshes the application cache by querying the database for all apps and updating the key-value store. * - * 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. + * @async + * @returns {Promise} A promise that resolves when the cache refresh operation is complete. * - * @param {string} app_uid - The unique identifier of the app for which to retrieve stats. - * @returns {Promise} 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. + * @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_cache () { this.log.tick('refresh app cache'); @@ -548,14 +546,13 @@ class AppInformationService extends BaseService { /** - * Refreshes the application cache by querying the database for all apps and updating the key-value store. - * - * @async - * @returns {Promise} A promise that resolves when the cache refresh operation is complete. - * + * Refreshes the cache of app statistics including open and user counts. + * * @notes * - This method logs a tick event for performance monitoring. - * - It populates the cache with app data indexed by name, id, and uid. + * + * @async + * @returns {Promise} A promise that resolves when the cache refresh operation is complete. */ async _refresh_app_stats () { this.log.tick('refresh app stats'); @@ -589,11 +586,17 @@ class AppInformationService extends BaseService { /** - * Refreshes the cache of app statistics including open and user counts. - * This method updates the cache every 120 seconds to ensure data freshness. - * - * @async - */ + * Refreshes the cache of app referral statistics. + * + * This method queries the database for user counts referred by each app's origin URL + * and updates the cache with the referral counts for each app. + * + * @notes + * - This method logs a tick event for performance monitoring. + * + * @async + * @returns {Promise} A promise that resolves when the cache refresh operation is complete. + */ async _refresh_app_stat_referrals () { this.log.tick('refresh app stat referrals'); @@ -653,12 +656,15 @@ class AppInformationService extends BaseService { /** - * Refreshes the cache of recently added or updated apps. + * Refreshes the cache of tags associated with 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. - * + * This method iterates through all approved apps, extracts their tags, + * and organizes them into a structured format for quick lookups. + * + * This data is used by the `/query/app` router to facilitate tag-based + * app discovery and categorization. + * + * @async * @returns {Promise} */ async _refresh_tags () { diff --git a/src/backend/src/modules/web/WebServerService.js b/src/backend/src/modules/web/WebServerService.js index db958071..b4c46fba 100644 --- a/src/backend/src/modules/web/WebServerService.js +++ b/src/backend/src/modules/web/WebServerService.js @@ -617,12 +617,13 @@ class WebServerService extends BaseService { } /** - * Starts the web server and sets up the necessary middleware and routes. - * This method is responsible for initializing the Express app, handling authentication, - * setting up routes, and starting the HTTP server. It also sets up error handling and - * socket.io for real-time communication. - * - * @param {Object} services - The services object containing all necessary services. + * Prints the Puter logo seen in the console after the server is started. + * + * Depending on the size of the terminal, a different version of the + * logo is displayed. The logo is displayed in blue text. + * + * @returns {void} + * @private */ // comment above line 497 print_puter_logo_() { diff --git a/src/backend/src/services/AnomalyService.js b/src/backend/src/services/AnomalyService.js index 7fa51a33..d948e9d3 100644 --- a/src/backend/src/services/AnomalyService.js +++ b/src/backend/src/services/AnomalyService.js @@ -42,6 +42,16 @@ class AnomalyService extends BaseService { _construct () { this.types = {}; } + /** + * 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} + */ register (type, config) { const type_instance = { config, @@ -58,14 +68,12 @@ class AnomalyService extends BaseService { this.types[type] = type_instance; } /** - * Registers a new type with the service, including its configuration and handler. + * Creates a note of the specified type with the provided data. + * See `groups_user_hour` in GroupService for an example. * - * @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} + * @param {*} id - The identifier of the type to create a note for. + * @param {*} data - The data to process with the type's handler. + * @returns */ async note (id, data) { const type = this.types[id]; diff --git a/src/backend/src/services/BaseService.js b/src/backend/src/services/BaseService.js index 2e74b0d3..d7095439 100644 --- a/src/backend/src/services/BaseService.js +++ b/src/backend/src/services/BaseService.js @@ -57,11 +57,10 @@ 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. + * Creates the service's data structures and initial values. + * This method sets up logging and error handling, and calls a custom `_construct` method if defined. * - * @param {Object} args - Arguments passed to the service for initialization. - * @returns {Promise} A promise that resolves when initialization is complete. + * @returns {Promise} A promise that resolves when construction is complete. */ async construct () { console.log('CLASS', this.constructor.name); diff --git a/src/backend/src/services/CleanEmailService.js b/src/backend/src/services/CleanEmailService.js index 1d58f8f9..2404deb5 100644 --- a/src/backend/src/services/CleanEmailService.js +++ b/src/backend/src/services/CleanEmailService.js @@ -76,17 +76,17 @@ class CleanEmailService extends BaseService { this.domain_nondistinct = this.constructor.DOMAIN_NONDISTINCT; } + /** + * Cleans an email address by applying provider-specific rules and standardizations + * @param {string} email - The email address to clean + * @returns {string} The cleaned email address with applied rules and standardizations + * + * Splits email into local and domain parts, applies provider-specific rules like: + * - Removing dots for certain providers (Gmail, iCloud) + * - Handling subaddressing (removing +suffix) + * - Normalizing domains (e.g. googlemail.com -> gmail.com) + */ clean (email) { - /** - * Cleans an email address by applying provider-specific rules and standardizations - * @param {string} email - The email address to clean - * @returns {string} The cleaned email address with applied rules and standardizations - * - * Splits email into local and domain parts, applies provider-specific rules like: - * - Removing dots for certain providers (Gmail, iCloud) - * - Handling subaddressing (removing +suffix) - * - Normalizing domains (e.g. googlemail.com -> gmail.com) - */ const eml = (() => { const [local, domain] = email.split('@'); return { local, domain }; diff --git a/src/backend/src/services/EntityStoreService.js b/src/backend/src/services/EntityStoreService.js index bce9a9b4..4e8b73fc 100644 --- a/src/backend/src/services/EntityStoreService.js +++ b/src/backend/src/services/EntityStoreService.js @@ -39,6 +39,10 @@ class EntityStoreService extends BaseService { * @param {Object} args.upstream - The upstream service to handle operations. * * @throws {Error} If `args.entity` is not provided. + * + * @returns {Promise} A promise that resolves when initialization is complete. + * + * @note This method sets up the context for the entity operations and provides it to the upstream service. */ async _init (args) { if ( ! args.entity ) { @@ -48,20 +52,6 @@ class EntityStoreService extends BaseService { this.upstream = args.upstream; - /** - * Initializes the EntityStoreService with the provided arguments. - * - * @param {Object} args - Initialization arguments. - * @param {string} args.entity - The name of the entity this service will manage. - * If not provided, an error is thrown. - * @param {Object} args.upstream - The upstream service or data source. - * - * @throws {Error} If the entity name is not provided in the arguments. - * - * @returns {Promise} A promise that resolves when initialization is complete. - * - * @note This method sets up the context for the entity operations and provides it to the upstream service. - */ const context = Context.get().sub({ services: this.services }); const om = this.services.get('registry').get('om:mapping').get(args.entity); this.om = om; @@ -181,18 +171,19 @@ class EntityStoreService extends BaseService { if ( ! predicate) predicate = new Null(); return await this.upstream.select({ predicate, ...rest }); } - /** - * Retrieves entities matching a given predicate. + /* Updates an existing entity in the store. * - * This method performs a selection query on the upstream data source. - * If no predicate is provided, it defaults to selecting all entities. + * @param {Object} entity - The entity to update with new values. + * @param {string|number} id - The identifier of the entity to update. Can be a string or number. + * @param {Object} options - Additional options for the update operation. + * @returns {Promise} The updated entity after the operation. + * @throws {APIError} If the entity to be updated is not found. * - * @param {Object} options - The selection options. - * @param {Array|Function} options.predicate - The predicate for filtering entities. - * If an array, it's expected to be in the format [operator, ...args]. - * If not provided, it defaults to a Null predicate, effectively selecting all entities. - * @param {Object} [options.rest] - Additional options for the selection query. - * @returns {Promise} A promise that resolves to an array of entities matching the predicate. + * @note This method first attempts to fetch the entity by its primary identifier. If not found, + * it uses `IdentifierUtil` to detect and fetch by other identifiers if provided. + * If the entity still isn't found, an error is thrown. The method ensures that the + * entity's primary identifier is updated to match the existing entity before performing + * the actual update through `this.upstream.update`. */ async update (entity, id, options) { let old_entity = await this.read( @@ -225,7 +216,7 @@ class EntityStoreService extends BaseService { return await this.upstream.upsert(entity, { old_entity, options }); } /** - * Updates an existing entity in the store. + * Updates an existing entity in the store or creates a new one. * * @param {Object} entity - The entity to update with new values. * @param {string|number} id - The identifier of the entity to update. Can be a string or number. diff --git a/src/backend/src/services/PuterHomepageService.js b/src/backend/src/services/PuterHomepageService.js index a1a7b4b6..378aea09 100644 --- a/src/backend/src/services/PuterHomepageService.js +++ b/src/backend/src/services/PuterHomepageService.js @@ -78,9 +78,7 @@ class PuterHomepageService extends BaseService { /** - * @description This method sets a GUI parameter. It allows you to assign a value to a key within the `gui_params` object. - * @param {string} key - The key for the parameter. - * @param {any} val - The value for the parameter. + * This method sends the initial HTML page that loads the Puter GUI and its assets. */ async send ({ req, res }, meta, launch_options) { const config = this.global_config; diff --git a/src/backend/src/services/SessionService.js b/src/backend/src/services/SessionService.js index 551d7380..24da506f 100644 --- a/src/backend/src/services/SessionService.js +++ b/src/backend/src/services/SessionService.js @@ -89,12 +89,11 @@ class SessionService extends BaseService { /** - * Initializes the session service by setting up the database connection and scheduling periodic session updates. + * Creates a new session for the specified user and records metadata about + * the requestor. * * @async - * @private - * @returns {Promise} A promise that resolves when initialization is complete. - * @note This method is called internally during the service setup. It does not need to be invoked manually. + * @returns {Promise} A new session object */ async create_session (user, meta) { const unix_ts = Math.floor(Date.now() / 1000); diff --git a/src/backend/src/services/TrackSpendingService.js b/src/backend/src/services/TrackSpendingService.js index e73bddb5..7a17eedd 100644 --- a/src/backend/src/services/TrackSpendingService.js +++ b/src/backend/src/services/TrackSpendingService.js @@ -33,13 +33,6 @@ const BaseService = require("./BaseService"); * pricing strategies for chat completions and image generation services. */ class TrackSpendingService extends BaseService { - /** - * @class TrackSpendingService - * @extends BaseService - * @description Service for tracking and monitoring API spending across different vendors and strategies. - * Implements cost tracking for chat completions and image generations, with configurable spending alerts. - * Maintains time-windowed spending metrics and triggers alarms when spending thresholds are exceeded. - */ static ChatCompletionStrategy = class ChatCompletionStrategy { static models = { 'gpt-4-1106-preview': { @@ -217,11 +210,12 @@ class TrackSpendingService extends BaseService { /** - * Records spending data for a vendor using a specified strategy - * @param {string} vendor - The vendor name/identifier - * @param {string} strategy_key - Key identifying the pricing strategy to use - * @param {Object} data - Data needed to calculate cost based on the strategy - * @throws {Error} If strategy_key is invalid/unknown + * Generates alarms when spending exceeds configured thresholds + * + * Periodically checks the current spending levels across all spending windows + * and triggers alarms when spending exceeds configured thresholds. Alarms are + * triggered based on the total spending across all windows and the configured + * alarm thresholds. */ setInterval(() => { const spending = this.get_window_spending_(); @@ -281,6 +275,14 @@ class TrackSpendingService extends BaseService { }, 0); } + /** + * Records spending for a given vendor using the specified strategy + * + * @param {string} vendor - The vendor name/identifier + * @param {string} strategy_key - Key identifying the pricing strategy to use + * @param {Object} data - Data needed to calculate cost based on the strategy + * @throws {Error} If strategy_key is invalid/unknown + */ record_spending (vendor, strategy_key, data) { const strategy = this.strategies[strategy_key]; if ( ! strategy ) { diff --git a/src/backend/src/services/abuse-prevention/IdentificationService.js b/src/backend/src/services/abuse-prevention/IdentificationService.js index 9ddba202..25a43d0a 100644 --- a/src/backend/src/services/abuse-prevention/IdentificationService.js +++ b/src/backend/src/services/abuse-prevention/IdentificationService.js @@ -140,13 +140,6 @@ class RequesterIdentificationExpressMiddleware extends AdvancedBase { install (app) { app.use(this.run.bind(this)); } - /** - * Installs the middleware into the Express application. - * This method binds the `run` method to the current instance - * and uses it as a middleware function in the Express app. - * - * @param {object} app - The Express application instance. - */ async run (req, res, next) { const x = Context.get(); diff --git a/src/backend/src/services/auth/PermissionService.js b/src/backend/src/services/auth/PermissionService.js index d9816359..49e82d42 100644 --- a/src/backend/src/services/auth/PermissionService.js +++ b/src/backend/src/services/auth/PermissionService.js @@ -134,12 +134,6 @@ class PermissionExploder { return this.matcher(permission); } - /** - * Check if the permission is implied by this implicator - * @param {Actor} actor - * @param {string} permission - * @returns - */ /** * Explodes a permission into a set of implied permissions. * @@ -785,15 +779,10 @@ class PermissionService extends BaseService { * - This was written for use in ll_listusers to display * home directories of users that shared files with the * current user. + * + * @param {Object} user - The user whose permission issuers are to be listed. + * @returns {Promise} A promise that resolves to an array of user objects. */ - /** - * Lists users who have granted any permissions to the specified user. - * - * This method provides a flat, non-recursive view of permission issuers. - * - * @param {Object} user - The user whose permission issuers are to be listed. - * @returns {Promise} A promise that resolves to an array of user objects. - */ async list_user_permission_issuers (user) { const rows = await this.db.read( 'SELECT DISTINCT issuer_user_id FROM `user_to_user_permissions` ' + @@ -822,17 +811,14 @@ class PermissionService extends BaseService { * Use History: * - This was written for FSNodeContext.fetchShares to query * all the "shares" associated with a file. + * + * This method retrieves permissions from the database where the permission key starts with a specified prefix. + * It is designed for "flat" (non-cascading) queries. + * + * @param {Object} issuer - The actor granting the permissions. + * @param {string} prefix - The prefix to match in the permission key. + * @returns {Object} An object containing arrays of user and app permissions matching the prefix. */ - /** - * Queries permissions granted by an issuer to various users and apps based on a permission prefix. - * - * This method retrieves permissions from the database where the permission key starts with a specified prefix. - * It is designed for "flat" (non-cascading) queries. - * - * @param {Object} issuer - The actor granting the permissions. - * @param {string} prefix - The prefix to match in the permission key. - * @returns {Object} An object containing arrays of user and app permissions matching the prefix. - */ async query_issuer_permissions_by_prefix (issuer, prefix) { const user_perms = await this.db.read( 'SELECT DISTINCT holder_user_id, permission ' + @@ -881,22 +867,11 @@ class PermissionService extends BaseService { * * This is a "flat" (non-cascading) view. * - * @param {*} issuer - * @param {*} holder - * @param {*} prefix - * @returns + * @param {Object} issuer - The actor granting the permissions. + * @param {Object} holder - The actor receiving the permissions. + * @param {string} prefix - The prefix of the permission keys to match. + * @returns {Promise>} An array of permission strings matching the prefix. */ - /** - * Queries the permissions granted by an issuer to a holder with a specific prefix. - * - * This method retrieves permissions that match a given prefix from the database. - * It's a flat view, meaning it does not include cascading permissions. - * - * @param {Object} issuer - The actor granting the permissions. - * @param {Object} holder - The actor receiving the permissions. - * @param {string} prefix - The prefix of the permission keys to match. - * @returns {Promise>} An array of permission strings matching the prefix. - */ async query_issuer_holder_permissions_by_prefix (issuer, holder, prefix) { const user_perms = await this.db.read( 'SELECT permission ' + diff --git a/src/backend/src/services/database/SqliteDatabaseAccessService.js b/src/backend/src/services/database/SqliteDatabaseAccessService.js index 01571301..4b1f8b7c 100644 --- a/src/backend/src/services/database/SqliteDatabaseAccessService.js +++ b/src/backend/src/services/database/SqliteDatabaseAccessService.js @@ -282,12 +282,7 @@ class SqliteDatabaseAccessService extends BaseDatabaseAccessService { /** - * Method to perform database upgrade if necessary. - * - * This method checks if the current database version is outdated and applies any necessary migration scripts to bring it up to date. - * - * @param {none} - * @returns {void} + * Implementation for prepared statements for READ operations. */ async _read (query, params = []) { query = this.sqlite_transform_query_(query); @@ -297,10 +292,9 @@ class SqliteDatabaseAccessService extends BaseDatabaseAccessService { /** - * @description This method initializes the SQLite database connection and performs any necessary upgrades to the database schema. - * @notes This method is responsible for creating a new instance of the SQLite database connection, registering commands for the SQLite CLI, and upgrading the database schema if necessary. - * @param {none} - * @return {Promise} A promise that resolves when the database connection is initialized and any necessary upgrades are completed. + * Implementation for prepared statements for READ operations. + * This method may perform additional steps to obtain the data, which + * is not applicable to the SQLite implementation. */ async _requireRead (query, params) { return this._read(query, params); @@ -308,11 +302,8 @@ class SqliteDatabaseAccessService extends BaseDatabaseAccessService { /** - * This method is responsible for performing database upgrades. It checks the current version of the database, compares it to the desired version, and applies any necessary migration scripts. - * - * It accepts no parameters and returns nothing. - */ - // line 261, method begins here. + * Implementation for prepared statements for WRITE operations. + */ async _write (query, params) { query = this.sqlite_transform_query_(query); params = this.sqlite_transform_params_(params); diff --git a/src/backend/src/services/periodic/FSEntryMigrateService.js b/src/backend/src/services/periodic/FSEntryMigrateService.js index 5700db74..d5670e37 100644 --- a/src/backend/src/services/periodic/FSEntryMigrateService.js +++ b/src/backend/src/services/periodic/FSEntryMigrateService.js @@ -55,9 +55,8 @@ class Job { return false; } /** - * Checks if the job should stop based on its current state - * @returns {boolean} True if the job should stop, false if it can continue - * @private + * Sets the job state to YELLOW, which means it will stop as soon as possible + * (generally after the current batch of work being processed) */ stop () { this.state = this.constructor.STATE_YELLOW;