Web Function Construct¶

The WebFunctionConstruct deploys an AWS Lambda Web Function: an ordinary HTTP server packaged as a zip, uploaded to S3, and run behind a managed HTTPS endpoint. It owns one Web Function's lifecycle — the function, its current immutable revision, its execution role and log groups (each optional), one default endpoint plus any added with AddEndpoint, and the function's single resource-based policy.

It is intentionally workload-neutral: Next.js, ASP.NET Core, and Blazor Static SSR deploy through the same public API, and the differences live in the artifacts and configuration only. See the workload recipes.

Features¶

• S3-backed artifacts: Deploy from an existing S3 object with WebFunctionCode.FromBucket, with optional object-version pinning.
• Explicit endpoint authentication: Every endpoint chooses IamAuth or ApplicationManaged; there is no default auth type.
• Endpoint-scoped grants: GrantInvoke grants lambda:InvokeWebFunctionEndpoint on a specific endpoint ARN.
• CloudFront OAC integration: WebFunctionOrigin returns a CloudFront IOrigin that configures origin access control and the required resource-policy statement.
• One resource policy per function: Every resource-policy contribution flows through a single policy owned by the construct.
• Immutable revisions: Each deployment creates a new revision; endpoints move to it without interruption.
• Configurable role and logs: Bring your own execution role and log groups, or let the construct create the centralized group and its home-Region .local companion.
• Consumer test helpers: Fluent Template assertions and a props builder in the Testing namespace.

Intentional Non-Goals (v1)¶

• Building, publishing, zipping, or uploading artifacts. The S3 object must exist before deployment.
• WebFunctionCode.FromAsset (designed for later; not built).
• Weighted revisions, canary or blue-green routing, traffic shifting, or retaining previous revisions.
• Network connectors (VPC egress).
• Whole-function imports (FromWebFunctionAttributes); only endpoints can be imported.
• Owning or creating CloudFront distributions, ACM certificates, Route 53 records, or WAF. Composition with those is plain CDK.
• Workload-specific constructs or CloudFront behavior helpers.
• Caller-side request signing (SigV4 in your application) or injecting caller configuration.
• Alarms and dashboards.
• Revision encryption with a customer-managed key (KmsKeyArn). Deferred; see Known Limitations. S3 artifact encryption (SSE-S3/SSE-KMS on the code bucket) is supported.

Prerequisites¶

• AWS CDK for .NET 2.274.0 or later (Amazon.CDK.Lib). This release adds the enum values the construct needs for OAC signing.
• A region where Lambda Web Functions are available.
• A versioned S3 bucket that holds the application zip, and an artifact uploaded before you deploy.
• aws-cdk bootstrapped in the account/region if you use CDK assets elsewhere in the same app.

Basic Usage¶

using Amazon.CDK;
using Amazon.CDK.AWS.S3;
using LayeredCraft.Cdk.Constructs;
using LayeredCraft.Cdk.Constructs.Models;

public class MyStack : Stack
{
    public MyStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
    {
        // Artifacts live in a versioned bucket (owned elsewhere or imported by name).
        var artifacts = Bucket.FromBucketName(this, "artifacts", "acme-artifacts");

        var web = new WebFunctionConstruct(this, "web", new WebFunctionConstructProps
        {
            FunctionName = "acme-web",
            Code = WebFunctionCode.FromBucket(artifacts, "1.2.3/web.zip", new WebFunctionCodeFromBucketOptions
            {
                BucketPolicy = WebFunctionCodeBucketPolicy.ExternallyManaged,
            }),
            Endpoint = new WebFunctionEndpointOptions
            {
                AuthType = WebFunctionAuthType.IamAuth,
            },
        });
    }
}

Configuration Properties¶

Required Properties¶

Optional Properties¶

Endpoint options (WebFunctionEndpointOptions)¶

S3 Artifact Requirements¶

WebFunctionCode.FromBucket(bucket, key, options) is the only supported source. The bucket must have versioning enabled, and the object must exist before CloudFormation creates the revision — the construct cannot verify that at synthesis time.

