@owlmeans/server-planning 0.1.18-rc.0

package/src/registry.ts

@@ -0,0 +1,143 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { ResilientError } from '@owlmeans/error'
+import { DEFAULT_PLUGIN_ORDER, PlanningRefused } from '@owlmeans/planning'
+import type {
+  CommitEvent, PlanningExecContext, PlanningHookContext, PlanningPlugin, PlanningSchemaRegistry,
+  PlanningStore, TransitionExecution, WorkcardDraft,
+} from '@owlmeans/planning'
+import type { StoreRoute } from './store/types.js'
+
+export interface PluginRegistry {
+  /** Register, or replace the plugin of the same `name`. Its schemas are contributed now. */
+  use: (plugin: PlanningPlugin) => void
+  /** Every plugin, `order` ascending (registration order among equals). */
+  plugins: () => PlanningPlugin[]
+  /** The owning plugins that supply a store, in plugin order, each store resolved once. */
+  routes: (ctx?: BasicContext<BasicConfig>) => StoreRoute[]
+  /** The first owning plugin's store for a type, else `fallback`. */
+  storeFor: (type: string | undefined, fallback: PlanningStore, ctx?: BasicContext<BasicConfig>) => PlanningStore
+  /** The first plugin answering a code wins. */
+  mintCode: (
+    draft: WorkcardDraft, taken: (code: string) => Promise<boolean>, contextOf: (plugin: PlanningPlugin) => PlanningExecContext
+  ) => Promise<string | undefined>
+  /** The `before` chain; answers the execution the chain left. */
+  before: (
+    exec: TransitionExecution, contextOf: (plugin: PlanningPlugin) => PlanningExecContext
+  ) => Promise<TransitionExecution>
+  /** The `after` chain; a failing hook is logged and the chain goes on. */
+  after: (event: CommitEvent, contextOf: (plugin: PlanningPlugin) => PlanningHookContext) => Promise<void>
+  /** Bumps on every `use` — what a cached composite store is keyed by. */
+  version: () => number
+}
+
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : `${error}`
+
+/**
+ * The plugin chain of one planning service.
+ *
+ * Ordering is `order ?? DEFAULT_PLUGIN_ORDER` ascending, lower first; a plugin registered under a
+ * name already present replaces it in place. A store factory is resolved once per plugin object and
+ * handed to `onStore` (the service binds its `committed` there).
+ */
+export const makePluginRegistry = (
+  schemas: PlanningSchemaRegistry, onStore?: (store: PlanningStore) => void
+): PluginRegistry => {
+  const registered: PlanningPlugin[] = []
+  const stores = new WeakMap<PlanningPlugin, PlanningStore>()
+  let version = 0
+
+  const ordered = (): PlanningPlugin[] => registered
+    .map((plugin, index) => ({ plugin, index }))
+    .sort((left, right) => (left.plugin.order ?? DEFAULT_PLUGIN_ORDER) - (right.plugin.order ?? DEFAULT_PLUGIN_ORDER)
+      || left.index - right.index)
+    .map(entry => entry.plugin)
+
+  const storeOf = (plugin: PlanningPlugin, ctx?: BasicContext<BasicConfig>): PlanningStore | undefined => {
+    if (plugin.store == null) {
+      return undefined
+    }
+    let store = stores.get(plugin)
+    if (store == null) {
+      store = typeof plugin.store === 'function' ? plugin.store(ctx as BasicContext<BasicConfig>) : plugin.store
+      stores.set(plugin, store)
+      onStore?.(store)
+    }
+    return store
+  }
+
+  const registry: PluginRegistry = {
+    use: plugin => {
+      const at = registered.findIndex(entry => entry.name === plugin.name)
+      if (at < 0) {
+        registered.push(plugin)
+      } else {
+        registered[at] = plugin
+      }
+      plugin.schemas?.flows?.forEach(schemas.registerFlow)
+      plugin.schemas?.types?.forEach(schemas.registerType)
+      version++
+    },
+
+    plugins: ordered,
+
+    routes: ctx => ordered()
+      .filter(plugin => plugin.owns != null && plugin.store != null)
+      .map(plugin => ({ owns: plugin.owns!, store: storeOf(plugin, ctx)! })),
+
+    storeFor: (type, fallback, ctx) => {
+      if (type == null) {
+        return fallback
+      }
+      const owner = ordered().find(plugin => plugin.store != null && plugin.owns?.(type) === true)
+      return owner == null ? fallback : storeOf(owner, ctx)!
+    },
+
+    mintCode: async (draft, taken, contextOf) => {
+      for (const plugin of ordered()) {
+        if (plugin.mintCode == null) {
+          continue
+        }
+        const code = await plugin.mintCode(draft, taken, contextOf(plugin))
+        if (code != null) {
+          return code
+        }
+      }
+      return undefined
+    },
+
+    before: async (exec, contextOf) => {
+      let current = exec
+      for (const plugin of ordered()) {
+        if (plugin.before == null) {
+          continue
+        }
+        try {
+          current = await plugin.before(current, contextOf(plugin)) ?? current
+        } catch (error) {
+          if (error instanceof ResilientError) {
+            throw error
+          }
+          throw new PlanningRefused(`${plugin.name}:${messageOf(error)}`)
+        }
+      }
+      return current
+    },
+
+    after: async (event, contextOf) => {
+      for (const plugin of ordered()) {
+        if (plugin.after == null) {
+          continue
+        }
+        try {
+          await plugin.after(event, contextOf(plugin))
+        } catch (error) {
+          console.error(`planning: after hook of ${plugin.name} failed on ${event.transition}:`, error)
+        }
+      }
+    },
+
+    version: () => version,
+  }
+
+  return registry
+}

