@fluojs/metrics 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,185 @@
+# @fluojs/metrics
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 애플리케이션을 위한 Prometheus 메트릭 노출 모듈입니다. `MetricsModule`을 마운트하여 Node.js 기본 메트릭과 선택적인 저지수(low-cardinality) HTTP 요청 모니터링 기능이 포함된 `/metrics` 엔드포인트를 제공합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [공통 패턴](#공통-패턴)
+- [공개 API](#공개-api)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+pnpm add @fluojs/metrics
+```
+
+## 사용 시점
+
+- Prometheus나 VictoriaMetrics 수집기에 애플리케이션 및 시스템 메트릭을 내보내야 할 때.
+- 수동 계측 없이 자동화된 HTTP 요청 지연 시간 및 횟수 메트릭을 원할 때.
+- 메트릭 데이터를 fluo의 런타임 헬스체크 및 준비 상태와 동기화하고 싶을 때.
+
+## 빠른 시작
+
+루트 모듈에 `MetricsModule.forRoot()`를 추가하여 기본 `/metrics` 엔드포인트를 활성화합니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { MetricsModule } from '@fluojs/metrics';
+
+@Module({
+  imports: [
+    MetricsModule.forRoot(),
+  ],
+})
+class AppModule {}
+
+// GET /metrics → Prometheus 텍스트 형식
+```
+
+`MetricsModule.forRoot()`는 기본적으로 `GET /metrics`를 노출합니다. 운영 환경에서는 이 경계를 명시적으로 다루세요. 플랫폼 프록시/네트워크 제어를 붙이기 전까지 `path: false`로 비활성화하거나, 전용 endpoint middleware를 연결하는 방식을 권장합니다.
+
+## 공통 패턴
+
+### HTTP 라벨 정규화
+
+`MetricsModule`은 HTTP 메트릭을 수집하는 미들웨어를 포함합니다. 기본적으로 경로 라벨을 템플릿 형태(예: `/users/123` → `/users/:id`)로 정규화하여, 라벨 카디널리티(cardinality) 폭발을 방지합니다.
+
+```typescript
+MetricsModule.forRoot({
+  http: {
+    pathLabelMode: 'template', // 기본 동작
+    unknownPathLabel: 'UNKNOWN',
+  },
+})
+```
+
+`pathLabelMode: 'raw'`는 이제 안전하지 않은 명시적 opt-in으로 취급됩니다. 경로 공간이 유한하다는 것을 보장할 수 있을 때만 `allowUnsafeRawPathLabelMode: true`와 함께 사용하세요.
+
+### 메트릭 엔드포인트 보호 또는 비활성화
+
+```typescript
+import { ForbiddenException, type MiddlewareContext, type Next } from '@fluojs/http';
+
+class MetricsTokenMiddleware {
+  async handle(context: MiddlewareContext, next: Next): Promise<void> {
+    if (context.request.headers['x-metrics-token'] !== 'secret-token') {
+      throw new ForbiddenException('Metrics endpoint requires x-metrics-token.');
+    }
+
+    await next();
+  }
+}
+
+MetricsModule.forRoot({
+  endpointMiddleware: [MetricsTokenMiddleware],
+});
+
+MetricsModule.forRoot({
+  path: false,
+});
+```
+
+특수한 경로 매핑이 필요한 경우 커스텀 normalizer를 제공할 수 있습니다.
+
+```typescript
+MetricsModule.forRoot({
+  http: {
+    pathLabelNormalizer: ({ path }) => (path.startsWith('/api/v1') ? '/api/v1/:resource' : path),
+  },
+})
+```
+
+### 공유 Registry (권장)
+
+커스텀 애플리케이션 메트릭을 프레임워크가 제공하는 메트릭과 하나의 `/metrics` 엔드포인트에서 통합하려면, 공유 `Registry` 인스턴스를 전달하세요.
+
+```typescript
+import { Registry, Counter } from 'prom-client';
+import { MetricsModule, MetricsService } from '@fluojs/metrics';
+
+const sharedRegistry = new Registry();
+
+// 커스텀 메트릭 등록
+const ordersTotal = new Counter({
+  name: 'orders_total',
+  help: '처리된 총 주문 수',
+  registers: [sharedRegistry],
+});
+
+@Module({
+  imports: [
+    MetricsModule.forRoot({ registry: sharedRegistry }),
+  ],
+})
+class AppModule {}
+```
+
+### 런타임 플랫폼 텔레메트리
+
+이 모듈은 플랫폼 셸 및 등록된 컴포넌트의 내부 상태를 반영하는 fluo 전용 Gauge를 자동으로 생성합니다.
+
+- `fluo_component_ready`: 준비 완료 시 1, 아닐 시 0.
+- `fluo_component_health`: 정상 상태 시 1, 아닐 시 0.
+
+이 데이터는 매 스크레이프 시점에 `PLATFORM_SHELL`을 쿼리하여 갱신됩니다. 초기화 시 환경 라벨을 제공할 수 있습니다.
+
+```typescript
+MetricsModule.forRoot({
+  platformTelemetry: {
+    env: 'production',
+    instance: 'web-01',
+  },
+})
+```
+
+### 런타임 플랫폼 텔레메트리 스크레이프 계약
+
+플랫폼 텔레메트리는 매 `/metrics` 스크레이프마다 `PLATFORM_SHELL`을 resolve하여 `fluo_component_ready`와 `fluo_component_health`를 갱신합니다.
+
+- `PLATFORM_SHELL` 등록 자체가 빠진 경우에는 스크레이프가 계속 성공하고 플랫폼 텔레메트리 시리즈만 생략됩니다.
+- 그 외의 `PLATFORM_SHELL` resolve 실패는 조용히 삼키지 않고 스크레이프 실패로 그대로 드러납니다.
+
+### 기본 프로세스/Node 메트릭 비활성화
+
+`defaultMetrics`의 기본값은 `true`입니다. 따라서 별도 설정이 없으면 Registry마다 Prometheus 기본 프로세스/Node.js collector를 한 번 등록합니다. 최소 Registry만 노출하고 싶다면 비활성화하세요.
+
+```typescript
+MetricsModule.forRoot({
+  defaultMetrics: false,
+})
+```
+
+## 공개 API
+
+- `MetricsModule.forRoot(options)`
+- `MetricsService`
+- `METER_PROVIDER` (Token)
+- 카운터, 게이지, 히스토그램 및 레지스트리 접근을 위한 Prometheus 기반 헬퍼
+
+### 운영 기본값
+
+- `path`의 기본값은 `'/metrics'`이며, `path: false`로 스크레이프 엔드포인트를 완전히 비활성화할 수 있습니다.
+- `defaultMetrics`의 기본값은 `true`이며, `defaultMetrics: false`로 해당 Registry의 Prometheus 기본 프로세스/Node.js collector를 끌 수 있습니다.
+- `endpointMiddleware`는 스크레이프 엔드포인트에만 route-scoped middleware를 바인딩합니다.
+- HTTP 메트릭은 기본적으로 템플릿 기반 경로 라벨 정규화를 사용합니다.
+- raw path 라벨은 `allowUnsafeRawPathLabelMode: true`를 명시한 bounded internal route에서만 사용해야 합니다.
+- 플랫폼 텔레메트리는 `PLATFORM_SHELL`이 실제로 누락된 경우에만 생략되며, 그 외 resolve 실패는 스크레이프를 실패시킵니다.
+
+## 관련 패키지
+
+- `@fluojs/http`: 컨트롤러 및 미들웨어 인프라를 제공합니다.
+- `@fluojs/runtime`: 플랫폼 셸 및 모듈 정의 로직을 제공합니다.
+- `@fluojs/terminus`: 헬스체크 통합을 위해 메트릭과 함께 자주 사용됩니다.
+
+## 예제 소스
+
+- `examples/ops-metrics-terminus/src/app.ts`: Metrics 및 Terminus 모듈 구성 예제.
+- `packages/metrics/src/metrics-module.test.ts`: 다양한 레지스트리 모드 및 HTTP 정규화 테스트.

package/README.md

@@ -0,0 +1,166 @@
+# @fluojs/metrics
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Prometheus metrics exposure for fluo applications, including framework-aware HTTP metrics and platform telemetry.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+pnpm add @fluojs/metrics
+```
+
+## When to Use
+
+- when your app should expose a `/metrics` endpoint for Prometheus-compatible scraping
+- when HTTP latency and request counts should be instrumented without hand-written middleware
+- when application telemetry should stay aligned with fluo readiness and health state
+
+## Quick Start
+
+```ts
+import { MetricsModule } from '@fluojs/metrics';
+import { Module } from '@fluojs/core';
+
+@Module({
+  imports: [MetricsModule.forRoot()],
+})
+class AppModule {}
+```
+
+`MetricsModule.forRoot()` still exposes `GET /metrics` by default. For production deployments, make that endpoint boundary explicit: either disable it with `path: false` until a platform-level proxy is in place, or attach dedicated endpoint middleware.
+
+## Common Patterns
+
+### Normalize HTTP path labels
+
+```ts
+MetricsModule.forRoot({
+  http: {
+    pathLabelMode: 'template',
+    unknownPathLabel: 'UNKNOWN',
+  },
+});
+```
+
+`pathLabelMode: 'raw'` is now treated as an unsafe opt-in. You must pass `allowUnsafeRawPathLabelMode: true` only when you can prove the path space is bounded.
+
+### Protect or disable the metrics endpoint
+
+```ts
+import { ForbiddenException, type MiddlewareContext, type Next } from '@fluojs/http';
+
+class MetricsTokenMiddleware {
+  async handle(context: MiddlewareContext, next: Next): Promise<void> {
+    if (context.request.headers['x-metrics-token'] !== 'secret-token') {
+      throw new ForbiddenException('Metrics endpoint requires x-metrics-token.');
+    }
+
+    await next();
+  }
+}
+
+MetricsModule.forRoot({
+  endpointMiddleware: [MetricsTokenMiddleware],
+});
+
+MetricsModule.forRoot({
+  path: false,
+});
+```
+
+### Share one registry for framework and app metrics
+
+```ts
+import { Counter, Registry } from 'prom-client';
+import { MetricsModule } from '@fluojs/metrics';
+
+const registry = new Registry();
+
+new Counter({
+  name: 'orders_total',
+  help: 'Total orders processed',
+  registers: [registry],
+});
+
+@Module({
+  imports: [MetricsModule.forRoot({ registry })],
+})
+class AppModule {}
+```
+
+### Duplicate metric names still fail fast
+
+Prometheus metric names must stay unique inside a registry. Shared-registry mode keeps that behavior intact instead of silently shadowing metrics.
+
+### Runtime platform telemetry
+
+The module emits fluo-specific gauges that mirror the platform shell and registered component state.
+
+- `fluo_component_ready`: `1` when a component is ready, otherwise `0`.
+- `fluo_component_health`: `1` when a component is healthy, otherwise `0`.
+
+The platform snapshot is refreshed during each scrape, and you can attach environment labels up front.
+
+```ts
+MetricsModule.forRoot({
+  platformTelemetry: {
+    env: 'production',
+    instance: 'web-01',
+  },
+});
+```
+
+### Runtime platform telemetry scrape contract
+
+Platform telemetry refreshes `fluo_component_ready` and `fluo_component_health` on each `/metrics` scrape by resolving `PLATFORM_SHELL`.
+
+- If `PLATFORM_SHELL` is not registered, the scrape still succeeds and omits the platform telemetry series.
+- If resolving `PLATFORM_SHELL` fails for any other reason, the scrape surfaces that failure instead of swallowing it.
+
+### Disable default process and Node metrics
+
+`defaultMetrics` defaults to `true`, so `MetricsModule.forRoot()` registers Prometheus default process and Node.js collectors once per registry unless you opt out.
+
+```ts
+MetricsModule.forRoot({
+  defaultMetrics: false,
+});
+```
+
+## Public API
+
+- `MetricsModule.forRoot(options)`
+- `MetricsService`
+- `METER_PROVIDER`
+- Prometheus-backed helpers for counters, gauges, histograms, and registry access
+
+### Operational defaults
+
+- `path` defaults to `'/metrics'`, and `path: false` disables the scrape endpoint entirely.
+- `defaultMetrics` defaults to `true`, and `defaultMetrics: false` disables Prometheus default process and Node.js collectors for that registry.
+- `endpointMiddleware` binds route-scoped middleware only to the scrape endpoint.
+- HTTP metrics default to template-normalized path labels.
+- Raw path labels require `allowUnsafeRawPathLabelMode: true` and should stay limited to bounded internal routes.
+- Platform telemetry is omitted only when `PLATFORM_SHELL` is genuinely missing; other resolution failures fail the scrape.
+
+## Related Packages
+
+- `@fluojs/http`: contributes the request lifecycle that HTTP metrics observe
+- `@fluojs/runtime`: provides platform state used by runtime telemetry gauges
+- `@fluojs/terminus`: commonly paired with metrics for ops visibility
+
+## Example Sources
+
+- `examples/ops-metrics-terminus/src/app.ts`
+- `packages/metrics/src/metrics-module.test.ts`

package/dist/http-metrics-middleware.d.ts

@@ -0,0 +1,37 @@
+import type { FrameworkRequest, Middleware, MiddlewareContext, Next } from '@fluojs/http';
+import type { Registry } from 'prom-client';
+/** Strategy used to label request paths in emitted HTTP metrics. */
+export type HttpMetricsPathLabelMode = 'raw' | 'template';
+/** Context passed to a custom path-label normalizer. */
+export interface HttpMetricsPathLabelContext {
+    method: string;
+    params: Readonly<Record<string, string>>;
+    path: string;
+    request: FrameworkRequest;
+}
+/** Callback that resolves the final path label used in emitted metrics. */
+export type HttpMetricsPathLabelNormalizer = (context: HttpMetricsPathLabelContext) => string;
+/** Options that tune HTTP request metric label generation. */
+export interface HttpMetricsMiddlewareOptions {
+    pathLabelMode?: HttpMetricsPathLabelMode;
+    pathLabelNormalizer?: HttpMetricsPathLabelNormalizer;
+    unknownPathLabel?: string;
+    allowUnsafeRawPathLabelMode?: boolean;
+}
+/**
+ * Middleware that records HTTP request totals, failures, and latency.
+ */
+export declare class HttpMetricsMiddleware implements Middleware {
+    private readonly requestsTotal;
+    private readonly errorsTotal;
+    private readonly requestDuration;
+    private readonly pathLabelMode;
+    private readonly pathLabelNormalizer?;
+    private readonly unknownPathLabel;
+    constructor(registry: Registry, options?: HttpMetricsMiddlewareOptions);
+    private resolvePathLabel;
+    handle(context: MiddlewareContext, next: Next): Promise<void>;
+    private resolveStatusCode;
+    private recordRequestMetrics;
+}
+//# sourceMappingURL=http-metrics-middleware.d.ts.map

package/dist/http-metrics-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-metrics-middleware.d.ts","sourceRoot":"","sources":["../src/http-metrics-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAkB5C,oEAAoE;AACpE,MAAM,MAAM,wBAAwB,GAAG,KAAK,GAAG,UAAU,CAAC;AAE1D,wDAAwD;AACxD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,MAAM,8BAA8B,GAAG,CAAC,OAAO,EAAE,2BAA2B,KAAK,MAAM,CAAC;AAE9F,8DAA8D;AAC9D,MAAM,WAAW,4BAA4B;IAC3C,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAsBD;;GAEG;AACH,qBAAa,qBAAsB,YAAW,UAAU;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAiC;IACtE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,4BAAiC;IA2B1E,OAAO,CAAC,gBAAgB;IAmBlB,MAAM,CAAC,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBnE,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,oBAAoB;CAsB7B"}

package/dist/http-metrics-middleware.js

@@ -0,0 +1,155 @@
+import { createPrometheusCounter, createPrometheusHistogram } from './providers/prometheus-metrics-factory.js';
+
+/** Strategy used to label request paths in emitted HTTP metrics. */
+
+/** Context passed to a custom path-label normalizer. */
+
+/** Callback that resolves the final path label used in emitted metrics. */
+
+/** Options that tune HTTP request metric label generation. */
+
+function readErrorStatusCode(error) {
+  if (typeof error !== 'object' || error === null) {
+    return undefined;
+  }
+  const candidate = error;
+  const fromStatus = typeof candidate.status === 'number' ? candidate.status : undefined;
+  const fromStatusCode = typeof candidate.statusCode === 'number' ? candidate.statusCode : undefined;
+  if (fromStatus !== undefined && Number.isFinite(fromStatus)) {
+    return fromStatus;
+  }
+  if (fromStatusCode !== undefined && Number.isFinite(fromStatusCode)) {
+    return fromStatusCode;
+  }
+  return undefined;
+}
+
+/**
+ * Middleware that records HTTP request totals, failures, and latency.
+ */
+export class HttpMetricsMiddleware {
+  requestsTotal;
+  errorsTotal;
+  requestDuration;
+  pathLabelMode;
+  pathLabelNormalizer;
+  unknownPathLabel;
+  constructor(registry, options = {}) {
+    if (options.pathLabelMode === 'raw' && options.allowUnsafeRawPathLabelMode !== true) {
+      throw new Error('HttpMetricsMiddleware pathLabelMode "raw" is disabled by default. Pass allowUnsafeRawPathLabelMode: true only when you have bounded path cardinality.');
+    }
+    this.pathLabelMode = options.pathLabelMode ?? 'template';
+    this.pathLabelNormalizer = options.pathLabelNormalizer;
+    this.unknownPathLabel = options.unknownPathLabel ?? 'UNKNOWN';
+    this.requestsTotal = createPrometheusCounter(registry, {
+      help: 'Total number of HTTP requests',
+      labelNames: ['method', 'path', 'status'],
+      name: 'http_requests_total'
+    });
+    this.errorsTotal = createPrometheusCounter(registry, {
+      help: 'Total number of HTTP error responses (4xx/5xx)',
+      labelNames: ['method', 'path', 'status'],
+      name: 'http_errors_total'
+    });
+    this.requestDuration = createPrometheusHistogram(registry, {
+      help: 'HTTP request duration in seconds',
+      labelNames: ['method', 'path', 'status'],
+      name: 'http_request_duration_seconds'
+    });
+  }
+  resolvePathLabel(request) {
+    if (this.pathLabelNormalizer) {
+      const normalized = this.pathLabelNormalizer({
+        method: request.method,
+        params: request.params,
+        path: request.path,
+        request
+      });
+      return normalized.trim() || this.unknownPathLabel;
+    }
+    if (this.pathLabelMode === 'raw') {
+      return request.path;
+    }
+    const normalized = normalizePathToTemplate(request.path, request.params);
+    return normalized || this.unknownPathLabel;
+  }
+  async handle(context, next) {
+    const start = performance.now();
+    const method = context.request.method;
+    const path = this.resolvePathLabel(context.request);
+    let requestError;
+    try {
+      await next();
+    } catch (error) {
+      requestError = error;
+      throw error;
+    } finally {
+      const durationSeconds = (performance.now() - start) / 1000;
+      this.recordRequestMetrics(method, path, this.resolveStatusCode(context.response.statusCode, requestError), durationSeconds, requestError);
+    }
+  }
+  resolveStatusCode(responseStatusCode, requestError) {
+    if (responseStatusCode !== undefined) {
+      return responseStatusCode;
+    }
+    if (requestError === undefined) {
+      return 200;
+    }
+    return readErrorStatusCode(requestError) ?? 500;
+  }
+  recordRequestMetrics(method, path, statusCode, durationSeconds, requestError) {
+    const baseLabels = {
+      method,
+      path,
+      status: String(statusCode)
+    };
+    const requestLabels = {
+      ...baseLabels
+    };
+    const errorLabels = statusCode >= 400 || requestError !== undefined ? {
+      ...baseLabels
+    } : undefined;
+    this.requestsTotal.inc(requestLabels);
+    this.requestDuration.observe(baseLabels, durationSeconds);
+    if (errorLabels) {
+      this.errorsTotal.inc(errorLabels);
+    }
+  }
+}
+function normalizePathToTemplate(path, params) {
+  if (!path) {
+    return '/';
+  }
+  const normalizedSegments = [];
+  const paramEntries = Object.entries(params);
+  const usedParamKeys = new Set();
+  for (const segment of path.split('/')) {
+    if (!segment) {
+      continue;
+    }
+    const decoded = safeDecodeURIComponent(segment);
+    let normalizedSegment = segment;
+    for (const [paramKey, paramValue] of paramEntries) {
+      if (usedParamKeys.has(paramKey)) {
+        continue;
+      }
+      if (segment === paramValue || decoded === paramValue) {
+        normalizedSegment = `:${paramKey}`;
+        usedParamKeys.add(paramKey);
+        break;
+      }
+    }
+    normalizedSegments.push(normalizedSegment);
+  }
+  if (normalizedSegments.length === 0) {
+    return '/';
+  }
+  return `/${normalizedSegments.join('/')}`;
+}
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Registry } from 'prom-client';
+export * from './metrics-module.js';
+export * from './metrics-service.js';
+export * from './providers/meter-provider.js';
+export * from './providers/prometheus-meter-provider.js';
+export * from './http-metrics-middleware.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Registry } from 'prom-client';
+export * from './metrics-module.js';
+export * from './metrics-service.js';
+export * from './providers/meter-provider.js';
+export * from './providers/prometheus-meter-provider.js';
+export * from './http-metrics-middleware.js';

package/dist/metrics-module.d.ts

@@ -0,0 +1,48 @@
+import { type Middleware, type MiddlewareLike } from '@fluojs/http';
+import { type ModuleType } from '@fluojs/runtime';
+import { type Registry } from 'prom-client';
+import { type HttpMetricsPathLabelMode, type HttpMetricsPathLabelNormalizer } from './http-metrics-middleware.js';
+/** HTTP-specific metric labeling options exposed by `MetricsModule.forRoot(...)`. */
+export interface MetricsHttpOptions {
+    pathLabelMode?: HttpMetricsPathLabelMode;
+    pathLabelNormalizer?: HttpMetricsPathLabelNormalizer;
+    unknownPathLabel?: string;
+    allowUnsafeRawPathLabelMode?: boolean;
+}
+/**
+ * Module options for exposing Prometheus metrics and runtime platform telemetry.
+ */
+export interface MetricsModuleOptions {
+    http?: boolean | MetricsHttpOptions;
+    path?: string | false;
+    provider?: 'prometheus';
+    defaultMetrics?: boolean;
+    middleware?: MiddlewareLike[];
+    endpointMiddleware?: Array<new (...args: any[]) => Middleware>;
+    platformTelemetry?: {
+        env?: string;
+        instance?: string;
+    };
+    /** External Prometheus registry to share between built-in and custom metrics. */
+    registry?: Registry;
+}
+/** Module entry point that exposes `/metrics` and optional HTTP/runtime telemetry. */
+export declare class MetricsModule {
+    private static registeredRegistries;
+    /**
+     * Register framework metrics, optional HTTP middleware, and a scrape endpoint.
+     *
+     * @example
+     * ```ts
+     * MetricsModule.forRoot({
+     *   http: { pathLabelMode: 'template' },
+     *   registry: new Registry(),
+     * });
+     * ```
+     *
+     * @param options Metrics endpoint, registry, HTTP middleware, and runtime telemetry configuration.
+     * @returns A runtime module that exposes metrics through the configured path.
+     */
+    static forRoot(options?: MetricsModuleOptions): ModuleType;
+}
+//# sourceMappingURL=metrics-module.d.ts.map

package/dist/metrics-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-module.d.ts","sourceRoot":"","sources":["../src/metrics-module.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,UAAU,EAAE,KAAK,cAAc,EAAuB,MAAM,cAAc,CAAC;AACrH,OAAO,EAAgB,KAAK,UAAU,EAA8C,MAAM,iBAAiB,CAAC;AAC5G,OAAO,EAAgE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE1G,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACpC,MAAM,8BAA8B,CAAC;AAKtC,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACtB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,kBAAkB,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,UAAU,CAAC,CAAC;IAC/D,iBAAiB,CAAC,EAAE;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,iFAAiF;IACjF,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,sFAAsF;AACtF,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAA2B;IAE9D;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU;CAqE/D"}

package/dist/metrics-module.js

@@ -0,0 +1,277 @@
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { ContainerResolutionError } from '@fluojs/di';
+import { Controller, Get, forRoutes } from '@fluojs/http';
+import { defineModule, PLATFORM_SHELL } from '@fluojs/runtime';
+import { collectDefaultMetrics, Gauge, Registry as PrometheusRegistry } from 'prom-client';
+import { HttpMetricsMiddleware } from './http-metrics-middleware.js';
+import { METER_PROVIDER } from './providers/meter-provider.js';
+import { MetricsService } from './metrics-service.js';
+import { PrometheusMeterProvider } from './providers/prometheus-meter-provider.js';
+
+/** HTTP-specific metric labeling options exposed by `MetricsModule.forRoot(...)`. */
+
+/**
+ * Module options for exposing Prometheus metrics and runtime platform telemetry.
+ */
+
+/** Module entry point that exposes `/metrics` and optional HTTP/runtime telemetry. */
+export class MetricsModule {
+  static registeredRegistries = new WeakSet();
+
+  /**
+   * Register framework metrics, optional HTTP middleware, and a scrape endpoint.
+   *
+   * @example
+   * ```ts
+   * MetricsModule.forRoot({
+   *   http: { pathLabelMode: 'template' },
+   *   registry: new Registry(),
+   * });
+   * ```
+   *
+   * @param options Metrics endpoint, registry, HTTP middleware, and runtime telemetry configuration.
+   * @returns A runtime module that exposes metrics through the configured path.
+   */
+  static forRoot(options = {}) {
+    const provider = options.provider ?? 'prometheus';
+    if (provider !== 'prometheus') {
+      throw new Error(`MetricsModule provider "${provider}" is not supported. Use provider "prometheus".`);
+    }
+    const httpOptions = resolveHttpOptions(options.http);
+    const metricsPath = options.path === undefined ? '/metrics' : options.path;
+    const registry = options.registry ?? new PrometheusRegistry();
+    const metricsService = new MetricsService(registry);
+    const meterProvider = new PrometheusMeterProvider(registry);
+    const platformTelemetry = new RuntimePlatformTelemetry(registry, options.registry ? 'shared' : 'isolated', options.platformTelemetry);
+    if (options.defaultMetrics !== false && !MetricsModule.registeredRegistries.has(registry)) {
+      MetricsModule.registeredRegistries.add(registry);
+      collectDefaultMetrics({
+        register: registry
+      });
+    }
+    const endpointMiddleware = metricsPath ? (options.endpointMiddleware ?? []).map(middlewareClass => forRoutes(middlewareClass, metricsPath)) : [];
+    const middleware = [...endpointMiddleware, ...(httpOptions ? [new HttpMetricsMiddleware(registry, httpOptions)] : []), ...(options.middleware ?? [])];
+    const providers = [{
+      provide: MetricsService,
+      useValue: metricsService
+    }, {
+      provide: METER_PROVIDER,
+      useValue: meterProvider
+    }];
+    const controllers = [];
+    if (typeof metricsPath === 'string') {
+      let _initProto, _initClass;
+      const metricsRoutePath = metricsPath;
+      let _MetricsController;
+      class MetricsController {
+        static {
+          ({
+            e: [_initProto],
+            c: [_MetricsController, _initClass]
+          } = _applyDecs(this, [Controller('')], [[Get(metricsRoutePath), 2, "getMetrics"]]));
+        }
+        constructor() {
+          _initProto(this);
+        }
+        async getMetrics(_input, ctx) {
+          ctx.response.setHeader('content-type', registry.contentType);
+          return platformTelemetry.collectMetrics(ctx, registry);
+        }
+        static {
+          _initClass();
+        }
+      }
+      controllers.push(_MetricsController);
+    }
+    class MetricsRuntimeModule {}
+    defineModule(MetricsRuntimeModule, {
+      controllers,
+      middleware,
+      providers
+    });
+    return MetricsRuntimeModule;
+  }
+}
+const PLATFORM_COMPONENT_LABELS = ['component_id', 'component_kind', 'operation', 'result', 'env', 'instance'];
+const REGISTRY_MODE_LABELS = ['mode'];
+const HEALTH_STATUSES = ['healthy', 'unhealthy', 'degraded'];
+const READINESS_STATUSES = ['ready', 'not-ready', 'degraded'];
+const PLATFORM_SHELL_TOKEN_NAME = 'PLATFORM_SHELL';
+const PLATFORM_SHELL_TOKEN_NAMES = new Set([PLATFORM_SHELL_TOKEN_NAME, String(PLATFORM_SHELL)]);
+function toReadinessValue(status) {
+  return status === 'ready' ? 1 : 0;
+}
+function toHealthValue(status) {
+  return status === 'healthy' ? 1 : 0;
+}
+function getOrCreateGauge(registry, config) {
+  const existing = registry.getSingleMetric(config.name);
+  if (existing instanceof Gauge) {
+    return existing;
+  }
+  return new Gauge({
+    help: config.help,
+    labelNames: [...config.labelNames],
+    name: config.name,
+    registers: [registry]
+  });
+}
+class RuntimePlatformTelemetry {
+  readinessGauge;
+  healthGauge;
+  registryModeGauge;
+  lastHealthStatuses = new Map();
+  lastReadinessStatuses = new Map();
+  scrapeChain = Promise.resolve();
+  constructor(registry, registryMode, labels = {}) {
+    this.registryMode = registryMode;
+    this.labels = labels;
+    this.readinessGauge = getOrCreateGauge(registry, {
+      help: 'Runtime platform component readiness from shared platform snapshot semantics.',
+      labelNames: PLATFORM_COMPONENT_LABELS,
+      name: 'fluo_component_ready'
+    });
+    this.healthGauge = getOrCreateGauge(registry, {
+      help: 'Runtime platform component health from shared platform snapshot semantics.',
+      labelNames: PLATFORM_COMPONENT_LABELS,
+      name: 'fluo_component_health'
+    });
+    this.registryModeGauge = getOrCreateGauge(registry, {
+      help: 'Metrics module registry mode: isolated or shared.',
+      labelNames: REGISTRY_MODE_LABELS,
+      name: 'fluo_metrics_registry_mode'
+    });
+    this.registryModeGauge.labels(this.registryMode).set(1);
+  }
+  async collectMetrics(ctx, registry) {
+    const collect = this.scrapeChain.then(async () => {
+      await this.refresh(ctx);
+      return registry.metrics();
+    });
+    this.scrapeChain = collect.then(() => undefined, () => undefined);
+    return collect;
+  }
+  async refresh(ctx) {
+    const platformShell = await this.resolvePlatformShell(ctx);
+    if (!platformShell) {
+      return;
+    }
+    const snapshot = await platformShell.snapshot();
+    const env = this.labels?.env ?? 'unknown';
+    const instance = this.labels?.instance ?? 'local';
+    const components = [{
+      health: snapshot.health.status,
+      id: 'runtime.shell',
+      kind: 'runtime',
+      readiness: snapshot.readiness.status
+    }, ...snapshot.components.map(component => ({
+      health: component.health.status,
+      id: component.id,
+      kind: component.kind,
+      readiness: component.readiness.status
+    }))];
+    this.syncGaugeStatuses({
+      currentStatuses: new Map(components.map(component => [this.toComponentKey(component.id, component.kind), component.health])),
+      env,
+      gauge: this.healthGauge,
+      instance,
+      lastStatuses: this.lastHealthStatuses,
+      operation: 'health',
+      statuses: HEALTH_STATUSES,
+      toMetricValue: toHealthValue
+    });
+    this.syncGaugeStatuses({
+      currentStatuses: new Map(components.map(component => [this.toComponentKey(component.id, component.kind), component.readiness])),
+      env,
+      gauge: this.readinessGauge,
+      instance,
+      lastStatuses: this.lastReadinessStatuses,
+      operation: 'readiness',
+      statuses: READINESS_STATUSES,
+      toMetricValue: toReadinessValue
+    });
+  }
+  syncGaugeStatuses({
+    currentStatuses,
+    env,
+    gauge,
+    instance,
+    lastStatuses,
+    operation,
+    statuses,
+    toMetricValue
+  }) {
+    for (const [componentKey, previousStatus] of lastStatuses) {
+      const nextStatus = currentStatuses.get(componentKey);
+      if (nextStatus === previousStatus) {
+        continue;
+      }
+      const [componentId, componentKind] = this.fromComponentKey(componentKey);
+      for (const status of statuses) {
+        if (status !== previousStatus) {
+          continue;
+        }
+        gauge.remove(componentId, componentKind, operation, status, env, instance);
+      }
+    }
+    for (const [componentKey, currentStatus] of currentStatuses) {
+      const [componentId, componentKind] = this.fromComponentKey(componentKey);
+      gauge.labels(componentId, componentKind, operation, currentStatus, env, instance).set(toMetricValue(currentStatus));
+    }
+    lastStatuses.clear();
+    for (const [componentKey, currentStatus] of currentStatuses) {
+      lastStatuses.set(componentKey, currentStatus);
+    }
+  }
+  fromComponentKey(componentKey) {
+    const separatorIndex = componentKey.indexOf('::');
+    return [componentKey.slice(0, separatorIndex), componentKey.slice(separatorIndex + 2)];
+  }
+  toComponentKey(componentId, componentKind) {
+    return `${componentId}::${componentKind}`;
+  }
+  async resolvePlatformShell(ctx) {
+    try {
+      return await ctx.container.resolve(PLATFORM_SHELL);
+    } catch (error) {
+      if (isMissingPlatformShellResolutionError(error)) {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+}
+function isMissingPlatformShellResolutionError(error) {
+  if (!(error instanceof ContainerResolutionError)) {
+    return false;
+  }
+  const containerError = error;
+  const token = typeof containerError.meta?.['token'] === 'string' ? containerError.meta['token'] : undefined;
+  if (token && PLATFORM_SHELL_TOKEN_NAMES.has(token)) {
+    return containerError.message.startsWith(`No provider registered for token ${token}.`);
+  }
+  for (const tokenName of PLATFORM_SHELL_TOKEN_NAMES) {
+    if (containerError.message.startsWith(`No provider registered for token ${tokenName}.`)) {
+      return true;
+    }
+  }
+  return false;
+}
+function resolveHttpOptions(http) {
+  if (!http) {
+    return undefined;
+  }
+  if (http === true) {
+    return {};
+  }
+  return {
+    allowUnsafeRawPathLabelMode: http.allowUnsafeRawPathLabelMode,
+    pathLabelMode: http.pathLabelMode,
+    pathLabelNormalizer: http.pathLabelNormalizer,
+    unknownPathLabel: http.unknownPathLabel
+  };
+}

package/dist/metrics-service.d.ts

@@ -0,0 +1,36 @@
+import type { Registry, CounterConfiguration, GaugeConfiguration, HistogramConfiguration } from 'prom-client';
+/**
+ * Small facade for creating custom Prometheus metrics on the module registry.
+ */
+export declare class MetricsService {
+    private readonly registry;
+    constructor(registry: Registry);
+    /**
+     * Create a counter on the module registry.
+     *
+     * @param config Prometheus counter configuration.
+     * @returns A counter registered on this module's registry.
+     */
+    counter<T extends string = string>(config: CounterConfiguration<T>): import("prom-client").Counter<T>;
+    /**
+     * Create a gauge on the module registry.
+     *
+     * @param config Prometheus gauge configuration.
+     * @returns A gauge registered on this module's registry.
+     */
+    gauge<T extends string = string>(config: GaugeConfiguration<T>): import("prom-client").Gauge<T>;
+    /**
+     * Create a histogram on the module registry.
+     *
+     * @param config Prometheus histogram configuration.
+     * @returns A histogram registered on this module's registry.
+     */
+    histogram<T extends string = string>(config: HistogramConfiguration<T>): import("prom-client").Histogram<T>;
+    /**
+     * Return the underlying Prometheus registry used by the module.
+     *
+     * @returns The registry backing all framework and custom metrics.
+     */
+    getRegistry(): Registry;
+}
+//# sourceMappingURL=metrics-service.d.ts.map

package/dist/metrics-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-service.d.ts","sourceRoot":"","sources":["../src/metrics-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAIrB;;GAEG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,QAAQ;IAE/C;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAIlE;;;;;OAKG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAI9D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAItE;;;;OAIG;IACH,WAAW,IAAI,QAAQ;CAGxB"}

package/dist/metrics-service.js

@@ -0,0 +1,49 @@
+import { createPrometheusCounter, createPrometheusGauge, createPrometheusHistogram } from './providers/prometheus-metrics-factory.js';
+
+/**
+ * Small facade for creating custom Prometheus metrics on the module registry.
+ */
+export class MetricsService {
+  constructor(registry) {
+    this.registry = registry;
+  }
+
+  /**
+   * Create a counter on the module registry.
+   *
+   * @param config Prometheus counter configuration.
+   * @returns A counter registered on this module's registry.
+   */
+  counter(config) {
+    return createPrometheusCounter(this.registry, config);
+  }
+
+  /**
+   * Create a gauge on the module registry.
+   *
+   * @param config Prometheus gauge configuration.
+   * @returns A gauge registered on this module's registry.
+   */
+  gauge(config) {
+    return createPrometheusGauge(this.registry, config);
+  }
+
+  /**
+   * Create a histogram on the module registry.
+   *
+   * @param config Prometheus histogram configuration.
+   * @returns A histogram registered on this module's registry.
+   */
+  histogram(config) {
+    return createPrometheusHistogram(this.registry, config);
+  }
+
+  /**
+   * Return the underlying Prometheus registry used by the module.
+   *
+   * @returns The registry backing all framework and custom metrics.
+   */
+  getRegistry() {
+    return this.registry;
+  }
+}

package/dist/providers/meter-provider.d.ts

@@ -0,0 +1,22 @@
+/** Counter facade exposed by the metrics abstraction layer. */
+export interface MeterCounter {
+    inc(labels?: Record<string, string | number>, value?: number): void;
+}
+/** Gauge facade exposed by the metrics abstraction layer. */
+export interface MeterGauge {
+    set(value: number, labels?: Record<string, string | number>): void;
+}
+/** Histogram facade exposed by the metrics abstraction layer. */
+export interface MeterHistogram {
+    observe(value: number, labels?: Record<string, string | number>): void;
+}
+/** Provider interface that creates concrete metric instruments for one backend. */
+export interface MeterProvider {
+    readonly type: 'prometheus' | 'otel' | string;
+    createCounter(name: string, help: string, labelNames?: string[]): MeterCounter;
+    createGauge(name: string, help: string, labelNames?: string[]): MeterGauge;
+    createHistogram(name: string, help: string, labelNames?: string[], buckets?: number[]): MeterHistogram;
+}
+/** Dependency-injection token for the active framework meter provider. */
+export declare const METER_PROVIDER: unique symbol;
+//# sourceMappingURL=meter-provider.d.ts.map

package/dist/providers/meter-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter-provider.d.ts","sourceRoot":"","sources":["../../src/providers/meter-provider.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrE;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;CACpE;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;CACxE;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC;IAC/E,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IAC3E,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC;CACxG;AAED,0EAA0E;AAC1E,eAAO,MAAM,cAAc,eAA4C,CAAC"}

package/dist/providers/meter-provider.js

@@ -0,0 +1,10 @@
+/** Counter facade exposed by the metrics abstraction layer. */
+
+/** Gauge facade exposed by the metrics abstraction layer. */
+
+/** Histogram facade exposed by the metrics abstraction layer. */
+
+/** Provider interface that creates concrete metric instruments for one backend. */
+
+/** Dependency-injection token for the active framework meter provider. */
+export const METER_PROVIDER = Symbol.for('fluo.metrics.meter-provider');

package/dist/providers/prometheus-meter-provider.d.ts

@@ -0,0 +1,12 @@
+import type { Registry } from 'prom-client';
+import type { MeterCounter, MeterGauge, MeterHistogram, MeterProvider } from './meter-provider.js';
+/** Meter-provider implementation that maps the framework abstraction onto Prometheus. */
+export declare class PrometheusMeterProvider implements MeterProvider {
+    private readonly registry;
+    readonly type: "prometheus";
+    constructor(registry: Registry);
+    createCounter(name: string, help: string, labelNames?: string[]): MeterCounter;
+    createGauge(name: string, help: string, labelNames?: string[]): MeterGauge;
+    createHistogram(name: string, help: string, labelNames?: string[], buckets?: number[]): MeterHistogram;
+}
+//# sourceMappingURL=prometheus-meter-provider.d.ts.map

package/dist/providers/prometheus-meter-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prometheus-meter-provider.d.ts","sourceRoot":"","sources":["../../src/providers/prometheus-meter-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGnG,yFAAyF;AACzF,qBAAa,uBAAwB,YAAW,aAAa;IAG/C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;gBAET,QAAQ,EAAE,QAAQ;IAE/C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,EAAO,GAAG,YAAY;IAmBlF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,EAAO,GAAG,UAAU;IAmB9E,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,EAAO,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc;CAmB3G"}

package/dist/providers/prometheus-meter-provider.js

@@ -0,0 +1,58 @@
+import { createPrometheusCounter, createPrometheusGauge, createPrometheusHistogram } from './prometheus-metrics-factory.js';
+
+/** Meter-provider implementation that maps the framework abstraction onto Prometheus. */
+export class PrometheusMeterProvider {
+  type = 'prometheus';
+  constructor(registry) {
+    this.registry = registry;
+  }
+  createCounter(name, help, labelNames = []) {
+    const counter = createPrometheusCounter(this.registry, {
+      help,
+      labelNames,
+      name
+    });
+    return {
+      inc(labels, value = 1) {
+        if (labels) {
+          counter.inc(labels, value);
+          return;
+        }
+        counter.inc(value);
+      }
+    };
+  }
+  createGauge(name, help, labelNames = []) {
+    const gauge = createPrometheusGauge(this.registry, {
+      help,
+      labelNames,
+      name
+    });
+    return {
+      set(value, labels) {
+        if (labels) {
+          gauge.set(labels, value);
+          return;
+        }
+        gauge.set(value);
+      }
+    };
+  }
+  createHistogram(name, help, labelNames = [], buckets) {
+    const histogram = createPrometheusHistogram(this.registry, {
+      buckets,
+      help,
+      labelNames,
+      name
+    });
+    return {
+      observe(value, labels) {
+        if (labels) {
+          histogram.observe(labels, value);
+          return;
+        }
+        histogram.observe(value);
+      }
+    };
+  }
+}

package/dist/providers/prometheus-metrics-factory.d.ts

@@ -0,0 +1,26 @@
+import { Counter, Gauge, Histogram, type CounterConfiguration, type GaugeConfiguration, type HistogramConfiguration, type Registry } from 'prom-client';
+/**
+ * Create a Prometheus counter bound to the provided registry.
+ *
+ * @param registry Prometheus registry that should own the created metric.
+ * @param config Counter configuration forwarded to `prom-client`.
+ * @returns A Prometheus counter registered only on the provided registry.
+ */
+export declare function createPrometheusCounter<T extends string = string>(registry: Registry, config: CounterConfiguration<T>): Counter<T>;
+/**
+ * Create a Prometheus gauge bound to the provided registry.
+ *
+ * @param registry Prometheus registry that should own the created metric.
+ * @param config Gauge configuration forwarded to `prom-client`.
+ * @returns A Prometheus gauge registered only on the provided registry.
+ */
+export declare function createPrometheusGauge<T extends string = string>(registry: Registry, config: GaugeConfiguration<T>): Gauge<T>;
+/**
+ * Create a Prometheus histogram bound to the provided registry.
+ *
+ * @param registry Prometheus registry that should own the created metric.
+ * @param config Histogram configuration forwarded to `prom-client`.
+ * @returns A Prometheus histogram registered only on the provided registry.
+ */
+export declare function createPrometheusHistogram<T extends string = string>(registry: Registry, config: HistogramConfiguration<T>): Histogram<T>;
+//# sourceMappingURL=prometheus-metrics-factory.d.ts.map

package/dist/providers/prometheus-metrics-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prometheus-metrics-factory.d.ts","sourceRoot":"","sources":["../../src/providers/prometheus-metrics-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,EACL,SAAS,EACT,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC/D,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC7D,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC5B,KAAK,CAAC,CAAC,CAAC,CAEV;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACjE,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAChC,SAAS,CAAC,CAAC,CAAC,CAEd"}

package/dist/providers/prometheus-metrics-factory.js

@@ -0,0 +1,43 @@
+import { Counter, Gauge, Histogram } from 'prom-client';
+
+/**
+ * Create a Prometheus counter bound to the provided registry.
+ *
+ * @param registry Prometheus registry that should own the created metric.
+ * @param config Counter configuration forwarded to `prom-client`.
+ * @returns A Prometheus counter registered only on the provided registry.
+ */
+export function createPrometheusCounter(registry, config) {
+  return new Counter({
+    ...config,
+    registers: [registry]
+  });
+}
+
+/**
+ * Create a Prometheus gauge bound to the provided registry.
+ *
+ * @param registry Prometheus registry that should own the created metric.
+ * @param config Gauge configuration forwarded to `prom-client`.
+ * @returns A Prometheus gauge registered only on the provided registry.
+ */
+export function createPrometheusGauge(registry, config) {
+  return new Gauge({
+    ...config,
+    registers: [registry]
+  });
+}
+
+/**
+ * Create a Prometheus histogram bound to the provided registry.
+ *
+ * @param registry Prometheus registry that should own the created metric.
+ * @param config Histogram configuration forwarded to `prom-client`.
+ * @returns A Prometheus histogram registered only on the provided registry.
+ */
+export function createPrometheusHistogram(registry, config) {
+  return new Histogram({
+    ...config,
+    registers: [registry]
+  });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@fluojs/metrics",
+  "description": "Prometheus metrics exposure with isolated registries and low-cardinality HTTP metric middleware for Fluo.",
+  "keywords": [
+    "fluo",
+    "metrics",
+    "prometheus",
+    "monitoring",
+    "observability"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/metrics"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "prom-client": "^15.1.3",
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1",
+    "@fluojs/http": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}