@byline/host-tanstack-start 4.19.0 → 5.0.0

package/src/server-fns/document-mutation-transport.test.node.ts

@@ -0,0 +1,211 @@
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+import {
+  ERR_CONFLICT,
+  ERR_DOCUMENT_HOOK_COMMITTED,
+  ERR_DOCUMENT_STALE,
+  ERR_LOCK_CONFLICT,
+  ERR_NOT_FOUND,
+  ERR_TREE_HOOK_COMMITTED,
+  ERR_VALIDATION,
+  getDocumentRevisionValidationDetails,
+  getDocumentStaleDetails,
+  getLockConflictDetails,
+} from '@byline/core'
+import { getDocumentHookCommittedDetails } from '@byline/core/services'
+import { beforeAll, describe, expect, it, vi } from 'vitest'
+
+import { documentMutationError, withDocumentMutationErrors } from './document-mutation-errors.js'
+
+// Exercise the installed Start HTTP handler and its real Seroval protocol. Only
+// manifest lookup and request-local response state are supplied by this harness;
+// the production application's compiled actions are covered by browser tests.
+const require = createRequire(import.meta.url)
+const startRequire = createRequire(require.resolve('@tanstack/react-start/package.json'))
+const serverPackage = startRequire.resolve('@tanstack/start-server-core/package.json')
+const esm = join(dirname(serverPackage), 'src')
+const serverRequire = createRequire(serverPackage)
+let handler: (input: { request: Request; context: object; serverFnId: string }) => Promise<Response>
+let seroval: {
+  toJSONAsync(value: unknown): Promise<unknown>
+  fromCrossJSON(value: unknown, options: object): unknown
+}
+let runWithStartContext: (context: object, fn: () => Promise<Response>) => Promise<Response>
+let action: (input: { data: unknown }) => Promise<unknown>
+
+beforeAll(async () => {
+  vi.doMock(join(esm, 'getServerFnById.ts'), () => ({ getServerFnById: async () => action }))
+  vi.doMock(join(esm, 'request-response.ts'), () => ({
+    getResponse: () => ({ status: 200, headers: new Headers() }),
+  }))
+  handler = (await import(join(esm, 'server-functions-handler.ts'))).handleServerAction
+  seroval = await import(serverRequire.resolve('seroval'))
+  runWithStartContext = (
+    await import(
+      join(
+        dirname(serverRequire.resolve('@tanstack/start-storage-context/package.json')),
+        'dist/esm/index.js'
+      )
+    )
+  ).runWithStartContext
+})
+
+async function roundTrip(data: unknown, operation: (data: unknown) => Promise<unknown>) {
+  const guarded = withDocumentMutationErrors(operation)
+  action = async ({ data }) => {
+    try {
+      return { result: await guarded(data) }
+    } catch (error) {
+      return { error }
+    }
+  }
+  const request = new Request('http://localhost/_serverFn/document-mutation', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-tsr-serverFn': 'true' },
+    body: JSON.stringify(await seroval.toJSONAsync({ data })),
+  })
+  const response = await runWithStartContext(
+    {
+      request,
+      startOptions: {},
+      contextAfterGlobalMiddlewares: {},
+      executedRequestMiddlewares: new Set(),
+      handlerType: 'serverFn',
+      getRouter: () => {
+        throw new Error('Router not used')
+      },
+    },
+    () => handler({ request, context: {}, serverFnId: 'document-mutation' })
+  )
+  const wire = await response.text()
+  const decoded = seroval.fromCrossJSON(JSON.parse(wire), {})
+  if (typeof decoded !== 'object' || decoded === null) throw new Error('Expected wire envelope')
+  return {
+    value: { error: Reflect.get(decoded, 'error'), result: Reflect.get(decoded, 'result') },
+    wire,
+  }
+}
+
+const staleCases = [
+  { reason: 'revision_mismatch', documentId: 'doc', expectedRevision: 1, currentRevision: 2 },
+  {
+    reason: 'version_parent_mismatch',
+    documentId: 'doc',
+    previousVersionId: 'old',
+    currentVersionId: 'new',
+  },
+  {
+    reason: 'singleton_slot_changed',
+    singletonPath: 'settings',
+    expectedState: 'empty',
+    currentState: 'document',
+  },
+] as const
+
+describe('document failures over Start HTTP serialization', () => {
+  for (const details of staleCases) {
+    it(`retains ${details.reason} and excludes diagnostics`, async () => {
+      const { value, wire } = await roundTrip({}, async () => {
+        throw ERR_DOCUMENT_STALE({
+          message: 'private driver detail',
+          details,
+          cause: new Error('SELECT secret'),
+          logExtra: { private: true },
+        })
+      })
+      expect(getDocumentStaleDetails(value.error)).toEqual(details)
+      expect(wire).not.toMatch(/private driver|SELECT secret|logExtra/)
+    })
+  }
+  for (const reason of ['missing_document_revision', 'invalid_document_revision'] as const) {
+    it(`retains reload-required validation: ${reason}`, async () => {
+      const { value } = await roundTrip({}, async () => {
+        throw ERR_VALIDATION({ message: 'internal', details: { reason } })
+      })
+      expect(getDocumentRevisionValidationDetails(value.error)).toEqual({ reason })
+      expect(getDocumentStaleDetails(value.error)).toBeNull()
+    })
+  }
+  it('retains a confirmed rollback without relabelling it stale', async () => {
+    const details = { reason: 'lock_conflict', rolledBack: true, retryable: true }
+    const { value, wire } = await roundTrip({}, async () => {
+      throw ERR_LOCK_CONFLICT({
+        message: 'driver message',
+        details,
+        cause: new Error('SQL private'),
+      })
+    })
+    expect(getLockConflictDetails(value.error)).toEqual(details)
+    expect(getDocumentStaleDetails(value.error)).toBeNull()
+    expect(wire).not.toMatch(/driver message|SQL private/)
+  })
+  it('keeps committed hook warnings separate and preserves their committed revision', async () => {
+    const details = {
+      phase: 'afterUpdate',
+      documentId: 'doc',
+      documentVersionId: 'version',
+      revision: 3,
+      sideEffectCode: 'ERR_UNHANDLED',
+    }
+    const { value, wire } = await roundTrip({}, async () => {
+      throw ERR_DOCUMENT_HOOK_COMMITTED({
+        message: 'private hook failure',
+        details,
+        cause: new Error('secret hook'),
+      })
+    })
+    expect(getDocumentHookCommittedDetails(value.error)).toEqual(details)
+    expect(getDocumentStaleDetails(value.error)).toBeNull()
+    expect(getLockConflictDetails(value.error)).toBeNull()
+    expect(wire).not.toMatch(/private hook failure|secret hook/)
+  })
+  it('round-trips safe integer observations and receipts as numbers', async () => {
+    const { value } = await roundTrip(
+      { expectedRevision: Number.MAX_SAFE_INTEGER - 1 },
+      async (data) => {
+        expect(data).toEqual({ expectedRevision: Number.MAX_SAFE_INTEGER - 1 })
+        return { documentId: 'doc', revision: Number.MAX_SAFE_INTEGER }
+      }
+    )
+    expect(value.result).toEqual({ documentId: 'doc', revision: Number.MAX_SAFE_INTEGER })
+  })
+  it('does not classify unrelated or malformed conflicts by message', () => {
+    const conflict = ERR_CONFLICT({ message: 'This document has changed.' })
+    expect(documentMutationError(conflict)).toBe(conflict)
+    const malformed = { code: 'ERR_DOCUMENT_STALE', details: { reason: 'revision_mismatch' } }
+    expect(documentMutationError(malformed)).toBe(malformed)
+  })
+})
+
+it('transports the authorized structural receipt on committed tree hook failure without diagnostics', async () => {
+  const receipt = {
+    documentId: 'doc',
+    revision: 3,
+    affectedDocuments: [{ documentId: 'allowed-sibling', revision: 4 }],
+    scheduledPublicationsNeedReconfirmation: true,
+  }
+  const { value, wire } = await roundTrip({}, async () => {
+    throw ERR_TREE_HOOK_COMMITTED({
+      message: 'private hook diagnostics',
+      cause: new Error('SQL secret'),
+      details: { ...receipt, change: 'reorder', affectedDocumentIds: ['private'], internal: true },
+    })
+  })
+  expect(value.error).toEqual({
+    code: 'ERR_TREE_HOOK_COMMITTED',
+    message: 'The structure was saved, but a follow-up action failed.',
+    details: receipt,
+  })
+  expect(wire).not.toMatch(/private|SQL secret|internal/)
+})
+it('transports unavailable-document errors without provider details', async () => {
+  const { value, wire } = await roundTrip({}, async () => {
+    throw ERR_NOT_FOUND({ message: 'private unavailable reason', details: { internal: true } })
+  })
+  expect(value.error).toEqual({
+    code: 'ERR_NOT_FOUND',
+    message: 'This document is no longer available.',
+  })
+  expect(wire).not.toMatch(/private|internal/)
+})

