@winkjs/composer 0.0.2 → 0.4.0

package/src/core/codec/index.js

@@ -0,0 +1,137 @@
+// src/core/codec/index.js
+
+/**
+ * @fileoverview Universal codec for WinkComposer and Dashboard
+ *
+ * Provides efficient message serialization for MQTT transport with support
+ * for both MessagePack (binary, efficient) and JSON (text, debuggable).
+ * Works identically in Node.js (WinkComposer) and browsers (Dashboard).
+ *
+ * Design principles:
+ * - Zero dependencies on Node.js-specific APIs
+ * - Minimal allocations in hot path
+ * - Consistent Uint8Array return type
+ * - Frozen objects to prevent accidental mutation
+ *
+ * @module codec
+ */
+
+import { Packr, Unpackr } from 'msgpackr';
+
+// MessagePack encoder/decoder with optimizations for streaming data
+const packr = new Packr( {
+    structuredClone: false,    // Avoid unnecessary object cloning
+    variableMapSize: true,     // Handle varying message sizes efficiently
+    bundleStrings: true        // Optimize repeated field names (sensorId, timestamp, etc.)
+} );
+
+const unpackr = new Unpackr( {
+    bundleStrings: true        // Must match packr configuration
+} );
+
+// UTF-8 encoder/decoder - native browser APIs, also available in Node.js 11+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/**
+ * Convert various byte-like types to Uint8Array without unnecessary copying.
+ * Handles Buffer (Node.js), ArrayBuffer, DataView, and other typed arrays.
+ *
+ * @param {BufferSource} bytes - ArrayBuffer, typed array, or DataView
+ * @returns {Uint8Array} View over the same underlying memory
+ * @throws {TypeError} If input is not a valid byte source
+ */
+const toUint8 = function ( bytes ) {
+    // Fast path - already correct type (includes Node.js Buffer)
+    if ( bytes instanceof Uint8Array ) return bytes;
+
+    // ArrayBuffer - wrap in view
+    if ( bytes instanceof ArrayBuffer ) return new Uint8Array( bytes );
+
+    // Other typed arrays (Int16Array, DataView, etc.) - create view over same buffer
+    if ( ArrayBuffer.isView( bytes ) ) {
+        return new Uint8Array( bytes.buffer, bytes.byteOffset, bytes.byteLength );
+    }
+
+    throw new TypeError( 'Expected BufferSource' );
+};
+
+/**
+ * Create a codec for message serialization
+ *
+ * @param {string} format - Serialization format: 'msgpack' or 'json'
+ * @returns {{
+ *   pack: (obj: any) => Uint8Array,
+ *   unpack: (bytes: BufferSource | string) => any,
+ *   contentType: string,
+ *   payloadFormatIndicator: number
+ * }} Frozen codec instance with MQTT v5 properties
+ * @throws {TypeError} If format is not supported
+ */
+export const createCodec = function ( format = 'msgpack' ) {
+    if ( format === 'msgpack' ) {
+        return Object.freeze( {
+
+            /**
+             * Serialize object to MessagePack binary format
+             * @param {*} obj - Object to serialize
+             * @returns {Uint8Array} Packed bytes
+             */
+            pack: ( obj ) => {
+                const out = packr.encode( obj );
+                // Ensure Uint8Array (packr returns Buffer in Node.js, but may differ in browsers)
+                /* c8 ignore next - defensive for browser environments, Buffer is Uint8Array in Node.js */
+                return out instanceof Uint8Array ? out : new Uint8Array( out );
+            },
+
+            /**
+             * Deserialize MessagePack bytes to object
+             * @param {BufferSource} bytes - MessagePack data
+             * @returns {*} Deserialized object
+             */
+            unpack: ( bytes ) => unpackr.decode( toUint8( bytes ) ),
+
+            // MQTT v5 properties
+            contentType: 'application/msgpack',
+            payloadFormatIndicator: 0  // 0 = binary format
+        } );
+    }
+
+    if ( format === 'json' ) {
+        return Object.freeze( {
+
+            /**
+             * Serialize object to JSON UTF-8 bytes
+             * @param {*} obj - Object to serialize (must be JSON-serializable)
+             * @returns {Uint8Array} UTF-8 encoded JSON
+             */
+            pack: ( obj ) => textEncoder.encode( JSON.stringify( obj ) ),
+
+            /**
+             * Deserialize JSON from UTF-8 bytes or string
+             * @param {BufferSource | string} bytes - JSON data
+             * @returns {*} Parsed object
+             */
+            unpack: ( bytes ) => {
+                // Handle both string and binary input
+                const u8 = typeof bytes === 'string' ?
+                    textEncoder.encode( bytes ) :
+                    toUint8( bytes );
+                return JSON.parse( textDecoder.decode( u8 ) );
+            },
+
+            // MQTT v5 properties
+            contentType: 'application/json',
+            payloadFormatIndicator: 1  // 1 = UTF-8 text
+        } );
+    }
+
+    throw new TypeError( `Unknown format: ${format}` );
+};
+
+// Pre-created codecs for convenience
+export const msgpackCodec = createCodec( 'msgpack' );
+export const jsonCodec = createCodec( 'json' );
+
+// Default export for simple import
+export default createCodec;

