github_mirrors/puter
1
0
Fork 0
mirror of https://github.com/HeyPuter/puter.git synced 2025-01-23 06:00:21 +08:00
Code Issues Packages Projects Releases Wiki Activity

doc: miscellaneous comment fixes

Browse Source
This commit is contained in:
KernelDeimos 2025-01-06 11:24:18 -05:00
parent 57befd310d
commit 0fb05309c2
13 changed files with 121 additions and 159 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
src/backend/src/modules/apps/AppInformationService.js
View File

@ -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<void>} 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<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.
* @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<void>} 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<void>} 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<void>} 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<void>}
*/
async _refresh_tags () {

13
src/backend/src/modules/web/WebServerService.js
View File

@ -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_() {

22
src/backend/src/services/AnomalyService.js
View File

@ -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];

7
src/backend/src/services/BaseService.js
View File

@ -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<void>} A promise that resolves when initialization is complete.
* @returns {Promise<void>} A promise that resolves when construction is complete.
*/
async construct () {
console.log('CLASS', this.constructor.name);

20
src/backend/src/services/CleanEmailService.js
View File

@ -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 };

41
src/backend/src/services/EntityStoreService.js
View File

@ -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<void>} 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<void>} 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<Object>} 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<Array>} 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.

4
src/backend/src/services/PuterHomepageService.js
View File

@ -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;

7
src/backend/src/services/SessionService.js
View File

@ -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<void>} 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<Session>} A new session object
*/
async create_session (user, meta) {
const unix_ts = Math.floor(Date.now() / 1000);

26
src/backend/src/services/TrackSpendingService.js
View File

@ -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 ) {

7
src/backend/src/services/abuse-prevention/IdentificationService.js
View File

@ -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();

53
src/backend/src/services/auth/PermissionService.js
View File

@ -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<Array>} 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<Array>} 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<Array<string>>} 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<Array<string>>} 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 ' +

21
src/backend/src/services/database/SqliteDatabaseAccessService.js
View File

@ -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);

5
src/backend/src/services/periodic/FSEntryMigrateService.js
View File

@ -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;