package/src/server-fns/editable-revision.test.node.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+
+import { withEditableRevision } from './editable-revision.js'
+
+describe('editable response revision binding', () => {
+  const observed = { id: 'document', versionId: 'current', revision: 7 }
+  it('restores only the source revision without changing populated targets', () => {
+    const related = { id: 'related', versionId: 'published', fields: {} }
+    expect(
+      withEditableRevision({ id: 'document', versionId: 'current', fields: { related } }, observed)
+    ).toEqual({ id: 'document', versionId: 'current', revision: 7, fields: { related } })
+    expect(related).not.toHaveProperty('revision')
+  })
+  it.each([
+    { id: 'document', versionId: 'historical' },
+    { id: 'another-document', versionId: 'current' },
+  ])('rejects a transferred observation: %o', (document) => {
+    expect(() => withEditableRevision(document, observed)).toThrow('source observation')
+  })
+  it('rejects a row removed from the editable result', () => {
+    expect(() => withEditableRevision(observed, undefined)).toThrow('source observation')
+  })
+})

package/src/server-fns/editable-revision.ts

@@ -0,0 +1,18 @@
+import { ERR_DATABASE, isDocumentRevision } from '@byline/core'
+
+/** Restore metadata stripped by schema parsing only onto the exact source version.
+ * Never attach by array position: filtering/reordering must not transfer tokens. */
+export function withEditableRevision<T extends object>(
+  document: T,
+  observation: { id: string; versionId: string; revision: number } | undefined
+): T & { revision: number } {
+  if (
+    !observation ||
+    !isDocumentRevision(observation.revision) ||
+    Reflect.get(document, 'id') !== observation.id ||
+    Reflect.get(document, 'versionId') !== observation.versionId
+  ) {
+    throw ERR_DATABASE({ message: 'Editable response no longer matches its source observation' })
+  }
+  return { ...document, revision: observation.revision }
+}

