\nThis article covers how-to:<\/p>\n
- \n
- Write golang functions for AWS Lambda.<\/li>\n
- Use AWS API Gateway to return binary content.<\/li>\n
- Link together AWS Lambda & API Gateway to create a scalable HTTPS service for barcode generation.<\/li>\n<\/ul>\n
Why do we need this at PassKit?<\/b><\/p>\n
- \n
- To display a \u2018live’ pass-render with accurate barcode in our Pass Designer & Management Tools<\/a>.<\/li>\n
- To generate QR codes (at scale) for our merchants for printing their Loyalty-program enrolment links onto tent-cards, menu\u2019s, websites, Facebook pages, etc.<\/li>\n<\/ul>\n
Why Golang?<\/b><\/p>\n
- \n
- Speed<\/a>! Very fast & a perfect choice for CPU-intensive tasks.<\/li>\n
- Quick & easy to master in a very short amount of time.<\/li>\n
- Portability across platforms.<\/li>\n
- Compiled binariers: plays nice with Docker.<\/li>\n
- Excellent concurreny primitives<\/a>.<\/li>\n
- Well defined error handling patterns.<\/li>\n
- Rich standard libraries.<\/li>\n
- Standard code formatting \/ ease of maintenance.<\/li>\n<\/ul>\n
Why AWS Lambda?<\/b>
\nAWS Lambda is a cloud computing service that lets you run code without provisioning or managing servers. AWS Lambda executes your code only when needed and scales automatically. In other words, it’s efficient and easy to use at scale, and you only pay for the resources that you use.
\nWhat else could this logic be applied to?<\/b><\/p>\n- \n
- Scalable image generators \/ manipulators on AWS (although keep in mind that if you\u2019d want to use external image-libraries like Imagick or VIPS – AWS Lambda won’t be your optimal solution).<\/li>\n
- Scalable document generator (PDF, Excel files, etc) on AWS.<\/li>\n<\/ul>\n
What is needed to get started?<\/b>
\nYou will need an AWS account<\/a> with access to Lambda & API Gateway in order to build this.<\/p>\n2. Samples<\/h3>\n
By the end of this article you will be able to create barcodes in QR and PDF417 format. Have a look at below samples:
\nA QR code of 200px by 200px, with the content ‘testing’.
\nURL: https:\/\/utils.passkit.net\/barcode?m=testing&f=qrcode&h=200&w=200<\/a>
\n
\nA PDF417 code of 200px by 50px, with the content ‘testing’.
\nURL: https:\/\/utils.passkit.net\/barcode?m=testing&f=pdf417&h=100&w=300<\/a>
\n<\/p>\n
3. Let\u2019s get started – Tech Specification<\/h3>\n
Note: The article assumes that you have basic knowledge of AWS Lambda, API Gateway & Golang. If you are new to all 3, then I’d recommend you first read the following resources:<\/p>\n
- \n
- What is AWS Lambda?<\/li>\n
- What is Amazon API Gateway?<\/li>\n
- Go Programming For Beginners<\/a><\/li>\n<\/ul>\n
<\/em>
\nSystem Flow<\/b>
\nThe image below outlines the system & data flow on what will be built over the course of this article. The final objective is to be able to use this barcode web-service by simply including its URL in an HTML image tag:
\n![\"Barcode](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/13131526\/barcode_lambda.png\" "\\"\\"")
\nThe API endpoint will be built according to the following specification:
\nSample URL: \/barcode?width=200&height=200&type=qr&message=testing<\/b>
\nEndpoint: \/barcode<\/b>
\nMethod: GET<\/b>
\nRequest Parameters:<\/p>\n- \n
- width<\/b>: barcode width (int).<\/li>\n
- height<\/b>: barcode height (int).<\/li>\n
- message<\/b>: barcode contents, UTF8 support (string).<\/li>\n
- type<\/b>: barcode type, ‘qr’ or ‘pdf417’ (string).<\/li>\n<\/ul>\n
For the purpose of this web-service, there are the following limitations:<\/p>\n
- \n
- Minimum barcode with & height: 150px.<\/li>\n
- Maximum barcode width & height of: 3000px.<\/li>\n
- Maximum length of barcode contents: 600 bytes.<\/li>\n
- Barcode types that are supported: QR, PDF417.<\/li>\n<\/ul>\n
4. The Lambda Function in Go<\/h3>\n
Code Repository<\/b>
\nThe code repository with the sample code can be downloaded from Github:
\nhttps:\/\/github.com\/pkosterman\/aws-lambda-barcode-generator<\/a>
\nCode Structure<\/b>
\nEssentially, the lambda consists of a simple Node.js function that spawns off a child process which executes a compiled Go binary. The Node.js function ensures it passes the Stdin & Stdout to the Go binary, so that the function receives the Lambda Context & Event JSON, and when it’s finished, it can write the output back to Stdout for the Lambda to pass back to the invoker:
\n![\"node_js_go_wrapper_flow\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15044440\/node_js_go_wrapper_flow.png\" "\\"\\"")
<\/a>
\nThere are 3 important parts in the code repo:<\/p>\n- \n
- main.go<\/b>: this contains the actual barcode generation (wrapped in our Node.Js wrapper).<\/li>\n
- lib\/nodewrapper\/nodewrapper.go<\/b>: this library marshalls input from\/to the stdin & stdout between our Go function and the Node.Js Lambda function.\n
- index.js<\/b> & build.sh<\/b> – the build script needs to be executed in order to compile our zipped Lambda Node.Js bundle<\/li>\n<\/ol>\n
For this article, we will mainly focus on item 1 – the main.go program. If you want to re-use the nodewrapper for another project, you can simply do so by changing the contents of the Handler function, and, renaming the executable file in index.js to the name of your compiled binary.
\nBarcode Generation<\/b>
\nLet’s have a look at main.go. At the top it lists the libraries that the function uses. Quite basic:
\n[js]
\nimport (
\n\t"bytes"
\n\t"encoding\/base64"
\n\t"encoding\/json"
\n\t"fmt"
\n\t"image\/png"
\n\t"os"
\n\t"aws-lambda-barcode-generator\/config"
\n\t"aws-lambda-barcode-generator\/lib\/nodewrapper"
\n\t"github.com\/boombuler\/barcode"
\n\t"github.com\/boombuler\/barcode\/pdf417"
\n\t"github.com\/boombuler\/barcode\/qr"
\n)
\n[\/js]
\nThe function uses an existing barcode library<\/a> for Go, since it’s well maintained, reasonably fast, and works like a charm! For the rest it uses standard Go libraries.
\nAfter the import statement, there is the LambdaInput struct – this is the struct that will be used to Marshall the Lambda eventJSON into. This struct conforms to our API endpoint specification, since this is all the data that is required to generate a barcode:
\n[js]
\ntype LambdaInput struct {
\n\tWidth *int `json:"width,omitempty"`
\n\tHeight *int `json:"height,omitempty"`
\n\tMessage *string `json:"message,omitempty"`
\n\tType *string `json:"type,omitempty"`
\n}
\n[\/js]
\nAll of the fields in the struct are pointers so that the function can return helpful error messages in case if one of them isn’t present (i.e. nil<\/em>).
\nIf you were to use this code to perform some different action with a Lambda (let’s say send an SMS message), then this is where you would specify the fields that you expect in your Lambda eventJSON.
\nNext, lets have a look at the main() function:
\n[js]
\nfunc main() {
\n\tnodewrapper.Run(func(context *nodewrapper.Context, eventJSON json.RawMessage) (interface{}, error) {
\n\t\t\/\/ declare this functions variables
\n\t\tvar input LambdaInput
\n\t\tvar c barcode.Barcode
\n\t\tvar err error
\n\t\tif err = json.Unmarshal(eventJSON, &input); err != nil {
\n\t\t\t\/\/ Add error prefixes to all final error strings to allow for AWS API Gateway regex
\n\t\t\treturn nil, fmt.Errorf("400 Bad Request: Invalid Request – cannot marshal JSON input. Object received: %s", string(eventJSON))
\n\t\t}
\n\t\t\/\/ ensure our input is valid and contains all the data we need
\n\t\terr = checkValidRequest(input)
\n\t\tif err != nil {
\n\t\t\treturn nil, err
\n\t\t}
\n\t\t\/\/ based on the barcode type – generate the barcode
\n\t\tswitch barcodeType := *input.Type; barcodeType {
\n\t\tcase "qr":
\n\t\t\tc, err = qr.Encode(*input.Message, qr.M, qr.Unicode)
\n\t\tcase "pdf417":
\n\t\t\tc, err = pdf417.Encode(*input.Message, 3)
\n\t\t}
\n\t\tif err != nil {
\n\t\t\treturn nil, fmt.Errorf("500 Server Error: Could not generate barcode. Details: %s", err)
\n\t\t}
\n\t\t\/\/ Scale the barcode to the provided width & height
\n\t\tc, err = barcode.Scale(c, *input.Width, *input.Height)
\n\t\tif err != nil {
\n\t\t\treturn nil, fmt.Errorf("500 Server Error: Could not scale the barcode to input width and height. Details: %s", err)
\n\t\t}
\n\t\t\/\/ if we have develop set to true, then also export as PNG (so its easy to view the barcode output on local machine)
\n\t\tif config.DEVELOP {
\n\t\t\t\/\/ create the output file
\n\t\t\tfile, _ := os.Create("code.png")
\n\t\t\tdefer file.Close()
\n\t\t\t\/\/ encode the barcode as png
\n\t\t\tpng.Encode(file, c)
\n\t\t}
\n\t\t\/\/ write image to buffer
\n\t\tbuf := new(bytes.Buffer)
\n\t\terr = png.Encode(buf, c)
\n\t\tif err != nil {
\n\t\t\treturn nil, fmt.Errorf("500 Server Error: Could not write image to buffer. Details: %s", err)
\n\t\t}
\n\t\t\/\/ return the image as a base64 encoded string
\n\t\treturn base64.StdEncoding.EncodeToString(buf.Bytes()), err
\n\t\t\/\/ append true here, so the nodewrapper returns our data without trying to marshall it into any response object
\n\t}, true)
\n}
\n[\/js]
\nThe function validates the input struct, and then uses the struct to generate a barcode according to the API specification. It then returns the barcode as a base64 encoded string, which the Lambda will pass onto API Gateway.
\nYou can see from the code that all errors are prefixed with their HTTP status code. This will later-on make it easy for API Gateway to do the proper HTTP header mapping.
\nOne important point to note. If you want to re-use this code for some other Lambda logic, all your code should go into the Nodewrapper.Run handler function:
\n[js]
\nfunc main() {
\n\tnodewrapper.Run(func(context *nodewrapper.Context, eventJSON json.RawMessage) (interface{}, error) {
\n \/\/ CODE GOES HERE
\n\t}, true)
\n}
\n[\/js]
\nBased on the required output (JSON, or raw), the rawOutput<\/em> boolean can be either true or false.
\nBuilding the Lambda deployment package<\/b>
\nAll that is required, is to open the terminal, and cd into the root directory of the repo, then type:
\n[js]
\n.\/build.sh
\n[\/js]
\nThis will create a build folder with in there the lambda.zip<\/em> file. This zip file contains the compiled Go binary, and the index.js code that executes this binary.
\nIf the build succeeded, then the result is something like this:
\n[js]
\nCleaning build folder
\nSetting Production Mode
\nCompiling for Linux
\nPreparing Lambda bundle
\n adding: main (deflated 65%)
\n adding: index.js (deflated 61%)
\nCleaning up
\nDone!
\n[\/js]
\nNext, we need to upload the zipped deployment package to AWS.
\nUpload the Lambda<\/b>
\nLogin to your AWS account, and navigate to Lambda.
\n1. Create a new function:<\/em>
\n![\"lambda-flow.001\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115808\/lambda-flow.001.jpeg\" "\\"\\"")
<\/a>
\n2. Click ‘Author from scratch’:<\/em>
\n![\"lambda-flow.002\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115857\/lambda-flow.002.jpeg\" "\\"\\"")
<\/a>
\n3. Click next on the ‘Triggers’ page. We will setup API Gateway later:<\/em>
\n![\"lambda-flow.003\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115910\/lambda-flow.003.jpeg\" "\\"\\"")
<\/a>
\n4. Fill out the function details:<\/em>
\nFor the runtime version, we will pick the latest Node.Js version that Lambda supports (which at the time of writing is 6.10).
\n![\"lambda-flow.004\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115935\/lambda-flow.004.jpeg\" "\\"\\"")
<\/a>
\n5. Upload the lambda.zip that we built in the previous step:<\/em>
\n![\"lambda-flow.005\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15120018\/lambda-flow.005.jpeg\" "\\"\\"")
<\/a>
\n![\"lambda-flow.006\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15120055\/lambda-flow.006.jpeg\" "\\"\\"")
<\/a>
\n6. Set the role permissions:<\/em>
\nAll that is needed for this particular lambda to run is the lambda_basic_execution<\/b> role.
\nNote: If you plan to write a Lambda that will be accessing other AWS services, then this will not be sufficient enough. In that case you’d have to create a new custom role and add additional permissions for the AWS services that your Lambda will consume. <\/em>
\n![\"lambda-flow.007\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15120211\/lambda-flow.007.jpeg\" "\\"\\"")
<\/a>
\n![\"lambda-flow.008\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115451\/lambda-flow.008.jpeg\" "\\"\\"")
<\/a>
\n![\"lambda-flow.009\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115500\/lambda-flow.009.jpeg\" "\\"\\"")
<\/a>
\n7. Increase the timeout:<\/em>
\nBy default an AWS Lambda function times out after 3 seconds. For this particular Lambda we don’t need to increase the timeout, since the Go barcode generation is reasonably fast (~10-20ms). But in case you are writing a more complex Lambda, then you might want to change these settings.
\n![\"lambda-flow.010\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115507\/lambda-flow.010.jpeg\" "\\"\\"")
<\/a>
\n8. Check the method summary and create the function:<\/em>
\n![\"lambda-flow.011\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115518\/lambda-flow.011.jpeg\" "\\"\\"")
<\/a>
\n9. Configure test event and test:<\/em>
\nFor a successful barode generation, we can test with the following JSON object:
\n[js]
\n{
\n "message": "testing",
\n "width": 200,
\n "height": 200,
\n "type": "qr"
\n}
\n[\/js]
\n![\"lambda-flow.013\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115540\/lambda-flow.013.jpeg\" "\\"\\"")
<\/a>
\nTadaaaa – it works:
\n![\"lambda-flow.014\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115617\/lambda-flow.014.jpeg\" "\\"\\"")
<\/a>
\nTo test if the error handling works OK, the following JSON object can be used (remember, the function requires a minimum height of 150px for successful generation):
\n[js]
\n{
\n "message": "testing",
\n "width": 200,
\n "height": 100,
\n "type": "qr"
\n}
\n[\/js]
\nAs expected, this outputs a properly JSON formatted error (including error-code prefix for API Gateway):
\n![\"lambda-flow.015\"](\"https:\/\/dxjl3qy52c1o9.cloudfront.net\/wp-content\/uploads\/2017\/08\/15115702\/lambda-flow.015.jpeg\" "\\"\\"")
<\/a>
\nThe Lambda function is setup correctly!
\nNext, Part 2<\/a>: learn how-to setup the API endpoint in API Gateway, so that it can call the Lambda via a GET HTTP request.<\/p>\n","protected":false},"excerpt":{"rendered":"1. Introduction This is part 1 of a 2 part series. For part 2, please click here. This article covers how-to: Write golang functions for AWS Lambda. Use AWS API Gateway to return binary content. Link together AWS Lambda & API Gateway to create a scalable HTTPS service for barcode generation. Why do we need […]<\/p>\n","protected":false},"author":5,"featured_media":13754,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[37],"tags":[],"class_list":["post-11228","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tech"],"_links":{"self":[{"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/posts\/11228","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/users\/5"}],"replies":[{"embeddable":true,"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/comments?post=11228"}],"version-history":[{"count":0,"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/posts\/11228\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/media\/13754"}],"wp:attachment":[{"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/media?parent=11228"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/categories?post=11228"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/passkit.com\/blog\/wp-json\/wp\/v2\/tags?post=11228"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
- lib\/nodewrapper\/nodewrapper.go<\/b>: this library marshalls input from\/to the stdin & stdout between our Go function and the Node.Js Lambda function.\n
- main.go<\/b>: this contains the actual barcode generation (wrapped in our Node.Js wrapper).<\/li>\n
- height<\/b>: barcode height (int).<\/li>\n
- What is Amazon API Gateway?<\/li>\n
- What is AWS Lambda?<\/li>\n
- To generate QR codes (at scale) for our merchants for printing their Loyalty-program enrolment links onto tent-cards, menu\u2019s, websites, Facebook pages, etc.<\/li>\n<\/ul>\n
- To display a \u2018live’ pass-render with accurate barcode in our Pass Designer & Management Tools<\/a>.<\/li>\n