@spfn/core
Version:
SPFN Framework Core - File-based routing, transactions, repository pattern
322 lines (315 loc) • 9.18 kB
TypeScript
import { MiddlewareHandler, Hono } from 'hono';
import { cors } from 'hono/cors';
import { serve } from '@hono/node-server';
/**
* CORS configuration options - inferred from hono/cors
*/
type CorsConfig = Parameters<typeof cors>[0];
/**
* Server Configuration Options
*
* Level 2: Partial customization with server.config.ts
*/
interface ServerConfig {
/**
* Server port (default: 4000)
*/
port?: number;
/**
* Server hostname (default: 'localhost')
*/
host?: string;
/**
* CORS configuration
* Set to false to disable default CORS middleware
*/
cors?: CorsConfig | false;
/**
* Enable/disable built-in middleware
*/
middleware?: {
/**
* Request logger (default: true)
*/
logger?: boolean;
/**
* CORS (default: true)
*/
cors?: boolean;
/**
* Error handler (default: true)
*/
errorHandler?: boolean;
};
/**
* Additional custom middleware
*/
use?: MiddlewareHandler[];
/**
* Global middlewares with names for route-level skip control
* Each middleware can be skipped per route using meta.skipMiddlewares
*
* @example
* ```typescript
* import { authMiddleware } from '@spfn/auth';
*
* export default {
* middlewares: [
* { name: 'auth', handler: authMiddleware() },
* { name: 'rateLimit', handler: rateLimitMiddleware() },
* ]
* } satisfies ServerConfig;
* ```
*/
middlewares?: Array<{
name: string;
handler: MiddlewareHandler;
}>;
/**
* Routes directory path (default: src/server/routes)
*/
routesPath?: string;
/**
* Enable debug mode (default: NODE_ENV === 'development')
*/
debug?: boolean;
/**
* Database configuration
*/
database?: {
/**
* Connection pool configuration
* Overrides environment variables and defaults
*/
pool?: {
/**
* Maximum number of connections in pool
* @default Production: 20, Development: 10
* @env DB_POOL_MAX
*/
max?: number;
/**
* Idle connection timeout in seconds
* @default Production: 30, Development: 20
* @env DB_POOL_IDLE_TIMEOUT
*/
idleTimeout?: number;
};
/**
* Health check configuration
* Periodic checks to ensure database connection is alive
*/
healthCheck?: {
/**
* Enable/disable health checks
* @default true
* @env DB_HEALTH_CHECK_ENABLED
*/
enabled?: boolean;
/**
* Health check interval in milliseconds
* @default 60000 (60 seconds)
* @env DB_HEALTH_CHECK_INTERVAL
*/
interval?: number;
/**
* Enable automatic reconnection on failure
* @default true
* @env DB_HEALTH_CHECK_RECONNECT
*/
reconnect?: boolean;
/**
* Maximum reconnection attempts
* @default 3
* @env DB_HEALTH_CHECK_MAX_RETRIES
*/
maxRetries?: number;
/**
* Delay between reconnection attempts in milliseconds
* @default 5000 (5 seconds)
* @env DB_HEALTH_CHECK_RETRY_INTERVAL
*/
retryInterval?: number;
};
/**
* Query performance monitoring configuration
* Tracks slow queries and logs performance metrics
*/
monitoring?: {
/**
* Enable/disable query performance monitoring
* @default true in development, false in production
* @env DB_MONITORING_ENABLED
*/
enabled?: boolean;
/**
* Slow query threshold in milliseconds
* Queries exceeding this duration will be logged as warnings
* @default 1000 (1 second)
* @env DB_MONITORING_SLOW_THRESHOLD
*/
slowThreshold?: number;
/**
* Log actual SQL queries in performance logs
* ⚠️ Warning: May expose sensitive data in logs
* @default false
* @env DB_MONITORING_LOG_QUERIES
*/
logQueries?: boolean;
};
};
/**
* Server timeout configuration
* Controls HTTP server timeout behavior for security and resource management
*/
timeout?: {
/**
* Request timeout in milliseconds
* Time limit for entire request/response cycle
* Set to 0 to disable (not recommended in production)
* @default 120000 (2 minutes)
* @env SERVER_TIMEOUT
*/
request?: number;
/**
* Keep-alive timeout in milliseconds
* How long to keep idle HTTP connections open for reuse
* Should be slightly longer than load balancer timeout (typically 60s)
* @default 65000 (65 seconds)
* @env SERVER_KEEPALIVE_TIMEOUT
*/
keepAlive?: number;
/**
* Headers timeout in milliseconds
* Time limit for receiving complete HTTP request headers
* Protects against Slowloris attacks
* @default 60000 (60 seconds)
* @env SERVER_HEADERS_TIMEOUT
*/
headers?: number;
};
/**
* Graceful shutdown configuration
* Controls server shutdown behavior during SIGTERM/SIGINT signals
*/
shutdown?: {
/**
* Graceful shutdown timeout in milliseconds
* Maximum time to wait for ongoing requests and resource cleanup
* After timeout, forces process termination
* @default 30000 (30 seconds)
* @env SHUTDOWN_TIMEOUT
*/
timeout?: number;
};
/**
* Health check endpoint configuration
* Provides monitoring endpoints for Kubernetes probes and load balancers
*/
healthCheck?: {
/**
* Enable health check endpoint
* @default true
* @env HEALTH_CHECK_ENABLED
*/
enabled?: boolean;
/**
* Health check endpoint path
* @default '/health'
* @env HEALTH_CHECK_PATH
*/
path?: string;
/**
* Include detailed status (DB, Redis, etc.)
* Detailed mode checks connectivity to external services
* @default false in production, true in development
* @env HEALTH_CHECK_DETAILED
*/
detailed?: boolean;
};
/**
* Hook: Run before routes are loaded
*/
beforeRoutes?: (app: Hono) => void | Promise<void>;
/**
* Hook: Run after routes are loaded
*/
afterRoutes?: (app: Hono) => void | Promise<void>;
}
/**
* App Factory Function
*
* Level 3: Full control with app.ts
*/
type AppFactory = () => Promise<Hono> | Hono;
/**
* Server Instance
*
* Returned by startServer() to provide access to server internals
* Allows programmatic control over the server lifecycle
*/
interface ServerInstance {
/**
* Underlying Node.js HTTP server
* Provides low-level access to the HTTP server instance
*/
server: ReturnType<typeof serve>;
/**
* Hono app instance
* Allows runtime route registration and middleware management
*/
app: Hono;
/**
* Final server configuration used
* Contains resolved values from all sources (runtime > file > env > defaults)
*/
config: ServerConfig;
/**
* Manually close the server
* Performs graceful shutdown: stops accepting connections, closes DB/Redis, exits process
*
* @example
* ```typescript
* const instance = await startServer({ port: 3000 });
*
* // Later...
* await instance.close(); // Clean shutdown
* ```
*/
close: () => Promise<void>;
}
/**
* Create Hono Server
*
* Creates and configures a Hono application instance.
*/
declare module 'hono' {
interface ContextVariableMap {
errorHandlerEnabled?: boolean;
}
}
/**
* Create Hono app with automatic configuration
*
* Levels:
* 1. No app.ts -> Full auto config
* 2. server.config.ts -> Partial customization
* 3. app.ts -> Full control (no auto config)
*/
declare function createServer(config?: ServerConfig): Promise<Hono>;
/**
* Start SPFN Server
*
* Starts and configures the SPFN HTTP server with graceful shutdown.
*/
/**
* Start SPFN server
*
* Automatically loads server.config.ts if exists
* Automatically initializes Database and Redis from environment
* Sets up graceful shutdown handlers for SIGTERM and SIGINT
*
* @returns ServerInstance with server, app, config, and close() method
*/
declare function startServer(config?: ServerConfig): Promise<ServerInstance>;
export { type AppFactory, type ServerConfig, type ServerInstance, createServer, startServer };