more/improved documentation; tests converted to Gomega

additions.go

@@ -49,13 +49,13 @@ func (r *Router) HandlerAll(path string, handler http.Handler, methods ...string
 //
 // The path must end with "/*filepath" (or simply "/*" is allowed in this case). The
 // attached handle sees the sub-path only. For example if path is "/a/b/" and the
-// request URI path is "/a/b/foo", the handle will see a request for "/foo".
-//
-// If no methods are specified, all methods (in AllMethods) will be supported. Otherwise,
-// only the specified methods will be supported.
+// request URI path is "/a/b/foo", the handler will see a request for "/foo".
 //
 // If you don't want the prefix trimmed, instead use Handle with a path that ends with
 // ".../*name" (for some name of your choice).
+//
+// If no methods are specified, all methods (in AllMethods) will be supported. Otherwise,
+// only the specified methods will be supported.
 func (r *Router) SubRouter(path string, handler http.Handler, methods ...string) {
 	if strings.HasSuffix(path, "/*") {
 		path = path + "filepath"

additions_test.go

@@ -0,0 +1,32 @@
+package httprouter_test
+
+import (
+	"github.com/rickb777/httprouter/v3"
+	"github.com/rickb777/servefiles/v3"
+	"log"
+	"net/http"
+	"time"
+)
+
+func ExampleRouter_SubRouter_usingAnAssetHandler() {
+	// This is a webserver using the asset handler provided by
+	// github.com/rickb777/servefiles/v3, which has enhanced
+	// HTTP expiry, cache control, compression etc.
+	// 'Normal' bespoke handlers are included as needed.
+
+	// where the assets are stored (replace as required)
+	localPath := "./assets"
+
+	// how long we allow user agents to cache assets
+	// (this is in addition to conditional requests, see
+	// RFC7234 https://tools.ietf.org/html/rfc7234#section-5.2.2.8)
+	maxAge := time.Hour
+
+	h := servefiles.NewAssetHandler(localPath).WithMaxAge(maxAge)
+
+	router := httprouter.New()
+	// ... add other routes / handlers as required
+	router.SubRouter("/files/*", h, http.MethodGet, http.MethodHead)
+
+	log.Fatal(http.ListenAndServe(":8080", router))
+}

api.go

@@ -240,7 +240,7 @@ func (r *Router) HandlerFunc(method, path string, handler http.HandlerFunc) {
 // ServeFiles serves files from the given file system root using the http.FileServer
 // handler. Note that http.NotFound is used instead of the Router's NotFound handler;
 // if this is inconvenient, consider using SubRouter with your own file server instead
-// (see https://github.com/rickb777/servefiles for example).
+// (see https://github.com/rickb777/servefiles/v3 for example).
 //
 // The path must end with "/*filepath" (or simply "/*" is allowed in this case), files
 // are then served from the local path /defined/root/dir/*filepath.
@@ -253,6 +253,11 @@ func (r *Router) HandlerFunc(method, path string, handler http.HandlerFunc) {
 // To use the operating system's file system implementation,
 // use http.Dir:
 //     router.ServeFiles("/src/*filepath", http.Dir("/var/www"))
+//
+// Tip: alternative file servers can be plugged in via SubRouter instead.
+// This allows, for example, use of the asset handler
+// github.com/rickb777/servefiles/v3 with its improved HTTP header
+// configuration.
 func (r *Router) ServeFiles(path string, root http.FileSystem) {
 	if len(path) < 10 || path[len(path)-10:] != "/*filepath" {
 		panic("path must end with /*filepath in path '" + path + "'")

doc.go

@@ -10,7 +10,7 @@
 //
 //  import (
 //      "fmt"
-//      "github.com/acoshift/httprouter"
+//      "github.com/rickb777/httprouter"
 //      "net/http"
 //      "log"
 //  )

go.mod

@@ -4,6 +4,7 @@ go 1.15
 
 require (
 	github.com/onsi/gomega v1.10.3
+	github.com/rickb777/servefiles/v3 v3.1.1
 	golang.org/x/net v0.0.0-20201016165138-7b1cca2348c0 // indirect
 	golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
 )

go.sum

@@ -1,3 +1,4 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/fsnotify/fsnotify v1.4.7 h1:IXs+QLmnXW2CcXuY+8Mzv/fWEsPGWxqefPtCP5CnV9I=
 github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
@@ -13,6 +14,7 @@ github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMyw
 github.com/google/go-cmp v0.4.0 h1:xsAVV57WRhGj6kEIi8ReJzQlHHqcBYCElAvkovg3B/4=
 github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
+github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
 github.com/nxadm/tail v1.4.4 h1:DQuhQpB1tVlglWS2hLQ5OV6B5r8aGxSrPc5Qo6uTN78=
 github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
@@ -21,7 +23,20 @@ github.com/onsi/ginkgo v1.12.1/go.mod h1:zj2OWP4+oCPe1qIXoGWkgMRwljMUYCdkwsT2108
 github.com/onsi/gomega v1.7.1/go.mod h1:XdKZgCCFLUoM/7CFJVPcG8C1xQ1AJ0vpAezJrB7JYyY=
 github.com/onsi/gomega v1.10.3 h1:gph6h/qe9GSUw1NhH1gp+qb+h8rXD8Cy60Z32Qw3ELA=
 github.com/onsi/gomega v1.10.3/go.mod h1:V9xEwhxec5O8UDM77eCW8vLymOMltsqPVYWrpDsH8xc=
+github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/sftp v1.10.1/go.mod h1:lYOWFsE0bwd1+KfKJaKeuokY15vzFx25BLbzYYoAxZI=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rickb777/path v0.15.0 h1:T3GndLort6GIFb4AOaKafEkYE2JEFoV2C7E9Vm/jjl0=
+github.com/rickb777/path v0.15.0/go.mod h1:ZKgQsDzXqqwuE5tdp6vFZ4jIYHYK32kDQvmrD9LLAFk=
+github.com/rickb777/servefiles/v3 v3.1.1 h1:T/ygMu8HHFUT2+Fj1kkvh4bxJ7qRFVBJ3vhCN7Ym9SI=
+github.com/rickb777/servefiles/v3 v3.1.1/go.mod h1:mQWz3MMfi3aeSNin6V55aXoig8i/Zh8uYu3jjCTI9EI=
+github.com/spf13/afero v1.4.1 h1:asw9sl74539yqavKaglDM5hFpdJVK0Y5Dr/JOgQ89nQ=
+github.com/spf13/afero v1.4.1/go.mod h1:Ai8FlHk4v/PARR026UzYexafAt9roJ7LcLMAmO6Z93I=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20190820162420-60c769a6c586/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9 h1:psW17arqaxU48Z5kZ0CQnkZWQJsqcURM6tKiBApRjXI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
@@ -40,6 +55,7 @@ golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3 h1:cokOdA+Jmi5PJGXLlLllQSgYigAEfHXJAERHVMaCc2k=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e h1:FDhOuMEY4JVRztM/gsbk+IKUQ8kj74bxZrgw87eMMVc=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
@@ -57,6 +73,7 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
 gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ=
 gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.3.0 h1:clyUAQHOM3G0M3f5vQj7LuJrETvjVot3Z5el9nffUtU=
 gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=