@byline/host-tanstack-start 4.14.1 → 4.16.0

package/src/server-fns/collections/scheduled-publication.ts

@@ -0,0 +1,270 @@
+/**
+ * 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
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import type { DocumentPublishScheduleInfo } from '@byline/client'
+import { getAdminBylineClient, getAdminRequestContext } from '@byline/client/server'
+import {
+  type DocumentPublishSchedule,
+  type DocumentPublishScheduleState,
+  ERR_NOT_FOUND,
+  ERR_VALIDATION,
+  type RecurringTaskHealth,
+} from '@byline/core'
+import { listDocumentPublishSchedules } from '@byline/core/services'
+
+import { bylineCore } from '../../integrations/byline-core.js'
+import { omitScheduleExecutionState } from './scheduled-publication-response.js'
+import { serialise } from './utils.js'
+
+const TASK_NAME = 'documents.publish-scheduled'
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export interface ScheduledPublicationRuntime {
+  enabled: boolean
+  health: {
+    status: 'healthy' | 'failed' | 'stale' | 'not_started'
+    task: SerializedRecurringTaskHealth | null
+  } | null
+}
+
+type SerializedRecurringTaskHealth = Omit<
+  RecurringTaskHealth,
+  'nextRunAt' | 'lastStartedAt' | 'lastSucceededAt' | 'lastFailedAt' | 'databaseNow'
+> & {
+  nextRunAt: string
+  lastStartedAt: string | null
+  lastSucceededAt: string | null
+  lastFailedAt: string | null
+  databaseNow: string
+}
+
+export type SerializedDocumentPublishSchedule = Omit<
+  DocumentPublishScheduleInfo,
+  | 'publishAt'
+  | 'suspendedAt'
+  | 'lastAuthorizedAt'
+  | 'scheduledAt'
+  | 'updatedAt'
+  | 'lastAttemptAt'
+  | 'nextAttemptAt'
+> & {
+  publishAt: string
+  suspendedAt: string | null
+  lastAuthorizedAt: string
+  scheduledAt: string
+  updatedAt: string
+  lastAttemptAt: string | null
+  nextAttemptAt: string
+}
+
+export interface ScheduledPublicationListItem extends SerializedDocumentPublishSchedule {
+  collectionPath: string
+  collectionLabel: string
+  documentPath: string | null
+  /**
+   * Display name for `lastAuthorizedBy` — full name, or email when the account
+   * has no name set. `null` when the account no longer exists, which is a real
+   * state rather than an error: the authorizer column is not a foreign key, so
+   * a schedule outlives the account that authorized it. Callers fall back to
+   * showing the id.
+   */
+  lastAuthorizedByName: string | null
+}
+
+export interface ScheduledPublicationListResponse {
+  schedules: ScheduledPublicationListItem[]
+  meta: {
+    page: number
+    pageSize: number
+    total: number
+    totalPages: number
+  }
+  runtime: ScheduledPublicationRuntime
+}
+
+function assertFeatureEnabled(): void {
+  if (bylineCore().config.scheduledPublication?.enabled === true) return
+  throw ERR_NOT_FOUND({ message: 'Scheduled publication is not enabled for this installation' })
+}
+
+function serializeSchedule(
+  schedule: DocumentPublishScheduleInfo | DocumentPublishSchedule
+): SerializedDocumentPublishSchedule {
+  return serialise(
+    omitScheduleExecutionState(schedule)
+  ) as unknown as SerializedDocumentPublishSchedule
+}
+
+async function scheduledPublicationRuntime(): Promise<ScheduledPublicationRuntime> {
+  const core = bylineCore()
+  if (core.config.scheduledPublication?.enabled !== true) {
+    return { enabled: false, health: null }
+  }
+
+  const scheduler = core.db.scheduler
+  if (scheduler == null) {
+    return { enabled: true, health: { status: 'not_started', task: null } }
+  }
+  const [task] = await scheduler.health([TASK_NAME])
+  if (task == null) {
+    return { enabled: true, health: { status: 'not_started', task: null } }
+  }
+
+  const staleAfter = task.nextRunAt.getTime() + task.intervalMs * 2
+  const status = task.leaseExpired
+    ? 'stale'
+    : task.lastStatus === 'failed'
+      ? 'failed'
+      : staleAfter < task.databaseNow.getTime()
+        ? 'stale'
+        : 'healthy'
+  return {
+    enabled: true,
+    health: {
+      status,
+      task: serialise(task) as unknown as SerializedRecurringTaskHealth,
+    },
+  }
+}
+
+/** Authenticated feature discovery for the admin shell and health warning. */
+export const getScheduledPublicationRuntime = createServerFn({ method: 'GET' }).handler(
+  async () => {
+    await getAdminRequestContext()
+    return scheduledPublicationRuntime()
+  }
+)
+
+export const scheduleCollectionDocumentPublish = createServerFn({ method: 'POST' })
+  .validator(
+    (input: { collection: string; id: string; publishAt: string; expectedVersionId: string }) =>
+      input
+  )
+  .handler(async ({ data }) => {
+    assertFeatureEnabled()
+    const schedule = await getAdminBylineClient()
+      .collection(data.collection)
+      .schedulePublish(data.id, {
+        publishAt: data.publishAt,
+        expectedVersionId: data.expectedVersionId,
+      })
+    return serializeSchedule(schedule)
+  })
+
+export const confirmCollectionDocumentScheduledPublish = createServerFn({ method: 'POST' })
+  .validator((input: { collection: string; id: string; expectedVersionId: string }) => input)
+  .handler(async ({ data }) => {
+    assertFeatureEnabled()
+    const schedule = await getAdminBylineClient()
+      .collection(data.collection)
+      .confirmScheduledPublish(data.id, { expectedVersionId: data.expectedVersionId })
+    return serializeSchedule(schedule)
+  })
+
+export const cancelCollectionDocumentScheduledPublish = createServerFn({ method: 'POST' })
+  .validator((input: { collection: string; id: string }) => input)
+  .handler(async ({ data }) => {
+    assertFeatureEnabled()
+    const schedule = await getAdminBylineClient()
+      .collection(data.collection)
+      .cancelScheduledPublish(data.id)
+    return schedule == null
+      ? { status: 'not_found' as const }
+      : { status: 'cancelled' as const, schedule: serializeSchedule(schedule) }
+  })
+
+export const listScheduledPublications = createServerFn({ method: 'GET' })
+  .validator(
+    (input: {
+      states?: readonly DocumentPublishScheduleState[]
+      lastAuthorizedBy?: string
+      page?: number
+      pageSize?: number
+    }) => input
+  )
+  .handler(async ({ data }) => {
+    assertFeatureEnabled()
+    if (data.states?.some((state) => state !== 'armed' && state !== 'needs_reconfirm') === true) {
+      throw ERR_VALIDATION({ message: 'state must be armed or needs_reconfirm' })
+    }
+    if (data.lastAuthorizedBy != null && !UUID_RE.test(data.lastAuthorizedBy)) {
+      throw ERR_VALIDATION({ message: 'lastAuthorizedBy must be a UUID' })
+    }
+    const core = bylineCore()
+    const page = data.page ?? 1
+    const pageSize = data.pageSize ?? 25
+    const requestContext = await getAdminRequestContext()
+    const result = await listDocumentPublishSchedules(core, requestContext, {
+      states: data.states,
+      lastAuthorizedBy: data.lastAuthorizedBy,
+      page,
+      pageSize,
+    })
+    const collections = new Map(
+      core.collections.map((definition) => {
+        const record = core.getCollectionRecord(definition.path)
+        return [record.collectionId, definition] as const
+      })
+    )
+    // Resolve authorizer names in one query for the whole page rather than one
+    // per row. `last_authorized_by` is deliberately not a foreign key — deleting
+    // an admin account must not revoke a schedule it authorized — so an id here
+    // may simply have no user row left, and the caller falls back to the id.
+    const authorizerIds = [
+      ...new Set(
+        result.schedules
+          .map((schedule) => schedule.lastAuthorizedBy)
+          .filter((id): id is string => id != null)
+      ),
+    ]
+    const authorizerNames = new Map<string, string>()
+    // `adminStore` is optional on core — an installation can run without the
+    // admin subsystem — so a missing store simply means no names to resolve and
+    // the column falls back to ids.
+    const adminUsers = core.adminStore?.adminUsers
+    if (authorizerIds.length > 0 && adminUsers != null) {
+      const users = await adminUsers.getByIds(authorizerIds)
+      for (const user of users) {
+        const fullName = [user.given_name, user.family_name].filter(Boolean).join(' ').trim()
+        authorizerNames.set(user.id, fullName.length > 0 ? fullName : user.email)
+      }
+    }
+
+    const schedules = await Promise.all(
+      result.schedules.map(async (schedule): Promise<ScheduledPublicationListItem> => {
+        const definition = collections.get(schedule.collectionId)
+        const documentPath = await core.db.queries.documents.getCurrentPath({
+          collection_id: schedule.collectionId,
+          document_id: schedule.documentId,
+        })
+        return {
+          ...serializeSchedule(schedule),
+          collectionPath: definition?.path ?? schedule.collectionId,
+          collectionLabel: definition?.labels.plural ?? definition?.path ?? schedule.collectionId,
+          documentPath,
+          lastAuthorizedByName:
+            schedule.lastAuthorizedBy == null
+              ? null
+              : (authorizerNames.get(schedule.lastAuthorizedBy) ?? null),
+        }
+      })
+    )
+
+    return {
+      schedules,
+      meta: {
+        page,
+        pageSize,
+        total: result.total,
+        totalPages: Math.max(1, Math.ceil(result.total / pageSize)),
+      },
+      runtime: await scheduledPublicationRuntime(),
+    } satisfies ScheduledPublicationListResponse
+  })

