mozey/httprouter-util

Example of using httprouter and other useful packages

httprouter-util

Examples of using httprouter with

• zerolog for logging
• Middleware: panic handler, request logging, request ID for tracing, token auth, max bytes handler, gzip
• Graceful shutdown on ctrl+c
• Swagger docs
• Caddy as a HTTPS endpoint, API gateway, and reverse proxy

This repo is not intended for use as a "framework", however, other projects may import the packages in pkg. The code in internal is specific to this app, and must not be imported by other projects

Quick start

Clone the repo (outside your GOPATH since this is a module)

git clone https://github.com/mozey/httprouter-util.git
cd httprouter-util # This is the APP_DIR

Following the 12 factor app recommendation to store config in the environment. Configuration is done using environment variables

Generate script to set dev config

APP_DIR=$(pwd) ./make.sh env_sh dev

Set dev config

source ./dev.sh

Run dev server (no live reload)

./make.sh app_run

Or run dev server with live reload

./make.sh app

Tests require running server

gotest -v ./...

Examples

Make requests from the cli with curlie

Authentication

Token is required by default http://localhost:8118/token/is/required/by/default

Some routes may skip the token check

• http://localhost:8118
• http://localhost:8118/index.html
• http://localhost:8118/www/data/go.txt

Using the token

For static files http://localhost:8118/hello/foo?token=123

And API endpoints http://localhost:8118/api?token=123

Error handling

http://localhost:8118/panic

http://localhost:8118/does/not/exist?token=123

Configuration

Use http.MaxBytesReader to limit POST body. Make the request with specified body size, Assuming MaxBytes is set to 1 KiB the request below will fail

dd if=/dev/urandom bs=1 count=1025 | curlie --data-binary @- POST "http://localhost:8118/api?token=123"

Settings to protect against malicious clients. NOTE The response body for errors below is not JSON, it's not possible to override string response hard-coded in Golang SDK

# ReadTimeout
gotest -v ./... -run TestReadTimeout

# WriteTimeout
gotest -v ./... -run TestWriteTimeout

# MaxHeaderBytes
gotest -v ./... -run TestMaxHeaderBytes

Proxy

Caddy is used as a HTTPS endpoint, API gateway, and reverse proxy. See #6 for Caddyfile configuration

Services

TODO Define services on the handler, e.g. DB connection http://localhost:8118/db?sql=select * from color

Client

Example client with self-update feature.

Build client

Build the client, download it, and print version

source dev.sh

VERSION=0.1.0 ./scripts/build-client.sh

./dist/client -version

rm -f client && curlie "http://localhost:8118/client/download?token=123" -o client

# Executing the client might require permissions, on macOS
#   System Preferences > Security & Privacy > General > Allow Anyway
chmod u+x ./client && ./client -version

Update client

Create a new build

VERSION=0.2.0 ./scripts/build-client.sh

./dist/client -version

curlie "http://localhost:8118/client/version?token=123"

Update from the server and print new version

./client -update -token 123

./client -version

Running update again prints "already on the latest version"

./client -update -token 123

Reset

Removes all user config

APP_DIR=$(pwd) ./scripts/reset.sh

Dependencies

This example aims for a good cross platform experience by depending on

• Golang
• Bash
• fswatch
• xargs

On macOS and Linux

• pgrep and kill

TODO On Windows

• taskkill

GNU Make is not needed because Golang is fast to build, and fswatch can be used for live reload. For this example main.go is kept in the project root. Larger projects might have separate bins in the "/cmd" dir

Bash on Windows is easy to setup using msys2, MinGW, or native shell on Windows 10. For other UNIX programs see gow

TODO Instructions for installing deps on Windows

httprouter-util's Issues

Harden server for Internet exposure

Review recommendations made in these articles

• The complete guide to Go net/http timeouts
• So you want to expose Go on the Internet

Endpoint for basic auth

See TODO

Catch ctrl+c for graceful shutdown

"Shutdown gracefully shuts down the server without
interrupting any active connections...
does not attempt to close nor wait for... WebSockets"

https://golang.org/pkg/net/http/#Server.Shutdown

Browser and gRPC-compatible HTTP APIs

Protocol buffer is an alternative to tools like Swagger.

Besides the benefits of using a binary protocol, it's potentially also more efficient to develop. The "spec" / clients are generated from interfaces and structs, no comment annotations, or manually editing JSON spec is required.

connect-go is an alternative lib for "for building browser and gRPC-compatible HTTP APIs. If you're tired of hand-written boilerplate and turned off by massive frameworks, Connect is for you.". It has the following features

• supports "three protocols: gRPC, gRPC-Web, and Connect's own protocol"
• "works over HTTP/1.1 or HTTP/2"
• "any package that works with an http.Server, http.Client, or http.Handler also works with Connect"

The official Google implementation of gRPC has some disadvantages

• "has no browser support (due to vendors not implementing trailers)"
• "is 130 thousand lines of hand-written code"
• "uses its own implementation of HTTP/2. It's incompatible with the rest of Go's HTTP ecosystem"
• "Supporting common HTTP clients (like web browsers) requires elaborate translating proxies"

As per gotime episode gRPC & protocol buffers

Caddy as a HTTPS endpoint, API gateway, and reverse proxy

Example Caddyfile for

• Automatic HTTPS (even on localhost?)
• API gateway to service running on a specific port
• Reverse proxy to another service

Auth with go-oauth2

Auth with go-oauth2, using default store BuntDB: "Both Bolt and Bunt are ACID, and both persist data to disk. The biggest difference between them is that Bolt reads and writes from disk, while Bunt reads and writes from memory (and has an append-only file for durability)"

See OAuth2 explained with cute shapes, create examples as per this article

Passwordless auth

Example of using johnsto/go-passwordless

Swagger spec, docs, and client

Do the following

• Document endpoints in handler comments
• Generate spec with swag
• Endpoint to serve UI

Gzip middleware

Example of using nytimes/gziphandler