Configuration Types

/**
 * Configuration options for Engine.IO server
 */
interface ServerOptions {
  /**
   * How many ms without a pong packet to consider the connection closed
   * @default 20000
   */
  pingTimeout?: number;
  
  /**
   * How many ms before sending a new ping packet
   * @default 25000
   */
  pingInterval?: number;
  
  /**
   * How many ms before an uncompleted transport upgrade is cancelled
   * @default 10000
   */
  upgradeTimeout?: number;
  
  /**
   * How many bytes or characters a message can be before closing the session
   * @default 1e6 (1MB)
   */
  maxHttpBufferSize?: number;
  
  /**
   * Function to authorize handshake or upgrade requests
   */
  allowRequest?: (
    req: IncomingMessage,
    fn: (err: string | null | undefined, success: boolean) => void
  ) => void;
  
  /**
   * Low-level transports that are enabled
   * @default ["polling", "websocket"]
   */
  transports?: ("polling" | "websocket" | "webtransport")[];
  
  /**
   * Whether to allow transport upgrades
   * @default true
   */
  allowUpgrades?: boolean;
  
  /**
   * WebSocket permessage-deflate extension parameters
   * @default false
   */
  perMessageDeflate?: boolean | {
    threshold?: number;
    concurrencyLimit?: number;
    deflateOptions?: {
      level?: number;
      windowBits?: number;
      memLevel?: number;
      chunkSize?: number;
    };
  };
  
  /**
   * HTTP compression parameters for polling transports
   * @default { threshold: 1024 }
   */
  httpCompression?: boolean | {
    threshold?: number;
    level?: number;
    memLevel?: number;
  };
  
  /**
   * Custom WebSocket server implementation
   * @default require("ws").Server
   */
  wsEngine?: any;
  
  /**
   * Initial packet concatenated to handshake packet
   */
  initialPacket?: any;
  
  /**
   * Cookie configuration for session persistence
   * @default false
   */
  cookie?: (CookieSerializeOptions & { name: string }) | boolean;
  
  /**
   * CORS configuration options
   */
  cors?: CorsOptions | CorsOptionsDelegate;
  
  /**
   * Whether to enable compatibility with Socket.IO v2 clients
   * @default false
   */
  allowEIO3?: boolean;
}

/**
 * Options for attaching Engine.IO to HTTP server
 */
interface AttachOptions {
  /**
   * Name of the path to capture
   * @default "/engine.io"
   */
  path?: string;
  
  /**
   * Destroy unhandled upgrade requests
   * @default true
   */
  destroyUpgrade?: boolean;
  
  /**
   * Milliseconds after which unhandled requests are ended
   * @default 1000
   */
  destroyUpgradeTimeout?: number;
  
  /**
   * Whether to add a trailing slash to the request path
   * @default true
   */
  addTrailingSlash?: boolean;
}

/**
 * Options for sending messages
 */
interface SendOptions {
  /**
   * Whether to compress the message
   * @default true for messages above compression threshold
   */
  compress?: boolean;
}

/**
 * Raw data types that can be sent/received
 */
type RawData = string | Buffer | ArrayBuffer | ArrayBufferView;

/**
 * CORS configuration options
 */
interface CorsOptions {
  /**
   * Allowed origins
   */
  origin?: boolean | string | RegExp | (string | RegExp)[] | 
           ((origin: string, callback: (err: Error | null, allow?: boolean) => void) => void);
  
  /**
   * Allowed HTTP methods
   */
  methods?: string | string[];
  
  /**
   * Allowed request headers
   */
  allowedHeaders?: string | string[];
  
  /**
   * Headers exposed to the client
   */
  exposedHeaders?: string | string[];
  
  /**
   * Whether to include credentials
   */
  credentials?: boolean;
  
  /**
   * How long to cache preflight results
   */
  maxAge?: number;
  
  /**
   * Whether to pass CORS preflight response to next handler
   */
  preflightContinue?: boolean;
  
  /**
   * Status code for successful OPTIONS request
   */
  optionsSuccessStatus?: number;
}

/**
 * Dynamic CORS configuration function
 */
type CorsOptionsDelegate = (
  req: IncomingMessage,
  callback: (err: Error | null, options?: CorsOptions) => void
) => void;

/**
 * HTTP cookie serialization options
 */
interface CookieSerializeOptions {
  /**
   * Cookie domain
   */
  domain?: string;
  
  /**
   * Function to encode cookie value
   */
  encode?: (value: string) => string;
  
