@owlmeans/server-planning 0.1.18-rc.2 → 0.1.18-rc.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-planning",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.21",
   "license": "MIT",
   "description": "The general planning implementation — the planning service and its plugin/middleware registry, the transition executor, the in-memory store, the protocol handlers and the commit feed.",
   "type": "module",
@@ -34,24 +34,32 @@
       "default": "./build/queue/index.js",
       "module": "./build/queue/index.js",
       "types": "./build/queue/index.d.ts"
+    },
+    "./conformance": {
+      "import": "./build/conformance/index.js",
+      "require": "./build/conformance/index.js",
+      "default": "./build/conformance/index.js",
+      "module": "./build/conformance/index.js",
+      "types": "./build/conformance/index.d.ts"
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.28",
-    "@owlmeans/auth-common": "^0.1.18-rc.30",
-    "@owlmeans/basic-ids": "^0.1.18-rc.27",
-    "@owlmeans/context": "^0.1.18-rc.26",
-    "@owlmeans/entrypoint": "^0.1.18-rc.29",
-    "@owlmeans/error": "^0.1.18-rc.28",
-    "@owlmeans/planning": "^0.1.18-rc.2",
-    "@owlmeans/queue": "^0.1.18-rc.24",
-    "@owlmeans/resource": "^0.1.18-rc.28",
-    "@owlmeans/route": "^0.1.18-rc.27",
-    "@owlmeans/server-api": "^0.1.18-rc.34",
-    "@owlmeans/server-context": "^0.1.18-rc.29",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.28",
-    "@owlmeans/server-socket": "^0.1.18-rc.36",
-    "@owlmeans/socket": "^0.1.18-rc.26"
+    "@owlmeans/auth": "^0.1.18-rc.39",
+    "@owlmeans/auth-common": "^0.1.18-rc.46",
+    "@owlmeans/basic-ids": "^0.1.18-rc.36",
+    "@owlmeans/context": "^0.1.18-rc.33",
+    "@owlmeans/entrypoint": "^0.1.18-rc.40",
+    "@owlmeans/error": "^0.1.18-rc.37",
+    "@owlmeans/planning": "^0.1.18-rc.18",
+    "@owlmeans/queue": "^0.1.18-rc.40",
+    "@owlmeans/resource": "^0.1.18-rc.39",
+    "@owlmeans/log": "^0.1.18-rc.1",
+    "@owlmeans/route": "^0.1.18-rc.34",
+    "@owlmeans/server-api": "^0.1.18-rc.50",
+    "@owlmeans/server-context": "^0.1.18-rc.42",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.39",
+    "@owlmeans/server-socket": "^0.1.18-rc.53",
+    "@owlmeans/socket": "^0.1.18-rc.39"
   },
   "peerDependencies": {
     "ajv": "*",
@@ -59,10 +67,10 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test": "^0.1.18-rc.26",
-    "@types/bun": "^1.4.0",
-    "@types/node": "^26.1.0",
-    "ajv": "^8.17.1",
+    "@owlmeans/test": "^0.1.18-rc.34",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.4",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"

package/src/actions/cards.ts

@@ -1,12 +1,8 @@
 import { handlers } from '@owlmeans/server-api'
-import {
-  decodeSpecificationQuery, decodeSummaryQuery, decodeTransitionQuery, decodeWorkcardQuery,
-} from '@owlmeans/planning'
-import type { PlanningProtocols } from '@owlmeans/planning'
+import { decodeSpecificationQuery, decodeSummaryQuery, decodeTransitionQuery, decodeWorkcardQuery, type PlanningProtocols } from '@owlmeans/planning'
 import type { Context, PlanningHandlerOptions } from '../types.js'
 import { concealed, handlerFacade } from '../utils/index.js'
-
-type RequestHandler = ReturnType<ReturnType<typeof handlers<Context>>['request']>
+import type { RequestHandler } from './types.js'
 
 /** Cards of the caller's entity; the query arrives in its wire shape and is decoded here. */
 export const listCards = (protocol: PlanningProtocols['card']['list'], opts?: PlanningHandlerOptions): RequestHandler =>

package/src/actions/execute.ts

@@ -1,23 +1,30 @@
 import { handlers } from '@owlmeans/server-api'
-import { DEFAULT_COMMIT_TIMEOUT, MAX_COMMIT_POLL, TransitionAction } from '@owlmeans/planning'
+import {
+  DEFAULT_COMMIT_TIMEOUT, isProject, isSpecification, MAX_COMMIT_POLL, normalizeParents, PlanningForbidden,
+  TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
 import type {
-  ExecuteOptions, ExecuteRequest, PlanningProtocols, PlanningScope, TransitionExecution, TransitionReceiptView,
+  ExecuteOptions, ExecuteRequest, PlanningFacade, PlanningProtocols, PlanningScope, TransitionExecution,
+  TransitionReceiptView, Workcard,
 } from '@owlmeans/planning'
-import type { Context, PlanningHandlerOptions } from '../types.js'
-import { concealed, handlerFacade } from '../utils/index.js'
+import { withCreator } from '../executor/creator.js'
+import type { Context, PlanningAccess, PlanningHandlerOptions } from '../types.js'
+import { assertGranted, concealed, handlerScopeOf, writableIn } from '../utils/index.js'
 
 /**
  * What a wire execution may say. `actor` is dropped — the scope names the writer — and a create's
- * `createdBy` is the authenticated subject, whatever the body claimed.
+ * `createdBy` claim is dropped too: the executor's {@link withCreator} stamps the authenticated
+ * subject, the same rule an in-process create follows. Applied here as well, so the returned
+ * execution already carries it. A `createdBy` in `changes` or `unset` is not dropped: the executor
+ * refuses it on every action (`assertCreatorFixed`), so no body moves an owner.
  */
 export const wireExecution = (body: ExecuteRequest, scope: PlanningScope): TransitionExecution => {
   const { wait: _wait, timeout: _timeout, actor: _actor, ...exec } = body
   if (exec.action === TransitionAction.Create && exec.card != null && typeof exec.card === 'object') {
     const { createdBy: _createdBy, ...draft } = exec.card
-    const subject = scope.profileId ?? scope.userId
-    exec.card = subject != null ? { ...draft, createdBy: subject } : draft
+    exec.card = draft
   }
-  return exec
+  return withCreator(exec, scope)
 }
 
 /** `wait`/`timeout` as a server grants them: the timeout never holds a request past `maxPoll`. */
@@ -30,16 +37,92 @@ export const executeOptionsOf = (body: Pick<ExecuteRequest, 'wait' | 'timeout'>,
   return { wait: true, timeout: Math.min(Number.isFinite(asked) && asked > 0 ? asked : DEFAULT_COMMIT_TIMEOUT, ceiling) }
 }
 
+/**
+ * Refuse an execution outside the access's `writes`: the card it acts on (a specification through
+ * its parent card), or every parent a create names, must be one {@link writableIn} admits. A create
+ * of a project is `grants.createProjects`' alone. A card or parent this scope cannot see is left to
+ * the executor, which answers it as absent.
+ *
+ * @throws {PlanningForbidden}
+ */
+export const assertExecutionWrites = async (
+  facade: PlanningFacade, exec: TransitionExecution, access?: PlanningAccess
+): Promise<void> => {
+  if (access?.writes == null) {
+    return
+  }
+  const admitted = async (card: Workcard): Promise<boolean> => {
+    if (writableIn(access, card)) {
+      return true
+    }
+    if (!isSpecification(card) || card.parent == null) {
+      return false
+    }
+    const parent = await facade.cards.load(card.parent)
+    return parent == null || writableIn(access, parent)
+  }
+
+  if (exec.action === TransitionAction.Create && exec.card != null && typeof exec.card === 'object') {
+    if (exec.card.kind === WorkcardKind.Project) {
+      return
+    }
+    const parents = normalizeParents(exec.card.parent, exec.card.parents)
+    if (parents.length === 0) {
+      throw new PlanningForbidden('writes:root')
+    }
+    for (const id of parents) {
+      const parent = await facade.cards.load(id)
+      if (parent != null && !await admitted(parent)) {
+        throw new PlanningForbidden(`writes:${id}`)
+      }
+    }
+    return
+  }
+  if (typeof exec.card === 'string' && exec.card !== '') {
+    const card = await facade.cards.load(exec.card)
+    if (card != null && !await admitted(card)) {
+      throw new PlanningForbidden(`writes:${exec.card}`)
+    }
+  }
+}
+
+/**
+ * The access a wire execution needs. `writes` first ({@link assertExecutionWrites}); then the
+ * grants: `createProjects` for a project create (its primary parent, or the root),
+ * `deleteProjects` for the delete of a project card. A card this scope cannot see is left to the
+ * executor, which answers it as absent.
+ *
+ * @throws {PlanningForbidden}
+ */
+export const assertExecutionGranted = async (
+  facade: PlanningFacade, exec: TransitionExecution, access?: PlanningAccess
+): Promise<void> => {
+  await assertExecutionWrites(facade, exec, access)
+  if (access?.grants == null) {
+    return
+  }
+  if (exec.action === TransitionAction.Create && typeof exec.card === 'object' && exec.card?.kind === WorkcardKind.Project) {
+    assertGranted(access, 'createProjects', normalizeParents(exec.card.parent, exec.card.parents)[0])
+    return
+  }
+  if (exec.action === TransitionAction.Delete && typeof exec.card === 'string') {
+    const card = await facade.cards.load(exec.card)
+    if (card != null && isProject(card)) {
+      assertGranted(access, 'deleteProjects', card.id)
+    }
+  }
+}
+
 /** The one write route. */
 export const executePlanning = (
   protocol: PlanningProtocols['execute'], opts?: PlanningHandlerOptions
 ): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
   handlers<Context>().request(protocol, async (req, ctx) => concealed(async (): Promise<TransitionReceiptView> => {
-    const facade = await handlerFacade(ctx, req, opts)
+    const { facade, access } = await handlerScopeOf(ctx, req, opts)
     const body = (req.body ?? {}) as ExecuteRequest
-    const receipt = await facade.execute(
-      wireExecution(body, facade.scope), executeOptionsOf(body, opts?.maxPoll ?? MAX_COMMIT_POLL)
-    )
+    const exec = wireExecution(body, facade.scope)
+    await assertExecutionGranted(facade, exec, access)
+    const receipt = await facade.execute(exec, executeOptionsOf(body, opts?.maxPoll ?? MAX_COMMIT_POLL))
 
     return receipt.card !== undefined
       ? { transition: receipt.transition, card: receipt.card }

package/src/actions/schemas.ts

@@ -1,15 +1,87 @@
 import { handlers } from '@owlmeans/server-api'
-import type { PlanningProtocols } from '@owlmeans/planning'
+import { PlanningUnsupported, SchemaWriteMode, type PlanningDefinitions, type PlanningProtocols, type SchemaDefineReply, type SchemaDefineRequest, type ScopedSchemaBundle, type ScopedSchemaRecord } from '@owlmeans/planning'
 import type { Context, PlanningHandlerOptions } from '../types.js'
-import { planningServiceOf, scopeOf } from '../utils/index.js'
+import { assertGranted, assertWrites, concealed, handlerScopeOf } from '../utils/index.js'
+import type { RequestHandler } from './types.js'
 
-/** The schema bundle the service holds — what a client loads to answer `can()` with no round trip. */
+const text = (value: unknown): string | undefined =>
+  value == null || value === '' ? undefined : `${Array.isArray(value) ? value[0] : value}`
+
+/**
+ * The schema bundle — what a client loads to answer `can()` with no round trip. Scoped like every
+ * other leaf (no organization, no bundle). Where the store holds data-defined schemas it is the
+ * resolved layer of the organization, or of the project the `project` query names (a project this
+ * scope can see); otherwise the service's code bundle.
+ *
+ * @throws {WorkcardNotFound} for a project this scope cannot see
+ */
 export const listSchemas = (
   protocol: PlanningProtocols['schema']['list'], opts?: PlanningHandlerOptions
-): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
-  handlers<Context>().request(protocol, async (req, ctx) => {
-    // Scoped like every other leaf: no organization, no bundle.
-    scopeOf(req)
+): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => concealed(async (): Promise<ScopedSchemaBundle> => {
+    const { facade } = await handlerScopeOf(ctx, req, opts)
+    if (facade.definitions == null) {
+      return facade.schemas.bundle()
+    }
+
+    return await facade.definitions.bundle(text((req.query as { project?: unknown } | undefined)?.project))
+  }))
+
+/**
+ * Apply one `schema.define` request to a facade's definitions: the declarations in the request's
+ * mode (flows before types), then the retirements — answering what was written and the layer as it
+ * resolves afterwards.
+ */
+export const applySchemaRequest = async (
+  definitions: PlanningDefinitions, request: SchemaDefineRequest
+): Promise<SchemaDefineReply> => {
+  const layer = request.project != null ? { project: request.project } : {}
+  const declarations = { types: request.types ?? [], flows: request.flows ?? [] }
+  const records: ScopedSchemaRecord[] = []
+
+  switch (request.mode ?? SchemaWriteMode.Define) {
+    case SchemaWriteMode.Put:
+      for (const flow of declarations.flows) {
+        records.push(await definitions.putFlow(flow, layer))
+      }
+      for (const type of declarations.types) {
+        records.push(await definitions.putType(type, layer))
+      }
+      break
+    case SchemaWriteMode.Seed:
+      records.push(...await definitions.seed(declarations, layer))
+      break
+    default:
+      records.push(...await definitions.define(declarations, layer))
+  }
+  for (const key of request.retire ?? []) {
+    records.push(await definitions.retire(key.kind, key.key, layer))
+  }
+
+  return { records, bundle: await definitions.bundle(request.project) }
+}
+
+/**
+ * The write of data-defined types and flows. A project layer needs the project in the access's
+ * `writes` when the resolver answers it; then `grants.defineSchemas` gates when the resolver answers
+ * grants (the organization-wide layer needs `true`, a project layer its id).
+ *
+ * @throws {PlanningUnsupported} where the store holds no data-defined schemas
+ * @throws {PlanningForbidden | SchemaConflict | SchemaSealed | SchemaInvalid | SchemaInUse | WorkcardNotFound}
+ */
+export const defineSchemas = (
+  protocol: NonNullable<PlanningProtocols['schema']['define']>, opts?: PlanningHandlerOptions
+): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => concealed(async (): Promise<SchemaDefineReply> => {
+    const { facade, access } = await handlerScopeOf(ctx, req, opts)
+    const request = (req.body ?? {}) as SchemaDefineRequest
+    if (facade.definitions == null) {
+      throw new PlanningUnsupported('definitions')
+    }
+    if (request.project != null) {
+      assertWrites(access, request.project)
+    }
+    assertGranted(access, 'defineSchemas', request.project)
 
-    return planningServiceOf(ctx, opts).schemas.bundle()
-  })
+    return await applySchemaRequest(facade.definitions, request)
+  }))

package/src/actions/specs.ts

@@ -2,8 +2,7 @@ import { handlers } from '@owlmeans/server-api'
 import type { PlanningProtocols } from '@owlmeans/planning'
 import type { Context, PlanningHandlerOptions } from '../types.js'
 import { concealed, handlerFacade } from '../utils/index.js'
-
-type RequestHandler = ReturnType<ReturnType<typeof handlers<Context>>['request']>
+import type { RequestHandler } from './types.js'
 
 /** @throws {WorkcardNotFound} */
 export const getSpecification = (protocol: PlanningProtocols['spec']['get'], opts?: PlanningHandlerOptions): RequestHandler =>

package/src/actions/types.ts

@@ -0,0 +1,4 @@
+import { handlers } from '@owlmeans/server-api'
+import type { Context } from '../types.js'
+
+export type RequestHandler = ReturnType<ReturnType<typeof handlers<Context>>['request']>

package/src/actions/watch.ts

@@ -1,3 +1,4 @@
+import { logger } from '@owlmeans/log'
 import { PLANNING_COMMIT_EVENT } from '@owlmeans/planning'
 import type { CommitEvent, CommitFeedQuery, PlanningProtocols } from '@owlmeans/planning'
 import { connection } from '@owlmeans/server-socket'
@@ -6,6 +7,8 @@ import { MessageType } from '@owlmeans/socket'
 import type { Context, PlanningHandlerOptions } from '../types.js'
 import { handlerFacade } from '../utils/index.js'
 
+const log = logger('planning:watch')
+
 const text = (value: unknown): string | undefined =>
   value == null || value === '' ? undefined : `${value}`
 
@@ -32,7 +35,7 @@ export const watchCommits = (
       const enriched = event.record !== undefined ? event : { ...event, record: await facade.cards.load(event.card) }
       await conn.notify(frame, enriched)
     } catch (e) {
-      console.error('Planning commit notify error:', e)
+      log.warn('Planning commit notify failed', e)
     }
   }, filter)
 
