otelturbine 0.1.0

package/index.ts

@@ -0,0 +1,27 @@
+// otelturbine — OTLP → Prometheus Remote-Write Pipeline Library
+
+// Core builder
+export { OtelTurbine, BuiltOtelTurbine } from './src/core/OtelTurbine.ts';
+
+// Pipeline (for advanced/testing use)
+export { Pipeline } from './src/core/Pipeline.ts';
+export { applyRequestLabelInjections } from './src/core/Pipeline.ts';
+export type { PipelineResult, LabelInjectionRule, ProcessOptions } from './src/core/Pipeline.ts';
+export { createCompatHandler, CompatRequestSession } from './src/core/Compat.ts';
+export type { CompatHandler, CompatRequestLike, CompatHeaders } from './src/core/Compat.ts';
+
+// Types
+export type { MetricSchema, LabelPattern, DefaultAction, CompiledSchema } from './src/types/schema.ts';
+export type { TimeSeries, Label, Sample, WriteRequest } from './src/types/prometheus.ts';
+export type { OtlpMetricsPayload, OtlpResourceMetrics, OtlpMetric } from './src/types/otlp.ts';
+export type { RemoteWriteConfig } from './src/core/RemoteWriteConfig.ts';
+
+// Transform utilities (for advanced use)
+export { otlpToTimeSeries } from './src/transform/otlpToTimeSeries.ts';
+export { compileSchemas, applySchemas } from './src/transform/SchemaEngine.ts';
+
+// Proto encoding (for advanced use)
+export { encodeWriteRequest } from './src/proto/writeRequest.ts';
+
+// Compression (for advanced use)
+export { snappyCompress, snappyUncompress } from './src/compress/snappy.ts';

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "otelturbine",
+  "version": "0.1.0",
+  "description": "OTLP/HTTP → Prometheus remote-write pipeline library for Bun",
+  "type": "module",
+  "module": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": {
+      "bun": "./index.ts",
+      "types": "./index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "index.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./index.ts --outdir ./dist --target node --format esm --external snappy",
+    "test": "bun test",
+    "bench": "bun run bench.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun test && bun run build"
+  },
+  "keywords": [
+    "otlp",
+    "opentelemetry",
+    "prometheus",
+    "remote-write",
+    "metrics",
+    "bun",
+    "elysia"
+  ],
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "elysia": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "elysia": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "elysia": "^1.4.26",
+    "mitata": "^1.0.34"
+  },
+  "dependencies": {
+    "snappy": "^7.3.3"
+  }
+}

package/src/adapters/bun.ts

@@ -0,0 +1,62 @@
+/**
+ * Bun-native adapter helpers for the Analyta pipeline.
+ */
+
+import type { Pipeline } from '../core/Pipeline.ts';
+
+/** Map pipeline status codes to appropriate HTTP responses. */
+function pipelineResultToResponse(status: number, message: string): Response {
+  switch (status) {
+    case 200:
+      return new Response(null, { status: 204 }); // Success → 204 No Content to caller
+    case 204:
+      return new Response(null, { status: 204 }); // Empty after filtering → 204
+    case 400:
+      return new Response(message, { status: 400 });
+    case 415:
+      return new Response(message, { status: 415 });
+    case 502:
+      return new Response(message, { status: 502 });
+    default:
+      return new Response(message, { status });
+  }
+}
+
+/**
+ * Returns a handler for use as a Bun.serve route POST handler.
+ * Assumes the route only handles POST (method checking done by Bun.serve routing).
+ */
+export function bunRouteHandler(pipeline: Pipeline): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    const contentType = req.headers.get('content-type') ?? 'application/json';
+    const body = await req.text();
+    const result = await pipeline.process(body, contentType);
+    return pipelineResultToResponse(result.status, result.message);
+  };
+}
+
+/**
+ * Returns a Bun fetch handler that handles POST to the specified path.
+ * Returns 405 for wrong method, 404 for unmatched paths.
+ */
+export function bunHandler(
+  pipeline: Pipeline,
+  path: string
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    if (url.pathname !== path) {
+      return new Response('Not Found', { status: 404 });
+    }
+    if (req.method !== 'POST') {
+      return new Response('Method Not Allowed', {
+        status: 405,
+        headers: { Allow: 'POST' },
+      });
+    }
+    const contentType = req.headers.get('content-type') ?? 'application/json';
+    const body = await req.text();
+    const result = await pipeline.process(body, contentType);
+    return pipelineResultToResponse(result.status, result.message);
+  };
+}

