@owlmeans/client-planning 0.1.18-rc.0

package/src/client.ts

@@ -0,0 +1,153 @@
+import { bindAll } from '@owlmeans/client-entrypoint'
+import { createLazyService, MiddlewareStage, MiddlewareType } from '@owlmeans/context'
+import type { EntrypointTree } from '@owlmeans/entrypoint'
+import {
+  DEFAULT_PLUGIN_ORDER, makeSchemaRegistry, PLANNING_SERVICE, PlanningUnsupported,
+} from '@owlmeans/planning'
+import type { PlanningFacade, PlanningPlugin, PlanningSchemaRegistry } from '@owlmeans/planning'
+import { makeRemoteCommitSource } from './commits.js'
+import { makeRemoteFacade } from './facade.js'
+import { planningStoresOf } from './stores.js'
+import type {
+  Config, Context, PlanningClientOptions, PlanningClientService, WithPlanningClient,
+} from './types.js'
+
+/**
+ * The client planning service: a remote facade factory under the SAME alias the server registers
+ * its service under, so `context.planning().for(scope)` is one call on both sides.
+ *
+ * What only a server can do is refused rather than faked: a client runs no middleware and folds
+ * nothing, so `store()`, `committed()` and a plugin carrying hooks or a store answer
+ * `PlanningUnsupported`. A plugin carrying only schemas is accepted — it layers over the server's
+ * bundle.
+ */
+export const makePlanningClientService = <C extends Config, T extends Context<C>>(
+  context: T, options: PlanningClientOptions
+): PlanningClientService => {
+  const registry = makeSchemaRegistry()
+  const plugins: PlanningPlugin[] = []
+  const stores = () => planningStoresOf(context)
+
+  const commits = makeRemoteCommitSource(context, options.protocols, {
+    socket: options.socket, poll: options.poll, timeout: options.timeout, stores,
+  })
+
+  const layerPlugins = (): void => plugins.forEach(plugin => {
+    plugin.schemas?.flows?.forEach(registry.registerFlow)
+    plugin.schemas?.types?.forEach(registry.registerType)
+  })
+
+  let loaded = false
+  let loading: Promise<PlanningSchemaRegistry> | null = null
+
+  const loadSchemas: PlanningClientService['loadSchemas'] = async opts => {
+    if (loaded && opts?.force !== true) {
+      return registry
+    }
+    if (loading == null || opts?.force === true) {
+      const attempt = (async () => {
+        const bundle = await context.entrypoint(options.protocols.schema.list).call({ timeout: options.timeout })
+        registry.load(bundle)
+        layerPlugins()
+        loaded = true
+
+        return registry
+      })()
+      loading = attempt
+      // A failed load is forgotten, so the next caller asks again instead of inheriting the error.
+      attempt.catch(() => {
+        if (loading === attempt) {
+          loading = null
+        }
+      })
+    }
+
+    return await loading
+  }
+
+  const facadeFor = (scope: Parameters<PlanningClientService['for']>[0]): PlanningFacade =>
+    makeRemoteFacade(context, options.protocols, { ...options.scope, ...scope }, {
+      commits, schemas: registry, loadSchemas, timeout: options.timeout, stores,
+    })
+
+  let fallback: PlanningFacade | null = null
+
+  // Lazy, like the server's host: `context.planning()` answers before the context initializes.
+  return createLazyService<PlanningClientService>(PLANNING_SERVICE, {
+    schemas: registry,
+
+    commits,
+
+    loadSchemas,
+
+    use: plugin => {
+      if (plugin.before != null || plugin.after != null || plugin.store != null || plugin.mintCode != null) {
+        throw new PlanningUnsupported(`client:plugin:${plugin.name}`)
+      }
+      const existing = plugins.findIndex(candidate => candidate.name === plugin.name)
+      if (existing >= 0) {
+        plugins.splice(existing, 1)
+      }
+      plugins.push(plugin)
+      plugins.sort((left, right) => (left.order ?? DEFAULT_PLUGIN_ORDER) - (right.order ?? DEFAULT_PLUGIN_ORDER))
+      layerPlugins()
+    },
+
+    plugins: () => [...plugins],
+
+    store: () => {
+      throw new PlanningUnsupported('client:store')
+    },
+
+    for: scope => scope == null ? (fallback ??= facadeFor({})) : facadeFor(scope),
+
+    committed: async () => {
+      throw new PlanningUnsupported('client:committed')
+    },
+
+    close: async () => await commits.close(),
+  })
+}
+
+/**
+ * Wire the planning client into a client context: bind the protocol tree as client entrypoints
+ * (unless `bind: false`), register the service under `PLANNING_SERVICE`, and add
+ * `context.planning()`.
+ *
+ * The tree must be the one the server mounted — the same `makePlanningProtocols` options, alias for
+ * alias. When its commit feed hangs under a `socketBase`, that base belongs to the host and must be
+ * bound by the host too: a parent a registry cannot resolve fails the whole context at init.
+ *
+ * The schema bundle is fetched in the background once the context is READY, and a failure there is
+ * swallowed — a browser that is not signed in yet cannot read it, and a context must not fail over
+ * data it can fetch later. `model()` and `loadSchemas()` load it on first use regardless.
+ */
+export const appendPlanningClient = <C extends Config, T extends Context<C>>(
+  context: T, options: PlanningClientOptions
+): T & WithPlanningClient => {
+  const ctx = context as T & WithPlanningClient
+
+  if (options.bind !== false) {
+    ctx.registerEntrypoints(bindAll(options.protocols as unknown as EntrypointTree))
+  }
+
+  const service = makePlanningClientService<C, T>(context, options)
+  ctx.registerService(service)
+  ctx.planning = () => ctx.service<PlanningClientService>(PLANNING_SERVICE)
+
+  if (options.schemas !== false) {
+    ctx.registerMiddleware({
+      type: MiddlewareType.Context,
+      stage: MiddlewareStage.Ready,
+      apply: async () => {
+        try {
+          await service.loadSchemas()
+        } catch {
+          // Best effort by design — see above.
+        }
+      },
+    })
+  }
+
+  return ctx
+}

