Bucket Management

/**
 * An S3 Bucket construct that creates a new S3 bucket with configurable properties
 */
class Bucket extends BucketBase {
  /**
   * Creates a new S3 bucket
   * @param scope - The scope in which to define this construct
   * @param id - The scoped construct ID
   * @param props - Bucket configuration properties
   */
  constructor(scope: Construct, id: string, props?: BucketProps);
  
  /** The ARN of the bucket */
  readonly bucketArn: string;
  
  /** The name of the bucket */
  readonly bucketName: string;
  
  /** The website URL of the bucket */
  readonly bucketWebsiteUrl: string;
  
  /** The domain name of the bucket */
  readonly bucketDomainName: string;
  
  /** The regional domain name of the bucket */
  readonly bucketRegionalDomainName: string;
  
  /** The dual-stack domain name of the bucket */
  readonly bucketDualStackDomainName: string;
  
  /** The encryption key used by this bucket */
  readonly encryptionKey?: kms.IKey;
  
  /** The bucket policy associated with this bucket */
  readonly policy?: BucketPolicy;
}

import * as s3 from '@aws-cdk/aws-s3';
import * as cdk from '@aws-cdk/core';

// Basic bucket
const bucket = new s3.Bucket(this, 'MyBucket');

// Bucket with custom name and versioning
const versionedBucket = new s3.Bucket(this, 'MyVersionedBucket', {
  bucketName: 'my-company-data-bucket',
  versioned: true,
});

// Fully configured bucket
const advancedBucket = new s3.Bucket(this, 'AdvancedBucket', {
  encryption: s3.BucketEncryption.KMS,
  versioned: true,
  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
  enforceSSL: true,
  lifecycleRules: [{
    id: 'CleanupOldVersions',
    noncurrentVersionExpiration: cdk.Duration.days(90),
  }],
  removalPolicy: cdk.RemovalPolicy.RETAIN,
});

/**
 * Import an existing bucket by ARN
 * @param scope - The scope in which to define this construct
 * @param id - The scoped construct ID
 * @param bucketArn - The ARN of the existing bucket
 * @returns IBucket reference to the imported bucket
 */
static fromBucketArn(scope: Construct, id: string, bucketArn: string): IBucket;

/**
 * Import an existing bucket by name
 * @param scope - The scope in which to define this construct
 * @param id - The scoped construct ID  
 * @param bucketName - The name of the existing bucket
 * @returns IBucket reference to the imported bucket
 */
static fromBucketName(scope: Construct, id: string, bucketName: string): IBucket;

/**
 * Import an existing bucket with detailed attributes
 * @param scope - The scope in which to define this construct
 * @param id - The scoped construct ID
 * @param attrs - Bucket attributes including ARN, name, and other properties
 * @returns IBucket reference to the imported bucket
 */
static fromBucketAttributes(scope: Construct, id: string, attrs: BucketAttributes): IBucket;

// Import by name (simplest approach)
const importedBucket = s3.Bucket.fromBucketName(
  this, 
  'ImportedBucket', 
  'existing-bucket-name'
);

// Import by ARN
const bucketByArn = s3.Bucket.fromBucketArn(
  this,
  'BucketByArn',
  'arn:aws:s3:::existing-bucket-name'
);

// Import with detailed attributes
const detailedImport = s3.Bucket.fromBucketAttributes(this, 'DetailedImport', {
  bucketArn: 'arn:aws:s3:::existing-bucket-name',
  bucketName: 'existing-bucket-name',
  region: 'us-east-1',
  encryptionKey: kms.Key.fromKeyId(this, 'ImportedKey', 'key-id'),
});

/**
 * Common interface for all S3 bucket implementations
 */
interface IBucket extends IResource {
  /** The ARN of this bucket */
  readonly bucketArn: string;
  
  /** The name of this bucket */
  readonly bucketName: string;
  
  /** The website URL of this bucket */
  readonly bucketWebsiteUrl: string;
  
  /** The domain name of this bucket */
  readonly bucketDomainName: string;
  
  /** The regional domain name of this bucket */
  readonly bucketRegionalDomainName: string;
  
  /** The dual-stack domain name of this bucket */
  readonly bucketDualStackDomainName: string;
  
  /** Optional KMS encryption key */
  readonly encryptionKey?: kms.IKey;
  
  /** Optional bucket policy */
  readonly policy?: BucketPolicy;
  
  /** Whether this bucket has been configured for website hosting */
  readonly isWebsite?: boolean;
  
  /**
   * Adds an event notification to this bucket
   * @param event - The event type to listen for
   * @param dest - The notification destination
   * @param filters - Optional key filters for the notification
   */
  addEventNotification(event: EventType, dest: IBucketNotificationDestination, ...filters: NotificationKeyFilter[]): void;
  
  /**
   * Grant read permissions on this bucket and/or its contents
   * @param identity - The principal to grant permissions to
   * @param objectsKeyPattern - Optional key pattern for object-level permissions
   * @returns The created Grant
   */
  grantRead(identity: iam.IGrantable, objectsKeyPattern?: any): iam.Grant;
  
  /**
   * Grant write permissions on this bucket and/or its contents
   * @param identity - The principal to grant permissions to
   * @param objectsKeyPattern - Optional key pattern for object-level permissions
   * @returns The created Grant
   */
  grantWrite(identity: iam.IGrantable, objectsKeyPattern?: any): iam.Grant;
  