package/src/adapters/elysia.ts

@@ -0,0 +1,35 @@
+/**
+ * ElysiaJS adapter for Analyta.
+ * Uses import type only — Elysia is an optional peer dependency.
+ * At runtime, dynamically imports Elysia only if the user has it installed.
+ */
+
+import type { Elysia as ElysiaType } from 'elysia';
+import type { Pipeline } from '../core/Pipeline.ts';
+
+/**
+ * Creates an ElysiaJS plugin that registers a POST handler for OTLP metrics.
+ *
+ * @param pipeline - The compiled Analyta pipeline
+ * @param path - The route path (default: '/v1/metrics')
+ * @returns An Elysia plugin instance (typed as unknown to avoid hard dep)
+ */
+export function createElysiaPlugin(pipeline: Pipeline, path: string): unknown {
+  // Dynamic import to avoid hard runtime dependency
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const { Elysia } = require('elysia') as { Elysia: typeof ElysiaType };
+
+  return new Elysia({ name: 'otelturbine' }).post(path, async ({ request }) => {
+    const contentType = request.headers.get('content-type') ?? 'application/json';
+    const body = await request.text();
+    const result = await pipeline.process(body, contentType);
+
+    switch (result.status) {
+      case 200:
+      case 204:
+        return new Response(null, { status: 204 });
+      default:
+        return new Response(result.message, { status: result.status });
+    }
+  });
+}

package/src/compress/snappy.ts

@@ -0,0 +1,9 @@
+import { compressSync, uncompressSync } from 'snappy';
+
+export function snappyCompress(data: Uint8Array): Uint8Array {
+  return compressSync(data);
+}
+
+export function snappyUncompress(data: Uint8Array): Uint8Array {
+  return uncompressSync(data, { asBuffer: true }) as Buffer;
+}

package/src/core/Compat.ts

@@ -0,0 +1,92 @@
+import type { Pipeline, PipelineResult, LabelInjectionRule } from './Pipeline.ts';
+
+export type CompatHeaders =
+  | Headers
+  | { get?: (name: string) => string | null | undefined }
+  | Record<string, string | string[] | undefined>;
+
+export interface CompatRequestLike {
+  method?: string;
+  headers?: CompatHeaders;
+  contentType?: string;
+  body?: unknown;
+  text?: () => Promise<string> | string;
+}
+
+export class CompatRequestSession {
+  private readonly injectRules: LabelInjectionRule[] = [];
+
+  constructor(
+    private readonly pipeline: Pipeline,
+    private readonly req: Request | CompatRequestLike
+  ) {}
+
+  injectLabel(selector: LabelInjectionRule['selector'], labels: Record<string, string>): this {
+    this.injectRules.push({ selector, labels: { ...labels } });
+    return this;
+  }
+
+  async push(): Promise<PipelineResult> {
+    const normalized = await normalizeRequest(this.req);
+    if (normalized.method && normalized.method !== 'POST') {
+      return { status: 405, message: 'Method Not Allowed' };
+    }
+    return this.pipeline.process(normalized.body, normalized.contentType, {
+      injectLabels: this.injectRules,
+    });
+  }
+}
+
+export type CompatHandler = (req: Request | CompatRequestLike) => CompatRequestSession;
+
+export function createCompatHandler(pipeline: Pipeline): CompatHandler {
+  return (req: Request | CompatRequestLike) => new CompatRequestSession(pipeline, req);
+}
+
+interface NormalizedRequest {
+  method: string | undefined;
+  contentType: string;
+  body: string | Uint8Array;
+}
+
+async function normalizeRequest(req: Request | CompatRequestLike): Promise<NormalizedRequest> {
+  if (req instanceof Request) {
+    return {
+      method: req.method,
+      contentType: req.headers.get('content-type') ?? 'application/json',
+      body: await req.text(),
+    };
+  }
+
+  const method = typeof req.method === 'string' ? req.method.toUpperCase() : undefined;
+  const contentType = req.contentType ?? getHeader(req.headers, 'content-type') ?? 'application/json';
+
+  if (typeof req.text === 'function') {
+    const text = await req.text();
+    return { method, contentType, body: text };
+  }
+
+  const body = req.body;
+  if (typeof body === 'string') return { method, contentType, body };
+  if (body instanceof Uint8Array) return { method, contentType, body };
+  if (body instanceof ArrayBuffer) return { method, contentType, body: new Uint8Array(body) };
+  if (body === undefined || body === null) return { method, contentType, body: '' };
+  if (typeof body === 'object') return { method, contentType, body: JSON.stringify(body) };
+  return { method, contentType, body: String(body) };
+}
+
+function getHeader(headers: CompatHeaders | undefined, name: string): string | undefined {
+  if (!headers) return undefined;
+  if (typeof (headers as Headers).get === 'function') {
+    const value = (headers as Headers).get(name);
+    return value ?? undefined;
+  }
+  const record = headers as Record<string, string | string[] | undefined>;
+  const direct = record[name];
+  if (typeof direct === 'string') return direct;
+  if (Array.isArray(direct) && direct.length > 0) return direct[0];
+  const lowered = record[name.toLowerCase()];
+  if (typeof lowered === 'string') return lowered;
+  if (Array.isArray(lowered) && lowered.length > 0) return lowered[0];
+  return undefined;
+}