package/src/server-fns/singleton-document-read.ts

@@ -7,7 +7,7 @@
  */
 
 import { getAdminBylineClient } from '@byline/client/server'
-import { getCollectionDefinition } from '@byline/core'
+import { ERR_NOT_FOUND, getCollectionDefinition } from '@byline/core'
 
 import { resolveAdminDocumentRead } from './admin-document-presentation.js'
 import { serialise } from './serialise.js'
@@ -27,6 +27,10 @@ export interface SingletonDocumentReadInput {
  */
 export async function readSingletonDocument(data: SingletonDocumentReadInput) {
   const handle = getAdminBylineClient().singleton(data.singleton)
-  const { options } = resolveAdminDocumentRead(getCollectionDefinition(data.singleton), data)
-  return serialise(await handle.get(options))
+  const {
+    options: { status: _status, ...options },
+  } = resolveAdminDocumentRead(getCollectionDefinition(data.singleton), data)
+  const snapshot = await handle.getForEdit(options)
+  if (snapshot == null) throw ERR_NOT_FOUND({ message: 'Singleton document is unavailable' })
+  return snapshot.state === 'empty' ? null : serialise(snapshot.document)
 }

package/src/server-fns/singletons/cancel-scheduled-publish.ts

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -13,7 +14,13 @@ import { getAdminBylineClient } from '@byline/client/server'
 import { serialise } from '../serialise.js'
 
 export const cancelSingletonScheduledPublish = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(await getAdminBylineClient().singleton(data.singleton).cancelScheduledPublish())
+  .validator((input: { expectedRevision: number; singleton: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient()
+          .singleton(data.singleton)
+          .cancelScheduledPublish({ expectedRevision: data.expectedRevision })
+      )
+    )
   )

package/src/server-fns/singletons/change-status.ts

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -13,7 +14,13 @@ import { getAdminBylineClient } from '@byline/client/server'
 import { serialise } from '../serialise.js'
 
 export const changeSingletonStatus = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; status: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(await getAdminBylineClient().singleton(data.singleton).changeStatus(data.status))
+  .validator((input: { expectedRevision: number; singleton: string; status: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient()
+          .singleton(data.singleton)
+          .changeStatus(data.status, { expectedRevision: data.expectedRevision })
+      )
+    )
   )

package/src/server-fns/singletons/confirm-scheduled-publish.ts

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -13,11 +14,16 @@ import { getAdminBylineClient } from '@byline/client/server'
 import { serialise } from '../serialise.js'
 
 export const confirmSingletonScheduledPublish = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; expectedVersionId: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(
-      await getAdminBylineClient()
-        .singleton(data.singleton)
-        .confirmScheduledPublish({ expectedVersionId: data.expectedVersionId })
+  .validator(
+    (input: { expectedRevision: number; singleton: string; expectedVersionId: string }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient().singleton(data.singleton).confirmScheduledPublish({
+          expectedRevision: data.expectedRevision,
+          expectedVersionId: data.expectedVersionId,
+        })
+      )
     )
   )

package/src/server-fns/singletons/copy-to-locale.ts

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -16,24 +17,28 @@ import { serialise } from '../serialise.js'
 export const copySingletonToLocale = createServerFn({ method: 'POST' })
   .validator(
     (input: {
+      expectedRevision: number
       singleton: string
       sourceLocale: string
       targetLocale: string
       overwrite?: boolean
     }) => input
   )
-  .handler(async ({ data }) => {
-    try {
-      return serialise(
-        await getAdminBylineClient().singleton(data.singleton).copyToLocale({
-          sourceLocale: data.sourceLocale,
-          targetLocale: data.targetLocale,
-          overwrite: data.overwrite,
-        })
-      )
-    } catch (error) {
-      const committedFailure = toCommittedDocumentHookFailureResponse(error)
-      if (committedFailure != null) return committedFailure
-      throw error
-    }
-  })
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      try {
+        return serialise(
+          await getAdminBylineClient().singleton(data.singleton).copyToLocale({
+            expectedRevision: data.expectedRevision,
+            sourceLocale: data.sourceLocale,
+            targetLocale: data.targetLocale,
+            overwrite: data.overwrite,
+          })
+        )
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
+    })
+  )

