suthep 0.1.0 → 0.2.0-beta.1

package/docs/api-reference.md

@@ -1,545 +0,0 @@
-# API Reference
-
-This document provides detailed reference for Suthep's internal APIs and utility functions.
-
-## Configuration Loader
-
-**File**: `src/utils/config-loader.ts`
-
-### `loadConfig(filePath: string): Promise<DeployConfig>`
-
-Loads and parses a YAML configuration file.
-
-**Parameters**:
-- `filePath`: Path to the configuration file
-
-**Returns**: Promise resolving to `DeployConfig` object
-
-**Throws**: Error if file doesn't exist or is invalid
-
-**Example**:
-```typescript
-const config = await loadConfig('suthep.yml');
-```
-
-### `saveConfig(filePath: string, config: DeployConfig): Promise<void>`
-
-Saves a configuration object to a YAML file.
-
-**Parameters**:
-- `filePath`: Path where to save the configuration
-- `config`: Configuration object to save
-
-**Returns**: Promise that resolves when file is saved
-
-**Example**:
-```typescript
-await saveConfig('suthep.yml', config);
-```
-
-## Docker Utilities
-
-**File**: `src/utils/docker.ts`
-
-### `startDockerContainer(service: ServiceConfig): Promise<void>`
-
-Starts or connects to a Docker container for a service.
-
-**Parameters**:
-- `service`: Service configuration with Docker settings
-
-**Returns**: Promise that resolves when container is running
-
-**Throws**: Error if container can't be started
-
-**Behavior**:
-- If container exists and is running: Does nothing
-- If container exists but is stopped: Starts it
-- If container doesn't exist and image provided: Creates and runs new container
-- If container doesn't exist and no image: Throws error
-
-**Example**:
-```typescript
-await startDockerContainer(service);
-```
-
-### `stopDockerContainer(containerName: string): Promise<void>`
-
-Stops a running Docker container.
-
-**Parameters**:
-- `containerName`: Name of the container to stop
-
-**Returns**: Promise that resolves when container is stopped
-
-**Throws**: Error if container can't be stopped
-
-**Example**:
-```typescript
-await stopDockerContainer('my-container');
-```
-
-### `removeDockerContainer(containerName: string): Promise<void>`
-
-Removes a Docker container (force stop and remove).
-
-**Parameters**:
-- `containerName`: Name of the container to remove
-
-**Returns**: Promise that resolves when container is removed
-
-**Throws**: Error if container can't be removed
-
-**Example**:
-```typescript
-await removeDockerContainer('my-container');
-```
-
-### `isContainerRunning(containerName: string): Promise<boolean>`
-
-Checks if a Docker container is currently running.
-
-**Parameters**:
-- `containerName`: Name of the container to check
-
-**Returns**: Promise resolving to `true` if running, `false` otherwise
-
-**Example**:
-```typescript
-const running = await isContainerRunning('my-container');
-```
-
-### `getContainerLogs(containerName: string, lines?: number): Promise<string>`
-
-Retrieves logs from a Docker container.
-
-**Parameters**:
-- `containerName`: Name of the container
-- `lines`: Number of log lines to retrieve (default: 100)
-
-**Returns**: Promise resolving to log output as string
-
-**Throws**: Error if logs can't be retrieved
-
-**Example**:
-```typescript
-const logs = await getContainerLogs('my-container', 50);
-```
-
-### `inspectContainer(containerName: string): Promise<any>`
-
-Inspects a Docker container and returns its configuration.
-
-**Parameters**:
-- `containerName`: Name of the container to inspect
-
-**Returns**: Promise resolving to container inspection object
-
-**Throws**: Error if container can't be inspected
-
-**Example**:
-```typescript
-const info = await inspectContainer('my-container');
-```
-
-## Nginx Utilities
-
-**File**: `src/utils/nginx.ts`
-
-### `generateNginxConfig(service: ServiceConfig, withHttps: boolean): string`
-
-Generates Nginx server block configuration for a service.
-
-**Parameters**:
-- `service`: Service configuration
-- `withHttps`: Whether to include HTTPS configuration
-
-**Returns**: Nginx configuration as string
-
-**Example**:
-```typescript
-const config = generateNginxConfig(service, true);
-```
-
-**Generated Configuration Includes**:
-- Upstream definition
-- HTTP server (with HTTPS redirect if enabled)
-- HTTPS server (if enabled)
-- SSL configuration (if enabled)
-- Proxy settings
-- Health check endpoint (if configured)
-- Logging configuration
-
-### `enableSite(siteName: string, configPath: string): Promise<void>`
-
-Enables an Nginx site by creating a symbolic link in `sites-enabled`.
-
-**Parameters**:
-- `siteName`: Name of the site (without .conf extension)
-- `configPath`: Path to sites-available directory
-
-**Returns**: Promise that resolves when site is enabled
-
-**Example**:
-```typescript
-await enableSite('my-service', '/etc/nginx/sites-available');
-```
-
-### `disableSite(siteName: string, configPath: string): Promise<void>`
-
-Disables an Nginx site by removing the symbolic link.
-
-**Parameters**:
-- `siteName`: Name of the site
-- `configPath`: Path to sites-available directory
-
-**Returns**: Promise that resolves when site is disabled
-
-**Example**:
-```typescript
-await disableSite('my-service', '/etc/nginx/sites-available');
-```
-
-### `reloadNginx(reloadCommand: string): Promise<void>`
-
-Tests and reloads Nginx configuration.
-
-**Parameters**:
-- `reloadCommand`: Command to execute for reloading
-
-**Returns**: Promise that resolves when Nginx is reloaded
-
-**Throws**: Error if Nginx configuration test fails or reload fails
-
-**Example**:
-```typescript
-await reloadNginx('sudo nginx -t && sudo systemctl reload nginx');
-```
-
-## Certbot Utilities
-
-**File**: `src/utils/certbot.ts`
-
-### `requestCertificate(domain: string, email: string, staging?: boolean): Promise<void>`
-
-Requests an SSL certificate from Let's Encrypt using Certbot.
-
-**Parameters**:
-- `domain`: Domain name for the certificate
-- `email`: Email address for certificate notifications
-- `staging`: Use staging environment (default: false)
-
-**Returns**: Promise that resolves when certificate is obtained
-
-**Throws**: Error if certificate request fails
-
-**Example**:
-```typescript
-await requestCertificate('example.com', 'admin@example.com', false);
-```
-
-### `renewCertificates(): Promise<void>`
-
-Renews all SSL certificates that are due for renewal.
-
-**Returns**: Promise that resolves when renewal is complete
-
-**Throws**: Error if renewal fails
-
-**Example**:
-```typescript
-await renewCertificates();
-```
-
-### `checkCertificateExpiration(domain: string): Promise<Date | null>`
-
-Checks the expiration date of a certificate for a domain.
-
-**Parameters**:
-- `domain`: Domain name to check
-
-**Returns**: Promise resolving to expiration date or `null` if not found
-
-**Example**:
-```typescript
-const expiry = await checkCertificateExpiration('example.com');
-if (expiry) {
-  console.log(`Certificate expires on: ${expiry}`);
-}
-```
-
-### `revokeCertificate(domain: string): Promise<void>`
-
-Revokes an SSL certificate for a domain.
-
-**Parameters**:
-- `domain`: Domain name whose certificate to revoke
-
-**Returns**: Promise that resolves when certificate is revoked
-
-**Throws**: Error if revocation fails
-
-**Example**:
-```typescript
-await revokeCertificate('example.com');
-```
-
-## Deployment Utilities
-
-**File**: `src/utils/deployment.ts`
-
-### `deployService(service: ServiceConfig, deploymentConfig: DeploymentConfig): Promise<void>`
-
-Deploys a service using the configured deployment strategy.
-
-**Parameters**:
-- `service`: Service configuration
-- `deploymentConfig`: Deployment strategy configuration
-
-**Returns**: Promise that resolves when service is deployed
-
-**Throws**: Error if deployment fails
-
-**Example**:
-```typescript
-await deployService(service, deploymentConfig);
-```
-
-### `performHealthCheck(url: string, timeout?: number): Promise<boolean>`
-
-Performs a health check on a service endpoint.
-
-**Parameters**:
-- `url`: Health check endpoint URL
-- `timeout`: Maximum time to wait in milliseconds (default: 30000)
-
-**Returns**: Promise resolving to `true` if healthy, `false` if timeout
-
-**Behavior**:
-- Polls endpoint every 2 seconds
-- Returns `true` on first successful (200 OK) response
-- Returns `false` if timeout is exceeded
-
-**Example**:
-```typescript
-const isHealthy = await performHealthCheck('http://localhost:3000/health', 30000);
-```
-
-### `waitForService(service: ServiceConfig, timeout?: number): Promise<boolean>`
-
-Waits for a service to become healthy.
-
-**Parameters**:
-- `service`: Service configuration
-- `timeout`: Maximum time to wait in milliseconds (default: 60000)
-
-**Returns**: Promise resolving to `true` if service becomes healthy
-
-**Example**:
-```typescript
-const ready = await waitForService(service, 60000);
-```
-
-### `gracefulShutdown(service: ServiceConfig, timeout?: number): Promise<void>`
-
-Gracefully shuts down a service.
-
-**Parameters**:
-- `service`: Service configuration
-- `timeout`: Maximum time to wait for shutdown (default: 30000)
-
-**Returns**: Promise that resolves when shutdown is complete
-
-**Note**: This is a placeholder implementation. Actual implementation depends on service management.
-
-**Example**:
-```typescript
-await gracefulShutdown(service, 30000);
-```
-
-## Type Definitions
-
-**File**: `src/types/config.ts`
-
-### `DeployConfig`
-
-Root configuration interface.
-
-```typescript
-interface DeployConfig {
-  project: ProjectConfig;
-  services: ServiceConfig[];
-  nginx: NginxConfig;
-  certbot: CertbotConfig;
-  deployment: DeploymentConfig;
-}
-```
-
-### `ProjectConfig`
-
-Project metadata.
-
-```typescript
-interface ProjectConfig {
-  name: string;
-  version: string;
-}
-```
-
-### `ServiceConfig`
-
-Service configuration.
-
-```typescript
-interface ServiceConfig {
-  name: string;
-  port: number;
-  domains: string[];
-  docker?: DockerConfig;
-  healthCheck?: HealthCheckConfig;
-  environment?: Record<string, string>;
-}
-```
-
-### `DockerConfig`
-
-Docker container configuration.
-
-```typescript
-interface DockerConfig {
-  image?: string;
-  container: string;
-  port: number;
-}
-```
-
-### `HealthCheckConfig`
-
-Health check configuration.
-
-```typescript
-interface HealthCheckConfig {
-  path: string;
-  interval: number;
-}
-```
-
-### `NginxConfig`
-
-Nginx configuration.
-
-```typescript
-interface NginxConfig {
-  configPath: string;
-  reloadCommand: string;
-}
-```
-
-### `CertbotConfig`
-
-Certbot/SSL configuration.
-
-```typescript
-interface CertbotConfig {
-  email: string;
-  staging: boolean;
-}
-```
-
-### `DeploymentConfig`
-
-Deployment strategy configuration.
-
-```typescript
-interface DeploymentConfig {
-  strategy: 'rolling' | 'blue-green';
-  healthCheckTimeout: number;
-}
-```
-
-## Command Handlers
-
-### `initCommand(options: InitOptions): Promise<void>`
-
-**File**: `src/commands/init.ts`
-
-Interactive configuration file creation.
-
-**Parameters**:
-- `options.file`: Configuration file path (default: 'suthep.yml')
-
-### `setupCommand(options: SetupOptions): Promise<void>`
-
-**File**: `src/commands/setup.ts`
-
-Install and configure prerequisites.
-
-**Parameters**:
-- `options.nginxOnly`: Only setup Nginx
-- `options.certbotOnly`: Only setup Certbot
-
-### `deployCommand(options: DeployOptions): Promise<void>`
-
-**File**: `src/commands/deploy.ts`
-
-Deploy services using configuration.
-
-**Parameters**:
-- `options.file`: Configuration file path (default: 'suthep.yml')
-- `options.https`: Enable HTTPS (default: true)
-- `options.nginx`: Configure Nginx (default: true)
-
-## Error Handling
-
-All functions throw errors with descriptive messages. Common error patterns:
-
-- **File operations**: `Error: Configuration file not found: ...`
-- **Docker operations**: `Error: Failed to start Docker container: ...`
-- **Nginx operations**: `Error: Failed to reload Nginx: ...`
-- **Certbot operations**: `Error: Failed to obtain SSL certificate for ...: ...`
-- **Health checks**: `Error: Service ... failed health check ...`
-
-## Usage Examples
-
-### Custom Deployment Script
-
-```typescript
-import { loadConfig } from './utils/config-loader';
-import { startDockerContainer } from './utils/docker';
-import { generateNginxConfig, enableSite, reloadNginx } from './utils/nginx';
-import { requestCertificate } from './utils/certbot';
-import { performHealthCheck } from './utils/deployment';
-
-async function customDeploy() {
-  const config = await loadConfig('suthep.yml');
-
-  for (const service of config.services) {
-    // Start Docker container
-    if (service.docker) {
-      await startDockerContainer(service);
-    }
-
-    // Generate and enable Nginx config
-    const nginxConfig = generateNginxConfig(service, false);
-    // ... write config file ...
-    await enableSite(service.name, config.nginx.configPath);
-
-    // Request certificate
-    for (const domain of service.domains) {
-      await requestCertificate(domain, config.certbot.email, config.certbot.staging);
-    }
-
-    // Health check
-    if (service.healthCheck) {
-      const url = `http://localhost:${service.port}${service.healthCheck.path}`;
-      const healthy = await performHealthCheck(url, 30000);
-      if (!healthy) {
-        throw new Error(`Service ${service.name} is not healthy`);
-      }
-    }
-
-    // Reload Nginx
-    await reloadNginx(config.nginx.reloadCommand);
-  }
-}
-```