package/src/core/emitter-manager/mqtt/constants.js

@@ -0,0 +1,102 @@
+// core/emitter-manager/mqtt/constants.js
+
+/**
+ * @fileoverview Production Constants - Pure Transport Layer
+ *
+ * Protocol invariants (QoS, WINK_NAMESPACE, protocol version) are imported
+ * from the shared mqtt-protocol module. Deployment-configurable values
+ * (keepalive, reconnect, queue limits, etc.) come from ENV_VARS.
+ *
+ * DESIGN DECISIONS (invariants, not configurable):
+ *
+ * 1. FIXED QoS 1
+ *    - Reliable without overhead of QoS 2
+ *    - At-least-once delivery sufficient for telemetry
+ *    - Duplicates handled by backend deduplication (UUID)
+ *
+ * 2. QUEUE_CRITICAL_THRESHOLD at 80%
+ *    - Time to investigate before critical
+ *
+ * 3. STORE_CONFIG compression + 8MB cache
+ *    - LevelDB defaults for the DORMANT store module (ADR-021; kept
+ *      for the WAL successor, not wired)
+ *
+ * @see src/core/mqtt-protocol.js - Shared protocol invariants
+ * @see src/core/env-vars.js - Deployment configuration
+ * @module mqtt-constants
+ */
+
+import { ENV_VARS } from '../../env-vars.js';
+import {
+    WINK_NAMESPACE,
+    MQTT_QOS as QOS,
+    MQTT_PROTOCOL_V
+} from '../../mqtt-protocol.js';
+
+// Re-export protocol invariants for local consumers
+export { WINK_NAMESPACE, QOS };
+
+// Queue default from ENV_VARS
+export const DEFAULT_MAX_QUEUE_SIZE = ENV_VARS.mqttMaxQueueSize;
+
+// Byte-axis cap for the DORMANT LevelDB store (ADR-021). The
+// MQTT_MAX_QUEUE_BYTES env var was retired with the disk store — the
+// in-memory emitter bounds memory by message count alone. The literal
+// stays so the dormant store module keeps a working default until the
+// composer-owned WAL successor re-wires deployment configuration.
+export const DEFAULT_MAX_QUEUE_BYTES = 52428800;   // 50 MB
+
+// Operational constant — not configurable (design decision)
+export const QUEUE_CRITICAL_THRESHOLD = 0.8;
+
+// Hard ceiling on maxQueueSize — not configurable (design
+// decision). MQTT packet ids are 16-bit, so at most 65,535 publishes
+// can be unacknowledged at once; a queue sized beyond that promises
+// capacity the protocol cannot deliver. The measured failure mode with
+// the default id allocator: the id space wraps and a new packet
+// OVERWRITES an unacked packet's store entry, destroying the only copy
+// of an undelivered QoS-1 message (about 1 per 700,000 under sustained
+// load in the soak gate). The emitter uses the client's
+// UniqueMessageIdProvider, which never reissues an in-use id — so the
+// unacked window must never hold more messages than the id space has
+// ids. 60,000 leaves margin for ids stuck on never-acknowledged packets.
+export const MQTT_INFLIGHT_ID_LIMIT = 60000;
+
+// Message expiry intervals (seconds)
+export const MESSAGE_EXPIRY = {
+    telemetry: 3600,                   // 1 hour - sensor data loses value quickly
+    status: 86400,                     // 24 hours - status needs longer persistence
+    default: ENV_VARS.mqttMsgExpiry    // Default expiry from ENV_VARS
+};
+
+// MQTT v5 configuration
+export const MQTT_CONFIG = {
+    protocolVersion: MQTT_PROTOCOL_V,
+    keepalive: ENV_VARS.mqttKeepalive,
+    reconnectPeriod: ENV_VARS.mqttReconnectMs,
+    connectTimeout: ENV_VARS.mqttConnectTimeoutMs,
+    // A deliberately clean session, spelled with the key mqtt.js
+    // actually reads (`clean`). The MQTT 5 spelling `cleanStart` is
+    // silently ignored by mqtt.js — the source carried that exact
+    // defect until 2026-07-09, caught by the ADR-022 dedup soak
+    // (see the cleanStart→clean mapping in source-manager/mqtt/client.js).
+    //
+    // Why clean: the emitter is publish-only. It holds no
+    // subscriptions a broker session could preserve, and its
+    // unacknowledged messages live in the mqtt.js client's in-memory
+    // store inside this process, tracked by composer's unacked
+    // counter (ADR-021).
+    // A broker session buys it nothing. Before this fix, the ignored
+    // key plus a random per-start clientId parked a 7-day orphan
+    // session at the broker on every restart (`sessionExpiryInterval`
+    // was riding along here as the same dead weight — the source is
+    // the only adapter that needs MQTT_SESSION_EXPIRY_S).
+    clean: true
+};
+
+// Storage configuration — operational constant for the DORMANT LevelDB
+// store (ADR-021; kept for the WAL successor, not wired)
+export const STORE_CONFIG = {
+    compression: true,
+    cacheSize: 8 * 1024 * 1024        // 8MB LevelDB cache
+};