@contember/engine-actions 2.2.0-alpha.3 → 2.2.0-alpha.5

package/src/graphql/resolvers/ResolversFactory.ts

@@ -27,7 +27,7 @@ export class ResolversFactory {
 		} = {
 			Json: JSONType,
 			DateTime: DateTimeType,
-			Uuid: UuidType,
+			UUID: UuidType,
 			Mutation: {
 				processBatch: this.processBatchMutationResolver.processBatch.bind(this.processBatchMutationResolver),
 				setVariables: this.setVariablesMutationResolver.setVariables.bind(this.setVariablesMutationResolver),

package/src/graphql/resolvers/mutation/SetVariablesMutationResolver.ts

@@ -12,7 +12,7 @@ export class SetVariablesMutationResolver implements MutationResolvers<ActionsCo
 	async setVariables(parent: unknown, { args }: MutationSetVariablesArgs, ctx: ActionsContext) {
 		await ctx.requireAccess(ActionsAuthorizationActions.VARIABLES_SET)
 
-		await this.variablesManager.setVariables(ctx.db, args)
+		await this.variablesManager.setVariables(ctx.db, args, ctx.project.slug)
 
 		return {
 			ok: true,

package/src/graphql/resolvers/query/EventsQueryResolver.ts

@@ -51,7 +51,7 @@ export class EventsQueryResolver implements QueryResolvers<ActionsContext> {
 		return rows.map(row => ({
 			id: row.id,
 			createdAt: row.created_at,
-			resolvedAt: row.created_at,
+			resolvedAt: row.resolved_at ?? undefined,
 			lastStateChange: row.last_state_change,
 			visibleAt: row.visible_at,
 			log: row.log,

package/src/graphql/resolvers/query/VariablesQueryResolver.ts

@@ -12,9 +12,6 @@ export class VariablesQueryResolver implements QueryResolvers<ActionsContext> {
 	async variables(parent: unknown, args: unknown, ctx: ActionsContext) {
 		await ctx.requireAccess(ActionsAuthorizationActions.VARIABLES_VIEW)
 
-		return Object.entries(await this.variablesManager.fetchVariables(ctx.db)).map(([name, value]) => ({
-			name,
-			value,
-		}))
+		return await this.variablesManager.listVariables(ctx.db, ctx.project.slug)
 	}
 }

package/src/graphql/schema/actions.graphql.ts

@@ -4,7 +4,7 @@ import { DocumentNode } from 'graphql'
 export const schema: DocumentNode = gql`
     scalar DateTime
     scalar Json
-    scalar Uuid
+    scalar UUID
 
     schema {
         query: Query
@@ -15,14 +15,14 @@ export const schema: DocumentNode = gql`
         failedEvents(args: EventArgs): [Event!]!
         eventsToProcess(args: EventArgs): [Event!]!
         eventsInProcessing(args: EventArgs): [Event!]!
-        event(id: Uuid!): Event
+        event(id: UUID!): Event
         variables: [Variable!]!
     }
 
     type Mutation {
         processBatch: ProcessBatchResponse!
-        retryEvent(id: Uuid!): RetryEventResponse!
-        stopEvent(id: Uuid!): StopEventResponse!
+        retryEvent(id: UUID!): RetryEventResponse!
+        stopEvent(id: UUID!): StopEventResponse!
         setVariables(args: SetVariablesArgs!): SetVariablesResponse!
     }
 
@@ -33,9 +33,9 @@ export const schema: DocumentNode = gql`
     }
 
     type Event {
-        id: Uuid!
-        transactionId: Uuid!
-        identityId: Uuid
+        id: UUID!
+        transactionId: UUID!
+        identityId: UUID
         ipAddress: String
         userAgent: String
         createdAt: DateTime!
@@ -99,7 +99,19 @@ export const schema: DocumentNode = gql`
 
     type Variable {
         name: String!
-        value: String!
+        """Null when the value is not readable, which is every ENVIRONMENT one."""
+        value: String
+        source: VariableSource!
     }
 
+	"""
+	Where the value comes from.
+	- DATABASE is stored in the project database, readable and writable with setVariables
+	- ENVIRONMENT is supplied by the engine environment, overrides a stored value of the same name, and is neither readable nor writable
+	"""
+	enum VariableSource {
+		DATABASE
+		ENVIRONMENT
+	}
+
 `

package/src/graphql/schema/index.ts

@@ -16,14 +16,14 @@ export type Scalars = {
 	Float: { input: number; output: number }
 	DateTime: { input: Date; output: Date }
 	Json: { input: any; output: any }
-	Uuid: { input: string; output: string }
+	UUID: { input: string; output: string }
 }
 
 export type Event = {
 	readonly __typename?: 'Event'
 	readonly createdAt: Scalars['DateTime']['output']
-	readonly id: Scalars['Uuid']['output']
-	readonly identityId?: Maybe<Scalars['Uuid']['output']>
+	readonly id: Scalars['UUID']['output']
+	readonly identityId?: Maybe<Scalars['UUID']['output']>
 	readonly ipAddress?: Maybe<Scalars['String']['output']>
 	readonly lastStateChange: Scalars['DateTime']['output']
 	readonly log: Scalars['Json']['output']
@@ -33,7 +33,7 @@ export type Event = {
 	readonly stage: Scalars['String']['output']
 	readonly state: EventState
 	readonly target: Scalars['String']['output']
-	readonly transactionId: Scalars['Uuid']['output']
+	readonly transactionId: Scalars['UUID']['output']
 	readonly userAgent?: Maybe<Scalars['String']['output']>
 	readonly visibleAt?: Maybe<Scalars['DateTime']['output']>
 }
@@ -61,7 +61,7 @@ export type Mutation = {
 }
 
 export type MutationRetryEventArgs = {
-	id: Scalars['Uuid']['input']
+	id: Scalars['UUID']['input']
 }
 
 export type MutationSetVariablesArgs = {
@@ -69,7 +69,7 @@ export type MutationSetVariablesArgs = {
 }
 
 export type MutationStopEventArgs = {
-	id: Scalars['Uuid']['input']
+	id: Scalars['UUID']['input']
 }
 
 export type ProcessBatchResponse = {
@@ -87,7 +87,7 @@ export type Query = {
 }
 
 export type QueryEventArgs = {
-	id: Scalars['Uuid']['input']
+	id: Scalars['UUID']['input']
 }
 
 export type QueryEventsInProcessingArgs = {
@@ -136,7 +136,9 @@ export type StopEventResponse = {
 export type Variable = {
 	readonly __typename?: 'Variable'
 	readonly name: Scalars['String']['output']
-	readonly value: Scalars['String']['output']
+	readonly source: VariableSource
+	/** Null when the value is not readable, which is every ENVIRONMENT one. */
+	readonly value?: Maybe<Scalars['String']['output']>
 }
 
 export type VariableInput = {
@@ -144,6 +146,15 @@ export type VariableInput = {
 	readonly value: Scalars['String']['input']
 }
 
+/**
+ * Where the value comes from.
+ * - DATABASE is stored in the project database, readable and writable with setVariables
+ * - ENVIRONMENT is supplied by the engine environment, overrides a stored value of the same name, and is neither readable nor writable
+ */
+export type VariableSource =
+	| 'DATABASE'
+	| 'ENVIRONMENT'
+
 export type ResolverTypeWrapper<T> = Promise<T> | T
 
 export type ResolverWithResolve<TResult, TParent, TContext, TArgs> = {
@@ -228,9 +239,10 @@ export type ResolversTypes = {
 	SetVariablesResponse: ResolverTypeWrapper<SetVariablesResponse>
 	StopEventResponse: ResolverTypeWrapper<StopEventResponse>
 	String: ResolverTypeWrapper<Scalars['String']['output']>
-	Uuid: ResolverTypeWrapper<Scalars['Uuid']['output']>
+	UUID: ResolverTypeWrapper<Scalars['UUID']['output']>
 	Variable: ResolverTypeWrapper<Variable>
 	VariableInput: VariableInput
+	VariableSource: VariableSource
 }
 
 /** Mapping between all available schema types and the resolvers parents */
@@ -249,7 +261,7 @@ export type ResolversParentTypes = {
 	SetVariablesResponse: SetVariablesResponse
 	StopEventResponse: StopEventResponse
 	String: Scalars['String']['output']
-	Uuid: Scalars['Uuid']['output']
+	UUID: Scalars['UUID']['output']
 	Variable: Variable
 	VariableInput: VariableInput
 }
@@ -260,8 +272,8 @@ export interface DateTimeScalarConfig extends GraphQLScalarTypeConfig<ResolversT
 
 export type EventResolvers<ContextType = any, ParentType extends ResolversParentTypes['Event'] = ResolversParentTypes['Event']> = {
 	createdAt?: Resolver<ResolversTypes['DateTime'], ParentType, ContextType>
-	id?: Resolver<ResolversTypes['Uuid'], ParentType, ContextType>
-	identityId?: Resolver<Maybe<ResolversTypes['Uuid']>, ParentType, ContextType>
+	id?: Resolver<ResolversTypes['UUID'], ParentType, ContextType>
+	identityId?: Resolver<Maybe<ResolversTypes['UUID']>, ParentType, ContextType>
 	ipAddress?: Resolver<Maybe<ResolversTypes['String']>, ParentType, ContextType>
 	lastStateChange?: Resolver<ResolversTypes['DateTime'], ParentType, ContextType>
 	log?: Resolver<ResolversTypes['Json'], ParentType, ContextType>
@@ -271,7 +283,7 @@ export type EventResolvers<ContextType = any, ParentType extends ResolversParent
 	stage?: Resolver<ResolversTypes['String'], ParentType, ContextType>
 	state?: Resolver<ResolversTypes['EventState'], ParentType, ContextType>
 	target?: Resolver<ResolversTypes['String'], ParentType, ContextType>
-	transactionId?: Resolver<ResolversTypes['Uuid'], ParentType, ContextType>
+	transactionId?: Resolver<ResolversTypes['UUID'], ParentType, ContextType>
 	userAgent?: Resolver<Maybe<ResolversTypes['String']>, ParentType, ContextType>
 	visibleAt?: Resolver<Maybe<ResolversTypes['DateTime']>, ParentType, ContextType>
 	__isTypeOf?: IsTypeOfResolverFn<ParentType, ContextType>
@@ -328,13 +340,14 @@ export type StopEventResponseResolvers<
 	__isTypeOf?: IsTypeOfResolverFn<ParentType, ContextType>
 }
 
-export interface UuidScalarConfig extends GraphQLScalarTypeConfig<ResolversTypes['Uuid'], any> {
-	name: 'Uuid'
+export interface UUIDScalarConfig extends GraphQLScalarTypeConfig<ResolversTypes['UUID'], any> {
+	name: 'UUID'
 }
 
 export type VariableResolvers<ContextType = any, ParentType extends ResolversParentTypes['Variable'] = ResolversParentTypes['Variable']> = {
 	name?: Resolver<ResolversTypes['String'], ParentType, ContextType>
-	value?: Resolver<ResolversTypes['String'], ParentType, ContextType>
+	source?: Resolver<ResolversTypes['VariableSource'], ParentType, ContextType>
+	value?: Resolver<Maybe<ResolversTypes['String']>, ParentType, ContextType>
 	__isTypeOf?: IsTypeOfResolverFn<ParentType, ContextType>
 }
 
@@ -348,6 +361,6 @@ export type Resolvers<ContextType = any> = {
 	RetryEventResponse?: RetryEventResponseResolvers<ContextType>
 	SetVariablesResponse?: SetVariablesResponseResolvers<ContextType>
 	StopEventResponse?: StopEventResponseResolvers<ContextType>
-	Uuid?: GraphQLScalarType
+	UUID?: GraphQLScalarType
 	Variable?: VariableResolvers<ContextType>
 }

package/src/index.ts

@@ -28,6 +28,7 @@ import { VariablesManager } from './model/VariablesManager.js'
 import { AccessEvaluator, Authorizator } from '@contember/authorization'
 import { ActionsPermissionsFactory } from './authorization/index.js'
 import { WebhookFetcherNative } from './dispatch/WebhookFetcher.js'
+import { ActionsMetrics } from './ActionsMetrics.js'
 
 export {
 	TriggerHandler,
@@ -42,20 +43,33 @@ export { ListenerStoreProvider } from './ListenerStoreProvider.js'
 export default class ActionsPlugin implements Plugin {
 	name = 'contember/actions'
 
+	/**
+	 * Metrics singleton, created in {@link getMasterContainerHook} (where the Prometheus registry is
+	 * available) and read back here in {@link getExecutionContainerHook}, which runs in the per-request
+	 * content container with no access to master-level services.
+	 */
+	private actionsMetrics: ActionsMetrics | undefined
+
 	getSystemMigrations(): MigrationGroup {
 		return migrationsGroup
 	}
 
 	getExecutionContainerHook() {
-		const hookFactory = new ActionsExecutionContainerHookFactory(new ListenerStoreProvider())
+		const hookFactory = new ActionsExecutionContainerHookFactory(new ListenerStoreProvider(), () => this.actionsMetrics)
 		return hookFactory.create()
 	}
 
 	getMasterContainerHook() {
 		const hook: MasterContainerHook = (builder: MasterContainerBuilder) => {
 			return builder
-				.addService('actions_variableManager', () => {
-					return new VariablesManager()
+				.addService('actions_metrics', ({ promRegistry }) => {
+					const metrics = new ActionsMetrics(promRegistry)
+					// expose to getExecutionContainerHook (runs in a different container scope)
+					this.actionsMetrics = metrics
+					return metrics
+				})
+				.addService('actions_variableManager', ({ env }) => {
+					return new VariablesManager(env)
 				})
 				.addService('actions_eventRepository', () => {
 					return new EventsRepository()
@@ -65,8 +79,8 @@ export default class ActionsPlugin implements Plugin {
 					const targetHandlerResolver = new TargetHandlerResolver(webhookTargetHandler)
 					return new EventDispatcher(actions_eventRepository, actions_variableManager, targetHandlerResolver)
 				})
-				.addService('actions_dispatchWorkerSupervisorFactory', ({ actions_eventDispatcher }) => {
-					const projectDispatcherFactory = new ProjectDispatcherFactory(actions_eventDispatcher)
+				.addService('actions_dispatchWorkerSupervisorFactory', ({ actions_eventDispatcher, actions_metrics }) => {
+					const projectDispatcherFactory = new ProjectDispatcherFactory(actions_eventDispatcher, actions_metrics)
 					return new DispatchWorkerSupervisorFactory(projectDispatcherFactory)
 				})
 				.addService('actions_authorizator', () => {
@@ -84,6 +98,7 @@ export default class ActionsPlugin implements Plugin {
 							actions_dispatchWorkerSupervisorFactory,
 							actions_variableManager,
 							actions_authorizator,
+							panelApiMount,
 						},
 					) => {
 						const handlerFactory = new ActionsGraphQLHandlerFactory()
@@ -113,6 +128,13 @@ export default class ActionsPlugin implements Plugin {
 						)
 						it.addRoute('actions', '/actions/:projectSlug', actionsMiddlewareFactory.create())
 						it.addWebsocketRoute('actions', '/actions/_worker', actionsWebsocketMiddlewareFactory.create())
+						// Does nothing unless the panel is served; when it is, the panel's access gate applies
+						// and the UI learns the actions module has an API to talk to.
+						panelApiMount.mount(it, {
+							name: 'actions',
+							path: 'actions/:projectSlug',
+							controller: actionsMiddlewareFactory.create(),
+						})
 					},
 				)
 				.setupService(

package/src/model/VariablesManager.ts

@@ -1,19 +1,54 @@
 import { DatabaseContext } from '@contember/engine-system-api'
 import { VariablesQuery } from './VariablesQuery.js'
-import { SetVariablesArgs } from '../graphql/schema/index.js'
+import { SetVariablesArgs, Variable } from '../graphql/schema/index.js'
 import { DeleteBuilder } from '@contember/database'
 import { SetVariableCommand } from './SetVariableCommand.js'
+import { Env, projectNameToEnvName } from '@contember/engine-http'
+import { UserInputError } from '@contember/graphql-utils'
 
 export type VariablesMap = Record<string, string>
 
+/** Between the project (or DEFAULT) prefix and the variable name: `MY_PROJECT_ACTIONS_VARIABLE_API_KEY`. */
+const ENV_NAME_INFIX = '_ACTIONS_VARIABLE_'
+
 export class VariablesManager {
-	public async fetchVariables(db: DatabaseContext): Promise<VariablesMap> {
-		return Object.fromEntries((await db.queryHandler.fetch(new VariablesQuery())).map(it => [it.name, it.value]))
+	/** The environment does not change while the process runs, so each project resolves its prefixes once. */
+	private readonly envVariablesCache = new Map<string, VariablesMap>()
+
+	constructor(
+		private readonly env: Env,
+	) {
+	}
+
+	/** Values for dispatch. A variable supplied by the environment shadows a stored row of the same name. */
+	public async fetchVariables(db: DatabaseContext, projectSlug: string): Promise<VariablesMap> {
+		return { ...await this.fetchStoredVariables(db), ...this.fetchEnvVariables(projectSlug) }
+	}
+
+	/**
+	 * The listing is an inventory, not a way to read secrets: an environment value stays in the operator's
+	 * secret store and is reported as a name with no value.
+	 */
+	public async listVariables(db: DatabaseContext, projectSlug: string): Promise<Variable[]> {
+		const envVariables = this.fetchEnvVariables(projectSlug)
+		const stored = await this.fetchStoredVariables(db)
+		return [
+			...Object.entries(stored)
+				.filter(([name]) => !Object.hasOwn(envVariables, name))
+				.map(([name, value]): Variable => ({ name, value, source: 'DATABASE' })),
+			...Object.keys(envVariables).map((name): Variable => ({ name, value: null, source: 'ENVIRONMENT' })),
+		].sort((a, b) => a.name.localeCompare(b.name))
 	}
 
-	public async setVariables(db: DatabaseContext, args: SetVariablesArgs) {
+	public async setVariables(db: DatabaseContext, args: SetVariablesArgs, projectSlug: string) {
+		const envVariables = this.fetchEnvVariables(projectSlug)
+		const readOnly = args.variables.map(it => it.name).filter(it => Object.hasOwn(envVariables, it))
+		if (readOnly.length > 0) {
+			throw new UserInputError(`Variables supplied by the environment are read-only: ${readOnly.join(', ')}`)
+		}
+
 		return await db.transaction(async db => {
-			const current = await this.fetchVariables(db)
+			const current = await this.fetchStoredVariables(db)
 			const mode = args.mode ?? 'MERGE'
 			const inputVariables = Object.fromEntries(args.variables.map(it => [it.name, it.value]))
 
@@ -30,7 +65,7 @@ export class VariablesManager {
 					break
 			}
 
-			const toDelete = Object.keys(current).filter(it => !(it in newVariables))
+			const toDelete = Object.keys(current).filter(it => !Object.hasOwn(newVariables, it))
 			if (toDelete.length > 0) {
 				await DeleteBuilder.create()
 					.from('actions_variable')
@@ -46,4 +81,29 @@ export class VariablesManager {
 			}
 		})
 	}
+
+	private async fetchStoredVariables(db: DatabaseContext): Promise<VariablesMap> {
+		return Object.fromEntries((await db.queryHandler.fetch(new VariablesQuery())).map(it => [it.name, it.value]))
+	}
+
+	private fetchEnvVariables(projectSlug: string): VariablesMap {
+		const cached = this.envVariablesCache.get(projectSlug)
+		if (cached !== undefined) {
+			return cached
+		}
+		// the project prefix is read last, so it overrides the shared DEFAULT_ one
+		const prefixes = [`DEFAULT${ENV_NAME_INFIX}`, projectNameToEnvName(projectSlug) + ENV_NAME_INFIX]
+		const result: VariablesMap = {}
+		for (const prefix of prefixes) {
+			for (const [name, value] of Object.entries(this.env)) {
+				// an empty value counts as unset, the same as the `||` fallback of the config parameter resolver
+				if (!name.startsWith(prefix) || name.length === prefix.length || value === '') {
+					continue
+				}
+				result[name.slice(prefix.length)] = value
+			}
+		}
+		this.envVariablesCache.set(projectSlug, result)
+		return result
+	}
 }

package/src/triggers/TriggerPayloadPersister.ts

@@ -3,6 +3,7 @@ import { Mapper, TriggeredActionEvent, TriggeredActionsCollector } from '@contem
 import { Actions, ActionsPayload } from '@contember/schema'
 import { EventRow } from '../model/types.js'
 import { notify } from '../utils/notifyChannel.js'
+import { ProjectActionsMetrics } from '../ActionsMetrics.js'
 
 type EventRowToInsert = Omit<EventRow, 'created_at' | 'visible_at' | 'last_state_change' | 'log'> & {
 	created_at: string | Date
@@ -21,6 +22,7 @@ export class TriggerPayloadPersister {
 		private readonly identityId: string,
 		private readonly userInfo: { ipAddress: string | null; userAgent: string | null },
 		private readonly triggeredActionsCollector: TriggeredActionsCollector | undefined,
+		private readonly metrics: ProjectActionsMetrics | undefined,
 	) {
 	}
 
@@ -62,6 +64,10 @@ export class TriggerPayloadPersister {
 				.values(rows)
 				.execute(this.client)
 
+			// Counted before commit (events are written in the mutation's transaction); a rollback
+			// would over-count enqueued. Acceptable for a backlog *trend*, which is the intended use.
+			this.metrics?.enqueued(rows.length)
+
 			if (collected && collected.length > 0) {
 				collector!.add(collected)
 			}

package/tests/cases/unit/actionsMetrics.test.ts

@@ -0,0 +1,76 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import { Registry } from 'prom-client'
+import { ActionsMetrics } from '../../../src/ActionsMetrics.js'
+
+// Parse the Prometheus text exposition (the actual /metrics output) rather than getMetricsAsJSON,
+// whose return type doesn't expose sample values.
+const valueFor = async (registry: Registry, name: string, project: string): Promise<number | undefined> => {
+	const text = await registry.metrics()
+	const line = text
+		.split('\n')
+		.find(it => it.startsWith(`${name}{`) && it.includes(`contember_project="${project}"`))
+	if (!line) {
+		return undefined
+	}
+	return Number(line.slice(line.lastIndexOf(' ') + 1))
+}
+
+describe('ActionsMetrics', () => {
+	let registry: Registry
+	let metrics: ActionsMetrics
+
+	beforeEach(() => {
+		registry = new Registry()
+		metrics = new ActionsMetrics(registry)
+	})
+
+	test('counts are labelled by project via forProject', async () => {
+		metrics.forProject('blog').enqueued(3)
+		metrics.forProject('shop').enqueued(5)
+
+		expect(await valueFor(registry, 'contember_actions_events_enqueued_total', 'blog')).toBe(3)
+		expect(await valueFor(registry, 'contember_actions_events_enqueued_total', 'shop')).toBe(5)
+	})
+
+	test('accumulates across calls', async () => {
+		const project = metrics.forProject('blog')
+		project.succeeded(2)
+		project.succeeded(4)
+		project.deliveryAttemptFailed(1)
+		project.failed(1)
+
+		expect(await valueFor(registry, 'contember_actions_events_succeeded_total', 'blog')).toBe(6)
+		expect(await valueFor(registry, 'contember_actions_delivery_attempts_failed_total', 'blog')).toBe(1)
+		expect(await valueFor(registry, 'contember_actions_events_failed_total', 'blog')).toBe(1)
+	})
+
+	test('zero counts are a no-op (no series created)', async () => {
+		metrics.forProject('blog').enqueued(0)
+
+		expect(await valueFor(registry, 'contember_actions_events_enqueued_total', 'blog')).toBeUndefined()
+	})
+
+	test('heartbeat sets a recent timestamp, dispose removes only the heartbeat series', async () => {
+		const project = metrics.forProject('blog')
+		project.succeeded(1)
+		project.heartbeat()
+
+		const beat = await valueFor(registry, 'contember_actions_worker_heartbeat_timestamp_seconds', 'blog')
+		expect(beat).toBeGreaterThan(1_700_000_000)
+
+		project.dispose()
+
+		// heartbeat series gone (a removed project must not look perpetually stuck)...
+		expect(await valueFor(registry, 'contember_actions_worker_heartbeat_timestamp_seconds', 'blog')).toBeUndefined()
+		// ...but the counter is untouched
+		expect(await valueFor(registry, 'contember_actions_events_succeeded_total', 'blog')).toBe(1)
+	})
+
+	test('crash counter increments per crash', async () => {
+		const project = metrics.forProject('blog')
+		project.crashed()
+		project.crashed()
+
+		expect(await valueFor(registry, 'contember_actions_worker_crashed_total', 'blog')).toBe(2)
+	})
+})

package/tests/cases/unit/eventsRepository.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from 'bun:test'
+import { Client, Connection, EventManager } from '@contember/database'
+import { createLogger, TestLoggerHandler } from '@contember/logger'
+import { Actions } from '@contember/schema'
+import { EventsRepository } from '../../../src/dispatch/EventsRepository.js'
+import { HandledEvent } from '../../../src/dispatch/types.js'
+import { createTestEvent } from '../../src/event.js'
+import { testUuid } from '../../src/uuid.js'
+
+/**
+ * Answers statements from a script, then with an empty result, so what is under test is the
+ * repository's own bookkeeping rather than any SQL.
+ */
+const createStubClient = (responses: Connection.Result[] = []): Client => {
+	const remaining = [...responses]
+	const eventManager = new EventManager()
+	const query = async <Row extends Record<string, any>>(): Promise<Connection.Result<Row>> => {
+		const next = remaining.shift() ?? { rowCount: 0, rows: [] }
+		return { rowCount: next.rowCount, rows: next.rows as Row[] }
+	}
+	const transaction: Connection.TransactionLike = {
+		eventManager,
+		isClosed: false,
+		query,
+		scope: cb => Promise.resolve(cb(transaction)),
+		transaction: cb => Promise.resolve(cb(transaction)),
+		on: () => () => {},
+		rollback: async () => {},
+		commit: async () => {},
+	}
+	const connection: Connection.ConnectionLike = {
+		eventManager,
+		query,
+		scope: cb => Promise.resolve(cb(transaction)),
+		transaction: cb => Promise.resolve(cb(transaction)),
+	}
+	return new Client(connection, 'system', {})
+}
+
+const target: Actions.WebhookTarget = {
+	name: 'test_target',
+	type: 'webhook',
+	url: 'http://localhost',
+	maxAttempts: 3,
+}
+
+const createFailedEvent = (numRetries: number): HandledEvent => ({
+	row: createTestEvent(0, { num_retries: numRetries, state: 'processing' }),
+	target,
+	result: { ok: false, code: 401, errorMessage: 'Unauthorized' },
+})
+
+const errorsOf = (handler: TestLoggerHandler) => handler.messages.filter(it => it.level.name === 'error')
+
+describe('persistProcessed', () => {
+	test('logs an error when the last attempt fails', async () => {
+		const testLoggerHandler = new TestLoggerHandler()
+
+		const result = await new EventsRepository().persistProcessed(
+			createStubClient(),
+			[createFailedEvent(2)],
+			createLogger(testLoggerHandler),
+		)
+
+		expect(result).toEqual({ succeeded: 0, retried: 0, failed: 1 })
+		const errors = errorsOf(testLoggerHandler)
+		expect(errors).toHaveLength(1)
+		expect(errors[0].message).toBe('Action event failed permanently, no attempts left')
+		// exact match: neither the target URL nor its headers may end up in the log
+		expect(errors[0].ownAttributes).toStrictEqual({
+			eventId: testUuid(1),
+			target: 'test_target',
+			trigger: 'test',
+			attempts: 3,
+			code: 401,
+			errorMessage: 'Unauthorized',
+		})
+	})
+
+	test('stays quiet while attempts remain', async () => {
+		const testLoggerHandler = new TestLoggerHandler()
+
+		const result = await new EventsRepository().persistProcessed(
+			createStubClient(),
+			[createFailedEvent(0)],
+			createLogger(testLoggerHandler),
+		)
+
+		expect(result).toEqual({ succeeded: 0, retried: 1, failed: 0 })
+		expect(errorsOf(testLoggerHandler)).toHaveLength(0)
+	})
+})
+
+describe('fetchBatch', () => {
+	const eventRow = createTestEvent(0, { state: 'processing' })
+
+	test('logs an error when the event names a target the schema does not have', async () => {
+		const testLoggerHandler = new TestLoggerHandler()
+		const client = createStubClient([
+			{ rowCount: 1, rows: [eventRow] },
+			{ rowCount: 1, rows: [] },
+		])
+
+		const result = await new EventsRepository().fetchBatch(
+			{ triggers: {}, targets: {} },
+			client,
+			createLogger(testLoggerHandler),
+		)
+
+		expect(result).toEqual({ ok: false, backoffMs: undefined, unknownTargetFailed: 1 })
+		const errors = errorsOf(testLoggerHandler)
+		expect(errors).toHaveLength(1)
+		expect(errors[0].message).toBe('Action event failed permanently, its target is not in the schema')
+		expect(errors[0].ownAttributes).toStrictEqual({
+			eventId: testUuid(1),
+			target: 'test_target',
+			trigger: 'test',
+		})
+	})
+
+	test('stays quiet when the target is in the schema', async () => {
+		const testLoggerHandler = new TestLoggerHandler()
+		const client = createStubClient([
+			{ rowCount: 1, rows: [eventRow] },
+		])
+
+		const result = await new EventsRepository().fetchBatch(
+			{ triggers: {}, targets: { test_target: target } },
+			client,
+			createLogger(testLoggerHandler),
+		)
+
+		expect(result).toEqual({ ok: true, events: [eventRow], target, unknownTargetFailed: 0 })
+		expect(testLoggerHandler.messages).toStrictEqual([])
+	})
+})