fix(clamav.manager): Improve log handling and add timeout for log reception in ClamAV manager tests

readme.md

@@ -1,28 +1,72 @@
 # @push.rocks/smartantivirus
 
-A package for performing antivirus testing, especially suitable for use with ClamAV. 
+A package for performing antivirus testing with ClamAV, featuring both direct daemon communication and Docker container management.
+
+## Features
+
+- **Docker Integration**: Automatically manages ClamAV containers for easy setup and testing
+- **Real-time Logging**: Captures and processes ClamAV logs with type-safe event handling
+- **Database Management**: Supports automatic database updates and version tracking
+- **Flexible Scanning**: Scan strings, buffers, and files for malware
+- **Health Monitoring**: Built-in service readiness checks and connection verification
 
 ## Install
 
-Installing `@push.rocks/smartantivirus` is straightforward. You'll need Node.js and npm installed on your machine to get started. Once they are ready, you can add the `@push.rocks/smartantivirus` package to your project by running the following command:
+Installing `@push.rocks/smartantivirus` is straightforward. You'll need Node.js and npm installed on your machine:
 
 ```bash
 npm install @push.rocks/smartantivirus
 ```
 
-This will add the package to your project's dependencies and allow you to integrate antivirus scanning capabilities directly into your application.
+### Prerequisites
+
+- Node.js and npm
+- Docker (for container-based usage)
+- ClamAV daemon (for direct daemon usage)
 
 ## Usage
 
-The `@push.rocks/smartantivirus` package provides tools to easily integrate antivirus scanning capabilities into your Node.js application by interfacing with the ClamAV daemon. Below is a comprehensive guide on how to use the features of this library.
+The package provides two main ways to use ClamAV:
 
-### Setting Up the ClamAV Daemon
+1. **Docker-based Usage** (Recommended): Uses `ClamAVManager` to automatically handle container lifecycle
+2. **Direct Daemon Usage**: Uses `ClamAvService` to communicate with an existing ClamAV daemon
 
-Before using this package, make sure you have ClamAV installed and running on your system. You can find installation instructions for various operating systems on the [ClamAV official website](https://www.clamav.net/documents/installing-clamav).
+Below is a comprehensive guide on how to use both approaches.
 
-After installing ClamAV, start the ClamAV daemon (`clamd`). Make sure it is configured to listen on a port accessible to your Node.js application. You can configure this in the `clamd.conf` file, typically located in `/etc/clamav/clamd.conf`.
+### Docker-based Usage with ClamAVManager
 
-### Basic Usage 
+The `ClamAVManager` class provides a high-level interface for managing ClamAV in Docker containers:
+
+```typescript
+import { ClamAVManager } from '@push.rocks/smartantivirus';
+
+async function main() {
+  // Create a new manager instance
+  const manager = new ClamAVManager();
+
+  // Start the ClamAV container
+  await manager.startContainer();
+
+  // Listen for log events
+  manager.on('log', (event) => {
+    console.log(`[ClamAV ${event.type}] ${event.message}`);
+  });
+
+  // Get database information
+  const dbInfo = await manager.getDatabaseInfo();
+  console.log('Database Info:', dbInfo);
+
+  // Update virus definitions
+  await manager.updateDatabase();
+
+  // When done, stop the container
+  await manager.stopContainer();
+}
+
+main().catch(console.error);
+```
+
+### Direct Daemon Usage with ClamAvService
 
 The primary interface provided by the package is the `ClamAvService` class. It allows you to scan data in memory or verify the connection to the ClamAV daemon.
 
@@ -89,11 +133,24 @@ scanBufferExample();
 
 ### Error Handling and Debugging
 
-The methods of `ClamAvService` throw errors if there are issues with communication or processing data. Wrap your code in try-catch blocks and use appropriate logging to handle errors gracefully.
+Both `ClamAVManager` and `ClamAvService` provide comprehensive error handling:
 
 ```typescript
 try {
-  const scanResult = await clamService.scanString('Some suspicious string...');
+  // Using ClamAVManager
+  const manager = new ClamAVManager();
+  await manager.startContainer();
+  
+  // Listen for errors in logs
+  manager.on('log', (event) => {
+    if (event.type === 'error') {
+      console.error(`ClamAV Error: ${event.message}`);
+    }
+  });
+
+  // Using ClamAvService
+  const service = new ClamAvService();
+  const scanResult = await service.scanString('Some suspicious string...');
   console.log(`Infection Status: ${scanResult.isInfected ? 'Infected' : 'Clean'}`);
   if (scanResult.isInfected) {
     console.log(`Reason: ${scanResult.reason}`);
@@ -115,6 +172,52 @@ The tests include creating and utilizing a `ClamAvService` instance and attempts
 
 ### Advanced Usage and Integration
 
-Beyond scanning strings and buffers, you can implement additional advanced use cases based on your specific application needs, such as integrating into web services or automating file scans in cloud environments. Consider building upon provided functionalities and adapting them to meet the requirements of your application architecture.
+#### Container Configuration
+
+The `ClamAVManager` supports customizing the Docker container:
+
+```typescript
+const manager = new ClamAVManager();
+
+// Container properties are configurable
+console.log(manager.containerName); // 'clamav-daemon'
+console.log(manager.port); // 3310
+```
+
+#### Log Management
+
+Access and process ClamAV logs:
+
+```typescript
+const manager = new ClamAVManager();
+
+// Get all logs
+const logs = manager.getLogs();
+
+// Filter logs by type
+const errorLogs = logs.filter(log => log.type === 'error');
+const updateLogs = logs.filter(log => log.type === 'update');
+```
+
+#### Health Checks
+
+Monitor ClamAV service health:
+
+```typescript
+const manager = new ClamAVManager();
+
+// Service automatically checks readiness during initialization
+await manager.startContainer(); // Includes readiness checks
+
+// Get database status
+const dbInfo = await manager.getDatabaseInfo();
+console.log('Database Version:', dbInfo);
+```
+
+You can build upon these functionalities to implement advanced use cases such as:
+- Automated virus scanning in CI/CD pipelines
+- Real-time file monitoring in web applications
+- Cloud-based malware detection services
+- Integration with security information and event management (SIEM) systems
 
 With the help of Node.js worker threads or external task queues like RabbitMQ, you can distribute scanning tasks efficiently within high-traffic environments.