platform

A module for Gingee platform-specific utilities and functions. Ideally used by only platform-level apps. To use this module the app needs to be declared in the `privilegedApps` list in the gingee.json server config. IMPORTANT: Requires privileged app config and explicit permission to use the module. See docs/permissions-guide for more details.
Description:
  • A module for Gingee platform-specific utilities and functions. Ideally used by only platform-level apps. To use this module the app needs to be declared in the `privilegedApps` list in the gingee.json server config. IMPORTANT: Requires privileged app config and explicit permission to use the module. See docs/permissions-guide for more details.

Methods

(static) createAppDirectory(appName) → {object}

Description:
  • Creates a new application directory structure.
Example
const result = platform.createAppDirectory('newApp');
console.log(result); // { message: 'App "newApp" created successfully.', appPath: '/path/to/newApp', boxPath: '/path/to/newApp/box' }
Parameters:
Name Type Description
appName string The name of the new app to create.
Throws:
If the app name is invalid or if the app already exists.
Type
Error
Returns:
An object confirming the paths created.
Type
object

(static) deleteApp(appName) → {boolean}

Description:
  • Recursively deletes an entire application directory. This is a destructive action.
Example
const result = platform.deleteApp('myApp');
console.log(result); // true if deleted successfully
Parameters:
Name Type Description
appName string The name of the app to delete.
Throws:
If the app does not exist or if the deletion is outside the web root.
Type
Error
Returns:
True if the app was deleted successfully.
Type
boolean

(static) installApp(appName, packageBuffer, permissions) → {Promise.<object>}

Description:
  • Installs a new application from a .gin package buffer into a new directory. Fails if an app with the same name already exists.
Example
const grantedPermissions = ["cache", "db", "fs"];
const result = await platform.installApp('myApp', packageBuffer, grantedPermissions);
console.log(result); // true if installed successfully
Parameters:
Name Type Description
appName string The name of the app to create/install.
packageBuffer Buffer The .gin file content as a buffer.
permissions object Permissions to set for the new app.
Throws:
If the app already exists or if the installation fails.
Type
Error
Returns:
A promise that resolves with a success message.
Type
Promise.<object>

(static) installFromBackup(appName, backupVersionopt) → {Promise.<object>}

Description:
  • Installs an application from a previously created backup file.
Example
const result = await platform.installFromBackup('myApp');
console.log(result); // true if installed successfully
Parameters:
Name Type Attributes Default Description
appName string The name of the application to install.
backupVersion string <optional>
 'latest' The specific backup file to use, or 'latest' for the most recent.
Throws:
If the app does not exist, if no backups are found, or if the backup file is missing.
Type
Error
Returns:
A promise that resolves with a success message.
Type
Promise.<object>

(static) listApps() → {Array.<string>}

Description:
  • Lists the names of all detected applications.
Example
const platform = require('platform');
const apps = platform.listApps();
console.log(apps); // ['app1', 'app2', ...]
Returns:
An array of app names.
Type
Array.<string>

(static) listBackups(appName) → {Array.<string>}

Description:
  • Lists all backups for a specific application. Backups are stored in the 'backups' directory under the project root.
Example
const backups = platform.listBackups('myApp');
console.log(backups);
Parameters:
Name Type Description
appName string The name of the application to list backups for.
Throws:
If the app does not exist or if the backups directory is inaccessible.
Type
Error
Returns:
An array of backup file names sorted by date (newest first).
Type
Array.<string>

(static) mockRollback(appName) → {Promise.<object>}

Description:
  • Mocks a rollback plan for an app based on the latest backup. This is a utility function for verifying an app rollback deployment before it happens.
Example
const rollbackPlan = await platform.mockRollback('myApp');
console.log(rollbackPlan); // { action: 'Rollback', fromVersion: '2.0.0', toVersion: '1.0.0', files: { preserved: [], added: [], overwritten: [], deleted: [] } }
Parameters:
Name Type Description
appName string The name of the app to rollback.
Throws:
If the app does not exist or if there are no backups available.
Type
Error
Returns:
A promise that resolves with the rollback plan.
Type
Promise.<object>

(static) mockUpgrade(appName, packageBuffer) → {Promise.<object>}

Description:
  • Mocks an upgrade plan for an app based on a package buffer. This is a utility function for verifying an app upgrade deployment before it happens.
Example
const upgradePlan = await platform.mockUpgrade('myApp', zipBuffer);
console.log(upgradePlan); // { action: 'Upgrade', fromVersion: '1.0.0', toVersion: '2.0.0', files: { preserved: [], added: [], overwritten: [], deleted: [] } }
Parameters:
Name Type Description
appName string The name of the app to upgrade.
packageBuffer Buffer The .gin file content as a buffer.
Throws:
If the app does not exist or if the package buffer is invalid or contains security issues.
Type
Error
Returns:
A promise that resolves with the upgrade plan.
Type
Promise.<object>

(static) packageApp(appName) → {Promise.<Buffer>}

Description:
  • Packages an entire application into a distributable .gin archive buffer. Obeys the rules in the app's .gpkg manifest file if it exists.
Example
const packageBuffer = await platform.packageApp('myApp');
console.log(packageBuffer); // The packaged app data
Parameters:
Name Type Description
appName string The name of the app to package.
Throws:
If the app does not exist or if the packaging fails.
Type
Error
Returns:
A promise that resolves with the .gin file data.
Type
Promise.<Buffer>

(static) readFile(appName, relativePath, encodingopt) → {string|Buffer}

Description:
  • Reads the content of a file from a specified app's directory.
