@intentius/chant-lexicon-aws 0.0.8 → 0.0.9

package/src/composites/index.ts

@@ -0,0 +1,20 @@
+export { LambdaFunction, LambdaNode, LambdaPython, NodeLambda, PythonLambda } from "./lambda-function";
+export type { LambdaFunctionProps } from "./lambda-function";
+export { LambdaApi } from "./lambda-api";
+export type { LambdaApiProps } from "./lambda-api";
+export { LambdaScheduled, ScheduledLambda } from "./scheduled-lambda";
+export type { ScheduledLambdaProps } from "./scheduled-lambda";
+export { LambdaSqs } from "./lambda-sqs";
+export type { LambdaSqsProps } from "./lambda-sqs";
+export { LambdaEventBridge } from "./lambda-eventbridge";
+export type { LambdaEventBridgeProps } from "./lambda-eventbridge";
+export { LambdaDynamoDB } from "./lambda-dynamodb";
+export type { LambdaDynamoDBProps } from "./lambda-dynamodb";
+export { LambdaS3 } from "./lambda-s3";
+export type { LambdaS3Props } from "./lambda-s3";
+export { LambdaSns } from "./lambda-sns";
+export type { LambdaSnsProps } from "./lambda-sns";
+export { VpcDefault } from "./vpc-default";
+export type { VpcDefaultProps } from "./vpc-default";
+export { FargateAlb } from "./fargate-alb";
+export type { FargateAlbProps } from "./fargate-alb";

package/src/composites/lambda-api.ts

@@ -0,0 +1,20 @@
+import { Composite } from "@intentius/chant";
+import { Permission } from "../generated";
+import { LambdaFunction, type LambdaFunctionProps } from "./lambda-function";
+
+export interface LambdaApiProps extends LambdaFunctionProps {
+  sourceArn?: string;
+}
+
+export const LambdaApi = Composite<LambdaApiProps>((props) => {
+  const { role, func } = LambdaFunction(props);
+
+  const permission = new Permission({
+    FunctionName: func.Arn,
+    Action: "lambda:InvokeFunction",
+    Principal: "apigateway.amazonaws.com",
+    SourceArn: props.sourceArn,
+  });
+
+  return { role, func, permission };
+}, "LambdaApi");

package/src/composites/lambda-dynamodb.ts

@@ -0,0 +1,64 @@
+import { Composite } from "@intentius/chant";
+import { Table, Table_AttributeDefinition, Table_KeySchema, Role_Policy } from "../generated";
+import { DynamoDBActions } from "../actions/dynamodb";
+import { LambdaFunction, type LambdaFunctionProps } from "./lambda-function";
+
+export interface LambdaDynamoDBProps extends LambdaFunctionProps {
+  tableName?: string;
+  partitionKey: string;
+  sortKey?: string;
+  access?: "ReadOnly" | "ReadWrite" | "Full";
+}
+
+export const LambdaDynamoDB = Composite<LambdaDynamoDBProps>((props) => {
+  const attributeDefinitions = [
+    new Table_AttributeDefinition({ AttributeName: props.partitionKey, AttributeType: "S" }),
+  ];
+  const keySchema: InstanceType<typeof Table_KeySchema>[] = [
+    new Table_KeySchema({ AttributeName: props.partitionKey, KeyType: "HASH" }),
+  ];
+
+  if (props.sortKey) {
+    attributeDefinitions.push(
+      new Table_AttributeDefinition({ AttributeName: props.sortKey, AttributeType: "S" }),
+    );
+    keySchema.push(
+      new Table_KeySchema({ AttributeName: props.sortKey, KeyType: "RANGE" }),
+    );
+  }
+
+  const table = new Table({
+    TableName: props.tableName,
+    BillingMode: "PAY_PER_REQUEST",
+    AttributeDefinitions: attributeDefinitions,
+    KeySchema: keySchema,
+  });
+
+  const access = props.access ?? "ReadWrite";
+  const dynamoPolicyDocument = {
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Allow",
+        Action: DynamoDBActions[access],
+        Resource: table.Arn,
+      },
+    ],
+  };
+
+  const dynamoPolicy = new Role_Policy({
+    PolicyName: `DynamoDB${access}`,
+    PolicyDocument: dynamoPolicyDocument,
+  });
+
+  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({
+    ...props,
+    Policies: policies,
+    Environment: { Variables: variables },
+  });
+
+  return { table, role, func };
+}, "LambdaDynamoDB");