package/src/server-fns/singletons/get.ts

@@ -23,9 +23,9 @@ export interface GetSingletonInput {
  * - this shared host layer owns lenient reads, raw missing-locale values,
  *   relation-summary population, transport serialization, and preservation of
  *   restore warnings and locale metadata;
- * - the route loader composes published-version metadata plus scheduled-
- *   publication enablement, capability, and schedule aliases because those
- *   require host-only database and actor context beyond the singleton handle.
+ * - the route loader composes the informational published-version badge, feature
+ *   enablement, capability, and schedule aliases. Schedule state itself comes
+ *   from the same editable snapshot as the source document.
  */
 export const getSingleton = createServerFn({ method: 'GET' })
   .validator((input: GetSingletonInput) => input)

package/src/server-fns/singletons/restore-version.ts

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -14,15 +15,19 @@ import { toCommittedDocumentHookFailureResponse } from '../collections/save-outc
 import { serialise } from '../serialise.js'
 
 export const restoreSingletonVersion = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; versionId: string }) => input)
-  .handler(async ({ data }) => {
-    try {
-      return serialise(
-        await getAdminBylineClient().singleton(data.singleton).restoreVersion(data.versionId)
-      )
-    } catch (error) {
-      const committedFailure = toCommittedDocumentHookFailureResponse(error)
-      if (committedFailure != null) return committedFailure
-      throw error
-    }
-  })
+  .validator((input: { expectedRevision: number; singleton: string; versionId: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      try {
+        return serialise(
+          await getAdminBylineClient()
+            .singleton(data.singleton)
+            .restoreVersion(data.versionId, { expectedRevision: data.expectedRevision })
+        )
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
+    })
+  )

package/src/server-fns/singletons/schedule-publish.ts

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -13,12 +14,22 @@ import { getAdminBylineClient } from '@byline/client/server'
 import { serialise } from '../serialise.js'
 
 export const scheduleSingletonPublish = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; publishAt: string; expectedVersionId: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(
-      await getAdminBylineClient().singleton(data.singleton).schedulePublish({
-        publishAt: data.publishAt,
-        expectedVersionId: data.expectedVersionId,
-      })
+  .validator(
+    (input: {
+      expectedRevision: number
+      singleton: string
+      publishAt: string
+      expectedVersionId: string
+    }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient().singleton(data.singleton).schedulePublish({
+          publishAt: data.publishAt,
+          expectedRevision: data.expectedRevision,
+          expectedVersionId: data.expectedVersionId,
+        })
+      )
     )
   )