AWS xRay in RC (tracer) and raw clients

• Resource Controller. You can now use AWS xRay tracer (from Powertools for AWS Lambda) for advanced monitoring of a Resource Controller. Note: you also have to enable tracing in your Lambda functions and API Gateway (when applicable) through IAC or via console. Example:

  import { Tracer } from '@aws-lambda-powertools/tracer';
  
  const ddb = new DynamoDB();
  
  const tracer = new Tracer();
  tracer.captureAWSv3Client(ddb.client);
  
  export const handler = (ev: any, _: any, cb: any): Promise<void> => new RC(ev, cb).handleRequest();
  
  class RC extends ResourceController {
     constructor(event: any, callback: any) {
        super(event, callback, { tracer });
        this.tracer.putAnnotation('userId', this.principalId);
     }
  }

• You can access the internal raw clients of the AWS Services's wrappers. Example:

   import { S3 } from 'idea-aws';
  
  const s3 = new S3();
  s3.client.send(...);

Better (JSON) logging

What's new and Breaking changes

• General. Lambda functions now support JSON logging and log level filters (read more here). Hence, logging throughout IDEA-AWS components has been adapted consequently. The new logger component is named LambdaLogger (previously: Logger). This component reads the configuration of the process.env. AWS_LAMBDA_LOG_LEVEL variable. For optimal results, the Lambda functions that use this new version of IDEA-AWS should be configured to use JSON format for logs (example in CDK; example in SAM); this requires the latest versions of CDK (example) and SAM (globally installed in your PC). Breaking change (example):

  // before
  logger = new Logger();
  
  // now
  logger = new LambdaLogger();

• General. IDEA-AWS components previously logged information at the INFO level; now, they log to either TRACE or DEBUG level. Note: that means that if a development Lambda function has the log level set to DEBUG, it won't display logs at the TRACE level. Read more about log levels here. You can change a Lambda log level from its configuration (CDK, SAM, Console) or (preferable) directly in its Controller's source code, with methods such as setLambdaLogLevel and silentLambdaLogs.
• General. RCError has been renamed into a more general HandledError. This type of error should be used in all types of Controller to differentiate errors that are considered handled (expected, due to bad user behaviours) from unexpected errors (errors in the source code or external factors). Breaking change (example):

  // before
  throw new RCError('Not found');
  
  // now
  throw new HandledError('Not found');

• ResourceController. Better logging at the beginning and end of the requests, differentiating a failed event between Handled errors (WARN log level) and Unhandled errors (ERROR log level). Moreover, at the end of an execution, more information is returned to help with CloudWatch Insights queries. Type of ending logs:
  • INFO "END-SUCCESS": the request has been handled successfully.
  • WARN "END-FAILED": the request has failed in a controlled way because of user errors.
  • ERROR "END-FAILED": the request has failed due to unexpected errors.
  • DEBUG "END-DETAIL": in case of success, it contains a preview of the returned values; in case of error, it returns the message returned to the user (public-facing error message), which may be different from the error message printed in "END-FAILED" (internal message).
• StreamController. These controllers should now be used through its overridable method processRecord instead of writing directly the handleRequest method — which should be left untouched because it manages errors and logging. Example here.
• S3: the getObject method has been split into three (depending on the desired result's format) to infer a better typing: getObject, getObjectAsText, getObjectAsJSON. Breaking change (example):

  // before
  await s3.getObject({ bucket, key, type: GetObjectTypes.JSON });
  await s3.getObject({ bucket, key, type: GetObjectTypes.TEXT });
  
  // now
  await s3.getObjectAsJSON({ bucket, key });
  await s3.getObjectAsText({ bucket, key });

• S3: the doesObjectExist method now has an additional parameter emptyMeansNotFound to consider empty files as "not found".
• DynamoDB: the deprecated ISID and IUID methods have been removed; their underlying DDB tables can be removed from the projects (example in CDK, example in SAM). The two methods should be replaced by IUNID, which provides short and reliable IDs in a faster way.
• SSM, SecretsManager. These two services now implement an inner cache to avoid repetitive requests for the same parameter/secret.
• SNS. The wrapper has been adapted to the style of the other IDEA-AWS components. Breaking change (example):

  // before
  const sns = new SNS();
  const endpoint =  await sns.createPushPlatormEndpoint(pushDevice.platform, pushDevice.token, {
      region: SNS_PUSH_REGION,
      appleArn: SNS_PUSH_PLATFORM_ARN_IOS,
      ...
  });
  await sns.publish({ region: SNS_PUSH_REGION, endpoint: device.endpoint, ... });
  
  // now
  const sns = new SNS({ region: SNS_PUSH_REGION });
  const endpoint = await sns.createPlatormEndpoint(pushDevice.platform, pushDevice.token, {
      appleArn: SNS_PUSH_PLATFORM_ARN_IOS,
      ...
  });
  await sns.publish({ endpoint: device.endpoint, ... });

AWS Systems Manager (SSM) Parameter Store (instead of Secrets Manager)

AWS Secrets Manager has a fixed cost of 0.40$ per secret each month; we achieved the same functionalities of storing/retrieving secrets (and parameters) through AWS SSM Parameter Store, which has no fixed cost.

It's suggested to transition every project from Secrets Manager to SSM; the process is easy:

• From the AWS Console, open Systems Manager > Parameter Store. Add a parameter as a Secret String and copy the value from the Secrets Manager console.
• Make a change in the code to use ssm.getSecretByName instead of sm.getSecretById.
• Make sure that the path to the parameter/secret is correct (you may need to add a trailing /).
• Update CDK/SAM to enable the Lambda Functions to access SSM; example from Starter project here.
• After the change is in production, delete the secret from Secrets Manager to stop paying the fixed cost.

S3: download/upload files with suggested filenames

Breaking changes

• s3.signedURLPut and s3.signedURLGet's third parameter is now an object representing a more complete set of options; previously it was an optional parameter to indicate the expiration time of the signedURL. To upgrade — only needed in cases where the third parameter was used — you need to use the new object format:

  // before
  await s3.signedURLGet(bucket, key, secondsToExpiration);
  
  // now
  await s3.signedURLGet(bucket, key, { secToExp: secondsToExpiration });

---

• S3: all the concerning methods can suggest a filename that will be used by the browsers when downloading or displaying a file.
• General: all modules recently updated to AWS SDK v3 have been tested and are stable.

AWS SDK 3, Node.js 18

Breaking changes

Following AWS's decision on Lambda functions with Node.js >= 18, AWS-SDK v2 is not supported anymore. You should use AWS-SDK v3 instead.

Chore audit fix

v3.16.7

v3.16.7

RC: app bundle information

• RC. Read the app bundle information from client requests (IDEA standard).

Allow Logger level configuration in helper classes

v3.16.4

v3.16.4

Controllers don't use internal AWS services

• GC, RC, SC. Removed old practice of using internal attributes for AWS services; to update, prefer global variables in a Lambda function's code.
• RC. CloudWatch metrics are now optional and not activated by default (since they cost quite a lot).

Cognito: set user password (admin)

v3.15.2

v3.15.2