package/src/core/OtelTurbine.ts

@@ -0,0 +1,121 @@
+// OtelTurbine fluent builder and built instance.
+//
+// Usage:
+//   const turbine = new OtelTurbine()
+//     .remoteWrite('http://prometheus:9090/api/v1/write')
+//     .defaultAction('drop')
+//     .schema([{ name: /^http_/, labels: { method: /^GET$/ } }])
+//     .build();
+//
+//   Bun.serve({ routes: { '/v1/metrics': { POST: turbine.bunRouteHandler() } } });
+//   Bun.serve({ fetch: turbine.bunHandler() });
+//   new Elysia().use(turbine.elysiaPlugin({ path: '/v1/metrics' }));
+
+import type { MetricSchema, DefaultAction } from '../types/schema.ts';
+import type { RemoteWriteConfig } from './RemoteWriteConfig.ts';
+import { compileSchemas } from '../transform/SchemaEngine.ts';
+import { Pipeline } from './Pipeline.ts';
+import { bunRouteHandler, bunHandler } from '../adapters/bun.ts';
+import { createElysiaPlugin } from '../adapters/elysia.ts';
+import { createCompatHandler } from './Compat.ts';
+import type { CompatHandler } from './Compat.ts';
+
+/** OtelTurbine fluent builder. */
+export class OtelTurbine {
+  private _remoteWrite?: RemoteWriteConfig;
+  private _defaultAction: DefaultAction = 'pass';
+  private _schemas: MetricSchema[] = [];
+
+  /**
+   * Configure the Prometheus remote-write endpoint.
+   * @param url Remote-write URL
+   * @param options Optional timeout and extra headers
+   */
+  remoteWrite(url: string, options?: { timeout?: number; headers?: Record<string, string> }): this {
+    this._remoteWrite = {
+      url,
+      timeout: options?.timeout ?? 10_000,
+      headers: options?.headers,
+    };
+    return this;
+  }
+
+  /**
+   * Set the default action for metrics that match no schema.
+   * - 'pass' (default): forward unchanged
+   * - 'drop': discard
+   */
+  defaultAction(action: DefaultAction): this {
+    this._defaultAction = action;
+    return this;
+  }
+
+  /**
+   * Register metric schemas for filtering and transformation.
+   * Schemas are matched in order; first match wins.
+   */
+  schema(schemas: MetricSchema[]): this {
+    this._schemas = [...this._schemas, ...schemas];
+    return this;
+  }
+
+  /** Build the configured pipeline. Throws if remoteWrite was not configured. */
+  build(): BuiltOtelTurbine {
+    if (!this._remoteWrite) {
+      throw new Error('OtelTurbine: remoteWrite() must be called before build()');
+    }
+    const compiled = compileSchemas(this._schemas);
+    const pipeline = new Pipeline(this._remoteWrite, compiled, this._defaultAction);
+    return new BuiltOtelTurbine(pipeline);
+  }
+}
+
+/** A configured, built OtelTurbine pipeline ready to handle requests. */
+export class BuiltOtelTurbine {
+  constructor(private readonly pipeline: Pipeline) {}
+
+  /**
+   * Returns a Bun route handler for use as a route value in Bun.serve routes.
+   * Handles only POST requests; returns 405 for other methods.
+   *
+   * Usage: Bun.serve({ routes: { '/v1/metrics': { POST: turbine.bunRouteHandler() } } })
+   */
+  bunRouteHandler(): (req: Request) => Promise<Response> {
+    return bunRouteHandler(this.pipeline);
+  }
+
+  /**
+   * Returns a Bun fetch handler for use as the `fetch` option in Bun.serve.
+   * Handles POST /v1/metrics; returns 405 for wrong method, 404 for other paths.
+   *
+   * Usage: Bun.serve({ fetch: turbine.bunHandler() })
+   */
+  bunHandler(path = '/v1/metrics'): (req: Request) => Promise<Response> {
+    return bunHandler(this.pipeline, path);
+  }
+
+  /**
+   * Returns an ElysiaJS plugin that registers the OTLP metrics endpoint.
+   * Elysia is an optional peer dependency; typed as unknown to avoid hard dep.
+   *
+   * Usage: new Elysia().use(turbine.elysiaPlugin({ path: '/v1/metrics' }))
+   */
+  elysiaPlugin(options?: { path?: string }): unknown {
+    return createElysiaPlugin(this.pipeline, options?.path ?? '/v1/metrics');
+  }
+
+  /**
+   * Returns a framework-agnostic request adapter.
+   * Usage:
+   *   const otelTurbine = turbine.compat();
+   *   await otelTurbine(req).injectLabel('*', { instance_name: 'a' }).push();
+   */
+  compat(): CompatHandler {
+    return createCompatHandler(this.pipeline);
+  }
+
+  /** Direct access to the pipeline for advanced use cases or testing. */
+  get rawPipeline(): Pipeline {
+    return this.pipeline;
+  }
+}

