@graffiti-garden/implementation-local 0.2.0

package/src/session-manager.ts

@@ -0,0 +1,122 @@
+import type {
+  Graffiti,
+  GraffitiLoginEvent,
+  GraffitiLogoutEvent,
+  GraffitiSessionInitializedEvent,
+} from "@graffiti-garden/api";
+
+/**
+ * A class that implements the login methods
+ * of the [Graffiti API]() for use in the browser.
+ * It is completely insecure and should only be used
+ * for testing and demonstrations.
+ *
+ * It uses `localStorage` to store login state and
+ * window prompts rather than an oauth flow for log in.
+ * It can be used in node.js but will not persist
+ * login state and a proposed username must be provided.
+ */
+export class GraffitiLocalSessionManager {
+  sessionEvents: Graffiti["sessionEvents"] = new EventTarget();
+
+  constructor() {
+    // Look for any existing sessions
+    const sessionRestorer = async () => {
+      // Allow listeners to be added first
+      await Promise.resolve();
+
+      // Restore previous sessions
+      for (const actor of this.getLoggedInActors()) {
+        const event: GraffitiLoginEvent = new CustomEvent("login", {
+          detail: { session: { actor } },
+        });
+        this.sessionEvents.dispatchEvent(event);
+      }
+
+      const event: GraffitiSessionInitializedEvent = new CustomEvent(
+        "initialized",
+      );
+      this.sessionEvents.dispatchEvent(event);
+    };
+    sessionRestorer();
+  }
+
+  loggedInActors: string[] = [];
+
+  protected getLoggedInActors(): string[] {
+    if (typeof window !== "undefined") {
+      const actorsString = window.localStorage.getItem("graffiti-actor");
+      return actorsString
+        ? actorsString.split(",").map(decodeURIComponent)
+        : [];
+    } else {
+      return this.loggedInActors;
+    }
+  }
+
+  protected setLoggedInActors(actors: string[]) {
+    if (typeof window !== "undefined") {
+      window.localStorage.setItem(
+        "graffiti-actor",
+        actors.map(encodeURIComponent).join(","),
+      );
+    } else {
+      this.loggedInActors = actors;
+    }
+  }
+
+  login: Graffiti["login"] = async (proposal) => {
+    let actor = proposal?.actor;
+    if (!actor && typeof window !== "undefined") {
+      const response = window.prompt(
+        `This is an insecure implementation of the Graffiti API \
+  for *demo purposes only*. Do not store any sensitive information \
+  here.\
+  \n\n\
+  Simply choose a username to log in.`,
+      );
+      if (response) actor = response;
+    }
+
+    let detail: GraffitiLoginEvent["detail"];
+    if (!actor) {
+      detail = {
+        error: new Error("No actor ID provided to login"),
+      };
+    } else {
+      const existingActors = this.getLoggedInActors();
+      if (!existingActors.includes(actor)) {
+        this.setLoggedInActors([...existingActors, actor]);
+      }
+
+      detail = {
+        session: { actor },
+      };
+    }
+
+    const event: GraffitiLoginEvent = new CustomEvent("login", { detail });
+    this.sessionEvents.dispatchEvent(event);
+  };
+
+  logout: Graffiti["logout"] = async (session) => {
+    const existingActors = this.getLoggedInActors();
+    const exists = existingActors.includes(session.actor);
+    if (exists) {
+      this.setLoggedInActors(
+        existingActors.filter((actor) => actor !== session.actor),
+      );
+    }
+
+    const detail: GraffitiLogoutEvent["detail"] = exists
+      ? {
+          actor: session.actor,
+        }
+      : {
+          actor: session.actor,
+          error: new Error("Not logged in with that actor"),
+        };
+
+    const event: GraffitiLogoutEvent = new CustomEvent("logout", { detail });
+    this.sessionEvents.dispatchEvent(event);
+  };
+}

package/src/synchronize.ts

