AWS Lambda recently announced WebFunction , a new way to run HTTP servers in AWS Lambda without wrapping them into an event handler. It is so fresh out of the oven that we don't have an L2 Construct yet. That gives me the chance to explore it and write my own L2 Construct 🤩
An L2 Construct is a building block that abstracts multiple L1 Constructs. L1 constructs represent a single CloudFormation resource in the higher language.
Currently, for the WebFunction, we have three L1 Constructs that we will simplify into one L2 Construct.
As a developer, I expected a WebFunction to include an endpoint; otherwise, what's the point?
The revision is the code I deploy, but the name isn't clear to me.
You can also distribute it to specific regions and assign weights.
In addition, there's an IAM role for the Lambda Web Function and an S3 Bucket for the HTTP server code.
We will use TypeScript in this blog 🚀
Parameters
As a developer, I want the best developer experience and the ability to customize it to my needs. That is why TypeScript is a strong candidate: you can keep your setup as minimal as you want while still making it configurable.
From the CloudFormation documentation, there are parameters required:
Some of them are incomprehensible without reading their docs.
For example, BuildConfig requires an S3 bucket and a Runtime as a reference, but as a developer (or agent), I want to upload my HTTP server from my local machine, so it would be nice to simply add my local path, and it automatically dumps it into an S3 Bucket.
AuthType and EndpointType could be enums so developers can't add a random string, and the ServiceConfig is currently so small that it can be hidden (but still be configurable later). My parameters for my L2 Construct (in Zod style)
const EndpointType = z.enum(["HOME_REGION", "MULTI_REGION", "PER_REGION"]);
type EndpointType = z.infer<typeof EndpointType>;
const AuthType = z.enum(["AWS_IAM", "APPLICATION_MANAGED"]);
type AuthType = z.infer<typeof AuthType>;
const WebFunctionEndpointProps =
z.custom<
Omit<
CfnWebFunctionEndpointProps,
"functionName" | "authType" | "endpointType" | "endpointName"
>
>();
const WebFunctionRevisionProps =
z.custom<Omit<
CfnWebFunctionRevisionProps,
"functionName" | "buildConfig" | "serviceConfig"
>
>();
const WebFunctionProps = z
.object({
entry: z.string(),
endpointType: EndpointType,
endpointName: z.string(),
functionName: z.string(),
authType: AuthType,
})
.extend(WebFunctionRevisionProps)
.extend(WebFunctionEndpointProps);
type WebFunctionProps = z.infer<typeof WebFunctionProps>;
I combine all L1 Construct props into a single type. I omit required parameters from the sub-props.
That gives me autocompletion and a better understanding of what to add here.
The idea is to create the resource like
new WebFunction(stack, "WebFunction", {
entry: "src/http.ts",
functionName: "my-web-function",
authType: WebFunctionAuthType.APPLICATION_MANAGED,
endpointType: WebFunctionEndpointType.HOME_REGION,
endpointName: "prod",
// additional parameter
});
And perhaps you notice that I omitted buildConfig and serviceConfig .
According to the documentation, they are required, but the configurations are so few that we can remove the configuration overhead for developers.
As shown in the diagram above, we need to put the code into an S3 bucket as a zip file.
One challenge I was facing was zipping and uploading before provisioning the web functions constructs. I also wanted to bundle the code into a single file, so I passed an entry property.
Below, you can see the whole flow using AWS CDK.
Code-wise, another challenge was a separate CDK synthesis timing issue: uploading to S3 was asynchronous, and it created CDK resources after the async ZIP step. CDK needs those resources during synchronous construct creation and synthesis, so they could be missing when synthesis ran and interfere with the watch/deploy loop.
The fix is to bundle and ZIP synchronously while constructing WebFunction, then let CDK handle uploading the staged ZIP during deployment. Furthermore, the entry file has to be named index.js .
Conclusion
The new web function is not simply "just" a function but a construct of three parts: revision, endpoint, and the web function itself (even though that part is useless).
In this post, we've seen what you need to develop an L2 construct in AWS CDK and that it is not straightforward. The CloudFormation documentation still doesn't cover these three parts comprehensively, so we had to rely on trial and error.
Next, I will benchmark several Node.js frameworks and compare them with HTTP API Gateway and the "old" event-based approach.
Loading article