@crowi/api 2.0.0-alpha.0

package/dist/crowi/index.d.ts

@@ -0,0 +1,245 @@
+import Tokens from 'csrf';
+import http from 'http';
+import mongoose from 'mongoose';
+import { type AttachedCollab } from '../collab/attach';
+import events from '../events';
+import models from '../models';
+import { type AttachedNotifications } from '../notifications/attach';
+import { PluginManager, type PluginRegistries } from '../plugin';
+import { type AttachedPresence } from '../presence/attach';
+import { type Renderer } from '../renderer';
+import { MailService } from '../service/mail';
+import { type BootReporter } from '../util/boot-reporter';
+import ConfigService from '../service/config';
+type Models = {
+    [K in keyof typeof models]: ReturnType<(typeof models)[K]>;
+};
+type Events = {
+    [K in keyof typeof events]: InstanceType<(typeof events)[K]>;
+};
+declare class Crowi {
+    version: string;
+    rootDir: string;
+    pluginDir: string;
+    publicDir: string;
+    resourceDir: string;
+    tmpDir: string;
+    cacheDir: string;
+    mongoose: any;
+    config: any;
+    mailer: MailService | null;
+    lru: any;
+    tokens: Tokens;
+    models: Models;
+    events: Events;
+    env: typeof process.env;
+    baseUrl: string | null;
+    node_env: string;
+    port: number;
+    redis: any;
+    redisUrl: string | null;
+    redisOpts: any;
+    /**
+     * PluginManager + resolved registries. Available after `setupPlugins`
+     * runs in `init()`. `null` until then so a half-booted process is
+     * obvious in stack traces.
+     */
+    pluginManager: PluginManager | null;
+    pluginRegistries: PluginRegistries | null;
+    /**
+     * Markdown renderer pipeline + registry. Available after
+     * `setupRenderer` runs in `init()` (between `setupModels` and
+     * `setupPlugins` — so PluginManager can layer external plugins on
+     * top of the core registrations).
+     */
+    renderer: Renderer | null;
+    /**
+     * Hocuspocus engine attach handle (RFC-0003 Phase 9 same-process).
+     * Built lazily in `start()` after the http.Server is listening so
+     * the `'upgrade'` event can be wired before any client connects.
+     * `null` outside of the running server (= `init()` finished but
+     * `start()` hasn't run yet, or after `shutdown()`).
+     */
+    collabAttachment: AttachedCollab | null;
+    /**
+     * Presence WebSocket attach handle (RFC-0005). Built in `start()`
+     * alongside `collabAttachment`; wires the `/presence` ws noServer
+     * handler so page viewers get the live-presence row. `null` outside
+     * of the running server.
+     */
+    presenceAttachment: AttachedPresence | null;
+    /**
+     * Notifications realtime invalidation WebSocket attach handle. Built
+     * in `start()` next to `collabAttachment` / `presenceAttachment`;
+     * wires the `/notifications/<userId>` ws noServer handler so the
+     * NotificationBell can drop its 30-second polling loop in favour of
+     * Redis-pub/sub-driven invalidation. `null` outside of the running
+     * server.
+     */
+    notificationsAttachment: AttachedNotifications | null;
+    /**
+     * Docker-style boot progress reporter (feature-boot-progress-ui). Spans
+     * `init()` (core/config/services layers) and `start()` (server layer), so it
+     * lives on the instance rather than a local. `null` for the CLI lightweight
+     * init (`initForCli`) which keeps the legacy quiet UX.
+     */
+    bootReporter: BootReporter | null;
+    initialized: boolean;
+    /**
+     * In-flight fire-and-forget side effects (EventEmitter listeners +
+     * Mongoose `post('save')` hooks that start an un-awaited DB/redis write).
+     * `trackSideEffect` adds the promise here and removes it on settle;
+     * `drainSideEffects` awaits the set until it is empty.
+     *
+     * Production never calls `drainSideEffects`, so tracking is the only
+     * runtime cost on the request path (a Set add/delete per side effect) and
+     * the drain primitive is a no-op there. The test harness drains before
+     * disconnecting Mongo so settling writes do not race the close.
+     */
+    private inFlightSideEffects;
+    constructor(rootdir: string, env: typeof process.env);
+    init(): Promise<void>;
+    private runInitLayers;
+    /**
+     * Lightweight init for the `@crowi/admin-cli` operator CLI. Brings up
+     * just what's needed to read Config + reach storage drivers — Redis
+     * / mailer / search / LRU / the boot-time AWS migration are
+     * all skipped (the migration belongs to `init()` so the long-running
+     * server runs it once; the CLI shouldn't mutate Mongo as a side
+     * effect of starting up).
+     *
+     * `setupConfig` works without Redis because `service/config.ts:setupPubSub`
+     * short-circuits when `redisOpts === null`.
+     *
+     * The CLI follows up with `teardownForCli()` to disconnect Mongo so
+     * the Node process exits cleanly.
+     */
+    initForCli(): Promise<void>;
+    /**
+     * Reverse of `initForCli`. Closes any connection the CLI helper opened
+     * so the Node process exits without dangling handles. Defensive about
+     * Redis (we never opened it in CLI mode, but a future helper might).
+     */
+    teardownForCli(): Promise<void>;
+    /**
+     * Track a fire-and-forget side effect so the test harness can drain it
+     * before tearing the connection down. The promise is removed from the
+     * in-flight set once it settles (resolve OR reject); we deliberately do
+     * NOT re-throw or alter the rejection — the caller keeps its own
+     * `.catch` and error-swallowing posture unchanged. This is purely
+     * drain bookkeeping.
+     *
+     * INVARIANT: a tracked side effect MUST be a finite chain. Never track
+     * work that re-schedules itself (recurring / periodic timers, retry
+     * loops with no terminal condition) — `drainSideEffects()` loops until
+     * the set empties, so a self-rescheduling effect makes the drain
+     * (`afterEach` + the test response barrier in `test/setup.ts`) never
+     * settle, and every HTTP test then hangs until jest's `testTimeout`.
+     * Multi-level fan-out is fine (each level settles); unbounded
+     * re-arming is not.
+     */
+    trackSideEffect(p: Promise<unknown>): void;
+    /**
+     * Wait until every tracked side effect has settled. Loops because a
+     * side effect can spawn a second-level fire-and-forget while draining
+     * (Activity `post('save')` → Notification fan-out; `userEvent`
+     * 'activated' → user-page creation → page events → backlink/watch/
+     * mention), and those are tracked too. Resolves once the set is empty.
+     *
+     * Production never calls this — it is the test-teardown drain hook.
+     */
+    drainSideEffects(): Promise<void>;
+    setupRenderer(options?: {
+        registerPageEventListeners?: boolean;
+    }): void;
+    /**
+     * Markdown renderer (parse → transform pipeline + extension registry).
+     * Throws if accessed before `setupRenderer` ran.
+     */
+    getRenderer(): Renderer;
+    setupPlugins(): Promise<void>;
+    /**
+     * Active storage / search / auth / notifier drivers resolved from
+     * `crowi.config.json`. Throws if accessed before `setupPlugins` ran.
+     */
+    getPlugins(): PluginRegistries;
+    isInitialized(): boolean;
+    isPageId(pageId: any): boolean | undefined;
+    setConfig(config: any): void;
+    getConfig(): any;
+    getConfigService(): ConfigService;
+    /**
+     * The site's public origin (the web app), used to build absolute URLs
+     * in emails (invite / activation / reset / email-change links) and for
+     * CORS. Sourced solely from the `CLIENT_URL` env — no fallback.
+     *
+     * Deliberately NOT derived from the incoming request: trusting the
+     * Host / Origin header here would let an attacker poison reset /
+     * activation links in a victim's inbox (host-header injection). When
+     * `CLIENT_URL` is unset this returns `null` and mail links fall back to
+     * relative paths — `setupMailer` warns about that at boot.
+     */
+    getBaseUrl(): string | null;
+    /**
+     * The address the api server itself is listening on (`this.port`, default
+     * 4301). Used for the boot reporter's `🚀 API ready` banner and the
+     * `@@crowi:ready api <url>` marker that `scripts/dev.mjs` keys on.
+     *
+     * Deliberately NOT `getBaseUrl()`: that is `CLIENT_URL` / `app:url`, the
+     * public site origin, which in dev is the web app on :4302 — using it here
+     * would mislabel the api as the web port.
+     */
+    getApiReadyUrl(): string;
+    /**
+     * Emit a boot-time line (warning / error / info such as the plugin summary)
+     * without corrupting the live progress spinner. When the reporter is active
+     * it clears the current spinner line, runs `write`, then re-draws; otherwise
+     * (no reporter / plain mode) it just runs `write`. Keeps the existing
+     * console.warn/error/log visibility intact (these are not gated on DEBUG).
+     */
+    bootNote(write: () => void): void;
+    getEnv(): NodeJS.ProcessEnv;
+    buildRedisOpts(redisUrl: string | null, redisRejectUnauthorized: boolean): Record<string, unknown> | null;
+    model<T extends keyof Models>(name: T, model?: Models[T]): Models[T];
+    event<T extends keyof Events>(name: T, event?: Events[T]): Events[T];
+    /**
+     * Validate CROWI_ENCRYPTION_KEY at boot. When set, it must base64-decode to
+     * exactly 32 bytes (AES-256). When unset we log a warning and let Config
+     * fall back to plaintext at-rest storage — same behaviour as pre-encryption
+     * deployments — so a missing key never blocks boot.
+     */
+    setupEncryption(): void;
+    setupDatabase(): Promise<typeof mongoose>;
+    setupRedisClient(): Promise<void>;
+    setupModels(): Promise<void>;
+    setupEvents(): void;
+    getMongo(): any;
+    /**
+     * True when the Mongoose connection is in the `connected` state
+     * (`readyState === 1`). Used to guard fire-and-forget deferred writes:
+     * a side effect scheduled by a synchronous `emit()` / `post('save')`
+     * can fire after the harness has begun tearing the connection down
+     * (`connecting=2` / `disconnecting=3` / `disconnected=0`), at which
+     * point the write would throw a teardown-noise `MongoNotConnectedError`
+     * / `MongoPoolClosedError`. We skip the write instead. In normal
+     * operation `readyState === 1` always holds, so production behaviour is
+     * unchanged.
+     */
+    isMongoConnected(): boolean;
+    getIo(): any;
+    /**
+     * Backwards-compat shim for legacy controllers that still reference
+     * `crowi.getSearcher()`. Returns the active search driver from the
+     * plugin registry, or `null` if none is configured / registered.
+     * New code should read `crowi.getPlugins().active.search` directly.
+     */
+    getSearcher(): import("@crowi/plugin-api").SearchDriver | null;
+    getMailer(): MailService;
+    setupConfig(): Promise<any>;
+    setupMailer(): void;
+    setupLRU(): void;
+    getTokens(): Tokens;
+    start: () => Promise<http.Server>;
+    exitOnError: (err: any) => never;
+}
+export default Crowi;