package/src/service.ts

@@ -0,0 +1,157 @@
+import { createLazyService } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { makeSchemaRegistry, PlanningError } from '@owlmeans/planning'
+import type { PlanningService, PlanningStore, Transition, WithPlanningService } from '@owlmeans/planning'
+import { DEFAULT_ALIAS } from './consts.js'
+import { makeStoreFacade } from './facade.js'
+import { makePluginRegistry } from './registry.js'
+import type { PluginRegistry } from './registry.js'
+import { makeCompositeStore } from './store/composite.js'
+import { makeMemoryPlanningStore } from './store/memory.js'
+import type { BindablePlanningStore } from './store/types.js'
+import type { PlanningHostService, PlanningServiceOptions } from './types.js'
+
+export type PlanningServiceApi = Pick<PlanningService, 'use' | 'plugins' | 'schemas' | 'store' | 'for' | 'committed'>
+
+/** What the facade and the executor reach the service through. */
+export interface PlanningRuntime {
+  service: () => PlanningService
+  registry: PluginRegistry
+  options: PlanningServiceOptions
+  context: () => BasicContext<BasicConfig> | undefined
+  /** The composite store reads and commits go through. */
+  reader: () => PlanningStore
+  /** Every distinct store: the default one first, then each plugin's. */
+  stores: () => PlanningStore[]
+}
+
+const contextOf = (service: PlanningService): BasicContext<BasicConfig> | undefined =>
+  (service as Partial<PlanningHostService>).ctx as BasicContext<BasicConfig> | undefined
+
+/**
+ * The service body, without context registration — spread it into a specialised service; `self`
+ * is late-bound for exactly that case.
+ *
+ * A store receives the service's `committed` through its `bind` the first time the service resolves
+ * it, so the store that folds runs the `after` chain in its own process.
+ */
+export const planningServiceApi = (
+  options: PlanningServiceOptions, self: () => PlanningService
+): PlanningServiceApi & { runtime: PlanningRuntime } => {
+  const schemas = makeSchemaRegistry(options.schemas)
+  const bound = new WeakSet<PlanningStore>()
+  const bind = (store: PlanningStore): void => {
+    if (bound.has(store)) {
+      return
+    }
+    bound.add(store)
+    ;(store as BindablePlanningStore).bind?.(async event => { await self().committed(event) })
+  }
+
+  const registry = makePluginRegistry(schemas, bind)
+  const fallback = options.store ?? makeMemoryPlanningStore({ ids: options.ids, now: options.now })
+  bind(fallback)
+
+  let reader: { version: number, store: PlanningStore } | undefined
+
+  const runtime: PlanningRuntime = {
+    service: self,
+    registry,
+    options,
+    context: () => contextOf(self()),
+    reader: () => {
+      if (reader == null || reader.version !== registry.version()) {
+        reader = { version: registry.version(), store: makeCompositeStore(registry.routes(runtime.context()), fallback) }
+      }
+      return reader.store
+    },
+    stores: () => [...new Set([fallback, ...registry.routes(runtime.context()).map(route => route.store)])],
+  }
+
+  options.plugins?.forEach(registry.use)
+
+  return {
+    runtime,
+
+    schemas,
+
+    use: plugin => registry.use(plugin),
+
+    plugins: () => registry.plugins(),
+
+    store: type => registry.storeFor(type, fallback, runtime.context()),
+
+    for: scope => {
+      if (scope?.entityId == null || scope.entityId === '') {
+        throw new PlanningError('malformed:scope-without-entity')
+      }
+      return makeStoreFacade(runtime, scope)
+    },
+
+    committed: async event => {
+      if (options.hooks === false || !registry.plugins().some(plugin => plugin.after != null)) {
+        return
+      }
+      const store = self().store(event.type)
+      let transition: Transition | undefined
+      try {
+        transition = await store.transitions?.get(event.transition) ?? undefined
+      } catch {
+        transition = undefined
+      }
+      const context = runtime.context() as BasicContext<BasicConfig>
+      // The hook acts as this process's service, never as whoever wrote the transition.
+      const facade = self().for({
+        entityId: event.entityId,
+        ...(context?.cfg?.service != null ? { service: context.cfg.service } : {}),
+      })
+
+      await registry.after(event, plugin => ({
+        context, schemas, store, plugin, facade, ...(transition != null ? { transition } : {}),
+      }))
+    },
+  }
+}
+
+export const makePlanningService = (
+  options: PlanningServiceOptions = {}, alias: string = DEFAULT_ALIAS
+): PlanningHostService => {
+  const service: PlanningHostService = createLazyService<PlanningHostService>(
+    alias, planningServiceApi(options, () => service) as unknown as Partial<PlanningHostService>
+  )
+
+  return service
+}
+
+/**
+ * Register the planning service and `context.planning()`.
+ *
+ * The default store's commits and every plugin store's run this service's `after` chain in the
+ * process that folds them; `hooks: false` makes this process fold without running it.
+ */
+export const appendPlanningService = <C extends BasicConfig, T extends BasicContext<C>>(
+  ctx: T, options: PlanningServiceOptions = {}, alias: string = DEFAULT_ALIAS
+): T & WithPlanningService => {
+  const context = ctx as T & WithPlanningService
+
+  context.registerService(makePlanningService(options, alias))
+  context.planning = () => context.service<PlanningHostService>(alias)
+
+  return context
+}
+
+/**
+ * The planning service on a context, registering one with defaults when there is none — the
+ * `ensureRouterService` shape. A plugin package calls it before `use`, from `makeContext`.
+ */
+export const ensurePlanningService = (
+  ctx: BasicContext<any>, alias: string = DEFAULT_ALIAS
+): PlanningService => {
+  if (!ctx.hasService(alias)) {
+    appendPlanningService(ctx, {}, alias)
+  } else if ((ctx as Partial<WithPlanningService>).planning == null && alias === DEFAULT_ALIAS) {
+    (ctx as unknown as WithPlanningService).planning = () => ctx.service<PlanningHostService>(alias)
+  }
+
+  return ctx.service<PlanningHostService>(alias)
+}

