table-v2-base.ts

import { DynamoDBMetrics } from './dynamodb-canned-metrics.generated';
import * as perms from './perms';
import type { SystemErrorsForOperationsMetricOptions, OperationsMetricOptions, ITable } from './shared';
import { Operation } from './shared';
import type { TableGrants } from './table-grants';
import type { IMetric, MetricOptions, MetricProps } from '../../aws-cloudwatch';
import { MathExpression, Metric } from '../../aws-cloudwatch';
import type { AddToResourcePolicyResult, GrantOnKeyResult, IGrantable, IResourceWithPolicy, PolicyDocument, PolicyStatement } from '../../aws-iam';
import { Grant } from '../../aws-iam';
import type { IKey } from '../../aws-kms';
import { Annotations, Resource, ValidationError } from '../../core';
import { isServicePrincipal } from './private/principal-utils';
import type { TableReference } from '../../interfaces/generated/aws-dynamodb-interfaces.generated';

/**
 * Represents an instance of a DynamoDB table.
 */
export interface ITableV2 extends ITable {
  /**
   * The ID of the table.
   *
   * @attribute
   */
  readonly tableId?: string;

  /**
   * Grants for this table
   */
  readonly grants: TableGrants;
}

/**
 * Base class for a DynamoDB table.
 */
export abstract class TableBaseV2 extends Resource implements ITableV2, IResourceWithPolicy {
  /**
   * The ARN of the table.
   *
   * @attribute
   */
  public abstract readonly tableArn: string;

  /**
   * The name of the table.
   *
   * @attribute
   */
  public abstract readonly tableName: string;

  /**
   * The stream ARN of the table.
   *
   * @attribute
   */
  public abstract readonly tableStreamArn?: string;

  /**
   * The ID of the table.
   *
   * @attribute
   */
  public abstract readonly tableId?: string;

  /**
   * Grants for this table.
   */
  public abstract readonly grants: TableGrants;

  /**
   * The KMS encryption key for the table.
   */
  public abstract readonly encryptionKey?: IKey;

  /**
   * The resource policy for the table
   */
  public abstract resourcePolicy?: PolicyDocument;

  protected abstract readonly region: string;

  protected abstract get hasIndex(): boolean;

  /**
   * A reference to this table.
   */
  public get tableRef(): TableReference {
    return {
      tableName: this.tableName,
      tableArn: this.tableArn,
    };
  }

  /**
   * Adds an IAM policy statement associated with this table to an IAM principal's policy.
   *
   * Note: If `encryptionKey` is present, appropriate grants to the key needs to be added
   * separately using the `table.encryptionKey.grant*` methods.
   *
   * [disable-awslint:no-grants]
   *
   * @param grantee the principal (no-op if undefined)
   * @param actions the set of actions to allow (i.e., 'dynamodb:PutItem', 'dynamodb:GetItem', etc.)
   */
  public grant(grantee: IGrantable, ...actions: string[]): Grant {
    if (isServicePrincipal(grantee.grantPrincipal)) {
      return this.dropServicePrincipalGrant(grantee);
    }
    const resourceArns = [this.tableArn];
    this.hasIndex && resourceArns.push(`${this.tableArn}/index/*`);
    return Grant.addToPrincipalOrResource({
      grantee,
      actions,
      resourceArns,
      resource: this,
    });
  }

  /**
   * Adds an IAM policy statement associated with this table to an IAM principal's policy.
   *
   * Note: If `encryptionKey` is present, appropriate grants to the key needs to be added
   * separately using the `table.encryptionKey.grant*` methods.
   *
   * [disable-awslint:no-grants]
   *
   * @param grantee the principal (no-op if undefined)
   * @param actions the set of actions to allow (i.e., 'dynamodb:DescribeStream', 'dynamodb:GetRecords', etc.)
   */
  public grantStream(grantee: IGrantable, ...actions: string[]): Grant {
    if (!this.tableStreamArn) {
      throw new ValidationError('StreamFoundTable', `No stream ARN found on the table ${this.node.path}`, this);
    }

    return Grant.addToPrincipal({
      grantee,
      actions,
      resourceArns: [this.tableStreamArn],
    });
  }

  /**
   * Adds an IAM policy statement associated with this table to an IAM principal's policy.
   *
   * Actions: DescribeStream, GetRecords, GetShardIterator, ListStreams.
   *
   * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this
   * table if one was configured.
   *
   * [disable-awslint:no-grants]
   *
   * @param grantee the principal to grant access to
   */
  public grantStreamRead(grantee: IGrantable): Grant {
    this.grantTableListStreams(grantee);

    const keyActions = perms.KEY_READ_ACTIONS;
    const streamActions = perms.READ_STREAM_DATA_ACTIONS;

    return this.combinedGrant(grantee, { keyActions, streamActions });
  }