@@ -0,0 +1,154 @@
+import Ajv from "ajv-draft-04";
+import type { Graffiti } from "@graffiti-garden/api";
+import type { GraffitiObjectBase } from "@graffiti-garden/api";
+import { Repeater } from "@repeaterjs/repeater";
+import { applyPatch } from "fast-json-patch";
+import {
+  applyGraffitiPatch,
+  attemptAjvCompile,
+  isActorAllowedGraffitiObject,
+  maskGraffitiObject,
+} from "./utilities";
+
+type SynchronizeEvent = CustomEvent<{
+  oldObject: GraffitiObjectBase;
+  newObject?: GraffitiObjectBase;
+}>;
+
+type GraffitiDatabaseMethods = Pick<
+  Graffiti,
+  "get" | "put" | "patch" | "delete" | "discover"
+>;
+
+/**
+ * Wraps a partial implementation of the [Graffiti API](https://api.graffiti.garden/classes/Graffiti.html)
+ * to provide the [`synchronize`](https://api.graffiti.garden/classes/Graffiti.html#synchronize) method.
+ * The partial implementation must include the primary database methods:
+ * `get`, `put`, `patch`, `delete`, and `discover`.
+ */
+export class GraffitiSynchronize
+  implements
+    Pick<
+      Graffiti,
+      "put" | "get" | "patch" | "delete" | "discover" | "synchronize"
+    >
+{
+  protected readonly synchronizeEvents = new EventTarget();
+  protected readonly ajv: Ajv;
+  protected readonly graffiti: GraffitiDatabaseMethods;
+
+  // Pass in the ajv instance
+  // and database methods to wrap
+  constructor(graffiti: GraffitiDatabaseMethods, ajv?: Ajv) {
+    this.ajv = ajv ?? new Ajv({ strict: false });
+    this.graffiti = graffiti;
+  }
+
+  protected synchronizeDispatch(
+    oldObject: GraffitiObjectBase,
+    newObject?: GraffitiObjectBase,
+  ) {
+    const event: SynchronizeEvent = new CustomEvent("change", {
+      detail: {
+        oldObject,
+        newObject,
+      },
+    });
+    this.synchronizeEvents.dispatchEvent(event);
+  }
+
+  get: Graffiti["get"] = async (...args) => {
+    const object = await this.graffiti.get(...args);
+    this.synchronizeDispatch(object);
+    return object;
+  };
+
+  put: Graffiti["put"] = async (...args) => {
+    const oldObject = await this.graffiti.put(...args);
+    const partialObject = args[0];
+    const newObject: GraffitiObjectBase = {
+      ...oldObject,
+      value: partialObject.value,
+      channels: partialObject.channels,
+      allowed: partialObject.allowed,
+      tombstone: false,
+    };
+    this.synchronizeDispatch(oldObject, newObject);
+    return oldObject;
+  };
+
+  patch: Graffiti["patch"] = async (...args) => {
+    const oldObject = await this.graffiti.patch(...args);
+    const newObject: GraffitiObjectBase = { ...oldObject };
+    newObject.tombstone = false;
+    for (const prop of ["value", "channels", "allowed"] as const) {
+      applyGraffitiPatch(applyPatch, prop, args[0], newObject);
+    }
+    this.synchronizeDispatch(oldObject, newObject);
+    return oldObject;
+  };
+
+  delete: Graffiti["delete"] = async (...args) => {
+    const oldObject = await this.graffiti.delete(...args);
+    this.synchronizeDispatch(oldObject);
+    return oldObject;
+  };
+
+  discover: Graffiti["discover"] = (...args) => {
+    const iterator = this.graffiti.discover(...args);
+    const dispatch = this.synchronizeDispatch.bind(this);
+    const wrapper = async function* () {
+      let result = await iterator.next();
+      while (!result.done) {
+        if (!result.value.error) {
+          dispatch(result.value.value);
+        }
+        yield result.value;
+        result = await iterator.next();
+      }
+      return result.value;
+    };
+    return wrapper();
+  };
+
+  synchronize: Graffiti["synchronize"] = (...args) => {
+    const [channels, schema, session] = args;
+    const validate = attemptAjvCompile(this.ajv, schema);
+
+    const repeater: ReturnType<
+      typeof Graffiti.prototype.synchronize<typeof schema>
+    > = new Repeater(async (push, stop) => {
+      const callback = (event: SynchronizeEvent) => {
+        const { oldObject: oldObjectRaw, newObject: newObjectRaw } =
+          event.detail;
+
+        for (const objectRaw of [newObjectRaw, oldObjectRaw]) {
+          if (
+            objectRaw &&
+            objectRaw.channels.some((channel) => channels.includes(channel)) &&
+            isActorAllowedGraffitiObject(objectRaw, session)
+          ) {
+            const object = { ...objectRaw };
+            maskGraffitiObject(object, channels, session);
+            if (validate(object)) {
+              push({ value: object });
+              break;
+            }
+          }
+        }
+      };
+
+      this.synchronizeEvents.addEventListener(
+        "change",
+        callback as EventListener,
+      );
+      await stop;
+      this.synchronizeEvents.removeEventListener(
+        "change",
+        callback as EventListener,
+      );
+    });
+
+    return repeater;
+  };
+}

package/src/tests.spec.ts

