suthep 0.1.0

package/docs/api-reference.md

@@ -0,0 +1,545 @@
+# 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);
+  }
+}
+```