package/src/composites/lambda-eventbridge.ts

@@ -0,0 +1,36 @@
+import { Composite } from "@intentius/chant";
+import { EventRule, EventRule_Target, Permission } from "../generated";
+import { LambdaFunction, type LambdaFunctionProps } from "./lambda-function";
+
+export interface LambdaEventBridgeProps extends LambdaFunctionProps {
+  ruleName?: string;
+  schedule?: string;
+  eventPattern?: Record<string, unknown>;
+  enabled?: boolean;
+}
+
+export const LambdaEventBridge = Composite<LambdaEventBridgeProps>((props) => {
+  const { role, func } = LambdaFunction(props);
+
+  const rule = new EventRule({
+    Name: props.ruleName,
+    ScheduleExpression: props.schedule,
+    EventPattern: props.eventPattern,
+    State: (props.enabled ?? true) ? "ENABLED" : "DISABLED",
+    Targets: [
+      new EventRule_Target({
+        Arn: func.Arn,
+        Id: "Target0",
+      }),
+    ],
+  });
+
+  const permission = new Permission({
+    FunctionName: func.Arn,
+    Action: "lambda:InvokeFunction",
+    Principal: "events.amazonaws.com",
+    SourceArn: rule.Arn,
+  });
+
+  return { rule, role, func, permission };
+}, "LambdaEventBridge");

package/src/composites/lambda-function.ts

@@ -0,0 +1,76 @@
+import { Composite, withDefaults } from "@intentius/chant";
+import { Role, Function, Function_VpcConfig, Role_Policy } from "../generated";
+
+const lambdaTrustPolicy = {
+  Version: "2012-10-17" as const,
+  Statement: [
+    {
+      Effect: "Allow" as const,
+      Principal: { Service: "lambda.amazonaws.com" },
+      Action: "sts:AssumeRole",
+    },
+  ],
+};
+
+const BASIC_EXECUTION_ARN =
+  "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole";
+const VPC_ACCESS_ARN =
+  "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole";
+
+export interface LambdaFunctionProps {
+  name: string;
+  Runtime: string;
+  Handler: string;
+  Code: ConstructorParameters<typeof Function>[0]["Code"];
+  Timeout?: number;
+  MemorySize?: number;
+  Environment?: ConstructorParameters<typeof Function>[0]["Environment"];
+  ManagedPolicyArns?: string[];
+  Policies?: InstanceType<typeof Role_Policy>[];
+  VpcConfig?: ConstructorParameters<typeof Function_VpcConfig>[0];
+}
+
+export const LambdaFunction = Composite<LambdaFunctionProps>((props) => {
+  const managedPolicies = [BASIC_EXECUTION_ARN];
+  if (props.VpcConfig) {
+    managedPolicies.push(VPC_ACCESS_ARN);
+  }
+  if (props.ManagedPolicyArns) {
+    managedPolicies.push(...props.ManagedPolicyArns);
+  }
+
+  const role = new Role({
+    AssumeRolePolicyDocument: lambdaTrustPolicy,
+    ManagedPolicyArns: managedPolicies,
+    Policies: props.Policies,
+  });
+
+  const func = new Function({
+    FunctionName: props.name,
+    Runtime: props.Runtime as any,
+    Handler: props.Handler,
+    Code: props.Code,
+    Role: role.Arn,
+    Timeout: props.Timeout ?? 30,
+    MemorySize: props.MemorySize,
+    Environment: props.Environment,
+    VpcConfig: props.VpcConfig ? new Function_VpcConfig(props.VpcConfig) : undefined,
+  });
+
+  return { role, func };
+}, "LambdaFunction");
+
+export const LambdaNode = withDefaults(LambdaFunction, {
+  Runtime: "nodejs20.x",
+  Handler: "index.handler",
+});
+
+export const LambdaPython = withDefaults(LambdaFunction, {
+  Runtime: "python3.12",
+  Handler: "handler.handler",
+});
+
+/** @deprecated Use `LambdaNode` instead */
+export const NodeLambda = LambdaNode;
+/** @deprecated Use `LambdaPython` instead */
+export const PythonLambda = LambdaPython;