package/src/core/Pipeline.ts

@@ -0,0 +1,169 @@
+/**
+ * Stateless pipeline: process(body, contentType) → PipelineResult
+ *
+ * Steps:
+ *  1. Validate content type (must be application/json or application/x-protobuf)
+ *  2. Parse OTLP JSON body
+ *  3. Convert to TimeSeries[]
+ *  4. Apply schemas
+ *  5. If empty result, return 204
+ *  6. Encode to protobuf
+ *  7. Compress with snappy
+ *  8. POST to remote-write endpoint
+ */
+
+import type { RemoteWriteConfig } from './RemoteWriteConfig.ts';
+import type { CompiledSchema, DefaultAction } from '../types/schema.ts';
+import type { OtlpMetricsPayload } from '../types/otlp.ts';
+import { otlpToTimeSeries } from '../transform/otlpToTimeSeries.ts';
+import { applySchemas } from '../transform/SchemaEngine.ts';
+import { encodeWriteRequest } from '../proto/writeRequest.ts';
+import { snappyCompress } from '../compress/snappy.ts';
+import type { TimeSeries } from '../types/prometheus.ts';
+
+export interface PipelineResult {
+  status: number;
+  message: string;
+}
+
+export interface LabelInjectionRule {
+  selector: '*' | string | RegExp;
+  labels: Record<string, string>;
+}
+
+export interface ProcessOptions {
+  injectLabels?: LabelInjectionRule[];
+}
+
+export function applyRequestLabelInjections(
+  series: TimeSeries[],
+  injectRules: LabelInjectionRule[]
+): TimeSeries[] {
+  if (injectRules.length === 0) return series;
+
+  return series.map((ts) => {
+    const labelsMap = new Map(ts.labels.map((l) => [l.name, l.value]));
+    const metricName = labelsMap.get('__name__') ?? '';
+
+    for (const rule of injectRules) {
+      if (!selectorMatches(rule.selector, metricName)) continue;
+      for (const [key, value] of Object.entries(rule.labels)) {
+        labelsMap.set(key, value);
+      }
+    }
+
+    const labels = [...labelsMap.entries()]
+      .map(([name, value]) => ({ name, value }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    return {
+      labels,
+      samples: ts.samples,
+    };
+  });
+}
+
+function selectorMatches(selector: LabelInjectionRule['selector'], metricName: string): boolean {
+  if (selector === '*') return true;
+  if (typeof selector === 'string') return selector === metricName;
+  return selector.test(metricName);
+}
+
+export class Pipeline {
+  constructor(
+    private readonly remoteWrite: RemoteWriteConfig,
+    private readonly schemas: CompiledSchema[],
+    private readonly defaultAction: DefaultAction
+  ) {}
+
+  async process(
+    body: string | Uint8Array,
+    contentType: string,
+    options?: ProcessOptions
+  ): Promise<PipelineResult> {
+    // Only accept JSON content types for OTLP
+    const ct = contentType.split(';')[0]!.trim().toLowerCase();
+    if (ct === 'application/x-protobuf') {
+      return { status: 415, message: 'Protobuf OTLP not supported; use application/json' };
+    }
+    if (ct !== 'application/json') {
+      return { status: 415, message: `Unsupported content type: ${contentType}` };
+    }
+
+    // Parse JSON
+    let payload: OtlpMetricsPayload;
+    try {
+      const text = typeof body === 'string' ? body : new TextDecoder().decode(body);
+      payload = JSON.parse(text) as OtlpMetricsPayload;
+    } catch {
+      return { status: 400, message: 'Invalid JSON body' };
+    }
+
+    // Validate basic shape
+    if (!payload || !Array.isArray(payload.resourceMetrics)) {
+      return { status: 400, message: 'Invalid OTLP payload: missing resourceMetrics' };
+    }
+
+    // Convert to TimeSeries
+    let series = otlpToTimeSeries(payload);
+
+    // Apply schemas
+    if (this.schemas.length > 0) {
+      series = applySchemas(series, this.schemas, this.defaultAction);
+    } else if (this.defaultAction === 'drop') {
+      series = [];
+    }
+
+    // Per-request injection happens after schema filtering so user logic always applies.
+    if (options?.injectLabels && options.injectLabels.length > 0) {
+      series = applyRequestLabelInjections(series, options.injectLabels);
+    }
+
+    // Empty result → 204 No Content
+    if (series.length === 0) {
+      return { status: 204, message: 'No metrics after filtering' };
+    }
+
+    // Encode to protobuf
+    const protoBytes = encodeWriteRequest({ timeseries: series });
+
+    // Compress with snappy
+    const compressed = snappyCompress(protoBytes);
+
+    // POST to remote-write
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.remoteWrite.timeout);
+
+      let response: Response;
+      try {
+        response = await fetch(this.remoteWrite.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/x-protobuf',
+            'Content-Encoding': 'snappy',
+            'X-Prometheus-Remote-Write-Version': '0.1.0',
+            ...this.remoteWrite.headers,
+          },
+          body: compressed,
+          signal: controller.signal,
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+
+      if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        return {
+          status: 502,
+          message: `Remote write failed: HTTP ${response.status} ${body}`.slice(0, 500),
+        };
+      }
+
+      return { status: 200, message: 'OK' };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { status: 502, message: `Remote write error: ${msg}` };
+    }
+  }
+}

package/src/core/RemoteWriteConfig.ts

@@ -0,0 +1,8 @@
+/**
+ * Configuration for the Prometheus remote-write endpoint.
+ */
+export interface RemoteWriteConfig {
+  url: string;
+  timeout: number; // milliseconds
+  headers?: Record<string, string>;
+}