@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/managers/BaseManager.js

@@ -0,0 +1,415 @@
+/**
+ * Base Manager class - All managers should extend this
+ *
+ * Following JSPWiki's modular manager pattern, this abstract base class
+ * provides common functionality for all managers including initialization,
+ * lifecycle management, and backup/restore operations.
+ *
+ * @class BaseManager
+ * @abstract
+ *
+ * @property {WikiEngine} engine - Reference to the wiki engine
+ * @property {boolean} initialized - Flag indicating initialization status
+ * @property {Record<string, unknown>} config - Configuration object passed during initialization
+ *
+ * @see {@link WikiEngine} for the main engine
+ */
+import logger from '../utils/logger.js';
+import { checkConfiguredPath } from '../utils/PathPreflight.js';
+import { recordAuditEvent } from '../utils/auditEvents.js';
+import { AUDIT_EVENT } from '../utils/auditEventNames.js';
+class BaseManager {
+    /** Reference to the wiki engine */
+    engine;
+    /** Initialization status flag */
+    initialized;
+    /** Configuration passed during initialization */
+    config;
+    /** What this manager is doing (#1155). Ready until something says otherwise. */
+    status = { state: 'ready' };
+    /**
+     * Short description of what this manager does.
+     * Used by admin UIs, addon registries, and introspection tools.
+     * Override in subclasses to provide a human-readable description.
+     */
+    description;
+    /**
+     * Creates a new BaseManager instance
+     *
+     * @param engine - The wiki engine instance
+     *
+     * @example
+     * class MyManager extends BaseManager {
+     *   constructor(engine: WikiEngine) {
+     *     super(engine);
+     *     this.myData = new Map();
+     *   }
+     * }
+     */
+    constructor(engine) {
+        this.engine = engine;
+        this.initialized = false;
+    }
+    /**
+     * Initialize the manager with configuration
+     *
+     * Override this method in subclasses to perform initialization logic.
+     * Always call super.initialize() first in overridden implementations.
+     *
+     * @param config - Configuration object
+     *
+     * @example
+     * async initialize(config: Record<string, any> = {}): Promise<void> {
+     *   await super.initialize(config);
+     *   // Your initialization logic here
+     *   console.log('MyManager initialized');
+     * }
+     */
+    async initialize(config = {}) {
+        this.config = config;
+        this.initialized = true;
+    }
+    /**
+     * Check if manager has been initialized
+     *
+     * @returns True if manager is initialized
+     *
+     * @example
+     * if (manager.isInitialized()) {
+     *   // Safe to use manager
+     * }
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get the wiki engine instance
+     *
+     * @returns The wiki engine instance
+     *
+     * @example
+     * const config = this.getEngine().getConfig();
+     */
+    getEngine() {
+        return this.engine;
+    }
+    /** A page's data changed outside savePage: its cached content goes, and every cached render re-renders (#1751). */
+    invalidateHandlerCache(pageUuid) {
+        this.engine.getManager('PageManager')?.invalidatePageCache(pageUuid);
+    }
+    /**
+     * Preflight a configured filesystem path before any mkdir/write happens.
+     *
+     * Wraps `checkConfiguredPath()` with a standardized warning log that names
+     * the manager (`this.constructor.name`) and the originating config key.
+     * Useful for paths that may live on volumes the OS has unmounted (notably
+     * macOS `/Volumes/<X>/...`), where `fs.ensureDir` would otherwise crash
+     * the engine with an opaque `EACCES`.
+     *
+     * The caller decides what to do on failure (degrade, fall back to a
+     * default, or treat as fatal).
+     *
+     * @param configKey  The config key that supplied this path — included in
+     *                   the warning so operators know what to fix.
+     * @param path       The resolved path to check.
+     * @returns          The preflight result. `result.ok === true` means safe
+     *                   to proceed.
+     *
+     * @example
+     * const preflight = this.preflightConfiguredPath(
+     *   'ngdpbase.backup.directory',
+     *   this.backupDirectory
+     * );
+     * if (!preflight.ok) {
+     *   // degrade — disable feature, fall back to default, etc.
+     *   return;
+     * }
+     */
+    preflightConfiguredPath(configKey, path, options = {}) {
+        // `options` carries only test seams (see PathPreflight). It is threaded
+        // through so the degraded-state path can be exercised on any platform:
+        // the underlying check runs on darwin alone, so on Linux CI this branch
+        // was unreachable and the test asserting it failed on every run.
+        const result = checkConfiguredPath(path, options);
+        if (!result.ok) {
+            logger.warn(`⚠️  ${this.constructor.name}: ${result.message} ` +
+                `(config key: ${configKey}).`);
+            // #1155: recorded, not only logged. This is the common entry point every
+            // degrading manager already goes through, so setting the state here is
+            // what makes twelve invisible degradations visible without each caller
+            // remembering to say so.
+            this.markDegraded(result.message ?? 'the configured path could not be used', configKey);
+        }
+        return result;
+    }
+    /**
+     * What this manager is doing (#1155).
+     *
+     * Not `getStatus()`: that name is already taken by `AddonsManager` and
+     * `BackgroundJobManager` for entirely different things, and a base-class
+     * method silently overridden by two subclasses would be worse than a longer
+     * name.
+     */
+    getManagerStatus() {
+        return { ...this.status };
+    }
+    /**
+     * Record that this manager is configured, wanted, and not working.
+     *
+     * @returns true when this is a TRANSITION — a state or reason that differs
+     *   from the current one. Only a transition is an event: a manager that
+     *   starts degraded and stays degraded must not re-emit on every boot, or
+     *   the signal is buried in its own noise.
+     */
+    markDegraded(reason, configKey) {
+        return this.transition({ state: 'degraded', reason, configKey });
+    }
+    /** Record that this manager is deliberately off. Not a problem (#1155). */
+    markDisabled(reason) {
+        return this.transition({ state: 'disabled', reason });
+    }
+    /** Record that this manager could not initialise at all (#1155). */
+    markFailed(reason, configKey) {
+        return this.transition({ state: 'failed', reason, configKey });
+    }
+    /**
+     * Record that this manager is working.
+     *
+     * Clears the reason rather than leaving a stale one behind — a recovered
+     * manager still carrying "the directory is not writable" is a worse lie than
+     * no reason at all.
+     */
+    markReady() {
+        return this.transition({ state: 'ready' });
+    }
+    /**
+     * Record that this manager is working again, but only while it is still
+     * degraded for `reason` — the one a check set, now cleared by re-running
+     * it (#1842). A different fault set since stays reported.
+     */
+    markReadyIfDegradedBy(reason) {
+        if (this.status.state !== 'degraded' || this.status.reason !== reason)
+            return false;
+        return this.markReady();
+    }
+    /**
+     * Apply a state and audit it if it CHANGED.
+     *
+     * Only a transition is an event. A manager that starts degraded and stays
+     * degraded must not re-emit on every boot, or the signal is buried in its
+     * own noise — and the at-boot picture is already carried by #1149's
+     * `system-start` record.
+     *
+     * Emitted from here rather than each manager, per the #1120 rule: a producer
+     * that has to remember to call something can be correct, but can never be
+     * PROVABLE.
+     */
+    transition(next) {
+        const changed = this.status.state !== next.state || this.status.reason !== next.reason;
+        this.status = next;
+        if (!changed)
+            return false;
+        // Fire-and-forget. Refusing to degrade because the record could not be
+        // written would take an instance down over a feature that is already
+        // broken, which is the wrong way round.
+        void recordAuditEvent(this.engine?.getManager?.('AuditManager'), {
+            eventType: AUDIT_EVENT.MANAGER_STATE_CHANGE,
+            user: 'system',
+            ipAddress: undefined,
+            action: 'manager-state-change',
+            result: 'success',
+            severity: next.state === 'degraded' || next.state === 'failed' ? 'high' : 'low',
+            metadata: {
+                manager: this.constructor.name,
+                state: next.state,
+                ...(next.reason ? { reason: next.reason } : {}),
+                ...(next.configKey ? { configKey: next.configKey } : {})
+            }
+        });
+        return true;
+    }
+    /**
+     * Shutdown the manager and cleanup resources
+     *
+     * Override this method in subclasses to perform cleanup logic.
+     * Always call super.shutdown() at the end of overridden implementations.
+     *
+     * @example
+     * async shutdown(): Promise<void> {
+     *   // Your cleanup logic here
+     *   await this.closeConnections();
+     *   await super.shutdown();
+     * }
+     */
+    async shutdown() {
+        this.initialized = false;
+    }
+    /**
+     * Backup manager data
+     *
+     * MUST be overridden by all managers that manage persistent data.
+     * Default implementation returns an empty backup object.
+     *
+     * @returns Backup data object containing all manager state
+     * @throws {Error} If backup operation fails
+     *
+     * @example
+     * async backup(): Promise<BackupData> {
+     *   return {
+     *     managerName: this.constructor.name,
+     *     timestamp: new Date().toISOString(),
+     *     data: {
+     *       users: Array.from(this.users.values()),
+     *       settings: this.settings
+     *     }
+     *   };
+     * }
+     */
+    async backup() {
+        // Default implementation returns empty object
+        // Managers with data MUST override this method
+        return {
+            managerName: this.constructor.name,
+            timestamp: new Date().toISOString(),
+            data: null
+        };
+    }
+    /**
+     * Restore manager data from backup
+     *
+     * MUST be overridden by all managers that manage persistent data.
+     * Default implementation only validates that backup data is provided.
+     *
+     * @param backupData - Backup data object from backup() method
+     * @throws {Error} If restore operation fails or backup data is missing
+     *
+     * @example
+     * async restore(backupData: BackupData): Promise<void> {
+     *   if (!backupData || !backupData.data) {
+     *     throw new Error('Invalid backup data');
+     *   }
+     *   this.users = new Map(backupData.data.users.map(u => [u.id, u]));
+     *   this.settings = backupData.data.settings;
+     * }
+     */
+    async restore(backupData) {
+        // Default implementation does nothing
+        // Managers with data MUST override this method
+        if (!backupData) {
+            throw new Error(`${this.constructor.name}: No backup data provided for restore`);
+        }
+    }
+    /**
+     * Return a plain-text string suitable for use as MarqueePlugin banner text.
+     *
+     * Override in subclasses to expose live manager data as a scrolling banner:
+     *
+     *   [{MarqueePlugin fetch='PageManager.toMarqueeText()'}]
+     *   [{MarqueePlugin fetch='PageManager.toMarqueeText(limit=5,sort=date-desc)'}]
+     *
+     * The default returns '' (no output). Subclasses should return a concise,
+     * single-line summary. Common options (limit, sortBy, sortOrder, since, before)
+     * are available via ManagerFetchOptions; domain-specific keys are read directly
+     * from the raw options object passed by the caller.
+     *
+     * @param _options  Parsed fetch args from the plugin invocation.
+     * @param _viewer   The viewer's context (#1556): show only what they may see.
+     *                  Page text reaches this method, and only this method, on
+     *                  every render for every viewer.
+     * @returns Plain text, or '' if this manager has nothing to display.
+     *
+     * @example
+     * async toMarqueeText(options: ManagerFetchOptions = {}): Promise<string> {
+     *   const pages = await this.getRecentChanges(options.limit ?? 5);
+     *   return 'Recent: ' + pages.map(p => p.name).join('  •  ');
+     * }
+     */
+    async toMarqueeText(_options = {}, _viewer) {
+        return '';
+    }
+    /**
+     * Return the choices for a form dropdown, for the forms add-on's
+     * `"optionsSource": "fetch:ManagerName.toFormOptions(list=funds)"`.
+     *
+     * The same convention and the same safety rules as `toMarqueeText()`: it is
+     * the one other method page content may reach (`resolveManagerOptions`), it
+     * runs on every render for every viewer, and it must have no side effect.
+     * Offer only what `_viewer` may see. The forms add-on calls it again when the
+     * form is submitted and refuses a value that is not among the choices.
+     *
+     * @param _options  Parsed args from the spec, as raw `{ key: value }` strings.
+     * @param _viewer   The viewer's context.
+     * @returns `{ value, label }` choices (plain strings are accepted too), or `[]`.
+     */
+    async toFormOptions(_options = {}, _viewer) {
+        return [];
+    }
+    /**
+     * What this manager holds (#1006).
+     *
+     * __Counts and health only — never item contents.__ That is the whole safety
+     * property, and it is why this is not the `getAll()` the question originally
+     * asked for. `AgentTokenManager` holds bearer credentials, `UserManager`
+     * holds users, `ShareManager` holds capability tokens; a generic enumeration
+     * on the base class means the first generic caller — an admin dump panel, a
+     * search indexer, a debug route — reaches all of it by default. A count
+     * cannot leak what it counts.
+     *
+     * Optional by override, with a safe default, exactly like `backup()` and
+     * `toMarqueeText()` above. A manager holding no countable collection omits
+     * `count` rather than reporting `0`, because "nothing to count" and "none"
+     * are different answers and an admin row that shows `0` for
+     * `RenderingManager` is noise.
+     *
+     * __Never throws.__ A broken manager reports `healthy: false`; it does not
+     * take down the page rendering every other manager. The base wraps nothing,
+     * so an override that can fail must catch its own errors — see the note on
+     * `safeGetManagerStats()`.
+     *
+     * __Named `getManagerStats`, not `getStats`.__ Two managers already have a
+     * `getStats()` returning their own domain shape — `FilterManager` (pipeline
+     * statistics, #615) and `NotificationManager` (`NotificationStats`, read by
+     * a live route). Both are correct for what they do, and taking the name from
+     * them would either break those callers or leave `getStats()` meaning two
+     * different things depending on the manager, which is the exact confusion
+     * this contract exists to remove. A generic caller needs a name that means
+     * one thing everywhere.
+     *
+     * @example
+     * async getManagerStats(): Promise<ManagerStats> {
+     *   const active = this.list('').filter((r) => !r.revokedAt);
+     *   return { ...await super.getManagerStats(), count: active.length };
+     * }
+     */
+    async getManagerStats() {
+        return {
+            // #1155 already answers "is this manager working", with four states and
+            // a reason. Re-deriving health from `isInitialized()` here would put a
+            // second, weaker source of truth next to it — a manager could be
+            // initialised and degraded, and the two answers would disagree with
+            // nothing to reconcile them. So this is the SAME fact, narrowed for a
+            // one-line admin row; a caller wanting why asks getManagerStatus().
+            healthy: this.getManagerStatus().state === 'ready'
+        };
+    }
+    /**
+     * `getManagerStats()` that cannot break the page it is rendered on.
+     *
+     * The contract says an override must not throw, and saying so does not make
+     * it true — an override reads a store, and a store can fail. This is what an
+     * admin surface iterating every manager should call: one manager throwing
+     * becomes one unhealthy row rather than a 500 for all of them.
+     */
+    async safeGetManagerStats() {
+        try {
+            return await this.getManagerStats();
+        }
+        catch (err) {
+            return {
+                healthy: false,
+                summary: `stats unavailable: ${err instanceof Error ? err.message : String(err)}`
+            };
+        }
+    }
+}
+export default BaseManager;