package/src/composites/lambda-s3.ts

@@ -0,0 +1,72 @@
+import { Composite } from "@intentius/chant";
+import {
+  Bucket,
+  Bucket_BucketEncryption,
+  Bucket_ServerSideEncryptionRule,
+  Bucket_ServerSideEncryptionByDefault,
+  Bucket_PublicAccessBlockConfiguration,
+  Role_Policy,
+} from "../generated";
+import { Sub } 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";
+}
+
+export const LambdaS3 = Composite<LambdaS3Props>((props) => {
+  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,
+    IgnorePublicAcls: true,
+    RestrictPublicBuckets: true,
+  });
+
+  const bucket = new Bucket({
+    BucketName: props.bucketName,
+    BucketEncryption: bucketEncryption,
+    PublicAccessBlockConfiguration: publicAccessBlock,
+  });
+
+  const access = props.access ?? "ReadWrite";
+  const s3PolicyDocument = {
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Allow",
+        Action: S3Actions[access],
+        Resource: [bucket.Arn, Sub`${bucket.Arn}/*`],
+      },
+    ],
+  };
+
+  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 };
+  const { role, func } = LambdaFunction({
+    ...props,
+    Policies: policies,
+    Environment: { Variables: variables },
+  });
+
+  return { bucket, role, func };
+}, "LambdaS3");

package/src/composites/lambda-sns.ts

@@ -0,0 +1,30 @@
+import { Composite } from "@intentius/chant";
+import { Topic, Subscription, Permission } from "../generated";
+import { LambdaFunction, type LambdaFunctionProps } from "./lambda-function";
+
+export interface LambdaSnsProps extends LambdaFunctionProps {
+  topicName?: string;
+}
+
+export const LambdaSns = Composite<LambdaSnsProps>((props) => {
+  const { role, func } = LambdaFunction(props);
+
+  const topic = new Topic({
+    TopicName: props.topicName,
+  });
+
+  const subscription = new Subscription({
+    TopicArn: topic.TopicArn,
+    Protocol: "lambda",
+    Endpoint: func.Arn,
+  });
+
+  const permission = new Permission({
+    FunctionName: func.Arn,
+    Action: "lambda:InvokeFunction",
+    Principal: "sns.amazonaws.com",
+    SourceArn: topic.TopicArn,
+  });
+
+  return { topic, role, func, subscription, permission };
+}, "LambdaSns");

package/src/composites/lambda-sqs.ts

