feat: add Prometheus Remote Write v2.0 support, tests, integration, and migration guide

CHANGELOG.md

@@ -0,0 +1,179 @@
+# CHANGELOG - v2 Unification
+
+## Summary
+
+Successfully refactored the prometheus-remote-write library to provide a unified API that seamlessly handles both Remote Write v1 and v2 protocols without the need for separate v2-suffixed methods.
+
+## Breaking Changes
+
+**None!** This refactoring maintains full backward compatibility.
+
+## New Features
+
+### Unified API
+- ✅ Same `pushTimeseries()` and `pushMetrics()` functions work for both v1 and v2
+- ✅ Automatic protocol version detection based on data features
+- ✅ Optional `version` parameter for explicit protocol control
+
+### Helper Functions
+- ✅ `createHistogram(options)` - Build native histogram structures
+- ✅ `createExemplar(value, labels, timestamp)` - Create exemplars easily
+- ✅ `buildSymbolTable(timeseries)` - Advanced symbol table management
+- ✅ `labelsToRefs(labels, symbolMap)` - Convert labels to v2 refs
+
+### Enhanced Type Definitions
+- ✅ Unified TypeScript definitions in single `types.d.ts`
+- ✅ Full support for v2 features (histograms, exemplars, metadata)
+- ✅ Proper JSDoc comments for IDE autocomplete
+
+## Removed
+
+### Deprecated Files (v2 suffixes)
+- ❌ `index_v2.js` - Merged into `index.js`
+- ❌ `types_v2.d.ts` - Merged into `types.d.ts`
+- ❌ `index_v2.test.js` - Merged into `index.test.js`
+- ❌ `examples_v2.js` - Replaced with `examples.js`
+
+### Deprecated Exports
+- ❌ `pushMetricsV2()` - Use `pushMetrics()` with `version: 2` option
+- ❌ `pushTimeseriesV2()` - Use `pushTimeseries()` with `version: 2` option
+- ❌ `serializeV2()` - Internal implementation detail
+- ❌ `deserializeV2()` - Internal implementation detail
+- ❌ `loadProtoV2()` - Internal implementation detail
+
+## Migration Guide
+
+### For Existing Users
+
+**No changes required!** Your existing code continues to work:
+```javascript
+// This still works exactly as before
+await pushMetrics({ my_metric: 42 }, config);
+await pushTimeseries(timeseries, config);
+```
+
+### To Use v2 Features
+
+**Option 1: Auto-detection** (Recommended)
+```javascript
+// Just add v2 features - protocol auto-detected
+await pushTimeseries({
+  labels: { __name__: "my_metric" },
+  samples: [{ value: 42 }],
+  metadata: { type: 1, help: "My metric" }
+}, config);
+```
+
+**Option 2: Explicit version**
+```javascript
+// Force v2 protocol
+await pushMetrics({ my_metric: 42 }, { ...config, version: 2 });
+```
+
+### Helper Functions
+
+```javascript
+import { createHistogram, createExemplar } from "prometheus-remote-write";
+
+// Create histogram
+const hist = createHistogram({
+  count_int: 100,
+  sum: 45.5,
+  schema: 0,
+  positive_spans: [{ offset: 0, length: 5 }],
+  positive_deltas: [10, 15, 30, 20, 10],
+});
+
+// Create exemplar
+const exemplar = createExemplar(42.5, { trace_id: "abc123" });
+```
+
+## Files Changed
+
+### Core Implementation
+- `index.js` - ✅ Integrated v2 protocol with auto-detection
+- `types.d.ts` - ✅ Unified type definitions
+- `index.test.js` - ✅ Comprehensive test coverage for both protocols
+
+### Documentation
+- `README.md` - ✅ Updated with unified API examples
+- `MIGRATION_V2.md` - ✅ Updated migration guide
+- `IMPLEMENTATION.md` - ✅ Updated architecture docs
+- `REFACTORING_SUMMARY.md` - ✅ New refactoring documentation
+- `CHANGELOG.md` - ✅ This file
+
+### Examples & Tests
+- `examples.js` - ✅ New comprehensive examples
+- `test-integration.js` - ✅ Updated to use unified API
+- `package.json` - ✅ Updated scripts (removed `test:v2`)
+
+### Removed Files
+- `index_v2.js` - ❌ Removed (merged into index.js)
+- `types_v2.d.ts` - ❌ Removed (merged into types.d.ts)
+- `index_v2.test.js` - ❌ Removed (merged into index.test.js)
+- `examples_v2.js` - ❌ Removed (replaced with examples.js)
+
+## Protocol Version Selection
+
+The library automatically chooses the appropriate protocol:
+
+1. **Explicit**: `version: 1` or `version: 2` in options
+2. **Auto-detect v2** when data contains:
+   - `histograms` field
+   - `exemplars` field
+   - `metadata` field
+   - Samples with `start_timestamp`
+3. **Default**: v1 for simple samples
+
+## Benefits
+
+### Developer Experience
+- ✨ Cleaner API without confusing v2 suffixes
+- ✨ Single set of functions to learn
+- ✨ Automatic protocol selection
+- ✨ Helper functions for complex types
+
+### Maintainability
+- 🔧 Single implementation to maintain
+- 🔧 Single test suite
+- 🔧 Single documentation set
+- 🔧 Less code duplication
+
+### Compatibility
+- 🔄 Full backward compatibility
+- 🔄 Gradual migration path
+- 🔄 Explicit control when needed
+
+## Testing
+
+All tests updated and passing:
+```bash
+npm test                    # Comprehensive tests (v1 and v2)
+npm run test:integration    # Integration tests
+```
+
+## Examples
+
+See `examples.js` for comprehensive usage examples covering:
+- Simple metrics (v1 default)
+- Explicit protocol versions
+- Auto-detection with v2 features
+- Native histograms
+- Exemplars for trace correlation
+- Metadata for better observability
+- Multiple timeseries with symbol deduplication
+
+## Next Steps
+
+1. ✅ **Completed**: Unified API implementation
+2. ✅ **Completed**: Type definitions
+3. ✅ **Completed**: Tests and documentation
+4. 📋 **Recommended**: Publish updated package to npm
+5. 📋 **Recommended**: Add CI/CD pipeline
+6. 📋 **Recommended**: Performance benchmarks (v1 vs v2)
+
+## Questions?
+
+For detailed migration instructions, see [MIGRATION_V2.md](MIGRATION_V2.md)
+For implementation details, see [IMPLEMENTATION.md](IMPLEMENTATION.md)
+For refactoring notes, see [REFACTORING_SUMMARY.md](REFACTORING_SUMMARY.md)

