s3browser

README

Caddy s3browser

This will provide directory listing for an S3 bucket (you are able to use minio, or other S3 providers).

Note: For performance reasons, the file listing is fetched once every 5 minutes to reduce load on S3. You can force a refresh by sending a POST request to the plugin.

Building

Use xcaddy to build.

Example:

$ xcaddy build --output ./caddy --with github.com/techknowlogick/caddy-s3browser@main

Configuration

See Caddyfile.tmpl for a template.

option	type	default	help
site_name	string	S3 Browser	Site display name
endpoint	string		S3 hostname
region	string	empty	S3 region (optional)
key	string		S3 access key
secret	string		S3 secret key
secure	bool	true	Use TLS when connection to S3
bucket	string		S3 bucket
refresh_interval	string	5m	Time between periodic refresh
refresh_api_secret	string	empty	A key to protect the refresh API. (optional)
debug	bool	false	Output debug information
signed_url_redirect	bool	false	Output debug information

Force Refresh

You can trigger a force refresh by making a POST request to the server:

curl -X POST "$HOST"

When refresh_api_secret is set, you must use HTTP basic auth:

curl -X POST "api:$SECRET@$HOST" # the username can be anything

Prior Art

• This is based on the Browse plugin that is built into Caddy
• s3server from jessfraz
• pretty-s3-index-html by Nolan Lawson

Documentation

Index

• type Crumb
• type Directory
  • func (d Directory) GetFile(fileName string) File
• type File
  • func (f File) HumanModTime(format string) string
  • func (f File) HumanSize() string
• type S3Browser
  • func (S3Browser) CaddyModule() caddy.ModuleInfo
  • func (b *S3Browser) Provision(ctx caddy.Context) (err error)
  • func (b S3Browser) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (b *S3Browser) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (b *S3Browser) Validate() error
• type S3Client
  • func NewS3Client(endpoint, key, secret string, secure bool, bucket string) (S3Client, error)
  • func (c *S3Client) ForEachObject(fn func(minio.ObjectInfo)) error
  • func (c *S3Client) GetObject(filePath string, rangeHdr string) (io.ReadCloser, minio.ObjectInfo, http.Header, error)
• type S3FsCache
  • func NewS3FsCache(client S3Client, sorter *S3FsSorter, l *zap.Logger) S3FsCache
  • func (fs *S3FsCache) GetDir(dirPath string) (Directory, bool)
  • func (fs *S3FsCache) GetFile(filePath string) (File, bool)
  • func (fs *S3FsCache) Refresh() (err error)
• type S3FsSorter
  • func NewS3FsSorter(algorithm string, reverse bool) (*S3FsSorter, error)
  • func (s *S3FsSorter) Sort(names []string)
• type TemplateArgs

Types

type Crumb

type Crumb struct {
	Link string
	Name string
}

type Directory

type Directory struct {
	Path      string
	Folders   []string
	Filenames []string
	// contains filtered or unexported fields
}

func (Directory) GetFile

func (d Directory) GetFile(fileName string) File

Caller must ensure file exists.

type File

type File struct {
	Bytes int64
	Date  time.Time
}

func (File) HumanModTime

func (f File) HumanModTime(format string) string

HumanModTime returns the modified time of the file as a human-readable string.

func (File) HumanSize

func (f File) HumanSize() string

HumanSize returns the size of the file as a human-readable string in IEC format (i.e. power of 2 or base 1024).

type S3Browser

type S3Browser struct {
	// Config (these fields must be public)
	SiteName          string        `json:"site_name,omitempty"`
	Endpoint          string        `json:"endpoint,omitempty"`
	Region            string        `json:"region,omitempty"`
	Key               string        `json:"key,omitempty"`
	Secret            string        `json:"secret,omitempty"`
	Bucket            string        `json:"bucket,omitempty"`
	Secure            bool          `json:"secure,omitempty"`
	RefreshInterval   time.Duration `json:"refresh_interval,omitempty"`
	RefreshAPISecret  string        `json:"refresh_api_secret,omitempty"`
	Debug             bool          `json:"debug,omitempty"`
	SignedURLRedirect bool          `json:"signed_url_redirect,omitempty"`
	SortAlgorithm     string        `json:"sort_algorithm,omitempty"`
	// contains filtered or unexported fields
}

func (S3Browser) CaddyModule

func (S3Browser) CaddyModule() caddy.ModuleInfo

func (*S3Browser) Provision

func (b *S3Browser) Provision(ctx caddy.Context) (err error)

func (S3Browser) ServeHTTP

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

func (*S3Browser) UnmarshalCaddyfile

func (b *S3Browser) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (*S3Browser) Validate

func (b *S3Browser) Validate() error

type S3Client

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

func NewS3Client

func NewS3Client(endpoint, key, secret string, secure bool, bucket string) (S3Client, error)

func (*S3Client) ForEachObject

func (c *S3Client) ForEachObject(fn func(minio.ObjectInfo)) error

func (*S3Client) GetObject

func (c *S3Client) GetObject(filePath string, rangeHdr string) (io.ReadCloser, minio.ObjectInfo, http.Header, error)

type S3FsCache

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

func NewS3FsCache

func NewS3FsCache(client S3Client, sorter *S3FsSorter, l *zap.Logger) S3FsCache

func (*S3FsCache) GetDir

func (fs *S3FsCache) GetDir(dirPath string) (Directory, bool)

func (*S3FsCache) GetFile

func (fs *S3FsCache) GetFile(filePath string) (File, bool)

func (*S3FsCache) Refresh

func (fs *S3FsCache) Refresh() (err error)

type S3FsSorter

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

func NewS3FsSorter

func NewS3FsSorter(algorithm string, reverse bool) (*S3FsSorter, error)

func (*S3FsSorter) Sort

func (s *S3FsSorter) Sort(names []string)

type TemplateArgs

type TemplateArgs struct {
	SiteName string
	Dir      Directory
}