@intentius/chant-lexicon-aws 0.1.0 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -47,7 +47,7 @@
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
-    "@intentius/chant": "0.1.0",
+    "@intentius/chant": "0.1.4",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {

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/composites.test.ts

@@ -14,6 +14,8 @@ import { FargateAlb } from "./fargate-alb";
 import { AlbShared } from "./alb-shared";
 import { FargateService } from "./fargate-service";
 import { RdsInstance } from "./rds-instance";
+import { Ec2InstanceRole } from "./ec2-instance-role";
+import { MinimalVpc } from "./minimal-vpc";
 
 const baseProps = {
   name: "TestFunc",
@@ -865,3 +867,66 @@ describe("per-member defaults", () => {
     expect(funcPropsA.Timeout).toBe(funcPropsB.Timeout);
   });
 });
+
+describe("Ec2InstanceRole", () => {
+  test("returns role and instanceProfile members", () => {
+    const instance = Ec2InstanceRole({});
+    expect(instance.role).toBeDefined();
+    expect(instance.instanceProfile).toBeDefined();
+    expect(Object.keys(instance.members)).toEqual(["role", "instanceProfile"]);
+  });
+
+  test("role has EC2 trust policy", () => {
+    const instance = Ec2InstanceRole({});
+    const roleProps = (instance.role as any).props;
+    expect(roleProps.AssumeRolePolicyDocument.Statement[0].Principal.Service).toBe("ec2.amazonaws.com");
+  });
+
+  test("ManagedPolicyArns are passed through", () => {
+    const arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore";
+    const instance = Ec2InstanceRole({ ManagedPolicyArns: [arn] });
+    const roleProps = (instance.role as any).props;
+    expect(roleProps.ManagedPolicyArns).toContain(arn);
+  });
+
+  test("expandComposite produces 2 entries", () => {
+    const expanded = expandComposite("myRole", Ec2InstanceRole({}));
+    expect(expanded.size).toBe(2);
+    expect(expanded.has("myRoleRole")).toBe(true);
+    expect(expanded.has("myRoleInstanceProfile")).toBe(true);
+  });
+});
+
+describe("MinimalVpc", () => {
+  test("returns 8 members", () => {
+    const instance = MinimalVpc({});
+    expect(Object.keys(instance.members)).toEqual([
+      "vpc", "subnet", "igw", "igwAttachment", "routeTable", "defaultRoute", "subnetRta", "securityGroup",
+    ]);
+  });
+
+  test("subnet uses Select/GetAZs for AZ (not a plain string)", () => {
+    const instance = MinimalVpc({});
+    const subnetProps = (instance.subnet as any).props;
+    expect(typeof subnetProps.AvailabilityZone).not.toBe("string");
+  });
+
+  test("vpc cidr defaults to 10.0.0.0/24", () => {
+    const instance = MinimalVpc({});
+    const vpcProps = (instance.vpc as any).props;
+    expect(vpcProps.CidrBlock).toBe("10.0.0.0/24");
+  });
+
+  test("custom cidr is respected", () => {
+    const instance = MinimalVpc({ cidr: "192.168.0.0/16", subnetCidr: "192.168.1.0/24" });
+    const vpcProps = (instance.vpc as any).props;
+    const subnetProps = (instance.subnet as any).props;
+    expect(vpcProps.CidrBlock).toBe("192.168.0.0/16");
+    expect(subnetProps.CidrBlock).toBe("192.168.1.0/24");
+  });
+
+  test("expandComposite produces 8 entries", () => {
+    const expanded = expandComposite("net", MinimalVpc({}));
+    expect(expanded.size).toBe(8);
+  });
+});

package/src/composites/ec2-instance-role.ts

