@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/loki-logging/loki-destination.d.ts

@@ -1,99 +1,125 @@
-import { ILogDestination, LogEntry, LogFilter, LogLevel } from '@camstack/types';
+/**
+* Grafana Loki log destination — batches entries and pushes them to Loki's
+* `POST /loki/api/v1/push`. Payload construction and the label policy live in the
+* pure `loki-payload.ts`; this file owns the batching, the transport and the
+* failure behaviour.
+*
+* ## It must never log
+*
+* This is the constraint that shapes everything else. A `log-destination` that
+* emits a log line feeds itself: one entry → a push → the push logs something →
+* another entry → another push. The `hub-forwarder` builtin carries the same
+* warning in its manifest for the same reason.
+*
+* So this class NEVER calls `ctx.logger`, and it does not throw out of `write()`
+* either — `LogManager` fans one entry to every destination, so throwing here
+* would break the other sinks. Errors are counted and exposed through
+* `getStatus()` for the Admin UI to render. Diagnosing a broken Loki
+* configuration is a UI affordance, deliberately, because it cannot be a log line.
+*
+* ## Backpressure
+*
+* If Loki is down, entries accumulate. A logger that OOMs the process it is
+* observing is worse than a logger that loses lines, so the queue is bounded at
+* `MAX_QUEUE` and drops OLDEST-first when full (a burst during an incident is
+* exactly when the newest lines matter most). Drops are counted and surfaced.
+*/
+import type { ILogDestination, LogEntry, LogFilter, LogLevel } from "@camstack/types";
 export interface LokiConfig {
-    readonly enabled: boolean;
-    /** Base URL of the Loki instance, e.g. `http://loki:3100`. */
-    readonly url: string;
-    readonly job: string;
-    readonly node: string;
-    readonly level: LogLevel;
-    /** Flush period in ms. */
-    readonly batchIntervalMs: number;
-    /** Flush early once this many entries are queued. */
-    readonly batchSize: number;
-    /** `key=value,key2=value2` static labels. Must stay low-cardinality. */
-    readonly extraLabels: string;
-    /** Grafana Cloud / multi-tenant Loki: sent as `X-Scope-OrgID`. */
-    readonly tenantId: string;
-    /** Optional HTTP basic auth. */
-    readonly username: string;
-    readonly password: string;
-    readonly timeoutMs: number;
+	readonly enabled: boolean;
+	/** Base URL of the Loki instance, e.g. `http://loki:3100`. */
+	readonly url: string;
+	readonly job: string;
+	readonly node: string;
+	readonly level: LogLevel;
+	/** Flush period in ms. */
+	readonly batchIntervalMs: number;
+	/** Flush early once this many entries are queued. */
+	readonly batchSize: number;
+	/** `key=value,key2=value2` static labels. Must stay low-cardinality. */
+	readonly extraLabels: string;
+	/** Grafana Cloud / multi-tenant Loki: sent as `X-Scope-OrgID`. */
+	readonly tenantId: string;
+	/** Optional HTTP basic auth. */
+	readonly username: string;
+	readonly password: string;
+	readonly timeoutMs: number;
 }
 export interface LokiStatus {
-    readonly enabled: boolean;
-    readonly configured: boolean;
-    readonly queued: number;
-    readonly pushed: number;
-    readonly dropped: number;
-    readonly failures: number;
-    readonly lastError: string | null;
-    readonly lastPushAtMs: number | null;
+	readonly enabled: boolean;
+	readonly configured: boolean;
+	readonly queued: number;
+	readonly pushed: number;
+	readonly dropped: number;
+	readonly failures: number;
+	readonly lastError: string | null;
+	readonly lastPushAtMs: number | null;
 }
 /** Injected in tests. Matches the shape of global `fetch` that is actually used. */
 export type LokiFetch = (url: string, init: {
-    readonly method: string;
-    readonly headers: Readonly<Record<string, string>>;
-    readonly body: string;
-    readonly signal?: AbortSignal;
+	readonly method: string;
+	readonly headers: Readonly<Record<string, string>>;
+	readonly body: string;
+	readonly signal?: AbortSignal;
 }) => Promise<{
-    readonly ok: boolean;
-    readonly status: number;
-    text(): Promise<string>;
+	readonly ok: boolean;
+	readonly status: number;
+	text(): Promise<string>;
 }>;
 export interface LokiDestinationDeps {
-    readonly fetchFn?: LokiFetch;
-    readonly setIntervalFn?: typeof setInterval;
-    readonly clearIntervalFn?: typeof clearInterval;
+	readonly fetchFn?: LokiFetch;
+	readonly setIntervalFn?: typeof setInterval;
+	readonly clearIntervalFn?: typeof clearInterval;
 }
 export declare class LokiDestination implements ILogDestination {
-    private config;
-    private queue;
-    private timer;
-    private flushing;
-    private pushed;
-    private dropped;
-    private failures;
-    private lastError;
-    private lastPushAtMs;
-    private readonly fetchFn;
-    private readonly setIntervalFn;
-    private readonly clearIntervalFn;
-    constructor(deps?: LokiDestinationDeps);
-    initialize(config?: LokiConfig): Promise<void>;
-    /**
-     * Re-apply configuration to an already-initialized destination after a
-     * settings change, without dropping the queued tail. Stops the current flush
-     * timer, swaps the config in, and starts a fresh timer only when the new
-     * config is active. This is what makes the addon's "enable without a restart"
-     * contract real: `initialize()` starts a timer, so calling it twice would leak
-     * the first one — `reconfigure()` clears it first.
-     */
-    reconfigure(config: LokiConfig): Promise<void>;
-    private stopTimer;
-    private startTimerIfActive;
-    /** Enabled AND pointed somewhere. An enabled destination with no URL is inert. */
-    private isActive;
-    write(entry: LogEntry): void;
-    /**
-     * Push whatever is queued. Never throws and never logs.
-     *
-     * On failure the batch is put BACK at the front of the queue so a transient
-     * Loki outage does not lose lines; `MAX_QUEUE` is what stops that from growing
-     * without bound.
-     */
-    flush(): Promise<void>;
-    private push;
-    getStatus(): LokiStatus;
-    /**
-     * One-shot reachability probe for the Admin UI's "Test connection" button.
-     * Pushes a single synthetic entry, which validates the URL, the auth, the
-     * tenant header AND the label policy in one go — a bare GET would validate
-     * none of them.
-     */
-    testConnection(config: LokiConfig): Promise<{
-        ok: boolean;
-        error: string | null;
-    }>;
-    query(_filter: LogFilter): Promise<readonly LogEntry[]>;
-    shutdown(): Promise<void>;
+	private config;
+	private queue;
+	private timer;
+	private flushing;
+	private pushed;
+	private dropped;
+	private failures;
+	private lastError;
+	private lastPushAtMs;
+	private readonly fetchFn;
+	private readonly setIntervalFn;
+	private readonly clearIntervalFn;
+	constructor(deps?: LokiDestinationDeps);
+	initialize(config?: LokiConfig): Promise<void>;
+	/**
+	* Re-apply configuration to an already-initialized destination after a
+	* settings change, without dropping the queued tail. Stops the current flush
+	* timer, swaps the config in, and starts a fresh timer only when the new
+	* config is active. This is what makes the addon's "enable without a restart"
+	* contract real: `initialize()` starts a timer, so calling it twice would leak
+	* the first one — `reconfigure()` clears it first.
+	*/
+	reconfigure(config: LokiConfig): Promise<void>;
+	private stopTimer;
+	private startTimerIfActive;
+	/** Enabled AND pointed somewhere. An enabled destination with no URL is inert. */
+	private isActive;
+	write(entry: LogEntry): void;
+	/**
+	* Push whatever is queued. Never throws and never logs.
+	*
+	* On failure the batch is put BACK at the front of the queue so a transient
+	* Loki outage does not lose lines; `MAX_QUEUE` is what stops that from growing
+	* without bound.
+	*/
+	flush(): Promise<void>;
+	private push;
+	getStatus(): LokiStatus;
+	/**
+	* One-shot reachability probe for the Admin UI's "Test connection" button.
+	* Pushes a single synthetic entry, which validates the URL, the auth, the
+	* tenant header AND the label policy in one go — a bare GET would validate
+	* none of them.
+	*/
+	testConnection(config: LokiConfig): Promise<{
+		ok: boolean;
+		error: string | null;
+	}>;
+	query(_filter: LogFilter): Promise<readonly LogEntry[]>;
+	shutdown(): Promise<void>;
 }

