@xyo-network/bridge-abstract 2.102.0

package/src/AbstractModuleProxy/AbstractModuleProxy.ts

@@ -0,0 +1,268 @@
+import { assertEx } from '@xylabs/assert'
+import { forget } from '@xylabs/forget'
+import { Address, asAddress } from '@xylabs/hex'
+import { compact } from '@xylabs/lodash'
+import { toJsonString } from '@xylabs/object'
+import { AccountInstance } from '@xyo-network/account-model'
+import { ArchivistInstance } from '@xyo-network/archivist-model'
+import { QueryBoundWitness } from '@xyo-network/boundwitness-model'
+import { BoundWitnessWrapper, QueryBoundWitnessWrapper } from '@xyo-network/boundwitness-wrapper'
+import { QuerySendFinishedEventArgs, QuerySendStartedEventArgs } from '@xyo-network/bridge-model'
+import { ModuleManifestPayload, ModuleManifestPayloadSchema, NodeManifestPayload, NodeManifestPayloadSchema } from '@xyo-network/manifest-model'
+import { AbstractModuleInstance } from '@xyo-network/module-abstract'
+import {
+  AddressPreviousHashPayload,
+  AddressPreviousHashSchema,
+  ArchivingModuleConfig,
+  DeadModuleError,
+  Module,
+  ModuleAddressQuery,
+  ModuleAddressQuerySchema,
+  ModuleConfigSchema,
+  ModuleInstance,
+  ModuleManifestQuery,
+  ModuleManifestQuerySchema,
+  ModuleName,
+  ModuleParams,
+  ModuleQueryHandlerResult,
+  ModuleQueryResult,
+  ModuleResolver,
+  ModuleStateQuerySchema,
+} from '@xyo-network/module-model'
+import { ModuleWrapper } from '@xyo-network/module-wrapper'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import { isPayloadOfSchemaType, ModuleError, ModuleErrorSchema, Payload, WithMeta } from '@xyo-network/payload-model'
+import { QueryPayload, QuerySchema } from '@xyo-network/query-payload-plugin'
+import { LRUCache } from 'lru-cache'
+
+import { ModuleProxyResolver } from './ModuleProxyResolver'
+
+export type ModuleProxyParams = ModuleParams<
+  {
+    schema: ModuleConfigSchema
+  },
+  {
+    account: AccountInstance
+    archiving?: ArchivingModuleConfig['archiving'] & { resolveArchivists: () => Promise<ArchivistInstance[]> }
+    host: ModuleResolver
+    moduleAddress: Address
+    onQuerySendFinished?: (args: Omit<QuerySendFinishedEventArgs, 'module'>) => void
+    onQuerySendStarted?: (args: Omit<QuerySendStartedEventArgs, 'module'>) => void
+  }
+>
+
+export abstract class AbstractModuleProxy<
+    TWrappedModule extends ModuleInstance = ModuleInstance,
+    TParams extends Omit<ModuleProxyParams, 'config'> & { config: TWrappedModule['config'] } = Omit<ModuleProxyParams, 'config'> & {
+      config: TWrappedModule['config']
+    },
+  >
+  extends AbstractModuleInstance<TParams, TWrappedModule['eventData']>
+  implements ModuleInstance<TParams, TWrappedModule['eventData']>
+{
+  static requiredQueries: string[] = [ModuleStateQuerySchema]
+
+  protected _config?: ModuleInstance['config']
+  protected _publicChildren?: ModuleInstance[]
+  protected _state: Payload[] | undefined = undefined
+  protected _stateInProcess = false
+
+  private _spamTrap = new LRUCache<string, number>({ max: 1000, ttl: 1000 * 60, ttlAutopurge: true })
+
+  constructor(params: TParams) {
+    params.addToResolvers = false
+    super(AbstractModuleProxy.privateConstructorKey, params, params.account)
+  }
+
+  override get address() {
+    return this.params.moduleAddress
+  }
+
+  override get archiving(): ArchivingModuleConfig['archiving'] | undefined {
+    return this.params?.archiving
+  }
+
+  override get config() {
+    return assertEx(this._config, () => 'Config not set')
+  }
+
+  override get queries(): string[] {
+    const queryPayloads = assertEx(this._state, () => 'Module state not found.  Make sure proxy has been started').filter((item) =>
+      isPayloadOfSchemaType<QueryPayload>(QuerySchema)(item),
+    ) as QueryPayload[]
+    return queryPayloads.map((payload) => payload.query)
+  }
+
+  protected override get _queryAccountPaths() {
+    return this._baseModuleQueryAccountPaths
+  }
+
+  static hasRequiredQueries(module: Module) {
+    return this.missingRequiredQueries(module).length === 0
+  }
+
+  static missingRequiredQueries(module: Module): string[] {
+    const moduleQueries = module.queries
+    return compact(
+      this.requiredQueries.map((query) => {
+        return moduleQueries.includes(query) ? null : query
+      }),
+    )
+  }
+
+  async addressPreviousHash(): Promise<AddressPreviousHashPayload> {
+    const queryPayload: ModuleAddressQuery = { schema: ModuleAddressQuerySchema }
+    const result: AddressPreviousHashPayload = assertEx(
+      (await this.sendQuery(queryPayload, undefined, this.account)).find(
+        isPayloadOfSchemaType<AddressPreviousHashPayload>(AddressPreviousHashSchema),
+      ) as WithMeta<AddressPreviousHashPayload>,
+      () => 'Result did not include correct payload',
+    )
+    return result
+  }
+
+  childAddressByName(name: ModuleName): Address | undefined {
+    const nodeManifests = this._state?.filter(isPayloadOfSchemaType<NodeManifestPayload>(NodeManifestPayloadSchema))
+    const childPairs = nodeManifests?.flatMap((nodeManifest) => Object.entries(nodeManifest.status?.children ?? {}) as [Address, ModuleName | null][])
+    return asAddress(childPairs?.find(([_, childName]) => childName === name)?.[0])
+  }
+
+  async childAddressMap(): Promise<Record<Address, ModuleName | null>> {
+    const state = await this.state()
+    const result: Record<Address, ModuleName | null> = {}
+    const nodeManifests = state.filter(isPayloadOfSchemaType<NodeManifestPayload>(NodeManifestPayloadSchema))
+    for (const manifest of nodeManifests) {
+      const children = manifest.modules?.public ?? []
+      for (const child of children) {
+        if (typeof child === 'object') {
+          const address = child.status?.address
+          if (address) {
+            result[address] = child.config.name ?? null
+          }
+        }
+      }
+    }
+    return result
+  }
+
+  override async manifest(maxDepth?: number): Promise<ModuleManifestPayload> {
+    const queryPayload: ModuleManifestQuery = { schema: ModuleManifestQuerySchema, ...(maxDepth === undefined ? {} : { maxDepth }) }
+    return (await this.sendQuery(queryPayload))[0] as WithMeta<ModuleManifestPayload>
+  }
+
+  override async moduleAddress(): Promise<AddressPreviousHashPayload[]> {
+    const queryPayload: ModuleAddressQuery = { schema: ModuleAddressQuerySchema }
+    return (await this.sendQuery(queryPayload)) as WithMeta<AddressPreviousHashPayload>[]
+  }
+
+  override async previousHash(): Promise<string | undefined> {
+    const queryPayload: ModuleAddressQuery = { schema: ModuleAddressQuerySchema }
+    return ((await this.sendQuery(queryPayload)).pop() as WithMeta<AddressPreviousHashPayload>).previousHash
+  }
+
+  override async publicChildren() {
+    this._publicChildren = this._publicChildren ?? (await super.publicChildren())
+    return this._publicChildren
+  }
+
+  override async query<T extends QueryBoundWitness = QueryBoundWitness>(query: T, payloads?: Payload[]): Promise<ModuleQueryResult> {
+    this._checkDead()
+    return await this.busy(async () => {
+      try {
+        await this.checkSpam(query)
+        this.params.onQuerySendStarted?.({ payloads, query })
+        const result = await this.proxyQueryHandler<T>(query, payloads)
+        this.params.onQuerySendFinished?.({ payloads, query, result, status: 'success' })
+        if (this.archiving && this.isAllowedArchivingQuery(query.schema)) {
+          forget(this.storeToArchivists(result.flat()))
+        }
+        forget(this.emit('moduleQueried', { module: this, payloads, query, result }))
+        return result
+      } catch (ex) {
+        this.params.onQuerySendFinished?.({ payloads, query, status: 'failure' })
+        const error = ex as Error
+        this._lastError = error
+        //this.status = 'dead'
+        const deadError = new DeadModuleError(this.address, error)
+        const errorPayload: ModuleError = {
+          message: deadError.message,
+          name: deadError.name,
+          schema: ModuleErrorSchema,
+        }
+        const sourceQuery = await PayloadBuilder.build(assertEx(QueryBoundWitnessWrapper.unwrap(query), () => 'Invalid query'))
+        return await this.bindQueryResult(sourceQuery, [], undefined, [errorPayload])
+      }
+    })
+  }
+
+  override queryHandler<T extends QueryBoundWitness = QueryBoundWitness>(
+    _query: T,
+    _payloads?: Payload[],
+    _queryConfig?: TWrappedModule['params']['config'],
+  ): Promise<ModuleQueryHandlerResult> {
+    throw new Error('queryHandler should never be called')
+  }
+
+  override async queryable<T extends QueryBoundWitness = QueryBoundWitness>(
+    _query: T,
+    _payloads?: Payload[],
+    _queryConfig?: TWrappedModule['params']['config'],
+  ): Promise<boolean> {
+    return await Promise.resolve(true)
+  }
+
+  override async resolveArchivingArchivists(): Promise<ArchivistInstance[]> {
+    return (await this.params.archiving?.resolveArchivists()) ?? []
+  }
+
+  setConfig(config: TWrappedModule['params']['config']) {
+    this._config = config
+  }
+
+  override async startHandler(): Promise<boolean> {
+    const state = await this.state()
+    const manifestPayload = state.find(
+      (payload) => isPayloadOfSchemaType(NodeManifestPayloadSchema)(payload) || isPayloadOfSchemaType(ModuleManifestPayloadSchema)(payload),
+    ) as ModuleManifestPayload
+    const manifest = assertEx(manifestPayload, () => "Can't find manifest payload")
+    this.setConfig({ ...manifest.config })
+    this.downResolver.addResolver(
+      new ModuleProxyResolver({
+        childAddressMap: await this.childAddressMap(),
+        host: this.params.host,
+        module: this,
+        moduleIdentifierTransformers: this.params.moduleIdentifierTransformers,
+      }),
+    )
+    return await super.startHandler()
+  }
+
+  override async state(): Promise<Payload[]> {
+    if (this._state === undefined) {
+      //temporarily add ModuleStateQuerySchema to the schema list so we can wrap it and get the real query list
+      const stateQueryPayload: QueryPayload = { query: ModuleStateQuerySchema, schema: QuerySchema }
+      const manifestQueryPayload: QueryPayload = { query: ModuleManifestQuerySchema, schema: QuerySchema }
+      this._state = [stateQueryPayload, manifestQueryPayload]
+      const wrapper = ModuleWrapper.wrap(this, this.account)
+      this._state = await wrapper.state()
+    }
+    return this._state
+  }
+
+  protected async filterErrors(result: ModuleQueryResult): Promise<ModuleError[]> {
+    const wrapper = await BoundWitnessWrapper.wrap(result[0], result[1])
+    return wrapper.payloadsBySchema<WithMeta<ModuleError>>(ModuleErrorSchema)
+  }
+
+  //this checks and warns if we are getting spammed by the same query
+  private async checkSpam(query: QueryBoundWitness) {
+    const hash = await PayloadBuilder.hash(query)
+    const previousCount = this._spamTrap.get(hash) ?? 0
+    if (previousCount > 0) {
+      this.logger?.warn(`Spam trap triggered for query: ${hash} from ${toJsonString(query.addresses)}`)
+    }
+    this._spamTrap.set(hash, previousCount + 1)
+  }
+
+  abstract proxyQueryHandler<T extends QueryBoundWitness = QueryBoundWitness>(query: T, payloads?: Payload[]): Promise<ModuleQueryResult>
+}