Example
const content = platform.readFile('myApp', 'box/api/test.js');
console.log(content); // 'console.log("Hello World");'
Parameters:
Name Type Attributes Default Description
appName string The target application.
relativePath string The path of the file to read.
encoding string | null <optional>
 'utf8' The encoding to use. Pass null for a raw Buffer.
Throws:
If the app does not exist or if the file does not exist.
Type
Error
Returns:
The content of the file.
Type
string | Buffer

(static) registerNewApp(appName) → {object}

Description:
  • Registers a new application in the server's context.
Example
const result = platform.registerNewApp('myApp');
console.log(result); // true if registered successfully
Parameters:
Name Type Description
appName string The name of the app to register.
Throws:
If the app already exists or if the name is invalid.
Type
Error
Returns:
Confirmation message and paths.
Type
object

(static) reloadApp(appName) → {boolean}

Description:
  • Reloads an application's configuration and clears its caches.
Example
const result = platform.reloadApp('myApp');
console.log(result); // true if reloaded successfully
Parameters:
Name Type Description
appName string The app to reload.
Throws:
If the app does not exist.
Type
Error
Returns:
True if the app was reloaded successfully.
Type
boolean

(static) rollbackApp(appName, grantedPermissions) → {Promise.<boolean>}

Description:
  • Rolls back an application to its previous version using the latest backup.
Example
const result = await platform.rollbackApp('myApp');
console.log(result); // true if rolled back successfully
Parameters:
Name Type Description
appName string The name of the app to rollback.
grantedPermissions Array.<string> The permissions granted to the app.
Throws:
If the app does not exist or if the rollback fails.
Type
Error
Returns:
A promise that resolves to true if the rollback was successful.
Type
Promise.<boolean>

(static) unzipToApp(appName, relativePath, zipBuffer) → {Promise.<boolean>}

Description:
  • Unzips a buffer into a target folder within an app, validating each entry for security.
Example
const result = await platform.unzipToApp('myApp', 'uploads', zipBuffer);
console.log(result); // true if unzipped successfully
Parameters:
Name Type Description
appName string The target application.
relativePath string The folder within the app to extract to.
zipBuffer Buffer The zip data as a buffer.
Throws:
If the app does not exist or if the zip contains invalid paths.
Type
Error
Returns:
A promise that resolves to true if the unzip was successful.
Type
Promise.<boolean>

(static) upgradeApp(appName, packageBuffer, permissions, optionsopt) → {Promise.<boolean>}

Description:
  • Upgrades an existing application to a new version using a .gin package buffer. Preserves files as specified in the app's .gup configuration.
Example
const grantedPermissions = ["cache", "db", "fs"];
const result = await platform.upgradeApp('myApp', packageBuffer, grantedPermissions);
console.log(result); // true if upgraded successfully
Parameters:
Name Type Attributes Default Description
appName string The name of the app to upgrade.
packageBuffer Buffer The .gin file content as a buffer.
permissions object Permissions to set for the upgraded app.
options object <optional>
 { backup: true } Options for the upgrade process.
Throws:
If the app does not exist or if the upgrade fails.
Type
Error
Returns:
A promise that resolves to true if the upgrade was successful.
Type
Promise.<boolean>

(static) writeFile(appName, relativePath, content) → {boolean}

Description:
  • Writes content to a file within a specified app's directory.
Example
const result = platform.writeFile('myApp', 'box/api/test.js', 'console.log("Hello World");');
console.log(result); // true
Parameters:
Name Type Description
appName string The target application.
relativePath string The path within the app (e.g., 'box/api/test.js').
content string | Buffer The content to write.
Throws:
If the app does not exist or if the path is invalid.
Type
Error
Returns:
True if the file was written successfully.
Type
boolean

(static) zipApp(appName) → {Promise.<Buffer>}

Description:
  • Zips an entire application's directory and returns the data as a buffer.
Example
const zipBuffer = await platform.zipApp('myApp');
console.log(zipBuffer); // The zipped app data
Parameters:
Name Type Description
appName string The name of the app to zip.
Throws:
If the app does not exist or if the zipping fails.
Type
Error
Returns:
A promise that resolves with the zip file data.
Type
Promise.<Buffer>

(inner) analyzeAppBackup(appName) → {Promise.<object>}

Description:
  • Analyzes the backup of a specific application.
Parameters:
Name Type Description
appName string The name of the application.
Throws:
If the app is not found or the backup is invalid.
Type
Error
Returns:
- A promise that resolves with the analysis results.
Type
Promise.<object>

(inner) getAppPermissions(appName) → {Promise.<object>}

Description:
  • Retrieves the permissions for a specific application.
Parameters:
Name Type Description
appName string The name of the application.
Throws:
If the app is not found.
Type
Error
Returns:
A promise that resolves with the app's permissions.
Type
Promise.<object>

(inner) removeAppPermissions(appName) → {Promise.<boolean>}

Description:
  • Removes all permissions for a specific application.
Parameters:
Name Type Description
appName string The name of the application.
Returns:
A promise that resolves with a success message.
Type
Promise.<boolean>

(inner) setAppPermissions(appName, permissionsArray, reloadopt) → {Promise.<object>}

Description:
  • Sets the permissions for a specific application.
Parameters:
Name Type Attributes Default Description
appName string The name of the application.
permissionsArray Array.<string> The permissions to set.
reload boolean <optional>
 true Whether to reload the app after setting permissions.
Throws:
If the app is not found.
Type
Error
Returns:
A promise that resolves with a success message.
Type
Promise.<object>