• Version pinning: set WebFunctionCodeFromBucketOptions.ObjectVersion to pin an exact object version. If you omit it, Lambda pins the latest version at revision-creation time.
• Read access: Lambda reads the artifact with the Lambda service principal (lambda.amazonaws.com), not with the caller. When the construct manages the policy (Automatic) the statement grants s3:GetObject and s3:GetObjectVersion and is scoped with both StringEquals aws:SourceAccount (the function's account) and ArnLike aws:SourceArn of the form arn:aws:lambda:{region}:{account}:web-function/{FunctionName}/revision/*. An externally managed policy must grant at least those actions with equivalent scoping.
• Automatic vs ExternallyManaged:
  • Automatic (default) adds that statement and makes the revision depend on the resulting bucket policy. It manages a bucket owned in this app, including a bucket owned by another stack when that stack's account and region are explicitly resolvable (for example a stack created with an explicit Env). If the bucket is imported, or is owned by another stack whose required environment information cannot be resolved, AddToResourcePolicy reports that nothing was added and synthesis fails asking you to switch to ExternallyManaged.
  • ExternallyManaged adds nothing; the bucket's owner must already grant the service-principal read (for example a long-lived artifact bucket deployed and managed in its own stack).
• SSE-KMS: if the code bucket uses SSE-KMS, its key policy must allow lambda.amazonaws.com kms:Decrypt, because Lambda reads with its service principal. CDK-managed aws/s3 and DSSE-managed keys cannot grant that, so an owned bucket using them is rejected. This is separate from the revision's own KmsKeyArn, which is not supported in v1.
• Cross-account / cross-region buckets: allowed within the same partition (not an opt-in region). Cross-account access needs a bucket-policy grant.
• Object lifecycle: deleting the pinned version (or removing read access) moves revisions to permanent Failed; requests then receive 409 Platform.RevisionNotActive.
• CDK bootstrap bucket is not usable: the bootstrap asset bucket does not grant the service-principal read, which is why v1 is FromBucket only.

Execution Role and Logging¶

Execution role¶

• Construct-created role (Role is null): the construct creates an ExecutionRole with the AWS managed AWSLambdaBasicExecutionRole policy. That policy includes logs:CreateLogGroup, logs:CreateLogStream, and logs:PutLogEvents, so a created role can write to the default log groups and to a managed .local companion.
• Supplied role (Role is not null): the construct uses it unchanged and never attaches the managed policy. Whether it adds CloudWatch Logs statements depends on the logging mode and the log-group name; see Execution-role permissions. When it adds nothing, you must configure the role yourself.
• Imported immutable role (Role.FromRoleArn(..., new FromRoleArnOptions { Mutable = false })): the construct never mutates it. You manage every log permission.

ApplicationLogLevel and SystemLogLevel reuse Amazon.CDK.AWS.Lambda.ApplicationLogLevel and SystemLogLevel.

Two CloudWatch Logs groups per Web Function¶

Every Lambda Web Function writes to two CloudWatch Logs groups:

Lambda writes to the companion in the serving Region and centralizes those events into the home-Region group. Events are not removed from the companion after centralization, so the same events appear in both groups with the same timestamps and messages. The centralized stream name adds a -{account}-{region} suffix, which is one way to tell the copies apart. CloudWatch Logs bills storage for both groups, and each group's own retention decides how long its copy remains.

See the AWS documentation for Lambda Web Function logging and Web Function permissions.

Logging modes¶

WebFunctionConstructProps.Logs is a closed choice of three modes:

After construction, LogGroup is the centralized group (or null for ServiceDefault), and LocalLogGroup is the managed or supplied home-Region companion (or null when it is not managed).

WebFunctionLogs.Create (default)¶

Create creates both the centralized group and its home-Region companion:

using Amazon.CDK;
using Amazon.CDK.AWS.Logs;
using LayeredCraft.Cdk.Constructs;
using LayeredCraft.Cdk.Constructs.Models;

var web = new WebFunctionConstruct(this, "web", new WebFunctionConstructProps
{
    FunctionName = "acme-web",
    Code = WebFunctionCode.FromBucket(artifacts, "1.2.3/web.zip", new WebFunctionCodeFromBucketOptions
    {
        BucketPolicy = WebFunctionCodeBucketPolicy.ExternallyManaged,
    }),
    Endpoint = new WebFunctionEndpointOptions { AuthType = WebFunctionAuthType.IamAuth },

    // Retention is independent for the two groups.
    Logs = WebFunctionLogs.Create(
        retention: RetentionDays.ONE_MONTH,          // centralized; default TWO_WEEKS
        removalPolicy: RemovalPolicy.RETAIN,          // both groups; default DESTROY
        companionRetention: RetentionDays.ONE_WEEK),  // companion; default THREE_DAYS
});

// Both are construct-created groups in the stack Region.
ILogGroup centralized = web.LogGroup!;
ILogGroup companion = web.LocalLogGroup!;

• The centralized group defaults to RetentionDays.TWO_WEEKS.
• The companion defaults to RetentionDays.THREE_DAYS. It is a short-lived staging copy whose main use is low-latency Live Tail; three days covers a centralization delay or weekend debugging at modest storage cost.
• companionRetention is independent of retention. Both created groups use the same RemovalPolicy; there is no separate companion removal policy. The default is RemovalPolicy.DESTROY.
• The construct adds explicit dependencies so both groups exist before the revision is created. The revision is also deleted before the groups on teardown.
• LocalLogGroup exposes the created companion.

WebFunctionLogs.Use¶

Use(logGroup, companion = null) routes logs to groups you provide. The construct never creates a group in this mode, including a companion.

using Amazon.CDK;
using Amazon.CDK.AWS.Logs;
using LayeredCraft.Cdk.Constructs;
using LayeredCraft.Cdk.Constructs.Models;

// Both groups are caller-owned and can have different retention.
var centralized = new LogGroup(this, "AppLogs", new LogGroupProps
{
    LogGroupName = "/acme/web",
    Retention = RetentionDays.ONE_MONTH,
});

var companion = new LogGroup(this, "AppLogsLocal", new LogGroupProps
{
    LogGroupName = "/acme/web.local",
    Retention = RetentionDays.THREE_DAYS,
});

var web = new WebFunctionConstruct(this, "web", new WebFunctionConstructProps
{
    FunctionName = "acme-web",
    Code = WebFunctionCode.FromBucket(artifacts, "1.2.3/web.zip", new WebFunctionCodeFromBucketOptions
    {
        BucketPolicy = WebFunctionCodeBucketPolicy.ExternallyManaged,
    }),
    Endpoint = new WebFunctionEndpointOptions { AuthType = WebFunctionAuthType.IamAuth },
    Logs = WebFunctionLogs.Use(centralized, companion),
});

• When the optional companion is supplied, it must have the name {centralizedName}.local. The construct validates names that are provably literal and throws ArgumentException (parameter companion) on a mismatch. Tokenized names are accepted rather than rejected speculatively.
• When the companion is omitted, the construct does not manage it. Lambda creates {centralizedName}.local on first request with no expiry unless it already exists, and warning W1 explains that retention remains externally managed. LocalLogGroup is null in this case.
• When the companion is supplied, LocalLogGroup references that group.
• Same-stack owned groups receive a revision dependency, so they exist before the revision. Imported groups (LogGroup.FromLogGroupName / LogGroup.FromLogGroupArn) and groups in another stack get no dependency: they must already exist before the deployment. The construct never invents a cross-stack dependency.
• The construct does not stop Lambda from creating a companion in other serving Regions; see Multi-Region endpoints.

WebFunctionLogs.ServiceDefault¶

ServiceDefault() creates neither group and leaves both to the Lambda service:

Logs = WebFunctionLogs.ServiceDefault()

• Lambda creates /aws/lambda/web/{FunctionName} and its .local companion on first use with default settings.
• Neither group has a finite retention: they never expire. The construct does not enforce retention in this mode.
• LogGroup and LocalLogGroup are both null.
• No W1 warning is emitted, because Use is not involved.
• The service-created groups are not stack-owned and outlive the stack.
• ServiceDefault is not suitable when you expect automatically managed retention or CloudFormation-managed deletion.

Ownership and retention¶

Do not switch ownership of an existing companion casually: see Upgrading an existing deployment.

Ordering and teardown¶

• Create: the revision depends explicitly on both created groups, not on synthesis order. Teardown deletes the revision first, then the groups (subject to RemovalPolicy).
• Use with same-stack owned groups: the revision depends on each supplied group that is a resource in the same stack. Imported and cross-stack groups get no dependency and must exist before deployment.
• Teardown: DESTROY removes both managed groups after the revision; RETAIN keeps both. Service-created and other-Region companions are never removed by this stack.

Execution-role permissions¶

CloudWatch Logs authorizes different actions against different resource types. Keep this distinction when writing your own policies:

ILogGroup.GrantWrite uses …:log-group:{name}:*, whose :* covers that group's log streams. The companion grant below uses the documented …:log-group:{name}.local:log-stream:* form.

The construct adds companion statements only when its existing write trigger applies: Use mode with a log-group name that is a token or is outside /aws/lambda/*. When the statements apply, they are:

• Companion write (G1): logs:CreateLogStream and logs:PutLogEvents on arn:{partition}:logs:{R}:{account}:log-group:{c}.local:log-stream:*.
• Companion create (G2, only when Lambda may create the companion): logs:CreateLogGroup on arn:{partition}:logs:{R}:{account}:log-group:{c}.local. It is added when no companion is supplied, or as soon as any endpoint is PerRegion or MultiRegion.
• {R} is the stack Region while every endpoint is HomeRegion, and * once any endpoint is PerRegion/MultiRegion.
• The construct never grants logs:CreateLogGroup on the centralized group, and never uses logs:* or a log-group:* resource. CreateLogGroup is not always granted.

Where the construct adds no statements (every Create and ServiceDefault configuration, immutable imported roles, and Use with an /aws/lambda/* name), the role must allow at least the following. A construct-created role already does so through AWSLambdaBasicExecutionRole; a supplied role is caller-managed:

• logs:CreateLogStream and logs:PutLogEvents on the centralized group's log streams, arn:{partition}:logs:{home}:{account}:log-group:{c}:log-stream:*, and on the companion's log streams, arn:{partition}:logs:{R}:{account}:log-group:{c}.local:log-stream:*.
• logs:CreateLogGroup on arn:{partition}:logs:{R}:{account}:log-group:{c}.local when a companion may be created (Use(g), ServiceDefault, or non-home-Region endpoints).
• For ServiceDefault, also logs:CreateLogGroup on arn:{partition}:logs:{home}:{account}:log-group:{c}.

If the CDK @aws-cdk/aws-iam:minimizePolicies setting combines statements during synthesis, the resulting effective permissions are the same; only the statement layout changes.

Multi-Region endpoints¶

The construct provisions a companion only in the stack (home) Region. When an endpoint is PerRegion or MultiRegion, Lambda may run requests in other Regions and creates a companion group there on first request. Those remote groups:

• Are service-created with no expiry and are not managed by this construct.
• Are not removed by stack teardown.
• Require logs:CreateLogGroup in those Regions (and write access to their log streams) when the execution role is caller-managed.

Each qualifying endpoint emits warning W2. The construct does not provision cross-Region log groups and does not add cross-stack resources. If you require finite retention outside the home Region, create those regional groups separately (for example in a stack deployed to each Region) and configure their retention there.

Warnings¶

The construct emits two acknowledgeable warnings with stable IDs. Unacknowledged warnings can fail strict synthesis (cdk synth --strict).

W1 is not emitted for Create, Use(g, c), or ServiceDefault. For literal names it reads:

Web Function '{fn}' writes to '{c}', but its companion log group '{c}.local' is not managed by this construct. Lambda creates it on first request with no expiry unless it already exists. Pass the companion to WebFunctionLogs.Use(logGroup, companion) or set its retention separately.

When the function or group name is a token, the message uses descriptive wording instead ("This Web Function writes to a log group whose companion log group is not managed...") and never contains raw token text.

W2 for literal names reads:

Endpoint '{endpoint}' ({type}) runs requests in Regions other than the stack Region. Lambda creates the companion log group '{c}.local' in each of those Regions on first request with no expiry; this construct does not manage log groups outside the stack Region. Set their retention separately. {mode sentence}

The trailing mode sentence is:

Tokenized names use descriptive wording ("This endpoint…" and "a per-Region companion log group") and never contain raw token text.

Acknowledge a warning on the construct, the endpoint, or an ancestor such as the stack. CDK applies an acknowledgement to child scopes, so acknowledging on the stack suppresses it for the whole stack:

using Amazon.CDK;

var web = new WebFunctionConstruct(this, "web", props);

// W1: the caller owns the companion and its retention.
Amazon.CDK.Annotations.Of(this).AcknowledgeWarning(
    "@layeredcraft/cdk-constructs:webFunctionUnmanagedCompanionLogGroup",
    "The companion log group and its retention are managed outside this stack.");

// W2: regional companions are managed out of band.
Amazon.CDK.Annotations.Of(this).AcknowledgeWarning(
    "@layeredcraft/cdk-constructs:webFunctionRemoteCompanionLogGroups",
    "Regional companion groups are created with retention by our regional logging stack.");

The second argument is the reason recorded with the acknowledgement. Use Amazon.CDK.Annotations (not Amazon.CDK.Assertions.Annotations) to avoid the name clash in a test project.

Upgrading an existing deployment (AlreadyExists)¶

If a Web Function has already served traffic without a managed companion, Lambda may have created {centralizedName}.local already. That includes stacks deployed with earlier 2.6.0-preview versions, a switch from ServiceDefault() to Create(), a switch from Use(g) to Use(g, companion), or a redeploy after the stack was deleted while its service-created groups remained.

A subsequent CloudFormation deployment that tries to create a group with the same physical name fails with AlreadyExists. The construct has no adoption, import, or migration mechanism for existing service-created groups.

Supported remedies:

• Delete the existing service-created group immediately before deploying, after coordinating the deployment window and accepting the loss of its events. This applies to the .local companion, and to the centralized group when moving from ServiceDefault() to Create().
• Move to a new centralized group name, for example with WebFunctionLogs.Use and a caller-owned pair, so the managed group does not collide with the service-created name.

Assess existing log retention and operational requirements before changing logging ownership. Do not routinely delete production log groups; deleting a group permanently removes its events.

Function Revisions and Endpoints¶

Revisions¶

Every deploy creates a new immutable revision. Changing the code key/version, environment variables, timeout, role, logging, or description produces a new revision and moves every endpoint to it without interruption. The previous revision is deleted during cleanup. Rollback is a redeploy of an earlier artifact (which creates another new revision); there is no re-selection of an old revision.

Endpoints¶

The construct always creates a DefaultEndpoint (endpoint name default) and exposes it as the DefaultEndpoint property. Add more with AddEndpoint(id, options); each added endpoint has identical semantics to the default one. Endpoint names must be unique per function, so passing EndpointName = "default" to AddEndpoint fails as a duplicate.

AddEndpoint rejects the reserved construct IDs Function, Revision, DefaultEndpoint, ExecutionRole, LogGroup, LocalLogGroup, and ResourcePolicy with an ArgumentException.

var webhooks = web.AddEndpoint("webhooks", new WebFunctionEndpointOptions
{
    EndpointName = "webhooks",
    AuthType = WebFunctionAuthType.ApplicationManaged,
    RateLimit = 100,
});

To change an endpoint's EndpointName, EndpointType, or Regions you cannot update in place — CloudFormation would try to replace a fixed name and fail with "already exists", and the domain changes. Add a new endpoint, move consumers, then remove the old one.

Authentication Modes¶

AuthType is a decision you make on every endpoint:

ApplicationManaged is appropriate when your application authenticates every request itself (for a genuinely public API). IamAuth is appropriate for service-to-service calls and for endpoints fronted by CloudFront with OAC.

Invocation Grants¶

Use GrantInvoke on an endpoint to authorize callers. An endpoint is an IResource and exposes:

• endpoint.GrantInvoke(grantee) — the default Automatic caller policy.
• endpoint.GrantInvoke(grantee, new WebFunctionInvokeGrantOptions { CallerPolicy = WebFunctionCallerPolicy.ExternallyManaged }).
• endpoint.GrantCloudFrontInvoke(distributionArn) — CloudFront-specific (see CloudFront OAC).

GrantInvoke throws for an ApplicationManaged endpoint: there is no IAM boundary to grant against.

Identity policy vs resource policy¶

• A same-account caller needs only an identity policy (an AWS::IAM::Policy attached to the caller) allowing lambda:InvokeWebFunctionEndpoint on the endpoint ARN.
• A cross-account caller needs the identity policy and a statement in the function's resource policy.

GrantInvoke writes the correct side for you whenever it can establish ownership, and fails synthesis when it cannot, rather than silently producing a nonfunctional grant.

Owned versus imported principals¶

The construct distinguishes two kinds of grantee:

• Owned mutable identities — Role, User, Group, or LazyRole created in this app (for example, a Role L2 or a WebFunctionConstruct itself). These can receive an identity policy.
• Everything else — imported roles/users (Role.FromRoleArn), principals without a concrete owned identity, and any principal whose account cannot be established. Whether an identity policy may be written depends on the rules below.

Same-stack, environment-agnostic grants¶

Automatic grants are valid when the owned caller and the endpoint belong to the same Stack instance, even when that stack's environment is unresolved. This is specifically about a single stack (or one stack reference) — two separate env-agnostic stacks are not the same stack. Their accounts are unresolved, so an Automatic grant between them is rejected; use ExternallyManaged across such stacks.

Cross-stack and cross-account restrictions¶

Automatic (the default) requires the library to fully configure invocation within this deployment. It rejects, at synthesis:

• Two different stacks where either stack's account is unresolved.
• Two different stacks with different literal accounts.
• Cross-account imported roles.
• Any grantee whose account cannot be established.

For these cases use ExternallyManaged (below) and configure the caller's identity policy in the caller's own account/stack.

Automatic versus ExternallyManaged caller policies¶

Why GrantInvoke rejects certain principals¶

To avoid confused-deputy grants and false confidence, GrantInvoke fails synthesis for:

• Service principals — bare or conditioned. An unconditioned service-principal statement would let, for example, any distribution in any account with an OAC origin for this endpoint invoke it. Use GrantCloudFrontInvoke(distributionArn) for CloudFront, or an explicit condition-scoped AddToResourcePolicy statement for any other service, including the scoping condition that service documents. GrantInvoke cannot know which condition keys a service supplies, so it neither adds aws:SourceAccount nor accepts arbitrary conditions as proof of scoping.
• Account principals (AccountPrincipal, AccountRootPrincipal, and any principal whose literal AWS principal is an account-root ARN), including the same account. An account-root resource statement authorizes no specific caller by itself, so it is never treated as a complete Automatic grant. Under ExternallyManaged an explicitly requested account principal can be recorded in the owned endpoint's resource policy, but that is only half the picture — caller-side authorization is still not configured, and the result must not be described as a working grant.
• Wildcard principals (conditioned or not) — AnyPrincipal, StarPrincipal, OrganizationPrincipal, *. Conditioned wildcards are supported only through an explicit AddToResourcePolicy statement (see below). AddToResourcePolicy only checks that an Allow wildcard statement has conditions — it does not verify that those conditions actually restrict access. You own the condition semantics: a condition such as aws:PrincipalOrgID can meaningfully restrict who may invoke, but the mere presence of a condition proves nothing, so design and validate the condition yourself.
• PrincipalWithConditions wrapping any principal, under either caller policy. Grant the underlying principal directly, or use AddToResourcePolicy.
• Role.WithoutPolicyUpdates() and every imported role as an identity-policy target — they are not concrete owned mutable identities, so the library falls back to the resource policy on an owned endpoint, or throws on an imported one.

If a case cannot be safely configured on either side, GrantInvoke throws. A false negative (requiring you to act) is always preferred over a false positive.

Resource-Policy Ownership¶

A Web Function has exactly one resource policy, attached to the function ARN, and the construct owns it. Every contribution flows through that single policy:

• The construct exposes no public "add to function policy" entry point. The only resource-policy entry points are on the endpoint: GrantInvoke, GrantCloudFrontInvoke, and AddToResourcePolicy.
• endpoint.AddToResourcePolicy(statement) requires statement.Resources to be exactly that endpoint's ARN; anything else throws an ArgumentException.
• Statements are validated when added (a Deny is unrestricted; an Allow must not use NotPrincipal; an Allow naming a wildcard or service principal must carry conditions), copied, frozen, and validated as part of the candidate policy document. A rejected statement leaves no partial state.
• Identical statements are deduplicated at synthesis.
• Multiple distributions or endpoints never create competing policy resources.

Because the policy is a single PUT-replace resource, an out-of-band aws lambda-web put-resource-policy is overwritten the next time the policy changes, and AWS warns against combining it with AWS::Lambda::Permission on the same function. Keep this function's invocation authorization in this construct.

Imported Endpoints¶

Use WebFunctionEndpointConstruct.FromEndpointAttributes to reference an endpoint owned by another stack or app:

var shared = WebFunctionEndpointConstruct.FromEndpointAttributes(this, "shared", new WebFunctionEndpointAttributes
{
    EndpointArn = "arn:aws:lambda:us-east-1:111122223333:web-function/shared/endpoint/default",
    DomainName = "abc123.lambda-web.us-east-1.on.aws",
    AuthType = WebFunctionAuthType.IamAuth,
});

An imported endpoint owns nothing. Its GrantCloudFrontInvoke and any grant that would need its resource policy throw — the resource policy is owned externally. GrantInvoke with CallerPolicy = ExternallyManaged also throws on an imported endpoint, because there is no owned resource policy to receive the statement; configure the caller's access in the endpoint owner's policy instead. It is usable as a CloudFront origin with WebFunctionOriginPermissions.ExternallyManaged, and it writes identity policies only for an owned mutable caller whose account is literally the same as the endpoint's.

• Literal EndpointArn values are validated against arn:{partition}:lambda:{region}:{12-digit account}:web-function/{function}/endpoint/{endpoint}; literal DomainName must be non-empty; literal Account must be 12 digits and agree with a literal ARN's account.
• Account (WebFunctionEndpointAttributes.Account) is required when EndpointArn is a token and you want identity grants: the endpoint's account = the literal ARN account, else the literal Account, otherwise it is not established and GrantInvoke throws for every grantee. A token-ARN endpoint can still be used as a CloudFront origin with ExternallyManaged permissions.

CloudFront OAC Integration¶

WebFunctionOrigin is a static factory that returns a CloudFront IOrigin, analogous to CDK's FunctionUrlOrigin.

var origin = WebFunctionOrigin.WithOriginAccessControl(web.DefaultEndpoint, new WebFunctionOriginWithOacProps
{
    CustomHeaders = new Dictionary<string, string> { ["x-origin-verify"] = secret },
});

var distribution = new Distribution(this, "distribution", new DistributionProps
{
    DefaultBehavior = new BehaviorOptions
    {
        Origin = origin,
        ViewerProtocolPolicy = ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
        AllowedMethods = AllowedMethods.ALLOW_ALL,
        CachePolicy = CachePolicy.CACHING_DISABLED,
        OriginRequestPolicy = OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
    },
    AdditionalBehaviors = new Dictionary<string, IBehaviorOptions>
    {
        ["/_next/static/*"] = new BehaviorOptions { Origin = origin, CachePolicy = CachePolicy.CACHING_OPTIMIZED },
    },
    DomainNames = ["app.example.com"],
    Certificate = certificate,
});

• WithOriginAccessControl(endpoint, props) requires an IamAuth endpoint. When bound to a distribution it creates one FunctionUrlOriginAccessControl (origin type lambda, always-amz-auth, sigv4 for HomeRegion/PerRegion and sigv4a for MultiRegion) and adds the resource-policy statement cloudfront.amazonaws.com → lambda:InvokeWebFunctionEndpoint on the endpoint ARN with StringEquals aws:SourceArn = arn:aws:cloudfront::{account}:distribution/{id}.
• WithoutOriginAccessControl(endpoint, props) requires an ApplicationManaged endpoint; the endpoint remains directly reachable and CloudFront adds no access control.
• Passing an ApplicationManaged endpoint to the OAC factory, or an IamAuth endpoint to the non-OAC factory, throws an InvalidOperationException at the factory call.
• Automatic permissions (the default) require the distribution and the Web Function to be in the same stack; otherwise synthesis fails with a dependency-cycle explanation. For a cross-stack distribution, use Permissions = WebFunctionOriginPermissions.ExternallyManaged and grant the distribution ARN via endpoint.GrantCloudFrontInvoke(...) in the owner's stack (a two-phase rollout).
• The same origin object reused on several behaviors of one distribution binds once, producing one OAC and one policy statement.
• A supplied OriginAccessControl is used unchanged and not inspected; the consumer is responsible for it being lambda/always-amz-auth/correct protocol.

Caching and header guidance¶

• Never forward the viewer Host header. Use OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER, not ALL_VIEWER. Forwarding Host makes the endpoint return 404.
• Dynamic/personalized routes should use CACHING_DISABLED.
• For GET/HEAD, CloudFront drops the viewer Authorization header unless it is part of the cache policy; prefer cookies or custom headers, and add Authorization to a cache policy only when you truly need it.
• Host-dependent applications (multi-tenant hosts) must recover the viewer host through a CloudFront Function that copies it into a custom header, and trust that header only after an origin-verification check.
• Content-hashed static assets (/_next/static/*, Blazor fingerprinted /_framework/* files, /_content/*) should use CACHING_OPTIMIZED.
• Lambda@Edge origin-request/origin-response triggers are rejected by CloudFront on behaviors that use a Web Function origin with OAC.
• OAC is not supported for global endpoints that include opt-in regions (requests get 403).
• OAC takes effect only after the distribution deploys (and, for MultiRegion, after the policy replicates); brief 403s in between are expected.

Grant Behavior Reference¶

The table below summarizes GrantInvoke behavior for an owned endpoint (an endpoint on a function in this app). An imported endpoint is stricter: it owns no resource policy, so only an owned mutable caller whose account is literally the same as the endpoint's can be granted (via an identity policy), and every other case throws.

"Partial by contract" means the library writes the resource-policy statement (on an owned endpoint) and annotates what the caller must do; it never claims the caller side is configured.

Signing Requests¶

A direct IAM invocation of an IamAuth endpoint must be signed with AWS Signature Version 4:

• Service name: lambda.
• Payload hash: send x-amz-content-sha256: UNSIGNED-PAYLOAD (chunked payload signing is not supported).
• Protocol: HomeRegion and PerRegion endpoints use SigV4 signed for the endpoint's Region; MultiRegion endpoints use SigV4A with the signing region set to *.
• The construct (and CloudFront, when not using OAC) does not sign requests on your behalf — the calling SDK or your BFF signs itself.

CloudFront OAC signing is different: with always-amz-auth, CloudFront signs the origin request in its own dedicated header and passes the viewer's Authorization header through unchanged. Lambda strips its own SigV4 Authorization (and X-Amz-Security-Token) before forwarding, so application code sees the viewer's header, not the caller's signature.

Resource Replacement and Update Behavior¶

A deployment that fails is rolled back by CloudFormation to the previous revision. These behaviors follow the CloudFormation resource model in the approved design; anything not listed here should be treated as unverified.

Public Testing Helpers¶

The LayeredCraft.Cdk.Constructs.Testing namespace ships fluent helpers for synthesized templates:

• WebFunctionConstructAssertions extension methods on Template: ShouldHaveWebFunction, ShouldHaveRevision, ShouldHaveRevisionCode, ShouldHaveEndpoint, ShouldHaveEndpointScaling, ShouldHaveInvokeGrant, ShouldHaveSingleResourcePolicy, ShouldHaveNoResourcePolicy, ShouldAllowCloudFront, ShouldAllowResourcePolicyPrincipal, ShouldHaveWebFunctionOac, ShouldHaveCodeBucketReadStatement, ShouldHaveWebFunctionLogGroup, ShouldHaveCompanionLogGroup, and ShouldHaveRevisionDependingOnLogGroups. The function, endpoint, and policy assertions match by function and endpoint names (not logical IDs) and require Effect = Allow with the expected action and the exact endpoint resource, so a Deny or an unrelated action never satisfies them. The log-group assertions match by log-group name and exact RetentionInDays; ShouldHaveRevisionDependingOnLogGroups resolves names to logical IDs through the template.
• WebFunctionConstructPropsBuilder via CdkTestHelper.CreateWebFunctionPropsBuilder(): WithFunctionName, WithCode, WithTestArtifact, WithIamAuthEndpoint, WithApplicationManagedEndpoint, WithEndpoint, WithEnvironmentVariable, WithEntryPoint, WithTimeout, WithMaxConcurrencyPerEnvironment, WithRole, WithLogs, then Build(). Build() throws without code or an endpoint.

Note that ShouldHaveLogGroup belongs to LambdaFunctionConstructAssertions; use ShouldHaveWebFunctionLogGroup for Web Functions.

var template = Template.FromStack(stack);
template.ShouldHaveWebFunction("acme-web");
template.ShouldHaveEndpoint("acme-web", "default", WebFunctionAuthType.IamAuth);
template.ShouldAllowCloudFront("acme-web", "default");

template.ShouldHaveWebFunctionLogGroup("/aws/lambda/web/acme-web", 14);
template.ShouldHaveCompanionLogGroup("/aws/lambda/web/acme-web", 3);
template.ShouldHaveRevisionDependingOnLogGroups(
    "acme-web",
    "/aws/lambda/web/acme-web",
    "/aws/lambda/web/acme-web.local");

Workload Recipes¶

Detailed recipes for Next.js, ASP.NET Core (Node.js execve shim), and Blazor Static SSR are in the Web Function Workloads page. They show how to build each artifact and wire CloudFront, and they are explicit about what synthesis tests verify versus what requires a real AWS deployment.

Known Limitations and Operational Guidance¶

• S3 versioning via escape hatches is not detected. The owned-bucket inspection only reads literal values in the rendered L2 properties. Versioning enabled through a property override (CfnBucket) is not detected; reference such a bucket by name (Bucket.FromBucketName) with ExternallyManaged instead.
• Tokenized configuration is skipped, never rejected. A token versioning status, encryption algorithm, or key ID can be shown neither compliant nor non-compliant, so validation skips it.
• Log-group switching. Moving an existing function from WebFunctionLogs.ServiceDefault() to Create() — or adopting a managed companion where Lambda already created {name}.local — can fail with AlreadyExists, because Lambda may have auto-created the group. See Upgrading an existing deployment for the supported remedies.
• Service-created default log groups outlive the stack. With WebFunctionLogs.ServiceDefault() (or a Use companion the construct does not manage) the construct creates no AWS::Logs::LogGroup; the Lambda service creates the group on first invocation. Such groups are not part of the stack, have no expiry, and are not removed by CloudFormation on teardown, so they keep the invocation history after the stack is deleted. CDK-managed Create() groups are stack-owned and follow their RemovalPolicy. In disposable sandboxes, delete leftover service-created groups explicitly by exact name after destroying the stack. Do not routinely delete production log groups.
• IAM policy propagation. The revision depends on the execution role's CfnRole only, never the role's default policy, so permissions granted to the role may not have propagated when the revision first activates. This avoids CloudFormation cycles for mutually-referencing functions.
• CloudFront origin-binding exceptions across jsii. Validation that runs inside the CDK IOrigin.Bind path (and inside HttpOrigin construction) surfaces in .NET as a System.Exception carrying CDK's message, whereas factory-time checks throw InvalidOperationException.
• F3006 resource-type warnings. CDK 2.274.0 emits F3006 "Unknown resource type AWS::Lambda::WebFunction*" validation warnings. They are warnings by default and become synthesis errors when @aws-cdk/core:validateAgainstDefaultRules is enabled; acknowledge with CloudFormation-Validate::F3006.
• OAC naming. The auto-created OAC name is derived from the distribution's origin scope. OAC names are unique per AWS account across Regions, so the collision risk is identical names within the same account — not across different accounts. If you deploy the same distribution shape repeatedly in one account, verify the generated naming still meets your conventions.
• Origin request policy. Use ALL_VIEWER_EXCEPT_HOST_HEADER, never ALL_VIEWER (see Caching and header guidance).
• Customer-managed revision keys. KmsKeyArn is not supported in v1. The only workaround is an unsupported escape hatch — ((CfnWebFunctionRevision)web.Node.FindChild("Revision")).KmsKeyArn = key.KeyArn plus the key-policy grants you write.
• Sandbox validation. Runtime behavior (actual invocation, execve shims, readiness, CloudFront end-to-end) is validated only by a real deployment in a sandbox account; synthesis tests do not prove runtime support.

Validation Errors¶

The construct fails at synthesis with ArgumentException, ArgumentOutOfRangeException, or InvalidOperationException, following repository style. Literal values are validated; tokens (Token.IsUnresolved) are skipped, never rejected. Notable cases:

• OAC origin for an ApplicationManaged endpoint, or non-OAC origin for an IamAuth endpoint → InvalidOperationException at the origin factory.
• Automatic OAC permissions with an imported endpoint or a cross-stack distribution → InvalidOperationException at bind.
• GrantInvoke/GrantCloudFrontInvoke on an ApplicationManaged endpoint, or a resource-policy grant on an imported endpoint → InvalidOperationException.
• An Automatic grant that cannot be fully configured → InvalidOperationException naming the grantee, endpoint, reason, and remedies.
• AddToResourcePolicy with a resource that is not exactly the endpoint ARN, or an unconditioned wildcard/service-principal Allow, or NotPrincipal → ArgumentException.
• A props-builder Build() without code or endpoint → InvalidOperationException.

Testing¶

See the Testing Guide for the test helpers and patterns shared across constructs.

Examples¶

See the Examples page and the Web Function Workloads page.