dignity.js 0.7.1 → 0.8.0

package/src/cqrs/domain-events.js

@@ -0,0 +1,285 @@
+const nacl = require('tweetnacl');
+const naclUtil = require('tweetnacl-util');
+const { stableStringify } = require('../security/message-security-service');
+
+const DOMAIN_EVENT_SCHEMA_VERSION = 1;
+
+const OPERATION_KIND_TO_EVENT_KIND = {
+  create: 'record:created',
+  update: 'record:updated',
+  delete: 'record:removed',
+  'transfer-ownership': 'ownership:transferred'
+};
+
+function computeContentHash(data) {
+  const canonical = stableStringify(data || {});
+  const bytes = naclUtil.decodeUTF8(canonical);
+  const hash = nacl.hash(bytes);
+  const hex = Array.from(hash, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `sha512:${hex}`;
+}
+
+function canonicalEventBody(event) {
+  return stableStringify({
+    schemaVersion: event.schemaVersion,
+    eventId: event.eventId,
+    groupId: event.groupId,
+    publisherId: event.publisherId,
+    kind: event.kind,
+    collectionName: event.collectionName,
+    id: event.id,
+    payload: event.payload,
+    timestamp: event.timestamp,
+    baseVersion: event.baseVersion,
+    prevHash: event.prevHash || null,
+    newOwnerId: event.newOwnerId || null
+  });
+}
+
+function computeEventHash(event) {
+  const canonical = canonicalEventBody(event);
+  const bytes = naclUtil.decodeUTF8(canonical);
+  const hash = nacl.hash(bytes);
+  const hex = Array.from(hash, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `sha512:${hex}`;
+}
+
+function operationToDomainEvent(operation, { publisherId, groupId, prevHash, eventIdGenerator }) {
+  if (!operation || !publisherId || !groupId) {
+    throw new Error('operationToDomainEvent requires operation, publisherId, and groupId');
+  }
+
+  const kind = OPERATION_KIND_TO_EVENT_KIND[operation.kind];
+  if (!kind) {
+    throw new Error(`Unsupported operation kind for domain event: ${operation.kind}`);
+  }
+
+  const event = {
+    schemaVersion: DOMAIN_EVENT_SCHEMA_VERSION,
+    eventId: eventIdGenerator ? eventIdGenerator() : `${Date.now()}-${Math.random().toString(16).slice(2)}`,
+    groupId,
+    publisherId,
+    kind,
+    collectionName: operation.collectionName,
+    id: operation.id,
+    payload: operation.payload || {},
+    timestamp: operation.timestamp,
+    baseVersion: operation.baseVersion || null,
+    prevHash: prevHash || null,
+    newOwnerId: operation.newOwnerId || null,
+    eventHash: null,
+    signature: null
+  };
+
+  event.eventHash = computeEventHash(event);
+  return event;
+}
+
+function signDomainEvent(event, signingSecretKey) {
+  if (!signingSecretKey) {
+    return { ...event };
+  }
+
+  const unsigned = { ...event, signature: null };
+  const eventHash = computeEventHash(unsigned);
+  const signature = nacl.sign.detached(
+    naclUtil.decodeUTF8(eventHash),
+    signingSecretKey
+  );
+
+  return {
+    ...unsigned,
+    eventHash,
+    signature: naclUtil.encodeBase64(signature)
+  };
+}
+
+function verifyDomainEventSignature(event, signingPublicKey) {
+  if (!event || !event.eventHash) {
+    return { ok: false, reason: 'missing-event-hash' };
+  }
+
+  const recomputed = computeEventHash({ ...event, signature: null });
+  if (recomputed !== event.eventHash) {
+    return { ok: false, reason: 'event-hash-mismatch' };
+  }
+
+  if (!event.signature) {
+    return { ok: true, unsigned: true };
+  }
+
+  if (!signingPublicKey) {
+    return { ok: false, reason: 'missing-public-key' };
+  }
+
+  const keyBytes = typeof signingPublicKey === 'string'
+    ? naclUtil.decodeBase64(signingPublicKey)
+    : signingPublicKey;
+
+  const valid = nacl.sign.detached.verify(
+    naclUtil.decodeUTF8(event.eventHash),
+    naclUtil.decodeBase64(event.signature),
+    keyBytes
+  );
+
+  return valid ? { ok: true } : { ok: false, reason: 'invalid-signature' };
+}
+
+function verifyDomainEvent(event, { signingPublicKey, supportedVersions } = {}) {
+  if (!event || typeof event !== 'object') {
+    return { ok: false, reason: 'invalid-event' };
+  }
+
+  const versions = supportedVersions || [DOMAIN_EVENT_SCHEMA_VERSION];
+  if (!versions.includes(event.schemaVersion)) {
+    return { ok: false, reason: 'unsupported-schema-version', schemaVersion: event.schemaVersion };
+  }
+
+  if (!event.eventId || !event.groupId || !event.publisherId || !event.kind) {
+    return { ok: false, reason: 'missing-required-fields' };
+  }
+
+  return verifyDomainEventSignature(event, signingPublicKey);
+}
+
+function createEmptyView(collections = []) {
+  const view = new Map();
+  for (const name of collections) {
+    view.set(name, new Map());
+  }
+  return view;
+}
+
+function ensureCollectionView(view, collectionName) {
+  if (!view.has(collectionName)) {
+    view.set(collectionName, new Map());
+  }
+  return view.get(collectionName);
+}
+
+function applyDomainEventToView(view, event, { collectionsFilter } = {}) {
+  if (!event || !event.collectionName) {
+    return { applied: false, reason: 'invalid-event' };
+  }
+
+  if (Array.isArray(collectionsFilter) && collectionsFilter.length > 0
+    && !collectionsFilter.includes(event.collectionName)) {
+    return { applied: false, reason: 'collection-filtered' };
+  }
+
+  const collection = ensureCollectionView(view, event.collectionName);
+
+  if (event.kind === 'record:created') {
+    if (collection.has(event.id)) {
+      return { applied: false, reason: 'already-exists' };
+    }
+    collection.set(event.id, {
+      id: event.id,
+      ownerId: event.publisherId,
+      data: { ...(event.payload || {}) },
+      hash: computeContentHash(event.payload || {}),
+      createdAt: event.timestamp,
+      updatedAt: event.timestamp,
+      deletedAt: null,
+      version: 1
+    });
+    return { applied: true, kind: event.kind };
+  }
+
+  const current = collection.get(event.id);
+  if (!current || current.deletedAt) {
+    if (event.kind === 'record:removed') {
+      return { applied: false, reason: 'not-found' };
+    }
+    return { applied: false, reason: 'missing-record' };
+  }
+
+  if (event.kind === 'record:updated') {
+    if (typeof event.baseVersion === 'number' && current.version !== event.baseVersion) {
+      return { applied: false, reason: 'version-conflict', currentVersion: current.version };
+    }
+    current.data = { ...current.data, ...(event.payload || {}) };
+    current.hash = computeContentHash(current.data);
+    current.updatedAt = event.timestamp;
+    current.version += 1;
+    return { applied: true, kind: event.kind };
+  }
+
+  if (event.kind === 'record:removed') {
+    if (typeof event.baseVersion === 'number' && current.version !== event.baseVersion) {
+      return { applied: false, reason: 'version-conflict', currentVersion: current.version };
+    }
+    current.deletedAt = event.timestamp;
+    current.version += 1;
+    return { applied: true, kind: event.kind };
+  }
+
+  if (event.kind === 'ownership:transferred') {
+    if (typeof event.baseVersion === 'number' && current.version !== event.baseVersion) {
+      return { applied: false, reason: 'version-conflict', currentVersion: current.version };
+    }
+    current.ownerId = event.newOwnerId;
+    current.updatedAt = event.timestamp;
+    current.version += 1;
+    return { applied: true, kind: event.kind };
+  }
+
+  return { applied: false, reason: 'unknown-kind' };
+}
+
+function verifyEventChain(events, { genesisHash = null } = {}) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return { ok: true, length: 0 };
+  }
+
+  let expectedPrev = genesisHash;
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    const prevHash = event.prevHash || null;
+
+    if (prevHash !== expectedPrev) {
+      return {
+        ok: false,
+        reason: 'chain-break',
+        index,
+        expectedPrev,
+        actualPrev: prevHash
+      };
+    }
+
+    const hashCheck = verifyDomainEventSignature(event, null);
+    if (!hashCheck.ok) {
+      return { ok: false, reason: hashCheck.reason, index };
+    }
+
+    expectedPrev = event.eventHash;
+  }
+
+  return { ok: true, length: events.length, lastHash: expectedPrev };
+}
+
+function buildCheckpoint(groupId, events, { publisherId } = {}) {
+  const chain = verifyEventChain(events);
+  return {
+    schemaVersion: DOMAIN_EVENT_SCHEMA_VERSION,
+    groupId,
+    publisherId: publisherId || null,
+    lastEventHash: chain.lastHash || null,
+    recordCount: events.length,
+    timestamp: Date.now()
+  };
+}
+
+module.exports = {
+  DOMAIN_EVENT_SCHEMA_VERSION,
+  OPERATION_KIND_TO_EVENT_KIND,
+  computeEventHash,
+  operationToDomainEvent,
+  signDomainEvent,
+  verifyDomainEvent,
+  verifyDomainEventSignature,
+  createEmptyView,
+  applyDomainEventToView,
+  verifyEventChain,
+  buildCheckpoint
+};