package/src/vite/analytics-dev.test.node.ts

@@ -0,0 +1,126 @@
+/**
+ * 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
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import { ANALYTICS_AGENT_SOURCE } from '@byline/analytics-agent/source'
+import type { Plugin } from 'vite'
+import { describe, expect, it, vi } from 'vitest'
+
+import { bylineAnalyticsDev } from './analytics-dev.js'
+
+type Middleware = (
+  request: IncomingMessage,
+  response: ServerResponse,
+  next: (error?: unknown) => void
+) => void | Promise<void>
+
+describe('bylineAnalyticsDev', () => {
+  it('directly serves browser script requests before Vite can transform them', async () => {
+    const handler = captureMiddleware(bylineAnalyticsDev())
+    const request = requestStub('GET', '/b.js?version=current', {
+      accept: '*/*',
+      'sec-fetch-dest': 'script',
+    })
+    const { response, headers, end } = responseStub()
+    const next = vi.fn()
+
+    await handler(request, response, next)
+
+    expect(response.statusCode).toBe(200)
+    expect(headers).toEqual({
+      'cache-control': 'public, max-age=3600, must-revalidate',
+      'content-type': 'text/javascript; charset=utf-8',
+      'x-content-type-options': 'nosniff',
+    })
+    expect(end).toHaveBeenCalledWith(ANALYTICS_AGENT_SOURCE)
+    expect(next).not.toHaveBeenCalled()
+    expect(request.headers).toEqual({
+      accept: '*/*',
+      'sec-fetch-dest': 'script',
+    })
+  })
+
+  it('continues unrelated requests through the Vite middleware chain', async () => {
+    const handler = captureMiddleware(bylineAnalyticsDev())
+    const { response, end } = responseStub()
+    const next = vi.fn()
+
+    await handler(requestStub('GET', '/about'), response, next)
+    await handler(requestStub('POST', '/api/events'), response, next)
+
+    expect(next).toHaveBeenCalledTimes(2)
+    expect(end).not.toHaveBeenCalled()
+  })
+
+  it('supports a custom public agent path', async () => {
+    const handler = captureMiddleware(bylineAnalyticsDev({ agentPath: '/first-party.js' }))
+    const defaultResponse = responseStub()
+    const customResponse = responseStub()
+    const next = vi.fn()
+
+    await handler(requestStub('GET', '/b.js'), defaultResponse.response, next)
+    await handler(requestStub('GET', '/first-party.js'), customResponse.response, next)
+
+    expect(next).toHaveBeenCalledOnce()
+    expect(defaultResponse.end).not.toHaveBeenCalled()
+    expect(customResponse.end).toHaveBeenCalledWith(ANALYTICS_AGENT_SOURCE)
+  })
+})
+
+function captureMiddleware(plugin: Plugin): Middleware {
+  const handlers: Middleware[] = []
+  const configureServer = plugin.configureServer
+
+  expect(typeof configureServer).toBe('function')
+  if (typeof configureServer !== 'function') {
+    throw new Error('Expected a Vite configureServer hook')
+  }
+
+  configureServer.call(
+    {} as never,
+    {
+      middlewares: {
+        use(handler: Middleware) {
+          handlers.push(handler)
+        },
+      },
+    } as never
+  )
+
+  const handler = handlers[0]
+  expect(handler).toBeDefined()
+  if (handler == null) throw new Error('Expected a Vite middleware')
+  return handler
+}
+
+function requestStub(
+  method: string,
+  url: string,
+  headers: IncomingMessage['headers'] = {}
+): IncomingMessage {
+  return { method, url, headers } as IncomingMessage
+}
+
+function responseStub(): {
+  response: ServerResponse
+  headers: Record<string, string | number | readonly string[]>
+  end: ReturnType<typeof vi.fn>
+} {
+  const headers: Record<string, string | number | readonly string[]> = {}
+  const end = vi.fn()
+  const response = {
+    statusCode: 0,
+    setHeader(name: string, value: string | number | readonly string[]) {
+      headers[name] = value
+      return response
+    },
+    end,
+  } as unknown as ServerResponse
+  return { response, headers, end }
+}