@@ -0,0 +1,39 @@
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Role, InstanceProfile } from "../generated";
+import { Ref } from "../intrinsics";
+
+export interface Ec2InstanceRoleProps {
+  ManagedPolicyArns?: string[];
+  Policies?: ConstructorParameters<typeof Role>[0]["Policies"];
+  defaults?: {
+    role?: Partial<ConstructorParameters<typeof Role>[0]>;
+    instanceProfile?: Partial<ConstructorParameters<typeof InstanceProfile>[0]>;
+  };
+}
+
+const EC2_ASSUME_ROLE = {
+  Version: "2012-10-17" as const,
+  Statement: [
+    {
+      Effect: "Allow" as const,
+      Principal: { Service: "ec2.amazonaws.com" },
+      Action: "sts:AssumeRole",
+    },
+  ],
+};
+
+export const Ec2InstanceRole = Composite<Ec2InstanceRoleProps>((props) => {
+  const { defaults } = props;
+
+  const role = new Role(mergeDefaults({
+    AssumeRolePolicyDocument: EC2_ASSUME_ROLE,
+    ManagedPolicyArns: props.ManagedPolicyArns ?? [],
+    Policies: props.Policies ?? [],
+  }, defaults?.role));
+
+  const instanceProfile = new InstanceProfile(mergeDefaults({
+    Roles: [Ref(role)],
+  }, defaults?.instanceProfile));
+
+  return { role, instanceProfile };
+}, "Ec2InstanceRole");

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,13 @@ import {
   EcsService_AwsVpcConfiguration,
   TaskDefinition,
   TaskDefinition_ContainerDefinition,
+  TaskDefinition_MountPoint,
   TaskDefinition_PortMapping,
   TaskDefinition_LogConfiguration,
   TaskDefinition_KeyValuePair,
+  TaskDefinition_EFSVolumeConfiguration,
+  TaskDefinition_Volume,
+  TaskDefinition_Ulimit,
   TargetGroup,
   ListenerRule,
   ListenerRule_Action,
@@ -20,8 +24,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,14 +50,34 @@ 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;
   privateSubnetIds: string[];
   healthCheckPath?: string;
 
+  // Ulimits (container-level)
+  ulimits?: Array<{ name: string; softLimit: number; hardLimit: number }>;
+
   // IAM
   ManagedPolicyArns?: string[];
   Policies?: InstanceType<typeof Role_Policy>[];
@@ -78,10 +106,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 +149,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 +178,12 @@ export const FargateService = Composite<FargateServiceProps>((props) => {
     LogConfiguration: logConfiguration,
     Environment: environmentVars.length > 0 ? environmentVars : undefined,
     Command: props.command,
+    MountPoints: allMountPoints.length > 0 ? allMountPoints : undefined,
+    Ulimits: props.ulimits?.map(u => new TaskDefinition_Ulimit({
+      Name: u.name,
+      SoftLimit: u.softLimit,
+      HardLimit: u.hardLimit,
+    })),
   });
 
   // Task definition
@@ -133,6 +195,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 +291,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 +334,7 @@ export const FargateService = Composite<FargateServiceProps>((props) => {
     targetGroup,
     rule,
     service,
+    ...(scalableTarget ? { scalableTarget } : {}),
+    ...(scalingPolicy ? { scalingPolicy } : {}),
   };
 }, "FargateService");

package/src/composites/index.ts

@@ -24,3 +24,11 @@ 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";
+export { SolrFargateService } from "./solr-fargate-service";
+export type { SolrFargateServiceProps } from "./solr-fargate-service";
+export { Ec2InstanceRole } from "./ec2-instance-role";
+export type { Ec2InstanceRoleProps } from "./ec2-instance-role";
+export { MinimalVpc } from "./minimal-vpc";
+export type { MinimalVpcProps } from "./minimal-vpc";

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-function.ts

@@ -1,5 +1,6 @@
 import { Composite, withDefaults, mergeDefaults } from "@intentius/chant";
 import { Role, Function, Function_VpcConfig, Role_Policy } from "../generated";
+import { Sub } from "../intrinsics";
 
 const lambdaTrustPolicy = {
   Version: "2012-10-17" as const,
@@ -18,7 +19,7 @@ const VPC_ACCESS_ARN =
   "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole";
 
 export interface LambdaFunctionProps {
-  name: string;
+  name: string | ReturnType<typeof Sub>;
   Runtime: string;
   Handler: string;
   Code: ConstructorParameters<typeof Function>[0]["Code"];