@avtechno/sfr 1.0.18 → 2.0.1

package/src/types/index.d.ts

@@ -37,16 +37,121 @@ declare type RESTHandlerDescriptor<V, H, C> = {
 };
 
 declare type WSHandlerDescriptor<V, H, C> = {
-  cfg?: SFRConfig;
+  cfg?: WSConfig;
   validators: RequestValidators & V;
-  handlers: WSRequestHandlers & H & ThisType<HandlerFacilities & C>;
-  controllers?: RequestControllers & C & ThisType<ControllerFacilities & C>;
+  handlers: WSRequestHandlers & H & ThisType<WSHandlerFacilities & C>;
+  controllers?: RequestControllers & C & ThisType<ControllerFacilities>;
 };
 
+/**
+ * WebSocket-specific configuration extending base SFRConfig
+ */
+declare type WSConfig = SFRConfig & {
+  /**
+   * Socket.IO namespace to use (e.g., "/chat", "/notifications")
+   * Defaults to "/" if not specified
+   */
+  namespace?: string;
+};
+
+/**
+ * Facilities injected into WS handlers
+ */
+declare interface WSHandlerFacilities extends HandlerFacilities {
+  /** The Socket.IO server instance */
+  io: Server;
+  /** The current socket connection */
+  socket: Socket;
+}
+
 declare interface HandlerFacilities { }
 
 declare interface ControllerFacilities { }
 
