@sphereon/ssi-sdk.data-store 0.19.1-next.24 → 0.19.1-next.96

package/src/index.ts

@@ -18,6 +18,7 @@ import { IssuerBrandingEntity, issuerBrandingEntityFrom } from './entities/issua
 import { TextAttributesEntity, textAttributesEntityFrom } from './entities/issuanceBranding/TextAttributesEntity'
 import { StatusListEntity } from './entities/statusList2021/StatusList2021Entity'
 import { StatusListEntryEntity } from './entities/statusList2021/StatusList2021EntryEntity'
+import { MachineStateInfoEntity } from './entities/machineState/MachineStateInfoEntity'
 import { IStatusListEntity, IStatusListEntryEntity } from './types'
 import { PartyRelationshipEntity } from './entities/contact/PartyRelationshipEntity'
 import { PartyTypeEntity } from './entities/contact/PartyTypeEntity'
@@ -35,12 +36,16 @@ import { DigitalCredentialEntity } from './entities/digitalCredential/DigitalCre
 import { digitalCredentialFrom, digitalCredentialsFrom, nonPersistedDigitalCredentialEntityFromAddArgs } from './utils/digitalCredential/MappingUtils'
 export { AbstractEventLoggerStore } from './eventLogger/AbstractEventLoggerStore'
 export { EventLoggerStore } from './eventLogger/EventLoggerStore'
+export { IAbstractMachineStateStore } from './machineState/IAbstractMachineStateStore'
+export { MachineStateStore } from './machineState/MachineStateStore'
+
 export {
   DataStoreMigrations,
   DataStoreEventLoggerMigrations,
   DataStoreContactMigrations,
   DataStoreIssuanceBrandingMigrations,
   DataStoreStatusListMigrations,
+  DataStoreMachineStateMigrations,
 } from './migrations'
 export * from './types'
 export * from './utils/contact/MappingUtils'
@@ -81,6 +86,8 @@ export const DataStoreEventLoggerEntities = [AuditEventEntity]
 
 export const DataStoreDigitalCredentialEntities = [DigitalCredentialEntity]
 
