@emmett-community/emmett-google-pubsub 0.2.0 → 0.4.0

package/README.md

@@ -378,6 +378,65 @@ JavaScript `Date` objects are preserved through serialization:
 
 See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for design decisions.
 
+## Observability
+
+The package supports optional observability through structured logging and OpenTelemetry tracing.
+
+### Logging
+
+Logging is opt-in and completely silent by default. To enable logging, provide a logger that implements the canonical `(context, message)` contract:
+
+```typescript
+const messageBus = getPubSubMessageBus({
+  pubsub,
+  observability: {
+    logger: {
+      debug: (context, message) => console.debug(message, context),
+      info: (context, message) => console.info(message, context),
+      warn: (context, message) => console.warn(message, context),
+      error: (context, message) => console.error(message, context),
+    },
+  },
+});
+```
+
+**Logger Contract:**
+
+The logger MUST implement the canonical `(context, message)` contract:
+
+- `context`: Structured data as `Record<string, unknown>` (first parameter)
+- `message`: Human-readable log message (second parameter, optional)
+
+Pino is natively compatible. For Winston, use an adapter.
+
+**Log Levels:**
+
+- `info` - Lifecycle events (start, stop)
+- `debug` - External I/O operations (publish, subscribe)
+- `warn` - Recoverable failures (timeouts, retries)
+- `error` - Failures (with Error objects in `{ err: error }` format)
+
+### Tracing (OpenTelemetry)
+
+The package creates OpenTelemetry spans for key operations. Tracing is passive - the `@opentelemetry/api` is a no-op by default.
+
+To enable tracing, configure OpenTelemetry in your application:
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+const sdk = new NodeSDK({ /* config */ });
+sdk.start();
+
+// Spans from emmett-google-pubsub are now captured
+const messageBus = getPubSubMessageBus({ pubsub });
+```
+
+**Notes:**
+
+- The package never initializes OpenTelemetry
+- No tracing flags needed - spans are always created (no-op if SDK not initialized)
+- Message types and payloads are never included in spans or logs
+
 ## Compatibility
 
 - **Node.js**: >= 18.0.0

package/dist/index.d.mts

@@ -1,6 +1,45 @@
 import { PubSub, Topic, Subscription, Message as Message$1 } from '@google-cloud/pubsub';
 import { Message, SingleMessageHandler, Command, Event, SingleRawMessageHandlerWithoutContext, AnyMessage, MessageBus, EventSubscription, CommandProcessor, ScheduledMessageProcessor } from '@event-driven-io/emmett';
 
+/**
+ * Canonical Logger contract for the Emmett ecosystem.
+ *
+ * DO NOT MODIFY this interface without updating ALL packages in the ecosystem.
+ *
+ * This package defines the canonical Logger interface.
+ * Implementations (Pino, Winston, etc.) MUST adapt to this contract.
+ * This contract MUST NOT adapt to any specific implementation.
+ *
+ * Semantic Rules:
+ * - context (first parameter): ALWAYS structured data as Record<string, unknown>
+ * - message (second parameter): ALWAYS the human-readable log message
+ * - The order is NEVER inverted
+ * - The (message, data) form is NOT valid for this contract
+ * - Error objects MUST use the 'err' key (frozen semantic)
+ *
+ * @example
+ * ```typescript
+ * // Pino - native compatibility
+ * import pino from 'pino';
+ * const logger = pino();
+ * // logger.info({ orderId }, 'Order created') matches our contract
+ * ```
+ */
+interface Logger {
+    debug(context: Record<string, unknown>, message?: string): void;
+    info(context: Record<string, unknown>, message?: string): void;
+    warn(context: Record<string, unknown>, message?: string): void;
+    error(context: Record<string, unknown>, message?: string): void;
+}
+/**
+ * Observability configuration options.
+ */
+interface ObservabilityOptions {
+    /**
+     * Optional logger instance. When not provided, the library operates silently.
+     */
+    logger?: Logger;
+}
 /**
  * Configuration for PubSub MessageBus
  */
@@ -43,6 +82,11 @@ interface PubSubMessageBusConfig {
      * @default true
      */
     closePubSubClient?: boolean;
+    /**
+     * Observability options (logging).
+     * If not provided, the package remains silent.
+     */
+    observability?: ObservabilityOptions;
 }
 /**
  * Subscription configuration options
@@ -217,14 +261,16 @@ declare function getOrCreateSubscription(topic: Topic, subscriptionName: string,
  * Delete a subscription
  *
  * @param subscription - The subscription to delete
+ * @param logger - Optional logger for observability
  */
-declare function deleteSubscription(subscription: Subscription): Promise<void>;
+declare function deleteSubscription(subscription: Subscription, logger?: Logger): Promise<void>;
 /**
  * Delete multiple subscriptions
  *
  * @param subscriptions - Array of subscriptions to delete
+ * @param logger - Optional logger for observability
  */
-declare function deleteSubscriptions(subscriptions: Subscription[]): Promise<void>;
+declare function deleteSubscriptions(subscriptions: Subscription[], logger?: Logger): Promise<void>;
 
 /**
  * Generate a random UUID
@@ -351,18 +397,20 @@ declare function shouldRetry(error: unknown): boolean;
  * @param message - The PubSub message
  * @param handlers - Map of message type to handlers
  * @param commandType - The command type being processed
+ * @param logger - Optional logger for observability
  * @returns 'ack' if successful or permanent failure, 'nack' if retriable failure
  */
-declare function handleCommandMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, commandType: string): Promise<'ack' | 'nack'>;
+declare function handleCommandMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, commandType: string, logger?: Logger): Promise<'ack' | 'nack'>;
 /**
  * Process an incoming event message from PubSub
  *
  * @param message - The PubSub message
  * @param handlers - Map of message type to handlers
  * @param eventType - The event type being processed
+ * @param logger - Optional logger for observability
  * @returns 'ack' if all handlers successful or permanent failure, 'nack' if retriable failure
  */
-declare function handleEventMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, eventType: string): Promise<'ack' | 'nack'>;
+declare function handleEventMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, eventType: string, logger?: Logger): Promise<'ack' | 'nack'>;
 /**
  * Create a message listener for a PubSub subscription
  *
@@ -370,8 +418,9 @@ declare function handleEventMessage(message: Message$1, handlers: Map<string, Si
  * @param messageType - The message type (command or event type)
  * @param kind - Whether this is a command or event
  * @param handlers - Map of message type to handlers
+ * @param logger - Optional logger for observability
  */
-declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>): void;
+declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, logger?: Logger): void;
 
 /**
  * Create a Google Cloud Pub/Sub based message bus for Emmett
@@ -410,4 +459,4 @@ declare function createMessageListener(subscription: Subscription, messageType:
  */
 declare function getPubSubMessageBus(config: PubSubMessageBusConfig): MessageBus & EventSubscription & CommandProcessor & ScheduledMessageProcessor & PubSubMessageBusLifecycle;
 
-export { type HandlerRegistration, MessageScheduler, type PubSubMessageBusConfig, type PubSubMessageBusLifecycle, type PubSubMessageEnvelope, type ScheduleOptions, type ScheduledMessage, type ScheduledMessageInfo, type SchedulerConfig, type SubscriptionInfo, type SubscriptionOptions, assertNotEmptyString, assertPositiveNumber, attachMessageId, calculateScheduledTime, createMessageListener, deleteSubscription, deleteSubscriptions, deserialize, extractMessageId, filterReadyMessages, generateUUID, getCommandSubscriptionName, getCommandTopicName, getEventSubscriptionName, getEventTopicName, getOrCreateSubscription, getOrCreateTopic, getPubSubMessageBus, handleCommandMessage, handleEventMessage, serialize, shouldRetry };
+export { type HandlerRegistration, type Logger, MessageScheduler, type ObservabilityOptions, type PubSubMessageBusConfig, type PubSubMessageBusLifecycle, type PubSubMessageEnvelope, type ScheduleOptions, type ScheduledMessage, type ScheduledMessageInfo, type SchedulerConfig, type SubscriptionInfo, type SubscriptionOptions, assertNotEmptyString, assertPositiveNumber, attachMessageId, calculateScheduledTime, createMessageListener, deleteSubscription, deleteSubscriptions, deserialize, extractMessageId, filterReadyMessages, generateUUID, getCommandSubscriptionName, getCommandTopicName, getEventSubscriptionName, getEventTopicName, getOrCreateSubscription, getOrCreateTopic, getPubSubMessageBus, handleCommandMessage, handleEventMessage, serialize, shouldRetry };

package/dist/index.d.ts

@@ -1,6 +1,45 @@
 import { PubSub, Topic, Subscription, Message as Message$1 } from '@google-cloud/pubsub';
 import { Message, SingleMessageHandler, Command, Event, SingleRawMessageHandlerWithoutContext, AnyMessage, MessageBus, EventSubscription, CommandProcessor, ScheduledMessageProcessor } from '@event-driven-io/emmett';
 
+/**
+ * Canonical Logger contract for the Emmett ecosystem.
+ *
+ * DO NOT MODIFY this interface without updating ALL packages in the ecosystem.
+ *
+ * This package defines the canonical Logger interface.
+ * Implementations (Pino, Winston, etc.) MUST adapt to this contract.
+ * This contract MUST NOT adapt to any specific implementation.
+ *
+ * Semantic Rules:
+ * - context (first parameter): ALWAYS structured data as Record<string, unknown>
+ * - message (second parameter): ALWAYS the human-readable log message
+ * - The order is NEVER inverted
+ * - The (message, data) form is NOT valid for this contract
+ * - Error objects MUST use the 'err' key (frozen semantic)
+ *
+ * @example
+ * ```typescript
+ * // Pino - native compatibility
+ * import pino from 'pino';
+ * const logger = pino();
+ * // logger.info({ orderId }, 'Order created') matches our contract
+ * ```
+ */
+interface Logger {
+    debug(context: Record<string, unknown>, message?: string): void;
+    info(context: Record<string, unknown>, message?: string): void;
+    warn(context: Record<string, unknown>, message?: string): void;
+    error(context: Record<string, unknown>, message?: string): void;
+}
+/**
+ * Observability configuration options.
+ */
+interface ObservabilityOptions {
+    /**
+     * Optional logger instance. When not provided, the library operates silently.
+     */
+    logger?: Logger;
+}
 /**
  * Configuration for PubSub MessageBus
  */
@@ -43,6 +82,11 @@ interface PubSubMessageBusConfig {
      * @default true
      */
     closePubSubClient?: boolean;
+    /**
+     * Observability options (logging).
+     * If not provided, the package remains silent.
+     */
+    observability?: ObservabilityOptions;
 }
 /**
  * Subscription configuration options
@@ -217,14 +261,16 @@ declare function getOrCreateSubscription(topic: Topic, subscriptionName: string,
  * Delete a subscription
  *
  * @param subscription - The subscription to delete
+ * @param logger - Optional logger for observability
  */
-declare function deleteSubscription(subscription: Subscription): Promise<void>;
+declare function deleteSubscription(subscription: Subscription, logger?: Logger): Promise<void>;
 /**
  * Delete multiple subscriptions
  *
  * @param subscriptions - Array of subscriptions to delete
+ * @param logger - Optional logger for observability
  */
-declare function deleteSubscriptions(subscriptions: Subscription[]): Promise<void>;
+declare function deleteSubscriptions(subscriptions: Subscription[], logger?: Logger): Promise<void>;
 
 /**
  * Generate a random UUID
@@ -351,18 +397,20 @@ declare function shouldRetry(error: unknown): boolean;
  * @param message - The PubSub message
  * @param handlers - Map of message type to handlers
  * @param commandType - The command type being processed
+ * @param logger - Optional logger for observability
  * @returns 'ack' if successful or permanent failure, 'nack' if retriable failure
  */
-declare function handleCommandMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, commandType: string): Promise<'ack' | 'nack'>;
+declare function handleCommandMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, commandType: string, logger?: Logger): Promise<'ack' | 'nack'>;
 /**
  * Process an incoming event message from PubSub
  *
  * @param message - The PubSub message
  * @param handlers - Map of message type to handlers
  * @param eventType - The event type being processed
+ * @param logger - Optional logger for observability
  * @returns 'ack' if all handlers successful or permanent failure, 'nack' if retriable failure
  */
-declare function handleEventMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, eventType: string): Promise<'ack' | 'nack'>;
+declare function handleEventMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, eventType: string, logger?: Logger): Promise<'ack' | 'nack'>;
 /**
  * Create a message listener for a PubSub subscription
  *
@@ -370,8 +418,9 @@ declare function handleEventMessage(message: Message$1, handlers: Map<string, Si
  * @param messageType - The message type (command or event type)
  * @param kind - Whether this is a command or event
  * @param handlers - Map of message type to handlers
+ * @param logger - Optional logger for observability
  */
-declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>): void;
+declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, logger?: Logger): void;
 
 /**
  * Create a Google Cloud Pub/Sub based message bus for Emmett
@@ -410,4 +459,4 @@ declare function createMessageListener(subscription: Subscription, messageType:
  */
 declare function getPubSubMessageBus(config: PubSubMessageBusConfig): MessageBus & EventSubscription & CommandProcessor & ScheduledMessageProcessor & PubSubMessageBusLifecycle;
 
-export { type HandlerRegistration, MessageScheduler, type PubSubMessageBusConfig, type PubSubMessageBusLifecycle, type PubSubMessageEnvelope, type ScheduleOptions, type ScheduledMessage, type ScheduledMessageInfo, type SchedulerConfig, type SubscriptionInfo, type SubscriptionOptions, assertNotEmptyString, assertPositiveNumber, attachMessageId, calculateScheduledTime, createMessageListener, deleteSubscription, deleteSubscriptions, deserialize, extractMessageId, filterReadyMessages, generateUUID, getCommandSubscriptionName, getCommandTopicName, getEventSubscriptionName, getEventTopicName, getOrCreateSubscription, getOrCreateTopic, getPubSubMessageBus, handleCommandMessage, handleEventMessage, serialize, shouldRetry };
+export { type HandlerRegistration, type Logger, MessageScheduler, type ObservabilityOptions, type PubSubMessageBusConfig, type PubSubMessageBusLifecycle, type PubSubMessageEnvelope, type ScheduleOptions, type ScheduledMessage, type ScheduledMessageInfo, type SchedulerConfig, type SubscriptionInfo, type SubscriptionOptions, assertNotEmptyString, assertPositiveNumber, attachMessageId, calculateScheduledTime, createMessageListener, deleteSubscription, deleteSubscriptions, deserialize, extractMessageId, filterReadyMessages, generateUUID, getCommandSubscriptionName, getCommandTopicName, getEventSubscriptionName, getEventTopicName, getOrCreateSubscription, getOrCreateTopic, getPubSubMessageBus, handleCommandMessage, handleEventMessage, serialize, shouldRetry };