IMPLEMENTATION.md

@@ -0,0 +1,187 @@
+# Prometheus Remote Write 2.0 Implementation Summary
+
+## Overview
+Successfully integrated full support for Prometheus Remote Write 2.0 specification into the `prometheus-remote-write` npm package with a unified API that seamlessly handles both v1 and v2 protocols.
+
+## What Was Implemented
+
+### 1. Protocol Buffer Schema (v2.0)
+- **File**: `prom_v2.proto` - Official Prometheus Remote Write 2.0 protobuf definition
+- **File**: `prom_v2.js` - Generated JavaScript code from proto using protobufjs
+- Supports all v2.0 features: symbols, native histograms, metadata, exemplars
+
+### 2. Unified Core Implementation (`index.js`)
+- **Automatic Protocol Detection**: Detects v2 features and switches protocols automatically
+- **Symbol Table Management**: Deduplicates label names/values across timeseries (v2)
+- **Serialization**: Handles both v1 and v2 protobuf formats
+- **Deserialization**: Parses v1 and v2 protobuf back to JavaScript
+- **Push Functions**: `pushTimeseries()` and `pushMetrics()` work with both protocols
+- **Helper Functions**: `createHistogram()` and `createExemplar()` for v2 features
+- **Proper Headers**: Automatically sets appropriate headers based on protocol version
+
+### 3. Unified TypeScript Definitions (`types.d.ts`)
+Complete type definitions covering both v1 and v2:
+- `Timeseries` - supports samples, histograms, exemplars, metadata
+- `Sample` - including optional `start_timestamp` for v2
+- `Histogram` - native histogram with exponential/custom buckets
+- `Metadata` - metric type, help text, units
+- `Exemplar` - trace correlation
+- `Options` - configuration with optional `version` field
+- `Result` - response with v2 written counts (when applicable)
+- Helper function types
+
+### 4. Integration & Testing
+
+#### Unit Tests
+- `index.test.js` - Comprehensive test suite for both v1 and v2
+- Tests symbol table building, serialization, auto-detection, helper functions
+- Covers both protocol versions
+
+#### Integration Tests  
+- `test-integration.js` - Full integration test suite
+- Tests both v1.x and v2.0 against real Prometheus
+- Validates data is written and queryable
+- **All tests passing** ✅
+
+#### Docker Setup
+- `docker-compose.yml` - Local Prometheus with remote write enabled
+- `prometheus.yml` - Prometheus configuration
+- Enables native histograms and exemplar storage
+
+### 5. Documentation
+
+#### README Updates
+- Unified API documentation showing single set of methods
+- Examples of v2 features with auto-detection
+- Migration guide from v1.x to v2.0 (seamless transition)
+- Benefits and key differences
+- Testing instructions
+- API reference for unified functions
+
+### 6. Build & Scripts
+Updated `package.json` with:
+- `npm test` - Run comprehensive test suite (v1 and v2)
+- `npm run test:integration` - Run integration tests
+- `npm run docker:up` - Start Prometheus
+- `npm run docker:down` - Stop Prometheus
+- `npm run docker:logs` - View Prometheus logs
+- `npm run build` - Build both v1 and v2 protobufs
+
+## Key Features
+
+### Symbol Table Deduplication
+Reduces payload size by storing unique strings once and referencing by index:
+```javascript
+symbols: ['', '__name__', 'http_requests_total', 'instance', 'server-01']
+labelsRefs: [1, 2, 3, 4] // __name__=http_requests_total, instance=server-01
+```
+
+### Native Histograms
+Supports exponential and custom bucket histograms:
+```javascript
+histograms: [{
+  count_int: 100,
+  sum: 45678.5,
+  schema: 0, // Exponential buckets
+  positive_spans: [{ offset: 0, length: 5 }],
+  positive_deltas: [10, 15, 30, 20, 10]
+}]
+```
+
+### Metadata
+Rich metric information:
+```javascript
+metadata: {
+  type: 1, // COUNTER
+  help: 'Total HTTP requests',
+  unit: 'requests'
+}
+```
+
+### Exemplars
+Trace correlation:
+```javascript
+exemplars: [{
+  labels: { trace_id: 'abc123' },
+  value: 0.234,
+  timestamp: Date.now()
+}]
+```
+
+### Start Timestamps
+Better rate calculations for counters:
+```javascript
+samples: [{
+  value: 150,
+  timestamp: Date.now(),
+  start_timestamp: Date.now() - 3600000 // Counter started 1 hour ago
+}]
+```
+
+## Validation
+
+### Integration Test Results
+```
+✅ Remote Write v1.x: PASSED
+✅ Remote Write v2.0: PASSED
+
+Verified:
+- Symbol table deduplication
+- Metadata preservation
+- Exemplar support
+- Native histogram ingestion
+- Response headers (samples/histograms/exemplars written)
+- Data queryable in Prometheus
+```
+
+### Prometheus Compatibility
+Tested against: **Prometheus latest** (with flags):
+- `--web.enable-remote-write-receiver`
+- `--enable-feature=native-histograms`
+- `--enable-feature=exemplar-storage`
+
+## Backward Compatibility
+- **Unified API**: Same functions (`pushTimeseries`, `pushMetrics`) work for both v1 and v2
+- **Auto-detection**: Protocol version automatically selected based on data features
+- **Explicit control**: Optional `version` parameter for manual selection
+- **No breaking changes**: Existing code continues to work unchanged
+
+## Files Structure
+
+### Core Files
+- `index.js` - Unified implementation with both v1 and v2 protocols
+- `types.d.ts` - Unified TypeScript definitions
+- `index.test.js` - Comprehensive test suite
+
+### Protocol Definitions
+- `prom.proto` - v1 protocol definition
+- `prom.js` - Generated v1 protobuf code
+- `prom_v2.proto` - v2 protocol definition
+- `prom_v2.js` - Generated v2 protobuf code
+
+### Testing & Docker
+- `test-integration.js` - Integration tests
+- `docker-compose.yml` - Prometheus setup
+- `prometheus.yml` - Prometheus config
+- `.dockerignore` - Docker ignore file
+
+### Documentation
+- `README.md` - Main documentation with unified API
+- `MIGRATION_V2.md` - v2 migration guide
+- `IMPLEMENTATION.md` - This file
+
+## Next Steps / Future Enhancements
+1. ✅ Support for native histograms - **DONE**
+2. ✅ Symbol table deduplication - **DONE**
+3. ✅ Metadata and exemplars - **DONE**
+4. ✅ Integration tests - **DONE**
+5. ✅ Unified API without v2 suffixes - **DONE**
+6. Publish to npm with updated version
+7. Add CI/CD workflow for automated testing
+8. Performance benchmarks (v1 vs v2 payload sizes)
+9. Support for streaming/chunked writes
+
+## References
+- [Prometheus Remote Write 2.0 Spec](https://prometheus.io/docs/specs/prw/remote_write_spec_2_0/)
+- [Native Histograms](https://prometheus.io/docs/specs/native_histograms/)
+- [Protocol Buffer Definition](https://buf.build/prometheus/prometheus/docs/main:io.prometheus.write.v2)