package/src/commits.ts

@@ -0,0 +1,247 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import {
+  CommitFailed, CommitState, CommitTimeout, DEFAULT_COMMIT_POLL, DEFAULT_COMMIT_TIMEOUT, MAX_COMMIT_POLL,
+  PLANNING_COMMIT_EVENT, PlanningError, WorkcardKind,
+} from '@owlmeans/planning'
+import type {
+  CommitEvent, CommitFilter, CommitStatus, PlanningProtocols, Unsubscribe, Workcard,
+} from '@owlmeans/planning'
+import type { Connection } from '@owlmeans/socket'
+import { EARLY_POLL_LADDER, EARLY_POLL_MS, LONG_POLL_GRACE } from './consts.js'
+import type { RemoteCommitSource, RemoteCommitSourceOptions } from './types.js'
+import { dropCard, putCard, putCommit } from './utils/record.js'
+
+interface Subscription {
+  listener: (event: CommitEvent) => void | Promise<void>
+  filter?: CommitFilter
+}
+
+const matches = (filter: CommitFilter | undefined, event: CommitEvent): 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 delay = (ms: number): { promise: Promise<void>, cancel: () => void } => {
+  let handle: ReturnType<typeof setTimeout> | undefined
+  const promise = new Promise<void>(resolve => { handle = setTimeout(resolve, Math.max(0, ms)) })
+
+  return { promise, cancel: () => clearTimeout(handle) }
+}
+
+/**
+ * The commit source of a remote facade: the `commit.get` long poll and, when the host injects a
+ * socket opener, the `commit.events` feed.
+ *
+ * `wait` SUBSCRIBES FIRST and only then reads the status — a commit landing between a read and a
+ * subscription would otherwise be missed until the deadline. It then long-polls in holds of
+ * `min(poll, remaining)` seconds, so a client with no socket (a Node connector) still learns of a
+ * commit within one round trip of it landing, and a client with one learns from whichever arrives
+ * first. The deadline is a {@link CommitTimeout}; the transition stays pending — nothing is undone.
+ *
+ * ONE socket serves every subscription of the source; releasing a subscription never closes it.
+ */
+export const makeRemoteCommitSource = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, protocols: PlanningProtocols, opts?: RemoteCommitSourceOptions
+): RemoteCommitSource => {
+  const poll = Math.max(0, Math.min(MAX_COMMIT_POLL, opts?.poll ?? DEFAULT_COMMIT_POLL))
+  const subscriptions = new Set<Subscription>()
+
+  let opening: Promise<Connection | null> | null = null
+  let open: Connection | null = null
+  let detach: (() => void) | null = null
+
+  const dispatch = async (event: CommitEvent): Promise<void> => {
+    for (const subscription of [...subscriptions]) {
+      if (!matches(subscription.filter, event)) {
+        continue
+      }
+      try {
+        await subscription.listener(event)
+      } catch (e) {
+        console.error('Planning commit listener error:', e)
+      }
+    }
+  }
+
+  const socket = async (): Promise<Connection | null> => {
+    const opener = opts?.socket
+    if (opener == null) {
+      return null
+    }
+    opening ??= (async () => {
+      try {
+        const connection = await opener(protocols.commit.events, { query: {} })
+        if (connection == null) {
+          // No socket right now (not signed in yet, say) — the next subscription asks again.
+          opening = null
+          return null
+        }
+        open = connection
+        detach = connection.observe<CommitEvent>(PLANNING_COMMIT_EVENT, async message => {
+          await dispatch(message.payload)
+        })
+        return connection
+      } catch (e) {
+        opening = null
+        console.error('Planning commit socket error:', e)
+        return null
+      }
+    })()
+
+    return await opening
+  }
+
+  const endpoint = () => context.entrypoint(protocols.commit.get)
+
+  const status = async (transition: string): Promise<CommitStatus> => await endpoint().call({
+    params: { transition }, query: { wait: 0 }, timeout: opts?.timeout,
+  })
+
+  const hold = async (transition: string, wait: number, signal: AbortSignal): Promise<CommitStatus> => {
+    try {
+      return await endpoint().call({
+        params: { transition }, query: { wait }, timeout: wait * 1000 + LONG_POLL_GRACE, signal,
+      })
+    } catch (e) {
+      if (signal.aborted || e instanceof PlanningError) {
+        throw e
+      }
+      // A dropped hold (a proxy closing an idle response) is not an answer about the commit: one
+      // non-holding read replaces it, and a failure of THAT is reported.
+      return await status(transition)
+    }
+  }
+
+  /** Fold a settled status into the mirror, when the host registered one. */
+  const fold = async (transition: string, settled: CommitStatus): Promise<void> => {
+    const stores = opts?.stores?.()
+    if (stores == null) {
+      return
+    }
+    const known = await stores.commits.load(transition)
+    await putCommit(stores.commits, {
+      id: transition, state: settled.state, at: settled.at, error: settled.error,
+    })
+    if (settled.state !== CommitState.Committed) {
+      return
+    }
+    if (settled.card != null) {
+      await putCard(stores.cards, settled.card)
+    } else if (settled.card === null && known?.card != null) {
+      await dropCard(stores, known.card, known.kind === WorkcardKind.Project)
+    }
+  }
+
+  const answer = async (transition: string, settled: CommitStatus): Promise<Workcard | null> => {
+    await fold(transition, settled)
+    if (settled.state === CommitState.Failed) {
+      throw new CommitFailed(settled.error ?? transition)
+    }
+
+    return settled.card ?? null
+  }
+
+  const subscribe = async (
+    listener: Subscription['listener'], filter?: CommitFilter
+  ): Promise<Unsubscribe> => {
+    const subscription: Subscription = { listener, filter }
+    subscriptions.add(subscription)
+    await socket()
+
+    return () => { subscriptions.delete(subscription) }
+  }
+
+  const source: RemoteCommitSource = {
+    status,
+
+    subscribe,
+
+    wait: async (transition, waitOpts) => {
+      const deadline = Date.now() + (waitOpts?.timeout ?? DEFAULT_COMMIT_TIMEOUT)
+      // Held in an object: a frame writes it from a callback, which flow analysis cannot see.
+      const frame: { landed: CommitEvent | null } = { landed: null }
+      let wake: () => void = () => { }
+      const unsubscribe = await subscribe(event => {
+        if (event.transition === transition && event.state !== CommitState.Pending) {
+          frame.landed = event
+          wake()
+        }
+      })
+
+      /** A frame says it settled; the status read carries the card when the frame does not. */
+      const fromFrame = async (event: CommitEvent): Promise<Workcard | null> => event.record !== undefined
+        ? await answer(transition, {
+          transition, state: event.state, at: event.at, error: event.error, card: event.record,
+        })
+        : await answer(transition, await status(transition))
+
+      try {
+        let current = await status(transition)
+        let early = 0
+        while (current.state === CommitState.Pending) {
+          if (frame.landed != null) {
+            return await fromFrame(frame.landed)
+          }
+          const remaining = deadline - Date.now()
+          if (remaining <= 0) {
+            throw new CommitTimeout(transition)
+          }
+
+          const wait = Math.min(poll, Math.ceil(remaining / 1000))
+          const abort = new AbortController()
+          const timer = delay(remaining)
+          const framed = new Promise<'frame'>(resolve => { wake = () => resolve('frame') })
+          const started = Date.now()
+          try {
+            const outcome = await Promise.race([
+              hold(transition, wait, abort.signal),
+              framed,
+              timer.promise.then(() => 'deadline' as const),
+            ])
+            if (outcome === 'frame' || outcome === 'deadline') {
+              continue
+            }
+            current = outcome
+          } finally {
+            abort.abort()
+            timer.cancel()
+            wake = () => { }
+          }
+
+          if (current.state === CommitState.Pending && Date.now() - started < EARLY_POLL_MS) {
+            // The server did not hold — pause on a ladder rather than spin until the deadline.
+            const pause = delay(Math.min(
+              EARLY_POLL_LADDER[Math.min(early, EARLY_POLL_LADDER.length - 1)], deadline - Date.now()
+            ))
+            early += 1
+            await Promise.race([pause.promise, new Promise<void>(resolve => { wake = resolve })])
+            pause.cancel()
+            wake = () => { }
+          } else {
+            early = 0
+          }
+        }
+
+        return await answer(transition, current)
+      } finally {
+        unsubscribe()
+      }
+    },
+
+    connected: () => open != null,
+
+    close: async () => {
+      detach?.()
+      detach = null
+      const connection = open
+      open = null
+      opening = null
+      await connection?.close()
+    },
+  }
+
+  return source
+}

