@avtechno/sfr 1.0.18 → 2.0.1

package/dist/sfr-pipeline.mjs

@@ -3,7 +3,13 @@ import fs from "fs/promises";
 import { template } from "./util.mjs";
 import { BroadcastMQ, TargetedMQ } from "./mq.mjs";
 import j2s from "joi-to-swagger";
-import { logger } from "./logger.mjs";
+import rateLimit from "express-rate-limit";
+// Observability imports
+import { init_observability, is_observability_enabled } from "./observability/index.mjs";
+import { sfr_logger as logger } from "./observability/logger.mjs";
+import { sfr_rest_telemetry } from "./observability/middleware/rest.mjs";
+import { instrument_socket_io, wrap_ws_handler } from "./observability/middleware/ws.mjs";
+import { wrap_mq_handler, record_mq_reject } from "./observability/middleware/mq.mjs";
 const CWD = process.cwd();
 const PATTERNS = ["Point-to-Point", "Request-Reply", "Fanout", "Direct", "Topic"];
 const TARGETED_PATTERN = ["Point-to-Point", "Request-Reply"];
@@ -25,11 +31,44 @@ export class SFRPipeline {
             handlers: {},
             controllers: {}
         },
+        ws: {
+            handlers: {},
+            controllers: {}
+        },
         mq: {
             handlers: {},
             controllers: {}
         },
     };