+export const DataStoreMachineStateEntities = [MachineStateInfoEntity]
+
 // All entities combined if a party wants to enable them all at once
 export const DataStoreEntities = [
   ...DataStoreContactEntities,
@@ -88,6 +95,7 @@ export const DataStoreEntities = [
   ...DataStoreStatusListEntities,
   ...DataStoreEventLoggerEntities,
   ...DataStoreDigitalCredentialEntities,
+  ...DataStoreMachineStateEntities,
 ]
 
 export {
@@ -128,4 +136,5 @@ export {
   digitalCredentialFrom,
   digitalCredentialsFrom,
   nonPersistedDigitalCredentialEntityFromAddArgs,
+  MachineStateInfoEntity,
 }

package/src/machineState/IAbstractMachineStateStore.ts

@@ -0,0 +1,65 @@
+import {
+  StoreMachineStateDeleteExpiredArgs,
+  StoreMachineStateDeleteArgs,
+  StoreMachineStatesFindActiveArgs,
+  StoreFindMachineStatesArgs,
+  StoreMachineStatePersistArgs,
+  StoreMachineStateInfo,
+  StoreMachineStateGetArgs,
+} from '../types'
+
+/**
+ * Represents an abstract class for storing machine states.
+ * This class provides methods for persisting, retrieving, and deleting machine states.
+ *
+ * @interface
+ */
+export abstract class IAbstractMachineStateStore {
+  /**
+   * Persists the machine state.
+   *
+   * @param {StoreMachineStatePersistArgs} state - The object containing the machine state to persist.
+   * @return {Promise<StoreMachineStateInfo>} - A Promise that resolves to the information about the persisted machine state.
+   */
+  abstract persistMachineState(state: StoreMachineStatePersistArgs): Promise<StoreMachineStateInfo>
+
+  /**
+   * Finds active machine states based on the given arguments.
+   *
+   * @param {StoreMachineStatesFindActiveArgs} args - The arguments for finding active machine states.
+   * @return {Promise<Array<StoreMachineStateInfo>>} - A promise that resolves with an array of active machine states.
+   */
+  abstract findActiveMachineStates(args: StoreMachineStatesFindActiveArgs): Promise<Array<StoreMachineStateInfo>>
+
+  /**
+   * Retrieves the state of a particular machine.
+   *
+   * @param {StoreMachineStateGetArgs} args - The arguments for retrieving the machine state.
+   * @returns {Promise<StoreMachineStateInfo>} - A promise that resolves to the machine state information.
+   */
+  abstract getMachineState(args: StoreMachineStateGetArgs): Promise<StoreMachineStateInfo>
+
+  /**
+   * Finds the machine states based on the given arguments.
+   *
+   * @param {StoreFindMachineStatesArgs} [args] - The arguments to filter the machine states.
+   * @returns {Promise<Array<StoreMachineStateInfo>>} - A promise that resolves to an array of machine state information.
+   */
+  abstract findMachineStates(args?: StoreFindMachineStatesArgs): Promise<Array<StoreMachineStateInfo>>
+
+  /**
+   * Deletes a machine state.
+   *
+   * @param {StoreMachineStateDeleteArgs} args - The arguments for deleting the machine state.
+   * @return {Promise<boolean>} - A promise that resolves to a boolean indicating if the machine state was successfully deleted or not.
+   */
+  abstract deleteMachineState(args: StoreMachineStateDeleteArgs): Promise<boolean>
+
+  /**
+   * Deletes expired machine states from the database.
+   *
+   * @param {StoreMachineStateDeleteExpiredArgs} args - The arguments for deleting expired machine states.
+   * @return {Promise<number>} - A promise that resolves to the number of deleted machine states.
+   */
+  abstract deleteExpiredMachineStates(args: StoreMachineStateDeleteExpiredArgs): Promise<number>
+}

package/src/machineState/MachineStateStore.ts

@@ -0,0 +1,149 @@
+import { OrPromise } from '@sphereon/ssi-types'
+import Debug from 'debug'
+import { Brackets, DataSource, FindOptionsWhere, IsNull, LessThan, Not } from 'typeorm'
+
+import { MachineStateInfoEntity } from '../entities/machineState/MachineStateInfoEntity'
+import {
+  StoreFindMachineStatesArgs,
+  StoreMachineStateDeleteArgs,
+  StoreMachineStateDeleteExpiredArgs,
+  StoreMachineStateGetArgs,
+  StoreMachineStateInfo,
+  StoreMachineStatePersistArgs,
+  StoreMachineStatesFindActiveArgs,
+} from '../types'
+import { IAbstractMachineStateStore } from './IAbstractMachineStateStore'
+
+const debug = Debug('sphereon:ssi-sdk:machine-state:store')
+
+/**
+ * Represents a data store for managing machine states.
+ */
+export class MachineStateStore extends IAbstractMachineStateStore {
+  private readonly _dbConnection: OrPromise<DataSource>
+
+  constructor(dbConnection: OrPromise<DataSource>) {
+    super()
+    this._dbConnection = dbConnection
+  }
+
+  async persistMachineState(state: StoreMachineStatePersistArgs): Promise<StoreMachineStateInfo> {
+    const connection: DataSource = await this._dbConnection
+    const { machineName, instanceId, tenantId } = state
+    debug(`Executing persistMachineState for machine ${machineName}, instance ${instanceId}, tenantId: ${tenantId}...`)
+    const entity = MachineStateStore.machineStateInfoEntityFrom(state)
+    const existing = await connection.getRepository(MachineStateInfoEntity).findOne({
+      where: {
+        instanceId: state.instanceId,
+      },
+    })
+    if (existing && existing.updatedCount > state.updatedCount) {
+      const error = `Updating machine state with an older version is not allowed. Machine ${existing.machineName}, last count: ${
+        existing.updatedCount
+      }, new count: ${existing.updatedCount}, last updated: ${existing.updatedAt}, current: ${new Date()}, instance: ${existing.instanceId}`
+      console.log(error)
+      return Promise.reject(new Error(error))
+    }
+    // No need for a transaction. This is a single entity. We don't want to be surprised by an isolation level hiding the state from others
+    const result = await connection.getRepository(MachineStateInfoEntity).save(entity, { transaction: false })
+    debug(`Done persistMachineState machine ${machineName}, instance ${instanceId}, tenantId: ${tenantId}`)
+    return MachineStateStore.machineInfoFrom(result)
+  }
+
+  async findActiveMachineStates(args: StoreMachineStatesFindActiveArgs): Promise<Array<StoreMachineStateInfo>> {
+    const { tenantId, machineName, instanceId } = args
+    const connection: DataSource = await this._dbConnection
+    debug(`Executing findActiveMachineStates query with machineName: ${machineName}, tenantId: ${tenantId}`)
+    const queryBuilder = connection
+      .getRepository(MachineStateInfoEntity)
+      .createQueryBuilder('state')
+      .where('state.completedAt IS NULL')
+      .andWhere(
+        new Brackets((qb) => {
+          qb.where('state.expiresAt IS NULL').orWhere('state.expiresAt > :now', { now: new Date() })
+        })
+      )
+
+    if (instanceId) {
+      queryBuilder.andWhere('state.instanceId = :instanceId', { instanceId })
+    }
+    if (tenantId) {
+      queryBuilder.andWhere('state.tenantId = :tenantId', { tenantId })
+    }
+    if (machineName) {
+      queryBuilder.andWhere('state.machineName = :machineName', { machineName })
+    }
+
+    return (
+      (await queryBuilder
+        .orderBy('state.updatedAt', 'DESC')
+        .getMany()
+        .then((entities) => entities.map(MachineStateStore.machineInfoFrom))) ?? []
+    )
+  }
+
+  async findMachineStates(args?: StoreFindMachineStatesArgs): Promise<Array<StoreMachineStateInfo>> {
+    const connection: DataSource = await this._dbConnection
+    debug('findMachineStates', args)
+    const result: Array<MachineStateInfoEntity> = await connection.getRepository(MachineStateInfoEntity).find({
+      ...(args?.filter && { where: args?.filter }),
+      transaction: false,
+    })
+
+    return result.map((event: MachineStateInfoEntity) => MachineStateStore.machineInfoFrom(event))
+  }
+
+  async getMachineState(args: StoreMachineStateGetArgs): Promise<StoreMachineStateInfo> {
+    const connection: DataSource = await this._dbConnection
+    debug('getMachineState', args)
+    return connection.getRepository(MachineStateInfoEntity).findOneOrFail({ where: { instanceId: args.instanceId } })
+  }
+
+  async deleteMachineState(args: StoreMachineStateDeleteArgs): Promise<boolean> {
+    debug(`Executing deleteMachineState query with id: ${args.instanceId}`)
+    if (!args.instanceId) {
+      throw new Error('No instanceId parameter is provided.')
+    }
+    try {
+      const connection: DataSource = await this._dbConnection
+
+      const result = await connection.getRepository(MachineStateInfoEntity).delete(args.instanceId)
+      return result.affected != null && result.affected > 0
+    } catch (error) {
+      debug(`Error deleting state: ${error}`)
+      return false
+    }
+  }
+
+  async deleteExpiredMachineStates(args: StoreMachineStateDeleteExpiredArgs): Promise<number> {
+    const { machineName, tenantId, deleteDoneStates } = args
+    debug(`Executing deleteExpiredMachineStates query with params: ${JSON.stringify(args)}`)
+    try {
+      const connection: DataSource = await this._dbConnection
+
+      const deleteCriteria: FindOptionsWhere<MachineStateInfoEntity> = {
+        ...(machineName && { machineName }),
+        ...(tenantId && { tenantId }),
+        // When deleteOnDone state is set we only look at completedAt, in other cases we compare current time with expiresAt
+        ...(!deleteDoneStates && { expiresAt: LessThan(new Date()) }),
+        ...(deleteDoneStates && { completedAt: Not(IsNull()) }),
+      }
+      const result = await connection.getRepository(MachineStateInfoEntity).delete(deleteCriteria)
+      return result.affected ?? 0
+    } catch (error) {
+      debug(`Error deleting machine info: ${error}`)
+      return Promise.reject(new Error(`Error deleting expired machine states for machine type ${machineName}`))
+    }
+  }
+
+  protected static machineInfoFrom = (machineStateInfoEntity: MachineStateInfoEntity): StoreMachineStateInfo => {
+    // We are making sure no entity function get copied
+    return JSON.parse(JSON.stringify(machineStateInfoEntity))
+  }
+
+  static machineStateInfoEntityFrom = (machineStateInfo: StoreMachineStateInfo | StoreMachineStatePersistArgs): MachineStateInfoEntity => {
+    const entity = new MachineStateInfoEntity()
+    Object.assign(entity, machineStateInfo)
+    return entity
+  }
+}

package/src/migrations/generic/7-CreateMachineStateStore.ts

@@ -0,0 +1,66 @@
+import { DatabaseType, MigrationInterface, QueryRunner } from 'typeorm'
+import Debug from 'debug'
+import { CreateMachineStateStore1708797018115 } from '../postgres/1708797018115-CreateMachineStateStore'
+import { CreateMachineStateStore1708796002272 } from '../sqlite/1708796002272-CreateMachineStateStore'
+
+const debug: Debug.Debugger = Debug('sphereon:ssi-sdk:migrations')
+
+export class CreateMachineStateStore1708098041262 implements MigrationInterface {
+  name = 'CreateMachineStateStore1708098041262'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    debug('migration: creating machine state tables')
+    const dbType: DatabaseType = queryRunner.connection.driver.options.type
+
+    switch (dbType) {
+      case 'postgres': {
+        debug('using postgres migration file')
+        const mig: CreateMachineStateStore1708797018115 = new CreateMachineStateStore1708797018115()
+        await mig.up(queryRunner)
+        debug('Migration statements executed')
+        return
+      }
+      case 'sqlite':
+      case 'expo':
+      case 'react-native': {
+        debug('using sqlite/react-native migration file')
+        const mig: CreateMachineStateStore1708796002272 = new CreateMachineStateStore1708796002272()
+        await mig.up(queryRunner)
+        debug('Migration statements executed')
+        return
+      }
+      default:
+        return Promise.reject(
+          `Migrations are currently only supported for sqlite, react-native, expo and postgres. Was ${dbType}. Please run your database without migrations and with 'migrationsRun: false' and 'synchronize: true' for now`
+        )
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    debug('migration: reverting machine state tables')
+    const dbType: DatabaseType = queryRunner.connection.driver.options.type
+
+    switch (dbType) {
+      case 'postgres': {
+        debug('using postgres migration file')
+        const mig: CreateMachineStateStore1708797018115 = new CreateMachineStateStore1708797018115()
+        await mig.down(queryRunner)
+        debug('Migration statements executed')
+        return
+      }
+      case 'sqlite':
+      case 'expo':
+      case 'react-native': {
+        debug('using sqlite/react-native migration file')
+        const mig: CreateMachineStateStore1708796002272 = new CreateMachineStateStore1708796002272()
+        await mig.down(queryRunner)
+        debug('Migration statements executed')
+        return
+      }
+      default:
+        return Promise.reject(
+          `Migrations are currently only supported for sqlite, react-native, expo and postgres. Was ${dbType}. Please run your database without migrations and with 'migrationsRun: false' and 'synchronize: true' for now`
+        )
+    }
+  }
+}

package/src/migrations/generic/index.ts

@@ -4,6 +4,7 @@ import { CreateContacts1690925872318 } from './3-CreateContacts'
 import { CreateStatusList1693866470000 } from './4-CreateStatusList'
 import { CreateAuditEvents1701635835330 } from './5-CreateAuditEvents'
 import { CreateDigitalCredential1708525189000 } from './6-CreateDigitalCredential'
+import { CreateMachineStateStore1708098041262 } from './7-CreateMachineStateStore'
 
 /**
  * The migrations array that SHOULD be used when initializing a TypeORM database connection.
@@ -19,6 +20,7 @@ export const DataStoreIssuanceBrandingMigrations = [CreateIssuanceBranding165946
 export const DataStoreStatusListMigrations = [CreateStatusList1693866470000]
 export const DataStoreEventLoggerMigrations = [CreateAuditEvents1701635835330]
 export const DataStoreDigitalCredentialMigrations = [CreateDigitalCredential1708525189000]
+export const DataStoreMachineStateMigrations = [CreateMachineStateStore1708098041262]
 
 // All migrations together
 export const DataStoreMigrations = [
@@ -27,4 +29,5 @@ export const DataStoreMigrations = [
   ...DataStoreStatusListMigrations,
   ...DataStoreEventLoggerMigrations,
   ...DataStoreDigitalCredentialMigrations,
+  ...DataStoreMachineStateMigrations,
 ]

package/src/migrations/index.ts

@@ -5,4 +5,5 @@ export {
   DataStoreIssuanceBrandingMigrations,
   DataStoreStatusListMigrations,
   DataStoreDigitalCredentialMigrations,
+  DataStoreMachineStateMigrations,
 } from './generic'

package/src/migrations/postgres/1708797018115-CreateMachineStateStore.ts

@@ -0,0 +1,29 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+export class CreateMachineStateStore1708797018115 implements MigrationInterface {
+  name = 'CreateMachineStateStore1708797018115'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+            CREATE TABLE "MachineStateInfoEntity" (
+                "instance_id" text NOT NULL,
+                "session_id" text,
+                "latest_state_name" text,
+                "machine_name" text NOT NULL,
+                "latest_event_type" text NOT NULL,
+                "state" text NOT NULL,
+                "created_at" TIMESTAMP NOT NULL DEFAULT now(),
+                "updated_at" TIMESTAMP NOT NULL DEFAULT now(),
+                "updated_count" integer NOT NULL DEFAULT 0,
+                "expires_at" TIMESTAMP,
+                "completed_at" TIMESTAMP,
+                "tenant_id" text,
+                CONSTRAINT "PK_MachineStateInfoEntity_id" PRIMARY KEY ("instance_id")
+            )
+        `)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE "MachineStateInfoEntity"`)
+  }
+}

package/src/migrations/sqlite/1708796002272-CreateMachineStateStore.ts

@@ -0,0 +1,28 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+export class CreateMachineStateStore1708796002272 implements MigrationInterface {
+  name = 'CreateMachineStateStore1708796002272'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+            CREATE TABLE "MachineStateInfoEntity" (
+                "instance_id" varchar PRIMARY KEY NOT NULL,
+                "session_id" varchar,
+                "machine_name" varchar NOT NULL,
+                "latest_state_name" varchar,
+                "latest_event_type" varchar NOT NULL,
+                "state" text NOT NULL,
+                "created_at" datetime NOT NULL DEFAULT (datetime('now')),
+                "updated_at" datetime NOT NULL DEFAULT (datetime('now')),
+                "updated_count" integer NOT NULL DEFAULT 0,
+                "expires_at" datetime,
+                "completed_at" datetime,
+                "tenant_id" varchar
+            )
+        `)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE "MachineStateInfoEntity"`)
+  }
+}

package/src/types/index.ts

@@ -7,3 +7,4 @@ export * from './statusList/statusList'
 export * from './statusList/IAbstractStatusListStore'
 export * from './eventLogger/IAbstractEventLoggerStore'
 export * from './eventLogger/eventLogger'
+export * from './machineState/IAbstractMachineStateStore'

package/src/types/machineState/IAbstractMachineStateStore.ts

@@ -0,0 +1,68 @@
+export type StoreMachineStatePersistArgs = Omit<StoreMachineStateInfo, 'createdAt' | 'updatedAt'>
+
+export type StoreMachineStatesFindActiveArgs = Partial<Pick<StoreMachineStateInfo, 'machineName' | 'tenantId' | 'instanceId'>>
+
+export type FindMachineStatesFilterArgs = Array<Partial<Omit<StoreMachineStateInfo, 'state'>>>
+
+export type StoreFindMachineStatesArgs = {
+  filter: FindMachineStatesFilterArgs
+}
+
+export type StoreMachineStateGetArgs = Pick<StoreMachineStateInfo, 'instanceId' | 'tenantId'>
+
+export type StoreMachineStateDeleteArgs = StoreMachineStateGetArgs
+export type StoreMachineStateDeleteExpiredArgs = { machineName?: string; tenantId?: string; deleteDoneStates?: boolean }
+
+export interface StoreMachineStateInfo {
+  /**
+   * Unique instance ID of the machine
+   */
+  instanceId: string
+
+  /**
+   * Session Id of the machine. Not necessarily unique
+   */
+  sessionId?: string
+
+  /**
+   * Machine name
+   */
+  machineName: string
+
+  /**
+   * The latest state name. Can be empty for a newly initialize machine
+   */
+  latestStateName?: string
+
+  /**
+   * event types like SET_TOC, SET_FIRSTNAME, .... Will be xstate.init on a newly initialized machine
+   */
+  latestEventType: string
+
+  /**
+   * Serialized Machine state
+   */
+  state: string
+
+  /**
+   * Represents the creation date
+   */
+  createdAt: Date
+
+  /**
+   * Represents the expiration date
+   */
+  expiresAt?: Date
+
+  /**
+   * Represents the update date
+   */
+  updatedAt: Date
+
+  /**
+   * Represents a counter for tracking updates.
+   */
+  updatedCount: number
+  completedAt?: Date
+  tenantId?: string
+}