package/dist/builtins/loki-logging/loki-logging.addon.d.ts

@@ -1,47 +1,66 @@
-import { LogLevel, ProviderRegistration, BaseAddon } from '@camstack/types';
-import { LokiDestination } from './loki-destination.js';
+/**
+* Loki logging addon — ships this node's log entries to a Grafana Loki instance.
+*
+* OPT-IN. It is a builtin so it is always available, but it does nothing until an
+* operator supplies a URL: `url` defaults to empty and `LokiDestination` treats
+* that as inert. Whether it is used at all is the per-destination
+* `log-destination` capability toggle — the ONE enable (D777); the old private
+* `enabled` setting is retired by `retire-enabled-flag.ts`. The provider is
+* registered either way, so the Logging page can show it and the operator can
+* turn it on without a restart of anything else.
+*
+* Sits at the same level as `winston-logging` (rotated files), `console-logging`
+* (stdout) and `hub-forwarder` (agent → hub): all four are `log-destination`
+* collection providers, `LogManager` fans every entry to all of them, and each is
+* independently configurable. Enabling this one does not disable any other.
+*
+* Why Loki's push API rather than Promtail: see the docblock in `loki-payload.ts`.
+*/
+import type { ConfigUISchema, LogLevel, ProviderRegistration } from "@camstack/types";
+import { BaseAddon } from "@camstack/types";
+import { LokiDestination } from "./loki-destination.js";
 interface LokiAddonConfig {
-    readonly url: string;
-    readonly job: string;
-    readonly level: LogLevel;
-    readonly batchIntervalMs: number;
-    readonly batchSize: number;
-    readonly extraLabels: string;
-    readonly tenantId: string;
-    readonly username: string;
-    readonly password: string;
-    readonly timeoutMs: number;
+	readonly url: string;
+	readonly job: string;
+	readonly level: LogLevel;
+	readonly batchIntervalMs: number;
+	readonly batchSize: number;
+	readonly extraLabels: string;
+	readonly tenantId: string;
+	readonly username: string;
+	readonly password: string;
+	readonly timeoutMs: number;
 }
 export declare class LokiLoggingAddon extends BaseAddon<LokiAddonConfig> {
-    private destination;
-    private retirementTimer;
-    private shuttingDown;
-    constructor();
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    /** One attempt of the D777 carry-over; reschedules itself while deferred. */
-    private attemptEnabledFlagRetirement;
-    protected onShutdown(): Promise<void>;
-    /**
-     * React to a settings change (URL, level, batching) without a
-     * restart — the contract this addon advertises. `BaseAddon` has already
-     * reloaded `this.config` by the time this runs; re-apply it to the live
-     * destination so setting or clearing the URL actually starts (or stops)
-     * pushing. Without this the destination keeps its boot-time config forever.
-     */
-    protected onConfigChanged(): Promise<void>;
-    /**
-     * `node` is a Loki LABEL, so it must be the node's real identity and must not
-     * be operator-editable — a typo would fork the stream and split a node's history
-     * in two. `kernel.localNodeId` is the Moleculer node id (`'hub'` on the hub, the
-     * agent's own name elsewhere), which is exactly the bounded value wanted here.
-     *
-     * NOT named `resolveConfig`: `BaseAddon` already has a protected
-     * `resolveConfig()` that reloads persisted settings, and shadowing it with a
-     * different signature is a type error — usefully, since silently overriding it
-     * would have broken this addon's settings reload.
-     */
-    private destinationConfig;
-    getDestination(): LokiDestination;
-    protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;
+	private destination;
+	private retirementTimer;
+	private shuttingDown;
+	constructor();
+	protected onInitialize(): Promise<ProviderRegistration[]>;
+	/** One attempt of the D777 carry-over; reschedules itself while deferred. */
+	private attemptEnabledFlagRetirement;
+	protected onShutdown(): Promise<void>;
+	/**
+	* React to a settings change (URL, level, batching) without a
+	* restart — the contract this addon advertises. `BaseAddon` has already
+	* reloaded `this.config` by the time this runs; re-apply it to the live
+	* destination so setting or clearing the URL actually starts (or stops)
+	* pushing. Without this the destination keeps its boot-time config forever.
+	*/
+	protected onConfigChanged(): Promise<void>;
+	/**
+	* `node` is a Loki LABEL, so it must be the node's real identity and must not
+	* be operator-editable — a typo would fork the stream and split a node's history
+	* in two. `kernel.localNodeId` is the Moleculer node id (`'hub'` on the hub, the
+	* agent's own name elsewhere), which is exactly the bounded value wanted here.
+	*
+	* NOT named `resolveConfig`: `BaseAddon` already has a protected
+	* `resolveConfig()` that reloads persisted settings, and shadowing it with a
+	* different signature is a type error — usefully, since silently overriding it
+	* would have broken this addon's settings reload.
+	*/
+	private destinationConfig;
+	getDestination(): LokiDestination;
+	protected globalSettingsSchema(): ConfigUISchema;
 }
 export {};