package/src/AbstractModuleProxy/ModuleProxyResolver.ts

@@ -0,0 +1,143 @@
+import { assertEx } from '@xylabs/assert'
+import { exists } from '@xylabs/exists'
+import { Address } from '@xylabs/hex'
+import { Promisable } from '@xylabs/promise'
+import { Account } from '@xyo-network/account'
+import {
+  isAddressModuleFilter,
+  isNameModuleFilter,
+  ModuleFilter,
+  ModuleFilterOptions,
+  ModuleIdentifier,
+  ModuleIdentifierTransformer,
+  ModuleInstance,
+  ModuleName,
+  ModuleResolver,
+  ModuleResolverInstance,
+  ObjectFilterOptions,
+  ObjectResolverPriority,
+} from '@xyo-network/module-model'
+import { CompositeModuleResolver } from '@xyo-network/module-resolver'
+
+import { wrapModuleWithType } from '../wrapModuleWithType'
+
+export interface ModuleProxyResolverOptions {
+  childAddressMap: Record<Address, ModuleName | null>
+  host: ModuleResolver
+  module: ModuleInstance
+  moduleIdentifierTransformers?: ModuleIdentifierTransformer[]
+}
+
+export class ModuleProxyResolver<T extends ModuleProxyResolverOptions = ModuleProxyResolverOptions> implements ModuleResolverInstance {
+  private downResolver: CompositeModuleResolver
+
+  constructor(private options: T) {
+    this.downResolver = new CompositeModuleResolver({ moduleIdentifierTransformers: options.moduleIdentifierTransformers, root: this.root })
+  }
+
+  get priority() {
+    return ObjectResolverPriority.VeryLow
+  }
+
+  get root() {
+    return this.options.module
+  }
+
+  protected get childAddressMap() {
+    return this.options.childAddressMap
+  }
+
+  protected get host() {
+    return this.options.host
+  }
+
+  protected get module() {
+    return this.options.module
+  }
+
+  addResolver(_resolver: ModuleResolver): this {
+    throw new Error('Not supported')
+  }
+
+  removeResolver(_resolver: ModuleResolver): this {
+    throw new Error('Not supported')
+  }
+
+  /** @deprecated do not pass undefined.  If trying to get all, pass '*' */
+  async resolve(): Promise<ModuleInstance[]>
+  async resolve<T extends ModuleInstance = ModuleInstance>(all: '*', options?: ModuleFilterOptions<T>): Promise<T[]>
+  async resolve<T extends ModuleInstance = ModuleInstance>(filter: ModuleFilter<T>, options?: ModuleFilterOptions<T>): Promise<T[]>
+  async resolve<T extends ModuleInstance = ModuleInstance>(id: ModuleIdentifier, options?: ModuleFilterOptions<T>): Promise<T | undefined>
+  /** @deprecated use '*' if trying to resolve all */
+  async resolve<T extends ModuleInstance = ModuleInstance>(filter?: ModuleFilter<T>, options?: ModuleFilterOptions<T>): Promise<T[]>
+  async resolve<T extends ModuleInstance = ModuleInstance>(
+    idOrFilter: ModuleFilter<T> | ModuleIdentifier = '*',
+    options?: ModuleFilterOptions<T>,
+  ): Promise<T | T[] | undefined> {
+    //console.log(`childAddressMap: ${toJsonString(this.childAddressMap, 10)}`)
+    const direction = options?.direction ?? 'all'
+    if (idOrFilter === '*') {
+      //get all the child addresses.  if they have been resolved before, they should be in downResolver
+      const childAddresses = Object.keys(this.childAddressMap)
+      const resolvedChildren = await Promise.all(childAddresses.map<Promise<T | undefined>>((address) => this.resolve<T>(address, options)))
+      return resolvedChildren.filter(exists)
+    } else if (typeof idOrFilter === 'string') {
+      const idParts = idOrFilter.split(':')
+      const firstPart: ModuleIdentifier = assertEx(idParts.shift(), () => 'Invalid module identifier at first position')
+      const firstPartAddress = await this.resolveIdentifier(firstPart)
+      if (firstPartAddress) {
+        const remainingParts = idParts.length > 0 ? idParts.join(':') : undefined
+        if (direction === 'down' || direction === 'all') {
+          const downResolverModule = await this.downResolver.resolve<T>(firstPartAddress)
+          if (downResolverModule) {
+            return remainingParts ? downResolverModule.resolve(remainingParts, options) : downResolverModule
+          }
+          //if it is a known child, create a proxy
+          const addressToProxy =
+            Object.keys(this.childAddressMap).includes(firstPartAddress as Address) ?
+              (firstPartAddress as Address)
+            : (Object.entries(this.childAddressMap).find(([_, value]) => value === firstPartAddress)?.[0] as Address | undefined)
+          if (addressToProxy) {
+            const proxy = await this.host.resolve(addressToProxy, { ...options, direction: 'down' })
+            if (proxy) {
+              const wrapped = wrapModuleWithType(proxy, Account.randomSync()) as unknown as T
+              return remainingParts ? wrapped?.resolve(remainingParts, options) : wrapped
+            }
+            return
+          }
+        }
+      }
+      return
+    } else {
+      const filter = idOrFilter
+      if (isAddressModuleFilter(filter)) {
+        const results = (await Promise.all(filter.address.map((item) => this.resolve(item, options)))).filter(exists)
+        return results
+      } else if (isNameModuleFilter(filter)) {
+        return (await Promise.all(filter.name.map((item) => this.resolve(item, options)))).filter(exists)
+      }
+    }
+  }
+
+  resolveIdentifier(id: ModuleIdentifier, _options?: ObjectFilterOptions): Promisable<Address | undefined> {
+    //check if any of the modules have the id as an address
+    if (this.childAddressMap[id as Address]) {
+      return id as Address
+    }
+
+    //check if id is a name of one of modules in the resolver
+    const addressFromName = Object.entries(this.childAddressMap).find(([, name]) => name === id)?.[0] as Address | undefined
+    if (addressFromName) {
+      return addressFromName
+    }
+  }
+
+  async resolvePrivate<T extends ModuleInstance = ModuleInstance>(all: '*', options?: ObjectFilterOptions<T>): Promise<T[]>
+  async resolvePrivate<T extends ModuleInstance = ModuleInstance>(id: ModuleIdentifier, options?: ObjectFilterOptions<T>): Promise<T | undefined>
+  async resolvePrivate<T extends ModuleInstance = ModuleInstance>(
+    id: ModuleIdentifier,
+    _options?: ObjectFilterOptions<T>,
+  ): Promise<T | T[] | undefined> {
+    if (id === '*') return await Promise.resolve([])
+  }
+}

