@intentius/chant-lexicon-aws 0.0.24 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.0.24",
+  "version": "0.1.1",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -43,11 +43,14 @@
     "prepack": "bun run generate && bun run bundle && bun run validate"
   },
   "dependencies": {
-    "@intentius/chant": "0.0.22",
     "fflate": "^0.8.2",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
+    "@intentius/chant": "0.1.1",
     "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@intentius/chant": "^0.1.0"
   }
 }

package/src/codegen/docs.ts

@@ -169,7 +169,9 @@ Reference parameters with \`Ref\`:
 
 ## Outputs
 
-Use \`output()\` to create explicit stack outputs. Cross-resource \`AttrRef\` usage is also auto-detected and promoted to outputs when needed.
+Use \`output()\` to create explicit stack outputs. Accepts an \`AttrRef\` (resource attribute)
+or any intrinsic (e.g. \`Sub\`, \`Join\`) for computed values. Cross-resource \`AttrRef\` usage
+is also auto-detected and promoted to outputs when needed.
 
 {{file:docs-snippets/src/output-explicit.ts}}
 
@@ -183,6 +185,12 @@ Produces:
 }
 \`\`\`
 
+Use \`Sub\` to export a computed value like a constructed URL:
+
+\`\`\`typescript
+export const solrUrl = output(Sub\`http://\${Ref(albDnsName)}/solr\`, "solrUrl");
+\`\`\`
+
 ## Pseudo-parameters
 
 Runtime context values available in every template, accessed via the \`AWS\` namespace:

package/src/composites/efs-with-access-point.ts

@@ -0,0 +1,90 @@
+import { Composite } from "@intentius/chant";
+import {
+  EFSFileSystem,
+  EFSFileSystem_ElasticFileSystemTag,
+  EFSAccessPoint,
+  EFSAccessPoint_PosixUser,
+  EFSAccessPoint_RootDirectory,
+  EFSAccessPoint_CreationInfo,
+  EFSAccessPoint_AccessPointTag,
+  SecurityGroup,
+  SecurityGroup_Ingress,
+} from "../generated";
+
+export interface EfsWithAccessPointProps {
+  name: string;
+  vpcId: string;
+  uid: string;
+  gid: string;
+  rootPath: string;
+  permissions?: string;
+  /** CIDR allowed inbound on NFS port 2049. Mutually exclusive with sourceSecurityGroupId.
+   *  When neither ingressCidr nor sourceSecurityGroupId is set, no inline ingress rule is created
+   *  (add a cross-stack EC2SecurityGroupIngress separately). */
+  ingressCidr?: string;
+  /** Security group ID allowed inbound on NFS port 2049. When provided, overrides ingressCidr. */
+  sourceSecurityGroupId?: string;
+  performanceMode?: "generalPurpose" | "maxIO";
+  throughputMode?: "bursting" | "provisioned" | "elastic";
+}
+
+export const EfsWithAccessPoint = Composite<EfsWithAccessPointProps>((props) => {
+  const ingressRules: SecurityGroup_Ingress[] = [];
+  if (props.sourceSecurityGroupId) {
+    ingressRules.push(new SecurityGroup_Ingress({
+      IpProtocol: "tcp",
+      FromPort: 2049,
+      ToPort: 2049,
+      SourceSecurityGroupId: props.sourceSecurityGroupId,
+    }));
+  } else if (props.ingressCidr) {
+    ingressRules.push(new SecurityGroup_Ingress({
+      IpProtocol: "tcp",
+      FromPort: 2049,
+      ToPort: 2049,
+      CidrIp: props.ingressCidr,
+    }));
+  }
+
+  const securityGroup = new SecurityGroup({
+    GroupDescription: "EFS mount target SG",
+    VpcId: props.vpcId,
+    ...(ingressRules.length > 0 ? { SecurityGroupIngress: ingressRules } : {}),
+  });
+
+  const nameTag = new EFSFileSystem_ElasticFileSystemTag({
+    Key: "Name",
+    Value: props.name,
+  });
+
+  const fs = new EFSFileSystem({
+    Encrypted: true,
+    PerformanceMode: props.performanceMode ?? "generalPurpose",
+    ThroughputMode: props.throughputMode ?? "bursting",
+    FileSystemTags: [nameTag],
+  });
+
+  const posixUser = new EFSAccessPoint_PosixUser({ Uid: props.uid, Gid: props.gid });
+
+  const creationInfo = new EFSAccessPoint_CreationInfo({
+    OwnerUid: props.uid,
+    OwnerGid: props.gid,
+    Permissions: props.permissions ?? "755",
+  });
+
+  const rootDirectory = new EFSAccessPoint_RootDirectory({
+    Path: props.rootPath,
+    CreationInfo: creationInfo,
+  });
+
+  const apNameTag = new EFSAccessPoint_AccessPointTag({ Key: "Name", Value: props.name });
+
+  const accessPoint = new EFSAccessPoint({
+    FileSystemId: fs.FileSystemId,
+    PosixUser: posixUser,
+    RootDirectory: rootDirectory,
+    AccessPointTags: [apNameTag],
+  });
+
+  return { securityGroup, fs, accessPoint };
+}, "EfsWithAccessPoint");

package/src/composites/fargate-service.ts

@@ -6,9 +6,12 @@ import {
   EcsService_AwsVpcConfiguration,
   TaskDefinition,
   TaskDefinition_ContainerDefinition,
+  TaskDefinition_MountPoint,
   TaskDefinition_PortMapping,
   TaskDefinition_LogConfiguration,
   TaskDefinition_KeyValuePair,
+  TaskDefinition_EFSVolumeConfiguration,
+  TaskDefinition_Volume,
   TargetGroup,
   ListenerRule,
   ListenerRule_Action,
@@ -20,8 +23,12 @@ import {
   LogGroup,
   Role,
   Role_Policy,
+  ScalableTarget,
+  ApplicationAutoScalingScalingPolicy,
+  ApplicationAutoScalingScalingPolicy_TargetTrackingScalingPolicyConfiguration,
+  ApplicationAutoScalingScalingPolicy_PredefinedMetricSpecification,
 } from "../generated";
-import { Sub } from "../intrinsics";
+import { Sub, Join, Select, Split } from "../intrinsics";
 import { ecsTrustPolicy } from "./ecs-trust-policy";
 
 export interface FargateServiceProps {
@@ -42,8 +49,25 @@ export interface FargateServiceProps {
   cpu?: string;
   memory?: string;
   desiredCount?: number;
+
+  // Autoscaling
+  autoscaling?: {
+    minCapacity?: number;
+    maxCapacity: number;
+    cpuTarget?: number;
+    scaleInCooldown?: number;
+    scaleOutCooldown?: number;
+  };
   environment?: Record<string, string>;
   command?: string[];
+  mountPoints?: TaskDefinition_MountPoint[];
+  efsMounts?: Array<{
+    fileSystemId: string;
+    accessPointId?: string;
+    containerPath: string;
+    volumeName?: string;
+    transitEncryption?: "ENABLED" | "DISABLED";
+  }>;
 
   // Networking
   vpcId: string;
@@ -78,10 +102,17 @@ export const FargateService = Composite<FargateServiceProps>((props) => {
   const logRetentionDays = props.logRetentionDays ?? 30;
   const { defaults: defs } = props;
 
+  // Auto-inject EFS managed policy when efsMounts are present
+  const EFS_POLICY = "arn:aws:iam::aws:policy/AmazonElasticFileSystemClientReadWriteAccess";
+  const managedPolicies = props.ManagedPolicyArns ? [...props.ManagedPolicyArns] : [];
+  if (props.efsMounts?.length && !managedPolicies.includes(EFS_POLICY)) {
+    managedPolicies.push(EFS_POLICY);
+  }
+
   // Task role — app permissions
   const taskRole = new Role(mergeDefaults({
     AssumeRolePolicyDocument: ecsTrustPolicy,
-    ManagedPolicyArns: props.ManagedPolicyArns,
+    ManagedPolicyArns: managedPolicies.length > 0 ? managedPolicies : undefined,
     Policies: props.Policies,
   }, defs?.taskRole));
 
@@ -114,6 +145,27 @@ export const FargateService = Composite<FargateServiceProps>((props) => {
     }
   }
 
+  // EFS volumes and mount points
+  const efsVolumes = (props.efsMounts ?? []).map((m, i) =>
+    new TaskDefinition_Volume({
+      Name: m.volumeName ?? `efs-${i}`,
+      EFSVolumeConfiguration: new TaskDefinition_EFSVolumeConfiguration({
+        FileSystemId: m.fileSystemId,
+        ...(m.accessPointId && { AuthorizationConfig: { AccessPointId: m.accessPointId } }),
+        TransitEncryption: m.transitEncryption ?? "ENABLED",
+      }),
+    }),
+  );
+
+  const efsMountPoints = (props.efsMounts ?? []).map((m, i) =>
+    new TaskDefinition_MountPoint({
+      ContainerPath: m.containerPath,
+      SourceVolume: m.volumeName ?? `efs-${i}`,
+    }),
+  );
+
+  const allMountPoints = [...efsMountPoints, ...(props.mountPoints ?? [])];
+
   const container = new TaskDefinition_ContainerDefinition({
     Name: "app",
     Image: props.image,
@@ -122,6 +174,7 @@ export const FargateService = Composite<FargateServiceProps>((props) => {
     LogConfiguration: logConfiguration,
     Environment: environmentVars.length > 0 ? environmentVars : undefined,
     Command: props.command,
+    MountPoints: allMountPoints.length > 0 ? allMountPoints : undefined,
   });
 
   // Task definition
@@ -133,6 +186,7 @@ export const FargateService = Composite<FargateServiceProps>((props) => {
     ExecutionRoleArn: props.executionRoleArn,
     TaskRoleArn: taskRole.Arn,
     ContainerDefinitions: [container],
+    ...(efsVolumes.length > 0 && { Volumes: efsVolumes }),
   }, defs?.taskDef));
 
   // Task security group — ingress on container port from ALB SG
@@ -228,6 +282,41 @@ export const FargateService = Composite<FargateServiceProps>((props) => {
     { DependsOn: [rule] },
   );
 
+  let scalableTarget: InstanceType<typeof ScalableTarget> | undefined;
+  let scalingPolicy: InstanceType<typeof ApplicationAutoScalingScalingPolicy> | undefined;
+
+  if (props.autoscaling) {
+    const { minCapacity = 1, maxCapacity, cpuTarget = 60, scaleInCooldown, scaleOutCooldown } = props.autoscaling;
+
+    const resourceId = Join("/", ["service", Select(1, Split("/", props.clusterArn)), service.Name]);
+
+    scalableTarget = new ScalableTarget({
+      ServiceNamespace: "ecs",
+      ScalableDimension: "ecs:service:DesiredCount",
+      ResourceId: resourceId,
+      MinCapacity: minCapacity,
+      MaxCapacity: maxCapacity,
+    });
+
+    const trackingConfig = new ApplicationAutoScalingScalingPolicy_TargetTrackingScalingPolicyConfiguration({
+      TargetValue: cpuTarget,
+      PredefinedMetricSpecification: new ApplicationAutoScalingScalingPolicy_PredefinedMetricSpecification({
+        PredefinedMetricType: "ECSServiceAverageCPUUtilization",
+      }),
+      ...(scaleInCooldown !== undefined && { ScaleInCooldown: scaleInCooldown }),
+      ...(scaleOutCooldown !== undefined && { ScaleOutCooldown: scaleOutCooldown }),
+    });
+
+    scalingPolicy = new ApplicationAutoScalingScalingPolicy({
+      PolicyName: Sub`\${AWS::StackName}-cpu`,
+      PolicyType: "TargetTrackingScaling",
+      ServiceNamespace: "ecs",
+      ScalableDimension: "ecs:service:DesiredCount",
+      ResourceId: resourceId,
+      TargetTrackingScalingPolicyConfiguration: trackingConfig,
+    });
+  }
+
   return {
     taskRole,
     logGroup,
@@ -236,5 +325,7 @@ export const FargateService = Composite<FargateServiceProps>((props) => {
     targetGroup,
     rule,
     service,
+    ...(scalableTarget ? { scalableTarget } : {}),
+    ...(scalingPolicy ? { scalingPolicy } : {}),
   };
 }, "FargateService");

package/src/composites/index.ts

@@ -24,3 +24,5 @@ export { FargateService } from "./fargate-service";
 export type { FargateServiceProps } from "./fargate-service";
 export { RdsInstance, RdsInstance as RdsPostgres } from "./rds-instance";
 export type { RdsInstanceProps, RdsInstanceProps as RdsPostgresProps } from "./rds-instance";
+export { EfsWithAccessPoint } from "./efs-with-access-point";
+export type { EfsWithAccessPointProps } from "./efs-with-access-point";

package/src/composites/lambda-dynamodb.ts

@@ -1,5 +1,12 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
-import { Table, Table_AttributeDefinition, Table_KeySchema, Role_Policy } from "../generated";
+import {
+  Table,
+  Table_AttributeDefinition,
+  Table_KeySchema,
+  Table_StreamSpecification,
+  Role_Policy,
+  EventSourceMapping,
+} from "../generated";
 import { DynamoDBActions } from "../actions/dynamodb";
 import { LambdaFunction, type LambdaFunctionProps } from "./lambda-function";
 
@@ -7,9 +14,16 @@ export interface LambdaDynamoDBProps extends LambdaFunctionProps {
   tableName?: string;
   partitionKey: string;
   sortKey?: string;
-  access?: "ReadOnly" | "ReadWrite" | "Full";
+  access?: "ReadOnly" | "ReadWrite" | "Full" | "None";
+  streams?: {
+    viewType?: "NEW_IMAGE" | "OLD_IMAGE" | "NEW_AND_OLD_IMAGES" | "KEYS_ONLY";
+    batchSize?: number;
+    startingPosition?: "TRIM_HORIZON" | "LATEST";
+    bisectOnFunctionError?: boolean;
+  };
   defaults?: LambdaFunctionProps["defaults"] & {
     table?: Partial<ConstructorParameters<typeof Table>[0]>;
+    eventSourceMapping?: Partial<ConstructorParameters<typeof EventSourceMapping>[0]>;
   };
 }
 
@@ -37,26 +51,49 @@ export const LambdaDynamoDB = Composite<LambdaDynamoDBProps>((props) => {
     BillingMode: "PAY_PER_REQUEST",
     AttributeDefinitions: attributeDefinitions,
     KeySchema: keySchema,
+    ...(props.streams && {
+      StreamSpecification: new Table_StreamSpecification({
+        StreamViewType: props.streams.viewType ?? "NEW_AND_OLD_IMAGES",
+      }),
+    }),
   }, defaults?.table));
 
   const access = props.access ?? "ReadWrite";
-  const dynamoPolicyDocument = {
-    Version: "2012-10-17",
-    Statement: [
-      {
-        Effect: "Allow",
-        Action: DynamoDBActions[access],
-        Resource: table.Arn,
+  const policies: InstanceType<typeof Role_Policy>[] = [];
+
+  if (access !== "None") {
+    policies.push(new Role_Policy({
+      PolicyName: `DynamoDB${access}`,
+      PolicyDocument: {
+        Version: "2012-10-17",
+        Statement: [{ Effect: "Allow", Action: DynamoDBActions[access], Resource: table.Arn }],
       },
-    ],
-  };
+    }));
+  }
 
-  const dynamoPolicy = new Role_Policy({
-    PolicyName: `DynamoDB${access}`,
-    PolicyDocument: dynamoPolicyDocument,
-  });
+  if (props.streams) {
+    policies.push(new Role_Policy({
+      PolicyName: "DynamoDBStreamRead",
+      PolicyDocument: {
+        Version: "2012-10-17",
+        Statement: [{
+          Effect: "Allow",
+          Action: [
+            "dynamodb:GetRecords",
+            "dynamodb:GetShardIterator",
+            "dynamodb:DescribeStream",
+            "dynamodb:ListStreams",
+          ],
+          Resource: table.StreamArn,
+        }],
+      },
+    }));
+  }
+
+  if (props.Policies) {
+    policies.push(...props.Policies);
+  }
 
-  const policies = props.Policies ? [dynamoPolicy, ...props.Policies] : [dynamoPolicy];
   const env = props.Environment ?? { Variables: {} };
   const variables = { ...((env as any).Variables ?? {}), TABLE_NAME: table.Ref };
   const { role, func } = LambdaFunction({
@@ -65,5 +102,17 @@ export const LambdaDynamoDB = Composite<LambdaDynamoDBProps>((props) => {
     Environment: { Variables: variables },
   });
 
-  return { table, role, func };
+  let eventSourceMapping: InstanceType<typeof EventSourceMapping> | undefined;
+  if (props.streams) {
+    const { startingPosition = "TRIM_HORIZON", batchSize, bisectOnFunctionError } = props.streams;
+    eventSourceMapping = new EventSourceMapping(mergeDefaults({
+      FunctionName: func.Arn,
+      EventSourceArn: table.StreamArn,
+      StartingPosition: startingPosition,
+      ...(batchSize !== undefined && { BatchSize: batchSize }),
+      ...(bisectOnFunctionError !== undefined && { BisectBatchOnFunctionError: bisectOnFunctionError }),
+    }, defaults?.eventSourceMapping));
+  }
+
+  return { table, role, func, ...(eventSourceMapping ? { eventSourceMapping } : {}) };
 }, "LambdaDynamoDB");

package/src/composites/lambda-s3.ts

@@ -5,33 +5,36 @@ import {
   Bucket_ServerSideEncryptionRule,
   Bucket_ServerSideEncryptionByDefault,
   Bucket_PublicAccessBlockConfiguration,
+  Bucket_NotificationConfiguration,
+  Bucket_LambdaConfiguration,
+  Permission,
   Role_Policy,
 } from "../generated";
-import { Sub } from "../intrinsics";
+import { Sub, Join } from "../intrinsics";
 import { S3Actions } from "../actions/s3";
 import { LambdaFunction, type LambdaFunctionProps } from "./lambda-function";
 
 export interface LambdaS3Props extends LambdaFunctionProps {
   bucketName?: string;
   access?: "ReadOnly" | "ReadWrite" | "Full";
+  trigger?: {
+    events?: string[];
+    prefix?: string;
+    suffix?: string;
+  };
   defaults?: LambdaFunctionProps["defaults"] & {
     bucket?: Partial<ConstructorParameters<typeof Bucket>[0]>;
   };
 }
 
 export const LambdaS3 = Composite<LambdaS3Props>((props) => {
-  const encryptionDefault = new Bucket_ServerSideEncryptionByDefault({
-    SSEAlgorithm: "AES256",
-  });
-
+  const encryptionDefault = new Bucket_ServerSideEncryptionByDefault({ SSEAlgorithm: "AES256" });
   const encryptionRule = new Bucket_ServerSideEncryptionRule({
     ServerSideEncryptionByDefault: encryptionDefault,
   });
-
   const bucketEncryption = new Bucket_BucketEncryption({
     ServerSideEncryptionConfiguration: [encryptionRule],
   });
-
   const publicAccessBlock = new Bucket_PublicAccessBlockConfiguration({
     BlockPublicAcls: true,
     BlockPublicPolicy: true,
@@ -40,30 +43,73 @@ export const LambdaS3 = Composite<LambdaS3Props>((props) => {
   });
 
   const { defaults } = props;
+  const access = props.access ?? "ReadWrite";
+
+  if (props.trigger) {
+    // Create Lambda first to break the circular CFN dependency.
+    // Compute bucket ARN from name (no GetAtt on bucket → no resource dep).
+    const name = props.bucketName ?? Sub`\${AWS::StackName}-bucket`;
+    const bucketArnBase = Join("", ["arn:aws:s3:::", name]);
+    const bucketArnWildcard = Join("", ["arn:aws:s3:::", name, "/*"]);
+
+    const s3Policy = new Role_Policy({
+      PolicyName: `S3${access}`,
+      PolicyDocument: {
+        Version: "2012-10-17",
+        Statement: [{ Effect: "Allow", Action: S3Actions[access], Resource: [bucketArnBase, bucketArnWildcard] }],
+      },
+    });
+
+    const policies = props.Policies ? [s3Policy, ...props.Policies] : [s3Policy];
+    const env = props.Environment ?? { Variables: {} };
+    const variables = { ...((env as any).Variables ?? {}), BUCKET_NAME: name };
+    const { role, func } = LambdaFunction({ ...props, Policies: policies, Environment: { Variables: variables } });
 
+    const permission = new Permission({
+      FunctionName: func.Arn,
+      Action: "lambda:InvokeFunction",
+      Principal: "s3.amazonaws.com",
+      SourceArn: bucketArnBase,
+    });
+
+    const { events = ["s3:ObjectCreated:*"], prefix, suffix } = props.trigger;
+    const rules: Array<{ Name: string; Value: string }> = [];
+    if (prefix) rules.push({ Name: "prefix", Value: prefix });
+    if (suffix) rules.push({ Name: "suffix", Value: suffix });
+
+    const lambdaConfigs = events.map((event) => new Bucket_LambdaConfiguration({
+      Event: event,
+      Function: func.Arn,
+      ...(rules.length > 0 && { Filter: { S3Key: { Rules: rules } } }),
+    }));
+
+    const notificationConfig = new Bucket_NotificationConfiguration({
+      LambdaConfigurations: lambdaConfigs,
+    });
+
+    const bucket = new Bucket(mergeDefaults({
+      BucketName: props.bucketName,
+      BucketEncryption: bucketEncryption,
+      PublicAccessBlockConfiguration: publicAccessBlock,
+      NotificationConfiguration: notificationConfig,
+    }, defaults?.bucket), { DependsOn: [permission] });
+
+    return { bucket, role, func, permission };
+  }
+
+  // Non-trigger path: original flow
   const bucket = new Bucket(mergeDefaults({
     BucketName: props.bucketName,
     BucketEncryption: bucketEncryption,
     PublicAccessBlockConfiguration: publicAccessBlock,
   }, defaults?.bucket));
 
-  const access = props.access ?? "ReadWrite";
   const s3PolicyDocument = {
     Version: "2012-10-17",
-    Statement: [
-      {
-        Effect: "Allow",
-        Action: S3Actions[access],
-        Resource: [bucket.Arn, Sub`${bucket.Arn}/*`],
-      },
-    ],
+    Statement: [{ Effect: "Allow", Action: S3Actions[access], Resource: [bucket.Arn, Sub`${bucket.Arn}/*`] }],
   };
 
-  const s3Policy = new Role_Policy({
-    PolicyName: `S3${access}`,
-    PolicyDocument: s3PolicyDocument,
-  });
-
+  const s3Policy = new Role_Policy({ PolicyName: `S3${access}`, PolicyDocument: s3PolicyDocument });
   const policies = props.Policies ? [s3Policy, ...props.Policies] : [s3Policy];
   const env = props.Environment ?? { Variables: {} };
   const variables = { ...((env as any).Variables ?? {}), BUCKET_NAME: bucket.Ref };