ClamClient.Net 1.2.1

ClamClient.Net

Async .NET client library for ClamAV (clamd) with TCP and Unix socket support, and built-in connection pooling.

Features

• Scan files and arbitrary byte streams via INSTREAM
• TCP and Unix domain socket endpoints
• Full async/await with CancellationToken support
• Built-in connection pool — reuses IDSESSION connections to reduce per-request overhead
• Microsoft DI integration (AddClamClient) — registers IClamClient as a singleton backed by the pool
• No external runtime dependencies beyond Microsoft.Extensions.DependencyInjection.Abstractions and Microsoft.Extensions.Options

Requirements

• .NET Standard 2.0 or .NET 8+
• A running clamd daemon

Quick way to get a daemon running locally:

docker run -p 3310:3310 clamav/clamav:latest

Installation

dotnet add package ClamClient.Net

Quick start

Direct instantiation

using ClamClient.Net;
using ClamClient.Net.Configuration;
using ClamClient.Net.Results;

var options = new ClamClientOptions
{
    Endpoint = ClamEndpoint.Tcp("localhost", 3310),
};

var client = new ClamAVClient(options);

bool alive = await client.PingAsync();
string version = await client.GetVersionAsync();

// Scan a stream
using var stream = File.OpenRead("/path/to/upload");
ScanResult result = await client.ScanStreamAsync(stream);

if (result.Status == ScanStatus.ThreatFound)
{
    foreach (var threat in result.Threats)
        Console.WriteLine($"Threat detected: {threat.ThreatName}");
}

Dependency Injection (ASP.NET Core / Generic Host)

// Program.cs
builder.Services.AddClamClient(options =>
{
    options.Endpoint = ClamEndpoint.Tcp("localhost", 3310);
    options.Timeout = TimeSpan.FromSeconds(15);
});

Inject IClamClient wherever you need it:

public class UploadService(IClamClient clamClient)
{
    public async Task<bool> IsSafeAsync(Stream file, CancellationToken ct = default)
    {
        var result = await clamClient.ScanStreamAsync(file, ct);
        return result.Status == ScanStatus.Clean;
    }
}

AddClamClient also registers IOptions<ClamClientOptions>, so you can inject it directly if you need to read the resolved options at runtime.

Unix domain socket (Linux / macOS)

var options = new ClamClientOptions
{
    Endpoint = ClamEndpoint.UnixSocket("/var/run/clamav/clamd.sock"),
};

Unix domain sockets require .NET 5 or later.

Connection pool

ClamAVClient owns an internal pool of IDSESSION connections. Each connection sends zIDSESSION\0 once on open and remains open for subsequent commands, eliminating the TCP handshake and ClamAV session-setup cost on every scan.

How it works:

• When a command is issued, the pool hands out an idle connection or opens a new one.
• While a connection is in use, it occupies one slot toward MaxConnections.
• When the call returns, the connection is checked back in and reused by the next caller.
• When all slots are occupied, further callers wait until a connection becomes available (subject to the operation's CancellationToken).
• Connections idle for longer than IdleConnectionTimeout are evicted and closed automatically.

Tuning:

Dispose ClamAVClient (or the DI container) when the application exits — this sends zEND\0 on every idle connection and closes the pool cleanly.

API reference

IClamClient

ClamClientOptions

ScanResult

StreamTooLarge is returned by ScanStreamAsync when the stream exceeds MaxStreamSize. No data is sent to clamd in this case.

Exceptions

License

MIT

ClamClient.Net（中文说明）

适用于 ClamAV（clamd）的异步 .NET 客户端库，支持 TCP 和 Unix 套接字，内置连接池。

功能特性

• 通过 INSTREAM 扫描文件及任意字节流
• 支持 TCP 和 Unix 域套接字端点
• 完整的 async/await 支持，含 CancellationToken
• 内置连接池——复用 IDSESSION 连接，降低每次请求的开销
• Microsoft DI 集成（AddClamClient）——将 IClamClient 注册为由连接池支撑的单例
• 除 Microsoft.Extensions.DependencyInjection.Abstractions 和 Microsoft.Extensions.Options 外无额外运行时依赖

环境要求

• .NET Standard 2.0 或 .NET 8+
• 正在运行的 clamd 守护进程

本地快速启动守护进程：

docker run -p 3310:3310 clamav/clamav:latest

安装

dotnet add package ClamClient.Net

快速入门

直接实例化

using ClamClient.Net;
using ClamClient.Net.Configuration;
using ClamClient.Net.Results;

var options = new ClamClientOptions
{
    Endpoint = ClamEndpoint.Tcp("localhost", 3310),
};

var client = new ClamAVClient(options);

bool alive = await client.PingAsync();
string version = await client.GetVersionAsync();

// 扫描流
using var stream = File.OpenRead("/path/to/upload");
ScanResult result = await client.ScanStreamAsync(stream);

if (result.Status == ScanStatus.ThreatFound)
{
    foreach (var threat in result.Threats)
        Console.WriteLine($"检测到威胁：{threat.ThreatName}");
}

依赖注入（ASP.NET Core / Generic Host）

// Program.cs
builder.Services.AddClamClient(options =>
{
    options.Endpoint = ClamEndpoint.Tcp("localhost", 3310);
    options.Timeout = TimeSpan.FromSeconds(15);
});

在需要的地方注入 IClamClient：

public class UploadService(IClamClient clamClient)
{
    public async Task<bool> IsSafeAsync(Stream file, CancellationToken ct = default)
    {
        var result = await clamClient.ScanStreamAsync(file, ct);
        return result.Status == ScanStatus.Clean;
    }
}

AddClamClient 同时注册了 IOptions<ClamClientOptions>，如需在运行时读取已解析的选项，可直接注入它。

Unix 域套接字（Linux / macOS）

var options = new ClamClientOptions
{
    Endpoint = ClamEndpoint.UnixSocket("/var/run/clamav/clamd.sock"),
};

Unix 域套接字需要 .NET 5 或更高版本。

连接池

ClamAVClient 内部维护一个 IDSESSION 连接池。每条连接在打开时发送一次 zIDSESSION\0 并保持不关闭，后续命令复用同一连接，从而消除每次扫描的 TCP 握手和 ClamAV 会话建立开销。

工作原理：

• 发出命令时，连接池提供一个空闲连接，若无空闲则新建连接。
• 连接使用中时，占用 MaxConnections 计数中的一个槽位。
• 调用返回后，连接归还连接池，供下一个调用方复用。
• 所有槽位均已占用时，后续调用方等待，直到有连接释放（受操作的 CancellationToken 控制）。
• 空闲时长超过 IdleConnectionTimeout 的连接会被自动驱逐并关闭。

调优建议：

应用退出时请 Dispose ClamAVClient（或 DI 容器）——这会向所有空闲连接发送 zEND\0 并干净地关闭连接池。

API 参考

IClamClient

ClamClientOptions

ScanResult

StreamTooLarge 由 ScanStreamAsync 在流超过 MaxStreamSize 时返回，此时不会向 clamd 发送任何数据。

异常

许可证

MIT