package/src/cqrs/peer-group-tiers.js

@@ -0,0 +1,46 @@
+const DEFAULT_LIVE_CAP = 5000;
+const DEFAULT_BULK_INTERVAL_MS = 30000;
+
+function assignPeerGroupTier({ joinIndex, liveCap = DEFAULT_LIVE_CAP, requestedTier, role }) {
+  if (role === 'publisher') {
+    return 'live';
+  }
+
+  if (requestedTier === 'live' || requestedTier === 'bulk') {
+    if (requestedTier === 'live' && joinIndex >= liveCap) {
+      return 'bulk';
+    }
+    return requestedTier;
+  }
+
+  return joinIndex < liveCap ? 'live' : 'bulk';
+}
+
+function getPeerTier(peer) {
+  return peer?.metadata?.peerGroupTier || peer?.peerGroupTier || null;
+}
+
+function filterPeersByTier(peers, tier) {
+  if (!tier) {
+    return peers;
+  }
+  return peers.filter((peer) => getPeerTier(peer) === tier);
+}
+
+function countLivePeers(peers) {
+  return peers.filter((peer) => getPeerTier(peer) === 'live').length;
+}
+
+function countBulkPeers(peers) {
+  return peers.filter((peer) => getPeerTier(peer) === 'bulk').length;
+}
+
+module.exports = {
+  DEFAULT_LIVE_CAP,
+  DEFAULT_BULK_INTERVAL_MS,
+  assignPeerGroupTier,
+  getPeerTier,
+  filterPeersByTier,
+  countLivePeers,
+  countBulkPeers
+};

