npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

serverless-haskell

v0.12.6

Published

Deploy Haskell binaries onto AWS Lambda

Downloads

110

Readme

Serverless Haskell

Build status Hackage Stackage LTS Hackage dependencies npm

Deploying Haskell code onto AWS Lambda using Serverless.

Prerequisites

Usage

There are two ways to start, either via the stack template, or directly modifying a project. You may want to use the manual approach as the template specifies a specific stack resolver as it needs to hardcode the stack.yaml file.

In either case, you will want to have Serverless installed, eg. npm install -g serverless.

Using the stack template

  • Create a Stack package for your code:

    stack new mypackage https://raw.githubusercontent.com/seek-oss/serverless-haskell/master/serverless-haskell.hsfiles
  • Update the resolver in the stack.yaml file. This is hardcoded as the resolver number is not known at template interpolation time. You should pick either the latest resolver, or one you have used before and have thus prebuilt many of the core packages for.

  • Install the dependencies and build the project:

    cd mypackage
    npm install
    stack build
    sls invoke local -f mypackage-func

    This should invoke serverless locally and display output once everything has built.

Manually

  • Create a Stack package for your code:

    stack new mypackage

    LTS 10-17 are supported, older versions are likely to work too but untested.

  • Initialise a Serverless project inside the Stack package directory and install the serverless-haskell plugin:

    cd mypackage
    npm init -y
    npm install --save serverless [email protected]

    The version of the NPM package to install must match the version of the Haskell package.

  • Create serverless.yml with the following contents:

    service: myservice
    
    provider:
      name: aws
      runtime: haskell
    
    functions:
      myfunc:
        handler: mypackage.mypackage-exe
        # Here, mypackage is the Haskell package name and mypackage-exe is the
        # executable name as defined in the Cabal file. The handler field may be
        # prefixed with a path of the form `dir1/.../dirn`, relative to
        # `serverless.yml`, which points to the location where the Haskell
        # package `mypackage` is defined. This prefix is not needed when the
        # Stack project is defined at the same level as `serverless.yml`.
    
    plugins:
      - serverless-haskell
  • Write your main function:

    import qualified Data.Aeson as Aeson
    
    import AWSLambda
    
    main = lambdaMain handler
    
    handler :: Aeson.Value -> IO [Int]
    handler evt = do
      putStrLn "This should go to logs"
      print evt
      pure [1, 2, 3]
  • Add aeson and serverless-haskell to package.yaml:

    dependencies:
    - base >= 4.7 && < 5
    - aeson
    - serverless-haskell
  • Build and test locally using sls invoke local:

    The serverless-haskell plugin will build the package using Stack. Note that the first build can take a long time. Consider adding export SLS_DEBUG=* so you can see what is happening.

    export SLS_DEBUG=*
    sls invoke local -f myfunc
  • Use sls deploy to deploy the executable to AWS Lambda.

    The serverless-haskell plugin will build the package using Stack, then upload it to AWS together with a JavaScript wrapper to pass the input and output from/to AWS Lambda.

    export SLS_DEBUG=*
    sls deploy

    You can test the function and see the invocation results with:

    sls invoke -f myfunc`

API Gateway

This plugin supports handling API Gateway requests. Declare the HTTP events normally in serverless.yml and use AWSLambda.Events.APIGateway in the handler to process them.

Serverless Offline can be used for local testing of API Gateway requests. You must use --useDocker flag so that the native Haskell runtime works correctly.

When using Serverless Offline, make sure that the project directory is world-readable, otherwise the started Docker container will be unable to access the handlers and all invocations will return HTTP status 502.

Notes

  • Only AWS Lambda is supported at the moment. Other cloud providers would require different JavaScript wrappers to be implemented.

See AWSLambda for documentation, including additional options to control the deployment.

Development

master branch is the stable version. It is normally released to Hackage once new changes are merged via Git tags.

The package is also maintained in Stackage LTS, provided the dependencies are not blocking it.

Testing

  • Haskell code is tested with Stack: stack test.
  • TypeScript code is linted with eslint.

Integration tests

Integration test verifies that the project can build and deploy a complete function to AWS, and it runs with expected functionality.

Integration test is only automatically run up to deployment due to the need for an AWS account. To run manually:

  • Ensure you have the required dependencies:
  • Get an AWS account and add the access credentials into your shell environment.
  • Run ./integration-test/run.sh. The exit code indicates success.
  • To verify just the packaging, without deployment, run ./integration-test/run.sh --dry-run.
  • By default, the integration test is run with the LTS specified in stack.yaml. To specify a different series, use RESOLVER_SERIES=lts-9.
  • To avoid creating a temporary directory for every run, specify --no-clean-dir. This can speed up repeated test runs, but does not guarantee the same results as a clean test.

Releasing

  • Ensure you are on the master branch.
  • Ensure that all the changes are reflected in the changelog.
  • Run the integration tests.
  • Run ./bumpversion major|minor|patch. This will increment the version number, update the changelog, create and push the Git tag and the branch.
  • If you have released an LTS version, merge the version branch into master, taking care of the conflicts around version numbers and changelog, and release the latest version as well.