package/src/store/commits.ts

@@ -0,0 +1,174 @@
+import { CommitFailed, CommitState, CommitTimeout, DEFAULT_COMMIT_TIMEOUT, WorkcardNotFound } from '@owlmeans/planning'
+import type { CommitEvent, CommitFilter, CommitStatus, Unsubscribe, Workcard } from '@owlmeans/planning'
+import { COMMIT_POLL_LADDER, DEFAULT_COMMIT_MEMORY } from '../consts.js'
+import type { CommitHub, CommitHubOptions } from './types.js'
+
+type Listener = (event: CommitEvent) => void | Promise<void>
+
+const matches = (event: CommitEvent, filter?: CommitFilter): boolean =>
+  filter == null || (
+    (filter.entityId == null || filter.entityId === event.entityId)
+    && (filter.project == null || filter.project === event.project)
+    && (filter.card == null || filter.card === event.card)
+    && (filter.kind == null || filter.kind === event.kind)
+  )
+
+const settled = (state: CommitState): boolean => state !== CommitState.Pending
+
+const failureOf = (transition: string, error?: string): CommitFailed =>
+  new CommitFailed(`${transition}:${error ?? 'unknown'}`)
+
+/**
+ * An in-process commit fan-out with a status lookup.
+ *
+ * It is the `CommitSource` a store answers with: the memory store publishes into it from its fold,
+ * and a durable store feeds it from its own bus (a Redis subscription) while answering `status`
+ * from its transition rows. It never decides anything about a commit — it only delivers events and
+ * waits for them.
+ *
+ * `wait` subscribes FIRST and polls second, so a commit that lands between the two is never
+ * missed; after one immediate poll it climbs `ladder`, which is what answers when the fold
+ * published somewhere this hub does not hear.
+ */
+export const makeCommitHub = (options: CommitHubOptions): CommitHub => {
+  const listeners = new Set<{ listener: Listener, filter?: CommitFilter }>()
+  const memory = new Map<string, CommitEvent>()
+  const remember = options.remember ?? DEFAULT_COMMIT_MEMORY
+  const ladder = options.ladder != null && options.ladder.length > 0 ? options.ladder : COMMIT_POLL_LADDER
+
+  const remembered = (event: CommitEvent): void => {
+    if (!settled(event.state) || remember <= 0) {
+      return
+    }
+    memory.delete(event.transition)
+    memory.set(event.transition, event)
+    while (memory.size > remember) {
+      const oldest = memory.keys().next().value
+      if (oldest == null) {
+        break
+      }
+      memory.delete(oldest)
+    }
+  }
+
+  const hub: CommitHub = {
+    publish: async event => {
+      remembered(event)
+      const targets = [...listeners].filter(entry => matches(event, entry.filter))
+      const results = await Promise.allSettled(targets.map(async entry => await entry.listener(event)))
+      results.forEach(result => {
+        if (result.status === 'rejected') {
+          console.error('planning: commit listener failed:', result.reason)
+        }
+      })
+    },
+
+    recall: transition => memory.get(transition),
+
+    listeners: () => listeners.size,
+
+    subscribe: (listener, filter) => {
+      const entry = { listener, filter }
+      listeners.add(entry)
+
+      const unsubscribe: Unsubscribe = () => { listeners.delete(entry) }
+      return unsubscribe
+    },
+
+    status: async transition => {
+      const found = await options.status(transition)
+      if (found != null) {
+        return found
+      }
+      const event = memory.get(transition)
+      if (event != null) {
+        const status: CommitStatus = { transition, state: event.state, at: event.at }
+        if (event.error != null) {
+          status.error = event.error
+        }
+        if (event.record !== undefined) {
+          status.card = event.record
+        }
+        return status
+      }
+
+      throw new WorkcardNotFound(`transition:${transition}`)
+    },
+
+    wait: async (transition, opts) => {
+      const timeout = opts?.timeout ?? DEFAULT_COMMIT_TIMEOUT
+
+      return await new Promise<Workcard | null>((resolve, reject) => {
+        let done = false
+        let step = 0
+        let poller: ReturnType<typeof setTimeout> | undefined
+        let unsubscribe: Unsubscribe = () => undefined
+
+        const finish = (settle: () => void): void => {
+          if (done) {
+            return
+          }
+          done = true
+          clearTimeout(deadline)
+          clearTimeout(poller)
+          unsubscribe()
+          settle()
+        }
+
+        const committedCard = async (record?: Workcard | null): Promise<Workcard | null> => {
+          if (record !== undefined) {
+            return record
+          }
+          try {
+            return (await hub.status(transition)).card ?? null
+          } catch {
+            return null
+          }
+        }
+
+        const answer = async (state: CommitState, error?: string, record?: Workcard | null): Promise<boolean> => {
+          if (state === CommitState.Committed) {
+            const card = await committedCard(record)
+            finish(() => resolve(card))
+            return true
+          }
+          if (state === CommitState.Failed) {
+            finish(() => reject(failureOf(transition, error)))
+            return true
+          }
+          return false
+        }
+
+        const deadline = setTimeout(() => finish(() => reject(new CommitTimeout(transition))), timeout)
+
+        unsubscribe = hub.subscribe(async event => {
+          if (event.transition === transition) {
+            await answer(event.state, event.error, event.record)
+          }
+        }) as Unsubscribe
+
+        const poll = async (): Promise<void> => {
+          if (done) {
+            return
+          }
+          try {
+            const status = await hub.status(transition)
+            if (await answer(status.state, status.error, status.card)) {
+              return
+            }
+          } catch (error) {
+            finish(() => reject(error))
+            return
+          }
+          if (!done) {
+            poller = setTimeout(() => { void poll() }, ladder[Math.min(step++, ladder.length - 1)])
+          }
+        }
+
+        void poll()
+      })
+    },
+  }
+
+  return hub
+}