package/src/AbstractModuleProxy/index.ts

@@ -0,0 +1,2 @@
+export * from './AbstractModuleProxy'
+export * from './ModuleProxyResolver'

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './AbstractBridge'
+export * from './AbstractBridgeModuleResolver'
+export * from './AbstractModuleProxy'
+export * from './wrapModuleWithType'

package/src/wrapModuleWithType.ts

@@ -0,0 +1,32 @@
+import { AccountInstance } from '@xyo-network/account-model'
+import { isArchivistModule } from '@xyo-network/archivist-model'
+import { ArchivistWrapper } from '@xyo-network/archivist-wrapper'
+import { isDivinerModule } from '@xyo-network/diviner-model'
+import { DivinerWrapper } from '@xyo-network/diviner-wrapper'
+import { Module } from '@xyo-network/module-model'
+import { ModuleWrapper } from '@xyo-network/module-wrapper'
+import { isNodeModule } from '@xyo-network/node-model'
+import { NodeWrapper } from '@xyo-network/node-wrapper'
+import { isSentinelModule } from '@xyo-network/sentinel-model'
+import { SentinelWrapper } from '@xyo-network/sentinel-wrapper'
+import { isWitnessModule } from '@xyo-network/witness-model'
+import { WitnessWrapper } from '@xyo-network/witness-wrapper'
+
+export const wrapModuleWithType = (module: Module, account: AccountInstance): ModuleWrapper => {
+  if (isArchivistModule(module)) {
+    return ArchivistWrapper.wrap(module, account)
+  }
+  if (isDivinerModule(module)) {
+    return DivinerWrapper.wrap(module, account)
+  }
+  if (isNodeModule(module)) {
+    return NodeWrapper.wrap(module, account)
+  }
+  if (isSentinelModule(module)) {
+    return SentinelWrapper.wrap(module, account)
+  }
+  if (isWitnessModule(module)) {
+    return WitnessWrapper.wrap(module, account)
+  }
+  throw 'Failed to wrap'
+}

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["src/index.ts"],
+  "tsconfig": "./tsconfig.typedoc.json"
+}