package/src/vite/analytics-dev.ts

@@ -0,0 +1,56 @@
+/**
+ * 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
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { Plugin } from 'vite'
+
+import { serveAnalyticsAgent } from '../integrations/serve-analytics-agent.js'
+
+/**
+ * Complete the first-party analytics transport during Vite development.
+ *
+ * Browser script requests carry `Sec-Fetch-Dest: script`, which Vite routes
+ * into its module pipeline before TanStack Start can serve the agent route.
+ * This plugin serves the agent directly. The application event route remains
+ * responsible for its development identity because POST server routes can
+ * bypass Vite's ordinary middleware chain. Production continues to use the
+ * application-owned agent route.
+ */
+export function bylineAnalyticsDev(
+  options: {
+    /** Public path that serves the standalone agent. */
+    agentPath?: string
+  } = {}
+): Plugin {
+  const agentPath = options.agentPath ?? '/b.js'
+
+  return {
+    name: 'byline:analytics-dev',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(async (request, response, next) => {
+        const pathname = request.url?.split('?', 1)[0]
+
+        if (request.method === 'GET' && pathname === agentPath) {
+          try {
+            const agentResponse = serveAnalyticsAgent()
+            response.statusCode = agentResponse.status
+            agentResponse.headers.forEach((value, name) => {
+              response.setHeader(name, value)
+            })
+            response.end(await agentResponse.text())
+          } catch (error) {
+            next(error)
+          }
+          return
+        }
+
+        next()
+      })
+    },
+  }
+}

package/src/vite/index.ts

@@ -6,4 +6,5 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+export { bylineAnalyticsDev } from './analytics-dev.js'
 export { bylineClientHookBoundary } from './client-hook-boundary.js'