package/src/cqrs/query-replica.js

@@ -0,0 +1,213 @@
+const EventEmitter = require('../utils/event-emitter');
+const {
+  createEmptyView,
+  applyDomainEventToView,
+  verifyEventChain,
+  verifyDomainEvent,
+  DOMAIN_EVENT_SCHEMA_VERSION
+} = require('./domain-events');
+
+class DignityQueryReplica extends EventEmitter {
+  constructor(dignityP2P, { groupId, collections = [], tierMode = 'auto', publisherId = null } = {}) {
+    super();
+
+    if (!dignityP2P) {
+      throw new Error('DignityQueryReplica requires dignityP2P');
+    }
+    if (!groupId) {
+      throw new Error('DignityQueryReplica requires groupId');
+    }
+
+    this.dignity = dignityP2P;
+    this.groupId = groupId;
+    this.collections = [...collections];
+    this.tierMode = tierMode;
+    this.publisherId = publisherId;
+    this.view = createEmptyView(this.collections);
+    this.eventLog = [];
+    this.started = false;
+    this.boundDomainHandler = this.handleDomainEvent.bind(this);
+    this.boundPeerGroupHandler = this.handlePeerGroupMessage.bind(this);
+  }
+
+  async start(options = {}) {
+    if (this.started) {
+      return this;
+    }
+
+    await this.dignity.joinPeerGroup(this.groupId, {
+      tierMode: this.tierMode,
+      role: 'subscriber',
+      commandCapable: false,
+      domainEvents: true,
+      publisherId: this.publisherId,
+      liveCap: options.liveCap,
+      bulkIntervalMs: options.bulkIntervalMs,
+      bootstrapPeerIds: options.bootstrapPeerIds,
+      metadata: { role: 'subscriber', replica: true }
+    });
+
+    this.dignity.on('domainevent', this.boundDomainHandler);
+    this.dignity.on('peergroupmessage', this.boundPeerGroupHandler);
+    this.started = true;
+    this.emit('started', { groupId: this.groupId });
+    return this;
+  }
+
+  async stop() {
+    if (!this.started) {
+      return;
+    }
+
+    this.dignity.off('domainevent', this.boundDomainHandler);
+    this.dignity.off('peergroupmessage', this.boundPeerGroupHandler);
+    await this.dignity.leavePeerGroup(this.groupId);
+    this.started = false;
+    this.emit('stopped', { groupId: this.groupId });
+  }
+
+  handleDomainEvent(event) {
+    if (!event || event.groupId !== this.groupId) {
+      return;
+    }
+
+    if (this.publisherId && event.publisherId !== this.publisherId) {
+      return;
+    }
+
+    this.ingestEvent(event);
+  }
+
+  handlePeerGroupMessage(message) {
+    if (!message || message.groupId !== this.groupId) {
+      return;
+    }
+
+    if (message.type === 'domain:checkpoint') {
+      this.emit('checkpoint', message.payload);
+    }
+  }
+
+  ingestEvent(event, { skipChainCheck = false } = {}) {
+    const verified = verifyDomainEvent(event, {
+      supportedVersions: [DOMAIN_EVENT_SCHEMA_VERSION]
+    });
+
+    if (!verified.ok) {
+      this.emit('warning', { type: 'domain-event-rejected', reason: verified.reason, event });
+      return false;
+    }
+
+    if (!skipChainCheck && this.eventLog.length > 0) {
+      const lastHash = this.eventLog[this.eventLog.length - 1].eventHash;
+      if (event.prevHash !== lastHash) {
+        this.emit('chainbroken', {
+          groupId: this.groupId,
+          expectedPrev: lastHash,
+          actualPrev: event.prevHash,
+          eventId: event.eventId
+        });
+        return false;
+      }
+    } else if (!skipChainCheck && this.eventLog.length === 0 && event.prevHash) {
+      this.emit('chainbroken', {
+        groupId: this.groupId,
+        expectedPrev: null,
+        actualPrev: event.prevHash,
+        eventId: event.eventId
+      });
+      return false;
+    }
+
+    const duplicate = this.eventLog.some((entry) => entry.eventId === event.eventId);
+    if (duplicate) {
+      return false;
+    }
+
+    const result = applyDomainEventToView(this.view, event, {
+      collectionsFilter: this.collections.length > 0 ? this.collections : null
+    });
+
+    if (result.applied || result.reason === 'collection-filtered') {
+      this.eventLog.push({ ...event });
+      this.emit('change', { event, result });
+      return true;
+    }
+
+    this.emit('warning', { type: 'domain-event-not-applied', reason: result.reason, event });
+    return false;
+  }
+
+  read(collectionName, id) {
+    const collection = this.view.get(collectionName);
+    if (!collection) {
+      return null;
+    }
+    const record = collection.get(id);
+    if (!record || record.deletedAt) {
+      return null;
+    }
+    return { ...record, data: { ...record.data } };
+  }
+
+  list(collectionName, options = {}) {
+    const collection = this.view.get(collectionName);
+    if (!collection) {
+      return [];
+    }
+
+    const includeDeleted = options.includeDeleted || false;
+    const records = [];
+
+    for (const record of collection.values()) {
+      if (record.deletedAt && !includeDeleted) {
+        continue;
+      }
+      if (record.deletedAt && includeDeleted) {
+        records.push({
+          id: record.id,
+          ownerId: record.ownerId,
+          deletedAt: record.deletedAt,
+          version: record.version
+        });
+        continue;
+      }
+      records.push({ ...record, data: { ...record.data } });
+    }
+
+    return records;
+  }
+
+  verifyChain() {
+    const result = verifyEventChain(this.eventLog);
+    if (!result.ok) {
+      this.emit('chainbroken', { groupId: this.groupId, ...result });
+    }
+    return result;
+  }
+
+  getViewStats() {
+    const stats = {
+      groupId: this.groupId,
+      eventCount: this.eventLog.length,
+      collections: {}
+    };
+
+    for (const [name, collection] of this.view.entries()) {
+      let active = 0;
+      let deleted = 0;
+      for (const record of collection.values()) {
+        if (record.deletedAt) {
+          deleted += 1;
+        } else {
+          active += 1;
+        }
+      }
+      stats.collections[name] = { active, deleted };
+    }
+
+    return stats;
+  }
+}
+
+module.exports = DignityQueryReplica;