@@ -45,7 +48,7 @@ export const watchCommits = (
       try {
         unsubscribe()
       } catch (e) {
-        console.error('Planning commit unsubscribe error:', e)
+        log.warn('Planning commit unsubscribe failed', e)
       }
     }
   })

package/src/conformance/assert.ts

@@ -0,0 +1,59 @@
+import { sameValue } from '@owlmeans/planning'
+
+/** A conformance expectation that did not hold. Plain `Error`, so any test runner reports it. */
+export class ConformanceFailure extends Error {
+  constructor(message: string) {
+    super(`planning conformance: ${message}`)
+    this.name = 'ConformanceFailure'
+  }
+}
+
+const show = (value: unknown): string => {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return `${value}`
+  }
+}
+
+/** @throws {ConformanceFailure} */
+export const check = (condition: unknown, message: string): void => {
+  if (condition !== true) {
+    throw new ConformanceFailure(message)
+  }
+}
+
+/** Structural equality over JSON values. @throws {ConformanceFailure} */
+export const same = (actual: unknown, expected: unknown, message: string): void => {
+  if (!sameValue(actual, expected)) {
+    throw new ConformanceFailure(`${message}: expected ${show(expected)}, got ${show(actual)}`)
+  }
+}
+
+/** The same members in any order. @throws {ConformanceFailure} */
+export const sameSet = (actual: readonly unknown[], expected: readonly unknown[], message: string): void => {
+  const sort = (values: readonly unknown[]) => [...values].map(show).sort()
+  same(sort(actual), sort(expected), message)
+}
+
+/**
+ * The promise rejects with an error of the class (matched by instance or by its registered type
+ * name, so a duplicate module copy counts). Answers the error.
+ *
+ * @throws {ConformanceFailure}
+ */
+export const rejects = async (
+  run: Promise<unknown> | (() => Promise<unknown>), expected: { typeName: string }, message: string
+): Promise<Error> => {
+  try {
+    await (typeof run === 'function' ? run() : run)
+  } catch (error) {
+    const type = (error as { type?: unknown } | null)?.type
+    if (error instanceof (expected as unknown as abstract new (...args: never[]) => unknown)
+      || (typeof type === 'string' && type === expected.typeName)) {
+      return error as Error
+    }
+    throw new ConformanceFailure(`${message}: expected ${expected.typeName}, got ${show((error as Error)?.message ?? error)}`)
+  }
+  throw new ConformanceFailure(`${message}: expected ${expected.typeName}, nothing was thrown`)
+}