package/dist/builtins/loki-logging/loki-payload.d.ts

@@ -1,57 +1,100 @@
-import { LogEntry } from '@camstack/types';
+/**
+* Pure Loki push-payload construction. No I/O, no timers — so the label policy
+* and the ordering rules below are testable without a Loki instance.
+*
+* ## Why Loki and not Promtail
+*
+* Promtail is a file *tailer*: it watches log files on disk and ships what it
+* reads to Loki. CamStack already has every entry in memory, in structured form,
+* at the moment it is emitted — writing it to disk purely so a sidecar can parse
+* it back out loses the structure and adds a process. Loki's own ingestion API
+* (`POST /loki/api/v1/push`) takes the structured form directly.
+*
+* Promtail is also end-of-life: Grafana deprecated it in favour of Alloy in 2025.
+* Building against a deprecated shipper to reach an API we can call ourselves
+* would be strange. If someone does run Promtail or Alloy, the rotated files
+* from the `winston-logging` destination are still there to tail — the two
+* destinations are independent.
+*
+* ## The label policy, which matters more than it looks
+*
+* Loki indexes labels, and every distinct label-value combination is a separate
+* *stream* with its own index entry and its own chunks. High-cardinality labels
+* are the documented way to make a Loki cluster fall over.
+*
+* So `scope`, `message`, `deviceId`, `sessionId` and everything else per-entry
+* stay OUT of the labels and go in the line body as JSON. Labels are only the
+* handful of values with a small, bounded set:
+*
+*   job    a fixed string, operator-configured (default `camstack`)
+*   node   the ORIGIN node's id — the agent that EMITTED the entry, not the
+*          node running this destination. The hub is the single Loki egress
+*          for the whole cluster (agents forward their logs to it via the
+*          `hub-forwarder`), so labelling every pushed line with the hub's own
+*          id would collapse the entire fleet onto `node="hub"` and lose the
+*          source. Each entry carries its origin in `tags.agentId` (`'hub'` for
+*          hub-local entries, the agent id for forwarded ones — always the root
+*          node, never a child process), which is bounded by cluster size. The
+*          destination's configured node is only the fallback for an entry with
+*          no `agentId` tag.
+*   level  one of four
+*
+* That is at most `4 × nodes` streams, which is what Loki is built for.
+*/
+import type { LogEntry } from "@camstack/types";
 /** One `[unixNano, line]` pair, exactly as Loki's push API expects. */
 export type LokiValue = readonly [string, string];
 export interface LokiStream {
-    readonly stream: Readonly<Record<string, string>>;
-    readonly values: readonly LokiValue[];
+	readonly stream: Readonly<Record<string, string>>;
+	readonly values: readonly LokiValue[];
 }
 export interface LokiPushBody {
-    readonly streams: readonly LokiStream[];
+	readonly streams: readonly LokiStream[];
 }
 export interface LokiLabelInput {
-    /** Fixed `job` label. Bounded by configuration, never per-entry. */
-    readonly job: string;
-    /**
-     * Fallback node id for entries that carry no `tags.agentId` origin — the
-     * id of the node running this destination. The per-entry origin
-     * (`tags.agentId`) is preferred so forwarded agent logs are attributed to
-     * their source node rather than the hub that ships them.
-     */
-    readonly node: string;
-    /** Extra static labels from configuration. Values must be low-cardinality. */
-    readonly extra?: Readonly<Record<string, string>>;
+	/** Fixed `job` label. Bounded by configuration, never per-entry. */
+	readonly job: string;
+	/**
+	* Fallback node id for entries that carry no `tags.agentId` origin — the
+	* id of the node running this destination. The per-entry origin
+	* (`tags.agentId`) is preferred so forwarded agent logs are attributed to
+	* their source node rather than the hub that ships them.
+	*/
+	readonly node: string;
+	/** Extra static labels from configuration. Values must be low-cardinality. */
+	readonly extra?: Readonly<Record<string, string>>;
 }
 /**
- * Loki rejects a label name that is not a valid Prometheus label
- * (`[a-zA-Z_][a-zA-Z0-9_]*`), so operator-supplied keys are sanitised rather
- * than passed through — a 400 from the push endpoint on every batch is a much
- * worse outcome than a renamed label.
- */
+* Loki rejects a label name that is not a valid Prometheus label
+* (`[a-zA-Z_][a-zA-Z0-9_]*`), so operator-supplied keys are sanitised rather
+* than passed through — a 400 from the push endpoint on every batch is a much
+* worse outcome than a renamed label.
+*/
 export declare function sanitizeLabelName(raw: string): string;
 /** Parse an operator's `key=value,key2=value2` label string. */
 export declare function parseExtraLabels(raw: string): Readonly<Record<string, string>>;
 /** `Date` → Loki's nanosecond-precision string timestamp. */
 export declare function toUnixNano(timestamp: Date | string | number): string;
 /**
- * The line body: JSON carrying everything that must NOT be a label. Loki can
- * parse this with `| json` at query time, so `scope` and `tags.deviceId` stay
- * filterable without ever being indexed.
- */
+* The line body: JSON carrying everything that must NOT be a label. Loki can
+* parse this with `| json` at query time, so `scope` and `tags.deviceId` stay
+* filterable without ever being indexed.
+*/
 export declare function formatLokiLine(entry: LogEntry): string;
 /**
- * Group a batch into one stream per distinct label set, and sort each stream's
- * values by timestamp.
- *
- * The `node` label is resolved PER ENTRY from `tags.agentId` (the emitting
- * agent, falling back to `labels.node` when absent), so a batch that mixes
- * hub-local lines with forwarded agent lines fans out into one stream per
- * origin node — the whole point of shipping the cluster's logs through the hub
- * without flattening every line onto `node="hub"`.
- *
- * The sort is not cosmetic. Loki historically rejected a stream whose entries
- * were not in ascending time order, and even with out-of-order ingestion enabled
- * it is bounded by a window. Entries reach a destination from several concurrent
- * producers, so a batch is NOT naturally ordered — without this, some pushes
- * fail with `entry out of order` and those log lines are simply gone.
- */
+* Group a batch into one stream per distinct label set, and sort each stream's
+* values by timestamp.
+*
+* The `node` label is resolved PER ENTRY from `tags.agentId` (the emitting
+* agent, falling back to `labels.node` when absent), so a batch that mixes
+* hub-local lines with forwarded agent lines fans out into one stream per
+* origin node — the whole point of shipping the cluster's logs through the hub
+* without flattening every line onto `node="hub"`.
+*
+* The sort is not cosmetic. Loki historically rejected a stream whose entries
+* were not in ascending time order, and even with out-of-order ingestion enabled
+* it is bounded by a window. Entries reach a destination from several concurrent
+* producers, so a batch is NOT naturally ordered — without this, some pushes
+* fail with `entry out of order` and those log lines are simply gone.
+*/
 export declare function buildPushBody(entries: readonly LogEntry[], labels: LokiLabelInput): LokiPushBody | null;