package/src/store/composite.ts

@@ -0,0 +1,171 @@
+import { WorkcardNotFound } from '@owlmeans/planning'
+import type {
+  CommitSource, PlanningStore, ProjectionStore, Relationship, RelationshipStore, SpecificationStore,
+  TransitionStore, Unsubscribe, Workcard,
+} from '@owlmeans/planning'
+import { applyQuery } from '@owlmeans/resource'
+import type { Criteria, ListResult } from '@owlmeans/resource'
+import type { CommitHub, StoreRoute } from './types.js'
+
+const firstOf = async <S, T>(
+  stores: S[], read: (store: S) => Promise<T | null | undefined> | undefined
+): Promise<T | null> => {
+  for (const store of stores) {
+    const found = await read(store)
+    if (found != null) {
+      return found
+    }
+  }
+  return null
+}
+
+const sum = async <S>(stores: S[], run: (store: S) => Promise<number>): Promise<number> =>
+  (await Promise.all(stores.map(run))).reduce((total, count) => total + count, 0)
+
+/**
+ * One `PlanningStore` over a default store and the stores plugins OWN.
+ *
+ * Writes that name a type go to the owning store; a read by id asks the default store first and
+ * then each owner; a list whose criteria names one owned type (or several owned by one store) goes
+ * there, and every other list is the default store's — a cross-type query is answered by the
+ * default store alone, never merged. Relationship lists and commit subscriptions span every store.
+ */
+export const makeCompositeStore = (routes: StoreRoute[], fallback: PlanningStore): PlanningStore => {
+  const all = [...new Set([fallback, ...routes.map(route => route.store)])]
+  if (all.length === 1) {
+    return fallback
+  }
+
+  const byType = (type?: string): PlanningStore =>
+    type == null ? fallback : routes.find(route => route.owns(type))?.store ?? fallback
+
+  const byCriteria = (where?: Criteria<Workcard>): PlanningStore => {
+    const type = (where as Record<string, unknown> | undefined)?.type
+    if (typeof type === 'string') {
+      return byType(type)
+    }
+    if (Array.isArray(type) && type.length > 0) {
+      const targets = new Set(type.map(entry => byType(`${entry}`)))
+      return targets.size === 1 ? [...targets][0] : fallback
+    }
+    return fallback
+  }
+
+  const logged = all.filter(store => store.transitions != null)
+  const byCard = async (card: string): Promise<PlanningStore> => {
+    for (const store of logged) {
+      if (await store.transitions!.head(card) > 0) {
+        return store
+      }
+    }
+    return fallback
+  }
+
+  const cards: ProjectionStore = {
+    get: (id, entityId) => firstOf(all, store => store.cards.get(id, entityId)),
+    list: (where, opts) => byCriteria(where).cards.list(where, opts),
+    count: where => byCriteria(where).cards.count(where),
+    summary: (parents, where) => byCriteria(where).cards.summary(parents, where),
+    put: card => byType(card.type).cards.put(card),
+    drop: async (id, entityId) => { await Promise.all(all.map(store => store.cards.drop(id, entityId))) },
+    project: async (card, hint) => { await (await byCard(card)).cards.project(card, hint) },
+    purge: (project, entityId) => sum(all, store => store.cards.purge(project, entityId)),
+  }
+
+  const transitions: TransitionStore | undefined = logged.length === 0 ? undefined : {
+    append: transition => (byType(transition.type).transitions ?? fallback.transitions!).append(transition),
+    get: id => firstOf(logged, store => store.transitions!.get(id)),
+    byKey: (entityId, key) => firstOf(logged, store => store.transitions!.byKey(entityId, key)),
+    list: async (where, opts) => {
+      const store = typeof where.card === 'string' ? await byCard(where.card) : fallback
+      return await (store.transitions ?? logged[0].transitions!).list(where, opts)
+    },
+    nextSeq: async (card, expect) => (await byCard(card)).transitions!.nextSeq(card, expect),
+    head: async card => (await byCard(card)).transitions?.head(card) ?? 0,
+    commit: async (id, commit) => {
+      for (const store of logged) {
+        if (await store.transitions!.get(id) != null) {
+          await store.transitions!.commit(id, commit)
+          return
+        }
+      }
+    },
+    purge: where => sum(logged, store => store.transitions!.purge(where)),
+  }
+
+  const specified = all.filter(store => store.specs != null)
+  const specs: SpecificationStore | undefined = specified.length === 0 ? undefined : {
+    current: (parent, category, entityId) => firstOf(specified, store => store.specs!.current(parent, category, entityId)),
+    list: async (parent, entityId, query) => {
+      for (const store of specified) {
+        const result = await store.specs!.list(parent, entityId, query)
+        if (result.total > 0) {
+          return result
+        }
+      }
+      return { items: [], total: 0 }
+    },
+    revisions: async (id, entityId, limit) => {
+      for (const store of specified) {
+        const result = await store.specs!.revisions(id, entityId, limit)
+        if (result.length > 0) {
+          return result
+        }
+      }
+      return []
+    },
+  }
+
+  const linked = all.filter(store => store.links != null)
+  const links: RelationshipStore | undefined = linked.length === 0 ? undefined : {
+    list: async (where, opts) => {
+      const results = await Promise.all(linked.map(store => store.links!.list(where, { size: 0 })))
+      const items = results.flatMap((result: ListResult<Relationship>) => result.items)
+      return applyQuery(items, undefined, opts)
+    },
+    put: link => (fallback.links ?? linked[0].links!).put(link),
+    drop: where => sum(linked, store => store.links!.drop(where)),
+  }
+
+  const committing = all.filter(store => store.commits != null)
+  const statusStore = async (transition: string): Promise<CommitSource> => {
+    for (const store of committing) {
+      try {
+        await store.commits!.status(transition)
+        return store.commits!
+      } catch {
+        // not this store's transition
+      }
+    }
+    throw new WorkcardNotFound(`transition:${transition}`)
+  }
+
+  const commits: (CommitSource & Pick<CommitHub, 'recall'>) | undefined = committing.length === 0 ? undefined : {
+    status: async transition => await (await statusStore(transition)).status(transition),
+    wait: async (transition, opts) => await (await statusStore(transition)).wait(transition, opts),
+    subscribe: async (listener, filter) => {
+      const releases = await Promise.all(committing.map(store => store.commits!.subscribe(listener, filter)))
+      const unsubscribe: Unsubscribe = () => releases.forEach(release => release())
+      return unsubscribe
+    },
+    recall: transition => {
+      for (const store of committing) {
+        const event = (store.commits as Partial<CommitHub>).recall?.(transition)
+        if (event != null) {
+          return event
+        }
+      }
+      return undefined
+    },
+  }
+
+  return {
+    alias: `composite:${fallback.alias ?? 'default'}`,
+    newId: fallback.newId,
+    cards,
+    ...(transitions != null ? { transitions } : {}),
+    ...(specs != null ? { specs } : {}),
+    ...(links != null ? { links } : {}),
+    ...(commits != null ? { commits } : {}),
+  }
+}