Create alert action publisher

Author: cnasikas

x-pack/platform/plugins/shared/alerting_v2/server/index.ts

@@ -14,6 +14,7 @@ import { bindOnSetup } from './setup/bind_on_setup';
 import { bindOnStart } from './setup/bind_on_start';
 import { bindRoutes } from './setup/bind_routes';
 import { bindServices } from './setup/bind_services';
+import { bindEvents } from './setup/bind_events';
 import { bindRuleExecutionServices } from './setup/bind_rule_executor';
 import { bindDispatcherExecutionServices } from './setup/bind_dispatcher_executor';
 import { bindTasks } from './setup/bind_tasks';
@@ -28,6 +29,7 @@ export const module = new ContainerModule((options) => {
   bindContract(options);
   bindRoutes(options);
   bindServices(options);
+  bindEvents(options);
   bindRuleExecutionServices(options);
   bindDispatcherExecutionServices(options);
   bindTasks(options);

x-pack/platform/plugins/shared/alerting_v2/server/lib/events/alert_action_event_publisher/alert_action_event_publisher.mock.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import type { EventBus } from '../event_bus';
+import { createEventBusMock } from '../event_bus/event_bus.mock';
+import type { AlertingDomainEvent } from '../domain_events';
+import { AlertActionEventPublisher } from './alert_action_event_publisher';
+
+/**
+ * Builds a real {@link AlertActionEventPublisher} wired to a jest-mocked
+ * {@link EventBus}. Use this when you want to test the publisher's
+ * translation/dispatch behaviour against assertions on the bus.
+ */
+export function createAlertActionEventPublisher(): {
+  publisher: AlertActionEventPublisher;
+  eventBus: jest.Mocked<EventBus<AlertingDomainEvent>>;
+} {
+  const eventBus = createEventBusMock<AlertingDomainEvent>();
+
+  return {
+    publisher: new AlertActionEventPublisher(eventBus),
+    eventBus,
+  };
+}

x-pack/platform/plugins/shared/alerting_v2/server/lib/events/alert_action_event_publisher/alert_action_event_publisher.test.ts

@@ -0,0 +1,102 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import type { EventBus } from '../event_bus';
+import type { AlertingDomainEvent } from '../domain_events';
+import { createAlertActionEventPublisher } from './alert_action_event_publisher.mock';
+import type { AlertActionEventPublisher } from './alert_action_event_publisher';
+import { EPISODE_ASSIGNED_EVENT_TYPE } from './events';
+
+describe('AlertActionEventPublisher', () => {
+  jest.useFakeTimers().setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+
+  let publisher: AlertActionEventPublisher;
+  let eventBus: jest.Mocked<EventBus<AlertingDomainEvent>>;
+
+  beforeEach(() => {
+    ({ publisher, eventBus } = createAlertActionEventPublisher());
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  afterAll(() => {
+    jest.useRealTimers();
+  });
+
+  describe('emitEpisodeAssigned', () => {
+    it('publishes an `episode.assigned` event with the canonical envelope and payload shape', () => {
+      publisher.emitEpisodeAssigned({
+        groupHash: 'group-hash-1',
+        episodeId: 'episode-1',
+        ruleId: 'rule-1',
+        spaceId: 'default',
+        assigneeUid: 'user-uid-1',
+        actorUid: 'actor-uid-1',
+        occurredAt: '2025-02-02T12:34:56.000Z',
+      });
+
+      expect(eventBus.publish).toHaveBeenCalledTimes(1);
+      expect(eventBus.publish).toHaveBeenCalledWith({
+        type: EPISODE_ASSIGNED_EVENT_TYPE,
+        occurredAt: '2025-02-02T12:34:56.000Z',
+        groupHash: 'group-hash-1',
+        episodeId: 'episode-1',
+        ruleId: 'rule-1',
+        spaceId: 'default',
+        actorUid: 'actor-uid-1',
+        payload: {
+          assigneeUid: 'user-uid-1',
+        },
+      });
+    });
+
+    it('defaults `occurredAt` to the current ISO timestamp when omitted', () => {
+      publisher.emitEpisodeAssigned({
+        groupHash: 'group-hash-1',
+        episodeId: 'episode-1',
+        ruleId: 'rule-1',
+        spaceId: 'default',
+        assigneeUid: 'user-uid-1',
+        actorUid: 'actor-uid-1',
+      });
+
+      expect(eventBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({ occurredAt: '2026-01-01T00:00:00.000Z' })
+      );
+    });
+
+    it('preserves a null assigneeUid in the payload (unassign case)', () => {
+      publisher.emitEpisodeAssigned({
+        groupHash: 'group-hash-1',
+        episodeId: 'episode-1',
+        ruleId: 'rule-1',
+        spaceId: 'default',
+        assigneeUid: null,
+        actorUid: 'actor-uid-1',
+      });
+
+      expect(eventBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({ payload: { assigneeUid: null } })
+      );
+    });
+
+    it('preserves a null actorUid on the envelope (internal / system actor case)', () => {
+      publisher.emitEpisodeAssigned({
+        groupHash: 'group-hash-1',
+        episodeId: 'episode-1',
+        ruleId: 'rule-1',
+        spaceId: 'default',
+        assigneeUid: 'user-uid-1',
+        actorUid: null,
+      });
+
+      expect(eventBus.publish).toHaveBeenCalledWith(expect.objectContaining({ actorUid: null }));
+    });
+  });
+});

x-pack/platform/plugins/shared/alerting_v2/server/lib/events/alert_action_event_publisher/alert_action_event_publisher.ts

@@ -0,0 +1,100 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { inject, injectable } from 'inversify';
+import type { EventBus } from '../event_bus';
+import { AlertingDomainEventBusToken, type AlertingDomainEvent } from '../domain_events';
+import {
+  EPISODE_ASSIGNED_EVENT_TYPE,
+  type AlertActionEventEnvelope,
+  type EpisodeAssignedEvent,
+} from './events';
+
+/**
+ * Caller-friendly inputs shared by every `emit*` method on the publisher.
+ *
+ * Each method extends this with its event-specific payload fields, kept
+ * flat so callers construct a single object rather than a nested
+ * `{ envelope, payload }` shape. The publisher does the lift.
+ */
+export interface BaseEmitAlertActionParams {
+  readonly groupHash: string;
+  readonly episodeId: string;
+  readonly ruleId: string;
+  readonly spaceId: string;
+  /** Actor user-profile uid, or `null` for internal/system actors. */
+  readonly actorUid: string | null;
+  /**
+   * ISO timestamp of when the action occurred. Defaults to
+   * `new Date().toISOString()` when omitted.
+   */
+  readonly occurredAt?: string;
+}
+
+/** Caller-friendly parameters for {@link AlertActionEventPublisherContract.emitEpisodeAssigned}. */
+export interface EmitEpisodeAssignedParams extends BaseEmitAlertActionParams {
+  /** New assignee user-profile uid, or `null` when unassigning. */
+  readonly assigneeUid: string | null;
+}
+
+/**
+ * Public contract for the alert-action event publisher.
+ *
+ * One method per concrete event. Additional `emit*` methods will be added
+ * as the other alert-action types (ack, snooze, tag, …) start publishing.
+ */
+export interface AlertActionEventPublisherContract {
+  emitEpisodeAssigned(params: EmitEpisodeAssignedParams): void;
+}
+
+/**
+ * Singleton publisher of alert-action domain events onto the in-process
+ * {@link EventBus}.
+ *
+ * Owns the construction of the canonical event shape (envelope + payload).
+ * Each `emit*` method:
+ *
+ *  1. Lifts the common envelope from the caller's flat params via
+ *     {@link AlertActionEventPublisher#buildEnvelope}, including the
+ *     `occurredAt` timestamp default.
+ *  2. Builds the event-specific `payload`.
+ *  3. Tags the result with the event's `type` discriminator and publishes.
+ *
+ * Publishing is fire-and-forget — `publish` returns synchronously and
+ * subscriber work runs on the next event-loop iteration. See
+ * {@link EventBus} for the dispatch contract.
+ */
+@injectable()
+export class AlertActionEventPublisher implements AlertActionEventPublisherContract {
+  constructor(
+    @inject(AlertingDomainEventBusToken)
+    private readonly eventBus: EventBus<AlertingDomainEvent>
+  ) {}
+
+  public emitEpisodeAssigned(params: EmitEpisodeAssignedParams): void {
+    const event: EpisodeAssignedEvent = {
+      type: EPISODE_ASSIGNED_EVENT_TYPE,
+      ...this.buildEnvelope(params),
+      payload: {
+        assigneeUid: params.assigneeUid,
+      },
+    };
+
+    this.eventBus.publish(event);
+  }
+
+  private buildEnvelope(common: BaseEmitAlertActionParams): AlertActionEventEnvelope {
+    return {
+      occurredAt: common.occurredAt ?? new Date().toISOString(),
+      groupHash: common.groupHash,
+      episodeId: common.episodeId,
+      ruleId: common.ruleId,
+      spaceId: common.spaceId,
+      actorUid: common.actorUid,
+    };
+  }
+}

x-pack/platform/plugins/shared/alerting_v2/server/lib/events/alert_action_event_publisher/events.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+/**
+ * Common envelope shared by every alert-action domain event.
+ *
+ * Captures the episode context (rule / group / episode / space), the actor
+ * who performed the action, and when the action occurred. Lifted out of
+ * individual events so subscribers can read this metadata uniformly
+ * (without switching on `type`) and so the publisher can construct it
+ * once per emit call.
+ */
+export interface AlertActionEventEnvelope {
+  /** ISO timestamp of when the event occurred. */
+  readonly occurredAt: string;
+  readonly groupHash: string;
+  readonly episodeId: string;
+  readonly ruleId: string;
+  readonly spaceId: string;
+  /**
+   * User-profile uid of the actor who performed the action, or `null`
+   * when the action was performed by an internal/system context (no user).
+   */
+  readonly actorUid: string | null;
+}
+
+/**
+ * Structure of every alert-action domain event.
+ *
+ * Concrete events specialise:
+ *  - `TType`    — the string-literal discriminator (e.g. `'episode.assigned'`).
+ *  - `TPayload` — the event-specific payload shape.
+ *
+ * The shared envelope fields stay at the top level so subscribers can read
+ * them uniformly. Per-event data lives under `payload`.
+ *
+ * @example
+ * ```ts
+ * type EpisodeAckedEvent = BaseAlertActionEvent<
+ *   'episode.acked',
+ *   { reason: string | null }
+ * >;
+ * ```
+ */
+export interface BaseAlertActionEvent<TType extends string, TPayload extends object>
+  extends AlertActionEventEnvelope {
+  readonly type: TType;
+  readonly payload: TPayload;
+}
+
+/** Discriminator value for {@link EpisodeAssignedEvent}. */
+export const EPISODE_ASSIGNED_EVENT_TYPE = 'episode.assigned' as const;
+
+/** Payload of {@link EpisodeAssignedEvent}. */
+export interface EpisodeAssignedPayload {
+  /** New assignee user-profile uid, or `null` when unassigning. */
+  readonly assigneeUid: string | null;
+}
+
+/**
+ * Domain event published when the assignee of an alerting episode changes —
+ * either set to a specific user, or cleared to `null`.
+ */
+export type EpisodeAssignedEvent = BaseAlertActionEvent<
+  typeof EPISODE_ASSIGNED_EVENT_TYPE,
+  EpisodeAssignedPayload
+>;
+
+/**
+ * Discriminated union of every alert-action domain event.
+ *
+ * Extend this when a new alert-action event type is added (ack, snooze,
+ * tag, …). Cross-domain events (rule executor, dispatcher) live under
+ * their own unions and are composed into `AlertingDomainEvent` in
+ * `lib/events/domain_events`.
+ */
+export type AlertActionEvent = EpisodeAssignedEvent;

x-pack/platform/plugins/shared/alerting_v2/server/lib/events/domain_events/index.ts

@@ -21,8 +21,52 @@
  *  3. Extend the {@link AlertingDomainEvent} union below.
  */
 
+import type { ServiceIdentifier } from 'inversify';
+import type { EventBus } from '../event_bus';
+import type { AlertActionEvent } from '../alert_action_event_publisher/events';
+
+export type {
+  AlertActionEvent,
+  AlertActionEventEnvelope,
+  BaseAlertActionEvent,
+  EpisodeAssignedEvent,
+  EpisodeAssignedPayload,
+} from '../alert_action_event_publisher/events';
+export { EPISODE_ASSIGNED_EVENT_TYPE } from '../alert_action_event_publisher/events';
+
+/**
+ * Discriminated union of every domain event the alerting framework publishes
+ * on its event bus.
+ *
+ * Composed from per-subdomain unions so each subdomain owns its own catalog
+ * (and its own envelope shape if it diverges). Today only the alert-action
+ * subdomain publishes. Future subdomains (rule executor, dispatcher) extend
+ * this union by adding their own sub-union here.
+ */
+export type AlertingDomainEvent = AlertActionEvent;
+
 /**
- * Discriminated union of every domain event the alerting framework publishes on its event bus.
- * Extend this when a new publisher is introduced.
+ * Inversify token for the singleton {@link EventBus} carrying every
+ * {@link AlertingDomainEvent}.
+ *
+ * Typed against the {@link AlertingDomainEvent} discriminated union so that
+ * subscribers receive a fully-narrowed event in their handler:
+ *
+ * ```ts
+ * constructor(@inject(AlertingDomainEventBusToken)
+ *             private readonly bus: EventBus<AlertingDomainEvent>) {}
+ *
+ * this.bus.subscribe('episode.assigned', (event) => {
+ *   // `event` is `EpisodeAssignedEvent` here — no cast needed.
+ * });
+ * ```
+ *
+ * Publishers can rely on the same narrowing on their `publish` call. The
+ * generic `EventBus<TEvent>` interface is contravariant in `TEvent` at its
+ * input positions, so the underlying `AsyncDomainEventBus` singleton
+ * (declared as `<DomainEvent>` by default) safely satisfies this narrower
+ * contract.
  */
-export type AlertingDomainEvent = Record<string, any>;
+export const AlertingDomainEventBusToken = Symbol.for(
+  'alerting_v2.AlertingDomainEventBus'
+) as ServiceIdentifier<EventBus<AlertingDomainEvent>>;