Global

Members

(constant) FORBIDDEN_BUILTINS

Description:

• Host Node built-ins that must never be opened via box.allowed_modules. Note: bare 'fs' is the Gingee sandboxed module (modules/fs.js), not host fs — host fs is blocked because it is not on the allowed list and is not a gingee module under node:fs.

(constant) LUA_DISCARD_DLQ

Description:

• Atomic DLQ discard: KEYS[1]=dlq list, KEYS[2]=job key, KEYS[3]=processing zset ARGV[1]=jobId Returns 1 if discarded, 0 if not on DLQ (does not delete live job hashes).

(constant) LUA_RETRY_DLQ

Description:

• Atomic DLQ retry claim + re-queue: KEYS[1]=dlq, KEYS[2]=job key, KEYS[3]=ready list, KEYS[4]=delayed zset, KEYS[5]=processing zset ARGV[1]=jobId, ARGV[2]=maxAttempts (0 = keep), ARGV[3]=nowMs, ARGV[4]=ttlSec Returns job JSON string or false if not available / not failed. Only one concurrent caller wins the LREM.

(constant) RESERVED_DELETE_APP_NAMES

Description:

• App names that must never be uninstalled via the public delete API. Upgrade/rollback may still replace them via deleteApp(..., { allowReserved: true }).

(constant) Redis

Description:

• Redis cache adapter. Connection config uses the same shape as queue.redis / scheduler.redis: nested under cache.redis, with optional url or host/port/password/db. Accepts full cache section from cache_service.init (provider, prefix, redis, …) or a bare redis options object (tests / legacy).

(constant) SAFE_APP_NAME_RE

Description:

• Safe app directory names only (no path separators, no `..`).

activeProvider

Description:

• Last successfully initialized provider name

(constant) inflight :Map.<string, {abortController: AbortController, cancelled: boolean}>

Description:

• In-flight HTTP scripts: requestId → { abortController, cancelled } Master sends `cancel_request` on timeout (M4).

Type:

• Map.<string, {abortController: AbortController, cancelled: boolean}>

(constant) instanceCache :Map.<string, {exports: *}>

Description:

• Sandboxed module instance cache (Node require.cache semantics inside gbox). Keyed by appName + absolute script path so shared local_modules paths do not leak exports / closed-over require across apps.

Type:

• Map.<string, {exports: *}>

(constant) path

Description:

• App worker process entry (forked by worker_manager). Runs sandboxed server scripts for one app or an isolation group. Messages in: { type: 'init', workerKey, apps: [...], ... } { type: 'http_script', requestId, appName, ... } { type: 'shutdown' } Messages out: { type: 'ready', workerKey } { type: 'http_result', requestId, ... } // buffered { type: 'stream_start'|'stream_chunk'|'stream_end'|'stream_error', requestId, ... } { type: 'log', level, message }

serviceLogger :object|null

Type:

• object | null

workerState :object|null

Type:

• object | null

Methods

_reclaimStale()

Description:

• Test / ops hook

allowDynamicCodeFromBox(box) → {boolean}

Description:

• Whether sandbox string codegen (eval / new Function) is allowed for the server default. Prefer box.allow_dynamic_code; legacy box.allow_code_generation still honored. Default: true (Instant Time to Joy — many UMD libs need Function at load).

Parameters:

Returns:

Type

boolean

cancelInflight(requestId, reasonopt)

Description:

• Cooperative cancel for one requestId.

Parameters:

clearInstanceCache(appNameopt) → {void}

Description:

• Drop cached sandboxed module instances. When appName is omitted, clears the entire instance cache. When provided, clears only keys for that app (prefix match).

Parameters:

Returns:

Type

void

clearScriptCachesByPrefixes(appName, absPrefixes) → {Object}

Description:

• Drop transpile + instance cache entries whose script paths lie under any of the absolute prefixes (for one app). Used by cache.invalidateSysCache.

Parameters:

Returns:

Type

Object

createMemoryDriver(opts)

Parameters:

createRedisDriver(opts)

Parameters:

deadLetter(job, erropt)

Description:

• Permanent failure → DLQ.

Parameters:

deadLetter(job, erropt)

Description:

• Permanent failure → DLQ list + job hash.

Parameters:

discardDlq(jobId) → {Promise.<boolean>}

Description:

• Atomically remove a job from the DLQ and delete its hash. Safe if jobId is not on DLQ (does not touch live job payloads).

Parameters:

Returns:

Type

Promise.<boolean>

extendVisibility(jobId)

Description:

• Extend processing lease while a long job runs.

Parameters:

fail()

Deprecated:

• use deadLetter

formatAddress(address, channel) → {string}

Description:

• Prefix WhatsApp scheme when channel is whatsapp; leave existing whatsapp: alone.

Parameters:

Returns:

Type

string

getProvider() → {string|null}

Returns:

Type

string | null

(async) init(config, logger)

Parameters:

isPathInside(candidatePath, boundaryPath, optionsopt) → {boolean}

Description:

• Returns true if `candidatePath` is the same as, or a descendant of, `boundaryPath`. Safer than String.startsWith on resolved paths: rejects sibling directories that only share a string prefix (e.g. `/web/app1` vs `/web/app10` or `C:\web\app1` vs `C:\web\app1_evil`). Also expands symlinks via resolveRealPath so a writable jail cannot escape by planting a symlink to an outside path (H12).

Parameters:

Returns:

Type

boolean

listPending(optsopt) → {Promise.<Array.<object>>}

Description:

• Jobs not yet completed (delayed timers + ready). Admin / Glade live view.

Parameters:

Returns:

Type

Promise.<Array.<object>>

listPending(optsopt)

Description:

• Ready + delayed + processing (claimed leases) for Glade live view.

Parameters:

loadJsonFile(filePath) → {object|array|string|number|boolean|null}

Description:

• Read and parse a JSON file. Purges require.cache for the path when present so repeated loads (reload) see disk changes. Throws a clear SyntaxError-style message on invalid JSON (does not crash the process by itself).

Parameters:

Returns:

Type

object | array | string | number | boolean | null

loadOptional(loader, packageName, featureLabel) → {any}

Description:

• Load an optional npm package with a clear operator-facing error. Used when packages live under package.json `optionalDependencies` (or may be omitted via `npm install --omit=optional`). Prefer a **static** loader so Jest/bundlers can resolve and mock the package: loadOptional(() => require('pdfmake'), 'pdfmake', 'PDF generation')

Parameters:

Returns:

Type

any

pendingCounts() → {Promise.<{pending: number, delayed: number}>}

Returns:

Type

Promise.<{pending: number, delayed: number}>

releaseClaim(jobOrId)

Description:

• Return a claimed job to the ready path (wait-queue drain).

Parameters:

releaseClaim(jobOrId)

Description:

• Return a claimed job to the ready list (wait-queue drain on shutdown).

Parameters:

requireOptional()

Deprecated:

• Prefer loadOptional with a static `() => require('pkg')` loader so Jest mocks apply. Kept for call sites that only need a string require.

resolveAllowDynamicCode(gBoxConfigopt) → {boolean}

Description:

• Resolve for a gBoxConfig run (server box + app config; optional per-run override).

Parameters:

Returns:

Type

boolean

resolveAllowDynamicCodeForApp(serverBox, appConfig) → {boolean}

Description:

• Resolve allow_dynamic_code for a specific app. Policy (explicit app wins): - If app.json sets allow_dynamic_code (or nested box.allow_dynamic_code), that value is used — apps may opt in (true) or tighten (false). - Otherwise inherit server box.allow_dynamic_code (default true). - Legacy key allow_code_generation is accepted at both levels. Typical production pattern: server false, only apps that need UMD libs set true.

Parameters:

Returns:

Type

boolean

resolveFailClosed(cacheConfig, provider) → {boolean}

Description:

• Whether Redis init failure should abort (true) or fall back to memory (false). Default: fail closed when provider is redis.

Parameters:

Returns:

Type

boolean

resolveRealPath(p) → {string}

Description:

• Resolve a path with `realpath` on every existing ancestor. Non-existent leaf segments are re-joined under the realpath of the deepest existing parent. This closes symlink-jail escapes for paths that do not exist yet (e.g. write targets under a symlink directory).

Parameters:

Returns:

Type

string

resolveRedisConnection(config) → {Object|Object}

Description:

• Resolve ioredis constructor args from cache config. Prefers nested `config.redis`; falls back to top-level host/port/url for legacy flat configs.

Parameters:

Returns:

Type

Object | Object

retryDlq(jobId, optsopt) → {Promise.<(object|null)>}

Description:

• Atomically claim from DLQ then re-enqueue (attempt 1). Concurrent retries: second caller gets null after first claims.

Parameters:

Returns:

Type

Promise.<(object|null)>

retryDlq(jobId, optsopt) → {Promise.<(object|null)>}

Description:

• Atomically claim a DLQ job and re-queue it (attempt 1). Concurrent retries: only one caller receives a job; others get null.

Parameters:

Returns:

Type

Promise.<(object|null)>

(async) runHttpScript(msg)

Parameters:

(async) runStartupScripts() → {Promise.<boolean>}

Returns:

Type

Promise.<boolean>

stopConsuming()

Description:

• Stop delivering new jobs to onReady (graceful shutdown).

stopConsuming()

Description:

• Stop BRPOP / delivering new jobs (graceful shutdown step 1).

waitForResponseSettle(res, store, maxMs, signalopt)

Description:

• Wait until response is completed/ended, aborted, or timeout. Covers fire-and-forget `gingee(...)` without await.

Parameters:

waitUntilReady(client, timeoutMs)

Description:

• Wait until Redis is ready or reject (for fail-closed boot). Injected mock clients may skip status and just ping.

Parameters: