nervur 0.19.2 → 0.20.1

package/src/ward/ward-being.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// The ward-being: the first being of every ward, the ward itself. Her asks
+// are the root's, shown and answered to `OWNER` alone.
+import { Being, isSilence, isWord, KIT, OWNER, told, type Answer, type Asker, type AskSpec, type BeingClass, type Blueprint, type Invitation, type JsonObject, type Stance } from '../being/index.ts';
+
+// What the ward lends its ward-being, and no other being.
+export interface Steward {
+  pk(): string;
+  classOf(name: string): BeingClass | undefined;
+  beings(): Record<string, { class: string; public: boolean; absent: boolean }>;
+  boot(key: string, className: string): Promise<'booted' | 'key taken' | 'no such class' | 'threw at birth'>;
+  unboot(key: string): boolean;
+  publish(key: string | null): boolean;
+  invite(being: string, id: string, notes: JsonObject): Promise<Invitation | null>;
+  ask(being: string | null, method: string | undefined, args: JsonObject): Promise<Answer>;
+}
+
+export type WardBeingStance = Stance & { readonly steward: Steward };
+
+// Whoever pilots a ward: the root, holding its unsealed ask, or an owner,
+// an occupant of the ward-being the root invited as one.
+export const pilots = (asker: Asker, notes: JsonObject | undefined): boolean => asker.id === OWNER || notes?.owner === true;
+
+// An ask whoever pilots the ward may make.
+export const ownerAsk = (description: string, input: JsonObject = {}): AskSpec => ({ description, input: { type: 'object', ...input }, for: pilots });
+
+// An ask the root alone may make, so a carried key pilots but never hands
+// piloting on.
+const rootAsk = (description: string, input: JsonObject = {}): AskSpec => ({ description, input: { type: 'object', ...input }, for: (asker: Asker) => asker.id === OWNER });
+// The one kit kind the root boots: every other kit class stands where the
+// kit puts it.
+export const PILOT = 'org.nervur.pilot';
+
+const text = (v: unknown): v is string => typeof v === 'string';
+const object = (v: unknown): v is JsonObject => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+export class WardBeing extends Being {
+  static override readonly kind: string = 'org.nervur.ward-being';
+  static override asks: Record<string, AskSpec> = {
+    boot: ownerAsk('a new being of this ward', { required: ['key', 'class'] }),
+    unboot: ownerAsk('a being out, with every relation she holds', { required: ['being'] }),
+    public: ownerAsk('the being a stranger reaches, or none', { required: ['key'] }),
+    invite: ownerAsk('an invitation on a being of this ward', { required: ['being', 'id'] }),
+    ask: ownerAsk('a being of this ward, asked as the owner; with no being, the public being asked as nobody'),
+    own: rootAsk('an invitation for an owner of this ward, under an id', { required: ['id'] }),
+    disown: rootAsk('an owner no more', { required: ['id'] }),
+  };
+
+  readonly steward: Steward;
+
+  constructor(stance: WardBeingStance) {
+    super(stance);
+    this.steward = stance.steward;
+  }
+
+  override describe(asker: Asker): Blueprint {
+    const { asks } = super.describe(asker);
+    return { asks, notes: pilots(asker, this.notes(asker)) ? { pk: this.steward.pk(), beings: this.steward.beings() } : {} };
+  }
+
+  async own(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.id)) return { error: 'id is text' };
+    return (await this.stance.occupants.invite(args.id, { owner: true })) ?? { error: 'id taken' };
+  }
+
+  disown(args: JsonObject): JsonObject {
+    if (!text(args.id) || this.stance.occupants.notes(args.id)?.owner !== true) return { error: 'no such owner' };
+    this.stance.occupants.remove(args.id);
+    return { disowned: args.id };
+  }
+
+  async boot(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.key) || !text(args.class)) return { error: 'key and class are text' };
+    if (args.class.startsWith(KIT) && args.class !== PILOT) return { error: 'no such class' };
+    const out = await this.steward.boot(args.key, args.class);
+    return out === 'booted' ? { booted: args.key } : { error: out };
+  }
+
+  unboot(args: JsonObject): JsonObject {
+    return text(args.being) && this.steward.unboot(args.being) ? { unbooted: args.being } : { error: 'no such being' };
+  }
+
+  public(args: JsonObject): JsonObject {
+    if (args.key !== null && !text(args.key)) return { error: 'key is text or null' };
+    return this.steward.publish(args.key) ? { public: args.key } : { error: 'no such being' };
+  }
+
+  async invite(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.being) || !text(args.id) || (args.notes !== undefined && !object(args.notes))) return { error: 'being and id are text, notes an object' };
+    const invitation = await this.steward.invite(args.being, args.id, args.notes ?? {});
+    return invitation ?? { error: 'not invited' };
+  }
+
+  async ask(args: JsonObject): Promise<JsonObject> {
+    if ((args.being !== undefined && !text(args.being)) || (args.method !== undefined && !text(args.method)) || (args.args !== undefined && !object(args.args))) {
+      return { error: 'being and method are text, args an object' };
+    }
+    const out = await this.steward.ask(args.being ?? null, args.method, args.args ?? {});
+    if (isSilence(out)) return { error: 'silence' };
+    if (isWord(out)) return { error: told(out) as string };
+    return { answer: out };
+  }
+}