lamux

README

Lamux

Description

Lamux is a HTTP multiplexer for AWS Lambda Function aliases.

Usage

Usage: lamux [flags]

Flags:
  -h, --help                           Show context-sensitive help.
      --port=8080                      Port to listen on ($LAMUX_PORT)
      --function-name="*"              Name of the Lambda function to proxy ($LAMUX_FUNCTION_NAME)
      --domain-suffix="localdomain"    Domain suffix to accept requests for ($LAMUX_DOMAIN_SUFFIX)
      --upstream-timeout=30s           Timeout for upstream requests ($LAMUX_UPSTREAM_TIMEOUT)

Lamux runs an HTTP server that listens on a specified port and forwards requests to a specified Lambda function aliases. The Lambda function alias is identified by its name, and the domain suffix is used to determine which requests should be forwarded to it.

For example, if you run lamux with --function-name=example and --domain-suffix=example.com, it will forward requests to foo.example.com to the Lambda function aliased example:foo.

The forwarded Lambda functions should process Function URLs payload, but these functions do not need Function URLs settings.

Request URL	Lambda Function	Alias
http://foo.example.com/	example	foo
http://bar.example.com/	example	bar

Limitations

Lambda alias names allow alphanumeric characters, hyphens, and underscores, but domain names do not allow underscores. And more, lamux uses - as a delimiter between the alias and the function name.

• alias name pattern: ^[a-zA-Z0-9]+$ (- and _ are not allowed)
• function name allows: ^[a-zA-Z0-9-_]+$ (- is allowed, _ is not allowed)

Route to multiple Lambda functions

You can route requests to any Lambda function by specifying the --function-name set to *.

In this case, Lamux will forward requests to the Lambda function aliased myalias-my-func.example.com to the Lambda function my-func aliased as myalias.

Request URL	Lambda Function	Alias
http://foo-bar.example.com/	bar	foo
http://foo-baz.example.com/	baz	foo
http://bar-baz.example.com/	baz	bar

Working with CloudFront and Lambda FunctionURLs

Lamux can work as a Lambda FunctionURLs. But in this case, Lamux cannot use the Host header because the Lambda function should be accessed via FunctionURLs (e.g., ***.lambda-url.us-east-1.on.aws). So, Lamux uses the X-Forwarded-Host header to determine which requests should be forwarded to the Lambda function.

You may use CloudFront to forward requests to Lamux running on FunctionURLs. In this case, you should set the X-Forwarded-Host header to the original Host header value by Cloud Front Functions(CFF).

// CloudFront Function for setting X-Forwarded-Host header in viewer request
async function handler(event) {
  const request = event.request;
  request.headers['x-forwarded-host'] = { value: request.headers['host'].value };
  return request;
}

Working as a Lambda extension

Lamux can work as a Lambda extension. In this case, Lamux works the same as the local server mode, but it can be registered as a Lambda extension.

This mode is useful for calling other Lambda functions from the Lambda function running on a VPC without the NAT Gateway. Your Lambda handlers can invoke other Lambda functions by HTTP request to the Lamux extension.

To deploy Lamux as a Lambda extension, you need to create a Lambda layer that contains a lamux binary in the extensions/ directory.

$ mkdir extensions
$ cp /path/to/lamux extensions/lamux
$ zip -r layer.zip extensions
$ aws lambda publish-layer-version \
		--layer-name lamux \
		--zip-file fileb://layer.zip \
		--compatible-runtimes provided.al2023 provided.al2

Installation

Download the latest release

The lamux binary is a standalone executable. You can run it on your local machine or deploy it to AWS Lambda bootstrap for custom runtimes (provided.al2023 or provided.al2).

Configuration

All settings can be specified via command-line flags or environment variables.

AWS_REGION environment variable

AWS region to use.

IAM Policy

Lamux must have the IAM policy, which can lambda:InvokeFunction.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "lambda:InvokeFunction",
      "Resource": "*",
    }
  ]
}

If you want to restrict the functions to invoke, you must set an IAM Policy to specify the Lambda function to be invoked.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "lambda:InvokeFunction",
      "Resource": [
        "arn:aws:lambda:us-east-1:123456789012:function:foo:*",
        "arn:aws:lambda:us-east-1:123456789012:function:bar:*",
      ],
    }
  ]
}

If lamux runs on Lambda Function URLs, you should attach the appropriate execution policy to the Lambda function's role. (e.g., AWSLambdaBasicExecutionRole managed policy)

--port ($LAMUX_PORT)

Port to listen on. Default is 8080. This setting is ignored when lamux running on AWS Lambda Function URLs.

--function-name ($LAMUX_FUNCTION_NAME)

Name of the Lambda function to proxy. This setting is required.

If you set --function-name to *, Lamux will route requests to any Lambda function. In this case, the Lambda function and alias are determined by the hostname.

--domain-suffix ($LAMUX_DOMAIN_SUFFIX)

Domain suffix to accept requests for. This setting is required.

--upstream-timeout ($LAMUX_UPSTREAM_TIMEOUT)

Timeout for upstream requests. Default is 30s.

This setting is affected by the Lambda function timeout. If the Lambda function timeout is less than the --upstream-timeout, it will time out before the --upstream-timeout.

LICENSE

MIT

Author

Fujiwara Shunichiro

Documentation

Index

• func Run(ctx context.Context) error
• type Config
  • func (cfg *Config) ExtractAliasAndFunctionName(_ context.Context, r *http.Request) (string, string, error)
  • func (cfg *Config) Validate() error
• type HandlerError
  • func (h *HandlerError) Code() int
  • func (h *HandlerError) Error() string
  • func (h *HandlerError) Unwrap() error
• type Lamux
  • func NewLamux(cfg *Config) (*Lamux, error)
  • func (l *Lamux) Invoke(ctx context.Context, functionName, alias string, b []byte) (*lambda.InvokeOutput, error)

Functions

func Run

func Run(ctx context.Context) error

Types

type Config

type Config struct {
	Port            int           `help:"Port to listen on" default:"8080" env:"LAMUX_PORT" name:"port"`
	FunctionName    string        `help:"Name of the Lambda function to proxy" default:"*" env:"LAMUX_FUNCTION_NAME" name:"function-name"`
	DomainSuffix    string        `help:"Domain suffix to accept requests for" default:"localdomain" env:"LAMUX_DOMAIN_SUFFIX" name:"domain-suffix"`
	UpstreamTimeout time.Duration `help:"Timeout for upstream requests" default:"30s" env:"LAMUX_UPSTREAM_TIMEOUT" name:"upstream-timeout"`
}

func (*Config) ExtractAliasAndFunctionName

func (cfg *Config) ExtractAliasAndFunctionName(_ context.Context, r *http.Request) (string, string, error)

func (*Config) Validate

func (cfg *Config) Validate() error

type HandlerError

type HandlerError struct {
	// contains filtered or unexported fields
}

func (*HandlerError) Code

func (h *HandlerError) Code() int

func (*HandlerError) Error

func (h *HandlerError) Error() string

func (*HandlerError) Unwrap

func (h *HandlerError) Unwrap() error

type Lamux

type Lamux struct {
	Config *Config
	// contains filtered or unexported fields
}

func NewLamux

func NewLamux(cfg *Config) (*Lamux, error)

func (*Lamux) Invoke

func (l *Lamux) Invoke(ctx context.Context, functionName, alias string, b []byte) (*lambda.InvokeOutput, error)