@@ -0,0 +1,44 @@
+import { Composite } from "@intentius/chant";
+import { Queue, EventSourceMapping, Role_Policy } from "../generated";
+import { SQSActions } from "../actions/sqs";
+import { LambdaFunction, type LambdaFunctionProps } from "./lambda-function";
+
+export interface LambdaSqsProps extends LambdaFunctionProps {
+  queueName?: string;
+  batchSize?: number;
+  maxBatchingWindow?: number;
+}
+
+export const LambdaSqs = Composite<LambdaSqsProps>((props) => {
+  const queue = new Queue({
+    QueueName: props.queueName,
+  });
+
+  const sqsPolicyDocument = {
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Allow",
+        Action: SQSActions.ReceiveMessage,
+        Resource: queue.Arn,
+      },
+    ],
+  };
+
+  const sqsPolicy = new Role_Policy({
+    PolicyName: "SQSReceive",
+    PolicyDocument: sqsPolicyDocument,
+  });
+
+  const policies = props.Policies ? [sqsPolicy, ...props.Policies] : [sqsPolicy];
+  const { role, func } = LambdaFunction({ ...props, Policies: policies });
+
+  new EventSourceMapping({
+    EventSourceArn: queue.Arn,
+    FunctionName: func.Arn,
+    BatchSize: props.batchSize ?? 10,
+    MaximumBatchingWindowInSeconds: props.maxBatchingWindow,
+  });
+
+  return { queue, role, func };
+}, "LambdaSqs");

package/src/composites/scheduled-lambda.ts

@@ -0,0 +1,37 @@
+import { Composite } from "@intentius/chant";
+import { EventRule, EventRule_Target, Permission } from "../generated";
+import { LambdaFunction, type LambdaFunctionProps } from "./lambda-function";
+
+export interface ScheduledLambdaProps extends LambdaFunctionProps {
+  ruleName?: string;
+  schedule: string;
+  enabled?: boolean;
+}
+
+export const LambdaScheduled = Composite<ScheduledLambdaProps>((props) => {
+  const { role, func } = LambdaFunction(props);
+
+  const rule = new EventRule({
+    Name: props.ruleName,
+    ScheduleExpression: props.schedule,
+    State: (props.enabled ?? true) ? "ENABLED" : "DISABLED",
+    Targets: [
+      new EventRule_Target({
+        Arn: func.Arn,
+        Id: "Target0",
+      }),
+    ],
+  });
+
+  const permission = new Permission({
+    FunctionName: func.Arn,
+    Action: "lambda:InvokeFunction",
+    Principal: "events.amazonaws.com",
+    SourceArn: rule.Arn,
+  });
+
+  return { role, func, rule, permission };
+}, "LambdaScheduled");
+
+/** @deprecated Use `LambdaScheduled` instead */
+export const ScheduledLambda = LambdaScheduled;

package/src/composites/vpc-default.ts

