@holochain-syn/client 0.0.1

package/README.md

@@ -0,0 +1,20 @@
+# @holochain-syn/client
+
+A simple wrapper class that implements the interface for the `syn` zome.
+
+## Usage
+
+```js
+import { HolochainClient, CellClient } from '@holochain-open-dev/cell-client';
+import { SynClient } from '@holochain-syn/client';
+
+const hcClient = await HolochainClient.connect(url, 'syn');
+const cellData = hcClient.cellDataByRoleId('syn');
+const cellClient = hcClient.forCell(cellData);
+
+const client = new SynClient(cellClient, signal =>
+  handleSignal(this.#workspace, signal)
+);
+
+const sessionInfo = await client.newSession();
+```

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@holochain-syn/client",
+  "version": "0.0.1",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "run-singleton \"tsc -w --preserveWatchOutput\""
+  },
+  "devDependencies": {
+    "@types/lodash-es": "^4.17.4",
+    "gh-pages": "^3.2.3",
+    "rimraf": "^3.0.2",
+    "run-singleton-cli": "^0.0.5",
+    "typescript": "^4.2.4"
+  },
+  "dependencies": {
+    "@holochain-open-dev/cell-client": "^0.3.2",
+    "@holochain-open-dev/core-types": "^0.2.0",
+    "@holochain/client": "^0.3.2",
+    "@msgpack/msgpack": "^2.7.0",
+    "lodash-es": "^4.17.21"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./syn-client";
+export * from "./types/signal";
+export * from "./types/commit";
+export * from "./types/change";
+export * from "./types/folks";
+export * from "./types/heartbeat";
+export * from "./types/session";
+export * from "./types/sync";

package/src/syn-client.ts

@@ -0,0 +1,227 @@
+import type { CellClient } from '@holochain-open-dev/cell-client';
+import type {
+  EntryHashB64,
+  AgentPubKeyB64,
+} from '@holochain-open-dev/core-types';
+import { encode, decode } from '@msgpack/msgpack';
+import isEqual from 'lodash-es/isEqual';
+
+import type {
+  ChangeBundle,
+  SendChangeInput,
+  SendChangeRequestInput,
+} from './types/change';
+import type { Commit, CommitInput, Content } from './types/commit';
+import type { SendFolkLoreInput } from './types/folks';
+import type { SendHeartbeatInput } from './types/heartbeat';
+import type {
+  CloseSessionInput,
+  NewSessionInput,
+  NotifyLeaveSessionInput,
+  Session,
+  SessionInfo,
+} from './types/session';
+import type { SendSyncRequestInput, SendSyncResponseInput } from './types/sync';
+import { allMessageTypes, SynSignal } from './types/signal';
+import { deepDecodeUint8Arrays } from './utils';
+
+export class SynClient {
+  unsubscribe: () => void = () => {};
+
+  constructor(
+    public cellClient: CellClient,
+    protected handleSignal: (synSignal: SynSignal) => void,
+    protected zomeName = 'syn'
+  ) {
+    const { unsubscribe } = cellClient.addSignalHandler(signal => {
+      console.log(signal);
+      if (
+        isEqual(cellClient.cellId, signal.data.cellId) &&
+        signal.data.payload.message &&
+        allMessageTypes.includes(signal.data.payload.message.type)
+      ) {
+        handleSignal(deepDecodeUint8Arrays(signal.data.payload));
+      }
+    });
+
+    this.unsubscribe = unsubscribe;
+  }
+
+  public close() {
+    return this.unsubscribe();
+  }
+
+  /** Session */
+  public async getSession(sessionHash: EntryHashB64): Promise<Session> {
+    return this.callZome('get_session', sessionHash);
+  }
+
+  public async newSession(
+    newSessionInput: NewSessionInput
+  ): Promise<SessionInfo> {
+    return this.callZome('new_session', newSessionInput);
+  }
+
+  public async closeSession(input: CloseSessionInput): Promise<void> {
+    return this.callZome('close_session', input);
+  }
+
+  public getSessions(): Promise<Record<string, Session>> {
+    return this.callZome('get_sessions', null);
+  }
+
+  public notifyLeaveSession(input: NotifyLeaveSessionInput): Promise<void> {
+    return this.callZome('notify_leave_session', input);
+  }
+
+  /** Content */
+  public putSnapshot(content: Content): Promise<EntryHashB64> {
+    return this.callZome('put_snapshot', encode(content));
+  }
+
+  public async getSnapshot(
+    snapshotHash: EntryHashB64
+  ): Promise<Content | undefined> {
+    const content = await this.callZome('get_snapshot', snapshotHash);
+    if (!content) return content;
+    return decode(content);
+  }
+
+  public hashSnapshot(content: Content): Promise<EntryHashB64> {
+    return this.callZome('hash_snapshot', encode(content));
+  }
+
+  /** Commits */
+  public commitChanges(commitInput: CommitInput): Promise<EntryHashB64> {
+    const commit = {
+      ...commitInput,
+      commit: {
+        ...commitInput.commit,
+        changes: this.encodeChangeBundle(commitInput.commit.changes),
+      },
+    };
+
+    return this.callZome('commit_changes', commit);
+  }
+
+  public async getCommit(commitHash: EntryHashB64): Promise<Commit> {
+    const commit = await this.callZome('get_commit', commitHash);
+    return this.decodeCommit(commit);
+  }
+
+  public async getAllCommits(): Promise<Record<string, Commit>> {
+    const commits = await this.callZome('get_all_commits', null);
+
+    for (const key of Object.keys(commits)) {
+      commits[key] = this.decodeCommit(commits[key]);
+    }
+
+    return commits;
+  }
+
+  /** Folks */
+
+  public getFolks(): Promise<Array<AgentPubKeyB64>> {
+    return this.callZome('get_folks', null);
+  }
+
+  public sendFolkLore(sendFolkLoreInput: SendFolkLoreInput): Promise<void> {
+    return this.callZome('send_folk_lore', sendFolkLoreInput);
+  }
+
+  /** Sync */
+  public sendSyncRequest(
+    syncRequestInput: SendSyncRequestInput
+  ): Promise<void> {
+    return this.callZome('send_sync_request', syncRequestInput);
+  }
+
+  public sendSyncResponse(
+    syncResponseInput: SendSyncResponseInput
+  ): Promise<void> {
+    const input = {
+      ...syncResponseInput,
+    };
+
+    if (input.state.folkMissedLastCommit) {
+      input.state.folkMissedLastCommit.commit = this.encodeCommit(
+        input.state.folkMissedLastCommit.commit
+      );
+      input.state.folkMissedLastCommit.commitInitialSnapshot = encode(
+        input.state.folkMissedLastCommit.commitInitialSnapshot
+      );
+    }
+    if (input.state.uncommittedChanges) {
+      input.state.uncommittedChanges = this.encodeChangeBundle(
+        syncResponseInput.state.uncommittedChanges
+      );
+    }
+
+    return this.callZome('send_sync_response', input);
+  }
+
+  /** Changes */
+  public sendChangeRequest(
+    changeRequestInput: SendChangeRequestInput
+  ): Promise<void> {
+    const input = { ...changeRequestInput };
+    if (input.deltaChanges) {
+      input.deltaChanges = {
+        ...input.deltaChanges,
+        deltas: input.deltaChanges.deltas.map(d => encode(d)),
+      };
+    }
+
+    return this.callZome('send_change_request', input);
+  }
+
+  public sendChange(sendChangeInput: SendChangeInput): Promise<void> {
+    const input = {
+      ...sendChangeInput,
+    };
+    if (input.deltaChanges) {
+      input.deltaChanges = this.encodeChangeBundle(input.deltaChanges);
+    }
+    return this.callZome('send_change', input);
+  }
+
+  /** Heartbeat */
+  public sendHeartbeat(heartbeatInput: SendHeartbeatInput): Promise<void> {
+    return this.callZome('send_heartbeat', heartbeatInput);
+  }
+
+  /** Helpers */
+  private async callZome(fnName: string, payload: any): Promise<any> {
+    return this.cellClient.callZome(this.zomeName, fnName, payload);
+  }
+
+  private encodeCommit(commit: Commit) {
+    return {
+      ...commit,
+      changes: this.encodeChangeBundle(commit.changes),
+    };
+  }
+
+  private encodeChangeBundle(changes: ChangeBundle) {
+    return {
+      ...changes,
+      deltas: changes.deltas.map(d => ({
+        author: d.author,
+        delta: encode(d.delta),
+      })),
+    };
+  }
+
+  private decodeCommit(commit: any): Commit {
+    return {
+      ...commit,
+      changes: {
+        authors: commit.changes.authors,
+        deltas: commit.changes.deltas.map(d => ({
+          author: d.author,
+          delta: decode(d.delta),
+        })),
+      },
+    };
+  }
+}

package/src/types/change.ts

@@ -0,0 +1,66 @@
+import type {
+  AgentPubKeyB64,
+  EntryHashB64,
+  Dictionary,
+} from '@holochain-open-dev/core-types';
+
+export type Delta = any;
+
+export interface FolkChanges {
+  atFolkIndex: number;
+  commitChanges: Array<number>;
+}
+
+export interface AuthoredDelta {
+  author: AgentPubKeyB64;
+  delta: Delta;
+}
+
+export interface ChangeBundle {
+  // Indexed by commit index
+  deltas: Array<AuthoredDelta>;
+  // AgentPubKeyB64 -> folkIndex -> sessionIndex
+  authors: Dictionary<FolkChanges>;
+}
+
+// From folk to scribe
+export interface SendChangeRequestInput {
+  sessionHash: EntryHashB64;
+  scribe: AgentPubKeyB64;
+  lastDeltaSeen: LastDeltaSeen;
+
+  deltaChanges: DeltaChanges;
+}
+
+export interface DeltaChanges {
+  atFolkIndex: number;
+  deltas: Array<Delta>;
+}
+
+export interface LastDeltaSeen {
+  commitHash: EntryHashB64 | undefined;
+  deltaIndexInCommit: number;
+}
+
+export interface ChangeRequest {
+  folk: AgentPubKeyB64;
+  scribe: AgentPubKeyB64;
+
+  lastDeltaSeen: LastDeltaSeen;
+
+  deltaChanges: DeltaChanges;
+}
+
+export interface SendChangeInput {
+  participants: Array<AgentPubKeyB64>;
+  sessionHash: EntryHashB64;
+  lastDeltaSeen: LastDeltaSeen;
+
+  deltaChanges: ChangeBundle;
+}
+
+export interface ChangeNotice {
+  lastDeltaSeen: LastDeltaSeen;
+
+  deltaChanges: ChangeBundle;
+}

package/src/types/commit.ts

@@ -0,0 +1,41 @@
+import type {
+  AgentPubKeyB64,
+  EntryHashB64,
+  HeaderHashB64,
+} from '@holochain-open-dev/core-types';
+import type { ChangeBundle } from './change';
+
+export interface CommitInput {
+  sessionHash: EntryHashB64;
+
+  commit: Commit;
+
+  participants: AgentPubKeyB64[];
+}
+
+export interface Commit {
+  changes: ChangeBundle;
+
+  createdAt: number;
+
+  previousCommitHashes: Array<EntryHashB64>;
+
+  previousContentHash: EntryHashB64;
+  newContentHash: EntryHashB64;
+  meta: ChangeMeta;
+}
+
+export interface CommitNotice {
+  commitHash: HeaderHashB64;
+  committedDeltasCount: number;
+  previousContentHash: EntryHashB64;
+  newContentHash: EntryHashB64;
+  meta: ChangeMeta;
+}
+
+export interface ChangeMeta {
+  witnesses: AgentPubKeyB64[];
+  appSpecific: Content;
+}
+
+export type Content = any;

package/src/types/folks.ts

@@ -0,0 +1,17 @@
+import type {
+  AgentPubKeyB64,
+  Dictionary,
+  EntryHashB64,
+} from '@holochain-open-dev/core-types';
+
+export interface SendFolkLoreInput {
+  sessionHash: EntryHashB64;
+  participants: Array<AgentPubKeyB64>;
+  folkLore: FolkLore;
+}
+
+export interface FolkInfo {
+  lastSeen: number;
+}
+
+export type FolkLore = Dictionary<FolkInfo>;

package/src/types/heartbeat.ts

@@ -0,0 +1,15 @@
+import type {
+  AgentPubKeyB64,
+  EntryHashB64,
+} from "@holochain-open-dev/core-types";
+
+export interface SendHeartbeatInput {
+  sessionHash: EntryHashB64;
+  scribe: AgentPubKeyB64;
+  data: String;
+}
+
+export interface Heartbeat {
+  fromFolk: AgentPubKeyB64;
+  data: string;
+}

package/src/types/session.ts

@@ -0,0 +1,29 @@
+import type {
+  AgentPubKeyB64,
+  EntryHashB64,
+} from '@holochain-open-dev/core-types';
+
+export interface Session {
+  initialCommitHash: EntryHashB64 | undefined;
+  scribe: AgentPubKeyB64;
+  createdAt: number;
+}
+
+export interface SessionInfo {
+  sessionHash: EntryHashB64;
+  session: Session;
+}
+
+export interface NewSessionInput {
+  initialCommitHash: EntryHashB64 | undefined;
+}
+
+export interface CloseSessionInput {
+  sessionHash: EntryHashB64;
+  participants: AgentPubKeyB64[];
+}
+
+export interface NotifyLeaveSessionInput {
+  sessionHash: EntryHashB64;
+  scribe: AgentPubKeyB64;
+}

package/src/types/signal.ts

@@ -0,0 +1,52 @@
+import type { CommitNotice } from './commit';
+
+import type { ChangeNotice, ChangeRequest } from './change';
+import type { FolkLore } from './folks';
+import type { Heartbeat } from './heartbeat';
+import type { RequestSyncInput, StateForSync } from './sync';
+import type { AgentPubKeyB64 } from '@holochain-open-dev/core-types';
+
+export enum SynMessageType {
+  SyncReq = 'SyncReq',
+  SyncResp = 'SyncResp',
+  ChangeReq = 'ChangeReq',
+  ChangeNotice = 'ChangeNotice',
+  CommitNotice = 'CommitNotice',
+  Heartbeat = 'Heartbeat',
+  FolkLore = 'FolkLore',
+  SessionClosed = 'SessionClosed',
+  LeaveSessionNotice = 'LeaveSessionNotice',
+}
+
+export const allMessageTypes = [
+  SynMessageType.SyncReq,
+  SynMessageType.SyncResp,
+  SynMessageType.ChangeReq,
+  SynMessageType.ChangeNotice,
+  SynMessageType.CommitNotice,
+  SynMessageType.Heartbeat,
+  SynMessageType.FolkLore,
+  SynMessageType.SessionClosed,
+  SynMessageType.LeaveSessionNotice,
+];
+
+export type SynSignal = {
+  sessionHash: string;
+  message: SynMessage;
+};
+
+export interface MessageBody<TYPE, PAYLOAD> {
+  type: TYPE;
+  payload: PAYLOAD;
+}
+
+export type SynMessage =
+  | MessageBody<SynMessageType.SyncReq, RequestSyncInput>
+  | MessageBody<SynMessageType.SyncResp, StateForSync>
+  | MessageBody<SynMessageType.ChangeReq, ChangeRequest>
+  | MessageBody<SynMessageType.ChangeNotice, ChangeNotice>
+  | MessageBody<SynMessageType.CommitNotice, CommitNotice>
+  | MessageBody<SynMessageType.Heartbeat, Heartbeat>
+  | MessageBody<SynMessageType.FolkLore, FolkLore>
+  | MessageBody<SynMessageType.LeaveSessionNotice, AgentPubKeyB64>
+  | MessageBody<SynMessageType.SessionClosed, void>;

package/src/types/sync.ts

@@ -0,0 +1,42 @@
+import type { ChangeBundle, LastDeltaSeen } from './change';
+import type {
+  EntryHashB64,
+  AgentPubKeyB64,
+} from '@holochain-open-dev/core-types';
+import type { Commit, Content } from './commit';
+
+// Sent by the folk
+export interface SendSyncRequestInput {
+  sessionHash: EntryHashB64;
+  scribe: AgentPubKeyB64;
+  lastDeltaSeen: LastDeltaSeen | undefined;
+}
+
+// Received by the scribe
+export interface RequestSyncInput {
+  folk: AgentPubKeyB64;
+
+  scribe: AgentPubKeyB64;
+  lastDeltaSeen: LastDeltaSeen;
+}
+
+export interface MissedCommit {
+  commitHash: EntryHashB64;
+  commit: Commit;
+  commitInitialSnapshot: Content;
+}
+
+export interface StateForSync {
+  // Will contain the newer commits since `lastSessionIndexSeen`
+  folkMissedLastCommit: MissedCommit | undefined;
+
+  uncommittedChanges: ChangeBundle;
+
+  //currentContentHash: EntryHashB64;
+}
+
+export interface SendSyncResponseInput {
+  sessionHash: EntryHashB64;
+  participant: AgentPubKeyB64;
+  state: StateForSync;
+}

package/src/utils.ts

@@ -0,0 +1,17 @@
+import { decode } from "@msgpack/msgpack";
+
+export function deepDecodeUint8Arrays(object: any): any {
+  if (object === undefined || object === null) return object;
+  if (object instanceof Uint8Array) return decode(object);
+
+  if (typeof object !== "object") return object;
+
+  if (Array.isArray(object)) return object.map(deepDecodeUint8Arrays);
+
+  const obj = {};
+
+  for (const key of Object.keys(object)) {
+    obj[key] = deepDecodeUint8Arrays(object[key]);
+  }
+  return obj;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "outDir": "dist",
+    "declarationDir": "dist",
+    "declaration": true
+  },
+  "include": [
+    "./src/**/*"
+  ],
+  "exclude": [
+    "node_modules/**",
+    "**/node_modules/**",
+    "**/dist/**"
+  ]
+}