  /**
   * Grant read-write permissions on this bucket and/or its contents
   * @param identity - The principal to grant permissions to
   * @param objectsKeyPattern - Optional key pattern for object-level permissions
   * @returns The created Grant
   */
  grantReadWrite(identity: iam.IGrantable, objectsKeyPattern?: any): iam.Grant;
  
  /**
   * Grant delete permissions on this bucket and/or its contents
   * @param identity - The principal to grant permissions to
   * @param objectsKeyPattern - Optional key pattern for object-level permissions
   * @returns The created Grant
   */
  grantDelete(identity: iam.IGrantable, objectsKeyPattern?: any): iam.Grant;
  
  /**
   * Grant permissions to put objects with server-side encryption
   * @param identity - The principal to grant permissions to
   * @param objectsKeyPattern - Optional key pattern for object-level permissions
   * @returns The created Grant
   */
  grantPutAcl(identity: iam.IGrantable, objectsKeyPattern?: string): iam.Grant;
  
  /**
   * Grant public read access to this bucket
   * @param keyPrefix - Optional key prefix to limit access
   */
  grantPublicAccess(keyPrefix?: string): void;
  
  /**
   * Get the ARN for objects in this bucket
   * @param keyPattern - Key pattern for the objects (e.g., 'folder/*')
   * @returns ARN string for the objects
   */
  arnForObjects(keyPattern: string): string;
  
  /**
   * Get the HTTP URL for an object in this bucket
   * @param key - The object key
   * @returns HTTP URL for the object
   */
  urlForObject(key: string): string;
  
  /**
   * Get the virtual-hosted style HTTP URL for an object
   * @param key - The object key
   * @returns Virtual-hosted style HTTP URL
   */
  virtualHostedUrlForObject(key: string): string;
  
  /**
   * Get the S3 URL for an object in this bucket
   * @param key - The object key
   * @returns S3 URL (s3://bucket/key format)
   */
  s3UrlForObject(key: string): string;
  
  /**
   * Add a policy statement to the bucket's resource policy
   * @param permission - The policy statement to add
   * @returns AddToResourcePolicyResult indicating success
   */
  addToResourcePolicy(permission: iam.PolicyStatement): iam.AddToResourcePolicyResult;
}

/**
 * Properties for creating an S3 bucket
 */
interface BucketProps {
  /** Physical name of this bucket (must be globally unique) */
  bucketName?: string;
  
  /** Whether this bucket should have versioning turned on */
  versioned?: boolean;
  
  /** The kind of server-side encryption to apply to this bucket */
  encryption?: BucketEncryption;
  
  /** External KMS key to use for bucket encryption */
  encryptionKey?: kms.IKey;
  
  /** Whether to use S3 Bucket Keys for encryption cost optimization */
  bucketKeyEnabled?: boolean;
  
  /** The block public access configuration of this bucket */
  blockPublicAccess?: BlockPublicAccess;
  
  /** Whether this bucket should have public read access */
  publicReadAccess?: boolean;
  
  /** The name of the index document for the website */
  websiteIndexDocument?: string;
  
  /** The name of the error document for the website */
  websiteErrorDocument?: string;
  
  /** Specifies the redirect behavior of all requests to a website endpoint */
  websiteRedirect?: RedirectTarget;
  
  /** Rules that define how Amazon S3 manages objects during their lifetime */
  lifecycleRules?: LifecycleRule[];
  
  /** The CORS configuration of this bucket */
  cors?: CorsRule[];
  
  /** The name of the destination bucket for server access logs */
  serverAccessLogsBucket?: IBucket;
  
  /** Optional log file prefix to use for the bucket's access logs */
  serverAccessLogsPrefix?: string;
  
  /** The inventory configuration of the bucket */
  inventories?: Inventory[];
  
  /** The metrics configuration of this bucket */
  metrics?: BucketMetrics[];
  
  /** Whether this bucket should have transfer acceleration turned on */
  transferAcceleration?: boolean;
  
  /** Whether to enforce SSL-only access to the bucket */
  enforceSSL?: boolean;
  
  /** Whether this bucket should send notifications to Amazon EventBridge */
  eventBridgeEnabled?: boolean;
  
  /** Policy to apply when the bucket is removed from this stack */
  removalPolicy?: RemovalPolicy;
  
  /** Whether all objects should be automatically deleted when the bucket is removed */
  autoDeleteObjects?: boolean;
  
  /** The role to be used by the notifications handler */
  notificationsHandlerRole?: iam.IRole;
}

/**
 * Attributes required to import an existing bucket
 */
interface BucketAttributes {
  /** The ARN of the bucket */
  bucketArn?: string;
  
  /** The name of the bucket */
  bucketName?: string;
  
  /** The domain name of the bucket */
  bucketDomainName?: string;
  
  /** The website URL of the bucket */
  bucketWebsiteUrl?: string;
  
  /** The regional domain name of the bucket */
  bucketRegionalDomainName?: string;
  
  /** The dual-stack domain name of the bucket */
  bucketDualStackDomainName?: string;
  
  /** KMS encryption key, if this bucket is encrypted */
  encryptionKey?: kms.IKey;
  
  /** If this bucket has been configured for static website hosting */
  isWebsite?: boolean;
  
  /** The region this existing bucket is in */
  region?: string;
}

/**
 * Parses an S3 bucket ARN into its components
 * @param arn - The S3 bucket ARN to parse
 * @returns Parsed ARN components
 */
function parseBucketArn(arn: string): ArnComponents;

/**
 * Extracts the bucket name from an S3 bucket ARN
 * @param arn - The S3 bucket ARN
 * @returns The bucket name
 */
function parseBucketName(arn: string): string;