@objectstack/runtime 4.2.0 → 5.1.0

package/dist/index.d.cts

@@ -5,6 +5,8 @@ import { z } from 'zod';
 import * as Contracts from '@objectstack/spec/contracts';
 import { ISeedLoaderService, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
 import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Dataset, SeedLoaderConfigInput, ExpressionBody, ScriptBody, HookBody, Hook } from '@objectstack/spec/data';
+import { MetricsRegistry, ErrorReporter } from '@objectstack/observability';
+export { CapturedError, ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, MetricSample, MetricsRegistry, NoopErrorReporter, NoopMetricsRegistry, RUNTIME_METRICS } from '@objectstack/observability';
 import { ExecutionContext } from '@objectstack/spec/kernel';
 import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
 import { ProjectArtifact } from '@objectstack/spec/cloud';
@@ -490,142 +492,6 @@ declare function parseTraceparent(value: unknown): TraceContext | undefined;
  */
 declare function formatTraceparent(ctx: TraceContext): string;
 
-/**
- * Metrics registry contract.
- *
- * The runtime emits metrics via this interface so the host application
- * can plug in whatever metrics backend it wants (Prometheus via
- * `prom-client`, OTel via `@opentelemetry/api-metrics`, StatsD,
- * CloudWatch, etc.) without the framework taking a hard dep on any of
- * them.
- *
- * Naming follows Prometheus conventions:
- *   - snake_case names
- *   - unit suffix (`_ms`, `_seconds`, `_bytes`, `_total` for counters)
- *
- * Labels are arbitrary string maps; backends should map them to their
- * native label/tag concept. Keep cardinality low — never label by raw
- * url path or user id.
- *
- * All methods are fire-and-forget; implementations MUST NOT throw on
- * the hot path. Use {@link NoopMetricsRegistry} when metrics are
- * disabled.
- */
-interface MetricsRegistry {
-    /** Monotonic counter. `value` defaults to 1. */
-    counter(name: string, labels?: Record<string, string>, value?: number): void;
-    /** Histogram / timing in arbitrary units (typically ms). */
-    histogram(name: string, value: number, labels?: Record<string, string>): void;
-    /** Point-in-time gauge. */
-    gauge(name: string, value: number, labels?: Record<string, string>): void;
-}
-/**
- * No-op metrics registry — the default. Discards every observation.
- * Production deployments should swap this for a real registry; tests
- * can use {@link InMemoryMetricsRegistry} to assert emissions.
- */
-declare class NoopMetricsRegistry implements MetricsRegistry {
-    counter(): void;
-    histogram(): void;
-    gauge(): void;
-}
-/** Recorded metric sample (in-memory registry). */
-interface MetricSample {
-    name: string;
-    kind: 'counter' | 'histogram' | 'gauge';
-    value: number;
-    labels: Record<string, string>;
-    /** Wall-clock timestamp; useful for ordering assertions in tests. */
-    at: number;
-}
-/**
- * In-memory registry used for tests and local inspection. Stores
- * every observation in insertion order; query via the helpers below
- * or read {@link samples} directly.
- *
- * Not intended for production — unbounded growth.
- */
-declare class InMemoryMetricsRegistry implements MetricsRegistry {
-    readonly samples: MetricSample[];
-    counter(name: string, labels?: Record<string, string>, value?: number): void;
-    histogram(name: string, value: number, labels?: Record<string, string>): void;
-    gauge(name: string, value: number, labels?: Record<string, string>): void;
-    /**
-     * Sum of all counter increments matching `name` (and optionally a
-     * label subset). Useful in tests: `metrics.totalCounter('http_requests_total', { status: '500' })`.
-     */
-    totalCounter(name: string, labelMatch?: Record<string, string>): number;
-    /**
-     * All histogram observations matching `name` (and optionally a
-     * label subset), as raw values.
-     */
-    histogramValues(name: string, labelMatch?: Record<string, string>): number[];
-    /** Clear all recorded samples. */
-    reset(): void;
-}
-/**
- * Canonical metric names emitted by the runtime. Hosts may rely on
- * these (e.g., to wire alerts) so they are listed here for reference
- * rather than being string literals scattered through call sites.
- */
-declare const RUNTIME_METRICS: {
-    /** Counter, labels: method, route, status. */
-    readonly httpRequestsTotal: "http_requests_total";
-    /** Histogram (ms), labels: method, route. */
-    readonly httpRequestDurationMs: "http_request_duration_ms";
-    /** Counter, labels: method, route. Incremented when an in-flight handler throws (after the response is sent). */
-    readonly httpRequestErrorsTotal: "http_request_errors_total";
-};
-
-/**
- * Error reporter contract.
- *
- * Production deployments wire this to Sentry, Datadog APM, Rollbar,
- * etc. The runtime calls {@link ErrorReporter.captureException} when a
- * route handler results in a 5xx response so the host's APM gets the
- * stack trace without each plugin/route needing to import the SDK.
- *
- * Implementations MUST NOT throw — error reporting failures should be
- * swallowed (or at most logged) so the original error reaches the
- * client unmolested.
- *
- * 4xx responses are intentionally NOT captured here. Client errors
- * (validation failures, auth, not-found) flood APM systems with noise
- * and obscure real bugs. If a deployment wants to track them, do it
- * via the metrics counter (`http_requests_total{status="4xx"}`),
- * not error reporting.
- */
-interface ErrorReporter {
-    /**
-     * Capture a thrown error with optional context. Context typically
-     * includes `requestId`, `method`, `route`, `userId`, `orgId`.
-     *
-     * The reporter is responsible for redacting sensitive fields from
-     * `context` (the runtime does not know what is sensitive in the
-     * caller's deployment).
-     */
-    captureException(error: unknown, context?: Record<string, unknown>): void;
-}
-/** No-op reporter — the default. */
-declare class NoopErrorReporter implements ErrorReporter {
-    captureException(): void;
-}
-/** Recorded report (in-memory reporter). */
-interface CapturedError {
-    error: unknown;
-    context: Record<string, unknown>;
-    at: number;
-}
-/**
- * In-memory reporter used in tests to assert that error capture was
- * (or was not) invoked for a given request.
- */
-declare class InMemoryErrorReporter implements ErrorReporter {
-    readonly captured: CapturedError[];
-    captureException(error: unknown, context?: Record<string, unknown>): void;
-    reset(): void;
-}
-
 interface DispatcherPluginConfig {
     /**
      * API path prefix for all endpoints.
@@ -2361,4 +2227,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, type CapturedError, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, type ErrorReporter, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, InMemoryErrorReporter, InMemoryMetricsRegistry, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, type MetricSample, type MetricsRegistry, MiddlewareManager, NoopErrorReporter, NoopMetricsRegistry, type ObjectOSStackConfig, type ObjectOSStackResult, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, RUNTIME_METRICS, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveDefaultArtifactPath, resolveRequestId, seedPlatformSsoClient };
+export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveDefaultArtifactPath, resolveRequestId, seedPlatformSsoClient };

package/dist/index.d.ts

@@ -5,6 +5,8 @@ import { z } from 'zod';
 import * as Contracts from '@objectstack/spec/contracts';
 import { ISeedLoaderService, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
 import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Dataset, SeedLoaderConfigInput, ExpressionBody, ScriptBody, HookBody, Hook } from '@objectstack/spec/data';
+import { MetricsRegistry, ErrorReporter } from '@objectstack/observability';
+export { CapturedError, ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, MetricSample, MetricsRegistry, NoopErrorReporter, NoopMetricsRegistry, RUNTIME_METRICS } from '@objectstack/observability';
 import { ExecutionContext } from '@objectstack/spec/kernel';
 import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
 import { ProjectArtifact } from '@objectstack/spec/cloud';
@@ -490,142 +492,6 @@ declare function parseTraceparent(value: unknown): TraceContext | undefined;
  */
 declare function formatTraceparent(ctx: TraceContext): string;
 
-/**
- * Metrics registry contract.
- *
- * The runtime emits metrics via this interface so the host application
- * can plug in whatever metrics backend it wants (Prometheus via
- * `prom-client`, OTel via `@opentelemetry/api-metrics`, StatsD,
- * CloudWatch, etc.) without the framework taking a hard dep on any of
- * them.
- *
- * Naming follows Prometheus conventions:
- *   - snake_case names
- *   - unit suffix (`_ms`, `_seconds`, `_bytes`, `_total` for counters)
- *
- * Labels are arbitrary string maps; backends should map them to their
- * native label/tag concept. Keep cardinality low — never label by raw
- * url path or user id.
- *
- * All methods are fire-and-forget; implementations MUST NOT throw on
- * the hot path. Use {@link NoopMetricsRegistry} when metrics are
- * disabled.
- */
-interface MetricsRegistry {
-    /** Monotonic counter. `value` defaults to 1. */
-    counter(name: string, labels?: Record<string, string>, value?: number): void;
-    /** Histogram / timing in arbitrary units (typically ms). */
-    histogram(name: string, value: number, labels?: Record<string, string>): void;
-    /** Point-in-time gauge. */
-    gauge(name: string, value: number, labels?: Record<string, string>): void;
-}
-/**
- * No-op metrics registry — the default. Discards every observation.
- * Production deployments should swap this for a real registry; tests
- * can use {@link InMemoryMetricsRegistry} to assert emissions.
- */
-declare class NoopMetricsRegistry implements MetricsRegistry {
-    counter(): void;
-    histogram(): void;
-    gauge(): void;
-}
-/** Recorded metric sample (in-memory registry). */
-interface MetricSample {
-    name: string;
-    kind: 'counter' | 'histogram' | 'gauge';
-    value: number;
-    labels: Record<string, string>;
-    /** Wall-clock timestamp; useful for ordering assertions in tests. */
-    at: number;
-}
-/**
- * In-memory registry used for tests and local inspection. Stores
- * every observation in insertion order; query via the helpers below
- * or read {@link samples} directly.
- *
- * Not intended for production — unbounded growth.
- */
-declare class InMemoryMetricsRegistry implements MetricsRegistry {
-    readonly samples: MetricSample[];
-    counter(name: string, labels?: Record<string, string>, value?: number): void;
-    histogram(name: string, value: number, labels?: Record<string, string>): void;
-    gauge(name: string, value: number, labels?: Record<string, string>): void;
-    /**
-     * Sum of all counter increments matching `name` (and optionally a
-     * label subset). Useful in tests: `metrics.totalCounter('http_requests_total', { status: '500' })`.
-     */
-    totalCounter(name: string, labelMatch?: Record<string, string>): number;
-    /**
-     * All histogram observations matching `name` (and optionally a
-     * label subset), as raw values.
-     */
-    histogramValues(name: string, labelMatch?: Record<string, string>): number[];
-    /** Clear all recorded samples. */
-    reset(): void;
-}
-/**
- * Canonical metric names emitted by the runtime. Hosts may rely on
- * these (e.g., to wire alerts) so they are listed here for reference
- * rather than being string literals scattered through call sites.
- */
-declare const RUNTIME_METRICS: {
-    /** Counter, labels: method, route, status. */
-    readonly httpRequestsTotal: "http_requests_total";
-    /** Histogram (ms), labels: method, route. */
-    readonly httpRequestDurationMs: "http_request_duration_ms";
-    /** Counter, labels: method, route. Incremented when an in-flight handler throws (after the response is sent). */
-    readonly httpRequestErrorsTotal: "http_request_errors_total";
-};
-
-/**
- * Error reporter contract.
- *
- * Production deployments wire this to Sentry, Datadog APM, Rollbar,
- * etc. The runtime calls {@link ErrorReporter.captureException} when a
- * route handler results in a 5xx response so the host's APM gets the
- * stack trace without each plugin/route needing to import the SDK.
- *
- * Implementations MUST NOT throw — error reporting failures should be
- * swallowed (or at most logged) so the original error reaches the
- * client unmolested.
- *
- * 4xx responses are intentionally NOT captured here. Client errors
- * (validation failures, auth, not-found) flood APM systems with noise
- * and obscure real bugs. If a deployment wants to track them, do it
- * via the metrics counter (`http_requests_total{status="4xx"}`),
- * not error reporting.
- */
-interface ErrorReporter {
-    /**
-     * Capture a thrown error with optional context. Context typically
-     * includes `requestId`, `method`, `route`, `userId`, `orgId`.
-     *
-     * The reporter is responsible for redacting sensitive fields from
-     * `context` (the runtime does not know what is sensitive in the
-     * caller's deployment).
-     */
-    captureException(error: unknown, context?: Record<string, unknown>): void;
-}
-/** No-op reporter — the default. */
-declare class NoopErrorReporter implements ErrorReporter {
-    captureException(): void;
-}
-/** Recorded report (in-memory reporter). */
-interface CapturedError {
-    error: unknown;
-    context: Record<string, unknown>;
-    at: number;
-}
-/**
- * In-memory reporter used in tests to assert that error capture was
- * (or was not) invoked for a given request.
- */
-declare class InMemoryErrorReporter implements ErrorReporter {
-    readonly captured: CapturedError[];
-    captureException(error: unknown, context?: Record<string, unknown>): void;
-    reset(): void;
-}
-
 interface DispatcherPluginConfig {
     /**
      * API path prefix for all endpoints.
@@ -2361,4 +2227,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, type CapturedError, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, type ErrorReporter, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, InMemoryErrorReporter, InMemoryMetricsRegistry, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, type MetricSample, type MetricsRegistry, MiddlewareManager, NoopErrorReporter, NoopMetricsRegistry, type ObjectOSStackConfig, type ObjectOSStackResult, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, RUNTIME_METRICS, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveDefaultArtifactPath, resolveRequestId, seedPlatformSsoClient };
+export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveDefaultArtifactPath, resolveRequestId, seedPlatformSsoClient };