  /**
   * Permits an IAM principal to list streams attached to this table.
   *
   * [disable-awslint:no-grants]
   *
   * @param grantee the principal to grant access to
   */
  public grantTableListStreams(grantee: IGrantable): Grant {
    if (!this.tableStreamArn) {
      throw new ValidationError('StreamFoundTable', `No stream ARN found on the table ${this.node.path}`, this);
    }

    return Grant.addToPrincipal({
      grantee,
      actions: ['dynamodb:ListStreams'],
      resourceArns: [this.tableStreamArn],
    });
  }

  /**
   * Permits an IAM principal all data read operations on this table.
   *
   * Actions: BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, DescribeTable.
   *
   * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this
   * table if one was configured.
   *
   * [disable-awslint:no-grants]
   *
   * @param grantee the principal to grant access to
   */
  public grantReadData(grantee: IGrantable): Grant {
    const tableActions = perms.RESOURCE_READ_DATA_ACTIONS.concat(perms.DESCRIBE_TABLE);
    return this.combinedGrant(grantee, {
      keyActions: perms.KEY_READ_ACTIONS,
      tableActions,
      tablePrinicipalExclusiveActions: perms.PRINCIPAL_ONLY_READ_DATA_ACTIONS,
    });
  }

  /**
   * Permits an IAM principal all data write operations on this table.
   *
   * Actions: BatchWriteItem, PutItem, UpdateItem, DeleteItem, DescribeTable.
   *
   * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this
   * table if one was configured.
   *
   * [disable-awslint:no-grants]
   *
   * @param grantee the principal to grant access to
   */
  public grantWriteData(grantee: IGrantable): Grant {
    const tableActions = perms.WRITE_DATA_ACTIONS.concat(perms.DESCRIBE_TABLE);
    const keyActions = perms.KEY_READ_ACTIONS.concat(perms.KEY_WRITE_ACTIONS);
    return this.combinedGrant(grantee, { keyActions, tableActions });
  }

  /**
   * Permits an IAM principal to all data read/write operations on this table.
   *
   * Actions: BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, BatchWriteItem, PutItem, UpdateItem,
   * DeleteItem, DescribeTable.
   *
   * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this
   * table if one was configured.
   *
   * [disable-awslint:no-grants]
   *
   * @param grantee the principal to grant access to
   */
  public grantReadWriteData(grantee: IGrantable): Grant {
    const tableActions = perms.RESOURCE_READ_DATA_ACTIONS.concat(perms.WRITE_DATA_ACTIONS).concat(perms.DESCRIBE_TABLE);
    const keyActions = perms.KEY_READ_ACTIONS.concat(perms.KEY_WRITE_ACTIONS);
    return this.combinedGrant(grantee, {
      keyActions,
      tableActions,
      tablePrinicipalExclusiveActions: perms.PRINCIPAL_ONLY_READ_DATA_ACTIONS,
    });
  }

  /**
   * Permits an IAM principal to all DynamoDB operations ('dynamodb:*') on this table.
   *
   * Note: Appropriate grants will also be added to the customer-managed KMS keys associated with this
   * table if one was configured.
   *
   * [disable-awslint:no-grants]
   *
   * @param grantee the principal to grant access to
   */
  public grantFullAccess(grantee: IGrantable): Grant {
    const keyActions = perms.KEY_READ_ACTIONS.concat(perms.KEY_WRITE_ACTIONS);
    return this.combinedGrant(grantee, { keyActions, tableActions: ['dynamodb:*'] });
  }

  /**
   * Grants permissions on the table's encryption key.
   *
   * @param grantee the principal to grant access to
   * @param actions the KMS actions to grant
   */
  public grantOnKey(grantee: IGrantable, ...actions: string[]): GrantOnKeyResult {
    return {
      grant: this.encryptionKey?.grant(grantee, ...actions),
    };
  }

