signalk-server/dist/deltaPriority.d.ts

An implementation of a [Signal K](http://signalk.org) server for boats.

import { SourceRef } from '@signalk/server-api';
interface SourcePriority {
    sourceRef: SourceRef;
    timeout: number;
}
export interface SourcePrioritiesData {
    [path: string]: SourcePriority[];
}
export interface PriorityGroupConfig {
    id: string;
    sources: string[];
    inactive?: boolean;
}
export interface PriorityResolutionConfig {
    groups?: PriorityGroupConfig[];
    overrides?: SourcePrioritiesData;
    fallbackMs?: number;
    unknownSourceTimeout?: number;
    canonicalise?: CanonicaliseSourceRef;
    /**
     * Optional initial state for the per-path "publishers seen" map and
     * the per-path "claimed-by-group" map. Used at engine init to
     * recover the routing state across server restarts: walking the
     * already-loaded delta cache surfaces every publisher that has
     * historically emitted each path, which lets routesPath flip on
     * immediately for paths that already have ≥2 publishers — instead
     * of the admin UI flashing a "no priority configured" warning for
     * a few seconds while the engine waits for live deltas to arrive.
     * Each ref must already be in canonical (canName) form; the engine
     * does not re-canonicalise the seed.
     */
    seenPublishersByPath?: Record<string, string[]>;
    /**
     * Source identities to drop from the candidate set entirely.
     * Keys are sourceRefIdentity() outputs (the CAN Name when present,
     * otherwise the raw sourceRef) — the caller pre-canonicalises so the
     * per-delta path doesn't pay for the lookup. A delta whose source
     * matches an excluded identity is filtered out before any precedence
     * check runs and leaves no trace in pathSeenPublishers /
     * pathToGroupId; the engine behaves as if the source never emitted.
     * Used by per-subscription engines to let a derived-data plugin
     * apply the user's source ranking to upstream sources without seeing
     * its own output in the cascade.
     */
    excludeIdentities?: Set<string>;
}
/**
 * Sentinel sourceRef that turns a path-level override into a
 * "fan out" rule: every source's value is delivered unchanged for that
 * path, regardless of ranking. Stored in priorities.json as a single
 * entry of the form `[{ sourceRef: '*', timeout: 0 }]` so older code
 * paths see a sourceRef that doesn't match any real device and fall
 * through their existing "no match" branches without crashing.
 */
export declare const FANOUT_SOURCEREF = "*";
export declare function isFanOutPriorities(entries: SourcePriority[] | undefined): boolean;
/**
 * An override is dormant when every one of its ranked sources belongs
 * to a group that the user has marked inactive. The principle: an
 * override only filters if at least one of its sources can win, and a
 * source from an inactive group is treated as ineligible. Sources that
 * belong to no group, or to an active one, keep the override alive.
 *
 * Used by both the server engine (to bypass dormant overrides during
 * delta routing) and by the admin-UI (to render dormant overrides as
 * visually disabled and exclude them from the attention-count badge),
 * so the truth derived from `(overrides, groups)` stays consistent on
 * both sides without an explicit flag being pushed across the wire.
 *
 * The fan-out sentinel never goes dormant — it has no real source to
 * map onto a group.
 */
export declare function isOverrideDormantUnderGroups(override: SourcePriority[] | undefined, groups: PriorityGroupConfig[] | undefined): boolean;
/**
 * Device identity for transport-agnostic matching. Returns the CAN Name
 * if the sourceRef encodes one; otherwise the sourceRef itself is
 * returned so exact-match semantics are preserved for non-N2K sources.
 */
export declare function sourceRefIdentity(sourceRef: string): string;
export type ToPreferredDelta = ((delta: any, now: Date, selfContext: string) => any) & {
    /**
     * Returns true when the engine actively filters this (path, sourceRef)
     * tuple — i.e. there is a non-dormant path-level override OR the
     * source belongs to an active group. Used by the deltacache to gate
     * `preferredSources` writes: a path the engine doesn't route should
     * not produce a "live preferred winner" entry, otherwise the admin-UI
     * Data Browser's Priority-filtered view would suppress the other
     * sources on a path that's actually pass-through.
     */
    routesPath: (path: string, sourceRef: string) => boolean;
};
/**
 * Translate a raw `$source` (e.g. `can0.4`) into its canonical form
 * (e.g. `can0.c0788c00e7e04312`) so the engine can match it against
 * priorities saved in canName form. Implementations should return the
 * raw ref unchanged when no translation is known — that lets the
 * engine fall through to the existing "unknown source" rules and
 * keeps non-canName setups (legacy node-red flows) working as before.
 */
export type CanonicaliseSourceRef = (sourceRef: string) => string;
export declare const getToPreferredDelta: (config?: PriorityResolutionConfig) => ToPreferredDelta;
export {};
//# sourceMappingURL=deltaPriority.d.ts.map