@wardx/core 0.1.0

package/src/metrics/dimensions.js

@@ -0,0 +1,42 @@
+export function dimKey(dims) {
+  if (dims == null) return '';
+  const keys = Object.keys(dims);
+  const n = keys.length;
+  if (n === 0) return '';
+  if (n === 1) return keys[0] + '=' + String(dims[keys[0]]);
+  keys.sort();
+  let out = keys[0] + '=' + String(dims[keys[0]]);
+  for (let i = 1; i < n; i++) {
+    out += '\n' + keys[i] + '=' + String(dims[keys[i]]);
+  }
+  return out;
+}
+
+export function validateDimensions(dims, maxDimensionKeys, maxDimensionValueLength) {
+  if (dims == null) return { ok: true, dims: null };
+  if (typeof dims !== 'object' || Array.isArray(dims)) {
+    throw new Error('dimensions must be a plain object');
+  }
+  const keys = Object.keys(dims);
+  if (keys.length === 0) return { ok: true, dims: null };
+  if (keys.length > maxDimensionKeys) {
+    return { ok: false, reason: 'maxDimensionKeys' };
+  }
+  for (let i = 0; i < keys.length; i++) {
+    const value = dims[keys[i]];
+    const type = typeof value;
+    if (type !== 'string' && type !== 'number' && type !== 'boolean') {
+      throw new Error(`dimension ${keys[i]} must be string, number, or boolean`);
+    }
+    if (String(value).length > maxDimensionValueLength) {
+      return { ok: false, reason: 'maxDimensionValueLength' };
+    }
+  }
+  return { ok: true, dims };
+}
+
+export function assertMetricName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('metric name must be a non-empty string');
+  }
+}

package/src/protocol.js

@@ -0,0 +1,53 @@
+export const PROTOCOL_VERSION = 1;
+export const SDK_NAME = 'wardx-node';
+export const PLATFORM = 'node';
+
+export const INTERNAL = {
+  eventsBuffered: 'wardx.internal.events_buffered',
+  logsBuffered: 'wardx.internal.logs_buffered',
+  eventsDropped: 'wardx.internal.events_dropped',
+  logsDropped: 'wardx.internal.logs_dropped',
+  cardinalityDropped: 'wardx.internal.cardinality_dropped',
+  framesSent: 'wardx.internal.frames_sent',
+  framesFailed: 'wardx.internal.frames_failed',
+  bytesUncompressed: 'wardx.internal.bytes_uncompressed',
+  bytesCompressed: 'wardx.internal.bytes_compressed',
+  lastSyncMs: 'wardx.internal.last_sync_ms',
+  configVersion: 'wardx.internal.config_version',
+  processRssBytes: 'wardx.internal.process_rss_bytes'
+};
+
+export const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+
+export const LOG_RANK = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+
+export const UINT32 = 4294967296;
+
+export const REQUIRED_CREATE_KEYS = [
+  'endpoint',
+  'projectKey',
+  'project',
+  'role',
+  'appVersion',
+  'environment'
+];
+
+export const REQUIRED_SDK_DEFAULT_KEYS = [
+  'aggregateIntervalMs',
+  'syncIntervalMs',
+  'syncJitterMin',
+  'syncJitterMax',
+  'maxBufferedEvents',
+  'maxBufferedLogs',
+  'maxFrameBytes',
+  'maxSeriesPerMetric',
+  'maxDimensionKeys',
+  'maxDimensionValueLength',
+  'httpTimeoutMs',
+  'histogramBuckets'
+];

