cyanogilvie/alpine-tcl-lambda repository overview

⁠AWS-TCL

Tcl related resources for AWS:

• Tcl modules implementing a subset of the AWS REST API (s3 for now, but includes the core API functionality for v2 and v4 request signatures).
• A base container providing a Tcl runtime for AWS Lambda.

⁠API

The API attempts to authenticate with with the AWS REST API using any contextual credentials it can find (instance roles on EC2, execution roles on Lambda, ECS / Fargate, etc) in a similar fashion to the AWS CLI. So if your code is running on the AWS platform and you want to interact with other AWS services using the IAM instance role assigned to whatever is running the code, you don't have to do anything. If your code isn't running on AWS or you need to override the default credentials, they can be supplied in the calls using the -aws_id, -aws_key and -aws_token arguments.

The core API layer supports the ratelimiting negotiation used by the AWS API, and will back off and limit the request rate if it receives "slow down" errors (and transparently re-issue the failed requests).

package require aws::s3
package require rl_json

namespace import rl_json::*

# Upload an image
s3 upload \
    -region         us-east-1 \
    -bucket         assets \
    -path           foo/bar.jpg \
    -content_type   image/jpeg \
    -data           $image_bytes \
    -acl            public-read

# List files matching a prefix on a bucket.  S3 returns a limited number of
# results per response, so to support very large results we use continuation
# tokens:

set continuation_token ""
while {[info exists continuation_token]} {
    set batch [s3 ls \
        -continuation_token   $continuation_token \
        -region               us-east-1 \
        -bucket               assets \
        -prefix               images/foo \
        -delimiter            /]
        
    set continuation_token  [json get $batch next_continuation_token]
    if {$continuation_token eq ""} {unset continuation_token}
    json foreach entry [json extract $batch results] {
        puts "matched: [json get $entry key]"
    }
}

⁠API v2

The AWS API package version 2 switches to using generated code to implement the various aws services, derived from the JSON description files that are used by botocore (and therefore the standard AWS CLI). This means that the interface presented by v2 is very similar to the AWS CLI - except that underscores are used in place of dashes, and options are preceded by a single dash rather than two. So:

aws lambda list-functions --function-version ALL

becomes:

package require aws::lambda 2
aws lambda list_functions -function_version ALL

As indicated by the version suffix, version 2 is still in alpha, and isn't complete yet (the ec2 service uses a different protocol which still needs to be implemented). It's also very likely still full of bugs from the guesses I had to make when reverse engineering the botocore JSON description.

It would be trivial to just use the AWS CLI from Tcl like so:

exec aws list-functions --function-version ALL

but including the AWS CLI increases the size of an image hugely - the official AWS CLI docker image is 300 MB, and a hacked one based on alpine linux is 150 MB, whereas the generated Tcl bindings are a little over half a MB. In situations where a small image is a requirement (such as this one), including the AWS CLI is simply not an option.

⁠AWS-Tcl-Lambda

AWS Lambda now supports using a container as the function code. This repo provides a base image that supplies a Tcl runtime that is compatible with this:

myfunc.tcl:

proc handler {event context} {
    puts [json pretty $event]
    return "hello, world"
}

Dockerfile:

FROM cyanogilvie/aws-tcl-lambda
ENV LAMBDA_TASK_ROOT=/foo
WORKDIR /foo
COPY myfunc.tcl /foo
CMD ["myfunc.handler"]

⁠Build Flags

Since Nov 2020 AVX2 support is available to Lambda functions in all regions other than China, so all the sources for this image are built with that support. If you need other hardware support, override the CFLAGS arg.

⁠Included Packages

aws 2.0a1 supports all the services of the aws cli except for ec2 currently.

For Pixel_svg_cairo to be usable it needs librsvg, which isn't added by default because it more than doubles the image size. To use it, derive a new image like so:

FROM cyanogilvie/alpine-tcl-stripped
RUN apk add --no-cache librsvg

Similarly, Pixel_imlib2 requires imlib2:

FROM cyanogilvie/alpine-tcl-stripped
RUN apk add --no-cache imlib2

⁠License

Licensed under the same terms as the Tcl core.