+    /* Authentication middleware configuration */
+    static auth_config = {};
+    /* Rate limit configuration */
+    static rate_limit_config = {};
+    /* Observability configuration */
+    static observability_options = {};
+    /**
+     * Sets the authentication middleware for protected routes.
+     * @param middleware - The authentication middleware function
+     */
+    static set_auth_middleware(middleware) {
+        SFRPipeline.auth_config.middleware = middleware;
+    }
+    /**
+     * Configures global rate limiting options for all routes.
+     * Can be overridden per-route using cfg.rate_limit in SFR files.
+     * @param config - Rate limit configuration options
+     */
+    static set_rate_limit_config(config) {
+        SFRPipeline.rate_limit_config = config;
+    }
+    /**
+     * Configures observability options for tracing, metrics, and logging.
+     * Must be called before SFR initialization to take effect.
+     * @param options - Observability configuration options
+     */
+    static set_observability_options(options) {
+        SFRPipeline.observability_options = options;
+    }
     constructor(cfg, oas_cfg, comms) {
         this.cfg = cfg;
         this.oas_cfg = oas_cfg;
@@ -37,6 +76,18 @@ export class SFRPipeline {
     }
     async init(base_url) {
         this.base_url = base_url;
+        // Initialize observability with service config from oas_cfg
+        if (SFRPipeline.observability_options.enabled !== false) {
+            init_observability(this.oas_cfg, SFRPipeline.observability_options);
+        }
+        // Add REST telemetry middleware if enabled
+        if (this.comms["REST"] && is_observability_enabled()) {
+            this.comms["REST"].use(sfr_rest_telemetry());
+        }
+        // Instrument Socket.IO if enabled
+        if (this.comms["WS"] && is_observability_enabled()) {
+            instrument_socket_io(this.comms["WS"]);
+        }
         if (this.comms["MQ"]) {
             //Create channels for each type of Communication Pattern
             const channels = await Promise.all(PATTERNS.map(async (v) => {
@@ -52,6 +103,17 @@ export class SFRPipeline {
                 ...SFRPipeline.injections.mq.handlers,
                 mq: this.pattern_channels
             };
+            SFRPipeline.injections.ws.handlers = {
+                ...SFRPipeline.injections.ws.handlers,
+                mq: this.pattern_channels
+            };
+        }
+        // Inject Socket.IO server into WS handlers
+        if (this.comms["WS"]) {
+            SFRPipeline.injections.ws.handlers = {
+                ...SFRPipeline.injections.ws.handlers,
+                io: this.comms["WS"]
+            };
         }
         //Declarations for each protocol in key/value pairs.
         let protocols = await this.file_parsing();
@@ -110,6 +172,82 @@ export class SFRPipeline {
             }
         });
     }
+    /**
+     * Generates OpenAPI multipart/form-data schema for Multer validators.
+     * Since Multer middleware functions can't be easily inspected at runtime,
+     * this generates a generic file upload schema.
+     */
+    generate_multer_openapi_schema(validator) {
+        // Multer middleware is a function, so we generate a generic multipart schema
+        // In the future, this could be enhanced to parse Multer configuration
+        return {
+            content: {
+                "multipart/form-data": {
+                    schema: {
+                        type: "object",
+                        properties: {
+                            file: {
+                                type: "string",
+                                format: "binary",
+                                description: "File to upload"
+                            }
+                        }
+                    },
+                    encoding: {
+                        file: {
+                            contentType: "*/*"
+                        }
+                    }
+                }
+            }
+        };
+    }
+    /**
+     * Gets rate limit configuration for a route, merging global defaults with route-specific config.
+     */
+    get_rate_limit_config_for_route(cfg) {
+        if (cfg?.rate_limit === false) {
+            return null; // Explicitly disabled
+        }
+        const global_default = SFRPipeline.rate_limit_config.default;
+        const route_config = cfg?.rate_limit;
+        if (!global_default && !route_config) {
+            return null; // No rate limiting configured
+        }
+        return {
+            max: 100,
+            windowMs: 60000,
+            ...global_default,
+            ...route_config
+        };
+    }
+    /**
+     * Creates a rate limiter middleware based on configuration.
+     * Merges route-specific config with global defaults.
+     */
+    create_rate_limiter(route_config) {
+        // If explicitly disabled, return null
+        if (route_config === false) {
+            return null;
+        }
+        // Merge route config with global default
+        const global_default = SFRPipeline.rate_limit_config.default;
+        const config = {
+            max: 100,
+            windowMs: 60000,
+            message: "Too many requests, please try again later.",
+            statusCode: 429,
+            standardHeaders: true,
+            legacyHeaders: false,
+            ...global_default,
+            ...route_config
+        };
+        // Only create rate limiter if max is greater than 0
+        if (config.max && config.max > 0) {
+            return rateLimit(config);
+        }
+        return null;
+    }
     /* Fn Binding */
     async bind_rest_fns(declaration) {
         const comms = this.comms["REST"];
@@ -137,14 +275,26 @@ export class SFRPipeline {
                     const dir = `${base_dir}/${namespace}/${name}`;
                     const validator = validators[name];
                     const validator_type = typeof validator !== "function" ? "joi" : "multer";
+                    // Apply rate limiting middleware if configured
+                    const rate_limiter = this.create_rate_limiter(cfg.rate_limit);
+                    if (rate_limiter) {
+                        comms[method.toLowerCase()](dir, rate_limiter);
+                    }
                     /* bind validators */
                     switch (validator_type) {
                         case "joi":
                             {
-                                comms[method.toLowerCase()](dir, (req, res, next) => {
+                                comms[method.toLowerCase()](dir, async (req, res, next) => {
                                     let error = true;
-                                    if (is_public) {
-                                        //if(!req.session.user)return res.status(401).json({error : "Session not found."});
+                                    // Authentication check for protected routes
+                                    if (!is_public && SFRPipeline.auth_config.middleware) {
+                                        const auth_result = await SFRPipeline.auth_config.middleware(req, res);
+                                        if (auth_result === false) {
+                                            return res.status(401).json({ error: "Unauthorized" });
+                                        }
+                                        if (typeof auth_result === "object" && auth_result.error) {
+                                            return res.status(auth_result.status || 401).json({ error: auth_result.error });
+                                        }
                                     }
                                     const validator_keys = Object.keys(validator);
                                     if (validator_keys.length) {
@@ -177,6 +327,96 @@ export class SFRPipeline {
         });
     }
     async bind_ws_fns(declaration) {
+        const io = this.comms["WS"];
+        if (!io)
+            throw new Error(`FN Binding failed: \nWS protocol lacks its associated SFRProtocols`);
+        Object.entries(declaration).forEach(([namespace, module]) => {
+            const { cfg, validators, handlers } = module.content;
+            // Determine the Socket.IO namespace to use
+            // Priority: cfg.namespace -> cfg.base_dir -> "/"
+            let ws_namespace = "/";
+            if (cfg.namespace)
+                ws_namespace = cfg.namespace.startsWith("/") ? cfg.namespace : `/${cfg.namespace}`;
+            else if (cfg.base_dir)
+                ws_namespace = cfg.base_dir.startsWith("/") ? cfg.base_dir : `/${cfg.base_dir}`;
+            logger.info(`[SFR WS ${module.name}] namespace: ${ws_namespace}`);
+            // Get or create the namespace
+            const nsp = io.of(ws_namespace);
+            // Handle connections to this namespace
+            nsp.on("connection", (socket) => {
+                logger.info(`[SFR WS] Client connected to ${ws_namespace}: ${socket.id}`);
+                // Register event handlers for this connection
+                Object.entries(handlers).forEach(([event, handler]) => {
+                    // Skip if no matching validator
+                    const validator = validators[event];
+                    if (!validator)
+                        return;
+                    socket.on(event, async (data, ack) => {
+                        // Validate incoming data if validator is a Joi schema (not Multer)
+                        const validator_type = typeof validator !== "function" ? "joi" : "custom";
+                        if (validator_type === "joi") {
+                            const validator_keys = Object.keys(validator);
+                            if (validator_keys.length) {
+                                const error = template(validator, data || {});
+                                if (error) {
+                                    // Send validation error back via acknowledgement or emit
+                                    if (ack) {
+                                        ack({ error });
+                                    }
+                                    else {
+                                        socket.emit(`${event}:error`, { error });
+                                    }
+                                    return;
+                                }
+                            }
+                        }
+                        // Build context for handler
+                        const ctx = {
+                            io,
+                            socket,
+                            data: data || {},
+                            ack
+                        };
+                        // Create the handler execution function
+                        const execute_handler = async () => {
+                            await handler.fn.call({
+                                ...module.content.controllers,
+                                ...SFRPipeline.injections.ws.handlers,
+                                io,
+                                socket
+                            }, ctx);
+                        };
+                        try {
+                            // Wrap with telemetry if observability is enabled
+                            if (is_observability_enabled()) {
+                                const instrumented = wrap_ws_handler(ws_namespace, event, execute_handler);
+                                await instrumented();
+                            }
+                            else {
+                                await execute_handler();
+                            }
+                        }
+                        catch (err) {
+                            logger.error(`[SFR WS] Error in handler ${event}`, {
+                                error: err instanceof Error ? err.message : String(err),
+                                event,
+                                namespace: ws_namespace
+                            });
+                            if (ack) {
+                                ack({ error: err instanceof Error ? err.message : "Unknown error" });
+                            }
+                            else {
+                                socket.emit(`${event}:error`, { error: err instanceof Error ? err.message : "Unknown error" });
+                            }
+                        }
+                    });
+                    this.mount_data.ws++;
+                });
+                socket.on("disconnect", (reason) => {
+                    logger.info(`[SFR WS] Client disconnected from ${ws_namespace}: ${socket.id} (${reason})`);
+                });
+            });
+        });
     }
     async bind_mq_fns(declaration) {
         const comms = this.comms["MQ"];
@@ -202,11 +442,16 @@ export class SFRPipeline {
                     const dir = `${base_dir}${namespace}/${name}`;
                     const validator = validators[name];
                     //const validator_type = typeof validator !== "function" ? "joi" : "multer"; // TODO: Dynamically update parameter content based on validator type.
-                    let validator_fn = function (msg) {
+                    // Create the base handler with validation
+                    const base_handler = function (msg) {
                         const validator_keys = Object.keys(validator);
                         if (validator_keys.length) {
                             const error = template(validator, msg.content);
                             if (error) {
+                                // Record rejection metrics
+                                if (is_observability_enabled()) {
+                                    record_mq_reject(dir, pattern, false);
+                                }
                                 if (mq instanceof TargetedMQ) {
                                     if (error) {
                                         switch (pattern) {
@@ -224,6 +469,10 @@ export class SFRPipeline {
                         }
                         handler.fn(msg);
                     };
+                    // Wrap with telemetry if observability is enabled
+                    const validator_fn = is_observability_enabled()
+                        ? wrap_mq_handler(dir, pattern, base_handler)
+                        : base_handler;
                     /* bind validators */
                     if (mq instanceof TargetedMQ) {
                         mq.consume(dir, {
@@ -248,8 +497,8 @@ export class SFRPipeline {
         const documents = Object.entries(protocols).map(([protocol, declaration]) => {
             switch (protocol) {
                 case "REST": return [protocol, this.generate_open_api_document(declaration)];
-                case "WS": return [protocol, this.generate_async_api_document(declaration)];
-                case "MQ": return [protocol, this.generate_async_api_document(declaration)];
+                case "WS": return [protocol, this.generate_ws_async_api_document(declaration)];
+                case "MQ": return [protocol, this.generate_mq_async_api_document(declaration)];
                 default: throw new Error(`Failed to generate SFR Spec: ${protocol} protocol is unknown.`);
             }
         });
@@ -290,29 +539,97 @@ export class SFRPipeline {
                     if (body.tags && Array.isArray(body.tags))
                         default_tags.push(...body.tags);
                     const operation_id = `${base_dir}${namespace}/${endpoint}`;
+                    const is_public = Boolean(cfg.public);
+                    const rate_limit_config = this.get_rate_limit_config_for_route(cfg);
                     const document = {
                         operationId: `${method.toUpperCase()}:${operation_id}`,
                         summary: body.summary || "",
                         description: body.description || "",
                         tags: default_tags,
-                        public: Boolean(cfg.public),
+                        public: is_public,
                         responses: {
                             "200": {
                                 description: "Successful operation",
                                 content: { "application/json": { schema: { type: "object" } } }
                             },
                             "400": {
-                                description: "An error has occured",
-                                content: { "application/json": { schema: { type: "object" } } }
+                                description: "Bad request - validation error",
+                                content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } }
                             }
                         }
                     };
+                    // Add authentication-related responses for protected routes
+                    if (!is_public) {
+                        document.responses["401"] = {
+                            description: "Unauthorized - authentication required",
+                            content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } }
+                        };
+                        document.responses["403"] = {
+                            description: "Forbidden - insufficient permissions",
+                            content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } }
+                        };
+                    }
+                    // Add rate limiting response and headers if rate limiting is configured
+                    if (rate_limit_config && rate_limit_config.max && rate_limit_config.max > 0) {
+                        document.responses["429"] = {
+                            description: "Too many requests - rate limit exceeded",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            error: { type: "string" },
+                                            message: { type: "string" }
+                                        }
+                                    }
+                                }
+                            },
+                            headers: {}
+                        };
+                        // Add rate limit headers if standardHeaders is enabled
+                        if (rate_limit_config.standardHeaders !== false) {
+                            document.responses["429"].headers["RateLimit-Limit"] = {
+                                description: "The maximum number of requests allowed in the current window",
+                                schema: { type: "integer", example: rate_limit_config.max }
+                            };
+                            document.responses["429"].headers["RateLimit-Remaining"] = {
+                                description: "The number of requests remaining in the current window",
+                                schema: { type: "integer" }
+                            };
+                            document.responses["429"].headers["RateLimit-Reset"] = {
+                                description: "The time at which the current rate limit window resets (Unix timestamp)",
+                                schema: { type: "integer" }
+                            };
+                        }
+                        // Add legacy headers if enabled
+                        if (rate_limit_config.legacyHeaders) {
+                            document.responses["429"].headers["X-RateLimit-Limit"] = {
+                                description: "The maximum number of requests allowed in the current window (legacy)",
+                                schema: { type: "integer", example: rate_limit_config.max }
+                            };
+                            document.responses["429"].headers["X-RateLimit-Remaining"] = {
+                                description: "The number of requests remaining in the current window (legacy)",
+                                schema: { type: "integer" }
+                            };
+                            document.responses["429"].headers["X-RateLimit-Reset"] = {
+                                description: "The time at which the current rate limit window resets (legacy)",
+                                schema: { type: "integer" }
+                            };
+                        }
+                        // Add rate limit metadata to operation description
+                        if (rate_limit_config.windowMs) {
+                            const window_seconds = Math.floor(rate_limit_config.windowMs / 1000);
+                            const rate_limit_note = `\n\n**Rate Limit:** ${rate_limit_config.max} requests per ${window_seconds} second${window_seconds !== 1 ? 's' : ''}`;
+                            document.description = (document.description || "") + rate_limit_note;
+                        }
+                    }
                     //Insert either a parameter or a requestBody according to the method type
                     if (validator_type === "joi") {
                         document[method === "GET" ? "parameters" : "requestBody"] = j2s(validator).swagger;
                     }
-                    //Haven't found a library for converting multer validators to swagger doc
+                    // Convert Multer validators to multipart/form-data OpenAPI schema
                     if (validator_type === "multer") {
+                        document.requestBody = this.generate_multer_openapi_schema(validator);
                     }
                     //Create path if it does not exist.
                     if (!spec.paths[operation_id])
@@ -327,8 +644,91 @@ export class SFRPipeline {
         spec.info.meta = Object.fromEntries(Object.entries(spec.info.meta).map(([k, v]) => [`x-${k}`, v]));
         return spec;
     }
+    // Method to generate an AsyncAPI document from a WSNamespaceDeclaration
+    generate_ws_async_api_document(declaration) {
+        const spec = {
+            asyncapi: '3.0.0',
+            info: Object.assign({}, this.oas_cfg),
+            servers: {
+                websocket: {
+                    host: `localhost:${this.oas_cfg.meta?.port || 3000}`,
+                    protocol: 'ws',
+                    description: 'WebSocket server'
+                }
+            },
+            channels: {},
+            operations: {},
+            components: {
+                messages: {},
+            },
+        };
+        // Conform to AsyncAPI standards by appending "x-property" on each field under "meta"
+        if (spec.info.meta) {
+            spec.info.meta = Object.fromEntries(Object.entries(spec.info.meta).map(([k, v]) => [`x-${k}`, v]));
+        }
+        Object.entries(declaration).forEach(([namespace, module]) => {
+            const { cfg, validators, handlers } = module.content;
+            // Determine namespace path
+            let ws_namespace = "/";
+            if (cfg.namespace)
+                ws_namespace = cfg.namespace.startsWith("/") ? cfg.namespace : `/${cfg.namespace}`;
+            else if (cfg.base_dir)
+                ws_namespace = cfg.base_dir.startsWith("/") ? cfg.base_dir : `/${cfg.base_dir}`;
+            // Loop over all event handlers
+            Object.entries(handlers).forEach(([event, handler]) => {
+                const validator = validators[event];
+                if (!validator)
+                    return;
+                const validator_type = typeof validator !== "function" ? "joi" : "custom";
+                const channel_id = `${ws_namespace === "/" ? "" : ws_namespace}/${event}`.replace(/^\/+/, "").replace(/\//g, "-") || event;
+                // Default tags for service classification
+                const default_tags = [
+                    { name: `sfr-namespace:${namespace}` },
+                    { name: `sfr-service:${this.oas_cfg.title || "unspecified"}` }
+                ];
+                if (handler.tags && Array.isArray(handler.tags)) {
+                    default_tags.push(...handler.tags.map(t => ({ name: t })));
+                }
+                const channel_document = {
+                    address: ws_namespace === "/" ? `/${event}` : `${ws_namespace}/${event}`,
+                    messages: {}
+                };
+                const operation_document = {
+                    action: "receive",
+                    summary: handler.summary || `Handle ${event} event`,
+                    description: handler.description || "",
+                    channel: { $ref: `#/channels/${channel_id}` },
+                    tags: default_tags
+                };
+                // Generate message schema from Joi validator
+                if (validator_type === "joi") {
+                    const message_id = `${channel_id}-message`;
+                    channel_document.messages[message_id] = {
+                        $ref: `#/components/messages/${message_id}`
+                    };
+                    spec.components.messages[message_id] = {
+                        name: message_id,
+                        contentType: "application/json",
+                        payload: j2s(validator).swagger
+                    };
+                }
+                spec.channels[channel_id] = channel_document;
+                spec.operations[`${channel_id}-receive`] = operation_document;
+                // Add send operation for events that can emit responses
+                const send_operation = {
+                    action: "send",
+                    summary: `Send ${event} response`,
+                    description: `Response for ${event} event`,
+                    channel: { $ref: `#/channels/${channel_id}` },
+                    tags: default_tags
+                };
+                spec.operations[`${channel_id}-send`] = send_operation;
+            });
+        });
+        return spec;
+    }
     // Method to generate an AsyncAPI document from an MQNamespaceDeclaration
-    generate_async_api_document(declaration) {
+    generate_mq_async_api_document(declaration) {
         // This will hold the final AsyncAPI Document.
         const spec = {
             asyncapi: '3.0.0',

package/dist/templates.mjs

@@ -23,7 +23,14 @@ export function WS(struct) {
     const controllers = struct.controllers || {};
     const handlers = struct.handlers || {};
     const cfg = struct.cfg || {};
-    //Dependency injection happens here...npm
+    // Bind controller injections to each controller
+    Object.entries(controllers).map(([k, v]) => controllers[k] = v.bind({ ...SFRPipeline.injections.ws.controllers }));
+    // Bind handler injections and SFR controllers into each handler
+    Object.entries(handlers).forEach(([event, handler]) => {
+        /* @ts-ignore */
+        handlers[event] = { ...handler, fn: handler.fn.bind({ ...controllers, ...SFRPipeline.injections.ws.handlers }) };
+    });
+    /* @ts-ignore */
     return { validators, controllers, handlers, cfg };
 }
 export function MQ(struct) {

package/dist/types/index.d.mts

@@ -4,4 +4,11 @@ import { MQLib, BroadcastMQ, TargetedMQ } from "./mq.mjs";
 declare const _default: (cfg: ParserCFG, oas_cfg: OASConfig, connectors: SFRProtocols, base_url?: string) => Promise<ServiceManifest>;
 export default _default;
 declare function inject(injections: InjectedFacilities): void;
-export { REST, WS, MQ, MQLib, BroadcastMQ, TargetedMQ, inject };
+declare const set_auth_middleware: any;
+declare const set_rate_limit_config: any;
+declare const set_observability_options: any;
+export { init_observability, shutdown_observability, is_observability_enabled, type ObservabilityOptions } from "./observability/index.mjs";
+export { get_tracer, with_span, with_span_sync, get_trace_context, inject_trace_context, extract_trace_context, add_span_attributes, add_span_event, set_span_error, SpanKind } from "./observability/tracer.mjs";
+export { get_sfr_metrics, get_meter, record_rest_request, record_ws_event, record_mq_message, type SFRMetrics } from "./observability/metrics.mjs";
+export { sfr_logger, create_child_logger, init_logger, type LoggerConfig } from "./observability/logger.mjs";
+export { REST, WS, MQ, MQLib, BroadcastMQ, TargetedMQ, inject, set_auth_middleware, set_rate_limit_config, set_observability_options };

package/dist/types/logger.d.mts

@@ -1,3 +1,9 @@
-import winston from 'winston';
-declare const logger: winston.Logger;
-export { logger };
+/**
+ * SFR Logger Module (Backward Compatibility)
+ *
+ * This module re-exports the new observability logger for backward compatibility.
+ * New code should import from "./observability/logger.mjs" directly.
+ *
+ * @deprecated Use imports from "./observability/logger.mjs" instead
+ */
+export { sfr_logger as logger, sfr_logger, create_child_logger, init_logger, get_logger, type LoggerConfig } from "./observability/logger.mjs";

package/dist/types/mq.d.mts

@@ -5,6 +5,7 @@ import { ChannelModel, Options, Channel, ConsumeMessage } from "amqplib";
 export declare class MQLib {
     private connection?;
     private channel?;
+    private is_closing;
     /**
      * Initializes the connection and channel to the message queue.
      *
@@ -26,6 +27,24 @@ export declare class MQLib {
      * @returns The channel object to the message queue.
      */
     get_channel(): Channel;
+    /**
+     * Gracefully disconnects from the message queue.
+     * Closes the channel first, then the connection.
+     *
+     * @param timeout - Optional timeout in ms to wait for in-flight messages (default: 5000)
+     * @example
+     * const mqLib = new MQLib();
+     * await mqLib.init("amqp://localhost");
+     * // ... do work ...
+     * await mqLib.disconnect();
+     */
+    disconnect(timeout?: number): Promise<void>;
+    /**
+     * Checks if the connection is currently active.
+     *
+     * @returns true if connected, false otherwise
+     */
+    is_connected(): boolean;
 }
 export declare class BaseMQ {
     channel: Channel;

package/dist/types/observability/index.d.mts

@@ -0,0 +1,45 @@
+/**
+ * SFR Observability Module
+ *
+ * Provides OpenTelemetry-compatible tracing, metrics, and logging.
+ * Configuration is automatically extracted from SFR's OASConfig.
+ */
+export interface ObservabilityOptions {
+    /** Enable/disable observability (default: true) */
+    enabled?: boolean;
+    /** OTLP endpoint URL (default: http://localhost:4318) */
+    otlp_endpoint?: string;
+    /** Enable auto-instrumentation for common libraries (default: true) */
+    auto_instrumentation?: boolean;
+    /** Sampling ratio 0.0 - 1.0 (default: 1.0) */
+    sampling_ratio?: number;
+    /** Log format: 'json' for production, 'pretty' for development */
+    log_format?: "json" | "pretty";
+    /** Additional resource attributes */
+    resource_attributes?: Record<string, string>;
+    /** Enable debug logging for OTel SDK */
+    debug?: boolean;
+}
+/**
+ * Initializes the OpenTelemetry SDK with configuration derived from OASConfig.
+ * Must be called before SFR initialization for full instrumentation.
+ *
+ * @param oas_cfg - The OASConfig that will be passed to SFR
+ * @param options - Additional observability options
+ */
+export declare function init_observability(oas_cfg: OASConfig, options?: ObservabilityOptions): void;
+/**
+ * Gracefully shuts down the OpenTelemetry SDK.
+ * Flushes all pending telemetry data before closing.
+ */
+export declare function shutdown_observability(): Promise<void>;
+/**
+ * Checks if observability has been initialized.
+ */
+export declare function is_observability_enabled(): boolean;
+export { get_tracer, with_span, get_trace_context, inject_trace_context } from "./tracer.mjs";
+export { get_sfr_metrics, init_metrics, type SFRMetrics } from "./metrics.mjs";
+export { sfr_logger, create_child_logger, init_logger } from "./logger.mjs";
+export { sfr_rest_telemetry } from "./middleware/rest.mjs";
+export { instrument_socket_io } from "./middleware/ws.mjs";
+export { wrap_mq_handler, inject_mq_trace_context } from "./middleware/mq.mjs";