@gravito/core 1.6.0 → 1.6.1

package/dist/Metrics-VOWWRNNR.js

@@ -0,0 +1,219 @@
+import "./chunk-R5U7XKVJ.js";
+
+// src/observability/Metrics.ts
+var DEFAULTS = {
+  port: 9090,
+  prefix: "gravito_event_",
+  interval: 6e4,
+  // 60 秒
+  defaultMetrics: true
+};
+async function setupPrometheusMetrics(config = {}) {
+  const finalConfig = {
+    port: config.port ?? parseInt(process.env.PROMETHEUS_PORT || String(DEFAULTS.port), 10),
+    prefix: config.prefix ?? process.env.PROMETHEUS_PREFIX ?? DEFAULTS.prefix,
+    interval: config.interval ?? parseInt(process.env.PROMETHEUS_INTERVAL || String(DEFAULTS.interval), 10),
+    defaultMetrics: config.defaultMetrics ?? process.env.PROMETHEUS_DEFAULT_METRICS !== "false"
+  };
+  try {
+    const { metrics } = await import("@opentelemetry/api");
+    const { MeterProvider } = await import("@opentelemetry/sdk-metrics");
+    const { PrometheusExporter } = await import("@opentelemetry/exporter-prometheus");
+    const exporter = new PrometheusExporter(
+      {
+        port: finalConfig.port,
+        endpoint: "/metrics"
+      },
+      () => {
+        console.log(
+          `[Metrics] Prometheus metrics available at http://localhost:${finalConfig.port}/metrics`
+        );
+      }
+    );
+    const meterProvider = new MeterProvider({
+      exporter,
+      interval: finalConfig.interval
+    });
+    metrics.setGlobalMeterProvider(meterProvider);
+    if (finalConfig.defaultMetrics) {
+      try {
+        const { collectDefaultMetrics } = await import("@opentelemetry/auto-instrumentations-node");
+        collectDefaultMetrics({ meterProvider, prefix: finalConfig.prefix });
+      } catch (error) {
+        console.warn("[Metrics] Failed to setup default metrics:", error);
+      }
+    }
+    return {
+      port: finalConfig.port,
+      endpoint: `/metrics`
+    };
+  } catch (error) {
+    console.warn("[Metrics] Failed to setup Prometheus exporter:", error);
+    console.log("[Metrics] Metrics will not be exported to Prometheus");
+    return null;
+  }
+}
+function getEventMetricsDefinition(prefix = DEFAULTS.prefix) {
+  return {
+    dispatchLatency: {
+      name: `${prefix}dispatch_latency_seconds`,
+      help: "Event dispatch latency distribution",
+      labels: ["event_name", "priority"],
+      buckets: [1e-3, 5e-3, 0.01, 0.05, 0.1, 0.5, 1, 2, 5]
+    },
+    listenerExecutionTime: {
+      name: `${prefix}listener_execution_seconds`,
+      help: "Individual listener execution time",
+      labels: ["event_name", "listener_name"],
+      buckets: [1e-3, 5e-3, 0.01, 0.05, 0.1, 0.5, 1, 2, 5]
+    },
+    queueDepth: {
+      name: `${prefix}queue_depth`,
+      help: "Current queue depth by priority",
+      labels: ["priority"]
+    },
+    failureRate: {
+      name: `${prefix}failures_total`,
+      help: "Total event processing failures",
+      labels: ["event_name", "error_type"]
+    },
+    timeoutCount: {
+      name: `${prefix}timeouts_total`,
+      help: "Total event timeouts",
+      labels: ["event_name"]
+    },
+    throughput: {
+      name: `${prefix}throughput_total`,
+      help: "Total events processed",
+      labels: ["event_name", "status"]
+    },
+    circuitBreakerState: {
+      name: `${prefix}circuit_breaker_state`,
+      help: "Current circuit breaker state (0=CLOSED, 1=HALF_OPEN, 2=OPEN)",
+      labels: ["event_name"]
+    },
+    circuitBreakerTransitions: {
+      name: `${prefix}circuit_breaker_transitions_total`,
+      help: "Total number of circuit breaker state transitions",
+      labels: ["event_name", "from_state", "to_state"]
+    },
+    circuitBreakerFailures: {
+      name: `${prefix}circuit_breaker_failures_total`,
+      help: "Total number of failures tracked by circuit breaker",
+      labels: ["event_name"]
+    },
+    circuitBreakerSuccesses: {
+      name: `${prefix}circuit_breaker_successes_total`,
+      help: "Total number of successes tracked by circuit breaker",
+      labels: ["event_name"]
+    },
+    circuitBreakerOpenDuration: {
+      name: `${prefix}circuit_breaker_open_duration_seconds`,
+      help: "Duration of circuit breaker OPEN state in seconds",
+      labels: ["event_name"],
+      buckets: [1, 5, 10, 30, 60, 120, 300]
+    }
+  };
+}
+var PROMETHEUS_QUERIES = {
+  /** 事件派發延遲 P95 */
+  dispatchLatencyP95: "histogram_quantile(0.95, rate(gravito_event_dispatch_latency_seconds_bucket[5m]))",
+  /** 事件派發延遲 P99 */
+  dispatchLatencyP99: "histogram_quantile(0.99, rate(gravito_event_dispatch_latency_seconds_bucket[5m]))",
+  /** 隊列深度（按優先級） */
+  queueDepthByPriority: "gravito_event_queue_depth",
+  /** 吞吐量（事件/秒） */
+  throughput: "rate(gravito_event_throughput_total[1m])",
+  /** 失敗率 */
+  failureRate: "rate(gravito_event_failures_total[5m]) / rate(gravito_event_throughput_total[5m])",
+  /** 監聽器執行時間 P99 */
+  listenerLatencyP99: "histogram_quantile(0.99, rate(gravito_event_listener_execution_seconds_bucket[5m]))",
+  /** 超時次數 */
+  timeoutCount: "rate(gravito_event_timeouts_total[5m])",
+  /** 吞吐量異常檢測 */
+  throughputAnomaly: "rate(gravito_event_throughput_total[5m]) < 100",
+  /** 熔斷器狀態（0=CLOSED, 1=HALF_OPEN, 2=OPEN） */
+  circuitBreakerState: "gravito_event_circuit_breaker_state",
+  /** 熔斷器開啟率 */
+  circuitBreakerOpenRate: 'rate(gravito_event_circuit_breaker_transitions_total{to_state="OPEN"}[5m])',
+  /** 熔斷器恢復率 */
+  circuitBreakerRecoveryRate: 'rate(gravito_event_circuit_breaker_transitions_total{to_state="CLOSED"}[5m])',
+  /** 熔斷器失敗率 */
+  circuitBreakerFailureRate: "rate(gravito_event_circuit_breaker_failures_total[5m])",
+  /** 熔斷器 OPEN 持續時間 P95 */
+  circuitBreakerOpenDurationP95: "histogram_quantile(0.95, rate(gravito_event_circuit_breaker_open_duration_seconds_bucket[5m]))",
+  /** 熔斷器 OPEN 持續時間 P99 */
+  circuitBreakerOpenDurationP99: "histogram_quantile(0.99, rate(gravito_event_circuit_breaker_open_duration_seconds_bucket[5m]))"
+};
+var PROMETHEUS_ALERT_RULES = {
+  /** P99 延遲過高 */
+  HighDispatchLatency: {
+    expr: "histogram_quantile(0.99, gravito_event_dispatch_latency_seconds) > 0.8",
+    for: "5m",
+    severity: "critical",
+    summary: "\u4E8B\u4EF6\u6D3E\u767C P99 \u5EF6\u9072\u904E\u9AD8",
+    description: "P99 \u5EF6\u9072: {{ $value }}s\uFF0C\u5DF2\u8D85\u904E 800ms"
+  },
+  /** 隊列深度過高 */
+  HighQueueDepth: {
+    expr: 'gravito_event_queue_depth{priority="high"} > 1000',
+    for: "2m",
+    severity: "warning",
+    summary: "\u9AD8\u512A\u5148\u7D1A\u4E8B\u4EF6\u968A\u5217\u5806\u7A4D",
+    description: "\u968A\u5217\u6DF1\u5EA6: {{ $value }}\uFF0C\u61C9\u8ABF\u67E5\u539F\u56E0"
+  },
+  /** 失敗率過高 */
+  HighFailureRate: {
+    expr: "(rate(gravito_event_failures_total[5m]) / rate(gravito_event_throughput_total[5m])) > 0.05",
+    for: "3m",
+    severity: "critical",
+    summary: "\u4E8B\u4EF6\u8655\u7406\u5931\u6557\u7387\u904E\u9AD8",
+    description: "\u5931\u6557\u7387: {{ $value | humanizePercentage }}\uFF0C\u8D85\u904E 5%"
+  },
+  /** 監聽器執行時間過長 */
+  SlowListener: {
+    expr: "histogram_quantile(0.99, gravito_event_listener_execution_seconds) > 1.0",
+    for: "5m",
+    severity: "warning",
+    summary: "\u76E3\u807D\u5668\u57F7\u884C\u6642\u9593\u904E\u9577",
+    description: "P99 \u8017\u6642: {{ $value }}s\uFF0C\u76E3\u807D\u5668: {{ $labels.listener_name }}"
+  },
+  /** 吞吐量異常下降 */
+  ThroughputDrop: {
+    expr: "rate(gravito_event_throughput_total[5m]) < 100 and increase(gravito_event_throughput_total[1h]) > 0",
+    for: "2m",
+    severity: "critical",
+    summary: "\u4E8B\u4EF6\u541E\u5410\u91CF\u7570\u5E38\u4E0B\u964D",
+    description: "\u7576\u524D\u541E\u5410: {{ $value | humanize }} events/sec"
+  },
+  /** 熔斷器持續開啟 */
+  CircuitBreakerOpen: {
+    expr: 'gravito_event_circuit_breaker_state{event_name=~".+"} == 2',
+    for: "5m",
+    severity: "warning",
+    summary: "\u7194\u65B7\u5668\u6301\u7E8C\u958B\u555F",
+    description: "\u4E8B\u4EF6 {{ $labels.event_name }} \u7194\u65B7\u5668\u5DF2\u958B\u555F\u8D85\u904E 5 \u5206\u9418"
+  },
+  /** 熔斷器頻繁切換 */
+  CircuitBreakerFlapping: {
+    expr: "rate(gravito_event_circuit_breaker_transitions_total[5m]) > 10",
+    for: "2m",
+    severity: "critical",
+    summary: "\u7194\u65B7\u5668\u983B\u7E41\u5207\u63DB",
+    description: "\u4E8B\u4EF6 {{ $labels.event_name }} \u7194\u65B7\u5668\u72C0\u614B\u5207\u63DB\u904E\u65BC\u983B\u7E41\uFF0C\u5207\u63DB\u901F\u7387: {{ $value }}/sec"
+  },
+  /** 熔斷器故障率過高 */
+  CircuitBreakerHighFailureRate: {
+    expr: "rate(gravito_event_circuit_breaker_failures_total[5m]) > rate(gravito_event_circuit_breaker_successes_total[5m])",
+    for: "3m",
+    severity: "critical",
+    summary: "\u7194\u65B7\u5668\u6545\u969C\u7387\u8D85\u904E\u6210\u529F\u7387",
+    description: "\u4E8B\u4EF6 {{ $labels.event_name }} \u7684\u5931\u6557\u7387\u5DF2\u8D85\u904E\u6210\u529F\u7387"
+  }
+};
+export {
+  PROMETHEUS_ALERT_RULES,
+  PROMETHEUS_QUERIES,
+  getEventMetricsDefinition,
+  setupPrometheusMetrics
+};

