@songsid/agend 2.3.1 → 2.3.2-beta.10

package/dist/office-share.d.ts

@@ -0,0 +1,258 @@
+import { createServer, type Server } from "node:http";
+import { type OfficeAct } from "./web-office-acts.js";
+import type { Office } from "./web-office-store.js";
+export declare const OFFICE_SHARE_LIMITS: {
+    /** Shares open at once, fleet-wide. */
+    readonly links: 10;
+    /** Lifetime: 1 h unless asked, 15 min to `web.office_share.max_hours` (24 at most). */
+    readonly defaultMinutes: 60;
+    readonly minMinutes: 15;
+    readonly maxHours: 24;
+    /** Per share, a sliding minute: requests, and bytes answered. */
+    readonly requestsPerMinute: 120;
+    readonly bytesPerMinute: number;
+    /** The page's static files (its code, the same for every share), all shares together. */
+    readonly staticRequestsPerMinute: 1200;
+    readonly staticBytesPerMinute: number;
+    /**
+     * #2662: a share's pack pictures (immutable, content-addressed: a browser reads each once) have their own minute, never
+     * the 120 above: `pictureLoads` times what the shown packs hold (their files and bytes, as the host lists them), so a
+     * viewer's first look at every room never reaches it, and at least the floors here.
+     */
+    readonly pictureLoads: 2;
+    readonly pictureRequestsFloor: 240;
+    readonly pictureBytesFloor: number;
+};
+/** "All offices": every stored office (and whoever is in none); otherwise a stored office's id. */
+export declare const ALL_OFFICES = "all";
+/**
+ * An office's members after the share's cut, when every one it named is out of the share: a team no chart has (a team's
+ * name has no control character), so the page finds nobody — never [], which the page reads as everyone.
+ */
+export declare const NOBODY = "team:\0";
+/** An ended (or unknown) share's page: the same words whichever it is. */
+export declare const ENDED_PAGE: string;
+export interface OfficeShare {
+    /** A short handle for lists and revoking (never the token). */
+    id: string;
+    /** ALL_OFFICES, or a stored office's id. */
+    office: string;
+    /** Agents' own lines (office_set `say`) are shown. */
+    text: boolean;
+    /** Who made it (for the list and General's announcement). */
+    owner: string;
+    /** Wall-clock ms, for display; the expiry itself runs on the monotonic clock. */
+    createdAt: number;
+    expiresAt: number;
+}
+export type OfficeShareCreate = {
+    ok: true;
+    share: OfficeShare;
+    token: string;
+} | {
+    ok: false;
+    error: "too_many" | "duration" | "office";
+};
+export declare const hashShareToken: (token: string) => string;
+/** The longest a share may live, in minutes: `web.office_share.max_hours` (whole hours, 1–24), 24 by default. */
+export declare function shareMaxMinutes(maxHours: unknown): number;
+/**
+ * The open shares. Each ends at its deadline (monotonic; a timer tells `changed` then, and find() refuses it from that
+ * moment whatever the timer did), when revoked, or when its owner is no longer allowed (endWhere). `changed` hears every
+ * change with the list as it is now — the tunnel follows it (none left: stop).
+ */
+export declare class OfficeShares {
+    private readonly deps;
+    private readonly byHash;
+    private readonly now;
+    private readonly wall;
+    constructor(deps?: {
+        /** Monotonic ms (performance.now by default). */
+        now?(): number;
+        /** Wall-clock ms (Date.now by default): only what is shown. */
+        wall?(): number;
+        changed?(shares: OfficeShare[]): void;
+        random?(n: number): Buffer;
+        setTimer?(fn: () => void, ms: number): ReturnType<typeof setTimeout> | null;
+        clearTimer?(t: ReturnType<typeof setTimeout>): void;
+    });
+    /** A new share: `minutes` from 15 to `maxMinutes`; `office` ALL_OFFICES or an id `exists` knows. */
+    create(opts: {
+        office: string;
+        minutes?: number;
+        text?: boolean;
+        owner: string;
+        maxMinutes?: number;
+        exists?(office: string): boolean;
+    }): OfficeShareCreate;
+    /** The open share a token names, or null (unknown, malformed, ended). */
+    find(token: string): OfficeShare | null;
+    /** The open shares, soonest to end first. */
+    list(): OfficeShare[];
+    /** End one share by id, or every one (ALL_OFFICES is not an id: "all" ends all). Returns how many ended. */
+    revoke(id: string): number;
+    /** End every share `test` picks (an owner no longer a fleet admin, an office deleted, the feature turned off). */
+    endWhere(test: (share: OfficeShare) => boolean): number;
+    private drop;
+    private prune;
+    private announce;
+}
+export interface OfficeShareRate {
+    requests: number;
+    bytes: number;
+}
+/** Per key (a share's id): requests and bytes in a sliding minute (monotonic, memory only). */
+export declare class OfficeShareLimiter {
+    private readonly now;
+    private readonly limits;
+    private readonly seen;
+    constructor(now?: () => number, limits?: OfficeShareRate);
+    /** A request arrives: false when the key has had its requests or bytes this minute (`limits`: this key's, #2662). */
+    admit(id: string, limits?: OfficeShareRate): boolean;
+    /**
+     * #2662: whole seconds (1–60) until admit() would let the key in again — when enough of this minute's requests, and of
+     * its bytes, have left it. For Retry-After.
+     */
+    retryAfter(id: string, limits?: OfficeShareRate): number;
+    /** What the admitted request answered, in bytes. */
+    sent(id: string, bytes: number): void;
+    forget(id: string): void;
+    private window;
+}
+/** Where a share's picture is read from: the fleet's own reads, as they are now. */
+export interface OfficeShareSource {
+    /** The status frame (getUiStatus): its `instances`. */
+    status(): unknown;
+    /** The org chart (orgChart): `general` and `teams`. */
+    org(): {
+        general?: unknown;
+        teams?: unknown;
+    };
+    /** The stored offices (web-office-store.ts list()). */
+    offices(): {
+        rev: number;
+        offices: Office[];
+    };
+    /** The live acts (OfficeActs live()). */
+    acts(): OfficeAct[];
+    /** /ui/traffic's snapshot. */
+    traffic(): {
+        now: string;
+        items: unknown[];
+        delegations?: unknown[];
+    };
+    /** The instances "Needs you" names now (one entry per item). */
+    needs(): string[];
+    /** cross_instance_visibility "hidden" now. */
+    hidden(name: string): boolean;
+    /** The skin packs the host keeps (web-office-skins.ts). */
+    skins?: {
+        list(): {
+            packs: Array<{
+                id: string;
+                files?: number;
+                bytes?: number;
+            }>;
+        } & Record<string, unknown>;
+        get(id: string): unknown;
+        picture(id: string, sha: string): Buffer | null;
+    };
+}
+/**
+ * One share's picture, read once from `src`: who is in it (`scope`), and each read the page makes, cut to them.
+ * `offices`: the shared office, or every stored office; `null` when the shared office is gone (the share then shows
+ * nothing and its owner is told it ended).
+ */
+export declare class OfficeShareView {
+    private readonly share;
+    private readonly src;
+    readonly offices: Office[] | null;
+    readonly scope: ReadonlySet<string>;
+    private readonly people;
+    /** fleet.yaml's teams with someone shown, each with only its shown members. */
+    private readonly teams;
+    constructor(share: Pick<OfficeShare, "office" | "text"> & Partial<Pick<OfficeShare, "expiresAt">>, src: OfficeShareSource);
+    /** The status frame as the page's app store takes it, and the chart's structure (no descriptions, threads or info). */
+    state(): Record<string, unknown>;
+    /**
+     * /ui/offices's answer, the shared office (or all) only, each cut to the share (#2637 review): its members only those
+     * shown (an instance, or a team with someone shown; NOBODY when none is), and a seat kept for someone not shown keeps
+     * its place but not the name. The stored offices are never changed.
+     */
+    officeList(): {
+        rev: number;
+        offices: Office[];
+        readable: boolean;
+    };
+    /** /ui/office-acts's answer: the acts of the people shown, in a shown office, without their line unless shared. */
+    acts(): {
+        acts: OfficeAct[];
+        now: number;
+    };
+    /**
+     * A pack's answer as this share gets it (#2637 review): its manifest's instance names cut to the share — `byInstance`
+     * only for people shown, a furniture item's `activeFor` only them (none left: [], which watches nobody, never the
+     * missing key, which watches everyone). #2662: and only the character sets someone shown wears (theirs in `byInstance`,
+     * and `default` for everyone else), with `files` only the pictures it still names: the page loads what is drawn, not
+     * every set of a fleet-sized pack. A copy: the kept pack is never changed.
+     */
+    pack(answer: unknown): unknown;
+    /** The packs the shown offices are drawn in (a pack no shown office names is not offered). */
+    skinIds(): Set<string>;
+}
+/**
+ * #2662: a share's minute of pack pictures — OFFICE_SHARE_LIMITS.pictureLoads times the files and bytes of the packs its
+ * offices are drawn in (the host's own count of each), at least the floors. Read from the stored offices and the pack
+ * list only (cheap: it is asked before a picture is admitted).
+ */
+export declare function sharePictureRate(share: Pick<OfficeShare, "office">, offices: Office[], packs: Array<{
+    id: string;
+    files?: number;
+    bytes?: number;
+}>): OfficeShareRate;
+export interface OfficeShareGateway {
+    readonly server: Server;
+    readonly readinessMarker: string;
+    listen(): Promise<URL>;
+    setHost(host: string | null): void;
+    close(): void;
+}
+/**
+ * The share tunnel's gateway. GET and HEAD only, on this tunnel's own Host; `/ready` for the tunnel's probe; then
+ * `/o/<token>` and its reads, for an open share within its limits:
+ *
+ *   /o/<t>                                  the page (`page`; 404 while there is none)
+ *   /o/<t>/state                            OfficeShareView.state()
+ *   /o/<t>/offices                          OfficeShareView.officeList()
+ *   /o/<t>/office-acts                      OfficeShareView.acts()
+ *   /o/<t>/office-skins                     the packs the shown offices use
+ *   /o/<t>/office-skins/<id>                one of them, its instance names cut to the share (never cached)
+ *   /o/<t>/office-skins/<id>/img/<sha>.png  its picture (immutable)
+ *
+ * and, with no token, the page's static files at the dashboard's own paths (`statics`: `/assets/<name>`, `/ui/js/<name>`;
+ * office-share-page.ts names them), limited together (OFFICE_SHARE_LIMITS.static*).
+ *
+ * Anything else, an unknown or ended token, an office since deleted: an empty 404 (no word on why: a stranger learns
+ * nothing). Over the limit: 429. The share is asked again before each answer is sent. No cookie is read or set and
+ * nothing is logged per request.
+ */
+export declare function createOfficeShareGateway(opts: {
+    shares: Pick<OfficeShares, "find">;
+    source: OfficeShareSource;
+    limiter?: OfficeShareLimiter;
+    /** The page for a share (HTML), or null while there is none. */
+    page?(share: OfficeShare, token: string): {
+        body: string;
+        csp: string;
+    } | null;
+    /** A static file of the page by its path (`/assets/…`, `/ui/js/…`), or null. */
+    statics?(path: string): {
+        body: Buffer;
+        type: string;
+    } | null;
+    staticLimiter?: OfficeShareLimiter;
+    /** #2662: the shares' pack pictures, each share's minute sized by its packs (sharePictureRate). */
+    pictureLimiter?: OfficeShareLimiter;
+    create?: typeof createServer;
+    marker?: string;
+}): OfficeShareGateway;