Nihilist Postmodern Mistake
    Have ideas to improve npm?Join in the discussion! »

    bigband
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.182 • Public • Published

    Bigband

    Build production grade serveless systems.

    Why Bigband?

    • Super-fast deployments.
    • Proven - came out of testim.io where it is used to drive two business-critical large-scale projects.
    • Reusability - say goodbye to copy-pasting huge YAML snippets.
    • IAM permissions are automatically managed for you - say goodebye to getting an ___ is not authorized to perform: ___ on resource ___ error at runtime.
    • Dependencies are injected into your code wrapped by high-level APIs - say goodebye to getting a runtime errors due to a mis-constructed an ARN.
    • Secure - Bigband does its best to protect you from potentially costly mistakes. For instance, it will guard against cycles of lambda functions.

    What is Bigband?

    The Bigband system has three main parts:

    • A command line tool
    • A Typescript API for configuring the architecture of your system
    • A Typescript API to be used at runtime by Lambda functions

    Three core concepts

    • Instrument: the basic building-block, usually corresponds to an AWS resources such as: a Lambda function, a DynamoDB table, a Kinesis stream, etc.
    • Section: A set of instruments. This is the unit of deployment: depending on your exact needs you can define, for instance, a prod section and a staging section, or you can define a storage section and a business-logic section.
    • Bigband: a set of sections. This is the unit of isolation: instruments within the same bigband can be wired together to create a cohesive application/service-mesh.

    Quick start

    Prerequisites

    • Have an AWS profile setup on your local machine (instructions)
    • Optional: have npx installed. If you do not want to use npx you can run bigband directly via node_modules/.bin/bigband.

    Create a folder and Install

    mkdir hello-bigband
    cd hello-bigband
    npm init -y
    npm install --save-dev bigband
    mkdir src
    

    Define your bigband

    Create a bigband.config.ts file, as shown below. Place it at the same directory as your package.json file. Do not forget to replace the placeholder values (<YOUR-AWS-PROFILE-NAME>, <A-GUID>) with your own values.

    • Your AWS profile names are defined in ~/.aws/credentials (Linux & Mac) or %USERPROFILE%\.aws\credentials (Windows).
    • You can a GUID value from (say) here
    import { Bigband, LambdaInstrument, Section } from 'bigband-core';
     
    const bigband = new Bigband({
            name: 'hello-bigband',
            profileName: '<YOUR-AWS-PROFILE-NAME>',
            s3BucketGuid: '<A-GUID>'
        });
     
    const prod = new Section('eu-west-2', 'prod');
     
    const greeter = new LambdaInstrument('myapp', 'greeter', 'src/greeter', {
        Description: "plain old greeter",
        MemorySize: 256,
        Timeout: 15   
    });
     
     
    export function run() {
        return {
            bigband,
            sections: [
                {
                    section: prod,
                    instruments: [greeter],
                    wiring: []
                }
            ]
        }
    }

    Implement a greeter

    Add an src/greeter.ts file, as follows:

    import { AbstractController } from 'bigband-lambda';
     
    interface GreeterRequest {
        firstName?: string
        lastName?: string
    }
     
    interface GreeterResponse {
        greeting: string
    }
     
    class GreeterController extends AbstractController<GreeterRequest, GreeterResponse> {
        executeScheduledEvent(): void {}
        
        async executeInputEvent(event: GreeterRequest): Promise<GreeterResponse> {
            return {
                greeting: `The name is ${event.lastName}${event.firstName} ${event.lastName}`
            }
        }
    }
     
    export const controller = new GreeterController()

    This lambda function expects to receive an input with two string fields lastName, firstName. It generates an output which is an object with a single field, greeting.

    Time to ship

    We deploy via Bigband's ship command. This will setup everything in the AWS cloud as needed.

    npx bigband ship eu-west-2/prod

    First-time deployments usually take on the order of 60-90s to complete (as all necessary AWS resources need to be created via cloudformation). Subsequent deployments should be much faster thanks to bigband's fast-shipping (further details).

    Here is a full transcript of the ship command:

    $ npx bigband ship eu-west-2/prod
    Shipping section "prod" to eu-west-2
    Compiling myapp-greeter
    Compiling bigband-system-teleport
    Non-teleporting deployment (0.541MB) of bigband-system-teleport
    Non-teleporting deployment (0.002MB) of myapp-greeter
    Creating change set
    .
    ..
    Enacting Change set
    .
    ..
    ...
    Stack status: CREATE_COMPLETE
    Section "prod" shipped in 75.5s
    

    Let's greet

    Use Bigband's exec command to send a payload of your choice to the greeter lambda instrument.

    npx bigband exec eu-west-2/prod/myapp/greeter --input '{"firstName": "James", "lastName": "Bond"}'

    You should see an output such as this:

    $ npx bigband exec eu-west-2/prod/myapp/greeter --input '{"firstName": "James", "lastName": "Bond"}'
    {
      "StatusCode": 200,
      "LogResult": [
        "START RequestId: 3c2d1393-9348-4630-8c64-19d7c761a6db Version: $LATEST",
        "END RequestId: 3c2d1393-9348-4630-8c64-19d7c761a6db",
        "REPORT RequestId: 3c2d1393-9348-4630-8c64-19d7c761a6db\tDuration: 2.50 ms\tBilled Duration: 100 ms \tMemory Size: 1024 MB\tMax Memory Used: 57 MB\t",
        ""
      ],
      "ExecutedVersion": "$LATEST",
      "Payload": {
        "greeting": "The name is Bond, James Bond"
      }
    }
    

    Congratulations!

    Your first bigband is up-and-playing.

    Install

    npm i bigband

    DownloadsWeekly Downloads

    1

    Version

    0.1.182

    License

    MIT

    Unpacked Size

    1.44 MB

    Total Files

    81

    Last publish

    Collaborators

    • avatar