Server Lifecycle

/**
 * Creates a new Fastify server instance
 * @param options - Server configuration options
 * @returns FastifyInstance for method chaining
 */
function fastify(options?: FastifyServerOptions): FastifyInstance;

// Basic server creation
const fastify = require('fastify')();

// Server with logging enabled
const fastify = require('fastify')({ logger: true });

// Server with custom configuration
const fastify = require('fastify')({
  logger: {
    level: 'info',
    prettyPrint: true
  },
  bodyLimit: 1048576, // 1MB
  trustProxy: true
});

/**
 * Start the server and listen for connections
 * @param opts - Listen options including port, host, and other server options
 * @returns Promise resolving to the server address string
 */
listen(opts?: FastifyListenOptions): Promise<string>;

/**
 * Start the server with callback-style error handling
 * @param opts - Listen options
 * @param callback - Callback function called when server starts or fails
 */
listen(opts: FastifyListenOptions, callback: (err: Error | null, address: string) => void): void;

/**
 * Start the server with only callback (uses default options)
 * @param callback - Callback function called when server starts or fails
 */
listen(callback: (err: Error | null, address: string) => void): void;

interface FastifyListenOptions {
  port?: number;          // Default: 0 (picks first available port)
  host?: string;          // Default: 'localhost'
  path?: string;          // For IPC servers, ignored if port is specified
  backlog?: number;       // Default: 511
  exclusive?: boolean;    // Default: false
  readableAll?: boolean;  // For IPC servers, default: false
  writableAll?: boolean;  // For IPC servers, default: false
  ipv6Only?: boolean;     // Default: false
  signal?: AbortSignal;   // For graceful shutdown
  listenTextResolver?: (address: string) => string; // Custom listen message
}

// Promise-based listening
const start = async () => {
  try {
    const address = await fastify.listen({ port: 3000, host: '0.0.0.0' });
    console.log(`Server listening at ${address}`);
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

// Callback-based listening
fastify.listen({ port: 3000 }, (err, address) => {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }
  console.log(`Server listening at ${address}`);
});

// With AbortSignal for graceful shutdown
const controller = new AbortController();
await fastify.listen({ 
  port: 3000, 
  signal: controller.signal 
});

// Later: controller.abort(); // Gracefully closes server

/**
 * Close the server and call onClose hooks
 * @returns Promise that resolves when server is closed
 */
close(): Promise<undefined>;

/**
 * Close the server with callback
 * @param closeListener - Callback called when server is closed
 */
close(closeListener: () => void): undefined;

// Promise-based close
await fastify.close();

// Callback-based close
fastify.close(() => {
  console.log('Server closed');
});

// Graceful shutdown pattern
process.on('SIGINT', async () => {
  try {
    await fastify.close();
    console.log('Server closed gracefully');
    process.exit(0);
  } catch (err) {
    console.error('Error during shutdown:', err);
    process.exit(1);
  }
});

/**
 * Wait for all plugins to load and server to be ready
 * @returns FastifyInstance and Promise for method chaining
 */
ready(): FastifyInstance & Promise<undefined>;

/**
 * Wait for server ready with callback
 * @param readyListener - Callback called when ready or on error
 */
ready(readyListener: (err: Error | null) => void | Promise<void>): FastifyInstance;

// Promise-based ready
await fastify.ready();
console.log('Server is ready');

// Callback-based ready
fastify.ready((err) => {
  if (err) {
    console.error('Server failed to start:', err);
    return;
  }
  console.log('Server is ready');
});

// Chaining with other operations
await fastify
  .register(somePlugin)
  .ready();

/**
 * Get all server addresses (useful for multiple bindings)
 * @returns Array of address information objects
 */
addresses(): AddressInfo[];

interface AddressInfo {
  address: string;
  family: string;
  port: number;
}

interface FastifyInstance {
  server: RawServer;           // Underlying HTTP server instance
  listeningOrigin: string;     // Server listening origin URL (getter)
  version: string;             // Fastify version (getter)
  log: FastifyLoggerInstance;  // Logger instance
  initialConfig: object;       // Read-only initial configuration
}

// Get server addresses
const addresses = fastify.addresses();
console.log('Server listening on:', addresses);

// Access underlying server
const httpServer = fastify.server;
httpServer.timeout = 30000; // Set 30 second timeout

// Get listening origin
console.log('Origin:', fastify.listeningOrigin);
// Output: "http://localhost:3000"

// Check Fastify version
console.log('Fastify version:', fastify.version);

/**
 * Direct routing function for handling raw HTTP requests
 * @param req - Raw HTTP request
 * @param res - Raw HTTP response
 */
routing(req: RawRequest, res: RawReply): void;