srv

README

srv

srv is a simple, secure and modern HTTP server, written in Go, to serve static sites, single-page applications or a file with ease. You can use it through its command-line interface, Docker image or programmatically. As it's an http.Handler implementation, it should be easy to integrate it into your application. The following key features make srv unique and differentiable from the existing solutions and the http.FileServer implementation.

• Programmatic API.
• HTTP/2 and TLS support.
• Custom error handler and pages.
• Basic HTTP authentication.
• Hide dot files by default.
• Directory listing is disabled by default.
• Encoding negotiation with support of gzip, Deflate and Brotli compression algorithms.

Installation

go get github.com/kevinpollet/srv               # get dependency
go install github.com/kevinpollet/srv/cmd/srv   # build and install command-line interface bin

Usage

Command-line

srv can be use through its provided command-line. The following text is the output of the srv -help command.

srv [options]

Options:
-addr       The server address, "127.0.0.1:8080" by default.
-auth       The basic auth credentials (password must be hashed with bcrypt and escaped with '').
-auth-file  The basic auth credentials following the ".htpasswd" format.
-dir        The directory containing the files to serve, "." by default.
-cert       The TLS certificate.
-key        The TLS private key.
-help       Prints this text.

Library

package main

import (
	"log"
	"net/http"

	"github.com/kevinpollet/srv"
	"github.com/kevinpollet/srv/middlewares"
)

func main() {
	customErrorHandler := func(fs http.FileSystem, rw http.ResponseWriter, err error) {
		log.Print(err)
		rw.WriteHeader(http.StatusInternalServerError)
	}

	http.Handle("/static", srv.NewFileServer("examples/hello",
		srv.WithAutoIndex(),
		srv.WithMiddlewares(middlewares.NewStripPrefixHandler("/static")),
		srv.WithErrorHandler(customErrorHandler),
	))

	log.Fatal(http.ListenAndServe(":8080", nil))
}

Docker

An official docker image is available on Docker Hub. The following Dockerfile shows how to use the provided base image to serve your static sites or files through a running Docker container. By default, the base image will serve all files available in the /var/www/ directory and listen for TCP connections on 8080.

FROM kevinpollet/srv:latest
COPY . /var/www/

Then, you can build and run your Docker image with the following commands. Your static site or files will be available on http://localhost:8080.

docker build . -t moby:latest
docker run -d -p 8080:8080 moby:latest

Examples

The examples directory contains the following examples:

• hello — A simple static site that can be served from the command-line.
• docker — A simple static site that can be served from a docker container.

Contributing

Contributions are welcome!

Want to file a bug, request a feature or contribute some code?

1. Check out the Code of Conduct.
2. Check for an existing issue corresponding to your bug or feature request.
3. Open an issue to describe your bug or feature request.

License

MIT

Documentation

Index

• func NewFileServer(dir string, options ...Option) http.Handler
• type FileServer
  • func (fs *FileServer) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type Option
  • func WithAutoIndex() Option
  • func WithErrorHandler(errorHandler func(http.FileSystem, http.ResponseWriter, error)) Option
  • func WithMiddlewares(middlewares ...alice.Constructor) Option

Functions

func NewFileServer

func NewFileServer(dir string, options ...Option) http.Handler

NewFileServer returns a new handler instance that serves HTTP requests with the contents of the given directory.

Types

type FileServer

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

FileServer is a http.Handler implementation that serves HTTP requests with the contents of the corresponding file.

func (*FileServer) ServeHTTP

func (fs *FileServer) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP responds to an HTTP request.

type Option

type Option func(*FileServer)

Option is the functional option type.

func WithAutoIndex

func WithAutoIndex() Option

WithAutoIndex enables auto index.

func WithErrorHandler

func WithErrorHandler(errorHandler func(http.FileSystem, http.ResponseWriter, error)) Option

WithErrorHandler sets the Error handler.

func WithMiddlewares

func WithMiddlewares(middlewares ...alice.Constructor) Option

WithMiddlewares sets the middlewares to apply before serving the request.