@pagermon/ingest-core 1.0.0

package/.env.example

@@ -0,0 +1,20 @@
+# PagerMon Ingest Core configuration
+#
+# Prefixes:
+# - Core:    INGEST_CORE__*
+# - Adapter: INGEST_ADAPTER__*
+
+# Core runtime settings
+INGEST_CORE__LABEL=pagermon-ingest
+INGEST_CORE__API_URL=http://pagermon:3000
+INGEST_CORE__API_KEY=your_api_key_here
+INGEST_CORE__REDIS_URL=redis://redis:6379
+INGEST_CORE__ENABLE_DLQ=true
+INGEST_CORE__HEALTH_CHECK_INTERVAL=10000
+INGEST_CORE__HEALTH_UNHEALTHY_THRESHOLD=3
+
+# Adapter settings are forwarded to the selected adapter entry.
+# Example keys (actual keys depend on the adapter implementation):
+# INGEST_ADAPTER__FREQUENCIES=163000000
+# INGEST_ADAPTER__PROTOCOLS=POCSAG512
+# INGEST_ADAPTER__SMTP__HOST=smtp.example.org

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.0"
+}

package/README.md

@@ -0,0 +1,165 @@
+# @pagermon/ingest-core
+
+Shared ingest core runtime for PagerMon.
+
+---
+
+> **Looking to run PagerMon Ingest with RTL-SDR?**  
+> You probably want the [multimon adapter repository](https://github.com/eopo/ingest-adapter-multimon) instead.  
+> This repository is the shared core runtime library and is only relevant if you're developing custom adapters or contributing to the core.
+
+---
+
+## What This Is
+
+This repository contains the stable core pipeline shared by all PagerMon ingest adapters:
+
+- config parsing and validation
+- queue and worker processing
+- API client and health monitor
+- adapter orchestration and lifecycle management
+
+It does **not** contain a concrete source adapter implementation (RTL-SDR, SMTP, etc.).
+
+## Who This Is For
+
+- **Adapter developers**: building custom ingest sources
+- **Core contributors**: improving shared runtime behavior
+- **Not for**: end users who just want to run a ready-made adapter
+
+If you just want to run PagerMon Ingest with RTL-SDR hardware, use a concrete adapter repository instead of this one.
+
+## Architecture At A Glance
+
+`@pagermon/ingest-core` separates reusable runtime concerns from source-specific logic.
+
+- Core runtime responsibilities:
+  - read and validate config
+  - initialize queue/API/health/worker services
+  - start an adapter and consume emitted messages
+  - enqueue normalized messages for API delivery
+- Adapter responsibilities (in adapter repo):
+  - read from a concrete source (SDR, SMTP, polling, etc.)
+  - parse source-specific payloads
+  - emit normalized `Message` objects
+
+This split keeps source integration complexity out of the core and allows multiple adapter repos to share one stable runtime.
+
+## Runtime Flow
+
+On startup, the core follows this sequence:
+
+1. Validate `INGEST_CORE__*` configuration.
+2. Initialize API client, queue manager, health monitor, and worker.
+3. Load/create adapter instance.
+4. Start adapter stream processing.
+5. For each emitted message:
+   - set source label
+   - enqueue message
+   - worker submits to PagerMon API
+6. On signal/error: stop adapter pipeline and core services gracefully.
+
+This behavior is orchestrated in `lib/runtime/service.js` and `lib/runtime/pipeline.js`.
+
+## Repository Structure
+
+Important paths in this repository:
+
+- `index.js`: default entrypoint (loader mode)
+- `bootstrap.js`: bootstrap API used by adapter repos
+- `lib/config.js`: env parsing and validation
+- `lib/core/`: queue, API, worker, health services
+- `lib/runtime/`: adapter loader and runtime orchestration
+- `lib/message/Message.js`: shared normalized message model
+- `test/unit/`, `test/integration/`: core runtime tests
+
+## Adapter Convention
+
+A concrete adapter image must provide this module:
+
+- `/app/adapter/adapter.js`
+
+The core loads that module at startup and validates the runtime adapter contract (`getName`, `start`, `stop`, `isRunning`).
+
+## Configuration Prefixes
+
+- Core: `INGEST_CORE__*`
+- Adapter: `INGEST_ADAPTER__*`
+
+The core forwards adapter keys as structured config (`adapter`) and raw env map (`rawEnv`) to the selected adapter.
+
+Example mapping:
+
+- Env: `INGEST_ADAPTER__SMTP__HOST=smtp.example.org`
+- In adapter: `this.config.adapter.smtp.host === 'smtp.example.org'`
+- Raw fallback: `this.config.rawEnv.INGEST_ADAPTER__SMTP__HOST`
+
+## Runtime Modes
+
+`@pagermon/ingest-core` supports two startup modes:
+
+- Default loader mode: `node index.js`
+- Bootstrap mode: adapter repo entrypoint calls `bootstrapWithAdapter(AdapterClass)`
+
+Default loader mode expects an adapter entry module at `/app/adapter/adapter.js`
+(override with `INGEST_CORE__ADAPTER_ENTRY`).
+
+Bootstrap mode lets adapter repos pass the adapter class directly and avoids path conventions.
+
+Use loader mode when your container layout already provides `/app/adapter/adapter.js`.
+Use bootstrap mode when your adapter repo wants explicit startup control in code.
+
+## Development
+
+```bash
+npm ci
+npm run check
+npm test
+```
+
+## Container
+
+Build core image:
+
+```bash
+docker build -t shutterfire/ingest-core:latest .
+```
+
+## Using Ingest with PagerMon Server
+
+Ingest sends messages to PagerMon server API endpoint `INGEST_CORE__API_URL`.
+
+If both services run in one compose project, set:
+
+```bash
+INGEST_CORE__API_URL=http://pagermon:3000
+```
+
+Where `pagermon` is the server service name.
+
+## Developing Your Own Adapter
+
+You can always build your own adapter to support other sources, such as PDW, incoming emails, polling from websites and so on.
+
+- Full adapter contract and implementation guide: [ADAPTER_DEVELOPMENT.md](./ADAPTER_DEVELOPMENT.md)
+
+Rule of thumb:
+
+- change this repo when runtime behavior should be shared by all adapters
+- change adapter repo when behavior is source-specific
+
+If you only need to run Ingest, you can ignore this section.
+
+## Contribution
+
+If you plan to change code in this repository, use [CONTRIBUTING.md](./CONTRIBUTING.md) as the primary guide.
+
+Quick local quality check:
+
+```bash
+npm run lint
+npm test
+```
+
+Detailed testing conventions and adapter integration test behavior are documented in
+[CONTRIBUTING.md](./CONTRIBUTING.md).

package/bootstrap.js

@@ -0,0 +1,10 @@
+import { runService } from './lib/runtime/service.js';
+
+export function bootstrapWithAdapter(AdapterClass) {
+  if (typeof AdapterClass !== 'function') {
+    throw new TypeError('bootstrapWithAdapter requires an adapter class/constructor');
+  }
+
+  const adapterFactory = (adapterConfig) => new AdapterClass(adapterConfig);
+  return runService({ adapterFactory });
+}

package/eslint.config.mjs

@@ -0,0 +1,74 @@
+import js from '@eslint/js';
+import prettier from 'eslint-plugin-prettier';
+import prettierConfig from 'eslint-config-prettier';
+import globals from 'globals';
+
+export default [
+  js.configs.recommended,
+  prettierConfig,
+  {
+    plugins: {
+      prettier,
+    },
+    rules: {
+      // Prettier integration: options come from .prettierrc
+      'prettier/prettier': 'error',
+
+      // Console statements (allowed in Node.js service)
+      'no-console': 'off',
+
+      // Variable declarations
+      'no-var': 'warn',
+      'prefer-const': 'warn',
+
+      // Naming conventions
+      camelcase: ['warn', { properties: 'never', ignoreDestructuring: true }],
+
+      // Code quality
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      'no-unused-expressions': 'off',
+      'no-use-before-define': ['error', { functions: false, classes: true, variables: true }],
+
+      // Best practices
+      eqeqeq: ['error', 'always', { null: 'ignore' }],
+      'no-shadow': 'warn',
+      'no-param-reassign': ['warn', { props: false }],
+      'prefer-arrow-callback': 'warn',
+      'prefer-template': 'warn',
+      'no-else-return': 'warn',
+      'object-shorthand': ['warn', 'always'],
+      'prefer-destructuring': ['warn', { object: true, array: false }],
+
+      // Error handling
+      'no-throw-literal': 'error',
+      'prefer-promise-reject-errors': 'error',
+
+      // Async/await
+      'require-await': 'warn',
+      'no-await-in-loop': 'warn',
+
+      // Security
+      'no-eval': 'error',
+      'no-implied-eval': 'error',
+      'no-new-func': 'error',
+    },
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: 'module',
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ['test/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.vitest,
+      },
+    },
+  },
+  {
+    ignores: ['node_modules/**', 'coverage/**', 'docs/**', '*.min.js'],
+  },
+];

