caddys3proxy

README

caddy-s3-proxy

caddy-s3-proxy allows you to proxy requests directly from S3.

S3 does have the website option, in which case, a normal reverse proxy could be used to display S3 data. However, it is sometimes inconvient to do that. This module lets you access S3 data even if website access is not configured on your bucket.

Making a version of caddy with this plugin

With caddy 2 you can use xcaddy to build a version of caddy with this plugin installed. To install xcaddy do:

go get -u github.com/caddyserver/xcaddy/cmd/xcaddy

This repo has a Makefile to make it easier to build a new version of caddy with this plugin. Just type:

make build

You can run make docker do build a local image you can test with.

Configuration

The Caddyfile directive would look something like this:

	s3proxy [<matcher>] {
		bucket <bucket_name>
		region <region_name>
		index  <list of index file names>
		endpoint <alternative S3 endpoint>
		root   <key prefix>
		enable_put
		enable_delete
		not_found_key <S3 key>
	}

option	type	required	default	help
bucket	string	yes		S3 bucket name
region	string	no	env AWS_REGION	S3 region - if not give in the Caddyfile then AWS_REGION env var must be set.
endpoint	string	no	aws default	S3 hostname
index	string[]	no	[index.html, index.txt]	Index files to look up for dir path
root	string	no		Set a "prefix" to be added to key
enable_put	bool	yes	false	Allow PUT method to be sent through proxy
enable_delete	bool	yes	false	Allow DELETE method to be sent through proxy
not_found_key	string	no		S3 key that points to a custom 404 page

Credentials

This module uses the default providor chain to get credentials for access to S3. This provides several more secure options to provide credentials for accessing S3 without putting the credentials in the Caddyfile. The methods include (and are looked for in this order):

1. Environment variables. I.e. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

2. Shared credentials file. (Located at ~/.aws/credentials)

3. If your application uses an ECS task definition or RunTask API operation, IAM role for tasks.

4. If your application is running on an Amazon EC2 instance, IAM role for Amazon EC2.

For much more detail on the various options for setting AWS credentials see here: https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html

Examples you can play with

In the examples directory is an example of using the s3proxy with localstack. Localstack contains a working version of S3 you can use for local development.

Check out the examples here.

Documentation

Index

• type S3Proxy
  • func (S3Proxy) CaddyModule() caddy.ModuleInfo
  • func (p S3Proxy) HandleDelete(w http.ResponseWriter, r *http.Request, key string) error
  • func (p S3Proxy) HandlePut(w http.ResponseWriter, r *http.Request, key string) error
  • func (p *S3Proxy) Provision(ctx caddy.Context) (err error)
  • func (p S3Proxy) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

Types

type S3Proxy

type S3Proxy struct {
	// The path to the root of the site. Default is `{http.vars.root}` if set,
	// Or if not set the value is "" - meaning use the whole path as a key.
	Root string `json:"root,omitempty"`

	// The AWS region the bucket is hosted in
	Region string `json:"region,omitempty"`

	// The name of the S3 bucket
	Bucket string `json:"bucket,omitempty"`

	// Use non-standard endpoint for S3
	Endpoint string `json:"endpoint,omitempty"`

	// The names of files to try as index files if a folder is requested.
	IndexNames []string `json:"index_names,omitempty"`

	// A glob pattern used to hide matching key paths (returning a 404)
	Hide []string

	// Flag to determine if PUT operations are allowed (default false)
	EnablePut bool

	// Flag to determine if DELETE operations are allowed (default false)
	EnableDelete bool

	// Key that should exist in the bucket and that the proxy will fallback to
	// if the requested path doesn't exist in the bucket. This is especially
	// useful to make custom 404 error pages.
	NotFoundKey string `json:"not_found_key,omitempty"`
	// contains filtered or unexported fields
}

S3Proxy implements a proxy to return objects from S3

func (S3Proxy) CaddyModule

func (S3Proxy) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (S3Proxy) HandleDelete

func (p S3Proxy) HandleDelete(w http.ResponseWriter, r *http.Request, key string) error

func (S3Proxy) HandlePut

func (p S3Proxy) HandlePut(w http.ResponseWriter, r *http.Request, key string) error

func (*S3Proxy) Provision

func (p *S3Proxy) Provision(ctx caddy.Context) (err error)

func (S3Proxy) ServeHTTP

func (p S3Proxy) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error