@fbsm/saga-core 0.1.0-beta.3 → 0.2.0-beta.1

package/README.md

@@ -121,19 +121,19 @@ interface RunnerOptions {
 
 **Handler execution flow**:
 
-1. Parse inbound message via `SagaParser`
-2. Look up handler in route map
-3. Wrap emit with `final` hint (if `{ final: true }`)
-4. Wrap emit with fork logic (if `{ fork: true }`) — creates sub-saga per emit
-5. Set `SagaContext` via `AsyncLocalStorage`
-6. Execute handler with retry on `SagaRetryableError`
-7. On retry exhaustion, call `participant.onRetryExhausted()` if defined
+1. Parse inbound message via `SagaParser` — if parsed (saga metadata found), route to saga handler; if null (no metadata), route to plain handler
+2. Look up handler in route map (`RouteEntry` supports both `sagaHandler` and `plainHandler` per topic)
+3. **Saga path**: Wrap emit with `final` hint (if `{ final: true }`), fork logic (if `{ fork: true }`), set `SagaContext` via `AsyncLocalStorage`
+4. Execute handler with retry on `SagaRetryableError`
+5. On non-retryable error: call `participant.onFail()` if defined (with independent retry)
+6. On retry exhaustion (from handle or onFail): call `participant.onRetryExhausted()` if defined
+7. **Plain path**: Parse payload, call `plainHandler(PlainMessage)` — no context, no emit, no retry
 
 ## SagaParser
 
 Parses inbound messages using a 3-layer fallback strategy:
 
-1. **Headers** — `saga-id` header present → metadata from headers, payload from body
+1. **Headers** — `saga-id` header present → metadata from headers (including `saga-occurred-at`), body is the raw user payload. Topic is derived from the message's topic field
 2. **W3C Baggage** — OpenTelemetry baggage present → extract saga context from baggage items
 3. **Legacy envelope** — Body contains `sagaId` field → full envelope in message body
 
@@ -146,6 +146,7 @@ When using the header-based format (default with `@fbsm/saga-transport-kafka`):
 | `saga-id`               | Saga instance ID                                       |
 | `saga-event-id`         | Unique event ID                                        |
 | `saga-causation-id`     | ID of the event that caused this one                   |
+| `saga-occurred-at`      | ISO timestamp of when the event occurred               |
 | `saga-step-name`        | Logical step name                                      |
 | `saga-published-at`     | ISO timestamp of publication                           |
 | `saga-schema-version`   | Schema version (currently `1`)                         |
@@ -157,20 +158,36 @@ When using the header-based format (default with `@fbsm/saga-transport-kafka`):
 | `saga-step-description` | Step description (optional)                            |
 | `saga-key`              | Partition key (optional)                               |
 
+**Message body**: The Kafka message body contains **only the user's payload** (e.g., `{"orderId":"456"}`). Event metadata such as `occurredAt` is transmitted via the headers listed above, not in the body. The topic is derived from the Kafka message topic (i.e., `message.topic`), not from a header.
+
 ## Errors
 
 | Error                            | Description                                                                                                 |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | `SagaError`                      | Base error class for all saga errors                                                                        |
 | `SagaRetryableError`             | Throw in handlers to trigger retry with exponential backoff. `new SagaRetryableError(message, maxRetries?)` |
-| `SagaDuplicateHandlerError`      | Two handlers registered for the same event type                                                             |
+| `SagaDuplicateHandlerError`      | Two handlers registered for the same topic                                                                  |
 | `SagaParseError`                 | Message parsing failed                                                                                      |
 | `SagaTransportNotConnectedError` | Publishing to a disconnected transport                                                                      |
 | `SagaContextNotFoundError`       | `emit()`/`startChild()`/`emitToParent()` called outside a saga context                                      |
 | `SagaNoParentError`              | `emitToParent()` called in a saga without `parentSagaId`                                                    |
 | `SagaInvalidHandlerConfigError`  | Handler has conflicting options (e.g., both `final` and `fork`)                                             |
 
-**Retry behavior**: `SagaRetryableError` triggers exponential backoff: `initialDelayMs * 2^attempt`. After `maxRetries` attempts, `onRetryExhausted()` is called if defined. Non-retryable errors are logged and skipped.
+**Retry behavior**: `SagaRetryableError` triggers exponential backoff: `initialDelayMs * 2^attempt`. After `maxRetries` attempts, `onRetryExhausted()` is called if defined. Non-retryable errors are routed to `onFail()` if defined; otherwise logged and skipped.
+
+**Error flow**:
+
+```
+handle(event, emit)
+  ├── SUCCESS → done
+  ├── throws SagaRetryableError → retry → exhausted → onRetryExhausted?
+  └── throws non-retryable Error
+        ├── onFail defined → call onFail (retries independently)
+        │     ├── onFail succeeds → done
+        │     ├── onFail retries exhausted → onRetryExhausted?
+        │     └── onFail throws non-retryable → log → done
+        └── onFail not defined → log → done
+```
 
 ## OTel Integration
 
@@ -250,7 +267,7 @@ Default: `ConsoleSagaLogger` (wraps `console.log/warn/error`).
 
 ## Further Reading
 
-- [Concepts](../doc/concepts.md) — sagaId, hint, eventType, and other domain terms
+- [Concepts](../doc/concepts.md) — sagaId, hint, topic, and other domain terms
 - [Core Functions](../doc/core-functions.md) — emit, emitToParent, start, startChild, forSaga
 - [@fbsm/saga-nestjs](../saga-nestjs/README.md) — NestJS decorators and auto-discovery
 - [@fbsm/saga-transport-kafka](../saga-transport-kafka/README.md) — Kafka transport

package/dist/index.cjs

@@ -122,11 +122,13 @@ var SagaRunner = class {
   }
   routeMap;
   async start() {
-    this.routeMap = this.registry.buildRouteMap();
+    const baseRouteMap = this.registry.buildRouteMap();
     const prefix = this.options.topicPrefix ?? "";
-    const topics = Array.from(this.routeMap.keys()).map(
-      (et) => `${prefix}${et}`
-    );
+    this.routeMap = /* @__PURE__ */ new Map();
+    for (const [topic, entry] of baseRouteMap) {
+      this.routeMap.set(`${prefix}${topic}`, entry);
+    }
+    const topics = Array.from(this.routeMap.keys());
     await this.transport.connect();
     if (topics.length > 0) {
       this.logger.info(
@@ -160,16 +162,27 @@ var SagaRunner = class {
     };
   }
   async handleMessage(message) {
+    const route = this.routeMap.get(message.topic);
+    if (!route) {
+      return;
+    }
     const event = this.parser.parse(message);
-    if (!event) return;
-    const route = this.routeMap.get(event.eventType);
-    if (!route) return;
-    const isFinalHandler = route.options?.final === true;
+    if (event && route.sagaHandler) {
+      await this.handleSagaMessage(message, event, route);
+      return;
+    }
+    if (!event && route.plainHandler) {
+      await this.handlePlainMessage(message, route);
+      return;
+    }
+  }
+  async handleSagaMessage(message, event, route) {
+    const isFinalHandler = route.sagaOptions?.final === true;
     const incoming = {
       sagaId: event.sagaId,
       eventId: event.eventId,
       causationId: event.causationId,
-      eventType: event.eventType,
+      topic: event.topic,
       stepName: event.stepName,
       stepDescription: event.stepDescription,
       occurredAt: event.occurredAt,
@@ -193,7 +206,7 @@ var SagaRunner = class {
       const finalParams = isFinalHandler ? { ...params, hint: "final" } : params;
       return emit(finalParams);
     };
-    const forkConfig = route.options?.fork;
+    const forkConfig = route.sagaOptions?.fork;
     const finalEmit = forkConfig ? async (params) => {
       const subSagaId = (0, import_uuid.v7)();
       const subEmit = this.publisher.forSaga(
@@ -222,11 +235,11 @@ var SagaRunner = class {
     } : wrappedEmit;
     const spanAttrs = {
       "saga.id": event.sagaId,
-      "saga.event.type": event.eventType,
+      "saga.topic": event.topic,
       "saga.step.name": event.stepName,
       "saga.event.id": event.eventId,
       "saga.root.id": event.rootSagaId,
-      "saga.handler.service": route.participant.serviceId
+      "saga.handler.service": route.sagaParticipant.serviceId
     };
     if (event.sagaName) spanAttrs["saga.name"] = event.sagaName;
     if (event.sagaDescription)
@@ -246,15 +259,15 @@ var SagaRunner = class {
     const runHandler = () => SagaContext.run(
       sagaCtxData,
       () => this.runWithRetry(
-        route.handler,
-        route.participant,
+        route.sagaHandler,
+        route.sagaParticipant,
         incoming,
         finalEmit
       )
     );
     if (this.otelCtx) {
       await this.otelCtx.withExtractedSpan(
-        `saga.handle ${event.eventType}`,
+        `saga.handle ${event.topic}`,
         spanAttrs,
         message.headers,
         runHandler
@@ -263,12 +276,65 @@ var SagaRunner = class {
       await runHandler();
     }
   }
+  async handlePlainMessage(message, route) {
+    let payload;
+    try {
+      payload = JSON.parse(message.value);
+    } catch {
+      payload = message.value;
+    }
+    const plainMessage = {
+      topic: message.topic,
+      key: message.key,
+      payload,
+      headers: message.headers
+    };
+    await route.plainHandler(plainMessage);
+  }
   async runWithRetry(handler, participant, event, emit) {
+    try {
+      await this.executeWithRetry(handler, event, emit);
+    } catch (error) {
+      if (error instanceof SagaRetryableError) {
+        await this.callOnRetryExhausted(participant, event, error, emit);
+        return;
+      }
+      if (participant.onFail) {
+        try {
+          await this.executeWithRetry(
+            (ev, em) => participant.onFail(ev, error, em),
+            event,
+            emit
+          );
+        } catch (failError) {
+          if (failError instanceof SagaRetryableError) {
+            await this.callOnRetryExhausted(
+              participant,
+              event,
+              failError,
+              emit
+            );
+          } else {
+            this.logger.error(
+              `[SagaRunner] onFail threw non-retryable error for ${event.topic}:`,
+              failError
+            );
+          }
+        }
+        return;
+      }
+      this.logger.error(
+        `[SagaRunner] Non-retryable error in handler for ${event.topic}:`,
+        error
+      );
+    }
+  }
+  async executeWithRetry(fn, event, emit) {
     const maxRetries = this.options.retryPolicy?.maxRetries ?? 3;
     const initialDelayMs = this.options.retryPolicy?.initialDelayMs ?? 200;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
-        await handler(event, emit);
+        await fn(event, emit);
         return;
       } catch (error) {
         if (error instanceof SagaRetryableError) {
@@ -277,19 +343,17 @@ var SagaRunner = class {
             await this.sleep(delay);
             continue;
           }
-          if (participant.onRetryExhausted) {
-            await participant.onRetryExhausted(event, error, emit);
-          }
-          return;
+          throw error;
         }
-        this.logger.error(
-          `[SagaRunner] Non-retryable error in handler for ${event.eventType}:`,
-          error
-        );
-        return;
+        throw error;
       }
     }
   }
+  async callOnRetryExhausted(participant, event, error, emit) {
+    if (participant.onRetryExhausted) {
+      await participant.onRetryExhausted(event, error, emit);
+    }
+  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -308,7 +372,7 @@ var SagaNoParentError = class extends SagaError {
 
 // src/publisher/message-builder.ts
 function buildOutboundMessage(event, topicPrefix = "") {
-  const topic = `${topicPrefix}${event.eventType}`;
+  const topic = `${topicPrefix}${event.topic}`;
   const key = event.key ?? event.rootSagaId;
   const headers = {
     "saga-id": event.sagaId,
@@ -337,11 +401,8 @@ function buildOutboundMessage(event, topicPrefix = "") {
   if (event.key) {
     headers["saga-key"] = event.key;
   }
-  const value = JSON.stringify({
-    eventType: event.eventType,
-    occurredAt: event.occurredAt,
-    payload: event.payload
-  });
+  headers["saga-occurred-at"] = event.occurredAt;
+  const value = JSON.stringify(event.payload);
   return { topic, key, value, headers };
 }
 
@@ -425,7 +486,7 @@ var SagaPublisher = class {
     const parentSagaId = parentCtx?.parentSagaId;
     const baseCausationId = causationId ?? sagaId;
     return async ({
-      eventType,
+      topic,
       stepName,
       stepDescription,
       payload,
@@ -439,7 +500,7 @@ var SagaPublisher = class {
         sagaId,
         causationId: baseCausationId,
         eventId: (0, import_uuid2.v7)(),
-        eventType,
+        topic,
         stepName,
         stepDescription,
         occurredAt: now,
@@ -464,7 +525,7 @@ var SagaPublisher = class {
     );
     const attrs = {
       "saga.id": event.sagaId,
-      "saga.event.type": event.eventType,
+      "saga.topic": event.topic,
       "saga.step.name": event.stepName,
       "saga.root.id": event.rootSagaId
     };
@@ -484,7 +545,7 @@ var SagaPublisher = class {
     const message = buildOutboundMessage(event, this.topicPrefix);
     this.otelCtx.injectTraceContext(message.headers);
     await this.otelCtx.withSpan(
-      `saga.publish ${event.eventType}`,
+      `saga.publish ${event.topic}`,
       attrs,
       () => this.transport.publish(message)
     );
@@ -515,7 +576,7 @@ var SagaParser = class {
   }
   parseFromHeaders(message) {
     const headers = message.headers;
-    const body = JSON.parse(message.value);
+    const payload = JSON.parse(message.value);
     const sagaId = headers["saga-id"];
     if (!sagaId) {
       return null;
@@ -524,14 +585,14 @@ var SagaParser = class {
       sagaId,
       causationId: headers["saga-causation-id"] ?? sagaId,
       eventId: headers["saga-event-id"] ?? (0, import_uuid3.v7)(),
-      eventType: body.eventType,
+      topic: message.topic,
       stepName: headers["saga-step-name"] ?? "",
-      occurredAt: body.occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      occurredAt: headers["saga-occurred-at"] ?? (/* @__PURE__ */ new Date()).toISOString(),
       publishedAt: headers["saga-published-at"] ?? (/* @__PURE__ */ new Date()).toISOString(),
       schemaVersion: 1,
       rootSagaId: headers["saga-root-id"] ?? sagaId,
       parentSagaId: headers["saga-parent-id"] || void 0,
-      payload: body.payload,
+      payload,
       sagaName: headers["saga-name"] || void 0,
       sagaDescription: headers["saga-description"] || void 0,
       stepDescription: headers["saga-step-description"] || void 0,
@@ -561,7 +622,7 @@ var SagaParser = class {
       sagaId,
       causationId: sagaId,
       eventId: (0, import_uuid3.v7)(),
-      eventType: body.eventType,
+      topic: body.topic,
       stepName: "",
       occurredAt: body.occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
       publishedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -585,9 +646,9 @@ var SagaParser = class {
 
 // src/errors/saga-duplicate-handler.error.ts
 var SagaDuplicateHandlerError = class extends SagaError {
-  constructor(eventType, existingServiceId, newServiceId) {
+  constructor(topic, existingServiceId, newServiceId) {
     super(
-      `Duplicate handler for event type "${eventType}": registered by "${existingServiceId}" and "${newServiceId}"`
+      `Duplicate handler for event type "${topic}": registered by "${existingServiceId}" and "${newServiceId}"`
     );
     this.name = "SagaDuplicateHandlerError";
   }
@@ -595,9 +656,9 @@ var SagaDuplicateHandlerError = class extends SagaError {
 
 // src/errors/saga-invalid-handler-config.error.ts
 var SagaInvalidHandlerConfigError = class extends SagaError {
-  constructor(eventType, serviceId, reason) {
+  constructor(topic, serviceId, reason) {
     super(
-      `Invalid handler config for "${eventType}" in "${serviceId}": ${reason}`
+      `Invalid handler config for "${topic}" in "${serviceId}": ${reason}`
     );
     this.name = "SagaInvalidHandlerConfigError";
   }
@@ -615,24 +676,46 @@ var SagaRegistry = class {
   buildRouteMap() {
     const map = /* @__PURE__ */ new Map();
     for (const participant of this.participants) {
-      for (const [eventType, handler] of Object.entries(participant.on)) {
-        if (map.has(eventType)) {
-          const existing = map.get(eventType);
+      for (const [topic, handler] of Object.entries(participant.on)) {
+        const existing = map.get(topic) ?? {};
+        if (existing.sagaHandler) {
           throw new SagaDuplicateHandlerError(
-            eventType,
-            existing.participant.serviceId,
+            topic,
+            existing.sagaParticipant.serviceId,
             participant.serviceId
           );
         }
-        const options = participant.handlerOptions?.[eventType];
+        const options = participant.handlerOptions?.[topic];
         if (options?.final && options?.fork) {
           throw new SagaInvalidHandlerConfigError(
-            eventType,
+            topic,
             participant.serviceId,
             "cannot have both final and fork options"
           );
         }
-        map.set(eventType, { participant, handler, options });
+        map.set(topic, {
+          ...existing,
+          sagaParticipant: participant,
+          sagaHandler: handler,
+          sagaOptions: options
+        });
+      }
+      if (participant.onPlain) {
+        for (const [topic, handler] of Object.entries(participant.onPlain)) {
+          const existing = map.get(topic) ?? {};
+          if (existing.plainHandler) {
+            throw new SagaDuplicateHandlerError(
+              topic,
+              existing.plainParticipant.serviceId,
+              participant.serviceId
+            );
+          }
+          map.set(topic, {
+            ...existing,
+            plainParticipant: participant,
+            plainHandler: handler
+          });
+        }
       }
     }
     return map;