package/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { createAdapter } from './lib/runtime/adapter-loader.js';
+import { runService } from './lib/runtime/service.js';
+
+runService({ adapterFactory: createAdapter });

package/lib/config.js

@@ -0,0 +1,119 @@
+/**
+ * Configuration Module
+ *
+ * Configuration prefixes:
+ * - Core: INGEST_CORE__*
+ * - Adapter: INGEST_ADAPTER__*
+ */
+
+function getCoreEnv(key, fallback = null) {
+  const value = process.env[`INGEST_CORE__${key}`];
+  return value !== undefined ? value : fallback;
+}
+
+function parseAdapterConfig() {
+  const result = {};
+
+  for (const [envKey, value] of Object.entries(process.env)) {
+    if (!envKey.startsWith('INGEST_ADAPTER__')) {
+      continue;
+    }
+
+    const tail = envKey.slice('INGEST_ADAPTER__'.length);
+    const parts = tail.split('__').filter(Boolean);
+
+    // Expected minimum: <KEY>
+    if (parts.length < 1) {
+      continue;
+    }
+
+    const path = parts.map((part) => part.toLowerCase());
+    let node = result;
+    for (let i = 0; i < path.length - 1; i++) {
+      const segment = path[i];
+      if (typeof node[segment] !== 'object' || node[segment] === null) {
+        node[segment] = {};
+      }
+      node = node[segment];
+    }
+
+    node[path[path.length - 1]] = value;
+  }
+
+  return result;
+}
+
+function getAdapterRawEnv() {
+  const raw = {};
+  for (const [envKey, value] of Object.entries(process.env)) {
+    if (envKey.startsWith('INGEST_ADAPTER__')) {
+      raw[envKey] = value;
+    }
+  }
+  return raw;
+}
+
+function parseInteger(value, fallback = null) {
+  if (value === null || value === undefined || value === '') {
+    return fallback;
+  }
+
+  const parsed = parseInt(value, 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+
+const adapterConfig = parseAdapterConfig();
+const adapterRawEnv = getAdapterRawEnv();
+
+const config = {
+  // Service configuration
+  label: getCoreEnv('LABEL', 'pagermon-ingest'),
+
+  // Adapter configuration (single adapter prefix)
+  adapterConfig,
+  adapterRawEnv,
+
+  // Core services configuration
+  apiUrl: getCoreEnv('API_URL', 'http://pagermon:3000'),
+  apiKey: getCoreEnv('API_KEY', null),
+  redisUrl: getCoreEnv('REDIS_URL', 'redis://redis:6379'),
+  enableDLQ: getCoreEnv('ENABLE_DLQ', 'true') !== 'false',
+
+  // Health check configuration
+  healthCheckInterval: parseInteger(getCoreEnv('HEALTH_CHECK_INTERVAL', '10000'), 10000),
+  healthCheckUnhealthyThreshold: parseInteger(getCoreEnv('HEALTH_UNHEALTHY_THRESHOLD', '3'), 3),
+};
+
+/**
+ * Validate required configuration
+ */
+function validate() {
+  const errors = [];
+
+  if (!config.apiKey) {
+    errors.push('INGEST_CORE__API_KEY not set');
+  }
+
+  if (errors.length > 0) {
+    console.error('Configuration errors:');
+    errors.forEach((e) => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Build source adapter configuration
+ */
+function buildAdapterConfig() {
+  return {
+    label: config.label,
+    adapter: config.adapterConfig,
+    rawEnv: config.adapterRawEnv,
+  };
+}
+
+export default {
+  ...config,
+  validate,
+  buildAdapterConfig,
+};

package/lib/core/ApiClient.js

@@ -0,0 +1,207 @@
+/**
+ * API Client - PagerMon API communication
+ *
+ * Handles HTTP communication with the PagerMon API.
+ */
+
+import http from 'http';
+import https from 'https';
+
+// Error classes
+class TimeoutError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'TimeoutError';
+  }
+}
+
+class AuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AuthError';
+    this.isAuth = true;
+  }
+}
+
+class ClientError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ClientError';
+  }
+}
+
+class ServerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ServerError';
+  }
+}
+
+class ApiClient {
+  /**
+   * @param {Object} config
+   * @param {string} config.url - API Base URL
+   * @param {string} config.apiKey - API key for authentication
+   * @param {Object} [options] - Additional options
+   */
+  constructor(config, options = {}) {
+    if (!config.url) throw new Error('ApiClient requires config.url');
+    if (!config.apiKey) throw new Error('ApiClient requires config.apiKey');
+
+    this.url = config.url;
+    this.apiKey = config.apiKey;
+    this.timeout = options.timeout || 10000;
+    this.retries = options.retries || 3;
+    this.retryDelay = options.retryDelay || 1000;
+  }
+
+  /**
+   * Submit a message to the API
+   * @param {Message|Object} message - Message with address, message, format, etc.
+   * @returns {Promise<Object>} API response
+   */
+  async submitMessage(message) {
+    const payload = message.toPayload ? message.toPayload() : message;
+
+    try {
+      const result = await this._request('POST', '/api/messages', payload);
+      return { success: true, data: result };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
+  /**
+   * Check API health
+   * @returns {Promise<boolean>}
+   */
+  async checkHealth() {
+    try {
+      const result = await this._request('GET', '/api/health', null, {
+        timeout: 5000,
+        retries: 1,
+      });
+      return result && result.status === 'ok';
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Make HTTP request with retry logic
+   * @private
+   */
+  async _request(method, path, body = null, options = {}) {
+    const timeout = options.timeout || this.timeout;
+    const maxRetries = options.retries !== undefined ? options.retries : this.retries;
+
+    let lastErr;
+
+    // Sequential retry with exponential backoff is intentional here.
+    /* eslint-disable no-await-in-loop */
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this._makeRequest(method, path, body, timeout);
+      } catch (err) {
+        lastErr = err;
+
+        // Only retry on transient errors
+        if (!this._isTransientError(err)) {
+          throw err;
+        }
+
+        if (attempt < maxRetries) {
+          const delay = this.retryDelay * Math.pow(2, attempt); // Exponential backoff
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    /* eslint-enable no-await-in-loop */
+
+    throw lastErr;
+  }
+
+  /**
+   * Actually execute the HTTP request
+   * @private
+   */
+  _makeRequest(method, path, body, timeout) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, this.url);
+      const isHttps = url.protocol === 'https:';
+      const client = isHttps ? https : http;
+
+      const bodyStr = body ? JSON.stringify(body) : null;
+
+      const options = {
+        method,
+        timeout,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.apiKey,
+        },
+      };
+
+      if (bodyStr) {
+        options.headers['Content-Length'] = Buffer.byteLength(bodyStr);
+      }
+
+      const req = client.request(url, options, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          try {
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+              const parsed = data ? JSON.parse(data) : {};
+              resolve(parsed);
+            } else if (res.statusCode === 401) {
+              reject(new AuthError('Unauthorized'));
+            } else if (res.statusCode >= 400 && res.statusCode < 500) {
+              reject(new ClientError(`${res.statusCode}: ${data}`));
+            } else {
+              reject(new ServerError(`${res.statusCode}: ${data}`));
+            }
+          } catch (err) {
+            reject(err);
+          }
+        });
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new TimeoutError('Request timeout'));
+      });
+
+      req.on('error', (err) => {
+        reject(err);
+      });
+
+      if (bodyStr) {
+        req.write(bodyStr);
+      }
+
+      req.end();
+    });
+  }
+
+  /**
+   * Determine if an error is transient (retryable)
+   * @private
+   */
+  _isTransientError(err) {
+    if (err instanceof TimeoutError) return true;
+    if (err instanceof ServerError) return true;
+    if (err instanceof ClientError) return false; // 4xx errors don't retry
+    if (err instanceof AuthError) return false; // 401 doesn't retry
+    if (err.code === 'ECONNREFUSED') return true;
+    if (err.code === 'ETIMEDOUT') return true;
+    if (err.code === 'EHOSTUNREACH') return true;
+    return false;
+  }
+}
+
+export default ApiClient;