package/src/consts.ts

@@ -0,0 +1,38 @@
+import type { Relationship, Workcard } from '@owlmeans/planning'
+import { stateAlias } from '@owlmeans/state'
+import type { StateAlias } from '@owlmeans/state'
+import type { PlanningCommitRecord, PlanningStoreAliases } from './types.js'
+
+/**
+ * The ONE card store. Projects, cards and specifications share an id space on the server, so they
+ * share it here too — a store per kind would let a list reload of one kind drop another's rows.
+ */
+export const CARDS: StateAlias<Workcard> = stateAlias<Workcard>('planning-card-state')
+
+export const LINKS: StateAlias<Relationship> = stateAlias<Relationship>('planning-link-state')
+
+/** What the client has learned about each transition it wrote or saw, keyed by transition id. */
+export const COMMITS: StateAlias<PlanningCommitRecord> = stateAlias<PlanningCommitRecord>('planning-commit-state')
+
+export const DEFAULT_STORE_ALIASES: Readonly<PlanningStoreAliases> = Object.freeze({
+  cards: CARDS,
+  links: LINKS,
+  commits: COMMITS,
+})
+
+/**
+ * How much longer than its own `wait` a long poll's HTTP deadline is, in milliseconds — a held
+ * response must outlast the hold, or every quiet poll reads as a broken connection.
+ */
+export const LONG_POLL_GRACE = 10_000
+
+/**
+ * The pause ladder between polls that came back pending without holding, in milliseconds.
+ *
+ * A server that does not hold (an old deployment, a proxy that answers early) would otherwise be
+ * polled in a tight loop until the deadline.
+ */
+export const EARLY_POLL_LADDER: readonly number[] = Object.freeze([250, 1_000, 2_000])
+
+/** A poll that answered faster than this did not hold. */
+export const EARLY_POLL_MS = 250