package/lib/src/managers/CacheManager.d.ts

@@ -0,0 +1,159 @@
+import BaseManager from './BaseManager.js';
+import RegionCache from '../cache/RegionCache.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * Cache options for set operations
+ */
+export interface CacheOptions {
+    ttl?: number;
+}
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+    provider: string | null;
+    defaultTTL: number;
+    maxKeys: number;
+    checkPeriod: number;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    global?: unknown;
+    regions?: string[];
+    provider?: string | null;
+    config?: CacheConfig;
+    [key: string]: unknown;
+}
+declare class CacheManager extends BaseManager {
+    private provider;
+    private providerClass;
+    private regions;
+    private defaultTTL;
+    private maxKeys;
+    private checkPeriod;
+    /**
+     * Creates a new CacheManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the CacheManager and load the configured provider
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     * @throws {Error} If ConfigurationManager is not available
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Load the cache provider dynamically
+     * @private
+     * @returns {Promise<void>}
+     */
+    private loadProvider;
+    /**
+     * Normalize provider name to PascalCase class name
+     * @param {string} providerName - Lowercase provider name (e.g., 'nodecacheprovider')
+     * @returns {string} PascalCase class name (e.g., 'NodeCacheProvider')
+     * @private
+     */
+    private normalizeProviderName;
+    /**
+     * Get a cache region for a specific namespace
+     * @param {string} region - Region name (typically manager name)
+     * @returns {RegionCache} Cache instance scoped to the region
+     */
+    region(region: string): RegionCache;
+    /**
+     * The current version of a data topic: by convention a manager's name
+     * (`LedgerManager`). A cached render built from the topic is served only
+     * while this is unchanged (`RegionCache.getOrSetVersioned`). `'0'` until
+     * the topic is first bumped.
+     */
+    version(topic: string): Promise<string>;
+    /**
+     * Say that a topic's data changed: every cached render that read it is
+     * re-rendered on its next read. A manager calls this after each write, at
+     * its one door. Versions never expire (TTL 0); each bump is a new unique
+     * value, so two instances sharing a cache cannot collide on a count.
+     */
+    bump(topic: string): Promise<string>;
+    /**
+     * Get a value from the cache (global scope)
+     * @param {string} key - The cache key
+     * @returns {Promise<unknown>} The cached value or undefined if not found
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Set a value in the cache (global scope)
+     * @param {string} key - The cache key
+     * @param {unknown} value - The value to cache
+     * @param {CacheOptions} [options] - Cache options
+     * @param {number} [options.ttl] - Time to live in seconds
+     * @returns {Promise<void>}
+     */
+    set(key: string, value: unknown, options?: CacheOptions): Promise<void>;
+    /**
+     * Delete one or more keys from the cache
+     * @param {string|string[]} keys - Single key or array of keys to delete
+     * @returns {Promise<void>}
+     */
+    del(keys: string | string[]): Promise<void>;
+    /**
+     * Clear cache entries
+     * @param {string} [region] - Optional region to clear (if not specified, clears all)
+     * @param {string} [pattern] - Optional pattern to match keys
+     * @returns {Promise<void>}
+     */
+    clear(region?: string, pattern?: string): Promise<void>;
+    /**
+     * Get keys matching a pattern
+     * @param {string} [pattern='*'] - Pattern to match
+     * @returns {Promise<string[]>} Array of matching keys
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Get cache statistics
+     * @param {string} [region] - Optional region to get stats for
+     * @returns {Promise<CacheStats>} Cache statistics
+     */
+    stats(region?: string): Promise<CacheStats>;
+    /**
+     * Check if the cache is healthy
+     * @returns {Promise<boolean>} True if cache is healthy
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Get cache configuration
+     * @returns {CacheConfig} Cache configuration
+     */
+    getConfig(): CacheConfig;
+    /**
+     * Get all active regions
+     * @returns {string[]} Array of region names
+     */
+    getRegions(): string[];
+    /**
+     * Flush all caches (dangerous operation)
+     * @returns {Promise<void>}
+     */
+    flushAll(): Promise<void>;
+    /**
+     * Close and cleanup cache resources
+     * @returns {Promise<void>}
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Helper method to add cache support to BaseManager
+     * Can be called from any manager to get a cache region
+     * @param {any} engine - WikiEngine instance
+     * @param {string} [region] - Region name (defaults to calling class name)
+     * @returns {RegionCache} Cache instance scoped to the region
+     */
+    static getCacheForManager(engine: WikiEngine, region?: string): RegionCache;
+}
+export default CacheManager;