package/dist/chunk-R5U7XKVJ.js

@@ -0,0 +1,16 @@
+var __defProp = Object.defineProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __require,
+  __export
+};

package/dist/{compat-C4Src6NN.d.cts → compat-CI8hiulX.d.cts}

@@ -312,6 +312,25 @@ interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
      * ```
      */
     readonly native: unknown;
+    /**
+     * Access the RequestScopeManager for this request
+     * Services resolved through this manager are scoped to the HTTP request lifetime.
+     */
+    requestScope(): any;
+    /**
+     * Resolve or create a request-scoped service
+     *
+     * @param key - Service key (string or symbol)
+     * @param factory - Factory function to create the service if not cached
+     * @returns The cached or newly created service instance
+     *
+     * @example
+     * ```typescript
+     * // Subsequent calls in the same request return the same instance
+     * const cache = ctx.scoped('product:cache', () => new RequestProductCache())
+     * ```
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }
 /**
  * Next function for middleware chain

package/dist/{compat-C4Src6NN.d.ts → compat-CI8hiulX.d.ts}

@@ -312,6 +312,25 @@ interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
      * ```
      */
     readonly native: unknown;
+    /**
+     * Access the RequestScopeManager for this request
+     * Services resolved through this manager are scoped to the HTTP request lifetime.
+     */
+    requestScope(): any;
+    /**
+     * Resolve or create a request-scoped service
+     *
+     * @param key - Service key (string or symbol)
+     * @param factory - Factory function to create the service if not cached
+     * @returns The cached or newly created service instance
+     *
+     * @example
+     * ```typescript
+     * // Subsequent calls in the same request return the same instance
+     * const cache = ctx.scoped('product:cache', () => new RequestProductCache())
+     * ```
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }
 /**
  * Next function for middleware chain

package/dist/compat.d.cts

@@ -1 +1 @@
-export { C as ContentfulStatusCode, e as Context, e as GravitoContext, c as GravitoErrorHandler, a as GravitoHandler, b as GravitoMiddleware, g as GravitoNext, d as GravitoNotFoundHandler, f as GravitoRequest, G as GravitoVariables, a as Handler, H as HttpMethod, b as MiddlewareHandler, g as Next, S as StatusCode, V as ValidationTarget, G as Variables } from './compat-C4Src6NN.cjs';
+export { C as ContentfulStatusCode, e as Context, e as GravitoContext, c as GravitoErrorHandler, a as GravitoHandler, b as GravitoMiddleware, g as GravitoNext, d as GravitoNotFoundHandler, f as GravitoRequest, G as GravitoVariables, a as Handler, H as HttpMethod, b as MiddlewareHandler, g as Next, S as StatusCode, V as ValidationTarget, G as Variables } from './compat-CI8hiulX.cjs';

package/dist/compat.d.ts

@@ -1 +1 @@
-export { C as ContentfulStatusCode, e as Context, e as GravitoContext, c as GravitoErrorHandler, a as GravitoHandler, b as GravitoMiddleware, g as GravitoNext, d as GravitoNotFoundHandler, f as GravitoRequest, G as GravitoVariables, a as Handler, H as HttpMethod, b as MiddlewareHandler, g as Next, S as StatusCode, V as ValidationTarget, G as Variables } from './compat-C4Src6NN.js';
+export { C as ContentfulStatusCode, e as Context, e as GravitoContext, c as GravitoErrorHandler, a as GravitoHandler, b as GravitoMiddleware, g as GravitoNext, d as GravitoNotFoundHandler, f as GravitoRequest, G as GravitoVariables, a as Handler, H as HttpMethod, b as MiddlewareHandler, g as Next, S as StatusCode, V as ValidationTarget, G as Variables } from './compat-CI8hiulX.js';