package/src/events.ts

@@ -0,0 +1,121 @@
+import { CommitState, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { CommitEvent, PlanningFacade, TransitionReceiptView, Workcard } from '@owlmeans/planning'
+import { syncLinks } from './stores.js'
+import type { PlanningStores } from './types.js'
+import { dropCard, putCard, putCommit } from './utils/record.js'
+
+/**
+ * Fold one commit frame into the mirror.
+ *
+ * - An OLDER `seq` never overwrites a newer record — frames and list answers race.
+ * - A committed `delete` REMOVES the row and every link touching it (and, for a project, the rows
+ *   under it — the server purged them in the same fold).
+ * - A frame for an id the store never saw still writes a row: a card created in another tab
+ *   appears here without waiting for the next list.
+ * - A `failed` commit leaves the card alone; the reason is recorded in the commit store.
+ *
+ * A frame from a cross-process bus carries ids only. When `record` is absent the card is re-read
+ * through `facade`; without one there is nothing to write but the commit itself.
+ */
+export const applyCommitEvent = async (
+  stores: PlanningStores, event: CommitEvent, facade?: PlanningFacade
+): Promise<void> => {
+  const known = await stores.cards.load(event.card)
+
+  await putCommit(stores.commits, {
+    id: event.transition,
+    card: event.card,
+    entityId: event.entityId,
+    project: event.project,
+    kind: event.kind,
+    type: event.type,
+    seq: event.seq,
+    action: event.action,
+    state: event.state,
+    at: event.at,
+    error: event.error,
+  })
+
+  if (event.state === CommitState.Failed) {
+    return
+  }
+  if (event.state === CommitState.Pending) {
+    if (known != null && (known.head ?? known.seq) < event.seq) {
+      await stores.cards.save({ ...known, head: event.seq })
+    }
+    return
+  }
+  if (known != null && known.seq > event.seq) {
+    return
+  }
+
+  if (event.action === TransitionAction.Delete) {
+    await dropCard(stores, event.card, event.kind === WorkcardKind.Project)
+    return
+  }
+
+  const record: Workcard | null | undefined = event.record !== undefined
+    ? event.record
+    : facade != null ? await facade.cards.load(event.card) : undefined
+
+  if (record === null) {
+    // Committed, and gone by the time it was read: a later delete won the race.
+    await dropCard(stores, event.card, event.kind === WorkcardKind.Project)
+  } else if (record !== undefined) {
+    await putCard(stores.cards, record)
+  }
+
+  if (facade != null && (event.action === TransitionAction.Link || event.action === TransitionAction.Unlink)) {
+    const links = await facade.relationships.list({ from: event.card, size: 0 })
+    await syncLinks(stores.links, links.items, { from: event.card })
+  }
+}
+
+/**
+ * Mark a receipt in the mirror the moment the server answers it.
+ *
+ * A pending transition raises the card's `head` to its `seq`, so `head > seq` — the model's
+ * `pending()` — is true before any frame arrives. A receipt that already carries the committed
+ * card writes it; a committed delete drops the row.
+ */
+export const applyReceipt = async (stores: PlanningStores, receipt: TransitionReceiptView): Promise<void> => {
+  const { transition } = receipt
+  if (transition.id != null) {
+    await putCommit(stores.commits, {
+      id: transition.id,
+      card: transition.card,
+      entityId: transition.entityId,
+      project: transition.project,
+      kind: transition.kind,
+      type: transition.type,
+      seq: transition.seq,
+      action: transition.action,
+      state: transition.commit.state,
+      at: transition.commit.at,
+      error: transition.commit.error,
+    })
+  }
+  if (transition.commit.state === CommitState.Failed) {
+    return
+  }
+  if (transition.commit.state === CommitState.Committed && transition.action === TransitionAction.Delete) {
+    await dropCard(stores, transition.card, transition.kind === WorkcardKind.Project)
+    return
+  }
+  if (receipt.card != null) {
+    await putCard(stores.cards, receipt.card)
+    return
+  }
+
+  const known = await stores.cards.load(transition.card)
+  if (known != null && (known.head ?? known.seq) < transition.seq) {
+    await stores.cards.save({ ...known, head: transition.seq })
+  }
+}
+
+/** Write cards the caller read on its own, under the same newer-fold-wins rule as a commit. */
+export const applyCards = async (stores: Pick<PlanningStores, 'cards'>, cards: Workcard[]): Promise<void> => {
+  for (const card of cards) {
+    await putCard(stores.cards, card)
+  }
+}