feat(techdocs): add support for AWS S3 retries in publisher (#28446)

This change is to allow a configurable retry in Backstage TechDocs AWS S3 publisher.

It introduces a new possible option for techdocs-cli publish called --awsMaxAttempts. This configuration when specified as a number translates to maxAttempts that is compatible with aws-sdk/client-s3 (JavaScript v3) S3Client class. The change will not break existing configuration setups - maxAttempts is optional and fallbacks to already existing defaults if not specified.

Signed-off-by: Laimis Juzeliūnas <asnelaimis@gmail.com>

.changeset/old-phones-rest.md

@@ -0,0 +1,6 @@
+---
+'@techdocs/cli': minor
+'@backstage/plugin-techdocs-node': minor
+---
+
+Allow configurable optional retries for publisher AWS S3 operations.

docs/features/techdocs/cli.md

@@ -197,6 +197,7 @@ Options:
   --awsS3sse <AWS SSE>                                          Optional AWS S3 Server Side Encryption.
   --awsS3ForcePathStyle                                         Optional AWS S3 option to force path style.
   --awsBucketRootPath <AWS BUCKET ROOT PATH>                    Optional sub-directory to store files in Amazon S3
+  --awsMaxAttempts <AWS MAX ATTEMPTS>                           Optional maximum number of retries for AWS S3 operations. If not specified, default value of 3 is used.
   --osCredentialId <OPENSTACK SWIFT APPLICATION CREDENTIAL ID>  (Required for OpenStack) specify when --publisher-type openStackSwift
   --osSecret <OPENSTACK SWIFT APPLICATION CREDENTIAL SECRET>    (Required for OpenStack) specify when --publisher-type openStackSwift
   --osAuthUrl <OPENSTACK SWIFT AUTHURL>                         (Required for OpenStack) specify when --publisher-type openStackSwift

packages/techdocs-cli/cli-report.md

@@ -83,6 +83,7 @@ Options:
   --awsS3sse <AWS SSE>
   --awsS3ForcePathStyle
   --awsBucketRootPath <AWS BUCKET ROOT PATH>
+  --awsMaxAttempts <AWS MAX ATTEMPTS>
   --osCredentialId <OPENSTACK SWIFT APPLICATION CREDENTIAL ID>
   --osSecret <OPENSTACK SWIFT APPLICATION CREDENTIAL SECRET>
   --osAuthUrl <OPENSTACK SWIFT AUTHURL>

packages/techdocs-cli/src/commands/index.ts

@@ -196,6 +196,10 @@ export function registerCommands(program: Command) {
       '--awsBucketRootPath <AWS BUCKET ROOT PATH>',
       'Optional sub-directory to store files in Amazon S3',
     )
+    .option(
+      '--awsMaxAttempts <AWS MAX ATTEMPTS>',
+      'Optional maximum number of retries for AWS S3 operations. If not specified, default value of 3 is used.',
+    )
     .option(
       '--osCredentialId <OPENSTACK SWIFT APPLICATION CREDENTIAL ID>',
       '(Required for OpenStack) specify when --publisher-type openStackSwift',

packages/techdocs-cli/src/lib/PublisherConfig.ts

@@ -95,6 +95,9 @@ export class PublisherConfig {
         ...(opts.awsS3ForcePathStyle && { s3ForcePathStyle: true }),
         ...(opts.awsS3sse && { sse: opts.awsS3sse }),
         ...(opts.awsProxy && { httpsProxy: opts.awsProxy }),
+        ...(opts.awsMaxAttempts && {
+          maxAttempts: Number(opts.awsMaxAttempts),
+        }),
       },
     };
   }

plugins/techdocs-node/src/stages/publish/awsS3.ts

@@ -164,12 +164,18 @@ export class AwsS3Publish implements PublisherBase {
       'techdocs.publisher.awsS3.s3ForcePathStyle',
     );
 
+    // AWS MAX ATTEMPTS is an optional config. If missing, default value of 3 is used
+    const maxAttempts = config.getOptionalNumber(
+      'techdocs.publisher.awsS3.maxAttempts',
+    );
+
     const storageClient = new S3Client({
       customUserAgent: 'backstage-aws-techdocs-s3-publisher',
       credentialDefaultProvider: () => sdkCredentialProvider,
       ...(region && { region }),
       ...(endpoint && { endpoint }),
       ...(forcePathStyle && { forcePathStyle }),
+      ...(maxAttempts && { maxAttempts }),
       ...(httpsProxy && {
         requestHandler: new NodeHttpHandler({
           httpsAgent: new HttpsProxyAgent({ proxy: httpsProxy }),