@@ -0,0 +1,148 @@
+import { Composite } from "@intentius/chant";
+import {
+  Vpc,
+  Subnet,
+  InternetGateway,
+  VPCGatewayAttachment,
+  RouteTable,
+  EC2Route,
+  SubnetRouteTableAssociation,
+  EIP,
+  NatGateway,
+} from "../generated";
+import { Select, GetAZs } from "../intrinsics";
+
+export interface VpcDefaultProps {
+  cidr?: string;
+  publicSubnet1Cidr?: string;
+  publicSubnet2Cidr?: string;
+  privateSubnet1Cidr?: string;
+  privateSubnet2Cidr?: string;
+}
+
+export const VpcDefault = Composite<VpcDefaultProps>((props) => {
+  const cidr = props.cidr ?? "10.0.0.0/16";
+  const publicSubnet1Cidr = props.publicSubnet1Cidr ?? "10.0.0.0/20";
+  const publicSubnet2Cidr = props.publicSubnet2Cidr ?? "10.0.16.0/20";
+  const privateSubnet1Cidr = props.privateSubnet1Cidr ?? "10.0.128.0/20";
+  const privateSubnet2Cidr = props.privateSubnet2Cidr ?? "10.0.144.0/20";
+
+  const az1 = Select(0, GetAZs(""));
+  const az2 = Select(1, GetAZs(""));
+
+  const vpc = new Vpc({
+    CidrBlock: cidr,
+    EnableDnsSupport: true,
+    EnableDnsHostnames: true,
+  });
+
+  const igw = new InternetGateway({});
+
+  const igwAttachment = new VPCGatewayAttachment({
+    VpcId: vpc.VpcId,
+    InternetGatewayId: igw.InternetGatewayId,
+  });
+
+  // Public subnets
+  const publicSubnet1 = new Subnet({
+    VpcId: vpc.VpcId,
+    CidrBlock: publicSubnet1Cidr,
+    AvailabilityZone: az1,
+    MapPublicIpOnLaunch: true,
+  });
+
+  const publicSubnet2 = new Subnet({
+    VpcId: vpc.VpcId,
+    CidrBlock: publicSubnet2Cidr,
+    AvailabilityZone: az2,
+    MapPublicIpOnLaunch: true,
+  });
+
+  // Private subnets
+  const privateSubnet1 = new Subnet({
+    VpcId: vpc.VpcId,
+    CidrBlock: privateSubnet1Cidr,
+    AvailabilityZone: az1,
+  });
+
+  const privateSubnet2 = new Subnet({
+    VpcId: vpc.VpcId,
+    CidrBlock: privateSubnet2Cidr,
+    AvailabilityZone: az2,
+  });
+
+  // Public route table
+  const publicRouteTable = new RouteTable({
+    VpcId: vpc.VpcId,
+  });
+
+  const publicRoute = new EC2Route(
+    {
+      RouteTableId: publicRouteTable.RouteTableId,
+      DestinationCidrBlock: "0.0.0.0/0",
+      GatewayId: igw.InternetGatewayId,
+    },
+    { DependsOn: [igwAttachment] },
+  );
+
+  const publicRta1 = new SubnetRouteTableAssociation({
+    SubnetId: publicSubnet1.SubnetId,
+    RouteTableId: publicRouteTable.RouteTableId,
+  });
+
+  const publicRta2 = new SubnetRouteTableAssociation({
+    SubnetId: publicSubnet2.SubnetId,
+    RouteTableId: publicRouteTable.RouteTableId,
+  });
+
+  // NAT gateway
+  const natEip = new EIP({
+    Domain: "vpc",
+  });
+
+  const natGateway = new NatGateway({
+    AllocationId: natEip.AllocationId,
+    SubnetId: publicSubnet1.SubnetId,
+  });
+
+  // Private route table
+  const privateRouteTable = new RouteTable({
+    VpcId: vpc.VpcId,
+  });
+
+  const privateRoute = new EC2Route({
+    RouteTableId: privateRouteTable.RouteTableId,
+    DestinationCidrBlock: "0.0.0.0/0",
+    NatGatewayId: natGateway.NatGatewayId,
+  });
+
+  const privateRta1 = new SubnetRouteTableAssociation({
+    SubnetId: privateSubnet1.SubnetId,
+    RouteTableId: privateRouteTable.RouteTableId,
+  });
+
+  const privateRta2 = new SubnetRouteTableAssociation({
+    SubnetId: privateSubnet2.SubnetId,
+    RouteTableId: privateRouteTable.RouteTableId,
+  });
+
+  return {
+    vpc,
+    igw,
+    igwAttachment,
+    publicSubnet1,
+    publicSubnet2,
+    privateSubnet1,
+    privateSubnet2,
+    publicRouteTable,
+    publicRoute,
+    publicRta1,
+    publicRta2,
+    privateRouteTable,
+    privateRta1,
+    privateRta2,
+    natEip,
+    natGateway,
+    privateRoute,
+  };
+}, "VpcDefault");

package/src/default-tags.test.ts