  /**
   * Cookie expiration date
   */
  expires?: Date;
  
  /**
   * Whether cookie is HTTP-only
   */
  httpOnly?: boolean;
  
  /**
   * Cookie max age in seconds
   */
  maxAge?: number;
  
  /**
   * Whether cookie is partitioned
   */
  partitioned?: boolean;
  
  /**
   * Cookie path
   */
  path?: string;
  
  /**
   * Cookie priority level
   */
  priority?: "low" | "medium" | "high";
  
  /**
   * SameSite policy
   */
  sameSite?: true | false | "lax" | "strict" | "none";
  
  /**
   * Whether cookie requires HTTPS
   */
  secure?: boolean;
}

/**
 * Available transport names
 */
type TransportName = "polling" | "websocket" | "webtransport";

/**
 * Socket connection states
 */
type ReadyState = "opening" | "open" | "closing" | "closed";

/**
 * Extended HTTP request with Engine.IO properties
 */
interface EngineRequest extends IncomingMessage {
  /** Parsed query parameters */
  _query: Record<string, string>;
  
  /** HTTP response object */
  res?: ServerResponse;
  
  /** Cleanup function */
  cleanup?: Function;
  
  /** WebSocket instance for upgrade requests */
  websocket?: any;
}

/**
 * Configuration options for µWebSockets.js server
 */
interface uOptions {
  /**
   * WebSocket compression level
   * @default 0 (disabled)
   */
  compression?: number;
  
  /**
   * Connection idle timeout in seconds
   * @default 120
   */
  idleTimeout?: number;
  
  /**
   * Maximum WebSocket backpressure in bytes
   * @default 16MB
   */
  maxBackpressure?: number;
  
  /**
   * Maximum WebSocket message size in bytes
   * @default 16MB
   */
  maxPayloadLength?: number;
}

/**
 * Express-compatible middleware function
 */
type Middleware = (
  req: IncomingMessage,
  res: ServerResponse,
  next: (err?: any) => void
) => void;

/**
 * Engine.IO packet structure
 */
interface Packet {
  /** Packet type */
  type: string;
  
  /** Packet data */
  data?: string | Buffer;
  
  /** Additional packet options */
  options?: {
    compress?: boolean;
  };
}

/**
 * Authorization callback function
 */
type AuthorizationCallback = (
  err: string | null | undefined,
  success: boolean
) => void;

/**
 * Authorization function
 */
type AuthorizationFunction = (
  req: IncomingMessage,
  callback: AuthorizationCallback
) => void;

const developmentOptions: ServerOptions = {
  // Fast reconnection for development
  pingTimeout: 5000,
  pingInterval: 10000,
  
  // Enable all transports for testing
  transports: ['polling', 'websocket', 'webtransport'],
  
  // Permissive CORS for development
  cors: {
    origin: true,
    credentials: true
  },
  
  // Small buffer for testing
  maxHttpBufferSize: 1e4, // 10KB
  
  // Minimal compression
  httpCompression: {
    threshold: 512
  }
};

const productionOptions: ServerOptions = {
  // Standard timeouts
  pingTimeout: 20000,
  pingInterval: 25000,
  
  // Optimized transports
  transports: ['polling', 'websocket'],
  
  // Strict CORS
  cors: {
    origin: process.env.ALLOWED_ORIGINS?.split(','),
    credentials: true
  },
  
  // Large buffer for efficiency
  maxHttpBufferSize: 1e6, // 1MB
  
  // Aggressive compression
  httpCompression: {
    threshold: 1024,
    level: 6
  },
  
  // WebSocket compression
  perMessageDeflate: {
    threshold: 1024,
    deflateOptions: {
      level: 6,
      windowBits: 13
    }
  },
  
  // Session persistence
  cookie: {
    name: 'io',
    httpOnly: true,
    secure: true,
    sameSite: 'strict'
  }
};

const highPerformanceOptions: ServerOptions = {
  // Fast heartbeat
  pingTimeout: 10000,
  pingInterval: 15000,
  
  // WebSocket-first
  transports: ['websocket', 'polling'],
  
  // Use high-performance WebSocket engine
  wsEngine: require('eiows').Server,
  
  // Large buffers
  maxHttpBufferSize: 10e6, // 10MB
  
  // Optimized compression
  perMessageDeflate: {
    threshold: 2048,
    deflateOptions: {
      level: 1, // Fast compression
      windowBits: 13
    }
  }
};