diff --git a/API.md b/API.md index 52ef073..217cde8 100644 --- a/API.md +++ b/API.md @@ -37,6 +37,7 @@ NodeClam class definition. To cf * [.getVersion([cb])](#NodeClam+getVersion) ⇒ Promise.<string> * [.isInfected(file, [cb])](#NodeClam+isInfected) ⇒ Promise.<object> * [.passthrough()](#NodeClam+passthrough) ⇒ Transform + * [.ping([cb])](#NodeClam+ping) ⇒ Promise.<object> * [.scanFile(file, [cb])](#NodeClam+scanFile) ⇒ Promise.<object> * [.scanFiles(files, [endCb], [fileCb])](#NodeClam+scanFiles) ⇒ Promise.<object> * [.scanDir(path, [endCb], [fileCb])](#NodeClam+scanDir) ⇒ Promise.<object> @@ -250,6 +251,44 @@ 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 ``` + + + +### nodeClam.ping([cb]) ⇒ Promise.<object> +This method allows you to ping the socket. It supports a callback and Promise API. +If no callback is supplied, a Promise will be returned. + +**Kind**: instance method of [NodeClam](#NodeClam) +**Returns**: Promise.<object> - A copy of the Socket/TCP client. + +| Param | Type | Description | +| --- | --- | --- | +| [cb] | function | What to do after the ping | + +**Example** +```js +// Callback Example +clamscan.ping((err, client) => { + if (err) return console.error(err); + + console.log("ClamAV client is working"); + client.end(); +}); + +// Promise Example +clamscan.ping().then(client => { + console.log("ClamAV client is working"); + client.end(); +}).then(err => { + console.error(err); +}); + +// Async/Await Example +const client = await clamscan.ping(); +console.log("ClamAV client is working"); +client.end(); +``` + ### nodeClam.scanFile(file, [cb]) ⇒ Promise.<object> 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.