registry-assets-table.ts

/**
 *  MIT No Attribution
 *
 *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 *  Permission is hereby granted, free of charge, to any person obtaining a copy of
 *  the Software without restriction, including without limitation the rights to
 *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 *  the Software, and to permit persons to whom the Software is furnished to do so.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 *  SOFTWARE.
 */

import { RemovalPolicy } from 'aws-cdk-lib';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';

/** GSI name for listing every asset of a given kind (REGISTRY.md §3.1). */
export const REGISTRY_KIND_INDEX = 'kind-index';

/**
 * Properties for the RegistryAssetsTable construct.
 */
export interface RegistryAssetsTableProps {
  /**
   * Optional table name override.
   * @default - auto-generated by CloudFormation
   */
  readonly tableName?: string;

  /**
   * Removal policy for the table. Registry records are the source of truth for
   * what a task may load and are immutable-per-version, so production
   * deployments should RETAIN; the construct default stays DESTROY to match the
   * rest of the sample stack's dev-first posture.
   * @default RemovalPolicy.DESTROY
   */
  readonly removalPolicy?: RemovalPolicy;

  /**
   * Whether to enable point-in-time recovery.
   * @default true
   */
  readonly pointInTimeRecovery?: boolean;
}

/**
 * DynamoDB table backing the agent asset registry (#246; see
 * docs/design/REGISTRY.md §3.1 and ADR-018).
 *
 * Schema:
 *  - ``pk`` (partition) = ``{kind}#{namespace}/{name}`` — groups every version
 *    of one asset under a single partition.
 *  - ``sk`` (sort) = the semver ``version`` string.
 *
 * A single ``Query`` on ``pk`` returns all versions of an asset (show + resolve;
 * resolution ranks by parsed semver in code, since DynamoDB sorts the version
 * sort key lexicographically). The ``kind-index`` GSI (partition ``kind``, sort
 * ``pk``) powers ``GET /registry/assets?kind=...`` without a table scan.
 *
 * There is no TTL: registry records are immutable-per-version and audited; a
 * ``removed`` status tombstones a record rather than deleting the row (a task
 * pinned to it fails closed with ``REMOVED``).
 */
export class RegistryAssetsTable extends Construct {
  /**
   * The underlying DynamoDB table. Use this to grant access or read the table name.
   */
  public readonly table: dynamodb.Table;

  constructor(scope: Construct, id: string, props: RegistryAssetsTableProps = {}) {
    super(scope, id);

    this.table = new dynamodb.Table(this, 'Table', {
      tableName: props.tableName,
      partitionKey: {
        name: 'pk',
        type: dynamodb.AttributeType.STRING,
      },
      sortKey: {
        name: 'sk',
        type: dynamodb.AttributeType.STRING,
      },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      pointInTimeRecoverySpecification: {
        pointInTimeRecoveryEnabled: props.pointInTimeRecovery ?? true,
      },
      removalPolicy: props.removalPolicy ?? RemovalPolicy.DESTROY,
    });

    this.table.addGlobalSecondaryIndex({
      indexName: REGISTRY_KIND_INDEX,
      partitionKey: {
        name: 'kind',
        type: dynamodb.AttributeType.STRING,
      },
      sortKey: {
        name: 'pk',
        type: dynamodb.AttributeType.STRING,
      },
      // The list endpoint needs kind, namespace, name, version, and status to
      // render a summary — a KEYS_ONLY projection would force a second read per
      // row, so project everything.
      projectionType: dynamodb.ProjectionType.ALL,
    });
  }
}