@tradle/serverless-offline

    3.16.2 • Public • Published

    Serverless Offline Plugin

    serverless npm version Build Status PRs Welcome

    Announcement

    Dear users and contributors,

    Thank you for all your support. In the upcomming days my availability on this project should decline. This is why I'm looking for maintainers: anyone that pushed a successful PR and is willing to manage the upcomming ones is welcome to apply. To do so just comment on this issue.

    Thanks you for your attention. :)

    〰️〰️〰️

    This Serverless plugin emulates AWS λ and API Gateway on your local machine to speed up your development cycles. To do so, it starts an HTTP server that handles the request's lifecycle like APIG does and invokes your handlers.

    Features:

    • Nodejs λ only.
    • Velocity templates support.
    • Lazy loading of your files with require cache invalidation: no need for a reloading tool like Nodemon.
    • And more: integrations, authorizers, proxies, timeouts, responseParameters, HTTPS, Babel runtime, CORS, etc...

    This plugin is updated by its users, I just do maintenance and ensure that PRs are relevant to the community. In other words, if you find a bug or want a new feature, please help us by becoming one of the contributors ✌️ ! See the contributing section.

    Documentation

    Installation

    For Serverless v1 only. See this branch for 0.5.x versions.

    First, add Serverless Offline to your project:

    npm install serverless-offline --save-dev

    Then inside your project's serverless.yml file add following entry to the plugins section: serverless-offline. If there is no plugin section you will need to add it to the file.

    It should look something like this:

    plugins:
      - serverless-offline

    You can check wether you have successfully installed the plugin by running the serverless command line:

    serverless

    the console should display Offline as one of the plugins now available in your Serverless project.

    Usage and command line options

    In your project root run:

    serverless offline start or sls offline start.

    to list all the options for the plugin run:

    sls offline --help

    All CLI options are optional:

    --prefix                -p  Adds a prefix to every path, to send your requests to http://localhost:3000/[prefix]/[your_path] instead. E.g. -p dev
    --location              -l  The root location of the handlers' files. Defaults to the current directory
    --host                  -o  Host name to listen on. Default: localhost
    --port                  -P  Port to listen on. Default: 3000
    --stage                 -s  The stage used to populate your templates. Default: the first stage found in your project.
    --region                -r  The region used to populate your templates. Default: the first region for the first stage found.
    --noTimeout             -t  Disables the timeout feature.
    --noEnvironment             Turns off loading of your environment variables from serverless.yml. Allows the usage of tools such as PM2 or docker-compose.
    --resourceRoutes            Turns on loading of your HTTP proxy settings from serverless.yml.
    --dontPrintOutput           Turns off logging of your lambda outputs in the terminal.
    --httpsProtocol         -H  To enable HTTPS, specify directory (relative to your cwd, typically your project dir) for both cert.pem and key.pem files.
    --skipCacheInvalidation -c  Tells the plugin to skip require cache invalidation. A script reloading tool like Nodemon might then be needed.
    --corsAllowOrigin           Used as default Access-Control-Allow-Origin header value for responses. Delimit multiple values with commas. Default: '*'
    --corsAllowHeaders          Used as default Access-Control-Allow-Headers header value for responses. Delimit multiple values with commas. Default: 'accept,content-type,x-api-key'
    --corsDisallowCredentials   When provided, the default Access-Control-Allow-Credentials header value will be passed as 'false'. Default: true
    --exec "<script>"           When provided, a shell script is executed when the server starts up, and the server will shut domn after handling this command.
    --noAuth                    Turns off all authorizers
    

    Any of the CLI options can be added to your serverless.yml. For example:

    custom:
      serverless-offline:
        httpsProtocol: "dev-certs"
        port: 4000
    

    Options passed on the command line override YAML options.

    By default you can send your requests to http://localhost:3000/. Please note that:

    • You'll need to restart the plugin if you modify your serverless.yml or any of the default velocity template files.
    • The event object passed to your λs has one extra key: { isOffline: true }. Also, process.env.IS_OFFLINE is true.
    • When no Content-Type header is set on a request, API Gateway defaults to application/json, and so does the plugin. But if you send an application/x-www-form-urlencoded or a multipart/form-data body with an application/json (or no) Content-Type, API Gateway won't parse your data (you'll get the ugly raw as input), whereas the plugin will answer 400 (malformed JSON). Please consider explicitly setting your requests' Content-Type and using separate templates.

    Usage with Babel

    You can use Offline with Serverless-runtime-babel. To do so you need to install (at least) the es2015 preset in your project folder (npm i babel-preset-es2015 --save-dev).

    ~ Or ~

    Your λ handlers can be required with babel-register. To do so, in your serverless.yml file, set options to be passed to babel-register like this:

    custom:
      serverless-offline:
        babelOptions:
          presets: ["es2015", "stage-2"]

    Here is the full list of babel-register options

    Token Authorizers

    As defined in the Serverless Documentation you can use API Keys as a simple authentication method.

    Serverless-offline will emulate the behaviour of APIG and create a random token that's printed on the screen. With this token you can access your private methods adding x-api-key: generatedToken to your request header. All api keys will share the same token. To specify a custom token use the --apiKey cli option.

    Custom authorizers

    Only custom authorizers are supported. Custom authorizers are executed before a Lambda function is executed and return an Error or a Policy document.

    The Custom authorizer is passed an event object as below:

    {
      "type": "TOKEN",
      "authorizationToken": "<Incoming bearer token>",
      "methodArn": "arn:aws:execute-api:<Region id>:<Account id>:<API id>/<Stage>/<Method>/<Resource path>"
    }

    The methodArn does not include the Account id or API id.

    The plugin only supports retrieving Tokens from headers. You can configure the header as below:

    "authorizer": {
      "type": "TOKEN",
      "identitySource": "method.request.header.Authorization", // or method.request.header.SomeOtherHeader
      "authorizerResultTtlInSeconds": "0"
    }

    AWS API Gateway Features

    Velocity Templates

    Serverless doc ~ AWS doc

    You can supply response and request templates for each function. This is optional. To do so you will have to place function specific template files in the same directory as your function file and add the .req.vm extension to the template filename. For example, if your function is in code-file: helloworld.js, your response template should be in file: helloworld.res.vm and your request template in file helloworld.req.vm.

    CORS

    Serverless doc

    If the endpoint config has CORS set to true, the plugin will use the CLI CORS options for the associated route. Otherwise, no CORS headers will be added.

    Catch-all Path Variables

    AWS doc

    Set greedy paths like /store/{proxy+} that will intercept requests made to /store/list-products, /store/add-product, etc...

    ANY method

    AWS doc

    Works out of the box.

    Lambda and Lambda Proxy Integrations

    Serverless doc ~ AWS doc

    Works out of the box. See examples in the manual_test directory.

    HTTP Proxy

    Serverless doc ~ AWS doc - AWS::ApiGateway::Method ~ AWS doc - AWS::ApiGateway::Resource

    Example of enabling proxy:

    custom:
      serverless-offline:
        resourceRoutes: true
    

    or

        YourCloudFormationMethodId:
          Type: AWS::ApiGateway::Method
          Properties:
            ......
            Integration:
              Type: HTTP_PROXY
              Uri: 'https://s3-${self:custom.region}.amazonaws.com/${self:custom.yourBucketName}/{proxy}'
              ......
    
    custom:
      serverless-offline:
        resourceRoutes:
          YourCloudFormationMethodId:
            Uri: 'http://localhost:3001/assets/{proxy}'
    

    Response parameters

    AWS doc

    You can set your response's headers using ResponseParameters.

    May not work properly. Please PR. (Difficulty: hard?)

    Example response velocity template:

    "responseParameters": {
      "method.response.header.X-Powered-By": "Serverless", // a string
      "method.response.header.Warning": "integration.response.body", // the whole response
      "method.response.header.Location": "integration.response.body.some.key" // a pseudo JSON-path
    },

    Velocity nuances

    Consider this requestTemplate for a POST endpoint:

    "application/json": {
      "payload": "$input.json('$')",
      "id_json": "$input.json('$.id')",
      "id_path": "$input.path('$').id"
    }

    Now let's make a request with this body: { "id": 1 }

    AWS parses the event as such:

    {
      "payload": {
        "id": 1
      },
      "id_json": 1,
      "id_path": "1" // Notice the string
    }

    Whereas Offline parses:

    {
      "payload": {
        "id": 1
      },
      "id_json": 1,
      "id_path": 1, // Notice the number
      "isOffline": true
    }

    Accessing an attribute after using $input.path will return a string on AWS (expect strings like "1" or "true") but not with Offline (1 or true). You may find other differences.

    Debug process

    Serverless offline plugin will respond to the overall framework settings and output additional information to the console in debug mode. In order to do this you will have to set the SLS_DEBUG environmental variable. You can run the following in the command line to switch to debug mode execution.

    Unix: export SLS_DEBUG=*

    Windows: SET SLS_DEBUG=*

    Interactive debugging is also possible for your project if you have installed the node-inspector module and chrome browser. You can then run the following command line inside your project's root.

    Initial installation: npm install -g node-inspector

    For each debug run: node-debug sls offline

    The system will start in wait status. This will also automatically start the chrome browser and wait for you to set breakpoints for inspection. Set the breakpoints as needed and, then, click the play button for the debugging to continue.

    Depending on the breakpoint, you may need to call the URL path for your function in seperate browser window for your serverless function to be run and made available for debugging.

    Scoped execution

    Serverless offline plugin can invoke shell scripts when a simulated server has been started up for the purposes of integration testing. Downstream plugins may tie into the "before:offline:start:end" hook to release resources when the server is shutting down.

    > sls offline start --exec "./startIntegrationTests.sh"

    Simulation quality

    This plugin simulates API Gateway for many practical purposes, good enough for development - but is not a perfect simulator. Specifically, Lambda currently runs on Node v4.3.2 and v6.10.0, whereas Offline runs on your own runtime where no memory limits are enforced.

    Usage with serverless-offline and serverless-webpack plugin

    Run serverless offline start. In comparison with serverless offline, the start command will fire an init and a end lifecycle hook which is needed for serverless-offline and serverless-dynamodb-local to switch off ressources.

    Add plugins to your serverless.yml file:

    plugins:
      - serverless-webpack
      - serverless-dynamodb-local
      - serverless-offline #serverless-offline needs to be last in the list

    Credits and inspiration

    This plugin was initially a fork of Nopik's Serverless-serve.

    Contributing

    Yes, thank you! This plugin is community-driven, most of its features are from different authors. Please update the docs and tests and add your name to the package.json file. We try to follow Airbnb's JavaScript Style Guide.

    License

    MIT

    Install

    npm i @tradle/serverless-offline

    DownloadsWeekly Downloads

    3

    Version

    3.16.2

    License

    MIT

    Unpacked Size

    119 kB

    Total Files

    35

    Last publish

    Collaborators

    • leichtgewicht
    • genevayngrib
    • tenaciousmv
    • pgmemk