package/lib/core/HealthMonitor.js

@@ -0,0 +1,120 @@
+/**
+ * Health Monitor - API availability monitoring
+ *
+ * Tracks API availability only.
+ */
+
+class HealthMonitor {
+  /**
+   * @param {Object} config
+   * @param {ApiClient} config.apiClient - API client for health checks
+   * @param {Object} [options] - Additional options
+   */
+  constructor(config, options = {}) {
+    if (!config.apiClient) throw new Error('HealthMonitor requires config.apiClient');
+
+    this.apiClient = config.apiClient;
+    this.checkInterval = options.checkInterval || 10000; // 10 seconds
+    this.unhealthyThreshold = options.unhealthyThreshold || 3;
+
+    this.isHealthy = true;
+    this.failureCount = 0;
+    this.lastCheckTime = null;
+    this.timer = null;
+    this.callbacks = {
+      onHealthChange: null,
+      onCheck: null,
+    };
+  }
+
+  /**
+   * Register callbacks
+   */
+  on(event, callback) {
+    if (event === 'healthChange' || event === 'check') {
+      this.callbacks[`on${event.charAt(0).toUpperCase()}${event.slice(1)}`] = callback;
+    }
+  }
+
+  /**
+   * Start the monitor
+   */
+  start() {
+    console.log('[HEALTH] Starting health monitor');
+    this.perform();
+    this.timer = setInterval(() => this.perform(), this.checkInterval);
+  }
+
+  /**
+   * Stop the monitor
+   */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    console.log('[HEALTH] Health monitor stopped');
+  }
+
+  /**
+   * Perform one health check cycle
+   */
+  async perform() {
+    try {
+      const wasHealthy = this.isHealthy;
+      this.lastCheckTime = new Date();
+
+      const healthy = await this.apiClient.checkHealth();
+
+      if (healthy) {
+        this.isHealthy = true;
+        this.failureCount = 0;
+      } else {
+        this.failureCount++;
+        if (this.failureCount >= this.unhealthyThreshold) {
+          this.isHealthy = false;
+        }
+      }
+
+      if (this.callbacks.onCheck) {
+        this.callbacks.onCheck({
+          healthy: this.isHealthy,
+          failureCount: this.failureCount,
+          timestamp: this.lastCheckTime,
+        });
+      }
+
+      if (wasHealthy !== this.isHealthy && this.callbacks.onHealthChange) {
+        this.callbacks.onHealthChange({
+          healthy: this.isHealthy,
+          timestamp: this.lastCheckTime,
+        });
+      }
+    } catch (err) {
+      console.error('[HEALTH] Check error:', err.message);
+      this.failureCount++;
+      if (this.failureCount >= this.unhealthyThreshold && this.isHealthy) {
+        this.isHealthy = false;
+        if (this.callbacks.onHealthChange) {
+          this.callbacks.onHealthChange({
+            healthy: false,
+            timestamp: new Date(),
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Current status snapshot
+   */
+  getStatus() {
+    return {
+      healthy: this.isHealthy,
+      failureCount: this.failureCount,
+      lastCheck: this.lastCheckTime,
+    };
+  }
+}
+
+export default HealthMonitor;

package/lib/core/QueueManager.js

@@ -0,0 +1,156 @@
+/**
+ * Message Queue Manager - BullMQ based message queue
+ *
+ * Handles message queue management only.
+ */
+
+import { Queue, Worker as BullWorker } from 'bullmq';
+import IORedis from 'ioredis';
+
+class QueueManager {
+  /**
+   * @param {Object} config
+   * @param {string} config.redisUrl - Redis connection URL
+   * @param {Object} [options] - Additional options
+   */
+  constructor(config, options = {}) {
+    if (!config.redisUrl) throw new Error('QueueManager requires config.redisUrl');
+
+    this.redisUrl = config.redisUrl;
+    this.queueName = options.queueName || 'sdr-messages';
+    this.queue = null;
+    this.dlq = null;
+    this.worker = null;
+    this.connection = null;
+    this.workerConnection = null;
+    this.enableDLQ = options.enableDLQ !== false;
+  }
+
+  /**
+   * Initialize queue resources
+   */
+  initialize() {
+    this.connection = new IORedis(this.redisUrl, {
+      maxRetriesPerRequest: null,
+    });
+
+    this.queue = new Queue(this.queueName, {
+      connection: this.connection,
+      defaultJobOptions: {
+        attempts: 10,
+        backoff: {
+          type: 'exponential',
+          delay: 2000,
+        },
+        removeOnComplete: true,
+      },
+    });
+
+    if (this.enableDLQ) {
+      this.dlq = new Queue(`${this.queueName}-dlq`, {
+        connection: this.connection,
+      });
+    }
+
+    console.log(`[QUEUE] Initialized: ${this.queueName}`);
+  }
+
+  /**
+   * Enqueue a message
+   * @param {Message|Object} message
+   * @returns {Promise<Job>}
+   */
+  async addMessage(message) {
+    if (!this.queue) throw new Error('Queue not initialized. Call initialize() first.');
+
+    const payload = message.toPayload ? message.toPayload() : message;
+    const job = await this.queue.add('message', payload, {
+      jobId: `msg-${payload.source}-${payload.address}-${payload.timestamp}`,
+    });
+
+    console.debug(`[QUEUE] Added job ${job.id}`);
+    return job;
+  }
+
+  /**
+   * Get failed messages from the DLQ
+   * @returns {Promise<Object[]>}
+   */
+  async getDeadLetters(limit = 100) {
+    if (!this.enableDLQ || !this.dlq) {
+      return [];
+    }
+
+    const jobs = await this.dlq.getJobs(['failed'], 0, Math.max(0, limit - 1));
+    return jobs.map((job) => ({
+      id: job.id,
+      data: job.data,
+      failedReason: job.failedReason,
+      attemptsMade: job.attemptsMade,
+    }));
+  }
+
+  /**
+   * Get current queue size
+   */
+  async getQueueSize() {
+    if (!this.queue) return 0;
+    return await this.queue.count();
+  }
+
+  /**
+   * Start processing jobs using a BullMQ Worker
+   * @param {(job: import('bullmq').Job) => Promise<unknown>} processor
+   */
+  startProcessing(processor) {
+    if (this.worker) {
+      return;
+    }
+
+    // BullMQ worker uses blocking Redis operations; use dedicated connection.
+    this.workerConnection = this.connection.duplicate();
+
+    this.worker = new BullWorker(
+      this.queueName,
+      async (job) => {
+        return await processor(job);
+      },
+      {
+        connection: this.workerConnection,
+      }
+    );
+
+    this.worker.on('error', (err) => {
+      console.error('[QUEUE] Worker error:', err.message);
+    });
+  }
+
+  /**
+   * Close all queue connections
+   */
+  async close() {
+    if (this.worker) {
+      await this.worker.close();
+      this.worker = null;
+    }
+    if (this.queue) {
+      await this.queue.close();
+      this.queue = null;
+    }
+    if (this.dlq) {
+      await this.dlq.close();
+      this.dlq = null;
+    }
+    if (this.connection) {
+      await this.connection.quit();
+      this.connection = null;
+    }
+    if (this.workerConnection) {
+      await this.workerConnection.quit();
+      this.workerConnection = null;
+    }
+    console.log('[QUEUE] Closed');
+  }
+}
+
+export default QueueManager;

package/lib/core/Worker.js

@@ -0,0 +1,118 @@
+/**
+ * Worker - queue consumer that submits messages to the API
+ *
+ * Consumes messages from the queue and submits them to the API.
+ */
+
+class Worker {
+  /**
+   * @param {Object} config
+   * @param {QueueManager} config.queue - Queue manager
+   * @param {ApiClient} config.apiClient - API client
+   * @param {HealthMonitor} config.health - Health monitor
+   */
+  constructor(config) {
+    if (!config.queue) throw new Error('Worker requires config.queue');
+    if (!config.apiClient) throw new Error('Worker requires config.apiClient');
+    if (!config.health) throw new Error('Worker requires config.health');
+
+    this.queue = config.queue;
+    this.apiClient = config.apiClient;
+    this.health = config.health;
+    this.processing = false;
+    this.callbacks = {
+      onMessageProcessed: null,
+      onMessageFailed: null,
+    };
+  }
+
+  /**
+   * Register callbacks
+   */
+  on(event, callback) {
+    if (event === 'messageProcessed' || event === 'messageFailed') {
+      this.callbacks[`on${event.charAt(0).toUpperCase()}${event.slice(1)}`] = callback;
+    }
+  }
+
+  /**
+   * Start the worker and begin processing jobs
+   */
+  async start() {
+    console.log('[WORKER] Starting queue consumer');
+
+    if (!this.queue.queue) {
+      await this.queue.initialize();
+    }
+
+    this.processing = true;
+
+    // Process each message via QueueManager/BullMQ worker
+    this.queue.startProcessing((job) => this._processMessage(job));
+
+    console.log('[WORKER] Queue consumer started');
+  }
+
+  /**
+   * Process a single message
+   * @private
+   */
+  async _processMessage(job) {
+    const messageData = job.data;
+
+    const result = await this.apiClient.submitMessage(messageData);
+
+    if (result.success) {
+      console.debug(`[WORKER] Message sent: ${messageData.address}`);
+
+      if (this.callbacks.onMessageProcessed) {
+        this.callbacks.onMessageProcessed({
+          jobId: job.id,
+          message: messageData,
+        });
+      }
+
+      return result;
+    }
+    console.warn(`[WORKER] Message failed: ${messageData.address} - ${result.error}`);
+
+    // If API is unhealthy, throw to trigger queue retry
+    if (!this.health.isHealthy) {
+      throw new Error(`API unhealthy: ${result.error}`);
+    }
+
+    // For other failures, throw only for retryable classes
+    if (result.error && result.error.includes('401')) {
+      throw new Error('API Authentication failed - will not retry');
+    }
+
+    if (result.error && !result.error.includes('4')) {
+      // Server-side errors should be retried
+      throw new Error(result.error);
+    }
+
+    if (this.callbacks.onMessageFailed) {
+      this.callbacks.onMessageFailed({
+        jobId: job.id,
+        message: messageData,
+        error: result.error,
+      });
+    }
+
+    // Return a soft-failure payload without throwing
+    return { failed: true, error: result.error };
+  }
+
+  /**
+   * Stop the worker
+   */
+  async stop() {
+    this.processing = false;
+    if (this.queue) {
+      await this.queue.close();
+    }
+    console.log('[WORKER] Worker stopped');
+  }
+}
+
+export default Worker;

package/lib/message/Message.js

@@ -0,0 +1,75 @@
+/**
+ * Message Domain - normalized message structure
+ *
+ * Defines the standardized structure for all messages in the system.
+ */
+
+class Message {
+  /**
+   * @param {Object} data
+   * @param {string} data.address - Receiver address/capcode
+   * @param {string} data.message - Message text
+   * @param {string} data.format - 'alpha' or 'numeric'
+   * @param {string} data.source - Source label
+   * @param {number} [data.timestamp] - Unix timestamp
+   * @param {string} [data.time] - ISO8601 timestamp
+   * @param {Object} [data.metadata] - Optional protocol-specific metadata
+   */
+  constructor(data) {
+    if (!data.address) throw new Error('Message requires address');
+    if (!data.message && data.format === 'alpha') {
+      throw new Error('Alpha message requires message content');
+    }
+    if (!data.format) throw new Error('Message requires format');
+    if (!data.source) throw new Error('Message requires source');
+
+    this.address = String(data.address);
+    this.message = String(data.message || '');
+    this.format = data.format.toLowerCase();
+    this.source = data.source;
+    this.timestamp = data.timestamp || Math.floor(Date.now() / 1000);
+    this.time = data.time || new Date(this.timestamp * 1000).toISOString();
+    this.metadata = data.metadata || {};
+  }
+
+  /**
+   * Convert to API payload format
+   */
+  toPayload() {
+    return {
+      address: this.address,
+      message: this.message,
+      format: this.format,
+      source: this.source,
+      timestamp: this.timestamp,
+      time: this.time,
+      ...this.metadata,
+    };
+  }
+
+  /**
+   * Validate message shape and semantic constraints
+   */
+  validate() {
+    const errors = [];
+
+    if (!this.address || this.address.trim().length === 0) {
+      errors.push('address is required');
+    }
+
+    if (this.format === 'alpha' && this.message.trim().length === 0) {
+      errors.push('alpha messages require message content');
+    }
+
+    if (!['alpha', 'numeric'].includes(this.format)) {
+      errors.push(`invalid format: ${this.format}`);
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+}
+
+export default Message;

package/lib/runtime/adapter-loader.js

@@ -0,0 +1,32 @@
+const DEFAULT_ADAPTER_ENTRY = '/app/adapter/adapter.js';
+const REQUIRED_METHODS = ['getName', 'start', 'stop', 'isRunning'];
+
+function getAdapterEntry() {
+  const configured = process.env.INGEST_CORE__ADAPTER_ENTRY;
+  return configured && configured.trim() ? configured.trim() : DEFAULT_ADAPTER_ENTRY;
+}
+
+function validateAdapterInstance(instance) {
+  if (!instance || typeof instance !== 'object') {
+    throw new TypeError('Selected adapter must be an object instance');
+  }
+
+  for (const method of REQUIRED_METHODS) {
+    if (typeof instance[method] !== 'function') {
+      throw new TypeError(`Selected adapter missing required method: ${method}()`);
+    }
+  }
+}
+
+export async function createAdapter(config) {
+  const module = await import(getAdapterEntry());
+  const AdapterClass = module.default;
+
+  if (typeof AdapterClass !== 'function') {
+    throw new TypeError('Adapter module must export a default class or constructor function');
+  }
+
+  const instance = new AdapterClass(config);
+  validateAdapterInstance(instance);
+  return instance;
+}

package/lib/runtime/pipeline.js

@@ -0,0 +1,67 @@
+/**
+ * Orchestration Pipeline
+ *
+ * Orchestrates a unified source adapter.
+ * Used by the main application and contains no business logic.
+ */
+
+import { createAdapter } from './adapter-loader.js';
+
+class Orchestrator {
+  /**
+   * @param {Object} config
+   * @param {Object} config.adapter - Adapter configuration object
+   */
+  constructor(config) {
+    if (!config.adapter) {
+      throw new Error('Orchestrator requires adapter config');
+    }
+
+    this.config = config;
+    this.adapterFactory = config.adapterFactory || createAdapter;
+    this.adapter = null;
+  }
+
+  /**
+   * Initialize source adapter
+   */
+  async initialize() {
+    this.adapter = await this.adapterFactory(this.config.adapter);
+    console.log(`[ORCHESTRATOR] Source adapter: ${this.adapter.getName()}`);
+  }
+
+  /**
+   * Start reading messages from the adapter
+   * @param {Function} onMessage - Callback for each parsed message
+   * @param {Function} onClose - Callback when stream closes
+   * @param {Function} onError - Callback on stream error
+   */
+  async startReadingMessages(onMessage, onClose, onError) {
+    await this.adapter.start(onMessage, onClose, onError);
+  }
+
+  /**
+   * Stop the pipeline
+   */
+  async shutdown() {
+    console.log('[ORCHESTRATOR] Shutting down...');
+
+    if (this.adapter) {
+      await this.adapter.stop();
+    }
+
+    console.log('[ORCHESTRATOR] Shutdown complete');
+  }
+
+  /**
+   * Check status
+   */
+  getStatus() {
+    return {
+      adapterRunning: this.adapter && this.adapter.isRunning(),
+      adapterConfigured: !!this.config.adapter,
+    };
+  }
+}
+
+export default Orchestrator;

package/lib/runtime/service.js

@@ -0,0 +1,148 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import config from '../config.js';
+import ApiClient from '../core/ApiClient.js';
+import QueueManager from '../core/QueueManager.js';
+import HealthMonitor from '../core/HealthMonitor.js';
+import Worker from '../core/Worker.js';
+import Orchestrator from './pipeline.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8'));
+const { version } = packageJson;
+
+export async function runService({ adapterFactory } = {}) {
+  let orchestrator = null;
+  let api = null;
+  let queue = null;
+  let health = null;
+  let worker = null;
+
+  async function shutdown(code = 0) {
+    console.log('[MAIN] Shutting down...');
+
+    try {
+      if (orchestrator) {
+        await orchestrator.shutdown();
+      }
+
+      if (worker) {
+        await worker.stop();
+      }
+
+      if (queue) {
+        await queue.close();
+      }
+
+      if (health) {
+        health.stop();
+      }
+
+      console.log('[MAIN] Shutdown complete');
+      process.exit(code);
+    } catch (err) {
+      console.error('[MAIN] Shutdown error:', err.message);
+      process.exit(1);
+    }
+  }
+
+  config.validate();
+
+  console.log(`${'='.repeat(60)}`);
+  console.log(`Pagermon Ingest Service v${version}`);
+  console.log(`${'='.repeat(60)}`);
+  console.log(`Label:                 ${config.label}`);
+  console.log('Adapter:               /app/adapter/adapter.js');
+  console.log(`API URL:               ${config.apiUrl}`);
+  console.log(`Redis URL:             ${config.redisUrl}`);
+  console.log(`Dead Letter Queue:     ${config.enableDLQ ? 'enabled' : 'disabled'}`);
+  console.log(`${'='.repeat(60)}`);
+
+  try {
+    console.log('[MAIN] Initializing core services...');
+
+    api = new ApiClient({ url: config.apiUrl, apiKey: config.apiKey }, { timeout: 10000, retries: 3 });
+
+    queue = new QueueManager({ redisUrl: config.redisUrl }, { queueName: 'sdr-messages', enableDLQ: config.enableDLQ });
+    await queue.initialize();
+
+    health = new HealthMonitor(
+      { apiClient: api },
+      {
+        checkInterval: config.healthCheckInterval,
+        unhealthyThreshold: config.healthCheckUnhealthyThreshold,
+      }
+    );
+    health.start();
+
+    worker = new Worker({
+      queue,
+      apiClient: api,
+      health,
+    });
+
+    worker.on('messageProcessed', (info) => {
+      console.debug(`[WORKER] Processed: ${info.message.address}`);
+    });
+
+    worker.on('messageFailed', (info) => {
+      console.warn(`[WORKER] Failed: ${info.message.address} - ${info.error}`);
+    });
+
+    await worker.start();
+
+    console.log('[MAIN] Core services initialized');
+    console.log('[MAIN] Initializing adapters...');
+
+    orchestrator = new Orchestrator({
+      adapter: config.buildAdapterConfig(),
+      adapterFactory,
+    });
+
+    await orchestrator.initialize();
+
+    console.log('[MAIN] Starting message processing...');
+
+    await orchestrator.startReadingMessages(
+      async (message) => {
+        try {
+          message.source = config.label;
+          await queue.addMessage(message);
+        } catch (err) {
+          console.error('[MAIN] Failed to enqueue message:', err.message);
+        }
+      },
+      () => {
+        console.error('[MAIN] Message stream closed unexpectedly');
+        shutdown(1);
+      },
+      (err) => {
+        console.error('[MAIN] Message stream error:', err.message);
+        shutdown(1);
+      }
+    );
+
+    process.on('SIGINT', () => {
+      console.log('\n[MAIN] Received SIGINT');
+      shutdown(0);
+    });
+
+    process.on('SIGTERM', () => {
+      console.log('[MAIN] Received SIGTERM');
+      shutdown(0);
+    });
+
+    process.on('SIGQUIT', () => {
+      console.log('[MAIN] Received SIGQUIT');
+      shutdown(0);
+    });
+
+    console.log('[MAIN] Service started successfully');
+  } catch (err) {
+    console.error('[MAIN] Initialization error:', err.message);
+    console.error(err.stack);
+    process.exit(1);
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pagermon/ingest-core",
+  "version": "1.0.0",
+  "description": "PagerMon ingest core runtime",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "test": "vitest run --coverage",
+    "test:all": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"**/*.{js,mjs,json,md}\"",
+    "format:check": "prettier --check \"**/*.{js,mjs,json,md}\"",
+    "check": "npm run format:check && npm run lint",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "pagermon",
+    "sdr",
+    "rtl-sdr",
+    "multimon-ng",
+    "pocsag",
+    "flex"
+  ],
+  "author": "",
+  "license": "ISC",
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=9.0"
+  },
+  "dependencies": {
+    "bullmq": "^5.63.0",
+    "ioredis": "^5.8.2"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.16.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "globals": "^15.14.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.4.2",
+    "vitest": "^2.1.8"
+  }
+}

package/release-please-config.json

@@ -0,0 +1,11 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "package-name": "@pagermon/ingest-core",
+      "changelog-path": "CHANGELOG.md",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false
+    }
+  }
+}