@@ -0,0 +1,16 @@
+import {
+  graffitiLocationTests,
+  graffitiCRUDTests,
+  graffitiSynchronizeTests,
+  graffitiDiscoverTests,
+} from "@graffiti-garden/api/tests";
+import { GraffitiLocal } from "./index";
+
+const useGraffiti = () => new GraffitiLocal();
+const useSession1 = () => ({ actor: "someone" });
+const useSession2 = () => ({ actor: "someoneelse" });
+
+graffitiLocationTests(useGraffiti);
+graffitiCRUDTests(useGraffiti, useSession1, useSession2);
+graffitiSynchronizeTests(useGraffiti, useSession1, useSession2);
+graffitiDiscoverTests(useGraffiti, useSession1, useSession2);

package/src/utilities.ts

@@ -0,0 +1,128 @@
+import {
+  GraffitiErrorInvalidSchema,
+  GraffitiErrorInvalidUri,
+  GraffitiErrorPatchError,
+  GraffitiErrorPatchTestFailed,
+} from "@graffiti-garden/api";
+import type {
+  Graffiti,
+  GraffitiObjectBase,
+  GraffitiLocation,
+  GraffitiPatch,
+  JSONSchema4,
+  GraffitiSession,
+} from "@graffiti-garden/api";
+import type { Ajv } from "ajv";
+import type { applyPatch } from "fast-json-patch";
+
+export const locationToUri: Graffiti["locationToUri"] = (location) => {
+  return `${location.source}/${encodeURIComponent(location.actor)}/${encodeURIComponent(location.name)}`;
+};
+
+export const uriToLocation: Graffiti["uriToLocation"] = (uri) => {
+  const parts = uri.split("/");
+  const nameEncoded = parts.pop();
+  const webIdEncoded = parts.pop();
+  if (!nameEncoded || !webIdEncoded || !parts.length) {
+    throw new GraffitiErrorInvalidUri();
+  }
+  return {
+    name: decodeURIComponent(nameEncoded),
+    actor: decodeURIComponent(webIdEncoded),
+    source: parts.join("/"),
+  };
+};
+
+export function randomBase64(numBytes: number = 16) {
+  const bytes = new Uint8Array(numBytes);
+  crypto.getRandomValues(bytes);
+  // Convert it to base64
+  const base64 = btoa(String.fromCodePoint(...bytes));
+  // Make sure it is url safe
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/\=+$/, "");
+}
+
+export function unpackLocationOrUri(locationOrUri: GraffitiLocation | string) {
+  if (typeof locationOrUri === "string") {
+    return {
+      location: uriToLocation(locationOrUri),
+      uri: locationOrUri,
+    };
+  } else {
+    return {
+      location: {
+        name: locationOrUri.name,
+        actor: locationOrUri.actor,
+        source: locationOrUri.source,
+      },
+      uri: locationToUri(locationOrUri),
+    };
+  }
+}
+
+export function applyGraffitiPatch<Prop extends keyof GraffitiPatch>(
+  apply: typeof applyPatch,
+  prop: Prop,
+  patch: GraffitiPatch,
+  object: GraffitiObjectBase,
+): void {
+  const ops = patch[prop];
+  if (!ops || !ops.length) return;
+  try {
+    object[prop] = apply(object[prop], ops, true, false).newDocument;
+  } catch (e) {
+    if (
+      typeof e === "object" &&
+      e &&
+      "name" in e &&
+      typeof e.name === "string" &&
+      "message" in e &&
+      typeof e.message === "string"
+    ) {
+      if (e.name === "TEST_OPERATION_FAILED") {
+        throw new GraffitiErrorPatchTestFailed(e.message);
+      } else {
+        throw new GraffitiErrorPatchError(e.name + ": " + e.message);
+      }
+    } else {
+      throw e;
+    }
+  }
+}
+
+export function attemptAjvCompile<Schema extends JSONSchema4>(
+  ajv: Ajv,
+  schema: Schema,
+) {
+  try {
+    return ajv.compile(schema);
+  } catch (error) {
+    throw new GraffitiErrorInvalidSchema(
+      error instanceof Error ? error.message : undefined,
+    );
+  }
+}
+
+export function maskGraffitiObject(
+  object: GraffitiObjectBase,
+  channels: string[],
+  session?: GraffitiSession,
+): void {
+  if (object.actor !== session?.actor) {
+    object.allowed = object.allowed && session ? [session.actor] : undefined;
+    object.channels = object.channels.filter((channel) =>
+      channels.includes(channel),
+    );
+  }
+}
+export function isActorAllowedGraffitiObject(
+  object: GraffitiObjectBase,
+  session?: GraffitiSession,
+) {
+  return (
+    object.allowed === undefined ||
+    (!!session?.actor &&
+      (object.actor === session.actor ||
+        object.allowed.includes(session.actor)))
+  );
+}