package/dist/builtins/loki-logging/retire-enabled-flag.d.ts

@@ -1,23 +1,48 @@
-import { StoredKeyRead } from '@camstack/types';
+/**
+* ONE-SHOT retirement of Loki's private `enabled` setting (2026-07-30, D777).
+*
+* The per-destination `log-destination` capability toggle is the only enable.
+* A stored `enabled: false` is carried over to it ONCE, so an operator who had
+* Loki off does not silently start shipping logs to a host they may no longer
+* control:
+*
+*  - flag stored `false`            → the provider is disabled at the capability;
+*  - flag stored `true`, or never
+*    written                        → the capability is left as it is.
+*
+* Then the dead key is stripped and the marker is written in the SAME store
+* write, so the carry-over never repeats — an operator who re-enables Loki
+* afterwards is never switched off again.
+*
+* Anything that cannot be confirmed (unreadable store, refused toggle — the
+* provider is not registered yet while the addon initializes — or a write that
+* silently did not land) returns `deferred` and writes nothing; the caller
+* retries in the background.
+*
+* Same shape as the (since removed) magic-link addon's carry-over in
+* addon-auth; the one difference is the default the flag had (OFF there, ON
+* here).
+*/
+import type { StoredKeyRead } from "@camstack/types";
 /** The retired settings key. */
 export declare const RETIRED_ENABLED_KEY = "enabled";
 /** Store key marking the retirement as done. Not a schema field. Pre-D777 name kept. */
 export declare const RETIREMENT_MARKER_KEY = "migratedEnabled";
 export type RetirementOutcome = {
-    readonly kind: 'already-retired';
+	readonly kind: "already-retired";
 } | {
-    readonly kind: 'retired';
-    readonly capDisabled: boolean;
+	readonly kind: "retired";
+	readonly capDisabled: boolean;
 } | {
-    readonly kind: 'deferred';
-    readonly reason: string;
+	readonly kind: "deferred";
+	readonly reason: string;
 };
 export interface RetireEnabledFlagDeps {
-    /** Three-way read of one key of the addon's own store. */
-    readStoredKey(key: string): Promise<StoredKeyRead>;
-    /** Disable this addon at the `log-destination` toggle. Throws when refused. */
-    disableAtCapability(): Promise<void>;
-    /** ONE store write: strip {@link RETIRED_ENABLED_KEY} and set {@link RETIREMENT_MARKER_KEY}. */
-    commit(): Promise<void>;
+	/** Three-way read of one key of the addon's own store. */
+	readStoredKey(key: string): Promise<StoredKeyRead>;
+	/** Disable this addon at the `log-destination` toggle. Throws when refused. */
+	disableAtCapability(): Promise<void>;
+	/** ONE store write: strip {@link RETIRED_ENABLED_KEY} and set {@link RETIREMENT_MARKER_KEY}. */
+	commit(): Promise<void>;
 }
 export declare function retireEnabledFlag(deps: RetireEnabledFlagDeps): Promise<RetirementOutcome>;