feat: malware scan rate limiting & auto retry

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ## Version 3.12.0 - Upcoming
 
+### Added
+
+- A maximum concurrent amount of scans can now be configured for the malware scanner.
+
+### Changed
+
+- The retry logic for the malware scanner was improved to be more robust under high loads.
+
 ### Fixed
 
 - Wrong file name being shown when rejecting an attachment due to file size.

README.md

@@ -16,6 +16,8 @@ The `@cap-js/attachments` package is a [CDS plugin](https://cap.cloud.sap/docs/n
     - [Changes in the CDS Models](#changes-in-the-cds-models)
     - [Storage Targets](#storage-targets)
     - [Malware Scanner](#malware-scanner)
+      - [Rate Limit Handling (Auto-Retry)](#rate-limit-handling-auto-retry)
+      - [Scan Concurrency Limiting](#scan-concurrency-limiting)
       - [Automatic file rescanning](#automatic-file-rescanning)
     - [Audit logging](#audit-logging)
     - [Visibility Control for Attachments UI Facet Generation](#visibility-control-for-attachments-ui-facet-generation)
@@ -231,6 +233,60 @@ Scan status codes:
 > [!Note]
 > If the malware scanner reports a file size larger than the limit specified via [@Validation.Maximum](#specify-the-maximum-file-size) it removes the file and sets the status of the attachment metadata to failed.
 
+#### Rate Limit Handling (Auto-Retry)
+
+The SAP Malware Scanning Service enforces a rate limit of 30 concurrent requests per subaccount. When this limit is exceeded, the service responds with HTTP `429 Too Many Requests`. By default, the plugin automatically retries scan requests that receive a 429 response using exponential backoff with jitter.
+
+You can configure the retry behavior in `package.json` or `.cdsrc.json`:
+
+```json
+{
+  "cds": {
+    "requires": {
+      "malwareScanner": {
+        "retry": {
+          "maxAttempts": 5,
+          "initialDelay": 1000,
+          "maxDelay": 30000
+        }
+      }
+    }
+  }
+}
+```
+
+| Option               | Default | Description                                            |
+| -------------------- | ------- | ------------------------------------------------------ |
+| `retry.maxAttempts`  | `5`     | Total number of attempts including the initial request |
+| `retry.initialDelay` | `1000`  | Base delay in milliseconds before the first retry      |
+| `retry.maxDelay`     | `30000` | Maximum delay in milliseconds between retries          |
+
+When a 429 response includes a `Retry-After` header, the plugin respects that value (capped at `maxDelay`). Only 429 responses trigger retries — other errors fail immediately.
+
+To disable retry and restore the previous behavior (immediate failure on 429), set `retry` to `false`.
+
+#### Scan Concurrency Limiting
+
+To reduce pressure on the shared rate limit, the plugin limits how many scan requests run concurrently within a single process. Excess scans are queued and processed as slots become available.
+
+```json
+{
+  "cds": {
+    "requires": {
+      "malwareScanner": {
+        "maxConcurrentScans": 10
+      }
+    }
+  }
+}
+```
+
+| Option               | Default | Description                                                                                            |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `maxConcurrentScans` | `30`    | Maximum number of concurrent scan requests per process. Set to `0` to disable (unbounded parallelism). |
+
+A scan that is retrying due to a 429 response holds its concurrency slot during the backoff wait, preventing retry storms from competing with new scans.
+
 #### Automatic file rescanning
 
 According to the recommendation of the [Malware Scanning Service](http://help.sap.com/docs/malware-scanning-service/sap-malware-scanning-service/developing-applications-with-sap-malware-scanning-service), attachments should be rescanned automatically if the last scan is older than 3 days. This behavior can be configured in the attachments settings by specifying the `scanExpiryMs` property:

package.json

@@ -47,6 +47,12 @@
   "cds": {
     "requires": {
       "malwareScanner": {
+        "retry": {
+          "maxAttempts": 5,
+          "initialDelay": 1000,
+          "maxDelay": 30000,
+          "maxConcurrentScans": 30
+        },
         "vcap": {
           "label": "malware-scanner"
         }

srv/attachments/basic.js

@@ -127,11 +127,16 @@ class AttachmentsService extends cds.Service {
       res = await Promise.all(
         data.map(async (d) => {
           const res = await UPSERT(d).into(attachments)
-          const attachmentForHash = await this.get(attachments, { ID: d.ID })
-          // If this is just the PUT for metadata, there is not yet any file to retrieve
-          if (attachmentForHash) {
-            const hash = await computeHash(attachmentForHash)
-            await this.update(attachments, { ID: d.ID }, { hash })
+          // When scanning is enabled, skip hash computation here — the malware
+          // scanner returns SHA-256 in its response and writes the hash itself.
+          // This avoids a redundant file read (expensive for object store backends).
+          const scanEnabled = cds.env.requires?.attachments?.scan !== false
+          if (!scanEnabled || !this._skipInlineHash) {
+            const attachmentForHash = await this.get(attachments, { ID: d.ID })
+            if (attachmentForHash) {
+              const hash = await computeHash(attachmentForHash)
+              await this.update(attachments, { ID: d.ID }, { hash })
+            }
           }
           return res
         }),

srv/attachments/object-store.js

@@ -7,6 +7,9 @@ module.exports = class RemoteAttachmentsService extends require("./basic") {
   objectStoreKind = cds.env.requires?.attachments?.objectStore?.kind
   separateObjectStore =
     this.isMultiTenancyEnabled && this.objectStoreKind === "separate"
+  // Skip inline hash computation in put() — the malware scanner already
+  // returns SHA-256, avoiding a redundant remote file download from object store.
+  _skipInlineHash = true
 
   init() {
     LOG.debug(`${this.constructor.name} initialization`, {