package/src/gossip/peer-group.js

@@ -3,7 +3,7 @@ const PEER_GROUP_SCOPE_PREFIX = 'gossip:';
 const DEFAULT_PEER_GROUP_OPTIONS = {
   fanout: 3,
   maxActivePeers: 8,
-  maxHops: 6,
+  maxHops: 64,
   relayEnabled: true
 };
 

package/src/index.js

@@ -49,6 +49,24 @@ const {
   parsePeerGroupScope,
   selectFanoutPeers
 } = require('./gossip/peer-group');
+const {
+  DOMAIN_EVENT_SCHEMA_VERSION,
+  operationToDomainEvent,
+  signDomainEvent,
+  verifyDomainEvent,
+  verifyEventChain,
+  buildCheckpoint,
+  createEmptyView,
+  applyDomainEventToView
+} = require('./cqrs/domain-events');
+const {
+  DEFAULT_LIVE_CAP,
+  DEFAULT_BULK_INTERVAL_MS,
+  assignPeerGroupTier,
+  filterPeersByTier
+} = require('./cqrs/peer-group-tiers');
+const { electBulkRelays, DEFAULT_BULK_RELAY_COUNT } = require('./cqrs/bulk-relay');
+const DignityQueryReplica = require('./cqrs/query-replica');
 
 module.exports = {
   DignityP2P,
@@ -83,5 +101,20 @@ module.exports = {
   DEFAULT_PEER_GROUP_OPTIONS,
   peerGroupScope,
   parsePeerGroupScope,
-  selectFanoutPeers
+  selectFanoutPeers,
+  DOMAIN_EVENT_SCHEMA_VERSION,
+  operationToDomainEvent,
+  signDomainEvent,
+  verifyDomainEvent,
+  verifyEventChain,
+  buildCheckpoint,
+  createEmptyView,
+  applyDomainEventToView,
+  DEFAULT_LIVE_CAP,
+  DEFAULT_BULK_INTERVAL_MS,
+  assignPeerGroupTier,
+  filterPeersByTier,
+  electBulkRelays,
+  DEFAULT_BULK_RELAY_COUNT,
+  DignityQueryReplica
 };