yinzerflow 0.1.18 → 0.2.0

package/YinzerFlow.d.ts

@@ -0,0 +1,565 @@
+type CreateEnum<T> = T[keyof T];
+type DeepPartial<T> = {
+	[P in keyof T]?: T[P] extends object ? T[P] extends Array<infer U> ? Array<U> // Keep arrays as-is, don't make array items partial
+	 : DeepPartial<T[P]> : T[P];
+};
+interface InternalHandlerCallbackGenerics {
+	body: unknown;
+	response: unknown;
+	query: Record<string, string>;
+	params: Record<string, string>;
+}
+declare const httpStatusCode: {
+	readonly ok: 200;
+	readonly created: 201;
+	readonly accepted: 202;
+	readonly noContent: 204;
+	readonly movedPermanently: 301;
+	readonly found: 302;
+	readonly notModified: 304;
+	readonly badRequest: 400;
+	readonly unauthorized: 401;
+	readonly forbidden: 403;
+	readonly notFound: 404;
+	readonly methodNotAllowed: 405;
+	readonly conflict: 409;
+	readonly unsupportedMediaType: 415;
+	readonly tooManyRequests: 429;
+	readonly internalServerError: 500;
+};
+declare const httpMethod: {
+	readonly delete: "DELETE";
+	readonly get: "GET";
+	readonly head: "HEAD";
+	readonly post: "POST";
+	readonly put: "PUT";
+	readonly patch: "PATCH";
+	readonly options: "OPTIONS";
+};
+declare const httpHeaders: {
+	readonly authorization: "Authorization";
+	readonly proxyAuthorization: "Proxy-Authorization";
+	readonly wwwAuthenticate: "WWW-Authenticate";
+	readonly cacheControl: "Cache-Control";
+	readonly etag: "ETag";
+	readonly expires: "Expires";
+	readonly lastModified: "Last-Modified";
+	readonly ifMatch: "If-Match";
+	readonly ifNoneMatch: "If-None-Match";
+	readonly ifModifiedSince: "If-Modified-Since";
+	readonly ifUnmodifiedSince: "If-Unmodified-Since";
+	readonly ifRange: "If-Range";
+	readonly age: "Age";
+	readonly vary: "Vary";
+	readonly contentType: "Content-Type";
+	readonly contentLength: "Content-Length";
+	readonly contentEncoding: "Content-Encoding";
+	readonly contentLanguage: "Content-Language";
+	readonly contentDisposition: "Content-Disposition";
+	readonly contentLocation: "Content-Location";
+	readonly contentRange: "Content-Range";
+	readonly accessControlAllowCredentials: "Access-Control-Allow-Credentials";
+	readonly accessControlAllowHeaders: "Access-Control-Allow-Headers";
+	readonly accessControlAllowMethods: "Access-Control-Allow-Methods";
+	readonly accessControlAllowOrigin: "Access-Control-Allow-Origin";
+	readonly accessControlExposeHeaders: "Access-Control-Expose-Headers";
+	readonly accessControlMaxAge: "Access-Control-Max-Age";
+	readonly accessControlRequestHeaders: "Access-Control-Request-Headers";
+	readonly accessControlRequestMethod: "Access-Control-Request-Method";
+	readonly accept: "Accept";
+	readonly acceptEncoding: "Accept-Encoding";
+	readonly acceptLanguage: "Accept-Language";
+	readonly acceptRanges: "Accept-Ranges";
+	readonly host: "Host";
+	readonly userAgent: "User-Agent";
+	readonly referer: "Referer";
+	readonly origin: "Origin";
+	readonly from: "From";
+	readonly expect: "Expect";
+	readonly location: "Location";
+	readonly server: "Server";
+	readonly date: "Date";
+	readonly allow: "Allow";
+	readonly retryAfter: "Retry-After";
+	readonly range: "Range";
+	readonly contentSecurityPolicy: "Content-Security-Policy";
+	readonly contentSecurityPolicyReportOnly: "Content-Security-Policy-Report-Only";
+	readonly strictTransportSecurity: "Strict-Transport-Security";
+	readonly xContentTypeOptions: "X-Content-Type-Options";
+	readonly xFrameOptions: "X-Frame-Options";
+	readonly xXSSProtection: "X-XSS-Protection";
+	readonly referrerPolicy: "Referrer-Policy";
+	readonly permissionsPolicy: "Permissions-Policy";
+	readonly crossOriginEmbedderPolicy: "Cross-Origin-Embedder-Policy";
+	readonly crossOriginOpenerPolicy: "Cross-Origin-Opener-Policy";
+	readonly crossOriginResourcePolicy: "Cross-Origin-Resource-Policy";
+	readonly cookie: "Cookie";
+	readonly setCookie: "Set-Cookie";
+	readonly connection: "Connection";
+	readonly keepAlive: "Keep-Alive";
+	readonly upgrade: "Upgrade";
+	readonly upgradeInsecureRequests: "Upgrade-Insecure-Requests";
+	readonly transferEncoding: "Transfer-Encoding";
+	readonly te: "TE";
+	readonly trailer: "Trailer";
+	readonly forwarded: "Forwarded";
+	readonly xForwardedFor: "X-Forwarded-For";
+	readonly via: "Via";
+	readonly maxForwards: "Max-Forwards";
+	readonly altSvc: "Alt-Svc";
+	readonly altUsed: "Alt-Used";
+	readonly timingAllowOrigin: "Timing-Allow-Origin";
+	readonly serverTiming: "Server-Timing";
+	readonly refresh: "Refresh";
+	readonly link: "Link";
+	readonly xPoweredBy: "X-Powered-By";
+	readonly xPermittedCrossDomainPolicies: "X-Permitted-Cross-Domain-Policies";
+	readonly reportTo: "Report-To";
+	readonly serviceWorkerAllowed: "Service-Worker-Allowed";
+	readonly sourceMap: "SourceMap";
+	readonly priority: "Priority";
+	readonly secGPC: "Sec-GPC";
+	readonly clearSiteData: "Clear-Site-Data";
+	readonly noVarySearch: "No-Vary-Search";
+};
+type InternalHttpStatusCode = CreateEnum<typeof httpStatusCode>;
+type InternalHttpMethod = CreateEnum<typeof httpMethod>;
+type InternalHttpHeaders = Lowercase<CreateEnum<typeof httpHeaders>> | string;
+interface Request$1<T = InternalHandlerCallbackGenerics> {
+	protocol: string;
+	method: InternalHttpMethod;
+	path: string;
+	headers: Partial<Record<InternalHttpHeaders, string>>;
+	body: T["body"];
+	query: T["query"];
+	params: T["params"];
+	ipAddress: string; // The ip address of the client (Configure proxy hops if behind a proxy, load balancer, etc.)
+	rawBody: Buffer | string; // The raw body of the request. Useful for parsing the body manually.
+}
+interface Response$1 {
+	setStatusCode: (statusCode: InternalHttpStatusCode) => void;
+	addHeaders: (headers: Partial<Record<InternalHttpHeaders, string>>) => void;
+	removeHeaders: (headerNames: Array<InternalHttpHeaders>) => void;
+}
+interface Context {
+	request: Request$1;
+	response: Response$1;
+}
+type HandlerCallback<T = InternalHandlerCallbackGenerics> = (ctx: Context) => Promise<T["response"] | void> | T["response"] | void;
+type InternalGlobalHookOptions = {
+	routesToExclude: Array<string>;
+} & {
+	routesToInclude: Array<string>;
+};
+interface InternalHookRegistryImpl {
+	readonly _beforeAll: Set<{
+		handler: HandlerCallback;
+		options?: InternalGlobalHookOptions;
+	}>;
+	readonly _afterAll: Set<{
+		handler: HandlerCallback;
+		options?: InternalGlobalHookOptions;
+	}>;
+	_onError: HandlerCallback;
+	_onNotFound: HandlerCallback;
+	_addBeforeHooks: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
+	_addAfterHooks: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
+	_addOnError: (handler: HandlerCallback) => void;
+	_addOnNotFound: (handler: HandlerCallback) => void;
+}
+interface InternalRouteRegistryImpl {
+	readonly _exactRoutes: Map<InternalHttpMethod, Map<string, InternalRouteRegistry>>;
+	readonly _parameterizedRoutes: Map<InternalHttpMethod, Array<InternalPreCompiledRoute>>;
+	_register: (route: InternalRouteRegistry) => void;
+	_findRoute: (method: InternalHttpMethod, path: string) => InternalRouteRegistry | undefined;
+}
+interface InternalRouteRegistryOptions {
+	beforeHooks: Array<HandlerCallback>;
+	afterHooks: Array<HandlerCallback>;
+}
+interface InternalRouteRegistry {
+	prefix?: string;
+	path: string;
+	method: InternalHttpMethod;
+	handler: HandlerCallback;
+	options: InternalRouteRegistryOptions;
+	params: Record<string, string>;
+}
+interface InternalPreCompiledRoute extends InternalRouteRegistry {
+	pattern: RegExp;
+	paramNames: Array<string>;
+	isParameterized: boolean;
+}
+declare const logLevels: {
+	readonly off: "off";
+	readonly verbose: "verbose";
+	readonly network: "network";
+};
+type InternalCorsConfiguration = InternalCorsDisabledConfiguration | InternalCorsEnabledConfiguration;
+interface InternalCorsDisabledConfiguration {
+	/**
+	 * Disable CORS handling
+	 */
+	enabled: false;
+}
+interface InternalCorsEnabledConfiguration {
+	/**
+	 * Enable CORS handling
+	 */
+	enabled: true;
+	/**
+	 * Allowed origins for CORS requests (REQUIRED when enabled)
+	 * - string: Single origin (e.g., 'https://example.com')
+	 * - string[]: Multiple specific origins
+	 * - '*': Allow all origins (not recommended for production with credentials)
+	 * - function: Dynamic origin validation
+	 */
+	origin: Array<string> | RegExp | string | ((origin: string | undefined, request: any) => boolean);
+	/**
+	 * HTTP methods allowed for CORS requests
+	 * @default ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS']
+	 */
+	methods: Array<string>;
+	/**
+	 * Headers allowed in CORS requests
+	 * - string[]: Specific headers
+	 * - '*': Allow all headers
+	 * @default ['*']
+	 */
+	allowedHeaders: Array<string> | string | "*";
+	/**
+	 * Headers exposed to the client in CORS responses
+	 * @default []
+	 */
+	exposedHeaders: Array<string>;
+	/**
+	 * Allow credentials (cookies, authorization headers) in CORS requests
+	 * Note: When true, origin cannot be '*'
+	 * @default false
+	 */
+	credentials: boolean;
+	/**
+	 * Maximum age (in seconds) for preflight cache
+	 * Tells browser how long to cache preflight response (client-side only)
+	 * @default 86400 (24 hours)
+	 */
+	maxAge: number;
+	/**
+	 * Continue to route handler after preflight
+	 * - false: Handle preflight completely in CORS system (recommended)
+	 * - true: Pass preflight to route handlers (requires manual OPTIONS routes)
+	 * @default false
+	 */
+	preflightContinue: boolean;
+	/**
+	 * Status code for successful OPTIONS requests
+	 * @default 204
+	 */
+	optionsSuccessStatus: InternalHttpStatusCode;
+}
+interface InternalConnectionOptions {
+	/**
+	 * Default socket timeout in milliseconds (30 seconds)
+	 *
+	 * Standard timeout for most socket connections.
+	 * It is long enough for slow clients but short enough to prevent idle connections from staying open indefinitely.
+	 */
+	socketTimeout: number;
+	/**
+	 * Default graceful shutdown timeout in milliseconds (30 seconds)
+	 *
+	 * This is the maximum time to wait for a connection to complete before the server will close it.
+	 */
+	gracefulShutdownTimeout: number;
+	/**
+	 * Default keep-alive timeout in milliseconds (65 seconds)
+	 *
+	 * This is the maximum time a connection can be idle before the server will close it.
+	 * This is to allow for a connection to stay open for a period of time so subsequent requests can be handled without a new connection.
+	 * This is also to prevent a connection from staying open indefinitely.
+	 * This is also useful for load balancing and preventing a single server from being overwhelmed by a large number of connections.
+	 * AWS recommends a keep-alive timeout of 65 seconds because there idle timeout is 60 seconds.
+	 */
+	keepAliveTimeout: number;
+	/**
+	 * Default headers timeout in milliseconds (66 seconds)
+	 *
+	 * This is the maximum time to wait for a header from the client.
+	 * This is to allow for a connection to stay open for a period of time so subsequent requests can be handled without a new connection.
+	 * This is also to prevent a connection from staying open indefinitely.
+	 * This is also useful for load balancing and preventing a single server from being overwhelmed by a large number of connections.
+	 * It is recommended to set this value to be greater than the keep-alive timeout to prevent the server from closing the connection prematurely
+	 * before the keep-alive timeout has expired.
+	 */
+	headersTimeout: number;
+}
+interface InternalBodyParserConfiguration {
+	/**
+	 * JSON parsing security configuration
+	 */
+	json: InternalJsonParserConfiguration;
+	/**
+	 * File upload security configuration
+	 */
+	fileUploads: InternalFileUploadConfiguration;
+	/**
+	 * URL-encoded form data configuration
+	 */
+	urlEncoded: InternalUrlEncodedConfiguration;
+}
+interface InternalJsonParserConfiguration {
+	/**
+	 * Maximum JSON request body size in bytes
+	 * @default 262144 (256KB) - reasonable for API payloads
+	 * @min 1024 (1KB)
+	 */
+	maxSize: number;
+	/**
+	 * Maximum JSON nesting depth to prevent stack overflow attacks
+	 * @default 10
+	 * @min 1
+	 */
+	maxDepth: number;
+	/**
+	 * Allow prototype properties (__proto__, constructor, prototype) in JSON
+	 * SECURITY WARNING: Setting this to true enables prototype pollution attacks
+	 * @default false
+	 */
+	allowPrototypeProperties: boolean;
+	/**
+	 * Maximum number of keys in JSON objects to prevent memory exhaustion
+	 * @default 1000
+	 * @min 10
+	 */
+	maxKeys: number;
+	/**
+	 * Maximum length of JSON string values to prevent memory exhaustion
+	 * @default 1048576 (1MB)
+	 * @min 100
+	 */
+	maxStringLength: number;
+	/**
+	 * Maximum number of array elements to prevent memory exhaustion
+	 * @default 10000
+	 * @min 10
+	 */
+	maxArrayLength: number;
+}
+interface InternalFileUploadConfiguration {
+	/**
+	 * Maximum size per file in bytes
+	 * @default 10485760 (10MB) - reasonable for documents/images
+	 * @min 1024 (1KB)
+	 */
+	maxFileSize: number;
+	/**
+	 * Maximum total size of all files in a single request
+	 * @default 52428800 (50MB)
+	 * @min 1024 (1KB)
+	 */
+	maxTotalSize: number;
+	/**
+	 * Maximum number of files per request
+	 * @default 10
+	 * @min 1
+	 */
+	maxFiles: number;
+	/**
+	 * Allowed file extensions (empty array allows all)
+	 * @default [] (all extensions allowed)
+	 * @example ['.jpg', '.png', '.pdf', '.txt']
+	 */
+	allowedExtensions: Array<string>;
+	/**
+	 * Blocked file extensions for security
+	 * @default ['.exe', '.bat', '.cmd', '.scr', '.pif', '.com']
+	 */
+	blockedExtensions: Array<string>;
+	/**
+	 * Maximum filename length to prevent path issues
+	 * @default 255
+	 * @min 10
+	 */
+	maxFilenameLength: number;
+}
+interface InternalUrlEncodedConfiguration {
+	/**
+	 * Maximum URL-encoded form data size in bytes
+	 * @default 1048576 (1MB)
+	 * @min 1024 (1KB)
+	 */
+	maxSize: number;
+	/**
+	 * Maximum number of form fields
+	 * @default 1000
+	 * @min 10
+	 */
+	maxFields: number;
+	/**
+	 * Maximum field name length
+	 * @default 100
+	 * @min 5
+	 */
+	maxFieldNameLength: number;
+	/**
+	 * Maximum field value length
+	 * @default 1048576 (1MB)
+	 * @min 100
+	 */
+	maxFieldLength: number;
+}
+interface InternalIpValidationConfig {
+	/**
+	 * List of trusted proxy IP addresses that are allowed to set forwarded headers
+	 * Only these IPs can provide X-Forwarded-For and similar headers
+	 * Use '*' to trust any proxy (less secure but useful for complex/unknown infrastructure)
+	 * @default ['127.0.0.1', '::1']
+	 * @example ['127.0.0.1', '::1', '192.168.1.10'] // Specific proxies
+	 * @example ['*'] // Trust any proxy (enables spoofing detection without proxy validation)
+	 */
+	trustedProxies: Array<string>;
+	/**
+	 * Allow private IP addresses (RFC 1918, RFC 4193, RFC 3927) as client IPs
+	 * Set to false for public-facing APIs that should only receive public IPs
+	 * @default true
+	 */
+	allowPrivateIps: boolean;
+	/**
+	 * Header preference order for IP extraction
+	 * YinzerFlow will check headers in this order and use the first valid one
+	 * @default ['x-forwarded-for', 'x-real-ip', 'cf-connecting-ip', 'x-client-ip', 'true-client-ip']
+	 */
+	headerPreference: Array<string>;
+	/**
+	 * Maximum allowed length of IP chain in forwarded headers
+	 * Prevents DoS attacks through extremely long proxy chains
+	 * @default 10
+	 * @min 1
+	 * @max 50
+	 */
+	maxChainLength: number;
+	/**
+	 * Enable spoofing pattern detection
+	 * Detects suspicious patterns like duplicate IPs, mixed valid/invalid IPs
+	 * @default true
+	 */
+	detectSpoofing: boolean;
+}
+interface InternalServerConfiguration {
+	/**
+	 * Port number for the server to listen on
+	 * @default 5000
+	 */
+	port: number;
+	/**
+	 * Host address to bind the server to
+	 * @default '0.0.0.0'
+	 */
+	host: string;
+	/**
+	 * Logging level for YinzerFlow server
+	 * - 'off': No logging (silent mode)
+	 * - 'verbose': Application logging with Pittsburgh personality (level 1)
+	 * - 'network': Network logging + application logging (level 2)
+	 * @default 'off'
+	 */
+	logLevel: CreateEnum<typeof logLevels>;
+	/**
+	 * Cross-Origin Resource Sharing configuration
+	 */
+	cors: InternalCorsConfiguration;
+	/**
+	 * Body parsing configuration with security limits
+	 */
+	bodyParser: InternalBodyParserConfiguration;
+	/**
+	 * IP address security and validation configuration
+	 */
+	ipSecurity: InternalIpValidationConfig;
+	/**
+	 * Server connection options
+	 */
+	connectionOptions: InternalConnectionOptions;
+}
+interface Setup {
+	get: InternalSetupMethod;
+	post: InternalSetupMethod;
+	put: InternalSetupMethod;
+	patch: InternalSetupMethod;
+	delete: InternalSetupMethod;
+	options: InternalSetupMethod;
+	group: (prefix: string, callback: (group: Record<Lowercase<InternalHttpMethod>, InternalSetupMethod>) => void, options?: InternalRouteRegistryOptions) => void;
+	beforeAll: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
+	afterAll: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
+	onError: (handler: HandlerCallback) => void;
+	onNotFound: (handler: HandlerCallback) => void;
+}
+type InternalSetupMethod = (path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions) => void;
+interface InternalSetupImpl extends Setup {
+	readonly _configuration: InternalServerConfiguration;
+	readonly _routeRegistry: InternalRouteRegistryImpl;
+	readonly _hooks: InternalHookRegistryImpl;
+}
+declare class HookRegistryImpl implements InternalHookRegistryImpl {
+	readonly _beforeAll: Set<{
+		handler: HandlerCallback;
+		options?: InternalGlobalHookOptions;
+	}>;
+	readonly _afterAll: Set<{
+		handler: HandlerCallback;
+		options?: InternalGlobalHookOptions;
+	}>;
+	_onError: HandlerCallback;
+	_onNotFound: HandlerCallback;
+	constructor();
+	_addBeforeHooks(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
+	_addAfterHooks(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
+	_addOnError(handler: HandlerCallback): void;
+	_addOnNotFound(handler: HandlerCallback): void;
+}
+type ServerConfiguration = DeepPartial<InternalServerConfiguration>;
+declare class RouteRegistryImpl implements InternalRouteRegistryImpl {
+	readonly _exactRoutes: Map<InternalHttpMethod, Map<string, InternalRouteRegistry>>;
+	readonly _parameterizedRoutes: Map<InternalHttpMethod, InternalPreCompiledRoute[]>;
+	_register({ method, path, handler, options }: InternalRouteRegistry): void;
+	_findRoute(method: InternalHttpMethod, path: string): InternalRouteRegistry | undefined;
+	private _hasExactRoutePattern;
+	private _storeExactRoute;
+	private _storeParameterizedRoute;
+	private _findParameterizedRoute;
+}
+declare class SetupImpl implements InternalSetupImpl {
+	readonly _configuration: InternalServerConfiguration;
+	readonly _routeRegistry: RouteRegistryImpl;
+	readonly _hooks: HookRegistryImpl;
+	constructor(customConfiguration?: ServerConfiguration);
+	get(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
+	head(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
+	post(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
+	put(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
+	patch(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
+	delete(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
+	options(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
+	group(prefix: string, callback: (group: Record<Lowercase<InternalHttpMethod>, InternalSetupMethod>) => void, options?: InternalRouteRegistryOptions): void;
+	beforeAll(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
+	afterAll(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
+	onError(handler: HandlerCallback): void;
+	onNotFound(handler: HandlerCallback): void;
+}
+export declare class YinzerFlow extends SetupImpl {
+	private _isListening;
+	private _server?;
+	constructor(configuration?: ServerConfiguration);
+	private _setupServer;
+	private _processRequest;
+	private _handleConnection;
+	listen(): Promise<void>;
+	close(): Promise<void>;
+	status(): {
+		isListening: boolean;
+		port: number | undefined;
+		host: string | undefined;
+	};
+}
+
+export {};