  /**
   * Return the given named metric for this table.
   *
   * By default, the metric will be calculated as a sum over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metric(metricName: string, props?: MetricOptions): Metric {
    const metricProps: MetricProps = {
      namespace: 'AWS/DynamoDB',
      metricName,
      dimensionsMap: { TableName: this.tableName },
      ...props,
    };
    return this.configureMetric(metricProps);
  }

  /**
   * Metric for the consumed read capacity units for this table.
   *
   * By default, the metric will be calculated as a sum over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metricConsumedReadCapacityUnits(props?: MetricOptions): Metric {
    const metricProps: MetricProps = {
      ...DynamoDBMetrics.consumedReadCapacityUnitsSum({ TableName: this.tableName }),
      ...props,
    };
    return this.configureMetric(metricProps);
  }

  /**
   * Metric for the consumed write capacity units for this table.
   *
   * By default, the metric will be calculated as a sum over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metricConsumedWriteCapacityUnits(props?: MetricOptions): Metric {
    const metricProps: MetricProps = {
      ...DynamoDBMetrics.consumedWriteCapacityUnitsSum({ TableName: this.tableName }),
      ...props,
    };
    return this.configureMetric(metricProps);
  }

  /**
   * Metric for the user errors for this table.
   *
   * Note: This metric reports user errors across all the tables in the account and region the table
   * resides in.
   *
   * By default, the metric will be calculated as a sum over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metricUserErrors(props?: MetricOptions): Metric {
    if (props?.dimensions) {
      throw new ValidationError('SupportedMetric', '`dimensions` is not supported for the `UserErrors` metric', this);
    }

    return this.metric('UserErrors', { statistic: 'sum', ...props, dimensionsMap: {} });
  }

  /**
   * Metric for the conditional check failed requests for this table.
   *
   * By default, the metric will be calculated as a sum over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metricConditionalCheckFailedRequests(props?: MetricOptions): Metric {
    return this.metric('ConditionalCheckFailedRequests', { statistic: 'sum', ...props });
  }

  /**
   * Metric for the successful request latency for this table.
   *
   * By default, the metric will be calculated as an average over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metricSuccessfulRequestLatency(props?: MetricOptions): Metric {
    if (!props?.dimensions?.Operation && !props?.dimensionsMap?.Operation) {
      throw new ValidationError('MustBeDimensionPassedMetric', '`Operation` dimension must be passed for the `SuccessfulRequestLatency` metric', this);
    }

    const dimensionsMap = {
      TableName: this.tableName,
      Operation: props.dimensionsMap?.Operation ?? props.dimensions?.Operation,
    };

    const metricProps: MetricProps = {
      ...DynamoDBMetrics.successfulRequestLatencyAverage(dimensionsMap),
      ...props,
      dimensionsMap,
    };
    return this.configureMetric(metricProps);
  }

  /**
   * How many requests are throttled on this table for the given operation
   *
   * By default, the metric will be calculated as an average over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metricThrottledRequestsForOperation(operation: string, props?: OperationsMetricOptions): IMetric {
    const metricProps: MetricProps = {
      ...DynamoDBMetrics.throttledRequestsSum({ Operation: operation, TableName: this.tableName }),
      ...props,
    };
    return this.configureMetric(metricProps);
  }

  /**
   * How many requests are throttled on this table. This will sum errors across all possible operations.
   *
   * By default, each individual metric will be calculated as a sum over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metricThrottledRequestsForOperations(props?: OperationsMetricOptions): IMetric {
    return this.sumMetricsForOperations('ThrottledRequests', 'Sum of throttled requests across all operations', props);
  }

  /**
   * Metric for the system errors for this table. This will sum errors across all possible operations.
   *
   * By default, each individual metric will be calculated as a sum over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   */
  public metricSystemErrorsForOperations(props?: SystemErrorsForOperationsMetricOptions): IMetric {
    return this.sumMetricsForOperations('SystemErrors', 'Sum of errors across all operations', props);
  }

  /**
   * How many requests are throttled on this table.
   *
   * By default, each individual metric will be calculated as a sum over a period of 5 minutes.
   * You can customize this by using the `statistic` and `period` properties.
   *
   * @deprecated Do not use this function. It returns an invalid metric. Use `metricThrottledRequestsForOperation` instead.
   */
  public metricThrottledRequests(props?: MetricOptions): Metric {
    return this.metric('ThrottledRequests', { statistic: 'sum', ...props });
  }

  /**
   * Metric for the system errors this table
   *
   * @deprecated use `metricSystemErrorsForOperations`.
   */
  public metricSystemErrors(props?: MetricOptions): Metric {
    if (!props?.dimensions?.Operation && !props?.dimensionsMap?.Operation) {
      // 'Operation' must be passed because its an operational metric.
      throw new ValidationError('MustBeOperationDimensionPassed', "'Operation' dimension must be passed for the 'SystemErrors' metric.", this);
    }

    const dimensionsMap = {
      TableName: this.tableName,
      ...props?.dimensions ?? {},
      ...props?.dimensionsMap ?? {},
    };

    return this.metric('SystemErrors', { statistic: 'sum', ...props, dimensionsMap });
  }

