stackbridge v1.2.0

stackbridge

Just another infrastructure abstraction layer.

Stackbridge allows you to define your AWS resources once. Use the same resource objects you create to deploy and interact with using via the SDK.

Installing

npm install stackbridge

Supported resources

• SNS Topics
• Lambda Functions
• S3 Buckets

Examples

Creating a StackBridge Instance

A stackbridge instance contains the AWS Environment specific parameters required to deploy and interact with resources.

const stack: StackBridge = new StackBrdige({
    account: "123456789",
    region: "us-east-1",
    environment: "staging"
});

Creating an S3 Bucket

const bucket: Bucket = stack.Bucket("my-unique-bucket-name");

Putting object to bucket

bucket.putObject(
    "/key/path", 
    JSON.stringify({"object_content", "foobar"})
    );

Getting object from bucket

const object = bucket.getObject("/key/path")

Creating an SNS Topic

interface CoolPayload {
    event: string
}
const topic = stack.SNS<CoolPayload>("topic-name1");

Publishing a topic

topic.publish({
    "event" : "foobar"
});

Creating a simple NodeJS Lambda

const lambda: Lambda = stack.Lambda.pathLambda(
    'my_lambda', 
    'test/lambdas/path-lambda.ts', 
    'handler')

Event Based Lambdas

You can create event based lambdas that have built in functionality to handle the specific event or payload they are expected to recieve.

SNS Lambda

To create an SNS lambda, create a new class that extends SNSLambda and define you handler function. The payload interface that is expected to be recieved should match the one defined in the SNS Topic object that the lambda will be subscribed to.

export class CoolSNSLambda extends SNSLambda<CoolPayload> {

    public async handler (
        event: SNSEvent): Promise<any> {
        const campaign: CoolPayload = this.getPayload(event)
        return campaign
    }
};

this.getPayload will return a serialized payload from the standard string format that is received in the SNS Event. If you require more complex serialization you can provide a serializer function to your class:

export class CoolSNSLambda extends SNSLambda<CoolPayload> {

    protected serializer = (stringPayload: string): CoolPayload => {
        const json = JSON.parse(stringPayload)
        json.message = json.message === 'bar' ? json.message : 'foobar'
        return json
    }

    public async handler (
        event: SNSEvent): Promise<any> {
        const campaign: CoolPayload = this.getPayload(event)
        return campaign
    }
};

Then create your lambda:

import { CoolSNSLambda } from .
const lambda: Lambda = stack.Lambda.snsLambda('my_cool_lambda', CoolSNSLambda)

Subscribing a Topic to a Lambda Functions

topic.addLambdaSubscription(lambda);

Allow Lambda to Read & Write a bucket

lambda.canReadBuckets([bucket]);
lambda.canWriteBuckets([bucket]);

Grant Lambda AWS Managed Policy

lambda.addAwsManagedPolicy("AmazonS3ReadOnlyAccess");

Deploying

Simply create any ts file in your project that defines or imports any stack resources created through your app.

Import your StackBridge instance and define all deployable resources and export the deploy function.

src/sbstack.ts

# import resources and StackBridge instance
import { deploy } from "stackbridge";

stack.deployableResources(
    {
        buckets: [bucket],
        topics: [topic],
        lambdas: [lambda]
    }
);

export default deploy(stack);

On your first deploy you may need to run cdk bootstrap

cdk bootstrap aws://ACCOUNT-NUMBER/REGION-1

To create a differential

npx stackbridge diff ./src/sbstack.ts (or your export location)

To synthesize a template

npx stackbridge synth ./src/sbstack.ts

To deploy the stack

npx stackbridge deploy ./src/sbstack.ts

Running the environment locally

You can run your stack locally using localstack. It requires docker to be running on your system. If you want to run locally you must define your StackBridge instance as follows:

const stack: StackBridge = new StackBrdige({
    account: "000000000000",
    region: "us-east-1",
});

Install Localstack and cdklocal

pip install localstack
npm install -g aws-cdk-local aws-cdk

Start Localstack

SERVICES=lambda,sns,s3 localstack start

Boostrap your local environment

cdklocal bootstrap aws://000000000000/us-east-1

Deploy your stack locally

cdklocal deploy --app "npx ts-node src/sbstack.ts"