@@ -0,0 +1,38 @@
+import { describe, test, expect } from "bun:test";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import { defaultTags, isDefaultTags, DEFAULT_TAGS_MARKER } from "./default-tags";
+
+describe("defaultTags", () => {
+  test("factory returns correct markers and tags", () => {
+    const tags = defaultTags([
+      { Key: "Env", Value: "prod" },
+      { Key: "Team", Value: "platform" },
+    ]);
+
+    expect(tags[DEFAULT_TAGS_MARKER]).toBe(true);
+    expect(tags[DECLARABLE_MARKER]).toBe(true);
+    expect(tags.lexicon).toBe("aws");
+    expect(tags.entityType).toBe("chant:aws:defaultTags");
+    expect(tags.tags).toHaveLength(2);
+    expect(tags.tags[0]).toEqual({ Key: "Env", Value: "prod" });
+    expect(tags.tags[1]).toEqual({ Key: "Team", Value: "platform" });
+  });
+
+  test("factory accepts empty tags array", () => {
+    const tags = defaultTags([]);
+    expect(tags.tags).toHaveLength(0);
+  });
+
+  test("isDefaultTags returns true for DefaultTags", () => {
+    const tags = defaultTags([{ Key: "k", Value: "v" }]);
+    expect(isDefaultTags(tags)).toBe(true);
+  });
+
+  test("isDefaultTags returns false for non-DefaultTags", () => {
+    expect(isDefaultTags(null)).toBe(false);
+    expect(isDefaultTags(undefined)).toBe(false);
+    expect(isDefaultTags({})).toBe(false);
+    expect(isDefaultTags("string")).toBe(false);
+    expect(isDefaultTags({ lexicon: "aws" })).toBe(false);
+  });
+});

package/src/default-tags.ts

@@ -0,0 +1,77 @@
+/**
+ * Default Tags — declares project-wide tags for all taggable resources.
+ *
+ * When a project exports a `defaultTags(...)` declaration, the serializer
+ * automatically injects those tags into every taggable resource at synthesis
+ * time. Explicit tags on individual resources take precedence.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+
+/**
+ * Marker symbol for default tags identification.
+ */
+export const DEFAULT_TAGS_MARKER = Symbol.for("chant.aws.defaultTags");
+
+/**
+ * A single tag entry — Key is always a string, Value supports strings,
+ * Parameters, intrinsics, or any value the serializer can resolve.
+ */
+export interface TagEntry {
+  readonly Key: string;
+  readonly Value: unknown;
+}
+
+/**
+ * A default tags declaration — wraps a tag array into a Declarable
+ * that the serializer uses to inject tags into all taggable resources.
+ */
+export interface DefaultTags extends Declarable {
+  readonly [DEFAULT_TAGS_MARKER]: true;
+  readonly [DECLARABLE_MARKER]: true;
+  readonly lexicon: "aws";
+  readonly entityType: "chant:aws:defaultTags";
+  readonly tags: readonly TagEntry[];
+}
+
+/**
+ * Type guard for DefaultTags.
+ */
+export function isDefaultTags(value: unknown): value is DefaultTags {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    DEFAULT_TAGS_MARKER in value &&
+    (value as Record<symbol, unknown>)[DEFAULT_TAGS_MARKER] === true
+  );
+}
+
+/**
+ * Declare project-wide default tags for all taggable resources.
+ *
+ * Tags are injected at synthesis time into every resource that supports
+ * tagging (per the CloudFormation Registry metadata). If a resource has
+ * an explicit Tag with the same Key, the explicit value wins.
+ *
+ * @param tags - Array of { Key, Value } tag entries
+ * @returns A DefaultTags Declarable
+ *
+ * @example
+ * ```ts
+ * import { defaultTags, Sub, AWS } from "@intentius/chant-lexicon-aws";
+ *
+ * export const tags = defaultTags([
+ *   { Key: "Project", Value: "my-app" },
+ *   { Key: "Environment", Value: Sub`${AWS.StackName}` },
+ * ]);
+ * ```
+ */
+export function defaultTags(tags: TagEntry[]): DefaultTags {
+  return {
+    [DEFAULT_TAGS_MARKER]: true,
+    [DECLARABLE_MARKER]: true,
+    lexicon: "aws",
+    entityType: "chant:aws:defaultTags",
+    tags,
+  };
+}