package/src/settings.js

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { REQUIRED_CREATE_KEYS, REQUIRED_SDK_DEFAULT_KEYS } from './protocol.js';
+
+const DEFAULTS_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'defaults.json');
+
+export function requireKeys(object, keys, label) {
+  const missing = [];
+  for (const key of keys) {
+    if (object[key] === undefined || object[key] === null) missing.push(key);
+  }
+  if (missing.length > 0) {
+    throw new Error(`${label} missing required keys: ${missing.join(', ')}`);
+  }
+}
+
+export function loadSdkDefaults() {
+  let raw;
+  try {
+    raw = readFileSync(DEFAULTS_PATH, 'utf8');
+  } catch {
+    throw new Error(`Wardx SDK defaults file is missing at ${DEFAULTS_PATH}`);
+  }
+  const parsed = JSON.parse(raw);
+  requireKeys(parsed, REQUIRED_SDK_DEFAULT_KEYS, 'SDK defaults');
+  if (!Array.isArray(parsed.histogramBuckets) || parsed.histogramBuckets.length === 0) {
+    throw new Error('SDK defaults histogramBuckets must be a non-empty array');
+  }
+  return parsed;
+}
+
+function assertPositiveNumber(settings, key) {
+  const value = settings[key];
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`${key} must be a finite number > 0`);
+  }
+}
+
+function assertNumberInRange(settings, key, min, max) {
+  const value = settings[key];
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+    throw new Error(`${key} must be a finite number in [${min}, ${max}]`);
+  }
+}
+
+export function resolveSettings(options) {
+  if (options === null || typeof options !== 'object') {
+    throw new Error('createWardx requires an options object');
+  }
+  requireKeys(options, REQUIRED_CREATE_KEYS, 'createWardx');
+  const defaults = loadSdkDefaults();
+  const settings = { ...defaults, ...options };
+  if (typeof settings.role !== 'string' || settings.role.length === 0) {
+    throw new Error('role must be a non-empty string');
+  }
+  if (settings.role === '*') {
+    throw new Error('role cannot be *');
+  }
+  if (settings.privacySalt === undefined || settings.privacySalt === null || settings.privacySalt === '') {
+    settings.privacySalt = settings.projectKey;
+  }
+  assertPositiveNumber(settings, 'aggregateIntervalMs');
+  assertPositiveNumber(settings, 'syncIntervalMs');
+  assertPositiveNumber(settings, 'maxBufferedEvents');
+  assertPositiveNumber(settings, 'maxBufferedLogs');
+  assertPositiveNumber(settings, 'maxFrameBytes');
+  assertPositiveNumber(settings, 'maxSeriesPerMetric');
+  assertPositiveNumber(settings, 'maxDimensionKeys');
+  assertPositiveNumber(settings, 'maxDimensionValueLength');
+  assertPositiveNumber(settings, 'httpTimeoutMs');
+  assertNumberInRange(settings, 'syncJitterMin', 0, 1);
+  assertNumberInRange(settings, 'syncJitterMax', 1, 2);
+  if (settings.syncJitterMin > settings.syncJitterMax) {
+    throw new Error('syncJitterMin must be <= syncJitterMax');
+  }
+  if (settings.tracer != null && (typeof settings.tracer !== 'object' || Array.isArray(settings.tracer))) {
+    throw new Error('tracer must be an object');
+  }
+  if (!Array.isArray(settings.histogramBuckets) || settings.histogramBuckets.length === 0) {
+    throw new Error('histogramBuckets must be a non-empty array');
+  }
+  let prev = -Infinity;
+  for (const bound of settings.histogramBuckets) {
+    if (typeof bound !== 'number' || !Number.isFinite(bound) || bound <= prev) {
+      throw new Error('histogramBuckets must be strictly increasing finite numbers');
+    }
+    prev = bound;
+  }
+  return settings;
+}
+
+export function nextSyncDelayMs(settings) {
+  const span = settings.syncJitterMax - settings.syncJitterMin;
+  const factor = settings.syncJitterMin + Math.random() * span;
+  return settings.syncIntervalMs * factor;
+}

package/src/trace/emit.js

@@ -0,0 +1,5 @@
+export function emit(tracer, hook, record) {
+  if (tracer == null) return;
+  const fn = tracer[hook];
+  if (typeof fn === 'function') fn.call(tracer, record);
+}

package/src/trace/wrap.js

@@ -0,0 +1,46 @@
+import { emit } from './emit.js';
+
+export function wrapCounter(tracer, series, noop, name, dims) {
+  const n = noop ? name : series.name;
+  const d = noop ? (dims ?? null) : series.dims;
+  return {
+    inc() {
+      series.inc();
+      emit(tracer, 'measure', { type: 'counter', name: n, dims: d, op: 'inc', value: 1, noop });
+    },
+    add(value) {
+      series.add(value);
+      emit(tracer, 'measure', { type: 'counter', name: n, dims: d, op: 'add', value, noop });
+    }
+  };
+}
+
+export function wrapGauge(tracer, series, noop, name, dims) {
+  const n = noop ? name : series.name;
+  const d = noop ? (dims ?? null) : series.dims;
+  return {
+    set(value) {
+      series.set(value);
+      emit(tracer, 'measure', { type: 'gauge', name: n, dims: d, op: 'set', value, noop });
+    }
+  };
+}
+
+export function wrapHistogram(tracer, series, noop, name, dims) {
+  const n = noop ? name : series.name;
+  const d = noop ? (dims ?? null) : series.dims;
+  return {
+    observe(value, attrs) {
+      series.observe(value, attrs);
+      emit(tracer, 'measure', {
+        type: 'histogram',
+        name: n,
+        dims: d,
+        op: 'observe',
+        value,
+        attrs: attrs ?? null,
+        noop
+      });
+    }
+  };
+}