+/**
+ * Authentication middleware function signature.
+ * Return `true` to allow the request, `false` to deny, or an object with error details.
+ */
+declare type AuthMiddleware = (
+  req: ExpressRequest,
+  res: ExpressResponse
+) => boolean | { error: string; status?: number } | Promise<boolean | { error: string; status?: number }>;
+
+/**
+ * Authentication configuration for SFR
+ */
+declare type AuthConfig = {
+  /**
+   * Custom authentication middleware function.
+   * Called for all non-public routes before the handler executes.
+   */
+  middleware?: AuthMiddleware;
+}
+
+/**
+ * Rate limit configuration options.
+ * Compatible with express-rate-limit configuration.
+ */
+declare type RateLimitConfig = {
+  /**
+   * Maximum number of requests allowed within the window.
+   * @default 100
+   */
+  max?: number;
+  /**
+   * Time window in milliseconds.
+   * @default 60000 (1 minute)
+   */
+  windowMs?: number;
+  /**
+   * Message to return when rate limit is exceeded.
+   * @default "Too many requests, please try again later."
+   */
+  message?: string | object;
+  /**
+   * HTTP status code to return when rate limit is exceeded.
+   * @default 429
+   */
+  statusCode?: number;
+  /**
+   * Whether to include rate limit headers in the response.
+   * @default true
+   */
+  standardHeaders?: boolean;
+  /**
+   * Whether to include legacy rate limit headers.
+   * @default false
+   */
+  legacyHeaders?: boolean;
+  /**
+   * Custom key generator function. By default, uses req.ip.
+   * @param req - Express request object
+   * @returns Key to identify the client
+   */
+  keyGenerator?: (req: ExpressRequest) => string;
+  /**
+   * Custom skip function. Return true to skip rate limiting for this request.
+   * @param req - Express request object
+   * @returns Whether to skip rate limiting
+   */
+  skip?: (req: ExpressRequest) => boolean | Promise<boolean>;
+  /**
+   * Custom store for rate limit data. If not provided, uses memory store.
+   */
+  store?: any;
+}
+
+/**
+ * Global rate limit configuration for SFR
+ */
+declare type RateLimitGlobalConfig = {
+  /**
+   * Default rate limit configuration applied to all routes.
+   * Can be overridden per-route using cfg.rate_limit in SFR files.
+   */
+  default?: RateLimitConfig;
+}
+
 declare type InjectedFacilities = {
   handlers?: HandlerFacilities;
   controllers?: ControllerFacilities;
@@ -89,6 +194,13 @@ declare type SFRConfig = {
    * * Access Authorization
    */
   public?: boolean;
+  /**
+   * Per-route rate limit configuration.
+   * If not specified, uses the global default rate limit configuration.
+   * Set to `false` to disable rate limiting for this route.
+   * Set to an object to override the default configuration.
+   */
+  rate_limit?: RateLimitConfig | false;
 };
 
 declare type OASConfig = Omit<ServiceManifest, "documents"> & InfoObject
@@ -200,17 +312,41 @@ type CustomRequestHandler= (
   res: ExpressResponse,
   next: NextFunction
 ) => any;
-declare type WSRequestHandler = (
-  ctx: WSRequestCtx,
-  args?: object
-) => Promise<object>;
+/**
+ * WebSocket event handler function signature
+ * @param ctx - Context containing io, socket, and validated data
+ */
+declare type WSRequestHandler = (ctx: WSRequestCtx) => void | Promise<void>;
+
+/**
+ * Map of WebSocket event handlers with metadata
+ */
 declare type WSRequestHandlers = {
-  [event: string]: WSRequestHandler;
+  [event: string]: WSHandlerDefinition;
 };
+
+/**
+ * Individual WebSocket handler definition with metadata
+ */
+declare type WSHandlerDefinition = SFRMetadata & {
+  /**
+   * The handler function to execute when the event is received
+   */
+  fn: WSRequestHandler;
+};
+
+/**
+ * Context passed to WebSocket handlers
+ */
 declare type WSRequestCtx = {
+  /** The Socket.IO server instance */
   io: Server;
+  /** The current socket connection */
   socket: Socket;
-  args: string[];
+  /** The validated event data/payload */
+  data: any;
+  /** Callback function for acknowledgements (if provided by client) */
+  ack?: (...args: any[]) => void;
 };
 declare type RequestResponse =
   | {
@@ -227,10 +363,15 @@ declare type RESTNamespaceDeclaration = {
   }
 };
 declare type WSNamespaceDeclaration = {
-  [namespace: string]: DeclarationArtifact & {
-    content: {
-      handlers: WSRequestHandlers
-    }
+  [namespace: string]: WSDeclarationArtifact
+};
+
+declare type WSDeclarationArtifact = DeclarationArtifact & {
+  content: {
+    cfg: WSConfig;
+    validators: RequestValidators;
+    controllers: RequestControllers;
+    handlers: WSRequestHandlers;
   }
 };
 declare type MQNamespaceDeclaration = {
@@ -316,8 +457,8 @@ declare type PatternMQSet = {
   "Point-to-Point": TargetedMQ;
   "Fanout": BroadcastMQ;
   "Request-Reply": TargetedMQ;
-  "Direct": TargetedMQ;
-  "Topic": TargetedMQ;
+  "Direct": BroadcastMQ;
+  "Topic": BroadcastMQ;
 }
 
 declare type MQHandlerDescriptor<V, H, C> = {
@@ -401,4 +542,87 @@ type AsyncAPIMessage = {
     contentType: string;
     payload: any;
   };
-};
+};
+
+/* Observability Types */
+
+/**
+ * Configuration options for SFR observability (tracing, metrics, logging).
+ * Service name and version are automatically extracted from OASConfig.
+ */
+declare 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 for traces/metrics */
+  resource_attributes?: Record<string, string>;
+  /** Enable debug logging for OTel SDK */
+  debug?: boolean;
+}
+
+/**
+ * Logger configuration options.
+ */
+declare interface LoggerConfig {
+  service_name?: string;
+  level?: string;
+  format?: "json" | "pretty";
+  transports?: any[];
+}
+
+/**
+ * Pre-defined SFR metrics for all protocols.
+ */
+declare interface SFRMetrics {
+  // REST Metrics
+  rest_requests_total: any;
+  rest_request_duration: any;
+  rest_errors_total: any;
+  rest_request_size: any;
+  rest_response_size: any;
+
+  // WebSocket Metrics
+  ws_connections_active: any;
+  ws_connections_total: any;
+  ws_events_total: any;
+  ws_event_duration: any;
+  ws_errors_total: any;
+
+  // MQ Metrics
+  mq_messages_received: any;
+  mq_messages_published: any;
+  mq_processing_duration: any;
+  mq_errors_total: any;
+  mq_messages_rejected: any;
+  mq_messages_acked: any;
+}
+
+/**
+ * Options for creating a span.
+ */
+declare interface SpanOptions {
+  /** Name of the span */
+  name: string;
+  /** Kind of span (default: INTERNAL) */
+  kind?: import("@opentelemetry/api").SpanKind;
+  /** Initial attributes to set on the span */
+  attributes?: Record<string, string | number | boolean>;
+  /** Parent context (optional, uses active context if not provided) */
+  parent_context?: import("@opentelemetry/api").Context;
+}
+
+/**
+ * Trace context information.
+ */
+declare interface TraceContext {
+  trace_id: string;
+  span_id: string;
+  trace_flags: number;
+}

package/dist/example.mjs

@@ -1,33 +0,0 @@
-import Joi from "joi";
-import { REST } from "./templates.mjs";
-export default REST({
-    cfg: {
-        base_dir: "example",
-        public: false,
-    },
-    validators: {
-        "get-something": {
-            "name": Joi.string().required(),
-            "age": Joi.number().required(),
-        }
-    },
-    handlers: {
-        GET: {
-            "get-something": {
-                description: "Get something I guess?",
-                async fn(req, res) {
-                    const result = await this.db_call();
-                    res.status(200).json({
-                        data: result
-                    });
-                }
-            }
-        }
-    },
-    controllers: {
-        async db_call() {
-            /* Perform database calls here through accessing the "this" context (if injections are set) */
-            return "Something";
-        }
-    }
-});

package/dist/types/example.d.mts

@@ -1,11 +0,0 @@
-declare const _default: {
-    GET: {
-        "get-something": {
-            description: string;
-            fn(req: import("express").Request<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>, res: import("express").Response<any, Record<string, any>>): Promise<void>;
-        };
-    };
-} & {
-    db_call(): Promise<string>;
-};
-export default _default;

package/src/example.mts

@@ -1,35 +0,0 @@
-import Joi from "joi";
-import { REST } from "./templates.mjs";
-
-
-export default REST({
-  cfg : {
-    base_dir : "example",
-    public : false,
-  },
-  validators: {
-    "get-something": {
-      "name": Joi.string().required(),
-      "age": Joi.number().required(),
-    }
-  },
-  handlers: {
-    GET : {
-      "get-something": {
-        description : "Get something I guess?",
-        async fn(req, res){
-          const result = await this.db_call()
-          res.status(200).json({
-            data: result
-          });
-        }
-      }
-    }
-  },
-  controllers: {
-    async db_call(){
-      /* Perform database calls here through accessing the "this" context (if injections are set) */
-      return "Something";
-    }
-  }
-})