  /**
   * Create a math expression for operations.
   */
  private sumMetricsForOperations(metricName: string, expressionLabel: string, props?: OperationsMetricOptions) {
    if (props?.dimensions?.Operation) {
      throw new ValidationError('OperationDimensionSupported', 'The Operation dimension is not supported. Use the `operations` property', this);
    }

    const operations = props?.operations ?? Object.values(Operation);
    const values = this.createMetricForOperations(metricName, operations, { statistic: 'sum', ...props });
    const sum = new MathExpression({
      expression: `${Object.keys(values).join(' + ')}`,
      usingMetrics: { ...values },
      color: props?.color,
      label: expressionLabel,
      period: props?.period,
    });

    return sum;
  }

  /**
   * Create a map of metrics that can be used in a math expression.
   *
   * Using the return value of this function as the `usingMetrics` property in `cloudwatch.MathExpression` allows you to
   * use the keys of this map as metric names inside you expression.
   */
  private createMetricForOperations(metricName: string, operations: Operation[], props?: MetricOptions,
    metricNameMapper?: (op: Operation) => string) {
    const metrics: Record<string, IMetric> = {};
    const mapper = metricNameMapper ?? (op => op.toLowerCase());

    if (props?.dimensions?.Operation) {
      throw new ValidationError('InvalidPropertiesOperationDimensionSupported', 'Invalid properties. Operation dimension is not supported when calculating operational metrics', this);
    }

    for (const operation of operations) {
      const metric = this.metric(metricName, {
        ...props,
        dimensionsMap: { TableName: this.tableName, Operation: operation, ...props?.dimensions },
      });

      const operationMetricName = mapper(operation);
      const firstChar = operationMetricName.charAt(0);
      if (firstChar === firstChar.toUpperCase()) {
        throw new ValidationError('MapperGeneratedIllegalOperationMetric', `Mapper generated an illegal operation metric name: ${operationMetricName}. Must start with a lowercase letter`, this);
      }

      metrics[operationMetricName] = metric;
    }

    return metrics;
  }

  /**
   * Adds an IAM policy statement associated with this table to an IAM principal's policy.
   *
   * @param grantee the principal (no-op if undefined)
   * @param options options for keyActions, tableActions, and streamActions
   */
  private combinedGrant(grantee: IGrantable, options: {
    keyActions?: string[];
    tableActions?: string[];
    tablePrinicipalExclusiveActions?: string[];
    streamActions?: string[];
  }) {
    if (isServicePrincipal(grantee.grantPrincipal)) {
      return this.dropServicePrincipalGrant(grantee);
    }

    if (options.keyActions && this.encryptionKey) {
      this.encryptionKey.grant(grantee, ...options.keyActions);
    }

    if (options.tableActions) {
      const resourceArns = [this.tableArn];
      this.hasIndex && resourceArns.push(`${this.tableArn}/index/*`);
      const result = Grant.addToPrincipalOrResource({
        grantee,
        actions: options.tableActions,
        resourceArns,
        // Use wildcard for resource policy to avoid circular dependency when grantee is a resource principal
        // (e.g., AccountRootPrincipal). This follows the same pattern as KMS (aws-kms/lib/key.ts).
        // resourceArns is used for principal policies, resourceSelfArns is used for resource policies.
        resourceSelfArns: ['*'],
        resource: this,
      });

      if (options.tablePrinicipalExclusiveActions) {
        return result.combine(Grant.addToPrincipal({
          grantee,
          actions: options.tablePrinicipalExclusiveActions,
          resourceArns,
        }));
      }
      return result;
    }

    if (options.streamActions) {
      if (!this.tableStreamArn) {
        throw new ValidationError('StreamNsFoundTable', `No stream ARNs found on the table ${this.node.path}`, this);
      }

      return Grant.addToPrincipal({
        grantee,
        actions: options.streamActions,
        resourceArns: [this.tableStreamArn],
      });
    }

    throw new ValidationError('UnexpectedAction', `Unexpected 'action', ${options.tableActions || options.streamActions}`, this);
  }

  private configureMetric(props: MetricProps) {
    return new Metric({
      ...props,
      region: props?.region ?? this.region,
      account: props?.account ?? this.stack.account,
    });
  }

  private dropServicePrincipalGrant(grantee: IGrantable): Grant {
    Annotations.of(this).addWarningV2(
      '@aws-cdk/aws-dynamodb:servicePrincipalGrantDropped',
      'DynamoDB grant* methods do not support ServicePrincipal grantees. ' +
      'Use table.addToResourcePolicy() for an explicit service-specific table policy ' +
      'with required service principal, actions, and conditions',
    );
    return Grant.drop(grantee, 'DynamoDB grant* does not support ServicePrincipal grantees');
  }

  /**
   * Adds a statement to the resource policy associated with this table.
   * A resource policy will be automatically created upon the first call to `addToResourcePolicy`.
   *
   * Note that this does not work with imported tables.
   *
   * @param statement The policy statement to add
   */
  public abstract addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResult;
}