Quick check to see if the remote/local socket is working. Callback/Resolve
+response is an instance to a ClamAV socket client.
+
+
+
## Functions
@@ -26,7 +35,7 @@ By default, it will retrieve files recursively.
## NodeClam
-NodeClam class definition. To cf
+NodeClam class definition.
**Kind**: global class
@@ -55,6 +64,7 @@ Initialization method.
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Promise.<object> - An initated instance of NodeClam
+**Access**: public
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@@ -125,6 +135,7 @@ Allows one to create a new instances of clamscan with new options.
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Promise.<object> - A reset instance of NodeClam
+**Access**: public
| Param | Type | Description |
| --- | --- | --- |
@@ -138,6 +149,7 @@ Establish the clamav version of a local or remote clamav daemon.
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Promise.<string> - - The version of ClamAV that is being interfaced with
+**Access**: public
| Param | Type | Description |
| --- | --- | --- |
@@ -165,6 +177,7 @@ be the most common use-case for this module.
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Promise.<object> - Object like: `{ file: String, isInfected: Boolean, viruses: Array }`
+**Access**: public
| Param | Type | Description |
| --- | --- | --- |
@@ -208,6 +221,7 @@ destination (ex. delete a file or S3 object).
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Transform - A Transform stream for piping a Readable stream into
+**Access**: public
**Example**
```js
const NodeClam = require('clamscan');
@@ -257,6 +271,7 @@ Just an alias to `isInfected`. See docs for that for usage examples.
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Promise.<object> - Object like: `{ file: String, isInfected: Boolean, viruses: Array }`
+**Access**: public
| Param | Type | Description |
| --- | --- | --- |
@@ -276,6 +291,7 @@ of scanning many files or directories.
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Promise.<object> - Object like: `{ goodFiles: Array, badFiles: Array, errors: Object, viruses: Array }`
+**Access**: public
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@@ -333,6 +349,7 @@ method also allows for non-recursive scanning with the clamdscan binary.
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Promise.<object> - Object like: `{ path: String, isInfected: Boolean, goodFiles: Array, badFiles: Array, viruses: Array }`
+**Access**: public
| Param | Type | Default | Description |
| --- | --- | --- | --- |
@@ -368,6 +385,7 @@ have access to a local ClamAV binary.
**Kind**: instance method of [NodeClam](#NodeClam)
**Returns**: Promise.<object> - Object like: `{ file: String, isInfected: Boolean, viruses: Array } `
+**Access**: public
| Param | Type | Description |
| --- | --- | --- |
@@ -470,6 +488,20 @@ This will flush out the stream when all data has been received.
| --- | --- | --- |
| cb | function | What to do when done |
+
+
+## ping ⇒ Promise.<object>
+Quick check to see if the remote/local socket is working. Callback/Resolve
+response is an instance to a ClamAV socket client.
+
+**Kind**: global variable
+**Returns**: Promise.<object> - A copy of the Socket/TCP client
+**Access**: public
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [cb] | function | What to do after the ping |
+
## getFiles(dir, [recursive]) ⇒ Array
diff --git a/README.md b/README.md
index 4d63011..9c33475 100755
--- a/README.md
+++ b/README.md
@@ -31,6 +31,7 @@ If you are migrating from v0.8.5 or less to v1.0.0 or greater, please read the [
- [scanFiles](#scanFiles)
- [scanStream](#scanStream)
- [passthrough](#passthrough)
+ - [ping](#ping)
- [Contribute](#contribute)
- [Resources used to help develop this module](#resources-used-to-help-develop-this-module)
@@ -652,6 +653,66 @@ output.on('finish', () => {
// NOTE: no errors (or other events) are being handled in this example but standard errors will be emitted according to NodeJS's Stream specifications
```
+
+
+## .ping()
+
+This method checks to see if the remote/local socket is working. It supports a callback and Promise API. If no callback is supplied, a Promise will be returned. This method can be used for healthcheck purposes and is already implicitly used during scan.
+
+### Parameters
+
+- `callback` (function) (optional) Will be called after the ping:
+
+ - `err` (object or null) A standard JavaScript Error object (null if no error)
+ - `client` (object) A copy of the Socket/TCP client
+
+### Returns
+
+- Promise
+
+ - Promise resolution returns: `client` (object): A copy of the Socket/TCP client
+
+### Examples
+
+**Callback Example:**
+
+```javascript
+const NodeClam = require('clamscan');
+
+// You'll need to specify your socket or TCP connection info
+const clamscan = new NodeClam().init({
+ clamdscan: {
+ socket: '/var/run/clamd.scan/clamd.sock',
+ host: '127.0.0.1',
+ port: 3310,
+ }
+});
+
+clamscan.ping((err, client) => {
+ if (err) return console.error(err);
+ console.log('ClamAV is still working!');
+ client.end();
+});
+```
+
+**Promise Example:**
+
+```javascript
+clamscan.ping().then((client) => {
+ console.log('ClamAV is still working!');
+ client.end();
+}).catch(err => {
+ console.error(err);
+};
+```
+
+**Promise Example:**
+
+```javascript
+const client = await clamscan.ping();
+client.end();
+```
+
# Contribute
Got a missing feature you'd like to use? Found a bug? Go ahead and fork this repo, build the feature and issue a pull request.
diff --git a/index.js b/index.js
index bdbe0f4..0e4c618 100755
--- a/index.js
+++ b/index.js
@@ -2,7 +2,7 @@
/* eslint-disable no-async-promise-executor */
/*!
* Node - Clam
- * Copyright(c) 2013-2020 Kyle Farris
+ * Copyright(c) 2013-2024 Kyle Farris
* MIT Licensed
*/
@@ -31,7 +31,7 @@ const fsStat = fsPromises.stat;
const cpExecFile = promisify(execFile);
/**
- * NodeClam class definition. To cf
+ * NodeClam class definition.
*
* @typicalname NodeClam
*/
@@ -39,6 +39,8 @@ class NodeClam {
/**
* This sets up all the defaults of the instance but does not
* necessarily return an initialized instance. Use `.init` for that.
+ *
+ * @constructor
*/
constructor() {
this.initialized = false;
@@ -82,6 +84,7 @@ class NodeClam {
/**
* Initialization method.
*
+ * @public
* @param {object} [options] - User options for the Clamscan module
* @param {boolean} [options.removeInfected=false] - If true, removes infected files when found
* @param {boolean|string} [options.quarantineInfected=false] - If not false, should be a string to a path to quarantine infected files
@@ -326,7 +329,7 @@ class NodeClam {
if (this.settings.debugMode)
console.log(`${this.debugLabel}: Initially testing socket/tcp connection to clamscan server.`);
try {
- const client = await this._ping();
+ const client = await this.ping();
client.end();
if (this.settings.debugMode)
console.log(`${this.debugLabel}: Established connection to clamscan server!`);
@@ -353,6 +356,7 @@ class NodeClam {
/**
* Allows one to create a new instances of clamscan with new options.
*
+ * @public
* @param {object} [options] - Same options as the `init` method
* @param {Function} [cb] - What to do after reset (repsponds with reset instance of NodeClam)
* @returns {Promise